diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 689dfa5ea..e5cf7f575 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -8,7 +8,7 @@ - Dependency-aware issue tracking - Auto-sync with Git via JSONL - AI-optimized CLI with JSON output -- Built-in daemon for background operations +- Dolt server mode for background operations - MCP server integration for Claude and other AI assistants ## Tech Stack diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 24b22667c..1fdf2a34f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -180,13 +180,13 @@ go test -race -coverprofile=coverage.out ./... ### Dual-Mode Testing Pattern -**IMPORTANT**: bd supports two execution modes: *direct mode* (Dolt database access) and *daemon mode* (RPC via background process). Commands must work identically in both modes. To prevent bugs like GH#719, GH#751, and bd-fu83, use the dual-mode test framework for testing commands. +**IMPORTANT**: bd supports two execution modes: *embedded mode* (direct Dolt database access) and *server mode* (RPC via Dolt server). Commands must work identically in both modes. To prevent bugs like GH#719, GH#751, and bd-fu83, use the dual-mode test framework for testing commands. ```go // cmd/bd/dual_mode_test.go provides the framework func TestMyCommand(t *testing.T) { - // This test runs TWICE: once in direct mode, once with a live daemon + // This test runs TWICE: once in embedded mode, once with a live Dolt server RunDualModeTest(t, "my_test", func(t *testing.T, env *DualModeTestEnv) { // Create test data using mode-agnostic helpers issue := &types.Issue{ @@ -220,7 +220,7 @@ Available `DualModeTestEnv` helper methods: - `ListIssues(filter)` - List issues matching filter - `GetReadyWork()` - Get issues ready for work - `AddLabel(id, label)` - Add a label to an issue -- `Mode()` - Returns "direct" or "daemon" for error messages +- `Mode()` - Returns "embedded" or "server" for error messages Run dual-mode tests: ```bash diff --git a/FEDERATION-SETUP.md b/FEDERATION-SETUP.md index 3798c32d2..3eeb5cf82 100644 --- a/FEDERATION-SETUP.md +++ b/FEDERATION-SETUP.md @@ -152,8 +152,8 @@ as commands: ### "requires direct database access" -Federation commands require the Dolt backend. Ensure you're not running in -daemon mode for federation operations. +Federation commands require the Dolt backend with direct database access. Ensure +you have the Dolt backend configured for federation operations. ### "peer already exists" diff --git a/NEWSLETTER.md b/NEWSLETTER.md index eb2c6e23c..eed75a884 100644 --- a/NEWSLETTER.md +++ b/NEWSLETTER.md @@ -12,7 +12,7 @@ What was removed: - `internal/syncbranch/` -- 5,720 lines of worktree management - `snapshot_manager`, `deletion_tracking`, and the 3-way merge engine - Doctor sync-branch checks and fixes -- Daemon infrastructure (lockfile activity signals, orchestrator) +- Legacy daemon infrastructure (lockfile activity signals, orchestrator) - The dead `bd repair` command Manual `bd export` and `bd import` remain available as escape hatches. diff --git a/RELEASING.md b/RELEASING.md index cd63b6e27..77b7f92cf 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -126,8 +126,8 @@ Use the version bump script to update all version references and create the rele | `--install` | Build and install bd to `~/go/bin` AND `~/.local/bin` | | `--mcp-local` | Install beads-mcp from local source via uv/pip | | `--upgrade-mcp` | Upgrade beads-mcp from PyPI (after PyPI publish) | -| `--restart-daemons` | Restart all bd daemons to pick up new version | -| `--all` | Shorthand for `--install --mcp-local --restart-daemons` | +| `--restart-servers` | Restart all Dolt servers to pick up new version | +| `--all` | Shorthand for `--install --mcp-local --restart-servers` | This updates: - `cmd/bd/version.go` - CLI version constant diff --git a/claude-plugin/commands/export.md b/claude-plugin/commands/export.md index e0bbbd31c..cbd92c029 100644 --- a/claude-plugin/commands/export.md +++ b/claude-plugin/commands/export.md @@ -15,7 +15,7 @@ Issues are sorted by ID for consistent diffs, making git diffs readable. ## Automatic Export -The daemon automatically exports to `.beads/issues.jsonl` after any CRUD operation (5-second debounce). Manual export is rarely needed unless you need a custom output location or filtered export. +The Dolt server automatically exports to `.beads/issues.jsonl` after any CRUD operation (5-second debounce). Manual export is rarely needed unless you need a custom output location or filtered export. Export is used for: - Git version control diff --git a/claude-plugin/commands/import.md b/claude-plugin/commands/import.md index 47acb011c..78e1f2343 100644 --- a/claude-plugin/commands/import.md +++ b/claude-plugin/commands/import.md @@ -28,7 +28,7 @@ bd import -i issues.jsonl --dry-run ## Automatic Import -The daemon automatically imports from `.beads/issues.jsonl` when it's newer than the database (e.g., after `git pull`). Manual import is rarely needed. +The Dolt server automatically imports from `.beads/issues.jsonl` when it's newer than the database (e.g., after `git pull`). Manual import is rarely needed. ## Options diff --git a/claude-plugin/commands/sync.md b/claude-plugin/commands/sync.md index d4992e543..68500c3ca 100644 --- a/claude-plugin/commands/sync.md +++ b/claude-plugin/commands/sync.md @@ -51,4 +51,4 @@ The merge command includes safety checks: ## Note -Most users should rely on the daemon's automatic sync (`bd daemon --auto-commit --auto-push`) instead of running manual sync. This command is useful for one-off syncs or when not using the daemon. +Most users should rely on the Dolt server's automatic sync (with `dolt.auto-commit` enabled) instead of running manual sync. This command is useful for one-off syncs or when not using the Dolt server. diff --git a/claude-plugin/skills/beads/resources/CLI_REFERENCE.md b/claude-plugin/skills/beads/resources/CLI_REFERENCE.md index f3ee8d375..a4d71500a 100644 --- a/claude-plugin/skills/beads/resources/CLI_REFERENCE.md +++ b/claude-plugin/skills/beads/resources/CLI_REFERENCE.md @@ -73,14 +73,14 @@ bd prime --export # Dump default content for customization ### Check Status ```bash -# Check database path and daemon status +# Check database path and server status bd info --json # Example output: # { # "database_path": "/path/to/.beads/beads.db", # "issue_prefix": "bd", -# "daemon_running": true +# "server_running": true # } ``` @@ -361,7 +361,7 @@ Global flags work with any bd command and must appear **before** the subcommand. **Auto-detection (v0.21.1+):** bd automatically detects sandboxed environments and enables sandbox mode. -When detected, you'll see: `ℹ️ Sandbox detected, using direct mode` +When detected, you'll see: `Sandbox detected, using embedded mode` **Manual override:** @@ -370,15 +370,15 @@ When detected, you'll see: `ℹ️ Sandbox detected, using direct mode` bd --sandbox # Equivalent to combining these flags: -bd --no-daemon --no-auto-flush --no-auto-import +bd --no-auto-flush --no-auto-import ``` **What it does:** -- Disables daemon (uses direct SQLite mode) +- Uses embedded mode (direct database access, no Dolt server) - Disables auto-export to JSONL - Disables auto-import from JSONL -**When to use:** Sandboxed environments where daemon can't be controlled (permission restrictions), or when auto-detection doesn't trigger. +**When to use:** Sandboxed environments where the Dolt server can't be controlled (permission restrictions), or when auto-detection doesn't trigger. ### Staleness Control @@ -412,8 +412,8 @@ bd import --force -i .beads/issues.jsonl # JSON output for programmatic use bd --json -# Force direct mode (bypass daemon) -bd --no-daemon +# Force embedded mode (bypass Dolt server) +bd --embedded # Disable auto-sync bd --no-auto-flush # Disable auto-export to JSONL diff --git a/claude-plugin/skills/beads/resources/TROUBLESHOOTING.md b/claude-plugin/skills/beads/resources/TROUBLESHOOTING.md index f30ea5238..ffba47c27 100644 --- a/claude-plugin/skills/beads/resources/TROUBLESHOOTING.md +++ b/claude-plugin/skills/beads/resources/TROUBLESHOOTING.md @@ -5,24 +5,23 @@ Common issues encountered when using bd and how to resolve them. ## Interface-Specific Troubleshooting **MCP tools (local environment):** -- MCP tools require bd daemon running -- Check daemon status: `bd daemon status` (CLI) -- If MCP tools fail, verify daemon is running and restart if needed -- MCP tools automatically use daemon mode (no --no-daemon option) +- MCP tools require Dolt server running +- Check server status: `bd doctor` (CLI) +- If MCP tools fail, verify Dolt server is running and restart if needed **CLI (web environment or local):** -- CLI can use daemon mode (default) or direct mode (--no-daemon) -- Direct mode has 3-5 second sync delay +- CLI can use server mode (default) or embedded mode (direct database access) +- Embedded mode has 3-5 second sync delay - Web environment: Install via `npm install -g @beads/cli` - Web environment: Initialize via `bd init ` before first use -**Most issues below apply to both interfaces** - the underlying database and daemon behavior is the same. +**Most issues below apply to both interfaces** - the underlying database and server behavior is the same. ## Contents - [Dependencies Not Persisting](#dependencies-not-persisting) - [Status Updates Not Visible](#status-updates-not-visible) -- [Daemon Won't Start](#daemon-wont-start) +- [Dolt Server Won't Start](#dolt-server-wont-start) - [Database Errors on Cloud Storage](#database-errors-on-cloud-storage) - [JSONL File Not Created](#jsonl-file-not-created) - [Version Requirements](#version-requirements) @@ -40,7 +39,7 @@ bd show issue-2 ``` ### Root Cause (Fixed in v0.15.0+) -This was a **bug in bd** (GitHub issue #101) where the daemon ignored dependencies during issue creation. **Fixed in bd v0.15.0** (Oct 21, 2025). +This was a **bug in bd** (GitHub issue #101) where dependencies were ignored during issue creation. **Fixed in bd v0.15.0** (Oct 21, 2025). ### Resolution @@ -61,10 +60,10 @@ go install github.com/steveyegge/beads/cmd/bd@latest # See https://github.com/steveyegge/beads#installing ``` -**3. Restart daemon after upgrade:** +**3. Restart Dolt server after upgrade:** ```bash -pkill -f "bd daemon" # Kill old daemon -bd daemon start # Start new daemon with fix +bd dolt stop # Stop old server +bd dolt start # Start new server with fix ``` **4. Test dependency creation:** @@ -80,15 +79,14 @@ bd show If dependencies still don't persist after updating: -1. **Check daemon is running:** +1. **Check Dolt server is running:** ```bash - ps aux | grep "bd daemon" + bd doctor ``` -2. **Try without --no-daemon flag:** +2. **Try in server mode:** ```bash - # Instead of: bd --no-daemon dep add ... - # Use: bd dep add ... (let daemon handle it) + # Use: bd dep add ... (let the Dolt server handle it) ``` 3. **Check JSONL file:** @@ -108,77 +106,77 @@ If dependencies still don't persist after updating: ### Symptom ```bash -bd --no-daemon update issue-1 --status in_progress -# Reports: ✓ Updated issue: issue-1 +# In embedded mode, updates may not reflect immediately +bd update issue-1 --status in_progress bd show issue-1 # Shows: Status: open (not in_progress!) ``` ### Root Cause -This is **expected behavior**, not a bug. Understanding requires knowing bd's architecture: +This is **expected behavior** when using embedded mode. Understanding requires knowing bd's architecture: **BD Architecture:** - **JSONL files** (`.beads/issues.jsonl`): Human-readable export format -- **SQLite database** (`.beads/*.db`): Source of truth for queries -- **Daemon**: Syncs JSONL ↔ SQLite every 5 minutes +- **Dolt database** (`.beads/dolt/`): Source of truth for queries +- **Dolt server**: Syncs JSONL and Dolt database -**What `--no-daemon` actually does:** +**In embedded mode (without Dolt server):** - **Writes**: Go directly to JSONL file -- **Reads**: Still come from SQLite database -- **Sync delay**: Daemon imports JSONL → SQLite periodically +- **Reads**: Still come from the database +- **Sync delay**: The Dolt server imports JSONL periodically ### Resolution -**Option 1: Use daemon mode (recommended)** +**Option 1: Use server mode (recommended)** ```bash -# Don't use --no-daemon for CRUD operations +# With the Dolt server running, operations reflect immediately bd update issue-1 --status in_progress bd show issue-1 -# ✓ Status reflects immediately +# Status reflects immediately ``` -**Option 2: Wait for sync (if using --no-daemon)** +**Option 2: Wait for sync (if using embedded mode)** ```bash -bd --no-daemon update issue-1 --status in_progress -# Wait 3-5 seconds for daemon to sync +bd update issue-1 --status in_progress +# Wait for server to sync sleep 5 bd show issue-1 -# ✓ Status should reflect now +# Status should reflect now ``` **Option 3: Manual sync trigger** ```bash -bd --no-daemon update issue-1 --status in_progress +bd update issue-1 --status in_progress # Trigger sync by exporting/importing bd export > /dev/null 2>&1 # Forces sync bd show issue-1 ``` -### When to Use `--no-daemon` +### When to Use Embedded Mode -**Use --no-daemon for:** +**Use embedded mode for:** - Batch import scripts (performance) -- CI/CD environments (no persistent daemon) +- CI/CD environments (no persistent server) - Testing/debugging -**Don't use --no-daemon for:** +**Don't use embedded mode for:** - Interactive development - Real-time status checks - When you need immediate query results --- -## Daemon Won't Start +## Dolt Server Won't Start ### Symptom ```bash -bd daemon start +bd dolt start # Error: not in a git repository # Hint: run 'git init' to initialize a repository ``` ### Root Cause -bd daemon requires a **git repository** because it uses git for: +The Dolt server requires a **git repository** because it uses git for: - Syncing issues to git remote (optional) - Version control of `.beads/*.jsonl` files - Commit history of issue changes @@ -189,20 +187,13 @@ bd daemon requires a **git repository** because it uses git for: ```bash # In your project directory git init -bd daemon start -# ✓ Daemon should start now +bd dolt start +# Dolt server should start now ``` -**Run in local-only mode (no git required):** -```bash -# If you don't want daemon to use git at all -bd daemon start --local -``` - -**Flags:** -- `--local`: Run in local-only mode (no git required, no sync) -- `--interval=10m`: Custom sync interval (default: 5s) -- `--auto-commit=true`: Auto-commit JSONL changes +**Configuration:** +- `dolt.auto-commit: on`: Auto-commit changes +- See `bd config --help` for all Dolt server options --- @@ -282,37 +273,36 @@ bd create "My task" ### Symptom ```bash bd init myproject -bd --no-daemon create "Test" -t task +bd create "Test" -t task ls .beads/ # Only shows: .gitignore, myproject.db # Missing: issues.jsonl ``` ### Root Cause -**JSONL initialization coupling.** The `issues.jsonl` file is created by daemon on first startup, not by `bd init`. +**JSONL initialization coupling.** The `issues.jsonl` file is created by the Dolt server on first startup, not by `bd init`. ### Resolution -**Start daemon once to initialize JSONL:** +**Start Dolt server once to initialize JSONL:** ```bash -bd daemon start --local & +bd dolt start # Wait for initialization sleep 2 # Now JSONL file exists ls .beads/issues.jsonl -# ✓ File created +# File created -# Subsequent --no-daemon operations work -bd --no-daemon create "Task 1" -t task +# Create issues normally +bd create "Task 1" -t task cat .beads/issues.jsonl -# ✓ Shows task data +# Shows task data ``` **Why this matters:** -- Daemon owns the JSONL export format -- First daemon run creates empty JSONL skeleton -- `--no-daemon` operations assume JSONL exists +- The Dolt server owns the JSONL export format +- First server run creates empty JSONL skeleton **Pattern for batch scripts:** ```bash @@ -320,15 +310,15 @@ cat .beads/issues.jsonl # Batch import script bd init myproject -bd daemon start --local & # Start daemon +bd dolt start # Start Dolt server sleep 3 # Wait for initialization -# Now safe to use --no-daemon for performance +# Create issues for item in "${items[@]}"; do - bd --no-daemon create "$item" -t feature + bd create "$item" -t feature done -# Daemon syncs JSONL → SQLite in background +# Server syncs in background sleep 5 # Wait for final sync # Query results @@ -361,10 +351,10 @@ claude plugin update beads **v0.15.0:** - MCP parameter names changed from `from_id/to_id` to `issue_id/depends_on_id` -- Dependency creation now persists correctly in daemon mode +- Dependency creation now persists correctly in server mode **v0.14.0:** -- Daemon architecture changes +- Architecture changes - Auto-sync JSONL behavior introduced --- @@ -427,8 +417,8 @@ Before reporting issues, collect this information: # 1. Version bd version -# 2. Daemon status -ps aux | grep "bd daemon" +# 2. Dolt server status +bd doctor # 3. Database location echo $PWD/.beads/*.db @@ -473,10 +463,10 @@ If the **bd-issue-tracking skill** provides incorrect guidance: | Problem | Quick Fix | |---------|-----------| | Dependencies not saving | Upgrade to bd v0.15.0+ | -| Status updates lag | Use daemon mode (not `--no-daemon`) | -| Daemon won't start | Run `git init` first | +| Status updates lag | Use server mode (ensure Dolt server is running) | +| Dolt server won't start | Run `git init` first | | Database errors on Google Drive | Move to local filesystem | -| JSONL file missing | Start daemon once: `bd daemon start &` | +| JSONL file missing | Start Dolt server once: `bd dolt start` | | Dependencies backwards (MCP) | Update to v0.15.0+, use `issue_id/depends_on_id` correctly | --- diff --git a/claude-plugin/skills/beads/resources/WORKTREES.md b/claude-plugin/skills/beads/resources/WORKTREES.md index d62edecab..39f29e74b 100644 --- a/claude-plugin/skills/beads/resources/WORKTREES.md +++ b/claude-plugin/skills/beads/resources/WORKTREES.md @@ -25,7 +25,7 @@ bd worktree remove .worktrees/{name} **Why?** `bd worktree` auto-configures: - Beads database redirect files - Proper gitignore entries -- Daemon bypass for worktree operations +- Embedded mode for worktree operations ## Architecture @@ -41,7 +41,7 @@ main-repo/ └── .beads ← Redirect file ``` -**Key insight**: Daemon auto-bypasses for wisp operations in worktrees. +**Key insight**: Wisp operations in worktrees use embedded mode automatically. ## Commands diff --git a/cmd/bd/docs.md b/cmd/bd/docs.md index 78a80f056..4233334df 100644 --- a/cmd/bd/docs.md +++ b/cmd/bd/docs.md @@ -6,15 +6,15 @@ Path: @/cmd/bd The `cmd/bd` directory contains the complete CLI application for the Beads issue tracker. It implements the `bd` command-line tool, which users interact with to create, query, manage, and synchronize issues across distributed systems. -The CLI is built on the Cobra framework and consists of command implementations for core operations (create, list, delete, import, export, sync, etc.), daemon management for background operations, and version reporting that includes git commit and branch information from the build. +The CLI is built on the Cobra framework and consists of command implementations for core operations (create, list, delete, import, export, sync, etc.), Dolt server management for background operations, and version reporting that includes git commit and branch information from the build. ### How it fits into the larger codebase - **Entry Point**: The CLI defined here (`cmd/bd/main.go`) is the user-facing interface to the entire beads system. All user interactions flow through this package. -- **Integration with Core Libraries**: The CLI commands call into libraries at `@/internal/beads` (database discovery, version detection), `@/internal/storage` (database operations), `@/internal/rpc` (daemon communication), and other internal packages. +- **Integration with Core Libraries**: The CLI commands call into libraries at `@/internal/beads` (database discovery, version detection), `@/internal/storage` (database operations), `@/internal/rpc` (Dolt server communication), and other internal packages. -- **Daemon Communication**: Commands use RPC client logic to communicate with the background daemon (PersistentPreRun hook), allowing the CLI to operate either in daemon mode (delegating to the daemon) or direct mode (local database operations). +- **Server Communication**: Commands use RPC client logic to communicate with the Dolt server (PersistentPreRun hook), allowing the CLI to operate either in server mode (delegating to the Dolt server) or embedded mode (local database operations). - **Version Reporting**: The version command (`@/cmd/bd/version.go`) reports full build information - it resolves git commit and branch from ldflags set at build time via the Makefile (`@/Makefile`) and goreleaser config (`@/.goreleaser.yml`). This enables users to identify exactly what code their binary was built from. @@ -44,16 +44,16 @@ The CLI is built on the Cobra framework and consists of command implementations - **Text Output** (lines 52-58 in `version.go`): Shows format like `bd version 0.29.0 (dev: main@7e70940)` when both commit and branch are available - **JSON Output** (lines 39-50): Includes optional `commit` and `branch` fields when available -5. **Daemon Version Checking** (lines 63-109): The `--daemon` flag shows daemon/client compatibility by calling health RPC endpoints +5. **Server Version Checking** (lines 63-109): The `--server` flag shows server/client compatibility by calling health RPC endpoints **Command Structure**: - All commands follow the Cobra pattern with `Command` structs and run functions - Commands register themselves via `init()` functions that add them to `rootCmd` -- The daemon connection state is managed via PersistentPreRun hooks, allowing most commands to transparently work in daemon or direct mode +- The server connection state is managed via PersistentPreRun hooks, allowing most commands to transparently work in server or embedded mode **Key Data Paths**: - User input → Cobra command parsing → Internal beads library calls → Storage layer → Git operations -- Responses flow back through storage → RPC (if daemon) or direct return → formatted output +- Responses flow back through storage → RPC (if server) or direct return → formatted output ### Things to Know diff --git a/docs/ADVANCED.md b/docs/ADVANCED.md index 9a05c17a1..5ecb08f36 100644 --- a/docs/ADVANCED.md +++ b/docs/ADVANCED.md @@ -162,7 +162,7 @@ When agents discover duplicate issues, they should: Git worktrees work with bd. Each worktree can have its own `.beads` directory, or worktrees can share a database via redirects (see [Database Redirects](#database-redirects)). -**With Dolt backend:** Each worktree operates directly on the database — no daemon coordination needed. Use `bd sync` to synchronize JSONL with git when ready. +**With Dolt backend:** Each worktree operates directly on the database — no special coordination needed. Use `bd sync` to synchronize JSONL with git when ready. **With Dolt server mode:** Multiple worktrees can connect to the same Dolt server for concurrent access without conflicts. @@ -356,10 +356,10 @@ Understanding the role of each component: - **Business logic** — Ready work calculation, merge operations, import/export - **CLI commands** — Direct database access via `bd` command -### RPC Layer (Dolt Server Mode) -- **Multi-writer access** — Connects to a running `dolt sql-server` for concurrent clients +### RPC Layer (Server Mode) +- **Multi-writer access** — Connects to a running Dolt server (`bd dolt start`) for concurrent clients - **Used in multi-agent setups** — Gas Town and similar environments where multiple agents write simultaneously -- **Not needed for single-user** — a single Dolt server handles all local operations +- **Not needed for single-user** — embedded mode handles all local operations ### MCP Server (Optional) - **Protocol adapter** — Translates MCP calls to direct CLI invocations diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 24f6105e6..f973ec2c8 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -164,17 +164,17 @@ This eliminates the need for central coordination while ensuring all machines co See [COLLISION_MATH.md](COLLISION_MATH.md) for birthday paradox calculations on hash length vs collision probability. -## Daemon Architecture +## Server Architecture -Each workspace runs its own background daemon for auto-sync: +Each workspace can run its own Dolt server for multi-writer access: ``` ┌─────────────────────────────────────────────────────────────────┐ -│ RPC Server │ +│ Dolt Server Mode │ │ │ │ ┌─────────────┐ ┌─────────────┐ │ -│ │ RPC Server │ │ Background │ │ -│ │ (bd.sock) │ │ Tasks │ │ +│ │ RPC Server │ │ dolt │ │ +│ │ │ │ sql-server │ │ │ └─────────────┘ └─────────────┘ │ │ │ │ │ │ └──────────────────┘ │ @@ -186,16 +186,20 @@ Each workspace runs its own background daemon for auto-sync: │ └─────────────┘ │ └─────────────────────────────────────────────────────────────────┘ - CLI commands ───RPC───▶ Server ───SQL───▶ Database + CLI commands ───SQL───▶ dolt sql-server ───▶ Database or - CLI commands ───SQL───▶ Database (via dolt sql-server) + CLI commands ───SQL───▶ Database (embedded mode) ``` **Server mode:** - Connects to `dolt sql-server` (multi-writer, high-concurrency) +- PID file at `.beads/dolt/sql-server.pid` +- Logs at `.beads/dolt/sql-server.log` + +**Embedded mode:** +- Direct database access (single-writer, no server process) **Communication:** -- Unix domain socket at `.beads/bd.sock` (Windows: named pipes) - Protocol defined in `internal/rpc/protocol.go` - Used by Dolt server mode for multi-writer access @@ -303,11 +307,10 @@ Each issue in `.beads/issues.jsonl` is a JSON object with the following fields. ``` .beads/ -├── dolt/ # Dolt database directory (gitignored) +├── dolt/ # Dolt database, sql-server.pid, sql-server.log (gitignored) ├── issues.jsonl # JSONL export (git-tracked, for portability) ├── metadata.json # Backend config (local, gitignored) -├── config.yaml # Project config (optional) -└── bd.sock # RPC socket (gitignored, server mode only) +└── config.yaml # Project config (optional) ``` ## Key Code Paths diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md index f2ca07ae7..542635fe6 100644 --- a/docs/CLI_REFERENCE.md +++ b/docs/CLI_REFERENCE.md @@ -19,14 +19,13 @@ ### Check Status ```bash -# Check database path and daemon status +# Check database path and server status bd info --json # Example output: # { # "database_path": "/path/to/.beads/beads.db", # "issue_prefix": "bd", -# "daemon_running": true, # "agent_mail_enabled": false # } ``` @@ -283,17 +282,14 @@ When detected, you'll see: `ℹ️ Sandbox detected, using direct mode` ```bash # Explicitly enable sandbox mode bd --sandbox - -# Equivalent to combining these flags: -bd --no-daemon --no-auto-flush --no-auto-import ``` **What it does:** -- Disables daemon (uses direct SQLite mode) +- Uses embedded database mode (no server needed) - Disables auto-export to JSONL - Disables auto-import from JSONL -**When to use:** Sandboxed environments where daemon can't be controlled (permission restrictions), or when auto-detection doesn't trigger. +**When to use:** Sandboxed environments where the Dolt server can't be controlled (permission restrictions), or when auto-detection doesn't trigger. ### Staleness Control @@ -327,9 +323,6 @@ bd import --force -i .beads/issues.jsonl # JSON output for programmatic use bd --json -# Force direct mode (bypass daemon) -bd --no-daemon - # Disable auto-sync bd --no-auto-flush # Disable auto-export to JSONL bd --no-auto-import # Disable auto-import from JSONL @@ -553,7 +546,7 @@ bd mol burn --dry-run bd mol burn --force --json ``` -**Note:** Most mol commands require `--no-daemon` flag when daemon is running. +**Note:** Mol commands use the standard Dolt database access path. ## Database Management diff --git a/docs/COMMUNITY_TOOLS.md b/docs/COMMUNITY_TOOLS.md index 6115ac0b7..cf317fd64 100644 --- a/docs/COMMUNITY_TOOLS.md +++ b/docs/COMMUNITY_TOOLS.md @@ -39,7 +39,7 @@ A curated list of community-built UIs, extensions, and integrations for Beads. R ## Editor Extensions -- **[vscode-beads](https://marketplace.visualstudio.com/items?itemName=planet57.vscode-beads)** - VS Code extension with issues panel and daemon management. Built by [@jdillon](https://github.com/jdillon). (TypeScript) +- **[vscode-beads](https://marketplace.visualstudio.com/items?itemName=planet57.vscode-beads)** - VS Code extension with issues panel and server management. Built by [@jdillon](https://github.com/jdillon). (TypeScript) - **[Agent Native Abstraction Layer for Beads](https://marketplace.visualstudio.com/items?itemName=AgentNativeAbstractionLayer.agent-native-kanban)** (ANAL Beads) - VS Code Kanban board. Maintained by [@sebcook-ctrl](https://github.com/sebcook-ctrl). (Node.js) @@ -69,7 +69,7 @@ A curated list of community-built UIs, extensions, and integrations for Beads. R ## SDKs & Libraries -- **[beads-sdk](https://github.com/HerbCaudill/beads-sdk)** - Typed TypeScript SDK with zero runtime dependencies. High-level `BeadsClient` for CRUD, filtering, search, labels, dependencies, comments, epics, and sync. Includes `DaemonSocket` for real-time mutation watching via the beads daemon. Install with `pnpm add @herbcaudill/beads-sdk`. Built by [@HerbCaudill](https://github.com/HerbCaudill). (TypeScript) +- **[beads-sdk](https://github.com/HerbCaudill/beads-sdk)** - Typed TypeScript SDK with zero runtime dependencies. High-level `BeadsClient` for CRUD, filtering, search, labels, dependencies, comments, epics, and sync. Includes `DaemonSocket` for real-time mutation watching via the Dolt server. Install with `pnpm add @herbcaudill/beads-sdk`. Built by [@HerbCaudill](https://github.com/HerbCaudill). (TypeScript) ## Claude Code Orchestration diff --git a/docs/CONTRIBUTOR_NAMESPACE_ISOLATION.md b/docs/CONTRIBUTOR_NAMESPACE_ISOLATION.md index a4e558b91..7dcb49c3c 100644 --- a/docs/CONTRIBUTOR_NAMESPACE_ISOLATION.md +++ b/docs/CONTRIBUTOR_NAMESPACE_ISOLATION.md @@ -265,16 +265,16 @@ Contributor routing works independently of the project repo's sync configuration | **Direct** | Uses `.beads/` directly | Uses `~/.beads-planning/.beads/` | Both use direct storage, no interaction | | **Sync-branch** | Uses separate branch for beads | Uses direct storage | Planning repo does NOT inherit `sync.branch` config | | **No-db mode** | JSONL-only operations | Routes JSONL operations to planning repo | Planning repo still uses database | -| **Daemon mode** | Background auto-sync | Daemon bypassed for routed issues | Planning repo operations are synchronous | +| **Server mode** | Background Dolt server | Server bypassed for routed issues | Planning repo operations are synchronous | | **Local-only** | No git remote | Works normally | Planning repo can have its own git remote independently | | **External (BEADS_DIR)** | Uses separate repo via env var | BEADS_DIR takes precedence over routing | If `BEADS_DIR` is set, routing config is ignored | ### Key Principles 1. **Separate databases**: Planning repo is completely independent - it has its own `.beads/` directory -2. **No config inheritance**: Planning repo does not inherit project's `sync.branch`, `no-db`, or daemon settings +2. **No config inheritance**: Planning repo does not inherit project's `sync.branch`, `no-db`, or server mode settings 3. **BEADS_DIR precedence**: If `BEADS_DIR` environment variable is set, it overrides routing configuration -4. **Daemon bypass**: Issues routed to planning repo bypass daemon mode to avoid connection staleness +4. **Direct access**: Issues routed to planning repo use direct database access to avoid connection staleness ## Configuration Reference diff --git a/docs/ERROR_HANDLING.md b/docs/ERROR_HANDLING.md index 22114a211..64fc5e9c6 100644 --- a/docs/ERROR_HANDLING.md +++ b/docs/ERROR_HANDLING.md @@ -63,7 +63,7 @@ if err := createConfigYaml(beadsDir, false); err != nil { - `cmd/bd/init.go` (lines 155-157, 161-163, 167-169, 188-190, 236-238, 272-274, etc.) - `cmd/bd/sync.go` (lines 156, 257, 281, 329, 335, 720-722, 740, 743, 752, 762) - `cmd/bd/create.go` (lines 333-334, 340-341) -- `cmd/bd/daemon_sync.go` (lines 51) +- `cmd/bd/daemon_sync.go` (lines 51) *(handles Dolt server sync operations)* --- @@ -89,7 +89,7 @@ _ = os.Remove(tempPath) **Files using this pattern:** - `cmd/bd/init.go` (line 209, 326-327) - `cmd/bd/sync.go` (lines 696-698) -- `cmd/bd/daemon_sync.go` (lines 102-105) +- `cmd/bd/daemon_sync.go` (lines 102-105) *(server sync cleanup)* - Dozens of other locations throughout the codebase --- @@ -369,4 +369,4 @@ func WarnError(format string, args ...interface{}) { - `cmd/bd/create.go` - Examples of Pattern A for user input validation - `cmd/bd/init.go` - Examples of all three patterns - `cmd/bd/sync.go` - Examples of Pattern B for metadata operations -- `cmd/bd/daemon_sync.go` - Examples of Pattern C for cleanup operations +- `cmd/bd/daemon_sync.go` - Examples of Pattern C for cleanup operations (server sync) diff --git a/docs/EXCLUSIVE_LOCK.md b/docs/EXCLUSIVE_LOCK.md index 363b6f586..55ff35bb5 100644 --- a/docs/EXCLUSIVE_LOCK.md +++ b/docs/EXCLUSIVE_LOCK.md @@ -1,11 +1,11 @@ # Exclusive Lock Protocol -The exclusive lock protocol allows external tools to claim exclusive management of a beads database, preventing the bd daemon from interfering with their operations. +The exclusive lock protocol allows external tools to claim exclusive management of a beads database, preventing the Dolt server from interfering with their operations. ## Use Cases - **Deterministic execution systems** (e.g., VibeCoder) that need full control over database state -- **CI/CD pipelines** that perform atomic issue updates without daemon interference +- **CI/CD pipelines** that perform atomic issue updates without server interference - **Custom automation tools** that manage their own git sync workflow ## How It Works @@ -31,14 +31,14 @@ The lock file is located at `.beads/.exclusive-lock` and contains JSON: - `started_at` (RFC3339 timestamp, required): When the lock was acquired - `version` (string, optional): Version of the lock holder -### Daemon Behavior +### Server Behavior -The bd daemon checks for exclusive locks at the start of each sync cycle: +The Dolt server checks for exclusive locks at the start of each sync cycle: -1. **No lock file**: Daemon proceeds normally with sync operations -2. **Valid lock (process alive)**: Daemon skips all operations for this database -3. **Stale lock (process dead)**: Daemon removes the lock and proceeds -4. **Malformed lock**: Daemon fails safe and skips the database +1. **No lock file**: Server proceeds normally with sync operations +2. **Valid lock (process alive)**: Server skips all operations for this database +3. **Stale lock (process dead)**: Server removes the lock and proceeds +4. **Malformed lock**: Server fails safe and skips the database ### Stale Lock Detection @@ -46,11 +46,11 @@ A lock is considered stale if: - The hostname matches the current machine (case-insensitive) AND - The PID does not exist on the local system (returns ESRCH) -**Important:** The daemon only removes locks when it can definitively determine the process is dead (ESRCH error). If the daemon lacks permission to signal a PID (EPERM), it treats the lock as valid and skips the database. This fail-safe approach prevents accidentally removing locks owned by other users. +**Important:** The server only removes locks when it can definitively determine the process is dead (ESRCH error). If the server lacks permission to signal a PID (EPERM), it treats the lock as valid and skips the database. This fail-safe approach prevents accidentally removing locks owned by other users. -**Remote locks** (different hostname) are always assumed to be valid since the daemon cannot verify remote processes. +**Remote locks** (different hostname) are always assumed to be valid since the server cannot verify remote processes. -When a stale lock is successfully removed, the daemon logs: `Removed stale lock (holder-name), proceeding with sync` +When a stale lock is successfully removed, the server logs: `Removed stale lock (holder-name), proceeding with sync` ## Usage Examples @@ -141,9 +141,9 @@ func main() { ## Edge Cases and Limitations -### Multiple Writers Without Daemon +### Multiple Writers Without Server -The exclusive lock protocol **only prevents daemon interference**. It does NOT provide: +The exclusive lock protocol **only prevents Dolt server interference**. It does NOT provide: - ❌ Mutual exclusion between multiple external tools - ❌ Transaction isolation or ACID guarantees - ❌ Protection against direct file system manipulation @@ -152,21 +152,21 @@ If you need coordination between multiple tools, implement your own locking mech ### Git Worktrees -The daemon already has issues with git worktrees (see AGENTS.md). The exclusive lock protocol doesn't solve this—use `--no-daemon` mode in worktrees instead. +Dolt handles git worktrees natively. The exclusive lock protocol is separate from worktree support. ### Remote Hosts -Locks from remote hosts are always assumed valid because the daemon cannot verify remote PIDs. This means: +Locks from remote hosts are always assumed valid because the server cannot verify remote PIDs. This means: - Stale locks from remote hosts will **not** be automatically cleaned up - You must manually remove stale remote locks ### Lock File Corruption -If the lock file becomes corrupted (invalid JSON), the daemon **fails safe** and skips the database. You must manually fix or remove the lock file. +If the lock file becomes corrupted (invalid JSON), the server **fails safe** and skips the database. You must manually fix or remove the lock file. -## Daemon Logging +## Server Logging -The daemon logs lock-related events: +The Dolt server logs lock-related events: ``` Skipping database (locked by vc-executor) @@ -174,17 +174,17 @@ Removed stale lock (vc-executor), proceeding with sync Skipping database (lock check failed: malformed lock file: unexpected EOF) ``` -Check daemon logs (default: `.beads/daemon.log`) to troubleshoot lock issues. +Check server logs (`.beads/dolt/sql-server.log`) to troubleshoot lock issues. -**Note:** The daemon checks for locks at the start of each sync cycle. If a lock is created during a sync cycle, that cycle will complete, but subsequent cycles will skip the database. +**Note:** The server checks for locks at the start of each sync cycle. If a lock is created during a sync cycle, that cycle will complete, but subsequent cycles will skip the database. ## Testing Your Integration -1. **Start the daemon**: `bd daemon start --interval 1m` +1. **Start the Dolt server**: `bd dolt start` 2. **Create a lock**: Use your tool to create `.beads/.exclusive-lock` -3. **Verify daemon skips**: Check daemon logs for "Skipping database" message +3. **Verify server skips**: Check server logs for "Skipping database" message 4. **Release lock**: Remove `.beads/.exclusive-lock` -5. **Verify daemon resumes**: Check daemon logs for normal sync cycle +5. **Verify server resumes**: Check server logs for normal sync cycle ## Security Considerations @@ -223,7 +223,7 @@ func IsProcessAlive(pid int, hostname string) bool For integration help, see: - **AGENTS.md** - General workflow guidance -- **README.md** - Daemon configuration +- **README.md** - Server configuration - **examples/** - Sample integrations File issues at: https://github.com/steveyegge/beads/issues diff --git a/docs/FAQ.md b/docs/FAQ.md index 501d39bb3..4e45bc45c 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -174,7 +174,7 @@ bd init # Auto-imports from .beads/issues.jsonl # Or initialize new project: cd ~/my-project -bd init # Creates .beads/, sets up daemon +bd init # Creates .beads/, sets up Dolt database git add .beads/ git commit -m "Initialize beads" ``` @@ -195,7 +195,7 @@ bd automatically: - **Exports** to JSONL after CRUD operations (5-second debounce) - **Imports** from JSONL when it's newer than DB (e.g., after `git pull`) -**How auto-import works:** The first bd command after `git pull` detects that `.beads/issues.jsonl` is newer than the database and automatically imports it. There's no background daemon watching for changes - the check happens when you run a bd command. +**How auto-import works:** The first bd command after `git pull` detects that `.beads/issues.jsonl` is newer than the database and automatically imports it. There's no background process watching for changes - the check happens when you run a bd command. **Optional**: For immediate export (no 5-second wait) and guaranteed import after git operations, install the git hooks: ```bash @@ -236,7 +236,7 @@ Each project gets its own `.beads/` directory with its own database and JSONL fi - Multiple agents working on different projects simultaneously → No conflicts - Same machine, different repos → Each finds its own `.beads/*.db` automatically - Agents in subdirectories → bd walks up to find the project root (like git) -- **Per-project daemons** → Each project gets its own daemon at `.beads/bd.sock` (LSP model) +- **Per-project Dolt servers** → Each project gets its own Dolt server (LSP model) **Limitation:** Issues cannot reference issues in other projects. Each database is isolated by design. If you need cross-project tracking, initialize bd in a parent directory that contains both projects. @@ -248,10 +248,10 @@ cd ~/work/webapp && bd ready --json # Uses ~/work/webapp/.beads/webapp.db # Agent 2 working on API cd ~/work/api && bd ready --json # Uses ~/work/api/.beads/api.db -# No conflicts! Completely isolated databases and daemons. +# No conflicts! Completely isolated databases and Dolt servers. ``` -**Architecture:** bd uses per-project daemons (like LSP/language servers) for complete database isolation. See [ADVANCED.md#architecture-daemon-vs-mcp-vs-beads](ADVANCED.md#architecture-daemon-vs-mcp-vs-beads). +**Architecture:** bd uses per-project Dolt servers (like LSP/language servers) for complete database isolation. See [ADVANCED.md](ADVANCED.md) for details. ### What happens if two agents work on the same issue? @@ -407,16 +407,16 @@ Yes! bd has native Windows support (v0.9.0+): - No MSYS or MinGW required - PowerShell install script - Works with Windows paths and filesystem -- Daemon uses TCP instead of Unix sockets +- Dolt server uses TCP instead of Unix sockets See [INSTALLING.md](INSTALLING.md#windows-11) for details. ### Can I use bd with git worktrees? -Yes, but with limitations. The daemon doesn't work correctly with worktrees, so use `--no-daemon` mode: +Yes! Dolt handles worktrees natively. Use embedded mode if the Dolt server is not needed: ```bash -export BEADS_NO_DAEMON=1 +bd dolt set mode embedded bd ready bd create "Fix bug" -p 1 ``` diff --git a/docs/INSTALLING.md b/docs/INSTALLING.md index 5570c8b05..c0ece975a 100644 --- a/docs/INSTALLING.md +++ b/docs/INSTALLING.md @@ -230,8 +230,7 @@ bd version ``` **Windows notes:** -- The background daemon listens on a loopback TCP endpoint recorded in `.beads\bd.sock` -- Keep that metadata file intact +- The Dolt server listens on a loopback TCP endpoint - Allow `bd.exe` loopback traffic through any host firewall ## IDE and Editor Integrations diff --git a/docs/INTERNALS.md b/docs/INTERNALS.md index 50280b0a2..054bf0ab4 100644 --- a/docs/INTERNALS.md +++ b/docs/INTERNALS.md @@ -12,7 +12,7 @@ The original auto-flush implementation suffered from a critical race condition w - **Concurrent access points:** - Auto-flush timer goroutine (5s debounce) - - Daemon sync goroutine + - Server sync goroutine - Concurrent CLI commands - Git hook execution - PersistentPostRun cleanup @@ -151,11 +151,11 @@ The FlushManager is designed to work correctly when commands run multiple times ## Related Subsystems -### Daemon Mode +### Server Mode -When running with daemon mode (`--no-daemon=false`), the CLI delegates to an RPC server. The FlushManager is NOT used in daemon mode - the daemon process has its own flush coordination. +When running with Dolt server mode, the CLI communicates with the Dolt SQL server for database operations. The FlushManager is NOT used in server mode - the server process has its own flush coordination. -The `daemonClient != nil` check in `PersistentPostRun` ensures FlushManager shutdown only occurs in direct mode. +The server mode check in `PersistentPostRun` ensures FlushManager shutdown only occurs in embedded mode. ### Auto-Import diff --git a/docs/LINTING.md b/docs/LINTING.md index 556bce321..7d0a8b348 100644 --- a/docs/LINTING.md +++ b/docs/LINTING.md @@ -6,7 +6,7 @@ This document explains our approach to `golangci-lint` warnings in this codebase Running `golangci-lint run ./...` currently reports **22 issues** as of Nov 6, 2025. These are not actual code quality problems - they are false positives or intentional patterns that reflect idiomatic Go practice. -**Historical note**: The count was ~200 before extensive cleanup in October 2025, reduced to 34 by Oct 27, and now 22 after internal/daemonrunner removal. The remaining issues represent the acceptable baseline that doesn't warrant fixing. +**Historical note**: The count was ~200 before extensive cleanup in October 2025, reduced to 34 by Oct 27, and now 22 after removing legacy daemon code. The remaining issues represent the acceptable baseline that doesn't warrant fixing. ## Issue Breakdown @@ -37,7 +37,7 @@ Fixing these would add noise without improving code quality. The critical cleanu Examples: - Launching `$EDITOR` for issue editing - Executing git commands -- Running bd daemon binary +- Running external commands (e.g., git, dolt) **Pattern 2**: G304 - File inclusion via variable (3 issues) **Status**: Intended feature - user-specified file paths for import/export diff --git a/docs/MULTI_REPO_AGENTS.md b/docs/MULTI_REPO_AGENTS.md index d9efd3246..47f8dc622 100644 --- a/docs/MULTI_REPO_AGENTS.md +++ b/docs/MULTI_REPO_AGENTS.md @@ -8,7 +8,7 @@ This guide covers multi-repo workflow patterns specifically for AI agents workin ### Single MCP Server (Recommended) -AI agents should use **one MCP server instance** that automatically routes to per-project daemons: +AI agents should use **one MCP server instance** that automatically routes to per-project Dolt servers: ```json { @@ -21,17 +21,17 @@ AI agents should use **one MCP server instance** that automatically routes to pe The MCP server automatically: - Detects current workspace from working directory -- Routes to correct per-project daemon (`.beads/bd.sock`) -- Auto-starts daemon if not running +- Routes to correct per-project Dolt server +- Auto-starts Dolt server if not running - Maintains complete database isolation **Architecture:** ``` MCP Server (one instance) ↓ -Per-Project Daemons (one per workspace) +Per-Project Dolt Servers (one per workspace) ↓ -SQLite Databases (complete isolation) +Dolt Databases (complete isolation) ``` ### Multi-Repo Config Options @@ -264,7 +264,7 @@ bd list --json | jq '.[] | select(.source_repo == "~/.beads-planning")' bd config get routing.contributor # Should be ~/.beads-planning ``` -### Daemon routing to wrong database +### Server routing to wrong database **Symptom:** MCP operations affect wrong project @@ -314,7 +314,7 @@ bd doctor quick # Validate local installation health - ❌ Don't duplicate issues across repos ### General -- ✅ Always use single MCP server (per-project daemons) +- ✅ Always use single MCP server (per-project Dolt servers) - ✅ Check routing config before filing issues - ✅ Use `bd info --json` to verify workspace state - ✅ Run `bd sync` at end of session @@ -382,12 +382,12 @@ bd config get repos.additional ### Verify Configuration ```bash -# Show all config + database path + daemon status +# Show all config + database path + server status bd info --json # Sample output: { - "database_path": "/Users/you/projects/myapp/.beads/beads.db", + "database_path": "/Users/you/projects/myapp/.beads/dolt", "config": { "routing": { "mode": "auto", @@ -399,10 +399,10 @@ bd info --json "additional": ["~/repo1", "~/repo2"] } }, - "daemon": { + "server": { "running": true, "pid": 12345, - "socket": ".beads/bd.sock" + "mode": "server" } } ``` diff --git a/docs/PROTECTED_BRANCHES.md b/docs/PROTECTED_BRANCHES.md index a5980713f..0032d47f7 100644 --- a/docs/PROTECTED_BRANCHES.md +++ b/docs/PROTECTED_BRANCHES.md @@ -58,21 +58,21 @@ Files that should be committed to your protected branch (main): Files that are automatically gitignored (do NOT commit): - `.beads/beads.db` - SQLite database (local only, regenerated from JSONL) -- `.beads/daemon.lock`, `daemon.log`, `daemon.pid` - Runtime files +- `.beads/dolt/sql-server.pid`, `sql-server.log` - Dolt server runtime files - `.beads/beads.left.jsonl`, `beads.right.jsonl` - Temporary merge artifacts The sync branch (beads-sync) will contain: -- `.beads/issues.jsonl` - Issue data in JSONL format (committed automatically by daemon) +- `.beads/issues.jsonl` - Issue data in JSONL format (committed automatically via git hooks) - `.beads/metadata.json` - Metadata about the beads installation - `.beads/config.yaml` - Configuration template (optional) -**2. Start the daemon with auto-commit:** +**2. Start the Dolt server:** ```bash -bd daemon start --auto-commit +bd dolt start ``` -The daemon will automatically commit issue changes to the `beads-sync` branch. +With git hooks installed (`bd hooks install`), issue changes are automatically committed to the `beads-sync` branch. **3. When ready, merge to main:** @@ -116,13 +116,13 @@ Main branch (protected): - `.gitattributes` - Merge driver configuration Sync branch (beads-sync): -- `.beads/issues.jsonl` - Issue data (committed by daemon) +- `.beads/issues.jsonl` - Issue data (committed via git hooks) - `.beads/metadata.json` - Repository metadata - `.beads/config.yaml` - Configuration template Not tracked (gitignored): - `.beads/beads.db` - SQLite database (local only) -- `.beads/daemon.*` - Runtime files +- `.beads/dolt/sql-server.*` - Dolt server runtime files **Key points:** - The worktree is in `.git/beads-worktrees/` (hidden from your workspace) @@ -136,9 +136,9 @@ Not tracked (gitignored): When you update an issue: 1. Issue is updated in `.beads/beads.db` (SQLite database) -2. Daemon exports to `.beads/issues.jsonl` (JSONL file) +2. Git hooks export to `.beads/issues.jsonl` (JSONL file) 3. JSONL is copied to worktree (`.git/beads-worktrees/beads-sync/.beads/`) -4. Daemon commits the change in the worktree to `beads-sync` branch +4. Git hooks commit the change in the worktree to `beads-sync` branch 5. Main branch stays untouched (no commits on `main`) ## Setup @@ -164,28 +164,20 @@ If you already have beads set up and want to switch to a separate branch: # Set the sync branch bd config set sync.branch beads-sync -# Start the daemon (it will create the worktree automatically) -bd daemon start --auto-commit +# Start the Dolt server and install git hooks +bd dolt start +bd hooks install ``` -### Daemon Configuration +### Sync Configuration -For automatic commits to the sync branch: +For automatic commits to the sync branch, install git hooks: ```bash -# Start daemon with auto-commit -bd daemon start --auto-commit - -# Or with auto-commit and auto-push -bd daemon start --auto-commit --auto-push +bd hooks install ``` -**Daemon modes:** -- `--auto-commit`: Commits to sync branch after each change -- `--auto-push`: Also pushes to remote after each commit -- Default interval: 5 seconds (check for changes every 5s) - -**Recommended:** Use `--auto-commit` but not `--auto-push` if you want to review changes before pushing. Use `--auto-push` if you want fully hands-free sync. +Git hooks automatically export to JSONL and commit after each change. Use `bd sync` for manual sync when needed. ### Environment Variables @@ -193,7 +185,6 @@ You can also configure the sync branch via environment variable: ```bash export BEADS_SYNC_BRANCH=beads-sync -bd daemon start --auto-commit ``` This is useful for CI/CD or temporary overrides. @@ -215,7 +206,7 @@ bd update bd-a1b2 --status in_progress bd close bd-a1b2 "Completed authentication" ``` -All changes are automatically committed to the `beads-sync` branch by the daemon. No changes are needed to agent workflows! +All changes are automatically committed to the `beads-sync` branch via git hooks. No changes are needed to agent workflows! ### For Humans @@ -228,7 +219,7 @@ bd sync --status This shows the diff between `beads-sync` and `main` (or your current branch). -**Manual commit (if not using daemon):** +**Manual commit:** ```bash bd sync --flush-only # Export to JSONL and commit to sync branch @@ -360,21 +351,19 @@ rm -rf .git/beads-worktrees/beads-sync # Prune stale worktree entries git worktree prune -# Restart daemon (it will recreate the worktree) -bd daemon stop && bd daemon start +# Restart Dolt server (it will recreate the worktree) +bd dolt stop && bd dolt start ``` ### "branch 'beads-sync' not found" -The sync branch doesn't exist yet. The daemon will create it on the first commit. If you want to create it manually: +The sync branch doesn't exist yet. It will be created on the first commit. Create it manually: ```bash git checkout -b beads-sync git checkout main # Switch back ``` -Or just let the daemon create it automatically. - ### "Cannot push to protected branch" If the sync branch itself is protected: @@ -383,23 +372,23 @@ If the sync branch itself is protected: 2. **Option 2:** Use `--auto-commit` without `--auto-push`, and push manually when ready 3. **Option 3:** Use a different branch name that's not protected -### Daemon won't start +### Dolt server won't start -Check daemon status and logs: +Check server status and logs: ```bash # Check status -bd daemon status +bd dolt status # View logs -tail -f ~/.beads/daemon.log +tail -f .beads/dolt/sql-server.log -# Restart daemon -bd daemon stop && bd daemon start +# Restart server +bd dolt stop && bd dolt start ``` Common issues: -- Port already in use: Another daemon is running +- Port already in use: Another Dolt server is running - Permission denied: Check `.beads/` directory permissions - Git errors: Ensure git is installed and repository is initialized @@ -414,8 +403,8 @@ bd config get sync.branch # Should be the same (e.g., beads-sync) # Pull latest changes bd sync --no-push -# Check daemon is running -bd daemon status +# Check Dolt server is running +bd dolt status ``` ## FAQ @@ -440,7 +429,7 @@ Yes: ```bash bd config set sync.branch new-branch-name -bd daemon stop && bd daemon start +bd dolt stop && bd dolt start ``` The old worktree will remain (no harm), and a new worktree will be created for the new branch. @@ -451,7 +440,7 @@ Unset the sync branch config: ```bash bd config set sync.branch "" -bd daemon stop && bd daemon start +bd dolt stop && bd dolt start ``` Beads will go back to committing directly to your current branch. @@ -497,11 +486,11 @@ Worktrees are very lightweight: ### Can I delete the worktree? -Yes, but the daemon will recreate it. If you want to clean up permanently: +Yes, but it may be recreated on next sync. If you want to clean up permanently: ```bash -# Stop daemon -bd daemon stop +# Stop Dolt server +bd dolt stop # Remove worktree git worktree remove .git/beads-worktrees/beads-sync @@ -526,7 +515,6 @@ However, if you want fully automated sync: ```bash # WARNING: This bypasses branch protection! -bd daemon start --auto-commit --auto-push bd sync --merge # Run periodically (e.g., via cron) ``` @@ -670,9 +658,9 @@ If you have an existing beads setup committing to `main`: bd config set sync.branch beads-sync ``` -2. **Restart daemon:** +2. **Restart Dolt server:** ```bash - bd daemon stop && bd daemon start + bd dolt stop && bd dolt start ``` 3. **Verify:** @@ -691,9 +679,9 @@ If you want to stop using a sync branch: bd config set sync.branch "" ``` -2. **Restart daemon:** +2. **Restart Dolt server:** ```bash - bd daemon stop && bd daemon start + bd dolt stop && bd dolt start ``` Future commits will go to your current branch (e.g., `main`). diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index fe9f5388b..4ab6975f6 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -37,7 +37,7 @@ The wizard will: - Import existing issues from git (if any) - Prompt to install git hooks (recommended) - Prompt to configure git merge driver (recommended) -- Auto-start daemon for sync (SQLite backend only) +- Auto-start Dolt server for database operations Notes: - SQLite backend stores data in `.beads/beads.db`. @@ -229,10 +229,10 @@ As your project accumulates closed issues, the database grows. Manage size with bd admin compact --stats # Preview compaction candidates (30+ days closed) -bd admin compact --analyze --json --no-daemon +bd admin compact --analyze --json # Apply agent-generated summary -bd admin compact --apply --id bd-42 --summary summary.txt --no-daemon +bd admin compact --apply --id bd-42 --summary summary.txt # Immediately delete closed issues (CAUTION: permanent!) bd admin cleanup --force diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 88aa59de9..c88e017d9 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -22,23 +22,19 @@ If you prefer step-by-step control: ### Pre-Release Checklist -1. **Kill all running daemons (CRITICAL)**: +1. **Stop all running Dolt servers (CRITICAL)**: ```bash - # Kill by process name - pkill -f "bd.*daemon" - - # Verify no daemons are running - pgrep -lf "bd.*daemon" || echo "No daemons running ✓" - - # Alternative: find and kill by socket - find ~/.config -name "bd.sock" -type f 2>/dev/null | while read sock; do - echo "Found daemon socket: $sock" - done + # Stop Dolt servers in all workspaces + bd dolt stop + + # Or find and stop by process + pkill -f "dolt sql-server" 2>/dev/null + pgrep -lf "dolt sql-server" || echo "No Dolt servers running ✓" ``` - - **Why this matters**: Old daemon versions can cause: + + **Why this matters**: Old server versions can cause: - Auto-flush race conditions leaving working tree dirty after commits - - Version mismatches between client (new) and daemon (old) + - Version mismatches between client (new) and server (old) - Confusing behavior where changes appear to sync incorrectly 2. **Run tests and build**: @@ -180,10 +176,11 @@ The release will appear at: https://github.com/steveyegge/beads/releases ## Post-Release -1. **Kill old daemons again**: +1. **Stop old Dolt servers**: ```bash - pkill -f "bd.*daemon" - pgrep -lf "bd.*daemon" || echo "No daemons running ✓" + bd dolt stop + pkill -f "dolt sql-server" 2>/dev/null + pgrep -lf "dolt sql-server" || echo "No Dolt servers running ✓" ``` This ensures your local machine picks up the new version immediately. @@ -191,13 +188,10 @@ The release will appear at: https://github.com/steveyegge/beads/releases ```bash # Homebrew brew update && brew upgrade beads && bd version - + # PyPI pip install --upgrade beads-mcp beads-mcp --help - - # Check daemon version matches client - bd version --daemon # Should match client version after first command ``` 3. **Announce** (optional): diff --git a/docs/REPO_CONTEXT.md b/docs/REPO_CONTEXT.md index bd65395ec..4d33c6709 100644 --- a/docs/REPO_CONTEXT.md +++ b/docs/REPO_CONTEXT.md @@ -154,26 +154,26 @@ system directories: Temporary directories (e.g., `/var/folders` on macOS) are explicitly allowed for test environments. -## Daemon Handling +## Server Mode Handling -### CLI vs Daemon Context +### CLI vs Server Context For CLI commands, `GetRepoContext()` caches the result via `sync.Once` because: - CWD doesn't change during command execution - BEADS_DIR doesn't change during command execution - Repeated filesystem access would be wasteful -For the daemon (long-running process), this caching is inappropriate: +For the Dolt server (long-running process), this caching is inappropriate: - User may create new worktrees - BEADS_DIR may change via direnv - Multiple workspaces may be active simultaneously ### Workspace-Specific API -The daemon uses `GetRepoContextForWorkspace()` for fresh resolution: +The server uses `GetRepoContextForWorkspace()` for fresh resolution: ```go -// For daemon: fresh resolution per-operation (no caching) +// For server mode: fresh resolution per-operation (no caching) rc, err := beads.GetRepoContextForWorkspace(workspacePath) // Validation hook for detecting stale contexts diff --git a/docs/ROUTING.md b/docs/ROUTING.md index 908eb15b2..6321ee0d5 100644 --- a/docs/ROUTING.md +++ b/docs/ROUTING.md @@ -150,24 +150,24 @@ bd repo list Multi-repo hydration imports issues from all configured repos into the current database: 1. **JSONL as source of truth**: Each repo maintains its own `issues.jsonl` -2. **Periodic import**: Daemon imports from `repos.additional` every sync cycle +2. **Periodic import**: Beads imports from `repos.additional` every sync cycle 3. **Source tracking**: Each issue tagged with `source_repo` field 4. **Unified view**: `bd list` shows issues from all repos ### Requirements -**For optimal hydration, run daemons in all repos:** +**For optimal hydration, start Dolt servers in all repos:** ```bash # In main repo -bd daemon start +bd dolt start # In planning repo cd ~/.beads-planning -bd daemon start --local +bd dolt start ``` -Without daemons, JSONL files become stale and hydration only sees old data. +Without running servers, JSONL files become stale and hydration only sees old data. ### Troubleshooting @@ -179,7 +179,7 @@ bd doctor # Checks: # - routing.mode=auto with routing targets but repos.additional not configured # - Routing targets not in repos.additional list -# - Daemons not running in hydrated repos +# - Dolt servers not running in hydrated repos ``` **Common Issues:** @@ -189,8 +189,8 @@ bd doctor - **Fix:** `bd repo add ` 2. **Issues appear but data is stale** - - **Cause:** Daemon not running in target repo - - **Fix:** `cd && bd daemon start --local` + - **Cause:** Dolt server not running in target repo + - **Fix:** `cd && bd dolt start` 3. **After upgrading, routed issues missing** - **Cause:** Upgraded before hydration was automatic diff --git a/docs/TESTING_PHILOSOPHY.md b/docs/TESTING_PHILOSOPHY.md index 9d77874f3..6558647af 100644 --- a/docs/TESTING_PHILOSOPHY.md +++ b/docs/TESTING_PHILOSOPHY.md @@ -41,7 +41,7 @@ This document covers **what to test** and **what not to test**. For how to run t - Config file parsing - CLI argument handling -**In beads**: Tests tagged with `//go:build integration`, daemon tests +**In beads**: Tests tagged with `//go:build integration`, server mode tests ### Tier 3: E2E / Smoke Tests (1-5 minutes) @@ -164,16 +164,16 @@ for k, want := range expectedMap { Unit tests that execute real commands or heavy I/O when they could mock. ```go -// BAD: Actually executes bd killall in unit test -func TestDaemonFix(t *testing.T) { - exec.Command("bd", "killall").Run() +// BAD: Actually executes external commands in unit test +func TestServerFix(t *testing.T) { + exec.Command("bd", "dolt", "stop").Run() // ... } // GOOD: Mock the execution or use integration test tag -func TestDaemonFix(t *testing.T) { +func TestServerFix(t *testing.T) { executor := &mockExecutor{} - fix := NewDaemonFix(executor) + fix := NewServerFix(executor) // ... } ``` @@ -184,10 +184,10 @@ Tests that break when you refactor, even though behavior is unchanged. ```go // BAD: Tests internal state -if len(daemon.connectionPool) != 3 { t.Error(...) } +if len(server.connectionPool) != 3 { t.Error(...) } // GOOD: Tests observable behavior -if resp, err := daemon.HandleRequest(req); err != nil { t.Error(...) } +if resp, err := server.HandleRequest(req); err != nil { t.Error(...) } ``` ### 5. Missing Boundary Tests @@ -235,13 +235,13 @@ TestPriority(5) // boundary - first invalid | Sync/Export/Import | Data integrity critical - comprehensive edge cases | | SQLite transactions | Rollback safety, atomicity guarantees | | Merge operations | 3-way merge with conflict resolution | -| Daemon locking | Prevents corruption from multiple instances | +| Database locking | Prevents corruption from multiple instances | ### Needs Attention | Area | Gap | Priority | |------|-----|----------| -| Daemon lifecycle | Shutdown/signal handling | Medium | +| Server lifecycle | Shutdown/signal handling | Medium | | Concurrent operations | Stress testing under load | Medium | | Boundary validation | Edge inputs in mapping functions | Low | diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 75b8e02ba..798ec0b3d 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -23,10 +23,10 @@ bd supports several environment variables for debugging specific subsystems. Ena | Variable | Purpose | Output Location | Usage | |----------|---------|----------------|-------| | `BD_DEBUG` | General debug logging | stderr | Set to any value to enable | -| `BD_DEBUG_RPC` | RPC communication between CLI and daemon | stderr | Set to `1` or `true` | +| `BD_DEBUG_RPC` | RPC communication between CLI and Dolt server | stderr | Set to `1` or `true` | | `BD_DEBUG_SYNC` | Sync and import timestamp protection | stderr | Set to any value to enable | | `BD_DEBUG_ROUTING` | Issue routing and multi-repo resolution | stderr | Set to any value to enable | -| `BD_DEBUG_FRESHNESS` | Database file replacement detection | daemon logs | Set to any value to enable | +| `BD_DEBUG_FRESHNESS` | Database file replacement detection | server logs | Set to any value to enable | ### Usage Examples @@ -39,12 +39,12 @@ bd ready **RPC communication issues:** ```bash -# Debug daemon communication +# Debug Dolt server communication export BD_DEBUG_RPC=1 bd list # Example output: -# [RPC DEBUG] Connecting to daemon at .beads/bd.sock +# [RPC DEBUG] Connecting to Dolt server # [RPC DEBUG] Sent request: list (correlation_id=abc123) # [RPC DEBUG] Received response: 200 OK ``` @@ -74,16 +74,15 @@ bd create "Test issue" --rig=planning ```bash # Debug database file replacement detection export BD_DEBUG_FRESHNESS=1 -bd daemon start --foreground +bd dolt start # Example output: # [freshness] FreshnessChecker: inode changed 27548143 -> 7945906 # [freshness] FreshnessChecker: triggering reconnection # [freshness] Database file replaced, reconnection triggered -# Or check daemon logs -BD_DEBUG_FRESHNESS=1 bd daemon restart -bd daemons logs . -n 100 | grep freshness +# Or check server logs +tail -f .beads/dolt/sql-server.log | grep freshness ``` **Multiple debug flags:** @@ -92,7 +91,7 @@ bd daemons logs . -n 100 | grep freshness export BD_DEBUG=1 export BD_DEBUG_RPC=1 export BD_DEBUG_FRESHNESS=1 -bd daemon start --foreground +bd dolt start ``` ### Tips @@ -109,13 +108,10 @@ bd daemon start --foreground BD_DEBUG=1 bd sync 2> debug.log ``` -- **Daemon logs**: `BD_DEBUG_FRESHNESS` output goes to daemon logs, not stderr: +- **Server logs**: `BD_DEBUG_FRESHNESS` output goes to server logs, not stderr: ```bash - # View daemon logs - bd daemons logs . -n 200 - - # Or directly: - tail -f .beads/daemon.log + # View Dolt server logs + tail -f .beads/dolt/sql-server.log ``` - **When filing bug reports**: Include relevant debug output to help maintainers diagnose issues faster. @@ -557,8 +553,8 @@ See [WORKTREES.md](WORKTREES.md) for details on how beads uses worktrees. Check if auto-sync is enabled: ```bash -# Check if daemon is running -ps aux | grep "bd daemon" +# Check if Dolt server is running +bd doctor # Manually export/import bd export -o .beads/issues.jsonl @@ -728,24 +724,23 @@ cat ~/Library/Application\ Support/Claude/claude_desktop_config.json bd version bd ready -# Check for daemon -ps aux | grep "bd daemon" +# Check Dolt server health +bd doctor ``` See [integrations/beads-mcp/README.md](../integrations/beads-mcp/README.md) for MCP-specific troubleshooting. ### Sandboxed environments (Codex, Claude Code, etc.) -**Issue:** Sandboxed environments restrict permissions, preventing daemon control and causing "out of sync" errors. +**Issue:** Sandboxed environments restrict permissions, preventing server control and causing "out of sync" errors. **Common symptoms:** - "Database out of sync with JSONL" errors that persist after running `bd import` -- `bd daemon stop` fails with "operation not permitted" -- Cannot kill daemon process with `kill ` +- `bd dolt stop` fails with "operation not permitted" - JSONL hash mismatch warnings (bd-160) - Commands intermittently fail with staleness errors -**Root cause:** The sandbox can't signal/kill the existing daemon process, so the DB stays stale and refuses to import. +**Root cause:** The sandbox can't signal/kill the existing Dolt server process, so the DB stays stale and refuses to import. --- @@ -762,13 +757,10 @@ When auto-detected, you'll see: `ℹ️ Sandbox detected, using direct mode` bd --sandbox ready bd --sandbox create "Fix bug" -p 1 bd --sandbox update bd-42 --status in_progress - -# Equivalent to: -bd --no-daemon --no-auto-flush --no-auto-import ``` **What sandbox mode does:** -- Disables daemon (uses direct database mode) +- Uses embedded database mode (no server needed) - Disables auto-export to JSONL - Disables auto-import from JSONL - Allows bd to work in network-restricted environments @@ -783,7 +775,7 @@ bd sync #### Escape hatches for stuck states -If you're stuck in a "database out of sync" loop with a running daemon you can't stop, use these flags: +If you're stuck in a "database out of sync" loop with a running server you can't stop, use these flags: **1. Force metadata update (`--force` flag on import)** @@ -794,7 +786,7 @@ When `bd import` reports "0 created, 0 updated" but staleness persists: bd import --force # This updates internal metadata tracking without changing issues -# Fixes: stuck state caused by stale daemon cache +# Fixes: stuck state caused by stale server cache ``` **Shows:** `Metadata updated (database already in sync with JSONL)` @@ -848,7 +840,7 @@ bd sync | Flag | Purpose | When to use | Risk | |------|---------|-------------|------| -| `--sandbox` | Disable daemon and auto-sync | Sandboxed environments (Codex, containers) | Low - safe for sandboxes | +| `--sandbox` | Use embedded mode, disable auto-sync | Sandboxed environments (Codex, containers) | Low - safe for sandboxes | | `--force` (import) | Force metadata update | Stuck "0 created, 0 updated" loop | Low - updates metadata only | | `--allow-stale` | Skip staleness validation | Emergency access to database | **High** - may show stale data | @@ -875,9 +867,9 @@ where.exe bd $env:Path = [Environment]::GetEnvironmentVariable("Path", "User") ``` -### Windows: Firewall blocking daemon +### Windows: Firewall blocking Dolt server -The daemon listens on loopback TCP. Allow `bd.exe` through Windows Firewall: +The Dolt server listens on loopback TCP. Allow `bd.exe` through Windows Firewall: 1. Open Windows Security → Firewall & network protection 2. Click "Allow an app through firewall" diff --git a/docs/UNINSTALLING.md b/docs/UNINSTALLING.md index 6442a29fe..7c30dc95e 100644 --- a/docs/UNINSTALLING.md +++ b/docs/UNINSTALLING.md @@ -7,8 +7,8 @@ This guide explains how to completely remove Beads from a repository. Run these commands from your repository root: ```bash -# 1. Stop any running bd process (optional) -pkill -f "bd.*daemon" 2>/dev/null || true +# 1. Stop any running Dolt server (optional) +bd dolt stop 2>/dev/null || true # 2. Remove git hooks installed by Beads rm -f .git/hooks/pre-commit .git/hooks/prepare-commit-msg .git/hooks/post-merge .git/hooks/pre-push .git/hooks/post-checkout @@ -31,14 +31,12 @@ rm -rf .git/beads-worktrees ## Detailed Steps -### 1. Stop Legacy Daemon Processes (Optional) +### 1. Stop the Dolt Server (Optional) -Newer versions no longer expose daemon management commands, but you may have -an old daemon process from a previous release. Stop it before cleanup: +If a Dolt server is running, stop it before cleanup: ```bash -pgrep -lf "bd.*daemon" # Check for legacy daemon processes -pkill -f "bd.*daemon" 2>/dev/null || true # Stop them if present +bd dolt stop 2>/dev/null || true ``` ### 2. Remove Git Hooks @@ -107,12 +105,10 @@ The `.beads/` directory contains: | File/Dir | Description | |----------|-------------| -| `beads.db` | SQLite database with issues | +| `dolt/` | Dolt database directory | +| `dolt/sql-server.pid` | Running Dolt server PID (if server mode) | +| `dolt/sql-server.log` | Dolt server logs (if server mode) | | `issues.jsonl` | Git-tracked issue data | -| `daemon.pid` | Running daemon PID | -| `daemon.log` | Daemon logs | -| `daemon.lock` | Lock file for daemon | -| `bd.sock` | Unix socket for daemon IPC | | `config.yaml` | Project configuration | | `metadata.json` | Version tracking | | `deletions.jsonl` | Soft-deleted issues | diff --git a/docs/WORKTREES.md b/docs/WORKTREES.md index d1d9d43e3..395f2d715 100644 --- a/docs/WORKTREES.md +++ b/docs/WORKTREES.md @@ -75,10 +75,6 @@ If you don't want beads to use a separate sync branch: # Unset the sync branch configuration bd config set sync.branch "" -# Stop and restart daemon -bd daemon stop -bd daemon start - # Clean up existing worktrees rm -rf .git/beads-worktrees git worktree prune @@ -127,54 +123,43 @@ Main Repository - ✅ **Concurrent access** - Database locking prevents corruption - ✅ **Git integration** - Issues sync via JSONL in main repo -### Worktree Detection & Daemon Safety +### Worktree Detection -bd automatically detects when you're in a git worktree and handles daemon mode safely: +bd automatically detects when you're in a git worktree: **Default behavior (no sync-branch configured):** -- Daemon is **automatically disabled** in worktrees -- Uses direct mode for safety (no warning needed) -- All commands work correctly without configuration +- Uses embedded mode for safety (no configuration needed) +- All commands work correctly without additional setup **With sync-branch configured:** -- Daemon is **enabled** in worktrees - Commits go to dedicated sync branch (e.g., `beads-sync`) -- Full daemon functionality available across all worktrees +- Full server mode functionality available across all worktrees ## Usage Patterns -### Recommended: Configure Sync-Branch for Full Daemon Support +### Recommended: Configure Sync-Branch for Full Server Support ```bash # Configure sync-branch once (in main repo or any worktree) bd config set sync-branch beads-sync -# Now daemon works safely in all worktrees +# Now server mode works safely in all worktrees cd feature-worktree bd create "Implement feature X" -t feature -p 1 bd update bd-a1b2 --status in_progress -bd ready # Daemon auto-syncs to beads-sync branch +bd ready # Auto-syncs to beads-sync branch ``` -### Alternative: Direct Mode (No Configuration Needed) +### Alternative: Embedded Mode (No Configuration Needed) ```bash -# Without sync-branch, daemon is auto-disabled in worktrees +# Without sync-branch, worktrees use embedded mode automatically cd feature-worktree bd create "Implement feature X" -t feature -p 1 -bd ready # Uses direct mode automatically +bd ready # Uses embedded mode automatically bd sync # Manual sync when needed ``` -### Legacy: Explicit Daemon Disable - -```bash -# Still works if you prefer explicit control -export BEADS_NO_DAEMON=1 -# or -bd --no-daemon ready -``` - ## Worktree-Aware Features ### Database Discovery @@ -286,21 +271,16 @@ bd config set sync.branch "" **Solution:** See [Beads-Created Worktrees](#beads-created-worktrees-sync-branch) section above for details on what these are and how to remove them if unwanted. -### Issue: Daemon commits to wrong branch +### Issue: Commits to wrong branch **Symptoms:** Changes appear on unexpected branch in git history -**Note:** This issue should no longer occur with the new worktree safety feature. Daemon is automatically disabled in worktrees unless sync-branch is configured. +**Note:** This issue should no longer occur with the worktree safety feature. Worktrees use embedded mode automatically unless sync-branch is configured. **Solution (if still occurring):** ```bash -# Option 1: Configure sync-branch (recommended) +# Configure sync-branch (recommended) bd config set sync-branch beads-sync - -# Option 2: Explicitly disable daemon -export BEADS_NO_DAEMON=1 -# Or use --no-daemon flag for individual commands -bd --no-daemon sync ``` ### Issue: Database not found in worktree @@ -343,12 +323,6 @@ bd info # Should show database path in main repo ### Environment Variables ```bash -# Disable daemon globally for worktree usage -export BEADS_NO_DAEMON=1 - -# Disable auto-start (still warns if manually started) -export BEADS_AUTO_START_DAEMON=false - # Force specific database location export BEADS_DB=/path/to/specific/.beads/dolt ``` @@ -359,8 +333,8 @@ export BEADS_DB=/path/to/specific/.beads/dolt # Configure sync behavior bd config set sync.branch beads-sync # Use separate sync branch -# For git-portable workflows: -bd daemon start --auto-commit --auto-push +# Configure Dolt auto-commit +bd config set dolt.auto-commit true ``` ## Performance Considerations @@ -374,7 +348,7 @@ bd daemon start --auto-commit --auto-push ### Concurrent Access -- **Database locking**: Prevents corruption during simultaneous access (use Dolt server mode for multi-writer) +- **Database locking**: Prevents corruption during simultaneous access (use Dolt server mode via `bd dolt start` for multi-writer) - **Git operations**: Safe concurrent commits from different worktrees - **Sync coordination**: JSONL-based sync prevents conflicts @@ -382,7 +356,7 @@ bd daemon start --auto-commit --auto-push ### Before (Limited Worktree Support) -- ❌ Daemon mode broken in worktrees +- ❌ Broken in worktrees - ❌ Manual workarounds required - ❌ Complex setup procedures - ❌ Limited documentation @@ -410,7 +384,6 @@ git worktree add services/web # Each service team works in their worktree cd services/auth -export BEADS_NO_DAEMON=1 bd create "Add OAuth support" -t feature -p 1 cd ../api @@ -532,7 +505,7 @@ cd ~/project/feature-1 && bd list # Same issues cd ~/project/feature-2 && bd list # Same issues ``` -No daemon conflicts, no branch confusion - all worktrees see the same issues because they all use the same external repository. +No conflicts, no branch confusion - all worktrees see the same issues because they all use the same external repository. ## See Also diff --git a/docs/design/kv-store.md b/docs/design/kv-store.md index 49d28e20f..489024d1b 100644 --- a/docs/design/kv-store.md +++ b/docs/design/kv-store.md @@ -115,7 +115,7 @@ This format is: ## RPC Operations -For daemon mode, add these operations to the RPC protocol: +For server mode, add these operations to the RPC protocol: | Operation | Args | Response | |-----------|------|----------| diff --git a/docs/dev-notes/ERROR_HANDLING_AUDIT.md b/docs/dev-notes/ERROR_HANDLING_AUDIT.md index 426ffc8ca..2f3af5c34 100644 --- a/docs/dev-notes/ERROR_HANDLING_AUDIT.md +++ b/docs/dev-notes/ERROR_HANDLING_AUDIT.md @@ -567,22 +567,24 @@ The codebase demonstrates strong adherence to error handling patterns with a few ### daemon_sync.go ✅ MOSTLY CONSISTENT +*Note: This file handles Dolt server sync operations.* + **Pattern A (Exit):** Used for critical failures but returns early to channel instead of os.Exit ```go // daemon_sync.go - Returns error to channel, caller decides if err != nil { - log.log("daemon sync error: %v", err) - return // Logs and returns, daemon continues + log.log("server sync error: %v", err) + return // Logs and returns, server continues } ``` -**Pattern B (Warn):** Uses internal logging (log.log) which is appropriate for daemon background operations +**Pattern B (Warn):** Uses internal logging (log.log) which is appropriate for server background operations ```go // Non-fatal warnings logged to internal log log.log("warning: failed to update metadata: %v", err) ``` -**Analysis:** ✅ Appropriate - Daemon operations use internal logging since there's no interactive stderr. Background process errors are logged for debugging but don't crash the daemon. +**Analysis:** ✅ Appropriate - Server sync operations use internal logging since there's no interactive stderr. Background process errors are logged for debugging but don't crash the server. --- @@ -643,7 +645,7 @@ if err := store.UpdateIssue(ctx, fullID, updates, actor); err != nil { **Pattern A (Exit):** Correctly applied for ID resolution and dependency operations ```go // dep.go:37-44 - ID resolution -resp, err := daemonClient.ResolveID(resolveArgs) +resp, err := rpcClient.ResolveID(resolveArgs) if err != nil { fmt.Fprintf(os.Stderr, "Error resolving issue ID %s: %v\n", args[0], err) os.Exit(1) @@ -701,11 +703,11 @@ if err != nil { } ``` -**Pattern A with fallback:** Interesting pattern for daemon compatibility +**Pattern A with fallback:** Interesting pattern for RPC compatibility ```go // comments.go:42-50 - Fallback to direct mode if isUnknownOperationError(err) { - if err := fallbackToDirectMode("daemon does not support comment_list RPC"); err != nil { + if err := fallbackToDirectMode("server does not support comment_list RPC"); err != nil { fmt.Fprintf(os.Stderr, "Error getting comments: %v\n", err) os.Exit(1) } @@ -715,7 +717,7 @@ if isUnknownOperationError(err) { } ``` -**Analysis:** ✅ Consistent - Uses Pattern A but with smart fallback for daemon compatibility. +**Analysis:** ✅ Consistent - Uses Pattern A but with smart fallback for RPC compatibility. --- @@ -829,10 +831,10 @@ if err := syncbranch.Set(ctx, store, value); err != nil { **Pattern A (Exit):** Core validation failures ```go -// validate.go:28-32 - Daemon mode not supported -if daemonClient != nil { - fmt.Fprintf(os.Stderr, "Error: validate command not yet supported in daemon mode\n") - fmt.Fprintf(os.Stderr, "Use: bd --no-daemon validate\n") +// validate.go:28-32 - Server mode not supported +if rpcClient != nil { + fmt.Fprintf(os.Stderr, "Error: validate command not yet supported in server mode\n") + fmt.Fprintf(os.Stderr, "Use: bd validate (in embedded mode)\n") os.Exit(1) } @@ -878,9 +880,9 @@ func (r *validationResults) hasFailures() bool { } ``` -2. **Daemon Fallback Pattern:** Commands like comments.go implement a sophisticated fallback: - - Try daemon RPC first - - If daemon doesn't support operation, fall back to direct mode +2. **RPC Fallback Pattern:** Commands like comments.go implement a sophisticated fallback: + - Try RPC server first + - If server doesn't support operation, fall back to direct mode - Only exit on failure after all options exhausted 3. **Exit Code Propagation:** validate.go demonstrates proper exit code handling - aggregates results and returns appropriate exit code at the end. @@ -896,7 +898,7 @@ func (r *validationResults) hasFailures() bool { ### Files Still Needing Audit - doctor/* (doctor package files) -- daemon.go +- server-related files - stats.go - duplicates.go - repair_deps.go diff --git a/docs/dev-notes/TEST_SUITE_AUDIT.md b/docs/dev-notes/TEST_SUITE_AUDIT.md index 349c0fa8f..8b410977d 100644 --- a/docs/dev-notes/TEST_SUITE_AUDIT.md +++ b/docs/dev-notes/TEST_SUITE_AUDIT.md @@ -75,9 +75,9 @@ These tests only interact with the database and can safely share a single DB set These have a mix - some can share DB, some need isolation: -#### Daemon Tests (Already have integration tags): -- **daemon_test.go** (15 tests) - Mix of DB and daemon lifecycle - - Propose: Separate suites for DB-only vs daemon lifecycle tests +#### Server/RPC Tests (Already have integration tags): +- **daemon_test.go** (15 tests) - Mix of DB and server lifecycle + - Propose: Separate suites for DB-only vs server lifecycle tests - **daemon_autoimport_test.go** (2 tests) - **daemon_crash_test.go** (2 tests) @@ -87,7 +87,7 @@ These have a mix - some can share DB, some need isolation: - **daemon_sync_branch_test.go** (11 tests) - **daemon_watcher_test.go** (7 tests) -**Recommendation**: Keep daemon tests isolated (they already have `//go:build integration` tags) +**Recommendation**: Keep server/RPC tests isolated (they already have `//go:build integration` tags) #### Git Operation Tests: - **git_sync_test.go** (1 test) @@ -103,7 +103,7 @@ Tests that already use good patterns: 1. **label_test.go** - Uses helper struct with shared DB ✓ 2. **delete_test.go** - Has `//go:build integration` tag ✓ -3. All daemon tests - Have `//go:build integration` tags ✓ +3. All server/RPC tests - Have `//go:build integration` tags ✓ ### Category 4: Special Cases (50+ tests) @@ -220,7 +220,7 @@ After Phase 1 success: ### Phase 3: Special Cases (P3) - Complex Refactors Handle tests that need mixed isolation: -1. Review daemon tests for DB-only portions +1. Review server/RPC tests for DB-only portions 2. Review CLI tests for unit-testable logic 3. Consider utility functions that don't need DB @@ -233,7 +233,7 @@ Handle tests that need mixed isolation: ### After (Proposed): - **10-15 test suites** for DB tests = **~15 DB initializations** -- **~65 isolated tests** (daemon, git, filesystem) = **~65 DB initializations** +- **~65 isolated tests** (server/RPC, git, filesystem) = **~65 DB initializations** - **Total: ~80 DB initializations** (down from 280) - Expected time: **1-2 minutes** (5-8x speedup) @@ -258,7 +258,7 @@ Handle tests that need mixed isolation: ## Key Insights 1. **~150 tests** can immediately benefit from shared DB setup -2. **~65 tests** need isolation (daemon, git, filesystem) +2. **~65 tests** need isolation (server/RPC, git, filesystem) 3. **~65 tests** need analysis (mixed or may not need DB) 4. **label_test.go shows the ideal pattern** - use it as the template! 5. **Primary bottleneck**: Repeated `newTestStore()` calls diff --git a/docs/messaging.md b/docs/messaging.md index 394522f37..9015a1d7b 100644 --- a/docs/messaging.md +++ b/docs/messaging.md @@ -109,7 +109,7 @@ Scripts in `.beads/hooks/` run after certain events: | `on_update` | After `bd update` | | `on_close` | After `bd close` | -Hooks receive event data as JSON on stdin. This enables orchestrator integration (e.g., notifying daemons of new messages) without beads knowing about the orchestrator. +Hooks receive event data as JSON on stdin. This enables orchestrator integration (e.g., notifying services of new messages) without beads knowing about the orchestrator. ## See Also diff --git a/docs/pr-752-chaos-testing-review.md b/docs/pr-752-chaos-testing-review.md index b6315182e..3a9a188c7 100644 --- a/docs/pr-752-chaos-testing-review.md +++ b/docs/pr-752-chaos-testing-review.md @@ -34,7 +34,7 @@ Jordan proposes adding chaos testing and E2E test coverage to beads. The PR: ### Test Coverage Additions - `internal/storage/memory/memory_more_coverage_test.go` (921 lines) - Memory storage tests - `cmd/bd/cli_coverage_show_test.go` (426 lines) - CLI show command tests -- `cmd/bd/daemon_autostart_unit_test.go` (331 lines) - Daemon autostart tests +- `cmd/bd/daemon_autostart_unit_test.go` (331 lines) - Server autostart tests - `internal/rpc/client_gate_shutdown_test.go` (107 lines) - RPC client tests - Various other test files @@ -71,7 +71,7 @@ From `doctor_repair_chaos_test.go`: 1. **Complete DB corruption** - Writes "not a database" garbage, verifies recovery from JSONL 2. **Truncated DB without JSONL** - Tests graceful failure when no recovery source exists 3. **Sidecar file backup** - Ensures -wal, -shm, -journal files are preserved during repair -4. **Repair with running daemon** - Tests recovery while daemon holds locks +4. **Repair with running server** - Tests recovery while server holds locks 5. **JSONL integrity** - Malformed lines, re-export from DB Each test: diff --git a/examples/multi-phase-development/README.md b/examples/multi-phase-development/README.md index 962726857..d79593f22 100644 --- a/examples/multi-phase-development/README.md +++ b/examples/multi-phase-development/README.md @@ -23,8 +23,8 @@ Use beads epics and hierarchical issues to organize work by phase, with priority cd my-project bd init -# Start daemon for auto-sync (optional) -bd daemon start --auto-commit --auto-push +# Start Dolt server for auto-sync (optional) +bd dolt start ``` ## Phase 1: Research & Planning diff --git a/examples/multiple-personas/README.md b/examples/multiple-personas/README.md index 833e35c32..ec42a9c8e 100644 --- a/examples/multiple-personas/README.md +++ b/examples/multiple-personas/README.md @@ -26,8 +26,8 @@ Use beads labels, priorities, and dependencies to organize work by persona, with cd my-project bd init -# Start daemon for auto-sync (optional for teams) -bd daemon start --auto-commit --auto-push +# Start Dolt server for auto-sync (optional for teams) +bd dolt start ``` ## Persona: Architect diff --git a/examples/protected-branch/README.md b/examples/protected-branch/README.md index 80a8c4fef..b2bf80c57 100644 --- a/examples/protected-branch/README.md +++ b/examples/protected-branch/README.md @@ -48,11 +48,12 @@ bd update bd-XXXXX --status in_progress **Note:** Replace `bd-XXXXX` etc. with actual issue IDs created above. -### 3. Auto-Sync (Daemon) +### 3. Auto-Sync (Server Mode) ```bash -# Start daemon with auto-commit -bd daemon start --auto-commit +# Start Dolt server with auto-commit +bd config set dolt.auto-commit on +bd dolt start # All issue changes are now automatically committed to beads-metadata branch ``` @@ -67,9 +68,9 @@ git log beads-metadata --oneline | head -5 bd sync --status ``` -### 4. Manual Sync (Without Daemon) +### 4. Manual Sync (Without Server) -If you're not using the daemon: +If you're not using the Dolt server: ```bash # Create or update issues @@ -145,10 +146,11 @@ bd list # See the new feature issue │ ▼ ┌─────────────────┐ -│ Daemon (or │ -│ manual sync) │ -│ commits to │ -│ beads-metadata │ +│ Dolt server │ +│ (or manual │ +│ sync) commits │ +│ to beads- │ +│ metadata │ └────────┬────────┘ │ ▼ @@ -181,7 +183,7 @@ my-project/ ├── .beads/ # Main beads directory (in your workspace) │ ├── beads.db # SQLite database │ ├── issues.jsonl # JSONL export -│ └── bd.sock # Daemon socket (if running) +│ └── config.yaml # Beads configuration ├── src/ # Your application code │ └── ... └── README.md @@ -204,7 +206,7 @@ my-project/ ### For AI Agents - **No workflow changes:** Agents use `bd create`, `bd update`, etc. as normal -- **Let daemon handle it:** With `--auto-commit`, agents don't think about sync +- **Let the Dolt server handle it:** With auto-commit enabled, agents don't think about sync - **Session end:** Run `bd sync` at end of session to ensure everything is committed ### Troubleshooting @@ -218,17 +220,17 @@ JSONL is append-only and line-based, so conflicts are rare. If they occur: **"Worktree doesn't exist"** -The daemon creates it automatically on first commit. To create manually: +The Dolt server creates it automatically on first commit. To create manually: ```bash bd config get sync.branch # Verify it's set -bd daemon stop && bd daemon start # Daemon will create worktree +bd dolt stop && bd dolt start # Server will create worktree ``` **"Changes not syncing"** Make sure: - `bd config get sync.branch` returns the same value on all clones -- Daemon is running: `bd daemon status` +- Dolt server is running: `bd doctor` - Both clones have fetched: `git fetch origin beads-metadata` ## Advanced: GitHub Actions Integration diff --git a/examples/team-workflow/README.md b/examples/team-workflow/README.md index 49e94ed6b..b3d393f31 100644 --- a/examples/team-workflow/README.md +++ b/examples/team-workflow/README.md @@ -66,7 +66,7 @@ If main isn't protected: # Create issue bd create "Implement feature X" -p 1 -# Daemon auto-commits to main +# Dolt server auto-commits to main # (or run 'bd sync' manually) # Pull to see team's issues @@ -82,7 +82,7 @@ If main is protected: # Create issue bd create "Implement feature X" -p 1 -# Daemon commits to beads-metadata branch +# Auto-commits to beads-metadata branch # (or run 'bd sync' manually) # Push beads-metadata @@ -100,9 +100,8 @@ team: enabled: true sync_branch: beads-metadata # or main if not protected -daemon: - auto_commit: true - auto_push: true +dolt: + auto-commit: on ``` ### Manual Configuration @@ -114,9 +113,8 @@ bd config set team.enabled true # Set sync branch bd config set team.sync_branch beads-metadata -# Enable auto-sync -bd config set daemon.auto_commit true -bd config set daemon.auto_push true +# Enable auto-commit +bd config set dolt.auto-commit on ``` ## Example Workflows @@ -127,7 +125,7 @@ bd config set daemon.auto_push true # Alice creates an issue bd create "Fix authentication bug" -p 1 -# Daemon commits and pushes to main +# Auto-commits and pushes to main # (auto-sync enabled) # Bob pulls changes @@ -137,7 +135,7 @@ bd list # Sees Alice's issue # Bob claims it bd update bd-abc --status in_progress -# Daemon commits Bob's update +# Auto-commits Bob's update # Alice pulls and sees Bob is working on it ``` @@ -147,7 +145,7 @@ bd update bd-abc --status in_progress # Alice creates an issue bd create "Add new API endpoint" -p 1 -# Daemon commits to beads-metadata +# Auto-commits to beads-metadata git push origin beads-metadata # Bob pulls beads-metadata @@ -213,10 +211,11 @@ bd close bd-abc --reason "PR #123 merged" ### Auto-Sync (Recommended) -Daemon commits and pushes automatically: +The Dolt server commits and pushes automatically when auto-commit is enabled: ```bash -bd daemon start --auto-commit --auto-push +bd config set dolt.auto-commit on +bd dolt start ``` Benefits: @@ -315,8 +314,7 @@ A: Hash-based IDs prevent collisions. Even if created simultaneously, they get d A: Turn it off: ```bash -bd config set daemon.auto_commit false -bd config set daemon.auto_push false +bd config set dolt.auto-commit off # Sync manually bd sync @@ -344,27 +342,25 @@ A: Add to your CI pipeline: ## Troubleshooting -### Issue: Daemon not committing +### Issue: Server not committing -Check daemon status: +Check server status: ```bash -bd daemon status -bd daemons list +bd doctor ``` Verify config: ```bash -bd config get daemon.auto_commit -bd config get daemon.auto_push +bd config get dolt.auto-commit ``` -Restart daemon: +Restart Dolt server: ```bash -bd daemon stop -bd daemon start --auto-commit --auto-push +bd dolt stop +bd dolt start ``` ### Issue: Merge conflicts in JSONL diff --git a/integrations/beads-mcp/CONTEXT_MANAGEMENT.md b/integrations/beads-mcp/CONTEXT_MANAGEMENT.md index 814f194d7..01e7f04cd 100644 --- a/integrations/beads-mcp/CONTEXT_MANAGEMENT.md +++ b/integrations/beads-mcp/CONTEXT_MANAGEMENT.md @@ -84,15 +84,15 @@ AI clients would need to: 1. Call `set_context` at session start with workspace root 2. MCP protocol would need to support persistent session state -**Option 3: Daemon with RPC (Future - Path 1.5 from bd-105)** -- Add `cwd` parameter to daemon RPC protocol -- Daemon performs tree-walking per request +**Option 3: Dolt Server with RPC (Future - Path 1.5 from bd-105)** +- Add `cwd` parameter to Dolt server RPC protocol +- Server performs tree-walking per request - MCP server passes workspace_root via RPC -- Benefits: Centralized routing, supports multiple contexts per daemon +- Benefits: Centralized routing, supports multiple contexts per server -**Option 4: Advanced Routing Daemon (Future - Path 2 from bd-105)** +**Option 4: Advanced Routing Server (Future - Path 2 from bd-105)** For >50 repos: -- Dedicated routing daemon with repo→DB mappings +- Dedicated routing server with repo->DB mappings - MCP becomes thin shim - Enables shared connection pooling, cross-repo queries diff --git a/integrations/beads-mcp/README.md b/integrations/beads-mcp/README.md index 56eadeb5e..a7bfbf8ae 100644 --- a/integrations/beads-mcp/README.md +++ b/integrations/beads-mcp/README.md @@ -60,7 +60,6 @@ Then use in Claude Desktop config: ``` **Environment Variables** (all optional): -- `BEADS_USE_DAEMON` - Use daemon RPC instead of CLI (default: `1`, set to `0` to disable) - `BEADS_PATH` - Path to bd executable (default: `~/.local/bin/bd`) - `BEADS_DB` - Path to beads database file (default: auto-discover from cwd) - `BEADS_WORKING_DIR` - Working directory for bd commands (default: `$PWD` or current directory). Used for multi-repo setups - see below @@ -70,7 +69,7 @@ Then use in Claude Desktop config: ## Multi-Repository Setup -**Recommended:** Use a single MCP server instance for all beads projects - it automatically routes to per-project local daemons. +**Recommended:** Use a single MCP server instance for all beads projects - it automatically routes to per-project Dolt servers. ### Single MCP Server (Recommended) @@ -86,28 +85,26 @@ Then use in Claude Desktop config: ``` **How it works (LSP model):** -1. MCP server checks for local daemon socket (`.beads/bd.sock`) in your current workspace -2. Routes requests to the **per-project daemon** based on working directory -3. Auto-starts the local daemon if not running -4. **Each project gets its own isolated daemon** serving only its database +1. MCP server detects the beads project in your current workspace +2. Routes requests to the **per-project Dolt server** based on working directory +3. Auto-starts the local Dolt server if not running +4. **Each project gets its own isolated Dolt server** serving only its database **Architecture:** ``` MCP Server (one instance) ↓ -Per-Project Daemons (one per workspace) +Per-Project Dolt Servers (one per workspace) ↓ -SQLite Databases (complete isolation) +Dolt Databases (complete isolation) ``` -**Why per-project daemons?** -- ✅ Complete database isolation between projects -- ✅ No cross-project pollution or git worktree conflicts -- ✅ Simpler mental model: one project = one database = one daemon -- ✅ Follows LSP (Language Server Protocol) architecture -- ✅ One MCP config works for unlimited projects - -**Note:** Global daemon support was removed in v0.16.0 to prevent cross-project database pollution. +**Why per-project Dolt servers?** +- Complete database isolation between projects +- No cross-project pollution or git worktree conflicts +- Simpler mental model: one project = one database = one Dolt server +- Follows LSP (Language Server Protocol) architecture +- One MCP config works for unlimited projects ### Alternative: Per-Project MCP Instances (Not Recommended) @@ -160,7 +157,7 @@ await beads_create_issue( ### Architecture **Connection Pool**: The MCP server maintains a connection pool keyed by canonical workspace path: -- Each workspace gets its own daemon socket connection +- Each workspace gets its own Dolt server connection - Paths are canonicalized (symlinks resolved, git toplevel detected) - Concurrent requests use `asyncio.Lock` to prevent race conditions - No LRU eviction (keeps all connections open for session) @@ -203,9 +200,9 @@ await beads_ready_work(workspace_root="/Users/you/project-a") **Submodule handling**: Submodules with their own `.beads` directory are treated as separate projects. -**Stale sockets**: Currently no health checks. Phase 2 will add retry-on-failure if monitoring shows need. +**Stale connections**: Currently no health checks. Phase 2 will add retry-on-failure if monitoring shows need. -**Version mismatches**: Daemon version is auto-checked since v0.16.0. Mismatched daemons are automatically restarted. +**Version mismatches**: Dolt server version is auto-checked. Mismatched servers are automatically restarted. ## Features @@ -284,15 +281,15 @@ Test suite includes both mocked unit tests and integration tests with real `bd` ### Multi-Repo Integration Test -Test daemon RPC with multiple repositories: +Test Dolt server with multiple repositories: ```bash -# Start the daemon first +# Start the Dolt server first cd /path/to/beads -./bd daemon start +bd dolt start # Run multi-repo test cd integrations/beads-mcp uv run python test_multi_repo.py ``` -This test verifies that the daemon can handle operations across multiple repositories simultaneously using per-request context routing. +This test verifies that the Dolt server can handle operations across multiple repositories simultaneously using per-request context routing. diff --git a/scripts/README.md b/scripts/README.md index 0ee67fa82..aeb98ec39 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -20,7 +20,7 @@ Utility scripts for maintaining the beads project. This master script automates the **entire release process**: -1. ✅ Kills running daemons (avoids version conflicts) +1. ✅ Stops running Dolt servers (avoids version conflicts) 2. ✅ Runs tests and linting 3. ✅ Bumps version in all files 4. ✅ Commits and pushes version bump diff --git a/tests/integration/README.md b/tests/integration/README.md index 1a5611a65..84d089725 100644 --- a/tests/integration/README.md +++ b/tests/integration/README.md @@ -19,7 +19,7 @@ python3 -m pytest tests/integration/ Integration tests should: 1. Use temporary workspaces (cleaned up automatically) 2. Test real bd CLI commands, not just internal APIs -3. Use `--no-daemon` flag for fast execution +3. Use embedded mode for fast execution (no Dolt server dependency) 4. Verify behavior in `.beads/issues.jsonl` when relevant 5. Clean up resources in `finally` blocks 6. Provide clear output showing what's being tested diff --git a/website/docs/architecture/index.md b/website/docs/architecture/index.md index ed5488aee..603de853e 100644 --- a/website/docs/architecture/index.md +++ b/website/docs/architecture/index.md @@ -157,50 +157,49 @@ When working across multiple machines or clones: See [Sync Failures Recovery](/recovery/sync-failures) for data loss prevention in multi-machine workflows (Pattern A5/C3). -## The Daemon +## Dolt Server Mode -The Beads daemon (`bd daemon`) handles background synchronization: +The Dolt server handles background synchronization and database operations: -- Watches for file changes -- Triggers sync on changes +- Manages the Dolt database backend +- Handles auto-commit for change tracking - Keeps SQLite in sync with JSONL -- Manages lock files +- Logs available at `.beads/dolt/sql-server.log` :::tip -The daemon is optional but recommended for multi-agent workflows. +Start the Dolt server with `bd dolt start`. Check health with `bd doctor`. ::: -### Running Without the Daemon +### Embedded Mode (No Server) -For CI/CD pipelines, containers, and single-use scenarios, run commands without spawning a daemon: +For CI/CD pipelines, containers, and single-use scenarios, no server is needed. Beads operates in embedded mode automatically when no Dolt server is running: ```bash -bd --no-daemon create "CI-generated issue" -bd --no-daemon sync +bd create "CI-generated issue" +bd sync ``` -**When to use `--no-daemon`:** +**When embedded mode is appropriate:** - CI/CD pipelines (Jenkins, GitHub Actions) - Docker containers - Ephemeral environments - Scripts that should not leave background processes -- Debugging daemon-related issues -### Daemon in Multi-Clone Scenarios +### Multi-Clone Scenarios :::warning Race Conditions in Multi-Clone Workflows -When multiple git clones of the same repository run daemons simultaneously, race conditions can occur during push/pull operations. This is particularly common in: +When multiple git clones of the same repository run sync operations simultaneously, race conditions can occur during push/pull operations. This is particularly common in: - Multi-agent AI workflows (multiple Claude/GPT instances) - Developer workstations with multiple checkouts - Worktree-based development workflows **Prevention:** -1. Use `bd daemons killall` before switching between clones -2. Ensure only one clone's daemon is active at a time -3. Consider `--no-daemon` mode for automated workflows +1. Stop the Dolt server (`bd dolt stop`) before switching between clones +2. Dolt handles worktrees natively in server mode +3. Use embedded mode for automated workflows ::: -See [Sync Failures Recovery](/recovery/sync-failures) for daemon race condition troubleshooting (Pattern B2). +See [Sync Failures Recovery](/recovery/sync-failures) for sync race condition troubleshooting (Pattern B2). ## Recovery Model @@ -217,7 +216,7 @@ The following sequence demonstrates how the architecture enables quick recovery. This sequence resolves the majority of reported issues: ```bash -bd daemons killall # Stop daemons (prevents race conditions) +bd dolt stop # Stop Dolt server (prevents race conditions) git worktree prune # Clean orphaned worktrees rm .beads/beads.db* # Remove potentially corrupted database bd sync --import-only # Rebuild from JSONL source of truth diff --git a/website/docs/cli-reference/index.md b/website/docs/cli-reference/index.md index 3d5291047..b88ce2b6c 100644 --- a/website/docs/cli-reference/index.md +++ b/website/docs/cli-reference/index.md @@ -19,7 +19,6 @@ bd [global-flags] [command-flags] [arguments] | Flag | Description | |------|-------------| | `--db ` | Use specific database file | -| `--no-daemon` | Bypass daemon, direct database access | | `--json` | Output in JSON format | | `--quiet` | Suppress non-essential output | | `--verbose` | Verbose output | @@ -91,7 +90,7 @@ Most frequently used: | `bd info` | Show system info | | `bd version` | Show version | | `bd config` | Manage configuration | -| `bd daemons` | Manage daemons | +| `bd doctor` | Check system health | | `bd hooks` | Manage git hooks | ### Workflows diff --git a/website/docs/cli-reference/sync.md b/website/docs/cli-reference/sync.md index 4987db884..80311fd9e 100644 --- a/website/docs/cli-reference/sync.md +++ b/website/docs/cli-reference/sync.md @@ -143,20 +143,23 @@ bd hooks uninstall ## Auto-Sync Behavior -### With Daemon (Default) +### With Dolt Server Mode (Default) -The daemon handles sync automatically: -- Exports to JSONL after changes (5s debounce) +When the Dolt server is running, sync is handled automatically: +- Dolt auto-commit tracks changes +- JSONL export happens after changes (5s debounce) - Imports from JSONL when newer -### Without Daemon +Start the Dolt server with `bd dolt start`. -Use `--no-daemon` flag: -- Changes only written to SQLite +### Embedded Mode (No Server) + +In CI/CD pipelines and ephemeral environments, no server is needed: +- Changes written directly to the database - Must manually export/sync ```bash -bd --no-daemon create "Task" +bd create "CI-generated task" bd export # Manual export needed ``` @@ -205,4 +208,4 @@ git pull # Imports deletions from remote 1. **Always sync at session end** - `bd sync` 2. **Install git hooks** - `bd hooks install` 3. **Use merge driver** - Avoids manual conflict resolution -4. **Check sync status** - `bd info` shows daemon/sync state +4. **Check sync status** - `bd info` shows sync state diff --git a/website/docs/core-concepts/index.md b/website/docs/core-concepts/index.md index 8f1cd7b39..9283acf0f 100644 --- a/website/docs/core-concepts/index.md +++ b/website/docs/core-concepts/index.md @@ -40,13 +40,13 @@ Four types of relationships: | `discovered-from` | Track issues found during work | No | | `related` | Soft relationship | No | -### Daemon +### Dolt Server Mode -Background process per workspace: -- Auto-starts on first command -- Handles auto-sync with 5s debounce -- Socket at `.beads/bd.sock` -- Manage with `bd daemons` commands +Dolt provides the database backend for beads: +- Start with `bd dolt start` +- Handles auto-commit and sync +- Logs available at `.beads/dolt/sql-server.log` +- Check health with `bd doctor` ### JSONL Sync @@ -71,6 +71,6 @@ Declarative workflow templates: ## Navigation - [Issues & Dependencies](/core-concepts/issues) -- [Daemon Architecture](/core-concepts/daemon) +- [Dolt Server Mode](/core-concepts/dolt-server) - [JSONL Sync](/core-concepts/jsonl-sync) - [Hash-based IDs](/core-concepts/hash-ids) diff --git a/website/docs/getting-started/ide-setup.md b/website/docs/getting-started/ide-setup.md index c674e94e1..3898749bb 100644 --- a/website/docs/getting-started/ide-setup.md +++ b/website/docs/getting-started/ide-setup.md @@ -193,8 +193,8 @@ Run a complete health check: # Check version bd version -# Check daemon -bd info +# Check project health +bd doctor # Check hooks bd hooks status diff --git a/website/docs/getting-started/installation.md b/website/docs/getting-started/installation.md index 5e8933274..7cc962c68 100644 --- a/website/docs/getting-started/installation.md +++ b/website/docs/getting-started/installation.md @@ -250,7 +250,7 @@ brew upgrade beads go install github.com/steveyegge/beads/cmd/bd@latest ``` -For post-upgrade steps (hooks, daemons, migrations), see [Upgrading](/getting-started/upgrading). +For post-upgrade steps (hooks, migrations), see [Upgrading](/getting-started/upgrading). ## Next Steps diff --git a/website/docs/getting-started/quickstart.md b/website/docs/getting-started/quickstart.md index e7f9065c8..2dcf5b6b6 100644 --- a/website/docs/getting-started/quickstart.md +++ b/website/docs/getting-started/quickstart.md @@ -37,16 +37,11 @@ The wizard will: - Import existing issues from git (if any) - Prompt to install git hooks (recommended) - Prompt to configure git merge driver (recommended) -- Auto-start daemon for sync (SQLite backend only) - -Notes: -- SQLite backend stores data in `.beads/beads.db`. -- Dolt backend stores data in `.beads/dolt/` and records `"database": "dolt"` in `.beads/metadata.json`. -- Dolt backend runs **single-process-only**; daemon mode is disabled. Notes: - SQLite backend stores data in `.beads/beads.db`. - Dolt backend stores data in `.beads/dolt/` and records `"database": "dolt"` in `.beads/metadata.json`. +- Dolt backend uses a Dolt server for database access (`bd dolt start/stop`). ## Your First Issues diff --git a/website/docs/getting-started/upgrading.md b/website/docs/getting-started/upgrading.md index 4e5010df3..38fd62d16 100644 --- a/website/docs/getting-started/upgrading.md +++ b/website/docs/getting-started/upgrading.md @@ -68,7 +68,7 @@ sudo mv bd /usr/local/bin/ ## After Upgrading -**Important:** After upgrading, update your hooks and restart daemons: +**Important:** After upgrading, update your hooks: ```bash # 1. Check what changed @@ -77,11 +77,11 @@ bd info --whats-new # 2. Update git hooks to match new version bd hooks install -# 3. Restart all daemons -bd daemons killall - -# 4. Check for any outdated hooks +# 3. Check for any outdated hooks bd info # Shows warnings if hooks are outdated + +# 4. If using Dolt backend, restart the server +bd dolt stop && bd dolt start ``` **Why update hooks?** Git hooks are versioned with bd. Outdated hooks may miss new auto-sync features or bug fixes. @@ -104,29 +104,8 @@ bd migrate bd migrate --cleanup --yes ``` -## Daemon Version Mismatches - -If you see daemon version mismatch warnings: - -```bash -# List all running daemons -bd daemons list --json - -# Check for version mismatches -bd daemons health --json - -# Restart all daemons with new version -bd daemons killall --json -``` - ## Troubleshooting Upgrades -### Old daemon still running - -```bash -bd daemons killall -``` - ### Hooks out of date ```bash diff --git a/website/docs/integrations/claude-code.md b/website/docs/integrations/claude-code.md index a45801f44..998d31922 100644 --- a/website/docs/integrations/claude-code.md +++ b/website/docs/integrations/claude-code.md @@ -168,9 +168,8 @@ bd prime # Force sync bd sync -# Check daemon -bd info -bd daemons health +# Check system health +bd doctor ``` ### Database not found diff --git a/website/docs/integrations/junie.md b/website/docs/integrations/junie.md index e606d50fb..edc63b85b 100644 --- a/website/docs/integrations/junie.md +++ b/website/docs/integrations/junie.md @@ -190,9 +190,8 @@ bd mcp --help # Force sync bd sync -# Check daemon -bd info -bd daemons health +# Check system health +bd doctor ``` ### Database not found diff --git a/website/docs/intro.md b/website/docs/intro.md index e19b94a40..0c73c2bf5 100644 --- a/website/docs/intro.md +++ b/website/docs/intro.md @@ -45,7 +45,7 @@ bd ready |---------|-------------| | **Issues** | Work items with priorities, types, labels, and dependencies | | **Dependencies** | `blocks`, `parent-child`, `discovered-from`, `related` | -| **Daemon** | Background process for auto-sync and performance | +| **Dolt Server** | Database server for multi-writer access and performance | | **Formulas** | Declarative workflow templates (TOML or JSON) | | **Molecules** | Work graphs with parent-child relationships | | **Gates** | Async coordination primitives (human, timer, GitHub) | diff --git a/website/docs/recovery/database-corruption.md b/website/docs/recovery/database-corruption.md index 400b43ebb..885720820 100644 --- a/website/docs/recovery/database-corruption.md +++ b/website/docs/recovery/database-corruption.md @@ -33,9 +33,9 @@ If you see `-wal` or `-shm` files alongside `beads.db`, a transaction may have b Back up your `.beads/` directory before proceeding. ::: -**Step 1:** Stop the daemon +**Step 1:** Stop the Dolt server ```bash -bd daemon stop +bd dolt stop ``` **Step 2:** Back up current state @@ -54,13 +54,13 @@ bd status bd list ``` -**Step 5:** Restart daemon +**Step 5:** Restart the Dolt server ```bash -bd daemon start +bd dolt start ``` ## Prevention - Avoid interrupting `bd sync` operations -- Let the daemon handle synchronization -- Use `bd daemon stop` before system shutdown +- Let the Dolt server handle synchronization +- Use `bd dolt stop` before system shutdown diff --git a/website/docs/recovery/index.md b/website/docs/recovery/index.md index 6cfdaeb0e..151d78838 100644 --- a/website/docs/recovery/index.md +++ b/website/docs/recovery/index.md @@ -25,8 +25,8 @@ Before diving into specific runbooks, try these quick checks: # Check Beads status bd status -# Verify daemon is running -bd daemon status +# Verify Dolt server is running +bd doctor # Check for blocked issues bd blocked diff --git a/website/docs/recovery/sync-failures.md b/website/docs/recovery/sync-failures.md index 97ef903f4..36747bba9 100644 --- a/website/docs/recovery/sync-failures.md +++ b/website/docs/recovery/sync-failures.md @@ -13,32 +13,32 @@ This runbook helps you recover from `bd sync` failures. - `bd sync` hangs or times out - Network-related error messages - "failed to push" or "failed to pull" errors -- Daemon not responding +- Dolt server not responding ## Diagnosis ```bash -# Check daemon status -bd daemon status +# Check Dolt server health +bd doctor # Check sync state bd status -# View daemon logs -cat .beads/daemon.log | tail -50 +# View Dolt server logs +tail -50 .beads/dolt/sql-server.log ``` ## Solution -**Step 1:** Stop the daemon +**Step 1:** Stop the Dolt server ```bash -bd daemon stop +bd dolt stop ``` **Step 2:** Check for lock files ```bash ls -la .beads/*.lock -# Remove stale locks if daemon is definitely stopped +# Remove stale locks if Dolt server is definitely stopped rm -f .beads/*.lock ``` @@ -47,9 +47,9 @@ rm -f .beads/*.lock bd doctor --fix ``` -**Step 4:** Restart daemon +**Step 4:** Restart the Dolt server ```bash -bd daemon start +bd dolt start ``` **Step 5:** Verify sync works @@ -63,7 +63,7 @@ bd status | Cause | Solution | |-------|----------| | Network timeout | Retry with better connection | -| Stale lock file | Remove lock after stopping daemon | +| Stale lock file | Remove lock after stopping Dolt server | | Corrupted state | Use `bd doctor --fix` | | Git conflicts | See [Merge Conflicts](/recovery/merge-conflicts) | @@ -71,4 +71,4 @@ bd status - Ensure stable network before sync - Let sync complete before closing terminal -- Use `bd daemon stop` before system shutdown +- Use `bd dolt stop` before system shutdown diff --git a/website/docs/reference/advanced.md b/website/docs/reference/advanced.md index b87148a5d..743be0fb6 100644 --- a/website/docs/reference/advanced.md +++ b/website/docs/reference/advanced.md @@ -161,16 +161,22 @@ bd config set database.cache_size 10000 ### Many Concurrent Agents +Beads uses Dolt server mode to handle concurrent access from multiple agents. +The server manages transaction isolation automatically. + ```bash -# Use event-driven daemon -export BEADS_DAEMON_MODE=events -bd daemons killall +# Start the Dolt server +bd dolt start + +# Check server health +bd doctor ``` ### CI/CD Optimization +In CI/CD environments, beads uses embedded mode by default (no server required): + ```bash -# Disable daemon in CI -export BEADS_NO_DAEMON=true -bd --no-daemon list +# Just run commands directly — no special flags needed +bd list ``` diff --git a/website/docs/reference/configuration.md b/website/docs/reference/configuration.md index d7a05dc08..44e146746 100644 --- a/website/docs/reference/configuration.md +++ b/website/docs/reference/configuration.md @@ -72,16 +72,6 @@ auto_export = true # Auto-export on changes debounce_seconds = 5 # Debounce interval ``` -### Daemon - -```toml -[daemon] -auto_start = true # Auto-start daemon -sync_interval = "5s" # Sync check interval -log_level = "info" # debug|info|warn|error -mode = "poll" # poll|events (experimental) -``` - ### Git ```toml @@ -113,8 +103,6 @@ prune_on_sync = true # Auto-prune old records | Variable | Description | |----------|-------------| | `BEADS_DB` | Database path | -| `BEADS_NO_DAEMON` | Disable daemon | -| `BEADS_DAEMON_MODE` | Daemon mode (poll/events) | | `BEADS_LOG_LEVEL` | Log level | | `BEADS_CONFIG` | Config file path | @@ -123,9 +111,6 @@ prune_on_sync = true # Auto-prune old records ```bash # Override database bd --db /tmp/test.db list - -# Disable daemon for single command -bd --no-daemon create "Task" ``` ## Example Configuration @@ -141,11 +126,6 @@ hash_length = 6 orphan_handling = "resurrect" dedupe_on_import = true -[daemon] -auto_start = true -sync_interval = "10s" -mode = "events" - [git] auto_commit = true auto_push = true diff --git a/website/docs/reference/faq.md b/website/docs/reference/faq.md index de42d05fb..6caa02a9d 100644 --- a/website/docs/reference/faq.md +++ b/website/docs/reference/faq.md @@ -41,22 +41,21 @@ Sequential IDs (`#1`, `#2`) break when: Hash-based IDs are globally unique without coordination. -### Why a daemon? +### How does the Dolt server work? -The daemon provides: -- Auto-sync with 5-second debounce -- Batched operations for performance -- Background monitoring +Beads uses Dolt server mode for concurrent access: +- Transaction isolation for multiple agents +- SQL-based queries for performance +- Automatic retry on conflicts -Use `--no-daemon` when not needed (CI, worktrees). +In CI/CD or single-agent environments, beads uses embedded mode automatically (no server required). ## Usage ### How do I sync issues to git? ```bash -# Auto-sync via daemon (default) -# Or manual sync: +# Manual sync: bd sync ``` @@ -79,11 +78,8 @@ Yes! That's what beads was designed for: ### How do I use beads in CI/CD? ```bash -# Disable daemon in CI -export BEADS_NO_DAEMON=true - -# Or per-command -bd --no-daemon list +# Just run commands directly — beads uses embedded mode in CI +bd list ``` ## Workflows @@ -132,23 +128,23 @@ bd import --from github --repo owner/repo ## Troubleshooting -### Why is the daemon not starting? +### Why is the Dolt server not starting? ```bash -# Remove stale socket -rm -f .beads/bd.sock +# Check server status +bd doctor -# Restart -bd daemons killall -bd info +# Check server logs +cat .beads/dolt/sql-server.log + +# Restart the server +bd dolt stop +bd dolt start ``` ### Why aren't my changes syncing? ```bash -# Check daemon status -bd info - # Force sync bd sync diff --git a/website/docs/reference/git-integration.md b/website/docs/reference/git-integration.md index 1a33ffb16..e72ead3df 100644 --- a/website/docs/reference/git-integration.md +++ b/website/docs/reference/git-integration.md @@ -24,7 +24,7 @@ Beads uses git for: ├── issues.jsonl # Issue data (git-tracked) ├── deletions.jsonl # Deletion manifest (git-tracked) ├── config.toml # Project config (git-tracked) -└── bd.sock # Daemon socket (gitignored) +└── dolt/ # Dolt server data (gitignored) ``` ## Git Hooks @@ -97,16 +97,14 @@ This: ## Git Worktrees -Beads requires `--no-daemon` in git worktrees: +Beads works in git worktrees using embedded mode: ```bash -# In worktree -bd --no-daemon create "Task" -bd --no-daemon list +# In worktree — just run commands directly +bd create "Task" +bd list ``` -Why: Daemon uses `.beads/bd.sock` which conflicts across worktrees. - ## Branch Workflows ### Feature Branch @@ -167,4 +165,4 @@ bd duplicates --auto-merge 2. **Use merge driver** - Avoid manual conflict resolution 3. **Sync regularly** - `bd sync` at session end 4. **Pull before work** - Get latest issues -5. **Use `--no-daemon` in worktrees** +5. **Worktrees use embedded mode automatically** diff --git a/website/docs/reference/troubleshooting.md b/website/docs/reference/troubleshooting.md index 218543b6e..ea3705cca 100644 --- a/website/docs/reference/troubleshooting.md +++ b/website/docs/reference/troubleshooting.md @@ -53,8 +53,8 @@ bd --db .beads/beads.db list ### Database locked ```bash -# Stop daemon -bd daemons killall +# Stop the Dolt server if running +bd dolt stop # Try again bd list @@ -68,20 +68,20 @@ rm .beads/beads.db bd import -i .beads/issues.jsonl ``` -## Daemon Issues +## Dolt Server Issues -### Daemon not starting +### Server not starting ```bash -# Check status -bd info +# Check server health +bd doctor -# Remove stale socket -rm -f .beads/bd.sock +# Check server logs +cat .beads/dolt/sql-server.log -# Restart -bd daemons killall -bd info +# Restart the server +bd dolt stop +bd dolt start ``` ### Version mismatch @@ -89,16 +89,8 @@ bd info After upgrading bd: ```bash -bd daemons killall -bd info -``` - -### High CPU usage - -```bash -# Switch to event-driven mode -export BEADS_DAEMON_MODE=events -bd daemons killall +bd dolt stop +bd dolt start ``` ## Sync Issues @@ -109,9 +101,6 @@ bd daemons killall # Force sync bd sync -# Check daemon -bd info | grep daemon - # Check hooks bd hooks status ``` @@ -212,7 +201,7 @@ bd --verbose list ### Logs ```bash -bd daemons logs . -n 100 +cat .beads/dolt/sql-server.log ``` ### System info