@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5682

package/dist/core/codex-app-server-runner.js

@@ -0,0 +1,1271 @@
+import { productEnv } from './product-env.js';
+import { uiAskQuestions } from './ask.js';
+import { summarizeRunnerStderr } from './runner-stderr.js';
+import { randomUUID } from 'node:crypto';
+import { parseEffort } from '../contract/index.js';
+import { prependSystemPrompt, trackChildExit, } from './agent-runner.js';
+import { RUNNER_FACTS } from './runner-facts.js';
+import { codexToolGrantFields } from './runner-tool-grants.js';
+import { signalSession } from './session-process.js';
+import { afterExitDrain, AUTO_END_DELAY_MS, DEFAULT_RUN_TIMEOUT_MS, exitDrainBudget, KILL_GRACE_MS, } from './runner-runtime.js';
+import { parseAskRequest } from './ask.js';
+import { readNdjson } from './ndjson.js';
+import { drainsAfterClose, isServerRequest, isStaleTurnOutcome, parseNativeLine, sessionExitEvent, sessionStderrIsUnexpected, startupCrashOwnsFailure, stringField, turnIdOf } from './codex-native-frames.js';
+import { V1TextCoalescer } from './v1-text-coalescer.js';
+import { InputSubmissions } from './input-submissions.js';
+import { codexStreamError } from './codex-stream-error.js';
+import { codexTurnOutcome } from './codex-turn-outcome.js';
+import { codexNetworkIsRestricted, codexPermissionOverrides } from './codex-permissions.js';
+import { codexApproval, isCodexApprovalRequest } from './codex-approvals.js';
+import { cezarToolEnvNames } from '../ci-wait/tools.js';
+import { CodexAppServerRpc, CodexRpcResponseError, codexSpawnError, endCodexAppServer, resolveCodexExecutable, spawnCodexAppServer, waitForCodexAppServerExit, } from './codex-app-server-transport.js';
+import { codexSessionStarted, createCodexUiState, mapCodexNotification, } from './codex-ui-mapper.js';
+// One startup budget, including handshake ACKs and the first main-thread turn.
+// This is not a model-turn or human-question lifetime limit.
+const STARTUP_TIMEOUT_MS = 60_000;
+// A retry episode gets one budget, regardless of error/warning frequency.
+const STREAM_RETRY_TIMEOUT_MS = 60_000;
+/**
+ * `AgentRunner` over `codex app-server` — the same JSONL transport the VS Code
+ * extension and desktop app use (JSON-RPC 2.0, newline-delimited, over
+ * stdin/stdout). One long-lived process per session gives Codex the same
+ * multi-turn shape as the Claude runner: `turn/start` for a new turn,
+ * `turn/steer` for a mid-turn follow-up, `turn/interrupt` to cancel, and
+ * `thread/resume` to reopen a stored thread for "Continue".
+ *
+ * Auth = the host's logged-in ChatGPT/Codex session (or CODEX_API_KEY). The
+ * agent inherits managed permissions; confirmed unmanaged sessions keep cezar's
+ * full-access default. Approval policy always belongs to the app-server.
+ * Codex has no per-tool allowlist, so
+ * `spec.toolGrant` is ignored. `CEZ_CODEX_NETWORK=0` requires a confirmed
+ * network restriction without replacing managed filesystem rules.
+ */
+/**
+ * What the codex app-server receives from each `AgentRunSpec` field (#284).
+ * Tool access does not cross this wire: managed permissions belong to Codex;
+ * unmanaged sessions use cezar's sandbox choice. The app-server has no per-tool
+ * allowlist, so `toolGrant` is declared dropped rather than mapped (spec
+ * 2026-07-17-permission-modes). Held against the recorded JSON-RPC by the harness parity matrix.
+ */
+export const CODEX_SPEC_SUPPORT = {
+    cezarTools: { honored: true, via: 'thread/start and thread/resume dotted mcp_servers config with env_vars and default_tools_approval_mode approve' },
+    systemPrompt: { honored: true, via: 'prepended to the opening turn/start input through prependSystemPrompt' },
+    userPrompt: { honored: true, via: 'turn/start input text' },
+    images: { honored: false, reason: 'the adapter sends text input items only; image blocks are dropped' },
+    cwd: { honored: true, via: 'spawn cwd, and the thread/start / thread/resume cwd' },
+    toolGrant: { honored: false, reason: 'no per-tool allowlist on the app-server, so no command-prefix restriction either; managed permissions and approval policy belong to Codex' },
+    restrictCrossSessionMessaging: { honored: true, via: 'thread/start and thread/resume config features.agent_message_board=false; multi-agent tools reach only the session\'s own agents and stay as configured (hearsay-tools/cezarion#2279)' },
+    additionalDirectories: { honored: false, reason: 'no extra-root mapping; managed filesystem permissions belong to Codex' },
+    env: { honored: true, via: 'merged over the child env through buildCodexAppServerEnv' },
+    model: { honored: true, via: 'thread/start and thread/resume model' },
+    effort: { honored: true, via: 'turn/start effort, canonical level' },
+    timeoutMs: { honored: true, via: 'wall-clock kill switch on the child process' },
+    sessionId: { honored: true, via: 'thread/resume threadId when resume is set; a fresh thread/start mints its own thread id' },
+    resume: { honored: true, via: 'thread/resume in place of thread/start' },
+    resumeFallbackSystemPrompt: { honored: false, reason: 'thread/resume fails a missing thread; the adapter does not open a replacement thread' },
+};
+export class CodexAppServerRunner {
+    backend = 'codex';
+    specSupport = CODEX_SPEC_SUPPORT;
+    systemPromptOnResume = RUNNER_FACTS.codex.systemPromptOnResume;
+    facts = RUNNER_FACTS.codex;
+    inputDelivery = RUNNER_FACTS.codex.inputDelivery;
+    bin;
+    timeoutMs;
+    lastSession = null;
+    constructor(opts = {}) {
+        this.bin = resolveCodexExecutable(opts.bin);
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_RUN_TIMEOUT_MS;
+    }
+    run(spec, onEvent) {
+        return this.startSession(spec, onEvent, { autoEndAfterFirstTurn: true }).result;
+    }
+    async interrupt() {
+        this.lastSession?.interrupt();
+    }
+    startSession(spec, onEvent, opts = {}) {
+        const session = new CodexSession(this.bin, this.timeoutMs, spec, onEvent, opts);
+        this.lastSession = session;
+        return session;
+    }
+}
+/** One live `codex app-server` process driving a single thread. */
+class CodexSession {
+    bin;
+    spec;
+    onEvent;
+    opts;
+    result;
+    child;
+    rpc;
+    stdinOpen = true;
+    threadId;
+    activeTurnId;
+    streamRetryTimer;
+    streamRetryError;
+    agentInputReady = false;
+    /** Accepted agent input not yet seen as a consumed userMessage item (#505). */
+    submissions = new InputSubmissions();
+    inFlightSubmissionId;
+    refusedBeforeStartup = false;
+    humanPromptsPending = 0;
+    refusedForHuman = false;
+    /** Human sendMessage client ids still inside startOrSteerTurn (#486). */
+    humanSteerIds = new Set();
+    /** RPC id → human client id; cleared synchronously when that response is dispatched. */
+    humanPromptByRpc = new Map();
+    /** Human turn/start RPC ids — release on their response even before turn/started. */
+    humanStartRpcs = new Set();
+    /** Hint on the next turn/started after a human turn/start was accepted without a live turn. */
+    humanReadyOnTurnStart = false;
+    releasedHuman = new Set();
+    /** Human client ids already echoed as an in-turn userMessage (read-in-turn). */
+    echoedHuman = new Set();
+    /** Human steers admitted in-turn and not yet echoed; restarted on turn end (#486). */
+    unreadHumanSteers = new Map();
+    /** Submissions that opened a turn via turn/start rather than steering one. */
+    turnStartSubmissions = new Set();
+    /** Recent main-thread turn outcomes (true = completed without error), for a late turn/start response. */
+    completedTurns = new Map();
+    turnCompletions = 0;
+    agentSubmissionPending = false;
+    turnBoundaryVersion = 0;
+    pendingUserInput;
+    pendingApprovals = new Map();
+    toolCalls = [];
+    textChunks = [];
+    /** Streamed agentMessage deltas buffered per item — v1 `text` is emitted
+     *  once per completed item (claude parity: one event per complete block),
+     *  never per delta, so the persisted transcript and the headless CLI get
+     *  whole paragraphs. Streaming display rides protocol v2's `item.delta`. */
+    textCoalescer = new V1TextCoalescer((text) => {
+        this.textChunks.push(text);
+        this.emit({ type: 'text', text });
+    });
+    tokensUsed = 0;
+    ready;
+    startupPhase = 'initialize';
+    openingAcknowledged = false;
+    firstTurnStarted = false;
+    startupComplete = false;
+    startupTimer;
+    stopKillTimer;
+    hardStopStarted = false;
+    failure;
+    autoEndTimer;
+    eofTermTimer;
+    eofKillTimer;
+    spawnFailed = null;
+    timedOut = false;
+    /** Explicit teardown or automatic cleanup with positive live evidence. */
+    terminatedByCezar = false;
+    explicitEnd = false;
+    automaticCleanupStarted = false;
+    /** Native termination, independent of signal delivery (`child.killed`). */
+    hasExited;
+    /** Protocol v2 emission — additive alongside v1 (`onEvent` keeps flowing
+     *  byte-identical); the channel is `opts.onUiEvent` (RunManager wiring
+     *  lands in R2 step 2.1). */
+    uiState = createCodexUiState();
+    constructor(bin, timeoutMs, spec, onEvent, opts) {
+        this.bin = bin;
+        this.spec = spec;
+        this.onEvent = onEvent;
+        this.opts = opts;
+        try {
+            this.child = spawnCodexAppServer(bin, spec.cwd, spec.env, { session: true });
+            this.rpc = new CodexAppServerRpc(this.child, (error) => {
+                if (!this.hardStopStarted && !this.hasExited())
+                    this.fail(error);
+            });
+        }
+        catch (err) {
+            throw codexSpawnError(err, bin);
+        }
+        const hasExited = trackChildExit(this.child);
+        this.hasExited = hasExited;
+        // Observe termination BEFORE bootstrap. Pending RPCs cannot own the only
+        // path to discovering that their process has already gone (#493).
+        const exited = waitForCodexAppServerExit(this.child);
+        // After real process exit, allow buffered output to drain before closing pipes
+        // a descendant may have inherited. This drain never proves termination.
+        let cancelDrain;
+        this.child.on('error', (err) => {
+            if (this.child.pid === undefined) {
+                this.spawnFailed = codexSpawnError(err, bin);
+                this.closeInput(this.spawnFailed.message);
+                this.child.stdout.destroy();
+            }
+            else if (this.stdinOpen) {
+                this.fail(new Error(`codex app-server process error while waiting for ${this.startupPhase}`));
+            }
+        });
+        this.child.once('exit', (code, signal) => {
+            if (this.stdinOpen && !this.startupComplete) {
+                this.failure ??= new Error(`Codex startup exited (${signal ?? code ?? 'unknown'}) while waiting for ${this.startupPhase}`);
+            }
+            // Do not discard final buffered text on a healthy exit. Revoke RPCs
+            // immediately, then bound pipe draining ONLY after physical termination.
+            this.expireApprovals('codex app-server exited', false);
+            this.rpc.close('codex app-server exited');
+            cancelDrain = afterExitDrain(() => this.child.stdout.destroy(), exitDrainBudget(code));
+            if (this.stopKillTimer)
+                clearTimeout(this.stopKillTimer);
+        });
+        const stderrChunks = [];
+        this.child.stderr.setEncoding('utf8');
+        this.child.stderr.on('data', (chunk) => stderrChunks.push(chunk));
+        // Whole-session timeouts remain optional; startup is always bounded.
+        const limitMs = spec.timeoutMs ?? timeoutMs;
+        let deadline;
+        if (limitMs > 0) {
+            deadline = setTimeout(() => {
+                this.timedOut = true;
+                this.interrupt();
+            }, limitMs);
+            deadline.unref?.();
+        }
+        this.startupTimer = setTimeout(() => {
+            this.fail(new Error(`Codex startup timed out after 60s while waiting for ${this.startupPhase}`), 'timed out after 60s');
+        }, STARTUP_TIMEOUT_MS);
+        this.startupTimer.unref?.();
+        this.ready = this.bootstrap();
+        const reader = this.readNativeOutput();
+        this.result = this.finishSession(hasExited, exited, reader, deadline, () => cancelDrain?.(), stderrChunks, limitMs, spec);
+    }
+    /** Wait out the child, then map its exit onto the v1 result. Both awaits stay here, so
+     *  the cleanup and the result mapping run in the same continuation as the second await. */
+    async finishSession(hasExited, exited, reader, deadline, cancelDrain, stderrChunks, limitMs, spec) {
+        let exitCode;
+        try {
+            try {
+                await Promise.all([this.ready, reader]);
+            }
+            catch (err) {
+                if (this.stdinOpen && !hasExited())
+                    this.fail(err instanceof Error ? err : new Error(String(err)));
+            }
+            // RPC cancellation is not a receipt for process termination. Keep the
+            // TERM→KILL watchdog alive until this independently owned promise settles.
+            exitCode = await exited;
+            await reader;
+        }
+        finally {
+            if (deadline)
+                clearTimeout(deadline);
+            cancelDrain();
+            this.releaseSession();
+        }
+        return this.resultFromExit(exitCode, stderrChunks.join(''), limitMs, spec);
+    }
+    releaseSession() {
+        if (this.stopKillTimer)
+            clearTimeout(this.stopKillTimer);
+        if (this.eofTermTimer)
+            clearTimeout(this.eofTermTimer);
+        if (this.eofKillTimer)
+            clearTimeout(this.eofKillTimer);
+        this.closeInput('codex app-server exited');
+        this.child.stdin.destroy();
+        this.child.stderr.destroy();
+    }
+    resultFromExit(exitCode, stderr, limitMs, spec) {
+        if (this.spawnFailed)
+            throw this.spawnFailed;
+        // Preserve diagnostics even when an RPC/startup failure already owns the error.
+        if (stderr.trim() && (this.failure || sessionStderrIsUnexpected(exitCode, this.timedOut, this.terminatedByCezar))) {
+            this.emit({ type: 'note', message: `codex app-server stderr:\n${stderr}` });
+        }
+        // Before the first prompt ACK, process/pipe closure can own the failure
+        // before the ordinary crash branch. Keep its phase context and expose
+        // the drained terminal exception on the same v1 error seam as later exits.
+        if (this.failure)
+            this.throwOwnedFailure(stderr, exitCode, this.startupComplete, this.timedOut, this.terminatedByCezar);
+        return this.resultFromCleanExit(exitCode, stderr, limitMs, spec);
+    }
+    throwOwnedFailure(stderr, exitCode, startupComplete, timedOut, terminatedByCezar) {
+        if (!startupCrashOwnsFailure({ startupComplete, timedOut, terminatedByCezar }, stderr, exitCode))
+            throw this.failure;
+        const detail = summarizeRunnerStderr(stderr);
+        const message = `codex app-server exited with code ${exitCode}${detail ? ` — ${detail}` : ''} (${this.failure.message})`;
+        this.emit({ type: 'error', message });
+        throw new Error(message);
+    }
+    resultFromCleanExit(exitCode, stderr, limitMs, spec) {
+        // Timeout/interrupt can end the read loop mid-item — recover buffered prose.
+        this.textCoalescer.flush();
+        const base = {
+            text: this.textChunks.join('\n').trim(), toolCalls: this.toolCalls,
+            tokensUsed: this.tokensUsed, sessionId: this.threadId ?? spec.sessionId,
+        };
+        const settled = sessionExitEvent({
+            timedOut: this.timedOut, terminatedByCezar: this.terminatedByCezar, exitCode, signalCode: this.child.signalCode,
+            limitMs, stderrSummary: summarizeRunnerStderr(stderr),
+        });
+        if (settled && 'failure' in settled) {
+            this.emit({ type: 'error', message: settled.failure });
+            throw new Error(settled.failure);
+        }
+        if (settled)
+            this.emit({ type: settled.event, message: settled.message });
+        this.emit({ type: 'done' });
+        return base;
+    }
+    get open() {
+        return this.stdinOpen && this.rpc.open && !this.hasExited();
+    }
+    get pid() {
+        return this.child.pid;
+    }
+    sendAgentMessage(content, inputIds = []) {
+        // #505: a running turn is steered with turn/steer; only an unanswered native ask
+        // or an in-flight submission refuses.
+        // Until the thread and its first turn exist there is nothing to steer or start;
+        // a refusal here earns one readiness hint when startup completes.
+        if (this.open && !this.startupComplete) {
+            this.refusedBeforeStartup = true;
+            return false;
+        }
+        // A human prompt still on its way to the wire goes first (#505 local review).
+        if (this.open && this.humanPromptsPending > 0) {
+            this.refusedForHuman = true;
+            return false;
+        }
+        if (!this.open || this.pendingUserInput || this.pendingApprovals.size || this.agentSubmissionPending)
+            return false;
+        this.agentInputReady = false;
+        this.agentSubmissionPending = true;
+        if (this.autoEndTimer)
+            clearTimeout(this.autoEndTimer);
+        this.autoEndTimer = undefined;
+        const submissionId = randomUUID();
+        this.submissions.accept(submissionId, inputIds, '');
+        this.inFlightSubmissionId = submissionId;
+        // Reserve synchronously; only the matching RPC result acknowledges delivery.
+        return this.startOrSteerTurn(textOf(content), submissionId).catch((err) => {
+            this.submissions.consume(submissionId); // never accepted: the caller keeps ownership
+            if (this.stdinOpen)
+                this.emit({ type: 'error', message: `codex: agent input failed: ${String(err)}` });
+            throw err;
+        }).finally(() => {
+            this.agentSubmissionPending = false;
+            if (this.inFlightSubmissionId === submissionId)
+                this.inFlightSubmissionId = undefined;
+            if (this.stdinOpen && this.agentInputReady && !this.pendingUserInput && !this.pendingApprovals.size) {
+                this.opts.onAgentInputReady?.();
+                this.scheduleAutoEnd();
+            }
+        });
+    }
+    scheduleAutoEnd() {
+        if (!this.opts.autoEndAfterFirstTurn || !this.open || this.autoEndTimer || this.agentSubmissionPending || this.pendingApprovals.size)
+            return;
+        this.autoEndTimer = setTimeout(() => {
+            this.autoEndTimer = undefined;
+            if (this.opts.shouldAutoEnd?.() !== false)
+                this.end();
+        }, AUTO_END_DELAY_MS);
+        this.autoEndTimer.unref?.();
+    }
+    sendMessage(content) {
+        this.agentInputReady = false;
+        if (!this.open || this.pendingApprovals.size)
+            return false;
+        if (this.autoEndTimer) {
+            clearTimeout(this.autoEndTimer);
+            this.autoEndTimer = undefined;
+        }
+        const text = textOf(content);
+        if (!text)
+            return true;
+        if (this.pendingUserInput) {
+            const pending = this.pendingUserInput;
+            this.pendingUserInput = undefined;
+            this.rpc.respond({ id: pending.rpcId, result: { answers: userInputAnswers(pending.questions, text) } });
+            return this.open;
+        }
+        // Wait for the thread to exist, then steer the live turn or start a new one. Agent input
+        // waits until this prompt's request settles, so it can never overtake it.
+        const clientUserMessageId = randomUUID();
+        this.humanSteerIds.add(clientUserMessageId);
+        this.humanPromptsPending += 1;
+        void this.ready
+            .then(() => this.startOrSteerTurn(text, clientUserMessageId))
+            .catch((err) => {
+            if (this.stdinOpen) {
+                const message = err instanceof Error ? err.message : String(err);
+                this.emit({ type: 'note', message: `codex: turn failed: ${message}` });
+            }
+        })
+            .finally(() => this.finishHumanSteer(clientUserMessageId));
+        return true;
+    }
+    trackHumanRpc(id, clientUserMessageId, kind = 'steer') {
+        if (!this.humanSteerIds.has(clientUserMessageId))
+            return;
+        this.humanPromptByRpc.set(id, clientUserMessageId);
+        if (kind === 'start')
+            this.humanStartRpcs.add(id);
+    }
+    releaseHumanPrompt(clientUserMessageId, notify = true) {
+        for (const [rpc, id] of this.humanPromptByRpc)
+            if (id === clientUserMessageId) {
+                this.humanPromptByRpc.delete(rpc);
+                this.humanStartRpcs.delete(rpc);
+            }
+        if (this.releasedHuman.has(clientUserMessageId))
+            return;
+        this.releasedHuman.add(clientUserMessageId);
+        this.humanPromptsPending = Math.max(0, this.humanPromptsPending - 1);
+        if (notify)
+            this.notifyHumanInputDrained();
+    }
+    /** Drop bookkeeping once this id is no longer waiting for an echo or a restart. */
+    finishHumanSteer(clientUserMessageId) {
+        if (this.unreadHumanSteers.has(clientUserMessageId))
+            return;
+        this.humanSteerIds.delete(clientUserMessageId);
+        this.releaseHumanPrompt(clientUserMessageId);
+        this.releasedHuman.delete(clientUserMessageId);
+        this.echoedHuman.delete(clientUserMessageId);
+    }
+    /** turn/steer admitted this id into a live turn; keep holding until echo or turn end. */
+    holdUnreadHumanSteer(clientUserMessageId, text) {
+        this.unreadHumanSteers.set(clientUserMessageId, text);
+    }
+    /** Read-in-turn: the userMessage echo is the read. Do not restart this id. */
+    noteHumanEcho(clientId) {
+        if (!this.humanSteerIds.has(clientId))
+            return;
+        this.echoedHuman.add(clientId);
+        const heldUnread = this.unreadHumanSteers.delete(clientId);
+        this.releaseHumanPrompt(clientId);
+        if (heldUnread)
+            this.finishHumanSteer(clientId);
+    }
+    /** Admitted but never echoed: start a turn under the same clientUserMessageId. */
+    restartUnreadHumanSteers() {
+        if (this.unreadHumanSteers.size === 0)
+            return;
+        const pending = [...this.unreadHumanSteers];
+        this.unreadHumanSteers.clear();
+        if (this.autoEndTimer) {
+            clearTimeout(this.autoEndTimer);
+            this.autoEndTimer = undefined;
+        }
+        for (const [id, text] of pending) {
+            if (!this.open || this.echoedHuman.has(id)) {
+                this.finishHumanSteer(id);
+                continue;
+            }
+            void this.startOrSteerTurn(text, id)
+                .catch((err) => {
+                if (this.stdinOpen) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    this.emit({ type: 'note', message: `codex: turn failed: ${message}` });
+                }
+            })
+                .finally(() => this.finishHumanSteer(id));
+        }
+    }
+    notifyHumanInputDrained() {
+        // A just-accepted turn/start may not have `activeTurnId` yet; run.ts ignores
+        // settle once turn.started clears atTurnBoundary. Do not block on activeTurnId.
+        if (this.humanPromptsPending > 0 || this.humanReadyOnTurnStart || !this.open || this.pendingUserInput || this.pendingApprovals.size || this.agentSubmissionPending)
+            return;
+        if (this.refusedForHuman)
+            this.refusedForHuman = false;
+        this.opts.onAgentInputReady?.();
+    }
+    discardQueuedMessages() { }
+    holdsHumanInput() { return this.humanPromptsPending > 0 || this.humanReadyOnTurnStart; }
+    heldHumanInputCount() { return this.humanPromptsPending + (this.humanReadyOnTurnStart ? 1 : 0); }
+    end(explicit = true) {
+        if (explicit && !this.hasExited()) {
+            this.explicitEnd = true;
+            this.terminatedByCezar ||= this.automaticCleanupStarted;
+        }
+        if (!this.stdinOpen)
+            return;
+        this.closeInput('session ended');
+        try {
+            endCodexAppServer(this.child, (term, kill) => {
+                this.eofTermTimer = term;
+                this.eofKillTimer = kill;
+            }, (state) => {
+                this.automaticCleanupStarted = true;
+                this.terminatedByCezar ||= this.explicitEnd || state === 'live';
+            });
+        }
+        catch { /* already gone */ }
+    }
+    interrupt() {
+        if (this.hardStopStarted || this.hasExited())
+            return;
+        this.hardStopStarted = true;
+        if (!this.automaticCleanupStarted) {
+            if (this.eofTermTimer)
+                clearTimeout(this.eofTermTimer);
+            if (this.eofKillTimer)
+                clearTimeout(this.eofKillTimer);
+        }
+        if (this.stdinOpen && this.threadId && this.activeTurnId) {
+            void this.rpc.request('turn/interrupt', { threadId: this.threadId, turnId: this.activeTurnId }).catch(() => undefined);
+        }
+        this.closeInput('codex session stopped');
+        this.terminatedByCezar = true;
+        signalSession(this.child, 'SIGTERM');
+        this.stopKillTimer = setTimeout(() => {
+            if (!this.hasExited())
+                signalSession(this.child, 'SIGKILL');
+        }, KILL_GRACE_MS);
+        this.stopKillTimer.unref?.();
+    }
+    closeInput(reason) {
+        this.clearStreamRetry();
+        this.stdinOpen = false;
+        // Respond while stdin is still writable, before rpc.close or EOF/TERM.
+        this.expireApprovals(reason);
+        this.humanReadyOnTurnStart = false;
+        for (const id of [...this.unreadHumanSteers.keys()]) {
+            this.unreadHumanSteers.delete(id);
+            this.finishHumanSteer(id);
+        }
+        this.rejectPendingUserInput(reason);
+        this.agentInputReady = false;
+        if (this.startupTimer)
+            clearTimeout(this.startupTimer);
+        if (this.autoEndTimer)
+            clearTimeout(this.autoEndTimer);
+        this.rpc.close(reason);
+    }
+    fail(error, diagnostic = 'failed') {
+        if (!this.stdinOpen)
+            return;
+        this.failure ??= error;
+        // Stage-only diagnostics never include prompt/config/env or raw stderr.
+        const message = this.startupComplete ? 'Codex app-server failed; closing app-server'
+            : `Codex startup ${diagnostic} while waiting for ${this.startupPhase}; closing app-server`;
+        try {
+            this.emit({ type: 'note', message });
+        }
+        catch { /* A failing diagnostic sink cannot release a still-live process. */ }
+        this.interrupt();
+    }
+    assertOpen() {
+        if (!this.open)
+            throw new Error('codex session closed');
+    }
+    startupWaitingFor(phase) {
+        this.assertOpen();
+        this.startupPhase = phase;
+        this.emit({ type: 'note', message: `Codex startup: waiting for ${phase}` });
+    }
+    checkStartupComplete() {
+        if (!this.openingAcknowledged || !this.firstTurnStarted || !this.stdinOpen)
+            return;
+        if (this.startupComplete)
+            return;
+        this.startupComplete = true;
+        if (this.startupTimer)
+            clearTimeout(this.startupTimer);
+        // Input refused during startup can now steer the opening turn (#505).
+        if (this.refusedBeforeStartup)
+            queueMicrotask(() => {
+                this.refusedBeforeStartup = false;
+                if (this.open && !this.pendingUserInput && !this.pendingApprovals.size && !this.agentSubmissionPending)
+                    this.opts.onAgentInputReady?.();
+            });
+    }
+    // ---- protocol -----------------------------------------------------------
+    async bootstrap() {
+        this.startupWaitingFor('initialize');
+        await this.rpc.initialize();
+        this.assertOpen();
+        this.startupWaitingFor('configRequirements/read');
+        // Read through the same authenticated app-server as the thread. Do not
+        // guess policy from a local config file: enterprise requirements may be remote.
+        let requirements;
+        try {
+            requirements = await this.rpc.request('configRequirements/read', {});
+        }
+        catch (error) {
+            if (!(error instanceof CodexRpcResponseError))
+                throw error;
+            this.emit({ type: 'note', message: 'Codex requirements unavailable; using Codex permission defaults' });
+        }
+        this.assertOpen();
+        const restrictNetwork = productEnv('CODEX_NETWORK') === '0';
+        const overrides = {
+            model: this.spec.model,
+            cwd: this.spec.cwd,
+            ...codexToolGrantFields(this.spec.toolGrant),
+            ...codexPermissionOverrides(requirements, restrictNetwork),
+            // Start and resume accept dotted config overrides; no global config write. Governed sessions
+            // keep multi-agent and lose only the cross-thread message board (hearsay-tools/cezarion#2279).
+            ...((restrictNetwork || this.spec.restrictCrossSessionMessaging || this.spec.cezarTools) ? { config: {
+                    ...(restrictNetwork ? { 'sandbox_workspace_write.network_access': false } : {}),
+                    ...(this.spec.restrictCrossSessionMessaging ? { 'features.agent_message_board': false } : {}),
+                    // hearsay-tools/cezarion#1294: Codex asks before every MCP tool call unless the
+                    // server's mode is `approve`, and cezar's own tools must never wait on that.
+                    // approval_policy stays the user's (#381); older Codex ignores the unknown key.
+                    ...(this.spec.cezarTools ? { [`mcp_servers.${this.spec.cezarTools.name}`]: { command: this.spec.cezarTools.command, args: this.spec.cezarTools.args, env_vars: cezarToolEnvNames(this.spec.env ?? {}), default_tools_approval_mode: 'approve' } } : {}),
+                } } : {}),
+        };
+        let threadResponse;
+        if (this.spec.resume && this.spec.sessionId) {
+            this.startupWaitingFor('thread/resume');
+            threadResponse = await this.rpc.request('thread/resume', { threadId: this.spec.sessionId, ...clean(overrides) });
+            this.assertOpen();
+            this.threadId = this.spec.sessionId;
+        }
+        else {
+            this.startupWaitingFor('thread/start');
+            threadResponse = await this.rpc.request('thread/start', clean(overrides));
+            this.assertOpen();
+            this.threadId = threadIdOf(threadResponse) ?? this.spec.sessionId;
+        }
+        // Named managed profiles may ignore legacy sandbox settings. Do not silently
+        // run with network enabled, or replace their filesystem rules to disable it.
+        if (restrictNetwork && !codexNetworkIsRestricted(threadResponse)) {
+            throw new Error('CEZ_CODEX_NETWORK=0 requires a network-restricted Codex permission policy; the thread did not confirm one');
+        }
+        if (this.threadId) {
+            this.emit({ type: 'session', sessionId: this.threadId });
+            // The result path (thread/start response, or thread/resume which sends
+            // no thread/started notification) — deduplicated inside the mapper.
+            const threadId = this.threadId;
+            this.emitUi((state) => codexSessionStarted(threadId, state));
+        }
+        // Seed the first turn. The system prompt (skill body + handoff contract)
+        // has no dedicated app-server field, so it rides along as a leading block
+        // of the opening message.
+        const first = prependSystemPrompt(this.spec.systemPrompt, this.spec.userPrompt);
+        this.startupWaitingFor('turn/start');
+        await this.startOrSteerTurn(first);
+        this.assertOpen();
+        this.openingAcknowledged = true;
+        this.checkStartupComplete();
+        if (!this.startupComplete)
+            this.startupWaitingFor('first main-thread turn');
+    }
+    async startOrSteerTurn(text, clientUserMessageId) {
+        this.assertOpen();
+        if (!this.threadId)
+            throw new Error('codex app-server did not return a thread id');
+        this.agentInputReady = false;
+        const input = [{ type: 'text', text, text_elements: [] }];
+        // Echoed as the consumed userMessage item's `clientId` (#505).
+        const ids = clientUserMessageId ? { clientUserMessageId } : {};
+        const humanId = clientUserMessageId && this.humanSteerIds.has(clientUserMessageId) ? clientUserMessageId : undefined;
+        if (this.activeTurnId) {
+            if (await this.steerLiveTurn(input, ids, clientUserMessageId, humanId, text))
+                return;
+        }
+        else {
+            await this.startTurn(input, ids, clientUserMessageId, humanId);
+        }
+    }
+    /** The steer and, when it falls through, the turn/start request run in one continuation.
+     *  True when the steer settled the input. */
+    async steerLiveTurn(input, ids, clientUserMessageId, humanId, text) {
+        const boundary = this.turnBoundaryVersion;
+        const onSteerId = humanId ? (id) => this.trackHumanRpc(id, humanId, 'steer') : undefined;
+        let settled = false;
+        try {
+            await this.rpc.request('turn/steer', { threadId: this.threadId, input, expectedTurnId: this.activeTurnId, ...ids }, onSteerId);
+            settled = this.steerWasRead(clientUserMessageId, humanId, text, boundary);
+        }
+        catch (err) {
+            settled = this.steerRefusalSettled(err, clientUserMessageId, humanId, boundary);
+        }
+        if (!settled)
+            await this.startTurn(input, ids, clientUserMessageId, humanId);
+        return true;
+    }
+    /** Accepted, but the turn completed before the model read it: nothing will read it now,
+     *  so start a turn with it under the same client id (#505). Human steers get the same
+     *  restart so a coalesced steer+completed chunk cannot drop them (#486). Skip when the
+     *  turn already echoed this client id — it was read in-turn. */
+    steerWasRead(clientUserMessageId, humanId, text, boundary) {
+        const echoed = clientUserMessageId !== undefined && this.echoedHuman.has(clientUserMessageId);
+        const stranded = clientUserMessageId !== undefined && this.turnBoundaryVersion !== boundary && !this.activeTurnId && !echoed
+            && (this.submissions.has(clientUserMessageId) || this.humanSteerIds.has(clientUserMessageId));
+        if (stranded)
+            return false;
+        // Admission is not a read: keep a human steer held until echo or turn end.
+        if (humanId && this.activeTurnId && !echoed)
+            this.holdUnreadHumanSteer(humanId, text);
+        else if (humanId)
+            this.releaseHumanPrompt(humanId);
+        return true;
+    }
+    /** Only a definitive refusal falls back: the server answered with an error AND the turn
+     *  ended meanwhile. A timeout or closed transport is ambiguous — the steer may have
+     *  landed — so it rejects without a retry (#505). */
+    steerRefusalSettled(err, clientUserMessageId, humanId, boundary) {
+        if (!(err instanceof CodexRpcResponseError) || this.turnBoundaryVersion === boundary || this.activeTurnId)
+            throw err;
+        if (clientUserMessageId && this.echoedHuman.has(clientUserMessageId)) {
+            if (humanId)
+                this.releaseHumanPrompt(humanId);
+            return true;
+        }
+        return false;
+    }
+    async startTurn(input, ids, clientUserMessageId, humanId) {
+        // Ask the app-server for reasoning summaries; without this the model runs
+        // with its default (no summary), so the reasoning thread stays empty even
+        // though the mapper and UI can render it. The override persists for this
+        // turn and every subsequent turn, so seeding it on turn/start is enough.
+        const boundaryVersion = this.turnBoundaryVersion;
+        const completionsBefore = this.turnCompletions;
+        const onStartId = humanId ? (id) => this.trackHumanRpc(id, humanId, 'start') : undefined;
+        const res = await this.rpc.request('turn/start', {
+            threadId: this.threadId,
+            input,
+            ...ids,
+            ...codexTurnStartExtras(this.spec),
+        }, humanId && !this.activeTurnId ? onStartId : undefined);
+        if (clientUserMessageId)
+            this.recordStartedSubmission(clientUserMessageId, res, completionsBefore);
+        if (this.turnBoundaryVersion === boundaryVersion)
+            this.activeTurnId = turnIdOf(res) ?? this.activeTurnId;
+    }
+    /** This turn's own input: its completion proves the model processed it (#505). A response
+     *  can arrive after that turn already completed; settle it from the recorded outcome. */
+    recordStartedSubmission(clientUserMessageId, res, completionsBefore) {
+        const startedTurn = turnIdOf(res);
+        const outcome = startedTurn && this.turnCompletions > completionsBefore ? this.completedTurns.get(startedTurn) : undefined;
+        if (outcome === undefined) {
+            this.turnStartSubmissions.add(clientUserMessageId);
+            return;
+        }
+        const settled = this.submissions.consume(clientUserMessageId);
+        if (settled.length && outcome)
+            this.opts.onAgentInputConsumed?.(settled);
+        else if (settled.length)
+            this.emit({ type: 'input-unconsumed', inputIds: settled });
+    }
+    /** Native stdout reader. Every stage runs inside this one try, so a stage
+     *  throw ends the read the same way a transport failure does. */
+    async readNativeOutput() {
+        try {
+            for await (const line of readNdjson(this.child.stdout))
+                this.routeNativeLine(line);
+            this.settleNativeEof();
+        }
+        catch {
+            if (this.stdinOpen && !this.hasExited()) {
+                this.fail(new Error(`codex app-server output failed while waiting for ${this.startupPhase}`));
+            }
+        }
+    }
+    routeNativeLine(line) {
+        const msg = parseNativeLine(line);
+        if (msg === undefined)
+            return;
+        // A method+id is a server REQUEST, even if its method happens to name
+        // a lifecycle notification. It must never reach the notification mapper.
+        if (isServerRequest(msg)) {
+            if (this.open)
+                this.dispatch(msg);
+            return;
+        }
+        if (!this.admitsNotification(msg))
+            return;
+        this.opts.onActivity?.();
+        this.emitUi((state) => mapCodexNotification(msg, state));
+        this.dispatch(msg);
+    }
+    /** Lifecycle eligibility, then the current-turn filters, in that order. */
+    admitsNotification(msg) {
+        if (!this.open && !drainsAfterClose(msg, () => this.stdinOpen && this.hasExited()))
+            return false;
+        // Child turns do not reach either channel.
+        if (this.isForeignTurnLifecycle(msg))
+            return false;
+        // The UI mapper must not retire a live approval on an older turn's tail.
+        if (isStaleTurnOutcome(msg, this.activeTurnId))
+            return false;
+        // Stale/child retry errors must neither fail nor warn on this turn.
+        return msg.method !== 'error' || this.isCurrentTurn((msg.params ?? {}));
+    }
+    /** Clean EOF while the process lives: a startup failure, or automatic cleanup. */
+    settleNativeEof() {
+        if (!this.stdinOpen || this.hasExited())
+            return;
+        if (!this.startupComplete)
+            this.fail(new Error(`Codex startup stdout closed while waiting for ${this.startupPhase}`));
+        else
+            this.end(false);
+    }
+    dispatch(msg) {
+        if (typeof msg.method === 'string' && (typeof msg.id === 'number' || typeof msg.id === 'string')) {
+            if (msg.method === 'item/tool/requestUserInput')
+                this.handleUserInputRequest(msg.id, msg.params ?? {});
+            else if (isCodexApprovalRequest(msg.method, msg.params))
+                this.handleApprovalRequest(msg.method, msg.id, msg.params);
+            else
+                this.rpc.respond({ id: msg.id, error: { code: -32601, message: `unsupported server request: ${msg.method}` } });
+            return;
+        }
+        const humanClient = typeof msg.id === 'number' ? this.humanPromptByRpc.get(msg.id) : undefined;
+        if (this.rpc.dispatchResponse(msg)) {
+            // #486: settle human-prompt bookkeeping in RPC dispatch order, before the next line.
+            // Do not release a human steer whose turn already ended with no successor — the
+            // await continuation may still restart it, or release once it decides not to.
+            if (humanClient) {
+                const startRpc = typeof msg.id === 'number' && this.humanStartRpcs.has(msg.id);
+                if (typeof msg.id === 'number') {
+                    this.humanPromptByRpc.delete(msg.id);
+                    this.humanStartRpcs.delete(msg.id);
+                }
+                // A turn/steer result is admission, not a read (#486 review). Keep holding
+                // until the userMessage echo or the turn ends. turn/start still releases:
+                // the follow-up/idle prompt was accepted (or failed). Defer the ready hint
+                // until turn/started so run.ts does not settle the previous DONE/idle
+                // boundary before the follow-up turn exists.
+                if (startRpc) {
+                    const startError = msg.error !== undefined;
+                    const deferHint = !this.activeTurnId && !startError;
+                    if (deferHint)
+                        this.humanReadyOnTurnStart = true;
+                    else if (startError)
+                        this.humanReadyOnTurnStart = false;
+                    this.releaseHumanPrompt(humanClient, !deferHint);
+                }
+            }
+            return;
+        }
+        if (typeof msg.method === 'string')
+            this.handleNotification(msg.method, msg.params ?? {});
+    }
+    handleApprovalRequest(method, rpcId, params) {
+        const duplicate = [...this.pendingApprovals.entries()].find(([, pending]) => pending.rpcId === rpcId);
+        const approval = codexApproval(method, rpcId, params, this.spec.cezarTools?.name);
+        const routing = params;
+        if (!approval || !this.activeTurnId || routing?.threadId !== this.threadId || approval.turnId !== this.activeTurnId ||
+            duplicate) {
+            this.rpc.respond({ id: rpcId, error: { code: -32602, message: 'malformed, stale or unsupported approval routing' } });
+            // One native id cannot identify two requests. Its error settles the wire;
+            // revoke the old UI capability so it cannot produce a second response.
+            if (duplicate)
+                this.expireApproval(duplicate[0], 'duplicate native request id', false);
+            return;
+        }
+        this.clearStreamRetry();
+        this.agentInputReady = false;
+        if (this.autoEndTimer)
+            clearTimeout(this.autoEndTimer);
+        this.autoEndTimer = undefined;
+        this.pendingApprovals.set(approval.event.requestId, approval);
+        try {
+            if (!this.opts.onUiEvent)
+                throw new Error('approval UI unavailable');
+            this.opts.onUiEvent(approval.event);
+        }
+        catch {
+            // A missing/throwing consumer cannot leave a native RPC waiting forever.
+            this.expireApproval(approval.event.requestId, 'approval UI unavailable');
+        }
+    }
+    respondPermission(requestId, optionId) {
+        const approval = this.pendingApprovals.get(requestId);
+        const response = approval?.responses.get(optionId);
+        if (!this.open || !approval || !response || approval.turnId !== this.activeTurnId)
+            return false;
+        this.pendingApprovals.delete(requestId);
+        this.rpc.respond({ id: approval.rpcId, result: response });
+        this.emitPermissionResolved(requestId, this.open ? { optionId } : { reason: 'approval response transport failed' });
+        return this.open;
+    }
+    emitPermissionResolved(requestId, resolution) {
+        try {
+            this.opts.onUiEvent?.({ type: 'permission.resolved', requestId, ...resolution });
+        }
+        catch { /* A failed consumer must not strand other pending RPCs. */ }
+    }
+    expireApproval(requestId, reason, respond = true) {
+        const approval = this.pendingApprovals.get(requestId);
+        if (!approval)
+            return;
+        this.pendingApprovals.delete(requestId);
+        if (respond)
+            this.rpc.respond({ id: approval.rpcId, error: { code: -32000, message: reason } });
+        this.emitPermissionResolved(requestId, { reason });
+    }
+    expireApprovals(reason, respond = true) {
+        for (const requestId of this.pendingApprovals.keys())
+            this.expireApproval(requestId, reason, respond);
+    }
+    handleUserInputRequest(rpcId, params) {
+        const questions = codexAskQuestions(params.questions);
+        if (!questions) {
+            this.rpc.respond({ id: rpcId, error: { code: -32602, message: 'unsupported or malformed requestUserInput payload' } });
+            return;
+        }
+        if (this.isCurrentTurn(params))
+            this.clearStreamRetry();
+        if (this.pendingUserInput)
+            this.rejectPendingUserInput('superseded by a newer requestUserInput');
+        this.pendingUserInput = { rpcId, questions };
+        this.opts.onUiEvent?.({ type: 'ask.requested', requestId: `codex-${String(rpcId)}`, questions: uiAskQuestions(questions) });
+    }
+    rejectPendingUserInput(message) {
+        const pending = this.pendingUserInput;
+        if (!pending)
+            return;
+        this.pendingUserInput = undefined;
+        this.rpc.respond({ id: pending.rpcId, error: { code: -32000, message } });
+    }
+    /** True when a turn notification belongs to a sub-agent CHILD thread rather than this run's
+     *  own main thread — its lifecycle must not start or end the parent turn (#600). The app-server
+     *  multiplexes every thread over one connection, so a spawned skill's child `turn/completed`
+     *  would otherwise emit a `turn-end` and park the actively-working run under "Needs you".
+     *  Fail-open: an absent `threadId` (the single-thread wire shape) or our own id counts as ours. */
+    isForeignThreadTurn(params) {
+        const eventThreadId = stringField(params, 'threadId');
+        return !!eventThreadId && !!this.threadId && eventThreadId !== this.threadId;
+    }
+    /** A `turn/started|completed|failed` notification for a sub-agent child thread — dropped
+     *  before either channel processes it (#600). Only turn lifecycle is filtered; child item
+     *  events still map, so nested sub-agent activity keeps rendering. */
+    isForeignTurnLifecycle(msg) {
+        const method = typeof msg.method === 'string' ? msg.method : undefined;
+        if (!method || !TURN_LIFECYCLE_METHODS.has(method))
+            return false;
+        return this.isForeignThreadTurn((msg.params ?? {}));
+    }
+    isCurrentTurn(params) {
+        const turnId = turnIdOf(params);
+        return !!this.activeTurnId && !this.isForeignThreadTurn(params)
+            && (!turnId || turnId === this.activeTurnId);
+    }
+    clearStreamRetry() {
+        if (this.streamRetryTimer)
+            clearTimeout(this.streamRetryTimer);
+        this.streamRetryTimer = undefined;
+        this.streamRetryError = undefined;
+    }
+    handleStreamError(params) {
+        const message = codexStreamError(params);
+        if (!message || !this.isCurrentTurn(params))
+            return;
+        if (params.willRetry === false) {
+            this.fail(new Error(message));
+            return;
+        }
+        this.emit({ type: 'note', message });
+        if (params.willRetry !== true)
+            return;
+        this.streamRetryError = message;
+        if (this.streamRetryTimer)
+            return;
+        this.streamRetryTimer = setTimeout(() => {
+            const lastError = this.streamRetryError;
+            if (!this.open || !lastError)
+                return;
+            this.emitUi(state => mapCodexNotification({ method: 'turn/completed', params: {
+                    turn: { id: this.activeTurnId, status: 'failed', error: { message: lastError } },
+                } }, state));
+            this.fail(new Error(`Codex stream made no progress for 60s: ${lastError}`));
+        }, STREAM_RETRY_TIMEOUT_MS);
+        this.streamRetryTimer.unref?.();
+    }
+    handleNotification(method, params) {
+        if (this.streamRetryTimer && this.isCurrentTurn(params) && isStreamProgress(method, params)) {
+            this.clearStreamRetry();
+        }
+        if (method === 'serverRequest/resolved')
+            this.noteServerRequestResolved(params);
+        else if (method === 'error')
+            this.handleStreamError(params);
+        else if (method === 'warning' && typeof params.message === 'string' && params.message.trim())
+            this.emit({ type: 'note', message: params.message.trim() });
+        else if (method === 'turn/started')
+            this.noteTurnStarted(params);
+        else if (method === 'item/agentMessage/delta')
+            this.noteAgentDelta(params);
+        else if (method === 'item/started')
+            this.noteItemStarted(params);
+        else if (method === 'item/completed')
+            this.noteItemCompleted(params);
+        else if (method === 'thread/tokenUsage/updated') {
+            const total = tokenTotal(params);
+            if (total > 0) {
+                this.tokensUsed = total;
+                this.emit({ type: 'token-usage', tokensUsed: total });
+            }
+        }
+        else if (method === 'turn/completed' || method === 'turn/failed')
+            this.noteTurnEnded(method, params);
+    }
+    noteServerRequestResolved(params) {
+        if (params.threadId !== this.threadId)
+            return;
+        for (const [requestId, approval] of this.pendingApprovals) {
+            if (approval.rpcId === params.requestId)
+                this.expireApproval(requestId, 'resolved by Codex', false);
+        }
+    }
+    noteTurnStarted(params) {
+        if (!this.isForeignThreadTurn(params))
+            this.turnBoundaryVersion += 1;
+        if (this.isForeignThreadTurn(params))
+            return; // sub-agent child thread — not our turn (#600)
+        if (this.threadId && turnIdOf(params)) {
+            this.firstTurnStarted = true;
+            this.checkStartupComplete();
+        }
+        if (turnIdOf(params) !== this.activeTurnId) {
+            this.clearStreamRetry();
+            this.expireApprovals('a new turn started');
+        }
+        this.activeTurnId = turnIdOf(params) ?? this.activeTurnId;
+        if (this.humanReadyOnTurnStart) {
+            this.humanReadyOnTurnStart = false;
+            // emitUi already ran (clears atTurnBoundary); hint now that the hold dropped.
+            this.notifyHumanInputDrained();
+        }
+    }
+    noteAgentDelta(params) {
+        // Child text belongs only to v2; buffering it here would pollute the
+        // parent's marker parse when the coalescer flushes at turn-end (#149).
+        if (this.isForeignThreadTurn(params))
+            return;
+        const delta = typeof params.delta === 'string' ? params.delta : '';
+        if (delta)
+            this.textCoalescer.append(stringField(params, 'itemId'), delta);
+    }
+    noteItemStarted(params) {
+        const item = params.item ?? {};
+        const type = stringField(item, 'type');
+        if (type === 'userMessage' && !this.isForeignThreadTurn(params)) {
+            // The model received this input now; `clientId` names our submission (#505).
+            const clientId = stringField(item, 'clientId');
+            if (clientId)
+                this.noteHumanEcho(clientId);
+            const ids = clientId ? this.submissions.consume(clientId) : [];
+            if (ids.length)
+                this.opts.onAgentInputConsumed?.(ids);
+        }
+        // Only tool-like items become tool events; message/reasoning stream as text.
+        if (!type || NON_TOOL_ITEMS.has(type))
+            return;
+        const id = stringField(item, 'id') ?? `item-${this.rpc.allocateId()}`;
+        this.toolCalls.push({ id, name: type, input: item });
+        this.emit({ type: 'tool-call', id, tool: type, input: item });
+    }
+    noteItemCompleted(params) {
+        const item = params.item ?? {};
+        const type = stringField(item, 'type');
+        const id = stringField(item, 'id') ?? '';
+        if (type === 'agentMessage') {
+            if (this.isForeignThreadTurn(params))
+                return;
+            // One v1 `text` per finished message — the snapshot's full text when
+            // present (also covers turns that send no deltas), else the deltas.
+            this.textCoalescer.complete(id || undefined, typeof item.text === 'string' ? item.text : undefined);
+        }
+        else if (type && !NON_TOOL_ITEMS.has(type) && id) {
+            this.emit({
+                type: 'tool-result',
+                toolCallId: id,
+                result: safeStringify(item),
+                isError: /error|failed/i.test(stringField(item, 'status') ?? ''),
+            });
+        }
+    }
+    noteTurnEnded(method, params) {
+        if (this.isForeignThreadTurn(params))
+            return; // don't end the parent turn on a child turn (#600)
+        if (this.activeTurnId && turnIdOf(params) && turnIdOf(params) !== this.activeTurnId)
+            return;
+        if (this.isCurrentTurn(params))
+            this.clearStreamRetry();
+        this.expireApprovals('turn ended');
+        this.turnBoundaryVersion += 1;
+        this.pendingUserInput = undefined;
+        this.activeTurnId = undefined;
+        // An interrupted/failed item never sees item/completed — surface its
+        // partial prose before the turn boundary (run.ts reads markers there).
+        this.textCoalescer.flush();
+        const outcome = codexTurnOutcome(method, params);
+        const completedId = turnIdOf(params);
+        if (completedId) {
+            this.completedTurns.set(completedId, outcome.error === undefined);
+            if (this.completedTurns.size > 32)
+                this.completedTurns.delete(this.completedTurns.keys().next().value);
+        }
+        this.turnCompletions += 1;
+        this.emitTurnEnd(outcome.error);
+    }
+    emitTurnEnd(error) {
+        if (error !== undefined && !this.terminatedByCezar)
+            this.emit({ type: 'error', message: error });
+        this.agentInputReady = this.open;
+        // A completed turn processed its own input; a failed one may never have reached the
+        // model, so its input stays pending and is reported unconsumed below.
+        const started = error === undefined ? [...this.turnStartSubmissions].flatMap(id => this.submissions.consume(id)) : [];
+        this.turnStartSubmissions.clear();
+        if (started.length)
+            this.opts.onAgentInputConsumed?.(started);
+        // An in-flight steer is owned by its RPC outcome, not by this boundary.
+        const inFlight = this.inFlightSubmissionId ? this.submissions.consume(this.inFlightSubmissionId) : [];
+        const unconsumedInputIds = this.submissions.takeUnconsumed();
+        if (this.inFlightSubmissionId && inFlight.length)
+            this.submissions.accept(this.inFlightSubmissionId, inFlight, '');
+        this.emit(unconsumedInputIds.length ? { type: 'turn-end', unconsumedInputIds } : { type: 'turn-end' });
+        if (this.unreadHumanSteers.size)
+            this.restartUnreadHumanSteers();
+        else
+            this.scheduleAutoEnd();
+    }
+    emit(event) {
+        this.onEvent?.(event);
+    }
+    /** The mapper never throws, but a defect in it must still never disturb
+     *  the v1 stream — hence the belt-and-braces try. */
+    emitUi(map) {
+        try {
+            const mapped = map(this.uiState);
+            this.uiState = mapped.state;
+            if (this.opts.onUiEvent) {
+                for (const event of mapped.events)
+                    this.opts.onUiEvent(event);
+            }
+        }
+        catch {
+            // v2 mapping is best-effort; v1 consumers stay unaffected.
+        }
+    }
+}
+// ---- helpers --------------------------------------------------------------
+/** Only model/tool output proves recovery; bookkeeping, user input and retry
+ * chatter do not. Unknown notifications are deliberately not heartbeats. */
+function isStreamProgress(method, params) {
+    if (STREAM_PROGRESS_DELTAS.has(method)) {
+        return typeof params.delta === 'string' && params.delta.length > 0;
+    }
+    if (method !== 'item/started' && method !== 'item/completed')
+        return false;
+    const item = params.item;
+    if (!item || typeof item !== 'object' || Array.isArray(item))
+        return false;
+    const record = item;
+    return !!stringField(record, 'id') && !!stringField(record, 'type') && record.type !== 'userMessage';
+}
+const STREAM_PROGRESS_DELTAS = new Set([
+    'item/agentMessage/delta', 'item/reasoning/textDelta', 'item/reasoning/summaryDelta',
+    'item/reasoning/summaryTextDelta', 'item/commandExecution/outputDelta',
+]);
+function codexAskQuestions(value) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > 4)
+        return null;
+    const questions = [];
+    for (const raw of value) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            return null;
+        const question = raw;
+        if (question.isSecret === true)
+            return null;
+        const id = stringField(question, 'id');
+        const header = stringField(question, 'header');
+        const prompt = stringField(question, 'question');
+        if (!id || !header || !prompt || !Array.isArray(question.options))
+            return null;
+        const options = question.options.map((option) => {
+            if (!option || typeof option !== 'object' || Array.isArray(option))
+                return null;
+            const record = option;
+            const label = stringField(record, 'label');
+            const description = stringField(record, 'description');
+            return label ? { label, ...(description ? { description } : {}) } : null;
+        }).filter((option) => option !== null);
+        questions.push({ id, header, question: prompt, options, multiSelect: false });
+    }
+    return parseAskRequest({ questions })?.questions ?? null;
+}
+function userInputAnswers(questions, text) {
+    const lines = text.split(/\r?\n/);
+    const hasStructuredAnswer = questions.some((question) => lines.some((line) => line.startsWith(`${question.header}:`)));
+    const answers = {};
+    for (const [index, question] of questions.entries()) {
+        const prefix = `${question.header}:`;
+        const matching = lines.find((line) => line.startsWith(prefix));
+        const raw = matching?.slice(prefix.length).trim() ?? (!hasStructuredAnswer && index === 0 ? text.trim() : '');
+        answers[question.id ?? String(index)] = {
+            answers: raw === '' ? [] : raw.split(',').map((answer) => answer.trim()).filter(Boolean),
+        };
+    }
+    return answers;
+}
+/** ThreadItem `type`s that are conversation text, not tool activity. */
+const NON_TOOL_ITEMS = new Set(['agentMessage', 'userMessage', 'reasoning', 'plan']);
+/** Turn-lifecycle notification methods — the only frames whose child-thread copies must be
+ *  dropped so a sub-agent turn can't be mistaken for the parent's (#600). */
+const TURN_LIFECYCLE_METHODS = new Set(['turn/started', 'turn/completed', 'turn/failed']);
+const REASONING_SUMMARIES = new Set(['auto', 'concise', 'detailed', 'none']);
+/**
+ * The reasoning-summary override sent on `turn/start` (TurnStartParams.summary).
+ * Defaults to `auto` so reasoning is visible out of the box — without it the
+ * app-server runs with its own default (no summary) and the reasoning thread
+ * stays empty even when the model reasons. `CEZ_CODEX_REASONING` overrides the
+ * default (`auto`/`concise`/`detailed`, or `none` to opt out); an unrecognized
+ * value falls back to `auto`.
+ */
+export function reasoningSummary(env = process.env) {
+    const raw = productEnv('CODEX_REASONING', env)?.trim().toLowerCase();
+    if (!raw)
+        return 'auto';
+    return REASONING_SUMMARIES.has(raw) ? raw : 'auto';
+}
+/**
+ * Fields sent on `turn/start` besides thread/input. `summary` is the existing
+ * `CEZ_CODEX_REASONING` knob (out of scope for #45). `effort` is the per-run
+ * pin — omitted when unset so the app-server keeps its default.
+ */
+export function codexTurnStartExtras(spec, env = process.env) {
+    const effort = parseEffort(spec.effort);
+    return {
+        summary: reasoningSummary(env),
+        ...(effort ? { effort } : {}),
+    };
+}
+function textOf(content) {
+    return content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join('\n')
+        .trim();
+}
+/** Drop undefined values so we never send `"model": null` to the server. */
+function clean(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined && v !== null)
+            out[k] = v;
+    }
+    return out;
+}
+function threadIdOf(res) {
+    const thread = res.thread;
+    return typeof thread?.id === 'string' ? thread.id : stringField(res, 'threadId');
+}
+/** Cumulative tokens from a `thread/tokenUsage/updated` notification:
+ *  `params.tokenUsage.total.totalTokens`. */
+function tokenTotal(params) {
+    const usage = params.tokenUsage;
+    const total = usage?.total?.totalTokens;
+    return typeof total === 'number' ? total : 0;
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=codex-app-server-runner.js.map