@jini-ai/daemon 0.2.1 → 0.3.0

package/dist/agent-executor.js

@@ -9,7 +9,7 @@
  * a real `node:child_process` spawn, feeding both `RunLifecycle.emit()` and
  * this package's own `@jini-ai/protocol` event envelope.
  *
- * ## v1 scope: 23 of 24 registered agent defs
+ * ## 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
@@ -25,14 +25,14 @@
  * `mapPiRpcEvent` `send()` call site — no new translation code was needed),
  * so only the driver wiring (spawn → attach → cancel → finish) was new for it.
  *
- * 4 of the 5 `streamFormat: 'plain'` defs — grok-build, aider, deepseek,
- * qwen — are also driven, per
+ * 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. Every raw
- * `child.stdout` chunk is forwarded verbatim as a `text_delta` `'agent'`
- * event, live, as it arrives — never buffered until close (see
- * `wireChildLifecycle`'s `streamFormat === 'plain'` branch). Prompt delivery
- * across the 4 is not uniform: qwen already fit the pre-existing stdin-only
+ * 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,
@@ -41,16 +41,27 @@
  * Windows CreateProcess command-line-expansion guards
  * (`checkWindowsCmdShimCommandLineBudget`/`checkWindowsDirectExeCommandLineBudget`).
  *
- * The 5th plain def, **antigravity, is deliberately still rejected.** It
- * needs two concerns unrelated to `streamFormat: 'plain'` itself — buffering
- * stdout until close so a leaked OAuth URL can be suppressed before it
- * reaches the client, and a cross-run lock serializing writes to its shared
- * `settings.json` model-selection file — that the proposal doc explicitly
- * scoped out to its own follow-up (see that doc's §2c/§3). `run()` guards it
- * with its own `def.id === 'antigravity'` check, ahead of (and independent
- * of) the generic plain-format prompt-delivery/dispatch logic. `run()`
- * rejects cleanly (never a bare throw) with an `AgentExecutorError` for any
- * def outside the supported 23 — see `isSupportedStreamFormat`.
+ * ## 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
  *
@@ -72,7 +83,7 @@
  * deliberately never ported (see `run/core/failure-taxonomy.ts`'s own doc and
  * `source-map.md`). The real zero-config classifier lives in `@jini-ai/daemon`'s
  * `run/core/retry.ts` (`resumableFromProcessExit`/`classifyProcessExitFailure`)
- * and is wired in by `@jini-ai/node-host`'s `createLocalNodeDaemon` — see that
+ * and is wired in by `@jini-ai/server`'s `createLocalNodeDaemon` — see that
  * package's own source-map.md, 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
@@ -80,13 +91,16 @@
  */
 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 { applyAgentLaunchEnv, createClaudeStreamHandler, createCopilotStreamHandler, createJsonEventStreamHandler, createQoderStreamHandler, getAgentDef, resolveAgentLaunch, attachAcpSession, attachPiRpcSession, checkPromptArgvBudget, checkWindowsCmdShimCommandLineBudget, checkWindowsDirectExeCommandLineBudget, preparePromptFileForAgent, } from '@jini-ai/agent-runtime';
+import { applyAgentLaunchEnv, createClaudeStreamHandler, createCopilotStreamHandler, createJsonEventStreamHandler, createQoderStreamHandler, 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',
@@ -107,6 +121,59 @@ const SUPPORTED_STREAM_FORMATS = [
 export function isSupportedStreamFormat(value) {
     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 streamFormat = def.streamFormat;
+    if (!isSupportedStreamFormat(streamFormat)) {
+        return {
+            supported: false,
+            reason: `AgentExecutor: agent "${def.id}" has streamFormat "${streamFormat}", which is not implemented in v1 — only ${SUPPORTED_STREAM_FORMATS.join(', ')} are supported`,
+        };
+    }
+    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).supported;
+}
 /**
  * Selects and constructs the real stream-parser handler for a supported
  * `streamFormat`. `json-event-stream` additionally dispatches on
@@ -148,6 +215,27 @@ function asOptionalString(value) {
 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
@@ -162,14 +250,7 @@ function asOptionalNumber(value) {
  */
 function translateUsagePayload(rawEvent) {
     const rawUsage = isRecord(rawEvent.usage) ? rawEvent.usage : undefined;
-    const inputTokens = rawUsage ? asOptionalNumber(rawUsage.input_tokens) : undefined;
-    const outputTokens = rawUsage ? asOptionalNumber(rawUsage.output_tokens) : undefined;
-    const usage = inputTokens !== undefined || outputTokens !== undefined
-        ? {
-            ...(inputTokens !== undefined ? { input_tokens: inputTokens } : {}),
-            ...(outputTokens !== undefined ? { output_tokens: outputTokens } : {}),
-        }
-        : undefined;
+    const usage = extractUsageTokens(rawUsage);
     const costUsd = asOptionalNumber(rawEvent.costUsd);
     const durationMs = asOptionalNumber(rawEvent.durationMs);
     return {
@@ -179,6 +260,108 @@ function translateUsagePayload(rawEvent) {
         ...(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: translateStatusEvent,
+    text_delta: translateTextDeltaEvent,
+    thinking_start: translateThinkingStartEvent,
+    thinking_delta: translateThinkingDeltaEvent,
+    tool_use: translateToolUseEvent,
+    tool_input_delta: translateToolInputDeltaEvent,
+    tool_result: translateToolResultEvent,
+    usage: translateUsageEvent,
+    raw: translateRawEvent,
+    error: translateErrorEvent,
+    turn_end: translateTurnEndEvent,
+};
 /**
  * Narrows one parser-emitted `{type, ...}` record into this engine's
  * `RunAgentPayload` union (or the `error`/`turn-end`/`ignored` routing
@@ -198,92 +381,15 @@ function translateUsagePayload(rawEvent) {
  *
  * @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 discriminant switch, no iteration.
+ * @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' };
     }
-    switch (rawEvent.type) {
-        case 'status': {
-            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 } : {}),
-            };
-        }
-        case 'text_delta':
-            return { kind: 'agent', payload: { type: 'text_delta', delta: asString(rawEvent.delta) } };
-        case 'thinking_start':
-            return { kind: 'agent', payload: { type: 'thinking_start' } };
-        case 'thinking_delta':
-            return { kind: 'agent', payload: { type: 'thinking_delta', delta: asString(rawEvent.delta) } };
-        case 'tool_use':
-            return {
-                kind: 'agent',
-                payload: {
-                    type: 'tool_use',
-                    id: asString(rawEvent.id),
-                    name: asString(rawEvent.name),
-                    input: rawEvent.input ?? null,
-                },
-            };
-        case 'tool_input_delta':
-            return {
-                kind: 'agent',
-                payload: {
-                    type: 'tool_input_delta',
-                    id: asString(rawEvent.id),
-                    name: asString(rawEvent.name),
-                    delta: asString(rawEvent.delta),
-                },
-            };
-        case 'tool_result': {
-            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 } : {}),
-                },
-            };
-        }
-        case 'usage':
-            return { kind: 'agent', payload: translateUsagePayload(rawEvent) };
-        case 'raw':
-            return { kind: 'agent', payload: { type: 'raw', line: asString(rawEvent.line) } };
-        case 'error': {
-            const code = asOptionalString(rawEvent.code);
-            const message = asString(rawEvent.message, 'Unknown agent error');
-            return {
-                kind: 'error',
-                payload: { message, ...(code !== undefined ? { error: { code, message } } : {}) },
-            };
-        }
-        case 'turn_end': {
-            // 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 } : {}) };
-        }
-        default:
-            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 {
@@ -324,6 +430,13 @@ function toStringEnvRecord(env) {
 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. See tovu-learnings.md §9 for the full investigation trail.
+    'USER',
     'SystemRoot', 'windir', 'ComSpec', 'PATHEXT', // Windows-only; harmless no-ops elsewhere
 ];
 /**
@@ -380,6 +493,68 @@ 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(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
@@ -425,16 +600,27 @@ function receivedJournalEntry(channel, content) {
 }
 const JINI_MCP_SERVER_KEY = 'jini';
 /**
- * Builds this run's `mcpServers.jini` entry — pure, so every field mapping is directly
- * assertable without touching the filesystem.
+ * 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` 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) {
+export function buildMcpJsonServerEntry(runId, options, credential) {
     return {
         command: options.command,
         args: options.args !== undefined ? [...options.args] : [],
-        env: { JINI_RUN_ID: runId, JINI_DAEMON_URL: options.daemonUrl },
+        env: {
+            JINI_RUN_ID: runId,
+            JINI_DAEMON_URL: options.daemonUrl,
+            ...(credential !== undefined ? { JINI_DAEMON_TOKEN: credential } : {}),
+        },
     };
 }
 /**
@@ -464,43 +650,415 @@ export function mergeMcpJsonContent(existingRaw, serverEntry) {
     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 });
+}
+/**
+ * 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)}"`;
+}
+/**
+ * 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 `source-map.md` 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`;
+    const envLines = Object.entries(entry.env)
+        .filter((pair) => typeof pair[1] === 'string')
+        .map(([key, value]) => `${key} = ${tomlString(value)}`);
+    if (envLines.length === 0)
+        return serverTable;
+    return `${serverTable}\n[mcp_servers.${JINI_MCP_SERVER_KEY}.env]\n${envLines.join('\n')}\n`;
+}
+/**
+ * Builds the full `config.toml` a run's scratch `CODEX_HOME` gets: the real Codex home's own
+ * config, verbatim, with this run's `[mcp_servers.jini]` table appended.
+ *
+ * **Append-only by design, not a parse-and-merge.** `mergeMcpJsonContent`/`mergeEnvContentMcpConfig`
+ * above can safely parse-merge-reserialize because their formats have a JS-native parser
+ * (`JSON.parse`); this driver has no 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. Appending preserves all of it; the one failure mode this trades
+ * away is a PRE-EXISTING `[mcp_servers.jini]` table in the operator's own config, which would
+ * produce a duplicate TOML key Codex rejects at startup. Accepted as vanishingly unlikely — `jini`
+ * is this integration's own reserved server name (see {@link JINI_MCP_SERVER_KEY}), never suggested
+ * to an operator for their own config — rather than solved with a full TOML parser for one
+ * collision case.
+ * @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.
+ * @overallScore 100/100
+ */
+export function buildCodexHomeConfigToml(existingRaw, entry) {
+    const base = existingRaw ?? '';
+    const separator = base.length === 0 ? '' : base.endsWith('\n') ? '\n' : '\n\n';
+    return `${base}${separator}${buildCodexMcpServerToml(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, options, 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(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 };
+    }
+}
 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 });
+}
 /**
- * Writes (merging, never clobbering — see {@link mergeMcpJsonContent}) `.mcp.json` into `cwd`
- * before spawn, so Claude Code's own spawn-time config load (confirmed in `@jini-ai/agent-runtime`'s
- * `defs/claude.ts` doc: "Claude Code auto-loads `.mcp.json` from the project cwd at spawn")
- * discovers the `jini-mcp` bridge server without this driver needing to pass any CLI flag at all.
- * A no-op when `mcpJsonInjection` is `undefined` (opt-in, see `CreateAgentExecutorOptions`'s doc)
- * or `def.externalMcpInjection !== 'claude-mcp-json'` (every other injection strategy delivers
- * `mcpServers` a different way — see this module's own doc above).
+ * 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, runId, def, mcpJsonInjection) {
-    if (mcpJsonInjection === undefined || def.externalMcpInjection !== 'claude-mcp-json')
-        return;
-    const readFileFn = mcpJsonInjection.readFile ?? defaultReadMcpJsonFile;
-    const writeFileFn = mcpJsonInjection.writeFile ?? defaultWriteMcpJsonFile;
-    const filePath = join(cwd, '.mcp.json');
+async function writeMcpJsonForRun(cwd, delivery, options) {
+    const readFileFn = options.readFile ?? defaultReadMcpJsonFile;
+    const writeFileFn = options.writeFile ?? defaultWriteMcpJsonFile;
     let existingRaw;
     try {
-        existingRaw = await readFileFn(filePath);
+        existingRaw = await readFileFn(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;
     }
-    const serverEntry = buildMcpJsonServerEntry(runId, mcpJsonInjection);
-    await writeFileFn(filePath, mergeMcpJsonContent(existingRaw, serverEntry));
+    await writeFileFn(delivery.mcpJsonPath, mergeMcpJsonContent(existingRaw, 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(`jini-codex-home-${safeRunId}-`);
+    try {
+        let existingConfigRaw;
+        try {
+            existingConfigRaw = await seams.readFile(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(join(dir, 'config.toml'), buildCodexHomeConfigToml(existingConfigRaw, entry));
+        try {
+            const authRaw = await seams.readFile(join(sourceCodexHomeDir, 'auth.json'));
+            await seams.writeFile(join(dir, 'auth.json'), 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(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(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
@@ -526,14 +1084,35 @@ async function writeMcpJsonForRun(cwd, runId, def, mcpJsonInjection) {
  * `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 live, verbatim, as its own
- * `text_delta` `'agent'` event, through the same `enqueueEmit` FIFO queue
- * every other emit already goes through — no buffering until close, 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/source-map.md`'s
- * 2026-07-21 addition for the reasoning.
+ * §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/source-map.md`'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.
@@ -559,6 +1138,20 @@ function wireChildLifecycle(ctx) {
     // 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;
+    // `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 {
@@ -618,10 +1211,17 @@ function wireChildLifecycle(ctx) {
             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 = [];
             try {
                 const result = await continuation.toolExecutor.execute(continuation.principal, run, toolUse.name, toolUse.input);
                 content = resultContent(result);
                 isError = result.status !== 'completed';
+                media = extractResultMedia(result.output).media;
             }
             catch (error) {
                 content = errorMessage(error);
@@ -629,7 +1229,13 @@ function wireChildLifecycle(ctx) {
             }
             await lifecycle.emit(runId, {
                 event: 'agent',
-                data: { type: 'tool_result', toolUseId: toolUse.id, content, ...(isError ? { isError: true } : {}) },
+                data: {
+                    type: 'tool_result',
+                    toolUseId: toolUse.id,
+                    content,
+                    ...(isError ? { isError: true } : {}),
+                    ...(media.length > 0 ? { media } : {}),
+                },
             });
             injectToolResultLine(toolUse.id, content, isError);
         });
@@ -658,21 +1264,65 @@ function wireChildLifecycle(ctx) {
                 handleTurnEnd(translation.stopReason);
             }
         });
+    /**
+     * 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(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, { event: 'stdout', data: { chunk: text } }));
+        enqueueEmit(() => lifecycle.emit(runId, { event: 'agent', data: { type: 'text_delta', delta: text } }));
+    }
     child.stdout?.on('data', (chunk) => {
         const text = chunk.toString('utf8');
         if (journal)
             enqueueEmit(() => journal.record(runId, receivedJournalEntry('stdout', text)));
-        enqueueEmit(() => lifecycle.emit(runId, { event: 'stdout', data: { chunk: 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, { event: 'stdout', data: { chunk: text } }));
             enqueueEmit(() => lifecycle.emit(runId, { event: 'agent', data: { type: 'text_delta', delta: text } }));
+            return;
         }
-        else {
-            // Non-null: `streamHandler` is only ever null when `streamFormat === 'plain'` (see its
-            // construction above), the branch this `else` provably excludes.
-            streamHandler.feed(text);
-        }
+        enqueueEmit(() => lifecycle.emit(runId, { 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(text);
     });
     child.stderr?.on('data', (chunk) => {
         const text = chunk.toString('utf8');
@@ -705,12 +1355,17 @@ function wireChildLifecycle(ctx) {
             // 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();
-            await ctx.cleanupPromptFile();
+            // 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 = classifyRunCloseStatus({ cancelRequested, code, signal });
             const resumable = status === 'failed' && classifyFailure !== undefined
-                ? await classifyFailure({
+                ? await classifyFailureSafely(ctx, classifyFailure, {
                     runId,
                     agentId: def.id,
                     code,
@@ -761,6 +1416,28 @@ function translateAcpError(payload) {
             : {}),
     };
 }
+/**
+ * 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
@@ -814,10 +1491,11 @@ function wireAcpLifecycle(ctx) {
         void (async () => {
             await emitQueue;
             unsubscribeCancel();
-            await ctx.cleanupPromptFile();
+            // 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 classifyFailure({
+                ? await classifyFailureSafely(ctx, classifyFailure, {
                     runId,
                     agentId,
                     code,
@@ -842,20 +1520,20 @@ function wireAcpLifecycle(ctx) {
         ...(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 } : {}),
         send(event, payload) {
             if (event === 'agent') {
                 const translation = translateAgentRuntimeEvent(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;
-                    }
+                    applyAgentTranslationSideEffects(translation.payload, translation.sessionId, {
+                        onSessionId: (sessionId) => { capturedSessionId = sessionId; },
+                        onToolCall: () => { toolCallSeen = true; },
+                        onUserVisibleOutput: () => { userVisibleOutputSeen = true; },
+                    });
                     enqueueEmit(() => lifecycle.emit(runId, { event: 'agent', data: translation.payload }));
                 }
                 else if (translation.kind === 'error') {
@@ -933,10 +1611,11 @@ function wirePiRpcLifecycle(ctx) {
         void (async () => {
             await emitQueue;
             unsubscribeCancel();
-            await ctx.cleanupPromptFile();
+            // 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 classifyFailure({
+                ? await classifyFailureSafely(ctx, classifyFailure, {
                     runId,
                     agentId,
                     code,
@@ -1015,38 +1694,397 @@ function writePromptToStdin(def, child, prompt, handle) {
     handle.closeStdinOnce();
 }
 /**
- * Creates the `AgentExecutor` reference implementation: an in-process
- * `RunLifecycle` driver over real (by default) `@jini-ai/agent-runtime`
- * registry lookup, launch resolution, and stream parsing, plus a real
- * `node:child_process.spawn`. Every collaborator is an injectable seam
- * (matching this package's established convention — see
- * `tool-executor.ts`/`run-lifecycle.ts`) so tests can drive a fake child
- * process and a fake registry without touching the filesystem or spawning
- * a real subprocess.
+ * 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,
+        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 ?? collectProcessTreePids,
+        stopProcesses: options.stopProcesses ?? stopProcesses,
+    };
+}
+/** 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(input.agentId);
+    if (!def) {
+        return deps.failBeforeSpawn(input.runId, 'AGENT_NOT_FOUND', `AgentExecutor: unknown agentId "${input.agentId}"`);
+    }
+    const compatibility = assessAgentExecutorCompatibility(def);
+    if (!compatibility.supported) {
+        return deps.failBeforeSpawn(input.runId, 'AGENT_RUNTIME_UNSUPPORTED', 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(input.def.imageDelivery, input.prompt, input.imagePaths, input.extraAllowedDirs);
+    const argvBudgetError = checkPromptArgvBudget(input.def, imageDelivery.prompt);
+    if (argvBudgetError) {
+        return deps.failBeforeSpawn(input.runId, 'AGENT_PROMPT_TOO_LARGE', 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(input.def, input.resolvedEnv);
+    if (!launch.launchPath) {
+        return deps.failBeforeSpawn(input.runId, 'AGENT_BINARY_NOT_RESOLVED', `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(input.def, input.prompt, input.runId);
+    }
+    catch (err) {
+        return deps.failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `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(input.def, input.runId);
+    }
+    catch (err) {
+        await (input.preparedPromptFile ? input.preparedPromptFile.cleanup() : Promise.resolve());
+        return deps.failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `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?.(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(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: could not resolve the MCP bridge credential for agent "${input.def.id}": ${errorMessage(err)}`);
+    }
+}
+/**
+ * Phase 6a/10c: the subprocess environment every env-riding MCP 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`) and mechanism 5 (`'codex-toml'`, `CODEX_HOME` relocation).
+ * Pure — `codexHomeDir` arrives already staged by {@link prepareCodexHomeIfNeeded}, which is the
+ * one part of this mechanism that is NOT pure (a real `mkdtemp`).
+ * @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).
+ * @complexity O(1) plus `mergeEnvContentMcpConfig`'s own `JSON.parse`/`JSON.stringify` cost.
+ * @overallScore 100/100
+ */
+export function computeChildEnv(spawnEnv, mcpBridge, codexHomeDir) {
+    const envContentApplied = mcpBridge?.kind === 'env-content'
+        ? {
+            ...spawnEnv,
+            [mcpBridge.envVarName]: mergeEnvContentMcpConfig(spawnEnv[mcpBridge.envVarName], mcpBridge.serverEntry),
+        }
+        : spawnEnv;
+    if (codexHomeDir === undefined)
+        return envContentApplied;
+    return { ...envContentApplied, CODEX_HOME: codexHomeDir };
+}
+/**
+ * Phase 6b: the `RuntimeContext` `buildArgs` receives — `undefined` unless a file, bridge path, or
+ * session id was staged. Pure.
  *
- * @param options.lifecycle - The `RunLifecycle` this executor drives — its `start()` must already have been called for any `runId` passed to `run()`.
- * @returns An `AgentExecutor` whose `run()` never bare-throws (see module doc's Invariant).
- * @complexity `run()`'s own setup is O(1); steady-state cost is the chosen stream parser's.
+ * `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 — `undefined` when the run selects no model/reasoning/permissionMode/overlay at all (byte-identical to omitting the argument). Pure. */
+export function buildAgentBuildArgsOptions(input, systemPromptOverlay) {
+    const hasOverlay = systemPromptOverlay !== undefined && systemPromptOverlay !== null;
+    if (input.model === undefined && input.reasoning === undefined && input.permissionMode === undefined && !hasOverlay) {
+        return undefined;
+    }
+    return {
+        ...(input.model !== undefined ? { model: input.model } : {}),
+        ...(input.reasoning !== undefined ? { reasoning: input.reasoning } : {}),
+        ...(input.permissionMode !== undefined ? { permissionMode: input.permissionMode } : {}),
+        ...(hasOverlay ? { systemPromptOverlay } : {}),
+    };
+}
+/** Phase 9b: calls the def's `buildArgs`, releasing staged resources and failing the run on a throw. */
+export async function buildRunArgs(input, deps) {
+    try {
+        return input.def.buildArgs(input.imageDelivery.prompt, [...(input.imagePaths ?? [])], input.imageDelivery.extraAllowedDirs === undefined ? undefined : [...input.imageDelivery.extraAllowedDirs], buildAgentBuildArgsOptions(input.runInput, input.systemPromptOverlay), input.runtimeContext);
+    }
+    catch (err) {
+        await deps.releaseStagedResources();
+        return deps.failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `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(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: could not write .mcp.json 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(deps.hostEnv), resolveCodexHomeSeams(deps.mcpJsonInjection));
+    }
+    catch (err) {
+        await deps.releaseStagedResources();
+        return deps.failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: could not stage a CODEX_HOME 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(input.def, input.launchPath, input.args) ??
+        checkWindowsDirectExeCommandLineBudget(input.def, input.launchPath, input.args);
+    if (windowsBudgetError) {
+        await deps.releaseStagedResources();
+        await deps.failBeforeSpawn(input.runId, 'AGENT_PROMPT_TOO_LARGE', 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(streamFormat) {
+    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(input.runId, 'AGENT_SPAWN_FAILED', `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(input.runId, 'AGENT_SPAWN_FAILED', `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(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: could not attach pi-rpc session for agent "${input.agentId}": ${errorMessage(err)}`);
+    }
+}
 export function createAgentExecutor(options) {
     const lifecycle = options.lifecycle;
-    const getAgentDefFn = options.getAgentDef ?? getAgentDef;
-    const resolveAgentLaunchFn = options.resolveAgentLaunch ?? resolveAgentLaunch;
-    const applyAgentLaunchEnvFn = options.applyAgentLaunchEnv ?? applyAgentLaunchEnv;
-    const createCommandInvocationFn = options.createCommandInvocation ?? createCommandInvocation;
-    const spawnFn = options.spawn ?? nodeSpawn;
-    const attachAcpSessionFn = options.attachAcpSession ?? attachAcpSession;
-    const attachPiRpcSessionFn = options.attachPiRpcSession ?? attachPiRpcSession;
-    const preparePromptFileForAgentFn = options.preparePromptFileForAgent ?? preparePromptFileForAgent;
-    const listProcessSnapshotsFn = options.listProcessSnapshots ?? listProcessSnapshots;
-    const collectProcessTreePidsFn = options.collectProcessTreePids ?? collectProcessTreePids;
-    const stopProcessesFn = options.stopProcesses ?? stopProcesses;
-    const onCleanupFailureFn = options.onCleanupFailure ?? defaultCleanupFailureSink;
+    const { getAgentDef: getAgentDefFn, resolveAgentLaunch: resolveAgentLaunchFn, 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 promptAugmenter = options.promptAugmenter;
     /**
      * Transitions `runId` to `'failed'` (idempotent, never resumable — no
      * classifier exists, see module doc) then rejects with a typed
@@ -1075,106 +2113,154 @@ export function createAgentExecutor(options) {
      * @overallScore 100/100
      */
     async function run(input) {
-        const def = getAgentDefFn(input.agentId);
-        if (!def) {
-            return failBeforeSpawn(input.runId, 'AGENT_NOT_FOUND', `AgentExecutor: unknown agentId "${input.agentId}"`);
-        }
-        const streamFormat = def.streamFormat;
-        if (!isSupportedStreamFormat(streamFormat)) {
-            return failBeforeSpawn(input.runId, 'AGENT_RUNTIME_UNSUPPORTED', `AgentExecutor: agent "${def.id}" has streamFormat "${streamFormat}", which is not implemented in v1 — only ${SUPPORTED_STREAM_FORMATS.join(', ')} are supported (see packages/daemon/source-map.md for the deferred antigravity guard)`);
-        }
-        // Antigravity is the one plain def NOT driven — see module doc. This
-        // guard is deliberately independent of (and ahead of) the generic
-        // prompt-delivery/dispatch logic below: even though antigravity's def
-        // declares promptViaStdin: true and would otherwise clear every guard
-        // that follows, it needs auth-URL-leak buffering and a cross-run
-        // model-selection lock this driver has no seam for yet.
-        if (streamFormat === 'plain' && def.id === 'antigravity') {
-            return failBeforeSpawn(input.runId, 'AGENT_RUNTIME_UNSUPPORTED', `AgentExecutor: agent "${def.id}" needs auth-URL-leak buffering and a cross-run model-selection lock that generic streamFormat 'plain' driving does not provide — deliberately deferred, see ADS-memory/reports/proposals/PROP-plain-format-agent-driving-2026-07-21.md`);
-        }
-        if (streamFormat !== 'acp-json-rpc' &&
-            def.promptViaStdin !== true &&
-            def.promptViaFile !== true &&
-            typeof def.maxPromptArgBytes !== 'number') {
-            return failBeforeSpawn(input.runId, 'AGENT_RUNTIME_UNSUPPORTED', `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`);
-        }
-        // Argv-bound defs (aider, deepseek) — reject an oversized prompt before
-        // ever resolving a binary or touching the filesystem. A no-op for every
-        // def without `maxPromptArgBytes` (checkPromptArgvBudget's own guard).
-        const argvBudgetError = checkPromptArgvBudget(def, input.prompt);
-        if (argvBudgetError) {
-            return failBeforeSpawn(input.runId, 'AGENT_PROMPT_TOO_LARGE', argvBudgetError.message);
-        }
-        const resolvedEnv = input.env !== undefined ? toStringEnvRecord(input.env) : buildAgentEnv(process.env, input.credentialEnv);
-        const launch = resolveAgentLaunchFn(def, resolvedEnv);
-        if (!launch.launchPath) {
-            return failBeforeSpawn(input.runId, 'AGENT_BINARY_NOT_RESOLVED', `AgentExecutor: could not resolve an executable for agent "${def.id}" (bin "${def.bin}")`);
-        }
+        const { def, streamFormat } = await resolveDefAndStreamFormat({ runId: input.runId, agentId: input.agentId }, { 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({ runId: input.runId, def, prompt: input.prompt, imagePaths: input.imagePaths, extraAllowedDirs: input.extraAllowedDirs }, { failBeforeSpawn });
+        const resolvedEnv = resolveRunEnv(input, process.env);
+        const launch = await resolveLaunch({ runId: input.runId, def, resolvedEnv }, { resolveAgentLaunch: resolveAgentLaunchFn, failBeforeSpawn });
         const spawnEnv = applyAgentLaunchEnvFn({ ...resolvedEnv }, launch);
-        // 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).
-        let preparedPromptFile;
-        try {
-            preparedPromptFile = await preparePromptFileForAgentFn(def, input.prompt, input.runId);
-        }
-        catch (err) {
-            return failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: could not stage a prompt file for agent "${def.id}": ${errorMessage(err)}`);
-        }
+        // 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).
+        const preparedPromptFile = await stagePromptFile({ runId: input.runId, def, prompt: imageDelivery.prompt }, { 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({ runId: input.runId, def, preparedPromptFile }, { 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 is a confidentiality gap, not just a disk leak.
-        const cleanupPromptFile = preparedPromptFile
-            ? preparedPromptFile.cleanup
-            : async () => { };
-        const runtimeContext = preparedPromptFile
-            ? { promptFilePath: preparedPromptFile.path }
-            : undefined;
-        const args = def.buildArgs(input.prompt, [...(input.imagePaths ?? [])], input.extraAllowedDirs === undefined ? undefined : [...input.extraAllowedDirs], input.model !== undefined || input.reasoning !== undefined || input.permissionMode !== undefined
-            ? {
-                ...(input.model !== undefined ? { model: input.model } : {}),
-                ...(input.reasoning !== undefined ? { reasoning: input.reasoning } : {}),
-                ...(input.permissionMode !== undefined ? { permissionMode: input.permissionMode } : {}),
+        // 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;
+        const cleanupStagedFiles = async () => {
+            if (preparedPromptFile)
+                await preparedPromptFile.cleanup();
+            if (preparedLogFile)
+                await preparedLogFile.cleanup();
+            if (writtenMcpJsonPath !== undefined) {
+                const mcpJsonFileToRemove = writtenMcpJsonPath;
+                writtenMcpJsonPath = undefined;
+                await removeMcpJsonFileFn(mcpJsonFileToRemove);
             }
-            : undefined, runtimeContext);
-        // Gap 3, part 2 — write .mcp.json into the managed cwd before spawn, so a 'claude-mcp-json'
-        // def's own spawn-time config load discovers the jini-mcp bridge server. A no-op for every
-        // other def and whenever mcpJsonInjection is unconfigured — see writeMcpJsonForRun's doc.
-        try {
-            await writeMcpJsonForRun(input.cwd, input.runId, def, mcpJsonInjection);
-        }
-        catch (err) {
-            await cleanupPromptFile();
-            return failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: could not write .mcp.json for agent "${def.id}": ${errorMessage(err)}`);
-        }
+            if (preparedCodexHome) {
+                const codexHomeToRemove = preparedCodexHome;
+                preparedCodexHome = null;
+                await codexHomeToRemove.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({ runId: input.runId, cwd: input.cwd, def }, { mcpJsonInjection, cleanupStagedFiles, failBeforeSpawn });
+        const runtimeContext = computeRuntimeContext(preparedPromptFile, preparedLogFile, mcpBridge, input.resumeSessionId, 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();
+        };
+        // Computed once per `run()`, not per-token/per-event: a system-prompt overlay is a spawn-time
+        // CLI arg, not something that varies mid-run. `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 systemPromptOverlay = computeSystemPromptOverlay(promptAugmenter, def.id, runtimeContext);
+        // 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 = await buildRunArgs({ runId: input.runId, def, imageDelivery, imagePaths: input.imagePaths, runInput: input, systemPromptOverlay, runtimeContext }, { 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({ runId: input.runId, cwd: input.cwd, def, mcpBridge }, { 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({ runId: input.runId, def, mcpBridge }, { mcpJsonInjection, hostEnv: process.env, 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, mcpBridge, preparedCodexHome?.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.
-        const windowsBudgetError = checkWindowsCmdShimCommandLineBudget(def, launch.launchPath, args) ??
-            checkWindowsDirectExeCommandLineBudget(def, launch.launchPath, args);
-        if (windowsBudgetError) {
-            await cleanupPromptFile();
-            return failBeforeSpawn(input.runId, 'AGENT_PROMPT_TOO_LARGE', windowsBudgetError.message);
-        }
-        const invocation = createCommandInvocationFn({ command: launch.launchPath, args, env: spawnEnv });
-        let child;
-        try {
-            child = spawnFn(invocation.command, invocation.args, {
-                cwd: input.cwd,
-                env: spawnEnv,
-                stdio: ['pipe', 'pipe', 'pipe'],
-                windowsVerbatimArguments: invocation.windowsVerbatimArguments,
-            });
-        }
-        catch (err) {
-            await cleanupPromptFile();
-            return failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: spawn threw synchronously for agent "${def.id}": ${errorMessage(err)}`);
+        await guardWindowsCommandLineBudget({ runId: input.runId, def, launchPath: launch.launchPath, args }, { 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({ cwd: input.cwd, childEnv, invocation }, { spawn: spawnFn });
+        if (spawnResult.kind === 'error') {
+            await releaseStagedResources();
+            return failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: spawn threw synchronously for agent "${def.id}": ${errorMessage(spawnResult.error)}`);
         }
-        const stdinHandle = streamFormat === 'acp-json-rpc' || streamFormat === 'pi-rpc'
-            ? null
-            : wireChildLifecycle({
+        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 stdinHandle = isStdinDrivenFormat(streamFormat)
+            ? wireChildLifecycle({
                 runId: input.runId,
                 def,
                 streamFormat,
@@ -1184,94 +2270,73 @@ export function createAgentExecutor(options) {
                 collectProcessTreePids: collectProcessTreePidsFn,
                 stopProcesses: stopProcessesFn,
                 onCleanupFailure: onCleanupFailureFn,
-                cleanupPromptFile,
+                cleanupStagedFiles,
                 journal,
                 continuation,
                 classifyFailure,
-            });
-        try {
-            await waitForSpawnOrError(child);
-        }
-        catch (err) {
-            await cleanupPromptFile();
-            await lifecycle.finish({ runId: input.runId, status: 'failed', code: null, signal: null, resumable: false });
-            throw new AgentExecutorError('AGENT_SPAWN_FAILED', `AgentExecutor: failed to spawn agent "${def.id}": ${errorMessage(err)}`);
-        }
+                bufferedStdoutMaxBytes,
+            })
+            : null;
+        await confirmChildSpawned({ runId: input.runId, def, child }, { 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, { logFilePath: preparedLogFile?.path, model: selectedModel, processExited: processExitedController.signal }, releaseRuntimeLock);
         if (streamFormat === 'acp-json-rpc') {
-            try {
-                wireAcpLifecycle({
-                    runId: input.runId,
-                    agentId: def.id,
-                    child,
-                    lifecycle,
-                    prompt: input.prompt,
-                    cwd: input.cwd,
-                    model: input.model,
-                    imagePaths: input.imagePaths ?? [],
-                    envFormat: def.acpMcpEnvFormat,
-                    onPermissionRequest: options.acpPermissionHandler,
-                    attachAcpSession: attachAcpSessionFn,
-                    listProcessSnapshots: listProcessSnapshotsFn,
-                    collectProcessTreePids: collectProcessTreePidsFn,
-                    stopProcesses: stopProcessesFn,
-                    onCleanupFailure: onCleanupFailureFn,
-                    cleanupPromptFile,
-                    journal,
-                    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: listProcessSnapshotsFn,
-                    collectProcessTreePids: collectProcessTreePidsFn,
-                    stopProcesses: stopProcessesFn,
-                }, child, input.runId, 'acp-attach-failure', onCleanupFailureFn);
-                await cleanupPromptFile();
-                await lifecycle.finish({ runId: input.runId, status: 'failed', code: null, signal: null, resumable: false });
-                throw new AgentExecutorError('AGENT_SPAWN_FAILED', `AgentExecutor: could not attach ACP session for agent \"${def.id}\": ${errorMessage(err)}`);
-            }
+            await runAcpDispatch({
+                runId: input.runId,
+                agentId: def.id,
+                child,
+                prompt: input.prompt,
+                cwd: input.cwd,
+                model: input.model,
+                imagePaths: input.imagePaths ?? [],
+                envFormat: def.acpMcpEnvFormat,
+                mcpBridge,
+            }, {
+                lifecycle,
+                attachAcpSession: attachAcpSessionFn,
+                onPermissionRequest: options.acpPermissionHandler,
+                listProcessSnapshots: listProcessSnapshotsFn,
+                collectProcessTreePids: collectProcessTreePidsFn,
+                stopProcesses: stopProcessesFn,
+                onCleanupFailure: onCleanupFailureFn,
+                cleanupStagedFiles,
+                journal,
+                classifyFailure,
+                releaseStagedResources,
+                failBeforeSpawn,
+            });
             return;
         }
         if (streamFormat === 'pi-rpc') {
-            try {
-                wirePiRpcLifecycle({
-                    runId: input.runId,
-                    agentId: def.id,
-                    child,
-                    lifecycle,
-                    prompt: input.prompt,
-                    cwd: input.cwd,
-                    model: input.model,
-                    imagePaths: input.imagePaths ?? [],
-                    uploadRoot: input.uploadRoot,
-                    attachPiRpcSession: attachPiRpcSessionFn,
-                    listProcessSnapshots: listProcessSnapshotsFn,
-                    collectProcessTreePids: collectProcessTreePidsFn,
-                    stopProcesses: stopProcessesFn,
-                    onCleanupFailure: onCleanupFailureFn,
-                    cleanupPromptFile,
-                    journal,
-                    classifyFailure,
-                });
-            }
-            catch (err) {
-                // Same discipline as the ACP attach-failure path directly above: await cleanup here
-                // rather than fire-and-forget (SEC-007).
-                await terminateChildTreeBestEffort({
-                    listProcessSnapshots: listProcessSnapshotsFn,
-                    collectProcessTreePids: collectProcessTreePidsFn,
-                    stopProcesses: stopProcessesFn,
-                }, child, input.runId, 'pi-rpc-attach-failure', onCleanupFailureFn);
-                await cleanupPromptFile();
-                await lifecycle.finish({ runId: input.runId, status: 'failed', code: null, signal: null, resumable: false });
-                throw new AgentExecutorError('AGENT_SPAWN_FAILED', `AgentExecutor: could not attach pi-rpc session for agent \"${def.id}\": ${errorMessage(err)}`);
-            }
+            await runPiRpcDispatch({
+                runId: input.runId,
+                agentId: def.id,
+                child,
+                prompt: input.prompt,
+                cwd: input.cwd,
+                model: input.model,
+                imagePaths: input.imagePaths ?? [],
+                uploadRoot: input.uploadRoot,
+            }, {
+                lifecycle,
+                attachPiRpcSession: attachPiRpcSessionFn,
+                listProcessSnapshots: listProcessSnapshotsFn,
+                collectProcessTreePids: collectProcessTreePidsFn,
+                stopProcesses: stopProcessesFn,
+                onCleanupFailure: onCleanupFailureFn,
+                cleanupStagedFiles,
+                journal,
+                classifyFailure,
+                releaseStagedResources,
+                failBeforeSpawn,
+            });
             return;
         }
-        writePromptToStdin(def, child, input.prompt, stdinHandle);
+        writePromptToStdin(def, child, imageDelivery.prompt, stdinHandle);
     }
     return { run };
 }