CLI-path commands fail in shared Dolt server mode (`push`/`pull`/`remote`)

[s-a-c]

Problem

Several bd dolt subcommands shell out to the raw dolt CLI and assume the repo directory is at .beads/dolt/<database> relative to the project root. In shared-server mode, the actual data lives at a shared root (e.g. ~/.local/share/beads-dolt/<database>).

Command	Behavior	Impact
bd dolt push	Works only if a symlink exists at .beads/dolt/<db> -> shared root	Fragile dependency on manual symlink
bd dolt pull	Fails with "database is read only" — CLI opens repo directly, conflicting with running server lock	Broken in server mode regardless of symlink
bd dolt remote add	SQL path succeeds, CLI path fails → state divergence	Partially broken
bd dolt remote remove	Same dual-path divergence as remote add	Partially broken

Root cause

When Beads shells out to dolt push, dolt pull, or dolt remote, it constructs the working directory as .beads/dolt/<database>. This path:

1. Does not exist by default in shared-server mode (requires a manual symlink to work)
2. Even if it resolves via symlink, opening the Dolt repo directory directly conflicts with the running server's lock on that same directory (this is why pull fails)

Expected behavior

When dolt_mode: server, CLI-fallback commands should:

1. Resolve the repo path from explicit configuration (shared data root + database name), not from the per-project .beads/dolt/ convention
2. For operations that conflict with a running server (like pull), either:
   • Route through SQL instead of CLI
   • Coordinate with the server (stop/start around the operation)
   • Fail with a clear error explaining the server-lock conflict

Path resolution order

1. Explicit configured data-dir from metadata or config
2. dolt_server_host + dolt_database from metadata (derive shared root)
3. Legacy per-project .beads/dolt/<database> fallback only if no server config exists

Environment

• beads v1.0.0 (Homebrew)
• macOS, Dolt SQL server managed by launchctl on 127.0.0.1:3307
• .beads/metadata.json with dolt_mode: server
• Shared data root: ~/.local/share/beads-dolt

Workaround

Create a per-project symlink: .beads/dolt/<db> -> ~/.local/share/beads-dolt/<db>. This fixes push but pull remains broken due to the server lock conflict.

Related

• External Dolt server not recognized by bd dolt status / bd dolt show in server mode #3218 (external server recognition for bd dolt status/bd dolt show)

[s-a-c]

I dug this further in a disposable upstream clone and there are really two separate decisions hiding inside Patch Package B.

1. Generic external-server mode still needs a maintainer decision about the authoritative source for server-mode CLI repo paths.

   • DoltStore now clearly carries both dbPath and beadsDir, and helpers like doltserver.ResolveDoltDir(beadsDir) exist.
   • But the existing external-server integration test demonstrates that a client-side store can point at one local CLI directory while the live server is rooted somewhere else entirely.
   • So a naive global change like “always replace CLIDir() with ResolveDoltDir(beadsDir) in server mode” would be unsafe.

2. Shared-server mode is different and can be improved independently.

   • In shared-server mode, the local machine does have an authoritative shared Dolt root via doltserver.ResolveDoltDir(beadsDir) / SharedDoltDir().
   • I prototyped a shared-server-only CLIDir() change that uses the shared Dolt root only when serverMode and IsSharedServerMode() are both true, and leaves generic external-server mode untouched.
   • Focused tests passed for that narrower change.

My recommendation would be:

• Short term: consider accepting a shared-server-only CLIDir() fix as a scoped improvement for the workflow that is already explicit and locally authoritative.
• Separately: decide what the source of truth should be for generic external-server CLI repo paths (env-only, local-only config, shared-server-only support, or no CLI path support at all in that mode).

I also prototyped the following explicit-failure improvements while investigating this:

• bd dolt pull now fails clearly when CLI pull would be unsafe against a live dolt sql-server
• bd dolt push now fails clearly when CLI routing is required but the local CLI remote surface is unavailable

So the remaining architectural question is narrower now: it is mostly about whether maintainers want to support automatic CLI path resolution beyond shared-server mode.

[s-a-c]

I pushed the shared-server prototype a bit further in a disposable upstream clone.

New evidence:

• I added a workflow-style integration test: TestCredentialCLIRoutingE2ESharedServer
• The test starts a real dolt sql-server from the shared Dolt root, leaves the per-project .beads/dolt/testdb path intentionally stale (no remote configured), and verifies that:
  • CLIDir() resolves to the shared Dolt root in shared-server mode
  • credential-based routing discovers the remote on the shared CLI surface
  • CreateIssue + Commit + Push succeed through the store API
  • a fresh clone sees the pushed issue

That is a stronger proof than the earlier unit-style slices because it exercises a real write + commit + push + clone workflow, not just path/guard logic.

Fresh verification run:

CGO_ENABLED=0 go test -count=1 -tags integration ./internal/storage/dolt -run 'TestCredentialCLIRoutingE2ESharedServer|TestCredentialCLIRoutingE2E|TestGitRemoteExternalServerRouting'

Result:

ok github.com/steveyegge/beads/internal/storage/dolt 10.726s

So at this point the shared-server-only CLIDir() direction has three layers of evidence behind it:

1. direct path resolution tests
2. routing-guard tests
3. end-to-end shared-server push workflow test

That narrows the remaining design question even more: the hard unresolved part is still generic external-server path authority, not shared-server mode.

My recommendation is still the same, but with more confidence now: shared-server-only support looks ready to stand on its own as a scoped improvement if you want to take that smaller step first.

[s-a-c]

Opened a scoped follow-up PR for the shared-server-only slice:

• PR: fix(dolt): resolve shared-server CLI dir from shared root #3223
• URL: fix(dolt): resolve shared-server CLI dir from shared root #3223

This is the narrow version discussed above: shared-server-only CLIDir() resolution plus direct, routing, and workflow-level coverage. It intentionally leaves the broader external-server path-authority question out of scope.