Agents confused by multiple MCP beads servers - use wrong database

When multiple beads MCP servers are configured (e.g., beads-wyvern, beads-adar), agents may use the wrong server and create issues in wrong database. In this session, created wy-22 (wyvern) when working in beads repo. Root cause: All MCP servers available simultaneously with different BEADS_WORKING_DIR/BEADS_DB env vars. Agent must manually choose correct server or use direct bd commands.

## This is a SYMPTOM of bd-86

The multi-server approach was a workaround attempt that backfired. See bd-86 for comprehensive root cause analysis.

## Original Solutions (superseded by bd-86 analysis)

Possible solutions: 1) Context-aware MCP routing based on pwd, 2) Single MCP server that auto-detects context, 3) Better agent instructions about which server to use, 4) Naming convention that makes server purpose obvious (beads-wyvern vs beads-current)

## Actual Solution (from bd-86)

Implement PATH 1: Single MCP server with SetContext/WhereAmI tools. This issue will be resolved when bd-86 is implemented.

This issue is a SYMPTOM of bd-86 (missing CWD propagation). The multi-server workaround (beads-wyvern, beads-adar, etc.) doesn't solve the root cause and creates new problems (agent confusion about which server to use). See bd-86 for comprehensive analysis and architectural solutions. Should be resolved when bd-86 is fixed with Path 1 (SetContext/WhereAmI approach).


Implement daemon RPC with per-request context routing (PATH 1.5)

Enable MCP server to use daemon with per-request context instead of shelling out to bd CLI. This solves multi-repo routing properly.

## Goal

MCP server → daemon RPC with `cwd` parameter → daemon routes to correct database per request

## Architecture

```
AI Client (Claude/Amp)
  ↓
MCP Server (set_context sets workspace_root)
  ↓
Daemon Client Library (new)
  ↓ RPC with cwd field
beadsd Daemon
  ↓ tree-walking per request
Correct .beads/*.db
```

## Components

### 1. Extend Daemon RPC Protocol
**Files:** `internal/daemon/protocol.go`, daemon handlers

- Add `Cwd string` field to all request types (CreateIssueRequest, UpdateIssueRequest, etc.)
- Daemon does tree-walking to find `.beads/*.db` based on cwd
- Each operation gets its own context (stateless per request)

### 2. Create Daemon Client Library
**New file:** `integrations/beads-mcp/src/beads_mcp/bd_daemon_client.py`

- Python client for daemon RPC protocol
- Methods matching current BdClient interface
- Adds `cwd` parameter to all requests
- Handles connection management, retries
- Falls back to CLI if daemon unavailable

### 3. Update MCP Server
**File:** `integrations/beads-mcp/src/beads_mcp/server.py`

- Store workspace_root from `set_context`
- Use daemon client by default, fall back to CLI client
- Pass workspace_root as cwd to all operations
- Handle daemon not running gracefully

### 4. Update bd_client.py
**File:** `integrations/beads-mcp/src/beads_mcp/bd_client.py`

- Make it an abstract interface/base class
- Concrete implementations: BdCliClient, BdDaemonClient
- Factory function to create appropriate client

## Benefits

- ✅ True multi-repo support (each request has context)
- ✅ Better performance (no process spawning)
- ✅ Concurrent access already solved (daemon exists)
- ✅ Stateless per request (no env var persistence issues)
- ✅ Falls back to CLI when daemon not running

## Implementation Steps

1. **Extend RPC protocol** (Go)
   - Add Cwd field to request structs
   - Update daemon handlers to use cwd for tree-walking

2. **Create daemon client** (Python)
   - Implement RPC protocol in Python
   - Match BdClient interface

3. **Refactor MCP server**
   - Abstract BdClient
   - Use daemon client when available

4. **Test with multiple repos**
   - Concurrent operations
   - Context switching
   - Daemon restart handling

## Related Issues

- bd-86: Root cause investigation (this is PATH 1.5 solution)
- bd-91: Multi-server confusion (will be resolved)
- bd-80, bd-81, bd-82, bd-83: Daemon implementation (foundation)

- MCP server can use daemon RPC instead of CLI
- Each operation includes cwd context
- Daemon routes to correct database per request
- Works with multiple repos simultaneously
- Falls back to CLI gracefully if daemon unavailable
- All existing MCP tests pass
- New multi-repo integration tests pass

## Progress: Session 2 (2025-10-17 continued)

