toolroll 0.9.103 → 0.9.105

package/dist/provider.js

@@ -1,23 +1,3 @@
-/**
- * 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 { INTERPRETER_INJECTION_ENV } from "./acp-attest.js";
 import { claudeFenceSettings, codexFenceArgv } from "./agent-fence.js";
 import { claudeSteerHooks } from "./steer-mailbox.js";
@@ -35,45 +15,23 @@ export const PROVIDER_IDS = PROVIDER_ID_VALUES;
 export function isProviderId(value) {
     return providerIdSchema.safeParse(value).success;
 }
-/**
- * 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 { MODEL_ID };
 export function validModelId(model) {
-    // Not a string reads as its text, as the regex always read it (an untyped row's `undefined` passes as "undefined").
     return model === null || modelIdSchema.safeParse(String(model)).success;
 }
 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";
-/**
- * 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",
@@ -85,41 +43,9 @@ const CLAUDE_REVIEW_ISOLATION_ARGV = [
     "--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] },
@@ -131,8 +57,6 @@ const CLAUDE_REVIEW_JSON_SCHEMA = {
                 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"] },
                 },
@@ -154,12 +78,7 @@ const CLAUDE_REVIEW_JSON_SCHEMA = {
                 additionalProperties: false,
             },
         },
-        // The automatic build review's reply (build-review.ts), from its one
-        // schema (src/contracts/review-findings.ts); parseBuildFindings reads it.
         findings: FINDINGS_MODEL_SCHEMA,
-        // 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 },
@@ -172,42 +91,17 @@ const CLAUDE_REVIEW_JSON_SCHEMA = {
     required: ["version"],
     additionalProperties: false,
 };
-/**
- * A build's own setup (plan, build and repair; never a review, which keeps
- * the isolation above). No settings file loads — not the user's, the
- * repository's or the local one — so none of their hooks, plugins or
- * permissions reach the run; Toolroll's one `--settings` (the fence and the
- * steering hook) is all there is. MCP servers come only from `--mcp-config`:
- * the project's named tools, or an explicit empty list. The repository's
- * CLAUDE.md still loads, through `--add-dir` on the workspace. Sign-in is
- * the CLI's own (keychain or ~/.claude), which no setting source governs.
- * `-p` never shows the workspace trust prompt (Claude Code 2.1.290), so a
- * fresh worktree can't wedge a headless run. Checked against 2.1.290 with
- * planted user, project and local hooks and MCP servers: none loaded.
- */
 export const CLAUDE_BUILD_ISOLATION_ARGV = ["--setting-sources", "", "--strict-mcp-config"];
-/**
- * Plugins also ride the environment: a plugin named in CLAUDE_CODE_PLUGIN_DIRS
- * loads its hooks whatever `--setting-sources` says (Claude Code 2.1.290,
- * the provider canary's plugin sentinel). A build's launch sheds every
- * plugin variable of the environment it would inherit.
- */
 const CLAUDE_PLUGIN_ENV = /^CLAUDE_(CODE_\w*PLUGIN|AI_PLUGINS)\w*$/;
 export function claudePluginEnv(env) {
     return Object.keys(env).filter(name => CLAUDE_PLUGIN_ENV.test(name));
 }
 const EMPTY_MCP_CONFIG = '{"mcpServers":{}}';
