Document bd daemons commands (bd-150)

Amp-Thread-ID: https://ampcode.com/threads/T-f1cff202-188b-4850-a909-c2750d24ad22
Co-authored-by: Amp <amp@ampcode.com>

AGENTS.md

@@ -99,8 +99,10 @@ SQLite Databases (complete isolation)
 **Version Management:** bd automatically handles daemon version mismatches (v0.16.0+):
 - When you upgrade bd, old daemons are automatically detected and restarted
 - Version compatibility is checked on every connection
-- No manual `bd daemon --stop` required after upgrades
+- No manual intervention required after upgrades
 - Works transparently with MCP server and CLI
+- Use `bd daemons health` to check for version mismatches
+- Use `bd daemons killall` to force-restart all daemons if needed
 
 **Alternative (not recommended): Multiple MCP Server Instances**
 If you must use separate MCP servers:
@@ -198,6 +200,42 @@ bd merge <source-id...> --into <target-id> --json      # Consolidate duplicates
 bd merge bd-42 bd-43 --into bd-41 --dry-run            # Preview merge
 ```
 
+### Managing Daemons
+
+bd runs a background daemon per workspace for auto-sync and RPC operations. Use `bd daemons` to manage multiple daemons:
+
+```bash
+# List all running daemons
+bd daemons list --json
+
+# Check health (version mismatches, stale sockets)
+bd daemons health --json
+
+# Stop a specific daemon
+bd daemons stop /path/to/workspace --json
+bd daemons stop 12345 --json  # By PID
+
+# View daemon logs
+bd daemons logs /path/to/workspace -n 100
+bd daemons logs 12345 -f  # Follow mode
+
+# Stop all daemons
+bd daemons killall --json
+bd daemons killall --force --json  # Force kill if graceful fails
+```
+
+**When to use:**
+- **After upgrading bd**: Run `bd daemons health` to check for version mismatches, then `bd daemons killall` to restart all daemons with the new version
+- **Debugging**: Use `bd daemons logs <workspace>` to view daemon logs
+- **Cleanup**: `bd daemons list` auto-removes stale sockets
+
+**Troubleshooting:**
+- **Stale sockets**: `bd daemons list` auto-cleans them
+- **Version mismatch**: `bd daemons killall` then let daemons auto-start on next command
+- **Daemon won't stop**: `bd daemons killall --force`
+
+See [commands/daemons.md](commands/daemons.md) for detailed documentation.
+
 ### Workflow
 
 1. **Check for ready work**: Run `bd ready` to see what's unblocked

README.md

@@ -396,6 +396,37 @@ bd sync
 
 **Note:** Auto-sync is enabled by default. Manual export/import is rarely needed.
 
+### Managing Daemons
+
+bd runs a background daemon per workspace for auto-sync and RPC operations. Use `bd daemons` to manage multiple daemons:
+
+```bash
+# List all running daemons
+bd daemons list
+
+# Check health (version mismatches, stale sockets)
+bd daemons health
+
+# Stop a specific daemon
+bd daemons stop /path/to/workspace
+bd daemons stop 12345  # By PID
+
+# View daemon logs
+bd daemons logs /path/to/workspace -n 100
+bd daemons logs 12345 -f  # Follow mode
+
+# Stop all daemons
+bd daemons killall
+bd daemons killall --force  # Force kill if graceful fails
+```
+
+**Common use cases:**
+- **After upgrading bd**: Run `bd daemons health` to check for version mismatches, then `bd daemons killall` to restart all daemons with the new version
+- **Debugging**: Use `bd daemons logs <workspace>` to view daemon logs
+- **Cleanup**: `bd daemons list` auto-removes stale sockets
+
+See [commands/daemons.md](commands/daemons.md) for complete documentation.
+
 ## Examples
 
 Check out the **[examples/](examples/)** directory for:

commands/daemons.md

@@ -0,0 +1,215 @@
+# bd daemons - Daemon Management
+
+Manage bd daemon processes across all repositories and worktrees.
+
+## Synopsis
+
+```bash
+bd daemons <subcommand> [flags]
+```
+
+## Description
+
+The `bd daemons` command provides tools for discovering, monitoring, and managing multiple bd daemon processes across your system. This is useful when working with multiple repositories or git worktrees.
+
+## Subcommands
+
+### list
+
+List all running bd daemons with metadata.
+
+```bash
+bd daemons list [--search DIRS] [--json] [--no-cleanup]
+```
+
+**Flags:**
+- `--search` - Directories to search for daemons (default: home, /tmp, cwd)
+- `--json` - Output in JSON format
+- `--no-cleanup` - Skip auto-cleanup of stale sockets
+
+**Example:**
+```bash
+bd daemons list
+bd daemons list --search /Users/me/projects --json
+```
+
+### health
+
+Check health of all bd daemons and report issues.
+
+```bash
+bd daemons health [--search DIRS] [--json]
+```
+
+Reports:
+- Stale sockets (dead processes)
+- Version mismatches between daemon and CLI
+- Unresponsive daemons
+
+**Flags:**
+- `--search` - Directories to search for daemons
+- `--json` - Output in JSON format
+
+**Example:**
+```bash
+bd daemons health
+bd daemons health --json
+```
+
+### stop
+
+Stop a specific daemon gracefully.
+
+```bash
+bd daemons stop <workspace-path|pid> [--json]
+```
+
+**Arguments:**
+- `<workspace-path|pid>` - Workspace path or PID of daemon to stop
+
+**Flags:**
+- `--json` - Output in JSON format
+
+**Example:**
+```bash
+bd daemons stop /Users/me/projects/myapp
+bd daemons stop 12345
+bd daemons stop /Users/me/projects/myapp --json
+```
+
+### logs
+
+View logs for a specific daemon.
+
+```bash
+bd daemons logs <workspace-path|pid> [-f] [-n LINES] [--json]
+```
+
+**Arguments:**
+- `<workspace-path|pid>` - Workspace path or PID of daemon
+
+**Flags:**
+- `-f, --follow` - Follow log output (like tail -f)
+- `-n, --lines INT` - Number of lines to show from end (default: 50)
+- `--json` - Output in JSON format
+
+**Example:**
+```bash
+bd daemons logs /Users/me/projects/myapp
+bd daemons logs 12345 -n 100
+bd daemons logs /Users/me/projects/myapp -f
+bd daemons logs 12345 --json
+```
+
+### killall
+
+Stop all running bd daemons.
+
+```bash
+bd daemons killall [--search DIRS] [--force] [--json]
+```
+
+Uses escalating shutdown strategy:
+1. RPC shutdown (2 second timeout)
+2. SIGTERM (3 second timeout)
+3. SIGKILL (1 second timeout)
+
+**Flags:**
+- `--search` - Directories to search for daemons
+- `--force` - Use SIGKILL immediately if graceful shutdown fails
+- `--json` - Output in JSON format
+
+**Example:**
+```bash
+bd daemons killall
+bd daemons killall --force
+bd daemons killall --json
+```
+
+## Common Use Cases
+
+### Version Upgrade
+
+After upgrading bd, restart all daemons to use the new version:
+
+```bash
+bd daemons health  # Check for version mismatches
+bd daemons killall # Stop all old daemons
+# Daemons will auto-start with new version on next bd command
+```
+
+### Debugging
+
+Check daemon status and view logs:
+
+```bash
+bd daemons list
+bd daemons health
+bd daemons logs /path/to/workspace -n 100
+```
+
+### Cleanup
+
+Remove stale daemon sockets:
+
+```bash
+bd daemons list  # Auto-cleanup happens by default
+bd daemons list --no-cleanup  # Skip cleanup
+```
+
+### Multi-Workspace Management
+
+Discover daemons in specific directories:
+
+```bash
+bd daemons list --search /Users/me/projects
+bd daemons health --search /Users/me/work
+```
+
+## Troubleshooting
+
+### Stale Sockets
+
+If you see stale sockets (dead process but socket file exists):
+
+```bash
+bd daemons list  # Auto-cleanup removes stale sockets
+```
+
+### Version Mismatch
+
+If daemon version != CLI version:
+
+```bash
+bd daemons health  # Identify mismatched daemons
+bd daemons killall # Stop all daemons
+# Next bd command will auto-start new version
+```
+
+### Daemon Won't Stop
+
+If graceful shutdown fails:
+
+```bash
+bd daemons killall --force  # Force kill with SIGKILL
+```
+
+### Can't Find Daemon
+
+If daemon isn't discovered:
+
+```bash
+bd daemons list --search /path/to/workspace
+```
+
+Or check the socket manually:
+
+```bash
+ls -la /path/to/workspace/.beads/bd.sock
+```
+
+## See Also
+
+- [bd daemon](daemon.md) - Start a daemon manually
+- [AGENTS.md](../AGENTS.md) - Agent workflow guide
+- [README.md](../README.md) - Main documentation