### Completed
1. ✅ Updated MCP server to use daemon client
   - Modified `tools.py` to use `create_bd_client()` factory
   - Passes `BEADS_WORKING_DIR` from environment
   - Uses daemon by default, falls back to CLI
2. ✅ Added `BEADS_USE_DAEMON` environment variable
   - Default: `1` (enabled)
   - Set to `0` to force CLI mode
3. ✅ Created multi-repo integration test (`test_multi_repo.py`)
   - Tests concurrent operations across two repos
   - Verifies proper database routing based on cwd
   - Validates issue prefix isolation (r1- vs r2-)
   - All tests pass! ✅
4. ✅ Updated MCP README with daemon usage docs
   - Added BEADS_USE_DAEMON to environment variables
   - Added multi-repo test documentation

### Test Results
```
=== All Tests Passed! ===
Summary:
  ✅ Per-request context routing works
  ✅ Multiple repos are properly isolated
  ✅ Concurrent operations succeed
  ✅ Daemon handles rapid context switching
```

### Files Modified/Added (Session 2)
- `integrations/beads-mcp/src/beads_mcp/tools.py` - uses daemon client ✅
- `integrations/beads-mcp/test_multi_repo.py` - NEW integration test ✅
- `integrations/beads-mcp/README.md` - daemon documentation ✅

### Architecture Validated

```
AI Client (Claude/Amp)
  ↓
MCP Server (workspace_root from set_context)
  ↓ create_bd_client(prefer_daemon=True, workspace_root)
Daemon Client Library
  ↓ RPC with cwd field
beadsd Daemon
  ↓ per-request tree-walking
Correct .beads/*.db
```

### Ready to Close
All acceptance criteria met:
- ✅ MCP server can use daemon RPC instead of CLI
- ✅ Each operation includes cwd context
- ✅ Daemon routes to correct database per request
- ✅ Works with multiple repos simultaneously
- ✅ Falls back to CLI gracefully if daemon unavailable
- ✅ All existing MCP tests pass
- ✅ New multi-repo integration tests pass


Issue in repo1

This should go to repo1 database


Issue in repo2

This should go to repo2 database


Fix nil pointer crash in bd export command

When running `bd export -o .beads/issues.jsonl`, the command crashes with a nil pointer dereference.

## Error
```
panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x2 addr=0x108 pc=0x1034456fc]

goroutine 1 [running]:
main.init.func14(0x103c24380, {0x1034a9695?, 0x4?, 0x1034a95c9?})
        /Users/stevey/src/vc/adar/beads/cmd/bd/export.go:74 +0x15c
```

## Context
- This happened after closing bd-86, bd-91, bd-92
- Auto-export from daemon still works fine
- Only the manual `bd export` command crashes
- Data was already synced via auto-export, so no data loss

## Location
File: `cmd/bd/export.go` line 74


Add --global flag to daemon for multi-repo support

Currently daemon creates socket at .beads/bd.sock in each repo. For multi-repo support, add --global flag to create socket in ~/.beads/bd.sock that can serve requests from any repository.

Implementation:
- Add --global flag to daemon command
- When --global is set, use ~/.beads/bd.sock instead of ./.beads/bd.sock
- Don't require being in a git repo when --global is used
- Update daemon discovery logic to check ~/.beads/bd.sock as fallback
- Document that global daemon can serve multiple repos simultaneously

Benefits:
- Single daemon serves all repos on the system
- No need to start daemon per-repo
- Better resource usage
- Enables system-wide task tracking

Context: Per-request context routing (bd-92) already implemented - daemon can handle multiple repos. This issue is about making the UX better.

Related: bd-43 (parent issue for multi-repo support)


Document multi-repo workflow with daemon

The daemon already supports multi-repo via per-request context routing (bd-92), but this isn't documented. Users need to know how to use beads across multiple projects.

Add documentation for:
1. How daemon serves multiple repos simultaneously
2. Starting daemon in one repo, using from others
3. MCP server multi-repo configuration
4. Example: tracking work across a dozen projects
5. Comparison to workspace/global instance approaches

Documentation locations:
- README.md (Multi-repo section)
- AGENTS.md (MCP multi-repo config)
- integrations/beads-mcp/README.md (working_dir parameter)

Include:
- Architecture diagram showing one daemon, many repos
- Example MCP config with BEADS_WORKING_DIR
- CLI workflow example
- Reference to test_multi_repo.py as proof of concept

Context: Feature already works (proven by test_multi_repo.py), just needs user-facing docs.