Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

docs: the harness-grid plan, and the model-mesh one it supersedes

bitcoinbuilder0501c4195fb2
diff --git a/desktop/README.md b/desktop/README.md
index 88c297122..6daa3f593 100644
--- a/desktop/README.md
+++ b/desktop/README.md
@@ -6,8 +6,8 @@ and Linux (Ubuntu)** and includes an unexercised Windows runner.
## Development
-Install a compatible Flutter SDK, then run the project from this repository
-root:
+Install a compatible Flutter SDK, then run the project from this directory
+(`desktop/` in the monorepo):
```bash
flutter pub get
@@ -57,7 +57,7 @@ The optional A/B smoke test uses isolated identities, two loopback WebSockets,
the CLI's real E2EE handshake/media reader and ffmpeg-generated PNG/MP4 fixtures:
```bash
-REMOTE_MEDIA_CLI_ROOT=../autonomous-harness/cli flutter test test/remote_media_smoke_test.dart
+REMOTE_MEDIA_CLI_ROOT=../cli flutter test test/remote_media_smoke_test.dart
```
Install the companion CLI's npm dependencies first; ffmpeg must be on PATH.
diff --git a/docs/plans/2026-09-11-003-model-mesh-plan.md b/docs/plans/2026-09-11-003-model-mesh-plan.md
new file mode 100644
index 000000000..25ecff546
--- /dev/null
+++ b/docs/plans/2026-09-11-003-model-mesh-plan.md
@@ -0,0 +1,510 @@
+# Model mesh: an agent on one machine, its model on another
+
+Status: **SUPERSEDED** by `2026-09-14-004-harness-grid-plan.md` — this plan assumed grid was being deleted and that the harness had to carry inference itself. Grid stays; it already provides serving, the model catalogue and both dialects. Kept for the relay/E2EE analysis only.
+
+## Context
+
+```
+A — desktop, 1 opencode + 1 claude C — full harness machine: deepseek v4 flash,
+B — 1 codex agent, inference served by C and its own agents
+```
+
+The stated flow is four relay hops. Two corrections shape the design:
+
+1. **Hops 1 and 4 already exist and are not touched.** `prompt (A) → codex (B)` is the existing
+ `message` down-frame (`backendSocket.ts:1021` `dispatchDown` → `sessionInput` → tmux).
+ `codex (B) → answer (A)` is the existing transcript plane — codex writes JSONL, the watcher tails
+ it, `normalize` produces ServerEvents, `backend.send()` publishes `up:{machineId}`
+ (`backendSocket.ts:672`).
+
+2. **Hops 2 and 3 are not one round trip — they are N.** A coding agent does 10–50 model round trips
+ per prompt (tool call → read file → tool result → next completion). The B↔C leg is therefore the
+ hot path, carries the largest payloads in the product (full context on every request), and is the
+ only thing between "works" and "unusably slow".
+
+The build is exactly one new leg: **B ↔ C, carrying inference.**
+
+### Grid is being deleted, and it was carrying the launch layer
+
+This plan must not depend on `gridLaunch.ts`, `gridAssignment.ts`, `gridCredentials.ts`,
+`gridWebMcp.ts`, `gridConfigDir.ts`, `gridHandoff.ts`, or the `payload.grid` frame contract. That is a
+real cost, not a rename: grid owned the one thing this feature needs most — **the per-engine table of
+how a vendor lets you move its endpoint.** That table has to be re-derived and re-owned (Change 1),
+and it roughly doubles the CLI-side work versus reusing it.
+
+**Sequencing constraint, and it is the sharpest one in this plan: land Change 1 while grid still
+exists.** Grid's table is the only working reference for these contracts in the tree. Re-deriving
+each entry from vendor documentation is the correct method regardless, but doing it while a
+known-good implementation is still present means every entry can be differentially tested against it.
+After deletion there is no oracle, and a wrong entry fails *inside the vendor's binary* with an error
+naming neither the harness nor the endpoint — the exact failure mode `gridLaunch.ts:20-38` was
+written to prevent.
+
+### What survives grid's removal and is genuinely reusable
+
+Every one of these is generic plumbing that grid happened to be the only caller of:
+
+| Piece | Where | What it gives us |
+|---|---|---|
+| Pane env injection | `createAgentPane.ts:40` `env`, → tmux `new-session -e` | Set arbitrary env for a new agent's pane |
+| Launch argv + env clearing | `engineLaunch.ts:41` `extraArgs`, `:74` `clearEnv` | Codex's `-c` argv; removing inherited vendor creds. **Mesh becomes `clearEnv`'s new caller** — grid is its only one today |
+| Live process env read | `processEnv.ts` `readProcessEnv` | Read-back: what endpoint is this pane actually on |
+| Retarget | `restartAgent.ts`, `respawn-pane -k -e` | Move a running agent, keep pane + scrollback |
+| Machine→machine client | `remoteRelay.ts:171` `RemoteRelayPool`, `:212` `acquire()` | A daemon dialing `/api/web-ws` **as a client** toward a peer, terminating E2EE itself |
+| Machine→machine trust | `e2ee/machinePeers.ts` | Pinned Ed25519 peer, via `harness remote-password set` + `harness link connect` |
+| HTTP-over-WS streaming | `appTunnel.ts`, `tunnel.ts:74-110` | The streaming-HTTP-over-a-socket shape, already proven for SSE |
+| Binary lane + P2P | `terminalBinary.ts`, `terminalP2p.ts`, `remoteRelay.ts:511` | Per-`streamId` transport that already migrates to WebRTC and demotes back |
+| Loopback HTTP + credential | `hookServer.ts:328,654`, `hookAuth.ts` | 127.0.0.1 server, 0600 minted token, uid/mode/`O_NOFOLLOW` checked |
+
+### The repo became a monorepo after this plan was written
+
+`desktop/` (the Flutter client) and `device/esp32-circle/` (the dial firmware) now live in this tree.
+Three consequences, one of which reduces scope:
+
+**Changes 5 and 7 become atomic cross-stack commits.** The `payload.model` frame contract and the
+`machine_link_connect` UI used to span two repositories and therefore two PRs with a compatibility
+window between them. They are now one commit, testable end to end before merge. Add `desktop/lib/`
+to those changes' touch lists.
+
+**The Dart binary mirror does NOT need the model kinds.** `desktop/lib/terminal/terminal_binary.dart`
+mirrors `cli/src/lib/terminalBinary.ts` and carries explicit "keep the two in step" comments, so a
+reader adding `modelBody = 8` / `modelChunk = 9` will reasonably wonder whether to mirror them.
+**Do not.** Those kinds travel B-daemon ↔ C-daemon only; no model frame ever reaches the app, whose
+lane is the separate `terminalLocal*` framing over loopback. `fromCode` already answers null for an
+unknown code and drops, so the app stays correct with no change. Say this in the commit, or someone
+will mirror them "for consistency" and add two kinds the app can never receive.
+
+**Watch the `Grid` name collision when grid is deleted.** `Grid` in `desktop/lib/` is the **design
+system** ported from the Grid app — `_GridTokenScope` and its tokens (`main.dart:129-140`), plus
+several widgets documented as "ported from Grid". It has nothing to do with the inference grid this
+plan is dropping. A grep-driven deletion will happily take the app's theming with it.
+
+**Scope reduction: `agentFrame`'s `grid` field has no consumer left.** The app-v2 desktop parses
+`agentId`, `machineId`, `name`, `machine`, `recent`, `engine`, `confidence` (`desktop/lib/core/models.dart:359-366`)
+— and no `grid`. The field at `agentFrame.ts:45`, and the reconciliation bug its doc comment
+describes, belong to the pre-v2 client. So Change 5 should **delete** that field with grid rather
+than rename it to `mesh`, and add `mesh` only when there is UI that reads it. `meshAssignment.ts`
+read-back is net-new display, not a replacement for something working today — which means it can be
+deferred out of the first shippable phase if the schedule needs it.
+
+## Design principles
+
+**1. The harness tunnels bytes; it does not serve models, and it does not translate dialects.**
+C is not asked to become an inference server — it is asked to expose something already serving models
+on its loopback (ollama, vllm, llama.cpp, LM Studio). A dialect mismatch is **refused at launch with
+a named error**, never bridged. See "Not in scope".
+
+**2. Read the truth off the process; never bookkeep it.** Which model host an agent is on is read
+from its live environment, the way `gatewayRuntime.ts` reads which endpoint a pane talks to. A
+daemon restart forgets nothing, and an agent the user started themselves in their own shell reports
+the truth rather than "none".
+
+**3. Refusing loudly beats starting wrong.** Every precondition is checked before the pane spawns,
+with a code specific to what failed — not discovered when the first completion errors inside the
+vendor's binary.
+
+## Architecture
+
+```
+A (desktop)
+ │ agent_create { engine:'codex', model:{ hostMachineId:'C', model:'deepseek-v4-flash' } }
+ ▼
+relay ──▶ B daemon
+ │ modelEndpoint: OPENAI_BASE_URL=http://127.0.0.1:18474/mesh/C/v1
+ │ OPENAI_API_KEY=<minted per agent> + clearEnv vendor creds
+ ▼
+ codex process ──HTTP POST /v1/chat/completions (stream)──┐
+ ▼
+ B daemon: ModelGateway (loopback HTTP)
+ │ model_open + binary body chunks
+ │ over RemoteRelayPool.acquire(C)
+ ▼
+ relay (opaque ciphertext, rate-guarded)
+ ▼
+ C daemon: ModelHost
+ │ HTTP → 127.0.0.1:11434
+ ▼
+ deepseek v4 flash
+ │ SSE tokens
+ ▼
+ model_head + chunk frames ──▶ B's still-open response
+ │
+ codex writes its JSONL
+ ▼
+ watcher → normalize → up:{B} → A ← existing, untouched
+```
+
+**C is a full harness machine** (decided): it runs its own agents alongside serving models. Two
+consequences: there is no `--models-only` mode to build, and C's own agents compete with B for the
+same GPU — so the concurrency cap in Change 2 is a real scheduling decision, not a formality.
+
+**Loopback short-circuit.** An agent *on C* pointed at C's own model must not leave the machine. When
+`hostMachineId === own machineId`, the gateway proxies straight to the local backend and never
+touches `RemoteRelayPool`. Same URL shape, same token check, no relay, no E2EE session. This is the
+common case on a single GPU box and it must not pay for the network.
+
+---
+
+## Change 1 — own the engine endpoint contract
+
+New: `cli/src/lib/model-mesh/modelEndpoint.ts`. **Land this first, while grid still exists.**
+
+One table: *given engine E, a base URL, a key and a model, how does the vendor let you point it
+there?* Every entry cites the vendor documentation it was read from, and is proven by a recorded
+session from the real binary — the standard `cli/src/engines/README.md` already sets for engine
+contributions. Do not copy grid's implementation; re-derive, then differentially test against grid
+while it is still in the tree.
+
+**v1 covers the three engines in the worked example** — the two on A and the one on B:
+
+| Engine | Mechanism | Dialect it will speak to C |
+|---|---|---|
+| `codex` | `-c model_providers.*` argv + `env_key` indirection (key never in argv) | OpenAI |
+| `claude` | `ANTHROPIC_BASE_URL` + `ANTHROPIC_MODEL` | Anthropic |
+| `opencode` | private `opencode.json` via `OPENCODE_CONFIG` — the user's own `~/.config/opencode` is never touched | OpenAI |
+
+Every other engine is **refused** with `MESH_ENGINE_UNSUPPORTED` and a reason specific to it. Adding
+one later is a self-contained contribution: one table entry, one citation, one fixture.
+
+Also in this module, because they are the same knowledge:
+
+- `conflictingEnvToClear(launch)` — the vendor credentials a mesh launch must remove so the engine
+ cannot silently fall back to its own login. Computed from what the launch itself sets. Feeds
+ `engineLaunch.ts`'s existing `clearEnv`, which exists precisely for this and can only be done in
+ the launch script (tmux `new-session -e` can set a variable, never remove one).
+- `MESH_URL_RE` — the loopback route pattern, so Change 4's read-back and this writer cannot drift.
+
+> Note on claude: it speaks Anthropic Messages and ollama serves OpenAI only, so `claude → C` works
+> only if C runs a backend serving the Anthropic dialect. That is not a gap to paper over — it is
+> exactly the refusal `MESH_DIALECT_UNSUPPORTED` exists for, checked in Change 4's pre-flight.
+
+---
+
+## Change 2 — C: the model host
+
+New: `cli/src/lib/model-mesh/host.ts`, `backends.ts`.
+
+**Backend discovery, not configuration** (principle 2). Probe known local servers on their documented
+default ports and model-list endpoints; each entry cites its source:
+
+| Backend | Probe | Dialect |
+|---|---|---|
+| ollama | `GET 127.0.0.1:11434/api/tags` | OpenAI (`/v1`) |
+| vllm | `GET 127.0.0.1:8000/v1/models` | OpenAI |
+| llama.cpp server | `GET 127.0.0.1:8080/v1/models` | OpenAI |
+| LM Studio | `GET 127.0.0.1:1234/v1/models` | OpenAI |
+
+An unprobeable backend is absent, not an error — a machine hosting nothing pays nothing, the same
+rule `CONTRIBUTING.md` sets for multiplexers. `ADAPTER_MODEL_BACKENDS` overrides for a non-default
+port, parsed the way `config/terminalConfig.ts` parses its backends list.
+
+**Serving is opt-in and off by default.** Ownership and a peer link are not consent to spend a GPU —
+especially now that C runs its own agents on it. State in
+`${ADAPTER_DATA_DIR}/model-mesh/serve.json` (0600, `secureState.ts` conventions):
+
+```
+harness models serve --allow <machineId> # or --all-linked
+harness models serve --off
+harness models list # what this machine serves, and to whom
+```
+
+An unlisted requester gets `MESH_NOT_SERVING` — never a silent hang.
+
+**Concurrency cap.** `maxConcurrent` in `serve.json`, default 1. C's own agents are already using
+that GPU; a second concurrent stream on a single-GPU box makes both slower and neither fails
+visibly. Over the cap → `MESH_BUSY`, refused immediately rather than queued (a queued inference
+request is indistinguishable from a hung one to every engine's HTTP client).
+
+**Advertisement needs no backend change.** New RPC `model_backends_list`, answered in the existing
+switch in `dispatchDown` (`backendSocket.ts:1411` is the neighbour to copy). A already attaches to C
+with `machine_select` over `/api/web-ws`; it just calls the RPC. No new Redis key, no catalogue to
+keep in sync. Register `model_backends_list_result` in `ENCRYPTED_RPC_RESULT_TYPES`
+(`e2ee/core.ts:345`) — a model catalogue is machine content and must not leave C plaintext.
+
+---
+
+## Change 3 — the wire: a `model_*` plane
+
+New: `cli/src/lib/model-mesh/frames.ts`, `backend/src/lib/modelRelay.ts`.
+
+Modelled on `app_req`/`app_body`/`app_res` (`tunnel.ts:74-110`), multiplexed by `streamId`, but E2EE
+and machine↔machine.
+
+**Control frames (JSON, `up`/`down` with `targetConnId`):**
+
+| Down (B→C) | Up (C→B) |
+|---|---|
+| `model_open` `{streamId, method, path, headers, model}` | `model_head` `{streamId, status, headers}` |
+| `model_abort` `{streamId, reason}` | `model_end` `{streamId, ok}` |
+| | `model_error` `{streamId, code, message}` |
+
+**Body frames (binary):** two new kinds on the existing binary lane (`terminalBinary.ts:33`):
+
+```
+modelBody = 8 // request body chunk, B→C
+modelChunk = 9 // response body chunk, C→B
+```
+
+This is the highest-leverage decision here. Riding the existing binary lane means bodies are sealed
+with the already-derived binary key and stay opaque to the relay; the 24-byte hop header
+(`terminalBinary.ts:68`) is reused verbatim so the backend needs no new framing; and
+**`remoteRelay.ts:511` `sendBinary` already routes per-`streamId` over P2P and demotes to relay on
+failure** — so Change 6 is largely configuration rather than a second implementation.
+
+Chunk at `UPLOAD_CHUNK_BYTES` (256 KiB, `terminalStreamManager.ts:31`), under the 512 KiB
+per-binary-message ceiling shared by the relay and the data channel. A 200k-token prompt is ~800 KB,
+so chunking is the normal path, not an edge case.
+
+**Backend (`modelRelay.ts`, mirroring `terminalRelay.ts`):** closed `MODEL_DOWN_TYPES` /
+`MODEL_UP_TYPES` vocabularies; `isEncryptedModelFrame()` failing closed exactly like
+`terminalRelay.ts:27`; and a `ModelRateGuard` that is **byte-dominant where the terminal guard is
+frame-dominant** — single-digit requests per minute, megabytes each. Start at `model_open` 600
+frames / 64 MiB, body kinds 20,000 frames / 512 MiB, then tune against a measured run and write the
+measurement into the comment the way `terminalRelay.ts:48` does. Gate in `webWs.ts` (down, beside
+`TERMINAL_DOWN_TYPES` at `:309`) and `adapterWs.ts` (up).
+
+Register the JSON control types in `ENCRYPTED_DOWN_TYPES` (`e2ee/core.ts:362`) and
+`ENCRYPTED_UP_TYPES` (`:339`) — headers carry the model id and the caller's token.
+
+> `webWs.ts:414` forwards unrecognised frame types down generically, so a v1 would *function* with no
+> backend change. Do not ship that: an ungated plane has no size cap and no rate guard, and "it works
+> without the guard" is how the terminal plane's rejected-ack freeze happened.
+
+---
+
+## Change 4 — B: the loopback gateway
+
+New: `cli/src/lib/model-mesh/gateway.ts`, started by `cli.ts` beside the hook server.
+
+`http.createServer` bound to **127.0.0.1 only** (`hookServer.ts:654`), **one port per daemon**
+(decided): `ADAPTER_MESH_PORT`, default `18474`, with the same "taken means another daemon is
+running" report the hook port uses (`config/env.ts:123`).
+
+Route `/mesh/:machineId/*` → the peer's backend, path and query verbatim.
+
+**Auth: one token per agent** (decided). `Authorization: Bearer`, `timingSafeEqual`-compared, 0600
+under `${ADAPTER_DATA_DIR}/model-mesh/` via `secureState.ts` — `hookAuth.ts` is the file to copy,
+including its `O_NOFOLLOW`, uid and mode checks. A token is scoped to one `(agentId, hostMachineId)`
+pair and dies with the agent, so revoking one agent never touches its siblings.
+
+Per request:
+
+1. `hostMachineId === self` → proxy to the local backend, return. Otherwise
+ `RemoteRelayPool.acquire()` (`remoteRelay.ts:212`). No pinned peer → **403** naming the exact fix:
+ `harness link connect <machineId>`.
+2. `model_open` with method, path, and an **allowlisted** header set (`content-type`, `accept`,
+ `authorization`, `anthropic-version`; hop-by-hop and identifying headers such as `x-stainless-*`
+ are dropped — they do not cross machines).
+3. Stream the request body as `modelBody` chunks; `model_abort` if the client hangs up first.
+4. On `model_head`, write status + headers and `flushHeaders()` before the first chunk so SSE starts
+ immediately. Write each `modelChunk` straight through — no buffering.
+5. On `model_end`, `res.end()`.
+
+**Timeouts and truncation.** No `model_head` within 30s (`appTunnel.ts:32` `RESPONSE_TIMEOUT_MS`) →
+**504**. And the one that matters: if the link drops mid-stream, **`res.destroy()` — never
+`res.end()`**. A truncated-but-cleanly-ended SSE stream is indistinguishable from a complete one to
+every engine's HTTP client, and would be recorded as a finished turn that silently lost its tail.
+Destroying surfaces it as the transport error it is, and every engine retries on that.
+
+---
+
+## Change 5 — launch and read-back
+
+New: `cli/src/lib/model-mesh/meshAssignment.ts`. Touches `backendSocket.ts`, `cli.ts`,
+`registry.ts`, `createAgentPane.ts`, `terminalAgentDiscovery.ts`, `agentFrame.ts`.
+
+**New frame contract**, replacing `payload.grid` — on `agent_create` and `agent_retarget`:
+
+```ts
+/** Run this agent's inference on a peer machine reached over the relay. */
+model?: {
+ hostMachineId: string // a machine id; validated, control characters rejected
+ model: string // the model id as C reports it
+}
+```
+
+Deliberately **no `baseUrl` and no `apiKey`**: the caller cannot know B's loopback port and cannot
+mint B's token, so accepting either would create two sources of truth for one address. B synthesises
+`http://127.0.0.1:<meshPort>/mesh/<hostMachineId>/v1` and mints the key itself. Parsing mirrors
+`parseGridLaunchOverride`'s tri-state shape — `absent` is a first-class answer so a build that sends
+no `model` field creates agents exactly as it always did.
+
+**Read-back** (principle 2): `probeMeshAssignment(process)` reads the engine's own env/argv through
+`readProcessEnv`, matches Change 1's `MESH_URL_RE`, and answers
+`{ hostMachineId, model } | null`. The registry field `grid` becomes `mesh`, and
+`terminalAgentDiscovery.ts` / `tmuxAgentDiscovery.ts` / `agentFrame.ts` follow it. The key is never
+read — the pane's credential is the pane's business.
+
+**Pre-flight, before the pane spawns** (principle 3). B asks C `model_backends_list` and checks
+reachability, serving consent, model presence, and that the dialect the engine speaks is one C
+serves. Each miss refuses the create with its own code:
+
+`MESH_PEER_OFFLINE` · `MESH_NOT_SERVING` · `MESH_MODEL_NOT_FOUND` · `MESH_DIALECT_UNSUPPORTED` ·
+`MESH_ENGINE_UNSUPPORTED` · `MESH_NO_PEER_LINK`
+
+---
+
+## Confidentiality: what is encrypted, and between which two points
+
+**Every byte of a model request and response is ciphertext for the whole of its journey across the
+relay.** Naming the ends precisely, because "end-to-end" is doing real work in that sentence:
+
+```
+codex ──plaintext──▶ ModelGateway ══ciphertext═══════════▶ ModelHost ──plaintext──▶ ollama
+ 127.0.0.1 (B) │ relay sees only this │ 127.0.0.1 (C)
+ └── the cryptographic ends are B's daemon and C's daemon ──┘
+```
+
+**The two plaintext segments are on loopback, inside a trust boundary the user already owns.** They
+are unavoidable and should be stated rather than glossed: ollama does not speak this protocol, and
+codex speaks ordinary HTTP. The trust boundary is the machine, not the process — which is the same
+boundary the terminal plane already draws, where a pane's bytes are plaintext in the daemon before
+being sealed.
+
+**Keys must be pairwise, never the group key.** This is the one way to get it silently wrong. The
+per-process group key (`k: 'g'`) is readable by *every* paired client of a machine — every browser,
+every device. Model traffic carries whole prompts and whole completions and must be `k: 'p'`:
+the pairwise `c2s`/`s2c` pair from `RelaySessionCrypto`'s X25519 ephemeral DH, established against
+the Ed25519 peer pinned in `machinePeers.ts` and verified by `helloSig`/`welcomeVerify`
+(`e2ee/relayClient.ts`). Bodies on the binary lane use the separately derived
+`deriveTerminalBinaryKey(c2s|s2c)`, ChaCha20-Poly1305 per frame, with `replayWindow.ts` rejecting
+replays. Ephemeral per connection, so the leg has forward secrecy.
+
+**P2P changes nothing about this.** `remoteRelay.ts:511` seals *before* choosing a transport —
+`encryptTerminal(clear)` runs, then p2p or ws carries the identical sealed bytes. The JSON path does
+the same with `wrapOutgoing`. A DataChannel adds DTLS underneath; it never replaces the payload
+encryption.
+
+**Fail closed — the rule this plan was missing.** C must refuse a `model_open` that arrives on a
+connection with no established pairwise session, rather than serving it in the clear. This mirrors
+the existing enforcement in `emitReply` (`backendSocket.ts:989-1012`), where a content-bearing RPC
+result answers `E2EE_REQUIRED` instead of falling back to plaintext — including for the legacy
+`connId === ''` awaiter. Without the same rule here, "encrypted by default" is a property of the
+happy path rather than a guarantee. Add `MESH_E2EE_REQUIRED` to the refusal codes, and cover it in
+`modelRelay.test.ts` alongside the fail-closed envelope check.
+
+**What the relay does learn:** that B opened a stream to C, when, how large it was, and how often.
+Stream metadata and the cleartext hop header (`machineId`, `connId`, direction) are routing
+information and cannot be encrypted without a different relay design. It does not learn the prompt,
+the completion, the model id, or the credential — the model id and `Authorization` header travel
+inside `model_open`'s encrypted payload, not beside it.
+
+## Change 7 — the B→C link must be establishable from A's desk
+
+**The key setup is reused; the existing pins are not sufficient.** Both halves matter.
+
+**Reused.** The machine↔machine relation already exists and model calls are simply a third consumer
+of it. `cli.ts:4133` states the intent directly: *"The SAME identity `harness remote-password
+set` publishes and `harness link connect` proves knowledge against, so one link ceremony covers the
+desktop app's relay and the dial's lane alike."* Model calls join the desktop relay and the dial's
+lane as consumers of that one ceremony. No second key, no second ceremony, no new crypto — B→C runs
+through the same `RemoteRelayPool.acquire()` against the same `machinePeers.json` pin.
+
+**Not sufficient.** The pin is **directional and per-machine**: `machinePeers.json` lives in each
+machine's own `${ADAPTER_DATA_DIR}/e2e/`. Linking from a desktop on A produces **A→B** and **A→C**.
+The model call needs **B→C**, and B has no pin for C. Nothing about driving agents on B and C from A
+implies B has ever heard of C.
+
+**And today that link can only be made by standing on B.** `harness link connect` is an interactive
+command, run as its own process on the joining machine, prompting for the target's remote password.
+So the mesh currently requires SSH-ing into B — in a product whose premise is that the desk is where
+the work is directed from.
+
+**Fix: `machine_link_connect`, modelled on `device_e2ee_pair`.** That precedent is exact
+(`e2ee/manager.ts:457` `pairDeviceFromTrustedWeb`): a client with an already-established E2EE session
+— checked as `session.role === 'web'`, refusing `UNTRUSTED_WEB` otherwise — instructs the machine to
+carry out a pairing ceremony on its behalf, and gets an encrypted RPC reply. Same shape here:
+
+1. A's desktop is already E2EE-trusted with B. The user types C's remote password on A.
+2. A sends `machine_link_connect {hostMachineId: 'C', password}` to B, encrypted with the existing
+ A↔B pairwise session. The relay never sees the password.
+3. B runs the ordinary CPace ceremony against C and pins the result — byte-identical to what
+ `harness link connect C` does when typed on B.
+4. B replies with the peer fingerprint so A can display it for out-of-band verification, exactly as
+ `cli.ts:4789` asks the operator to do today.
+
+**The password proof stays.** It is tempting to let the backend authorize a link between two machines
+it already knows share an owner, and skip the password. Do not: the CPace exchange is what makes the
+relay unable to mint links, and a backend that could authorize one could link an attacker's machine
+into a user's mesh. Ownership is a necessary check, never a sufficient one.
+
+This is small, but without it the feature is "works once you SSH into B" rather than "works".
+
+---
+
+## Change 6 — P2P (phase 4, but designed for now)
+
+Because bodies ride the binary lane, `remoteRelay.ts`'s per-`streamId` P2P routing applies with two
+changes: add the model kinds to the migration-eligible set, and let `TERMINAL_P2P_DOWN_TYPES`
+(`terminalP2p.ts:47`) carry the `model_*` control frames.
+
+Worth doing early. Inference bodies are the largest payload class in the product — ~100 KB–1 MB per
+round trip × 30 round trips per prompt × every agent — and A, B and C are frequently on one LAN,
+where a direct path turns a WAN round trip into a sub-millisecond one.
+
+---
+
+## Not in scope (deliberately)
+
+- **Dialect translation** (Anthropic Messages ⇄ OpenAI). Refused with `MESH_DIALECT_UNSUPPORTED`.
+ A translator is a real product need but a substantial one, and putting it in the tunnel means every
+ bug in it presents as a model bug.
+- **Metering / billing** (decided). Stream-level counters go to the daemon log only — bytes, chunks,
+ duration, model, peer — so the data exists if we want it later, with no billing plumbing to unpick.
+- **Scheduling across several hosts.** One agent, one named host machine.
+- **Serving outside the user's account.** Ownership is checked at the relay and stays checked.
+
+## Failure modes
+
+| Condition | Caught where | User sees |
+|---|---|---|
+| C offline | pre-flight, then `model_open` | create refused, `MESH_PEER_OFFLINE` |
+| C not serving to B | pre-flight | refused, `MESH_NOT_SERVING` + the `harness models serve` command |
+| No pinned peer | `RemoteRelayPool.dial` | 403 + the `harness link connect` command |
+| Model absent on C | pre-flight | refused, `MESH_MODEL_NOT_FOUND`, listing what C does have |
+| Engine dialect ≠ C's | pre-flight | refused, `MESH_DIALECT_UNSUPPORTED`, naming both |
+| Engine has no endpoint contract | Change 1 | refused, `MESH_ENGINE_UNSUPPORTED`, reason specific to that engine |
+| C at its concurrency cap | ModelHost | `MESH_BUSY` → 503, immediately |
+| C's backend down mid-session | `model_error` | upstream status passed through (502) |
+| Link drops mid-stream | gateway | `res.destroy()` → engine sees a transport error and retries |
+| Over the rate guard | backend | frame rejected; gateway 429s rather than hanging |
+
+## Testing
+
+1. `modelEndpoint.spec.ts` — one fixture per engine contract; **differentially tested against
+ `gridLaunch.ts` while it still exists**, then the differential test is deleted with grid.
+2. `frames.spec.ts` — chunking, reassembly, ceilings, malformed-frame rejection.
+3. `modelRelay.test.ts` (backend) — fail-closed envelope check, `ModelRateGuard` buckets. Mirrors
+ `terminalRelay.test.ts`.
+4. `gateway.spec.ts` — a recorded OpenAI SSE stream replayed end-to-end through a stubbed relay,
+ byte-compared at the gateway's HTTP output. **This is the conformance bar: the bytes the engine
+ receives must equal the bytes C's backend produced.**
+5. Truncation test, explicitly: kill the link mid-stream, assert `destroy` not `end`.
+6. Loopback short-circuit test: `hostMachineId === self` never constructs a relay session.
+7. `model-mesh.real.spec.ts` (opt-in, like `test:tmux-real`) — two daemons, real ollama, real codex
+ pane. The one test that proves the thing works.
+
+## Sequencing
+
+| Phase | Contents | Ships alone? | Note |
+|---|---|---|---|
+| 1 | Change 1 — engine endpoint contract | Yes | **Must land before grid is deleted** |
+| 2 | Change 2 — host, probe, `serve.json`, `model_backends_list` | Yes | A can list what C serves |
+| 3 | Change 3 — frames, backend guards, e2ee registration | No | lands with 4 |
+| 4 | Change 4 + 5 — gateway, launch, read-back | Yes | first user-visible value |
+| 5 | Change 7 — `machine_link_connect` | Yes | can land any time; without it, setup needs shell access to B |
+| 6 | Change 6 — P2P | Yes | |
+
+Nothing in phases 1–4 changes an existing frame's meaning: an older daemon reports no model backends
+and refuses a mesh launch it does not understand.
+
+## Open questions
+
+1. **Does grid's deletion remove endpoint-pointing as a product capability entirely, or does mesh
+ inherit it?** If a user should still be able to point an agent at an arbitrary public endpoint
+ after grid is gone, Change 1 should expose that directly rather than only via `hostMachineId` —
+ it is the same table either way, and the decision changes the module's public shape.
+2. **Does C's GPU need protecting from its own agents?** `maxConcurrent` bounds remote streams, but
+ an agent running locally on C bypasses the gateway and the cap entirely.
+3. **Engine coverage past the three.** v1 is codex, claude, opencode. Which is fourth, and is there a
+ user waiting on it?
diff --git a/docs/plans/2026-09-14-004-harness-grid-plan.md b/docs/plans/2026-09-14-004-harness-grid-plan.md
new file mode 100644
index 000000000..03315914b
--- /dev/null
+++ b/docs/plans/2026-09-14-004-harness-grid-plan.md
@@ -0,0 +1,592 @@
+# The harness grid: one sign-in, one private grid, models from your own machines
+
+Status: proposed · 2026-09-14
+Supersedes: `2026-09-11-003-model-mesh-plan.md` (which assumed grid was being deleted — it is not)
+
+## Context
+
+The flow, in five steps:
+
+1. Signing in to harness also signs in to grid. One sign-in, and the app can then call grid functions.
+2. On sign-in, a private grid named **harness** is created if it does not exist.
+3. A harness node can start a local model and serve it to the harness grid.
+4. A node can point an agent at the harness grid's models, alongside its subscription models
+ (opus for Claude Code, aster for Codex).
+5. Signing out of harness signs out of grid.
+
+### The grid CLI already does all of it
+
+This is the finding that shapes the plan. Every capability the flow needs already exists as a
+`grid` subcommand, with `--json` on the ones that matter:
+
+| Need | Command | Output |
+|---|---|---|
+| Sign in with a harness token | `grid login --harness` | token read from **stdin** |
+| Does the grid exist? | `grid ls --json` | `[{grid, type, id}]` |
+| Create it | `grid start <name> --type permissioned-public` | creates on first run |
+| Who may use/serve it | `grid members add <grid> <email> --role both` | |
+| What models can it run now | `grid models --json <grid>` | `[{model, engine, node, responses}]` |
+| Endpoint + key | `grid info --env <grid>` | `OPENAI_BASE_URL`, `OPENAI_API_KEY` |
+| What can this box pull | `grid catalog --json` / `grid device-info --json` | |
+| Download a model | `grid pull <model>` | |
+| Serve it | `grid join --serve <model> <grid>` | built-in engine |
+| Adopt an existing engine | `grid join --all` or `--kind ollama\|vllm` | |
+| What is serving | `grid engines --json <grid>` | |
+| Stop serving | `grid leave` | |
+| Sign out | `grid logout` | stops serve children first |
+
+**Step 3 is not the build we assumed.** `grid join --serve` starts grid's own built-in engine, and
+its flags are llama.cpp's — `--ctx-size`, `--n-predict`, `--flash-attn`, `--mmproj`, `--parallel`.
+Grid already owns downloading, running and serving a local model. The harness does not need to
+install llama.cpp, supervise it, or learn its flags.
+
+### What the harness already has
+
+- `gridHandoff.ts` — `handOffToGrid(token)`: spawns `grid login --harness`, token on **stdin**
+ (never argv, never env), classifies the result by exit code.
+- `gridLogout.ts` — `passThroughToGridLogout(args)`: spawns `grid logout`, inherits all three
+ streams, adopts its exit code.
+- `gridLaunch.ts` — turns a base URL + key + model into a real launch for seven engines, each
+ through that vendor's own documented contract, and refuses the rest by name.
+- `gridAssignment.ts` — reads back which endpoint a live pane is actually on, off the process.
+- `gridCommand.spec.ts` — the test convention: a **fake `grid` first on PATH** that records argv and
+ stdin, built in a temp dir.
+
+So four of five steps are wiring, not invention. The two mechanisms for steps 1 and 5 exist and are
+simply bolted to the wrong commands.
+
+### Two facts to fix before anything is testable
+
+**The installed `grid` is too old.** It reports `0.3.34`, and its `grid login --help` offers only
+`--no-browser` and `--json`. `--harness` exists in `autonomous-grid/cli/parser.py:561` but not in
+this build, so `harness grid login` fails today with `GRID_CLI_OUTDATED` — exactly as designed
+(argparse exits 2 before any handler runs). Update `grid` before testing.
+
+**There is no grid named `harness`.** The account currently holds `BBB` (domain-restricted),
+`autonomous.ai` (private-domain, active) and `private autonomous` (permissioned-public).
+
+## Design principles
+
+**1. The harness orchestrates the grid CLI. It never speaks inference.**
+No model protocol, no serving, no dialect translation, no relay of its own. Every capability arrives
+as a `grid` subprocess with `--json`. This is the seam that already exists for login and logout;
+this plan adds calls to it, not a second kind of integration.
+
+**2. The app names a model. The daemon resolves the endpoint and the key — locally.**
+The old `payload.grid` contract had the client mint a key and send `baseUrl` + `apiKey` over the
+relay. Do not rebuild that. The app sends `{model: "DeepSeek-V4-Flash-0731"}`; the daemon on that
+machine runs `grid info --env` and fills in the rest. **No grid credential ever crosses the relay**,
+and there is one source of truth for an endpoint the client could not know anyway.
+
+**3. Grid trouble must never break harness sign-in.**
+A missing, old, or failing `grid` is a warning on stderr and a harness login that still succeeds.
+`harness grid login` stays as the explicit path, where the same failure is a real failure.
+
+**4. Read the truth; do not bookkeep it.**
+Which grid, which models, which engines — asked at the moment it is needed, cached only in daemon
+memory and dropped on sign-in/out. `gridAssignment.ts` already applies this to a running pane.
+
+## Architecture
+
+```
+harness login
+ │
+ ├─ SSO (unchanged) ─────────────▶ ~/.harness/auth/session.json
+ │
+ ├─ handOffToGrid(token) ────────▶ grid login --harness (token on stdin)
+ │
+ └─ ensureHarnessGrid() ─────────▶ grid ls --json
+ └─ absent? grid start harness --type …
+
+desktop daemon (node B) grid CLI
+ │ models_list │ │
+ ├───────────────────────────▶│ engine's own models ────────────┤ (runtimeProfile)
+ │ │ + grid models ──────────────────▶ grid models --json
+ │◀── one merged list ────────┤ │
+ │ │ │
+ │ agent_retarget {model} │ │
+ ├───────────────────────────▶│ grid info --env ───────────────▶│ OPENAI_BASE_URL + KEY
+ │ │ gridLaunch.ts → respawn-pane -k -e
+ │ ▼
+ │ codex, now on the harness grid
+```
+
+---
+
+## Change 1 — one sign-in (step 1)
+
+`cli/src/cli.ts`, `loginCommand`.
+
+After the harness SSO succeeds, call `handOffToGrid(token)` — the same call `gridLoginCommand`
+already makes (`cli.ts:657`).
+
+**Best-effort, per principle 3.** `GRID_CLI_MISSING`, `GRID_CLI_OUTDATED` and `GRID_LOGIN_FAILED`
+all print their existing sentence on stderr and leave `harness login` exiting 0. Each of those
+messages already names its own way forward; none of them is a reason to fail a harness sign-in.
+
+Under `--json`, the result line gains grid's own answer through the existing `gridSaid()` helper
+(`cli.ts:677`), so a client driving `harness login --json` reads one contract.
+
+`harness grid login` stays exactly as it is: the explicit path, where a hand-off failure **is** the
+command's failure, and the repair route when the best-effort attempt was skipped.
+
+---
+
+## Change 2 — the harness grid exists (step 2)
+
+New: `cli/src/lib/gridEnsure.ts`.
+
+```
+grid ls --json → [{grid, type, id}]
+ └─ no entry named "harness"?
+ grid start harness --type permissioned-public
+```
+
+Runs immediately after a successful hand-off in Change 1, and nowhere else — creating a grid is not
+something a daemon should do on a timer.
+
+**Same best-effort rule.** A failure here is a warning, never a failed login.
+
+**Both open questions are now answered from the grid source** (`autonomous-grid` @ `0c6930c`).
+
+**Use `permissioned-public` — the default — and it is the private one.** The name misleads: "public"
+means *not keyed to an email domain*, not *open to anyone*. ADR 0034 is explicit, and carries a
+correction measured on 2026-08-23 that settles it:
+
+> On any other network type — `permissioned-public` is what the front end creates — **the roster is
+> an allowlist with no domain constraint** […] grid-apis `store.member_for_access` checks an
+> allowlist row **before anything else, on every network type**.
+
+So a `permissioned-public` grid admits exactly the accounts on its roster. `create_network` writes
+every creator an allowlist row (ADR 0039 D-h), so **the owner is a member the moment it is created**.
+
+⚠️ **`permissioned-providers` is the wrong choice, and would be a real mistake.** That is the
+*open-consumer* type: `grid_auth._is_open_consumer` and `store._is_denied_consumer` both open by
+testing for it, the denylist exists only because strangers can consume there, and `relay._billing_on`
+switches on for that type alone — consumers pay and providers earn. Everywhere else "consumers pay
+nothing and providers earn nothing" (ADR 0039 D-g/D-h, ADR 0043). For one person's own machines that
+is billing and an open door, bought for nothing.
+
+**No `grid members add` is needed for the single-user flow.** Membership is keyed on **email**
+(`grid members add [grid] <email>`), not on machine — so every machine that signs in with the
+account is already covered by the owner's row. Members are only needed to share the grid.
+
+> ⚠️ Worth reporting upstream: `docs/omagrid-quickstart.md:132` says permissioned-public means
+> "anyone signed in can send it requests". Per the ADR above that is wrong, and it is the one
+> sentence a reader would use to pick a type.
+
+**`grid start` in remote mode registers and returns — no long-lived process.** `cmd_remote_up`
+(`cli/remote_grid.py:183`) is a short control-plane call:
+
+```
+credentials.require_session()
+ ├─ grid known locally ──▶ control_plane.start_managed_network(…) idempotent if already running
+ │ get_managed_network_status(…) → print → return 0
+ └─ unknown + name given ▶ control_plane.create_managed_network(session, name, type)
+ credentials.add_network(record) → print → return 0
+```
+
+The blocking server is **local mode only** — `cli/grid.py:28` `cmd_up`, which calls
+`runtime.start_grid(cfg)` and binds a port. Remote mode never goes near it; `cli/dispatch.py` routes
+these verbs to `remote_grid` before the local handler is reached.
+
+So **grid creation is safe to call from a login command.** Three behaviours to code against:
+
+- **A name is required.** Remote never auto-creates `home` — bare `grid start` with nothing active
+ exits with *"Name a grid to create"*. Always pass `harness`.
+- **`--type` applies on create only.** Passed against an existing grid it prints a note and is
+ ignored, so it is harmless to send every time.
+- ⚠️ **The duplicate-name trap.** `_by_name` reads the **locally stored** registry in
+ `credentials.toml` — `grid ls` makes no network call. If that list is stale, the existence check
+ misses and `create_managed_network` runs again under the same name. `grid login` fetches the list,
+ so a create immediately after the hand-off is safe; anywhere else, run `grid sync` first. The
+ handler already warns about this in its own failure path: a grid created server-side that cannot be
+ saved locally exits telling the user to re-sync, precisely so "the next `grid start <name>` would
+ create a duplicate" does not happen silently.
+
+---
+
+## Change 2b — confirmed: remote, private, and what to name it
+
+**Remote mode is automatic.** `cmd_login` (`autonomous-grid/cli/auth.py:139-141`) sets it: *"Signing
+in is what 'I want the hosted grids' looks like, so the mode follows the credentials."* A failed or
+denied sign-in leaves the mode alone.
+
+**Local mode is out of scope** — every grid call this plan makes is remote. Pass `--remote` on each
+one regardless: it is a one-shot override `resolve_override` strips from any position, and it makes
+the harness immune to a user who switched their own machine to local mode for their own reasons.
+Nothing here reads, sets, or reasons about the local-mode grid.
+
+**Private is confirmed on both jobs.** `permissioned-public` gates access on an allowlist roster
+(ADR 0034, corrected 2026-08-23), and the roster's roles are `consumer | provider | both` — so the
+same list governs *using* the grid and *serving* to it. `create_network` writes the creator an
+allowlist row, and membership is keyed on **email**, so every machine signed in as the owner can
+both serve and consume, and nobody else can do either.
+
+⚠️ **Do not call `grid use`.** Login deliberately does not auto-select a grid (`auth.py:142`), and
+the user's active grid is their own setting — on this machine it is currently `autonomous.ai`.
+Hijacking it would silently re-point every bare `grid` command they run by hand. **Pass the grid
+name explicitly** to `grid models`, `grid info` and `grid join` instead; every one of them takes it
+as a positional.
+
+### Naming: the suffix must be recoverable on a second machine
+
+The proposed shape is the email local-part + `-` + a unique string, e.g. `anhthuychaucfc-7f3a91`.
+The format is fine — `gridProviderId` slugifies to `[a-z0-9-]` anyway — but **a random suffix has a
+trap**, and it is the whole reason this needs deciding before implementation.
+
+`_by_name` matches a **locally stored** record by name or id. Machine A creates the grid and knows
+its name. Machine B signs in, fetches the account's grids, and then has to answer *which of these is
+the harness grid* — and with a random suffix it cannot. It finds nothing, and
+`create_managed_network` runs again: **a second grid, same purpose, different name**, with the user's
+models stranded on the first.
+
+**Decided: the backend remembers the name.** It already authenticates the token and holds
+`{id, email}` (`backend/src/lib/ssoAuth.ts:91`), and already pushes `machine_meta` to every adapter
+on connect. The first machine to create the grid reports the name back; the backend stores it on the
+user record and hands it to every other machine of that user. A random suffix is then fine, because
+nothing ever has to recompute it.
+
+**Grid names are globally unique** (confirmed), so the email prefix earns its place — it keeps one
+user's grid from colliding with another's, and the random suffix keeps it from colliding with their
+own. Final shape:
+
+```
+<email local-part, lowercased, [^a-z0-9]+ → "-"> "-" <random suffix>
+anhthuychaucfc-7f3a91
+```
+
+Sanitize the local-part rather than trusting it: `foo+test@…` and `first.last@…` are ordinary
+addresses, and `gridProviderId` slugifies to `[a-z0-9-]` downstream anyway — do it once, up front,
+so the name that is stored is the name that is sent.
+
+**Global uniqueness means create can lose a race.** Two machines signing in at once both find no
+stored name and both call `create_managed_network`. Make the backend the referee: a machine asks the
+backend for the name first, and only creates when the backend has none — then reports it back, with
+the backend keeping the first write and returning it to the loser, who adopts it instead of creating
+a second grid. Treat a control-plane name collision as "someone else won", re-read, and adopt.
+
+Two alternatives, recorded as rejected: a **deterministic hash suffix** needs the same backend change
+to learn the account and gives weaker collision behaviour under global uniqueness; **reading grid's
+`~/.grid/credentials.toml`** (it holds `[user] email` and `google_sub`) doubles down on the one
+fragile seam we have — `gridCredentials.ts` deliberately does nothing but test that file's existence,
+and its path layout is already hand-duplicated from grid's `shared/paths.py` behind a drift warning.
+
+---
+
+## Change 2c — Harness carries the grid CLI
+
+The user must not have to install `grid` separately. Feasible, and the two platforms differ.
+
+**Linux is easy.** Grid already ships a self-contained Nuitka onefile binary — *"no Python, uv, or
+pip"*. Download and sha256-verify it into `~/.harness/runtime/grid/` using the mechanism that already
+exists for the managed Node runtime: `runtimeInstall.ts` + `downloadVerified` (`selfUpdate.ts`),
+which is idempotent, falls back silently when a download fails, and already lands artifacts in
+`~/.harness/runtime/`.
+
+**macOS is the real work, and Harness is what unblocks it.** Grid ships *no* macOS binary, and
+`packaging/README.md` says exactly why:
+
+> The ad-hoc-signed Nuitka onefile is **SIGKILL'd on modern macOS** (verified on macOS 26) —
+> distributing a macOS binary requires Apple **Developer ID signing + notarization**, which isn't set
+> up yet. […] When notarization lands, add a `macos-*` binary back to the matrix.
+
+**Harness already has that, and it is who signs this** (decided). The same pipeline that signs the
+desktop app signs the grid binary: `desktop/scripts/publish-macos-variant.sh` with
+`Developer ID Application` under team `54DJVWMJCC`, `--timestamp --options runtime`, plus
+`.github/actions/macos-signing` and the existing notarization step. `packaging/build_binary.sh`
+already produces a macOS binary locally — only the signing was missing. So Harness publishes a
+signed, notarized grid artifact as a **versioned managed runtime**, on harness's release cadence,
+pinned in the same manifest the managed Node runtime uses
+(`desktop/scripts/publish-managed-node-runtime.sh` is the precedent to copy). This closes a gap that
+blocks grid's own macOS distribution too.
+
+**Decided — build `--standalone`, not onefile.** A Nuitka *onefile* unpacks itself to a temp
+directory and executes from there, which is exactly what the hardened runtime
+(`--options runtime`, required for notarization) exists to stop. A `--standalone` **directory** of
+ordinary Mach-O files is the shape macOS signing and notarization are designed around, so it removes
+the risk rather than mitigating it. Build standalone on both platforms and the two pipelines stay the
+same shape; Linux can equally keep grid's published onefile, since nothing there objects to it.
+
+⚠️ **It belongs to the CLI, not the app.** A server running `harness start` with no desktop at all
+still needs `grid` — the daemon is what shells out to it. Ship it as a managed runtime under
+`~/.harness/runtime/`, resolved by `gridExec` ahead of `PATH`, never as a resource inside
+`Harness.app`. **The pinned runtime wins, not `PATH`** (decided). Pinning is what makes the version floor a
+property we test rather than a surprise we discover, and letting an arbitrary `grid` on `PATH`
+take precedence would give that away. Resolution order: `HARNESS_GRID_BIN` (an explicit developer
+override) → the pinned managed runtime → `PATH` (only as a fallback when no runtime could be
+installed).
+
+⚠️ **The pinned binary and the user's own `grid` share `~/.grid`.** `GRID_HOME` is one state
+directory — credentials, device id, the network registry — so two binaries of different versions read
+and write the same files. That is fine while they are close, and it makes a grid state-format change
+a **coordination point** rather than a grid-side detail: the pin has to move before or with it. Track
+grid's releases rather than pinning and forgetting.
+
+---
+
+## Change 3 — a node serves a local model (step 3)
+
+Deferred, but the shape is now known and much smaller than assumed.
+
+```
+grid device-info --json can this box serve, and with what
+grid catalog --json what it can pull
+grid pull <model> download (long, needs progress)
+grid join --serve <model> <grid> start grid's built-in engine and join
+grid engines --json <grid> what is serving now
+grid leave stop
+```
+
+Two things the harness owns and nothing else:
+
+- **Progress.** `grid pull` is a long download; the desktop needs to show it. That is the only part
+ of step 3 with real UI work.
+- **Not supervising the child.** `grid join --serve` leaves a serve child that **grid itself** owns
+ and that `grid logout` tears down before deleting any credential. The harness must not daemonize,
+ restart, or reap it — doing so would fight the sign-out path that already exists.
+
+`grid join --all` / `--kind ollama` also adopts an engine the machine already runs, which is the
+cheaper first version: serve what is there before downloading anything.
+
+---
+
+## Change 4 — one model list, both sources (step 4)
+
+`cli/src/backendSocket.ts` (`models_list`, `agent_retarget`), `cli/src/cli.ts`
+(`runtimeModelsProvider`, `cli.ts:1945`), `cli/src/lib/gridLaunch.ts`, and new desktop UI.
+
+**The list.** `models_list` today returns `runtimeProfiles.modelsForSession(session)` — the engine's
+own models, read from its own config. Add the harness grid's models beside them, tagged by source:
+
+```jsonc
+{ "models": [
+ { "id": "opus", "source": "subscription" },
+ { "id": "DeepSeek-V4-Flash-0731", "source": "grid", "node": "scholes-60001" },
+ ] }
+```
+
+⚠️ **Filter out `auto`.** `grid models --json` lists the grid-router entry as
+`{"model": "auto", "engine": "grid-router"}`. It is deliberately **not** offered in the picker for
+now: routing is being reimplemented once E2EE lands on the grid path, and shipping it first would
+teach a selection we are about to change. Drop any row whose engine is `grid-router` rather than
+matching on the name `auto`, so a renamed router does not leak through.
+
+`node` comes straight from `grid models --json` and is worth surfacing: on the harness grid it names
+*which of the user's own machines* answers that model.
+
+**The switch is a pane respawn, not a menu change.** Moving an agent between its subscription and the
+grid changes the process's environment, so it goes through the existing `agent_retarget` path —
+`respawn-pane -k -e` with `--resume`, keeping the pane, its id and its scrollback, and refusing a
+pane mid-turn with `AGENT_BUSY`. The picker must say so; a model menu that silently restarts the
+engine is a worse surprise than a confirm.
+
+**The frame.** `agent_retarget` carries `{ model: "<id>", source: "grid" }` and nothing else. The
+daemon runs `grid info --env`, builds the launch through `gridLaunch.ts`'s existing per-engine
+contracts, and spawns. Per principle 2, no endpoint and no key crosses the relay.
+
+⚠️ **The key must stay out of argv and logs.** `gridLaunch.ts` already routes credentials through the
+environment (and codex's `env_key` indirection) for exactly this reason, and `registry.ts:105-111`
+holds the full launch for relaunch while documenting that it is never logged. Keep both properties;
+`grid info --env` output is a secret and must be handled like one.
+
+**Desktop is net-new.** The app-v2 client has no grid code at all — `models.dart` parses no grid
+field, and `harness_cli_runner.dart` runs the harness CLI, not `grid`. This change adds the model
+section and the retarget call to `desktop/`, which is now in this repo, so it lands in the same
+commit as the CLI side and is testable end to end before merge.
+
+---
+
+## Change 5 — one sign-out (step 5)
+
+`cli/src/cli.ts`, `logoutCommand` (`cli.ts:944`) and `resetCommand` (`cli.ts:4635`).
+
+Call `passThroughToGridLogout([])` — which already exists — **before** clearing the harness session,
+and keep `warnIfGridSignInRemains()` only as the fallback for when no `grid` could be run at all.
+
+Order matters and is not arbitrary: `grid logout` tears every serve child down **first**, while the
+token that makes their deregistration authoritative still exists, and it refuses rather than
+deleting credentials when a child cannot be confirmed stopped. Running it before the harness
+sign-out preserves that. Its refusal is reported, not fatal — a harness sign-out must still complete.
+
+⚠️ **This reverses a documented decision.** `gridLogout.ts` and `gridCredentials.ts` both state
+there is *"no cascade into the harness session, and none out of it."* That comment becomes wrong the
+moment this ships. Update it in the same commit, saying what changed and why, or it will be read as
+the current rule and dutifully restored.
+
+---
+
+## Change 6 — one grid seam (cross-cutting)
+
+New: `cli/src/lib/gridExec.ts`.
+
+`gridHandoff.ts` and `gridLogout.ts` each spawn `grid` their own way, which was fine for two calls.
+This plan adds roughly eight more. Extract one helper before writing the second one:
+
+- `binaryOnPath` pre-check, so a missing `grid` is a sentence rather than a spawn error every caller
+ re-recognises (and it catches present-but-not-executable, which `ENOENT` does not).
+- Bounded capture on the **capture** only, never the passthrough — `gridHandoff.ts:52` already has
+ the shape.
+- One exit-code classification: `0` ok, `2` outdated, else failed.
+- Typed `--json` parsing, so no caller hand-rolls `JSON.parse` on child output.
+
+**A version floor.** Several commands here need a `grid` newer than the `0.3.34` on this machine.
+Read `grid version` once per daemon start, compare, and say which command needs what — a single
+clear "update grid" beats eight different argparse errors.
+
+## Failure modes
+
+| Condition | Where | What happens |
+|---|---|---|
+| No `grid` on PATH | `gridExec` pre-check | login succeeds; stderr says to install grid |
+| `grid` too old for `--harness` | exit 2 | login succeeds; stderr says to update grid |
+| Grid sign-in fails | exit ≠ 0,2 | login succeeds; grid's own stderr is shown |
+| `grid ls` fails | Change 2 | login succeeds; no grid ensured; retry next login |
+| Harness grid missing at model-list time | Change 4 | list shows subscription models only |
+| `grid info --env` fails | Change 4 | retarget refused before the pane is touched |
+| Pane mid-turn | `agent_retarget` | `AGENT_BUSY` — never interrupt a turn |
+| `grid logout` refuses (serve child) | Change 5 | reported; harness sign-out still completes |
+
+## Testing
+
+Follow `gridCommand.spec.ts`: a **fake `grid` first on PATH**, in a temp dir, recording argv and
+stdin. It already proves the one thing a fake can honestly prove about the hand-off — that the token
+went to stdin and never to argv or the environment.
+
+1. `gridEnsure.spec.ts` — grid present → no `start`; absent → `start` with the right name and type;
+ `grid ls` failure → warning, no throw.
+2. `login` best-effort — fake `grid` in each of missing / not-executable / outdated / failing, and
+ `harness login` still exits 0 every time.
+3. `logout` cascade — `grid logout` is spawned **before** the session is cleared; a refusing child
+ does not block the harness sign-out.
+4. Merged `models_list` — subscription and grid models in one list, correctly tagged and sourced.
+5. `agent_retarget` — the frame carries only the model id; the key comes from `grid info --env`;
+ **assert no key appears in argv or in any log line**.
+6. Desktop widget tests for the picker, including the "this restarts the pane" affordance.
+
+## Sequencing
+
+| Phase | Contents | Ships alone? |
+|---|---|---|
+| 0 | Update `grid` past `0.3.34` (needed for `login --harness`); signed `--standalone` grid artifact published | prerequisite |
+| 1 | Change 6 (seam + version floor) + Change 2c (grid as a managed runtime) | yes, invisible |
+| 2 | Change 7 (backend mints the name) → Change 1 + 2 (one sign-in, grid ensured) | yes |
+| 3 | Change 5 (one sign-out) | yes — pairs with phase 2 |
+| 4 | Change 4 (merged picker + retarget), CLI and desktop together | yes — the feature |
+| 5 | Change 3 (serving) | yes |
+
+Phases 2–4 are the flow as described. Phase 5 turns the user's own machines into the thing that
+answers, which is where it gets interesting.
+
+## Change 7 — the backend mints and remembers the grid name
+
+`backend/prisma/schema.prisma` (User), a new route, and `cli/src/lib/gridEnsure.ts`.
+
+**The backend computes the whole name; the CLI never proposes one.** The `User` row already holds
+both inputs — `email` (unique, normalized) and `id` — and the CLI holds neither. Making the backend
+the author removes the proposal round trip, the need to ship the email to every machine, and the
+race, all at once.
+
+**Schema.** One nullable column:
+
+```prisma
+model User {
+ …
+ gridName String? // the private harness grid, minted on first ask; never rewritten
+}
+```
+
+Deliberately **not** `@unique`: on MongoDB a unique index counts nulls as values, so every user
+without a grid would collide with every other. Global uniqueness is the grid control plane's rule
+to enforce, not ours — ours is only *one name per user*, which the conditional write below gives.
+
+**Route.** `POST /api/grid/name`, no body, under the existing SSO middleware so the user comes from
+the token and never from the path:
+
+```
+POST /api/grid/name → { "gridName": "anhthuychaucfc-7f3a91c4" }
+```
+
+Read-if-set, mint-if-not. The referee is a conditional update rather than a transaction:
+
+```ts
+const minted = gridNameFor(user) // pure, see below
+const { count } = await prisma.user.updateMany({
+ where: { id: user.id, gridName: null }, // ← only an unclaimed row matches
+ data: { gridName: minted },
+})
+// count === 1 → we minted it. count === 0 → another machine won; read theirs and return that.
+return count === 1 ? minted : (await prisma.user.findUnique(…))!.gridName
+```
+
+Two machines signing in at once therefore converge on one name, and the loser adopts rather than
+creating a second grid. A `GET` variant is not needed — the POST is idempotent by construction.
+
+**The name.**
+
+```
+gridName = sanitize(localPart(email)).slice(0, 32) + "-" + sha256(user.id).hex.slice(0, 8)
+```
+
+- `sanitize` lowercases and maps `[^a-z0-9]+` → `-`, trimming leading/trailing dashes — the same
+ reduction `gridProviderId` applies downstream, done once here so what is stored is what is sent.
+ `first.last@`, `foo+test@` and a local-part of pure punctuation are all ordinary inputs; the last
+ falls back to `user`.
+- **8 hex, derived from `user.id`, not random.** Collisions only matter between users who share an
+ email local-part — `admin@`, `info@`, `dev@` are the realistic cases. At 8 hex (4.3 × 10⁹), a
+ thousand users sharing one local-part collide with probability ≈ 0.01%; at 6 hex it is ≈ 3%, which
+ is too high for exactly the prefixes most likely to be shared. Deriving rather than randomising
+ also makes the value reproducible when someone has to support it.
+- The **stored string is authoritative**. The formula runs once, at mint; changing it later never
+ renames an existing grid.
+
+**Delivery.** Push `gridName` on the existing `machine_meta` frame the backend already sends every
+adapter on connect (`adapterWs.ts`), so a machine that never calls the route still learns it.
+
+**CLI order matters — claim before create.** Claiming is backend-only and cheap; creating is not.
+
+```
+POST /api/grid/name → the name (minted or adopted)
+grid --remote sync → pull the account's grids, so a name another machine created is visible
+grid --remote ls --json → present? nothing to do
+grid --remote start <name> --type permissioned-public
+```
+
+The `sync` is what stops the loser of a race from calling `create_managed_network` for a grid that
+already exists — without it `_by_name` reads a stale local registry, and **the control plane rejects
+a duplicate name outright** (confirmed). That rejection makes duplicates impossible by construction,
+which is the property this flow wants.
+
+⚠️ **Detect it by observation, not by parsing the error.** Under `--json`, grid emits a refusal
+envelope on **stderr** — `{"error": {"code": …, "message": …}}` (`cli/json_error.py`) — but `code` is
+documented as `None` for a local refusal and for any relay sending a plain-string detail, so a
+control-plane duplicate is likely to arrive as a sentence carrying a status, not a code. Matching on
+that text is exactly the thing that module exists to stop people doing. So on **any** create failure:
+
+```
+grid --remote sync
+grid --remote ls --json → name present? the race was lost, and we are done
+ → still absent? report grid's own message verbatim
+```
+
+The same "read the truth rather than trusting a report" rule the rest of this plan follows, and it
+stays correct however the rejection is encoded.
+
+---
+
+## Open questions
+
+None. Every decision this plan waited on is recorded above:
+
+| Question | Decided |
+|---|---|
+| Grid type for "only my machines" | `permissioned-public` — its roster is an allowlist |
+| `grid start` in remote mode | Registers and returns; safe inside a login command |
+| Who mints and remembers the name | The backend, from `email` + `id` (Change 7) |
+| Name shape | `<local-part>-<8 hex of sha256(user.id)>` |
+| Name uniqueness | Global; the control plane **rejects** a duplicate |
+| Who signs the grid binary | Harness's own release pipeline (Change 2c) |
+| Binary shape | Nuitka `--standalone`, never onefile |
+| Grid version | **Pinned** in the harness manifest; no self-update underneath it |
+| `auto` / grid-router model | Excluded from the picker until the grid path is E2EE |
+| Local mode | Out of scope; every call passes `--remote` |