toolroll 0.5.0

package/dist/provider.js

@@ -0,0 +1,935 @@
+/**
+ * The provider registry: every way this plane can spend money on an agent,
+ * in one file (§5's "one door", widened to three harness shapes).
+ *
+ * A provider here is how to SPAWN a harness and how to READ its envelope —
+ * argv dialect, transport, session identity, usage. The briefs, the mailbox
+ * protocol, and every custody proof are provider-neutral and live where
+ * they always did; this module owns only the dialect differences.
+ *
+ * Boundary (the architecture test enforces it): only `invoke.ts` may import
+ * the spawning surface (`adapterFor`); everything else that needs provider
+ * facts uses the non-spending inspection surface (`PROVIDERS`,
+ * `inspectionOf`) — identification must never be a way to start an LLM.
+ *
+ * `openrouter` is deliberately not a fourth transport: it is the codex
+ * harness pointed at OpenRouter through `-c` overrides whose keys and
+ * values are CONSTANTS below — no caller-supplied dotted keys, values
+ * TOML-quoted deterministically, and the API key excluded from every
+ * shell the model itself launches (Codex provider review, Q5).
+ */
+import { claudeFenceSettings, codexFenceArgv } from "./agent-fence.js";
+import {} from "./exec.js";
+import { runStreamJsonl, runClaudeStreamJsonl, runGeminiStreamJsonl } from "./exec.js";
+import { scanForSecrets } from "./evidence.js";
+import { REVIEW_OUTPUT_LIMITS } from "./structured-output.js";
+export const PROVIDER_IDS = ["claude", "codex", "openrouter", "gemini"];
+export function isProviderId(value) {
+    return PROVIDER_IDS.includes(value);
+}
+/**
+ * Model ids cross providers ("anthropic/claude-sonnet-4.5", "gpt-5-codex",
+ * "opus"). Bounded and printable, never leading-dash (argv safety), and no
+ * TOML-hostile characters — but NOT alphanumeric-only, which would refuse
+ * real ids carrying `/ . : -` (Codex provider review, Q5).
+ */
+export const MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/;
+export function validModelId(model) {
+    return model === null || MODEL_ID.test(model);
+}
+const USAGE_JSON_CAP = 8 * 1024;
+/** Empty and whitespace-only identities are absence, never resumable ids. */
+function sessionIdOf(value) {
+    if (typeof value !== "string")
+        return null;
+    const id = value.trim();
+    return id === "" ? null : id;
+}
+/** Deterministic TOML basic-string quoting for -c values — never the CLI's raw fallback. */
+function toml(value) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+/** OpenRouter rides codex under a PRIVATE provider key, isolated from user config. */
+const OPENROUTER_PROVIDER_KEY = "standing-orders_openrouter";
+export const OPENROUTER_ENV_KEY = "OPENROUTER_API_KEY";
+const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+/**
+ * The held-session argv (Parity II Phase 2): the same family as
+ * claudeArgv MINUS the positional prompt — every turn, the brief
+ * included, rides stdin as stream-json — plus the input format flag.
+ * maxBudgetUsd is the Probe-6 backstop: the CLI's cap is cumulative
+ * across the whole process, so the remaining authorization budget rides
+ * the argv and later turns cannot spend past it.
+ */
+export const claudeHeldArgv = (invocation) => [
+    "-p",
+    ...(invocation.resumeSession === null ? [] : ["--resume", invocation.resumeSession]),
+    "--input-format",
+    "stream-json",
+    "--output-format",
+    "stream-json",
+    "--verbose",
+    "--max-turns",
+    String(invocation.maxTurns),
+    ...(invocation.skipPermissions
+        ? ["--dangerously-skip-permissions"]
+        : ["--permission-mode", invocation.permissionMode]),
+    ...(invocation.model === null ? [] : ["--model", invocation.model]),
+    ...(invocation.maxBudgetUsd === undefined ? [] : ["--max-budget-usd", String(invocation.maxBudgetUsd)]),
+];
+/**
+ * Reviewer isolation (fail-closed for the phase that must never mutate):
+ * the SAME flag family `subscription-chat.ts` already uses for its own
+ * sealed-scratch turn — no tool but reading the sealed files, no prompt
+ * that can stall a headless run waiting on an
+ * approval nobody can answer, and no MCP server (global OR project) loaded
+ * at all. A reviewer that goes looking for tools beyond its scratch
+ * directory is exactly the leak this closes: `--permission-mode plan`
+ * alone governs EDITS, not an MCP server's own tools or an interactive
+ * prompt, and a headless `-p` turn that stalls on either just sits idle
+ * until the timeout kills it, having spent the money on nothing.
+ */
+const CLAUDE_REVIEW_ISOLATION_ARGV = [
+    "--restricted",
+    "--safe-mode",
+    "--tools",
+    "Read",
+    "--permission-prompts",
+    "none",
+    "--strict-mcp-config",
+    "--mcp-config",
+    '{"mcpServers":{}}',
+];
+/**
+ * Run 1467's fix: Opus's reply to a review turn came back as JSON that
+ * `parseReview` refused outright — prose around the object, a stray code
+ * fence, a shape close but not exact. `--json-schema` is claude's own
+ * structured-output enforcement, so the CLI (not this codebase) is what
+ * makes the model's final message parse as JSON shaped like a review — it
+ * is a formatting floor, never a validator: an id absent from the signed
+ * rubric, a duplicate id, or a judgement word outside the three legal ones
+ * still only `parseReview` can catch, because only `parseReview` is handed
+ * the run's actual signed criteria. Claude-only and review-phase-only: no
+ * other provider has this flag, and no other phase asks for structured
+ * output.
+ *
+ * Run 1638's fix: ONE flat object, never a top-level union. The evidence
+ * read channel (`readEvidence`, review-evidence.ts) shares this reply
+ * schema and session, and the first draft expressed "a review OR a read
+ * request" as a root `anyOf`. The API refuses that before any model turn
+ * (`tools.N.custom.input_schema.type: Field required`), and a root
+ * `type: "object"` beside the `anyOf` is refused the same way — top-level
+ * unions are unsupported for structured output. So the two reply shapes
+ * are merged into one property set with only `version` required, and
+ * the machine's own parsers do the discrimination the schema cannot:
+ * `isEvidenceOnlyReply`/`evidenceRequest` accept exactly
+ * `{version, readEvidence}` and nothing else; `parseReview` refuses any
+ * reply carrying `readEvidence` (a mixed reply is neither), and still
+ * refuses a review missing its comments or any signed criterion. Nothing
+ * a looser floor lets through lands anywhere but a typed refusal.
+ */
+const CLAUDE_REVIEW_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        // Optional advice is not a review gate. project-learning validates its
+        // shape, UTF-8 byte limits, secrets and provenance after core ingestion,
+        // recording invalid advice without changing the review. Duplicating that
+        // contract here made a 126-character observation kill a valid review.
+        learningAssessment: {},
+        learning: {},
+        version: { type: "integer", enum: [1] },
+        comments: {
+            type: "array",
+            maxItems: REVIEW_OUTPUT_LIMITS.comments,
+            items: {
+                type: "object",
+                properties: {
+                    path: { type: "string" },
+                    line: { type: ["integer", "null"], minimum: 1 },
+                    // Text limits belong to parseReview and its bounded same-session
+                    // correction, not a second provider retry loop counting code points.
+                    note: { type: "string" },
+                    severity: { type: "string", enum: ["note", "question", "problem"] },
+                },
+                required: ["path", "note"],
+                additionalProperties: false,
+            },
+        },
+        criteria: {
+            type: "array",
+            maxItems: REVIEW_OUTPUT_LIMITS.criteria,
+            items: {
+                type: "object",
+                properties: {
+                    id: { type: "string" },
+                    judgement: { type: "string", enum: ["upholds", "contradicts", "cannot-tell"] },
+                    note: { type: "string" },
+                },
+                required: ["id", "judgement", "note"],
+                additionalProperties: false,
+            },
+        },
+        // The read request rides the same structured reply channel and
+        // session. The machine validates the exact allowlist/hash/range
+        // before supplying bytes; this only shapes the request.
+        readEvidence: {
+            type: "object", properties: {
+                file: { type: "string", minLength: 1, maxLength: 100 },
+                sha256: { type: "string", pattern: "^[0-9a-f]{64}$" },
+                offset: { type: "integer", minimum: 0 },
+                length: { type: "integer", minimum: 1, maximum: 65536 },
+            }, required: ["file", "sha256", "offset", "length"], additionalProperties: false,
+        },
+    },
+    required: ["version"],
+    additionalProperties: false,
+};
+const claudeArgv = (invocation) => [
+    "-p",
+    invocation.brief,
+    ...(invocation.resumeSession === null ? [] : ["--resume", invocation.resumeSession]),
+    // stream-json (arc 1): the terminal result event IS the old buffered
+    // envelope, now arriving as one line of many — the streaming transport
+    // retains it structurally instead of buffering the whole session into
+    // an 8 MiB kill. --verbose is required by the harness for stream-json
+    // with -p and changes nothing else.
+    "--output-format",
+    "stream-json",
+    "--verbose",
+    "--max-turns",
+    String(invocation.maxTurns),
+    ...(invocation.phase === "review"
+        ? ["--permission-mode", invocation.permissionMode === "bypassPermissions" ? "plan" : invocation.permissionMode]
+        : invocation.skipPermissions
+            ? ["--dangerously-skip-permissions"]
+            : ["--permission-mode", invocation.permissionMode]),
+    ...(invocation.model === null ? [] : ["--model", invocation.model]),
+    ...(invocation.maxBudgetUsd === undefined ? [] : ["--max-budget-usd", String(invocation.maxBudgetUsd)]),
+    ...(invocation.phase === "review"
+        ? [...CLAUDE_REVIEW_ISOLATION_ARGV, "--json-schema", JSON.stringify(CLAUDE_REVIEW_JSON_SCHEMA)]
+        : [...(invocation.toolArgv ?? []), ...(invocation.fence !== undefined && invocation.fence.length > 0 ? ["--settings", claudeFenceSettings(invocation.fence)] : [])]),
+];
+/**
+ * The turn's own words, preferring the schema-validated structured field
+ * (present only under `--json-schema`) over the plain result string — the
+ * same preference `subscription-chat.ts`'s `claudeOutput` already applies
+ * for its own `--json-schema` turn. Re-serialized (never the CLI's raw
+ * text) so downstream parsing (`parseReview`) sees canonical JSON either
+ * way.
+ */
+function claudeFinalMessage(result) {
+    if (result === null)
+        return null;
+    if (result.structured_output !== undefined && result.structured_output !== null) {
+        return JSON.stringify(result.structured_output);
+    }
+    return typeof result.result === "string" ? result.result : null;
+}
+/**
+ * The primary-result allowlist (arc 1 finding 10): only an absent origin or
+ * an explicit human origin can be the main query's accounting envelope.
+ * Every other kind — task-notification, channel, peer, coordinator, and
+ * anything the SDK grows later — fails closed as a non-primary result.
+ */
+function claudePrimaryOrigin(event) {
+    if (event.origin === undefined || event.origin === null)
+        return true;
+    return typeof event.origin === "object" && String(event.origin["kind"] ?? "") === "human";
+}
+function claudeEnvelopeOf(result, sessionFromInit, initObserved, initSessionConflict = false) {
+    const input = result?.usage?.input_tokens;
+    const output = result?.usage?.output_tokens;
+    const cost = result?.total_cost_usd;
+    const sessionFromResult = sessionIdOf(result?.session_id);
+    const resultSessionConflict = sessionFromInit !== null && sessionFromResult !== null && sessionFromInit !== sessionFromResult;
+    const sessionConflict = initSessionConflict || resultSessionConflict;
+    return {
+        // Never choose one side of a contradictory identity. A repair must not
+        // resume either session until the gateway has refused this turn.
+        sessionId: sessionConflict ? null : sessionFromResult ?? sessionFromInit,
+        protocolError: initSessionConflict
+            ? "Claude emitted conflicting system/init session ids"
+            : resultSessionConflict
+                ? "the Claude init event and terminal result announced different session ids"
+                : null,
+        finalMessage: claudeFinalMessage(result),
+        ending: result === null ? null : {
+            subtype: typeof result.subtype === "string" ? result.subtype : null,
+            turns: typeof result.num_turns === "number" && result.num_turns >= 0 ? result.num_turns : null,
+        },
+        tokensIn: typeof input === "number" && input >= 0 ? input : null,
+        tokensOut: typeof output === "number" && output >= 0 ? output : null,
+        costUsd: typeof cost === "number" && cost >= 0 ? cost : null,
+        usageRaw: result?.usage === undefined ? null : JSON.stringify(result.usage).slice(0, USAGE_JSON_CAP),
+        initObserved,
+        // Structural, never prose (finding 15): consumed means the primary
+        // result says SUCCESS. An error result keeps its text as diagnostics
+        // while proving nothing about delivery; when the transport carries no
+        // signal (legacy buffered), null defers to the gateway's old rule.
+        promptConsumed: initObserved === null
+            ? null
+            : result !== null && result.is_error !== true && String(result.subtype ?? "") === "success",
+        diagnostic: null,
+        // Claude's usage-limit signal, when a fixture exists, is recognized
+        // from the error result's text at classification; the parser records a
+        // structural failure terminal when the result is a non-success error.
+        structuralTerminal: result !== null &&
+            (result.is_error === true ||
+                (typeof result.subtype === "string" && result.subtype !== "success") ||
+                (initObserved !== null && typeof result.subtype !== "string"))
+            ? { failed: true, text: typeof result.result === "string" ? result.result.slice(0, 2048) : null, code: typeof result.subtype === "string" ? result.subtype.slice(0, 128) : null }
+            : null,
+    };
+}
+/**
+ * Reads the streaming runner's retained lines: a bounded set of
+ * `system`/`init` identity witnesses and one primary `result`, re-proved here
+ * (the parser trusts no transport to have selected correctly). A single
+ * object without a `type` field is the
+ * legacy buffered envelope — kept for recorded fixtures, carrying no init
+ * signal, exactly as before the transport switch.
+ */
+function claudeParse(stdout) {
+    let initSeen = false;
+    let sessionFromInit = null;
+    let initSessionConflict = false;
+    let primary = null;
+    let transportFailure = null;
+    for (const line of stdout.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (event === null || typeof event !== "object")
+            continue;
+        const type = event["type"];
+        if (type === undefined) {
+            // Legacy buffered envelope: one JSON object, no event framing.
+            return claudeEnvelopeOf(event, null, null);
+        }
+        if (String(type) === "system" && String(event["subtype"] ?? "") === "init") {
+            initSeen = true;
+            const id = sessionIdOf(event["session_id"]);
+            if (id !== null) {
+                if (sessionFromInit === null)
+                    sessionFromInit = id;
+                else if (id !== sessionFromInit)
+                    initSessionConflict = true;
+            }
+        }
+        else if (String(type) === "result") {
+            const result = event;
+            if (result.is_error === true &&
+                result.subtype === "standing-orders-stream-event-overflow" &&
+                transportFailure === null) {
+                // The transport may append this bounded witness after an otherwise
+                // valid result when a later oversized init could conceal a second
+                // session identity. It is an independent protocol failure, not a
+                // replacement for the primary result's usage/accounting envelope.
+                transportFailure = result;
+            }
+            if (primary === null && claudePrimaryOrigin(result))
+                primary = result;
+        }
+    }
+    const envelope = claudeEnvelopeOf(primary, sessionFromInit, initSeen, initSessionConflict);
+    if (transportFailure === null)
+        return envelope;
+    return {
+        ...envelope,
+        structuralTerminal: {
+            failed: true,
+            text: typeof transportFailure.result === "string" ? transportFailure.result.slice(0, 2048) : null,
+            code: "standing-orders-stream-event-overflow",
+        },
+    };
+}
+/**
+ * The sandbox on a RESUME rides as a config override (`-c sandbox_mode=…`),
+ * never as `--sandbox`: `codex exec resume` (0.145.0, probed 2026-09-11)
+ * has no `--sandbox` flag and exits 2 before initializing when handed one
+ * — every structured correction and repair-by-resume was an immediately
+ * doomed turn that never echoed its thread. The override names the same
+ * exact mode the fresh turn was sealed with; the bypass flag and every
+ * `-c` override are accepted by both subcommands.
+ */
+const codexSandboxArgv = (mode, resuming) => resuming ? ["-c", `sandbox_mode="${mode}"`] : ["--sandbox", mode];
+/**
+ * Codex's own fail-closed equivalent of `CLAUDE_REVIEW_ISOLATION_ARGV`:
+ * read-only sandbox rather than the ordinary `workspace-write` (a reviewer
+ * dispatched to codex was, until this, handed a write-capable sandbox —
+ * the same class of leak the claude side had), approvals that REFUSE
+ * rather than wait on a prompt a headless turn can never answer, and the
+ * user's own `~/.codex/config.toml` — which can name arbitrary MCP
+ * servers, exactly the surface `--strict-mcp-config` closes for claude —
+ * ignored outright.
+ */
+const CODEX_REVIEW_ISOLATION_ARGV = (resuming) => [
+    "--ignore-user-config",
+    ...codexSandboxArgv("read-only", resuming),
+    "-c",
+    'approval_policy="never"',
+    "-c",
+    'web_search="disabled"',
+    "-c",
+    "features.shell_tool=false",
+    "-c",
+    "features.unified_exec=false",
+    "-c",
+    "features.multi_agent=false",
+    "-c",
+    "apps._default.enabled=false",
+];
+/**
+ * Codex argv. The brief is the positional prompt; resume is a subcommand.
+ * Auto uses `workspace-write` because the protocol REQUIRES workspace
+ * writes (the mailbox, the handoff). Full access uses Codex's one explicit
+ * combined bypass flag; that exact choice came from the sealed profile.
+ * Never `--ephemeral`: repair resumes.
+ */
+const codexArgv = (extra) => (invocation) => {
+    const resuming = invocation.resumeSession !== null;
+    return [
+        "exec",
+        ...(invocation.resumeSession === null ? [] : ["resume", invocation.resumeSession]),
+        "--json",
+        "--skip-git-repo-check",
+        ...(invocation.phase === "review"
+            ? CODEX_REVIEW_ISOLATION_ARGV(resuming)
+            // The agent fence: Codex's own sandbox with Toolroll's secrets
+            // denied. Full access becomes that sandbox widened to write anywhere
+            // with network, instead of no sandbox (which fenced nothing).
+            : invocation.fence !== undefined && invocation.fence.length > 0
+                ? codexFenceArgv(invocation.fence, invocation.skipPermissions)
+                : invocation.skipPermissions
+                    ? ["--dangerously-bypass-approvals-and-sandbox"]
+                    : codexSandboxArgv("workspace-write", resuming)),
+        ...(invocation.model === null ? [] : ["-m", invocation.model]),
+        ...extra,
+        // After `extra`: the tools' shell_environment_policy must be the last word (it keeps OpenRouter's key out too).
+        ...(invocation.phase === "review" ? [] : invocation.toolArgv ?? []),
+        ...(invocation.phase === "review" ? (invocation.reviewImages ?? []).flatMap(path => ["--image", path]) : []),
+        // Review includes the sealed text itself: no shell/read tool exists in
+        // this posture. stdin avoids both per-argument and Windows argv limits.
+        invocation.phase === "review" ? "-" : invocation.brief,
+    ];
+};
+/**
+ * The retained JSONL lines (the streaming transport keeps only these):
+ * thread.started (session), turn.completed (usage), the last agent_message.
+ * Unknown events were dropped at the transport; unknown here are ignored
+ * too. Missing terminal usage stays NULL — unmeasured, and said so.
+ */
+function codexParse(stdout) {
+    let sessionId = null;
+    let sessionConflict = false;
+    let finalMessage = null;
+    let tokensIn = null;
+    let tokensOut = null;
+    let usageRaw = null;
+    let initObserved = false;
+    let structuralTerminal = null;
+    for (const line of stdout.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const type = String(event["type"] ?? "");
+        if (type === "thread.started") {
+            // The init signal, id or no id: the harness came up. A malformed
+            // thread_id loses the session, not the fact of initialization.
+            initObserved = true;
+            const announced = sessionIdOf(event["thread_id"]);
+            if (announced !== null) {
+                if (sessionId === null)
+                    sessionId = announced;
+                else if (announced !== sessionId)
+                    sessionConflict = true;
+            }
+        }
+        else if (type === "turn.completed") {
+            const usage = event["usage"];
+            const input = usage?.["input_tokens"];
+            const output = usage?.["output_tokens"];
+            // cached_input_tokens deliberately NOT summed into input — it rides
+            // only in the raw record (Codex provider review, Q2).
+            if (typeof input === "number" && input >= 0)
+                tokensIn = input;
+            if (typeof output === "number" && output >= 0)
+                tokensOut = output;
+            if (usage !== undefined)
+                usageRaw = JSON.stringify(usage).slice(0, USAGE_JSON_CAP);
+        }
+        else if (type === "item.completed") {
+            const item = event["item"];
+            if (item !== undefined && String(item["type"] ?? "") === "agent_message") {
+                const text = item["text"];
+                if (typeof text === "string")
+                    finalMessage = text;
+            }
+        }
+        else if (type === "turn.failed") {
+            // RETAIN the structural failure terminal (Codex fallback verify,
+            // finding 1): a turn.failed carries the usage-limit signal, and
+            // dropping it here is where the evidence used to die. The error
+            // object's message + typed code ride into the taxonomy; its mere
+            // presence blocks success ingestion downstream.
+            const error = event["error"];
+            const message = error?.["message"];
+            const code = error?.["type"] ?? error?.["code"];
+            structuralTerminal = {
+                failed: true,
+                text: typeof message === "string" ? message.slice(0, 2048) : null,
+                code: typeof code === "string" ? code.slice(0, 128) : null,
+            };
+        }
+    }
+    // Codex reports no dollars. NULL is the honest cost — unmeasured — and
+    // every surface downstream already says so instead of summing a lie.
+    // promptConsumed stays null: codex carries no structural consumption
+    // signal, and the gateway keeps its historical rule for it.
+    return {
+        // As with Claude, never let either side of a contradictory identity
+        // become repair state. The gateway records the spend, then refuses it.
+        sessionId: sessionConflict ? null : sessionId,
+        protocolError: sessionConflict
+            ? "Codex emitted conflicting thread.started session ids"
+            : null,
+        finalMessage,
+        tokensIn,
+        tokensOut,
+        costUsd: null,
+        usageRaw,
+        initObserved,
+        promptConsumed: null,
+        diagnostic: null,
+        structuralTerminal,
+    };
+}
+/** Codex interval caps: inactivity for current profiles, wall clock for
+ * repair and legacy profiles. */
+const CODEX_TIMEOUT_CAP_MS = {
+    build: 20 * 60_000,
+    plan: 20 * 60_000,
+    repair: 5 * 60_000,
+    review: 20 * 60_000,
+};
+/**
+ * Gemini argv (Phase 3, v0.57.0 audit). The brief is `-p` (headless);
+ * `--approval-mode` is the ONE sealed autonomy dial — skipPermissions
+ * maps to yolo exactly where claude maps it to bypass, anything else is
+ * auto_edit (fail-closed: never `default`, whose headless behavior is
+ * tool failure, and never `plan`, which cannot write the mailbox).
+ * Session identity is minted by the plane (`--session-id`) or resumed
+ * (`--resume`) — never both. No turn bound and no dollar cap exist to
+ * render (the audit and money capabilities say so instead).
+ */
+const geminiArgv = (invocation) => [
+    "-p",
+    invocation.brief,
+    // S2 (live spike, v0.57.0): headless REFUSES untrusted directories, and
+    // a freshly leased worktree is always untrusted. --skip-trust grants
+    // this run's trust — and honestly (Codex gemini verify, finding 1): the
+    // CLI implements the flag by setting GEMINI_CLI_TRUST_WORKSPACE in its
+    // OWN process, which descendants inherit, and trusted mode is what lets
+    // gemini load a worktree's .gemini/ config (hooks, MCP). We accept that
+    // because gemini is dispatched ONLY on EXPLICIT operator selection (a
+    // phase-config row, a task pin, or a flag — never a default or fallback;
+    // the resolver's default is always claude), so trusting the workspace is
+    // the operator's own deliberate choice, not an ambient grant. A per-run
+    // config-isolation boundary (isolated GEMINI_DIR) is the tracked
+    // follow-up if gemini ever becomes a default. Until that lands, gemini
+    // has no fail-closed equivalent of the claude/codex review isolation
+    // above — `resolvePhaseAgent` (agentconfig.ts) refuses gemini for the
+    // review phase outright rather than let a documented, untracked leak
+    // pose as a confined reviewer.
+    "--skip-trust",
+    "--output-format",
+    "stream-json",
+    "--approval-mode",
+    invocation.skipPermissions ? "yolo" : "auto_edit",
+    ...(invocation.resumeSession !== null
+        ? ["--resume", invocation.resumeSession]
+        : invocation.startSessionId !== undefined
+            ? ["--session-id", invocation.startSessionId]
+            : []),
+    ...(invocation.model === null ? [] : ["-m", invocation.model]),
+    ...(invocation.toolArgv ?? []),
+];
+/** Gemini interval caps: inactivity for current profiles, wall clock for
+ * repair and legacy profiles. */
+const GEMINI_TIMEOUT_CAP_MS = {
+    build: 20 * 60_000,
+    plan: 20 * 60_000,
+    repair: 5 * 60_000,
+    review: 20 * 60_000,
+};
+const DIAGNOSTIC_CAP = 2 * 1024;
+/**
+ * Reads the gemini retention runner's synthetic stdout (Phase 3 D2/A7):
+ * a bounded set of `init` identity witnesses (result events carry no id, so
+ * identity is init-or-nothing), one `synthetic_message` (the runner-assembled
+ * assistant text; a type the real CLI cannot emit, so fixtures and transport
+ * share an unambiguous contract), the LAST `result` (tokens + structural
+ * status), and the first error line (diagnostics only). No legacy branch:
+ * the attestation floor is the only dialect this parser has ever had to honor.
+ */
+function geminiParse(stdout) {
+    let initSeen = false;
+    let sessionId = null;
+    let sessionConflict = false;
+    let finalMessage = null;
+    let tokensIn = null;
+    let tokensOut = null;
+    let usageRaw = null;
+    let resultStatus = null;
+    let diagnostic = null;
+    for (const line of stdout.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (event === null || typeof event !== "object")
+            continue;
+        const type = String(event["type"] ?? "");
+        if (type === "init") {
+            initSeen = true;
+            const announced = sessionIdOf(event["session_id"]);
+            if (announced !== null) {
+                if (sessionId === null)
+                    sessionId = announced;
+                else if (announced !== sessionId)
+                    sessionConflict = true;
+            }
+        }
+        else if (type === "synthetic_message") {
+            const content = event["content"];
+            if (typeof content === "string")
+                finalMessage = content;
+        }
+        else if (type === "result") {
+            resultStatus = String(event["status"] ?? "");
+            const stats = event["stats"];
+            const input = stats?.["input_tokens"];
+            const output = stats?.["output_tokens"];
+            if (typeof input === "number" && input >= 0)
+                tokensIn = input;
+            if (typeof output === "number" && output >= 0)
+                tokensOut = output;
+            if (stats !== undefined)
+                usageRaw = JSON.stringify(stats).slice(0, USAGE_JSON_CAP);
+            const resultError = event["error"];
+            const message = resultError?.["message"];
+            if (diagnostic === null && typeof message === "string" && message !== "") {
+                diagnostic = safeDiagnostic(message);
+            }
+        }
+        else if (type === "error") {
+            const message = event["message"];
+            if (diagnostic === null && String(event["severity"] ?? "") === "error" && typeof message === "string" && message !== "") {
+                diagnostic = safeDiagnostic(message);
+            }
+        }
+    }
+    return {
+        // A plane-minted id is useful only while the provider tells one
+        // consistent story about it. Never select either side of contradictory
+        // init events; the gateway records usage and refuses the turn.
+        sessionId: sessionConflict ? null : sessionId,
+        protocolError: sessionConflict ? "Gemini emitted conflicting init session ids" : null,
+        finalMessage,
+        tokensIn,
+        tokensOut,
+        // Gemini reports tokens, never dollars. NULL is the honest cost.
+        costUsd: null,
+        usageRaw,
+        initObserved: initSeen,
+        // Structural, never prose: consumed means the terminal result said
+        // SUCCESS. Missing or error results prove nothing about delivery —
+        // and for this provider the gateway's terminal contract REQUIRES the
+        // proof before exit 0 is believed (Phase 3 A4).
+        promptConsumed: resultStatus === "success",
+        diagnostic,
+        // A structural failure terminal ONLY when an ACTUAL non-success RESULT
+        // was seen (Codex foundation review, finding 2): a MISSING result
+        // (resultStatus null) is not evidence of anything — never fabricate a
+        // failure terminal from its absence (terminalContract already handles
+        // the exit-0-without-success case as protocol, not exhaustion).
+        structuralTerminal: resultStatus === null || resultStatus === "success"
+            ? null
+            : { failed: true, text: diagnostic, code: String(resultStatus).slice(0, 128) },
+    };
+}
+/** Truncate to a UTF-8 byte budget without splitting a code point. */
+function capUtf8(text, bytes) {
+    if (Buffer.byteLength(text, "utf8") <= bytes)
+        return text;
+    // The ellipsis lives INSIDE the byte budget, not on top of it.
+    const buffer = Buffer.from(text, "utf8").subarray(0, Math.max(0, bytes - 3));
+    return buffer.toString("utf8").replace(/�+$/, "") + "…";
+}
+/**
+ * The diagnostic discipline (Phase 3 B6/C6): the harness's own words are
+ * untrusted bytes headed for refusal screens and notifications — controls
+ * and line separators collapse to spaces (the fence's character class),
+ * and a line that trips the secret scanner is REPLACED, never quoted.
+ */
+export function safeDiagnostic(text) {
+    const normalized = text.replace(/[\u0000-\u001F\u007F-\u009F\u2028\u2029]+/g, " ").trim();
+    if (normalized === "")
+        return null;
+    if (scanForSecrets(normalized).length > 0)
+        return "the harness's error text was withheld — it matched a secret pattern";
+    return capUtf8(normalized, DIAGNOSTIC_CAP);
+}
+/** Every provider credential the plane knows about, by owner. A spawned
+ * provider gets its OWN keys and nobody else's: S4 (live spike) confirmed
+ * what inheritance makes true by construction — an agent's shell reads its
+ * process env, so a foreign key in that env is a foreign key disclosed. */
+const CREDENTIAL_ENV = {
+    claude: ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
+    codex: ["OPENAI_API_KEY", "CODEX_API_KEY"],
+    openrouter: [OPENROUTER_ENV_KEY],
+    gemini: ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
+};
+const foreignCredentialEnv = (own) => Object.entries(CREDENTIAL_ENV)
+    .filter(([provider]) => provider !== own)
+    .flatMap(([, keys]) => [...keys]);
+/** EVERY provider credential — what a version/help/which PROBE strips,
+ * since a feature check needs no key at all (Codex gemini verify,
+ * finding 2). Agent spawns keep their own; probes keep none. */
+export const ALL_CREDENTIAL_ENV = Object.values(CREDENTIAL_ENV).flat();
+const ADAPTERS = {
+    claude: {
+        binary: "claude",
+        argv: claudeArgv,
+        parse: claudeParse,
+        defaultRunner: runClaudeStreamJsonl,
+        extraOmitEnv: foreignCredentialEnv("claude"),
+        clampTimeout: (_phase, requested) => requested,
+    },
+    codex: {
+        binary: "codex",
+        argv: codexArgv([]),
+        stdin: invocation => invocation.phase === "review" ? invocation.brief : undefined,
+        parse: codexParse,
+        defaultRunner: runStreamJsonl,
+        extraOmitEnv: foreignCredentialEnv("codex"),
+        clampTimeout: (phase, requested) => Math.min(requested, CODEX_TIMEOUT_CAP_MS[phase]),
+    },
+    openrouter: {
+        binary: "codex",
+        stdin: invocation => invocation.phase === "review" ? invocation.brief : undefined,
+        argv: codexArgv([
+            "-c",
+            `model_provider=${toml(OPENROUTER_PROVIDER_KEY)}`,
+            "-c",
+            `model_providers.${OPENROUTER_PROVIDER_KEY}.name=${toml("OpenRouter")}`,
+            "-c",
+            `model_providers.${OPENROUTER_PROVIDER_KEY}.base_url=${toml(OPENROUTER_BASE_URL)}`,
+            "-c",
+            `model_providers.${OPENROUTER_PROVIDER_KEY}.env_key=${toml(OPENROUTER_ENV_KEY)}`,
+            // Asks Codex to keep the key out of the agent's shells. codex-cli
+            // 0.156 ignores shell_environment_policy, so the key IS readable from
+            // the agent's shell in practice; kept for Codex builds that honour it.
+            // What does hold is the agent fence: nothing else of Toolroll's
+            // (other keys, logins, tokens, the database) is reachable.
+            "-c",
+            `shell_environment_policy.exclude=[${toml(OPENROUTER_ENV_KEY)}]`,
+        ]),
+        parse: codexParse,
+        defaultRunner: runStreamJsonl,
+        extraOmitEnv: foreignCredentialEnv("openrouter"),
+        clampTimeout: (phase, requested) => Math.min(requested, CODEX_TIMEOUT_CAP_MS[phase]),
+    },
+    gemini: {
+        binary: "gemini",
+        argv: geminiArgv,
+        parse: geminiParse,
+        defaultRunner: runGeminiStreamJsonl,
+        extraOmitEnv: foreignCredentialEnv("gemini"),
+        clampTimeout: (phase, requested) => Math.min(requested, GEMINI_TIMEOUT_CAP_MS[phase]),
+    },
+};
+/**
+ * The spawning surface. Imported by invoke.ts and NOWHERE else — the
+ * architecture test reads imports, not string literals, because provider
+ * ids and binary names are legitimately the same words elsewhere.
+ */
+export function adapterFor(provider) {
+    return ADAPTERS[provider];
+}
+const AUDITS = {
+    claude: {
+        transport: "streaming-jsonl",
+        resume: "native",
+        initSignal: "system-init",
+        sessionIdentity: "announced",
+        terminalContract: "none",
+        // Restricted mode is resume-safe and is enforced for sealed reviewer
+        // turns. `enforced` remains false here because this provider-wide audit
+        // also covers ordinary build turns, where the flag is not applied.
+        isolation: { flag: "--restricted", resumeSafe: true, enforced: false },
+        configSurface: [
+            "~/.claude/CLAUDE.md and settings (hooks, MCP servers, plugins)",
+            "repository CLAUDE.md / .claude directory",
+        ],
+    },
+    codex: {
+        transport: "streaming-jsonl",
+        resume: "native",
+        initSignal: "thread.started",
+        sessionIdentity: "announced",
+        terminalContract: "none",
+        // --ephemeral exists and is deliberately not passed: repair resumes
+        // sessions, and ephemeral runs have none to resume.
+        isolation: { flag: "--ephemeral", resumeSafe: false, enforced: false },
+        configSurface: ["~/.codex/config.toml", "repository AGENTS.md"],
+    },
+    openrouter: {
+        transport: "streaming-jsonl",
+        resume: "native",
+        initSignal: "thread.started",
+        sessionIdentity: "announced",
+        terminalContract: "none",
+        isolation: { flag: "--ephemeral", resumeSafe: false, enforced: false },
+        // The constant -c overrides pin the model provider per invocation, so
+        // user config cannot reroute the spend — but the file still loads.
+        configSurface: ["~/.codex/config.toml (model_provider pinned per invocation)", "repository AGENTS.md"],
+    },
+    gemini: {
+        transport: "streaming-jsonl",
+        // S1 (live spike 2026-08-29, v0.57.0) PROVED headless persistence AND
+        // resume-by-uuid in the same cwd — the flip from "none" is the
+        // re-attestation the comment always demanded, now earned. Repair
+        // resumes the session instead of paying for a fresh one; geminiArgv
+        // must mint OR resume, never both (see the repair caller).
+        resume: "native",
+        initSignal: "init-event",
+        sessionIdentity: "minted",
+        terminalContract: "required",
+        isolation: { flag: "--sandbox", resumeSafe: null, enforced: false },
+        configSurface: [
+            "~/.gemini/settings.json (HOOKS — BeforeAgent/AfterTool commands run inside every invocation — plus MCP servers and model settings)",
+            "project .gemini/settings.json",
+            "GEMINI.md (global and repository)",
+            "extensions, skills, and policy files",
+            "GEMINI_API_KEY / GOOGLE_GENAI_USE_* environment (an API key in env is visible to the gemini agent's own shells — S4; every OTHER provider's spawn now sheds it, and cached login remains the tighter posture)",
+            "trusted-folder store (S2, live at 0.57.0: headless REFUSES untrusted directories; the plane grants --skip-trust per-invocation to its own leased worktrees)",
+        ],
+    },
+};
+export const MONEY_CAPABILITIES = {
+    claude: {
+        incrementalUsage: true,
+        nativeDollarCapFlag: "--max-budget-usd",
+        usageSemantics: "per-invocation",
+        tournamentEligible: true,
+        whyIneligible: null,
+    },
+    codex: {
+        incrementalUsage: false,
+        nativeDollarCapFlag: null,
+        usageSemantics: "cumulative-session",
+        tournamentEligible: false,
+        whyIneligible: "codex reports billable usage only when a turn completes — no mid-run dollar cap exists to enforce",
+    },
+    openrouter: {
+        incrementalUsage: false,
+        nativeDollarCapFlag: null,
+        usageSemantics: "cumulative-session",
+        tournamentEligible: false,
+        whyIneligible: "openrouter rides the codex harness here and shares its turn-end-only usage reporting",
+    },
+    gemini: {
+        incrementalUsage: false,
+        nativeDollarCapFlag: null,
+        // Stats come from a per-process telemetry service: an invocation's
+        // numbers cover that invocation only (conformance fixture j).
+        usageSemantics: "per-invocation",
+        tournamentEligible: false,
+        whyIneligible: "gemini reports tokens, never dollars — no native cap exists to hold",
+    },
+};
+/**
+ * The fail-closed budget-flag probe (finding 24's amendment): resolve
+ * the EXACT executable that will spawn, read its version, and prove the
+ * flag exists in that binary's own help — presence is a feature check
+ * and nothing more; pricing and semantics stay pinned in pricing.ts.
+ */
+export async function probeBudgetCap(provider, runner) {
+    const flag = MONEY_CAPABILITIES[provider].nativeDollarCapFlag;
+    if (flag === null)
+        return { ok: false, problem: `${provider} has no native dollar cap` };
+    const binary = provider === "claude" ? "claude" : provider;
+    // A feature probe needs no credential (round 2, finding 2): strip them all.
+    const strip = { omitEnv: ALL_CREDENTIAL_ENV };
+    const where = await runner("which", [binary], { timeoutMs: 5_000, ...strip });
+    if (where.code !== 0)
+        return { ok: false, problem: `${binary} is not on PATH` };
+    const executable = where.stdout.trim().split("\n")[0] ?? "";
+    const version = await runner(executable, ["--version"], { timeoutMs: 10_000, ...strip });
+    if (version.code !== 0)
+        return { ok: false, problem: `${executable} did not answer --version` };
+    const help = await runner(executable, ["--help"], { timeoutMs: 10_000, ...strip });
+    if (help.code !== 0 || !help.stdout.includes(flag)) {
+        return { ok: false, problem: `${executable} does not advertise ${flag} — the dollar cap cannot be enforced` };
+    }
+    return { ok: true, executable, version: version.stdout.trim() };
+}
+export function auditOf(provider) {
+    return AUDITS[provider];
+}
+/**
+ * A spec a person or a config row proposed, validated to a complete pair.
+ * openrouter REQUIRES a model: there is no meaningful harness default
+ * across a 300-model catalog.
+ */
+export function validateSpec(spec) {
+    if (!isProviderId(spec.provider)) {
+        return { ok: false, problem: `unknown provider \`${String(spec.provider)}\` — one of ${PROVIDER_IDS.join(", ")}` };
+    }
+    if (!validModelId(spec.model)) {
+        return { ok: false, problem: "a model id is 1–128 characters of letters, digits, and . _ : / - (never leading with a dash)" };
+    }
+    if (spec.provider === "openrouter" && spec.model === null) {
+        return { ok: false, problem: "openrouter needs an explicit model — there is no default across its catalog" };
+    }
+    if (spec.provider === "gemini" && spec.model === null) {
+        return { ok: false, problem: "gemini needs an explicit model — the harness default drifts with its releases" };
+    }
+    return { ok: true };
+}
+/**
+ * Whether this provider reports dollar cost. The routine budget interacts:
+ * a ceiling against an unmeasured provider fails closed by design, so the
+ * approval surfaces refuse the combination outright.
+ */
+export function reportsCost(provider) {
+    return provider === "claude";
+}
+export function inspectionOf(provider) {
+    const adapter = ADAPTERS[provider];
+    return {
+        id: provider,
+        binary: adapter.binary,
+        identityProbe: provider === "codex" || provider === "openrouter" ? ["login", "status"] : null,
+        requiresEnv: provider === "openrouter" ? OPENROUTER_ENV_KEY : null,
+        measuresCost: reportsCost(provider),
+    };
+}