fix(doctor): detect missing git repo and improve daemon startup message (#890)

When not in a git repository:
- Daemon startup now shows clear message immediately instead of waiting
  5 seconds: "Note: No git repository initialized — running without
  background sync"
- Added new doctor check "Git Sync Setup" that explains the situation

Doctor check now shows three states:
1. No git repo → Warning with fix: "Run 'git init' to enable background sync"
2. Git repo, no sync-branch → OK with hint about team collaboration benefits
3. Git repo + sync-branch → OK, fully configured

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

cmd/bd/daemon_autostart.go

@@ -310,6 +310,14 @@ func determineSocketPath(socketPath string) string {
 }
 
 func startDaemonProcess(socketPath string) bool {
+	// Early check: daemon requires a git repository (unless --local mode)
+	// Skip attempting to start and avoid the 5-second wait if not in git repo
+	if !isGitRepo() {
+		debugLog("not in a git repository, skipping daemon start")
+		fmt.Fprintf(os.Stderr, "%s No git repository initialized - running without background sync\n", ui.RenderMuted("Note:"))
+		return false
+	}
+
 	binPath, err := executableFn()
 	if err != nil {
 		binPath = os.Args[0]

cmd/bd/daemon_autostart_unit_test.go

@@ -8,6 +8,7 @@ import (
 	"os/exec"
 	"path/filepath"
 	"runtime"
+	"strings"
 	"testing"
 	"time"
 
@@ -280,6 +281,39 @@ func TestDaemonAutostart_StartDaemonProcess_Stubbed(t *testing.T) {
 	}
 }
 
+func TestDaemonAutostart_StartDaemonProcess_NoGitRepo(t *testing.T) {
+	// Test that startDaemonProcess returns false immediately when not in a git repo
+	tmpDir := t.TempDir()
+	oldDir, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("Getwd: %v", err)
+	}
+	defer func() {
+		_ = os.Chdir(oldDir)
+	}()
+
+	// Change to a temp directory that is NOT a git repo
+	if err := os.Chdir(tmpDir); err != nil {
+		t.Fatalf("Chdir: %v", err)
+	}
+
+	// Capture stderr to verify the message
+	output := captureStderr(t, func() {
+		result := startDaemonProcess(filepath.Join(tmpDir, "bd.sock"))
+		if result {
+			t.Errorf("expected startDaemonProcess to return false when not in git repo")
+		}
+	})
+
+	// Verify the correct message is shown
+	if !strings.Contains(output, "No git repository initialized") {
+		t.Errorf("expected output to contain 'No git repository initialized', got: %q", output)
+	}
+	if !strings.Contains(output, "running without background sync") {
+		t.Errorf("expected output to contain 'running without background sync', got: %q", output)
+	}
+}
+
 func TestDaemonAutostart_RestartDaemonForVersionMismatch_Stubbed(t *testing.T) {
 	oldExec := execCommandFn
 	oldWait := waitForSocketReadinessFn

cmd/bd/doctor.go

@@ -349,7 +349,12 @@ func runDiagnostics(path string) doctorResult {
 		result.OverallOK = false
 	}
 
-	// Check 8: Daemon health
+	// Check 8a: Git sync setup (informational - explains why daemon might not start)
+	gitSyncCheck := convertWithCategory(doctor.CheckGitSyncSetup(path), doctor.CategoryRuntime)
+	result.Checks = append(result.Checks, gitSyncCheck)
+	// Don't fail overall check for git sync warning - beads works fine without git
+
+	// Check 8b: Daemon health
 	daemonCheck := convertWithCategory(doctor.CheckDaemonStatus(path, Version), doctor.CategoryRuntime)
 	result.Checks = append(result.Checks, daemonCheck)
 	if daemonCheck.Status == statusWarning || daemonCheck.Status == statusError {

cmd/bd/doctor/daemon.go

@@ -7,6 +7,8 @@ import (
 	"path/filepath"
 
 	"github.com/steveyegge/beads/internal/daemon"
+	"github.com/steveyegge/beads/internal/git"
+	"github.com/steveyegge/beads/internal/syncbranch"
 )
 
 // CheckDaemonStatus checks the health of the daemon for a workspace.
@@ -122,3 +124,39 @@ func CheckVersionMismatch(db *sql.DB, cliVersion string) string {
 
 	return ""
 }
+
+// CheckGitSyncSetup checks if git repository and sync-branch are configured for daemon sync.
+// This is informational - beads works fine without git sync, but users may want to enable it.
+func CheckGitSyncSetup(path string) DoctorCheck {
+	// Check if we're in a git repository
+	_, err := git.GetGitDir()
+	if err != nil {
+		return DoctorCheck{
+			Name:     "Git Sync Setup",
+			Status:   StatusWarning,
+			Message:  "No git repository (background sync unavailable)",
+			Detail:   "The daemon requires a git repository for background sync. Without it, beads runs in direct mode.",
+			Fix:      "Run 'git init' to enable background sync",
+			Category: CategoryRuntime,
+		}
+	}
+
+	// Git repo exists - check if sync-branch is configured
+	if !syncbranch.IsConfigured() {
+		return DoctorCheck{
+			Name:     "Git Sync Setup",
+			Status:   StatusOK,
+			Message:  "Git repository detected (sync-branch not configured)",
+			Detail:   "Beads commits directly to current branch. For team collaboration or to keep beads changes isolated, consider using a sync-branch.",
+			Fix:      "Run 'bd config set sync.branch beads-sync' to use a dedicated branch for beads metadata",
+			Category: CategoryRuntime,
+		}
+	}
+
+	return DoctorCheck{
+		Name:     "Git Sync Setup",
+		Status:   StatusOK,
+		Message:  "Git repository and sync-branch configured",
+		Category: CategoryRuntime,
+	}
+}

cmd/bd/doctor/daemon_test.go

@@ -2,8 +2,11 @@ package doctor
 
 import (
 	"os"
+	"os/exec"
 	"path/filepath"
 	"testing"
+
+	"github.com/steveyegge/beads/internal/git"
 )
 
 func TestCheckDaemonStatus(t *testing.T) {
@@ -33,3 +36,71 @@ func TestCheckDaemonStatus(t *testing.T) {
 		}
 	})
 }
+
+func TestCheckGitSyncSetup(t *testing.T) {
+	t.Run("not in git repository", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		oldDir, err := os.Getwd()
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer func() {
+			_ = os.Chdir(oldDir)
+			git.ResetCaches()
+		}()
+
+		if err := os.Chdir(tmpDir); err != nil {
+			t.Fatal(err)
+		}
+		git.ResetCaches()
+
+		check := CheckGitSyncSetup(tmpDir)
+
+		if check.Status != StatusWarning {
+			t.Errorf("Status = %q, want %q", check.Status, StatusWarning)
+		}
+		if check.Name != "Git Sync Setup" {
+			t.Errorf("Name = %q, want %q", check.Name, "Git Sync Setup")
+		}
+		if check.Fix == "" {
+			t.Error("Expected Fix to contain instructions")
+		}
+	})
+
+	t.Run("in git repository without sync-branch", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		oldDir, err := os.Getwd()
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer func() {
+			_ = os.Chdir(oldDir)
+			git.ResetCaches()
+		}()
+
+		// Initialize git repo
+		cmd := exec.Command("git", "init")
+		cmd.Dir = tmpDir
+		if err := cmd.Run(); err != nil {
+			t.Fatalf("Failed to init git repo: %v", err)
+		}
+
+		if err := os.Chdir(tmpDir); err != nil {
+			t.Fatal(err)
+		}
+		git.ResetCaches()
+
+		check := CheckGitSyncSetup(tmpDir)
+
+		if check.Status != StatusOK {
+			t.Errorf("Status = %q, want %q", check.Status, StatusOK)
+		}
+		if check.Name != "Git Sync Setup" {
+			t.Errorf("Name = %q, want %q", check.Name, "Git Sync Setup")
+		}
+		// Should mention sync-branch not configured
+		if check.Detail == "" {
+			t.Error("Expected Detail to contain sync-branch hint")
+		}
+	})
+}