viewable-one 0.0.0-stage → 0.12.1

package/lib/acp.mjs

@@ -0,0 +1,978 @@
+import { imageAttachments } from "./imageAttachments.mjs";
+// SPEAKING ACP, and translating it into the only event stream this runner
+// knows.
+//
+// Added 2026-09-02 for brief 15 decision 8 ("Engine layer: ACP beside the
+// existing Claude runner"), on the findings of the spike in
+// spikes/acp-2026-09-02/. That spike's `capture/*.jsonl` is the evidence for
+// every shape asserted below; where a line here says "verified", it means a
+// real adapter sent it, not that a doc implied it.
+//
+// WHY THIS FILE EXISTS AT ALL, rather than a second `args` row in agents.mjs.
+// Claude Code speaks `--output-format stream-json`: one JSON object per line
+// on stdout, and the runner's whole apparatus - the live terminal file, the
+// stall watchdog's tool_use/tool_result pairing, the result envelope that
+// carries cost and turn count, the session id extraction - reads that format
+// and nothing else. ACP speaks JSON-RPC 2.0 over the same pipe, with the
+// events arriving as `session/update` NOTIFICATIONS and the turn's outcome as
+// a RESPONSE to a request the client made. Nothing about it looks like a
+// stream-json line.
+//
+// So this module owns the whole difference. It runs the adapter, speaks the
+// protocol, and writes stream-json lines into a stream of its own that the
+// runner's `attachChild` reads exactly as it reads a real Claude child's
+// stdout. The mapping, and it is the point of the file:
+//
+//   agent_message_chunk   -> {"type":"assistant", message.content:[{type:"text"}]}
+//   tool_call (pending)   -> {"type":"assistant", message.content:[{type:"tool_use", id}]}
+//   tool_call_update      -> {"type":"user", message.content:[{type:"tool_result", tool_use_id}]}
+//     (completed/failed)     ... which is what re-arms the stall watchdog
+//   usage_update          -> {"type":"assistant", message.usage:{input_tokens}}
+//     ({used, size})         ... which is outcome.contextFill, for free
+//   session/prompt reply  -> {"type":"result", is_error, total_cost_usd, num_turns}
+//   session/new reply     -> {"type":"system", session_id}  (the sidecar's id)
+//
+// The consequence is that `runRequest`, `formatVerdict`, `describeOutcome`,
+// the live log ring and the frame need NO branch for this engine. An ACP
+// cost is an ESTIMATE and the envelope says so (see ACP_PRICES).
+//
+// WHAT IS DELIBERATELY NOT MAPPED. `available_commands_update` (the local
+// skill list - noise), `current_mode_update`, and the `_meta.claudeCode.*`
+// side channels. A line the runner would ignore is a line worth not writing:
+// the log is capped, and the frame draws it.
+
+import { spawn } from "node:child_process";
+import { PassThrough } from "node:stream";
+import { Readable, Writable } from "node:stream";
+import { createRequire } from "node:module";
+import { accessSync, constants, readFileSync, writeFileSync } from "node:fs";
+import { readdir, readFile, unlink } from "node:fs/promises";
+import { delimiter, isAbsolute, join } from "node:path";
+
+import { DEFAULTS, attachChild } from "./child.mjs";
+
+// ---------------------------------------------------------------- the money
+//
+// ACP REPORTS NO DOLLARS, and that is the one thing the bridge already had
+// that this engine gives up. The spike checked it rather than assumed it:
+// `usage_update` carries `{used, size}` - tokens - and the `session/prompt`
+// response carries `usage` and `_meta.quota.model_usage` with per-model token
+// counts, and NO cost field anywhere. The ACP schema allows an optional
+// `cost {amount, currency}` on `usage_update`; claude-agent-acp 0.73.0 does
+// not send one.
+//
+// So the figure on an ACP receipt is COMPUTED HERE, from token counts times
+// the table below, and every reader is told so: the envelope carries
+// `cost_source: "estimate"` and the session sidecar carries `costSource: "estimate"`, so the
+// receipt says the figure is an estimate.
+//
+// THE TABLE IS A GUESS WITH A DATE ON IT, not a measurement.
+//
+//   - Checked 2026-09-02 against Anthropic's published list prices per
+//     million tokens. Input/output are the list figures; cache write is the
+//     documented ~1.25x of input and cache read the documented ~0.1x.
+//   - A session on a Claude subscription (which is how every session on this
+//     machine runs - the adapter authenticates through the CLI's own
+//     credentials, no API key) is not billed per token AT ALL. The estimate
+//     is therefore an answer to "what would this have cost on the API",
+//     which is the only comparable number.
+//   - Prices move. When one does, this table is wrong and nothing will say
+//     so. That is the price of the engine, and it is why the number is
+//     labelled everywhere it is shown rather than in a comment here alone.
+//
+// Keyed by the model id the adapter reports in `_meta.quota.model_usage`
+// (the capture names `claude-opus-4-6` and `claude-haiku-4-5-20251001`), and
+// matched by longest PREFIX so a dated snapshot resolves to its family.
+/** How long Stop waits for the adapter to ACT on `session/cancel` before the
+ * kill behind it starts. Two seconds is a round trip on a pipe with room to
+ * spare, and it is only ever paid by an adapter that is ignoring the cancel -
+ * one that answers ends the wait the moment its turn comes back. See
+ * cancelTurn, and brief 21's first windows-latest run for why it exists. */
+export const CANCEL_GRACE_MS = 2_000;
+
+const price = (input, output) => ({
+  input,
+  output,
+  // The documented multipliers, not separately published figures.
+  cacheWrite: input * 1.25,
+  cacheRead: input * 0.1,
+});
+
+/** USD per MILLION tokens. See the block comment above before trusting it. */
+export const ACP_PRICES = {
+  "claude-opus-5": price(5, 25),
+  "claude-opus-4-8": price(5, 25),
+  "claude-opus-4-7": price(5, 25),
+  "claude-opus-4-6": price(5, 25),
+  "claude-sonnet-5": price(2, 10),
+  "claude-sonnet-4-6": price(3, 15),
+  "claude-sonnet-4-5": price(3, 15),
+  "claude-haiku-4-5": price(1, 5),
+};
+
+// What an unrecognised model is priced at. NOT zero: a model this table has
+// never heard of that silently costs nothing is a receipt that lies low. Opus
+// rates are the most expensive row, so an unknown model is over-estimated
+// rather than under-estimated.
+const UNKNOWN_MODEL_PRICE = ACP_PRICES["claude-opus-5"];
+
+/** The price row for a model id, by longest prefix. */
+export function priceFor(model) {
+  if (typeof model !== "string" || model.trim() === "") return UNKNOWN_MODEL_PRICE;
+  let best = null;
+  for (const [id, row] of Object.entries(ACP_PRICES)) {
+    if (model.startsWith(id) && (best === null || id.length > best.id.length)) {
+      best = { id, row };
+    }
+  }
+  return best ? best.row : UNKNOWN_MODEL_PRICE;
+}
+
+/** Dollars for one `_meta.quota.model_usage` entry list, or for the flat
+ * `usage` object when the per-model breakdown is absent.
+ *
+ * The field names are the adapter's, taken from the capture:
+ * `{totalTokens, inputTokens, cachedInputTokens, cachedWriteTokens,
+ *   outputTokens, reasoningOutputTokens}`. `totalTokens` is NOT summed - it
+ * already includes the others, and adding it would triple-count.
+ *
+ * Returns null when there is nothing to price, so a caller can leave the
+ * figure off the receipt entirely rather than print a confident $0.00. */
+export function estimateCostUsd(usage) {
+  const rows = Array.isArray(usage?._meta?.quota?.model_usage)
+    ? usage._meta.quota.model_usage
+    : Array.isArray(usage?.model_usage)
+      ? usage.model_usage
+      : null;
+  const per = (counts, model) => {
+    const p = priceFor(model);
+    const n = (v) => (Number.isFinite(Number(v)) ? Number(v) : 0);
+    return (
+      (n(counts?.inputTokens) * p.input +
+        n(counts?.outputTokens) * p.output +
+        // Reasoning tokens are output tokens that were billed as output.
+        n(counts?.reasoningOutputTokens) * p.output +
+        n(counts?.cachedWriteTokens) * p.cacheWrite +
+        n(counts?.cachedInputTokens) * p.cacheRead) /
+      1_000_000
+    );
+  };
+  if (rows && rows.length > 0) {
+    let total = 0;
+    for (const row of rows) total += per(row?.token_count, row?.model);
+    return total;
+  }
+  // The flat shape, whose field names differ from the per-model one
+  // (cachedReadTokens vs cachedInputTokens). Both are in the capture.
+  const flat = usage?.usage ?? usage;
+  if (flat && typeof flat === "object") {
+    const counts = {
+      inputTokens: flat.inputTokens,
+      outputTokens: flat.outputTokens,
+      cachedInputTokens: flat.cachedReadTokens ?? flat.cachedInputTokens,
+      cachedWriteTokens: flat.cachedWriteTokens,
+    };
+    const any = Object.values(counts).some((v) => Number.isFinite(Number(v)) && Number(v) > 0);
+    if (any) return per(counts, null);
+  }
+  return null;
+}
+
+// --------------------------------------------------------- the permission door
+//
+// ACP puts the allowlist ON THE CLIENT, which is the shape the bridge wanted
+// all along. `session/request_permission` arrives as a REQUEST carrying
+// `toolCall.name` - the raw Claude tool name, `mcp__spikeboard__spike_ping`
+// in the capture - and `options` labelled by `kind`: allow_once, allow_always,
+// reject_once, reject_always. The spike answered from a regex list and the
+// turn continued, so this is verified rather than designed.
+//
+// CLAUDE_TOOLS is the list, unchanged and un-forked: the same strings the
+// `claude` engine hands to `--allowedTools`, matched here instead of there.
+// One list, two enforcement points, no second place to keep in step.
+//
+// ALLOW_ONCE, NEVER ALLOW_ALWAYS. `allow_always` is cheaper - the adapter
+// stops asking - and it is wrong here, because "always" outlives the decision
+// that justified it: `Bash(git:*)` allows `git push` on the strength of a
+// `git status` the model asked about first. Asking every time costs a
+// round trip inside the adapter's own process and keeps every answer a
+// decision about the call in front of it.
+
+/** One entry of CLAUDE_TOOLS, split into the tool and its argument pattern.
+ * `Read` -> {tool:"Read", arg:null}; `Bash(git:*)` -> {tool:"Bash", arg:"git:*"}. */
+function parseRule(rule) {
+  const match = /^([A-Za-z_][\w-]*)\((.*)\)$/.exec(String(rule ?? "").trim());
+  return match ? { tool: match[1], arg: match[2] } : { tool: String(rule ?? "").trim(), arg: null };
+}
+
+/** Does the allowlist cover this tool call?
+ *
+ * Three matches, and no fourth:
+ *   exact          `Read` covers the tool named Read.
+ *   mcp namespace  `mcp__glytch` covers `mcp__glytch__report`, because Claude
+ *                  Code namespaces an MCP server's tools that way and the
+ *                  allowlist names the SERVER (renamed from `board` to
+ *                  `glytch` 2026-09-12, brief 31, Move 3b - see agents.mjs's
+ *                  CLAUDE_TOOLS).
+ *   command prefix `Bash(git:*)` covers a Bash call whose command starts with
+ *                  `git`. The `:*` suffix is Claude Code's own spelling.
+ *
+ * Anything else is rejected. A rule this function cannot understand matches
+ * NOTHING - failing closed is the only safe direction for a door that spends
+ * money and writes files. */
+export function toolCallAllowed(toolCall, allowTools = []) {
+  const name = typeof toolCall?.name === "string" && toolCall.name.trim() !== ""
+    ? toolCall.name.trim()
+    // The capture shows `title` carrying the same string when `name` is
+    // absent on an update; the permission request itself always has `name`.
+    : typeof toolCall?.title === "string"
+      ? toolCall.title.trim()
+      : "";
+  if (name === "") return false;
+  const command =
+    typeof toolCall?.rawInput?.command === "string" ? toolCall.rawInput.command.trim() : "";
+  for (const raw of allowTools) {
+    const { tool, arg } = parseRule(raw);
+    if (tool === "") continue;
+    if (arg === null) {
+      if (name === tool) return true;
+      // The MCP namespace, and only as a namespace: `mcp__glytch` must not
+      // match `mcp__glytched__x`, so the separator is part of the test.
+      if (name.startsWith(`${tool}__`)) return true;
+      continue;
+    }
+    if (name !== tool) continue;
+    const prefix = arg.endsWith(":*") ? arg.slice(0, -2) : arg;
+    if (prefix === "" || command === "") continue;
+    if (command === prefix || command.startsWith(`${prefix} `)) return true;
+  }
+  return false;
+}
+
+/** The option id to answer a permission request with.
+ *
+ * Picked by the option's own `kind` rather than by position: the adapter
+ * labels them, the labels are stable, and an index is a bet on an order
+ * nobody promised. Returns null when the agent offered nothing usable, which
+ * the caller turns into `outcome: "cancelled"` - the protocol's own answer
+ * for "the client cannot decide this". */
+export function permissionOptionId(options, allow) {
+  const list = Array.isArray(options) ? options : [];
+  const of = (kind) => list.find((o) => o?.kind === kind)?.optionId ?? null;
+  return allow
+    ? of("allow_once")
+    : of("reject_once") ?? of("reject_always");
+}
+
+// ------------------------------------------------------------ the executable
+//
+// THE ADAPTER SHIPS ITS OWN CLAUDE CODE, and it is not the one this machine
+// runs. claude-agent-acp 0.73.0 wraps @anthropic-ai/claude-agent-sdk 0.3.257,
+// whose darwin-arm64 binary reports 2.1.257; the `claude` on this machine's
+// PATH is 2.1.34. Two Claude Codes on one box, one of them invisible, is how
+// a session behaves differently from every other session on the board for a
+// reason nobody can see - and every bound in this bridge (the tool fence, the
+// disallowed list, the flags in agents.mjs) was checked against 2.1.34.
+//
+// CLAUDE_CODE_EXECUTABLE pins the run to a chosen binary. The spike ran that
+// way from the first prompt and this does the same. The order is: what the
+// caller already set, then the bridge's own PM_CLAUDE_BIN (so the fake binary
+// in the test suite is honoured here exactly as it is for the claude engine),
+// then whatever `claude` is on PATH. If none of those resolve, the variable
+// is left unset and the adapter uses its bundled copy - which is a working
+// session rather than a refusal, and the receipt says which happened.
+export function resolveClaudeExecutable(env = process.env) {
+  const explicit = env.CLAUDE_CODE_EXECUTABLE?.trim();
+  if (explicit) return { path: explicit, source: "CLAUDE_CODE_EXECUTABLE" };
+  const pinned = env.PM_CLAUDE_BIN?.trim();
+  if (pinned && isAbsolute(pinned) && canExecute(pinned)) {
+    return { path: pinned, source: "PM_CLAUDE_BIN" };
+  }
+  for (const dir of (env.PATH ?? "").split(delimiter)) {
+    if (dir.trim() === "") continue;
+    const candidate = join(dir, "claude");
+    if (canExecute(candidate)) return { path: candidate, source: "PATH" };
+  }
+  return { path: null, source: "none (the adapter's bundled Claude Code will run)" };
+}
+
+function canExecute(path) {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Where the adapter's stdio entrypoint is, or null.
+ *
+ * Resolved from bridge/, which is where `npm install` puts it, and
+ * overridable by env - which is both the escape hatch for an odd install and
+ * the seam the tests drive, because a fake adapter is the only way to test
+ * the handshake, a rejected permission and a cancel without spending.
+ *
+ * THE SPECIFIER NAMES A FILE, NOT A PACKAGE, and that is not fussiness.
+ * claude-agent-acp's `main` is `dist/lib.js` - the LIBRARY, for embedding the
+ * adapter in another program - while the thing that speaks JSON-RPC on stdio
+ * is `dist/index.js`, its `bin`. Resolving the package name gets the wrong
+ * file, or (because the package exports only an `import` condition for ".")
+ * throws outright, which is what it did the first time this ran. The spike
+ * used the same path for the same reason. */
+export function adapterEntry(specifier, env = process.env) {
+  const override = env.PM_ACP_ADAPTER?.trim();
+  if (override) return override;
+  try {
+    return createRequire(import.meta.url).resolve(specifier);
+  } catch {
+    return null;
+  }
+}
+
+// ----------------------------------------------------------- the translation
+
+/** The stream-json line an ACP `session/update` becomes, or null for the
+ * kinds the runner has no use for. Pure, so the mapping is testable without
+ * a process. */
+export function lineForUpdate(update, sessionId) {
+  const kind = update?.sessionUpdate;
+  const base = sessionId ? { session_id: sessionId } : {};
+  if (kind === "agent_message_chunk" || kind === "agent_thought_chunk") {
+    const text = update?.content?.type === "text" ? update.content.text : null;
+    if (typeof text !== "string" || text === "") return null;
+    return {
+      ...base,
+      type: "assistant",
+      message: { role: "assistant", content: [{ type: "text", text }] },
+    };
+  }
+  if (kind === "tool_call") {
+    if (typeof update?.toolCallId !== "string") return null;
+    // NO `usage` ON THIS LINE, and it is not an oversight. The runner's
+    // scanner is an if/else-if chain in which a usage field wins over a
+    // content field - an assistant event carrying both records the usage and
+    // never sees the tool_use, so the stall watchdog would never arm. The
+    // two facts therefore travel as two lines.
+    return {
+      ...base,
+      type: "assistant",
+      message: {
+        role: "assistant",
+        content: [
+          { type: "tool_use", id: update.toolCallId, name: update.title ?? "tool", input: update.rawInput ?? {} },
+        ],
+      },
+    };
+  }
+  if (kind === "tool_call_update") {
+    // Only a TERMINAL update closes the tool. The capture shows four updates
+    // for one call - rawInput filling in, then content, then status - and
+    // closing on the first would disarm the stall watchdog while the tool was
+    // still running, which is the exact condition it exists to distinguish.
+    const status = update?.status;
+    if (status !== "completed" && status !== "failed") return null;
+    if (typeof update?.toolCallId !== "string") return null;
+    return {
+      ...base,
+      type: "user",
+      message: {
+        role: "user",
+        content: [
+          {
+            type: "tool_result",
+            tool_use_id: update.toolCallId,
+            is_error: status === "failed",
+          },
+        ],
+      },
+    };
+  }
+  if (kind === "usage_update") {
+    const used = Number(update?.used);
+    if (!Number.isFinite(used)) return null;
+    // contextFill = input + cache_read + cache_creation (child.mjs), and ACP
+    // gives one number for the whole window. It goes in as input_tokens so
+    // the sum is that number and nothing is invented for the other two.
+    return {
+      ...base,
+      type: "assistant",
+      message: {
+        role: "assistant",
+        usage: { input_tokens: used, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 },
+      },
+    };
+  }
+  return null;
+}
+
+/** The result envelope one `session/prompt` response becomes.
+ *
+ * `is_error` follows the stop reason: `end_turn` and `max_turn_request`
+ * finished; `refusal` and `cancelled` did not. An unknown stop reason is NOT
+ * an error - a future adapter inventing one must not turn finished work into
+ * a failed receipt, which is the mistake that cost 26 sessions their verdict
+ * (child.mjs, "a finished stream is finished"). */
+export function resultEnvelope({ response, sessionId, turns, durationMs, priorCostUsd = 0 }) {
+  const stop = response?.stopReason;
+  const isError = stop === "refusal" || stop === "cancelled";
+  // CUMULATIVE, because the runner keeps only the LAST envelope (child.mjs,
+  // "keep the LAST one") and writes its total_cost_usd into the session
+  // sidecar, which is what the receipt shows. Claude Code's own
+  // total_cost_usd is a session total; ACP
+  // reports per-TURN usage and nothing else, so a per-turn figure here would
+  // charge a five-turn session for its fifth turn only.
+  //
+  // Caught on the first real two-turn run: turn one estimated $0.0313 (it
+  // paid the cache WRITE), turn two $0.0026, and the receipt would have said
+  // $0.0026 for the pair. num_turns and duration_ms were already cumulative,
+  // which is exactly why the mismatch was invisible until the money was
+  // looked at.
+  const turnCost = estimateCostUsd(response);
+  const cost = turnCost === null && priorCostUsd === 0 ? null : priorCostUsd + (turnCost ?? 0);
+  return {
+    type: "result",
+    subtype: isError ? `error_${stop}` : "success",
+    is_error: isError,
+    stop_reason: stop ?? "unknown",
+    session_id: sessionId,
+    num_turns: turns,
+    duration_ms: durationMs,
+    ...(cost !== null ? { total_cost_usd: cost, cost_source: "estimate" } : {}),
+    usage: response?.usage ?? null,
+  };
+}
+
+// --------------------------------------------------------------- the runner
+
+/** Run one request on an ACP adapter, and give back what `runChild` and
+ * `runStreamingChild` give back.
+ *
+ * The option list is theirs, deliberately: `runRequest` builds ONE options
+ * object and hands it to whichever run function the engine table names, so a
+ * field this engine does not use (images on the one-shot path) is ignored the
+ * way the other two ignore fields they do not use. `acp` is the only addition
+ * and the other two never read it.
+ *
+ * PERSISTENT VERSUS ONE-SHOT is decided the same way runStreamingChild
+ * decides whether to watch for replies: by whether a replyDir was passed. A
+ * persistent request holds the session open after its first turn and delivers
+ * each reply file as a SECOND `session/prompt` into the same sessionId - the
+ * spike proved that works and costs no stdin trick. A one-shot request ends
+ * when its single turn does. */
+export function runAcpChild(opts) {
+  const {
+    bin,
+    args = [],
+    cwd,
+    env,
+    maxMs,
+    maxLogBytes = DEFAULTS.maxLogBytes,
+    killGraceMs = DEFAULTS.killGraceMs,
+    stallMs = DEFAULTS.stallMs,
+    onChunk,
+    prompt,
+    images,
+    replyDir,
+    replyPrefix,
+    replyPollMs = 2000,
+    answerPoll,
+    answerPollMs = 4000,
+    stopCheck,
+    stopPollMs = 2000,
+    acp = {},
+  } = opts;
+
+  return new Promise((resolve) => {
+    try { imageAttachments(images); } catch (error) { resolve({ ok: false, log: "", spawnError: error.message }); return; }
+    if (typeof args[0] !== "string" || args[0].trim() === "") {
+      resolve({
+        ok: false,
+        log: "",
+        spawnError:
+          `The ACP adapter for this engine is not installed. Run \`npm install\` in bridge/ ` +
+          `(it pulls ${acp.adapter ?? "the adapter"} and @agentclientprotocol/sdk), or set ` +
+          `PM_ACP_ADAPTER to the adapter's entrypoint.`,
+      });
+      return;
+    }
+
+    // The pinned binary. Set on the CHILD's environment rather than the
+    // runner's, so one ACP session cannot change what the next one runs.
+    const pinned = resolveClaudeExecutable(env ?? {});
+    const childEnvironment = { ...(env ?? {}) };
+    if (pinned.path) childEnvironment.CLAUDE_CODE_EXECUTABLE = pinned.path;
+
+    let child;
+    try {
+      child = spawn(bin, args, { cwd, env: childEnvironment, stdio: ["pipe", "pipe", "pipe"] });
+    } catch (error) {
+      resolve({ ok: false, spawnError: error instanceof Error ? error.message : String(error), log: "" });
+      return;
+    }
+    // An EPIPE on the adapter's stdin must not throw out of the daemon. Same
+    // reasoning as runStreamingChild's: the guarded writes below report a
+    // dead pipe by their own return value.
+    child.stdin?.on("error", () => {});
+
+    // THE TRANSLATED STREAM. attachChild reads this as if it were the child's
+    // own stdout; the adapter's real stdout is JSON-RPC and goes to the SDK.
+    // stderr is the adapter's own, unchanged - a crash reason is one line and
+    // it belongs in the log the frame draws.
+    const translated = new PassThrough();
+    let sessionId = null;
+    const emit = (obj) => {
+      if (obj === null) return;
+      try {
+        translated.write(`${JSON.stringify(obj)}\n`);
+      } catch { /* the stream is gone; the outcome is already settling */ }
+    };
+
+    const facade = {
+      stdout: translated,
+      stderr: child.stderr,
+      kill: (signal) => child.kill(signal),
+      on: (event, fn) => {
+        // Only the two attachChild listens for. Forwarding the rest would
+        // hand it events about a pipe it does not own.
+        if (event === "error" || event === "close") child.on(event, fn);
+        return facade;
+      },
+    };
+
+    const handle = attachChild(facade, {
+      resolve,
+      maxMs,
+      maxLogBytes,
+      killGraceMs,
+      onChunk,
+      stopPollMs,
+      // THE STOP PATH, and the one place this engine has something better
+      // than SIGTERM. `session/cancel` lets the adapter stop its model
+      // request and flush its pending updates; the kill that attachChild does
+      // next is the backstop for an adapter that ignores it. Wrapping the
+      // caller's stopCheck rather than adding a second watcher keeps the stop
+      // file consumed exactly once.
+      stopCheck: stopCheck
+        ? async () => {
+            if (!(await stopCheck())) return false;
+            // THE STOP IS DECIDED HERE, before the cancel is sent and before
+            // the wait inside it. `cancelTurn` now waits for the turn to come
+            // back cancelled, and a turn coming back can settle the outcome on
+            // its own - a one-shot ends when its queue drains and stdin closes
+            // - so a flag set only after `stopCheck` returned would arrive
+            // after `settle` had already read it, and a stopped session would
+            // report itself as one that simply finished. attachChild sets the
+            // same field for the same reason a moment later; setting it twice
+            // is free.
+            handle.state.stoppedByUser = true;
+            await cancelTurn();
+            return true;
+          }
+        : undefined,
+      // Identical to runStreamingChild's, and for the identical reason: a
+      // session whose last turn ended is DONE, and the wall clock closing its
+      // reply window is bookkeeping. See child.mjs.
+      onWallClock: (state) => { if (!state.sawResult) state.timedOut = true; },
+      okOf: (state, code) =>
+        state.sawResult
+          ? !state.resultWasError
+          : !state.timedOut && !state.stoppedByUser && !state.stalled && code === 0,
+      extraFields: (state) => ({
+        stalled: state.stalled,
+        ...(state.stalled ? { stallMs } : {}),
+        finished: state.sawResult,
+        finishedWithError: state.sawResult && state.resultWasError,
+        acpSessionId: sessionId,
+        // Which Claude Code actually ran, on the receipt rather than in
+        // anyone's head. The whole point of pinning is that it is checkable.
+        claudeExecutable: pinned.path,
+        claudeExecutableSource: pinned.source,
+      }),
+    });
+
+    // ------------------------------------------------------------- protocol
+
+    let connection = null;
+    let turns = 0;
+    let cancelled = false;
+    // Every turn's estimate, added up, because the receipt reads the last
+    // envelope only. See resultEnvelope.
+    let costSoFar = 0;
+    const startedAt = Date.now();
+
+    const cancelTurn = async () => {
+      cancelled = true;
+      if (!sessionId || !connection) return;
+      try {
+        await connection.agent.notify("session/cancel", { sessionId });
+      } catch { /* the adapter may already be gone */ return; }
+      // THE CANCEL NEEDS A MOMENT OF ITS OWN (2026-09-07, brief 21, the first
+      // windows-latest run). Sending the notification and returning made the
+      // comment above this block true only by accident of how POSIX kills
+      // work: `child.kill("SIGTERM")` is asynchronous delivery, so the
+      // adapter's event loop drained the cancel line it already had queued
+      // before its signal handler ran. Windows has no such moment - taskkill
+      // ends the process outright - and the adapter was killed with the cancel
+      // still unread, having stopped nothing and flushed nothing.
+      //
+      // So the stop waits for the in-flight turn to come BACK cancelled,
+      // bounded: an adapter that answers is given exactly as long as it takes,
+      // and one that ignores the cancel costs CANCEL_GRACE_MS before the kill
+      // that was always the backstop for it.
+      const until = Date.now() + CANCEL_GRACE_MS;
+      while (promptBusy && !handle.settled() && Date.now() < until) {
+        await new Promise((r) => setTimeout(r, 25));
+      }
+    };
+
+    // A serial queue for prompts. The adapter advertises promptQueueing, but
+    // the spike did not exercise it, so this sends the next prompt only after
+    // the previous turn has returned its stop reason. A reply that arrives
+    // mid-turn waits rather than racing an untested path.
+    const queue = [];
+    let promptBusy = false;
+    let ended = false;
+
+    let supportsImages = false;
+    const promptBlocks = (text, imageUrls) => {
+      const attachments = imageAttachments(imageUrls);
+      if (attachments.length && !supportsImages) throw new Error("This ACP adapter does not support reference images. Choose an image-capable agent and try again.");
+      return [{ type: "text", text }, ...attachments.map((image) => ({ type: "image", mimeType: image.mimeType, data: image.data }))];
+    };
+
+    const runTurn = async (text, imageUrls) => {
+      if (!connection || !sessionId || cancelled) return;
+      turns += 1;
+      // A new turn means whatever envelope stood no longer describes the
+      // session: the stall clock restarts and the wall clock stops reading
+      // as "the reply window closed on finished work".
+      handle.markSent();
+      const at = Date.now();
+      let response;
+      try {
+        response = await connection.agent.request("session/prompt", {
+          sessionId,
+          prompt: promptBlocks(text, imageUrls),
+        });
+      } catch (error) {
+        // A failed prompt is a failed TURN, not a crashed runner. It becomes
+        // an error envelope so the receipt says so in the same words a
+        // Claude Code error result would.
+        emit({
+          type: "result",
+          subtype: "error_during_execution",
+          is_error: true,
+          session_id: sessionId,
+          num_turns: turns,
+          duration_ms: Date.now() - at,
+          error: String(error?.message ?? error),
+        });
+        return;
+      }
+      const envelope = resultEnvelope({
+        response,
+        sessionId,
+        turns,
+        durationMs: Date.now() - startedAt,
+        priorCostUsd: costSoFar,
+      });
+      if (typeof envelope.total_cost_usd === "number") costSoFar = envelope.total_cost_usd;
+      emit(envelope);
+    };
+
+    const pump = async () => {
+      if (promptBusy) return;
+      promptBusy = true;
+      while (queue.length > 0 && !handle.settled() && !cancelled) {
+        const next = queue.shift();
+        await runTurn(next.text, next.images);
+      }
+      promptBusy = false;
+      // A one-shot request is over when its only turn is: closing stdin ends
+      // the adapter (verified, `stdinCloseEndsProcess` in the spike summary),
+      // which is what settles the outcome.
+      if (!replyDir && queue.length === 0 && !ended) {
+        ended = true;
+        try { child.stdin?.end(); } catch { /* already gone */ }
+      }
+    };
+
+    const push = (text, imageUrls) => {
+      if (handle.settled() || cancelled || typeof text !== "string" || text.trim() === "") return;
+      queue.push({ text, images: imageUrls });
+      void pump();
+    };
+
+    // --------------------------------------------------------- reply files
+    //
+    // THE SAME DOOR the streaming child has, behind a different knock. A
+    // reply file is delivered as a second `session/prompt` into the same
+    // sessionId rather than as a line on stdin, and everything else about it
+    // is unchanged: sorted by name, consumed BEFORE it is sent (an unlink
+    // that fails after a successful write is how a human's message arrives
+    // twice), a `from` label wrapped around a peer's words.
+    const watchReplies = () => {
+      if (!replyDir || !replyPrefix) return;
+      const watcher = handle.every(async () => {
+        if (handle.settled()) { clearInterval(watcher); 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;
+              replyImages = data.images;
+              fromField =
+                typeof data.from === "string" && data.from.trim() !== "" ? data.from.trim() : null;
+            } catch { continue; }
+            try { promptBlocks(text ?? "", replyImages); } catch (error) {
+              emit({ type: "result", subtype: "error_during_execution", is_error: true, session_id: sessionId, errors: [error.message] });
+              cancelled = true;
+              handle.kill();
+              return;
+            }
+            try { await unlink(full); } catch { continue; }
+            if (text) push(fromField ? `[message from ${fromField}] ${text}` : text, replyImages);
+          }
+        } catch { /* replyDir may not exist yet */ }
+      }, replyPollMs);
+    };
+
+    // Answers the human gave on the canvas after ask_user had already timed
+    // out. Same contract as runStreamingChild: onDelivered runs AFTER the
+    // message is accepted, never before, or a ruling is marked delivered to a
+    // session that never heard it.
+    let answerBusy = false;
+    const watchAnswers = () => {
+      if (!answerPoll) return;
+      const collect = async () => {
+        if (handle.settled()) return;
+        if (answerBusy) return;
+        answerBusy = true;
+        try {
+          for (const answer of await answerPoll()) {
+            if (handle.settled()) break;
+            push(answer.text);
+            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);
+    };
+
+    // THE STALL WATCHDOG, byte for byte the rule runStreamingChild uses -
+    // armed only when the MODEL should be producing output (a turn open, no
+    // tool awaiting its result) - because the events it reads are now the
+    // same events. This is the whole reason the translation above bothers to
+    // emit tool_use/tool_result pairs at all.
+    const armStallWatchdog = () => {
+      const watcher = handle.every(() => {
+        const state = handle.state;
+        if (state.settled) return;
+        const armed = !state.sawResult && state.openToolUses.size === 0;
+        if (armed && Date.now() - state.lastStdoutAt >= stallMs) {
+          state.stalled = true;
+          handle.kill();
+          clearInterval(watcher);
+        }
+      }, Math.min(10_000, stallMs / 4));
+    };
+
+    // ---------------------------------------------------------------- boot
+
+    const boot = async () => {
+      const sdk = await import("@agentclientprotocol/sdk");
+      const app = sdk
+        .client({ name: "pm-bridge" })
+        .onNotification("session/update", ({ params }) => {
+          if (!sessionId) sessionId = params?.sessionId ?? null;
+          emit(lineForUpdate(params?.update, sessionId));
+        })
+        .onRequest("session/request_permission", ({ params }) => {
+          const allow = toolCallAllowed(params?.toolCall, acp.allowTools ?? []);
+          const optionId = permissionOptionId(params?.options, allow);
+          // The decision goes in the LOG, as a tool_result-shaped note beside
+          // the call it answered, because a session that quietly did less
+          // than it was asked to is the failure this bridge keeps meeting.
+          emit({
+            session_id: sessionId,
+            type: "system",
+            subtype: "permission",
+            tool: params?.toolCall?.name ?? params?.toolCall?.title ?? null,
+            decision: allow ? "allow_once" : "reject_once",
+            option_id: optionId,
+          });
+          return optionId
+            ? { outcome: { outcome: "selected", optionId } }
+            : { outcome: { outcome: "cancelled" } };
+        })
+        // The two filesystem capabilities the client declares below. Served
+        // honestly rather than refused: an adapter told it may read files and
+        // then answered -32601 is an adapter that has been lied to.
+        .onRequest("fs/read_text_file", ({ params }) => ({
+          content: readFileSync(params.path, "utf8"),
+        }))
+        .onRequest("fs/write_text_file", ({ params }) => {
+          writeFileSync(params.path, params.content, "utf8");
+          // A write through this request leaves no tool call in the log, so
+          // it gets its own line: the in-place warning reads it (#735 review).
+          emit({ session_id: sessionId, type: "system", subtype: "file_write", path: params.path });
+          return null;
+        });
+
+      const stream = sdk.ndJsonStream(
+        Writable.toWeb(child.stdin),
+        Readable.toWeb(child.stdout),
+      );
+      connection = app.connect(stream);
+
+      const init = await connection.agent.request("initialize", {
+        protocolVersion: Number(acp.protocolVersion ?? 1),
+        clientInfo: { name: "pm-bridge", version: "0.2.0" },
+        clientCapabilities: { fs: { readTextFile: true, writeTextFile: true }, terminal: false },
+      });
+
+      supportsImages = init?.agentCapabilities?.promptCapabilities?.image === true;
+      if (imageAttachments(images).length && !supportsImages) throw new Error("This ACP adapter does not support reference images. No model turn was started.");
+
+      // AUTHENTICATION IS NOT ATTEMPTED, EVER. An adapter that offers auth
+      // methods is one whose credentials are missing, and logging a session
+      // in from a daemon nobody is watching is not this runner's decision to
+      // make. It says so and stops, which is one refusal receipt instead of a
+      // hung session. (Codex is exactly this case - the spike got
+      // `-32000 Authentication required` from session/new and stopped there.)
+      const authMethods = Array.isArray(init?.authMethods) ? init.authMethods : [];
+
+      const params = {
+        cwd,
+        mcpServers: Array.isArray(acp.mcpServers) ? acp.mcpServers : [],
+      };
+      let created;
+      // RESUME IS UNTESTED and is treated as such. `loadSession: true` was
+      // advertised in the spike's initialize reply, but no session was ever
+      // loaded, so this TRIES and falls back to a fresh session rather than
+      // failing the run over a path nobody has watched work.
+      const resume = typeof acp.resumeSessionId === "string" ? acp.resumeSessionId.trim() : "";
+      if (resume !== "" && init?.agentCapabilities?.loadSession === true) {
+        try {
+          created = await connection.agent.request("session/load", { ...params, sessionId: resume });
+          sessionId = resume;
+        } catch (error) {
+          emit({
+            type: "system",
+            subtype: "resume_failed",
+            detail: `session/load failed (${String(error?.message ?? error)}); starting a fresh session`,
+          });
+          created = undefined;
+        }
+      }
+      if (!created && !sessionId) {
+        try {
+          created = await connection.agent.request("session/new", params);
+        } catch (error) {
+          if (authMethods.length > 0) {
+            throw new Error(
+              `${acp.label ?? "the adapter"} needs authentication (${authMethods
+                .map((m) => m?.id)
+                .filter(Boolean)
+                .join(", ")}) and this runner never logs anything in. ` +
+                `Sign in with the engine's own CLI, then file the request again. ` +
+                `(${String(error?.message ?? error)})`,
+            );
+          }
+          throw error;
+        }
+        sessionId = created?.sessionId ?? null;
+      }
+
+      // The one line the sidecar reads. extractSessionIdFromLog takes the
+      // FIRST session_id in the log, so this has to come before any update
+      // line - which it does, because nothing has been prompted yet.
+      emit({
+        type: "system",
+        subtype: "init",
+        session_id: sessionId,
+        agent: init?.agentInfo?.name ?? null,
+        agent_version: init?.agentInfo?.version ?? null,
+        claude_executable: pinned.path,
+        claude_executable_source: pinned.source,
+        cost_source: "estimate",
+      });
+
+      // MODEL AND MODE, through the method the spike found by getting the
+      // other one wrong: `session/set_config_option`, NOT
+      // `session/set_session_config_option`, which this adapter answers
+      // -32601. Both attempts are in capture/claude.probe.jsonl.
+      //
+      // A config option this adapter does not offer is SKIPPED rather than
+      // sent and failed: the options list comes back on session/new, so
+      // asking for a model the engine has no select for is a question that
+      // can be answered without a round trip. Effort is exactly that case -
+      // claude-agent-acp 0.73.0 offers no reasoning option at all - and
+      // commandFor has already recorded it as ignored.
+      const offered = Array.isArray(created?.configOptions) ? created.configOptions : [];
+      const set = async (configId, value) => {
+        const option = offered.find((o) => o?.id === configId);
+        if (!option || value === undefined || value === null || value === "") return;
+        const allowed = Array.isArray(option.options) ? option.options : [];
+        if (allowed.length > 0 && !allowed.some((o) => o?.value === value)) {
+          emit({ type: "system", subtype: "config_skipped", option: configId, value });
+          return;
+        }
+        try {
+          await connection.agent.request("session/set_config_option", { sessionId, configId, value });
+          emit({ type: "system", subtype: "config", option: configId, value });
+        } catch (error) {
+          emit({
+            type: "system",
+            subtype: "config_failed",
+            option: configId,
+            value,
+            detail: String(error?.message ?? error),
+          });
+        }
+      };
+      // acceptEdits, the same permission mode the `claude` engine passes.
+      // Never `plan`: a headless session in plan mode is parked for good
+      // (agents.mjs, CLAUDE_DISALLOWED_TOOLS), and here plan mode is simply a
+      // mode nobody selects - which is the whole of what the disallowed list
+      // was buying on this path.
+      await set("mode", acp.mode ?? "acceptEdits");
+      await set("model", typeof acp.model === "string" ? acp.model.trim() : "");
+
+      watchReplies();
+      watchAnswers();
+      armStallWatchdog();
+      push(prompt, images);
+    };
+
+    boot().catch((error) => {
+      // A protocol failure before the first turn is a session that never
+      // started. It is emitted as an error envelope AND written to the log,
+      // then the adapter is closed - so the receipt carries the reason
+      // instead of an empty log and a bare exit code.
+      const detail = String(error?.message ?? error);
+      translated.write(`\n[acp] ${detail}\n`);
+      emit({
+        type: "result",
+        subtype: "error_during_execution",
+        is_error: true,
+        session_id: sessionId,
+        num_turns: turns,
+        error: detail,
+      });
+      try { child.stdin?.end(); } catch { /* already gone */ }
+      // An adapter that does not take the hint still has the grace period.
+      setTimeout(() => { if (!handle.settled()) handle.kill(); }, 2000).unref?.();
+    });
+  });
+}