fix: propagate BEADS_DOLT_SERVER_HOST so bd doesn't default to localhost

Adds GT_DOLT_HOST → BEADS_DOLT_SERVER_HOST translation everywhere gt
already propagates GT_DOLT_PORT → BEADS_DOLT_PORT. Without this, bd
subprocesses fall back to 127.0.0.1 when the Dolt server runs on a
remote machine (e.g., over Tailscale), causing recurring config drift.

Fixes #2827.

Co-Authored-By: Trillium Smith <[email protected]>
Co-Authored-By: Claude Opus 4.6 <[email protected]>

Author: 3 people

docs/design/dolt-storage.md

@@ -32,8 +32,26 @@ Dolt SQL Server (one per town, port 3307)
 **Data directory**: `~/gt/.dolt-data/` — each subdirectory is a database
 accessible via `USE <name>` in SQL.
 
-**Connection**: `root@tcp(127.0.0.1:3307)/<database>` (no password for
-localhost).
+**Connection**: `root@tcp(<host>:3307)/<database>` (no password).
+
+## Environment Variables
+
+gt and bd use separate env vars for Dolt connection. gt automatically
+translates its variables to bd's equivalents when spawning agents.
+
+| gt (Gas Town) | bd (Beads) | Purpose |
+|---------------|------------|---------|
+| `GT_DOLT_HOST` | `BEADS_DOLT_SERVER_HOST` | Server host (bd defaults to `127.0.0.1` if unset) |
+| `GT_DOLT_PORT` | `BEADS_DOLT_PORT` | Server port (default: `3307`) |
+
+**Remote Dolt servers**: If Dolt runs on a different machine (e.g., over
+Tailscale), set `GT_DOLT_HOST` in the environment. gt propagates this as
+`BEADS_DOLT_SERVER_HOST` to all bd subprocesses, overriding bd's hardcoded
+`127.0.0.1` default. Without this, every new rig/worktree/polecat silently
+connects to localhost and fails.
+
+Per-workspace override: set `dolt.host` in a rig's `.beads/config.yaml`.
+This takes priority over the env var for that specific workspace.
 
 ## Commands
 

internal/beads/beads.go

