fix: migrate server-root remotes to database dir on store open (GH#2118)

Users commonly run `dolt remote add` in .beads/dolt/ (server root) instead
of .beads/dolt/<database>/ (where CLI push/pull runs). syncCLIRemotesToSQL
now checks the server root for remotes missing from the database directory
and propagates them to both CLI and SQL surfaces.

Also improves the "remote not found" hint to explain the directory mismatch
and recommend `bd dolt remote add` over raw `dolt remote add`.

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

Author: steveyegge

cmd/bd/dolt.go

@@ -157,15 +157,19 @@ uncommitted changes in its working set).`,
 			if err := st.ForcePush(ctx); err != nil {
 				fmt.Fprintf(os.Stderr, "Error: %v\n", err)
 				if isRemoteNotFoundErr(err) {
-					fmt.Fprintf(os.Stderr, "Hint: run 'bd dolt remote add <name> <url>' to register the remote.\n")
+					fmt.Fprintf(os.Stderr, "Hint: use 'bd dolt remote add <name> <url>' (not 'dolt remote add').\n")
+					fmt.Fprintf(os.Stderr, "  Running 'dolt remote add' directly may add the remote to the wrong directory.\n")
+					fmt.Fprintf(os.Stderr, "  Use 'bd dolt remote list' to check for discrepancies.\n")
 				}
 				os.Exit(1)
 			}
 		} else {
 			if err := st.Push(ctx); err != nil {
 				fmt.Fprintf(os.Stderr, "Error: %v\n", err)
 				if isRemoteNotFoundErr(err) {
-					fmt.Fprintf(os.Stderr, "Hint: run 'bd dolt remote add <name> <url>' to register the remote.\n")
+					fmt.Fprintf(os.Stderr, "Hint: use 'bd dolt remote add <name> <url>' (not 'dolt remote add').\n")
+					fmt.Fprintf(os.Stderr, "  Running 'dolt remote add' directly may add the remote to the wrong directory.\n")
+					fmt.Fprintf(os.Stderr, "  Use 'bd dolt remote list' to check for discrepancies.\n")
 				}
 				os.Exit(1)
 			}
@@ -193,7 +197,9 @@ variables for authentication.`,
 		if err := st.Pull(ctx); err != nil {
 			fmt.Fprintf(os.Stderr, "Error: %v\n", err)
 			if isRemoteNotFoundErr(err) {
-				fmt.Fprintf(os.Stderr, "Hint: run 'bd dolt remote add <name> <url>' to register the remote.\n")
+				fmt.Fprintf(os.Stderr, "Hint: use 'bd dolt remote add <name> <url>' (not 'dolt remote add').\n")
+				fmt.Fprintf(os.Stderr, "  Running 'dolt remote add' directly may add the remote to the wrong directory.\n")
+				fmt.Fprintf(os.Stderr, "  Use 'bd dolt remote list' to check for discrepancies.\n")
 			}
 			os.Exit(1)
 		}

internal/storage/dolt/federation.go

