viewable-one 0.0.0-stage → 0.12.1

package/SPAWN.md

@@ -0,0 +1,2105 @@
+# The spawn contract - running a Claude Code session from the board
+
+This is the runner's contract, written for whoever maintains it: every row it
+reads and writes, every bound it respects, and what happens at each edge. It
+is not a guide to using glytch - [README.md](./README.md) is that.
+
+The rows contract below is what runs today.
+
+**Words, checked 2026-10-04 against `INBOX_OPS.md` and `src/types.ts`.** The
+board has one kind that carries work: the **idea**. Its title and body are the
+prompt a run is given, its run record sits under `run`, and its questions and
+answers are **question notes** on it, not circles of their own. Everywhere
+below, "the idea" is the thing a run belongs to (what `fromIdOf(request)`
+names), and `ask_user` lands a question note on that idea. Older dated
+paragraphs keep their dates; where one names a prompt or a question as a
+circle, read it as the idea or a question note on it.
+
+## Coding checks (#2193)
+
+A successful coding session (not a draft plan or chat turn) runs the folder's
+`package.json` scripts `test` and `build`, sequentially, with `CI=true`.
+No dependency installation is attempted. Missing scripts, dependencies, or
+tools are skipped with a plain reason. Scripts receive the existing dev-server
+environment filter, not the agent's credentials. npm is spawned without a shell;
+npm itself runs the folder's scripts. Checks have their own process group on
+POSIX so Stop and timeout also stop their child processes.
+
+A failed check triggers one agent turn in the same copy, with its diagnostics
+and an instruction to reproduce and fix the failure without weakening checks.
+Both scripts are checked again afterwards. A failed check that becomes unavailable
+stays failed. The original session, checks, and repair share one deadline. Running
+out of time fails the available checks with a plain reason; it does not turn a
+completed coding session into a crash. Stop keeps the run's stopped state.
+
+The closing `addComment` carries `result`, also retained in `sidecar.result`:
+
+```json
+{"checks":[{"kind":"tests","status":"failed","failed":1,"reason":"Tests did not pass."},{"kind":"build","status":"passed","failed":0}],"fixAttempted":true}
+```
+
+`kind` is `tests` or `build`; `status` is `passed`, `failed`, or `skipped`.
+`failed` counts failed checks (0 or 1), not individual test assertions, whose
+output formats differ. `reason` explains failure or skipping. A repair starts
+with a streamed step and the closing reply says “Coding tried one fix.”
+The result-card consumer is delivered separately in #2023; it must preserve this
+payload on the reply. Installed bridges need a release through #584/#640.
+
+## Before and After pictures (#2194)
+
+Checked against the runner code on 2026-10-24.
+
+`lib/pagePictures.mjs` is the one module behind this (with
+`lib/pageRoutes.mjs`, which only it uses); it adds no dependency. It runs only
+for a coding run that made a copy and changed a screen file that is still
+there (`.tsx .jsx .vue .svelte .astro .html .css .scss .sass .less`, or a
+routed page file such as `page.ts` or an `.mdx` page; not tests or stories).
+A deleted page is not opened. A run with no copy has no list of what it
+changed, so no pictures.
+
+- The browser is one already installed: Chrome, then Edge, then Chromium, in
+  the usual install places (PATH on Linux). Nothing is downloaded.
+  `GLYTCH_BROWSER` names one, or `none` turns pictures off. It runs headless
+  over its DevTools pipe with a fresh profile that is deleted afterwards, and
+  without the runner's secrets.
+- The app is the folder's `dev` script, else `start`, through npm without a
+  shell, with the dev-server environment filter, `PORT` set to a free port and
+  `BROWSER=none`. Its address is read from its output, else that port. It must
+  answer within 60 s. Its whole process group stops after each picture. One
+  app runs at a time: the copy, then the folder.
+- The page is the one the session names in `.glytch-page.json` at the copy's
+  root (`{"path":"/settings","name":"settings page"}`, never committed), else
+  the file route of a changed page file (Next, SvelteKit, Astro, Remix), else
+  `/`. Its name comes from the record, else from its address.
+- The page check (`kind: "page"`, with `page` set to its name) is part of the
+  check pass, so its failure gets the one fix turn and the same deadline and
+  Stop. After is taken then. Before is taken from the folder at the end; the
+  folder is still the "before" state because the run worked in its copy. The
+  changed area is the box around the pixels that differ, found in the same
+  browser, as fractions of the picture. Pictures that do not differ are
+  dropped: the wrong page was opened.
+- The closing reply carries `result.before`, `result.after` (JPEG data URLs)
+  and `result.changed` (`{x,y,w,h}`). `sidecar.result` keeps the checks but
+  not the pictures, so lists of runs stay light.
+
+Nothing here fails a run. No browser, or one that does not answer when it
+starts (Stop and the time limit end that wait too): the check is skipped and the reply ends with "No pictures: no browser
+found." A browser that closes while it opens the page: skipped, "No pictures:
+the browser closed." No `dev` or `start` script: skipped,
+"No pictures: this folder has no app to start." An app that starts in neither
+place: skipped, "No pictures: the app did not start." An app that starts in
+the folder but not in the copy, or a page that does not load or answers 400
+or more: the check fails, with what to fix. Stop and the time limit are
+looked at while the page loads, not only between steps. Stopping the app
+kills its whole process group after the grace, so a server that outlives npm
+does not stay up. Installed bridges need a release through #584/#640.
+
+## The runner talks to the board over rows, not files
+
+Every request the runner picks up is a row in the hosted database, and every
+answer it gives back is an update to that row. Nothing passes through a
+request folder on disk. Terminal retry receipts are stored locally until the
+server acknowledges them. The tables and the Edge Function ops that own them are
+specified elsewhere (brief 30, "Move 2 contract"); this file owns the
+engine side - worktree, wall clock, resume and retry, money - which the move
+to rows did not change.
+
+`bridge/lib/runnerApi.mjs` is the whole of the wire: one function per op (`register`, `heartbeat`, `claim`,
+`update`, `events`, `opTake`, `opResult`, `runs`, `resume`), bearer resolved
+the same way every other hosted call in this package resolves one, POST to
+`supabase/functions/board-runner/`.
+
+`bridge/lib/runner.mjs` reads and writes rows, not files, for every request
+kind, chat turns included. What replaces each piece that used to be a file
+under `.glytch/inbox/spawn/`:
+
+| was a file | is now |
+| --- | --- |
+| `<id>.json` (the request), `<id>.claim` | `claim {projectIds}` - one atomic server-side update, no exclusive-create race |
+| `<id>.result.txt` | `update {runId, patch:{status, result, finished_at}}` - `result` still write-once |
+| `<id>.log`, streamed | `events {runId, events:[{seq,kind,text}]}` - chunks every `PM_LOG_FLUSH_MS` (default 3000ms), `seq` monotonic; see rowsEvents.mjs for how the head/cut/tail cap is honoured at settle time |
+| `<id>.session.json` | `sidecar` on the run row, written by `update` - for EVERY request kind, chat turns included (a first chat message is not `isPersistent` and mints no worktree either, so without this exception it would write no sidecar at all - see `runnerCompletion.mjs`) |
+| `.runner.json` | `register`+`heartbeat`, on start and every beat (`RUNNER_BEAT_MS`). `glytch doctor`'s liveness row used to read the file and froze at whatever the last file-based daemon wrote; it asks the board directly now, through the read-only `presence` op |
+| `<id>.stop` | `heartbeat`'s `stops` array |
+| `<id>.merge` / `<id>.delete` / `<id>.relaunch` | `heartbeat`'s `ops`, `opTake`, `opResult` - relaunch's record is the run row's own `server` column (or the worktree's live `.glytch-server.json` when the row has none yet), never a `.server` mailbox file |
+| the shared-preview request/receipt pair (`.glytch/inbox/preview/`) | a `run_ops` row of `kind:"preview"` - claimed once (`opTake`), its proofs read from the claimed run row (`runnerApi.runs`) and from `get_node` over `hosted.callTool`, never from `canvas/`; `opResult` ticks through starting/ready/offline/error on the SAME op row, since preview (unlike merge/delete/relaunch) is not one-shot - `bridge/lib/sharedPreview.mjs`'s `createSharedPreviewService` tracks it across beats |
+| `<id>.reply-*.json` promoted to a new request | the `resume` op - one call, no file, no `createdBy:"runner"` request to write. Carries `images` (a late message's own, same shape a reply file's `images` array used) when the message had any - `runnerApi.mjs`'s own header says why the OP does not declare the field yet on its side |
+| the `startSession`/`endSession` ops files, and the wait for their receipt | nothing - `claim` moving a row to `status:'running'` IS the start; there is no more window to guard |
+| a chat-turn's request FILE, `<id>.stop`, its per-room lock (`activeChatTurnForRoom`, disk-scanned) | the same row contract as an ordinary session, plus `activeChatTurnForRoomRows` (`runner.mjs`) in place of the per-idea lock - a chat turn has no idea behind it, so its lock is per `roomId` instead |
+
+**Admission, leases and completion recovery (2026-09-26).** Admission refuses
+unavailable concurrency or spending reads. Each claim carries an instance UUID
+and five-minute lease, renewed every 30 seconds; local execution stops before
+lease expiry if renewal fails. Expired claims become errors, never automatic
+re-runs. A later original completion may reconcile an expired claim while its
+result is still unwritten. The one exception is the restart pass (see "The
+conversation on an idea"): it continues a session a person asked for, in its
+own worktree, once.
+
+Terminal patches are saved under `GLYTCH_HOME/run-completions` before delivery.
+The runner retries exact receipts after restart and blocks new admission while
+any receipt remains undelivered. A failed disk write retains the patch in memory
+and attempts delivery; simultaneous disk/network failure cannot survive process
+loss. The server accepts identical retries and rejects conflicting results.
+
+**How often the runner calls the board (ticket e8, approved 2026-10-03; #616).**
+`lib/runnerPace.mjs` decides every wait for both loops of a folder:
+
+| loop | healthy | queue empty | 5xx, 429 or network failure |
+| --- | --- | --- | --- |
+| claim (`claim`, plus `runs` when `PM_SPAWN_MAX_CONCURRENT` is set) | `PM_SPAWN_POLL_MS`, 5 s | no call while the beat's `pending` leaves this folder out; against an older function, grows by 2.5 s per empty claim to 30 s (6x) | 5, 10, 20, 40, then 60 s (12x), jitter down to 20%; reset by the first success |
+| beat (`register` + `heartbeat`) | `RUNNER_BEAT_MS`, 10 s, one heartbeat for every folder of the process; `register` only every 5 min or when the folder list changes | - | 10, 20, 40, then 60 s (6x); reset by the first success |
+
+A 429 or 503 with `Retry-After` waits at least that long, up to an hour, and
+the folders share that failure instead of each asking again. The error line
+names Cloudflare's Ray ID (`cf-ray`, or the Ray ID on its HTML page) and the
+function's request id, and a Cloudflare HTML page is summed up in one line
+instead of 400 characters of markup.
+
+A healthy beat stays at 10 s, a third of the 30 s window the app
+(`RUNNER_PROJECT_STALE_MS`) and doctor (`RUNNER_STALE_MS`) read as online.
+A 401 and every refusal keep the base interval: a dead credential already
+stops reaching the network (`auth.mjs`). `runnerApi.mjs` marks the failures
+to back off on with `transient: true`. This is polling backoff only; a failed
+run is still never re-run.
+
+The daemon (`multiwatch.mjs`) gives every folder one shared registrar and one
+heartbeat hub. The hub sends one `heartbeat` for every folder that beat
+lately and hands each folder its own stops and ops (`op.project_id`). The
+answer's `pending` lists the folders with an approved run nobody has claimed;
+only those folders call `claim`, each with its own admission lock, its own
+concurrency count and its own `runnerInstanceId`, so no process-level claim
+dispatcher is needed. A function without `pending` (deployed before #616)
+turns the hub off and each folder beats and polls `claim` alone, as before.
+A folder the server refuses inside a batch beats alone so it cannot refuse
+the others. Lease renewal for an active run is still its own heartbeat
+(`runnerLease.mjs`). With five idle folders this goes from about 45 calls a
+minute to about 6 (one heartbeat every 10 s, `register` every 5 minutes,
+no claims).
+
+**One casualty confirmed to have no rows equivalent.** `askedAndNeverReported`
+(the "asked N questions and reported nothing" line on a run's outcome
+comment) read `inbox/ops/*.json` and `inbox/tell/*.json` to reconstruct what
+a session had put in front of the human. There is no rows op that answers
+"what did this run itself write to the board" - `collect_session` answers
+"what came back", the opposite question - so this line is dropped rather
+than approximated; a rows-based equivalent would need its own op (e.g. a
+`session_asks` view) and is not in the Move 2 contract. `ops.mjs`,
+`tell.mjs`, `questions.mjs` and `sidecar.mjs` are DELETED (2026-09-11, Move
+2b) rather than kept as dead code: their only caller, the local stdio server,
+was deleted in Move 1 W3, and nothing else in this package called them
+after Move 2's own rewrite of `runner.mjs`. `lateReplies.mjs` is deleted the
+same pass for the same reason - its rows-era replacement, `resume`, settles
+a late answer or message through a call to `runnerApi.resume`, not a file
+write. `bridge/hooks/stop-report.mjs` was the ONE EXCEPTION - a Claude Code
+Stop hook, not the spawn runner, writing into `inbox/tell/` as a session's own
+fallback report. It is DELETED (2026-09-13): the app-side reader of that
+mailbox went with the rest of the `.glytch/` contract in Move 2, so the write
+had no reader, and `paths.mjs`'s `OPS_DIR` and `TELL_DIR` constants are gone
+with their last user.
+
+## Reference image delivery - 2026-09-10
+
+Image-bearing requests must preserve every selected attachment. The runner
+validates the complete `images` array before launching a coding process and
+reports malformed or unsupported data instead of filtering it out. Supported
+transport formats are PNG, JPEG, GIF and WebP. File-based engines receive
+validated temporary files; failure to write any file aborts the run. Claude
+streaming, Codex app-server and ACP receive native image content. ACP must
+advertise image prompt support before an image-bearing model turn is sent.
+
+Both draft and implementation sessions are instructed to inspect references,
+identify their sources and record concrete observations before planning or
+editing. Visual implementations must be compared against those references.
+The board MCP `get_node` returns native image blocks with source labels; missing
+stored images are reported explicitly. Instructions inside attachments remain
+reference content, not authority to override the user's request.
+
+Transport tests prove byte delivery and refusal behavior using fake processes.
+They do not prove model comprehension. Do not describe these safeguards as a
+guarantee that a model interpreted a reference correctly. Existing runner and
+MCP processes must reload the updated code to pick up the changes.
+
+
+Amended 2026-09-02 (third pass), ON A BRANCH and not in main yet, against
+`src/agents/`, `src/store/actions/folder.ts` and
+`scripts/check-spawn-callers.mjs`. NO FILE UNDER `bridge/` CHANGED, and the
+request, claim and receipt shapes are all unchanged - what changed is who may
+file a request.
+
+- **A request can now be filed without a human click**, by an agent whose
+  `AgentCaps` allow it (brief 15, decision 5): auto-run on, under its sessions
+  per round. No dollar cap is checked (#75). `src/agents/autoRunSpawn.ts` is the
+  only such caller, and it asks `decideAutoRun` on every path before it files.
+  An agent whose caps refuse files nothing and spends nothing; the prompt
+  waits for the click, exactly as before.
+- **Per-agent caps are a second way a request gets filed, not only a human
+  click.** The section at the foot of this file describes filing by a human
+  click, which is still true of the human path. Still no confirm dialog
+  anywhere - ruled against twice (`q-mt9q8qrg`), and this change does not
+  reopen it.
+- **The app now reads `costUsd` out of the session sidecar.** The runner has
+  written it since the 2026-09-01 pass ("Verdict and cost"); nothing about the
+  sidecar changes, but the app records that figure on the run's receipt,
+  and nothing reads it to refuse a run (#75, #364). A runner that omits
+  `costUsd` records nothing.
+
+Checked and amended 2026-09-02 (second pass) against `bridge/lib/runner.mjs`,
+`bridge/lib/exitClass.mjs`, `bridge/lib/worktree.mjs`: the stall watchdog
+re-arms on tool results, which arrive as USER events (the first pass waited
+for a top-level `tool_result` event that never comes, so it never armed after
+the first tool call); the crash retry budget counts from the spawn, not the
+filing; a crash AFTER any assistant event is not retried. Tests cover stall,
+tool-left-open, crash-before-output, crash-after-output and lock ordering.
+
+Checked and amended 2026-09-01 against `bridge/lib/runner.mjs`,
+`bridge/lib/exitClass.mjs`, `bridge/lib/worktree.mjs`: verdict and cost land on
+the frame and in the receipt, stall watchdog and crash retry, per-repo lock for
+git mutations. See new sections "Verdict and cost", "Stall watchdog", and
+"Per-repo worktree lock" below. No file under `src/` changed.
+
+Written 2026-08-26, against `bridge/lib/`, `src/folder/folder.ts`, `src/folder/inboxOps.ts`,
+`src/folder/mirror.ts`, `src/types.ts` at `aa0a0eb`. No file under `src/` was changed
+to make the runner work.
+
+Checked and amended 2026-08-30 (third pass) against `bridge/lib/runner.mjs`,
+`bridge/lib/repomap.mjs`: a FRESH session (not a resume) gets a repo primer
+after the preamble - the file tree plus exported symbols per source file,
+cached keyed to HEAD sha, deterministic (no model call, no tree-sitter). Built
+to reduce cache re-reads: the 3-day spend audit showed 69% of Opus cost was
+cache re-reads across 100+ turn sessions, and a big share of those turns is
+rediscovering the tree. Primer + attempts section together capped at ~16KB,
+primer trimmed first. See "Repository primer" below. No file under `src/`
+changed.
+
+Checked and amended 2026-08-30 (second pass) against `bridge/lib/runner.mjs`,
+`bridge/lib/spawn.mjs` and the receipts in `.glytch/inbox/spawn/`: a persistent
+streaming session that emitted its final result envelope is FINISHED - the
+wall clock closes the idle stream and the receipt settles as success, while
+staying the money bound for a child that never emits one - and the request
+scan skips the runner's own bookkeeping (`*.session.json` sidecars, dotfiles)
+the way it already skips reply files. See "A finished stream is finished" and
+"The scan reads requests and nothing else" below. No file under `src/`
+changed.
+
+Checked and amended 2026-08-30 against `bridge/lib/runner.mjs`,
+`bridge/lib/spawn.mjs`, `bridge/lib/worktree.mjs`, `src/store.ts`,
+`src/nodes/SessionTerminal.tsx`, `src/store/runs/prompt.ts`, `src/types.ts`:
+signal files (stop, merge, delete), per-idea lock with resume exemption,
+separate worktree op receipts, worktree summary, merge safety checks, stall
+verdicts, and re-run into a live session. See the new sections "Signal files",
+"Per-idea lock", and "Worktree op receipts" below.
+
+Checked and amended 2026-08-29 against `bridge/lib/runner.mjs`,
+`bridge/lib/spawn.mjs` and `bridge/lib/questions.mjs`: reply files are no
+longer read as spawn requests, the live log is a ring rather than a head, and
+an answer given after `ask_user` timed out is pushed into a running streaming
+session. See the amendment under "What is NOT possible without app work". No
+file under `src/` changed.
+
+Checked and amended 2026-08-28 against `bridge/lib/runner.mjs` and
+`bridge/lib/spawn.mjs`: a watcher runs as many sessions at once as are filed,
+any number of sessions run at once by default, the liveness mark beats on its own timer,
+and a session that cannot get a worktree while another is running is refused
+before it spawns. See the two new rows in the money table and the note
+under it. No file under `src/` changed.
+
+Checked and amended 2026-08-27 against `src/folder/spawnRequest.ts` and `src/store.ts`
+(`spawnPayloadFor`, `fileSpawnRequest`): a request's `prompt` now carries the
+ideas' wired-in context as well as their own words, there is a `contextIds`
+field beside it, the board's controls show the size before the click, and a
+request already in flight refuses a second one. No file under `bridge/`
+changed for any of it - see "The three files" and the new money row.
+
+Checked and amended 2026-08-26 against `src/folder/spawnRequest.ts`, `src/store.ts`
+(`fileSpawnRequest`), the idea card and
+`src/components/SelectionBar.tsx`: the board-side button exists now, it files
+on ONE click per ruling `q-mt9q8qrg`, and the last section says so. The
+confirm dialog this file described earlier the same day is gone; see the
+note in the money table. Nothing in the runner changed.
+
+## What this is for
+
+The user's overnight goal, verbatim: "be able to spawn sessions of claude code
+here", "be able to see the output in predictable place (currently is all over
+the place)", "be able to use claude code from here to get better analysis on my
+board", "be able to track things between claude code and the area of its
+operation here (when its done - propose to delete)".
+
+## Why it looks like this and not like anything else
+
+The repo's one hard architectural rule (`CLAUDE.md`): nothing under `src/` may
+import from `bridge/`, and the app must build and behave identically with
+`bridge/` and `.mcp.json` deleted. A browser also cannot spawn a process. So
+the app can only ever STATE an intent, through the folder contract it already
+offers any outside actor, and something outside must act on it.
+
+That gives the whole shape, and there is no second option:
+
+```
+  the app / a session          the folder                    the runner
+  --------------------         --------------------------    -------------------
+  states an intent      ->     inbox/spawn/<id>.json
+                               inbox/spawn/<id>.claim   <-    claims it, once
+  ingests, once per            inbox/ops/*.json         <-    startSession
+  file version                 inbox/ops/*.result.txt   ->    ...checked, THEN spawn
+                               canvas/<board>.json      ->    answers, comments
+                               inbox/ops/*.json         <-    endSession
+                               inbox/spawn/<id>.result.txt <- the receipt
+```
+
+`bridge/README.md:22` already anticipated exactly this: "A future hosted MCP
+endpoint or spawn runner replaces this process by speaking the same files."
+
+**A third folder, not a third meaning for `.glytch/inbox/ops/`.** The app lists
+`inbox/*.md` (top level, markdown only) and `inbox/ops/*.json` (json only) -
+`src/folder/folder.ts:189` and `:207`. It never walks deeper. So `.glytch/inbox/spawn/` is
+invisible to the app: a request file there can never be parsed as a Board API
+ops file and can never put a red panel on his screen. Putting requests in
+`.glytch/inbox/ops/` would have done exactly that.
+
+**The file shapes are copied from the ops channel on purpose.** A request file
+plus a `.result.txt` receipt written back beside it is the idiom this repo
+already has, the one `bridge/lib/ops.mjs` already reads, and the one a session
+already knows how to look for. Inventing a second shape for the same job would
+be the drift the sidecar exists to avoid.
+
+## Two states, and no progress protocol
+
+The ruling, 2026-08-26 (`q-mt9as5a0`): a run is **running**, then **done**.
+There is no third board state, no heartbeat, no liveness channel, and nothing
+anywhere infers a session's state from its silence. The record rides the
+idea, and its card draws these same two states.
+
+That ruling deletes a lot, and the deletions are the good part. There is no
+`.status.json`, no `STALE_MS`, no reaper, no "waiting on you" state, and no
+timeout that guesses whether a quiet session is thinking or dead. A session
+that dies without ending leaves its card reading `running`, and he sees that
+and presses Rerun or clears the idea. A wrong-looking card he can act on beats a
+right-looking state machine he has to trust.
+
+Since 2026-09-07 (the QA sweep of the runner) the end op says which of the two
+endings it was: `endSession` carries `stopped: true` when the run ended because
+a stop was asked for, and a `reason` line when it ended without ever starting.
+That is not a third state - the board still reads running, then done - it is
+the difference between "finished" and "you stopped it", which the card could
+not otherwise tell.
+
+What is NOT a progress protocol, and stays:
+
+- the **claim file**, which records who owns a request so two runners cannot
+  both run it. It is written once and never updated, so it says nothing about
+  liveness and cannot go stale in a way anyone reads.
+- the **wall clock**, which kills a child that has run past `maxMs`. That is a
+  money bound on a process, not a state on the board. When it fires the runner
+  still calls `endSession`, so the board says `done` like any other ending, and
+  the reason lives in `inbox/spawn/<id>.result.txt` where a person reads it.
+  Amended 2026-08-30: for a streaming child whose final result envelope stands,
+  the firing is the reply window closing, not a timeout - see "A finished
+  stream is finished" below. The bound itself is unchanged. Amended again
+  2026-09-06: there is no reply window any more, so an idle child does not
+  reach the wall clock at all - the envelope closes its stdin and it exits.
+  The bound is still unchanged, and it is what a child mid-turn meets.
+
+The board carries two states. The disk carries the detail. Neither pretends to
+carry the other.
+
+## A finished stream is finished
+
+Added 2026-08-30. A persistent session runs streaming (`--input-format
+stream-json`) so the human can reply into it, and a streaming child NEVER
+exits on its own: it ends each turn with a result envelope (`{"type":
+"result", ..., "total_cost_usd", "session_id"}`) and then sits on stdin
+holding the reply window open. The runner read that ending like a one-shot
+child's: the wall clock fired, killed it, and wrote an ERROR receipt saying
+the work is unfinished. By 2026-08-30, 26 of the 28 sessions killed at the
+90-minute wall had their final envelope in the log - work done, billed, and
+receipted as failed. spawn-mtfx5hex-bb857e is the type specimen: its log ends
+"tsc clean, build clean, 1865 tests pass" with `total_cost_usd` 7.52, and its
+receipt says the session ran out of time.
+
+So the runner scans a streaming child's stdout for result envelopes. An
+envelope means the child is IDLE - the turn is over and nothing is billing.
+Sending it a new user message (a reply, a pushed answer) starts a new turn
+and clears the flag. When the child ends while the flag stands - the wall
+clock closing the reply window, the human clicking Stop, or its own exit -
+the outcome is `finished`: the receipt settles as success, the session's one
+reply lands on the run's idea (`reportOutcomeOnBoard` writes it through
+`commentOnAnchor`, see "The conversation on an idea"), and the sidecar stays resumable with the worktree
+kept per the persistent-session rules. An envelope carrying
+`is_error: true` ends the session without calling it a success.
+
+What does NOT change: the wall clock is still the money bound, and for a
+child that never emitted an envelope - hung mid-work, looping, never got
+started - its firing is still a timeout and still an ERROR receipt. The two
+states on the board also do not change: running, then done, with the detail
+on disk (q-mt9as5a0). This is a receipt telling the truth, not a third state.
+
+### The reply window closes with the envelope
+
+Everything above still holds about what an envelope MEANS and how the exit is
+read. The runner closes the child's stdin the moment the envelope lands, so
+the child exits on its own and the session ends when its work does.
+
+The wall clock is untouched for a child MID-TURN (no envelope since the last
+message it was sent), and the SIGTERM-then-SIGKILL path stays for a child that
+ignores a closed stdin.
+
+A reply that arrives for a child whose stdin is closed, or that has already
+exited, is NOT lost and is never written to a dead pipe: the runner turns it
+into a new spawn request in the same folder - `createdBy: "runner"`, approved
+exactly as the original was, the reply as `prompt` and `title`, the same
+`nodeIds` and `agent`, `resumeSessionId` from the sidecar's `claudeSessionId`
+and its `worktreePath` - and the ordinary watch runs it, resuming the session
+in the tree it lived in. See `promoteReplyToRequest` and `promoteLateReplies`
+in `lib/runner.mjs`. A reply arriving MID-TURN still goes straight down stdin,
+which is where the live reply channel described below still applies.
+
+Answers are unchanged: a session blocked inside `ask_user` is mid-turn, so its
+stdin is open and `answerPoll` still pushes the ruling in live.
+
+## Resume - the worktree IS the session's life
+
+*Added 2026-09-07. Checked against `bridge/lib/runner.mjs` and the four tests
+named at the bottom of this section.*
+
+A request carrying `resumeSessionId` continues a conversation Claude Code
+already has. **Claude Code keeps conversations per working directory**, so
+`--resume <id>` only means anything in the directory that conversation ran in.
+That is the whole rule, and everything below follows from it.
+
+**The recorded worktree runs the session.** A request that carries
+`resumeSessionId` AND a `worktreePath` that exists on disk and is a git
+worktree inside `<root>/.claude/worktrees/` runs IN that worktree, on its
+existing branch. No new worktree, no new branch, no repo primer, no attempts
+section - a resume already has all of that in its history. The sidecar and the
+receipt both name that tree ("Reused existing worktree at ..."). The per-prompt
+lock is exempted for it: a resume into the prompt's OWN tree is not a second
+session, it IS the session.
+
+**The command is now built AFTER the tree is chosen, and that is the fix.**
+Until 2026-09-07 `--resume` was decided at the top of `runRequest` and the
+working directory a hundred lines further down, so a resume whose recorded tree
+had gone got the fallback's FRESH tree with the resume flag still on it. What
+that produces is not an error the runner can read as one:
+
+```
+{"type":"result","subtype":"error_during_execution","num_turns":0,
+ "total_cost_usd":0,"errors":["No conversation found with session ID: ..."]}
+```
+
+spawn-mtqay776-f76882 (2026-09-06 21:06 UTC) is that envelope. Its receipt said
+"ended with an error result; $0.00, 0 turns" and its frame read DONE with
+nothing in it. The question it produced - "why did it fail, lack of context?" -
+has an honest answer: no. The resume ran in the wrong directory and never
+started.
+
+**When the recorded worktree is gone** (merged and deleted, swept, pruned,
+manually removed), the runner does NOT run `--resume` in a fresh tree. It
+starts a **fresh session** - no `--resume`, a new session id minted by the
+engine - in a fresh worktree, and:
+
+- the prompt carries one extra line saying the earlier conversation could not
+  be resumed because its worktree is gone, so the session knows its history is
+  not there rather than acting as though it is;
+- the fresh session gets what a fresh session gets: the repo primer and the
+  attempts log;
+- the receipt says so in plain words, starting `THE EARLIER CONVERSATION COULD
+  NOT BE RESUMED: ITS WORKTREE IS GONE`;
+- the sidecar records the NEW `claudeSessionId`, so the app's next "run again"
+  on that idea resumes the session that exists instead of the one that does
+  not.
+
+A request that names its own `cwd` and resumes there is untouched by all of
+this: it never asked for a recorded tree, so it has nothing to have lost.
+
+**The tree is there and the conversation still is not.** Same envelope, from a
+pruned session file or a tree restored from elsewhere. `isMissingConversation`
+in `lib/runner.mjs` recognises it - `is_error`, `num_turns: 0`,
+`total_cost_usd: 0`, and `No conversation found` in `errors[]`, all four - and
+the runner retries **exactly once**, as a fresh session, in that SAME worktree,
+logging one line and telling the session the same thing in one line of prompt.
+The receipt says `THE EARLIER CONVERSATION COULD NOT BE RESUMED: CLAUDE CODE
+HAD NO RECORD OF IT`.
+
+**Why that retry does not break "Exactly once".** The rule below exists because
+a re-run spends money that is already spent. This envelope says the opposite on
+its face: **0 turns and $0.00**. Nothing was billed, nothing was done, and there
+is no partial work to duplicate - so the retry is not paying twice, it is the
+first attempt actually happening. The turn count and the cost are checked, not
+assumed: a run that reached one turn or one cent is not this case whatever its
+errors say, and a second failure is terminal like any other.
+
+Tested in `bridge/test/runner.test.mjs`: a resume with a live `worktreePath`
+runs there and makes no second tree; a resume whose tree is gone starts fresh,
+is told so, and gets the attempts section; the 0-turn envelope retries once in
+the same tree and the sidecar names the session that lives; a second failure is
+terminal. The `no-conversation` mode of `test/fixtures/fake-claude.mjs` plays
+the envelope.
+
+## The scan reads requests and nothing else
+
+Added 2026-08-30. The request scan filtered on `*.json` minus the reply
+marker, and everything else the folder legitimately holds in `.json` was
+claimed as a request, found to have no `prompt` and no `approved`, and
+refused. Two victims:
+
+- **`<id>.session.json`**, the runner's own sidecar for persistent sessions
+  (`claudeSessionId`, `worktreePath`, `expired`). 47 "Refused: Pass prompt"
+  receipts had accumulated by 2026-08-30 - one per sidecar - and each
+  refusal's claim also counted in `spendSince` as though a session had been
+  started, the same quiet half the reply-file bug had.
+- **`.runner.json`**, the watcher's own liveness mark. `.runner.result.txt`
+  in the real inbox is the proof the runner refused its own heartbeat.
+
+`listRequests` now skips reply files, `*.session.json` (the marker lives in
+`spawn.mjs` as `SESSION_SIDECAR_SUFFIX`, and the runner builds the sidecar
+path from it rather than spelling it twice), and dotfiles. Nothing hidden is
+input, and nothing the runner writes for itself can come back to it as a
+request.
+
+## The three files
+
+`bridge/lib/runner.mjs` reads and writes none of this - see the table near
+the top of this file. Kept below verbatim: the SHAPE of a request (what
+fields it carries, what `approved` and `maxMs` mean) is exactly the shape
+`run.request` carries in a row now, and `bridge/spawn-runner.mjs`'s deferred
+CLI subcommands still speak this file contract directly.
+
+All under `.glytch/inbox/spawn/`, all keyed by one request id (`spawn-<base36>-<hex>`,
+the same `newOpId` shape the ops channel uses).
+
+### `<id>.json` - the request
+
+```json
+{
+  "version": 1,
+  "id": "spawn-mt8n-ab12cd",
+  "createdAt": "2026-08-26T02:10:00.000Z",
+  "createdBy": "board",
+  "approved": true,
+  "approvedBy": "nicolas",
+  "prompt": "Read the board and say which of the four features is closest to shipping.",
+  "title": "Which feature is closest",
+  "cwd": "/Users/nicolasjamal/Projects/glytch",
+  "maxMs": 1800000
+}
+```
+
+- `approved` is the money gate and it is checked, not decorated. **A request
+  without `approved: true` is never run** - it is finalised as `refused` with
+  the reason, and the runner moves on. See "Money" below.
+- `prompt` is what the session is told to do. Required, non-empty. Since
+  2026-08-27 it carries the ASK followed by everything wired into those
+  ideas, as numbered `[Block N]` sections under one heading - ruling
+  `q-mt9ssgrs`, "Should spawning a prompt send everything wired into it, the
+  way a model run does?" / "Yes, but show me the size before it spends".
+  **Nothing in the runner changed for it, and that is the point**: the context
+  is inside the field the runner already passes to the engine, because a
+  `context` field beside it would be context the engine never sees.
+- `contextIds` (optional, board-side) names the ideas that fed it, in the
+  order the session was shown them. Provenance only - the runner ignores it;
+  a session calling `get_node` uses it to walk back to the board.
+- `title` names the run on the board - `RunRecord.title`, what the card's
+  heading reads (see "The run record" below). Optional;
+  the prompt's first line is used when it is absent.
+- `cwd` is where `claude` runs. Optional; defaults to `PM_BOARD_ROOT`.
+- `maxMs` is this request's wall clock. Clamped to `MAX_WALL_MS`.
+- `webSearch` (optional boolean, #478) lets the run search and read the web
+  without asking first: Claude Code gets `WebSearch` and `WebFetch` on its
+  list, Codex gets live web search (not on a Codex plan draft). Without it a
+  Codex thread is started with web search disabled, whatever the computer's
+  own Codex config says. It is the agent's Web search setting in Manage
+  agent. A value that is not a boolean is refused.
+
+### `<id>.claim` - who owns it
+
+Created with `flag: "wx"` - an exclusive create, which is atomic on a local
+filesystem. **That single call is the whole of "exactly once" across two
+runners**: the loser gets `EEXIST`, logs it, and never touches the request
+again. No lockfile protocol, no lease negotiation, nothing to get wrong.
+
+```json
+{ "runnerId": "r-mt8n-9f31", "pid": 40122, "host": "mac", "claimedAt": 1756..., "sessionKey": "spawn-mt8n-ab12cd" }
+```
+
+Written once, never updated, never removed - not even on completion. It is the
+permanent record that this request has been taken.
+
+### `<id>.result.txt` - the receipt
+
+Terminal, written once, in the ops channel's own voice (`OK` / `ERROR` on line
+one, then the file and a timestamp, then the detail). It is what a human or a
+later session reads to find out what happened without parsing JSON, and it is
+where a timeout, a non-zero exit and a refusal all say what they were.
+
+## The detached dev server - the run row's `server` column
+
+A prompt with the Browser switch on tells the session to start the project's
+dev server and file a browser frame pointing at its URL. A finished session is
+closed on its result envelope, so a server started as an ordinary background
+job dies with the child and the frame points at a dead port, which is what the
+2026-09-06 test pass caught (`npx serve -l 8765`, the frame filed, the session
+done, curl getting nothing). So the session is told to start it DETACHED, and
+the server outlives the session on purpose. **The words differ per platform
+and the record does not.**
+
+| the runner reports | what the session is told to run |
+| --- | --- |
+| `darwin`, `linux`, `wsl`, anything else, or nothing at all | `setsid <cmd> >/dev/null 2>&1 &` where setsid exists, `nohup <cmd> >/dev/null 2>&1 & disown` on macOS |
+| `win32` | PowerShell: `$p = Start-Process -FilePath <exe> -ArgumentList <args> -WindowStyle Hidden -PassThru`, and the pid is `$p.Id` |
+
+None of `setsid`, `nohup`, `disown`, `&` backgrounding or `/dev/null` exists in
+cmd or PowerShell, so a Windows session handed the first row either fails the
+command or starts a server that dies with it - the frame pointing at a dead
+port, which is the failure this whole section exists to stop. `start /b` was
+option B of the same ruling and was rejected: it does not reliably leave the
+console, so the child still dies with it. `-PassThru` is how a Windows session
+learns its own child's pid at all - there is no `$!` there - and WSL takes the
+POSIX row because it is Linux and has `setsid`.
+
+**The words are the app's, and the platform is the runner's.** The instruction
+lives in `src/store/spawnPayload.ts` (shared with the Preview button), and the
+app chooses between the two rows from the `platform` the runner reports when
+it registers its projects: `process.platform`, or `wsl` when `/proc/version`
+names Microsoft (`bridge/lib/platform.mjs`). Never from `navigator`: the board
+may be open in a browser on a different machine from the one the session runs
+on, and a runner that reports no platform means the POSIX row.
+
+**The record.** The SESSION writes `<worktree>/.glytch-server.json`,
+`{pid, port, cmd, startedAt}`, in the root of its working directory: the only
+thing that knows what it started. When the child ends, the runner copies that
+record plus `worktreePath` onto the run row's own `server` column
+(`bridge/lib/runnerCompletion.mjs`), so it outlives a tree that is merged,
+deleted or cleaned. Nothing is written beside the request; the row is the
+record.
+
+**Who stops it.** `sweepDetachedServers` (`bridge/lib/serverSweep.mjs`), once
+a day from the runner's own beat, per registered folder: it lists the folder's
+finished run rows that still carry a `server`, stops the server when the run
+finished more than 14 days ago or as soon as the worktree it was serving is
+gone, and clears the column. A running or pending row is never touched.
+Nothing else kills it - not the child's close, not `killProcessesIn`, whose
+parent-chain guard spares a process that reparented to init.
+`bridge/test/serverSweep.test.mjs` pins the age, the missing worktree and the
+untouched running row.
+
+**And it never kills on a bare pid.** A record can outlive its process by days
+and pids are reused, so `verifyRecordedServer` (`lib/devserver.mjs`) requires
+positive evidence: the pid must be listening on the recorded port, or carry a
+command line that agrees with the recorded one, and its start time must sit
+within ten minutes of the record's `startedAt`. Anything short of that is one
+log line and the process is left alone. `bridge/test/detachedserver.test.mjs`
+pins both halves - a detached grandchild is still alive after the envelope
+closes its parent, and an unverifiable pid is never signalled.
+
+**Who starts it again.** Added 2026-09-06, the ask: "When a dev server gets
+detached, add a button in terminal to relaunch dev server in this branch.
+Allows me to test browser." The sweep above is what makes the button necessary
+- the frame outlives the server - and nothing in a browser can start a process,
+so the runner does it. The app files a `relaunch` op on the run (see "Signal
+files" below); on its next beat the runner re-runs the record's `cmd`,
+detached, in the recorded worktree, writes a fresh record to the row, and
+answers through the op's result.
+
+**No session, and no command.** A relaunch costs nothing: it is one process
+started from a command that is already written down, so there is no LLM turn to
+pay for and no session to file. The `cmd` comes from the record and only from
+the record - the op may carry `{ worktreePath }` as a hint for finding one,
+and nothing else. An op that could name its own command would be a way to run
+arbitrary shell out of the canvas, which is a different feature and not one
+anybody asked for. So a missing record is a refusal, never a prompt for one.
+
+It refuses, and says which, when:
+
+| refusal | why |
+| --- | --- |
+| no record | the session started no server, or the sweep cleared the record when the worktree went |
+| the record has no `cmd` | there is nothing to re-run, and nothing may be guessed |
+| the worktree is gone and so is the linked folder | `cmd` has nowhere to run. While the folder is there (Keep changes deleted the copy), the app starts again from the folder and writes no record file into it (#485) |
+| the recorded port is held | something that is not this record is on it, and a second server on a taken port is worse than none |
+| the command exits at once | it died inside `RELAUNCH_SETTLE_MS` (700ms); a detached server has no terminal, so its output went nowhere |
+
+A server that is STILL RUNNING is not a refusal: the answer is the pid and port
+it is already on - verified by the same evidence the sweep demands before it
+kills anything - and nothing is started twice.
+`bridge/test/relaunchserver.test.mjs` pins the lot.
+
+**How it is stopped, per platform.** The stop is two passes with a grace
+between them, and the words for those two passes differ (brief 21, ruling
+4A of 2026-09-07). On macOS and Linux it is `SIGTERM` and then `SIGKILL`; on
+Windows, where Node maps both signals to TerminateProcess and reaches only the
+one pid while the real server usually runs as a grandchild of a `.cmd` shim, it
+is `taskkill /pid <pid> /t` and then `taskkill /pid <pid> /t /f`. One seam,
+`killTree` in `lib/kill.mjs`, holds both, and `lib/child.mjs`'s kill closure and
+`lib/procs.mjs` go through the same seam. THE GUARD IS UNCHANGED AND COMES
+FIRST either way: `killTree` decides nothing about whether a pid may be killed.
+The Windows evidence for that guard is `netstat -ano` for the pid listening on
+the recorded port and `Get-CimInstance Win32_Process` (through
+`ConvertTo-Json`) for the start time and the command line, injected exactly
+where `ps` and `lsof` are; `bridge/test/windowsevidence.test.mjs` pins the
+parsers against sample output, and `bridge/test/kill.test.mjs` the two argv
+sequences.
+
+## Windows
+
+*Brief 21, the rulings of 2026-09-07. Written against sessions 1-5; session 6
+is the end-to-end on a real machine and nothing here has met one yet.*
+
+**What is Windows and what is not.** Ruling 6C: native Windows and WSL both
+count, and `glytch doctor` names which one it is running in. WSL is Linux for
+everything in this file - it has `setsid`, it has real npm shims, it gets the
+POSIX spelling of every command below - so the runner reports it as its own
+name, `wsl`, rather than as either `linux` or `win32`
+(`bridge/lib/platform.mjs`).
+
+**How the runner says which.** Every beat of the liveness mark
+(`.glytch/inbox/spawn/.runner.json`) carries a `platform` key beside `at`,
+`version`, `updateAvailable` and `agents`: `process.platform`, or `wsl` when
+`/proc/version` names Microsoft. It is optional and stays optional - a runner
+from before this brief writes none, and the app reads that as "nothing has
+said" and falls back to the POSIX shape, exactly as it reads a missing
+`agents` block. THE APP MUST NOT USE `navigator` FOR THIS: the board runs in
+a browser that need not be on the machine the session runs on.
+
+**`.mcp.json` names the board server differently.** Ruling 2A: a writer on
+Windows writes `{"command":"cmd","args":["/c","glytch","mcp"]}`, and every
+other platform keeps `{"command":"glytch","args":["mcp"]}`. npm installs the
+bin as `glytch.cmd` there, and an MCP client spawning `glytch` with no shell
+hits the refusal Node has enforced since 18.20.2 / 20.12.2. `bridge/lib/mcpjson.mjs` branches on `process.platform`, because `glytch init`
+IS the machine, and `bridge/test/fixtures/mcp-json-cases.json` carries the
+Windows cases. (The app's second writer went with the old Help, #494.) **A file
+that already carries EITHER shape is left exactly as it is**, which is the same
+presence rule as always and is what stops a folder shared between two machines
+being rewritten forever.
+
+**Starting and stopping processes.** `runnableCommand`
+(`bridge/lib/windows-command.mjs`) resolves `claude`, `opencode` and `npm`
+through `PATHEXT` before spawning them, and `childEnv`'s allowlist matches
+`Path` case-insensitively and passes `SystemRoot` (without which a child cannot
+resolve DNS). `killTree` (`bridge/lib/kill.mjs`) is `taskkill /pid <pid> /t`
+then `/t /f`, behind the same verification guard. See the two sections above.
+
+**Git for Windows is a warning, not a refusal** (ruling 8B). Without it there
+is no worktree isolation and no Bash tool, so `glytch init` and `glytch doctor`
+say so in a row that is a WARNING - and a session then runs unisolated in the
+linked folder, which is what `makeWorktreeImpl` already does anywhere git is
+missing. Option A, a FAIL row and `exit 1`, was rejected: an unisolated session
+is worth more than no session.
+
+**CI gates it** (ruling 7A). `.github/workflows/bridge-tests.yml` runs the
+bridge suite on `windows-latest` as well as `ubuntu-latest`, and the Windows
+job BLOCKS.
+
+## Exactly once, and the one place this deliberately differs from ops
+
+The ops channel keys on `(path, lastModified)`: editing a file makes a new
+version and the new version runs. **The spawn channel does not do that.** A
+request runs AT MOST ONCE, EVER, per request id, no matter how many times the
+file is edited or how the run ended. The claim file is the record of that.
+
+The reason is money and nothing else. Re-running an ops file costs a proposal
+the user can reject in one click. Re-running a spawn costs credits that are
+already spent by the time he sees it. Symmetry with the ops channel is worth
+less than that, so it goes. To run something again, write a new request.
+
+Consequence, stated so nobody rediscovers it: a request that fails is **not
+retried**, by the runner or by anything else. Failure is terminal. That is also
+why there is no backoff, no retry count and no dead-letter queue - each of
+those is a mechanism for spending money again without being asked.
+
+**The two exceptions, and what they have in common** (crash retry, 2026-09-01;
+the No-conversation retry, 2026-09-07). Both re-run the child once, and both
+are allowed for the same reason: the first attempt provably spent nothing and
+produced nothing. A crash before any assistant event streamed has no output to
+duplicate; a `No conversation found` envelope says `num_turns: 0` and
+`total_cost_usd: 0` on its own face. Neither is a retry of work - each is the
+first attempt actually happening. A third exception is a money decision and
+needs a ruling, not a patch.
+
+**A runner that dies mid-session leaks its concurrency slot**, because its
+claim has no receipt and nothing infers death from silence. That is the ruling's
+direct cost and it is accepted rather than worked around. `spawn-runner release
+<id>` is the explicit human way to free it - a person deciding a session is
+gone, which is the only actor allowed to decide that.
+
+**Caught failures (2026-09-08):** a runner that catches an exception after
+claiming a request writes an ERROR receipt whenever the spawn directory is
+still writable, and attempts to close its board run with the failure reason.
+The receipt distinguishes failure before invoking a child from failure after
+invocation; neither path retries the request. Its live-log timer and temporary
+images are cleaned up even when finalization fails. This does not release an
+unobserved crash's request claim.
+
+**Admission (2026-09-08):** direct runs and polling share an atomic mutex at
+`inbox/spawn/.admission.lock` around room checks and the request
+claim. The claim is the durable reservation; the mutex is released before the
+board start and child execution. A busy mutex leaves the request unclaimed for
+the next poll. Concurrent runners therefore share the configured concurrent
+limit, and cannot claim two live turns in the same room.
+
+The mutex publishes a complete owner atomically. A verified-dead PID on the
+same host can be recovered automatically; elapsed time alone never permits
+stealing it. Recovery keeps a tiny `.admission-recovered-<token>` marker so a
+delayed competing cleaner cannot remove a newer owner's lock. A remote or
+unreadable owner, or a cleaner that itself crashed during recovery, requires
+manual removal of `.admission.lock` after confirming its owner is stopped.
+This short admission mutex is separate from durable request claims, whose
+manual `release` contract above remains unchanged.
+
+## The run record - the "predictable place"
+
+The run ROW is the record: it exists the moment `run_request` inserted it,
+`claim` moving it to `status:'running'` IS the start (no wait, because
+there is no window between "claimed" and "on the board" left to guard),
+and `update`'s `status:'done'|'error'|'stopped'` is the end. `frameId` -
+still the idea's own id, unrenamed - is `fromIdOf(request)`, read
+straight off the row.
+
+**Built in the app, not here.** `boardApi.startSession({key, title, brief,
+fromId})` and `boardApi.endSession({key})` land on the app side; this runner
+is a caller of them and defines none of it. What they do, as of brief 26:
+
+- `startSession` finds the IDEA named by `fromId` (the idea whose run
+  this is - `fromIdOf(request)`, the first id on the request) and writes a
+  `RunRecord` onto it: `key`, `title`, `brief`, `status: "running"`,
+  `startedAt`, `openedBy`, replacing any earlier record that idea carried.
+  It lands live, not as a proposal. With no `fromId`, or one that no longer
+  names an idea, the op returns **OK with no id** - the run happens and its
+  report reaches him through the Glytch Agent when `report` is called, and
+  nothing is drawn. Refusing would mean a stale idea id costs a session,
+  which is the worse trade.
+- The `key` is the same key `report()` takes. That is the whole trick: the
+  session's report reaches the Glytch Agent, which places it beside the
+  ideas it is about, and its questions land as question notes on the idea
+  that asked. Nothing is wired. No nesting logic anywhere in this runner.
+- `endSession` flips `status` to `done`, stamps `endedAt`, and **proposes
+  nothing** - there is no node to propose deleting, because starting the run
+  created none.
+
+The runner's whole part is: call one, spawn, call the other, with the request id
+as the `key`.
+
+## Answers and comments coming back
+
+This is item 2's tail: "as soon as I finish answering questions or commenting,
+to be able to send those to agent directly from this board."
+
+A runner-spawned child reaches the board through the HOSTED endpoint, under
+its own run key (`X-Glytch-Session`, `session.key` - the same key `report()`'s
+`PM_SESSION_KEY` already uses). The runner reaches for `collect_session`,
+exactly the tool a session would call by hand - `bridge/lib/rowsAnswers.mjs`
+is the whole of it. Only a runner-spawned session ever has an idea behind it
+at all - a CLI request or a conversational session has nothing to collect, and
+`collect_session` says so plainly rather than erroring.
+
+- **While the child runs**, the runner polls `collect_session` through
+  `hosted.callTool`, passing the child's OWN run key as `X-Glytch-Session`
+  and a `since` watermark it advances from each reply's `next_since`. A
+  matching reply hint on the runner topic wakes collection immediately. While
+  joined, a one-minute safety read catches missed hints; without push,
+  `PM_ROWS_POLL_MS` (default 5000ms, `settingsFromEnv`) remains the fallback.
+  Rejoining also wakes collection. `collect_session`
+  already matches "this run's own rows" server-side; what the runner adds
+  is remembering which ANSWERED QUESTION it has already delivered (the
+  tool hands back every one of this key's answered questions on every
+  call, with no time filter). A MESSAGE is stamped `delivered_at` only once
+  the child TOOK it (round 4 item 75): the poll passes `delivered`, the ids
+  the child accepted since its last call, and the endpoint hands a message
+  back unstamped until a call names it; the post-exit sweep sends the last
+  acks, and what still comes back is carried on as a resume or, when no run
+  can carry it, recorded on the sidecar as `undelivered` for the card. Each new
+  row becomes a stdin message through the exact door a typed reply already
+  uses (`sendToChild` in `child.mjs`'s `runStreamingChild`) - a message as
+  `[message from <from>] <text>`, matching a reply file's own attribution.
+  Wired only when the run has a bearer to send at all (`glytch login` or
+  `GLYTCH_BOARD_TOKEN`); with neither, there is nothing on the hosted
+  endpoint for the child to have asked in the first place.
+- **After the child exits**, ONE more `collect_session` call
+  (`promoteLateRows`) catches whatever arrived in the gap between the last
+  live poll and the exit, called from `completeRequest` right after the
+  receipt is written. `promoteLateRows`'s `promote` callback is
+  `runnerApi.resume`, for every request kind, chat turns included: the
+  runner sends one `resume {runId, message}` call and the board-runner
+  function inserts the approved child run row server-side.
+  `acceptsMessages`' one-shot-vs-persistent distinction decides "logged and
+  dropped" vs "resumed" the same way it always has. A content-addressed id
+  (`lateRowRequestId`) keeps a duplicate promotion attempt from filing the
+  same resume twice.
+- **The one known gap**, spelled out rather than hidden: a MESSAGE that
+  arrives in the same poll tick the child happens to exit on is marked
+  `delivered_at` by that fetch whether or not `sendToChild` actually got to
+  write it before the pipe closed - `watchAnswers` breaks its delivery loop
+  the moment the child is settled, before calling `onDelivered`. Such a
+  message is not "late" (it was already fetched) and will not come back on
+  a later poll either (the server will not hand it back). An ANSWERED
+  QUESTION has no such gap - it carries no `delivered_at`, so it is simply
+  asked for again, here or on the next live poll, until this run's own
+  delivered-set has actually recorded it.
+
+The file-based reply path (`<id>.reply-*.json`) stays working alongside this:
+a human typing into a running session still goes straight down the same
+stdin door, file or row.
+
+A session collects with the `collect_session` tool, passing `since`. The
+watermark is the caller's, not the daemon's, so it survives a restart, and
+`since: 0` reads everything. An EXITED session cannot be woken - that is a
+new session, which is a spend, which is a click.
+
+**Images travel the same doors.** A message's `images` travel into `resume`
+alongside `message` when the poll has any (`rowsAnswers.mjs`'s
+`createRowsAnswerPoll`/`promoteLateRows`), and a LIVE answer's images reach a
+still-running child through `child.mjs`'s `userMessage`, which turns them into
+native image blocks. `collect_session` writes a message's pictures as a
+`{"images":[...]}` line right under it; the poll reads that line per message,
+or, when a batch is one message, the block the tool wrote. A picture that
+cannot be read (bad data URL, too large) never drops its message: the text
+goes through with a short line saying a picture came and could not be read.
+`bridge/test/rowsAnswers.test.mjs` runs this through the fake binary.
+
+## Money - the constraint that outranks the feature
+
+A spawned session bills the user's subscription. A spawned session that loops
+bills it repeatedly and does so overnight. Every one of these is a bound, and
+each is enforced in code, not in a comment:
+
+| bound | value | what it stops |
+| --- | --- | --- |
+| runner off by default | `PM_SPAWN_RUNNER=on` AND an explicit `watch` command | a runner that starts itself because something imported it |
+| per-request approval | `approved: true`, or the request is refused | a row nobody clicked "run" on ever running |
+| `claim` is the start | `claim` moving a row to `status:'running'` IS the start - the row exists under RLS the moment `run_request` inserted it, so nothing waits for a receipt | a run that is on the board but not yet accounted for |
+| concurrency | `PM_SPAWN_MAX_CONCURRENT`, **any number by default** since 2026-08-28, counted from `runs {status:'running'}` plus the runner's own in-flight set | ten requests becoming ten sessions |
+| no shared working tree | a session that wanted isolation, could not get a worktree, and finds another session running is refused before it spawns (2026-08-28) | two agents editing one checkout with no branch between them |
+| wall clock | `maxMs`, default 90min (`DEFAULT_WALL_MS`), at most 2h (`MAX_WALL_MS`), both in `spawn.mjs` | a session that hangs billing all night |
+| no retry, ever | a failed request is terminal | paying twice for the same failure |
+| no re-run on edit | one request id, one run | a saved file re-billing |
+| the fake binary | `PM_CLAUDE_BIN` | every test in this suite costing money |
+| the board's controls say the price | two callers, both a human click, both labelled with the spend AND with the size the payload weighs (`spawnPayloadFor`, 2026-08-27) | a control that spends without saying so |
+| one request per idea in flight | an idea whose request is filed and unclaimed reads "Waiting" and files nothing (`fileSpawnRequest`, 2026-08-27) | a double press billing twice for one intent |
+
+**The default of one session at once is gone, since 2026-08-28**, on the ruling
+"No cap, my click is the cap", asked for out loud: *"I would like to operate
+multiple sessions at once on the board."*
+
+Worth recording because the number was never the thing that stopped a second
+session, and reading the table would have told you it was. `pollOnce` awaited
+each child inside its own loop, so ONE WATCHER RAN ONE SESSION AT A TIME
+whatever the cap said - the cap was decoration, and being set to 1 is what
+made the serial behaviour look deliberate. Worse, the same await starved the
+runner's own liveness mark, which was refreshed once per pass: with a session
+running the mark aged past the app's 30s window, the board said "A runner was
+watching but has stopped" over a session that was running fine, and the gate
+that message drives refused to file anything else. One running session made a
+second one impossible, and nothing in the money table was doing it.
+
+What replaces the number: `startPending` starts runs without awaiting them,
+slots are counted as the union of the claims on disk and the runner's own
+in-flight set, and the mark beats on its own timer (`RUNNER_BEAT_MS`, a third
+of the staleness window). A clean stop now drains its children before clearing
+the mark, so Ctrl-C still writes every receipt.
+
+**"One click files a session" is gone, 2026-08-26 (later the same day)**, and
+the halo wedge that did it. He ruled the confirm dialog off that morning
+(`q-mt9q8qrg`, "One click is what I said, drop it"), then reversed the rule
+himself once the shape of the feature was clear: *"Yes reverse the one click
+rule.. Already we're making things efficient enough."*
+
+What replaces it is not a confirm step - it is the idea becoming the
+one place a run is configured. An idea carries a TARGET (an OpenRouter model,
+or a Claude Code session, the latter unselectable while the setup is
+incomplete) alongside the run settings it already has, and Run means run,
+whichever target is set. So a session costs the same one gesture a model run
+costs, and the second "click" is a property you set once rather than a
+question asked every time.
+
+Recorded because the two rulings read as contradictory out of context - the
+first removed a step from a control that was about to be deleted, the second
+deleted the control. Neither is a reversal of the money principle: every
+session still needs a deliberate human action, and `approved: true` is still
+set by that action alone.
+
+**"The board's own button confirms - one dialog, then the click that
+approves" is gone from this table, since 2026-08-26.** It shipped and he ruled it out the same
+day (`q-mt9q8qrg`, "One click is what I said, drop it"), consistent with the
+brief that asked for the work. Recorded rather than deleted because a later
+session reading the money section would otherwise reinvent it as an obvious
+improvement. It is not an improvement he wants: the click IS the approval, and
+a dialog in front of it is a machine being careful with his money on his
+behalf, which is the thing this product exists to stop. The bound that
+replaces it is the row above - a control that spends has to say so on its own
+label, and `src/store.spawn.test.ts` pins the caller list so a third caller
+cannot appear quietly.
+
+**No run has a spend or token limit (#364).** The wall clock is the one
+bound on a single run; the runner still counts cost and tokens off the
+child's own usage events, for the receipt, and nothing it counts stops a run.
+The free AI that comes with a new account is the only limit, and it is the
+model proxy's, not the runner's.
+
+**No autonomous spawning.** Nothing in this repo files a request on its own.
+The runner runs what it is given and refuses what is not approved; the deciding
+is the human's, exactly as `ask_user` and proposals already are. That is not a
+policy bolted on top, it is the rule the rest of the bridge already keeps:
+`runPrompt`, `generateMore`, `composeDoc` and `composeBrief` are all refused by
+the ops vocabulary for the same reason - "they spend the user's model credits"
+(`INBOX_OPS.md`).
+
+## The one thing that needed `src/` - BUILT 2026-08-26
+
+This section records the ruling that closed a real gap: the runner half was
+complete before the app could FILE a request, so spawning still needed a
+terminal. The ruling on `q-mt9kh6xc` - "Yes, build the button next" - closed
+it, and it is built.
+
+The app's half is `src/folder/spawnRequest.ts` (the request shape, REIMPLEMENTED
+rather than imported - nothing under `src/` may import from `bridge/`), plus
+`fileSpawnRequest` in `src/store.ts`, which is the one call this section
+predicted:
+
+```ts
+await writeFolderFile(handle, `inbox/spawn/${id}.json`, JSON.stringify(request));
+```
+
+Two ways in, and each is ONE click: the Go button on an idea
+(`src/nodes/IdeaCard.tsx`), and a row in the selection bar's overflow menu
+for anything else (`src/components/SelectionBar.tsx`). That click writes the
+file, and that click IS the human gesture that sets `approved: true`.
+
+The ruling, twice. The brief that asked for this work: "Filing and approving
+may be one gesture here BECAUSE it is a human click; the CLI keeps them
+separate only because a script can call the CLI." Then `q-mt9q8qrg`, after it
+shipped with a confirm dialog in front of it and he was asked whether to keep
+the second click: "One click is what I said, drop it." The fork this section
+used to say was "not guessed at here" was closed by him, not by a session.
+
+So the gate is the CALLER LIST, and it is two controls, both a human click,
+both labelled with what they cost. Nothing inside `fileSpawnRequest` checks
+that a person asked - it cannot, and it is not supposed to. That safety
+property lives in the call graph and in no type, so it has a test:
+`src/store.spawn.test.ts` reads `src/` and fails if a third caller appears.
+
+Filing does not start anything, and the app says so without a dialog to say it
+in. Nothing in the app starts a runner or could - a browser cannot spawn a
+process - so both controls carry the caveat on their own label, and the
+toolbar's receipt pill says "Needs the runner" rather than reporting a
+session.
+
+`node bridge/spawn-runner.mjs request ...` still works and is still the only
+way for a SCRIPT to file one, unapproved, with `approve` as a separate command.
+The app collapses the two because there is a person at the other end of the
+click; the CLI cannot, because a script can call the CLI.
+
+**This is a RULING, not a session's invention, and it is worth saying so.**
+It was set directly in the brief that opened the session which built the
+button, 2026-08-26: filing and approving may be one gesture here BECAUSE it
+is a human click, and the CLI keeps them separate only because a script can
+call the CLI. He confirmed it again the same day when asked to choose between
+one confirm, splitting filing from approving, and forcing the full prompt
+into the dialog: "One confirm is enough."
+
+It is recorded here because until now it was not written down anywhere a
+reader could check. This file previously said the fork was "a UI decision on
+contested files, so it is not guessed at here", and the paragraph above
+replaced that with the rule but not with its source - so a later reader would
+have found an unattributed rule about money and no way to tell whose it was.
+The shipped design is in fact STRICTER than he allowed: he permitted one
+click, the button uses two, and the first writes nothing.
+
+**He ruled against this route, 2026-08-26.** Asked on `q-mt9kh6xb`
+whether answering a question should be able to file a spawn request, he
+answered "No, keep spending on its own gesture". Do not build it. The
+reasoning below is kept because it explains what was rejected and why the
+option is tempting; it is not a design still on the table.
+
+~~There is a second route that needs no app UI at all~~, and it was worth knowing
+before the button was designed: a question note IS a human approval gate.
+`addQuestion` lands live, only the human can answer it, the answer reaches the
+mirror, and a dismissal means no. A session could propose "Spawn a Claude Code
+session to do X?" with options, and the runner could treat the answered question
+as the approval and file the request itself. It needs no app change and it works
+today. It is deliberately NOT built, because it turns every question note into
+a potential spend, and that is a bigger decision than a night's work should make
+on its own.
+
+## Signal files - stop, merge, delete, relaunch
+
+`stop`, `merge`, `delete` and `relaunch` are all rows - `heartbeat`'s `stops`
+array and its `ops` + `opTake`/`opResult` (`bridge/lib/runner.mjs`'s
+`serviceRowOps`) - for every request kind, chat turns included. `relaunch`'s
+record is the claimed run row's own `server` column (mirrored there by
+`runnerCompletion.mjs` when the child exits), falling back to the op's
+`worktreePath` hint plus the worktree's own live `.glytch-server.json` when
+the row has none yet. The pure decision core, `relaunchServer`
+(`bridge/lib/devserver.mjs`), decides exactly what is below - only where the
+record comes from and where the answer goes is rows rather than files.
+
+Kept below: the SHAPE of each signal, named for the file it once travelled as
+- what it decides, not how it travels.
+
+| signal | shape | what the runner does |
+| --- | --- | --- |
+| stop | `{ worktreePath }` | sends SIGTERM to the child, writes receipt |
+| merge | `{ worktreePath }` | Keep changes: commits the copy's leftovers, merges into the default branch around the person's uncommitted changes, deletes the copy and its branch |
+| delete | `{ worktreePath }` | Throw away: removes the worktree and deletes the branch without merging |
+| relaunch | `{ worktreePath }` (optional, a hint) | re-runs the RECORDED dev server command, detached, in the recorded worktree, or in the linked folder once that worktree is gone |
+
+Each of the first three carries at least `{ worktreePath }`. The runner
+consumes the op after acting on it (on success only for merge, so a failed
+merge can be retried). A merge that clashes writes `conflict: true` and
+`files` (the clashing paths) into its result; a merge that lands writes
+`files` as the count changed. No question is filed: the app sends Coding back
+to fit its changes around the person's (#483).
+
+`relaunch` is the odd one: its body is optional, nothing more than a hint for
+finding the record, it is consumed on refusal as well as on success - the
+receipt is the answer, and a signal left behind would relaunch on every pass
+- and the command it runs is never in the op. See "Who starts it again" above
+for what it refuses and why.
+
+**Keep safety (#483).** `mergeWorktree` in `bridge/lib/worktree.mjs` first
+commits what the agent left uncommitted in the copy, as the person or as
+Glytch when git has no name, never its `node_modules` link (#482), then tries
+the merge with `git merge-tree --write-tree`, which touches no file. A clash,
+including one with the person's uncommitted changes or a file of theirs git
+does not track or ignores where the merge adds, renames or copies a file
+(read from the disk, since a fast-forward overwrites an ignored file
+without a word), stops with nothing in the folder
+changed and names the files. When the folder is on the default branch, the
+person's changes are set aside with a named stash, the default branch
+fast-forwards to the merge commit, and the stash is applied with `--index`
+and dropped by its sha. When the folder is on another branch, only the
+default branch's ref moves (compare-and-swap) and the folder's files stay
+put. Then the copy and its branch are deleted. Nothing is pushed.
+
+## Per-idea lock
+
+Added 2026-08-30. The ruling on `q-mtf2x89x`: "Only one session per idea,
+unless the old session lost its worktree."
+
+`activeWorktreeForPromptRows` in `bridge/lib/runner.mjs` reads this project's
+run rows through `runnerApi.runs`, then checks whether a worktree for the
+given idea still exists on disk AND its branch has not been merged into
+main. Both halves matter: without the merged check, a finished session
+blocks its own idea forever. The former file-scanning
+`activeWorktreeForPrompt` helper in `worktree.mjs` was deleted on
+2026-09-14; admission has used the rows version since 2026-09-11.
+
+**Own-tree exemption.** A request whose `worktreePath` is one of the same
+idea's own kept worktrees bypasses the lock and runs IN that tree, on its
+branch: a resume (Claude, a Codex thread, and opencode, which tries to resume
+and falls back to a fresh session; D8), and since 2026-10-04 (brief 52
+review, D7) a new session naming the tree without `resumeSessionId` (a note
+after a done session that recorded no id). The lock prevents a SECOND tree,
+not the idea from working on its own branch. A request naming no tree (Rerun)
+is still refused, and a named tree that is gone gets a new one
+(`runnerWorkspace.mjs`). A request naming a tree no run of ITS idea made
+(another idea's tree, or a path no row holds) is treated as tree gone (round
+3, item 67). The lock's exemption and the own-tree match compare paths through
+`realpathSync.native` (items 69, 70), and the tree is reused under its own
+recorded spelling, so an 8.3 short name or a `/var` spelling of a
+`/private/var` tree still reuses it.
+
+## Chat turns
+
+Added 2026-09-07, brief 25 session 1, on the rulings of the same day. Ruling
+1A: **a coding agent's chat turn runs through the daemon**, as a persistent
+Claude Code conversation, one per DM, on his subscription, with Claude Code's
+own tools plus the board tools. Until this, a DM with an agent whose engine
+said `claude-code` was an OpenRouter API call like every other chat turn -
+so "Coder, engine claude-code" had never once run on Claude Code when you
+talked to it.
+
+**DONE OVER ROWS, 2026-09-11 (brief 30 Move 2b).** Move 2 (the same day,
+earlier) shipped the ordinary session path over rows and refused a
+chat-turn row outright, naming the per-room lock and the chat worktree mint
+as file-shaped work not migrated in that pass. Both are rows now: the
+per-room lock is `activeChatTurnForRoomRows` (`bridge/lib/runner.mjs`,
+`runnerApi.runs({..., status:'running'})` filtered to `isChatTurn(request)`
+and a matching `roomId`) in place of a disk scan for an unreceipted claim;
+the chat worktree mint (`makeChatWorktree`/`resolveChatCwd`,
+`bridge/lib/worktree.mjs`) is UNCHANGED - it was never file-shaped, only
+called from the file-based runner, and is called from the rows one now the
+same way. Every difference below is unchanged in what it means; only the
+DOOR each one reaches through moved (a run row and `runnerApi` calls, not a
+signal file) - marked `chat turn:` at each site in `runner.mjs` exactly as
+they are marked here.
+
+**The request is the same shape, riding a row's `request` column, with one
+new field.**
+
+```json
+{
+  "version": 1,
+  "id": "spawn-mtr...",
+  "kind": "chat-turn",
+  "roomId": "room-dm-coder",
+  "cwd": ".claude/worktrees/chat-a-coder",
+  "mintIfMissing": true,
+  "agent": "claude",
+  "model": "",
+  "prompt": "<the room's composed message>",
+  "approved": true,
+  "resumeSessionId": "…",
+  "worktreePath": "/Users/n/proj/.claude/worktrees/chat-a-coder"
+}
+```
+
+| field | required | what it is |
+| --- | --- | --- |
+| `kind` | no | `"chat-turn"`. **Absent means `"session"`**, so every request written before today runs unchanged. An unknown value is refused rather than guessed at - there is no code path to fall back to, and guessing "session" would put a frame on his board. |
+| `roomId` | for a chat turn | Which DM this turn belongs to. It is what the per-room lock locks. |
+| `cwd` | for a chat turn | The directory the conversation lives in. **RELATIVE to the folder root when the app writes it** (a browser directory handle has a name, not a path), absolute when the CLI does, and absolute again from the second turn on because the app hands the runner's own `worktreePath` back. All three are resolved by `resolveChatCwd` (`lib/worktree.mjs`); anything that escapes the watched folder - `..`, an absolute path outside it - is refused. Claude Code keys conversations to a working directory, so the directory is which conversation this is. |
+| `mintIfMissing` | no | `true` asks the runner to CUT the chat worktree if `cwd` is not there. The app cannot make a worktree, and ruling 1's directory has to exist before the first message can run in it. Absent (or `false`) and a missing `cwd` is refused, unchanged. Anything but a boolean is refused rather than read as true. |
+| `boardFolder` | no | One folder name (2026-09-30). The turn runs in that subfolder of the chat worktree, made if missing, so each board has its own place in the Glytch folder. The app sends it when the chat's folder is the Glytch folder (`~/Glytch`, made and registered by the runner when it starts watching; `GLYTCH_FOLDER=off` turns it off, a scratch `GLYTCH_HOME` makes none, and a `GLYTCH_FOLDER` path is for tests: the app knows the Glytch folder only in a home folder). Refused: separators, a leading dot, a trailing dot or space, Windows device names. The sidecar's `worktreePath` is then the subfolder, and a later turn whose `cwd` is that subfolder stays in it whatever `boardFolder` says, so a renamed board's chat keeps its files. |
+| `agent` | no | Must name a coding CLI this bridge has (`isCodingCli`, `lib/agents.mjs`). A SESSION falls back to the default on an unknown name; a chat turn refuses, because answering as `claude` would tell him he is talking to the agent he named when he is not. |
+| `resumeSessionId` | no | Absent on the first message of a conversation, present on every one after it. |
+| `worktreePath` | no | What the sidecar recorded, handed back. For a chat turn it equals `cwd`. |
+
+**The five differences, and no others.**
+
+1. **No frame on the board.** No `startSession`, no outcome written into a
+   frame, no `endSession` - a chat turn writes NOTHING into `inbox/ops/`. It
+   therefore does not wait for the app's receipt either, so it answers with
+   the app closed. Ruling 3: chat bubble only. A streaming terminal on the
+   canvas for every message he types is the noise the board is not for.
+2. **No worktree is minted PER MESSAGE.** It runs in `cwd` and refuses if that
+   is not a directory - it never falls back to the linked checkout, which is
+   his own working tree with an agent holding Write, Edit and Bash. The one
+   exception is asked for by name, `mintIfMissing`, and it makes the agent's
+   ONE long-lived tree (below). The spawn-time orphan sweep is skipped either
+   way: that sweep exists to clear the way for a tree about to be made per
+   run, and `ps -eo pid,args` over every process on the machine is not a thing
+   to do on the path a person waits on for every message they type.
+3. **No repo primer and no attempts log**, and no runner preamble. All three
+   exist to save a FRESH session from rediscovery, and every sentence of the
+   preamble is about a frame ("call `report` before you finish...") that a
+   chat turn does not have. What a chat turn is told is the app's to compose:
+   persona, the room's context blocks, his message.
+4. **A per-ROOM lock instead of the per-prompt one.** OVER ROWS (brief 30
+   Move 2b): `activeChatTurnForRoomRows` (`lib/runner.mjs`) asks
+   `runnerApi.runs({..., status:'running'})` and filters to
+   `isChatTurn(request)` with a matching `roomId`, so two runners sharing a
+   project share one answer the same way the file version's disk scan did.
+   One live turn per room: both would otherwise resume the same conversation
+   in the same directory at once, and a conversation is one thread. A chat
+   turn has no idea behind it, so the per-idea lock above never applies to
+   it, and it never takes one.
+5. **No `chat` word needed to tell traffic apart.** The file version's
+   receipt needed one on its own first line so a person reading
+   `.glytch/inbox/spawn/` - and `readSpawnReceipt`/`store/actions/folder.ts`,
+   which both parsed a receipt by `startsWith("OK"/"ERROR")` - could tell the
+   traffic apart without a second meaning colliding with the first. A row
+   has no such ambiguity: `run.request.kind` says which it is, structurally,
+   on the SAME row a session's `status`/`result` already live on - there is
+   nothing left for the result TEXT to also have to say.
+
+**Everything else is deliberately the same.** Same money gate
+(`approved: true`), same claim-exactly-once (server-side now, `claim`),
+same live log (`run_events` now, `<id>.log` then), same stop signal
+(`heartbeat`'s `stops` now, `<id>.stop` then),
+same wall clock, same stall watchdog, same sidecar, same tool fence
+(`CLAUDE_TOOLS`) plus the board through the cwd's own `.mcp.json`.
+
+**Where the conversation lives, and who makes it** (added 2026-09-07, session
+1b, ruling 1: "one long-lived chat worktree per agent per folder, made
+once and kept").
+
+1. **The cwd is resolved, once, against the folder being watched.** A relative
+   `cwd` is joined onto the folder root; an absolute one is used as it stands.
+   The result is what the child runs in AND what the sidecar records as
+   `worktreePath`, so the app's next turn sends an absolute path back and the
+   conversation stays in one directory.
+2. **A cwd that escapes the folder is refused**, in a receipt that names the
+   resolved path. A chat turn holds Write, Edit and Bash; the linked folder is
+   the boundary the person chose. The folder root ITSELF is allowed - a caller
+   naming it said so - and nothing ever falls back to it.
+3. **`mintIfMissing: true` cuts the tree, once.** `git worktree add -b
+   glytch/chat-<agentId> <root>/.claude/worktrees/chat-<agentId> HEAD`, off the
+   checked-out commit for the same reason `makeWorktree` picks it (whatever he
+   is looking at is what the agent starts from, and naming a branch breaks on a
+   detached head), with `node_modules` symlinked the way a session's tree gets
+   it. A branch that already exists is checked out into the new tree rather
+   than re-created, so a hand-removed tree comes back. The branch name is read
+   off the directory name, which is the only thing both sides have to agree on.
+4. **Only there.** The mint refuses any path that is not
+   `<root>/.claude/worktrees/chat-*` (`isChatWorktreePath`), so a request file -
+   an injection surface - cannot turn "mint if missing" into "make a directory
+   anywhere in my folder". It also refuses a folder that is not a git
+   repository, in words that say a chat needs one for its own worktree; there
+   is no unisolated fallback to offer.
+5. **Nothing removes it.** `cleanWorktree` refuses a chat path (and the runner
+   never calls it for a chat turn), the sweep has never removed a worktree and
+   now says so in its never-touch list, and the orphan reaper steps over a
+   `chat-` name. A chat worktree is removed when the AGENT is deleted, which is
+   not built yet: today the way out is `git worktree remove` by hand, and the
+   next message mints it again.
+
+**The sidecar is written for EVERY chat turn**, not only a persistent one. A
+first message carries no session id to resume, so `isPersistentRequest` is
+false for it and no tree is kept - and without this it would have written no
+sidecar at all. That file is how the room learns which conversation it just
+opened (`claudeSessionId`) and where it lives (`worktreePath`, equal to the
+cwd). No sidecar, no second turn.
+
+**Stop keeps the conversation** (ruling 5). `<id>.stop` kills the child
+and the receipt says `Stopped by user request`, and the sidecar still carries
+the conversation id with no `expired` mark - so the next message resumes where
+it left off. Stop cancels the turn, not the thread.
+
+**No limits are checked here** (#364). The `approved: true` gate and the wall
+clock are what bound a chat turn. `PM_SPAWN_MAX_CONCURRENT` counts a chat turn
+like anything else; it is a machine bound, `Infinity` by default.
+
+**An empty `model` passes no `--model`** (ruling 7): an empty field means
+"you choose", and the daemon is what is running it. This needs no code - it is
+what `commandFor` already does for an unset model.
+
+**What is NOT here.** The app half: the room's routing, the streamed bubble,
+Stop from the room, and the ledger are sessions 2, 3 and 4 of the brief.
+Channels are phase 2 (ruling 2A). See `brief 25`.
+
+## Worktree op receipts
+
+`opResult`'s `result` on the `run_ops` row is the merge and delete receipt,
+in the same `{ok, detail}` shape this section describes below. `relaunch`'s
+receipt works the same way (see "Signal files" above).
+
+Kept below: the SHAPE of each op's outcome, named for the file it once
+travelled as - separate from the session's own result, so a merge outcome
+never overwrites what the session did:
+
+| op | what it records |
+| --- | --- |
+| merge | outcome of a merge operation |
+| delete | outcome of a delete operation |
+| relaunch | outcome of a dev server relaunch: the pid and port, or the refusal |
+
+The app reads the op's result to know when it is done and whether it
+succeeded. `ok: true` means success; `ok: false` means failure, and `detail`
+carries why.
+
+## Worktree summary
+
+Added 2026-08-30. The ruling on `q-mtf66we4`: "One summary line: branch,
+commits, files touched."
+
+`worktreeSummary` in `bridge/lib/worktree.mjs` produces
+`{ branch, commits, files, uncommitted, line }`. `files` counts every file the
+branch touched, committed or not; `uncommitted` is how many are not committed
+yet (#482). The runner writes it into the session
+sidecar (`.session.json`) for every kept worktree, not just persistent ones.
+The app shows the summary line in the session frame before the merge/delete
+buttons.
+
+### The sidecar is written TWICE, 2026-09-08
+
+The write above happens after the child exits, because the summary counts
+commits. That made `worktreePath` - the only thing that tells the app where a
+session works - arrive only once the run was over, so "Where it is working"
+was empty for the whole life of every run. Evidence: `spawn-mtrrmcux-513704`,
+running for hours in
+`.claude/worktrees/glytch-investigate-...-mtrrmcux-513704`, with no
+`.session.json` in `inbox/spawn/` at all.
+
+So the runner now writes a FIRST sidecar as soon as the worktree is minted or
+reused, before the child spawns, carrying `worktreePath` and `fromId` and
+nothing else. The end-of-run write replaces it whole; nothing is carried
+forward. It is written **only for a tree that really is one** (`isolated` and
+a `path`): a run that fell back to the linked checkout has no worktree, and
+recording the checkout under `worktreePath` would put Merge and Delete over
+the linked folder itself.
+
+The app's side of the same gap is in `src/store/actions/folder.ts`: the
+running branch of `refreshSessionPersistence` pushed a patch only when the
+sidecar carried a `worktreeSummary`, so a path-only sidecar was read and
+discarded on every tick.
+
+## Orphan reaper
+
+Added 2026-08-30. `reapOrphanedWorktreeProcesses` in `bridge/lib/worktree.mjs`
+finds processes whose command line references a `.claude/worktrees/<name>` path
+that no longer exists on disk and kills them. Called at spawn/teardown time,
+never as a daemon (ruling `q-mt9as5a0`: no reaper daemon).
+
+**Corrected 2026-09-02: it WAS a daemon, and this paragraph was the only place
+that said otherwise.** `watch`'s loop called both the reaper and the sidecar
+backfill on every five-second pass, for the life of the runner - `ps -eo
+pid,args` over every process on the machine plus two `git` processes per stale
+sidecar, twelve times a minute, learning the same nothing each time. A doc and
+a loop disagreeing about whether something is a daemon is settled by the loop,
+so the loop moved.
+
+`housekeeping(root, log, { reap, backfill })` in `bridge/lib/runner.mjs` now
+holds both, and it runs at the three moments a sweep can find anything:
+
+| when | reap | backfill | why |
+| --- | --- | --- | --- |
+| the watcher starts | yes | yes | whatever a previous runner left behind |
+| a session is about to spawn | yes | no | a leftover process may hold a port or a lock the new tree wants; nothing has ended, so no sidecar can be newly stale, and a person is waiting on this path |
+| a session tears down | yes | yes | its tree may have just gone |
+
+The backfill also **remembers what it tried**. A sidecar whose worktree is
+missing is skipped on a `stat` rather than on two `git` processes, and one
+whose git call produced no summary is recorded and never asked again for the
+life of the process. In memory rather than on disk: the fact is about this
+process's attempts, not about the session, and writing "could not summarise"
+into the sidecar would put a second meaning into a file the app reads.
+`bridge/test/housekeeping.test.mjs` asserts a poll pass does not sweep and
+that `housekeeping` called directly still does.
+
+## Attempts log
+
+Added 2026-08-30. When the runner composes a FRESH child's prompt (new session,
+new worktree - NOT a resume, which carries its own conversation memory), it
+looks up previous requests with the same `fromId` (the idea) whose
+receipts were errors, and appends a 'Previous attempts' section to the prompt.
+
+The section includes:
+
+- Attempt number (chronological, oldest first when displaying)
+- Request ID
+- What it tried: closing summary from the log tail, or the receipt reason when
+  the log is unavailable
+
+**Bounds** (borrowed deliberately from tpm-flow's `attempts.ts`):
+
+- ~700 characters per attempt
+- ~6000 characters for the whole section
+- Oldest attempts dropped first when the cap is reached
+- When something is dropped, the section SAYS so with a count
+
+A silently truncated history reads as a complete one, which is why the omission
+notice is mandatory. Summaries only, never a previous prompt: feeding attempt
+N-1's prompt into attempt N doubles the prompt every re-run.
+
+**What stays unchanged:**
+
+- Read-only over other sessions' files: never edit a receipt or log
+- Exactly-once stays untouched: this changes what a NEW request is told, never
+  retries anything
+- Composed at spawn time from disk, no model call
+- Resume requests see no section: they carry their own conversation memory
+
+The history a re-run needs is already on disk in `.glytch/inbox/spawn/`: earlier
+requests carry `fromId`, their `.result.txt` receipts carry the failure reason,
+and their `.log` tails carry the session's own closing summary.
+
+## Repository primer
+
+Added 2026-08-30. When the runner composes a FRESH child's prompt (new session,
+new worktree - NOT a resume), it prepends a compact repo map showing the file
+tree plus top-level exported symbols per source file. Built to reduce cache
+re-reads: the 3-day spend audit showed 69% of Opus cost was cache re-reads
+across 100+ turn sessions, and a big share of those turns is rediscovering the
+tree through `grep` and `find`.
+
+**Implementation** (`bridge/lib/repomap.mjs`):
+
+- Walks the repo from its root, skipping `node_modules`, `.git`, `dist`,
+  `build`, `coverage`, `canvas`, `inbox`, and dotdirs
+- Emits the file tree (always included)
+- Extracts top-level exported symbols (functions, classes, consts) from source
+  files (`.js`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.jsx`) using regex
+- Deliberately regex-based (not tree-sitter): fast, deterministic, dependency-free,
+  good enough. Reference: tpm-flow's `server/src/repomap.ts` (idea, bounds,
+  regex on purpose); reimplemented here, license boundary matters
+- Caps the whole map at ~10KB; past the cap, keeps the tree and drops symbol
+  detail deepest-first (files furthest from root lose detail first)
+- When detail is dropped, the map SAYS so with a count
+
+**Caching:**
+
+- Cached keyed to HEAD sha in `inbox/spawn/.repomap-{sha}.txt`
+- Regenerate when HEAD moved, reuse otherwise
+- Cache miss rebuilds, cache write is best-effort (doesn't fail the spawn)
+
+**Bounds:**
+
+- Primer + attempts section together must not exceed ~16KB
+- Primer is trimmed first when the combined size exceeds the bound
+- If less than 500 chars remain for the primer after accounting for attempts,
+  no primer is included
+- Truncation includes a notice so a truncated primer doesn't read as complete
+
+**What stays unchanged:**
+
+- Fresh sessions only: resume requests get nothing (their context already knows
+  the tree through conversation memory)
+- Composed at spawn time from disk, no model call
+- Appended after the preamble, before the user's prompt and attempts section
+- The primer says it may be stale versus the session's working branch (HEAD
+  points to main, session works in a worktree on a branch)
+
+## The conversation on an idea
+
+Brief 52, 2026-10-04. A note a person writes on an idea starts a coding
+session; the session answers on that same idea; the computer restarting does
+not lose it. Four pieces, all in the bridge.
+
+**The request's `note` and `agentId` are not the runner's to touch.** The app
+puts `note: {noteId, text}` and `agentId` on the request. The runner copies
+neither, strips neither and never repeats the text: the child gets the prompt
+once, ahead of which the output contract (`preambleFor` in `lib/agents.mjs`)
+sits. `bridge/test/runner.test.mjs` has the test.
+
+**Who is speaking.** A message that reaches a live session arrives as
+`[message from <name>] <text>`, so the session can tell the person from a
+teammate. The contract tells the session to answer through `propose` with an
+`addComment` op and no `id` (it lands as its reply on its own idea), to attach
+pictures with `images` (up to 6, data URLs) and to choose between looks with
+`ask_user` and `images`. It also tells the session not to file a closing reply
+of its own, because the runner files one.
+
+**One reply at the end, for a session that finished.** When a session
+finishes (the verdict is `finished`, or a Codex run exits 0),
+`reportOutcomeOnBoard` posts exactly one `addComment` on the idea, with
+`agentId`, `runId` (the session's own key), `summary` (first sentence of the
+closing text, at most 200 characters), `images` (at most 6), and
+`branch`, `files`, `preview`, `report` for the links. Its text is the closing
+text of the session (the tail, at most 2000 characters), then a single figures
+line led by "Finished": "Finished; 12 turns, 4m, branch x, 3 files". It
+never carries a cost (#281). A stop, an error, a stall, a timeout and a binary that would not start
+write NO comment from the bridge: the app writes those endings itself from the
+row (`src/store/runs/sessionReplies.ts`), so a second one would double it.
+Comments the bridge used to write on those paths are gone.
+
+**Carry on after a restart.** `lib/restartPass.mjs`. When the runner starts,
+and once more seven minutes later, it lists this folder's rows that the last
+process left behind and carries each on once:
+
+- Which rows: idea-bound, not a chat, not a plan, not already flagged
+  `sidecar.restarted`, not run by this process, and either `running` with a
+  lease that was not renewed in the last four minutes, or `error` with a
+  `recovery_reason` and no result when a person's note started it, whatever
+  its age (other reaped rows stay the app's). The second look
+  exists because a lease only runs out five minutes after the process died.
+- A Claude Code session with its worktree kept and a conversation: the row is
+  settled as an error that says why (a `resume` needs a finished parent), then
+  ONE `resume` (with `unlessStopped`, so a Stop that landed after the listing
+  wins) files a child that continues the same conversation in the same
+  worktree with "Your computer restarted while you were working. Carry on from
+  where you were." The child keeps `agentId` and `note`, so its closing reply is
+  signed and keyed like the first. The `resume` op carries the parent's
+  `sidecar.worktreePath` into the child's request; without it the per-idea lock
+  would refuse the child as a stranger.
+- A session that cannot resume (Codex, opencode, or a failed `resume`): the row
+  is settled the same way and ONE reply lands on the idea, "Your computer
+  restarted during this session, so it stopped.", with the
+  branch and file count. The branch is kept.
+- A Claude Code session whose worktree is gone is left alone for the reaper.
+- ONE ATTEMPT. The settle writes `sidecar.restarted: true` first and `result`
+  is write-once, so of two runners racing for a row exactly one wins and goes
+  on. The winner records `sidecar.restartedTo`. A flagged row is never a
+  candidate again. The app must not write its own ending reply for a row with
+  `sidecar.restarted`.
+
+`bridge/test/restartPass.test.mjs` runs the pass against the fake binary.
+
+## Verdict and cost
+
+Added 2026-09-01. The runner now tracks the full result envelope (not just two
+booleans) and surfaces turn count, time and context fill in the receipt. The
+cost is kept in the sidecar for the run's record, and no receipt or reply
+shows it (#281).
+
+**Envelope tracking:** `runChild` and `runStreamingChild` scan stdout for
+result envelopes (`{"type": "result", ...}`) and keep the LAST one parsed as
+`outcome.envelope`. Context fill is tracked separately: the last assistant
+event's `usage` (ignoring events with `parent_tool_use_id`, so subagent turns
+cannot overwrite the lead's fill). Fill = `input_tokens` +
+`cache_read_input_tokens` + `cache_creation_input_tokens`, exposed as
+`outcome.contextFill`.
+
+**Verdict line:** one-line summary computed from the envelope and outcome.
+Format: `finished` / `ended with an error result` / `stopped responding` /
+`killed at wall clock` / `exited N`, followed by figures from the envelope when
+present: `41 turns, 38m, context 212k`.
+
+**Where it lands:**
+
+- `reportOutcomeOnBoard` writes the one closing reply on the run's idea, and
+  only for a session that finished (see "The conversation on an idea"). Its
+  figures line reads "Finished;" then turns and time, without context or
+  cost. The words above stay exactly as they are in the row's
+  `result`: the app parses them (`verdictOf`, `resultTail`).
+- `describeOutcome` puts the verdict line at the start of the receipt text.
+- `writeSessionSidecar` gains `costUsd`, `numTurns`, `contextFill` fields so
+  `spendSince` and other readers can use them when present.
+
+No new model calls, no new file shapes beyond sidecar fields.
+
+## Stall watchdog
+
+Added 2026-09-01. A streaming session (`runStreamingChild` only) that goes
+silent for `stallMs` (default 15 minutes) with a turn open is killed with
+SIGTERM then SIGKILL. The watchdog is armed only when the MODEL should be
+producing output: a turn is open (no result envelope since the last user
+message) AND no `tool_use` is awaiting its `tool_result` (a running tool is
+allowed to be silent; the wall clock covers a hung tool).
+
+**How it works:** The stream-json scanner tracks `tool_use` blocks (by id) and
+their `tool_result` events. A `tool_use` opens, a `tool_result` closes. Tool
+results arrive as USER events (`{"type":"user","message":{"content":[{"type":"tool_result",...}]}}`),
+and that is what re-arms the watchdog. The stall timer checks every `stallMs / 4`
+whether it is armed (turn open, no open tools) and whether `Date.now() - lastStdoutAt >= stallMs`.
+If both, it kills the child. Sending a new user message resets `lastStdoutAt` (a new turn starts).
+
+**Outcome:** `stalled: true` and `stallMs` when it fires. Receipt and frame say
+"stopped responding" with the silence duration. It is not a success and not a
+timeout.
+
+**Settings:** `PM_SPAWN_STALL_MS` sets the timeout (default 900000, 15 minutes).
+
+## Crash retry
+
+Added 2026-09-01. A crash that happens BEFORE any assistant event streamed is
+retried exactly once, inside the same wall-clock budget. SIGKILL is never
+retried (the runner itself killed it). A crash after output streamed is not
+retried (partial work would be duplicated).
+
+**Exit code classification** (`bridge/lib/exitClass.mjs`): `classifyExit(code,
+signal)` distinguishes crashes (SIGSEGV, SIGABRT, SIGBUS, SIGILL, SIGFPE,
+SIGTRAP on Unix; 0xC0000005 and 0xC00000FD on Windows) from clean exits and
+other failures. SIGKILL is classified as `isKill: true`, not a crash. Returns
+`{ isCrash, isKill, description }`.
+
+**Retry logic in runRequest:** After the first run, if `exitClass.isCrash &&
+!outcome.envelope && !outcome.finished`, the runner logs "retrying once" and
+runs the child again with `maxMs` set to the remaining wall-clock budget
+(original `maxMs` minus the first run's duration). Both logs are kept:
+`outcome.log` becomes `=== First attempt (crash class) ===\n...\n\n=== Retry
+===\n...`. The outcome carries `retried: true` and `firstCrashClass`.
+
+**Receipt:** When retried, the receipt says "Retried once after [class] before
+any output" in the `where` footer.
+
+## What the tool fence stops, and what it does not
+
+Added 2026-09-02, correcting a claim that stood in `lib/agents.mjs` and
+`bridge/README.md`: that a Claude session "cannot open a shell". It can.
+`CLAUDE_TOOLS` carries `Bash(git:*)`, `Bash(npm:*)`, `Bash(npx:*)` and
+`Bash(node:*)`, and `Bash(node:*)` alone is `node -e '<anything>'` - an
+arbitrary program with the session's own file access. `Write` and `Edit` are
+unscoped, so the session may write any path the process can reach.
+
+| | stopped | not stopped |
+| --- | --- | --- |
+| tools | anything not on `CLAUDE_TOOLS` | everything on it |
+| interactive prompts | `EnterPlanMode`, `AskUserQuestion` | - |
+| arbitrary code | - | `node -e`, `npx <anything>` |
+| writes | the checkout you are looking at (the **worktree** does this, not the list) | any other path the process can reach |
+| money | wall clock, no retry | - |
+
+**The specific hole this opens.** A child gets `PM_BOARD_ROOT` (`childEnv`)
+and has `Write`, so it can file its own `.glytch/inbox/spawn/<id>.json`
+carrying `approved: true` and have the runner that spawned it pick it up.
+`PM_SPAWN_DEPTH` refuses a session that starts its OWN runner; it does nothing
+about a session asking the runner above it.
+
+**There is no cheap discriminator, and one was looked for.** Every field the
+app writes - `createdBy: "board"`, `approvedBy: "board"`, `version: 1`,
+`nodeIds` (`src/folder/spawnRequest.ts` `buildSpawnRequest`) - is a field a child with
+Write can spell exactly. Refusing requests filed *while a session is running*
+would be a real narrowing but it would break a shipped ruling: "I would like
+to operate multiple sessions at once on the board" (2026-08-28), which is
+precisely a person clicking Go on a second idea while the first is going.
+Anything stronger (an HMAC over the request, a nonce the app and the runner
+share) means app work and a shared secret in a folder both sides can read, and
+that is a bigger change than this class of risk earns while the runner is off
+by default and every real request starts with a click.
+
+So it is **recorded rather than guarded**. Narrowing `CLAUDE_TOOLS` is the
+lever that actually closes it, and that is the user's ruling to make: it changes
+what a brief can do.
+
+## Asks in the idea (#478)
+
+A coding run that wants something outside its list (`CLAUDE_TOOLS`, or
+what Codex runs without approval) asks the person instead of being refused
+silently. `lib/permissionAsk.mjs` owns it; `child.mjs` answers Claude's
+`control_request` and `codex.mjs` answers Codex's approval requests with it.
+
+- One `ask_user` question on the run's idea: "Can I run pip install requests
+  in my-app?", with Allow (recommended), Not this and Always allow in
+  <folder>, and a line on what it is for.
+- The asker claims its question on the answer poll and reads the answer with
+  `check_answer` itself: an answer resolves the pending request, it is never
+  typed into the conversation.
+- No answer means keep waiting. Stop and the wall clock still end the run;
+  the stall watchdog does not count time spent waiting for a person.
+- Always allow is remembered per folder in
+  `<glytch home>/permissions/<sha256 of the folder path>.json`: a shell
+  command by its first word (`Bash(pip:*)`), anything else by its tool name.
+  A remembered rule is answered without asking. A chained, piped or
+  redirected command is asked every time.
+- A plan draft is read-only and is never given the asker.
+
+## What a spawned session inherits
+
+Added 2026-09-02. `childEnv` in `bridge/lib/runner.mjs` used to be
+`{ ...process.env }`. A spawned session is an autonomous agent with Write,
+Edit and Bash in a worktree on this machine, so that handed it every secret
+the shell that started the runner happened to be carrying - a deploy token, a
+database URL, a payment key, whatever `direnv` loaded for the project. A leak
+through that door is invisible: no error, no log line, nothing on the board.
+
+It is an ALLOWLIST now, and everything on it is there for one of two stated
+reasons: a process has to be able to BE a process, and the two engines this
+runner knows have to be able to AUTHENTICATE. Anything else is dropped.
+
+**Exact names.** `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `TMPDIR`, `TMP`,
+`TEMP`, `LANG`, `TERM`, `TZ`; `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` and
+their lowercase spellings, `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`,
+`SSL_CERT_DIR`; `CLOUD_ML_REGION`; `CLAUDECODE`.
+
+**Prefixes.** `LC_`, `PM_`, `ANTHROPIC_`, `CLAUDE_`, `AWS_`, `GOOGLE_`,
+`XDG_`, `OPENCODE_`, `OPENAI_`, `OPENROUTER_`, `FAKE_CLAUDE_`.
+
+**Authentication is mostly `HOME`, and that is worth saying out loud.** Claude
+Code's subscription credentials live in `~/.claude/.credentials.json` (or the
+macOS keychain); opencode's live under `~/.local/share/opencode/auth.json`.
+Neither needs a key in the environment to work. The variables above are for
+the people who set one instead: `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`,
+`CLAUDE_CODE_OAUTH_TOKEN`, `AWS_*` for Bedrock, `GOOGLE_APPLICATION_CREDENTIALS`
+plus `CLOUD_ML_REGION` for Vertex, `OPENAI_API_KEY` / `OPENROUTER_API_KEY` for
+opencode. Every one of those names was read out of the shipped binaries on
+2026-09-02 (`strings` on `claude` 2.1.x and on `opencode`), not assumed.
+
+`FAKE_CLAUDE_` is on the list because the fake binary is a shipped seam, not a
+test detail: `PM_CLAUDE_BIN` is a row in the money table above, and
+`test/fixtures/fake-claude.mjs` is driven entirely by `FAKE_CLAUDE_*`. Drop
+them and the crash, timeout and runaway paths lose their only tests.
+
+**`PM_SPAWN_ENV_ALLOW` is the escape hatch**, because opencode ships around
+two hundred `*_API_KEY` provider names and enumerating them here would make
+this list a lie. It is a comma-separated list of variable names, and a
+trailing `*` makes one a prefix:
+
+```bash
+PM_SPAWN_ENV_ALLOW='CEREBRAS_API_KEY,MYCO_*' PM_SPAWN_RUNNER=on node bridge/spawn-runner.mjs watch
+```
+
+The three doors `childEnv` closes on purpose are closed AFTER the allowlist
+runs, so the `PM_` prefix does not quietly re-open them: `PM_SPAWN_RUNNER` is
+deleted (a spawned session must not be able to switch a runner on),
+`PM_SPAWN_DEPTH` is set rather than inherited, and `PM_SESSION_FROM` is
+dropped unless this run has an idea of its own (a stale idea is worse than
+no idea). `bridge/test/childenv.test.mjs` asserts both ends of the list.
+
+## Per-repo worktree lock
+
+Added 2026-09-01. Git mutations on the same repo root run one at a time,
+serialized by an in-process lock. Two sessions finishing concurrently can no
+longer both `git checkout main`, pull, and merge at the same time.
+
+**How it works:** A promise chain keyed by repo root (normalized with
+`resolve()`). Acquiring the lock means waiting for the existing chain and
+setting a new promise; releasing resolves that promise so the next waiter can
+proceed.
+
+**Amended 2026-09-02: it is two locks, because there are two ways to collide.**
+This section said "one runner process owns a root (claim files keep two runners
+apart), so an in-process lock is enough", and the code beside it disagreed:
+`spawn-runner.mjs merge <path>` and `spawn-runner.mjs delete-worktree <path>`
+are a SECOND process, typed by a person, calling straight into `mergeWorktree`
+while a watcher is running. Claim files keep two runners off the same REQUEST;
+they say nothing about two processes running `git checkout main` in the same
+second.
+
+So `withRepoLock` also takes a **lockdir**, `mkdir` being the one atomic
+exclusive create every filesystem agrees on - the same reasoning the claim file
+uses `flag: "wx"`. It lives at `<root>/.git/pm-repo.lock`, and that location is
+load-bearing rather than tidy: a lock `git status` can see would read as the
+person's own change, and Keep sets those aside and puts them back.
+`.git/` is the one directory git never reports, it is exactly per-repo, and it
+is already where git keeps its own locks.
+
+An `owner.json` inside it records pid, host and time, which is how the lock
+survives its holder being killed: a pid that is gone **on this host** frees it
+at once, a lock from another host frees on age (`LOCK_STALE_MS`, 10 minutes).
+Waiting is bounded (`LOCK_WAIT_MS`, 60s) and losing the wait is not fatal - it
+logs loudly and goes ahead, because refusing to clean up a worktree is worse
+than the race that was there all along. A `.git` that is a file (the root is
+itself a linked worktree) or a read-only checkout takes the same path.
+
+**No `git pull`.** `mergeWorktreeImpl` used to run `git pull --ff-only` on the
+user's main before merging, best-effort and unexplained. Removed 2026-09-02: it
+is a network operation on his main branch that nobody asked for. It moves main
+under him, brings down commits he has not looked at, can prompt for credentials
+with nobody watching, and hangs on a slow or absent remote while a button on
+his board spins. Merging is local work on local branches - the same reasoning
+the code already gave for not pushing.
+
+**What is locked:** `makeWorktree`, `cleanWorktree`, `reuseWorktree`,
+`mergeWorktree`, `deleteWorktree`. Each wraps its implementation (`*Impl`) with
+`withRepoLock(root, fn)`.
+
+**What stays unlocked:** Reads (`branchOfWorktree`, `worktreeSummary`) and
+the runner's `activeWorktreeForPromptRows` admission check do not mutate git
+state and run without the lock.
+
+**Test:** `bridge/test/worktree.test.mjs` proves two concurrent `mergeWorktree`
+calls on the same root serialize (order preserved, second starts after first
+completes, both commits land in main).
+
+## The ACP engine
+
+Added 2026-09-02 (brief 15 decision 8, on the amendment written by the spike
+in `spikes/acp-2026-09-02/`). Checked against the code in this commit.
+
+`acp-claude` is a third engine in `bridge/lib/agents.mjs`, labelled "Claude
+Code via ACP". It runs `@agentclientprotocol/claude-agent-acp` 0.73.0 over
+stdio with `@agentclientprotocol/sdk` 1.4.0 - the versions the spike pinned,
+now the two dependencies in `bridge/package.json`. **`claude` is untouched and
+is still the default.** That is a ruling, not an accident: ACP gives no way to
+SET a spend ceiling and reports no dollar FIGURE, and the `claude` engine has
+both. Beside, permanently - not a migration step.
+
+`bridge/lib/acp.mjs` owns the protocol. Loading it costs nothing on a checkout
+that never installed the adapter: the SDK is a dynamic `import()` reached only
+when an ACP session starts, so every other engine and every other test runs on
+a bare clone.
+
+### What maps onto what
+
+The whole design is that `runRequest`, the live log, the stall watchdog, the
+receipt and the frame need **no branch** for this engine. `acp.mjs` runs the
+adapter, speaks JSON-RPC on its real stdio, and writes *stream-json lines* into
+a stream that `attachChild` reads exactly as it reads a Claude child's stdout.
+
+| ACP | stream-json line the runner already understands |
+|---|---|
+| `session/update` `agent_message_chunk` | `{"type":"assistant", message.content:[{type:"text"}]}` |
+| `session/update` `tool_call` (pending) | `{"type":"assistant", message.content:[{type:"tool_use", id}]}` |
+| `session/update` `tool_call_update` (`completed`/`failed`) | `{"type":"user", message.content:[{type:"tool_result", tool_use_id}]}` |
+| `session/update` `usage_update` `{used, size}` | `{"type":"assistant", message.usage.input_tokens}` → `outcome.contextFill` |
+| `session/prompt` response | `{"type":"result", is_error, total_cost_usd, num_turns, duration_ms}` |
+| `session/new` response | `{"type":"system", subtype:"init", session_id}` → the sidecar's id |
+
+Two details that are load-bearing rather than cosmetic:
+
+- **A tool_use line carries no `usage`.** The scanner in `child.mjs` is an
+  if/else-if chain in which a usage field wins over a content field, so an
+  assistant event carrying both records the usage and never sees the
+  `tool_use` - and the stall watchdog would never arm. The two facts travel as
+  two lines.
+- **Only a *terminal* `tool_call_update` closes the tool.** The spike's capture
+  shows four updates for one call; closing on the first would disarm the
+  watchdog while the tool was still running, which is the exact condition it
+  exists to distinguish.
+
+`available_commands_update`, `current_mode_update` and the `_meta.claudeCode.*`
+side channels are deliberately not written at all: the log is capped and the
+frame draws it.
+
+### The rest of the mapping
+
+- **Board tools.** Every engine reaches the board over the HOSTED endpoint
+  (`supabase/functions/board-mcp`), authenticated by `lib/auth.mjs`'s
+  `hostedToken()`/`hostedConfig()` (a `glytch login` credential, or
+  `GLYTCH_BOARD_TOKEN` for a script), resolved ONCE per request in
+  `runRequest` so a token refresh mid-request cannot leave one engine's
+  wiring disagreeing with another's. `acpServersFor` still builds what
+  `session/new`'s `mcpServers` carries, inline rather than through a file -
+  that half is unchanged - but the entry is now `{type: "http", name:
+  "glytch", url, headers: [{name: "Authorization", value: "Bearer
+  <token>"}, {name: "X-Glytch-Session", value: "<session.key>"}]}` (RENAMED
+  2026-09-12, brief 31, Move 3b: the key was `"board"` until then), the
+  `McpServer::Http` shape checked against `@agentclientprotocol/sdk@1.4.0`'s
+  own schema. `claude` gets the same URL and headers through
+  `--strict-mcp-config --mcp-config '<json>'` (VERIFIED against the
+  installed 2.1.34: `claude mcp add --transport http` writes exactly this
+  JSON shape into a real `.mcp.json`) - `--strict-mcp-config` means any
+  committed `.mcp.json` naming a different server is ignored outright, not
+  merely superseded. `codex` gets a `-c mcp_servers.board={url
+  = ..., bearer_token_env_var = "PM_BOARD_TOKEN", http_headers =
+  {"X-Glytch-Session" = ...}}` override (`codexBoardArgs`, `lib/codex.mjs`) -
+  the bearer is a NAME, never a literal, on that one engine's command line,
+  because `codex mcp add --help` and the installed binary's own strings both
+  say a literal `bearer_token` is refused. `opencode` gets
+  `OPENCODE_CONFIG_CONTENT` (an env var, confirmed present in the installed
+  1.18.23 binary) carrying a `type: "remote"` entry, in place of the
+  `opencode.json` `prepareWorkspace` used to write into the worktree - a
+  bearer token is not a thing to leave sitting in a file for as long as a
+  kept worktree lives. The bearer token's own lifetime is the one thing that
+  needed a NEW decision rather than a rewiring: see `ACCESS_TTL_MS` /
+  `RUNNER_ACCESS_TTL_MS` in `supabase/functions/board-oauth/oauth.mjs`.
+  The **X-Glytch-Session** header is new on the endpoint side too
+  (`supabase/functions/board-mcp/sessionKeyHeader.mjs`): it lets many
+  children spawned under ONE hosted OAuth token each keep their own
+  identity for `list_sessions`/`send_message`, and land their `report()`
+  under the exact run key their receipt already carries.
+  **X-Glytch-Board** rides beside it (2026-09-21, board reporting fix): the
+  claimed run row always carries `board_id` (`src/runs/api.ts`'s
+  `RunRequestRow`), `runRequest` reads it off `run.board_id` and passes it
+  through every engine's board wiring the same way `sessionKey` travels -
+  `acpServersFor`, the headless `claude` engine's `--mcp-config`,
+  `prepareWorkspace`, `codexBoardArgs` (one shared `http_headers` table,
+  since a second one would overwrite rather than merge). Without it,
+  `board-mcp/tools.mjs`'s `boardFor` falls back to `lastBoardId`, unset
+  until the session's first `get_board` - so a session whose first call is
+  `report` used to land on the account's most recently touched board, not
+  the one the prompt actually lived on. `index.ts` reads the header the same
+  way it reads `X-Glytch-Session` (`boardHeader.mjs`) and seeds
+  `lastBoardId` with it before any tool runs. `run.board_id` is the board's
+  LOCAL id ("default", "bd-mua2gtcm"), not the `<account uuid>:<local id>`
+  row id every board is actually keyed by, so the header value may be that
+  local id alone - `tools.mjs`'s `readBoardById` prefixes it with the
+  token's own account before matching a row, falling back to the bare value
+  when that prefixed id is not this account's.
+- **Permissions.** `session/request_permission` is answered by the client from
+  `CLAUDE_TOOLS` - the same list `--allowedTools` gets, one list at a second
+  door. Matching is exact name, MCP namespace (`mcp__glytch` covers
+  `mcp__glytch__report`; renamed from `mcp__board` 2026-09-12, brief 31,
+  Move 3b), or command prefix (`Bash(git:*)` against
+  `rawInput.command`). Anything else, including a rule the matcher cannot
+  parse, is `reject_once`. **Never `allow_always`**: "always" outlives the
+  decision that justified it. Each decision is written into the log as a
+  `{"type":"system","subtype":"permission"}` line.
+- **`CLAUDE_DISALLOWED_TOOLS` has no equivalent and needs none.** Plan mode is
+  a session *mode* on this engine, and `acp.mjs` selects `acceptEdits` and
+  never `plan`.
+- **Model and effort.** The model goes through
+  `session/set_config_option {sessionId, configId:"model", value}` - **not**
+  `session/set_session_config_option`, which this adapter answers `-32601`
+  (both attempts are in the spike's `capture/claude.probe.jsonl`). An option
+  the adapter does not offer is skipped rather than sent and failed. There is
+  no effort option at all on 0.73.0, so `commandFor` records effort as
+  ignored, exactly as it does for `claude`.
+- **Replies into a live session.** A persistent request keeps the session open
+  after its turn and delivers each reply file as a **second `session/prompt`
+  into the same `sessionId`**. `acceptsMessages` now answers true for
+  `acp-claude` as well as `claude`. Prompts are queued and sent one at a time:
+  the adapter advertises `promptQueueing`, but nobody has watched it work.
+- **Stop.** `stopCheck` sends `session/cancel` first and *then* returns true, so
+  `attachChild`'s SIGTERM/SIGKILL is the backstop rather than the mechanism.
+- **The stall watchdog and the wall clock** are byte for byte the rules
+  `runStreamingChild` uses, because the events they read are now the same
+  events. A finished stream is still finished: the wall clock closing an idle
+  session is not a timeout.
+- **`CLAUDE_CODE_EXECUTABLE`.** The adapter ships its **own** Claude Code
+  (2.1.257 against the 2.1.34 on this machine), so every run is pinned to a
+  chosen binary: an explicit `CLAUDE_CODE_EXECUTABLE`, else `PM_CLAUDE_BIN`,
+  else `claude` on `PATH`. Two Claude Codes on one box, one of them invisible,
+  is how a session behaves differently for a reason nobody can see - and every
+  bound in this bridge was checked against 2.1.34. When none resolves the
+  adapter's bundled copy runs and the outcome says so.
+
+### What is an estimate
+
+**Everything about the money.** ACP reports token counts and no dollars: the
+`session/prompt` response carries `usage` and `_meta.quota.model_usage`, and
+the schema's optional `cost {amount, currency}` on `usage_update` is not sent
+by this adapter. The bounds on this engine are the wall clock and the stall
+watchdog, as on every engine (#364).
+
+So the figure is computed: tokens × `ACP_PRICES` in `acp.mjs`, a dated table
+(checked 2026-09-02 against published list prices per million tokens; cache
+write at the documented 1.25× of input, cache read at 0.1×). It is labelled
+wherever it is stored, and no receipt prints it (#281):
+
+- the envelope carries `cost_source: "estimate"`;
+- the session sidecar carries `costSource: "estimate"` beside `costUsd`.
+
+Three things about the number worth stating plainly. It is **cumulative over
+the session**, not per turn, because the runner keeps only the last envelope
+and that is what the receipt records. An **unknown model is priced at Opus
+rates**. And a session on a Claude
+subscription - which is how everything on this machine runs - is not billed
+per token at all, so the estimate answers "what would this have cost on the
+API", which is the only comparable number.
+
+### What is untested
+
+- **Resuming an ACP session.** `loadSession: true` is advertised and
+  `session/load` is *tried* when a request carries `resumeSessionId`, falling
+  back to a fresh session on failure (the fallback is tested; a successful
+  load is not). Nobody has resumed a real ACP session.
+- **Mid-turn steering.** `_meta.steering.supported` and
+  `claudeCode.promptQueueing` are declared by the adapter and exercised by
+  nothing. Replies are queued between turns instead.
+- **Codex, opencode, and every other adapter.** This engine is Claude Code
+  only. The spike got `-32000 Authentication required` from Codex's
+  `session/new` and stopped there, so nothing below Codex's handshake is
+  known. `acp.mjs` refuses with a clear message when an adapter offers auth
+  methods and `session/new` fails - it never logs anything in.
+- **Images on a real run.** Data-URL images are sent as ACP `image` content
+  blocks (the adapter advertises `promptCapabilities.image`), and the one-shot
+  temp-file path in `runRequest` correctly skips this engine because its
+  prompt is not an argument. Neither half has been run with a real image.
+- **The permission door on a real adapter.** Answered from the allowlist in
+  the spike (a stub MCP tool, allowed, turn continued) and covered both ways
+  against the fake adapter here. The two real prompts run for this commit
+  called no tools.
+- **`runRequest` end to end on this engine.** The two real prompts drove
+  `runAcpChild` through `commandFor` with the runner's own options, not
+  through the whole claim → frame → receipt path, because that path spends a
+  session per attempt.
+
+### Tests
+
+`bridge/test/acp.test.mjs`, against `bridge/test/fixtures/fake-acp-adapter.mjs`
+ -  a small node program speaking enough JSON-RPC to be indistinguishable from
+the real adapter for the methods `acp.mjs` calls. It covers the handshake,
+model/mode config, the board server reaching `session/new`, a streamed turn
+with a tool call whose permission is allowed from the allowlist, a rejected
+permission, a second prompt into the same session delivered as a reply file,
+`session/cancel` on Stop, the stall watchdog, an auth wall, a failed resume, a
+missing adapter, the token-to-cost estimate, and the translation itself.
+Nothing here spends money; the two real prompts that proved the engine end to
+end are recorded in the commit body.
+
+## Editable plans and explicit implementation approval (2026-09-08)
+
+A prompt can opt into **Plan first, then ask me to approve**. Existing runs
+without this option keep their previous behavior. The runner advertises
+`planApproval: true` in its heartbeat; the app refuses plan mode on older runners.
+
+The initial request carries `planMode: "draft"`. This is currently supported
+only by Claude Code; opencode, Codex and ACP requests are refused explicitly.
+The runner offers only Read, Glob, Grep, WebSearch and WebFetch. It removes
+MCP servers, skills, hooks, Chrome integration, saved-session inheritance,
+and command-line argument overrides. This is a CLI tool-capability boundary,
+not an operating-system sandbox. The final response is the proposed plan;
+the runner completes the draft and does not start implementation. Replies to
+a draft cannot be promoted into an implementation session.
+
+The draft lives with its prompt as `planReview`. The expanded run shows the
+completed plan in an editable field. Edits save without starting a session.
+**Reject plan** closes that draft. **Approve and implement** is a human-only
+store action, absent from the Board API, agent tools and structured inbox ops.
+It consumes a transient approval, checks the matching successful completed
+run, and files one fresh request. A failed write restores the draft for an
+explicit retry. Running the prompt again while plan mode is selected creates
+a new draft, never an implicit approval.
+
+An implementation request carries `planMode: "execute"`, the exact edited
+`approvedPlan`, `approvedPlanFrom` (the draft request ID), and the usual
+`approvedBy: "board"` / `approvedAt` metadata. The runner independently checks
+that the source was a successful draft for the same prompt IDs before starting
+any child. The filed request captures the reviewed text and original
+prompt/context. Implementation starts in a fresh session; the reviewed plan
+stays visible in the expanded run. As with existing spawn approval files,
+the folder is a trusted local transport, not a cryptographic identity system.
+
+### Operational timing receipts
+
+Settled runs retain numeric phase measurements in `sidecar.performance`: queue
+(including approval wait), setup, execution, first protocol output, cleanup and
+total duration. Existing workspace metadata remains alongside the measurements,
+including when Stop or setup failure occurs before spawning. Local
+`runner.performance` and `runner.delivery` logs distinguish execution from
+receipt acknowledgment. These contain no prompt/output text; they are not a
+central analytics export. See `docs/sentry.md` for definitions and current gaps.
+
+### Explicit computer app discovery (#1132)
+
+A runner advertising `computerAppsLook: true` receives `computer-apps` operations
+on its existing heartbeat after the person presses Look in Settings. Each
+operation targets a project and request id. `computerAppsTake` claims it once;
+`computerAppsResult` writes only names, source labels, availability states and
+which sources could not be read. No prompt/model turn or app tool runs. The
+saved result is informational: every real run still performs its existing
+computer-app approval preflight. Unclaimed requests expire after ten minutes;
+a failed or interrupted look needs another press. The old result survives a
+new request, and a late answer cannot overwrite a newer request.