viewable-one 0.0.0-stage → 0.12.1

package/lib/codex.mjs

@@ -0,0 +1,747 @@
+import { writeRisk, riskReason } from "./writePolicy.mjs";
+// Codex's native app-server protocol, translated to the board's session log.
+// No SDK or API key is needed: this uses the user's installed, signed-in CLI.
+import { PassThrough } from "node:stream";
+import { readFile, readdir, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { attachChild, DEFAULTS } from "./child.mjs";
+import { imageAttachments } from "./imageAttachments.mjs";
+import { CODEX_TOOL_TIMEOUT_SEC } from "./mcpjson.mjs";
+import { codexRpc, startCodex } from "./codex-rpc.mjs";
+import { planWindowInfoMessage, readPlanWindow } from "./codexPlanWindow.mjs";
+import { prepareCodexApps, verifyCodexApps } from "./codexApps.mjs";
+import { secretLike, toolInputsText } from "./codexToolInputs.mjs";
+
+// MOVED ONTO THE HOSTED ENDPOINT, 2026-09-11 (brief 30, W2a): the local
+// stdio server this used to spawn as `mcp_servers.board`'s
+// `command`/`args`/`env` is retired - every engine reaches the board
+// over HTTP now (supabase/functions/board-mcp). Codex's own config schema has
+// a streamable-HTTP shape for this (`url`, `http_headers`, and either
+// `bearer_token` or `bearer_token_env_var`), checked directly against the
+// installed codex binary rather than assumed: `codex mcp add --help` offers
+// `--bearer-token-env-var` and says why in its own words - `strings` on the
+// binary turns up the literal message "uses unsupported `bearer_token`; set
+// `bearer_token_env_var`", which is codex refusing a LITERAL secret on this
+// exact field and asking for an environment variable's NAME instead.
+//
+// So the bearer token itself never appears in this string - only the NAME of
+// the env var the child was given it under (`tokenEnvVar`, `PM_BOARD_TOKEN`
+// by default, set on the child's own environment by lib/runner.mjs's
+// childEnv). `-c mcp_servers.glytch={...}` is still one argv entry, so
+// `http_headers` (the session key, not a secret) is fine to embed directly -
+// it is exactly as visible in `ps` as the tool allowlist already is for
+// every engine.
+//
+// RENAMED 2026-09-12 (brief 31, Move 3, ruling 3): the key is `glytch`,
+// matching the same key `.codex/config.toml`'s persisted entry now uses
+// (lib/project-mcp.mjs) - a session spawned by the runner and a session a
+// person connects by hand (`codex mcp login glytch`) now name the same
+// server.
+export function codexBoardArgs({ boardUrl, tokenEnvVar = "PM_BOARD_TOKEN", sessionKey, boardId } = {}) {
+  if (!boardUrl) return ["app-server"];
+  const fields = [
+    `url = ${JSON.stringify(boardUrl)}`,
+    `bearer_token_env_var = ${JSON.stringify(tokenEnvVar)}`,
+    // THE BOARD TOOLS MUST NOT NEED AN APPROVAL NOBODY CAN GIVE (2026-09-26,
+    // live run spawn-muiptqah-414f7a). codex-cli 0.153 gates every MCP
+    // tool call behind a per-server approval mode, and the thread runs
+    // with `approvalPolicy: "never"` (runCodexChild below) - so the board
+    // read, the question and the final report were all auto-REJECTED, and
+    // Codex finished its work with nothing drawn on the canvas. The server
+    // is ours, over our own bearer token; its tools are the run's one
+    // channel to the person, never something to prompt about. The key name
+    // is the one in codex's own config schema (`McpServerConfig.
+    // default_tools_approval_mode`, values auto/prompt/writes/approve).
+    // NOT "auto": in codex-rs's requires_mcp_tool_approval_for_mode, auto
+    // still asks for every tool that is not annotated read-only (ours carry
+    // no annotations, so all of them), and the second live run
+    // (spawn-muirjn8n-710207) was rejected the same way with auto set.
+    // "approve" is the one value that never asks.
+    `default_tools_approval_mode = "approve"`,
+    // A check_answer that waits for the person holds its call up to 50s;
+    // Codex's own default cuts a tool call at 60s, too close.
+    `tool_timeout_sec = ${CODEX_TOOL_TIMEOUT_SEC}`,
+  ];
+  // THE RUN'S OWN BOARD (2026-09-21, board reporting fix), both headers in
+  // ONE inline table: a second `http_headers = {...}` field would silently
+  // overwrite the first rather than merge with it, so X-Glytch-Session and
+  // X-Glytch-Board have to be built together - same reasoning as
+  // agents.mjs's acpServersFor for the other two engines.
+  const headerFields = [];
+  if (sessionKey) headerFields.push(`"X-Glytch-Session" = ${JSON.stringify(sessionKey)}`);
+  if (boardId) headerFields.push(`"X-Glytch-Board" = ${JSON.stringify(boardId)}`);
+  if (headerFields.length > 0) fields.push(`http_headers = {${headerFields.join(", ")}}`);
+  return ["app-server", "-c", `mcp_servers.glytch={${fields.join(", ")}}`];
+}
+
+/** Codex streams token-sized deltas and then sends the authoritative complete
+ * agent message. Board log readers treat each assistant event as complete, so
+ * hold deltas and publish one event when the item completes. */
+export function agentMessageAssembler() {
+  const partial = new Map();
+  const completed = new Set();
+  return {
+    delta(id, text) {
+      if (typeof id !== "string" || completed.has(id)) return;
+      partial.set(id, `${partial.get(id) ?? ""}${typeof text === "string" ? text : ""}`);
+    },
+    complete(item) {
+      const id = item?.id;
+      if (typeof id !== "string" || completed.has(id)) return null;
+      completed.add(id);
+      const streamedText = partial.get(id) ?? "";
+      partial.delete(id);
+      return typeof item.text === "string" && item.text !== "" ? item.text : streamedText;
+    },
+  };
+}
+
+const inputFor = (text, images) => [
+  { type: "text", text },
+  ...imageAttachments(images).map(({ url }) => ({ type: "image", url })),
+];
+
+// THE APPROVALS CODEX CAN ASK (#478), turned into the same question Claude's
+// can_use_tool gives. Shell commands read as Bash and edits as Edit, so the
+// words and the remembered rule are the same for both engines.
+const ASKABLE_APPROVALS = new Set([
+  "item/commandExecution/requestApproval",
+  "item/fileChange/requestApproval",
+  "item/permissions/requestApproval",
+]);
+function approvalAsAsk(method, params = {}) {
+  if (method === "item/commandExecution/requestApproval") {
+    return { toolName: "Bash", input: { command: String(params.command ?? ""), ...(params.reason ? { description: String(params.reason) } : {}) } };
+  }
+  if (method === "item/fileChange/requestApproval") {
+    return { toolName: "Edit", input: { file_path: String(params.grantRoot ?? ""), ...(params.reason ? { description: String(params.reason) } : {}) } };
+  }
+  return { toolName: "Permissions", input: { scopes: grantScopesOf(params.permissions), ...(params.reason ? { description: String(params.reason) } : {}) } };
+}
+// The scopes a grant asks for, so "Always allow" remembers exactly those
+// (permissionAsk.mjs ruleKeyFor): "network", and "<access> <path>" per
+// filesystem entry, the legacy read and write lists included.
+const pathText = (path) => {
+  if (typeof path === "string") return path;
+  if (path?.type === "path") return String(path.path ?? "");
+  if (path?.type === "glob_pattern") return String(path.pattern ?? "");
+  if (path?.type === "special") return `<${path.value?.kind ?? "special"}>${path.value?.subpath ? ` ${path.value.subpath}` : ""}`;
+  return "";
+};
+function grantScopesOf(permissions = {}) {
+  const scopes = [];
+  if (permissions?.network?.enabled) scopes.push("network");
+  const fs = permissions?.fileSystem ?? {};
+  for (const entry of Array.isArray(fs.entries) ? fs.entries : []) scopes.push(`${entry?.access ?? "access"} ${pathText(entry?.path)}`);
+  for (const access of ["read", "write"]) for (const path of Array.isArray(fs[access]) ? fs[access] : []) scopes.push(`${access} ${pathText(path)}`);
+  return [...new Set(scopes)];
+}
+function approvalAnswer(method, params = {}, allowed) {
+  if (method === "item/permissions/requestApproval") {
+    return allowed ? { permissions: params.permissions ?? {}, scope: "turn" } : { permissions: {}, scope: "turn" };
+  }
+  return { decision: allowed ? "accept" : "decline" };
+}
+
+// Installed 0.162.1 ServerRequest.json uses item/tool/requestUserInput;
+// current app-server documentation also calls it tool/requestUserInput.
+const INPUT_REQUESTS = new Set(["item/tool/requestUserInput", "tool/requestUserInput"]);
+const ELICITATION = "mcpServer/elicitation/request";
+// Chat turns, plan drafts, automatic starts and the switch set off all land here.
+export const APPS_OFF_INFO = "The computer's apps are off for this run, so Codex has none of their tools.";
+// McpServerElicitationRequestParams in codex 0.162.1's generated schema: the
+// two OpenAI form modes carry a schema typed only as JSON, so they get the
+// same checks as "form".
+const FORM_MODES = new Set(["form", "openai/form", "openaiForm"]);
+// Schema keys that only describe the form. They are never forwarded.
+const IGNORED_SCHEMA_KEYS = new Set(["$schema", "title", "description", "additionalProperties"]);
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+// A field id, title or choice that asks for a credential. Names only, not
+// prose: approval for a tool called list_api_keys is still asked (#599).
+const sensitive = (value) => /password|passphrase|secret|token|credential|api[ _-]?key|authorization|cookie|one[ -]?time|verification[ -]?code/i.test(value);
+const shortText = (value) => typeof value === "string" && value.trim() !== "" && value.length <= 2000;
+// Forwarded prose must not carry a credential value (codexToolInputs.mjs).
+const prose = (value) => shortText(value) && !secretLike(value);
+// The schema allows an empty header or description; it forwards nothing.
+const optionalProse = (value) => value === "" || prose(value);
+// One cancel word: every hosted question gets it, so no request offers its
+// own "Cancel" beside it.
+const CANCEL = "Cancel";
+// The hosted question path accepts at most four options. Reserve one for
+// cancellation so no arbitrary field value has to be recommended.
+const choices = (values) => Array.isArray(values) && values.length > 0 && values.length <= 3 && values.every((value) => shortText(value) && !sensitive(value) && value !== CANCEL) && new Set(values).size === values.length;
+const refuse = (reason) => ({ refused: reason });
+// Names only, never values: what a refused request looked like (#599).
+const keysOf = (value) => (object(value) && Object.keys(value).length ? Object.keys(value).slice(0, 20).map((key) => key.slice(0, 40)).join(",") : "none");
+function refusalLine(method, params, reason) {
+  const mode = typeof params?.mode === "string" && /^[\w/.-]{1,40}$/.test(params.mode) ? params.mode : params?.mode == null ? "none" : "other";
+  return `Codex ${method} refused: ${reason}. mode=${mode} keys=${keysOf(params)} _meta=${keysOf(params?._meta)}` +
+    ` requestedSchema=${keysOf(params?.requestedSchema)} fields=${keysOf(params?.requestedSchema?.properties)}`;
+}
+
+// Extend the incumbent permission asker with exact choices, never its memory
+// or free-text path. No arbitrary schema, defaults, metadata or credentials
+// are forwarded to the board. Unsupported shapes return { refused: reason }.
+function protocolQuestions(method, params) {
+  if (INPUT_REQUESTS.has(method)) {
+    if (!shortText(params.itemId)) return refuse("no item id");
+    if (!Array.isArray(params.questions) || !params.questions.length || params.questions.length > 8) return refuse("no questions, or more than 8");
+    const ids = new Set();
+    const questions = [];
+    for (const [index, q] of params.questions.entries()) {
+      const which = `question ${index + 1}`;
+      if (!shortText(q.id) || ids.has(q.id)) return refuse(`${which} has no id, or a repeated one`);
+      if (!prose(q.question) || (q.header != null && !optionalProse(q.header))) return refuse(`${which} has no text, or text shaped like a credential`);
+      if (q.isSecret || q.isOther) return refuse(`${which} asks for free text`);
+      if (sensitive(`${q.id} ${q.header ?? ""}`)) return refuse(`${which} asks for a credential`);
+      ids.add(q.id);
+      // The legacy MCP approval offers persistence. This bridge only offers
+      // the literal one-call Allow, never a remembered grant. Not this and
+      // the hosted Cancel both refuse the call without supplying an answer.
+      let options = q.options?.map((option) => option?.label).filter((label) => label !== CANCEL);
+      if (q.id.startsWith("mcp_tool_call_approval")) options = options?.filter((label) => label === "Allow");
+      if (!choices(options)) return refuse(`${which} has no bounded choices`);
+      if (q.id.startsWith("mcp_tool_call_approval")) options.push("Not this");
+      if (q.options.some((option) => !optionalProse(option.description))) return refuse(`${which} has a choice without a plain description`);
+      questions.push({ id: q.id, question: q.question, options,
+        why: `Choose an answer for this request only.\n${q.options.filter((option) => options.includes(option.label)).map((option) => `${option.label}: ${option.description}`).join("\n")}${q.id.startsWith("mcp_tool_call_approval") ? "\nNot this: Decline this app request." : ""}` });
+    }
+    return { questions };
+  }
+  if (!shortText(params.serverName)) return refuse("no server name");
+  if (!prose(params.message)) return refuse("no message, or a message shaped like a credential");
+  if (params._meta != null && !object(params._meta)) return refuse("_meta is not an object");
+  if (params._meta?.codex_approval_kind != null && params._meta.codex_approval_kind !== "mcp_tool_call") return refuse("approval kind is not mcp_tool_call");
+  if (params.mode === "url") {
+    // Signed URLs and OAuth callback parameters cannot be copied into hosted
+    // questions. A plain HTTPS page can be completed by the person directly.
+    let url;
+    try { url = new URL(params.url); } catch { return refuse("url does not parse"); }
+    if (!shortText(params.elicitationId)) return refuse("no elicitation id");
+    if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash || !["/", "/connect", "/login", "/authorize", "/auth"].includes(url.pathname)) return refuse("url is not a plain https sign-in page");
+    return { questions: [{ question: `${params.serverName}: ${params.message}`, options: ["Completed", "Not this"],
+      why: `Open ${url.href} yourself. Choose Completed only after finishing there. Do not put passwords or codes in this question.` }] };
+  }
+  if (!FORM_MODES.has(params.mode)) return refuse("unsupported mode");
+  const schema = params.requestedSchema;
+  if (!object(schema) || schema.type !== "object" || !object(schema.properties)) return refuse("requestedSchema is not an object schema");
+  const extra = Object.keys(schema).find((key) => !["type", "properties", "required"].includes(key) && !IGNORED_SCHEMA_KEYS.has(key));
+  if (extra) return refuse(`unsupported schema key ${JSON.stringify(extra.slice(0, 40))}`);
+  const entries = Object.entries(schema.properties);
+  if (entries.length > 8) return refuse("more than 8 fields");
+  if (schema.required != null && (!Array.isArray(schema.required) || schema.required.some((key) => !Object.hasOwn(schema.properties, key)))) return refuse("required names an unknown field");
+  const questions = [];
+  for (const [id, field] of entries) {
+    const which = `field ${JSON.stringify(id.slice(0, 40))}`;
+    if (!shortText(id) || !object(field)) return refuse(`${which} is not a field`);
+    if (sensitive(`${id} ${field.title ?? ""}`)) return refuse(`${which} asks for a credential`);
+    if ((field.title != null && !prose(field.title)) || (field.description != null && !optionalProse(field.description))) return refuse(`${which} has a title or description that is not plain text`);
+    const key = Object.keys(field).find((k) => !["type", "title", "description", "enum", "oneOf", "enumNames", "default"].includes(k));
+    if (key) return refuse(`${which} has unsupported key ${JSON.stringify(key.slice(0, 40))}`);
+    const values = field.type === "boolean" ? [true, false] : field.type === "string" ? field.enum ?? field.oneOf?.map((option) => option.const) : null;
+    if (field.type === "boolean" && (field.enum || field.oneOf || field.enumNames)) return refuse(`${which} is a boolean with choices`);
+    if (field.type === "string" && ((field.enum && field.oneOf) ||
+        (field.enum && !field.enum.every((value) => typeof value === "string")) ||
+        (field.oneOf && !field.oneOf.every((option) => object(option) && typeof option.const === "string" && shortText(option.title) && Object.keys(option).every((k) => k === "const" || k === "title"))))) return refuse(`${which} has malformed choices`);
+    const labels = values?.map(String);
+    if (!choices(labels)) return refuse(`${which} is free text, or has more than 3 choices`);
+    questions.push({ id, values, question: `${params.serverName}: ${field.title ?? id}`, why: `${params.message}\n${field.description ?? ""}\nChoose an answer for this request only.`, options: labels });
+  }
+  // Accept is a separate, explicit per-call choice, including an empty form
+  // (the actual Codex MCP tool approval shape). No persistence metadata back.
+  // The tool's inputs come with it, short and with secrets hidden (#608).
+  const details = toolInputsText(params);
+  questions.push({ question: `${params.serverName}: ${params.message}`, options: ["Allow", "Not this"],
+    why: `On your computer, ${params.serverName}\n${riskReason(writeRisk(params.serverName.toLowerCase(), params.message, params._meta?.tool_params) ?? "open-ended")}\n${details ? `${details}\n\n` : ""}This answer applies only to this request.` });
+  return { questions };
+}
+
+export async function runCodexChild(opts) {
+  const isDraft = opts.codex?.planMode === "draft";
+  let apps;
+  try {
+    imageAttachments(opts.images);
+    apps = await prepareCodexApps(opts, { on: opts.codex?.computerApps === true, isDraft });
+  } catch (error) { return { ok: false, log: "", spawnError: error.message }; }
+  const startedAt = Date.now();
+  const maxMs = opts.maxMs ?? 60_000;
+  for (;;) {
+    const remainingMs = maxMs - (Date.now() - startedAt);
+    if (remainingMs <= 0) return { ok: false, log: "", spawnError: "Codex ran out of time checking apps." };
+    const { appsRetry: retry, ...outcome } = await runCodexAttempt({ ...opts, maxMs: remainingMs }, apps);
+    if (!retry || outcome.timedOut || outcome.stoppedByUser || outcome.stalled) return outcome;
+    apps = { args: [...apps.args, ...retry.args], sources: retry.sources, notices: [...apps.notices, ...retry.notices] };
+  }
+}
+
+function runCodexAttempt(opts, apps) {
+  return new Promise((resolve) => {
+    const startedAt = Date.now();
+    const config = opts.codex ?? {};
+    const isDraft = config.planMode === "draft";
+    let child;
+    // Custom CLI arguments still need the linked board and this session's
+    // attribution. Append our configuration last so stale project settings
+    // cannot silently point a worktree session at another board.
+    //
+    // A DRAFT GETS NO BOARD MCP SERVER, AT ALL (briefs/plan-mode-beyond-claude.md).
+    // Read-only sandboxing stops a shell write or a network call FROM A CHILD
+    // PROCESS, but an MCP tool call is answered by codex's own process over
+    // its own network stack - a sandbox flag never sees it. So the only
+    // enforceable stop is not giving the thread's process a board server to
+    // call in the first place: codexBoardArgs is skipped outright here,
+    // never merely told not to mutate anything.
+    // USE MY COMPUTER'S APPS (#481): Codex loads the person's own MCP
+    // servers from their config whatever we pass, so the switch is applied
+    // here, server by server, before the app server starts.
+    const appSources = apps.sources;
+    let appsRetry;
+    const start = async () => [...(opts.args ?? ["app-server"]), ...(isDraft ? [] : codexBoardArgs(config).slice(1)), ...apps.args];
+    start().then((args) => {
+      try { child = startCodex({ ...opts, args }); } catch (error) { resolve({ ok: false, log: "", spawnError: error.message }); return; }
+      drive();
+    }, (error) => resolve({ ok: false, log: "", spawnError: error.message }));
+    const drive = () => {
+    if (opts.onSpawn) child.once("spawn", () => opts.onSpawn());
+    const translated = new PassThrough();
+    let threadId = null;
+    let turnId = null;
+    let modelCalls = 0;
+    let ending = false;
+    let replyBusy = false;
+    let answerBusy = false;
+    let ownWordsPending = 0;
+    let finishError;
+    let closedInput = false;
+    // Approval questions go to the person only on a normal run that was given
+    // an asker. `waitingOnPerson` counts questions still open.
+    const asking = !isDraft && config.askPermissions === true && typeof opts.askPermission === "function";
+    let waitingOnPerson = 0;
+    // Each open question's abort, so Stop or the run ending ends its wait
+    // (permissionAsk.mjs stops polling check_answer when aborted).
+    const openQuestions = new Set();
+    const protocolRequests = new Map();
+    // Notifications can drain before codexRpc's queued request handler runs.
+    // Retain resolution by connection-scoped RPC ID, including that window.
+    const resolvedRequests = new Set();
+    const abortQuestions = () => { for (const controller of openQuestions) controller.abort(); };
+    let stopping = false;
+    const approvalsClosed = () => stopping || ending || handle.settled() || handle.state.timedOut || handle.state.stalled;
+    let rpc;
+    let latestUsage;
+    let planWindow = { primary: null, secondary: null, readAt: null };
+    let accountingUsage;
+    let contextWindow;
+    let finishTimer;
+    let lastAssistantText = "";
+    const opened = new Map();
+    const closed = new Set();
+    const messages = agentMessageAssembler();
+    const emit = (event) => { if (!handle.settled()) translated.write(`${JSON.stringify({ ...event, session_id: threadId })}\n`); };
+    const assistant = (content, extra = {}) => emit({ type: "assistant", message: { content, ...extra } });
+    const facade = { pid: child.pid, stdout: translated, stderr: child.stderr,
+      kill: (signal) => child.kill(signal), on(event, fn) { child.on(event, fn); return facade; } };
+    const handle = attachChild(facade, {
+      ...opts,
+      resolve: (outcome) => { clearTimeout(finishTimer); abortQuestions(); rpc?.close(); resolve({ ...outcome, ...(appsRetry ? { appsRetry } : {}) }); },
+      // Latch admission closed BEFORE SIGTERM. A still-running child may
+      // issue entirely new requests during the independent kill grace.
+      onWallClock: (state) => { stopping = true; state.timedOut = true; abortQuestions(); },
+      maxMs: opts.maxMs ?? 60_000,
+      okOf: (state) => state.sawResult && !state.resultWasError && !state.stoppedByUser && !state.timedOut && !state.stalled,
+      extraFields: (state) => ({ finished: state.sawResult, finishedWithError: state.resultWasError, stalled: state.stalled,
+        codexThreadId: threadId, accountingUsage, ...(contextWindow ? { contextWindow } : {}) }),
+      stopCheck: opts.stopCheck ? async () => {
+        if (stopping || !(await opts.stopCheck())) return false;
+        stopping = true; handle.state.stoppedByUser = true;
+        abortQuestions();
+        if (threadId && turnId) {
+          // Native interruption gets a bounded opportunity to persist the
+          // turn; the shared SIGTERM/SIGKILL path remains the backstop.
+          void rpc.request("turn/interrupt", { threadId, turnId }).catch(() => {});
+          await new Promise((done) => setTimeout(done, 150));
+        }
+        return !handle.settled();
+      } : undefined,
+    });
+    // A completion can arrive in the same stdout chunk as a steer reply.
+    // Drain the delivery acknowledgement before closing, so a late reply is
+    // restored before the runner writes its sidecar and promotes late files.
+    const closeTurn = () => {
+      if (!ending || replyBusy || answerBusy || ownWordsPending !== 0 || closedInput || handle.settled()) return;
+      closedInput = true;
+      const error = finishError;
+      if (!appsRetry) emit({ type: "result", subtype: error ? "error_during_execution" : "success", is_error: !!error,
+        ...(error ? { error: String(error), errors: [String(error)] } : {}),
+        ...(!error && lastAssistantText ? { result: lastAssistantText } : {}),
+        num_turns: Math.max(modelCalls, turnId ? 1 : 0), duration_ms: Date.now() - startedAt,
+        cost_source: "unavailable", ...(latestUsage ? { usage: latestUsage } : {}) });
+      child.stdin.end();
+      finishTimer = setTimeout(() => { if (!handle.settled()) handle.kill(); }, 500);
+    };
+    const finish = (error) => {
+      if (ending || handle.settled()) return;
+      ending = true;
+      abortQuestions();
+      finishError = error;
+      closeTurn();
+    };
+    const toolStart = (item) => {
+      if (closed.has(item.id)) return;
+      let name; let input;
+      if (item.type === "mcpToolCall") { name = `mcp__${item.server}__${item.tool}`; input = item.arguments; }
+      else if (item.type === "commandExecution") { name = "Bash"; input = { command: item.command }; }
+      else if (item.type === "fileChange") { name = "Edit"; input = { changes: item.changes }; }
+      else return;
+      const previous = opened.get(item.id);
+      const snapshot = JSON.stringify(input);
+      if (opened.has(item.id)) {
+        // File inputs can change after item/started. Keep the snapshot in
+        // the raw transcript without inventing another tool call (#925).
+        if (item.type === "fileChange" && previous !== snapshot) {
+          opened.set(item.id, snapshot);
+          emit({ type: "system", subtype: "tool_input", tool_use_id: item.id, name, input });
+        }
+        return;
+      }
+      opened.set(item.id, snapshot);
+      assistant([{ type: "tool_use", id: item.id, name, input }]);
+    };
+    rpc = codexRpc(child, {
+      timeoutMs: opts.rpcTimeoutMs ?? 15_000,
+      async onRequest(method, params, requestId) {
+        if (method === ELICITATION || INPUT_REQUESTS.has(method)) {
+          const cancelled = method === ELICITATION ? { action: "cancel", content: null } : { answers: {} };
+          const refused = method === ELICITATION ? { action: "decline", content: null } : { answers: {} };
+          const identityMatches = () => params.threadId === threadId && threadId !== null &&
+            (params.turnId == null ? method === ELICITATION : params.turnId === turnId);
+          if (resolvedRequests.has(requestId)) return cancelled;
+          let parsed;
+          try { parsed = protocolQuestions(method, params); } catch { parsed = refuse("request could not be read"); }
+          const reason = !asking ? "this run does not ask the person"
+            : config.computerApps !== true ? "the computer's apps are off for this run"
+            : approvalsClosed() ? "the run is ending"
+            : !identityMatches() ? "thread or turn does not match this run"
+            : method === ELICITATION && !appSources?.some((source) => source.enabled && source.name === params.serverName) ? "server is not an enabled app"
+            : parsed.refused;
+          if (reason) {
+            opts.log?.(refusalLine(method, params, reason));
+            emit({ type: "system", subtype: "permission", decision: "denied", message: "Codex requested input this run cannot safely ask for. No answer or permission was supplied." });
+            return refused;
+          }
+          const { questions } = parsed;
+          const controller = new AbortController();
+          openQuestions.add(controller);
+          protocolRequests.set(requestId, controller);
+          waitingOnPerson += 1;
+          const answers = [];
+          try {
+            for (const question of questions) {
+              if (controller.signal.aborted || approvalsClosed() || resolvedRequests.has(requestId) || !identityMatches()) return cancelled;
+              const appApproval = question.id?.startsWith("mcp_tool_call_approval") ||
+                (method === ELICITATION && question.id === undefined && question.options.includes("Allow"));
+              const hostedQuestion = { ...question, options: [...question.options, CANCEL],
+                recommendation: appApproval
+                  ? { answer: "Allow", why: "It lets this run carry on with what you asked." }
+                  : { answer: CANCEL, why: "Cancel unless you have checked this request and want to answer it." } };
+              let abort;
+              const aborted = new Promise((resolve) => {
+                abort = () => resolve(null);
+                controller.signal.addEventListener("abort", abort, { once: true });
+              });
+              let verdict;
+              try {
+                verdict = await Promise.race([aborted, Promise.resolve().then(() => opts.askPermission({ question: hostedQuestion, signal: controller.signal }))]);
+              } finally { controller.signal.removeEventListener("abort", abort); }
+              if (controller.signal.aborted || approvalsClosed() || resolvedRequests.has(requestId) || !identityMatches() || verdict?.behavior === "cancel" || verdict == null) return cancelled;
+              if (verdict.behavior === "answer" && verdict.answer === CANCEL) return cancelled;
+              if (verdict.behavior === "answer" && typeof verdict.answer === "string" && !verdict.answer.trim()) return refused;
+              if (appApproval && verdict.behavior === "answer" && verdict.answer === "Not this") return refused;
+              if ((method === ELICITATION || appApproval) && verdict.behavior === "answer" && typeof verdict.answer === "string" && !question.options.includes(verdict.answer)) {
+                // Declines have no protocol content. Use the incumbent live
+                // reply path so own words reach the agent, never grant a call.
+                ownWordsPending += 1;
+                try {
+                  if (!(await deliver(`The person declined this app request: ${question.question}\nTheir answer: ${verdict.answer}`))) throw new Error("the turn is no longer active");
+                } catch (error) {
+                  // Completion may already have begun while steer was in
+                  // flight. Preserve its delivery failure before closing.
+                  finishError ??= `Codex could not deliver your app answer: ${error.message}`;
+                  finish(finishError);
+                } finally { ownWordsPending -= 1; closeTurn(); }
+                return refused;
+              }
+              if (verdict.behavior !== "answer" || !question.options.includes(verdict.answer)) return refused;
+              answers.push(verdict.answer);
+            }
+            if (INPUT_REQUESTS.has(method)) return { answers: Object.fromEntries(questions.map((question, i) => [question.id, { answers: [answers[i]] }])) };
+            if (answers.at(-1) === "Not this") return refused;
+            return { action: "accept", content: params.mode === "url" ? null : Object.fromEntries(questions.filter((q) => q.id !== undefined).map((q, i) => [q.id, q.values[q.options.indexOf(answers[i])]])) };
+          } catch (error) {
+            opts.log?.(`Codex ${method} refused: the question failed (${error.message})`);
+            return refused;
+          } finally {
+            controller.abort();
+            openQuestions.delete(controller);
+            protocolRequests.delete(requestId);
+            waitingOnPerson -= 1;
+            handle.state.lastStdoutAt = Date.now();
+          }
+        }
+        // ASK IN THE IDEA (#478): a normal run with a board to ask on files the
+        // question and returns the person's answer. A draft, or a run with no
+        // asker, keeps declining. While the person decides, the stall watcher
+        // stands down (waitingOnPerson).
+        if (asking && ASKABLE_APPROVALS.has(method) && !approvalsClosed() && !resolvedRequests.has(requestId)) {
+          const call = approvalAsAsk(method, params);
+          const controller = new AbortController();
+          openQuestions.add(controller);
+          protocolRequests.set(requestId, controller);
+          waitingOnPerson += 1;
+          let verdict = null;
+          try { verdict = await opts.askPermission({ toolName: call.toolName, input: call.input, signal: controller.signal }); }
+          catch (error) { opts.log?.(`permission question failed: ${error.message}`); }
+          finally { openQuestions.delete(controller); protocolRequests.delete(requestId); waitingOnPerson -= 1; handle.state.lastStdoutAt = Date.now(); }
+          const allowed = !controller.signal.aborted && !approvalsClosed() && !resolvedRequests.has(requestId) && verdict?.behavior === "allow";
+          emit({ type: "system", subtype: "permission", decision: allowed ? "allowed" : "denied", message: allowed ? `${method}: the person allowed it.` : `${method}: ${verdict?.message ?? "the person said no, or did not answer."}` });
+          return approvalAnswer(method, params, allowed);
+        }
+        emit({ type: "system", subtype: "permission", decision: "denied", message: `${method}: use board ask_user for human decisions; this run cannot approve sandbox escalation.` });
+        if (ASKABLE_APPROVALS.has(method)) return approvalAnswer(method, params, false);
+        if (method.endsWith("/requestApproval")) return { decision: "decline" };
+        // RENAMED 2026-09-12 (brief 31, Move 3b): codexBoardArgs above
+        // registers the server as `mcp_servers.glytch`, so that is the tool
+        // name codex's own namespace actually answers to.
+        throw new Error(`Unsupported Codex request ${method}; ask with mcp__glytch__ask_user.`);
+      },
+      onNotification(method, params) {
+        if (handle.settled() || (threadId && params.threadId && params.threadId !== threadId)) return;
+        // Every protocol event proves liveness, including long-running tools.
+        handle.state.lastStdoutAt = Date.now();
+        if (method === "serverRequest/resolved" && params.threadId === threadId) {
+          resolvedRequests.add(params.requestId);
+          protocolRequests.get(params.requestId)?.abort();
+        }
+        if (method === "turn/started") {
+          if (turnId && params.turn?.id && turnId !== params.turn.id) abortQuestions();
+          turnId = params.turn?.id ?? turnId;
+        }
+        if (method === "item/agentMessage/delta") {
+          messages.delta(params.itemId, params.delta);
+        } else if (method === "item/reasoning/summaryTextDelta") {
+          assistant([{ type: "thinking", thinking: params.delta ?? "" }]);
+        } else if (method === "turn/plan/updated") {
+          const id = `codex-plan-${Date.now()}`;
+          assistant([{ type: "tool_use", id, name: "TodoWrite", input: { todos: (params.plan ?? []).map((p) => ({ content: p.step, status: p.status === "inProgress" ? "in_progress" : p.status })) } }]);
+          emit({ type: "user", message: { role: "user", content: [{ type: "tool_result", tool_use_id: id, content: "Plan updated" }] } });
+        } else if (method === "thread/tokenUsage/updated") {
+          // One usage update per model response: the count Claude Code calls
+          // turns (QA 2026-10-01, e4 - Codex always read "1 turn").
+          modelCalls += 1;
+          const usage = params.tokenUsage?.last;
+          if (params.tokenUsage?.total) accountingUsage = params.tokenUsage.total;
+          contextWindow = params.tokenUsage?.modelContextWindow;
+          if (usage) {
+            // inputTokens already INCLUDES cachedInputTokens. The shared
+            // context scanner adds caches, so do not count them twice.
+            latestUsage = { input_tokens: usage.inputTokens, output_tokens: usage.outputTokens };
+            assistant([], { usage: latestUsage, usage_is_snapshot: true,
+              total_usage: params.tokenUsage.total ? { input_tokens: params.tokenUsage.total.inputTokens, output_tokens: params.tokenUsage.total.outputTokens } : latestUsage });
+          }
+        } else if (method === "item/started") toolStart(params.item ?? {});
+        else if (method === "item/fileChange/patchUpdated") {
+          toolStart({ type: "fileChange", id: params.itemId, changes: params.changes });
+        } else if (method === "item/completed") {
+          const item = params.item ?? {};
+          if (item.type === "agentMessage") {
+            const text = messages.complete(item);
+            if (text !== null) {
+              lastAssistantText = text;
+              assistant([{ type: "text", text }]);
+            }
+          }
+          toolStart(item);
+          closed.add(item.id);
+          if (opened.delete(item.id)) emit({ type: "user", message: { role: "user", content: [{ type: "tool_result", tool_use_id: item.id,
+            is_error: item.status === "failed" || item.status === "declined" || item.error != null || (item.exitCode != null && item.exitCode !== 0),
+            content: item.result?.content ?? item.aggregatedOutput ?? item.error?.message ?? "Completed" }] } });
+        } else if (method === "turn/completed") {
+          turnId = params.turn?.id ?? turnId;
+          finish(params.turn?.status === "completed" ? null : params.turn?.error?.message ?? `Codex turn ${params.turn?.status ?? "failed"}`);
+        } else if (method === "error" && params.willRetry !== true) finish(params.error?.message ?? "Codex failed");
+      },
+    });
+    const deliver = async (text, images) => {
+      if (!threadId || !turnId || ending || stopping || handle.settled()) return false;
+      await rpc.request("turn/steer", { threadId, expectedTurnId: turnId, input: inputFor(text, images) });
+      emit({ type: "user", message: { role: "user", content: [{ type: "text", text }] } });
+      return true;
+    };
+    if (opts.replyDir && opts.replyPrefix) handle.every(async () => {
+      if (replyBusy || !turnId || ending || stopping || handle.settled()) return;
+      replyBusy = true;
+      try {
+        const files = (await readdir(opts.replyDir)).filter((f) => f.startsWith(opts.replyPrefix) && f.endsWith(".json")).sort();
+        for (const file of files) {
+          if (ending || stopping || handle.settled()) break;
+          let reply;
+          const path = join(opts.replyDir, file);
+          try { reply = JSON.parse(await readFile(path, "utf8")); } catch { continue; }
+          if (typeof reply.message !== "string") continue;
+          try { imageAttachments(reply.images); } catch (error) {
+            finish(`Reference image reply was not delivered: ${error.message}`);
+            return;
+          }
+          // Consume once before sending, matching the existing runner. A
+          // rejected steer becomes a resumable reply; never replay blindly.
+          try { await unlink(path); } catch { continue; }
+          try {
+            const text = reply.from ? `[message from ${reply.from}] ${reply.message}` : reply.message;
+            if (!(await deliver(text, reply.images))) await writeFile(path, JSON.stringify(reply), { flag: "wx" });
+          } catch (error) {
+            emit({ type: "system", subtype: "error", message: `Reply delivery failed: ${error.message}` });
+            // Only a definite active-turn rejection is safe to promote.
+            if (/turn.*(not found|not active|mismatch|completed)|no active turn/i.test(error.message)) {
+              await writeFile(path, JSON.stringify(reply), { flag: "wx" });
+            } else {
+              finish(`Codex could not confirm delivery of your reply: ${error.message}`);
+            }
+          }
+        }
+      } catch { /* directory may disappear while disconnecting */ }
+      finally { replyBusy = false; closeTurn(); }
+    }, opts.replyPollMs ?? 2000);
+    const collectAnswers = async () => {
+      if (!opts.answerPoll) return;
+      if (answerBusy || ending || !turnId || stopping || handle.settled()) return;
+      answerBusy = true;
+      try { for (const answer of await opts.answerPoll()) if (await deliver(answer.text)) await answer.onDelivered?.(); }
+      catch { /* a failed delivery is not an acknowledged answer */ }
+      finally { answerBusy = false; closeTurn(); }
+    };
+    if (opts.answerPoll) {
+      handle.every(collectAnswers, opts.answerPollMs ?? 4000);
+      opts.answerPoll.subscribe?.(collectAnswers);
+    }
+    const stallMs = opts.stallMs ?? DEFAULTS.stallMs;
+    handle.every(() => {
+      if (!ending && waitingOnPerson === 0 && handle.state.openToolUses.size === 0 && Date.now() - handle.state.lastStdoutAt >= stallMs) {
+        handle.state.stalled = true; handle.kill();
+      }
+    }, Math.min(10_000, stallMs / 4));
+    void (async () => {
+      await rpc.initialize();
+      // ONE EXTRA CALL, ON THE SAME CONNECTION, BEFORE ANY BILLABLE TURN
+      // (brief 46, Move 4). Codex reports no dollars; what it reports
+      // instead is how full its 5-hour and weekly windows are
+      // (`account/rateLimits/read`). Read once here for the info line a
+      // person reads instead of a cost figure. It stops nothing: a Codex
+      // run no longer stands down at a percentage (#170, #338).
+      planWindow = await readPlanWindow(rpc, { log: opts.log });
+      const account = await rpc.request("account/read", { refreshToken: false });
+      if (account.account == null && account.requiresOpenaiAuth !== false) throw new Error("Codex is not signed in. Run `codex login` and try again.");
+      if (!planWindow.primary && !planWindow.secondary) opts.log?.("Codex did not report its plan window.");
+      // Check the account's catalog before starting any billable turn. A
+      // stale saved model/effort must fail explicitly, never be substituted.
+      const catalog = [];
+      let cursor;
+      do {
+        const page = await rpc.request("model/list", { ...(cursor ? { cursor } : {}), limit: 100 });
+        catalog.push(...(page.data ?? []));
+        cursor = page.nextCursor;
+      } while (cursor && catalog.length < 200);
+      const selected = config.model ? catalog.find((m) => m.model === config.model) : catalog.find((m) => m.isDefault);
+      if (config.model && !selected) throw new Error(`Codex model "${config.model}" is not available in this account. Choose a model from the current Codex catalog.`);
+      if (config.effort && (!selected || !(selected.supportedReasoningEfforts ?? []).some((e) => e.reasoningEffort === config.effort))) {
+        throw new Error(`Codex effort "${config.effort}" is not supported by the selected model. Choose a supported effort or Default.`);
+      }
+      // DRAFT: read-only sandbox, no resume, no persisted session.
+      //
+      // `sandbox: "read-only"` is checked against the installed codex-cli
+      // 0.153.4's own generated protocol schema (`codex app-server
+      // generate-json-schema --out <dir>`, definitions.SandboxPolicy): the
+      // `ReadOnlySandboxPolicy` variant defaults `networkAccess: false`
+      // alongside blocking writes, so this is an OS-level seatbelt/landlock
+      // restriction on top of the CLI flag being named "read-only" - not an
+      // assumption that the label implies both. `approvalPolicy: "never"`
+      // means a blocked write or network attempt is returned to the model as
+      // a failure and never escalated into an approval prompt this runner
+      // would have to answer (the onRequest handler above declines any that
+      // somehow arrive anyway). `ephemeral: true` is codex's own "no session
+      // files persisted to disk" (matches `codex exec --ephemeral`'s
+      // documented meaning), which is this engine's version of "no
+      // persistent session" - and resume is never requested for a draft
+      // regardless of what a caller passed, so a draft can never inherit an
+      // implementation thread's history or permissions.
+      const thread = await rpc.request(!isDraft && config.resumeSessionId ? "thread/resume" : "thread/start", {
+        ...(!isDraft && config.resumeSessionId ? { threadId: config.resumeSessionId } : {}),
+        cwd: opts.cwd, approvalPolicy: asking ? "on-request" : "never", sandbox: isDraft ? "read-only" : "workspace-write",
+        ...(isDraft ? { ephemeral: true } : {}),
+        ...(config.model ? { model: config.model } : {}),
+        // The extra writable root for `<boardRoot>/.glytch` retired with it
+        // (2026-09-11, brief 30 W2a): it existed so the locally-spawned
+        // local stdio server - itself a child of this sandboxed process,
+        // back when the board was a `command`/`args` MCP entry - could
+        // write ops files onto disk. The board is an HTTPS call now, made by codex itself
+        // rather than by a filesystem-writing subprocess, so there is nothing
+        // under `.glytch` for this sandbox to need write access to any more.
+        config: {
+          ...(isDraft ? {} : { "sandbox_workspace_write.writable_roots": [opts.cwd].filter(Boolean) }),
+          ...(config.effort ? { model_reasoning_effort: config.effort } : {}),
+          // THE PLAN TOOL, SWITCHED ON (2026-09-26, the same live run): the
+          // preamble tells a Codex session to plan with `update_plan`, and
+          // the run screen shows steps from that tool's calls - but
+          // the app-server thread does not carry it unless asked, so the
+          // session wrote "update_plan is unavailable" and planned in prose,
+          // which shows no steps. `tools.update_plan` is codex's own config
+          // key for it (ToolsToml: web_search, experimental_request_user_input,
+          // update_plan). It is a STRUCT, not a flag: codex-rs's
+          // UpdatePlanToolConfig is `{ enabled: bool }` with unknown fields
+          // rejected, and a bare `true` made thread/start fail outright
+          // ("invalid type: boolean `true`, expected struct
+          // UpdatePlanToolConfig", live run spawn-muir3xjh-94fa5c).
+          "tools.update_plan": { enabled: true },
+          // WEB SEARCH FOR A RUN ON THIS COMPUTER (#478): `web_search` is
+          // codex's own top-level config key (WebSearchMode: disabled |
+          // cached | indexed | live, checked against codex-cli 0.162's
+          // generated protocol schema). Live only when asked for; otherwise
+          // set to disabled, so a ~/.codex/config.toml that turns live
+          // search on cannot search past the promised question (box review
+          // of PR 504). A plan draft never searches.
+          web_search: !isDraft && config.webSearch === true ? "live" : "disabled",
+        },
+      });
+      threadId = thread.thread?.id;
+      if (!threadId) throw new Error("Codex did not return a thread id");
+      await opts.onSession?.(threadId);
+      const checkedApps = await verifyCodexApps(rpc, { cwd: opts.cwd, threadId, on: config.computerApps === true, isDraft, sources: appSources });
+      if (checkedApps.notices.length) {
+        appsRetry = checkedApps;
+        // Reap the child through the existing bounded shutdown before retrying.
+        finish("Checking apps again with the unverified apps turned off.");
+        return;
+      }
+      for (const message of apps.notices) emit({ type: "system", subtype: "info", message });
+      emit({ type: "system", subtype: "init", model: thread.model ?? config.model, effort: thread.reasoningEffort ?? config.effort, engine: "codex" });
+      emit({ type: "system", subtype: "info", message: planWindowInfoMessage(planWindow) });
+      // An apps-off run looks like missing tools from the transcript alone:
+      // the model searches, finds none and says so (#2366, a chat turn).
+      if (config.computerApps !== true) emit({ type: "system", subtype: "info", message: APPS_OFF_INFO });
+      handle.markSent();
+      // THE ECHO IS THE PERSON'S OWN WORDS, NOT THE WHOLE BRIEF (2026-09-26):
+      // `opts.prompt` is the preamble plus the repo primer plus what they
+      // typed, and the expanded run drew all of it as the first transcript
+      // line - a wall of instructions above a two-line request. The runner
+      // hands the typed part separately as `opts.brief`; the child still
+      // receives the full prompt below. The role is what makes it the
+      // person's: the app reads a user event without one as the agent
+      // talking, and a chat streamed its instructions into the reply (#702).
+      emit({ type: "user", message: { role: "user", content: [{ type: "text", text: opts.brief ?? opts.prompt }] } });
+      const result = await rpc.request("turn/start", { threadId, input: inputFor(opts.prompt, opts.images),
+        ...(config.outputSchema ? { outputSchema: config.outputSchema } : {}),
+        ...(config.model ? { model: config.model } : {}), ...(config.effort ? { effort: config.effort } : {}) });
+      turnId = result.turn?.id ?? turnId;
+    })().catch((error) => finish(error.message));
+    };
+  });
+}