@jini-ai/daemon 0.5.2 → 0.5.4

package/dist/agent-executor.js

@@ -1,3007 +1,10 @@
 /**
- * `AgentExecutor` — the driver `RunLifecycle`'s own module doc names as the
- * missing piece: *"It does not spawn or signal a subprocess... A driver...
- * calls `emit()` for agent/stdout/stderr/error events, observes cancellation
- * via `onCancelRequested`, and calls `finish()` once it knows the real
- * outcome."* This module is that driver — it wires `@jini-ai/agent-runtime`'s
- * registry/launch-resolution/stream-parsers (previously a complete but
- * disconnected library, zero callers anywhere outside its own package) into
- * a real `node:child_process` spawn, feeding both `RunLifecycle.emit()` and
- * this package's own `@jini-ai/protocol` event envelope.
- *
- * ## v1 scope: all 24 registered agent defs
- *
- * `@jini-ai/agent-runtime`'s registry ships 24 built-in defs across four
- * `streamFormat` families. The JSON-stream-parser family — the four
- * `createXStreamHandler`-shaped parsers (`claude-stream-json`,
- * `json-event-stream`, `copilot-stream-json`, `qoder-stream-json`), covering
- * 9 defs (amp, codebuddy, claude, codex, cursor-agent, opencode, mimo,
- * copilot, qoder) — plus all 9 `acp-json-rpc` defs, plus the one `pi-rpc`
- * def (`pi`), are wired here. ACP and pi-rpc each own their own JSON-RPC
- * prompt-delivery protocol, so each takes its own lifecycle branch rather
- * than being treated as a stdout-tail parser; pi-rpc's events arrive through
- * the exact same `{type, ...}` vocabulary `translateAgentRuntimeEvent`
- * already handles for ACP/JSON-stream (confirmed by reading every
- * `mapPiRpcEvent` `send()` call site — no new translation code was needed),
- * so only the driver wiring (spawn → attach → cancel → finish) was new for it.
- *
- * All 5 `streamFormat: 'plain'` defs — grok-build, aider, deepseek, qwen,
- * antigravity — are also driven, per
- * `ADS-memory/reports/proposals/PROP-plain-format-agent-driving-2026-07-21.md`'s
- * recommended "Option B": no structured stream parser at all. By default
- * every raw `child.stdout` chunk is forwarded verbatim as a `text_delta`
- * `'agent'` event, live, as it arrives (see `wireChildLifecycle`'s
- * `streamFormat === 'plain'` branch). Prompt delivery across the 5 is not
- * uniform: qwen and antigravity already fit the pre-existing stdin-only
- * guard; grok-build stages the prompt to a temp file via
- * `preparePromptFileForAgent` (its path threaded into `buildArgs` through a
- * `RuntimeContext`, cleaned up after the child exits on every path,
- * including pre-spawn/spawn-failure ones); aider/deepseek carry the prompt
- * on argv and are guarded pre-spawn by `checkPromptArgvBudget` plus the two
- * Windows CreateProcess command-line-expansion guards
- * (`checkWindowsCmdShimCommandLineBudget`/`checkWindowsDirectExeCommandLineBudget`).
- *
- * ## Antigravity's two extra needs, met declaratively
- *
- * Antigravity was the one def this driver rejected outright, for two reasons
- * the proposal doc (§2c) scoped out to a follow-up: `agy` can print an OAuth
- * sign-in URL to stdout and *still exit 0*, so live streaming leaks it; and
- * its model choice is written into one process-global `settings.json` that
- * `agy` reads on its own startup, so two concurrent runs race on it.
- *
- * Both are now met through **declarative `RuntimeAgentDef` fields this driver
- * reads generically** — `needsAgentLogFile`, `stdoutPolicy`, `runtimeLock` —
- * not a `def.id === 'antigravity'` branch. That mirrors how all 14 of the
- * def's other optional behavior flags (`promptViaFile`, `authProbe`,
- * `capturesSessionIdFromStream`, …) already work, and it is a deliberate
- * divergence from OD's own `server.ts`, which hardcodes `def.id ===
- * 'antigravity'` twice. The three fields are no-ops for the other 23 defs,
- * none of which declares any of them — so nothing else's behavior changed.
- *
- * `run()` still rejects cleanly (never a bare throw) with an
- * `AgentExecutorError` for any def whose `streamFormat` or prompt-delivery
- * shape this driver does not implement — see `isSupportedStreamFormat` and
- * `assessAgentExecutorCompatibility`.
- *
- * ## Invariant
- *
- * `RunLifecycle.start()` already transitions a run to `'running'` before
- * `run()` is ever called. Every *pre-spawn* failure path in `run()` — unknown
- * `agentId`, an unsupported `streamFormat`/prompt-delivery shape, an
- * unresolvable binary, or a spawn error — calls `lifecycle.finish({status:
- * 'failed', resumable: false, code: null, signal: null})` itself before
- * rejecting, so a run can never get stuck `'running'` with no watchdog.
- * `resumable` is unconditionally `false` on these paths — there is no spawned
- * child, hence nothing a classifier could examine (see
- * `FailureClassificationContext`'s own doc).
- *
- * For a run that *did* spawn and then failed, `resumable` is decided by
- * `classifyFailure` (gap 4 — see `ClassifyFailure`'s own doc), an injectable
- * port with no default of its own in this module (`undefined` stays
- * byte-identical to pre-gap-4 behavior — every `'failed'` outcome
- * resumable:false). OD's ~20-vendor-CLI text-matching failure classifier was
- * deliberately never ported (see `run/core/failure-taxonomy.ts`'s own doc and
- * `archived provenance ledger`). The real zero-config classifier lives in `@jini-ai/daemon`'s
- * `run/core/retry.ts` (`resumableFromProcessExit`/`classifyProcessExitFailure`)
- * and is wired in by `@jini-ai/server`'s `createLocalNodeDaemon` — see that
- * package's own archived provenance ledger, and `run/core/retry.ts`'s own doc for the
- * classification policy and its 2026-07-22 merge-time reconciliation against
- * a second, independently-built (and rejected) classifier that once lived in
- * this module.
- */
-import { spawn as nodeSpawn } from 'node:child_process';
-import { promises as fsPromises } from 'node:fs';
-import { homedir, tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { redactSecrets } from '@jini-ai/core';
-import { agentCapabilities, applyAgentLaunchEnv, createClaudeStreamHandler, createCopilotStreamHandler, createJsonEventStreamHandler, createQoderStreamHandler, ensureAgentCapabilities, getAgentDef, resolveAgentLaunch, attachAcpSession, attachPiRpcSession, checkPromptArgvBudget, checkWindowsCmdShimCommandLineBudget, checkWindowsDirectExeCommandLineBudget, prepareAgentLogFile, preparePromptFileForAgent, } from '@jini-ai/agent-runtime';
-import { collectProcessTreePids, createCommandInvocation, listProcessSnapshots, stopProcesses, } from '@jini-ai/platform';
-import { classifyRunCloseStatus } from './close-status.js';
-import { resolveContinuationTransport } from './continuation/continuation-transport.js';
-import { resultContent } from './delegated-tool-bridge.js';
-import { applyImagePromptDelivery } from './image-prompt-delivery.js';
-import { extractResultMedia } from './tool-result-media.js';
-const SUPPORTED_STREAM_FORMATS = [
-    'claude-stream-json',
-    'json-event-stream',
-    'copilot-stream-json',
-    'qoder-stream-json',
-    'acp-json-rpc',
-    'pi-rpc',
-    'plain',
-];
-/**
- * Narrows a `RuntimeAgentDef.streamFormat` string to the supported
- * families.
- * @param value - The def's raw `streamFormat` string.
- * @returns `true` when `value` is one of the JSON-stream-parser, ACP, pi-rpc, or plain formats this driver wires.
- * @complexity O(1) — fixed membership check.
- * @overallScore 100/100
- */
-export function isSupportedStreamFormat(args) {
-    const { value } = args;
-    return SUPPORTED_STREAM_FORMATS.includes(value);
-}
-/**
- * The single source of truth for whether this executor can drive a def.
- *
- * It exists because that knowledge was previously reachable only by *calling* `run()` and inspecting
- * the failure. Anything that lists agents for a user to pick from — a discovery route, an agent
- * picker, a CLI healthcheck — needs the same answer *before* a run exists, and had no way to ask it.
- * The observable symptom was a consumer advertising an agent that its own executor then rejected the
- * instant it was selected.
- *
- * `run()` consumes this rather than re-checking the conditions itself, so the discovery-time answer
- * and the run-time guards cannot disagree. A predicate that merely duplicated the guards would be
- * the same bug in a second location.
- *
- * @param def - The def to assess. Must be the **full** `RuntimeAgentDef`, not a projected
- * `DetectedAgent`: that type omits `maxPromptArgBytes`, one of the three prompt-delivery signals
- * checked here, so the argv-bound defs (`aider`, `deepseek`) would be misjudged as unsupported.
- * @returns A discriminated result — see {@link AgentExecutorCompatibility}. The `reason` text is
- * operator-facing and is what `run()` reports as its `AGENT_RUNTIME_UNSUPPORTED` message.
- * @complexity O(1) — fixed field checks.
- * @overallScore 100/100
- */
-export function assessAgentExecutorCompatibility({ def }) {
-    const format = { value: def.streamFormat };
-    if (!isSupportedStreamFormat(format)) {
-        return {
-            supported: false,
-            reason: `AgentExecutor: agent "${def.id}" has streamFormat "${format.value}", which is not implemented in v1 — only ${SUPPORTED_STREAM_FORMATS.join(', ')} are supported`,
-        };
-    }
-    const streamFormat = format.value;
-    if (streamFormat !== 'acp-json-rpc' &&
-        def.promptViaStdin !== true &&
-        def.promptViaFile !== true &&
-        typeof def.maxPromptArgBytes !== 'number') {
-        return {
-            supported: false,
-            reason: `AgentExecutor: agent "${def.id}" does not deliver its prompt via stdin, a staged prompt file, or a byte-budgeted argv — v1 has no other prompt delivery path`,
-        };
-    }
-    return { supported: true, streamFormat };
-}
-/**
- * Whether `run()` can actually drive this def — the discovery-time counterpart to the guards inside
- * `run()`, so a consumer never offers a user an agent that fails the moment it is selected.
- *
- * @param def - The full `RuntimeAgentDef`; see {@link assessAgentExecutorCompatibility} for why a
- * projected `DetectedAgent` is not sufficient.
- * @returns `true` when this executor would attempt the run.
- * @complexity O(1).
- * @overallScore 100/100
- */
-export function isAgentExecutorSupported({ def }) {
-    return assessAgentExecutorCompatibility({ def: def }).supported;
-}
-/**
- * Selects and constructs the real stream-parser handler for a supported
- * `streamFormat`. `json-event-stream` additionally dispatches on
- * `def.eventParser` (the parser's own internal `kind` switch — e.g.
- * `'codex'`, `'cursor-agent'`, `'opencode'`; `mimo` shares `'opencode'`'s
- * `kind`); an unrecognized/absent `eventParser` degrades to that parser's
- * own `{type:'raw', line}` fallback rather than throwing, matching the
- * parser's own documented behavior. Never called for `streamFormat:
- * 'plain'` — `wireChildLifecycle` handles that format inline with no
- * parser at all (see `ChildDrivenStreamFormat`'s doc).
- * @param def - The resolved agent def (only `.eventParser` is read beyond `streamFormat`).
- * @param streamFormat - `def.streamFormat`, already narrowed by {@link isSupportedStreamFormat}.
- * @param onEvent - Sink the parser calls once per parsed (or malformed-raw) event.
- * @returns A `{feed, flush}` handle for the chosen parser.
- * @complexity O(1) dispatch; the returned handler's own per-chunk cost is the parser's.
- * @overallScore 100/100
- */
-function createStreamHandlerForDef(def, streamFormat, onEvent) {
-    switch (streamFormat) {
-        case 'claude-stream-json':
-            return createClaudeStreamHandler({ onEvent: onEvent });
-        case 'copilot-stream-json':
-            return createCopilotStreamHandler({ onEvent: onEvent });
-        case 'qoder-stream-json':
-            return createQoderStreamHandler({ onEvent: onEvent });
-        case 'json-event-stream':
-            return createJsonEventStreamHandler({ kind: def.eventParser ?? '', onEvent: onEvent });
-    }
-}
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function asString(value, fallback = '') {
-    return typeof value === 'string' ? value : fallback;
-}
-function asOptionalString(value) {
-    return typeof value === 'string' ? value : undefined;
-}
-function asOptionalNumber(value) {
-    return typeof value === 'number' ? value : undefined;
-}
-/**
- * Narrows a parsed `usage` event's `usage` sub-object (`{input_tokens?, output_tokens?}`) — the one
- * piece of {@link translateUsagePayload} with real nested branching (an optional container holding
- * two optional numeric fields), extracted so that function reads as a flat field-by-field mapping.
- * @param rawUsage - `rawEvent.usage` once already narrowed to a record, or `undefined` when absent/malformed.
- * @returns `undefined` when neither token count is present — matching `translateUsagePayload`'s
- * original "omit the whole `usage` field rather than emit an empty object" behavior.
- * @complexity O(1).
- */
-export function extractUsageTokens({ rawUsage }) {
-    if (!rawUsage)
-        return undefined;
-    const inputTokens = asOptionalNumber(rawUsage.input_tokens);
-    const outputTokens = asOptionalNumber(rawUsage.output_tokens);
-    if (inputTokens === undefined && outputTokens === undefined)
-        return undefined;
-    return {
-        ...(inputTokens !== undefined ? { input_tokens: inputTokens } : {}),
-        ...(outputTokens !== undefined ? { output_tokens: outputTokens } : {}),
-    };
-}
-/**
- * Narrows one parsed `usage` event's loosely-typed fields into
- * `RunAgentPayload`'s `usage` variant. The 4 source parsers attach extra
- * fields this narrow payload has no room for — `thought_tokens`,
- * `cached_read_tokens`/`cached_write_tokens` (opencode/gemini/codex),
- * `modelUsage`/`stopReason`/`isError` (qoder), a top-level `stopReason`
- * (claude/copilot) — all intentionally dropped here, not carried through.
- * @param rawEvent - The raw `{type:'usage', ...}` record from a stream parser.
- * @returns The narrowed `RunAgentPayload` `usage` variant.
- * @complexity O(1).
- * @overallScore 100/100
- */
-function translateUsagePayload(rawEvent) {
-    const rawUsage = isRecord(rawEvent.usage) ? rawEvent.usage : undefined;
-    const usage = extractUsageTokens({ rawUsage: rawUsage });
-    const costUsd = asOptionalNumber(rawEvent.costUsd);
-    const durationMs = asOptionalNumber(rawEvent.durationMs);
-    return {
-        type: 'usage',
-        ...(usage !== undefined ? { usage } : {}),
-        ...(costUsd !== undefined ? { costUsd } : {}),
-        ...(durationMs !== undefined ? { durationMs } : {}),
-    };
-}
-export function translateStatusEvent({ rawEvent }) {
-    const model = asOptionalString(rawEvent.model);
-    const ttftMs = asOptionalNumber(rawEvent.ttftMs);
-    const detail = asOptionalString(rawEvent.detail);
-    const sessionId = asOptionalString(rawEvent.sessionId);
-    return {
-        kind: 'agent',
-        payload: {
-            type: 'status',
-            label: asString(rawEvent.label, 'unknown'),
-            ...(model !== undefined ? { model } : {}),
-            ...(ttftMs !== undefined ? { ttftMs } : {}),
-            ...(detail !== undefined ? { detail } : {}),
-        },
-        ...(sessionId !== undefined ? { sessionId } : {}),
-    };
-}
-function translateTextDeltaEvent(rawEvent) {
-    return { kind: 'agent', payload: { type: 'text_delta', delta: asString(rawEvent.delta) } };
-}
-function translateThinkingStartEvent() {
-    return { kind: 'agent', payload: { type: 'thinking_start' } };
-}
-function translateThinkingDeltaEvent(rawEvent) {
-    return { kind: 'agent', payload: { type: 'thinking_delta', delta: asString(rawEvent.delta) } };
-}
-function translateToolUseEvent(rawEvent) {
-    return {
-        kind: 'agent',
-        payload: {
-            type: 'tool_use',
-            id: asString(rawEvent.id),
-            name: asString(rawEvent.name),
-            input: rawEvent.input ?? null,
-        },
-    };
-}
-function translateToolInputDeltaEvent(rawEvent) {
-    return {
-        kind: 'agent',
-        payload: {
-            type: 'tool_input_delta',
-            id: asString(rawEvent.id),
-            name: asString(rawEvent.name),
-            delta: asString(rawEvent.delta),
-        },
-    };
-}
-export function translateToolResultEvent({ rawEvent }) {
-    const isError = typeof rawEvent.isError === 'boolean' ? rawEvent.isError : undefined;
-    return {
-        kind: 'agent',
-        payload: {
-            type: 'tool_result',
-            toolUseId: asString(rawEvent.toolUseId),
-            content: asString(rawEvent.content),
-            ...(isError !== undefined ? { isError } : {}),
-        },
-    };
-}
-function translateUsageEvent(rawEvent) {
-    return { kind: 'agent', payload: translateUsagePayload(rawEvent) };
-}
-function translateRawEvent(rawEvent) {
-    return { kind: 'agent', payload: { type: 'raw', line: asString(rawEvent.line) } };
-}
-export function translateErrorEvent({ rawEvent }) {
-    const code = asOptionalString(rawEvent.code);
-    const message = asString(rawEvent.message, 'Unknown agent error');
-    return {
-        kind: 'error',
-        payload: { message, ...(code !== undefined ? { error: { code, message } } : {}) },
-    };
-}
-export function translateTurnEndEvent({ rawEvent }) {
-    // Claude-specific per-turn boundary. Not forwarded as an 'agent'
-    // event (no RunAgentPayload variant represents it) — run() reacts to
-    // it directly to close stdin (or, for gap 3, decide whether to inject
-    // a tool result and keep it open instead). See module doc.
-    const stopReason = asOptionalString(rawEvent.stopReason);
-    return { kind: 'turn-end', ...(stopReason !== undefined ? { stopReason } : {}) };
-}
-/**
- * One entry per `rawEvent.type` this driver understands, each producing the same
- * {@link AgentRuntimeEventTranslation} `translateAgentRuntimeEvent` used to return from an inline
- * `switch` — replaced with this table (refactor-patterns' preferred fix for a long switch over an
- * event-kind discriminant) so each case's own mapping is independently readable and testable, and so
- * `translateAgentRuntimeEvent` itself is just a lookup plus the two upfront guards.
- */
-const EVENT_TYPE_TRANSLATORS = {
-    status: rawEvent => translateStatusEvent({ rawEvent }),
-    text_delta: translateTextDeltaEvent,
-    thinking_start: translateThinkingStartEvent,
-    thinking_delta: translateThinkingDeltaEvent,
-    tool_use: translateToolUseEvent,
-    tool_input_delta: translateToolInputDeltaEvent,
-    tool_result: rawEvent => translateToolResultEvent({ rawEvent }),
-    usage: translateUsageEvent,
-    raw: translateRawEvent,
-    error: rawEvent => translateErrorEvent({ rawEvent }),
-    turn_end: rawEvent => translateTurnEndEvent({ rawEvent }),
-};
-/**
- * Narrows one parser-emitted `{type, ...}` record into this engine's
- * `RunAgentPayload` union (or the `error`/`turn-end`/`ignored` routing
- * `run()` special-cases). Pure — no I/O, no closure state — so every
- * variant each of the 4 supported parsers can produce is directly
- * assertable in isolation.
- *
- * Defensive by construction: several real parser emissions carry fields
- * looser than `RunAgentPayload`'s types promise (e.g. copilot's
- * `tool.execution_start` emits `id: data.toolCallId ?? null` — a literal
- * `null`, not the `string` `RunAgentPayload['tool_use']['id']` demands).
- * Every field read here is defensively coerced (`asString`/
- * `asOptionalString`/`asOptionalNumber`) rather than trusted, so a
- * malformed or null field degrades to a safe default instead of
- * propagating `null`/`undefined` into a field typed as required, or
- * throwing.
- *
- * @param rawEvent - One event as delivered to a stream parser's `onEvent` callback.
- * @returns The routing + payload this event maps to.
- * @complexity O(1) — one table lookup, no iteration.
- * @overallScore 100/100
- */
-export function translateAgentRuntimeEvent({ rawEvent }) {
-    if (!isRecord(rawEvent) || typeof rawEvent.type !== 'string') {
-        return { kind: 'ignored' };
-    }
-    const translator = EVENT_TYPE_TRANSLATORS[rawEvent.type];
-    return translator ? translator(rawEvent) : { kind: 'ignored' };
-}
-/** Thrown by `AgentExecutor.run()` on every failure path — never a bare `Error`, so callers can branch on `.code` instead of parsing `.message`. */
-export class AgentExecutorError extends Error {
-    code;
-    constructor({ code, message }) {
-        super(message);
-        this.name = 'AgentExecutorError';
-        this.code = code;
-    }
-}
-function errorMessage(err) {
-    return err instanceof Error ? err.message : String(err);
-}
-/**
- * Drops `undefined` values so `NodeJS.ProcessEnv` (whose values are
- * `string | undefined`) can feed `resolveAgentLaunch`'s
- * `Record<string, string>` parameter.
- * @param env - The source environment (the caller-supplied `input.env` escape hatch — the
- * default path builds its env via `buildAgentEnv` instead, never this function on `process.env`).
- * @returns A new object containing only the string-valued entries.
- * @complexity O(n) in the number of env entries.
- * @overallScore 100/100
- */
-function toStringEnvRecord(env) {
-    const result = {};
-    for (const [key, value] of Object.entries(env)) {
-        if (typeof value === 'string')
-            result[key] = value;
-    }
-    return result;
-}
-/**
- * Fixed baseline of host environment variables every spawned agent subprocess may see by
- * default — resolved from the host's env one name at a time, never derived programmatically
- * from `process.env` as a bag, so this can't silently widen. SEC-001's deny-by-default fix; see
- * `AgentExecutorRunInput.env`'s doc for the full threat model.
- */
-const BASELINE_AGENT_ENV_KEYS = [
-    'PATH', 'HOME', 'USERPROFILE', 'TMPDIR', 'TEMP', 'TMP', 'SHELL',
-    'LANG', 'LC_ALL', 'LC_CTYPE',
-    // `USER` is required for a spawned `claude` CLI to find its own login/credential state — with
-    // it omitted (even though `HOME` is present), `claude` fails fast with "Not logged in · Please
-    // run /login" despite real credentials existing on disk/keychain. Confirmed by bisection against
-    // a real authenticated `claude` install: `BASELINE_AGENT_ENV_KEYS` alone fails, adding back every
-    // `CLAUDE_CODE_*`/`CLAUDECODE` var still fails, `LOGNAME`/`SSH_AUTH_SOCK` alone still fail, but
-    // `USER` alone flips it to success. Login lookup requires the user identity
-    // as well as the home directory.
-    'USER',
-    'SystemRoot', 'windir', 'ComSpec', 'PATHEXT', // Windows-only; harmless no-ops elsewhere
-];
-/**
- * Deny-by-default agent subprocess environment: `BASELINE_AGENT_ENV_KEYS` resolved from
- * `hostEnv`, plus this run's explicitly-delegated credential(s) — never a passthrough of
- * `hostEnv` itself. Only reached when the caller omits `AgentExecutorRunInput.env`; supplying
- * `env` bypasses this function entirely (see its call site).
- */
-function buildAgentEnv(hostEnv, credentialEnv) {
-    const result = {};
-    for (const key of BASELINE_AGENT_ENV_KEYS) {
-        const value = hostEnv[key];
-        if (typeof value === 'string')
-            result[key] = value;
-    }
-    for (const [key, value] of Object.entries(credentialEnv ?? {})) {
-        result[key] = value;
-    }
-    return result;
-}
-/**
- * Resolves once `child` emits `'spawn'`, or rejects on `'error'`. Replicates
- * `@jini-ai/platform`'s own internal (non-exported) `waitForChildSpawn` race
- * idiom inline — see that module's `spawnLoggedProcess`/`spawnBackgroundProcess`.
- * @param child - The just-spawned `ChildProcess` to race.
- * @returns A promise settling on the first of `'spawn'`/`'error'` to fire.
- * @complexity O(1) — two one-time listener registrations.
- * @overallScore 100/100
- */
-function waitForSpawnOrError(child) {
-    return new Promise((resolve, reject) => {
-        child.once('error', reject);
-        child.once('spawn', resolve);
-    });
-}
-/**
- * Enumerates `child`'s full descendant process tree and stops it (SIGTERM →
- * SIGKILL escalation, via the injected `stopProcesses` port).
- * @param deps - The process-snapshot/tree-collection/stop ports (real `@jini-ai/platform` implementations by default — see {@link CreateAgentExecutorOptions}).
- * @param child - The child whose descendant tree should be terminated.
- * @returns Resolves once escalation completes (or immediately, as a no-op, if `child.pid` was never assigned — spawn never actually started).
- * @complexity O(p) in the number of live OS processes (`listProcessSnapshots`'s own cost) plus O(1) escalation rounds.
- * @overallScore 100/100
- */
-async function terminateChildTree(deps, child) {
-    if (child.pid == null)
-        return;
-    const processes = await deps.listProcessSnapshots();
-    const pids = deps.collectProcessTreePids({ processes, rootPids: [child.pid] });
-    await deps.stopProcesses({ pids });
-}
-/** Default sink when a host does not supply `onCleanupFailure`: still observable, never silent. Redacted per SEC-007 (a spawn/permission error can embed paths/host detail). */
-function defaultCleanupFailureSink(context) {
-    // eslint-disable-next-line no-console
-    console.error(`[@jini-ai/daemon] agent-executor: process-tree cleanup failed for run "${context.runId}" (${context.phase}, pid=${context.pid})`, redactSecrets({ input: errorMessage(context.error) }));
-}
-/**
- * Reports a contained post-close failure through the host's sink, absorbing a throwing sink.
- *
- * A diagnostic sink is host code too, and the whole point of the two callers below is that nothing
- * between `'close'` and `finish()` can strand the run — a sink that throws must not reintroduce
- * exactly that. Same reasoning `run-lifecycle.ts`'s `handleInactivityTimeout` already applies to its
- * own `onInternalError`.
- */
-function reportPostCloseFailure(onCleanupFailure, context) {
-    try {
-        onCleanupFailure(context);
-    }
-    catch {
-        // Nothing further can be done from here, and the terminal transition below still must happen.
-    }
-}
-/**
- * Removes this run's staged files, reporting rather than propagating a failure.
- *
- * Unguarded, a rejecting cleanup (EBUSY, a temp directory yanked out from under the daemon, a host
- * stager bug) escaped the `void (async () => …)()` wrapper in each close handler and took `finish()`
- * with it: the child was already gone, yet the run stayed `'running'` forever — unfinishable and
- * unresumable — and the rejection surfaced only as an unhandled promise. A leaked temp file is a real
- * problem, but it is strictly smaller than a permanently stranded run, and reporting it keeps it
- * visible.
- */
-async function cleanupStagedFilesSafely(ctx) {
-    try {
-        await ctx.cleanupStagedFiles();
-    }
-    catch (error) {
-        reportPostCloseFailure(ctx.onCleanupFailure, {
-            runId: ctx.runId,
-            phase: 'staged-file-cleanup',
-            pid: ctx.child.pid,
-            error,
-        });
-    }
-}
-/**
- * Resolves `finish()`'s `resumable` flag from the host's classifier, falling back to `false` when the
- * classifier itself rejects.
- *
- * `classifyFailure` is host-supplied and may do real work (a keystore read, an HTTP call), so it can
- * fail for reasons unrelated to this run. `false` is the right fallback: it is already the answer for
- * every run with no classifier configured at all, so an unavailable classifier degrades to the
- * documented default rather than losing the run.
- */
-async function classifyFailureSafely(ctx, classifyFailure, context) {
-    try {
-        return await classifyFailure(context);
-    }
-    catch (error) {
-        reportPostCloseFailure(ctx.onCleanupFailure, {
-            runId: ctx.runId,
-            phase: 'failure-classification',
-            pid: ctx.child.pid,
-            error,
-        });
-        return false;
-    }
-}
-/**
- * Fire-and-forget-safe wrapper around {@link terminateChildTree} for the cancellation paths
- * (a synchronous `onCancelRequested` listener, an ACP attach-failure catch) that observed this
- * promise with a bare `void` — silently swallowing any `listProcessSnapshots`/`stopProcesses`
- * rejection (e.g. EPERM — see `packages/platform/src/__tests__/process.test.ts`) and letting it
- * become an unhandled rejection, with descendants possibly still running and no diagnostic at
- * all (SEC-007). This never rejects: a tree-stop failure is reported through `onCleanupFailure`
- * (redacted) and followed by a best-effort direct kill of `child` itself, since the immediate
- * child is still worth trying even when tree enumeration/escalation failed.
- */
-function terminateChildTreeBestEffort(deps, child, runId, phase, onCleanupFailure) {
-    return terminateChildTree(deps, child).catch((error) => {
-        // `terminateChildTree` only reaches a rejecting call (rather than its own early return) once
-        // its own `child.pid == null` guard has already passed, and a real ChildProcess's `pid` is
-        // never unset after being assigned — so `child.pid` is provably a number here. The non-null
-        // assertion documents that invariant instead of a `?? null` fallback that could never
-        // actually be exercised (same pattern as `pi-rpc/session.ts`'s `resolveSessionPathChangedSince`).
-        onCleanupFailure({ runId, phase, pid: child.pid, error });
-        try {
-            if (child.pid != null && !child.killed)
-                child.kill('SIGKILL');
-        }
-        catch {
-            // Best-effort only — nothing further can be done from here.
-        }
-    });
-}
-/**
- * Gap 1's byte-journal record for bytes the host sent to the child's stdin — always `trust:
- * 'trusted'`, since these are bytes this driver itself composed and wrote, not agent output. See
- * `packages/daemon/src/continuation/journal.ts`'s module doc.
- */
-function sentJournalEntry(content) {
-    return { content, provenance: { source: 'host', channel: 'stdin' }, trust: 'trusted' };
-}
-/**
- * Gap 1's byte-journal record for bytes a child agent process produced on `channel` — always
- * `trust: 'untrusted'`, since this is attacker-influenceable agent output the kernel does not
- * control (see `@jini-ai/protocol`'s `JournalEntry` doc on why `trust` exists).
- */
-function receivedJournalEntry(channel, content) {
-    return { content, provenance: { source: 'agent', channel }, trust: 'untrusted' };
-}
-const JINI_MCP_SERVER_KEY = 'jini';
-/** The run-error code a run gets when its CLI reports the injected `jini` bridge as anything but connected. */
-export const MCP_BRIDGE_UNAVAILABLE = 'MCP_BRIDGE_UNAVAILABLE';
-/**
- * Judges a CLI's startup report of the injected bridge. Returns the bridge's status (`'missing'`
- * when the list omits it) when it is not `'connected'`, and `undefined` when it is connected or
- * when `rawEvent` is not an init status carrying an MCP server list (nothing to judge).
- *
- * `'pending'` counts as a failure on purpose: the CLI decides which MCP tools a session has at
- * startup, so a bridge that is not connected by then never joins this run.
- * @param rawEvent - One parsed stream event, as `@jini-ai/agent-runtime`'s parser emits it.
- * @complexity O(n) in the number of reported servers.
- */
-export function unavailableJiniBridgeStatus({ rawEvent }) {
-    if (!isRecord(rawEvent) || rawEvent.type !== 'status' || rawEvent.label !== 'initializing')
-        return undefined;
-    if (!Array.isArray(rawEvent.mcpServers))
-        return undefined;
-    const bridge = rawEvent.mcpServers.find((server) => isRecord(server) && server.name === JINI_MCP_SERVER_KEY);
-    const status = isRecord(bridge) ? String(bridge.status) : 'missing';
-    return status === 'connected' ? undefined : status;
-}
-/** The user-readable reason a run stopped because its bridge did not connect. */
-function bridgeUnavailableMessage(status) {
-    return `The assistant's tools did not load (MCP bridge "${JINI_MCP_SERVER_KEY}" status: ${status}). The run was stopped instead of continuing without them.`;
-}
-/**
- * Builds this run's `mcpServers.jini` entry — pure and synchronous, so every field mapping is
- * directly assertable without touching the filesystem. The credential arrives already resolved:
- * `McpJsonInjectionOptions.credential` is a possibly-async per-run resolver, and awaiting it is
- * `writeMcpJsonForRun`'s job, which keeps the effect out of this function.
- *
- * @param runId - The run this entry scopes its child to.
- * @param options - `command`/`args`/`daemonUrl`/`env` from the host's injection options.
- * @param credential - The already-resolved bearer token, or `undefined` to omit `JINI_DAEMON_TOKEN`
- * entirely. Omitting produces byte-identical output to before this parameter existed.
- * @complexity O(1).
- * @overallScore 100/100
- */
-export function buildMcpJsonServerEntry({ runId, options }, { credential } = {}) {
-    const hostEnv = Object.entries(options.env ?? {}).filter(([key]) => !key.startsWith('JINI_'));
-    return {
-        command: options.command,
-        args: options.args !== undefined ? [...options.args] : [],
-        env: {
-            ...Object.fromEntries(hostEnv),
-            JINI_RUN_ID: runId,
-            JINI_DAEMON_URL: options.daemonUrl,
-            ...(credential !== undefined ? { JINI_DAEMON_TOKEN: credential } : {}),
-        },
-    };
-}
-/**
- * Merges {@link JINI_MCP_SERVER_KEY} into an existing `.mcp.json`'s `mcpServers` map, preserving
- * every other key and every other registered server untouched. A missing (`existingRaw ===
- * undefined`), empty, or unparseable-as-a-JSON-object existing file all degrade to "start from an
- * empty document" rather than throwing — an unparseable project `.mcp.json` is a pre-existing
- * problem this driver did not create and cannot safely repair, so it is deliberately overwritten
- * with a fresh, valid file containing just this run's bridge entry rather than left broken or
- * left blocking the run. Pure — no I/O — so every branch is directly assertable.
- * @complexity O(1) plus `JSON.parse`/`JSON.stringify`'s own cost on a small config file.
- * @overallScore 100/100
- */
-export function mergeMcpJsonContent({ existingRaw, serverEntry }) {
-    let doc = {};
-    if (existingRaw !== undefined) {
-        try {
-            const parsed = JSON.parse(existingRaw);
-            if (isRecord(parsed))
-                doc = parsed;
-        }
-        catch {
-            doc = {};
-        }
-    }
-    const existingServers = isRecord(doc.mcpServers) ? doc.mcpServers : {};
-    const mcpServers = { ...existingServers, [JINI_MCP_SERVER_KEY]: serverEntry };
-    return `${JSON.stringify({ ...doc, mcpServers }, null, 2)}\n`;
-}
-/**
- * Mechanism 2 of 5 — `'acp-merge'`. Re-shapes the same bridge entry into the `mcpServers` element
- * an ACP `session/new` call carries, for the 9 ACP-native defs declaring this strategy (amr, devin,
- * hermes, kilo, kimi, kiro, reasonix, trae-cli, vibe). Pure.
- *
- * `env` is emitted as a plain object on purpose: `@jini-ai/agent-runtime`'s
- * `buildAcpSessionNewParams` already normalises a plain-object `env` into either the
- * `[{name, value}]` array form or the `{"KEY": "val"}` map form according to each def's own
- * `acpMcpEnvFormat`, so the per-vendor wire-shape difference stays in the one place that already
- * owns it rather than being re-decided here.
- *
- * **The credential travels in `env`, never in `args`.** An ACP agent spawns this server itself and
- * applies `env` to that child's environment; a token in `args` would land in the child's process
- * arguments, readable by any other local user via `ps`. Same rule as the `.mcp.json` path.
- *
- * @param entry - The shared bridge entry from {@link buildMcpJsonServerEntry}.
- * @returns A single-element list — this driver contributes exactly its own bridge server and never
- * removes or rewrites servers a def or host added by other means.
- * @complexity O(1).
- * @overallScore 100/100
- */
-export function buildAcpMcpBridgeServers({ entry }) {
-    return [
-        {
-            type: 'stdio',
-            name: JINI_MCP_SERVER_KEY,
-            command: entry.command,
-            args: [...entry.args],
-            env: { ...entry.env },
-        },
-    ];
-}
-/**
- * Mechanism 3+4 of 5 — the spawn-env-content strategies. One map, not two code paths: OpenCode and
- * MiMo consume byte-identical JSON (MiMo's def doc: "the same JSON schema as OpenCode's `mcp`
- * config ... following the same structure as `OPENCODE_CONFIG_CONTENT`"), and differ only in which
- * env var carries it. Adding a third such CLI is a row here, not a new serializer.
- */
-const ENV_CONTENT_VAR_BY_STRATEGY = {
-    'opencode-env-content': 'OPENCODE_CONFIG_CONTENT',
-    'mimo-env-content': 'MIMOCODE_CONFIG_CONTENT',
-};
-/**
- * Serialises the bridge entry into the OpenCode-schema config JSON that `OPENCODE_CONFIG_CONTENT`
- * / `MIMOCODE_CONFIG_CONTENT` carries, merging into whatever the host already put in that variable
- * rather than replacing it — the same "merge, never clobber" discipline
- * {@link mergeMcpJsonContent} applies to `.mcp.json`, and for the same reason: a host may already
- * be handing the CLI the *user's* configured MCP servers through this exact variable, and
- * overwriting it would silently delete them.
- *
- * A missing, empty, or unparseable-as-a-JSON-object existing value degrades to "start from an empty
- * document". Overwriting an unparseable value is deliberate and matches `mergeMcpJsonContent`: this
- * driver did not create it, cannot safely repair it, and must not block the run on it.
- *
- * Emitted per server: `{type: 'local', command: [<command>, ...<args>], environment: {...},
- * enabled: true}` — the shape `@jini-ai/mcp`'s own `buildOpenCodeMcpConfigContent` emits for a
- * stdio server, so both producers stay schema-compatible.
- *
- * **The credential lands in `environment`, i.e. the MCP child's env — never in `command`.** OpenCode
- * spawns the bridge from `command`, so a token placed there would be visible in `ps` output to
- * every other local user. This is the same constraint that keeps `JINI_DAEMON_TOKEN` out of argv on
- * the `.mcp.json` and ACP paths.
- *
- * @param existingRaw - Whatever the spawn env already held for this variable, or `undefined`.
- * @param entry - The shared bridge entry from {@link buildMcpJsonServerEntry}.
- * @returns The full JSON string to set as the env var's value.
- * @complexity O(1) plus `JSON.parse`/`JSON.stringify` over a small config document.
- * @overallScore 100/100
- */
-export function mergeEnvContentMcpConfig({ existingRaw, entry }) {
-    let doc = {};
-    if (existingRaw !== undefined && existingRaw.length > 0) {
-        try {
-            const parsed = JSON.parse(existingRaw);
-            if (isRecord(parsed))
-                doc = parsed;
-        }
-        catch {
-            doc = {};
-        }
-    }
-    const existingMcp = isRecord(doc.mcp) ? doc.mcp : {};
-    const mcp = {
-        ...existingMcp,
-        [JINI_MCP_SERVER_KEY]: {
-            type: 'local',
-            command: [entry.command, ...entry.args],
-            environment: { ...entry.env },
-            enabled: true,
-        },
-    };
-    return JSON.stringify({ ...doc, mcp });
-}
-/**
- * Merges a staged system-prompt overlay file's path into the `instructions` array of the same
- * OpenCode-schema config document {@link mergeEnvContentMcpConfig} writes `mcp` into — for a
- * `systemPromptDelivery: { strategy: 'config-instructions-file' }` def (`opencode` today).
- *
- * Confirmed live (2026-09-01, opencode-cli 1.17.10), not inferred from docs alone:
- *   1. `instructions` is honored — a run configured with it visibly followed the file's directive
- *      (a required exact-token prefix), while an identical run without it did not.
- *   2. It appends, never replaces: the same run that followed the custom instruction ALSO still
- *      answered correctly using opencode's own baked-in environment-context system prompt (asked
- *      for its cwd, with nothing about cwd anywhere in the custom instructions file) — proof
- *      opencode's own defaults survive alongside a custom `instructions` entry, not just proof the
- *      file was read at all.
- *   3. Adding this key alongside `mcp` in the same `OPENCODE_CONFIG_CONTENT` document disturbs
- *      neither: in one combined run, the MCP bridge still got its connection attempt (logged
- *      `key=jini type=local`) AND the custom instruction was still followed — same as running each
- *      key alone.
- *   4. `instructions` is re-read fresh from the env on every spawn, including a `-s <id>`-resumed
- *      turn (proved by swapping in a second instructions file between two turns of one resumed
- *      session and seeing the second turn immediately reflect it while still recalling
- *      conversation memory from turn one) — so this mechanism is safe to redeliver every turn like
- *      `'append-flag'`/`'env-var'`, exempt from the prompt-prefix fallback's create-only gating
- *      (see {@link resolveSystemPromptOverlayDelivery}'s doc): nothing here is ever baked into
- *      opencode's own persisted session state the way re-injecting fallback prompt text would be.
- *
- * @param existingRaw - Whatever the spawn env already held for this variable (already possibly
- * carrying `mcp`, if `mergeEnvContentMcpConfig` ran first on the same value — order between the two
- * doesn't matter, each only touches its own top-level key), or `undefined`.
- * @param instructionsFilePath - The staged overlay file's absolute path (see
- * {@link prepareSystemPromptOverlayFileIfNeeded}).
- * @returns The full JSON string to set as the env var's value. Appends to, never clobbers, any
- * `instructions` entries already present — the same "merge, never clobber" discipline
- * {@link mergeEnvContentMcpConfig} applies to `mcp`, in case a host is already using this same
- * config-content variable to carry the operator's own instruction files.
- * @complexity O(1) plus `JSON.parse`/`JSON.stringify` over a small config document.
- * @overallScore 100/100
- */
-export function mergeEnvContentInstructions({ existingRaw, instructionsFilePath }) {
-    let doc = {};
-    if (existingRaw !== undefined && existingRaw.length > 0) {
-        try {
-            const parsed = JSON.parse(existingRaw);
-            if (isRecord(parsed))
-                doc = parsed;
-        }
-        catch {
-            doc = {};
-        }
-    }
-    const existingInstructions = Array.isArray(doc.instructions)
-        ? doc.instructions.filter((entry) => typeof entry === 'string')
-        : [];
-    return JSON.stringify({ ...doc, instructions: [...existingInstructions, instructionsFilePath] });
-}
-/**
- * TOML basic-string escaping for the narrow value shapes {@link buildCodexMcpServerToml} emits (a
- * command name, an argv token, an env var value — never multi-line or control-character-heavy
- * text). Escapes exactly what TOML's basic-string grammar requires: backslash first (so it is not
- * re-escaped by a later replacement), then the quote delimiter, then the three whitespace control
- * characters a real command/argv/env value could plausibly contain.
- *
- * A hand-rolled minimal escaper rather than a TOML dependency — this mechanism never needs to
- * *parse* TOML (the real install's existing `config.toml` is appended after, never rewritten — see
- * {@link buildCodexHomeConfigToml}), so pulling in a full TOML library for one serialization shape
- * would be substantially more surface than the problem needs. Checked against the repo's existing
- * dependency graph first — no package here already depends on a TOML library.
- * @param value - The raw string to embed inside TOML `"..."` delimiters.
- * @returns The escaped text, WITHOUT the surrounding quotes — {@link tomlString} adds those.
- * @complexity O(n) in the string's length.
- */
-function escapeTomlBasicString(value) {
-    return value
-        .replace(/\\/g, '\\\\')
-        .replace(/"/g, '\\"')
-        .replace(/\n/g, '\\n')
-        .replace(/\r/g, '\\r')
-        .replace(/\t/g, '\\t');
-}
-/** Wraps {@link escapeTomlBasicString}'s output in the TOML basic-string delimiters. */
-function tomlString(value) {
-    return `"${escapeTomlBasicString(value)}"`;
-}
-/** A TOML key: bare when TOML allows it, quoted otherwise — host-supplied bridge env names are not guaranteed bare-safe. */
-function tomlKey(key) {
-    return /^[A-Za-z0-9_-]+$/.test(key) ? key : tomlString(key);
-}
-/**
- * Codex's per-tool deadline for the Jini bridge, in seconds: `@jini-ai/mcp`'s
- * `DEFAULT_DELEGATED_TOOL_TIMEOUT_MS` (6 min, mirrored because this package does not depend on
- * that one) plus 40 s. Codex's own default (60 s) is shorter than a delegated call parked on a
- * human dialog, and when Codex abandons a call the dialog stayed answerable, so a late click ran
- * an action the model had been told failed. Outlasting the bridge's deadline means the bridge
- * times out first, drops its daemon request, and the daemon expires the dialog. Codex does not
- * pass the parent env through to MCP servers, so the bridge under Codex always runs at its default.
- */
-const CODEX_TOOL_TIMEOUT_SEC = 6 * 60 + 40;
-/**
- * Mechanism 5 of 5 — `'codex-toml'`'s serialization step. Builds the `[mcp_servers.jini]` TOML
- * table (plus, when the entry carries any env vars, a separate `[mcp_servers.jini.env]` table)
- * Codex's own config schema expects.
- *
- * Confirmed against a real installed Codex CLI (0.151.0), not assumed from docs: round-tripping
- * `codex mcp add <name> --env K=V -- <cmd> <args>` against a scratch `CODEX_HOME` and reading back
- * `config.toml` produced exactly this shape (`command`/`args` as TOML strings/array in the main
- * table, env vars in a nested `.env` table) — see `archived provenance ledger` for the transcript.
- * @param entry - The shared bridge entry from {@link buildMcpJsonServerEntry}.
- * @returns A TOML fragment with no leading/trailing blank-line padding — {@link buildCodexHomeConfigToml} owns spacing when combining it with existing content.
- * @complexity O(n) in the number of argv/env entries.
- * @overallScore 100/100
- */
-export function buildCodexMcpServerToml({ entry }) {
-    const argsLiteral = entry.args.map(tomlString).join(', ');
-    const serverTable = `[mcp_servers.${JINI_MCP_SERVER_KEY}]\ncommand = ${tomlString(entry.command)}\nargs = [${argsLiteral}]\n` +
-        `tool_timeout_sec = ${CODEX_TOOL_TIMEOUT_SEC}\n`;
-    const envLines = Object.entries(entry.env)
-        .filter((pair) => typeof pair[1] === 'string')
-        .map(([key, value]) => `${tomlKey(key)} = ${tomlString(value)}`);
-    if (envLines.length === 0)
-        return serverTable;
-    return `${serverTable}\n[mcp_servers.${JINI_MCP_SERVER_KEY}.env]\n${envLines.join('\n')}\n`;
-}
-/**
- * Splits a TOML table header's dotted key into its individual segments, honoring quoted parts
- * (`"basic"` or `'literal'`) that may themselves contain a literal `.` — a bare `.` only
- * separates segments outside of quotes. Each segment is trimmed and, if quoted, unwrapped.
- *
- * Not a full TOML parser: it does not resolve escape sequences (`\"`, `\u...`) inside basic
- * strings. That is deliberately out of scope — see {@link stripExistingJiniMcpServerTable}'s doc
- * for why it is safe to skip for this specific comparison.
- * @param rawKey - The raw text between a table header's `[` and `]`.
- * @returns The dotted key's segments, dequoted and trimmed.
- * @complexity O(n) in the length of `rawKey`.
- */
-function splitTomlDottedKey(rawKey) {
-    const segments = [];
-    let current = '';
-    let quote = null;
-    for (const ch of rawKey) {
-        if (quote) {
-            if (ch === quote)
-                quote = null;
-            else
-                current += ch;
-            continue;
-        }
-        if (ch === '"' || ch === "'") {
-            quote = ch;
-            continue;
-        }
-        if (ch === '.') {
-            segments.push(current.trim());
-            current = '';
-            continue;
-        }
-        current += ch;
-    }
-    segments.push(current.trim());
-    return segments;
-}
-/**
- * Removes any pre-existing `[mcp_servers.{@link JINI_MCP_SERVER_KEY}]` table — and its
- * `[mcp_servers.{@link JINI_MCP_SERVER_KEY}.*]` subtables (e.g. `.env`) — from a real Codex
- * `config.toml`'s raw text, so {@link buildCodexHomeConfigToml} can append this run's own table
- * without producing the duplicate TOML key Codex's parser rejects at startup.
- *
- * Line-oriented, not a real TOML parser (matching {@link buildCodexMcpServerToml}'s own
- * no-TOML-dependency constraint), but wide enough to survive a hand-edited config, which is the
- * scenario this whole function exists for. A table header line is recognized when, after
- * trimming, it is `[<key>]` optionally followed only by a `# comment` (TOML's own grammar allows
- * nothing else there) — so it tolerates leading indentation, whitespace inside the brackets, a
- * trailing line comment, and a dotted key written with quoted segments (`["mcp_servers"."jini"]`),
- * via {@link splitTomlDottedKey}. Once such a header's key matches the jini table or one of its
- * subtables, every following line is dropped until the next table header (of any name) or EOF.
- * Every other table, key, comment-only, and blank line is passed through untouched.
- *
- * Deliberately unhandled, and why it is safe to leave that way:
- * - **Escape sequences inside quoted key segments** (e.g. a segment containing `\"`) — neither
- *   `mcp_servers` nor {@link JINI_MCP_SERVER_KEY} ever needs escaping, and this driver's own
- *   writer ({@link buildCodexMcpServerToml}) never emits a quoted form at all, so no real
- *   `config.toml` this driver produced can exercise this gap; a hand-edit that goes out of its
- *   way to escape a character inside a key that is supposed to spell "jini" would fail to match
- *   and fall back to today's pre-fix behavior (append a duplicate) rather than silently doing
- *   something worse.
- * - **`[[array-of-tables]]` syntax** — Codex's schema has no array-of-tables shape for
- *   `mcp_servers`, and the header regex's `[^[\]]+` capture cannot match a line starting with a
- *   second `[`, so `[[mcp_servers.jini]]` is not recognized as a header before or after this fix
- *   — unchanged, not a new gap.
- * - **A single quoted segment that happens to spell the same characters with the dot included**
- *   (e.g. `["mcp_servers.jini"]`, which in real TOML names one key literally containing a `.`,
- *   not two nested tables) — this collapses to the same joined string as the real nested-table
- *   spelling and is therefore treated as a match. This is a false positive in the conservative
- *   direction the reported bug calls for: a missed detection duplicates a key and crashes Codex,
- *   so on this axis over-matching a spelling nobody would plausibly hand-write for an MCP server
- *   table is preferable to under-matching the real one.
- * @param existingRaw - The real Codex home's `config.toml` content, already known to be defined
- * (callers pass `''` for a missing file).
- * @returns `existingRaw` with any jini table/subtable removed.
- * @complexity O(n) in the number of lines.
- */
-function stripExistingJiniMcpServerTable(existingRaw) {
-    const jiniTableKey = `mcp_servers.${JINI_MCP_SERVER_KEY}`;
-    const kept = [];
-    let skipping = false;
-    for (const line of existingRaw.split('\n')) {
-        const header = /^\s*\[([^[\]]+)\]\s*(#.*)?$/.exec(line);
-        if (header) {
-            const key = splitTomlDottedKey(header[1] ?? '').join('.');
-            skipping = key === jiniTableKey || key.startsWith(`${jiniTableKey}.`);
-            if (skipping)
-                continue;
-        }
-        if (!skipping)
-            kept.push(line);
-    }
-    return kept.join('\n');
-}
-/**
- * Builds the full `config.toml` a run's scratch `CODEX_HOME` gets: the real Codex home's own
- * config, with any pre-existing `[mcp_servers.jini]` table removed (see
- * {@link stripExistingJiniMcpServerTable}), then this run's own table appended.
- *
- * **Append-only by design, not a parse-and-merge, for everything but the jini table itself.**
- * `mergeMcpJsonContent`/`mergeEnvContentMcpConfig` above can safely parse-merge-reserialize because
- * their formats have a JS-native parser (`JSON.parse`); this driver has no general TOML parser in
- * its dependency graph (see `buildCodexMcpServerToml`'s doc), and every other setting a real Codex
- * install carries — model choice, sandbox policy, the trusted-project list, the operator's own
- * other MCP servers — must survive a spawn byte-for-byte. Only the one table this driver itself
- * owns (`jini` is this integration's own reserved server name — see {@link JINI_MCP_SERVER_KEY}) is
- * ever removed, via the narrow line-oriented scan above, never a full TOML parse.
- * @param existingRaw - The real Codex home's `config.toml` content, or `undefined` when it does not
- * exist (a fresh Codex install — degrades to "start from just this run's block", matching
- * {@link mergeMcpJsonContent}'s own "missing file" handling).
- * @param entry - The shared bridge entry.
- * @returns The full text to write to the scratch `CODEX_HOME`'s `config.toml`.
- * @complexity O(n) in the existing config's length.
- */
-export function buildCodexHomeConfigToml({ existingRaw, entry }) {
-    const base = stripExistingJiniMcpServerTable(existingRaw ?? '');
-    const separator = base.length === 0 ? '' : base.endsWith('\n') ? '\n' : '\n\n';
-    return `${base}${separator}${buildCodexMcpServerToml({ entry: entry })}`;
-}
-/**
- * Where `'codex-toml'` reads the operator's REAL Codex config from, to seed a run's scratch copy —
- * never where it writes. Resolved against the daemon HOST process's own environment (`hostEnv`,
- * `process.env` at the real call site), not a run's sandboxed spawn env: `CODEX_HOME` is not in
- * `BASELINE_AGENT_ENV_KEYS`, so a spawned child never inherits it anyway, and the whole point here
- * is finding wherever the *operator's actual* Codex install lives, which is a host-machine fact.
- * @param hostEnv - The daemon process's own environment.
- * @returns `hostEnv.CODEX_HOME` when set to a non-blank value (matching Codex's own resolution
- * order), else the CLI's documented default, `~/.codex`.
- * @complexity O(1).
- * @overallScore 100/100
- */
-export function resolveSourceCodexHomeDir({ hostEnv }) {
-    const override = hostEnv.CODEX_HOME;
-    return override !== undefined && override.trim().length > 0 ? override : join(homedir(), '.codex');
-}
-/**
- * **The single dispatch point from an `externalMcpInjection` strategy to its delivery mechanism.**
- * Pure and synchronous — the one effectful input (the per-run bearer credential) arrives already
- * resolved, so every strategy's mapping is directly assertable without touching the filesystem,
- * the environment, or a keystore.
- *
- * Keyed off the declared *strategy*, never off `def.id`: a def gets a working bridge by declaring a
- * mechanism, not by being named in this file. That is what makes the 9 `'acp-merge'` defs work
- * without any of their own files being touched.
- *
- * @param input.cwd - The run's working directory; only `'claude-mcp-json'` uses it, to place this
- * run's own config file (see {@link mcpJsonPathForRun}) — never `cwd/.mcp.json` itself.
- * @param input.runId - Scopes the bridge child to this run.
- * @param input.strategy - The def's declared `externalMcpInjection`, or `undefined` for a def with no native MCP transport.
- * @param input.options - The host's bridge options, or `undefined` when the host never configured injection.
- * @param input.credential - Already-resolved bearer token, or `undefined` to omit `JINI_DAEMON_TOKEN` entirely.
- * @returns `null` when this run delivers nothing — an unconfigured host, or a def declaring no
- * strategy — which is byte-identical to this feature not existing.
- * @complexity O(1).
- * @overallScore 100/100
- */
-export function buildMcpBridgeDelivery(input) {
-    const { cwd, runId, strategy, options, credential } = input;
-    if (options === undefined || strategy === undefined)
-        return null;
-    const serverEntry = buildMcpJsonServerEntry({ runId: runId, options: options }, credential === undefined ? {} : { credential });
-    switch (strategy) {
-        case 'claude-mcp-json':
-            return { kind: 'claude-mcp-json', mcpJsonPath: mcpJsonPathForRun(cwd, runId), serverEntry };
-        case 'acp-merge':
-            return { kind: 'acp-merge', mcpServers: buildAcpMcpBridgeServers({ entry: serverEntry }) };
-        case 'opencode-env-content':
-        case 'mimo-env-content':
-            return { kind: 'env-content', envVarName: ENV_CONTENT_VAR_BY_STRATEGY[strategy], serverEntry };
-        case 'codex-toml':
-            return { kind: 'codex-toml', serverEntry };
-        case 'env-passthrough':
-            return { kind: 'env-passthrough', serverEntry };
-    }
-}
-function defaultReadMcpJsonFile({ path }) {
-    return fsPromises.readFile(path, 'utf8');
-}
-function defaultWriteMcpJsonFile({ path, content }) {
-    return fsPromises.writeFile(path, content, 'utf8');
-}
-function defaultRemoveMcpJsonFile({ path }) {
-    return fsPromises.rm(path, { force: true });
-}
-/**
- * This run's own MCP config path, inside `cwd` but deliberately **not** `cwd/.mcp.json`.
- *
- * A shared filename cannot carry two runs' identities at once, and that is exactly what the file
- * carries: `mcpServers.jini.env` holds this run's `JINI_RUN_ID` and its bearer `JINI_DAEMON_TOKEN`.
- * A spawned CLI reads its MCP config when it starts its client, not synchronously at spawn — so with
- * one shared file, a second run in the same directory overwrote the entry the first run's child had
- * not read yet, and that child's `jini-mcp` subprocess then called back carrying the *other* run's id
- * and token: run A's tool calls executing inside run B's authority context. Concurrent runs in one
- * working directory are supported by design (see `McpJsonInjectionOptions.credential`'s doc on why the
- * credential is a per-run resolver at all), so the resolution is one file per run, not a lock that
- * refuses the second run.
- *
- * Naming it after the run also means the project's own `.mcp.json` is never written at all — it stays
- * purely a merge source, so there is no original content to restore afterwards either.
- *
- * The run id is host-supplied and lands in a filename, so everything outside `[A-Za-z0-9_-]` is
- * replaced (dots included — a `..` segment must not survive) and the result is length-capped. Real run
- * ids are UUIDs, which pass through untouched; the cap could in principle collide two ids sharing a
- * 128-character prefix, which no id shape this daemon mints can produce.
- * @complexity O(n) in the run id's length.
- */
-function mcpJsonPathForRun(cwd, runId) {
-    const safeRunId = runId.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 128);
-    return join(cwd, `.mcp.jini-${safeRunId}.json`);
-}
-/**
- * The `'claude-mcp-json'` mechanism's one effect: writes (merging, never clobbering — see
- * {@link mergeMcpJsonContent}) this run's own config — the project's own servers merged with this
- * run's `jini` bridge entry — to the run-scoped path ({@link mcpJsonPathForRun}) the def was already
- * handed via `RuntimeContext.mcpJsonPath`, so the def's own `--strict-mcp-config --mcp-config <path>`
- * argv has a real file to point at by spawn time, instead of auto-discovering `cwd/.mcp.json` (which
- * needs an interactive trust prompt a headless spawn can never answer — confirmed live 2026-07-30,
- * see `@jini-ai/agent-runtime`'s `defs/claude.ts`).
- *
- * Reads `cwd/.mcp.json` and writes `delivery.mcpJsonPath`: the project's file is a merge source only,
- * never a write target. See {@link mcpJsonPathForRun} for why one file per run is load-bearing rather
- * than cosmetic, and why the read and write paths must differ.
- *
- * A no-op for every other delivery mechanism, which is expressed by the caller simply not having a
- * `'claude-mcp-json'` delivery to hand it rather than by a strategy re-check in here.
- * @param cwd - The run's working directory, so the project's own `.mcp.json` can be read as the
- * merge base — not carried on `delivery` itself, since that only describes the write target.
- * @param delivery - The already-built `'claude-mcp-json'` delivery (path + entry). Both fields come
- * from {@link buildMcpBridgeDelivery}, so the credential was resolved exactly once, for this run.
- * @param options - Supplies the injectable `readFile`/`writeFile` seams.
- * @throws Whatever `writeFile` rejects with — the caller (`run()`) turns that into a pre-spawn
- * `AGENT_SPAWN_FAILED` failure, matching every other pre-spawn filesystem guard in this file
- * (`preparePromptFileForAgentFn`'s own try/catch).
- * @complexity O(1) plus one `readFile`/`writeFile` round trip.
- * @overallScore 100/100
- */
-async function writeMcpJsonForRun(cwd, delivery, options) {
-    const readFileFn = options.readFile ?? defaultReadMcpJsonFile;
-    const writeFileFn = options.writeFile ?? defaultWriteMcpJsonFile;
-    let existingRaw;
-    try {
-        existingRaw = await readFileFn({ path: join(cwd, '.mcp.json') });
-    }
-    catch {
-        // No existing file (ENOENT — the common case) or unreadable for any other reason: both
-        // degrade to "start fresh", matching mergeMcpJsonContent's own doc.
-        existingRaw = undefined;
-    }
-    await writeFileFn({ path: delivery.mcpJsonPath, content: mergeMcpJsonContent({ existingRaw: existingRaw, serverEntry: delivery.serverEntry }) });
-}
-function defaultMkdtempCodexHome({ prefix }) {
-    return fsPromises.mkdtemp(join(tmpdir(), prefix));
-}
-function defaultRemoveCodexHomeDir({ path }) {
-    return fsPromises.rm(path, { recursive: true, force: true });
-}
-function resolveCodexHomeSeams(options) {
-    return {
-        mkdtemp: options.mkdtemp ?? defaultMkdtempCodexHome,
-        readFile: options.readFile ?? defaultReadMcpJsonFile,
-        writeFile: options.writeFile ?? defaultWriteMcpJsonFile,
-        removeDir: options.removeDir ?? defaultRemoveCodexHomeDir,
-    };
-}
-/**
- * Mechanism 5 of 5 — `'codex-toml'`'s one effect. Stages a fresh, randomly-named `CODEX_HOME`
- * directory (see {@link McpJsonInjectionOptions.mkdtemp}'s doc for why non-deterministic naming is
- * load-bearing here, not cosmetic) carrying:
- *   - `config.toml`: the real Codex home's own config (read best-effort — see
- *     {@link buildCodexHomeConfigToml}'s "missing file" handling) with this run's
- *     `[mcp_servers.jini]` table appended.
- *   - `auth.json`: a best-effort copy of the real Codex home's stored login, so the spawned CLI is
- *     still authenticated. Best-effort is safe here, not merely convenient: a real headless spawn
- *     against a `CODEX_HOME` with no `auth.json` at all was confirmed (against installed Codex CLI
- *     0.151.0) to fail fast with a structured `401 Unauthorized` stream event, never an interactive
- *     login prompt or a hang — see `defs/codex.ts`'s module doc for the full transcript summary.
- *
- * **Never touches the real `CODEX_HOME`.** `sourceCodexHomeDir` is read-only throughout; nothing is
- * ever written back to it.
- *
- * A failure after the directory is created (a rejecting `writeFile`, most plausibly) does not leak
- * it: the directory may already hold a partial `config.toml` or a copied credential, so the
- * `catch` below best-effort-removes it before rethrowing, exactly the "partial-failure state leak"
- * class of bug this package's own adversarial-test-design guidance calls out.
- * @param runId - Embedded in the temp-dir prefix for traceability, sanitized the same way
- * `@jini-ai/agent-runtime`'s `prepareAgentLogFile`'s `label` is.
- * @param entry - The shared bridge entry.
- * @param sourceCodexHomeDir - Where to read the real install's `config.toml`/`auth.json` from — see {@link resolveSourceCodexHomeDir}.
- * @param seams - Injectable mkdtemp/readFile/writeFile/removeDir, real filesystem by default.
- * @throws Whatever `mkdtemp`/`writeFile` rejects with — the caller ({@link prepareCodexHomeIfNeeded}) turns that into a pre-spawn `AGENT_SPAWN_FAILED` failure, matching {@link writeMcpJsonForRun}'s own contract.
- * @complexity O(1) plus one directory creation and up to two best-effort file read/write round trips.
- * @overallScore 100/100
- */
-async function prepareCodexHomeForRun(runId, entry, sourceCodexHomeDir, seams) {
-    // Stricter than `@jini-ai/agent-runtime`'s `prepareAgentLogFile`/`preparePromptFileForAgent`
-    // labels (which keep dots): this prefix stages a directory that ends up holding a copied Codex
-    // login credential, so it gets `mcpJsonPathForRun`'s tighter discipline instead — dots stripped
-    // too, not just path separators, so a run id like `../../etc/evil` cannot leave even a cosmetic
-    // `..` substring in the mkdtemp prefix.
-    const safeRunId = runId.replace(/[^A-Za-z0-9_-]/g, '-').slice(0, 80) || 'run';
-    const dir = await seams.mkdtemp({ prefix: `jini-codex-home-${safeRunId}-` });
-    try {
-        let existingConfigRaw;
-        try {
-            existingConfigRaw = await seams.readFile({ path: join(sourceCodexHomeDir, 'config.toml') });
-        }
-        catch {
-            // No config yet (fresh Codex install) or unreadable — start from just this run's block,
-            // matching writeMcpJsonForRun's identical "missing file" handling.
-            existingConfigRaw = undefined;
-        }
-        await seams.writeFile({ path: join(dir, 'config.toml'), content: buildCodexHomeConfigToml({ existingRaw: existingConfigRaw, entry: entry }) });
-        try {
-            const authRaw = await seams.readFile({ path: join(sourceCodexHomeDir, 'auth.json') });
-            await seams.writeFile({ path: join(dir, 'auth.json'), content: authRaw });
-        }
-        catch {
-            // No stored login (or unreadable) — the spawned CLI runs unauthenticated. Confirmed above:
-            // this fails the run fast and observably, never as a hang.
-        }
-    }
-    catch (err) {
-        await seams.removeDir({ path: dir }).catch(() => {
-            // Best-effort only — the original error below is what the caller must see either way.
-        });
-        throw err;
-    }
-    return {
-        path: dir,
-        cleanup: async () => {
-            await seams.removeDir({ path: dir });
-        },
-    };
-}
-function defaultMkdtempClaudeConfigDir({ prefix }) {
-    return fsPromises.mkdtemp(join(tmpdir(), prefix));
-}
-function defaultRemoveClaudeConfigDir({ path }) {
-    return fsPromises.rm(path, { recursive: true, force: true });
-}
-function resolveClaudeConfigDirSeams(options) {
-    return {
-        mkdtemp: options?.mkdtemp ?? defaultMkdtempClaudeConfigDir,
-        readFile: options?.readFile ?? defaultReadMcpJsonFile,
-        writeFile: options?.writeFile ?? defaultWriteMcpJsonFile,
-        removeDir: options?.removeDir ?? defaultRemoveClaudeConfigDir,
-    };
-}
-/**
- * Where `claude`'s own config resolution reads the operator's REAL config from, to seed a run's
- * scratch copy — never where it writes. Mirrors {@link resolveSourceCodexHomeDir}'s exact reasoning
- * and resolution order: `CLAUDE_CONFIG_DIR` is not in `BASELINE_AGENT_ENV_KEYS`, so a spawned child
- * never inherits it anyway — the whole point is finding wherever the *operator's actual* Claude Code
- * install lives, a host-machine fact resolved against the daemon HOST process's own environment.
- * @param hostEnv - The daemon process's own environment.
- * @returns `hostEnv.CLAUDE_CONFIG_DIR` when set to a non-blank value (matching Claude Code's own
- * resolution order, confirmed against installed Claude Code 2.1.263), else the CLI's documented
- * default, `~/.claude`.
- * @complexity O(1).
- */
-export function resolveSourceClaudeConfigDir({ hostEnv }) {
-    const override = hostEnv.CLAUDE_CONFIG_DIR;
-    return override !== undefined && override.trim().length > 0 ? override : join(homedir(), '.claude');
-}
-/**
- * Stages a fresh, randomly-named `CLAUDE_CONFIG_DIR` directory (same non-determinism requirement as
- * {@link McpJsonInjectionOptions.mkdtemp}'s own doc — `os.tmpdir()` is a shared location on a
- * multi-user host, so a guessable name is a real pre-plant/symlink target).
- *
- * **Deliberately empty by default** — unlike {@link prepareCodexHomeForRun}, which copies the real
- * `config.toml` wholesale (Codex has no personal-data problem in that file), this directory gets
- * NOTHING written into it beyond a best-effort copy of `.credentials.json` (see below). That is the
- * fix: the operator's real `skills`/`plugins`/`agents`/`memory-path index`/`settings.json` must NOT
- * carry over implicitly. `claude` runs correctly against a config directory holding nothing at all —
- * it falls back to its own built-in defaults, not an error.
- *
- * **Login preservation, verified rather than assumed** (per this task's own instruction — "prove
- * login still resolves; do not assume"): confirmed live (2026-09-07, installed Claude Code 2.1.263,
- * macOS) that `claude auth status` reports `loggedIn: false` against ANY `CLAUDE_CONFIG_DIR` other
- * than the operator's real one — including the real `HOME` with only `CLAUDE_CONFIG_DIR` swapped —
- * and confirmed against Claude Code's own docs (code.claude.com/docs/en/authentication) why: "If
- * you've set the CLAUDE_CONFIG_DIR environment variable, Claude Code keeps the .credentials.json
- * file under that directory instead, including the file the macOS fallback writes, and keys the
- * macOS Keychain entry to that directory too, so a session with a different CLAUDE_CONFIG_DIR reads
- * a different entry." So a scratch directory is never logged in by default on ANY platform, not just
- * the ones with no Keychain at all. This function only closes the *portable* case: when the source
- * directory holds a file-based `.credentials.json` (Linux, Windows, or a Keychain-locked macOS
- * fallback — none of which this function can distinguish, and does not need to), it is copied
- * best-effort into the scratch directory, exactly `prepareCodexHomeForRun`'s `auth.json` copy. When
- * it does not (a normal macOS Keychain-only install, confirmed the common case on this codebase's
- * own dev machine), this function does NOT attempt to read the macOS Keychain itself — that would
- * mean this daemon process extracting a live OAuth secret out of an OS-managed credential store into
- * a plaintext file, a materially different and larger security surface than forwarding an
- * already-resolved credential the host handed it (which `credentialEnv`/`ANTHROPIC_API_KEY` already
- * does, safely, today — see `AgentExecutorRunInput.credentialEnv`'s own doc). In that case this
- * mirrors `prepareCodexHomeForRun`'s own accepted outcome for a missing credential file verbatim:
- * "the spawned CLI runs unauthenticated" is documented, existing, precedented behavior in this file,
- * not a new failure mode invented here. A host that needs the isolated child to stay logged in on
- * such an install must supply a credential explicitly via `AgentExecutorRunInput.credentialEnv`
- * (`ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN` — both outrank Keychain-based subscription login
- * in Claude Code's own auth precedence, so the isolated child authenticates without ever needing the
- * operator's personal Keychain entry at all) — see this fix's own handoff report for the operational
- * consequence on a host with no such credential configured yet.
- *
- * **Never touches the real config directory.** `sourceConfigDir` is read-only throughout.
- * @param runId - Embedded in the temp-dir prefix for traceability, same sanitization discipline as {@link prepareCodexHomeForRun}'s `safeRunId`.
- * @param sourceConfigDir - Where to read a possible real `.credentials.json` from — see {@link resolveSourceClaudeConfigDir}.
- * @param seams - Injectable mkdtemp/readFile/writeFile/removeDir, real filesystem by default.
- * @throws Whatever `mkdtemp` rejects with — the caller ({@link prepareClaudeConfigDirIfNeeded}) turns that into a pre-spawn `AGENT_SPAWN_FAILED` failure, matching {@link prepareCodexHomeForRun}'s own contract.
- * @complexity O(1) plus one directory creation and up to one best-effort file read/write round trip.
- */
-async function prepareClaudeConfigDirForRun(runId, sourceConfigDir, seams) {
-    const safeRunId = runId.replace(/[^A-Za-z0-9_-]/g, '-').slice(0, 80) || 'run';
-    const dir = await seams.mkdtemp({ prefix: `jini-claude-config-${safeRunId}-` });
-    try {
-        const credentialsPath = join(sourceConfigDir, '.credentials.json');
-        let credentialsRaw;
-        try {
-            credentialsRaw = await seams.readFile({ path: credentialsPath });
-        }
-        catch {
-            // No file-based credential to copy (the common macOS-Keychain-only case) — see this
-            // function's own doc for why that is an accepted, documented outcome, not a failure here.
-            credentialsRaw = undefined;
-        }
-        if (credentialsRaw !== undefined) {
-            await seams.writeFile({ path: join(dir, '.credentials.json'), content: credentialsRaw });
-        }
-    }
-    catch (err) {
-        await seams.removeDir({ path: dir }).catch(() => {
-            // Best-effort only — the original error below is what the caller must see either way.
-        });
-        throw err;
-    }
-    return {
-        path: dir,
-        cleanup: async () => {
-            await seams.removeDir({ path: dir });
-        },
-    };
-}
-/**
- * Default ceiling on the `'until-close'` stdout accumulator (see `RuntimeStdoutPolicy` in
- * `@jini-ai/agent-runtime`), in bytes of received UTF-8.
- *
- * A buffered def holds its child's entire stdout in one in-memory string until the process closes,
- * which is exactly what makes the accumulator a denial-of-service surface: the child is a
- * prompt-influenced agent CLI this driver already treats as potentially adversarial (SEC-001), and
- * nothing obliges it to ever close or to stop emitting. Without a ceiling one run could exhaust the
- * daemon's heap and take every unrelated run in the process down with it.
- *
- * 8 MiB is chosen to sit far above any real buffered-agent transcript (antigravity's print-mode
- * output — the only `'until-close'` def — is a few KiB of auth prompt and result text) while staying
- * small enough that a hostile child cannot meaningfully pressure the heap. A host that genuinely
- * needs more passes `CreateAgentExecutorOptions.bufferedStdoutMaxBytes`.
- */
-export const DEFAULT_BUFFERED_STDOUT_MAX_BYTES = 8 * 1024 * 1024;
-/**
- * The host-authored note appended to a truncated flush. Written *after* the def's own `sanitize`
- * runs, never before: it is this driver's own text, not agent output, and passing it through a
- * consumer-supplied redactor could silently delete the one line that says output is missing.
- */
-function bufferedStdoutTruncationNotice(droppedBytes, maxBytes) {
-    return `\n[jini] agent stdout truncated: ${droppedBytes} byte(s) dropped after the ${maxBytes}-byte buffer limit was reached.\n`;
-}
-/**
- * Wires one spawned child's full observable lifecycle: raw stdout/stderr
- * forwarding, structured stream-parser dispatch (translated via
- * {@link translateAgentRuntimeEvent}), cancellation (subscribes
- * `lifecycle.onCancelRequested` and escalates via `stopProcesses` on the
- * child's full descendant tree), and the terminal `close` → `finish()`
- * transition. Registered *before* the caller awaits spawn confirmation so
- * no early `'error'`/`'close'` event is ever missed.
- *
- * Every `lifecycle.emit()` call is funneled through a per-run FIFO queue
- * (`enqueueEmit`) rather than fired independently: a single stdout `data`
- * chunk can synchronously produce several parsed events (a JSON line's
- * `feed()` call may invoke `onEvent` more than once), and successive
- * `data` events must not have their derived `emit()` calls race each
- * other out of order. The queue also absorbs an individual `emit()`
- * rejection (e.g. a race against an already-terminal run) without losing
- * subsequently queued events, and the `close` handler awaits it fully
- * drained before computing the terminal outcome — so `finish()`'s `'end'`
- * event is always durably last, never interleaved with a still-in-flight
- * `'agent'`/`'stdout'`/`'stderr'` append.
- *
- * `streamFormat: 'plain'` gets no `createStreamHandlerForDef` parser at
- * all (Option B — see module doc and
- * `ADS-memory/reports/proposals/PROP-plain-format-agent-driving-2026-07-21.md`
- * §3): every raw stdout chunk is forwarded verbatim as a `text_delta`
- * `'agent'` event, through the same `enqueueEmit` FIFO queue every other
- * emit already goes through — no new parser state machine.
- * **Deliberately un-hygiened for v1**: no ANSI/terminal-control-sequence
- * stripping is applied (there is no Jini equivalent of OD's
- * `TerminalControlSequenceStripper` yet) — a documented decision, not an
- * oversight; see `packages/daemon/archived provenance ledger`'s 2026-07-21 addition for
- * the reasoning.
- *
- * *When* those chunks leave is the def's call, via `def.stdoutPolicy`:
- *
- *   - `'live'` (the default, and every def but antigravity) — emit per
- *     chunk, as it arrives.
- *   - `'until-close'` — accumulate, and emit the whole thing exactly once
- *     from the `close` handler, after `def.stdoutPolicy.sanitize`. For an
- *     adapter that can print a secret to stdout and still exit 0, no
- *     per-chunk decision is safe: the pattern to redact can straddle two
- *     `'data'` events.
- *
- * The buffered path holds back the raw `'stdout'` echo too, not just the
- * `'agent'`/`text_delta`, and sanitizes both. Emitting an unsanitized raw
- * echo while withholding the chat copy would leak the exact string the
- * sanitizer exists to remove to any client subscribed to the run's events —
- * the raw channel is a different *purpose*, not a different audience.
- * `journal` is the one thing still recorded per-chunk and verbatim: it is
- * the host's own byte record, deliberately kept in a **separate** `EventLog`
- * instance that is never replayed to run-event subscribers (see
- * `continuation/journal.ts`'s module doc), and "every byte received" is its
- * whole contract.
- *
- * @param ctx - Run/def/child/lifecycle plus the cancellation-escalation ports.
- * @returns A handle exposing `closeStdinOnce` for the initial prompt write to share.
- * @complexity Registration is O(1); steady-state per-chunk cost is the
- * chosen stream parser's own `feed()` cost plus O(1) queue bookkeeping.
- * @overallScore 100/100
- */
-function wireChildLifecycle(ctx) {
-    const { runId, def, streamFormat, child, lifecycle, journal, continuation, classifyFailure } = ctx;
-    let stdinClosed = false;
-    let cancelRequested = false;
-    let emitQueue = Promise.resolve();
-    // Gap 5 (session resume) — the last session/thread id a 'status' event reported, threaded into
-    // finish()'s sessionRef below. `streamFormat === 'plain'` defs have no structured parser and
-    // therefore never populate this — an honest scope limit, not an oversight.
-    let capturedSessionId;
-    // Real `FailureClassificationContext.sideEffects` signals (2026-07-22) — see that interface's
-    // own doc for exactly what these two mean and why the other two `RunRetrySideEffectState`
-    // fields aren't tracked here at all.
-    let userVisibleOutputSeen = false;
-    let toolCallSeen = false;
-    // Gap 3 (stdin-tool-result injection) — the most recently reported tool_use, cleared once
-    // consumed by a turn-end injection decision. See `ContinuationOptions`'s doc for why this is
-    // only ever acted on when a host has explicitly allowlisted the tool's name.
-    let pendingToolUse;
-    // Bridge guard (see `expectsJiniBridge`): checked on the first init frame only. Once the bridge is
-    // found unavailable, the child is being stopped and nothing it still prints is forwarded.
-    let bridgeChecked = !ctx.expectsJiniBridge;
-    let bridgeUnavailable = false;
-    // `def.stdoutPolicy` read once, up front, so the per-chunk handler below is a single boolean
-    // test rather than a repeated union narrowing. `undefined` (every def but antigravity) means
-    // live — see this function's own doc.
-    const stdoutPolicy = def.stdoutPolicy;
-    const bufferStdoutUntilClose = stdoutPolicy?.buffering === 'until-close';
-    const sanitizeBufferedStdout = stdoutPolicy?.buffering === 'until-close' ? stdoutPolicy.sanitize : undefined;
-    // Accumulator for the `'until-close'` path. Stays `''` for every live def, and the flush below
-    // is then a no-op that emits nothing. Bounded by `ctx.bufferedStdoutMaxBytes` — see
-    // {@link DEFAULT_BUFFERED_STDOUT_MAX_BYTES} for why an unbounded accumulator was a
-    // denial-of-service surface rather than merely untidy.
-    let bufferedStdout = '';
-    let bufferedStdoutBytes = 0;
-    /** Bytes the ceiling refused, reported verbatim on flush so truncation is never silent. */
-    let droppedStdoutBytes = 0;
-    function enqueueEmit(task) {
-        emitQueue = emitQueue.then(async () => {
-            try {
-                await task();
-            }
-            catch {
-                // A single emit failing (e.g. a race against an already-terminal
-                // run) must not block delivery of subsequently queued events —
-                // see this function's own doc.
-            }
-        });
-    }
-    function closeStdinOnce() {
-        if (stdinClosed)
-            return;
-        stdinClosed = true;
-        child.stdin?.end();
-    }
-    /**
-     * Writes a structured (never string-concatenated — see `ContinuationOptions`'s doc on the
-     * prompt-injection stakes here) tool_result JSONL line, mirroring the shape
-     * `claude-stream.ts`'s own inbound parser already expects on the opposite direction of this
-     * exact wire format. Journals the sent content the same way `writePromptToStdin`'s
-     * `recordSentBytes` does.
-     */
-    function injectToolResultLine(toolUseId, content, isError) {
-        const stdin = child.stdin;
-        if (!stdin)
-            return;
-        const line = JSON.stringify({
-            type: 'user',
-            message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: toolUseId, content, ...(isError ? { is_error: true } : {}) }] },
-        });
-        stdin.write(`${line}\n`, 'utf8');
-        if (journal)
-            enqueueEmit(() => journal.record({ runId: runId, entry: sentJournalEntry(content) }));
-    }
-    /**
-     * Decides, per `turn_end`, whether to auto-resolve a pending tool_use through the injected
-     * `ToolExecutor` and keep stdin open (gap 3), or close stdin exactly as every version of this
-     * function has always done (the default, and the only behavior when `continuation` is
-     * unconfigured or the pending tool isn't allowlisted).
-     */
-    function handleTurnEnd(stopReason) {
-        const toolUse = pendingToolUse;
-        const shouldInject = stopReason === 'tool_use' &&
-            toolUse !== undefined &&
-            continuation !== undefined &&
-            resolveContinuationTransport({ def: def }) === 'stdin-injection' &&
-            continuation.autonomousToolNames.has(toolUse.name);
-        if (!shouldInject) {
-            closeStdinOnce();
-            return;
-        }
-        pendingToolUse = undefined;
-        enqueueEmit(async () => {
-            const run = { id: runId };
-            let content;
-            let isError;
-            // Same extraction `delegated-tool-bridge.ts`'s `execute()` runs, kept consistent per
-            // `resultContent`'s own doc ("both callers share one mapping"). This path never ran
-            // `splitToolResultSurfaces` (it has no `mcp-ui` withhold-from-model concept — the flattened
-            // `content` below already carries the whole raw output, a pre-existing, unrelated gap), so
-            // there is no `remainder` to thread back in — only the extracted blocks are used here.
-            let media = [];
-            // Suspend the slow-run watchdog for the duration of this daemon-awaited execution: the daemon
-            // knows exactly why the run is quiet here (it dispatched the tool itself and is waiting on it),
-            // so a legitimately long tool (an install, a build, a repo-wide scan) must not be mistaken for
-            // the CPU-starved-and-silent condition the watchdog exists to catch. Resumed in `finally` so a
-            // genuinely stalled stretch *after* this tool settles is still caught — see
-            // `RunLifecycle.suspendSlowRunNotice`'s own doc.
-            lifecycle.suspendSlowRunNotice({ runId: runId });
-            try {
-                const result = await continuation.toolExecutor.execute({ principal: continuation.principal, run: run, toolId: toolUse.name, input: toolUse.input });
-                content = resultContent({ result: result });
-                isError = result.status !== 'completed';
-                media = extractResultMedia({ output: result.output }).media;
-            }
-            catch (error) {
-                content = errorMessage(error);
-                isError = true;
-            }
-            finally {
-                lifecycle.resumeSlowRunNotice({ runId: runId });
-            }
-            await lifecycle.emit({ runId: runId, input: {
-                    event: 'agent',
-                    data: {
-                        type: 'tool_result',
-                        toolUseId: toolUse.id,
-                        content,
-                        ...(isError ? { isError: true } : {}),
-                        ...(media.length > 0 ? { media } : {}),
-                    },
-                } });
-            injectToolResultLine(toolUse.id, content, isError);
-        });
-    }
-    const streamHandler = streamFormat === 'plain'
-        ? null
-        : createStreamHandlerForDef(def, streamFormat, (rawEvent) => {
-            if (bridgeUnavailable)
-                return;
-            const translation = translateAgentRuntimeEvent({ rawEvent: rawEvent });
-            if (translation.kind === 'agent') {
-                if (translation.sessionId !== undefined)
-                    capturedSessionId = translation.sessionId;
-                if (!bridgeChecked && translation.payload.type === 'status' && translation.payload.label === 'initializing') {
-                    bridgeChecked = true;
-                    const bridgeStatus = unavailableJiniBridgeStatus({ rawEvent: rawEvent });
-                    if (bridgeStatus !== undefined) {
-                        stopForUnavailableBridge(translation.payload, bridgeStatus);
-                        return;
-                    }
-                }
-                if (translation.payload.type === 'tool_use') {
-                    pendingToolUse = { id: translation.payload.id, name: translation.payload.name, input: translation.payload.input };
-                    toolCallSeen = true;
-                }
-                else if ((translation.payload.type === 'text_delta' || translation.payload.type === 'thinking_delta') &&
-                    translation.payload.delta.length > 0) {
-                    userVisibleOutputSeen = true;
-                }
-                enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'agent', data: translation.payload } }));
-            }
-            else if (translation.kind === 'error') {
-                enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'error', data: translation.payload } }));
-            }
-            else if (translation.kind === 'turn-end') {
-                handleTurnEnd(translation.stopReason);
-            }
-        });
-    /**
-     * Ends a run whose CLI started without the `jini` bridge: emits the init status and a
-     * {@link MCP_BRIDGE_UNAVAILABLE} error, then stops the child's process tree before the model can
-     * answer with no host tools. The close handler then finishes the run `'failed'` whatever exit code
-     * the child reports.
-     */
-    function stopForUnavailableBridge(initStatus, bridgeStatus) {
-        bridgeUnavailable = true;
-        const message = bridgeUnavailableMessage(bridgeStatus);
-        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'agent', data: initStatus } }));
-        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'error', data: { message, error: { code: MCP_BRIDGE_UNAVAILABLE, message } } } }));
-        void terminateChildTreeBestEffort(ctx, child, runId, 'cancel', ctx.onCleanupFailure);
-    }
-    /**
-     * Emits the accumulated `'until-close'` stdout — sanitized — as exactly one raw `'stdout'` echo
-     * plus one `text_delta`, through the same `enqueueEmit` FIFO queue every other emit uses, so the
-     * flush is ordered after every already-queued event and before `finish()`'s `'end'`. A no-op for
-     * every live-streaming def (nothing was ever accumulated) and for a buffered run that produced
-     * no stdout at all — an empty `text_delta` is noise, not information.
-     *
-     * A run whose accumulator hit its ceiling is the one case that still emits when the sanitized text
-     * is empty: "the sanitizer redacted everything" and "we dropped output on the floor" must not look
-     * identical to a client, so the truncation notice is information in its own right.
-     */
-    function flushBufferedStdout() {
-        if (bufferedStdout.length === 0 && droppedStdoutBytes === 0)
-            return;
-        const safe = sanitizeBufferedStdout ? sanitizeBufferedStdout({ fullText: bufferedStdout }) : bufferedStdout;
-        bufferedStdout = '';
-        bufferedStdoutBytes = 0;
-        const text = droppedStdoutBytes > 0
-            ? `${safe}${bufferedStdoutTruncationNotice(droppedStdoutBytes, ctx.bufferedStdoutMaxBytes)}`
-            : safe;
-        droppedStdoutBytes = 0;
-        if (text.length === 0)
-            return;
-        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'stdout', data: { chunk: text } } }));
-        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'agent', data: { type: 'text_delta', delta: text } } }));
-    }
-    child.stdout?.on('data', (chunk) => {
-        const text = chunk.toString('utf8');
-        if (journal)
-            enqueueEmit(() => journal.record({ runId: runId, entry: receivedJournalEntry('stdout', text) }));
-        if (streamFormat === 'plain') {
-            if (text.length > 0)
-                userVisibleOutputSeen = true;
-            if (bufferStdoutUntilClose) {
-                // Nothing is emitted on *either* channel yet — see this function's doc on why holding the
-                // raw echo back matters as much as holding back the chat copy.
-                //
-                // Whole chunks only: a chunk that would cross the ceiling is dropped entirely rather than
-                // sliced to fit, which keeps the accumulator free of half-written multi-byte characters (a
-                // `data` event boundary already need not align with one) and makes the kept prefix exactly
-                // the bytes some prefix of chunks produced. Everything after the first refusal is dropped
-                // too — the point is a hard ceiling on resident bytes, not a best-effort tail.
-                const chunkBytes = Buffer.byteLength(text, 'utf8');
-                if (droppedStdoutBytes > 0 || bufferedStdoutBytes + chunkBytes > ctx.bufferedStdoutMaxBytes) {
-                    droppedStdoutBytes += chunkBytes;
-                    return;
-                }
-                bufferedStdout += text;
-                bufferedStdoutBytes += chunkBytes;
-                return;
-            }
-            enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'stdout', data: { chunk: text } } }));
-            enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'agent', data: { type: 'text_delta', delta: text } } }));
-            return;
-        }
-        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'stdout', data: { chunk: text } } }));
-        // Non-null: `streamHandler` is only ever null when `streamFormat === 'plain'` (see its
-        // construction above), the branch this statement is provably unreachable from.
-        streamHandler.feed({ chunk: text });
-    });
-    child.stderr?.on('data', (chunk) => {
-        const text = chunk.toString('utf8');
-        if (journal)
-            enqueueEmit(() => journal.record({ runId: runId, entry: receivedJournalEntry('stderr', text) }));
-        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'stderr', data: { chunk: text } } }));
-    });
-    // EPIPE-tolerant: a fast-exiting child that closes its stdin read end
-    // before every queued write lands must not crash the host process with
-    // an unhandled stream error — the real failure (if any) surfaces through
-    // the 'close' handler below regardless.
-    child.stdin?.on('error', () => { });
-    // Safety net for any child-level 'error' event that fires after the
-    // spawn-confirmation race (see waitForSpawnOrError) has already settled —
-    // EventEmitter throws on an unheard 'error' otherwise. The real outcome
-    // is still decided by 'close' below.
-    child.on('error', () => { });
-    const unsubscribeCancel = lifecycle.onCancelRequested({ runId: runId, listener: () => {
-            cancelRequested = true;
-            void terminateChildTreeBestEffort(ctx, child, runId, 'cancel', ctx.onCleanupFailure);
-        } });
-    child.on('close', (code, signal) => {
-        void (async () => {
-            // Not wrapped in try/catch: all 4 supported parser factories'
-            // flush() implementations already internally guard their own
-            // JSON.parse/dispatch and degrade a malformed trailing buffered
-            // line to a `{type:'raw'}` event rather than throwing (confirmed by
-            // reading each of the 4 modules in full — see module doc). A guard
-            // here would be dead code for the fixed, closed set of parsers this
-            // driver dispatches to. `streamHandler` is null for `'plain'` (no
-            // parser, hence nothing to flush) — `?.` skips it cleanly.
-            streamHandler?.flush();
-            // Queued before `await emitQueue` so the flushed text is durably appended ahead of
-            // `finish()`'s `'end'` event, exactly like every live-path emit already is.
-            flushBufferedStdout();
-            await emitQueue;
-            unsubscribeCancel();
-            // Both of the next two steps are guarded: neither a failed cleanup nor a rejecting host
-            // classifier may prevent the terminal transition below — see each helper's own doc.
-            await cleanupStagedFilesSafely(ctx);
-            const status = bridgeUnavailable ? 'failed' : classifyRunCloseStatus({ cancelRequested, code }, { signal });
-            // A bridge failure is not resumable: resuming would start the same CLI with the same bridge.
-            const resumable = status === 'failed' && !bridgeUnavailable && classifyFailure !== undefined
-                ? await classifyFailureSafely(ctx, classifyFailure, {
-                    runId,
-                    agentId: def.id,
-                    code,
-                    signal: signal ?? null,
-                    sideEffects: { userVisibleOutputSeen, toolCallSeen },
-                })
-                : false;
-            await lifecycle.finish({ runId, status, code, signal: signal ?? null, resumable }, { ...(capturedSessionId !== undefined ? { sessionRef: capturedSessionId } : {}) });
-        })();
-    });
-    return {
-        closeStdinOnce,
-        recordSentBytes(content) {
-            if (journal)
-                enqueueEmit(() => journal.record({ runId: runId, entry: sentJournalEntry(content) }));
-        },
-    };
-}
-/**
- * Maps an ACP session's transport error into the canonical run-error shape.
- * ACP adapters may add a structured `error` member, but a daemon driver must
- * never make one vendor's error shape part of the run protocol.
- */
-function translateAcpError(payload) {
-    if (!isRecord(payload))
-        return { message: asString(payload, 'ACP agent failed') };
-    const message = asString(payload.message, 'ACP agent failed');
-    const error = isRecord(payload.error) ? payload.error : null;
-    const code = error ? asOptionalString(error.code) : undefined;
-    const retryable = error && typeof error.retryable === 'boolean' ? error.retryable : undefined;
-    return {
-        message,
-        ...(code !== undefined
-            ? {
-                error: {
-                    code,
-                    message: asString(error?.message, message),
-                    ...(retryable !== undefined ? { retryable } : {}),
-                },
-            }
-            : {}),
-    };
-}
-/**
- * Applies one already-translated `'agent'`-kind event's side-effect signals — a captured session id
- * (gap 5), and the `toolCallSeen`/`userVisibleOutputSeen` pair every `wire*Lifecycle` driver tracks
- * for `FailureClassificationContext.sideEffects` — through `sink`. Extracted from `wireAcpLifecycle`'s
- * `send()`, where this exact three-level-deep nesting (session-id check, then tool_use/else-if
- * delta-length check) was that function's largest single cognitive-complexity contributor. Pure
- * except for calling the injected `sink` callbacks.
- * @param payload - The translated event's `RunAgentPayload`.
- * @param sessionId - The translation's optional captured session id, or `undefined`.
- * @param sink - The driver-specific effects to apply.
- * @complexity O(1).
- */
-export function applyAgentTranslationSideEffects({ payload, sessionId, sink }) {
-    if (sessionId !== undefined)
-        sink.onSessionId({ sessionId });
-    if (payload.type === 'tool_use') {
-        sink.onToolCall();
-    }
-    else if ((payload.type === 'text_delta' || payload.type === 'thinking_delta') && payload.delta.length > 0) {
-        sink.onUserVisibleOutput();
-    }
-}
-/**
- * Wires an ACP child to a run. Unlike the JSON-stream path, ACP owns the
- * prompt protocol and reports its parsed events through `attachAcpSession`'s
- * callback. This wrapper retains raw stdout/stderr for diagnostics, preserves
- * event order through the same FIFO discipline, forwards cancellation both as
- * ACP `session/cancel` and an OS process-tree stop, and uses the controller's
- * clean-prompt signal rather than SIGTERM (expected ACP cleanup) to determine
- * success.
- */
-function wireAcpLifecycle(ctx) {
-    const { runId, agentId, child, lifecycle, journal, classifyFailure } = ctx;
-    let cancelRequested = false;
-    let emitQueue = Promise.resolve();
-    // Gap 5 (session resume) — see wireChildLifecycle's identical local for the full rationale.
-    let capturedSessionId;
-    // Real `FailureClassificationContext.sideEffects` signals — see that interface's own doc.
-    let userVisibleOutputSeen = false;
-    let toolCallSeen = false;
-    function enqueueEmit(task) {
-        emitQueue = emitQueue.then(async () => {
-            try {
-                await task();
-            }
-            catch {
-                // A late event racing a terminal lifecycle is intentionally dropped;
-                // it must not prevent subsequent queued cleanup from running.
-            }
-        });
-    }
-    child.stdout?.on('data', (chunk) => {
-        const text = chunk.toString('utf8');
-        if (journal)
-            enqueueEmit(() => journal.record({ runId: runId, entry: receivedJournalEntry('stdout', text) }));
-        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'stdout', data: { chunk: text } } }));
-    });
-    child.stderr?.on('data', (chunk) => {
-        const text = chunk.toString('utf8');
-        if (journal)
-            enqueueEmit(() => journal.record({ runId: runId, entry: receivedJournalEntry('stderr', text) }));
-        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'stderr', data: { chunk: text } } }));
-    });
-    child.stdin?.on('error', () => { });
-    child.on('error', () => { });
-    let controller = null;
-    const unsubscribeCancel = lifecycle.onCancelRequested({ runId: runId, listener: () => {
-            cancelRequested = true;
-            controller?.abort();
-            void terminateChildTreeBestEffort(ctx, child, runId, 'cancel', ctx.onCleanupFailure);
-        } });
-    child.on('close', (code, signal) => {
-        void (async () => {
-            await emitQueue;
-            unsubscribeCancel();
-            // Guarded for the same reasons as the child-driven handler above.
-            await cleanupStagedFilesSafely(ctx);
-            const status = cancelRequested ? 'cancelled' : controller?.completedSuccessfully() ? 'succeeded' : 'failed';
-            const resumable = status === 'failed' && classifyFailure !== undefined
-                ? await classifyFailureSafely(ctx, classifyFailure, {
-                    runId,
-                    agentId,
-                    code,
-                    signal: signal ?? null,
-                    sideEffects: { userVisibleOutputSeen, toolCallSeen },
-                })
-                : false;
-            await lifecycle.finish({ runId, status, code, signal: signal ?? null, resumable }, { ...(capturedSessionId !== undefined ? { sessionRef: capturedSessionId } : {}) });
-        })();
-    });
-    controller = ctx.attachAcpSession({ child, prompt: ctx.prompt, send({ event, payload }) {
-            if (event === 'agent') {
-                const translation = translateAgentRuntimeEvent({ rawEvent: payload });
-                if (translation.kind === 'agent') {
-                    applyAgentTranslationSideEffects({ payload: translation.payload, sessionId: translation.sessionId, sink: {
-                            onSessionId: ({ sessionId }) => { capturedSessionId = sessionId; },
-                            onToolCall: () => { toolCallSeen = true; },
-                            onUserVisibleOutput: () => { userVisibleOutputSeen = true; },
-                        } });
-                    enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'agent', data: translation.payload } }));
-                }
-                else if (translation.kind === 'error') {
-                    enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'error', data: translation.payload } }));
-                }
-                return;
-            }
-            if (event === 'error') {
-                enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'error', data: translateAcpError(payload) } }));
-            }
-        } }, { cwd: ctx.cwd, ...(ctx.model !== undefined ? { model: ctx.model } : {}), ...(ctx.imagePaths.length > 0 ? { imagePaths: [...ctx.imagePaths] } : {}), ...(ctx.envFormat !== undefined ? { envFormat: ctx.envFormat } : {}),
-        // Spread-when-present rather than always: passing `mcpServers: []` is not the same as passing
-        // nothing for every downstream ACP agent, and "no bridge configured" must stay byte-identical
-        // to before this field existed.
-        ...(ctx.mcpServers !== undefined && ctx.mcpServers.length > 0 ? { mcpServers: [...ctx.mcpServers] } : {}), ...(ctx.onPermissionRequest !== undefined ? { onPermissionRequest: ctx.onPermissionRequest } : {}) });
-    return controller;
-}
-/**
- * Wires a pi-rpc child to a run. Like ACP, pi owns its own prompt-delivery
- * protocol (`prompt`/`new_session`/`abort` RPC commands over stdin) and
- * reports parsed events through `attachPiRpcSession`'s `send` callback —
- * unlike ACP's callback, pi-rpc's `send` always uses the `'agent'` channel
- * (confirmed by reading every `mapPiRpcEvent` call site: error-ness is
- * signaled via the payload's own `type: 'error'` field, never a separate
- * channel), so this wrapper runs every payload through the same
- * `translateAgentRuntimeEvent` pipeline ACP/JSON-stream already use, with no
- * channel branch needed. Raw stdout/stderr are still forwarded for
- * diagnostics (same as ACP) even though `attachPiRpcSession` also consumes
- * `child.stdout` itself for its own JSON-RPC parsing — Node multicasts
- * `'data'` events to every listener, so both coexist safely.
- *
- * v1 omits `parentSession` — none of
- * `AgentExecutorRunInput`'s fields carry them yet (matching this module's
- * established "explicitly out of scope" discipline for other follow-ups:
- * multi-turn tool continuation, resumable session ids, etc.).
- */
-function wirePiRpcLifecycle(ctx) {
-    const { runId, agentId, child, lifecycle, journal, classifyFailure } = ctx;
-    let cancelRequested = false;
-    let emitQueue = Promise.resolve();
-    // Gap 5 (session resume) — see wireChildLifecycle's identical local for the full rationale.
-    let capturedSessionId;
-    // Real `FailureClassificationContext.sideEffects` signals — see that interface's own doc.
-    let userVisibleOutputSeen = false;
-    let toolCallSeen = false;
-    function enqueueEmit(task) {
-        emitQueue = emitQueue.then(async () => {
-            try {
-                await task();
-            }
-            catch {
-                // A late event racing a terminal lifecycle is intentionally dropped;
-                // it must not prevent subsequent queued cleanup from running.
-            }
-        });
-    }
-    child.stdout?.on('data', (chunk) => {
-        const text = chunk.toString('utf8');
-        if (journal)
-            enqueueEmit(() => journal.record({ runId: runId, entry: receivedJournalEntry('stdout', text) }));
-        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'stdout', data: { chunk: text } } }));
-    });
-    child.stderr?.on('data', (chunk) => {
-        const text = chunk.toString('utf8');
-        if (journal)
-            enqueueEmit(() => journal.record({ runId: runId, entry: receivedJournalEntry('stderr', text) }));
-        enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'stderr', data: { chunk: text } } }));
-    });
-    child.stdin?.on('error', () => { });
-    child.on('error', () => { });
-    let session = null;
-    const unsubscribeCancel = lifecycle.onCancelRequested({ runId: runId, listener: () => {
-            cancelRequested = true;
-            session?.abort();
-            void terminateChildTreeBestEffort(ctx, child, runId, 'cancel', ctx.onCleanupFailure);
-        } });
-    child.on('close', (code, signal) => {
-        void (async () => {
-            await emitQueue;
-            unsubscribeCancel();
-            // Guarded for the same reasons as the child-driven handler above.
-            await cleanupStagedFilesSafely(ctx);
-            const status = cancelRequested ? 'cancelled' : session?.hasFatalError() ? 'failed' : 'succeeded';
-            const resumable = status === 'failed' && classifyFailure !== undefined
-                ? await classifyFailureSafely(ctx, classifyFailure, {
-                    runId,
-                    agentId,
-                    code,
-                    signal: signal ?? null,
-                    sideEffects: { userVisibleOutputSeen, toolCallSeen },
-                })
-                : false;
-            await lifecycle.finish({ runId, status, code, signal: signal ?? null, resumable }, { ...(capturedSessionId !== undefined ? { sessionRef: capturedSessionId } : {}) });
-        })();
-    });
-    session = ctx.attachPiRpcSession({ child: ctx.child, prompt: ctx.prompt, send({ payload }) {
-            const translation = translateAgentRuntimeEvent({ rawEvent: payload });
-            if (translation.kind === 'agent') {
-                if (translation.sessionId !== undefined)
-                    capturedSessionId = translation.sessionId;
-                if (translation.payload.type === 'tool_use') {
-                    toolCallSeen = true;
-                }
-                else if ((translation.payload.type === 'text_delta' || translation.payload.type === 'thinking_delta') &&
-                    translation.payload.delta.length > 0) {
-                    userVisibleOutputSeen = true;
-                }
-                enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'agent', data: translation.payload } }));
-            }
-            else if (translation.kind === 'error') {
-                enqueueEmit(() => lifecycle.emit({ runId: runId, input: { event: 'error', data: translation.payload } }));
-            }
-        } }, { cwd: ctx.cwd, ...(ctx.model !== undefined ? { model: ctx.model } : {}), ...(ctx.imagePaths.length > 0 ? { imagePaths: [...ctx.imagePaths] } : {}), ...(ctx.uploadRoot !== undefined ? { uploadRoot: ctx.uploadRoot } : {}) });
-    return session;
-}
-/**
- * Writes the initial user turn to the child's stdin per `def.promptInputFormat`
- * (both branches only run for `promptViaStdin: true` defs — the only shape
- * `run()` supports in v1, see module doc):
- * - `'text'` (default): the raw prompt buffer, then stdin is closed —
- *   matches `RuntimeAgentDef.promptInputFormat`'s own doc.
- * - `'stream-json'`: one JSONL line wrapping the prompt as an Anthropic
- *   user message; stdin is deliberately left open (a real multi-turn
- *   caller would inject further messages) — v1 has no such caller, so
- *   {@link wireChildLifecycle}'s `turn_end` handling closes it once the
- *   agent's own stream reports the turn ended.
- * @param def - The resolved agent def (only `.promptInputFormat` is read).
- * @param child - The spawned child (no-ops if `.stdin` is unexpectedly absent).
- * @param prompt - The composed user turn.
- * @param handle - Shared stdin-close guard so a `'text'` write's immediate close and a later `turn_end` close never race into a double-`end()`; also carries gap 1's byte-journal recorder (see `StdinCloseHandle.recordSentBytes`).
- * @complexity O(1) plus the underlying stream write's own cost.
- * @overallScore 100/100
- */
-function writePromptToStdin(def, child, prompt, handle) {
-    const stdin = child.stdin;
-    if (!stdin)
-        return;
-    if (def.promptInputFormat === 'stream-json') {
-        const line = JSON.stringify({ type: 'user', message: { role: 'user', content: [{ type: 'text', text: prompt }] } });
-        stdin.write(`${line}\n`, 'utf8');
-        handle.recordSentBytes(prompt);
-        return;
-    }
-    stdin.write(prompt, 'utf8');
-    handle.recordSentBytes(prompt);
-    handle.closeStdinOnce();
-}
-/**
- * Resolves `CreateAgentExecutorOptions`' agent-runtime collaborator seams (registry lookup, launch
- * resolution, ACP/pi-rpc session attachment, prompt/log file staging) to their real
- * `@jini-ai/agent-runtime` defaults. Split out of `createAgentExecutor` together with
- * {@link resolveProcessDeps}/{@link resolveMiscExecutorDeps}: a flat 14-line `options.x ?? default`
- * sequence was that function's entire cyclomatic-complexity excess (one branch point per default) —
- * grouping the same defaults by concern keeps each resulting function's own complexity low without
- * hiding which options belong together. Pure.
- */
-function resolveAgentRuntimeDeps(options) {
-    return {
-        getAgentDef: options.getAgentDef ?? getAgentDef,
-        resolveAgentLaunch: options.resolveAgentLaunch ?? resolveAgentLaunch,
-        ensureAgentCapabilities: options.ensureAgentCapabilities ?? ensureAgentCapabilities,
-        applyAgentLaunchEnv: options.applyAgentLaunchEnv ?? applyAgentLaunchEnv,
-        attachAcpSession: options.attachAcpSession ?? attachAcpSession,
-        attachPiRpcSession: options.attachPiRpcSession ?? attachPiRpcSession,
-        preparePromptFileForAgent: options.preparePromptFileForAgent ?? preparePromptFileForAgent,
-        prepareAgentLogFile: options.prepareAgentLogFile ?? prepareAgentLogFile,
-    };
-}
-/** Resolves the OS-process-facing collaborator seams — see {@link resolveAgentRuntimeDeps}'s doc. Pure. */
-function resolveProcessDeps(options) {
-    return {
-        createCommandInvocation: options.createCommandInvocation ?? createCommandInvocation,
-        spawn: options.spawn ?? nodeSpawn,
-        listProcessSnapshots: options.listProcessSnapshots ?? listProcessSnapshots,
-        collectProcessTreePids: options.collectProcessTreePids ?? (({ processes, rootPids }) => collectProcessTreePids(processes, rootPids)),
-        stopProcesses: options.stopProcesses ?? (({ pids }) => stopProcesses(pids)),
-    };
-}
-/** Resolves the two remaining defaultable options — see {@link resolveAgentRuntimeDeps}'s doc. Pure. */
-function resolveMiscExecutorDeps(options) {
-    return {
-        onCleanupFailure: options.onCleanupFailure ?? defaultCleanupFailureSink,
-        bufferedStdoutMaxBytes: options.bufferedStdoutMaxBytes ?? DEFAULT_BUFFERED_STDOUT_MAX_BYTES,
-    };
-}
-/** Phase 1: registry lookup + `assessAgentExecutorCompatibility` guard. */
-export async function resolveDefAndStreamFormat({ input, deps }) {
-    const def = deps.getAgentDef({ id: input.agentId });
-    if (!def) {
-        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_NOT_FOUND', message: `AgentExecutor: unknown agentId "${input.agentId}"` });
-    }
-    const compatibility = assessAgentExecutorCompatibility({ def: def });
-    if (!compatibility.supported) {
-        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_RUNTIME_UNSUPPORTED', message: compatibility.reason });
-    }
-    return { def, streamFormat: compatibility.streamFormat };
-}
-/** Phase 2: image-prompt-delivery augmentation + argv-budget guard for argv-bound defs. */
-export async function resolveImageDeliveryAndArgvBudget({ input, deps }) {
-    const imageDelivery = applyImagePromptDelivery({ imageDelivery: input.def.imageDelivery, prompt: input.prompt, imagePaths: input.imagePaths, extraAllowedDirs: input.extraAllowedDirs });
-    const argvBudgetError = checkPromptArgvBudget({ def: input.def, composed: imageDelivery.prompt });
-    if (argvBudgetError) {
-        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_PROMPT_TOO_LARGE', message: argvBudgetError.message });
-    }
-    return imageDelivery;
-}
-/**
- * Phase 3a: the subprocess environment this run's launch resolution and spawn should use — the
- * caller-supplied escape hatch verbatim, or the deny-by-default `BASELINE_AGENT_ENV_KEYS` allowlist.
- * Pure.
- */
-export function resolveRunEnv({ input, hostEnv }) {
-    return input.env !== undefined ? toStringEnvRecord(input.env) : buildAgentEnv(hostEnv, input.credentialEnv);
-}
-/** Phase 3b: launch-path resolution + binary-not-resolved guard. */
-export async function resolveLaunch({ input, deps }) {
-    const launch = deps.resolveAgentLaunch({ def: input.def }, { configuredEnv: input.resolvedEnv });
-    if (!launch.launchPath) {
-        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_BINARY_NOT_RESOLVED', message: `AgentExecutor: could not resolve an executable for agent "${input.def.id}" (bin "${input.def.bin}")` });
-    }
-    // Narrowed by the guard above; `resolveAgentLaunch`'s own return type still declares
-    // `launchPath: string | null` since it can't know this call site already checked.
-    return launch;
-}
-/** Phase 4a: stage a `promptViaFile` def's prompt to a temp file (a no-op for every other def). */
-export async function stagePromptFile({ input, deps }) {
-    try {
-        return await deps.preparePromptFileForAgent({ def: input.def, prompt: input.prompt, label: input.runId });
-    }
-    catch (err) {
-        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not stage a prompt file for agent "${input.def.id}": ${errorMessage(err)}` });
-    }
-}
-/** Phase 4b: stage a `needsAgentLogFile` def's diagnostic-log path (a no-op for every other def). */
-export async function stageLogFile({ input, deps }) {
-    try {
-        return await deps.prepareAgentLogFile({ def: input.def, label: input.runId });
-    }
-    catch (err) {
-        await (input.preparedPromptFile ? input.preparedPromptFile.cleanup() : Promise.resolve());
-        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not stage a log file for agent "${input.def.id}": ${errorMessage(err)}` });
-    }
-}
-/** Phase 5: resolves this run's MCP bridge delivery (credential resolution + {@link buildMcpBridgeDelivery}). */
-export async function resolveMcpBridgeForRun({ input, deps }) {
-    try {
-        // Awaited here rather than inside `buildMcpBridgeDelivery` so that function stays pure and
-        // synchronous. `undefined` when the host supplied no resolver, which omits the token entirely.
-        const credential = deps.mcpJsonInjection !== undefined ? await deps.mcpJsonInjection.credential?.({ runId: input.runId }) : undefined;
-        return buildMcpBridgeDelivery({
-            cwd: input.cwd,
-            runId: input.runId,
-            strategy: input.def.externalMcpInjection,
-            options: deps.mcpJsonInjection,
-            credential,
-        });
-    }
-    catch (err) {
-        // Spawning a child that cannot authenticate would produce a run whose every bridged tool call
-        // 401s, so a rejecting credential resolver fails the run before spawn instead.
-        await deps.cleanupStagedFiles();
-        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not resolve the MCP bridge credential for agent "${input.def.id}": ${errorMessage(err)}` });
-    }
-}
-/**
- * Phase 6a/10c: the subprocess environment every env-riding mechanism uses — mechanism 3+4
- * (`'opencode-env-content'`/`'mimo-env-content'`, merged into whatever the host already set there,
- * never a CLI argument: the config embeds `JINI_DAEMON_TOKEN`, and process arguments are readable
- * by any other local user through `ps`), mechanism 5 (`'codex-toml'`, `CODEX_HOME` relocation),
- * mechanism 6 (`'env-passthrough'`, the bridge entry's flat env vars set directly with no carrier
- * document — see {@link McpBridgeDelivery}'s own doc), a
- * `systemPromptDelivery: 'env-var'` def's overlay (`reasonix`'s `REASONIX_ACP_SYSTEM_APPEND` today
- * — see `resolveSystemPromptOverlayDelivery`'s own doc), and a `'config-instructions-file'` def's
- * staged overlay file (`opencode` today — see {@link mergeEnvContentInstructions}'s own doc). Pure
- * — `codexHomeDir` and `stagedInstructionsFile` arrive already staged by
- * {@link prepareCodexHomeIfNeeded} and {@link prepareSystemPromptOverlayFileIfNeeded} respectively,
- * the only parts of this mechanism that are NOT pure (real `mkdtemp`/`writeFile` calls).
- * @param spawnEnv - The env every other spawn-time step (launch-path resolution, `applyAgentLaunchEnv`) already computed.
- * @param mcpBridge - This run's resolved bridge delivery, or `null` for an unconfigured host / no-strategy def.
- * @param codexHomeDir - The staged scratch `CODEX_HOME` path for a `'codex-toml'` def, or `undefined` for every other run (including a `'codex-toml'` def when `mcpJsonInjection` was never configured — see `prepareCodexHomeIfNeeded`'s own gate).
- * @param systemPromptEnvOverrides - `resolveSystemPromptOverlayDelivery`'s `envOverrides` — `{}` (default) for every def but an `'env-var'`-strategy one with an overlay present, in which case it carries that one var. Applied after `codexHomeDir`, so it can never be shadowed by it — the two never share a key (`CODEX_HOME` vs. e.g. `REASONIX_ACP_SYSTEM_APPEND`), so the ordering is a documentation choice, not a correctness one.
- * @param stagedInstructionsFile - `varName` (from the def's own `systemPromptDelivery` declaration) and the staged overlay file's `path`, or `undefined` for every def but a `'config-instructions-file'` one with an overlay present. Merged into `varName`'s value AFTER the `mcp` merge above (reading `envContentApplied`, not the original `spawnEnv`, for that same key) so both a `mcp` entry and an `instructions` entry from the two mechanisms survive together in one document — confirmed live this coexistence is safe (see {@link mergeEnvContentInstructions}'s doc).
- * @complexity O(1) plus `mergeEnvContentMcpConfig`'s and `mergeEnvContentInstructions`'s own `JSON.parse`/`JSON.stringify` cost.
- * @overallScore 100/100
- */
-export function computeChildEnv({ spawnEnv, mcpBridge }, { codexHomeDir, systemPromptEnvOverrides, stagedInstructionsFile, claudeConfigDir } = {}) {
-    const envContentApplied = mcpBridge?.kind === 'env-content'
-        ? {
-            ...spawnEnv,
-            [mcpBridge.envVarName]: mergeEnvContentMcpConfig({ existingRaw: spawnEnv[mcpBridge.envVarName], entry: mcpBridge.serverEntry }),
-        }
-        : spawnEnv;
-    // `'env-passthrough'` (antigravity): no document, no named carrier variable — the bridge
-    // entry's own `env` keys (`JINI_RUN_ID`/`JINI_DAEMON_URL`/`JINI_DAEMON_TOKEN`) are set directly
-    // on the child's environment, for the spawned CLI to inherit down to its own globally
-    // pre-registered MCP child in turn. See `McpBridgeDelivery`'s own doc for why this def has no
-    // config document to merge into at all.
-    const envPassthroughApplied = mcpBridge?.kind === 'env-passthrough' ? { ...envContentApplied, ...mcpBridge.serverEntry.env } : envContentApplied;
-    const instructionsApplied = stagedInstructionsFile === undefined
-        ? envPassthroughApplied
-        : {
-            ...envPassthroughApplied,
-            [stagedInstructionsFile.varName]: mergeEnvContentInstructions({ existingRaw: envPassthroughApplied[stagedInstructionsFile.varName], instructionsFilePath: stagedInstructionsFile.path }),
-        };
-    const codexHomeApplied = codexHomeDir === undefined ? instructionsApplied : { ...instructionsApplied, CODEX_HOME: codexHomeDir };
-    // Finding 1 of SEC-assistant-env-isolation-2026-09-07: same "only set when staged" shape as
-    // codexHomeApplied above — mutually exclusive with it in practice (codexHomeDir is only ever set
-    // for a 'codex-toml' bridge, claudeConfigDir only ever for a `claude`-id run), so both existing
-    // side by side here is a documentation convenience, not a real collision risk.
-    const claudeConfigDirApplied = claudeConfigDir === undefined ? codexHomeApplied : { ...codexHomeApplied, CLAUDE_CONFIG_DIR: claudeConfigDir };
-    return systemPromptEnvOverrides === undefined ? claudeConfigDirApplied : { ...claudeConfigDirApplied, ...systemPromptEnvOverrides };
-}
-/**
- * Phase 6b: the `RuntimeContext` `buildArgs` receives — `undefined` unless a file, bridge path, or
- * session id was staged. Pure.
- *
- * `resumeSessionId`/`newSessionId` round-trip a prior run's `RunEndPayload.sessionRef` (see
- * `@jini-ai/protocol`'s doc on that field) back into this run's `RuntimeContext`, letting a
- * `resumesSessionViaCli` def (e.g. claude) continue its own CLI session across turns instead of
- * spawning cold every time. Either one alone must still produce a context — a run supplying ONLY a
- * session id, with no prompt/log file staged and no claude-mcp-json bridge, is exactly the common
- * case for a resumed turn.
- */
-export function computeRuntimeContext({ preparedPromptFile, preparedLogFile, mcpBridge }, { resumeSessionId, newSessionId } = {}) {
-    // Matches claude.ts buildArgs' own `typeof x === 'string' && x` truthiness check, so an empty
-    // string or explicit `null` (no resume target yet) is treated as absent here too, rather than
-    // manufacturing a context that carries a session field the def would ignore anyway.
-    const hasResumeSessionId = typeof resumeSessionId === 'string' && resumeSessionId.length > 0;
-    const hasNewSessionId = typeof newSessionId === 'string' && newSessionId.length > 0;
-    if (!preparedPromptFile
-        && !preparedLogFile
-        && mcpBridge?.kind !== 'claude-mcp-json'
-        && !hasResumeSessionId
-        && !hasNewSessionId) {
-        return undefined;
-    }
-    return {
-        ...(preparedPromptFile ? { promptFilePath: preparedPromptFile.path } : {}),
-        ...(preparedLogFile ? { agentLogFilePath: preparedLogFile.path } : {}),
-        // Safe to pass before the file exists: `writeMcpJsonForRun` runs after buildArgs but still
-        // before spawn, so the path is real by the time the child process starts.
-        ...(mcpBridge?.kind === 'claude-mcp-json' ? { mcpJsonPath: mcpBridge.mcpJsonPath } : {}),
-        ...(hasResumeSessionId ? { resumeSessionId } : {}),
-        ...(hasNewSessionId ? { newSessionId } : {}),
-    };
-}
-/**
- * Phase 7: acquires a `runtimeLock` def's process-global mutex before `buildArgs` runs — see
- * `RuntimeLock`'s own doc for the concrete race. A no-op (`undefined`) for the 23 of 24 defs with no
- * `runtimeLock` declared.
- */
-async function acquireRuntimeLockIfConfigured(def, model) {
-    return def.runtimeLock?.acquire({ model });
-}
-/**
- * Phase 8: the host's `PromptAugmenter.systemOverlay()` result, if configured — see
- * `CreateAgentExecutorOptions.promptAugmenter`'s doc for `turnIndex`'s coarse 0/1 proxy.
- */
-function computeSystemPromptOverlay(promptAugmenter, agentId, runtimeContext) {
-    return promptAugmenter?.systemOverlay?.({
-        agentId,
-        turnIndex: runtimeContext?.hasPriorAssistantTurn ? 1 : 0,
-    });
-}
-/** Phase 9a: the def's `buildArgs` 4th argument. Historically omitted when every override was absent;
- * that let defs silently enable auto-approval. Always supply the validated restricted default now. Pure. */
-export function buildAgentBuildArgsOptions({ input, systemPromptOverlay }) {
-    const permissionMode = input.permissionMode ?? 'restricted';
-    if (permissionMode !== 'restricted' && permissionMode !== 'bypass') {
-        throw new AgentExecutorError({ code: 'AGENT_PERMISSION_MODE_INVALID', message: 'AgentExecutor: permissionMode must be restricted or bypass' });
-    }
-    const hasOverlay = systemPromptOverlay !== undefined && systemPromptOverlay !== null;
-    const options = {
-        ...(input.model !== undefined ? { model: input.model } : {}),
-        ...(input.reasoning !== undefined ? { reasoning: input.reasoning } : {}),
-        permissionMode,
-        ...(input.disallowedTools !== undefined ? { disallowedTools: input.disallowedTools } : {}),
-        ...(input.allowedTools !== undefined ? { allowedTools: input.allowedTools } : {}),
-        ...(input.settingSources !== undefined ? { settingSources: input.settingSources } : {}),
-        ...(input.settings !== undefined ? { settings: input.settings } : {}),
-        ...(hasOverlay ? { systemPromptOverlay } : {}),
-    };
-    return Object.keys(options).length === 0 ? undefined : options;
-}
-/**
- * **The single dispatch point from a computed system-prompt overlay to its delivery mechanism** —
- * see `RuntimeAgentDef.systemPromptDelivery`'s own doc for the declared shape. Pure and
- * synchronous, mirroring {@link buildMcpBridgeDelivery}'s "keyed off the declared strategy, never
- * off the def's id" contract: a def earns overlay delivery by declaring a strategy, not by being
- * named in this file. That is what makes every def with no declaration work via the fallback
- * without any of their own files being touched.
- *
- * The fallback (no declared strategy — every def but `claude` today) prefixes the overlay directly
- * onto the composed prompt text, clearly delimited from the user's own request. It is gated on
- * session state, not merely on whether an overlay exists: a def that carries its own conversation
- * memory across spawns (`resumesSessionViaCli` / `resumesSessionViaAcpLoad`) persists whatever its
- * session-creating turn sends it — see `RuntimeContext.resumeSessionId`'s own doc: its presence on
- * a run means "continue a prior session", not "start one". Prefixing on every later turn of that
- * same session would therefore bake the overlay into the CLI's own stored history again and again,
- * compounding without bound turn over turn. So the fallback prefixes only when there is no resume
- * target yet (the session's own first turn, or a def with no session memory at all, which never
- * replays anything back at the CLI and so gets it on every turn).
- *
- * `'append-flag'` and `'env-var'` defs are the opposite case: the flag/env var is a fresh,
- * un-stored per-spawn directive — never part of what a resumed session replays — so it is set on
- * every turn unconditionally, exactly `claude`'s pre-existing (now-centralized) behavior before
- * this function existed.
- *
- * @param input.defId - Looks up this def's probed capabilities for an `'append-flag'` strategy's
- * `capabilityKey`. Otherwise unused — the dispatch itself is keyed off `systemPromptDelivery`, per
- * this function's own doc above, never off the id.
- * @param input.systemPromptDelivery - The def's declared strategy, or `undefined` for the fallback.
- * @param input.resumesSessionViaCli - The def's own flag (see `RuntimeAgentDef`'s doc).
- * @param input.resumesSessionViaAcpLoad - The def's own flag (see `RuntimeAgentDef`'s doc).
- * @param input.overlay - The computed `PromptAugmenter.systemOverlay()` result. `null`/`undefined`/
- * empty short-circuits to "no delivery" — byte-identical to no `PromptAugmenter` configured at all.
- * @param input.prompt - The composed prompt `buildArgs` would otherwise receive verbatim.
- * @param input.resumeSessionId - This run's `RuntimeContext.resumeSessionId`; presence means an
- * existing session is being continued, not created.
- * @returns A {@link SystemPromptOverlayDelivery}: the prefix this run's prompt text must carry
- * (`''` unless the fallback applies), that prefix already applied to `input.prompt`, any extra argv
- * to append to whatever `buildArgs` itself returns, and any env var overrides to merge into the
- * spawn env (`{}` for every strategy but `'env-var'`). Every one of `run()`'s four prompt
- * transports consumes this same result — see the interface's own no-double-delivery note.
- * @complexity O(n) in the overlay/prompt lengths — string concatenation only, no I/O.
- * @overallScore 100/100
- */
-export function resolveSystemPromptOverlayDelivery(input) {
-    const { defId, systemPromptDelivery, resumesSessionViaCli, resumesSessionViaAcpLoad, overlay, prompt, resumeSessionId } = input;
-    if (typeof overlay !== 'string' || overlay.length === 0) {
-        return { promptPrefix: '', prompt, extraArgs: [], envOverrides: {} };
-    }
-    if (systemPromptDelivery?.strategy === 'append-flag') {
-        const capabilityKey = systemPromptDelivery.capabilityKey;
-        // `!== false`, not a truthiness check: mirrors `claude.ts`'s own pre-existing
-        // `agentCapabilities.get('claude') || {}` gate exactly (moved here, not changed) — an
-        // undetected/never-probed capability defaults to allowed, and only an EXPLICIT `false` (the
-        // `--help` probe ran and did not find the flag) withholds it. `capabilityKey === undefined`
-        // (e.g. `pi`'s existing `--append-system-prompt`, trusted unconditionally) always passes, same
-        // as an absent key.
-        const capabilityOk = capabilityKey === undefined || agentCapabilities.get(defId)?.[capabilityKey] !== false;
-        return { promptPrefix: '', prompt, extraArgs: capabilityOk ? [systemPromptDelivery.flag, overlay] : [], envOverrides: {} };
-    }
-    if (systemPromptDelivery?.strategy === 'env-var') {
-        // No capability gate, unlike `'append-flag'`: an unrecognized env var is inert to a CLI (it
-        // simply never reads it), never a fatal "unknown option" exit — there is no equivalent hazard
-        // to probe-gate against here. Set verbatim, not merged with any existing value — a dedicated
-        // single-purpose var, not a shared config channel (see this field's own `types.ts` doc).
-        return { promptPrefix: '', prompt, extraArgs: [], envOverrides: { [systemPromptDelivery.varName]: overlay } };
-    }
-    if (systemPromptDelivery?.strategy === 'config-instructions-file') {
-        // Delivered elsewhere, not here: unlike `'append-flag'`/`'env-var'`, this mechanism needs real
-        // filesystem I/O (staging the overlay to a temp file — `opencode`'s `instructions` array only
-        // accepts a file path or URL, confirmed live, never inline text), which this function's "pure
-        // and synchronous" contract cannot perform. `prepareSystemPromptOverlayFileIfNeeded` (a separate
-        // async phase in `run()`, gated on this same strategy check) stages the file, and
-        // `computeChildEnv` merges its path into the config document via `mergeEnvContentInstructions`.
-        // This branch's only job is to make sure the universal prefix fallback below does NOT ALSO run
-        // for a def that already has this strategy declared — the same "no double delivery" concern
-        // `imageDelivery`'s doc calls out for its own native-vs-fallback split.
-        return { promptPrefix: '', prompt, extraArgs: [], envOverrides: {} };
-    }
-    const isContinuingExistingSession = (resumesSessionViaCli === true || resumesSessionViaAcpLoad === true) &&
-        typeof resumeSessionId === 'string' &&
-        resumeSessionId.length > 0;
-    if (isContinuingExistingSession) {
-        return { promptPrefix: '', prompt, extraArgs: [], envOverrides: {} };
-    }
-    // KNOWN TRADE-OFF, deliberate: for a resume-capable def with no `'append-flag'`/`'env-var'`
-    // mechanism yet (`codex`, `codebuddy`, `opencode`, `amr` — all four presently on this fallback),
-    // the overlay is therefore only injected on the SESSION-CREATING turn, not every turn. A host
-    // whose `PromptAugmenter.systemOverlay()` result can change mid-conversation (e.g. a host that
-    // lets an operator edit its own stored instructions and re-reads them before every run — see
-    // `prompt-augmenter.ts`'s own doc for the seam) will see NO effect from such an edit until a NEW
-    // session starts for one of these four defs specifically — a real, silent limitation, not a
-    // theoretical one. This is the correct
-    // trade against the alternative (re-injecting every turn would bake the overlay into that def's
-    // own CLI-persisted session history again and again, compounding without bound) — do not change
-    // this gating to "fix" the staleness. The actual fix is giving each of the four its own
-    // `'append-flag'`-equivalent `systemPromptDelivery` (an argv flag or an env var, neither of which
-    // is part of what a resumed session replays), which removes this limitation entirely for that
-    // def. See `reasonix.ts`'s and `opencode.ts`'s module docs for the two already-identified,
-    // not-yet-wired native mechanisms.
-    const promptPrefix = `${overlay}\n\n---\n\n`;
-    return { promptPrefix, prompt: `${promptPrefix}${prompt}`, extraArgs: [], envOverrides: {} };
-}
-/**
- * Phase 9b: calls the def's `buildArgs`, releasing staged resources and failing the run on a throw.
- *
- * @param input.overlayDelivery - This run's already-resolved overlay decision, computed once in
- * `run()` rather than here. It is resolved upstream because `buildArgs` is only ONE of the four
- * channels that can carry the prompt: the staged prompt file is written *before* this function
- * runs, and stdin/ACP/pi-rpc send theirs *after* spawn. A decision made inside this function could
- * therefore only ever reach the 7 defs whose `buildArgs` reads its first argument at all — the
- * other 17 declare it `_prompt` and discard it, which is exactly how the overlay used to go missing.
- */
-export async function buildRunArgs({ input, deps }) {
-    try {
-        const delivery = input.overlayDelivery;
-        const options = buildAgentBuildArgsOptions({ input: input.runInput, systemPromptOverlay: input.systemPromptOverlay });
-        const args = input.def.buildArgs({ prompt: delivery.prompt, imagePaths: [...(input.imagePaths ?? [])] }, {
-            ...(input.imageDelivery.extraAllowedDirs === undefined ? {} : { extraAllowedDirs: [...input.imageDelivery.extraAllowedDirs] }),
-            ...(options === undefined ? {} : { options }),
-            ...(input.runtimeContext === undefined ? {} : { runtimeContext: input.runtimeContext }),
-        });
-        // `'append-flag'` delivery's extra argv (empty for every other def/strategy) is appended after
-        // whatever the def's own `buildArgs` returned — safe because it is only ever non-empty for a
-        // `promptViaStdin` def with no trailing positional argv (`claude`/`pi` today; see
-        // `resolveSystemPromptOverlayDelivery`'s doc for why a future 'append-flag' def must keep that
-        // property too). `envOverrides` (non-empty only for `'env-var'` — `reasonix` today) is handed
-        // back rather than applied here, since the spawn env isn't finalized until `computeChildEnv`
-        // runs, later in `run()`.
-        return { args: [...args, ...delivery.extraArgs], envOverrides: delivery.envOverrides };
-    }
-    catch (err) {
-        await deps.releaseStagedResources();
-        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not build launch arguments for agent "${input.def.id}": ${errorMessage(err)}` });
-    }
-}
-/** Phase 10: mechanism 1 of 5's one effect — stages this run's own `.mcp.json`, returning the path `cleanupStagedFiles` should later remove (`undefined` for every other mechanism / unconfigured host). */
-export async function writeMcpJsonIfNeeded({ input, deps }) {
-    if (input.mcpBridge?.kind !== 'claude-mcp-json' || deps.mcpJsonInjection === undefined) {
-        return undefined;
-    }
-    try {
-        await writeMcpJsonForRun(input.cwd, input.mcpBridge, deps.mcpJsonInjection);
-        return input.mcpBridge.mcpJsonPath;
-    }
-    catch (err) {
-        await deps.releaseStagedResources();
-        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not write .mcp.json for agent "${input.def.id}": ${errorMessage(err)}` });
-    }
-}
-/**
- * Phase 10b1: `systemPromptDelivery: { strategy: 'config-instructions-file' }`'s one effect —
- * stages the computed overlay to a fresh, run-scoped temp file, so `computeChildEnv` has a real
- * path to merge into that def's `instructions` config array (see
- * {@link mergeEnvContentInstructions}'s own doc for the live verification this mechanism rests on).
- * `null` for every other strategy, an unset `systemPromptDelivery`, or no overlay present at all —
- * byte-identical to before this mechanism existed, matching {@link writeMcpJsonIfNeeded}'s and
- * {@link prepareCodexHomeIfNeeded}'s identical no-op-when-inapplicable gate.
- *
- * `opencode`'s `instructions` field only accepts a file path or a remote URL — confirmed live
- * (2026-09-01): a literal instruction string in the array is silently ignored (no error, just never
- * honored), so an inline-text shortcut is not available and this staging step is load-bearing, not
- * a defensive extra.
- * @param input.def - Only used for its `id`, in the failure message, and its `systemPromptDelivery` declaration.
- * @param input.overlay - The computed `PromptAugmenter.systemOverlay()` result for this run.
- * @complexity O(1) plus one directory creation and one file write.
- * @overallScore 100/100
- */
-export async function prepareSystemPromptOverlayFileIfNeeded({ input, deps }) {
-    if (input.def.systemPromptDelivery?.strategy !== 'config-instructions-file' ||
-        typeof input.overlay !== 'string' ||
-        input.overlay.length === 0) {
-        return null;
-    }
-    try {
-        const safeRunId = input.runId.replace(/[^A-Za-z0-9_-]/g, '-').slice(0, 80) || 'run';
-        const dir = await fsPromises.mkdtemp(join(tmpdir(), `jini-system-prompt-overlay-${safeRunId}-`));
-        const filePath = join(dir, 'overlay.md');
-        await fsPromises.writeFile(filePath, input.overlay, { encoding: 'utf8', mode: 0o600 });
-        return {
-            path: filePath,
-            cleanup: async () => {
-                await fsPromises.rm(dir, { recursive: true, force: true });
-            },
-        };
-    }
-    catch (err) {
-        await deps.releaseStagedResources();
-        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not stage a system-prompt overlay file for agent "${input.def.id}": ${errorMessage(err)}` });
-    }
-}
-/**
- * Phase 10b: mechanism 5 of 5's one effect — stages this run's scratch `CODEX_HOME` directory,
- * returning the prepared handle `cleanupStagedFiles` should later release (`null` for every other
- * mechanism, or for an unconfigured host — matching {@link writeMcpJsonIfNeeded}'s identical gate).
- * @param input.def - Only used for its `id`, in the failure message.
- * @param input.mcpBridge - This run's resolved bridge delivery — a no-op unless its `kind` is `'codex-toml'`.
- * @param deps.hostEnv - The daemon's own environment, threaded through to {@link resolveSourceCodexHomeDir} rather than read from a module-level `process.env` so this phase stays testable with an injected env.
- * @complexity O(1) plus {@link prepareCodexHomeForRun}'s own cost.
- * @overallScore 100/100
- */
-export async function prepareCodexHomeIfNeeded({ input, deps }) {
-    if (input.mcpBridge?.kind !== 'codex-toml' || deps.mcpJsonInjection === undefined) {
-        return null;
-    }
-    try {
-        return await prepareCodexHomeForRun(input.runId, input.mcpBridge.serverEntry, resolveSourceCodexHomeDir({ hostEnv: deps.hostEnv }), resolveCodexHomeSeams(deps.mcpJsonInjection));
-    }
-    catch (err) {
-        await deps.releaseStagedResources();
-        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not stage a CODEX_HOME for agent "${input.def.id}": ${errorMessage(err)}` });
-    }
-}
-/**
- * Finding 1 of SEC-assistant-env-isolation-2026-09-07's one effect — stages this run's scratch
- * `CLAUDE_CONFIG_DIR` directory, returning the prepared handle `cleanupStagedFiles` should later
- * release (`null` for every def other than `claude` — see {@link prepareClaudeConfigDirForRun}'s
- * own doc for why this is unconditional for `claude` runs, unlike {@link prepareCodexHomeIfNeeded}'s
- * gate on a host-configured MCP bridge strategy).
- *
- * Gated on `def.id === 'claude'` directly rather than on `externalMcpInjection === 'claude-mcp-json'`
- * (which `codebuddy` also declares): isolating the operator's personal `~/.claude` is specific to
- * the real `claude` CLI's own config resolution, not to every def that happens to share its `.mcp.
- * json` delivery shape. Matches the existing `USER`-for-claude-login special case already singled
- * out by id in `BASELINE_AGENT_ENV_KEYS`'s own doc, a few hundred lines above.
- *
- * ALSO gated on `deps.enabled` (`CreateAgentExecutorOptions.claudeConfigDirIsolationEnabled`, default
- * `false`) since this task's own fix — see that field's doc for why it defaults off (Keychain login
- * is `CLAUDE_CONFIG_DIR`-keyed and no caller was supplying a credential when this was unconditional).
- * `def.id === 'claude'` is still checked first and independently: a host that flips this flag on
- * should not suddenly stage a directory for `codebuddy` or any other def.
- * @param input.def - Used for both the `id` gate and the failure message.
- * @param deps.enabled - The isolation on/off switch — see this function's own doc above.
- * @param deps.hostEnv - The daemon's own environment, threaded through to {@link resolveSourceClaudeConfigDir} rather than read from a module-level `process.env`, matching {@link prepareCodexHomeIfNeeded}'s identical testability reasoning.
- * @complexity O(1) plus {@link prepareClaudeConfigDirForRun}'s own cost.
- */
-export async function prepareClaudeConfigDirIfNeeded({ input, deps }) {
-    if (input.def.id !== 'claude' || !deps.enabled) {
-        return null;
-    }
-    try {
-        return await prepareClaudeConfigDirForRun(input.runId, resolveSourceClaudeConfigDir({ hostEnv: deps.hostEnv }), resolveClaudeConfigDirSeams(deps.claudeConfigDirIsolation));
-    }
-    catch (err) {
-        await deps.releaseStagedResources();
-        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not stage a CLAUDE_CONFIG_DIR for agent "${input.def.id}": ${errorMessage(err)}` });
-    }
-}
-/** Phase 11: post-`buildArgs` guard for argv-bound defs whose resolved binary is a Windows shim/.exe — a no-op off-Windows and for non-argv-bound defs. */
-export async function guardWindowsCommandLineBudget({ input, deps }) {
-    const windowsBudgetError = checkWindowsCmdShimCommandLineBudget({ def: input.def, resolvedBin: input.launchPath, args: input.args }) ??
-        checkWindowsDirectExeCommandLineBudget({ def: input.def, resolvedBin: input.launchPath, args: input.args });
-    if (windowsBudgetError) {
-        await deps.releaseStagedResources();
-        await deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_PROMPT_TOO_LARGE', message: windowsBudgetError.message });
-    }
-}
-/**
- * Phase 12: the real `node:child_process.spawn` call.
- *
- * **Deliberately synchronous, unlike every other phase in this file.** A spawned child can emit
- * `'error'` on the very next microtask tick (Node schedules it eagerly on some failure modes, and a
- * test harness simulating "the child emits 'error' before 'spawn'" does so explicitly via
- * `queueMicrotask`). `run()` must register its `'error'` listeners (`wireChildLifecycle`'s safety net,
- * then `waitForSpawnOrError`'s `child.once('error', reject)`) in the *same synchronous turn* as this
- * spawn call — Node's `EventEmitter` throws synchronously when `'error'` fires with zero listeners
- * attached. Wrapping this call in an `async function` and `await`ing it (as every other phase here
- * does) would insert a microtask tick between spawn and listener registration, occasionally losing
- * that race — confirmed by a real test failure during this refactor (an uncaught `EventEmitter`
- * `'error'` exception) before this function was changed back to a plain, unawaited call returning a
- * result object instead of throwing/rejecting.
- * @returns `{kind:'ok', child}` on success, `{kind:'error', error}` on a synchronous throw from `spawn`
- * — `run()` itself is responsible for cleanup and `failBeforeSpawn` on the error variant, both of
- * which are safe to make asynchronous since no child (and hence no listener race) exists yet.
- * @complexity O(1) plus `spawn`'s own cost.
- */
-export function spawnAgentChildProcess({ input, deps }) {
-    try {
-        return {
-            kind: 'ok',
-            child: deps.spawn(input.invocation.command, input.invocation.args, {
-                cwd: input.cwd,
-                env: input.childEnv,
-                stdio: ['pipe', 'pipe', 'pipe'],
-                windowsVerbatimArguments: input.invocation.windowsVerbatimArguments,
-            }),
-        };
-    }
-    catch (error) {
-        return { kind: 'error', error };
-    }
-}
-/** Named predicate replacing an inline `streamFormat === 'acp-json-rpc' || streamFormat === 'pi-rpc'` check — the two formats that own their own prompt/event protocol and skip `wireChildLifecycle`. */
-export function isStdinDrivenFormat(args) {
-    const { streamFormat } = args;
-    return streamFormat !== 'acp-json-rpc' && streamFormat !== 'pi-rpc';
-}
-/** Phase 13: awaits spawn confirmation, routing a failure through the same `failBeforeSpawn` shape every earlier guard uses. */
-export async function confirmChildSpawned({ input, deps }) {
-    try {
-        await waitForSpawnOrError(input.child);
-    }
-    catch (err) {
-        await deps.releaseStagedResources();
-        await deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: failed to spawn agent "${input.def.id}": ${errorMessage(err)}` });
-    }
-}
-/** Phase 14: starts a `runtimeLock` def's handoff watcher once a live process exists to consume the locked side effect — a no-op when the def declared no `waitForHandoff`. Deliberately not awaited; see `RuntimeLockHold.waitForHandoff`'s own doc. */
-export function armHandoffWatcher({ runtimeLockHold, handoffInput, release }) {
-    if (!runtimeLockHold?.waitForHandoff)
-        return;
-    void runtimeLockHold.waitForHandoff(handoffInput).then(release, release);
-}
-/** Phase 15 (ACP branch): attaches the ACP session, escalating process-tree teardown and failing the run through `failBeforeSpawn` on an attach-time throw. */
-export async function runAcpDispatch({ input, deps }) {
-    try {
-        wireAcpLifecycle({
-            runId: input.runId,
-            agentId: input.agentId,
-            child: input.child,
-            lifecycle: deps.lifecycle,
-            prompt: input.prompt,
-            cwd: input.cwd,
-            model: input.model,
-            imagePaths: input.imagePaths,
-            envFormat: input.envFormat,
-            // Mechanism 2 of 5 — see `WireAcpLifecycleContext.mcpServers`. `undefined` for any def that
-            // did not declare `'acp-merge'` and for an unconfigured host.
-            mcpServers: input.mcpBridge?.kind === 'acp-merge' ? input.mcpBridge.mcpServers : undefined,
-            onPermissionRequest: deps.onPermissionRequest,
-            attachAcpSession: deps.attachAcpSession,
-            listProcessSnapshots: deps.listProcessSnapshots,
-            collectProcessTreePids: deps.collectProcessTreePids,
-            stopProcesses: deps.stopProcesses,
-            onCleanupFailure: deps.onCleanupFailure,
-            cleanupStagedFiles: deps.cleanupStagedFiles,
-            journal: deps.journal,
-            classifyFailure: deps.classifyFailure,
-        });
-    }
-    catch (err) {
-        // Unlike the cancellation-listener call sites, we are already in an async function about to
-        // call finish() and throw — nothing else races this, so cleanup is awaited here rather than
-        // fired-and-forgotten (SEC-007: "await where lifecycle ordering allows it").
-        await terminateChildTreeBestEffort({ listProcessSnapshots: deps.listProcessSnapshots, collectProcessTreePids: deps.collectProcessTreePids, stopProcesses: deps.stopProcesses }, input.child, input.runId, 'acp-attach-failure', deps.onCleanupFailure);
-        await deps.releaseStagedResources();
-        await deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not attach ACP session for agent "${input.agentId}": ${errorMessage(err)}` });
-    }
-}
-/** Phase 15 (pi-rpc branch): same discipline as {@link runAcpDispatch}, for the one `'pi-rpc'` def. */
-export async function runPiRpcDispatch({ input, deps }) {
-    try {
-        wirePiRpcLifecycle({
-            runId: input.runId,
-            agentId: input.agentId,
-            child: input.child,
-            lifecycle: deps.lifecycle,
-            prompt: input.prompt,
-            cwd: input.cwd,
-            model: input.model,
-            imagePaths: input.imagePaths,
-            uploadRoot: input.uploadRoot,
-            attachPiRpcSession: deps.attachPiRpcSession,
-            listProcessSnapshots: deps.listProcessSnapshots,
-            collectProcessTreePids: deps.collectProcessTreePids,
-            stopProcesses: deps.stopProcesses,
-            onCleanupFailure: deps.onCleanupFailure,
-            cleanupStagedFiles: deps.cleanupStagedFiles,
-            journal: deps.journal,
-            classifyFailure: deps.classifyFailure,
-        });
-    }
-    catch (err) {
-        // Same discipline as the ACP attach-failure path above: await cleanup here rather than
-        // fire-and-forget (SEC-007).
-        await terminateChildTreeBestEffort({ listProcessSnapshots: deps.listProcessSnapshots, collectProcessTreePids: deps.collectProcessTreePids, stopProcesses: deps.stopProcesses }, input.child, input.runId, 'pi-rpc-attach-failure', deps.onCleanupFailure);
-        await deps.releaseStagedResources();
-        await deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not attach pi-rpc session for agent "${input.agentId}": ${errorMessage(err)}` });
-    }
-}
-export function createAgentExecutor(requiredArgs, optionalArgs = {}) {
-    const options = { ...requiredArgs, ...optionalArgs };
-    const lifecycle = options.lifecycle;
-    const { getAgentDef: getAgentDefFn, resolveAgentLaunch: resolveAgentLaunchFn, ensureAgentCapabilities: ensureAgentCapabilitiesFn, applyAgentLaunchEnv: applyAgentLaunchEnvFn, attachAcpSession: attachAcpSessionFn, attachPiRpcSession: attachPiRpcSessionFn, preparePromptFileForAgent: preparePromptFileForAgentFn, prepareAgentLogFile: prepareAgentLogFileFn, } = resolveAgentRuntimeDeps(options);
-    const { createCommandInvocation: createCommandInvocationFn, spawn: spawnFn, listProcessSnapshots: listProcessSnapshotsFn, collectProcessTreePids: collectProcessTreePidsFn, stopProcesses: stopProcessesFn, } = resolveProcessDeps(options);
-    const { onCleanupFailure: onCleanupFailureFn, bufferedStdoutMaxBytes } = resolveMiscExecutorDeps(options);
-    const journal = options.journal;
-    const continuation = options.continuation;
-    const classifyFailure = options.classifyFailure;
-    const mcpJsonInjection = options.mcpJsonInjection;
-    const claudeConfigDirIsolation = options.claudeConfigDirIsolation;
-    const claudeConfigDirIsolationEnabled = options.claudeConfigDirIsolationEnabled ?? false;
-    const promptAugmenter = options.promptAugmenter;
-    /**
-     * Transitions `runId` to `'failed'` (idempotent, never resumable — no
-     * classifier exists, see module doc) then rejects with a typed
-     * {@link AgentExecutorError}. Every pre-spawn guard in `run()` returns
-     * this call directly.
-     * @param runId - The run to transition.
-     * @param code - The machine-readable failure reason.
-     * @param message - The human-readable rejection message.
-     * @throws Always — this function never returns normally.
-     * @complexity O(1) plus `lifecycle.finish()`'s own cost.
-     * @overallScore 100/100
-     */
-    async function failBeforeSpawn({ runId, code, message }) {
-        // The reason goes on the run's own stream before `end`, not only into the thrown error: the
-        // thrown error reaches the server log, while a chat client sees only this stream. Without it
-        // the user got a bare "Run failed". Best-effort: a stream that will not take the event must not
-        // stop the run from finishing.
-        await lifecycle
-            .emit({ runId: runId, input: { event: 'error', data: { message: `The assistant could not start: ${message.replace(/^AgentExecutor:\s*/, '')}` } } })
-            .catch(() => undefined);
-        await lifecycle.finish({ runId, status: 'failed', code: null, signal: null, resumable: false });
-        throw new AgentExecutorError({ code: code, message: message });
-    }
-    /**
-     * `AgentExecutor.run()` — see that interface method's own doc for the
-     * public contract. Implementation note on shape: every guard below
-     * returns `failBeforeSpawn(...)` directly (a `Promise<never>`, valid
-     * wherever `Promise<void>` is expected) rather than `await`-then-`return`,
-     * so each failure path reads as a single, obviously-terminal statement.
-     * @param input - `{runId, agentId, prompt, cwd, model?, reasoning?, imagePaths?, extraAllowedDirs?, uploadRoot?, env?}` — `runId` must already be `lifecycle.start()`-ed.
-     * @throws {@link AgentExecutorError} — see module doc's Invariant; never a bare `Error`.
-     * @complexity O(1) setup (registry lookup, launch resolution, one spawn call); steady-state cost thereafter belongs to {@link wireChildLifecycle}.
-     * @overallScore 100/100
-     */
-    async function run(requiredArgs, optionalArgs = {}) {
-        const input = { ...requiredArgs, ...optionalArgs, permissionMode: optionalArgs.permissionMode ?? 'restricted' };
-        if (input.permissionMode !== 'restricted' && input.permissionMode !== 'bypass') {
-            return failBeforeSpawn({ runId: input.runId, code: 'AGENT_PERMISSION_MODE_INVALID', message: 'AgentExecutor: permissionMode must be restricted or bypass' });
-        }
-        const { def, streamFormat } = await resolveDefAndStreamFormat({ input: { runId: input.runId, agentId: input.agentId }, deps: { getAgentDef: getAgentDefFn, failBeforeSpawn } });
-        // Computed once, before anything downstream ever looks at "the prompt" or "the allowed
-        // dirs" — a no-op (`{prompt: input.prompt, extraAllowedDirs: input.extraAllowedDirs}`,
-        // literally unchanged) unless `def.imageDelivery === 'prompt-path'` AND `input.imagePaths`
-        // is non-empty, so this can never affect a 'native'-delivery def (ACP, pi-rpc, qoder) or a
-        // run with no attachments. See `image-prompt-delivery.ts`'s own doc for the full mechanism;
-        // every use of `input.prompt`/`input.extraAllowedDirs` below that reflects what the CLI
-        // actually receives reads `imageDelivery.*` instead — the two ACP/pi-rpc `wire*Lifecycle`
-        // calls further down deliberately keep reading `input.prompt` verbatim, since those two
-        // defs' own native protocol already delivers the image and must never also get this
-        // treatment (the double-delivery hazard this mechanism exists to avoid).
-        const imageDelivery = await resolveImageDeliveryAndArgvBudget({ input: { runId: input.runId, def, prompt: input.prompt, imagePaths: input.imagePaths, extraAllowedDirs: input.extraAllowedDirs }, deps: { failBeforeSpawn } });
-        // Phase 8, hoisted deliberately above EVERY step that writes or sends the prompt. Four
-        // different channels carry a prompt in this driver, and they do not all run at the same point:
-        // the `promptViaFile` staging below writes its file BEFORE `buildArgs`, `buildArgs` itself runs
-        // mid-`run()`, and stdin/ACP/pi-rpc all send theirs AFTER spawn. Resolving the overlay once,
-        // here, is what lets all four consume the same decision; resolving it later (as this used to,
-        // inside `buildRunArgs`) could only ever reach `buildArgs`, so the 17 defs that discard that
-        // argument, plus grok-build's staged file, silently received no overlay at all.
-        //
-        // `computeSystemPromptOverlay`'s third argument is the pre-staging `RuntimeContext`: it reads
-        // only `hasPriorAssistantTurn`, which `computeRuntimeContext` never populates from any of the
-        // staged-file/MCP inputs added to the fuller context built further down, so nothing between
-        // here and there can change the overlay this returns. Passing the narrower context makes that
-        // independence explicit rather than relying on the ordering staying lucky.
-        //
-        // `turnIndex` is a coarse 0/1 proxy (no exact turn counter exists on this driver) — sufficient
-        // because every `PromptAugmenter.systemOverlay()` implementation this seam has today wants the
-        // same overlay on every turn, not a first-turn-only one; a caller that needs finer-grained turn
-        // numbering can track it itself and ignore this arg.
-        const preStagingRuntimeContext = computeRuntimeContext({ preparedPromptFile: null, preparedLogFile: null, mcpBridge: null }, {
-            ...(input.resumeSessionId === undefined ? {} : { resumeSessionId: input.resumeSessionId }),
-            ...(input.newSessionId === undefined ? {} : { newSessionId: input.newSessionId }),
-        });
-        const systemPromptOverlay = computeSystemPromptOverlay(promptAugmenter, def.id, preStagingRuntimeContext);
-        const overlayDelivery = resolveSystemPromptOverlayDelivery({
-            defId: def.id,
-            systemPromptDelivery: def.systemPromptDelivery,
-            resumesSessionViaCli: def.resumesSessionViaCli,
-            resumesSessionViaAcpLoad: def.resumesSessionViaAcpLoad,
-            overlay: systemPromptOverlay,
-            prompt: imageDelivery.prompt,
-            resumeSessionId: preStagingRuntimeContext?.resumeSessionId,
-        });
-        // The def's own declared env (e.g. claude's `ENABLE_TOOL_SEARCH=false`) is a default the run's
-        // env can override. Detection already spawns with it (`detection.ts`); without this the run
-        // spawn silently dropped it. Declared by the def itself, so it never widens SEC-001's allowlist.
-        const resolvedEnv = { ...(def.env ?? {}), ...resolveRunEnv({ input: input, hostEnv: process.env }) };
-        const launch = await resolveLaunch({ input: { runId: input.runId, def, resolvedEnv }, deps: { resolveAgentLaunch: resolveAgentLaunchFn, failBeforeSpawn } });
-        const spawnEnv = applyAgentLaunchEnvFn({ env: { ...resolvedEnv }, launch });
-        // Fill the def's `--help` capability gate before `buildArgs` reads it. Without this, only a
-        // host that happened to call `detectAgents` in THIS process ever had the gate filled, so e.g.
-        // `claude` never got `--include-partial-messages` (no streamed text). Probes once per binary;
-        // never rejects (a failed probe keeps the safe no-optional-flags baseline).
-        await ensureAgentCapabilitiesFn({ def, launchPath: launch.launchPath, env: spawnEnv });
-        // Stage a promptViaFile def's (grok-build) prompt to a temp file before buildArgs runs — its
-        // buildArgs throws without runtimeContext.promptFilePath. A no-op (returns null) for every
-        // def without promptViaFile: true (preparePromptFileForAgent's own guard).
-        //
-        // `overlayDelivery.prompt`, not `imageDelivery.prompt`: for a `promptViaFile` def this file IS
-        // the prompt transport — its `buildArgs` declares `_prompt` and passes only the path — so the
-        // overlay has to be in the bytes written here or the CLI never sees it at all.
-        const preparedPromptFile = await stagePromptFile({ input: { runId: input.runId, def, prompt: overlayDelivery.prompt }, deps: { preparePromptFileForAgent: preparePromptFileForAgentFn, failBeforeSpawn } });
-        // Stage a needsAgentLogFile def's (antigravity) diagnostic-log path, on the same terms and at
-        // the same point as the prompt file above: before buildArgs, since buildArgs is what turns the
-        // path into a `--log-file <path>` argument. A no-op (returns null) for every def without
-        // `needsAgentLogFile: true` (prepareAgentLogFile's own guard). Sequenced after the prompt file
-        // rather than concurrently so the failure path above has exactly one thing to clean up.
-        const preparedLogFile = await stageLogFile({ input: { runId: input.runId, def, preparedPromptFile }, deps: { prepareAgentLogFile: prepareAgentLogFileFn, failBeforeSpawn } });
-        // Cleaned up after the child exits (wireChildLifecycle/wireAcpLifecycle/wirePiRpcLifecycle's
-        // close handlers) and on every pre-spawn/spawn-failure path below — a leaked temp file
-        // containing the full prompt, or whatever the CLI chose to write into its log, is a
-        // confidentiality gap, not just a disk leak. One composed closure covering both staged files;
-        // see `WireChildLifecycleContext.cleanupStagedFiles`'s doc for why they are not two fields.
-        /**
-         * Set once `writeMcpJsonForRun` has actually written this run's MCP config, so `cleanupStagedFiles`
-         * knows there is a file holding a live bearer token to remove. Cleared as it is consumed, so the
-         * removal happens exactly once across the several paths that may call the cleanup. Only the
-         * `'claude-mcp-json'` mechanism stages a file at all — `'acp-merge'` and `'env-content'` leave
-         * nothing on disk, so this stays `undefined` for those.
-         */
-        let writtenMcpJsonPath;
-        const removeMcpJsonFileFn = mcpJsonInjection?.removeFile ?? defaultRemoveMcpJsonFile;
-        /**
-         * Set once `prepareCodexHomeIfNeeded` has actually staged this run's scratch `CODEX_HOME`, so
-         * `cleanupStagedFiles` knows there is a directory holding a copied login credential to remove.
-         * Cleared as it is consumed, matching `writtenMcpJsonPath`'s identical single-removal discipline.
-         * Only the `'codex-toml'` mechanism stages a directory at all.
-         */
-        let preparedCodexHome = null;
-        /**
-         * Set once `prepareClaudeConfigDirIfNeeded` has actually staged this run's scratch
-         * `CLAUDE_CONFIG_DIR`, so `cleanupStagedFiles` knows there is a directory (possibly holding a
-         * copied login credential) to remove. Cleared as it is consumed, matching `preparedCodexHome`'s
-         * identical single-removal discipline. Only a `claude`-id run stages a directory this way.
-         */
-        let preparedClaudeConfigDir = null;
-        /**
-         * Set once `prepareSystemPromptOverlayFileIfNeeded` has actually staged this run's overlay file
-         * for a `'config-instructions-file'` def, so `cleanupStagedFiles` knows there is a temp
-         * directory to remove. Cleared as it is consumed, matching `preparedCodexHome`'s identical
-         * single-removal discipline. Only that one strategy stages a file this way — `null` for every
-         * other def/strategy/no-overlay run.
-         */
-        let preparedSystemPromptOverlayFile = null;
-        const cleanupStagedFiles = async () => {
-            if (preparedPromptFile)
-                await preparedPromptFile.cleanup();
-            if (preparedLogFile)
-                await preparedLogFile.cleanup();
-            if (writtenMcpJsonPath !== undefined) {
-                const mcpJsonFileToRemove = writtenMcpJsonPath;
-                writtenMcpJsonPath = undefined;
-                await removeMcpJsonFileFn({ path: mcpJsonFileToRemove });
-            }
-            if (preparedCodexHome) {
-                const codexHomeToRemove = preparedCodexHome;
-                preparedCodexHome = null;
-                await codexHomeToRemove.cleanup();
-            }
-            if (preparedClaudeConfigDir) {
-                const claudeConfigDirToRemove = preparedClaudeConfigDir;
-                preparedClaudeConfigDir = null;
-                await claudeConfigDirToRemove.cleanup();
-            }
-            if (preparedSystemPromptOverlayFile) {
-                const overlayFileToRemove = preparedSystemPromptOverlayFile;
-                preparedSystemPromptOverlayFile = null;
-                await overlayFileToRemove.cleanup();
-            }
-        };
-        // Resolve this run's MCP bridge delivery once, before buildArgs — the `'claude-mcp-json'`
-        // variant's path has to be in `runtimeContext` for that def's own `--mcp-config` argv, and
-        // resolving here means the per-run bearer credential is minted exactly once no matter which of
-        // the five mechanisms ends up carrying it. `null` for an unconfigured host or a def declaring
-        // no strategy — see `buildMcpBridgeDelivery`'s doc.
-        const mcpBridge = await resolveMcpBridgeForRun({ input: { runId: input.runId, cwd: input.cwd, def }, deps: { mcpJsonInjection, cleanupStagedFiles, failBeforeSpawn } });
-        const runtimeContext = computeRuntimeContext({ preparedPromptFile: preparedPromptFile, preparedLogFile: preparedLogFile, mcpBridge: mcpBridge }, {
-            ...(input.resumeSessionId === undefined ? {} : { resumeSessionId: input.resumeSessionId }),
-            ...(input.newSessionId === undefined ? {} : { newSessionId: input.newSessionId }),
-        });
-        // A `runtimeLock` def's buildArgs mutates process-global state its own CLI reads back at
-        // startup, so the mutex must be held from before buildArgs until the spawned child has
-        // demonstrably consumed it — see `RuntimeLock`'s own doc for the concrete race. Undefined for
-        // 23 of 24 defs, in which case nothing below waits on anything.
-        const selectedModel = input.model;
-        const runtimeLockHold = await acquireRuntimeLockIfConfigured(def, selectedModel);
-        // Aborts once the spawned process is gone — or immediately, on a path where no process ever
-        // ran — so a def's own handoff watcher can never outlive the run it was polling for.
-        const processExitedController = new AbortController();
-        /**
-         * Releases the runtime lock and cancels any handoff watcher. Safe to call from any number of
-         * paths: `AbortController.abort()` after the first is a no-op, and `RuntimeLockHold.release`
-         * is idempotent by contract.
-         */
-        const releaseRuntimeLock = () => {
-            processExitedController.abort();
-            runtimeLockHold?.release();
-        };
-        /** Both staged-file and lock release, for the pre-spawn/spawn-failure paths that own neither a child nor a close handler. */
-        const releaseStagedResources = async () => {
-            releaseRuntimeLock();
-            await cleanupStagedFiles();
-        };
-        // Guarded, like every other step between staging and spawn: a `runtimeLock` def's `buildArgs` is
-        // guarded precisely *because* it performs real filesystem writes (antigravity writes its model
-        // choice into a shared settings file), so EACCES on a read-only home, ENOSPC, or a malformed
-        // existing settings file all reach here as a throw. Unguarded, that escaped `run()` as a bare
-        // `Error` — breaking this driver's "never a bare throw, always an `AgentExecutorError`" contract
-        // — and left the run `'running'` forever while still holding the process-global mutex and both
-        // staged files, so no later run of that def could ever acquire the lock either.
-        const { args, envOverrides: systemPromptEnvOverrides } = await buildRunArgs({ input: { runId: input.runId, def, imageDelivery, imagePaths: input.imagePaths, runInput: input, systemPromptOverlay, overlayDelivery, runtimeContext }, deps: { releaseStagedResources, failBeforeSpawn } });
-        // Mechanism 1 of 5's one effect — stage this run's own MCP config file (run-scoped, see
-        // `mcpJsonPathForRun`) before spawn so the `--mcp-config <path>` argv buildArgs just produced
-        // points at a real file. Skipped entirely for the other four mechanisms and whenever no bridge
-        // was resolved at all. `writtenMcpJsonPath` is set only once the write actually happens, so
-        // `cleanupStagedFiles` knows there is a live-token file to remove afterward.
-        writtenMcpJsonPath = await writeMcpJsonIfNeeded({ input: { runId: input.runId, cwd: input.cwd, def, mcpBridge }, deps: { mcpJsonInjection, releaseStagedResources, failBeforeSpawn } });
-        // Mechanism 5 of 5's one effect — stage this run's scratch `CODEX_HOME` directory. Skipped
-        // entirely for the other four mechanisms and whenever no bridge was resolved at all.
-        // `codex.ts`'s `buildArgs` needs no argv change for this (CODEX_HOME is an env var, not a flag),
-        // so — unlike the `.mcp.json` staging above — this can run after `buildArgs` with no ordering
-        // constraint of its own; it is placed here only to keep the two staging steps adjacent.
-        preparedCodexHome = await prepareCodexHomeIfNeeded({ input: { runId: input.runId, def, mcpBridge }, deps: { mcpJsonInjection, hostEnv: process.env, releaseStagedResources, failBeforeSpawn } });
-        // Finding 1 of SEC-assistant-env-isolation-2026-09-07's one effect — stage this run's scratch
-        // `CLAUDE_CONFIG_DIR` directory. Unconditional for a `claude`-id run (unlike CODEX_HOME above,
-        // this does not depend on `mcpJsonInjection` being configured at all — see
-        // `prepareClaudeConfigDirIfNeeded`'s own doc for why). Placed here only to stay adjacent to the
-        // other pre-`computeChildEnv` staging steps; `claude.ts`'s `buildArgs` needs no argv change for
-        // this (CLAUDE_CONFIG_DIR is an env var, not a flag), same as CODEX_HOME.
-        preparedClaudeConfigDir = await prepareClaudeConfigDirIfNeeded({ input: { runId: input.runId, def }, deps: {
-                enabled: claudeConfigDirIsolationEnabled,
-                claudeConfigDirIsolation,
-                hostEnv: process.env,
-                releaseStagedResources,
-                failBeforeSpawn,
-            } });
-        // `'config-instructions-file'`'s one effect — stage the overlay to a temp file so
-        // `computeChildEnv` below has a real path to merge into that def's `instructions` array. A
-        // no-op (`null`) for every other def/strategy or a run with no overlay at all. Independent of
-        // `mcpBridge`/`preparedCodexHome` above (a different strategy field entirely), so placed here
-        // only to stay adjacent to the other pre-`computeChildEnv` staging steps, not for any ordering
-        // requirement between them.
-        preparedSystemPromptOverlayFile = await prepareSystemPromptOverlayFileIfNeeded({ input: { runId: input.runId, def, overlay: systemPromptOverlay }, deps: { releaseStagedResources, failBeforeSpawn } });
-        // Computed only now, not right after `mcpBridge` resolution: mechanism 5's directory path is
-        // not known until the staging step directly above actually runs `mkdtemp` (see
-        // `McpBridgeDelivery`'s `'codex-toml'` variant doc for why it cannot be pre-computed the way
-        // `'claude-mcp-json'`'s deterministic path is). Nothing between the old, earlier call site and
-        // here ever read `childEnv`, so moving the call cost nothing.
-        const childEnv = computeChildEnv({ spawnEnv: spawnEnv, mcpBridge: mcpBridge }, {
-            ...(preparedCodexHome === null ? {} : { codexHomeDir: preparedCodexHome.path }),
-            systemPromptEnvOverrides,
-            ...(preparedSystemPromptOverlayFile && def.systemPromptDelivery?.strategy === 'config-instructions-file'
-                ? { stagedInstructionsFile: { varName: def.systemPromptDelivery.varName, path: preparedSystemPromptOverlayFile.path } }
-                : {}),
-            ...(preparedClaudeConfigDir === null ? {} : { claudeConfigDir: preparedClaudeConfigDir.path }),
-        });
-        // Post-buildArgs guard for argv-bound defs whose resolved binary is a
-        // Windows .cmd/.bat shim or a direct .exe: a prompt under the raw byte
-        // budget can still expand past CreateProcess's command-line cap once
-        // quote-escaped. Both are no-ops off-Windows / for non-argv-bound defs.
-        await guardWindowsCommandLineBudget({ input: { runId: input.runId, def, launchPath: launch.launchPath, args }, deps: { releaseStagedResources, failBeforeSpawn } });
-        const invocation = createCommandInvocationFn({ command: launch.launchPath, args, env: childEnv });
-        // Kept a synchronous call (no `await`) on purpose — see `spawnAgentChildProcess`'s own doc for
-        // the microtask-timing race this avoids. The error branch's own cleanup/failBeforeSpawn calls are
-        // async, which is fine: no child exists yet on that path, so nothing is racing a listener.
-        const spawnResult = spawnAgentChildProcess({ input: { cwd: input.cwd, childEnv, invocation }, deps: { spawn: spawnFn } });
-        if (spawnResult.kind === 'error') {
-            await releaseStagedResources();
-            return failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: spawn threw synchronously for agent "${def.id}": ${errorMessage(spawnResult.error)}` });
-        }
-        const child = spawnResult.child;
-        // Registered before the spawn-confirmation await below, for the same reason
-        // `wireChildLifecycle` is: a child that exits immediately must not slip past the listener.
-        // `'exit'` rather than `'close'` on purpose — a `runtimeLock` guards state the *process* reads,
-        // so the process being gone is the release condition, not its stdio pipes draining (which a
-        // grandchild inheriting them can delay arbitrarily). A spawn that never produced a process at
-        // all emits no `'exit'`, and is covered instead by `releaseStagedResources` on the reject path.
-        child.once('exit', releaseRuntimeLock);
-        const formatForStdin = { streamFormat };
-        const stdinHandle = isStdinDrivenFormat(formatForStdin)
-            ? wireChildLifecycle({
-                runId: input.runId,
-                def,
-                streamFormat: formatForStdin.streamFormat,
-                child,
-                lifecycle,
-                listProcessSnapshots: listProcessSnapshotsFn,
-                collectProcessTreePids: collectProcessTreePidsFn,
-                stopProcesses: stopProcessesFn,
-                onCleanupFailure: onCleanupFailureFn,
-                cleanupStagedFiles,
-                journal,
-                continuation,
-                classifyFailure,
-                bufferedStdoutMaxBytes,
-                expectsJiniBridge: writtenMcpJsonPath !== undefined,
-            })
-            : null;
-        await confirmChildSpawned({ input: { runId: input.runId, def, child }, deps: { releaseStagedResources, failBeforeSpawn } });
-        // Now — and only now — is there a live process that could consume the locked side effect, so
-        // this is where a def's handoff watcher starts. Deliberately not awaited: the whole point is to
-        // release the lock as soon as the child confirms the handoff, in parallel with this run
-        // continuing. Rejection releases too — a lock stuck open because a watcher threw is strictly
-        // worse than releasing early (see `RuntimeLockHold.waitForHandoff`'s own doc).
-        armHandoffWatcher({ runtimeLockHold: runtimeLockHold, handoffInput: { logFilePath: preparedLogFile?.path, model: selectedModel, processExited: processExitedController.signal }, release: releaseRuntimeLock });
-        if (streamFormat === 'acp-json-rpc') {
-            await runAcpDispatch({ input: {
-                    runId: input.runId,
-                    agentId: def.id,
-                    child,
-                    // `overlayDelivery.promptPrefix` applied to `input.prompt`, NOT `overlayDelivery.prompt`:
-                    // this call site deliberately sends the raw input prompt rather than the image-delivery
-                    // rewrite (see `resolveImageDeliveryAndArgvBudget`'s call site above — an ACP def delivers
-                    // images natively and must never also get `'prompt-path'`'s appended paths), and the prefix
-                    // is the part of the overlay decision that applies to whatever prompt text a transport was
-                    // already sending. `''` for `reasonix` (env-var) and any resumed ACP session, so those keep
-                    // sending byte-identical text and never receive the overlay twice.
-                    prompt: `${overlayDelivery.promptPrefix}${input.prompt}`,
-                    cwd: input.cwd,
-                    model: input.model,
-                    imagePaths: input.imagePaths ?? [],
-                    envFormat: def.acpMcpEnvFormat,
-                    mcpBridge,
-                }, deps: {
-                    lifecycle,
-                    attachAcpSession: attachAcpSessionFn,
-                    onPermissionRequest: options.acpPermissionHandler,
-                    listProcessSnapshots: listProcessSnapshotsFn,
-                    collectProcessTreePids: collectProcessTreePidsFn,
-                    stopProcesses: stopProcessesFn,
-                    onCleanupFailure: onCleanupFailureFn,
-                    cleanupStagedFiles,
-                    journal,
-                    classifyFailure,
-                    releaseStagedResources,
-                    failBeforeSpawn,
-                } });
-            return;
-        }
-        if (streamFormat === 'pi-rpc') {
-            await runPiRpcDispatch({ input: {
-                    runId: input.runId,
-                    agentId: def.id,
-                    child,
-                    // Same reasoning as the ACP call site above. `pi` declares an `'append-flag'` strategy,
-                    // so its prefix is `''` and this stays byte-identical to the raw prompt — the overlay
-                    // rides `--append-system-prompt` instead, exactly once.
-                    prompt: `${overlayDelivery.promptPrefix}${input.prompt}`,
-                    cwd: input.cwd,
-                    model: input.model,
-                    imagePaths: input.imagePaths ?? [],
-                    uploadRoot: input.uploadRoot,
-                }, deps: {
-                    lifecycle,
-                    attachPiRpcSession: attachPiRpcSessionFn,
-                    listProcessSnapshots: listProcessSnapshotsFn,
-                    collectProcessTreePids: collectProcessTreePidsFn,
-                    stopProcesses: stopProcessesFn,
-                    onCleanupFailure: onCleanupFailureFn,
-                    cleanupStagedFiles,
-                    journal,
-                    classifyFailure,
-                    releaseStagedResources,
-                    failBeforeSpawn,
-                } });
-            return;
-        }
-        // The overlay reaches stdin only for a def that declares stdin as its prompt transport. The
-        // four `plain`-format defs that do not (`aider`/`antigravity`/`deepseek` put the prompt in
-        // argv, `grok-build` in a staged file) are still written to and closed here exactly as before,
-        // because this driver always spawns with `stdio: ['pipe','pipe','pipe']` and their CLIs need
-        // the EOF — but their prompt already carried the overlay through argv or the staged file, so
-        // sending the overlaid text here too would deliver it twice. This is the one place the
-        // resolver's own `''`-prefix rule is not sufficient on its own: those four defs are on the
-        // fallback strategy, so their prefix is genuinely non-empty; what makes stdin the wrong
-        // channel for them is the def's declared transport, not the strategy.
-        const stdinPrompt = def.promptViaStdin === true ? overlayDelivery.prompt : imageDelivery.prompt;
-        writePromptToStdin(def, child, stdinPrompt, stdinHandle);
-    }
-    return { run };
-}
+ * Compatibility entry for the agent executor's original module path.
+ * The split implementation owns subprocess launch, credential delivery,
+ * cancellation, and run events. Named re-exports preserve the existing API
+ * and AgentExecutorError identity across this entry and the package barrel;
+ * wrappers or a second implementation would let tested and shipped behavior drift.
+ * See agent-executor/index.ts for the driver contracts and invariants.
+ */
+export { isSupportedStreamFormat, assessAgentExecutorCompatibility, isAgentExecutorSupported, extractUsageTokens, translateStatusEvent, translateToolResultEvent, translateErrorEvent, translateTurnEndEvent, translateAgentRuntimeEvent, AgentExecutorError, MCP_BRIDGE_UNAVAILABLE, unavailableJiniBridgeStatus, buildMcpJsonServerEntry, mergeMcpJsonContent, buildAcpMcpBridgeServers, mergeEnvContentMcpConfig, mergeEnvContentInstructions, buildCodexMcpServerToml, buildCodexHomeConfigToml, resolveSourceCodexHomeDir, buildMcpBridgeDelivery, resolveSourceClaudeConfigDir, DEFAULT_BUFFERED_STDOUT_MAX_BYTES, applyAgentTranslationSideEffects, resolveDefAndStreamFormat, resolveImageDeliveryAndArgvBudget, resolveRunEnv, resolveLaunch, stagePromptFile, stageLogFile, resolveMcpBridgeForRun, computeChildEnv, computeRuntimeContext, buildAgentBuildArgsOptions, resolveSystemPromptOverlayDelivery, buildRunArgs, writeMcpJsonIfNeeded, prepareSystemPromptOverlayFileIfNeeded, prepareCodexHomeIfNeeded, prepareClaudeConfigDirIfNeeded, guardWindowsCommandLineBudget, spawnAgentChildProcess, isStdinDrivenFormat, confirmChildSpawned, armHandoffWatcher, runAcpDispatch, runPiRpcDispatch, createAgentExecutor, } from './agent-executor/index.js';
 //# sourceMappingURL=agent-executor.js.map