-/** Claude's own tools that only make sense with a person to wake them. */
 export const HEADLESS_DISALLOWED_TOOLS = ["ScheduleWakeup", "CronCreate", "Monitor"];
 const claudeArgv = (invocation) => [
     "-p",
     ...(invocation.streamInput === true ? ["--input-format", "stream-json"] : [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",
@@ -223,28 +117,22 @@ const claudeArgv = (invocation) => [
     ...(invocation.phase === "review"
         ? [...CLAUDE_REVIEW_ISOLATION_ARGV, "--json-schema", JSON.stringify(CLAUDE_REVIEW_JSON_SCHEMA)]
         : [
-            // Headless (run 2085): a wakeup, cron job or monitor needs a later
-            // turn that a -p process never gets. Denied at the harness too.
             "--disallowedTools", HEADLESS_DISALLOWED_TOOLS.join(","),
             ...(invocation.allowedTools === undefined || invocation.allowedTools.length === 0 ? [] : ["--allowedTools", invocation.allowedTools.join(",")]),
             ...CLAUDE_BUILD_ISOLATION_ARGV,
             ...(invocation.workspace === undefined ? [] : ["--add-dir", invocation.workspace]),
             ...(invocation.toolArgv ?? []),
             ...(invocation.extraMcpServers === undefined ? [] : ["--mcp-config", JSON.stringify({ mcpServers: invocation.extraMcpServers })]),
-            // Strict with nothing named still names its empty list.
             ...((invocation.toolArgv ?? []).includes("--mcp-config") || invocation.extraMcpServers !== undefined ? [] : ["--mcp-config", EMPTY_MCP_CONFIG]),
             ...claudeSettingsArgv(invocation),
             ...(invocation.jsonSchema === undefined ? [] : ["--json-schema", JSON.stringify(invocation.jsonSchema)])
         ]),
 ];
-/** The route's model, or for a build routed with none, the operator's own (never for a review). */
 function modelArgv(flag, invocation) {
     const model = invocation.model ?? (invocation.phase === "review" ? undefined : invocation.inherited?.model);
     return model === undefined ? [] : [flag, model];
 }
-/** What else a no-model build keeps of the operator's setup. */
 const inheritedFrom = (invocation) => invocation.model === null && invocation.phase !== "review" ? invocation.inherited ?? {} : {};
-/** The build's one --settings: no personal memory, plus the fence and steering doorbell. */
 function claudeSettingsArgv(invocation) {
     const denied = [...(invocation.fence ?? []), ...(invocation.fileToolFence ?? [])];
     const readOnly = invocation.fenceGrants?.readOnly ?? [];
@@ -256,19 +144,12 @@ function claudeSettingsArgv(invocation) {
             ...(invocation.steerFolder === undefined ? {} : { hooks: claudeSteerHooks(invocation.steerFolder.dir, invocation.steerFolder.name) }),
         })];
 }
-/** With no settings sources, only `--add-dir` folders' CLAUDE.md load, and only with this set. */
 const claudeEnv = (invocation) => invocation.phase === "review" || invocation.workspace === undefined ? {} : { CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD: "1" };
-/** The flags a build's own setup depends on, by provider. */
 const ISOLATION_FLAGS = {
     claude: ["--setting-sources", "--strict-mcp-config", "--settings", "--add-dir", "--mcp-config"],
     codex: ["--ignore-user-config", "--ignore-rules"],
     openrouter: ["--ignore-user-config", "--ignore-rules"],
 };
-/**
- * Whether a failed launch was an installed CLI too old for a build's own
- * setup: it names one of those flags as unknown. Then nothing ran, and the
- * run says so plainly instead of reading as a failed sign-in or bad work.
- */
 export function isolationUnsupported(provider, stderr) {
     const flags = ISOLATION_FLAGS[provider] ?? [];
     const said = stderr.slice(0, 8192);
@@ -278,14 +159,6 @@ export function isolationUnsupported(provider, stderr) {
     const name = provider === "claude" ? "Claude Code" : "Codex";
     return `The installed ${name} doesn't support ${flag}, which builds need to run without your own hooks, plugins and MCP servers. Update ${name} and try again.`;
 }
-/**
- * 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;
@@ -302,8 +175,6 @@ function claudeEnvelopeOf(result, sessionFromInit, initObserved, initSessionConf
     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"
@@ -323,20 +194,12 @@ function claudeEnvelopeOf(result, sessionFromInit, initObserved, initSessionConf
         costUsd: typeof cost === "number" && cost >= 0 ? cost : null,
         ...(result !== null && result[CLAUDE_COST_UNKNOWN] === true ? { costUnknown: true } : {}),
         usageRaw: result?.usage === undefined ? null : JSON.stringify(result.usage).slice(0, USAGE_JSON_CAP),
-        // The model only when the session's own events name it (never the agent's words); no result, no report.
         modelReported: result === null ? (initModel.conflict ? null : initModel.model) : claudeResultReport(result, initModel).modelReported,
         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") ||
@@ -345,14 +208,6 @@ function claudeEnvelopeOf(result, sessionFromInit, initObserved, initSessionConf
             : 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;
@@ -372,13 +227,10 @@ function claudeParse(stdout) {
         }
         if (event === null || typeof event !== "object")
             continue;
-        // A subagent's object (parent_tool_use_id set) is never the session's envelope, init, result or overflow witness
-        // (stream-scope.ts). The transport's own witness carries no parent and still counts.
         if (!topLevelEvent(event))
             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") {
@@ -399,10 +251,6 @@ function claudeParse(stdout) {
             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 && primaryResultEvent(event))
@@ -421,35 +269,7 @@ function claudeParse(stdout) {
         },
     };
 }
-/**
- * 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.
- */
-/**
- * A Codex build's own setup, the equivalent of Claude's: the operator's
- * config.toml (its MCP servers, model choices, profiles) and execpolicy
- * rules ignored, ChatGPT apps and plugins off (plugins carry their own MCP
- * servers), and hooks off. The gateway gives each launch its own CODEX_HOME
- * linking only the operator's sign-in and sessions (provider-home.ts), so no
- * skills or AGENTS.md of theirs load either. The project's named tools follow
- * as `-c mcp_servers.*` (project-tools.ts).
- */
 export const CODEX_BUILD_ISOLATION_ARGV = [
     "--ignore-user-config",
     "--ignore-rules",
@@ -473,13 +293,6 @@ const CODEX_REVIEW_ISOLATION_ARGV = (resuming) => [
     "-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 [
@@ -490,9 +303,6 @@ const codexArgv = (extra) => (invocation) => {
         ...(invocation.phase === "review" ? [] : CODEX_BUILD_ISOLATION_ARGV),
         ...(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.fenceGrants)
                 : invocation.skipPermissions
@@ -501,20 +311,11 @@ const codexArgv = (extra) => (invocation) => {
         ...modelArgv("-m", invocation),
         ...(inheritedFrom(invocation).effort === undefined ? [] : ["-c", `model_reasoning_effort=${toml(inheritedFrom(invocation).effort)}`]),
         ...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;
@@ -536,8 +337,6 @@ function codexParse(stdout) {
         }
         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) {
@@ -551,8 +350,6 @@ function codexParse(stdout) {
             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)
@@ -569,11 +366,6 @@ function codexParse(stdout) {
             }
         }
         else if (type === "turn.failed") {
-            // RETAIN the structural failure terminal (Codex verify, finding 1):
-            // a turn.failed carries the usage-limit or sign-in 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"];
@@ -584,13 +376,7 @@ function codexParse(stdout) {
             };
         }
     }
-    // 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"
@@ -606,43 +392,15 @@ function codexParse(stdout) {
         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",
@@ -656,8 +414,6 @@ const geminiArgv = (invocation) => [
     ...(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,
@@ -665,15 +421,6 @@ const GEMINI_TIMEOUT_CAP_MS = {
     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;
@@ -737,48 +484,27 @@ function geminiParse(stdout) {
         }
     }
     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 === "")
@@ -787,28 +513,16 @@ export function safeDiagnostic(text) {
         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 = withAcp({
     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"],
-    // An ACP agent signs in its own way; Toolroll holds no key for it, so it sheds every key above.
 }, () => []);
 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();
-/**
- * An ACP agent's retained record (acp-client.ts) read into the gateway's
- * envelope. Its own usage report is never priced: tokens and cost stay null.
- */
 function acpEnvelope(stdout) {
     const read = acpParse(stdout);
     return {
@@ -833,7 +547,6 @@ function acpAdapter(provider) {
         argv: () => [...ACP_AGENTS[provider].argv],
         parse: acpEnvelope,
         defaultRunner: runAcpSession,
-        // Every key Toolroll knows, and whatever would make the pinned interpreter load code beside the checked script.
         extraOmitEnv: [...foreignCredentialEnv(provider), ...INTERPRETER_INJECTION_ENV],
         clampTimeout: (_phase, requested) => requested,
     };
@@ -869,11 +582,6 @@ const ADAPTERS = withAcp({
             `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)}]`,
         ]),
@@ -891,11 +599,6 @@ const ADAPTERS = withAcp({
         clampTimeout: (phase, requested) => Math.min(requested, GEMINI_TIMEOUT_CAP_MS[phase]),
     },
 }, (_agent, provider) => acpAdapter(provider));
-/**
- * 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];
 }
@@ -906,8 +609,6 @@ const AUDITS = withAcp({
         initSignal: "system-init",
         sessionIdentity: "announced",
         terminalContract: "none",
-        // Builds: no settings sources and strict MCP, fresh and resumed alike
-        // (CLAUDE_BUILD_ISOLATION_ARGV). Reviews keep --restricted --safe-mode.
         isolation: { flag: CLAUDE_BUILD_ISOLATION_ARGV.filter(one => one !== "").join(" "), resumeSafe: true, enforced: true },
         configSurface: [
             "Toolroll's own --settings (the fence and steering hook)",
@@ -923,10 +624,6 @@ const AUDITS = withAcp({
         initSignal: "thread.started",
         sessionIdentity: "announced",
         terminalContract: "none",
-        // Builds ignore config.toml and execpolicy rules, with apps, plugins and
-        // hooks off (CODEX_BUILD_ISOLATION_ARGV), in a per-launch CODEX_HOME that
-        // links only the sign-in and sessions (provider-home.ts).
-        // Never --ephemeral: repair resumes sessions.
         isolation: { flag: "--ignore-user-config --ignore-rules", resumeSafe: true, enforced: true },
         configSurface: ["the project's named tools (Settings → Tools)", "repository AGENTS.md", "sign-in and sessions linked from CODEX_HOME (no skills or AGENTS.md)", "your model and reasoning effort, when the route names no model"],
     },
@@ -936,17 +633,11 @@ const AUDITS = withAcp({
         initSignal: "thread.started",
         sessionIdentity: "announced",
         terminalContract: "none",
-        // Codex's build setup, with the model provider pinned by constant -c overrides.
         isolation: { flag: "--ignore-user-config --ignore-rules", resumeSafe: true, enforced: true },
         configSurface: ["the project's named tools (Settings → Tools)", "repository AGENTS.md", `${OPENROUTER_ENV_KEY}`],
     },
     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",
@@ -962,7 +653,6 @@ const AUDITS = withAcp({
         ],
     },
 }, agent => ({
-    // One ACP conversation per build: the prompt's answer is the only success (acp-client.ts), so exit 0 alone is never believed.
     transport: "acp-jsonrpc",
     resume: "none",
     initSignal: "acp-session",
@@ -990,12 +680,9 @@ export const MONEY_CAPABILITIES = withAcp({
     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",
     },
 }, () => ({
-    // ACP carries no dollars Toolroll trusts: an agent's own usage report is kept apart, unpriced.
     incrementalUsage: false,
     nativeDollarCapFlag: null,
     usageSemantics: "per-invocation",
@@ -1003,13 +690,7 @@ export const MONEY_CAPABILITIES = withAcp({
 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) {
-    // A refusal names the field, never the value: a pasted credential must not travel on in a problem.
     const parsed = agentSpecSchema.safeParse({ provider: spec.provider, model: spec.model === null ? null : String(spec.model) });
     if (!parsed.success) {
         const field = parsed.error.issues[0]?.path[0];
@@ -1028,11 +709,6 @@ export function validateSpec(spec) {
     }
     return { ok: true };
 }
-/**
- * Whether this provider reports dollar cost. A schedule's weekly limit 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";
 }