viewable-one 0.0.0-stage → 0.12.1

package/lib/child.mjs

@@ -0,0 +1,1252 @@
+import { imageAttachments } from "./imageAttachments.mjs";
+// RUNNING A CHILD PROCESS, and nothing about the board.
+//
+// Split out of runner.mjs on 2026-09-02, verbatim: this is the "process half"
+// its own section comment already named, plus the bounds that only the child
+// uses and the environment it is handed. runner.mjs kept `runRequest` - the
+// one function that has to know about both halves - and re-exports everything
+// here, so every existing importer and every test is unchanged.
+//
+// Nothing in this file reads or writes the board. It takes a binary, some
+// arguments and a wall clock, and gives back what happened. That is what made
+// it separable, and keeping it that way is what keeps the crash, timeout,
+// runaway and stall paths testable against a fake binary.
+
+import { spawn } from "node:child_process";
+import { readFile, readdir, unlink } from "node:fs/promises";
+import { createWriteStream } from "node:fs";
+import { createGzip, constants as zlibConstants } from "node:zlib";
+import { join } from "node:path";
+
+import { killTree } from "./kill.mjs";
+import { RUNNER_BEAT_MS } from "./spawn.mjs";
+import { runnableCommand } from "./windows-command.mjs";
+
+// Defaults, all overridable by env and all bounds rather than preferences.
+export const DEFAULTS = {
+  // It was 1, and nobody ever chose that either. What it cost is worth
+  // writing down because the symptom looked like something else entirely:
+  // with one watcher the cap was never even reached, because pollOnce awaited
+  // each child, so sessions were serial by construction and the number was
+  // decoration. The visible failure was the runner going quiet - see
+  // RUNNER_BEAT_MS in spawn.mjs.
+  //
+  // Infinity is "any number at once", not "unbounded spending", and the guards that
+  // actually bound spend all stay: off unless PM_SPAWN_RUNNER is exactly
+  // "on", approved: true per request, one click per session, the board
+  // answering before anything is billed, the wall clock, no retry, no re-run
+  // on edit. PM_SPAWN_MAX_CONCURRENT still sets how many run at once for anyone
+  // who wants that, and the count is still read and still shown.
+  maxConcurrent: Infinity,
+  pollMs: 5_000,
+  // How often the watcher updates row-backed presence. Overridable so a
+  // heartbeat test does not have to wait ten real seconds.
+  beatMs: RUNNER_BEAT_MS,
+  // How long a SIGTERM'd child gets to exit before SIGKILL.
+  killGraceMs: 5_000,
+  // Stall watchdog: no stdout for this long with a turn open (no result envelope
+  // since the last user message AND no tool_use waiting for its tool_result) kills
+  // the child. Default 15 minutes. Armed only when the MODEL should be producing
+  // output; a running tool is allowed to be silent (the wall clock covers a hung tool).
+  stallMs: 15 * 60_000,
+  // Child output kept per session. Enough to debug, small enough that a
+  // runaway printing a gigabyte does not fill his disk - and deliberately
+  // BELOW what the app will read.
+  //
+  // It was 512KB against the app's 500,000-byte read limit, so a long session
+  // produced a log the board could not open and the terminal vanished mid-run
+  // with no explanation. Two caps that disagree are one bug waiting for a long
+  // enough session, and this one waited about six minutes.
+  maxLogBytes: 400_000,
+};
+
+// How the cap SPENDS itself, once it binds. Keeping the first 400,000 bytes
+// and dropping everything after is the wrong way round: the beginning is a
+// prompt he already wrote, and the end is why the session died. So the kept
+// log has two ends and a hole in the middle.
+//
+// The share is head-light on purpose. What a session started with is a few
+// hundred lines; what killed it is the last few.
+const HEAD_SHARE = 0.25;
+// Stderr, kept in its OWN buffer that the stdout flood cannot reach. A crash
+// reason is one line, and merging the two streams is how that one line ends
+// up buried under 400,000 bytes of event JSON with no way to find it.
+const STDERR_KEEP = 8_000;
+
+/** A ring with two ends, and the single definition of what a capped log is.
+ *
+ * The first headBytes are kept as they arrive; after that everything lands in
+ * a rolling tail, and what falls out of the tail is counted rather than
+ * silently forgotten.
+ *
+ * What the old head-only cap cost: spawn-mtbqgnys-67d5e4 (2026-08-27) ran
+ * 6m18s, filled the cap with opencode event JSON, exited 1, and had its
+ * reason thrown away. The frame then showed 150 characters of whatever source
+ * file the session happened to be reading last, because "the tail of the log"
+ * was really "wherever the cap landed, mid-line".
+ *
+ * It lives out here because THREE readers need the same answer: runChild's
+ * final log, runStreamingChild's, and the live file the APP tails while the
+ * session is still running. That third one used to keep its own head-only
+ * rule, which is how a run could go blind seven minutes in - see the live
+ * writer in runRequest. (DATED REWRITE 2026-09-07, brief 26 ruling 4: the
+ * tailer was the session frame's terminal, which is retired; the same file
+ * is now the run's raw transcript, read from the expanded run.) */
+export function makeLogRing(maxBytes) {
+  const headBytes = Math.floor(maxBytes * HEAD_SHARE);
+  const cutNote = (n) =>
+    `\n\n[truncated: ${n} characters dropped from the MIDDLE, limit ${maxBytes}. The start and the END are both here.]\n\n`;
+  // Leave room for the note itself, so a capped log still fits under the cap.
+  // The reserve is measured with a zero count plus room for any digits the
+  // real one turns out to have - a reserve sized from maxBytes is three
+  // characters short the moment a session drops more than it kept.
+  const tailBytes = Math.max(0, maxBytes - headBytes - cutNote(0).length - 24);
+  let head = "";
+  let tail = "";
+  let dropped = 0;
+  return {
+    push(chunk) {
+      if (head.length < headBytes) {
+        const room = headBytes - head.length;
+        head += chunk.slice(0, room);
+        chunk = chunk.slice(room);
+        if (chunk.length === 0) return;
+      }
+      tail += chunk;
+      if (tail.length > tailBytes) {
+        dropped += tail.length - tailBytes;
+        tail = tail.slice(-tailBytes);
+      }
+    },
+    get dropped() {
+      return dropped;
+    },
+    text() {
+      return dropped > 0 ? `${head}${cutNote(dropped)}${tail}` : head + tail;
+    },
+  };
+}
+
+/** A second, independent sink for a child's stdout: the FULL, untruncated
+ * bytes, gzipped as they stream, written to `<dir>/transcript.jsonl.gz`.
+ *
+ * Deliberately NOT makeLogRing. The ring stays exactly what it was - head,
+ * tail, hole in the middle - because live in-process readers (finalObject,
+ * the app's own log reads) depend on that shape today.
+ * This is a tee beside it, fed the same chunks, for the operator who needs
+ * the part the ring dropped.
+ *
+ * `--output-format stream-json` already emits one JSON object per line, so
+ * this writes each raw chunk exactly as it arrives on stdout - no
+ * line-buffering, no re-parse/re-serialize. Concatenating the gunzipped
+ * bytes back together reproduces the child's stdout byte for byte.
+ *
+ * Opened in append mode: one job attempt runs several containers (triage,
+ * each implement round, verify, review) sharing the same evidence dir, and
+ * each is a fresh call to this function. A concatenated multi-member gzip
+ * file is a valid gzip stream - every member decodes in order - so append
+ * keeps every stage's bytes instead of the last container truncating the
+ * ones before it.
+ *
+ * Diagnostic tooling must never be a reason a real job fails: every failure
+ * here (a full disk, a read-only mount, a bad path) is caught, reported once
+ * through `warn`, and the sink goes quietly inert. Nothing here ever throws
+ * into the caller or touches the child's own outcome. */
+export function openTranscriptSink(dir, {
+  warn = (message) => { try { process.stderr.write(`${message}\n`); } catch { /* nowhere left to say it */ } },
+  // An interval scheduler that cannot outlive its owner, e.g. attachChild's
+  // own `every` (unref'd, tracked in a Set settle() clears). Standalone
+  // callers (tests, or any caller with no such lifecycle to join) fall back
+  // to a private unref'd setInterval with the same shape.
+  every = (fn, ms) => { const t = setInterval(fn, ms); if (t.unref) t.unref(); return t; },
+} = {}) {
+  if (!dir) return null;
+  let failed = false;
+  const fail = (label, error) => {
+    if (failed) return;
+    failed = true;
+    warn(`[transcript] ${label}: ${error instanceof Error ? error.message : String(error)}`);
+    // A write() just before this may have returned false, leaving the caller
+    // paused and waiting on onceDrained (an alias for gzip's own 'drain') to
+    // resume its source. The real drain will never come once the stream has
+    // errored, so fire it here - a no-op if nothing is listening. gzip may
+    // not exist yet if createGzip() itself is what failed.
+    gzip?.emit("drain");
+  };
+  let gzip;
+  let file;
+  let closing = null;
+  try {
+    gzip = createGzip();
+    file = createWriteStream(join(dir, "transcript.jsonl.gz"), { flags: "a" });
+  } catch (error) {
+    fail("failed to open transcript sink", error);
+    return null;
+  }
+  gzip.on("error", (error) => fail("gzip stream error", error));
+  file.on("error", (error) => fail("write stream error", error));
+  gzip.pipe(file);
+  // A hard kill (OOM, SIGKILL on the container) never gets to run close()
+  // below. A periodic sync flush means gunzip can still read everything up
+  // to the last flush instead of refusing the whole file for a trailer that
+  // never landed.
+  const flushTimer = every(() => {
+    if (failed || !gzip.writable) return;
+    try { gzip.flush(zlibConstants.Z_SYNC_FLUSH); } catch { /* next tick retries */ }
+  }, 5000);
+  return {
+    /** Returns false when the caller should pause its source until
+     * `onceDrained` fires - the same contract as `Writable.write()` - so a
+     * slow disk applies backpressure instead of buffering every stdout
+     * chunk of a 20-minute run in memory. */
+    write(chunk) {
+      if (failed || !gzip.writable) return true;
+      try { return gzip.write(chunk); } catch (error) { fail("write failed", error); return true; }
+    },
+    onceDrained(callback) { gzip.once("drain", callback); },
+    /** Ends the gzip stream so the trailer is flushed and the file on disk is
+     * valid gzip rather than a stream cut mid-frame. Safe to call more than
+     * once and safe to call after a failure.
+     *
+     * RESOLVES WHEN THE FILE IS COMPLETE (2026-09-19, brief 43 review). It
+     * used to return at once, and runChild settled on the same tick, so a
+     * reader that opened transcript.jsonl.gz straight after the run saw the
+     * trailer still in flight: gunzip answered "unexpected end of file"
+     * (Z_BUF_ERROR), one run in ten under the test suite and the same odds
+     * for any caller that reads the transcript right away. The promise
+     * settles on the write stream's `finish` (all bytes handed to the fd),
+     * on its error, or after two seconds, so a hung disk never pins a run
+     * that has already ended. */
+    close() {
+      clearInterval(flushTimer);
+      if (failed) return Promise.resolve();
+      if (!closing) {
+        closing = new Promise((done) => {
+          const timer = setTimeout(done, CLOSE_WAIT_MS);
+          if (timer.unref) timer.unref();
+          const finish = () => { clearTimeout(timer); done(); };
+          file.once("finish", finish);
+          file.once("error", finish);
+          if (gzip.writableEnded && file.writableFinished) finish();
+          else { try { gzip.end(); } catch { finish(); } }
+        });
+      }
+      return closing;
+    },
+  };
+}
+
+/** How long close() waits for the transcript file to finish before letting
+ *  the run settle anyway. */
+const CLOSE_WAIT_MS = 2000;
+
+/** Compute context fill from assistant usage.
+ * Fill = input_tokens + cache_read_input_tokens + cache_creation_input_tokens. */
+export function computeContextFill(usage) {
+  if (!usage || typeof usage !== "object") return null;
+  const input = Number(usage.input_tokens) || 0;
+  const cacheRead = Number(usage.cache_read_input_tokens) || 0;
+  const cacheCreation = Number(usage.cache_creation_input_tokens) || 0;
+  return input + cacheRead + cacheCreation;
+}
+
+/** Tokens on ONE assistant usage event - input + output + both cache kinds.
+ * `computeContextFill` above answers "how full is the window right now"
+ * from the LAST such event alone; this is the per-event number `totalTokens`
+ * sums across every event in the run, for the receipt. */
+export function computeTurnTokens(usage) {
+  if (!usage || typeof usage !== "object") return 0;
+  const input = Number(usage.input_tokens) || 0;
+  const output = Number(usage.output_tokens) || 0;
+  const cacheRead = Number(usage.cache_read_input_tokens) || 0;
+  const cacheCreation = Number(usage.cache_creation_input_tokens) || 0;
+  return input + output + cacheRead + cacheCreation;
+}
+
+/** The money on a result envelope, under whichever name the build that wrote
+ * it used. `total_cost_usd` is what Claude Code emits today; the two older
+ * spellings are read after it so an older recording is not silently free.
+ *
+ * IT IS THE SESSION TOTAL SO FAR, not this turn's cost, so the last envelope
+ * is the whole answer and adding them up would bill a long session several
+ * times over. The same reading src/folder/sessionLog/claude.ts gives it. */
+export function costOf(envelope) {
+  if (!envelope || typeof envelope !== "object") return null;
+  for (const key of ["total_cost_usd", "cost_usd", "costUSD"]) {
+    const value = envelope[key];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return null;
+}
+
+/** EVERYTHING BOTH CHILDREN DO, once.
+ *
+ * runChild and runStreamingChild are two ways of running the same process,
+ * and about sixty percent of them was the same code written twice: the log
+ * ring, the stderr tail, the stream-json scanner, the wall clock with its
+ * SIGTERM-then-SIGKILL grace, the stop-file watcher, and the settle that
+ * clears every timer and assembles the result.
+ *
+ * Two copies of a scanner is the expensive kind of duplication here, because
+ * the copies had already drifted: only the streaming one tracked `sawResult`
+ * (the envelope that says a turn is over) and `openToolUses` (what the stall
+ * watchdog arms on). A one-shot child running `--output-format stream-json`
+ * emits exactly the same events, so the one-shot path was throwing away the
+ * tool tracking it could have had. It has it now, and that is the only
+ * BEHAVIOUR this extraction changes.
+ *
+ * What is deliberately NOT here, because it is genuinely different: stdin.
+ * The streaming child has a pipe, an opening message, reply files, pushed
+ * answers and a stall watchdog; the one-shot child has none of it and its
+ * stdio is `ignore`. Those stay in runStreamingChild, written against the
+ * handle this returns.
+ *
+ * The handle:
+ *   state       the mutable facts every watcher reads and writes
+ *   kill()      SIGTERM, then SIGKILL after the grace - the one kill path
+ *   every()     an interval that is cleared on settle, so a watcher cannot
+ *               outlive the child it watches
+ *   markSent()  a message went in: the turn is open again and the stall
+ *               clock restarts
+ *   settled()   whether the promise has already been resolved
+ */
+export function attachChild(child, {
+  resolve,
+  maxMs,
+  maxLogBytes = DEFAULTS.maxLogBytes,
+  killGraceMs = DEFAULTS.killGraceMs,
+  stopPollMs = 2000,
+  onChunk,
+  stopCheck,
+  killProcessGroup = false,
+  // What the wall clock means for this child. The one-shot answer is "out of
+  // time"; the streaming answer is "out of time ONLY if the turn is still
+  // open", because for an idle child the wall clock is the reply window
+  // closing and the work is done. Defaults to the one-shot reading.
+  onWallClock = (state) => { state.timedOut = true; },
+  // A result envelope just landed: the turn is over and nothing is billing.
+  // The one-shot child has nothing to do with that (it is about to exit
+  // anyway); the streaming child closes its stdin here, which is the
+  // 2026-09-06 ruling and the whole of "a finished session exits". Called
+  // once per envelope, never after the promise has settled.
+  onResult = () => {},
+  // A `control_request` or `control_cancel_request` line arrived on stdout:
+  // the CLI is asking the host something (today, "may I use this tool?" under
+  // `--permission-prompt-tool stdio`). Only the streaming child has a stdin to
+  // answer on; the one-shot child never passes this and the lines are ignored
+  // as they always were. Never called after settle.
+  onControl = () => {},
+  // What has been counted so far, after every assistant usage event and
+  // every result envelope. The runner uses it to move the card's numbers
+  // mid-flight instead of only at the end.
+  onSpend = () => {},
+  // Whether this run counts as a success, given how the child ended.
+  okOf,
+  // Fields only one of the two shapes carries.
+  extraFields = () => ({}),
+  // A directory to tee this child's FULL, untruncated stdout into as
+  // `transcript.jsonl.gz` - see openTranscriptSink. Undefined (the default)
+  // means no sink: every existing caller that does not pass this is
+  // unaffected, byte for byte.
+  transcriptDir,
+}) {
+  const ring = makeLogRing(maxLogBytes);
+  const timers = new Set();
+  /** An interval that cannot outlive the child: settle clears every one. */
+  const every = (fn, ms) => {
+    const timer = setInterval(fn, ms);
+    if (timer.unref) timer.unref();
+    timers.add(timer);
+    return timer;
+  };
+  const transcriptSink = openTranscriptSink(transcriptDir, { every });
+  let errTail = "";
+  const keepErr = (chunk) => {
+    errTail += chunk;
+    if (errTail.length > STDERR_KEEP) errTail = errTail.slice(-STDERR_KEEP);
+  };
+  // onChunk is called for EVERY chunk, cap or no cap. It used to sit behind
+  // the memory cap's early return, so a full buffer silenced the live terminal
+  // as well - two caps stacked, one of them invisible. The stream side owns
+  // its own limit and says so on the file when it binds.
+  const collect = (chunk) => {
+    ring.push(chunk);
+    if (onChunk) onChunk(chunk);
+  };
+
+  const state = {
+    // Any assistant event at all: the line between 'retry' and 'do not'.
+    sawAssistant: false,
+    // A result envelope stands: the turn is over and nothing is billing.
+    sawResult: false,
+    resultWasError: false,
+    // The LAST result envelope parsed, for cost and turn count.
+    resultEnvelope: null,
+    // Usage from the last assistant event, for context fill.
+    lastAssistantUsage: null,
+    // Input + output + cache tokens, SUMMED across every assistant usage
+    // event this run has had, for the receipt. Different from
+    // `lastAssistantUsage`/context fill above, which is a snapshot of the
+    // LAST turn alone: this one never resets.
+    //
+    // SUMMED ACROSS DISTINCT MESSAGES, not distinct events (2026-09-21, live
+    // run spawn-qa3-fable-01): Claude Code's stream-json emits one
+    // `assistant` EVENT PER CONTENT BLOCK of a turn (thinking, text, each
+    // tool_use), and every one of them carries the SAME `message.usage` -
+    // same `message.id` - because it is the running total for that message,
+    // not a per-block figure. A three-block turn of ~57k tokens was being
+    // added three times, crossed the 400k cap in 27 seconds and three real
+    // turns.
+    // `lastUsageMessageId`/`lastUsageMessageTokens` below dedupe it: a repeat
+    // of the same message id adds only the DELTA (a later chunk can report a
+    // larger output_tokens than an earlier one), so this equals the sum over
+    // distinct messages of their final usage.
+    totalTokens: 0,
+    // The message id `totalTokens` was last counted against, and the token
+    // figure counted for it - see the note on `totalTokens` above. A message
+    // with no id (an older CLI, a fixture) is never treated as a repeat, so
+    // nothing here changes what an id-less run counts.
+    lastUsageMessageId: null,
+    lastUsageMessageTokens: 0,
+    // tool_use ids without their tool_result yet: the stall watchdog is
+    // disarmed while a tool is running, because a running tool is allowed to
+    // be silent and the wall clock covers a hung one.
+    openToolUses: new Set(),
+    lastStdoutAt: Date.now(),
+    timedOut: false,
+    stoppedByUser: false,
+    stalled: false,
+    settled: false,
+  };
+
+  /** COUNT WHAT THIS RUN HAS USED, for the card's numbers and the receipt.
+   *
+   * Called after every event that can move any of the three numbers: a
+   * result envelope (money) and an assistant event with usage (room, and the
+   * running total). `cost` is the session total the envelope reports;
+   * `contextTokens` is the LAST turn's input side; `totalTokens` is the
+   * running total summed across every turn. Nothing here stops a run: there
+   * are no run limits (#364). */
+  const countSpend = () => {
+    const spend = {
+      cost: costOf(state.resultEnvelope),
+      contextTokens: state.lastAssistantUsage ? computeContextFill(state.lastAssistantUsage) : null,
+      totalTokens: state.lastAssistantUsage ? state.totalTokens : null,
+    };
+    try { onSpend(spend, state); } catch { /* a listener must not take the child down */ }
+  };
+
+  // THE STREAM-JSON SCANNER. Events are one JSON object per line and only
+  // stdout carries them.
+  let lineBuf = "";
+  const scan = (chunk) => {
+    lineBuf += chunk;
+    // A line the child never ends must not grow this without bound. Nothing
+    // parseable we care about is this long; a real envelope is a few KB.
+    if (!lineBuf.includes("\n") && lineBuf.length > 1_000_000) {
+      lineBuf = "";
+      return;
+    }
+    const lines = lineBuf.split("\n");
+    lineBuf = lines.pop() ?? "";
+    for (const raw of lines) {
+      const line = raw.trim();
+      if (!line.startsWith("{")) continue;
+      try {
+        const parsed = JSON.parse(line);
+        if (parsed === null || typeof parsed !== "object") continue;
+        if (parsed.type === "assistant") state.sawAssistant = true;
+        if ((parsed.type === "control_request" || parsed.type === "control_cancel_request") && !state.settled) {
+          try { onControl(parsed); } catch { /* a listener must not take the child down */ }
+        }
+        if (parsed.type === "result") {
+          state.sawResult = true;
+          state.resultWasError = parsed.is_error === true;
+          state.resultEnvelope = parsed; // keep the LAST one
+          // AFTER the state is written, so a listener that closes stdin sees
+          // a consistent picture, and never after settle - the child is gone
+          // and there is nothing left to tell.
+          if (!state.settled) {
+            try { onResult(state); } catch { /* a listener must not take the child down */ }
+          }
+          // AFTER onResult, so a streaming child has already closed its stdin
+          // for the turn before the wall is read. Where the wall fires, the
+          // handoff message reopens the turn through markSent - which is the
+          // one order in which "finish the turn, then stop" can actually be
+          // said to a child that was about to exit.
+          countSpend();
+        }
+        if (parsed.type === "assistant" && parsed.message?.usage && !parsed.parent_tool_use_id) {
+          // Context fill = input_tokens + cache_read + cache_creation, from
+          // the LAST assistant event. parent_tool_use_id is skipped so a
+          // subagent's small turn cannot overwrite the lead's number - and
+          // for the same reason it is skipped below, so a subagent's tokens
+          // cannot inflate the lead run's own total either.
+          state.lastAssistantUsage = parsed.message.usage;
+          // ONCE PER MESSAGE, not once per content-block event - see the note
+          // on `state.totalTokens` above. A repeat of the same message id
+          // adds only what grew since the last chunk; a new id (or no id at
+          // all) adds its full figure, same as before.
+          const messageId = parsed.message.id ?? null;
+          const messageTokens = computeTurnTokens(parsed.message.usage);
+          if (messageId && messageId === state.lastUsageMessageId) {
+            state.totalTokens += Math.max(0, messageTokens - state.lastUsageMessageTokens);
+          } else {
+            state.totalTokens += messageTokens;
+          }
+          state.lastUsageMessageId = messageId;
+          state.lastUsageMessageTokens = messageTokens;
+          countSpend();
+        }
+        // Usage and tool lifecycle may appear in the same assistant event.
+        if (parsed.type === "assistant" && Array.isArray(parsed.message?.content)) {
+          for (const block of parsed.message.content) {
+            if (block.type === "tool_use" && block.id) state.openToolUses.add(block.id);
+          }
+        } else if (parsed.type === "user" && Array.isArray(parsed.message?.content)) {
+          // Tool results arrive as USER events with tool_result blocks.
+          for (const block of parsed.message.content) {
+            if (block.type === "tool_result" && block.tool_use_id) {
+              state.openToolUses.delete(block.tool_use_id);
+            }
+          }
+        }
+      } catch { /* a partial or non-event line is not an envelope */ }
+    }
+  };
+
+  child.stdout?.setEncoding("utf8");
+  child.stderr?.setEncoding("utf8");
+  child.stdout?.on("data", (chunk) => {
+    state.lastStdoutAt = Date.now();
+    scan(chunk);
+    collect(chunk);
+    // The disk tee gets the raw chunk directly, same as the ring - stderr
+    // never reaches it, and it sees every byte the ring's cap would drop.
+    // Respect backpressure: a slow disk pauses stdout rather than growing
+    // an unbounded internal buffer for the life of the run.
+    if (transcriptSink?.write(chunk) === false) {
+      child.stdout.pause();
+      transcriptSink.onceDrained(() => child.stdout.resume());
+    }
+  });
+  child.stderr?.on("data", (chunk) => {
+    keepErr(chunk);
+    collect(chunk);
+  });
+
+  let killTimer;
+  /** The one kill path: SIGTERM, then SIGKILL after the grace. A child that
+   * ignores SIGTERM is still billing.
+   *
+   * IT IS THE CHILD'S PID AND NOT ITS PROCESS GROUP, and since 2026-09-06
+   * that is load-bearing rather than incidental. `child.kill(sig)` signals
+   * one pid; `process.kill(-pgid, sig)` would signal everything the child
+   * started, and the child is spawned WITHOUT `detached`, so it shares the
+   * runner's group and a group kill here would reach the runner itself.
+   *
+   * Ruling A that day is what makes the distinction matter: a session
+   * with the Browser switch on starts its dev server detached so the browser
+   * frame outlives the session, and a group kill on the envelope - or on the
+   * wall clock, or on Stop - would take that server down with the child and
+   * put the frame back on a dead port. The daily sweep stops it instead
+   * (lib/sweep.mjs, lib/devserver.mjs), and
+   * bridge/test/detachedserver.test.mjs pins that a grandchild started
+   * detached is still alive after this close.
+   *
+   * ON WINDOWS THE SAME TWO LINES WOULD DO THE OPPOSITE (brief 21, ruling
+   * 4A of 2026-09-07): Node maps both signals to TerminateProcess, so the
+   * grace is a fiction, and it ends one pid while `claude.cmd` runs the real
+   * agent as a grandchild that survives and keeps billing. `killTree` sends
+   * `taskkill /pid <pid> /t` and then `/t /f` there. The POSIX call it makes
+   * is `child.kill(sig)`, this closure's own, so the paragraph above still
+   * describes exactly what happens on his Mac. Package checks alone opt into
+   * killProcessGroup: runChild gives them their OWN group, with no preview
+   * intended to survive. Agent sessions never enable it. */
+  const kill = () => {
+    const send = (force) =>
+      killTree(child.pid, { force, signal: (_pid, sig) => killProcessGroup ? process.kill(-child.pid, sig) : child.kill(sig) }).catch(() => {
+        /* a child that is already gone is not an error here */
+      });
+    send(false);
+    killTimer = setTimeout(() => send(true), killGraceMs);
+  };
+
+  const wallTimer = setTimeout(() => {
+    onWallClock(state);
+    kill();
+  }, maxMs);
+
+  // STOP ON REQUEST: the app writes a .stop file and this poll picks it up.
+  // The SIGTERM + grace + SIGKILL path is the same one the wall clock uses,
+  // so a stopped session ends the same way a timed-out one does.
+  if (stopCheck) {
+    const stopWatcher = every(async () => {
+      if (state.settled) { clearInterval(stopWatcher); return; }
+      try {
+        if (await stopCheck()) {
+          state.stoppedByUser = true;
+          kill();
+          clearInterval(stopWatcher);
+        }
+      } catch { /* a failed check is not a stop */ }
+    }, stopPollMs);
+  }
+
+  const settle = (result) => {
+    state.settled = true;
+    clearTimeout(wallTimer);
+    clearTimeout(killTimer);
+    if (killProcessGroup && (state.timedOut || state.stoppedByUser)) {
+      // The npm parent may close before a script that ignored SIGTERM.
+      try { process.kill(-child.pid, "SIGKILL"); } catch { /* group already gone */ }
+    }
+    for (const timer of timers) clearInterval(timer);
+    // Flush and close the gzip trailer so the file on disk is complete and
+    // valid gzip, whichever way this child ended - and only THEN resolve,
+    // so whoever reads the transcript next finds the whole of it (see
+    // openTranscriptSink's close()).
+    const finish = () => resolve({
+      ...result,
+      log: ring.text(),
+      stderr: errTail.trim(),
+      truncated: ring.dropped > 0,
+      dropped: ring.dropped,
+      timedOut: state.timedOut,
+      stoppedByUser: state.stoppedByUser,
+      envelope: state.resultEnvelope,
+      contextFill: state.lastAssistantUsage ? computeContextFill(state.lastAssistantUsage) : null,
+      // The running total - see the note on `state.totalTokens`.
+      totalTokens: state.totalTokens,
+      sawAssistant: state.sawAssistant,
+      ...extraFields(state),
+    });
+    const closed = transcriptSink?.close();
+    if (closed && typeof closed.then === "function") closed.then(finish, finish);
+    else finish();
+  };
+
+  child.on("error", (error) => settle({ ok: false, spawnError: error.message }));
+  child.on("close", (code, signal) => settle({ ok: okOf(state, code, signal), code, signal }));
+
+  return {
+    state,
+    kill,
+    every,
+    settled: () => state.settled,
+    /** A message went in, so whatever envelope stood no longer describes the
+     * child's state: the turn is open again and the stall clock restarts. A
+     * kill from here on is a kill of work in progress. */
+    markSent() {
+      state.sawResult = false;
+      state.resultWasError = false;
+      state.lastStdoutAt = Date.now();
+    },
+  };
+}
+
+/** Run the child to completion, or kill it at the wall clock.
+ *
+ * The wall clock is not a progress protocol and does not put a third state on
+ * the board. It is the one bound between "a session hung" and "a session
+ * billed all night". */
+export function runChild({ bin, args, cwd, env, input, maxMs, maxLogBytes = DEFAULTS.maxLogBytes, killGraceMs = DEFAULTS.killGraceMs, onChunk, onStdout, stopCheck, stopPollMs = 2000, onSpend, platform = process.platform, transcriptDir, killProcessGroup = false }) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      // On Windows, npm .cmd shims resolve to their JavaScript entry point
+      // so no request argument passes through a shell. `env` is the lookup source
+      // for Path/PATHEXT: it is the child's own environment, already
+      // filtered by childEnv, and carries those names on Windows (session 2
+      // of brief 21, ruling 5B: claude AND opencode both spawn this way).
+      const resolved = runnableCommand(bin, args, { platform, env });
+      // `windowsHide: true` is harmless on POSIX (detect.mjs's execProbe has
+      // carried it unconditionally since before this brief) and stops a
+      // console window flashing per session on Windows.
+      child = spawn(resolved.file, resolved.args, { cwd, env, stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], shell: resolved.shell, windowsHide: true, detached: killProcessGroup && platform !== "win32" });
+    } catch (error) {
+      resolve({ ok: false, spawnError: error instanceof Error ? error.message : String(error), log: "" });
+      return;
+    }
+    // Machine-readable callers must not parse the combined diagnostic log.
+    if (onStdout) {
+      child.stdout.setEncoding("utf8");
+      child.stdout.on("data", onStdout);
+    }
+    // Everything below this line is attachChild's: the ring, the stderr tail,
+    // the envelope scan, the wall clock, the stop watcher and the settle. A
+    // one-shot child adds nothing to it - it has no stdin - so this is the
+    // whole function.
+    attachChild(child, {
+      resolve,
+      maxMs,
+      maxLogBytes,
+      killGraceMs,
+      onChunk,
+      stopCheck,
+      stopPollMs,
+      killProcessGroup: killProcessGroup && platform !== "win32",
+      transcriptDir,
+      ...(onSpend ? { onSpend } : {}),
+      okOf: (state, code) => !state.timedOut && !state.stoppedByUser && code === 0,
+    });
+    if (input !== undefined) {
+      // A child that dies during startup can close the pipe before end lands.
+      // Its process error/close event owns the outcome; stdin's EPIPE is not a
+      // second uncaught failure in the runner.
+      child.stdin.on("error", () => {});
+      child.stdin.end(input);
+    }
+  });
+}
+
+/** A streaming child: stdin stays open, takes JSON-line user messages, exits
+ * when there is nothing more to say. Used for part 3 of the persistent session
+ * spec: typing a reply while the session is still running.
+ *
+ * The initial prompt is sent as the first message on stdin. After that, the
+ * runner watches for reply files in `inbox/spawn/<id>.reply-*.json` and sends
+ * each one as a new user message. The child stays alive until:
+ * - Its turn ends with a result envelope, which CLOSES stdin (2026-09-06):
+ *   nothing more can be said to it, so it exits 0 on its own
+ * - The wall clock fires on a turn that never ended
+ * - The stall watchdog, or a human pressing Stop, kills it
+ *
+ * SHAPE OF A STDIN MESSAGE (verified on CLI 2.1.34):
+ * {"type":"user","message":{"role":"user","content":[{"type":"text","text":"..."}]}}
+ *
+ * A FINISHED STREAM IS FINISHED, whatever closes the process (2026-08-30).
+ * "Exits when there is nothing more to say" was never true of this child:
+ * with --input-format stream-json it ends each turn with a result envelope
+ * ({"type":"result", ..., "total_cost_usd", "session_id"}) and then sits on
+ * stdin waiting for the next message. That wait IS the reply window, but the
+ * ending was read like runChild's: wall clock, SIGTERM, timedOut: true, an
+ * ERROR receipt saying the work is unfinished. 26 of the 28 sessions killed
+ * at the 90-minute wall by 2026-08-30 had their final envelope in the log -
+ * work done, billed, and reported as failed (spawn-mtfx5hex-bb857e: "tsc
+ * clean, build clean, 1865 tests pass", $7.52, receipt ERROR).
+ *
+ * So stdout is scanned for result envelopes as it streams. 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, so every
+ * send 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 carries `finished: true` and is NOT a timeout: the receipt
+ * settles as success and the worktree keeps its persistent-session rules.
+ * The wall clock stays exactly what it was for a child with no envelope: the
+ * money bound on a session that hangs mid-work.
+ *
+ * What a reply does now: a `.reply-*.json` arriving for a child whose stdin
+ * is closed cannot be spoken, so it is handed back through
+ * `onUndeliveredReply` and the RUNNER turns it into a new spawn request that
+ * resumes the session (runner.mjs, promoteReplyToRequest). Nothing is written
+ * to a dead stdin and no reply is dropped. A reply arriving mid-turn - before
+ * any envelope - still goes straight in, which is what the stall watchdog and
+ * `markSent` are about.
+ *
+ * The wall clock keeps its whole meaning for a child MID-TURN, and the
+ * SIGTERM-then-SIGKILL path stays for a child that ignores a closed stdin.
+ *
+ * Returns the same shape as runChild, plus `finished` (the final result
+ * envelope stood when the child ended) and `finishedWithError` (that
+ * envelope said is_error: true - it ended, but not well).
+ *
+ * REPLY POLL: 2000ms until 2026-09-08, 500ms since. A reply typed mid-turn
+ * waited up to two seconds (one on average) before this loop even looked, on
+ * top of everything the CLI then does with it, and that wait is on the path a
+ * person is watching. The cost of the change is one `readdir` of
+ * `inbox/spawn/` four times a second per streaming child instead of twice -
+ * sub-millisecond even on a folder with the 639 files his has - and the loop
+ * only opens a file when a reply is actually sitting there.
+ *
+ * It is NOT the latency he actually complained about, and shortening it is
+ * not a claim to have fixed that: a reply arriving after the turn's result
+ * envelope cannot be spoken at all (stdin is closed on the envelope, the
+ * ruling of 2026-09-06), so it is handed to `onUndeliveredReply` and becomes a
+ * whole new resume request - the watch loop's 5s poll, the app's receipt, the
+ * worktree, and a cold `claude --resume`. That is tens of seconds and it is a
+ * design decision, not a constant. */
+export function runStreamingChild({ bin, args, cwd, env, onSpawn, maxMs, maxLogBytes = DEFAULTS.maxLogBytes, killGraceMs = DEFAULTS.killGraceMs, stallMs = DEFAULTS.stallMs, onChunk, prompt, images, replyDir, replyPrefix, replyPollMs = 500, onUndeliveredReply, answerPoll, answerPollMs = 4000, askPermission, stopCheck, stopPollMs = 2000, onSpend, platform = process.platform, transcriptDir }) {
+  return new Promise((resolve) => {
+    try { imageAttachments(images); } catch (error) { resolve({ ok: false, log: "", spawnError: error.message }); return; }
+    let child;
+    try {
+      // Same resolution as runChild above, and for the same engines (claude
+      // AND opencode per ruling 5B) - streaming is the path a persistent
+      // Claude Code session takes.
+      const resolved = runnableCommand(bin, args, { platform, env });
+      child = spawn(resolved.file, resolved.args, { cwd, env, stdio: ["pipe", "pipe", "pipe"], shell: resolved.shell, windowsHide: true });
+    } catch (error) {
+      resolve({ ok: false, spawnError: error instanceof Error ? error.message : String(error), log: "" });
+      return;
+    }
+
+    if (onSpawn) child.once("spawn", () => onSpawn());
+
+    // The ring, the stderr tail, the envelope scan, the wall clock, the kill
+    // path and the stop watcher are attachChild's - the same ones runChild
+    // uses. What is left in this function is the half a one-shot child does
+    // not have: stdin.
+    const handle = attachChild(child, {
+      resolve,
+      maxMs,
+      maxLogBytes,
+      killGraceMs,
+      onChunk,
+      stopCheck,
+      stopPollMs,
+      transcriptDir,
+      // THE WALL CLOCK MEANS SOMETHING ELSE HERE. Closing an IDLE child is
+      // the reply window ending, not a timeout: the work finished when the
+      // envelope landed. Only a child still mid-turn - no envelope since the
+      // last message it was sent - is out of time. This is the fix for 26
+      // finished sessions receipted as ERROR (see the doc comment above).
+      onWallClock: (state) => { if (!state.sawResult) state.timedOut = true; },
+      ...(onSpend ? { onSpend } : {}),
+      // CLOSE ON THE ENVELOPE, IMMEDIATELY (the ruling, 2026-09-06). The turn
+      // is over; a child holding an open stdin from here is an idle process
+      // costing a file descriptor and a slot until the wall clock, which is
+      // what a background daemon multiplies by every session it has ever run.
+      // Closing stdin is how the real CLI is told there is nothing more to
+      // say: it exits on its own, and `okOf`/`extraFields` below read that
+      // exit exactly as they read a wall-clock close of an idle child.
+      //
+      // Not a kill: a SIGTERM here would race the child's own flush and lose
+      // the tail of the log. The wall clock's SIGTERM-then-SIGKILL path stays
+      // for a child that ignores a closed stdin.
+      onResult: () => {
+        abortPermissions();
+        const stdin = child.stdin;
+        if (!stdin || stdin.destroyed || !stdin.writable) return;
+        try { stdin.end(); } catch { /* the pipe is already gone */ }
+      },
+      onControl: (message) => handleControl(message),
+      // A standing SUCCESS envelope is a finished session whatever the exit
+      // looks like - SIGTERM from the wall clock or from Stop leaves a null
+      // code, and that must not turn done work into a failure. An ERROR
+      // envelope is the opposite: the child itself said the turn went wrong,
+      // and exit 0 must not paper over it.
+      okOf: (state, code) =>
+        state.sawResult
+          ? !state.resultWasError
+          : !state.timedOut && !state.stoppedByUser && !state.stalled && code === 0,
+      extraFields: (state) => ({
+        stalled: state.stalled,
+        ...(state.stalled ? { stallMs } : {}),
+        // Read at the end rather than latched at the kill, so a child that
+        // ended any other way with its envelope standing says so too.
+        finished: state.sawResult,
+        finishedWithError: state.sawResult && state.resultWasError,
+      }),
+    });
+
+    // Send a user message, optionally with images as content blocks.
+    // Images are data URLs (data:image/...;base64,...) from an idea's pictures or
+    // reply files. Claude Code's streaming protocol accepts content arrays with
+    // image blocks alongside text.
+    const userMessage = (text, images) => {
+      const content = [{ type: "text", text }, ...imageAttachments(images).map((image) => ({
+        type: "image", source: { type: "base64", media_type: image.mimeType, data: image.data },
+      }))];
+      return JSON.stringify({ type: "user", message: { role: "user", content } }) + "\n";
+    };
+
+    // AN 'error' ON stdin USED TO KILL THE WHOLE DAEMON. `child.on("error")`
+    // catches SPAWN failures only; it does not cover stream errors on the
+    // pipe, and an unhandled 'error' on a Writable throws. The child can exit
+    // inside the reply poll's own `await readFile`, so the next write lands on
+    // a closed pipe: EPIPE, uncaught, runner dead - and every session still in
+    // flight stays "running" forever, the one leak SPAWN.md only accepts for a
+    // crash. Swallowing here is right because the guarded write below already
+    // reports undeliverable messages by returning false.
+    child.stdin?.on("error", () => {});
+
+    /** Write to the child unless the pipe is gone. Returns whether it went. */
+    const sendToChild = (payload) => {
+      const stdin = child.stdin;
+      if (handle.settled() || !stdin || stdin.destroyed || !stdin.writable) return false;
+      try {
+        stdin.write(payload);
+        handle.markSent();
+        return true;
+      } catch {
+        return false;
+      }
+    };
+
+    // ASK IN THE IDEA (#478). With `--permission-prompt-tool stdio` the CLI
+    // sends a `control_request` (subtype `can_use_tool`) on stdout for every
+    // tool call outside its allowlist and WAITS for a `control_response` on
+    // stdin. `askPermission` files the question and resolves once the person
+    // answers. This is a control message, not a conversation turn: it is
+    // written straight to stdin and NEVER through sendToChild/userMessage, so
+    // the answer resolves the pending request and is not also typed into the
+    // session as a user message.
+    //
+    // While one is pending the stall watchdog stands down (below): a run
+    // waiting on a person is not a stalled run. The wall clock and Stop still
+    // apply, and settling the child aborts every wait.
+    const pendingPermissions = new Map();
+    const abortPermissions = () => { for (const controller of pendingPermissions.values()) controller.abort(); };
+    child.once("close", abortPermissions);
+    child.once("error", abortPermissions);
+    const writeControl = (response) => {
+      const stdin = child.stdin;
+      if (handle.settled() || !stdin || stdin.destroyed || !stdin.writable) return false;
+      try {
+        stdin.write(JSON.stringify({ type: "control_response", response }) + "\n");
+        // The CLI is about to resume; its silence so far was ours.
+        handle.state.lastStdoutAt = Date.now();
+        return true;
+      } catch {
+        return false;
+      }
+    };
+    const answerControl = (requestId, payload) => writeControl({ subtype: "success", request_id: requestId, response: payload });
+    const refuseControl = (requestId, error) => writeControl({ subtype: "error", request_id: requestId, error });
+    function handleControl(message) {
+      if (message.type === "control_cancel_request") {
+        pendingPermissions.get(message.request_id)?.abort();
+        return;
+      }
+      const requestId = message.request_id;
+      const request = message.request ?? {};
+      if (typeof requestId !== "string") return;
+      // Any other question the CLI might put to its host: answer with an error
+      // rather than leave it hanging on a reply that never comes.
+      if (request.subtype !== "can_use_tool") {
+        refuseControl(requestId, `Unsupported control request: ${String(request.subtype)}`);
+        return;
+      }
+      const input = request.input && typeof request.input === "object" ? request.input : {};
+      if (!askPermission) {
+        answerControl(requestId, { behavior: "deny", message: "This run cannot ask the person for permission. Carry on without it." });
+        return;
+      }
+      const controller = new AbortController();
+      pendingPermissions.set(requestId, controller);
+      Promise.resolve()
+        .then(() => askPermission({ toolName: request.tool_name, input, toolUseId: request.tool_use_id, signal: controller.signal }))
+        .then(
+          (verdict) => {
+            // null: the wait was cancelled (the CLI withdrew it, or the run ended).
+            if (!verdict || controller.signal.aborted) return;
+            if (verdict.behavior === "allow") answerControl(requestId, { behavior: "allow", updatedInput: input });
+            else answerControl(requestId, { behavior: "deny", message: verdict.message ?? "The person said no to this. Carry on without it." });
+          },
+          () => { answerControl(requestId, { behavior: "deny", message: "The person could not be asked just now. Carry on without it." }); },
+        )
+        .finally(() => { pendingPermissions.delete(requestId); });
+    }
+
+    sendToChild(userMessage(prompt, images));
+
+    // Watch for reply files. Each file is a JSON object with a `message` string.
+    // Files are sorted by name (timestamp-based) and consumed in order.
+    const watchReplies = () => {
+      if (handle.settled() || !replyDir || !replyPrefix) return;
+      const replyWatcher = handle.every(async () => {
+        if (handle.settled()) { clearInterval(replyWatcher); return; }
+        try {
+          const files = (await readdir(replyDir))
+            .filter((f) => f.startsWith(replyPrefix) && f.endsWith(".json"))
+            .sort();
+          for (const file of files) {
+            if (handle.settled()) break;
+            const full = join(replyDir, file);
+            let text = null;
+            let replyImages;
+            let fromField = null;
+            try {
+              const data = JSON.parse(await readFile(full, "utf8"));
+              text = typeof data.message === "string" ? data.message : null;
+              // Reply files may carry images alongside text, same data URL
+              // format as the spawn request. The runner sends them as image
+              // content blocks on stdin.
+              replyImages = data.images;
+              // Brief 12: agent-to-agent messaging. A `from` field in the
+              // reply file labels the sender (another session's id, the human's
+              // name, anything) so the receiver never mistakes a peer's words
+              // for the user's. The runner wraps it: injection is prompt
+              // injection by design; label it.
+              fromField = typeof data.from === "string" && data.from.trim() !== "" ? data.from.trim() : null;
+            } catch { continue; /* skip malformed reply files */ }
+            try { imageAttachments(replyImages); } catch (error) {
+              const detail = `Reference image reply was not delivered: ${error.message}`;
+              const failure = JSON.stringify({ type: "result", subtype: "error_during_execution", is_error: true, errors: [detail] }) + "\n";
+              child.stdout.emit("data", Buffer.from(failure));
+              handle.kill();
+              return;
+            }
+            // CONSUME BEFORE SENDING. The write used to come first, and an
+            // unlink that then failed (permission, or the app rewriting the
+            // file) left the reply on disk for the next 2s poll to send
+            // again - the human's message arrived at the session twice, with
+            // the failure swallowed. Deleting first means the worst case is a
+            // reply that is not delivered because the child is already gone,
+            // which is not a delivery this could have made anyway.
+            try {
+              await unlink(full);
+            } catch {
+              continue;
+            }
+            if (text) {
+              const attributed = fromField ? `[message from ${fromField}] ${text}` : text;
+              // A REPLY THAT CANNOT BE SPOKEN IS NOT A LOST REPLY (2026-09-06).
+              // Since the envelope closes stdin, this is the ordinary ending
+              // of a finished session rather than a rare race: the human typed
+              // into a session whose turn was already over. The file has been
+              // consumed above, so the words exist only here - hand them
+              // straight back to whoever passed this callback (runner.mjs
+              // turns them into a resume request) rather than dropping them on
+              // the floor the way a `false` from sendToChild used to.
+              if (!sendToChild(userMessage(attributed, replyImages)) && onUndeliveredReply) {
+                try {
+                  await onUndeliveredReply({ text, from: fromField, images: replyImages, attributed });
+                } catch { /* the caller's problem to log; never take the child down */ }
+              }
+            }
+          }
+        } catch { /* replyDir may not exist yet */ }
+      }, replyPollMs);
+    };
+    watchReplies();
+
+    // THE SAME DOOR, for answers the human gave on the canvas after ask_user
+    // had already returned pending. `answerPoll` hands back ready-made
+    // messages so this function stays free of board vocabulary; it knows only
+    // that something upstream may have words for the child.
+    //
+    // Delivery is confirmed AFTER the write, not before: onDelivered is what
+    // records that the session has been told, and marking first would lose a
+    // ruling for good if the child settled in between.
+    let answerBusy = false;
+    const watchAnswers = () => {
+      if (handle.settled() || !answerPoll) return;
+      const collect = async () => {
+        if (handle.settled()) return;
+        // setInterval does not wait for an async callback, and a slow mirror
+        // read would otherwise let two passes see the same unmarked answer.
+        if (answerBusy) return;
+        answerBusy = true;
+        try {
+          for (const answer of await answerPoll()) {
+            if (handle.settled()) break;
+            // Only record delivery if the pipe actually took it, or a ruling
+            // would be marked delivered to a child that never heard it.
+            // `answer.images` (item 6, brief 30 Move 2b): a message's
+            // images, delivered through the SAME content-block channel a
+            // reply file's images already use (`userMessage`, above).
+            if (!sendToChild(userMessage(answer.text, answer.images))) break;
+            if (answer.onDelivered) await answer.onDelivered();
+          }
+        } catch { /* a poll that throws is not an answer either way */ }
+        answerBusy = false;
+      };
+      handle.every(collect, answerPollMs);
+      answerPoll.subscribe?.(collect);
+    };
+    watchAnswers();
+
+    // STALL WATCHDOG: no stdout for stallMs while the MODEL should be producing
+    // output. Armed when 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).
+    const stallWatcher = handle.every(() => {
+      const state = handle.state;
+      if (state.settled) return;
+      const elapsed = Date.now() - state.lastStdoutAt;
+      // A pending permission question is the PERSON's silence, not the model's.
+      const armed = !state.sawResult && state.openToolUses.size === 0 && pendingPermissions.size === 0;
+      if (armed && elapsed >= stallMs) {
+        state.stalled = true;
+        handle.kill();
+        clearInterval(stallWatcher);
+      }
+    }, Math.min(10_000, stallMs / 4));
+  });
+}
+
+// WHAT A SPAWNED SESSION IS ALLOWED TO INHERIT.
+//
+// This used to be `{ ...process.env }`. A spawned session is an autonomous
+// agent with Write, Edit and Bash(node:*) in a worktree on this machine, and
+// handing it the runner's whole environment hands 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. None
+// of that is needed to read a board and write code, and a leak through this
+// door is invisible: no error, no log line, nothing on the board.
+//
+// So it is an ALLOWLIST, and everything on it is here for a stated reason.
+// Two rules, so the list can be read rather than trusted:
+//
+//   1. a process has to be able to BE a process (find binaries, have a home
+//      directory, write temp files, speak a locale);
+//   2. the two engines this runner knows have to be able to AUTHENTICATE.
+//
+// Rule 2 is mostly HOME, and that is worth saying out loud: Claude Code's
+// subscription credentials live in ~/.claude/.credentials.json (or the macOS
+// keychain, which also needs the user's session), and opencode's live under
+// ~/.local/share/opencode/auth.json. Neither needs an API key in the
+// environment to work; the key variables below are for the people who DO set
+// one - checked against the shipped binaries on 2026-09-02 rather than
+// assumed, `strings` on the claude 2.1.x binary and on opencode.
+//
+// Anything else is dropped. `PM_SPAWN_ENV_ALLOW` is the documented escape
+// hatch for a provider not listed here (opencode ships ~200 `*_API_KEY`
+// names and enumerating them would make this list a lie); it is a
+// comma-separated list of names, and a trailing `*` makes one a prefix.
+const CHILD_ENV_ALLOW_EXACT = new Set([
+  // Rule 1: be a process.
+  "PATH",
+  "HOME",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  "TMPDIR",
+  "TMP",
+  "TEMP",
+  "LANG",
+  "TERM",
+  "TZ",
+  // Reaching the network the way the machine does. A corporate proxy or a
+  // custom CA is the difference between a session that runs and a session
+  // that fails at its first request, and neither is a secret.
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "NO_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "no_proxy",
+  "NODE_EXTRA_CA_CERTS",
+  "SSL_CERT_FILE",
+  "SSL_CERT_DIR",
+  // Vertex, for a Claude Code pointed at Google Cloud.
+  "CLOUD_ML_REGION",
+  // Claude Code sets this for its own children; harmless and expected.
+  "CLAUDECODE",
+  // Rule 1 again, Windows' own names for it (session 2 of brief 21,
+  // 2026-09-07). Without SystemRoot a Node child on Windows cannot resolve
+  // DNS - winsock loads from it - so the session starts and then cannot
+  // reach the network, which reads as an auth failure rather than what it
+  // is. Harmless on POSIX: none of these are set there, so listing them here
+  // adds nothing to what a macOS or Linux child receives.
+  "SystemRoot",
+  "windir",
+  "COMSPEC",
+  "PATHEXT",
+  "USERPROFILE",
+  "HOMEDRIVE",
+  "HOMEPATH",
+  "APPDATA",
+  "LOCALAPPDATA",
+  "ProgramData",
+  "ProgramFiles",
+  "NUMBER_OF_PROCESSORS",
+  "OS",
+]);
+
+// Same set, uppercased, for the WINDOWS-ONLY case-insensitive lookup below.
+// Built once rather than per call.
+const CHILD_ENV_ALLOW_EXACT_UPPER = new Set([...CHILD_ENV_ALLOW_EXACT].map((n) => n.toUpperCase()));
+
+const CHILD_ENV_ALLOW_PREFIX = [
+  "LC_", // the rest of the locale
+  "PM_", // this bridge's own contract - see the explicit deletions below
+  "ANTHROPIC_", // API key, auth token, base url, model overrides
+  "CLAUDE_", // CLAUDE_CODE_OAUTH_TOKEN, CLAUDE_CONFIG_DIR, CLAUDE_CODE_*
+  "AWS_", // Claude Code on Bedrock
+  "GOOGLE_", // Claude Code on Vertex (GOOGLE_APPLICATION_CREDENTIALS)
+  "XDG_", // opencode reads XDG_CONFIG_HOME and XDG_DATA_HOME for its auth
+  "OPENCODE_",
+  "CODEX_",
+  "OPENAI_",
+  "OPENROUTER_",
+  // THE FAKE BINARY IS A SHIPPED SEAM, not a test detail sneaking in here.
+  // `PM_CLAUDE_BIN` is a row in SPAWN.md's money table ("every test in this
+  // suite costing money"), and test/fixtures/fake-claude.mjs is driven
+  // entirely by FAKE_CLAUDE_* - which mode to play, where to drop its marker
+  // file, how long to hang. Drop these and the fake binary cannot be told
+  // what to be, so the crash, timeout, runaway and missing-binary paths lose
+  // their only tests. A real engine ignores the name.
+  "FAKE_CLAUDE_",
+  "FAKE_CODEX_",
+];
+
+/** The names in `PM_SPAWN_ENV_ALLOW`, split into exact names and prefixes. */
+function extraAllowFrom(baseEnv) {
+  const raw = typeof baseEnv?.PM_SPAWN_ENV_ALLOW === "string" ? baseEnv.PM_SPAWN_ENV_ALLOW : "";
+  const exact = new Set();
+  const prefixes = [];
+  for (const entry of raw.split(",").map((s) => s.trim()).filter(Boolean)) {
+    if (entry.endsWith("*")) prefixes.push(entry.slice(0, -1));
+    else exact.add(entry);
+  }
+  return { exact, prefixes };
+}
+
+/** The names on the allowlist under `prefixes`, plus `PM_SPAWN_ENV_ALLOW`'s
+ * unless `agentAllow` is false. */
+function allowedEnv(baseEnv, prefixes, platform, { agentAllow = true } = {}) {
+  const extra = agentAllow ? extraAllowFrom(baseEnv) : { exact: new Set(), prefixes: [] };
+  const isWindows = platform === "win32";
+  const env = {};
+  for (const [name, value] of Object.entries(baseEnv ?? {})) {
+    if (value === undefined) continue;
+    const allowed =
+      CHILD_ENV_ALLOW_EXACT.has(name) ||
+      (isWindows && CHILD_ENV_ALLOW_EXACT_UPPER.has(name.toUpperCase())) ||
+      extra.exact.has(name) ||
+      prefixes.some((p) => name.startsWith(p)) ||
+      extra.prefixes.some((p) => name.startsWith(p));
+    if (allowed) env[name] = value;
+  }
+  return env;
+}
+
+/** What a relaunched dev server is told (#324): rule 1 only. A dev server
+ * has to be a process; it has no engine to sign in, so no model key, no
+ * cloud credential and none of this bridge's own `PM_` names reach it. Nor
+ * does `PM_SPAWN_ENV_ALLOW`: that list lets a key through to the AGENT, and
+ * a dev server is the project's own code, not the agent. */
+export function devServerEnv(baseEnv, platform = process.platform) {
+  return allowedEnv(baseEnv, ["LC_", "XDG_"], platform, { agentAllow: false });
+}
+
+/** Everything a child is told, and everything it is deliberately NOT told.
+ *
+ * `platform` gates a CASE-INSENSITIVE match against CHILD_ENV_ALLOW_EXACT,
+ * Windows only: `Object.entries` keeps whatever casing the OS actually used
+ * for a name, and Windows spells the path variable `Path` while this list
+ * (like everything else in Node) says `PATH`. An exact-only match on Windows
+ * drops it silently and hands the child no path at all - one line breaking
+ * every spawn even after the `.cmd` fix. POSIX stays exact-only on purpose:
+ * a stray secret that happens to share a name's case is not this list's to
+ * forgive. */
+export function childEnv(baseEnv, { root, session, depth, fromId, platform = process.platform }) {
+  const env = allowedEnv(baseEnv, CHILD_ENV_ALLOW_PREFIX, platform);
+  // The board it writes to, and the frame its report lands in.
+  //
+  // PM_SESSION_KEY is THE key - the same string startSession was given, taken
+  // from the session record rather than derived again here. The board reads
+  // it and hands it to report() as the key, which is the only reason the
+  // session's report circles land inside its own frame. Mint a different one
+  // and report() silently builds a second frame at top level: no error, and
+  // the board back to being all over the place.
+  env.PM_BOARD_ROOT = root;
+  env.PM_SESSION_KEY = session.key;
+  // THE IDEA THIS RUN CAME FROM, so the child's questions land as notes on
+  // the same idea its frame hangs off. Without it a session's ask_user left
+  // questions floating beside the board: answered, feeding nothing,
+  // and asked again from scratch on the next run. Absent for a CLI request,
+  // and every reader treats absent as "leave it unwired".
+  if (fromId) env.PM_SESSION_FROM = fromId;
+  else delete env.PM_SESSION_FROM;
+  // A spawned session must not be able to switch a runner on. Inheriting this
+  // would let one approved spawn quietly become a spawning machine.
+  delete env.PM_SPAWN_RUNNER;
+  // And it must not be able to spawn even if a runner is somehow started for
+  // it: depth 1 is refused before anything is claimed.
+  env.PM_SPAWN_DEPTH = String((depth ?? 0) + 1);
+  return env;
+}