@@ -576,14 +576,15 @@ func (b *Beads) buildRoutingEnv() []string {
 // environment slice. This ensures test isolation by preventing inherited
 // BD_ACTOR, BEADS_DB, GT_ROOT, HOME etc. from routing commands to production databases.
 //
-// Preserves GT_DOLT_PORT and BEADS_DOLT_PORT so that isolated-mode tests can
-// reach a test Dolt server on a non-default port.
+// Preserves GT_DOLT_PORT, BEADS_DOLT_PORT, and BEADS_DOLT_SERVER_HOST so that
+// isolated-mode tests can reach a test Dolt server on a non-default port/host.
 func filterBeadsEnv(environ []string) []string {
 	filtered := make([]string, 0, len(environ))
 	for _, env := range environ {
-		// Preserve port env vars needed to reach test Dolt servers.
+		// Preserve Dolt connection env vars needed to reach test/remote Dolt servers.
 		// These must be checked before the broad BEADS_ prefix strip below.
 		if strings.HasPrefix(env, "BEADS_DOLT_PORT=") ||
+			strings.HasPrefix(env, "BEADS_DOLT_SERVER_HOST=") ||
 			strings.HasPrefix(env, "GT_DOLT_PORT=") {
 			filtered = append(filtered, env)
 			continue
@@ -603,24 +604,34 @@ func filterBeadsEnv(environ []string) []string {
 	return filtered
 }
 
-// translateDoltPort ensures BEADS_DOLT_PORT is set when GT_DOLT_PORT is present.
-// Gas Town uses GT_DOLT_PORT; beads uses BEADS_DOLT_PORT. This translation
-// prevents bd subprocesses from falling back to metadata.json's port 3307
-// (production) when a test or daemon has set GT_DOLT_PORT to an alternate port.
+// translateDoltPort ensures BEADS_DOLT_PORT and BEADS_DOLT_SERVER_HOST are set
+// when their GT_ counterparts are present. Gas Town uses GT_DOLT_PORT and
+// GT_DOLT_HOST; beads uses BEADS_DOLT_PORT and BEADS_DOLT_SERVER_HOST. This
+// translation prevents bd subprocesses from falling back to localhost:3307
+// when a test or daemon has set GT_DOLT_* to alternate values.
 func translateDoltPort(env []string) []string {
-	var gtPort string
-	hasBDP := false
+	var gtPort, gtHost string
+	hasBDP, hasBDH := false, false
 	for _, e := range env {
 		if strings.HasPrefix(e, "GT_DOLT_PORT=") {
 			gtPort = strings.TrimPrefix(e, "GT_DOLT_PORT=")
 		}
+		if strings.HasPrefix(e, "GT_DOLT_HOST=") {
+			gtHost = strings.TrimPrefix(e, "GT_DOLT_HOST=")
+		}
 		if strings.HasPrefix(e, "BEADS_DOLT_PORT=") {
 			hasBDP = true
 		}
+		if strings.HasPrefix(e, "BEADS_DOLT_SERVER_HOST=") {
+			hasBDH = true
+		}
 	}
 	if gtPort != "" && !hasBDP {
 		env = append(env, "BEADS_DOLT_PORT="+gtPort)
 	}
+	if gtHost != "" && !hasBDH {
+		env = append(env, "BEADS_DOLT_SERVER_HOST="+gtHost)
+	}
 	return env
 }
 

internal/cmd/dashboard.go

@@ -153,11 +153,11 @@ func runDashboard(cmd *cobra.Command, args []string) error {
 	return server.ListenAndServe()
 }
 
-// ensureDoltPortEnv sets GT_DOLT_PORT and BEADS_DOLT_PORT to the actual Dolt
-// SQL server port. This prevents bd subprocesses from inheriting a stale or
-// incorrect port (e.g., the dashboard's HTTP listen port) from the environment.
-// Reads the running port from daemon/dolt-state.json; falls back to the
-// daemon.json env config; otherwise uses the Dolt default (3307).
+// ensureDoltPortEnv sets GT_DOLT_PORT, BEADS_DOLT_PORT, and BEADS_DOLT_SERVER_HOST
+// to the actual Dolt server connection info. This prevents bd subprocesses from
+// inheriting stale or incorrect values from the environment.
+// Reads the running state from daemon/dolt-state.json; falls back to
+// doltserver.DefaultConfig; otherwise uses the Dolt defaults.
 func ensureDoltPortEnv(townRoot string) {
 	var port int
 	if state, err := doltserver.LoadState(townRoot); err == nil && state.Port > 0 {
@@ -168,6 +168,12 @@ func ensureDoltPortEnv(townRoot string) {
 	portStr := strconv.Itoa(port)
 	os.Setenv("GT_DOLT_PORT", portStr)
 	os.Setenv("BEADS_DOLT_PORT", portStr)
+
+	// Propagate host so bd doesn't fall back to 127.0.0.1.
+	doltCfg := doltserver.DefaultConfig(townRoot)
+	if doltCfg.Host != "" {
+		os.Setenv("BEADS_DOLT_SERVER_HOST", doltCfg.Host)
+	}
 }
 
 // openBrowser opens the specified URL in the default browser.

internal/cmd/up.go

@@ -311,13 +311,18 @@ func runUp(cmd *cobra.Command, args []string) error {
 	// was skipped, polling the port would just burn the full timeout. (review finding #1)
 	if !doltSkipped && doltOK {
 		waitForDoltReady(townRoot)
-		// Propagate Dolt port to process env so all subsequently spawned
+		// Propagate Dolt connection info to process env so all subsequently spawned
 		// agents (witnesses, refineries, crew) inherit it. Without this,
 		// bd auto-starts rogue Dolt instances in agent tmux sessions. (GH#2412)
+		// Host propagation prevents bd from falling back to 127.0.0.1 when the
+		// Dolt server runs on a remote machine (e.g., mini2 over Tailscale).
 		doltCfg := doltserver.DefaultConfig(townRoot)
 		portStr := fmt.Sprintf("%d", doltCfg.Port)
 		os.Setenv("GT_DOLT_PORT", portStr)
 		os.Setenv("BEADS_DOLT_PORT", portStr)
+		if doltCfg.Host != "" {
+			os.Setenv("BEADS_DOLT_SERVER_HOST", doltCfg.Host)
+		}
 	}
 
 	// 5 & 6. Witnesses and Refineries (using prefetched rigs)

internal/config/env.go

@@ -309,6 +309,16 @@ func AgentEnv(cfg AgentEnvConfig) map[string]string {
 		env["BEADS_DOLT_AUTO_START"] = "0"
 	}
 
+	// Propagate Dolt server host so bd doesn't fall back to 127.0.0.1 when
+	// the server runs on a remote machine (e.g., mini2 over Tailscale).
+	if _, ok := env["BEADS_DOLT_SERVER_HOST"]; !ok {
+		if v := os.Getenv("BEADS_DOLT_SERVER_HOST"); v != "" {
+			env["BEADS_DOLT_SERVER_HOST"] = v
+		} else if v := os.Getenv("GT_DOLT_HOST"); v != "" {
+			env["BEADS_DOLT_SERVER_HOST"] = v
+		}
+	}
+
 	// Pass through cloud API credentials and provider configuration from the parent shell.
 	// Only variables explicitly listed here are forwarded; all others are blocked for isolation.
 	for _, key := range []string{

internal/daemon/daemon.go

@@ -175,12 +175,16 @@ func New(config *Config) (*Daemon, error) {
 		doltServer = NewDoltServerManager(config.TownRoot, patrolConfig.Patrols.DoltServer, logger.Printf)
 		if doltServer.IsEnabled() {
 			logger.Printf("Dolt server management enabled (port %d)", patrolConfig.Patrols.DoltServer.Port)
-			// Propagate Dolt port to process env so AgentEnv() passes it to
+			// Propagate Dolt connection info to process env so AgentEnv() passes it to
 			// all spawned agent sessions. Without this, bd in agent sessions
-			// auto-starts rogue Dolt instances. (GH#2412)
+			// auto-starts rogue Dolt instances or connects to localhost. (GH#2412)
 			portStr := strconv.Itoa(patrolConfig.Patrols.DoltServer.Port)
 			os.Setenv("GT_DOLT_PORT", portStr)
 			os.Setenv("BEADS_DOLT_PORT", portStr)
+			if patrolConfig.Patrols.DoltServer.Host != "" {
+				os.Setenv("GT_DOLT_HOST", patrolConfig.Patrols.DoltServer.Host)
+				os.Setenv("BEADS_DOLT_SERVER_HOST", patrolConfig.Patrols.DoltServer.Host)
+			}
 		}
 	}
 
@@ -197,6 +201,16 @@ func New(config *Config) (*Daemon, error) {
 		}
 	}
 
+	// Propagate Dolt host to process env so bd doesn't fall back to 127.0.0.1
+	// when the server runs on a remote machine (e.g., mini2 over Tailscale).
+	if os.Getenv("BEADS_DOLT_SERVER_HOST") == "" {
+		doltCfg := doltserver.DefaultConfig(config.TownRoot)
+		if doltCfg.Host != "" {
+			os.Setenv("BEADS_DOLT_SERVER_HOST", doltCfg.Host)
+			logger.Printf("Set BEADS_DOLT_SERVER_HOST=%s from Dolt config", doltCfg.Host)
+		}
+	}
+
 	// PATCH-006: Resolve binary paths at startup.
 	gtPath, err := exec.LookPath("gt")
 	if err != nil {

internal/rig/manager.go

@@ -912,22 +912,31 @@ func (m *Manager) InitBeads(rigPath, prefix, rigName string) error {
 	}
 	filteredEnv = append(filteredEnv, "BEADS_DIR="+beadsDir)
 
-	// Ensure BEADS_DOLT_PORT is set when GT_DOLT_PORT is present, so that
-	// bd subprocesses connect to the correct Dolt server (especially in tests
-	// where an ephemeral server runs on a non-default port).
-	var gtDoltPort string
-	hasBDP := false
+	// Ensure BEADS_DOLT_PORT and BEADS_DOLT_SERVER_HOST are set when their GT_
+	// counterparts are present, so that bd subprocesses connect to the correct
+	// Dolt server (especially in tests or when the server is remote).
+	var gtDoltPort, gtDoltHost string
+	hasBDP, hasBDH := false, false
 	for _, e := range filteredEnv {
 		if strings.HasPrefix(e, "GT_DOLT_PORT=") {
 			gtDoltPort = strings.TrimPrefix(e, "GT_DOLT_PORT=")
 		}
+		if strings.HasPrefix(e, "GT_DOLT_HOST=") {
+			gtDoltHost = strings.TrimPrefix(e, "GT_DOLT_HOST=")
+		}
 		if strings.HasPrefix(e, "BEADS_DOLT_PORT=") {
 			hasBDP = true
 		}
+		if strings.HasPrefix(e, "BEADS_DOLT_SERVER_HOST=") {
+			hasBDH = true
+		}
 	}
 	if gtDoltPort != "" && !hasBDP {
 		filteredEnv = append(filteredEnv, "BEADS_DOLT_PORT="+gtDoltPort)
 	}
+	if gtDoltHost != "" && !hasBDH {
+		filteredEnv = append(filteredEnv, "BEADS_DOLT_SERVER_HOST="+gtDoltHost)
+	}
 
 	// Run bd init if available (Dolt is the only backend since bd v0.51.0).
 	// --server tells bd to set dolt_mode=server in metadata.json so bd

internal/testutil/cmd.go

@@ -7,17 +7,19 @@ import (
 )
 
 // CleanGTEnv returns os.Environ() with GT_* and BD_* variables removed, except
-// GT_DOLT_PORT which is preserved so subprocesses connect to the ephemeral test
-// Dolt server instead of production on port 3307. BEADS_DOLT_PORT (prefix
-// BEADS_, not BD_) passes through implicitly since only BD_* is stripped.
+// GT_DOLT_PORT and GT_DOLT_HOST which are preserved so subprocesses connect to
+// the correct Dolt server. BEADS_DOLT_PORT and BEADS_DOLT_SERVER_HOST (prefix
+// BEADS_, not BD_) pass through implicitly since only BD_* is stripped.
 //
 // Use this when setting cmd.Env on bd/gt subprocess calls in tests.
 // If you do NOT set cmd.Env, the process env (including GT_DOLT_PORT) is
 // inherited automatically — no need for this function in that case.
 func CleanGTEnv(extraEnv ...string) []string {
 	var clean []string
 	for _, e := range os.Environ() {
-		if strings.HasPrefix(e, "GT_") && !strings.HasPrefix(e, "GT_DOLT_PORT=") {
+		if strings.HasPrefix(e, "GT_") &&
+			!strings.HasPrefix(e, "GT_DOLT_PORT=") &&
+			!strings.HasPrefix(e, "GT_DOLT_HOST=") {
 			continue
 		}
 		if strings.HasPrefix(e, "BD_") {