fix: detect backup files on database-not-found and after bd init (GH#2327)

When switching git branches, the Dolt database does not travel with the
branch, causing database not found errors. Previously the error message
only mentioned server misconfiguration. Now it:

1. Checks for .beads/backup/*.jsonl files and suggests bd backup restore
2. Lists branch switching as a common cause
3. After bd init creates a fresh DB, warns if backup files exist

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: steveyegge

cmd/bd/init.go

@@ -882,6 +882,16 @@ environment variable.`,
 		fmt.Printf("  Issues will be named: %s\n\n", ui.RenderAccent(prefix+"-<hash> (e.g., "+prefix+"-a3f2dd)"))
 		fmt.Printf("Run %s to get started.\n\n", ui.RenderAccent("bd quickstart"))
 
+		// Detect backup files from a previous session (GH#2327).
+		// This catches the branch-switch scenario: user ran bd init on a new
+		// branch and the database was created fresh, but backup JSONL files
+		// exist from a prior backup on this or another branch.
+		if !bootstrappedFromRemote && dolt.HasBackupFiles(beadsDir) {
+			fmt.Printf("  %s Backup files detected in .beads/backup/\n", ui.RenderWarn("!"))
+			fmt.Printf("    To restore issues from a previous backup, run:\n")
+			fmt.Printf("      %s\n\n", ui.RenderAccent("bd backup restore"))
+		}
+
 		// Run limited diagnostics to verify init succeeded.
 		// Uses runInitDiagnostics (not runDiagnostics) to only check things
 		// that should be true immediately after init — skips git-dependent,

internal/storage/dolt/errors.go

@@ -4,6 +4,8 @@ import (
 	"database/sql"
 	"errors"
 	"fmt"
+	"os"
+	"path/filepath"
 	"strings"
 
 	mysql "github.com/go-sql-driver/mysql"
@@ -91,12 +93,25 @@ func wrapExecError(op string, err error) error {
 }
 
 // databaseNotFoundError builds the "database not found" error with a config-aware
-// hint about sync.git-remote. Extracted from openServerConnection for testability.
+// hint about sync.git-remote and backup recovery. Extracted from openServerConnection
+// for testability.
 func databaseNotFoundError(cfg *Config) error {
 	var b strings.Builder
 	fmt.Fprintf(&b, "database %q not found on Dolt server at %s:%d\n\n", cfg.Database, cfg.ServerHost, cfg.ServerPort)
-	b.WriteString("This usually means a server configuration problem, NOT a missing database.\n")
+
+	// Check if backup files exist — strong signal this is a branch-switch or
+	// fresh-clone scenario rather than a server misconfiguration (GH#2327).
+	if HasBackupFiles(cfg.BeadsDir) {
+		b.WriteString("Backup files found in .beads/backup/ — this may be a branch-switch\n")
+		b.WriteString("or fresh-clone scenario where the Dolt database doesn't exist yet.\n\n")
+		b.WriteString("To restore your issues:\n")
+		b.WriteString("  bd init --prefix <prefix>    # Initialize the database\n")
+		b.WriteString("  bd backup restore            # Restore issues from backup\n\n")
+		b.WriteString("If this is NOT a branch switch, see common causes below.\n\n")
+	}
+
 	b.WriteString("Common causes:\n")
+	b.WriteString("  - Switched git branches (the Dolt database is runtime state, not in git)\n")
 	b.WriteString("  - The server is serving a different data directory than expected\n")
 	b.WriteString("  - The server was restarted and is using a different port\n")
 	b.WriteString("  - Another project's Dolt server is running on this port\n\n")
@@ -112,3 +127,22 @@ func databaseNotFoundError(cfg *Config) error {
 
 	return errors.New(b.String())
 }
+
+// HasBackupFiles checks whether .beads/backup/ contains any JSONL files,
+// indicating a prior backup that could be restored (GH#2327).
+func HasBackupFiles(beadsDir string) bool {
+	if beadsDir == "" {
+		return false
+	}
+	backupDir := filepath.Join(beadsDir, "backup")
+	entries, err := os.ReadDir(backupDir)
+	if err != nil {
+		return false
+	}
+	for _, e := range entries {
+		if !e.IsDir() && strings.HasSuffix(e.Name(), ".jsonl") {
+			return true
+		}
+	}
+	return false
+}

internal/storage/dolt/errors_test.go

@@ -4,6 +4,8 @@ import (
 	"database/sql"
 	"errors"
 	"fmt"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 
@@ -147,4 +149,97 @@ func TestDatabaseNotFoundHint(t *testing.T) {
 			t.Errorf("expected bd init suggestion, got:\n%s", msg)
 		}
 	})
+
+	t.Run("hint detects backup files in beads dir (GH#2327)", func(t *testing.T) {
+		// Create a temp .beads/backup/ with a JSONL file
+		tmpDir := t.TempDir()
+		backupDir := filepath.Join(tmpDir, "backup")
+		if err := os.MkdirAll(backupDir, 0700); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(backupDir, "issues.jsonl"), []byte(`{"id":"x"}`), 0600); err != nil {
+			t.Fatal(err)
+		}
+
+		cfg := baseCfg
+		cfg.BeadsDir = tmpDir
+		err := databaseNotFoundError(&cfg)
+		msg := err.Error()
+
+		if !strings.Contains(msg, "Backup files found") {
+			t.Errorf("expected backup detection hint, got:\n%s", msg)
+		}
+		if !strings.Contains(msg, "bd backup restore") {
+			t.Errorf("expected bd backup restore suggestion, got:\n%s", msg)
+		}
+		// Should still mention branch switching as a common cause
+		if !strings.Contains(msg, "branch") {
+			t.Errorf("expected branch-switch mention, got:\n%s", msg)
+		}
+	})
+
+	t.Run("no backup hint when no backup files exist", func(t *testing.T) {
+		tmpDir := t.TempDir()
+
+		cfg := baseCfg
+		cfg.BeadsDir = tmpDir
+		err := databaseNotFoundError(&cfg)
+		msg := err.Error()
+
+		if strings.Contains(msg, "Backup files found") {
+			t.Errorf("should not mention backups when none exist, got:\n%s", msg)
+		}
+	})
+}
+
+func TestHasBackupFiles(t *testing.T) {
+	t.Run("returns false for empty beadsDir", func(t *testing.T) {
+		if HasBackupFiles("") {
+			t.Error("expected false for empty beadsDir")
+		}
+	})
+
+	t.Run("returns false when backup dir does not exist", func(t *testing.T) {
+		if HasBackupFiles(t.TempDir()) {
+			t.Error("expected false when backup dir missing")
+		}
+	})
+
+	t.Run("returns false when backup dir is empty", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		if err := os.MkdirAll(filepath.Join(tmpDir, "backup"), 0700); err != nil {
+			t.Fatal(err)
+		}
+		if HasBackupFiles(tmpDir) {
+			t.Error("expected false when backup dir is empty")
+		}
+	})
+
+	t.Run("returns false when backup dir has non-jsonl files", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		backupDir := filepath.Join(tmpDir, "backup")
+		if err := os.MkdirAll(backupDir, 0700); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(backupDir, "state.json"), []byte("{}"), 0600); err != nil {
+			t.Fatal(err)
+		}
+		if HasBackupFiles(tmpDir) {
+			t.Error("expected false when only non-jsonl files present")
+		}
+	})
+
+	t.Run("returns true when backup dir has jsonl files", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		backupDir := filepath.Join(tmpDir, "backup")
+		if err := os.MkdirAll(backupDir, 0700); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(backupDir, "issues.jsonl"), []byte(`{"id":"x"}`), 0600); err != nil {
+			t.Fatal(err)
+		}
+		if !HasBackupFiles(tmpDir) {
+			t.Error("expected true when jsonl files present")
+		}
+	})
 }