From da8a1bf4ed0b91b4ccdddf87895e92abeef7eb9b Mon Sep 17 00:00:00 2001 From: beads/crew/elinor Date: Sun, 22 Feb 2026 18:34:44 -0800 Subject: [PATCH] fix: doctor lock false positive and stale bd sync references (GH#1981, GH#2007) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit GH#1981: (b) Replace stale 'bd sync' advice in doctor messages with correct commands (bd import, bd init, bd doctor). (c) Fix noms LOCK false positive — run CheckLockHealth before any embedded Dolt opens so doctor's own flock()s don't trigger warnings. Remove age-based noms LOCK detection from CheckStaleLockFiles (redundant with flock probing in CheckLockHealth). GH#2007: Remove stale 'bd sync --status' and 'bd sync' references from bd prime output. Replace with bd dolt push/pull, bd export, bd search. Simplify close protocol (beads auto-commit to Dolt). Update onboard and init_team references. Co-Authored-By: Claude Opus 4.6 --- cmd/bd/doctor.go | 15 ++++++---- cmd/bd/doctor/dolt.go | 14 +++++++-- cmd/bd/doctor/git.go | 2 +- cmd/bd/doctor/gitignore.go | 4 +-- cmd/bd/doctor/locks.go | 27 ++++------------- cmd/bd/doctor/locks_test.go | 53 +++++---------------------------- cmd/bd/init_team.go | 2 +- cmd/bd/onboard.go | 4 +-- cmd/bd/onboard_test.go | 4 +-- cmd/bd/prime.go | 59 +++++++++++++++++++------------------ 10 files changed, 71 insertions(+), 113 deletions(-) diff --git a/cmd/bd/doctor.go b/cmd/bd/doctor.go index 6efc58017..aea9ae728 100644 --- a/cmd/bd/doctor.go +++ b/cmd/bd/doctor.go @@ -363,6 +363,12 @@ func runDiagnostics(path string) doctorResult { result.OverallOK = false } + // GH#1981: Run lock health check BEFORE any checks that open embedded + // Dolt databases. Earlier checks (CheckDatabaseVersion, CheckSchemaCompatibility, + // etc.) create noms LOCK files via flock(); if CheckLockHealth runs after them, + // it detects those same-process locks as "held by another process" (false positive). + earlyLockCheck := doctor.CheckLockHealth(path) + // Check 2: Database version dbCheck := convertWithCategory(doctor.CheckDatabaseVersion(path, Version), doctor.CategoryCore) result.Checks = append(result.Checks, dbCheck) @@ -437,11 +443,10 @@ func runDiagnostics(path string) doctorResult { result.OverallOK = false } - // Dolt health checks (connection, schema, sync, status via AccessLock) - // Run BEFORE federation checks: federation opens Dolt connections that may - // leave noms LOCK files on disk. CheckLockHealth (inside RunDoltHealthChecks) - // must run first to avoid false positives from doctor's own connections (#1925). - for _, dc := range doctor.RunDoltHealthChecks(path) { + // Dolt health checks (connection, schema, issue count, status). + // GH#1981: Pass the pre-computed lock check (run before any embedded Dolt + // opens) to avoid false positives from doctor's own noms LOCK files. + for _, dc := range doctor.RunDoltHealthChecksWithLock(path, earlyLockCheck) { result.Checks = append(result.Checks, convertDoctorCheck(dc)) } diff --git a/cmd/bd/doctor/dolt.go b/cmd/bd/doctor/dolt.go index bded2cb54..567b2097a 100644 --- a/cmd/bd/doctor/dolt.go +++ b/cmd/bd/doctor/dolt.go @@ -105,7 +105,18 @@ func IsDoltBackend(beadsDir string) bool { // RunDoltHealthChecks runs all Dolt-specific health checks using a single // shared server connection. Returns one check per health dimension. // Non-Dolt backends get N/A results for all dimensions. +// +// Note: Prefer RunDoltHealthChecksWithLock when the lock check has already +// been run early (before any embedded Dolt opens) to avoid false positives. func RunDoltHealthChecks(path string) []DoctorCheck { + return RunDoltHealthChecksWithLock(path, CheckLockHealth(path)) +} + +// RunDoltHealthChecksWithLock is like RunDoltHealthChecks but accepts a +// pre-computed lock health check result. This allows the caller to run +// CheckLockHealth before any checks that open embedded Dolt databases, +// avoiding false positives from doctor's own noms LOCK files (GH#1981). +func RunDoltHealthChecksWithLock(path string, lockCheck DoctorCheck) []DoctorCheck { beadsDir := resolveBeadsDir(filepath.Join(path, ".beads")) if !IsDoltBackend(beadsDir) { @@ -118,9 +129,6 @@ func RunDoltHealthChecks(path string) []DoctorCheck { } } - // Run lock health check before opening database (it doesn't need a connection) - lockCheck := CheckLockHealth(path) - conn, err := openDoltConn(beadsDir) if err != nil { errCheck := DoctorCheck{ diff --git a/cmd/bd/doctor/git.go b/cmd/bd/doctor/git.go index 858755db2..77472a055 100644 --- a/cmd/bd/doctor/git.go +++ b/cmd/bd/doctor/git.go @@ -394,7 +394,7 @@ func CheckGitUpstream(path string) DoctorCheck { Status: StatusWarning, Message: fmt.Sprintf("Behind upstream by %d commit(s)", behind), Detail: fmt.Sprintf("Branch: %s, upstream: %s", branch, upstream), - Fix: "Run 'git pull --rebase' (then re-run bd sync / bd doctor)", + Fix: "Run 'git pull --rebase' (then re-run bd doctor)", } } diff --git a/cmd/bd/doctor/gitignore.go b/cmd/bd/doctor/gitignore.go index ea448c2d1..675650ad5 100644 --- a/cmd/bd/doctor/gitignore.go +++ b/cmd/bd/doctor/gitignore.go @@ -196,7 +196,7 @@ func CheckIssuesTracking() DoctorCheck { return DoctorCheck{ Name: "Issues Tracking", Status: "warning", - Message: "issues.jsonl is ignored by git (bd sync will fail)", + Message: "issues.jsonl is ignored by git (JSONL import/export will fail)", Detail: detail, Fix: "Check global gitignore: git config --global core.excludesfile", } @@ -493,7 +493,7 @@ func CheckRedirectTargetSyncWorktree() DoctorCheck { Status: StatusWarning, Message: "Redirect target missing beads-sync worktree", Detail: fmt.Sprintf("Expected worktree at: %s", worktreePath), - Fix: fmt.Sprintf("Run 'bd sync' in %s to create the worktree", targetRepoRoot), + Fix: fmt.Sprintf("Run 'bd init' in %s to set up beads", targetRepoRoot), } } diff --git a/cmd/bd/doctor/locks.go b/cmd/bd/doctor/locks.go index 40689940a..07e3436e7 100644 --- a/cmd/bd/doctor/locks.go +++ b/cmd/bd/doctor/locks.go @@ -66,28 +66,11 @@ func CheckStaleLockFiles(path string) DoctorCheck { } } - // Check Dolt internal LOCK files (noms layer filesystem lock). - // These live at .beads/dolt//.dolt/noms/LOCK and are created - // by the embedded Dolt engine. If a process crashes without closing - // the embedded connector, the LOCK file persists and blocks future opens. - doltDir := filepath.Join(beadsDir, "dolt") - if dbEntries, err := os.ReadDir(doltDir); err == nil { - for _, dbEntry := range dbEntries { - if !dbEntry.IsDir() { - continue - } - nomsLock := filepath.Join(doltDir, dbEntry.Name(), ".dolt", "noms", "LOCK") - if info, err := os.Stat(nomsLock); err == nil { - age := time.Since(info.ModTime()) - if age > 5*time.Minute { - lockName := fmt.Sprintf("dolt/%s/.dolt/noms/LOCK", dbEntry.Name()) - staleFiles = append(staleFiles, lockName) - details = append(details, fmt.Sprintf("%s: age %s (Dolt internal lock from crashed process)", - lockName, age.Round(time.Second))) - } - } - } - } + // Note: Dolt internal noms LOCK files (.beads/dolt//.dolt/noms/LOCK) + // are NOT checked here. These files are created by the embedded Dolt engine + // and are never deleted, even after a clean close. Age-based detection + // produces false positives because the file persists indefinitely. + // Use CheckLockHealth() (which probes flock state) instead. (GH#1981) // Check startup lock (bd.sock.startlock) // Look for any .startlock files in beadsDir diff --git a/cmd/bd/doctor/locks_test.go b/cmd/bd/doctor/locks_test.go index 8e0d94b80..bd5b123a9 100644 --- a/cmd/bd/doctor/locks_test.go +++ b/cmd/bd/doctor/locks_test.go @@ -160,25 +160,10 @@ func TestCheckStaleLockFiles(t *testing.T) { } }) - t.Run("fresh noms LOCK not stale", func(t *testing.T) { - tmpDir := t.TempDir() - nomsDir := filepath.Join(tmpDir, ".beads", "dolt", "beads", ".dolt", "noms") - if err := os.MkdirAll(nomsDir, 0755); err != nil { - t.Fatal(err) - } - - lockPath := filepath.Join(nomsDir, "LOCK") - if err := os.WriteFile(lockPath, []byte("lock"), 0600); err != nil { - t.Fatal(err) - } - - result := CheckStaleLockFiles(tmpDir) - if result.Status != StatusOK { - t.Errorf("expected OK for fresh noms LOCK, got %s: %s", result.Status, result.Message) - } - }) - - t.Run("stale noms LOCK detected", func(t *testing.T) { + // GH#1981: noms LOCK files are no longer checked by CheckStaleLockFiles. + // Age-based detection produced false positives because Dolt never deletes + // these files. Use CheckLockHealth (flock probing) instead. + t.Run("noms LOCK ignored by staleness check", func(t *testing.T) { tmpDir := t.TempDir() nomsDir := filepath.Join(tmpDir, ".beads", "dolt", "beads", ".dolt", "noms") if err := os.MkdirAll(nomsDir, 0755); err != nil { @@ -189,39 +174,15 @@ func TestCheckStaleLockFiles(t *testing.T) { if err := os.WriteFile(lockPath, []byte("lock"), 0600); err != nil { t.Fatal(err) } + // Even an old noms LOCK should not trigger a warning oldTime := time.Now().Add(-10 * time.Minute) if err := os.Chtimes(lockPath, oldTime, oldTime); err != nil { t.Fatal(err) } result := CheckStaleLockFiles(tmpDir) - if result.Status != StatusWarning { - t.Errorf("expected Warning for stale noms LOCK, got %s: %s", result.Status, result.Message) - } - }) - - t.Run("stale noms LOCK multi-database", func(t *testing.T) { - tmpDir := t.TempDir() - beadsDir := filepath.Join(tmpDir, ".beads") - - for _, dbName := range []string{"beads", "other"} { - nomsDir := filepath.Join(beadsDir, "dolt", dbName, ".dolt", "noms") - if err := os.MkdirAll(nomsDir, 0755); err != nil { - t.Fatal(err) - } - lockPath := filepath.Join(nomsDir, "LOCK") - if err := os.WriteFile(lockPath, []byte("lock"), 0600); err != nil { - t.Fatal(err) - } - oldTime := time.Now().Add(-10 * time.Minute) - if err := os.Chtimes(lockPath, oldTime, oldTime); err != nil { - t.Fatal(err) - } - } - - result := CheckStaleLockFiles(tmpDir) - if result.Status != StatusWarning { - t.Errorf("expected Warning for multiple stale noms LOCKs, got %s: %s", result.Status, result.Message) + if result.Status != StatusOK { + t.Errorf("expected OK for noms LOCK (not checked by staleness), got %s: %s", result.Status, result.Message) } }) diff --git a/cmd/bd/init_team.go b/cmd/bd/init_team.go index 30f5d4880..008f70789 100644 --- a/cmd/bd/init_team.go +++ b/cmd/bd/init_team.go @@ -145,7 +145,7 @@ func runTeamWizard(ctx context.Context, store *dolt.DoltStore) error { fmt.Println(" • Periodically merge", syncBranch, "to main via PR") } - fmt.Println(" • Dolt handles sync natively — run 'bd sync' to sync changes") + fmt.Println(" • Dolt handles sync natively — run 'bd dolt push' to push changes") fmt.Println() fmt.Printf("Try it: %s\n", ui.RenderAccent("bd create \"Team planning issue\" -p 2")) fmt.Println() diff --git a/cmd/bd/onboard.go b/cmd/bd/onboard.go index 7609eed40..9f2ef0c3f 100644 --- a/cmd/bd/onboard.go +++ b/cmd/bd/onboard.go @@ -19,7 +19,7 @@ Run ` + "`bd prime`" + ` for workflow context, or install hooks (` + "`bd hooks - ` + "`bd ready`" + ` - Find unblocked work - ` + "`bd create \"Title\" --type task --priority 2`" + ` - Create issue - ` + "`bd close `" + ` - Complete work -- ` + "`bd sync`" + ` - Sync with git (run at session end) +- ` + "`bd dolt push`" + ` - Push beads to remote For full workflow details: ` + "`bd prime`" + `` @@ -32,7 +32,7 @@ Run ` + "`bd prime`" + ` for workflow context, or install hooks (` + "`bd hooks - ` + "`bd ready`" + ` - Find unblocked work - ` + "`bd create \"Title\" --type task --priority 2`" + ` - Create issue - ` + "`bd close `" + ` - Complete work -- ` + "`bd sync`" + ` - Sync with git (run at session end) +- ` + "`bd dolt push`" + ` - Push beads to remote For full workflow details: ` + "`bd prime`" + `` diff --git a/cmd/bd/onboard_test.go b/cmd/bd/onboard_test.go index 674bbddb3..dd1384013 100644 --- a/cmd/bd/onboard_test.go +++ b/cmd/bd/onboard_test.go @@ -45,8 +45,8 @@ func TestOnboardCommand(t *testing.T) { if !strings.Contains(agentsContent, "bd close") { t.Error("agentsContent should include quick reference to 'bd close'") } - if !strings.Contains(agentsContent, "bd sync") { - t.Error("agentsContent should include quick reference to 'bd sync'") + if !strings.Contains(agentsContent, "bd dolt push") { + t.Error("agentsContent should include quick reference to 'bd dolt push'") } // Verify it's actually minimal (less than 500 chars) diff --git a/cmd/bd/prime.go b/cmd/bd/prime.go index 4561a831b..de1f10863 100644 --- a/cmd/bd/prime.go +++ b/cmd/bd/prime.go @@ -203,14 +203,14 @@ func outputMCPContext(w io.Writer, stealthMode bool) error { var closeProtocol string if stealthMode || localOnly { - // Stealth mode or local-only: only flush to JSONL, no git operations - closeProtocol = "Before saying \"done\": bd sync --flush-only" + // Stealth mode or local-only: only export to JSONL, no git operations + closeProtocol = "Before saying \"done\": bd export" } else if ephemeral { - closeProtocol = "Before saying \"done\": git status → git add → bd sync → git commit (no push - ephemeral branch)" + closeProtocol = "Before saying \"done\": git status → git add → git commit (no push - ephemeral branch)" } else if noPush { - closeProtocol = "Before saying \"done\": git status → git add → bd sync → git commit (push disabled - run git push manually)" + closeProtocol = "Before saying \"done\": git status → git add → git commit (push disabled - run git push manually)" } else { - closeProtocol = "Before saying \"done\": git status → git add → bd sync → git commit → bd sync → git push" + closeProtocol = "Before saying \"done\": git status → git add → git commit → git push" } redirectNotice := getRedirectNotice(false) @@ -246,14 +246,14 @@ func outputCLIContext(w io.Writer, stealthMode bool) error { var gitWorkflowRule string if stealthMode || localOnly { - // Stealth mode or local-only: only flush to JSONL, no git operations - closeProtocol = `[ ] bd sync --flush-only (export beads to JSONL only)` + // Stealth mode or local-only: only export to JSONL, no git operations + closeProtocol = `[ ] bd export (export beads to JSONL)` syncSection = `### Sync & Collaboration -- ` + "`bd sync --flush-only`" + ` - Export to JSONL` +- ` + "`bd export`" + ` - Export beads to JSONL` completingWorkflow = `**Completing work:** ` + "```bash" + ` bd close ... # Close all completed issues at once -bd sync --flush-only # Export to JSONL +bd export # Export to JSONL ` + "```" // Only show local-only note if not in stealth mode (stealth is explicit user choice) if localOnly && !stealthMode { @@ -265,54 +265,55 @@ bd sync --flush-only # Export to JSONL } else if ephemeral { closeProtocol = `[ ] 1. git status (check what changed) [ ] 2. git add (stage code changes) -[ ] 3. bd sync (pull beads updates from main) +[ ] 3. bd dolt pull (pull beads updates from main) [ ] 4. git commit -m "..." (commit code changes)` closeNote = "**Note:** This is an ephemeral branch (no upstream). Code is merged to main locally, not pushed." syncSection = `### Sync & Collaboration -- ` + "`bd sync`" + ` - Pull beads updates from main (for ephemeral branches) -- ` + "`bd sync --status`" + ` - Check sync status without syncing` +- ` + "`bd dolt pull`" + ` - Pull beads updates from Dolt remote +- ` + "`bd dolt push`" + ` - Push beads to Dolt remote +- ` + "`bd search `" + ` - Search issues by keyword` completingWorkflow = `**Completing work:** ` + "```bash" + ` bd close ... # Close all completed issues at once -bd sync # Pull latest beads from main +bd dolt pull # Pull latest beads from main git add . && git commit -m "..." # Commit your changes # Merge to main when ready (local merge, not push) ` + "```" - gitWorkflowRule = "Git workflow: run `bd sync` at session end" + gitWorkflowRule = "Git workflow: run `bd dolt pull` at session start" } else if noPush { closeProtocol = `[ ] 1. git status (check what changed) [ ] 2. git add (stage code changes) -[ ] 3. bd sync (commit beads changes) -[ ] 4. git commit -m "..." (commit code) -[ ] 5. bd sync (commit any new beads changes)` +[ ] 3. git commit -m "..." (commit code) +[ ] 4. git push (push when ready)` closeNote = "**Note:** Push disabled via config. Run `git push` manually when ready." syncSection = `### Sync & Collaboration -- ` + "`bd sync`" + ` - Sync with git remote (run at session end) -- ` + "`bd sync --status`" + ` - Check sync status without syncing` +- ` + "`bd dolt push`" + ` - Push beads to Dolt remote +- ` + "`bd dolt pull`" + ` - Pull beads from Dolt remote +- ` + "`bd search `" + ` - Search issues by keyword` completingWorkflow = `**Completing work:** ` + "```bash" + ` bd close ... # Close all completed issues at once -bd sync # Sync beads (push disabled) +git add . && git commit -m "..." # Commit code changes # git push # Run manually when ready ` + "```" - gitWorkflowRule = "Git workflow: run `bd sync` at session end (push disabled)" + gitWorkflowRule = "Git workflow: beads auto-commit to Dolt (push disabled)" } else { closeProtocol = `[ ] 1. git status (check what changed) [ ] 2. git add (stage code changes) -[ ] 3. bd sync (commit beads changes) -[ ] 4. git commit -m "..." (commit code) -[ ] 5. bd sync (commit any new beads changes) -[ ] 6. git push (push to remote)` +[ ] 3. git commit -m "..." (commit code) +[ ] 4. git push (push to remote)` closeNote = "**NEVER skip this.** Work is not done until pushed." syncSection = `### Sync & Collaboration -- ` + "`bd sync`" + ` - Sync with git remote (run at session end) -- ` + "`bd sync --status`" + ` - Check sync status without syncing` +- ` + "`bd dolt push`" + ` - Push beads to Dolt remote +- ` + "`bd dolt pull`" + ` - Pull beads from Dolt remote +- ` + "`bd search `" + ` - Search issues by keyword` completingWorkflow = `**Completing work:** ` + "```bash" + ` bd close ... # Close all completed issues at once -bd sync # Push to remote +git add . && git commit -m "..." # Commit code changes +git push # Push to remote ` + "```" - gitWorkflowRule = "Git workflow: hooks auto-sync, run `bd sync` at session end" + gitWorkflowRule = "Git workflow: beads auto-commit to Dolt, run `git push` at session end" } redirectNotice := getRedirectNotice(true)