fix: doctor lock false positive and stale bd sync references (GH#1981, GH#2007)

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 <noreply@anthropic.com>
This commit is contained in:
beads/crew/elinor 2026-02-22 18:34:44 -08:00 • committed by Steve Yegge
commit da8a1bf4ed
10 changed files with 71 additions and 113 deletions

View file

@ -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))
}

View file

@ -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{

View file

@ -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)",
}
}

View file

@ -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),
}
}

View file

@ -66,28 +66,11 @@ func CheckStaleLockFiles(path string) DoctorCheck {
}
}
// Check Dolt internal LOCK files (noms layer filesystem lock).
// These live at .beads/dolt/<database>/.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/<db>/.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

View file

@ -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)
}
})

View file

@ -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()

View file

@ -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 <id>`" + ` - 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 <id>`" + ` - Complete work
- ` + "`bd sync`" + ` - Sync with git (run at session end)
- ` + "`bd dolt push`" + ` - Push beads to remote
For full workflow details: ` + "`bd prime`" + ``

View file

@ -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)

View file

@ -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 <id1> <id2> ... # 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 <files> (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 <query>`" + ` - Search issues by keyword`
completingWorkflow = `**Completing work:**
` + "```bash" + `
bd close <id1> <id2> ... # 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 <files> (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 <query>`" + ` - Search issues by keyword`
completingWorkflow = `**Completing work:**
` + "```bash" + `
bd close <id1> <id2> ... # 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 <files> (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 <query>`" + ` - Search issues by keyword`
completingWorkflow = `**Completing work:**
` + "```bash" + `
bd close <id1> <id2> ... # 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)