feat(workspace): remote shared backend — run the shared stack on a remote Docker host (spec 21)

[gustavobertoi]

What & why

Generalizes the shared stack (spec 21) so it can run on a remote Docker host — an SSH/TCP docker context or a DOCKER_HOST endpoint — instead of only the local daemon. The ref-counting, provisioning, and DNS/alias model are backend-agnostic; this only swaps where the containers run and how host-side consumers reach them. The local backend is the default and byte-for-byte unchanged.

Delivered (tested core)

1. Config selector — a workspace backend: block (context: or host:), plus a machine-global default on the store config.yaml. Validated: a dockerhost scheme rule (ssh|tcp|unix|npipe|fd://) and a cross-field check that context and host are mutually exclusive. nil = local. (internal/config, internal/store)
2. Docker seam — docker.Backend (ComposeEnv/Reachability/NewClient/RemoteReachable). The local backend is the zero value and defers to the existing NewClient (so context-name resolution / ledger keying is unchanged). A remote backend binds moby to the resolved endpoint (WithHost + version negotiation; a docker context endpoint is resolved via docker context inspect) and keys the ledger by the context name / host, so remote rows never bleed into the local counts — exactly like the WSL2 Desktop-vs-dockerd split. Compose gains ContextEnv, appended after the resolved-secret Env, pinning every compose verb to the endpoint via DOCKER_HOST/DOCKER_CONTEXT (never written to disk).
3. Wiring — cli/up.go buildUpDeps resolves the backend, builds the read-only client from it, keys state.Open by the backend context, and threads it through UpDeps.Backend into the shared-phase, project, and down composes. doctor targets the selected endpoint too.
4. Reachability — a remote bridge is not host-routable, so no loopback provision port is published; host-side Postgres provisioning over a remote backend is guarded with a clear, actionable error (re-run with --no-provision, or provision from the remote host). Remote up of the non-provisioned shared stack (redis/minio, or postgres with no host-provisioned consumer) works.
5. doctor — a backend.remote reachability probe (Ping + ServerVersion) with a remediation; only emitted for a remote backend (the local daemon is already covered by the existing preflight).

Scoped out (flagged follow-ups — this is a frontier spec)

• Distributed lock — the local flock cannot serialize two developers on two machines against the same remote ledger. The DistLock (recommended: a Postgres advisory lock on the cluster DB) is not implemented; this pass is the single-user, local-flock, all-remote-topology sketch the spec calls ~3–4w.
• Per-user tenant isolation on a shared cluster (u_<user>_<project> roles, REVOKE … FROM PUBLIC, a tenant ledger column).
• Host-side provisioning over remote — needs an SSH local-forward/tunnel; guarded with an error rather than silently publishing an unreachable port.
• Remote-authoritative ledger (local SQLite degrading to a cache).

These are documented in code doc-comments (internal/docker/backend.go) and gate on a daemon decision (Q-DAEMON).

How tested

mock docker.Client + a fake compose runner, no real remote:

• internal/docker — IsRemote/Reachability/ComposeEnv/String; ContextEnv threads through the runner after secrets; local adds nothing; RemoteReachable ok/fail/nil-client.
• internal/config — backend default-local, context, host, bad scheme, mutual exclusion, valid schemes.
• internal/orchestrate — remote up pins every compose verb (shared + project) to DOCKER_CONTEXT; local leaks no backend env; the remote host-provision guard fails the shared phase with an actionable message.
• internal/cli — the doctor backend.remote probe (reachable / unreachable / local-absent).

CGO_ENABLED=0 go build ./..., CGO_ENABLED=1 go test ./internal/..., gofmt -l (clean), go vet ./..., and a darwin/arm64 cross-build all pass. No new dependencies.

🤖 Generated with Claude Code