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 web-search-on-a-Local-model plan and its end-to-end run

Kelvina5211f3089d2
diff --git a/docs/plans/2026-09-15-005-harness-grid-websearch-plan.md b/docs/plans/2026-09-15-005-harness-grid-websearch-plan.md
new file mode 100644
index 000000000..e0cdbbd4c
--- /dev/null
+++ b/docs/plans/2026-09-15-005-harness-grid-websearch-plan.md
@@ -0,0 +1,311 @@
+# Web search for agents on a Local model
+
+Status: proposed · 2026-09-15
+Depends on: `2026-09-14-004-harness-grid-plan.md` (Change 4 — the `agent_retarget` path this plan extends)
+Decided in a design interview on 2026-09-15; the decisions are tabulated at the end.
+
+## Context
+
+When an agent is moved from its subscription model to a Local (grid) model, the engine's native
+web tools stop working. They are not tools the engine runs; they are features of the vendor API,
+and a grid base URL is not the vendor API:
+
+- Claude Code's `WebSearch` is executed server-side by Anthropic's API. On a grid endpoint it is
+ simply absent.
+- Claude Code's `WebFetch` fetches the page locally but *summarises it through a haiku call on the
+ same base URL*. The grid's master relay rejects a model name it does not serve with
+ `503 no_providers_available` (`grid-src grid_cli/private_server/relay.py:2254-2275`; only the
+ reserved name `auto` is routed). So `WebFetch` is dead too. The comment in
+ `cli/src/lib/gridWebMcp.ts:130` that leaves `WebFetch` enabled on purpose rests on a wrong
+ assumption and goes with this plan.
+- Codex's native `web_search` is likewise an API-side feature.
+
+A model that keeps a dead tool in its list will call it — the names are familiar — and fail.
+
+### What the grid already ships
+
+The control plane hosts an MCP server for exactly this gap (`grid-apis grid_networks/web_mcp.py`,
+mounted at `/v1/grid/web-mcp/` when `GRID_WEB_MCP_ENABLED` is set; otherwise 404). Facts that shape
+the plan:
+
+| Fact | Where |
+|---|---|
+| Streamable-HTTP FastMCP, stateless, JSON responses; two tools | `web_mcp.py:110,320-384` |
+| `web_search(query, num_results=5)` → `{results:[{title,url,excerpt}]}` | `web_mcp.py:333` |
+| `web_read(urls ≤ 5, max_chars=6000)` → `{results:[{url,title,text,status,error}]}` | `web_mcp.py:360` |
+| Bearer = the **same per-grid access token** `grid info --env` prints as `OPENAI_API_KEY` | `web_mcp.py:168-231`; `autonomous-grid cli/remote_grid.py:378-391` |
+| Served by the control plane over public HTTPS — never the private-server node | `web_mcp.py:11-16` |
+| Allowance 250 searches / rolling 24 h per account, burst 30/min | `grid_networks/web_search.py:239-248`; `web_mcp.py:98-99` |
+| Exhaustion is an `isError` tool result with clean text (no "grid" in it) | `web_mcp.py:273-287` |
+| `grid mcp config [<grid>] --json` → `{server, url, authorization}`; trailing slash on `url` is load-bearing (bare path answers 307) | `autonomous-grid cli/mcp_config.py:30-31,94` |
+| `--harness <engine>` is a *print style* (mutually exclusive with `--json`); the positional is the **grid name**, not a harness name | `cli/parser.py:1642-1672` |
+| `mcp config` renews the token when it is within 30 days of `exp` and persists the renewal; `info --env` never renews | `cli/mcp_config.py:57,139-171` |
+| Token TTL 365 days; carries `member_epoch`/`network_epoch`, so it can be revoked before `exp` | `grid-apis grid_networks/tokens.py:23,254-274` |
+
+So the private server is not in the path at all: the agent talks to the control plane directly, and
+web search works whether the grid node is asleep, behind a LAN address, or reached through an SSH
+tunnel.
+
+### What the harness already has
+
+`cli/src/lib/gridLaunch.ts` already wires an MCP server into six of its seven engines whenever
+`GridLaunchOverride.mcpUrl` is set (`gridLaunch.ts:109`), each through the vendor's own config
+contract, with the key reaching the process **only through the environment** (`GRID_API_KEY`, or
+`GRID_MCP_AUTHORIZATION` for codex); argv and config files carry the variable *name*
+(`gridWebMcp.ts:90,143,193,309`). `pi` has no MCP client (`grid mcp config --harness pi` refuses,
+too). `--disallowedTools=WebSearch` is already appended to every claude grid launch
+(`gridLaunch.ts:522-527`). Retarget is a pane respawn (`respawn-pane -k` + `--resume`,
+`cli.ts:3808-3900`), and `gridEnvVarNames()` — derived from a probe override that includes
+`mcpUrl` (`gridLaunch.ts:853,866`) — already clears the MCP variables on the way back to the
+subscription model.
+
+**The gap is one function.** `resolveGridTarget()` (`cli/src/lib/gridModels.ts:109-129`) returns
+`{ networkId, networkName, baseUrl, apiKey, model }` and never fills `mcpUrl`, so on the desktop path
+no engine ever attaches the server. Everything downstream is built and tested; nothing upstream
+feeds it.
+
+### Where the word "grid" leaks
+
+The grid is an implementation detail; the user's vocabulary is "Subscription" and "Local"
+(`desktop/lib/widgets/grid_model_picker.dart:121,136`). Today it leaks in four places:
+
+1. The MCP server name `grid-web` (`gridWebMcp.ts:54`) — tools appear as `mcp__grid-web__web_search`
+ in the engine's permission prompts and `/mcp`.
+2. The tool descriptions the model reads: "Search the live web **through your grid**." /
+ "Read … **through your grid**." (`grid-apis web_mcp.py:335,362`).
+3. The 401 body: "This **grid** credential was refused. Run `**grid** mcp config <grid>` …"
+ (`web_mcp.py:82-85`), which Claude Code prints verbatim when the server refuses a connection.
+4. One desktop string: `'No grid on this account yet — sign in again to set one up.'`
+ (`grid_model_picker.dart:146`).
+
+The harness cannot intercept 2 and 3 — MCP traffic runs engine ↔ control plane, not through the
+daemon — so those are fixed at the source.
+
+## Design principles
+
+**1. Same seam, one more call.** Web search arrives as one more `grid` subprocess with `--json`,
+on the seam plan 004 established. No HTTP client in the daemon, no MCP proxy, no probe.
+
+**2. One key.** The MCP server accepts the inference token. There is no second secret, no second
+env var, and nothing new to keep out of argv or logs — the existing property holds unchanged.
+
+**3. Degrade, never refuse.** Inference is the feature; web search is an accessory. If the MCP
+config cannot be obtained, the retarget still happens, the native tools are still disabled (they are
+dead regardless), and the agent is marked so the user can see why it cannot search.
+
+**4. The user never reads "grid".** Not in a menu, not in a tool name, not in a tool description,
+not in an error. Where the harness cannot rewrite the text, the text changes at its source.
+
+**5. State, not events.** The MCP URL is cached against the token's own `exp`, not a timer; the
+degraded condition is a field on the agent, not a toast. Both are correct again after a reconnect or
+a daemon restart without replaying anything.
+
+## Architecture
+
+```
+desktop daemon grid CLI / control plane
+ │ agent_retarget {model} │
+ ├──────────────────────────────▶│ resolveGridTarget(gridName, model)
+ │ │ cache[gridName]? miss, or exp − now < 30 d
+ │ │ └─▶ grid mcp config <gridName> --json ──▶ { url, authorization }
+ │ │ store { mcpUrl, exp }; token discarded
+ │ │ grid --remote info <gridName> --env ───────▶ OPENAI_BASE_URL + KEY
+ │ │ grid --remote ls ──────────────────────────▶ network id
+ │ │ gridLaunch.ts: MCP "harness" + native web tools off
+ │ │ respawn-pane -k -e … (--resume)
+ │◀── agent_synced {agent.grid.webSearch: on|unavailable|unsupported}
+ │
+ │ engine ── MCP (bearer = inference token) ──▶ https://<api>/v1/grid/web-mcp/
+ │ mcp__harness__web_search / web_read
+```
+
+---
+
+## Change 1 — `resolveGridTarget()` fills `mcpUrl`, with a cache keyed by token expiry
+
+`cli/src/lib/gridModels.ts`; a small new `cli/src/lib/gridWebSearchCache.ts` (or a module-level
+map in the same file if it stays under a screen).
+
+**The call.** `grid mcp config <gridName> --json` (note: `--json`, not `--harness`; the positional is
+the grid name from `machine_meta`). Parse `url` — keep it exactly, trailing slash included — and
+decode `exp` from the JWT in `authorization` (base64url middle segment, `JSON.parse`, read `exp`;
+the same offline check the grid CLI does in `cli/grid_credential.py:96-98`). **Discard the token.**
+The key the launch uses comes from `info --env`, as today.
+
+**Order on a miss:** `mcp config --json` first, because it may renew the token and persist it; then
+`info --env`, which then reads the renewed token. The other order can hand inference an older
+token than the one MCP holds — both valid, but a latent mismatch nobody would look for.
+
+**The cache.** `Map<gridName, { mcpUrl, exp }>`, in daemon memory. A retarget re-runs `mcp config`
+only when there is no entry or `exp − now < 30 days`. The margin equals `mcp config`'s own renewal
+margin on purpose: a re-run inside it *always* renews, so the daemon is now the thing that keeps a
+harness user's grid token alive (nothing else on the harness path renews). A smaller margin would
+re-run without renewing and re-run again tomorrow. An undecodable token counts as expired (re-run
+every retarget — safe, slow, loud in the log). Dropped whole on harness sign-out (= grid sign-out);
+keyed by name so a re-minted grid name never hits a stale entry. Failures are not cached.
+
+**Return shape.** Add `mcpUrl?: string` to the resolved target. Undefined means "could not get one";
+the reason (`GRID_CLI_OUTDATED`, `GRID_CLI_MISSING`, not logged in, grid not found) goes to the
+daemon log only. `info --env` failing still collapses to `null` → `GRID_UNAVAILABLE`, exactly as
+today; this plan does not touch the error path (interview Q13).
+
+Revocation before `exp` (epoch bump) is outside every cache's reach and outside the daemon's: the
+401 happens engine ↔ control plane. The engine shows it; the daemon never sees it.
+
+---
+
+## Change 2 — server name `harness`, native web tools off
+
+`cli/src/lib/gridWebMcp.ts`, `cli/src/lib/gridLaunch.ts`, `gridLaunch.spec.ts`.
+
+- `GRID_MCP_SERVER_NAME = 'harness'`. Tools read `mcp__harness__web_search` / `web_read` in Claude
+ Code, `harness` in `/mcp`, `mcp_servers.harness` in codex, and so on. Fixtures follow.
+- Claude Code: `--disallowedTools=WebSearch,WebFetch` (verify the comma form on the installed
+ version; fall back to two `=` arguments). Keep the `=` form — the flag is variadic and the doc
+ comment explaining that stays; the sentence about `WebFetch` goes.
+- Codex: turn off the native `web_search` feature through its config knob via `-c` (the exact key
+ is verified at implementation against the installed codex, not assumed here).
+- opencode / copilot / hermes / grok: best-effort — disable a native web tool only where a
+ documented knob exists; do not invent one.
+- These flags are applied on **every** grid launch, with or without `mcpUrl` — the native tools are
+ dead either way.
+- `pi` gets no MCP and is marked `unsupported` (Change 3).
+
+---
+
+## Change 3 — the status reaches the desktop
+
+`cli/src/lib/launchOverrides.ts` (`buildLaunchOverrides`), `cli/src/cli.ts` (`gridConfigDirFor`,
+`announceSession`), `cli/src/registry.ts`, `desktop/lib/core/models.dart`,
+`desktop/lib/widgets/grid_model_picker.dart`, the pane header tooltip.
+
+`agent.grid` in `agent_synced` gains `webSearch: 'on' | 'unavailable' | 'unsupported'`:
+
+| Value | When |
+|---|---|
+| `on` | `mcpUrl` present and the engine wired it |
+| `unavailable` | `resolveGridTarget` had no `mcpUrl` (Change 1 failure) |
+| `unsupported` | engine has no MCP client (`pi`), or Hermes on a machine with `/etc/hermes`, where the managed overlay is dropped (`cli.ts:3353-3358`) |
+
+The value is decided where the launch is built, stored with the launch in the registry (which
+already holds the full grid launch, 0600, never logged), and emitted by `announceSession` — so it
+survives reconnects and is absent again the moment the agent returns to its subscription model.
+
+Desktop: `Agent.gridWebSearch`; a subtitle under the Local model row in the picker and the same
+sentence in the pane-header tooltip ("Where this agent runs"): *Web search unavailable* /
+*Web search not supported by this engine*. Nothing for `on`. No new frame, no toast, and the
+retarget callers in `app_state.dart:3057-3092` are left as they are.
+
+---
+
+## Change 4 — the tools get the native cards
+
+`cli/src/lib/normalize.ts` (`:195-196,311`), per-engine normalizers, `commander.ts:99` colours.
+
+`mcp__harness__web_search` → the canonical `WebSearch` card; `mcp__harness__web_read` → `WebFetch`.
+The user sees an agent searching the web, not which road it took — and the server name never
+reaches a card even if something upstream slips. Claude Code and Codex are required (Codex's MCP
+tool spelling is checked at implementation); other engines best-effort.
+
+---
+
+## Change 5 — the one desktop leak, and three codes to check
+
+`desktop/lib/widgets/grid_model_picker.dart:146` → `'No local models on this account yet — sign in
+again to set them up.'`. While there: `INVALID_GRID`, `TMUX_TOO_OLD_FOR_GRID`, `GRID_CONFIG_FAILED`
+pass through `_creationFailureMessage` (`app_state.dart:4033-4037`) — confirm they map to a sentence
+and are not shown raw.
+
+---
+
+## Change 6 — three strings in grid-apis (separate PR, ships first)
+
+`grid-apis grid_networks/web_mcp.py` and `tests/test_web_mcp.py`.
+
+| Line | Now | After |
+|---|---|---|
+| `:335` | Search the live web through your grid. | Search the live web. |
+| `:362` | Read the main text of up to five web pages through your grid. | Read the main text of up to five web pages. |
+| `:82-85` | This grid credential was refused. Run `grid mcp config <grid>` to get a fresh one, and paste it into this MCP server's configuration. | This credential was refused or has expired. Refresh it and update this MCP server's configuration. |
+
+Neutral text costs direct `grid` users nothing and is the only way to keep principle 4 on a path the
+harness cannot intercept. No client detection, no per-client text.
+
+---
+
+## Failure modes
+
+| Condition | Where | What happens |
+|---|---|---|
+| `grid` too old for `mcp config` (argparse exit 2 → `GRID_CLI_OUTDATED`) | Change 1 | retarget proceeds; `webSearch: unavailable`; reason in daemon log |
+| Not logged in / grid not in credential store / grid not found | Change 1 | same |
+| Token expired and no refresh token (`mcp config` refuses) | Change 1 | same — and inference will fail on its own, as today |
+| `info --env` fails | today's path | `GRID_UNAVAILABLE`, pane untouched |
+| Control plane has `GRID_WEB_MCP_ENABLED` off (404) | engine | attached blind; the engine reports the server as failed to connect; no daemon involvement |
+| Token revoked before `exp` (401) | engine | engine prints the (now neutral) 401 text; next retarget after `exp − 30 d` renews |
+| Allowance exhausted / burst / vendor busy | model | `isError` tool result; the model relays the sentence; harness parses nothing |
+| Engine without MCP client (`pi`) / Hermes overlay dropped | Change 3 | `webSearch: unsupported` |
+| Daemon restart | Change 1 | cache empty; one extra `mcp config` on the next retarget |
+
+## Testing
+
+Follow `cli/src/lib/gridEnsure.spec.ts:41-57`: a plan-driven fake `grid` injected through
+`HARNESS_GRID_BIN`, logging calls. There is no `gridModels.spec.ts` today; this plan adds it.
+
+1. `gridModels.spec.ts` — `mcp config` succeeds → `mcpUrl` set, trailing slash intact, and the
+ fake was called **before** `info --env`; exit 2 → no `mcpUrl`, retarget still resolves;
+ second call with a fresh entry → `mcp config` **not** called; entry with `exp` inside 30 days →
+ called again; undecodable token → called every time; sign-out → map empty. Assert the token
+ from `authorization` is never stored and never logged.
+2. `gridLaunch.spec.ts` — server name `harness` in every engine's config; claude carries both
+ disallowed tools with and without `mcpUrl`; codex carries its native-off knob; no MCP block when
+ `mcpUrl` is absent; `pi` and dropped-Hermes yield `unsupported`; no key in argv or on disk
+ (existing assertions, kept).
+3. `normalize` tests — `mcp__harness__web_search` / `web_read` map to the `WebSearch` / `WebFetch`
+ cards for Claude Code and Codex.
+4. Desktop — `webSearch` parsed from `agent_synced`; picker subtitle and tooltip for both degraded
+ values; the leak string gone (`grid_model_picker_test.dart`).
+5. grid-apis — `tests/test_web_mcp.py` updated for the three strings.
+6. Manual end-to-end, Claude Code then Codex, over the SSH tunnel: the model calls
+ `web_search` and `web_read`; the native tools are absent from its tool list; the cards render
+ as native; `/mcp` shows `harness`; switching back to the subscription model restores the native
+ tools. No automated e2e — it needs a live grid.
+
+## Sequencing
+
+| Phase | Contents | Ships alone? |
+|---|---|---|
+| 0 | Change 6 (grid-apis strings) | yes — independent, three lines |
+| 1 | Change 1 + Change 2 (daemon: `mcpUrl`, cache, name, native off) | yes — the feature, invisible until Change 3 |
+| 2 | Change 3 + Change 4 + Change 5 (status field, cards, leak), CLI and desktop together | yes |
+
+Nothing in phase 1 depends on phase 0 technically; shipping 0 first only means no harness user ever
+sees the old strings.
+
+## Decisions from the design interview (2026-09-15)
+
+| # | Decision |
+|---|---|
+| Q1 | Attach automatically on every retarget to a Local model; no toggle |
+| Q2 | Degrade, do not refuse, when the MCP config cannot be obtained |
+| Q3 | Disable both native tools (search + fetch), replaced 1:1 by `web_search` + `web_read` |
+| Q4 | Claude Code first-class, Codex second; other engines best-effort |
+| Q5 | MCP server name `harness` |
+| Q6 | Quota/burst errors are relayed by the model; the harness parses nothing |
+| Q7 | Unit tests on the fake-`grid` convention; manual e2e; no automated e2e |
+| Q8 | Out of scope: `agent_create` accepting `gridModel`; removing the daemon's acceptance of a full `payload.grid` with `apiKey` |
+| Q9, Q16, Q17 | Cache in daemon memory keyed by grid name; re-run when `exp − now < 30 d`; drop on sign-out |
+| Q10, Q19, Q20 | Fix "grid" wording at the source in grid-apis; three strings; ships first |
+| Q11 | One key (the inference token); `mcp config` supplies only the URL; called before `info --env` on a miss |
+| Q12 | No endpoint probe; attach blind |
+| Q13 | Do not change how retarget errors are surfaced (daemon flattens, desktop swallows) |
+| Q14 | Map the MCP tools onto the native `WebSearch` / `WebFetch` cards |
+| Q15 | Fix the picker's "No grid on this account" string here |
+| Q18 | Degraded status as `agent.grid.webSearch` on `agent_synced`; picker subtitle + tooltip |
+
+## Open questions
+
+None blocking. Verified at implementation, not decided here: the comma form of
+`--disallowedTools` on the installed Claude Code; the codex config key that disables native
+`web_search`; codex's spelling of MCP tool names in its event stream (for Change 4); which daemon
+path learns of sign-out (for the cache drop).
diff --git a/docs/plans/2026-09-15-006-harness-grid-websearch-e2e-plan.md b/docs/plans/2026-09-15-006-harness-grid-websearch-e2e-plan.md
new file mode 100644
index 000000000..8428b874f
--- /dev/null
+++ b/docs/plans/2026-09-15-006-harness-grid-websearch-e2e-plan.md
@@ -0,0 +1,244 @@
+# Web search on a Local model — manual end-to-end plan
+
+Status: **run 2026-09-15, all runs green** — see §Outcome · written to be RUN BY AN AGENT from a terminal, no GUI required
+Verifies: `2026-09-15-005-harness-grid-websearch-plan.md` §Testing item 6, and ticket 02's two
+live-grid bullets (the `harness` server appears, `web_search` / `web_read` answer, the native tools
+are gone, the cards are native, returning to the Subscription model restores everything).
+Code under test: ticket 02 = `7a1660d`, merged with `origin/main` as `56b5e2b` on
+`feat/harness-grid-websearch`. Ticket 01 (neutral strings) is live on the dev control plane.
+
+## Facts this plan rests on (read on 2026-09-15, not assumed)
+
+| Fact | Evidence |
+|---|---|
+| Dev control plane `https://api-grid.autonomousdev.xyz`; `grid-apis.service` restarted 06:21 with `GRID_WEB_MCP_ENABLED=1`; its pinned CLI is `/opt/grid-public-0.3.46/bin/grid` | nginx `server_name`, `/etc/grid-apis/grid-apis.env` on `grid-dev` |
+| Dev mount answers an unauthenticated POST `401 {"detail": "This credential was refused or has expired. Refresh it and update this MCP server's configuration."}` — ticket 01's text; prod still answers the old "grid" sentence | `curl -X POST …/v1/grid/web-mcp/` on both |
+| `harness login` hands the **Autonomous account access token** (prod SSO) to `grid login --harness` on stdin; `grid` POSTs it in the body to `<plane>/v1/grid/auth/harness`; grid-apis introspects it at `GRID_ACCOUNT_API_BASE_URL`, **unset on grid-dev → production `apiv2.autonomous.ai`** — so a prod harness sign-in is exactly what dev accepts | `cli.ts:500-520`, `gridHandoff.ts:90`, autonomous-grid `remote/control_plane.py:75-97`, grid-apis `handler.py:1593`, `account_api.py:55` |
+| The plane `grid` talks to is `explicit > stored api_url > GRID_CONTROL_PLANE_URL > prod`; `GRID_HOME` moves the whole credential home. This Mac's `~/.grid` is signed into prod | autonomous-grid `remote/credentials.py:154`, `shared/paths.py:22`; `grid --remote mcp config` listing |
+| Only `harness login` (not `harness grid login`) mints the grid name (`POST /api/grid/name`, `<email-local-part>-<8 hex>`) and runs `ensureHarnessGrid` (`sync`/`ls`/`start`/`sync`). An already-signed-in `harness login` skips the browser and still does both | `cli.ts:525-580` (`succeed` → `attachGridToSignIn`), `cli.ts:688-722` |
+| This repo's "local stack" (`desktop/scripts/start-terminal-local-manual.sh`) runs the backend in **API-key mode with no SSO** and needs a sibling `../autonomous-code` (absent here) — so it can produce no account token and no hand-off | the script; `ls ../../autonomous-code` empty |
+| The installed `harness` is `~/.harness/cli/cli.js` v0.2.20-dev (Sep 14, predates 02); a daemon started from `node cli/dist/cli.js` **never self-updates** (inode check) | `cli.ts:4194-4201` |
+| The daemon serves a local WebSocket at `http://127.0.0.1:18473/api/local-ws` — the transport the desktop uses on this machine. Handshake: no `Origin` header, first frame `machine_select {machineId, localProtocolVersion: 1}` → `connected`; then any frame; replies are `<type>_result {requestId, …}`; `e2ee: false`. The picker's model list is the frame `grid_models_list` → `{models: [{id, node}]}` | `localWsServer.ts:250-284`, `backendSocket.ts:985-991,1420-1426`; `curl 127.0.0.1:18473/api/status` → `machineId` |
+| Live agents today: two Claude Code panes `%1`, `%2` (cwd `BC_whitepapers`) on the DEFAULT tmux server — not to be touched. A registry row carries `agentId`, `engine`, `tmuxPane`, `sessionId`, `transcriptPath` | `~/.harness/cli/data/registry.json`, `tmux list-panes -a` |
+| Codex is signed in on this Mac ("Logged in using ChatGPT") | `codex login status` |
+| Text models running on the 8x5090 boxes (via `cmc-8x4090-noproxyjump`): `cmc-8x50903:8100` and `:8200` `qwen/qwen3.6-35b-a3b` (vLLM, `--enable-auto-tool-choice --tool-call-parser qwen3_xml`, 0 % util); `cmc-8x50902:9096` `Qwen/Qwen3.8-27B-FP8` (`qwen3_coder`, serving prod, GPUs ~95 %); `cmc-8x50901` DeepSeek-V4-Flash on loopback `:1919` with `--max-running-requests 1`, GPUs at 100 % | `nvidia-smi`, `ps`, `curl /v1/models` on each |
+| A grid node **polls** the relay for work; the relay never dials the node, so a Mac behind NAT joining a loopback endpoint is a supported shape | autonomous-grid `remote/serve.py:4-6` |
+
+## Decisions
+
+**D1 — Harness: this branch's CLI, the prod harness backend; grid: dev.** The harness backend's
+only jobs here are SSO, minting the grid name, and relaying frames — prod does all three and this
+Mac is already signed in. A local backend cannot take part (no SSO, see facts). The daemon is run
+from `cli/dist/cli.js` with a dev grid home, on the existing data dir so the machine identity and
+session are reused:
+
+```sh
+export GRID_HOME=~/.grid-dev # fresh home → no stored prod api_url; ~/.grid untouched
+export GRID_CONTROL_PLANE_URL=https://api-grid.autonomousdev.xyz
+export HARNESS_GRID_BIN=/tmp/grid-shim # Setup S4 — logs every grid argv; drop it to skip
+```
+
+Every `harness`/`node cli/dist/cli.js` invocation below, and `grid join`, runs with these exported.
+`gridExec` and `handOffToGrid` spawn `grid` with the daemon's own environment, so a daemon started
+from a shell without `GRID_HOME` talks to prod and the run is silently wrong.
+
+**D2 — Model: `qwen/qwen3.6-35b-a3b` on `cmc-8x50903:8100`, tunnelled.** Idle, tool-calling on,
+fast MoE. Fall back to `cmc-8x50902:9096` (`Qwen/Qwen3.8-27B-FP8`) if it fumbles two-step tool use.
+Skip DeepSeek on 50901 (one busy slot).
+
+**D3 — Driver: the daemon's local WebSocket, not the app.** A small Node script speaks the same
+frames the desktop sends (`grid_models_list`, `agent_create`, `agent_retarget`, `agent_delete`);
+prompts go in with `tmux send-keys`, the pane is read with `tmux capture-pane`, and the transcript
+cards are proven by replaying the engine's transcript through the daemon's own normalizer
+(`dist/lib/normalize.js`, `dist/engines/codex/normalizer.js`) — the code path that feeds the
+desktop. Running the desktop app alongside is optional (to see the cards with eyes); nothing here
+depends on it.
+
+## Setup
+
+**S1 — build and swap the daemon.**
+```sh
+cd ~/Projects/autonomous-harness/cli && git rev-parse --short HEAD # 56b5e2b or later
+npm run build # per-file dist/: dist/cli.js (daemon) + dist/lib/*.js (replay)
+harness stop # the installed v0.2.20-dev daemon
+node dist/cli.js start # env from D1 exported; self-update is off for a checkout run
+node dist/cli.js status # running · backend wss://harness-api.autonomous.ai
+tail -f ~/.harness/cli/data/harness.log # keep open
+```
+Expect the log's first lines to include `[update] self-update off · running a dev/repo build`.
+
+**S2 — sign the grid side into dev and get the harness grid created there.**
+```sh
+node dist/cli.js login # already signed in → no browser; runs the hand-off, mints the name, ensures the grid
+```
+Expect on stderr `Created your private grid '<name>'` (or nothing, if it existed). Then:
+```sh
+grid --remote ls --json | jq -r '.[] | "\(.grid) \(.type) \(.id)"' # GRID_HOME=~/.grid-dev: the <name>, permissioned-public
+grid --remote mcp config # listing: url: https://api-grid.autonomousdev.xyz/v1/grid/web-mcp/ — no token
+env -u GRID_HOME grid --remote ls --json | jq -r '.[].grid' # prod home: <name> is NOT there — the isolation held
+```
+The daemon must be RESTARTED after this (S1's daemon connected before the name existed and
+`machine_meta.gridName` is pushed on connect): `node dist/cli.js stop && node dist/cli.js start`.
+Then `curl -s 127.0.0.1:18473/api/status | jq .connected` → `true`.
+
+**S3 — tunnel and join the model.** Own tmux window, left running:
+```sh
+ssh -N -L 8100:127.0.0.1:8100 cmc-8x50903
+curl -s http://127.0.0.1:8100/v1/models | jq -r '.data[].id' # qwen/qwen3.6-35b-a3b
+grid --remote join -m qwen/qwen3.6-35b-a3b --at http://127.0.0.1:8100/v1 <name> # blocks; GRID_HOME=~/.grid-dev — ⚠️ WITH /v1: `remote/probe.py` posts to `<at>/chat/completions`, so a bare host:port 404s every capability probe and the node registers `tools: false` (relay answers `400 No active provider for this model supports tools`)
+grid --remote models <name> --json | jq -c '.[] | {model, node, engine}' # the model, node = this Mac
+```
+The id the engine must be handed is the RELAY's spelling — `grid models` lowercases it
+(`gridModels.ts`); read it from the daemon's own list instead: driver `models` below.
+
+**S4 — the `grid` argv shim** (what makes the cache and the call order observable):
+```sh
+cat > /tmp/grid-shim <<'EOF'
+#!/bin/sh
+printf '%s\n' "$*" >> /tmp/grid-calls.log
+exec /Users/macbookpro/.local/bin/grid "$@"
+EOF
+chmod +x /tmp/grid-shim; : > /tmp/grid-calls.log
+```
+(`HARNESS_GRID_BIN` is read by `gridExec`, i.e. the daemon's calls; the hand-off in S2 uses PATH.)
+
+**S5 — the driver.** `/tmp/hd.mjs`, run from `cli/` so `ws` resolves:
+```js
+// node /tmp/hd.mjs <cmd> [args] — models | create <engine> <cwd> | retarget <agentId> <model> | clear <agentId> | delete <agentId>
+import { WebSocket } from 'ws'
+const [cmd, ...a] = process.argv.slice(2)
+const status = await (await fetch('http://127.0.0.1:18473/api/status')).json()
+const ws = new WebSocket('ws://127.0.0.1:18473/api/local-ws') // no Origin header: loopback trust
+const once = (t) => new Promise((res) => { const h = (raw) => { const f = JSON.parse(raw); if (f.type === t) { ws.off('message', h); res(f.payload) } }; ws.on('message', h) })
+await new Promise((r) => ws.once('open', r))
+ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: status.machineId, localProtocolVersion: 1 } }))
+await once('connected')
+const rpc = async (type, payload) => { const requestId = `hd-${Date.now()}`; const p = once(`${type}_result`); ws.send(JSON.stringify({ type, payload: { requestId, ...payload } })); return p }
+const frames = {
+ models: () => rpc('grid_models_list', {}), // { models: [{id, node}] } — the picker's list
+ create: () => rpc('agent_create', { engine: a[0], cwd: a[1], bypassPermission: true }),
+ retarget: () => rpc('agent_retarget', { agentId: a[0], gridModel: a[1] }),
+ clear: () => rpc('agent_retarget', { agentId: a[0], clearGrid: true }),
+ delete: () => rpc('agent_delete', { agentId: a[0] }),
+}
+console.log(JSON.stringify(await frames[cmd](), null, 2)); ws.close()
+```
+`bypassPermission: true` so the MCP tool call is not parked on a permission prompt nobody is there
+to answer — hence a throwaway `cwd` under `/tmp`.
+
+**S6 — the pane and the transcript.** After `create`, the reply's `agent.agentId` names the row in
+`~/.harness/cli/data/registry.json`; its `tmuxPane` (`%N`) is on the default tmux server:
+```sh
+tmux send-keys -t %N 'Search the web for the current Bitcoin price and read the top result.' Enter
+sleep 20; tmux capture-pane -p -t %N -S -60
+```
+Transcript replay (the cards): the row's `transcriptPath` once the session is bound (Claude Code:
+`~/.claude/projects/<cwd with / → ->/<sessionId>.jsonl`; Codex: `~/.codex/sessions/YYYY/MM/DD/…`).
+```sh
+node -e 'import("./dist/lib/normalize.js").then(m => { const lines = require("fs").readFileSync(process.argv[1],"utf8").split("\n").filter(Boolean); for (const e of m.messagesToEvents(lines)) if (e.type==="tool_start"||e.type==="tool_end") console.log(e.type, e.payload.tool, JSON.stringify(e.payload.input??"").slice(0,80)) })' <transcript.jsonl>
+```
+
+## Run A — Claude Code
+
+| # | Do | Expect | Pins |
+|---|---|---|---|
+| A1 | `mkdir -p /tmp/e2e-claude && node /tmp/hd.mjs create claude /tmp/e2e-claude` → `AGENT`; prompt via S6: *"What is on the front page of news.ycombinator.com right now?"* | Pane answers; replay shows `tool_start WebSearch` / `WebFetch` (native). Baseline. | — |
+| A2 | `node /tmp/hd.mjs models` → copy the exact `id`; `node /tmp/hd.mjs retarget $AGENT <id>` | Reply `{retargeted: true}`. Pane respawned with `--resume`; the A1 answer still on screen. Log: `[grid] claude -> <name> (grid-…) · <id>`, **no** `web tools unavailable`. `/tmp/grid-calls.log`: `--remote mcp config <name> --json` **above** `--remote info <name> --env`, then `--remote ls --json`. | 02 §4 |
+| A3 | `PID=$(pgrep -n -f 'claude .*--resume'); ps -Eww -o args= -p $PID` (argv, then env; own processes only — NOT `tmux show-environment`: a retarget sets variables on the respawned PROCESS, `tmuxBackend.ts:178`) | argv has `--disallowedTools=WebSearch,WebFetch` and `--mcp-config {"mcpServers":{"harness":{"type":"http","url":"https://api-grid.autonomousdev.xyz/v1/grid/web-mcp/","headers":{"Authorization":"Bearer ${GRID_API_KEY}"}}}}` — the variable NAME; the env part has `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `GRID_API_KEY`. `ps -o args= -p $PID | grep -c eyJ` → 0. | 02 §7, §8 |
+| A4 | `tmux send-keys -t %N '/mcp' Enter; sleep 3; tmux capture-pane -p -t %N`; then select `harness` (`Enter`), capture; `Escape` ×2 | One server **`harness`** · connected · tools `web_search`, `web_read`; descriptions *"Search the live web."* / *"Read the main text of up to five web pages."* — no "grid" anywhere on screen. | 02 §1, ticket 01 |
+| A5 | Prompt: *"Which web tools do you have? List their exact tool names and nothing else."* | Names `mcp__harness__web_search`, `mcp__harness__web_read`; does NOT name `WebSearch` or `WebFetch`. | 02 §1 |
+| A6 | Prompt: *"Search the web for the current Bitcoin price and read the top result."*; wait; capture; replay | Pane: two tool calls with real results, no `API Error: 400 Unsupported tool type`, no `503`. Replay: `tool_start WebSearch {"query":…}` then `tool_start WebFetch {"urls":[…],"url":…}` — never `mcp__harness__…`. | 02 §1, §9 |
+| A7 | `node /tmp/hd.mjs clear $AGENT` | `{retargeted: true}`; new pid: `ps -Eww` has none of `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`, `GRID_API_KEY`; argv has no `--disallowedTools`, no `--mcp-config`; `/mcp` lists no `harness`; A1's prompt replays as native `WebSearch`. | 02 §10 |
+| A8 | `node /tmp/hd.mjs retarget $AGENT <id>` again | `/tmp/grid-calls.log` gains `info --env` and `ls` but **no second** `mcp config` — the entry is fresh (365-day token). | 02 §5 |
+| A9 | `node /tmp/hd.mjs delete $AGENT` | Pane gone from `tmux list-panes -a`. | cleanup |
+
+## Run B — Codex
+
+| # | Do | Expect | Pins |
+|---|---|---|---|
+| B1 | `mkdir -p /tmp/e2e-codex && node /tmp/hd.mjs create codex /tmp/e2e-codex`; A1's prompt | Baseline answer; replay (Codex normalizer) shows `WebSearch`. | — |
+| B2 | `retarget $AGENT <id>`; `PID=$(pgrep -n -f 'codex .*-c model_provider'); ps -Eww -o args= -p $PID` | argv: `-c web_search="disabled"`, `-c mcp_servers.harness.url="https://api-grid.autonomousdev.xyz/v1/grid/web-mcp/"`, `-c mcp_servers.harness.env_http_headers.Authorization="GRID_MCP_AUTHORIZATION"`; env: `GRID_API_KEY`, `GRID_MCP_AUTHORIZATION=Bearer …`; no token in argv. | 02 §2, §7 |
+| B3 | `/mcp` in the pane | `harness` with two tools. | 02 §2 |
+| B4 | A6's prompt; replay the rollout through `dist/engines/codex/normalizer.js` (`new CodexNormalizer('replay')`, `ingest` each line) | Calls spelled `mcp__harness__web_search` / `web_read` (or `name`+`namespace: mcp__harness`; or code-mode `tools.mcp__harness__…(…)`) — replay shows `WebSearch` / `WebFetch` regardless. | 02 §2, §9 |
+| B5 | `clear $AGENT`; `ps -Eww` on the new pid; `delete $AGENT` | No `GRID_API_KEY`, `GRID_MCP_AUTHORIZATION`; argv has no `web_search=`, no `mcp_servers.harness`. | 02 §10 |
+
+## Run C — degraded path
+
+```sh
+cat > /tmp/grid-old <<'EOF'
+#!/bin/sh
+case "$*" in *"mcp config"*) echo "grid: error: argument command: invalid choice: 'mcp'" >&2; exit 2;; esac
+exec /Users/macbookpro/.local/bin/grid "$@"
+EOF
+chmod +x /tmp/grid-old
+node dist/cli.js stop && HARNESS_GRID_BIN=/tmp/grid-old node dist/cli.js start
+```
+`create claude` → `retarget` → reply `{retargeted: true}` (no `error`); log has `[grid] web tools
+unavailable for <name> · This machine's grid is older than 0.3.36 …`; argv still carries
+`--disallowedTools=WebSearch,WebFetch` but no `--mcp-config`; `/mcp` lists nothing; a plain prompt
+still answers (inference intact). Pins 02 §3, §6 live. Then `delete`, and restart with the S4 shim.
+
+## Evidence to keep
+
+Per run: the daemon log lines, `/tmp/grid-calls.log`, one `ps -o args=` per direction (argv only —
+never paste the `-E` env part, it holds the token), the `/mcp` capture, the replay output, and
+versions (`claude --version`, `codex --version`, `grid version`, `node dist/cli.js version`).
+Paste under the two live bullets in the ticket and tick them.
+
+## Teardown
+
+```sh
+node /tmp/hd.mjs delete <any test agent left>
+grid --remote leave <name> # GRID_HOME=~/.grid-dev; unregisters this Mac's node; then close the ssh tunnel
+node dist/cli.js stop
+harness start # the installed daemon, prod grid home, as before
+harness status && tmux list-panes -a # %1 and %2 still there
+```
+The dev grid `<name>` and `~/.grid-dev` may stay; they cost nothing and the next run reuses them.
+
+## If it does not work
+
+| Symptom | Where to look |
+|---|---|
+| `machine_select` closes with 4403 | `machineId` must be `/api/status`'s; `localProtocolVersion` must be `1`; no `Origin` header |
+| `agent_retarget_result` has `error: GRID_UNAVAILABLE` | `grid-calls.log`: did `info --env` run with `GRID_HOME=~/.grid-dev`? Is `<name>` in `grid --remote ls` there? Was the daemon restarted after S2 (`machine_meta.gridName`)? |
+| `/mcp` shows `harness` **failed** | The URL in argv must end in `/`; `curl -X POST <url>`: 404 → `GRID_WEB_MCP_ENABLED`, 401 → token not this grid's (`node dist/cli.js grid login` again) |
+| Inference `503 no_providers_available` | The id is not the relay's spelling — use the `models` driver output, not `ollama`/`vllm`'s |
+| `WebSearch` still offered (A5) | The daemon on 18473 is the installed one: `curl …/api/status | jq .version` must NOT be `0.2.20-dev.bae1fc6` |
+| Replay shows `mcp__harness__web_search` | `npm run build` was skipped — `dist/lib/normalize.js` predates 02 |
+| A8 shows a second `mcp config` | Token within 30 days of `exp` or undecodable: `grid mcp config --json | jq -r .authorization | cut -d' ' -f2 | cut -d. -f2 | base64 -d` |
+| `grid login --harness` answers 401/403 from dev | The harness session is not a prod one (`~/.harness/cli/data/auth-session` says `autonomousEnv`) |
+| `grid join` says the engine is unreachable | The tunnel shell closed, or the port is wrong (`:8100` on 50903, `:9096` on 50902) |
+
+## Out of scope here
+
+`agent.grid.webSearch` and the picker/tooltip text (ticket 03); `agent_create` straight onto a
+Local model (plan Q8); shipping ticket 01 to prod; the desktop app itself (D3).
+
+## Outcome (run 2026-09-15 15:12–15:15, by the agent, from this terminal)
+
+**Run A (Claude Code 2.1.272) ✅ · Run B (Codex 0.154.0) ✅ · Run C (degraded) ✅.** Ticket 02's two
+live bullets are ticked with the evidence below. Deviations from the plan as written, and two
+findings that are not this ticket's:
+
+| What | Detail |
+|---|---|
+| No tunnel needed | The dev control plane already serves `qwen/qwen3.8-27b` and `deepseek/deepseek-v4-flash-0731` (`owned_by localagi-p2p`) into a freshly created grid; both answer `tool_calls` through the relay in 2–8 s. S3 stays as the fallback. |
+| Prod harness backend has no `/api/grid/name` | `harness login` said `Could not read this account's grid name (HTTP 404); skipping grid setup` — the `feat/harness-grid` backend is not on prod. The grid `kelvin-e2e09150` (`grid-bcba99c5d54a44a5`) was created on dev with the daemon's own `ensureHarnessGrid` (`dist/lib/gridEnsure.js`) and its name injected as a `machine_meta` frame over the local WS (driver `meta`). Every backend reconnect wipes it (the prod backend's `machine_meta` carries no `gridName`), so `meta` is re-sent before each retarget. |
+| `~/.grid-dev` was not fresh | It held a dev session for a different account; the hand-off replaced it with this account's. Prod `~/.grid` untouched throughout. |
+| **Finding 1 — daemon deadlock at start (pre-existing, not this branch)** | With `~/.cursor/projects` at 22k files / 6.9k dirs, `cursor-discovery`'s chokidar watcher hits `EMFILE`, closes the failing handle inside its own FSEvents callback, and libuv blocks the main thread forever in `uv__fsevents_close → uv_sem_wait` (`sample` shows 1372/1375 frames there). The event loop is dead: TCP handshakes complete but nothing is `accept()`ed, no frame is handled. Reproduced with the installed v0.2.27 as well; the same log has 76k `EMFILE` lines since Sep 11. Interim: `CURSOR_HOME=<empty dir>` on the daemon. Proper fix is a separate ticket (one recursive `fs.watch` / FSEvents stream instead of a handle per directory, and never `close()` from inside the watcher's error callback). |
+| Finding 2 — self-update swapped the installed bundle | Starting the installed copy from this shell let its updater replace `~/.harness/cli/cli.js` (v0.2.20-dev.bae1fc6.dirty) with the published v0.2.27; no `.prev` was kept. Rebuild with `npm run bundle` if the dev bundle is wanted back. |
+
+Evidence (argv shown, never the env part):
+
+- A2 `/tmp/grid-calls.log`: `--remote mcp config kelvin-e2e09150 --json` → `--remote info kelvin-e2e09150 --env` → `--remote ls --json`; log `[grid] claude -> kelvin-e2e09150 (grid-bcba99c5d54a44a5) · qwen/qwen3.8-27b · retargeted eb2ee7f4 · resumed`.
+- A3 argv: `--dangerously-skip-permissions --resume b5cc30a8-… --disallowedTools=WebSearch,WebFetch --mcp-config {"mcpServers":{"harness":{"type":"http","url":"https://api-grid.autonomousdev.xyz/v1/grid/web-mcp/","headers":{"Authorization":"Bearer ${GRID_API_KEY}"}}}}`; `eyJ` count 0; env names `ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL ANTHROPIC_MODEL GRID_API_KEY`, `ANTHROPIC_BASE_URL=https://grid-llm.autonomousdev.xyz/grid-bcba99c5d54a44a5/relay`.
+- A4 `/mcp`: `harness · ✔ connected · 2 tools`; `web_search` — "Search the live web. Returns {results: [{title, url, excerpt}]}."; `web_read` — "Read the main text of up to five web pages. …". (This Mac's own `~/.claude.json` also carries a hand-configured `grid-web` — the two-servers case the doc comment accepts.)
+- A5 forced call: `Error: No such tool available: WebSearch. WebSearch is disabled for this session, in subagents as well as here.`
+- A6 replay: `tool_start WebSearch {"query":"bitcoin price today current","num_results":5}` · `tool_start WebFetch {"urls":["https://coinmarketcap.com/currencies/bitcoin/"],"max_chars":6000,"url":"https://coinmarketcap.com/…"}`; raw transcript names were `mcp__harness__web_search` ×3 / `mcp__harness__web_read` ×3.
+- A7 after `clear`: argv `--dangerously-skip-permissions --resume b5cc30a8-…` only; env has none of `ANTHROPIC_BASE_URL/AUTH_TOKEN/GRID_API_KEY` (`ANTHROPIC_MODEL=opus` is the agent's own subscription model, set on the way back); zero `grid` calls.
+- A8 second retarget: `--remote info … --env` → `--remote ls --json`, **no** `mcp config`; argv carries `--mcp-config` again from the cache.
+- B2 argv: `-c model_provider="grid" … -c web_search="disabled" -c mcp_servers.harness.url="https://api-grid.autonomousdev.xyz/v1/grid/web-mcp/" -c mcp_servers.harness.env_http_headers.Authorization="GRID_MCP_AUTHORIZATION"`; env `GRID_API_KEY`, `GRID_MCP_AUTHORIZATION=Bearer…`; `eyJ` count 0.
+- B3 `/mcp`: `harness: connected (2 tools)`. B4 rollout: `function_call name: web_search namespace: mcp__harness` / `web_read`; replay → `WebSearch {"query":"current Bitcoin price"}`, `WebFetch {"urls":[…],"url":…}`. B5 after `clear`: no `web_search=`, no `mcp_servers.harness`, no grid env.
+- C: `[grid] web tools unavailable for kelvin-e2e09150 · This machine's \`grid\` is older than 0.3.36 …`, then `[grid] claude -> … · resumed`; argv `--disallowedTools=WebSearch,WebFetch`, no `--mcp-config`; prompt answered `DEGRADED-OK`.
+- Versions: claude 2.1.272, codex-cli 0.154.0, grid 0.3.46, daemon = `cli/dist/cli.js` at `56b5e2b`.