fix: add shared Dolt server mode for multi-repo/agent setups (GH#2416)

Introduces BEADS_DOLT_SHARED_SERVER mode where multiple beads projects
share a single Dolt server on a fixed port (3308), avoiding per-project
server sprawl. Includes `bd init --shared-server`, `bd dolt shared-*`
commands, doctor checks, and comprehensive tests.

Co-Authored-By: Shybko <shybko@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

cmd/bd/doctor/dolt.go

@@ -136,6 +136,7 @@ func RunDoltHealthChecksWithLock(path string, lockCheck DoctorCheck) []DoctorChe
 			{Name: "Dolt Status", Status: StatusOK, Message: "N/A (SQLite backend)", Category: CategoryData},
 			{Name: "Dolt Lock Health", Status: StatusOK, Message: "N/A (SQLite backend)", Category: CategoryRuntime},
 			{Name: "Phantom Databases", Status: StatusOK, Message: "N/A (SQLite backend)", Category: CategoryData},
+			{Name: "Shared Server", Status: StatusOK, Message: "N/A (SQLite backend)", Category: CategoryRuntime},
 		}
 	}
 
@@ -149,6 +150,7 @@ func RunDoltHealthChecksWithLock(path string, lockCheck DoctorCheck) []DoctorChe
 			{Name: "Dolt Status", Status: StatusError, Message: "Skipped (no connection)", Detail: connErr, Category: CategoryData},
 			lockCheck,
 			{Name: "Phantom Databases", Status: StatusError, Message: "Skipped (no connection)", Detail: connErr, Category: CategoryData},
+			checkSharedServerHealth(beadsDir),
 		}
 	}
 	defer conn.Close()
@@ -160,6 +162,7 @@ func RunDoltHealthChecksWithLock(path string, lockCheck DoctorCheck) []DoctorChe
 		checkStatusWithDB(conn),
 		lockCheck,
 		checkPhantomDatabases(conn),
+		checkSharedServerHealth(beadsDir),
 	}
 }
 
@@ -688,3 +691,63 @@ func probeForCorrectDatabase(conn *doltConn) string {
 
 	return ""
 }
+
+// checkSharedServerHealth verifies shared server configuration and health.
+func checkSharedServerHealth(beadsDir string) DoctorCheck {
+	if !doltserver.IsSharedServerMode() {
+		return DoctorCheck{
+			Name:     "Shared Server",
+			Status:   StatusOK,
+			Message:  "N/A (per-project mode)",
+			Category: CategoryRuntime,
+		}
+	}
+
+	sharedDir, err := doltserver.SharedServerDir()
+	if err != nil {
+		return DoctorCheck{
+			Name:     "Shared Server",
+			Status:   StatusError,
+			Message:  "Cannot access shared server directory",
+			Detail:   err.Error(),
+			Fix:      "Ensure ~/.beads/shared-server/ is writable",
+			Category: CategoryRuntime,
+		}
+	}
+
+	state, err := doltserver.IsRunning(sharedDir)
+	if err != nil {
+		return DoctorCheck{
+			Name:     "Shared Server",
+			Status:   StatusWarning,
+			Message:  "Cannot check shared server status",
+			Detail:   err.Error(),
+			Category: CategoryRuntime,
+		}
+	}
+
+	if state == nil || !state.Running {
+		return DoctorCheck{
+			Name:     "Shared Server",
+			Status:   StatusWarning,
+			Message:  "Shared server not running (will auto-start on next bd command)",
+			Detail:   fmt.Sprintf("Server directory: %s", sharedDir),
+			Fix:      "Run 'bd dolt start' to start the shared server",
+			Category: CategoryRuntime,
+		}
+	}
+
+	cfg, _ := configfile.Load(beadsDir)
+	dbName := configfile.DefaultDoltDatabase
+	if cfg != nil {
+		dbName = cfg.GetDoltDatabase()
+	}
+
+	return DoctorCheck{
+		Name:     "Shared Server",
+		Status:   StatusOK,
+		Message:  fmt.Sprintf("Running (PID %d, port %d), database: %s", state.PID, state.Port, dbName),
+		Detail:   fmt.Sprintf("Server directory: %s", sharedDir),
+		Category: CategoryRuntime,
+	}
+}

