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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
docs: the harness-grid plan, and the model-mesh one it supersedes
bitcoinbuilder0501c4195fb2
diff --git a/desktop/README.md b/desktop/README.mdindex 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):```bashflutter 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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` |