@@ -3,7 +3,9 @@ package dolt
 import (
 	"context"
 	"fmt"
+	"os"
 	"os/exec"
+	"path/filepath"
 	"strings"
 	"time"
 
@@ -121,14 +123,32 @@ func (s *DoltStore) ListRemotes(ctx context.Context) ([]storage.RemoteInfo, erro
 // After a server restart, dolt_remotes (in-memory) is empty while CLI remotes
 // (persisted in .dolt/config) survive. This is best-effort: errors are silently
 // ignored because a missing remote will surface a clear error at push/pull time.
+//
+// GH#2118: Also checks the server root directory (dbPath) for remotes that were
+// added there instead of the database subdirectory (CLIDir). Users commonly run
+// `dolt remote add` in .beads/dolt/ (server root) rather than .beads/dolt/<db>/
+// (database dir). When found, these remotes are propagated to the database CLI
+// directory so that CLI push/pull can find them.
+//
 // See GH#2315.
 func (s *DoltStore) syncCLIRemotesToSQL(ctx context.Context) {
 	dir := s.CLIDir()
 	if dir == "" {
 		return
 	}
 	cliRemotes, err := doltutil.ListCLIRemotes(dir)
-	if err != nil || len(cliRemotes) == 0 {
+	if err != nil {
+		cliRemotes = nil
+	}
+
+	// GH#2118: If the database directory has no remotes (or doesn't exist),
+	// check the server root directory. Users often run `dolt remote add` in
+	// .beads/dolt/ (server root) instead of .beads/dolt/<database>/.
+	if len(cliRemotes) == 0 {
+		cliRemotes = s.migrateServerRootRemotes(dir)
+	}
+
+	if len(cliRemotes) == 0 {
 		return
 	}
 	sqlRemotes, err := s.ListRemotes(ctx)
@@ -143,6 +163,39 @@ func (s *DoltStore) syncCLIRemotesToSQL(ctx context.Context) {
 	}
 }
 
+// migrateServerRootRemotes checks the dolt server root directory (dbPath) for
+// remotes that should be propagated to the database CLI directory (CLIDir).
+// This handles GH#2118: users run `dolt remote add` in .beads/dolt/ (server root)
+// instead of .beads/dolt/<database>/ (where CLI push/pull actually runs).
+//
+// Returns the combined CLI remotes after migration, or nil if nothing to migrate.
+func (s *DoltStore) migrateServerRootRemotes(cliDir string) []storage.RemoteInfo {
+	rootDir := s.dbPath
+	if rootDir == "" || rootDir == cliDir {
+		return nil
+	}
+	// Server root must have .dolt/ (from dolt init)
+	if _, err := os.Stat(filepath.Join(rootDir, ".dolt")); err != nil {
+		return nil
+	}
+	rootRemotes, err := doltutil.ListCLIRemotes(rootDir)
+	if err != nil || len(rootRemotes) == 0 {
+		return nil
+	}
+	// Database dir must have .dolt/ to accept CLI remotes
+	if _, err := os.Stat(filepath.Join(cliDir, ".dolt")); err != nil {
+		return nil
+	}
+	// Propagate server-root remotes to the database directory
+	for _, r := range rootRemotes {
+		if existing := doltutil.FindCLIRemote(cliDir, r.Name); existing == "" {
+			_ = doltutil.AddCLIRemote(cliDir, r.Name, r.URL)
+		}
+	}
+	combined, _ := doltutil.ListCLIRemotes(cliDir)
+	return combined
+}
+
 // RemoveRemote removes a configured remote.
 func (s *DoltStore) RemoveRemote(ctx context.Context, name string) error {
 	_, err := s.execContext(ctx, "CALL DOLT_REMOTE('remove', ?)", name)

internal/storage/dolt/federation_test.go

@@ -7,6 +7,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 
@@ -518,6 +519,97 @@ func TestSyncCLIRemotesToSQL(t *testing.T) {
 	_ = store.RemoveRemote(ctx, remoteName)
 }
 
+// TestMigrateServerRootRemotes verifies GH#2118: remotes added in the dolt
+// server root directory (.beads/dolt/) are propagated to the database
+// subdirectory (.beads/dolt/<database>/) during syncCLIRemotesToSQL.
+// This handles the common case where users run `dolt remote add` in the
+// visible server root instead of the database subdirectory.
+func TestMigrateServerRootRemotes(t *testing.T) {
+	skipIfNoDolt(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+	defer cancel()
+
+	store, cleanup := setupTestStore(t)
+	defer cleanup()
+
+	remoteName := "test-root-remote"
+	remoteURL := "file:///tmp/test-root-remote"
+
+	// Set up CLIDir with dolt init (database directory)
+	cliDir := store.CLIDir()
+	if cliDir == "" {
+		t.Skip("no CLI dir available")
+	}
+	if err := os.MkdirAll(cliDir, 0755); err != nil {
+		t.Fatalf("failed to create CLI dir: %v", err)
+	}
+	initCmd := exec.Command("dolt", "init", "--name", "test", "--email", "test@test.com")
+	initCmd.Dir = cliDir
+	if out, err := initCmd.CombinedOutput(); err != nil {
+		// Might already be initialized
+		if !strings.Contains(string(out), "already") {
+			t.Fatalf("dolt init in CLIDir failed: %s: %v", out, err)
+		}
+	}
+
+	// Set up server root (dbPath) with dolt init — separate from CLIDir
+	rootDir := store.Path()
+	if rootDir == "" || rootDir == cliDir {
+		t.Skip("dbPath same as CLIDir — migration not applicable")
+	}
+	if _, err := os.Stat(filepath.Join(rootDir, ".dolt")); err != nil {
+		// Initialize root dir if needed
+		if err := os.MkdirAll(rootDir, 0755); err != nil {
+			t.Fatalf("failed to create root dir: %v", err)
+		}
+		initRootCmd := exec.Command("dolt", "init", "--name", "test", "--email", "test@test.com")
+		initRootCmd.Dir = rootDir
+		if out, err := initRootCmd.CombinedOutput(); err != nil {
+			if !strings.Contains(string(out), "already") {
+				t.Fatalf("dolt init in root failed: %s: %v", out, err)
+			}
+		}
+	}
+
+	// Add remote to server root (the wrong place — simulates the user's mistake)
+	if err := doltutil.AddCLIRemote(rootDir, remoteName, remoteURL); err != nil {
+		t.Fatalf("failed to add remote to server root: %v", err)
+	}
+	defer func() { _ = doltutil.RemoveCLIRemote(rootDir, remoteName) }()
+
+	// Verify remote is NOT in CLIDir before migration
+	if url := doltutil.FindCLIRemote(cliDir, remoteName); url != "" {
+		t.Fatalf("remote should not be in CLIDir before migration, found: %s", url)
+	}
+
+	// Remove from SQL if present (simulate clean state)
+	_ = store.RemoveRemote(ctx, remoteName)
+
+	// Run sync — should discover remote in server root and migrate to CLIDir + SQL
+	store.syncCLIRemotesToSQL(ctx)
+
+	// Verify remote was migrated to CLIDir
+	if url := doltutil.FindCLIRemote(cliDir, remoteName); url == "" {
+		t.Error("expected remote to be migrated to CLIDir")
+	} else if url != remoteURL {
+		t.Errorf("CLIDir remote URL = %q, want %q", url, remoteURL)
+	}
+
+	// Verify remote was registered in SQL
+	has, err := store.HasRemote(ctx, remoteName)
+	if err != nil {
+		t.Fatalf("HasRemote failed: %v", err)
+	}
+	if !has {
+		t.Error("expected remote to be registered in SQL after migration")
+	}
+
+	// Clean up
+	_ = doltutil.RemoveCLIRemote(cliDir, remoteName)
+	_ = store.RemoveRemote(ctx, remoteName)
+}
+
 // setupFederationStore creates a Dolt store for federation testing
 func setupFederationStore(t *testing.T, ctx context.Context, path, prefix string) (*DoltStore, func()) {
 	t.Helper()