cmd/bd/doctor/dolt_test.go

@@ -33,8 +33,8 @@ func TestRunDoltHealthChecks_DoltBackendNoServer(t *testing.T) {
 	t.Setenv("BEADS_DOLT_SERVER_PORT", "59998")
 
 	checks := RunDoltHealthChecks(tmpDir)
-	if len(checks) != 6 {
-		t.Fatalf("expected exactly 6 checks (consistent shape), got %d", len(checks))
+	if len(checks) != 7 {
+		t.Fatalf("expected exactly 7 checks (consistent shape), got %d", len(checks))
 	}
 
 	if checks[0].Name != "Dolt Connection" {
@@ -45,7 +45,7 @@ func TestRunDoltHealthChecks_DoltBackendNoServer(t *testing.T) {
 	}
 
 	// Verify placeholder checks for dimensions that require a connection
-	expectedNames := []string{"Dolt Connection", "Dolt Schema", "Dolt Issue Count", "Dolt Status", "Dolt Lock Health", "Phantom Databases"}
+	expectedNames := []string{"Dolt Connection", "Dolt Schema", "Dolt Issue Count", "Dolt Status", "Dolt Lock Health", "Phantom Databases", "Shared Server"}
 	for i, name := range expectedNames {
 		if checks[i].Name != name {
 			t.Errorf("checks[%d].Name = %q, want %q", i, checks[i].Name, name)
@@ -103,8 +103,8 @@ func TestServerMode_NoLockAcquired(t *testing.T) {
 	t.Setenv("BEADS_DOLT_SERVER_PORT", "59999")
 
 	checks := RunDoltHealthChecks(tmpDir)
-	if len(checks) != 6 {
-		t.Fatalf("expected exactly 6 checks (consistent shape), got %d", len(checks))
+	if len(checks) != 7 {
+		t.Fatalf("expected exactly 7 checks, got %d", len(checks))
 	}
 
 	check := checks[0]

cmd/bd/dolt.go

@@ -281,6 +281,9 @@ required. Use this command for explicit control or diagnostics.`,
 		fmt.Printf("Dolt server started (PID %d, port %d)\n", state.PID, state.Port)
 		fmt.Printf("  Data: %s\n", state.DataDir)
 		fmt.Printf("  Logs: %s\n", doltserver.LogPath(serverDir))
+		if doltserver.IsSharedServerMode() {
+			fmt.Println("  Mode: shared server")
+		}
 	},
 }
 
@@ -345,6 +348,9 @@ Displays whether the server is running, its PID, port, and data directory.`,
 		fmt.Printf("  Port: %d\n", state.Port)
 		fmt.Printf("  Data: %s\n", state.DataDir)
 		fmt.Printf("  Logs: %s\n", doltserver.LogPath(serverDir))
+		if doltserver.IsSharedServerMode() {
+			fmt.Println("  Mode: shared server")
+		}
 	},
 }
 
@@ -887,6 +893,7 @@ func showDoltConfig(testConnection bool) {
 			result["host"] = showHost
 			result["port"] = showPort
 			result["user"] = cfg.GetDoltServerUser()
+			result["shared_server"] = doltserver.IsSharedServerMode()
 			if testConnection {
 				result["connection_ok"] = testServerConnection(showHost, showPort)
 			}
@@ -906,6 +913,14 @@ func showDoltConfig(testConnection bool) {
 	fmt.Printf("  Host:     %s\n", showHost)
 	fmt.Printf("  Port:     %d\n", showPort)
 	fmt.Printf("  User:     %s\n", cfg.GetDoltServerUser())
+	if doltserver.IsSharedServerMode() {
+		fmt.Println("  Mode:     shared server")
+		if sharedDir, err := doltserver.SharedServerDir(); err == nil {
+			fmt.Printf("  Server:   %s\n", sharedDir)
+		}
+	} else {
+		fmt.Println("  Mode:     per-project")
+	}
 
 	if testConnection {
 		fmt.Println()
@@ -1048,9 +1063,37 @@ func setDoltConfig(key, value string, updateConfig bool) {
 		}
 		yamlKey = "dolt.data-dir"
 
+	case "shared-server":
+		lower := strings.ToLower(value)
+		if lower != "true" && lower != "false" {
+			fmt.Fprintf(os.Stderr, "Error: shared-server must be 'true' or 'false'\n")
+			os.Exit(1)
+		}
+		// shared-server is yaml-only (not stored in metadata.json)
+		if err := config.SetYamlConfig("dolt.shared-server", lower); err != nil {
+			fmt.Fprintf(os.Stderr, "Error setting shared-server: %v\n", err)
+			os.Exit(1)
+		}
+		if jsonOutput {
+			outputJSON(map[string]interface{}{
+				"key":      "shared-server",
+				"value":    lower,
+				"location": "config.yaml",
+			})
+			return
+		}
+		if lower == "true" {
+			fmt.Println("Shared server mode enabled.")
+			fmt.Println("All projects will use a single Dolt server at ~/.beads/shared-server/.")
+			fmt.Println("Each project's data remains isolated in its own database.")
+		} else {
+			fmt.Println("Shared server mode disabled. Each project will use its own Dolt server.")
+		}
+		return
+
 	default:
 		fmt.Fprintf(os.Stderr, "Error: unknown key '%s'\n", key)
-		fmt.Fprintf(os.Stderr, "Valid keys: database, host, port, user, data-dir\n")
+		fmt.Fprintf(os.Stderr, "Valid keys: database, host, port, user, data-dir, shared-server\n")
 		os.Exit(1)
 	}
 

cmd/bd/init.go

@@ -64,6 +64,7 @@ environment variable.`,
 		serverUser, _ := cmd.Flags().GetString("server-user")
 		database, _ := cmd.Flags().GetString("database")
 		destroyToken, _ := cmd.Flags().GetString("destroy-token")
+		sharedServer, _ := cmd.Flags().GetBool("shared-server")
 
 		// Handle --backend flag: "dolt" is the only supported backend.
 		// "sqlite" is accepted for backward compatibility but prints a
@@ -91,6 +92,13 @@ environment variable.`,
 		// Dolt is the only supported backend
 		backend := configfile.BackendDolt
 
+		// Propagate --shared-server flag to env so that IsSharedServerMode(),
+		// ResolveDoltDir(), and DefaultConfig() all see shared mode immediately
+		// (before config.yaml exists). Safe: init runs once and exits.
+		if sharedServer {
+			_ = os.Setenv("BEADS_DOLT_SHARED_SERVER", "1")
+		}
+
 		// Initialize config (PersistentPreRun doesn't run for init command)
 		if err := config.Initialize(); err != nil {
 			fmt.Fprintf(os.Stderr, "Warning: failed to initialize config: %v\n", err)
@@ -278,6 +286,13 @@ environment variable.`,
 
 		useLocalBeads := filepath.Clean(initDBDirAbs) == filepath.Clean(beadsDirAbs)
 
+		// Shared server mode: dolt data lives in ~/.beads/shared-server/dolt/
+		// (a different path tree), but the project still needs its local .beads/
+		// for metadata.json, config.yaml, .gitignore, etc.
+		if doltserver.IsSharedServerMode() {
+			useLocalBeads = true
+		}
+
 		if useLocalBeads {
 			// Create .beads directory
 			if err := os.MkdirAll(beadsDir, 0750); err != nil {
@@ -558,6 +573,16 @@ environment variable.`,
 				// Non-fatal - continue anyway
 			}
 
+			// Enable shared server mode if requested via flag OR env var (GH#2377).
+			// Persist to config.yaml so the project continues working without the env var.
+			if sharedServer || doltserver.IsSharedServerMode() {
+				if err := config.SetYamlConfig("dolt.shared-server", "true"); err != nil {
+					fmt.Fprintf(os.Stderr, "Warning: failed to enable shared server mode: %v\n", err)
+				} else if !quiet {
+					fmt.Printf("  %s Shared server mode enabled\n", ui.RenderPass("✓"))
+				}
+			}
+
 			// In stealth mode, persist no-git-ops: true so bd prime
 			// automatically uses stealth session-close protocol (GH#2159)
 			if stealth {
@@ -889,6 +914,7 @@ func init() {
 	initCmd.Flags().Int("server-port", 0, "Dolt server port (default: 3307)")
 	initCmd.Flags().String("server-user", "", "Dolt server MySQL user (default: root)")
 	initCmd.Flags().String("database", "", "Use existing server database name (overrides prefix-based naming)")
+	initCmd.Flags().Bool("shared-server", false, "Enable shared Dolt server mode (all projects share one server at ~/.beads/shared-server/)")
 
 	rootCmd.AddCommand(initCmd)
 }

docs/ARCHITECTURE.md

@@ -165,8 +165,11 @@ Each workspace can run its own Dolt server for multi-writer access:
 
 **Server mode:**
 - Connects to `dolt sql-server` (multi-writer, high-concurrency)
-- PID file at `.beads/dolt/sql-server.pid`
-- Logs at `.beads/dolt/sql-server.log`
+- PID file at `.beads/dolt-server.pid`
+- Logs at `.beads/dolt-server.log`
+- **Shared server mode** (opt-in): all projects share a single Dolt server at
+  `~/.beads/shared-server/` instead of per-project servers. Enable via
+  `dolt.shared-server: true` in config.yaml or `BEADS_DOLT_SHARED_SERVER=1`.
 
 **Embedded mode:**
 - Direct database access (single-writer, no server process)

docs/CONFIG.md

@@ -47,6 +47,8 @@ Tool-level settings you can configure:
 | `backup.git-push` | - | `BD_BACKUP_GIT_PUSH` | `false` | Auto git-add + commit + push after export |
 | `dolt.auto-push` | - | `BD_DOLT_AUTO_PUSH` | (auto) | Auto-push to Dolt remote after writes (auto-enabled when origin exists) |
 | `dolt.auto-push-interval` | - | `BD_DOLT_AUTO_PUSH_INTERVAL` | `5m` | Minimum time between auto-pushes |
+| `dolt.shared-server` | `--shared-server` | `BEADS_DOLT_SHARED_SERVER` | `false` | Share a single Dolt server across all projects at `~/.beads/shared-server/` |
+| `dolt.idle-timeout` | - | - | `30m` | Idle auto-stop timeout (`"0"` disables) |
 | `db` | `--db` | `BD_DB` | (auto-discover) | Database path |
 | `actor` | `--actor` | `BD_ACTOR` | `git config user.name` | Actor name for audit trail (see below) |
 

docs/DOLT-BACKEND.md

@@ -77,6 +77,7 @@ dolt:
 | `BEADS_DOLT_SERVER_PORT` | `3306` | Server port (MySQL protocol) |
 | `BEADS_DOLT_SERVER_USER` | `root` | MySQL username |
 | `BEADS_DOLT_SERVER_PASS` | (empty) | MySQL password |
+| `BEADS_DOLT_SHARED_SERVER` | (empty) | Shared server mode: `1` or `true` to enable |
 
 ### Server Lifecycle
 
@@ -85,13 +86,32 @@ dolt:
 bd doctor
 
 # Server auto-starts when needed
-# PID stored in: .beads/dolt/sql-server.pid
-# Logs written to: .beads/dolt/sql-server.log
+# PID stored in: .beads/dolt-server.pid
+# Logs written to: .beads/dolt-server.log
 
-# Manual stop (rarely needed)
-kill $(cat .beads/dolt/sql-server.pid)
+# Start/stop/status
+bd dolt start
+bd dolt stop
+bd dolt status
 ```
 
+### Shared Server Mode
+
+On multi-project machines, enable shared server mode to use a single Dolt server
+for all projects (instead of one server per project):
+
+```bash
+# Enable via config
+bd dolt set shared-server true
+
+# Or via environment variable (machine-wide)
+export BEADS_DOLT_SHARED_SERVER=1
+```
+
+Shared server state lives in `~/.beads/shared-server/` and uses port 3308 by default
+(avoiding conflict with Gas Town on 3307). Each project's data remains isolated in its
+own database (named by project prefix). See [DOLT.md](DOLT.md) for details.
+
 ## Sync Modes
 
 Dolt supports multiple sync strategies: