@jungjaehoon/mama-core 2.4.1 → 4.0.0

package/dist/runtime/drivers/codex-app-server-process.js

@@ -0,0 +1,2342 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CodexAppServerProcess = void 0;
+const cli_secret_redaction_js_1 = require("./cli-secret-redaction.js");
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_readline_1 = require("node:readline");
+const types_js_1 = require("./types.js");
+const types_js_2 = require("./types.js");
+const codex_home_js_1 = require("./codex-home.js");
+const codex_thread_registry_js_1 = require("./codex-thread-registry.js");
+const DEFAULT_TIMEOUT = 300_000;
+const STOP_GRACE_MS = 200;
+const STDERR_LIMIT = 4_000;
+const CLIENT_INFO = { name: 'mama-codex-app-server', version: '1.0.0' };
+const TURN_STATUSES = new Set(['completed', 'interrupted', 'failed', 'inProgress']);
+const TURN_ITEM_VIEWS = new Set(['notLoaded', 'summary', 'full']);
+const APPROVAL_REVIEWERS = new Set(['user', 'auto_review', 'guardian_subagent']);
+const OVERLOADED_ERROR_CODE = -32001;
+const OVERLOAD_RETRY_LIMIT = 4;
+const OVERLOAD_RETRY_BASE_MS = 25;
+const TURN_START_RECONCILE_GRACE_MS = 250;
+const SUBAGENT_FINAL_TEXT_LIMIT = 4_000;
+/** Wait for the child's own `turn/completed` after the parent announced it finished. */
+const SUBAGENT_COMPLETION_GRACE_MS = 5_000;
+/** A registered child that never completes is reported failed rather than leaked. */
+const SUBAGENT_TTL_MS = 45 * 60_000;
+/** Bound on remembered finished child threads; identity, not history. */
+const MAX_FINISHED_SUBAGENTS = 200;
+const SUBAGENT_AUTHORITY_UNAVAILABLE = 'subagent authority unavailable';
+// `SUBAGENT_AUTHORITY_EXPIRED` and the `[expired]` marker stood here. They read
+// a refusal the envelope enforcer emitted once a grant passed its wall; a
+// principal's access has no wall, so nothing emits it and nothing may pretend
+// to detect it.
+/** turn/start was explicitly rejected by the app-server, so no turn exists on the thread. */
+class CodexTurnRejectedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CodexTurnRejectedError';
+    }
+}
+class CodexAppServerRpcError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'CodexAppServerRpcError';
+        this.code = code;
+    }
+}
+function object(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function stableJson(value) {
+    if (Array.isArray(value)) {
+        return value.map(stableJson);
+    }
+    const record = object(value);
+    if (!record) {
+        return value;
+    }
+    return Object.fromEntries(Object.keys(record)
+        .sort()
+        .map((key) => [key, stableJson(record[key])]));
+}
+function deepFreeze(value) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            deepFreeze(item);
+        }
+        Object.freeze(value);
+        return;
+    }
+    const record = object(value);
+    if (record) {
+        for (const item of Object.values(record)) {
+            deepFreeze(item);
+        }
+        Object.freeze(record);
+    }
+}
+function snapshotHostToolBridge(bridge) {
+    if (!bridge) {
+        return undefined;
+    }
+    // Codex's dynamic-tool protocol accepts only ASCII letters, digits, `_` and `-`.
+    // Product actions keep their canonical dotted names; translate only at this wire
+    // boundary and restore the original name before the host executes it.
+    const canonicalByWire = new Map();
+    const tools = bridge.tools
+        .map((tool) => {
+        const wireName = tool.name.replace(/[^a-zA-Z0-9_-]/g, '_');
+        if (!wireName || canonicalByWire.has(wireName)) {
+            throw new Error(`Codex dynamic tool names collide at ${wireName || '<empty>'}`);
+        }
+        canonicalByWire.set(wireName, tool.name);
+        return stableJson({ ...tool, name: wireName });
+    })
+        .sort((left, right) => left.name.localeCompare(right.name));
+    deepFreeze(tools);
+    const execute = bridge.execute.bind(bridge);
+    return Object.freeze({
+        tools,
+        execute: (call) => {
+            const canonical = canonicalByWire.get(call.name);
+            if (!canonical) {
+                throw new Error(`Codex dynamic tool ${call.name} was not advertised`);
+            }
+            return execute({ ...call, name: canonical });
+        },
+    });
+}
+function errorMessage(value, fallback) {
+    const record = object(value);
+    return typeof record?.message === 'string' && record.message ? record.message : fallback;
+}
+function stringField(record, name, context) {
+    const value = record[name];
+    if (typeof value !== 'string') {
+        throw new Error(`Codex app-server returned malformed ${context}.${name}`);
+    }
+    return value;
+}
+function nullableStringField(record, name, context) {
+    const value = record[name];
+    if (value !== null && typeof value !== 'string') {
+        throw new Error(`Codex app-server returned malformed ${context}.${name}`);
+    }
+}
+function nullableNumberField(record, name, context) {
+    const value = record[name];
+    if (value !== null && (typeof value !== 'number' || !Number.isFinite(value))) {
+        throw new Error(`Codex app-server returned malformed ${context}.${name}`);
+    }
+}
+function validateTurn(value, context) {
+    const turn = object(value);
+    if (!turn) {
+        throw new Error(`Codex app-server returned malformed ${context}`);
+    }
+    stringField(turn, 'id', context);
+    if (!Array.isArray(turn.items) || !TURN_ITEM_VIEWS.has(String(turn.itemsView))) {
+        throw new Error(`Codex app-server returned malformed ${context} items`);
+    }
+    if (!TURN_STATUSES.has(String(turn.status))) {
+        throw new Error(`Codex app-server returned malformed ${context}.status`);
+    }
+    if (turn.error !== null) {
+        const error = object(turn.error);
+        if (!error ||
+            typeof error.message !== 'string' ||
+            error.codexErrorInfo === undefined ||
+            (error.additionalDetails !== null && typeof error.additionalDetails !== 'string')) {
+            throw new Error(`Codex app-server returned malformed ${context}.error`);
+        }
+    }
+    nullableNumberField(turn, 'startedAt', context);
+    nullableNumberField(turn, 'completedAt', context);
+    nullableNumberField(turn, 'durationMs', context);
+    return turn;
+}
+function validateThread(value) {
+    const thread = object(value);
+    if (!thread) {
+        throw new Error('Codex app-server returned malformed thread');
+    }
+    for (const field of ['id', 'sessionId', 'preview', 'modelProvider', 'cwd', 'cliVersion']) {
+        stringField(thread, field, 'thread');
+    }
+    for (const field of [
+        'forkedFromId',
+        'parentThreadId',
+        'path',
+        'threadSource',
+        'agentNickname',
+        'agentRole',
+        'name',
+    ]) {
+        nullableStringField(thread, field, 'thread');
+    }
+    if (typeof thread.ephemeral !== 'boolean') {
+        throw new Error('Codex app-server returned malformed thread.ephemeral');
+    }
+    for (const field of ['createdAt', 'updatedAt']) {
+        if (typeof thread[field] !== 'number' || !Number.isFinite(thread[field])) {
+            throw new Error(`Codex app-server returned malformed thread.${field}`);
+        }
+    }
+    nullableNumberField(thread, 'recencyAt', 'thread');
+    const status = object(thread.status);
+    if (!status ||
+        !['notLoaded', 'idle', 'systemError', 'active'].includes(String(status.type)) ||
+        (status.type === 'active' && !Array.isArray(status.activeFlags))) {
+        throw new Error('Codex app-server returned malformed thread.status');
+    }
+    const sourceValid = typeof thread.source === 'string' || object(thread.source) !== undefined;
+    if (!sourceValid ||
+        (thread.gitInfo !== null && !object(thread.gitInfo)) ||
+        !Array.isArray(thread.turns)) {
+        throw new Error('Codex app-server returned malformed thread metadata');
+    }
+    for (const turn of thread.turns) {
+        validateTurn(turn, 'thread.turns[]');
+    }
+    return thread;
+}
+function shaFile(path) {
+    return (0, node_crypto_1.createHash)('sha256').update((0, node_fs_1.readFileSync)(path)).digest('hex');
+}
+function managedFileSignature(path) {
+    if (!(0, node_fs_1.existsSync)(path)) {
+        return undefined;
+    }
+    const stat = (0, node_fs_1.statSync)(path);
+    return `${stat.dev}:${stat.ino}:${stat.mode}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`;
+}
+function ensurePrivateDirectory(path) {
+    (0, node_fs_1.mkdirSync)(path, { recursive: true, mode: 0o700 });
+    (0, node_fs_1.chmodSync)(path, 0o700);
+}
+function atomicPrivateWrite(path, value) {
+    ensurePrivateDirectory((0, node_path_1.dirname)(path));
+    const temporary = `${path}.${process.pid}.${(0, node_crypto_1.randomUUID)()}.tmp`;
+    (0, node_fs_1.writeFileSync)(temporary, value, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    (0, node_fs_1.chmodSync)(temporary, 0o600);
+    (0, node_fs_1.renameSync)(temporary, path);
+    (0, node_fs_1.chmodSync)(path, 0o600);
+}
+function copyAuthAtomically(source, destination) {
+    if (!(0, node_fs_1.existsSync)(source) ||
+        (0, node_fs_1.statSync)(source).size === 0 ||
+        (0, node_path_1.resolve)(source) === (0, node_path_1.resolve)(destination)) {
+        return;
+    }
+    ensurePrivateDirectory((0, node_path_1.dirname)(destination));
+    const temporary = `${destination}.${process.pid}.${(0, node_crypto_1.randomUUID)()}.tmp`;
+    (0, node_fs_1.copyFileSync)(source, temporary);
+    (0, node_fs_1.chmodSync)(temporary, 0o600);
+    (0, node_fs_1.renameSync)(temporary, destination);
+    (0, node_fs_1.chmodSync)(destination, 0o600);
+}
+/** Item IDs are provider-local; this identifier is only for host observations. */
+function nativeObservationId(threadId, itemId) {
+    return JSON.stringify([threadId, itemId]);
+}
+class CodexAppServerProcess {
+    options;
+    registry;
+    child;
+    stdout;
+    stderr;
+    nextId = 0;
+    pending = new Map();
+    lateTurnStarts = new Map();
+    turnStartReconciliations = new Map();
+    turns = new Map();
+    subagents = new Map();
+    /**
+     * Child threads that already reported a terminal status. The SAME `started`
+     * announcement arrives as both an item/started and an item/completed view, and the
+     * second view can land after the child's own turn/completed - `subagents.has` no longer
+     * dedupes it then, so it would mint a second authority and a second completion for a
+     * dead child. Bounded FIFO: identity of recent children, not a growing ledger.
+     */
+    finishedSubagents = new Set();
+    threadContexts = new Map();
+    sessions = new Map();
+    sessionQueues = new Map();
+    connectionQueue = Promise.resolve();
+    startPromise;
+    shutdownPromise;
+    stopped = false;
+    stderrTail = '';
+    secrets = new Set();
+    authFingerprint;
+    authFingerprintInitialized = false;
+    authSourceSignature;
+    managedConfigFingerprint;
+    managedConfigSignature;
+    secretLaunchFingerprint;
+    secretLaunchFingerprintInitialized = false;
+    killTimer;
+    finalKillTimer;
+    constructor(options) {
+        const mamaRoot = options.hostRootDir;
+        this.options = {
+            ...options,
+            command: options.command ?? 'codex',
+            requestTimeout: options.requestTimeout ?? DEFAULT_TIMEOUT,
+            codexHome: (0, node_path_1.resolve)(options.codexHome ?? (0, node_path_1.join)(mamaRoot, '.codex')),
+            isolatedHome: (0, node_path_1.resolve)(options.isolatedHome ?? (0, node_path_1.join)(mamaRoot, 'codex-runtime', 'home')),
+            registryRoot: (0, node_path_1.resolve)(options.registryRoot ?? (0, node_path_1.join)(mamaRoot, 'codex-runtime', 'threads')),
+            cwd: (0, node_path_1.resolve)(options.cwd),
+        };
+        ensurePrivateDirectory((0, node_path_1.dirname)(this.options.registryRoot));
+        this.registry = new codex_thread_registry_js_1.CodexThreadRegistry({ rootDir: this.options.registryRoot });
+    }
+    async prompt(text, callbacks, overrides = {}) {
+        if (this.stopped) {
+            throw new Error('Codex app-server process is stopped');
+        }
+        const session = this.resolveSessionPolicy(overrides);
+        return this.enqueueSession(session.sessionKey, async () => {
+            try {
+                if (this.stopped) {
+                    throw new Error('Codex app-server process is stopped');
+                }
+                const launch = (0, codex_home_js_1.buildCodexAppServerLaunchConfig)(this.options.mcpConfigPath, this.options.processEnv ?? process.env);
+                if (overrides.resumeSession === false) {
+                    this.discardSessionThreadState(session.sessionKey, 'session was restarted');
+                    this.registry.remove(session.sessionKey);
+                    this.sessions.delete(session.sessionKey);
+                }
+                this.assertRegistryPolicy(session, launch);
+                await this.prepareConnection(launch, session.requestTimeout);
+                let state = this.sessions.get(session.sessionKey);
+                if (!state?.threadId) {
+                    try {
+                        state = await this.openThread(session, launch);
+                    }
+                    catch (error) {
+                        if (this.child && !this.shutdownPromise) {
+                            await this.shutdown(this.toError(error));
+                        }
+                        throw error;
+                    }
+                    this.sessions.set(session.sessionKey, state);
+                }
+                const reconciliation = this.turnStartReconciliations.get(state.threadId);
+                if (reconciliation) {
+                    await reconciliation.promise;
+                    await this.prepareConnection(launch, session.requestTimeout);
+                    state = this.sessions.get(session.sessionKey);
+                    if (!state?.threadId) {
+                        state = await this.openThread(session, launch);
+                        this.sessions.set(session.sessionKey, state);
+                    }
+                }
+                let prompt = text;
+                if (overrides.preparePrompt) {
+                    try {
+                        prompt = await overrides.preparePrompt({
+                            sessionId: state.threadId,
+                            isNewSession: state.startupPending === true,
+                        });
+                    }
+                    catch (error) {
+                        // No turn/start has been sent. Do not persist a never-populated thread
+                        // as a retained session if startup context failed to assemble.
+                        if (state.startupPending) {
+                            this.registry.remove(session.sessionKey);
+                            this.sessions.delete(session.sessionKey);
+                        }
+                        throw error;
+                    }
+                }
+                const replayReminder = Boolean(state.bootstrapPending && session.systemPrompt);
+                const turnText = replayReminder
+                    ? `<system-reminder>\nFresh MAMA runtime context after resuming this durable thread:\n${session.systemPrompt.replace(/<\/system-reminder>/gi, '')}\n</system-reminder>\n\n${prompt}`
+                    : prompt;
+                // One line per turn, where the text that actually reaches the model is known.
+                // This is what makes "fixed things once, turns carry only deltas" measurable
+                // from daemon.log instead of asserted.
+                console.log(`[prompt] thread=${state.threadId} kind=${session.promptTelemetry?.kind ?? 'chat'} ` +
+                    `chars=${turnText.length} brief=${session.promptTelemetry?.brief ?? 'omitted'} ` +
+                    `reminder=${replayReminder ? 'sent' : 'omitted'}`);
+                // A Codex-native child can be announced after this turn resolved, so remember
+                // which session the thread belongs to outside the PendingTurn lifetime. The
+                // parent's BRIDGE is deliberately not kept: a child gets its own authority.
+                // A session that rotated its thread leaves the previous thread's context behind,
+                // and a stale entry both leaks and lets a dead thread announce children.
+                this.pruneThreadContexts(session.sessionKey, state.threadId);
+                this.threadContexts.set(state.threadId, {
+                    sessionKey: session.sessionKey,
+                    onToolUse: callbacks?.onToolUse,
+                    onToolComplete: callbacks?.onToolComplete,
+                });
+                const result = await this.startTurn(state.threadId, turnText, {
+                    ...callbacks,
+                    onAccepted: (receipt) => {
+                        state.startupPending = false;
+                        callbacks?.onAccepted?.(receipt);
+                    },
+                }, session.requestTimeout, session.hostToolBridge, overrides.runTokenBudget, overrides.nativeInputId, session.restrictedReadRoots);
+                state.bootstrapPending = false;
+                state.startupPending = false;
+                state.unproven = false;
+                return result;
+            }
+            catch (error) {
+                const opened = this.sessions.get(session.sessionKey);
+                if (opened?.unproven && error instanceof CodexTurnRejectedError) {
+                    // Live 2026-09-25: a first turn rejected for input length left the thread saved
+                    // although Codex kept no rollout for it, and every later turn failed with "no
+                    // rollout found". Only an explicit rejection proves no turn exists; a timeout or a
+                    // late acknowledgement may have started one, and that retry keeps the thread.
+                    console.warn(`[CodexAppServer] forgetting thread ${opened.threadId}: its first turn was rejected`);
+                    this.registry.remove(session.sessionKey);
+                    this.sessions.delete(session.sessionKey);
+                }
+                if (error instanceof CodexAppServerRpcError &&
+                    error.code !== OVERLOADED_ERROR_CODE &&
+                    this.child &&
+                    !this.shutdownPromise) {
+                    await this.shutdown(error);
+                }
+                if (this.shutdownPromise) {
+                    await this.shutdownPromise;
+                }
+                throw error;
+            }
+        });
+    }
+    /** Append input to this exact native turn; never queue behind it or start a replacement. */
+    async steer(text, target, sessionKey = this.options.sessionKey, beforeSend) {
+        const session = this.sessions.get(sessionKey);
+        const active = session && this.turns.get(session.threadId);
+        if (this.stopped ||
+            target.backend !== 'codex' ||
+            !session ||
+            session.threadId !== target.sessionId ||
+            !active ||
+            active.turnId !== target.turnId ||
+            active.abortController.signal.aborted) {
+            throw new types_js_1.NativeSteeringTargetUnavailableError();
+        }
+        // The core journals this input only after the exact target is known active,
+        // but before the RPC can write anything to the native transport.
+        beforeSend?.();
+        let response;
+        try {
+            response = await this.request('turn/steer', {
+                threadId: target.sessionId,
+                expectedTurnId: target.turnId,
+                input: [{ type: 'text', text, text_elements: [] }],
+            }, active.requestTimeout);
+        }
+        catch (error) {
+            if (error instanceof CodexAppServerRpcError)
+                throw error;
+            throw new types_js_1.NativeInputUncertainError('Native steer acceptance is uncertain', target, error);
+        }
+        if (object(response)?.turnId !== target.turnId) {
+            throw new types_js_1.NativeInputUncertainError('Native steer acknowledgement is uncertain', target);
+        }
+        return { ...target };
+    }
+    async reset(sessionKey = this.options.sessionKey) {
+        await this.enqueueSession(sessionKey, async () => {
+            this.discardSessionThreadState(sessionKey, 'session was reset');
+            this.registry.remove(sessionKey);
+            this.sessions.delete(sessionKey);
+        });
+    }
+    getSessionPolicyStatus(overrides = {}) {
+        const session = this.resolveSessionPolicy(overrides);
+        const record = this.registry.load(session.sessionKey);
+        if (!record) {
+            return 'missing';
+        }
+        const launch = (0, codex_home_js_1.buildCodexAppServerLaunchConfig)(this.options.mcpConfigPath, this.options.processEnv ?? process.env);
+        return this.registryPolicyMatches(record, session, launch) ? 'compatible' : 'mismatch';
+    }
+    async stop() {
+        this.stopped = true;
+        await this.shutdown(new Error('Codex app-server process stopped'));
+        this.terminateSubagents(new Error('Codex app-server process stopped'));
+        this.threadContexts.clear();
+    }
+    async executeSandboxedCommand(command, cwd, roots, signal) {
+        signal?.throwIfAborted();
+        if (!this.child)
+            throw new Error('Codex app-server is not connected');
+        const shellCommand = process.platform === 'win32'
+            ? ['cmd.exe', '/d', '/s', '/c', command]
+            : ['/bin/sh', '-c', command];
+        const result = object(await this.request('command/exec', {
+            command: shellCommand,
+            cwd,
+            sandboxPolicy: {
+                type: 'workspaceWrite',
+                writableRoots: [...roots],
+                readOnlyAccess: {
+                    type: 'restricted',
+                    includePlatformDefaults: true,
+                    readableRoots: [...roots],
+                },
+                networkAccess: false,
+            },
+            timeoutMs: this.options.requestTimeout,
+        }, this.options.requestTimeout));
+        signal?.throwIfAborted();
+        if (typeof result?.exitCode !== 'number' ||
+            typeof result.stdout !== 'string' ||
+            typeof result.stderr !== 'string') {
+            throw new Error('Codex app-server returned a malformed command result');
+        }
+        return { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr };
+    }
+    getThreadId(sessionKey = this.options.sessionKey) {
+        return this.sessions.get(sessionKey)?.threadId || undefined;
+    }
+    getStatus() {
+        return {
+            running: this.child !== undefined,
+            childPid: this.child?.pid,
+            pendingRequestCount: this.pending.size,
+            hasActiveTurn: this.turns.size > 0,
+            stdoutListenerCount: this.stdout?.listenerCount('line') ?? 0,
+            stderrListenerCount: this.stderr?.listenerCount('line') ?? 0,
+            shutdownTimerActive: this.killTimer !== undefined || this.finalKillTimer !== undefined,
+        };
+    }
+    resolveSessionPolicy(overrides) {
+        const hostToolBridge = snapshotHostToolBridge(overrides.hostToolBridge);
+        const restrictedReadRoots = overrides.restrictedReadRoots
+            ? [
+                ...new Set(overrides.restrictedReadRoots.map((root) => (0, node_fs_1.realpathSync)((0, node_path_1.resolve)(root)))),
+            ].sort()
+            : undefined;
+        if (restrictedReadRoots?.length === 0) {
+            throw new Error('Restricted native read policy requires at least one real root');
+        }
+        const cwd = restrictedReadRoots
+            ? (0, node_fs_1.realpathSync)((0, node_path_1.resolve)(overrides.cwd ?? this.options.cwd))
+            : (0, node_path_1.resolve)(overrides.cwd ?? this.options.cwd);
+        if (restrictedReadRoots &&
+            !restrictedReadRoots.some((root) => {
+                const childPath = (0, node_path_1.relative)(root, cwd);
+                return (childPath === '' ||
+                    (childPath !== '..' && !childPath.startsWith(`..${node_path_1.sep}`) && !(0, node_path_1.isAbsolute)(childPath)));
+            })) {
+            throw new Error('Restricted native working directory must be inside a readable root');
+        }
+        return {
+            sessionKey: overrides.sessionKey ?? this.options.sessionKey,
+            model: overrides.model ?? this.options.model,
+            systemPrompt: overrides.systemPrompt ?? this.options.systemPrompt,
+            cwd,
+            sandbox: restrictedReadRoots ? 'read-only' : (overrides.sandbox ?? this.options.sandbox),
+            ...(restrictedReadRoots ? { restrictedReadRoots } : {}),
+            requestTimeout: overrides.requestTimeout ?? this.options.requestTimeout,
+            policyFingerprint: overrides.policyFingerprint ?? this.options.policyFingerprint,
+            hostToolBridge,
+            resumeInstructions: overrides.resumeInstructions,
+            promptTelemetry: overrides.promptTelemetry,
+        };
+    }
+    enqueueSession(sessionKey, operation) {
+        const previous = this.sessionQueues.get(sessionKey) ?? Promise.resolve();
+        const result = previous.catch(() => undefined).then(operation);
+        const tail = result.then(() => undefined, () => undefined);
+        this.sessionQueues.set(sessionKey, tail);
+        void tail.finally(() => {
+            if (this.sessionQueues.get(sessionKey) === tail) {
+                this.sessionQueues.delete(sessionKey);
+            }
+        });
+        return result;
+    }
+    async prepareConnection(launch, requestTimeout) {
+        const operation = this.connectionQueue.then(async () => {
+            if (this.stopped) {
+                throw new Error('Codex app-server process is stopped');
+            }
+            if (this.shutdownPromise) {
+                await this.shutdownPromise;
+            }
+            if (this.stopped) {
+                throw new Error('Codex app-server process is stopped');
+            }
+            const refreshed = this.prepareManagedFiles(launch);
+            if (refreshed && this.child) {
+                await this.restart();
+            }
+            try {
+                await this.ensureStarted(launch, requestTimeout);
+            }
+            catch (error) {
+                if (this.child && !this.shutdownPromise) {
+                    await this.shutdown(this.toError(error));
+                }
+                throw error;
+            }
+        });
+        this.connectionQueue = operation.catch(() => undefined);
+        await operation;
+    }
+    assertRegistryPolicy(session, launch) {
+        const record = this.registry.load(session.sessionKey);
+        if (!record) {
+            return;
+        }
+        if (!this.registryPolicyMatches(record, session, launch)) {
+            throw new Error('Codex app-server thread policy mismatch; reset the session explicitly');
+        }
+    }
+    registryPolicyMatches(record, session, launch) {
+        return (record.model === session.model &&
+            record.cwd === session.cwd &&
+            record.systemPromptFingerprint === this.policyFingerprint(session) &&
+            record.mcpConfigFingerprint === launch.fingerprint);
+    }
+    prepareManagedFiles(launch) {
+        ensurePrivateDirectory(this.options.codexHome);
+        ensurePrivateDirectory(this.options.isolatedHome);
+        const configPath = (0, node_path_1.join)(this.options.codexHome, 'config.toml');
+        const config = (0, codex_home_js_1.buildMAMACodexAppServerConfig)(this.options.effort, undefined, {
+            shellTool: this.options.shellTool,
+            webSearch: this.options.webSearch,
+            shellEnvironment: this.options.shellEnvironment,
+            deniedReadPaths: this.options.deniedReadPaths,
+            allowLoginShell: this.options.allowLoginShell,
+        });
+        const configFingerprint = (0, codex_thread_registry_js_1.fingerprintText)(config);
+        const configSignature = managedFileSignature(configPath);
+        if (this.managedConfigFingerprint !== configFingerprint ||
+            this.managedConfigSignature !== configSignature) {
+            if (configSignature === undefined || shaFile(configPath) !== configFingerprint) {
+                atomicPrivateWrite(configPath, config);
+            }
+            this.managedConfigFingerprint = configFingerprint;
+            this.managedConfigSignature = managedFileSignature(configPath);
+        }
+        const sourceAuth = this.options.authSourcePath;
+        const destinationAuth = (0, node_path_1.join)(this.options.codexHome, 'auth.json');
+        const sourceStat = sourceAuth !== undefined && (0, node_fs_1.existsSync)(sourceAuth) ? (0, node_fs_1.statSync)(sourceAuth) : undefined;
+        const sourceSignature = sourceAuth !== undefined && sourceStat && sourceStat.size > 0
+            ? `${(0, node_fs_1.realpathSync)(sourceAuth)}:${sourceStat.size}:${sourceStat.mtimeMs}:${sourceStat.ctimeMs}`
+            : undefined;
+        let sourceFingerprint = this.authFingerprint;
+        if (!this.authFingerprintInitialized ||
+            this.authSourceSignature !== sourceSignature ||
+            (sourceSignature !== undefined && !(0, node_fs_1.existsSync)(destinationAuth))) {
+            sourceFingerprint =
+                sourceAuth !== undefined && sourceSignature ? shaFile(sourceAuth) : undefined;
+            if (sourceAuth !== undefined &&
+                sourceFingerprint &&
+                (!(0, node_fs_1.existsSync)(destinationAuth) || shaFile(destinationAuth) !== sourceFingerprint)) {
+                copyAuthAtomically(sourceAuth, destinationAuth);
+            }
+        }
+        const changed = this.authFingerprintInitialized && this.authFingerprint !== sourceFingerprint;
+        this.authFingerprint = sourceFingerprint;
+        this.authFingerprintInitialized = true;
+        this.authSourceSignature = sourceSignature;
+        const secretChanged = this.secretLaunchFingerprintInitialized &&
+            this.secretLaunchFingerprint !== launch.secretFingerprint;
+        if (!this.secretLaunchFingerprintInitialized ||
+            this.secretLaunchFingerprint !== launch.secretFingerprint) {
+            this.secrets = (0, cli_secret_redaction_js_1.configuredSecretValues)(launch);
+            this.secretLaunchFingerprint = launch.secretFingerprint;
+            this.secretLaunchFingerprintInitialized = true;
+        }
+        return changed || secretChanged;
+    }
+    async ensureStarted(launch, requestTimeout) {
+        if (this.child) {
+            return;
+        }
+        if (!this.startPromise) {
+            this.startPromise = this.start(launch, requestTimeout);
+        }
+        try {
+            await this.startPromise;
+        }
+        finally {
+            this.startPromise = undefined;
+        }
+    }
+    async start(launch, requestTimeout) {
+        const child = (0, node_child_process_1.spawn)(this.options.command, ['app-server', '--strict-config', '--stdio', ...launch.args], {
+            cwd: this.options.cwd,
+            env: { ...launch.env, HOME: this.options.isolatedHome, CODEX_HOME: this.options.codexHome },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.child = child;
+        this.stdout = (0, node_readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
+        this.stderr = (0, node_readline_1.createInterface)({ input: child.stderr, crlfDelay: Infinity });
+        this.stdout.on('line', (line) => this.handleLine(child, line));
+        this.stderr.on('line', (line) => this.handleStderr(line));
+        child.once('error', (error) => this.failProcess(child, error));
+        child.once('exit', (code, signal) => this.failProcess(child, new Error(`Codex app-server exited (${code ?? signal ?? 'unknown'})`)));
+        const initialized = await this.request('initialize', {
+            clientInfo: CLIENT_INFO,
+            capabilities: { experimentalApi: true },
+        }, requestTimeout);
+        const initializeResponse = object(initialized);
+        if (!initializeResponse ||
+            typeof initializeResponse.userAgent !== 'string' ||
+            typeof initializeResponse.codexHome !== 'string' ||
+            typeof initializeResponse.platformFamily !== 'string' ||
+            typeof initializeResponse.platformOs !== 'string') {
+            throw new Error('Codex app-server initialize returned a malformed response');
+        }
+        if ((0, node_fs_1.realpathSync)(initializeResponse.codexHome) !== (0, node_fs_1.realpathSync)(this.options.codexHome)) {
+            throw new Error('Codex app-server initialize returned an unexpected CODEX_HOME');
+        }
+        this.notify('initialized');
+    }
+    async openThread(session, launch) {
+        const record = this.registry.load(session.sessionKey);
+        if (record) {
+            // A rehydrated thread carries its original instructions only in the model's own
+            // history, where compaction eventually erodes them. ThreadResumeParams accepts
+            // baseInstructions, so re-anchor through the protocol when the caller can supply
+            // the full text. assertRegistryPolicy already proved the stored policy fingerprint
+            // matches this session, and the caller builds these instructions from the same
+            // composed-prompt sources that produced that fingerprint - so re-supplying them
+            // restates the agreed policy rather than switching to a new one.
+            const resumeInstructions = session.resumeInstructions
+                ? await session.resumeInstructions()
+                : undefined;
+            if (session.resumeInstructions && !resumeInstructions?.trim()) {
+                // No-fallback: silently resuming without instructions is the very failure this
+                // path exists to remove.
+                throw new Error('Codex app-server resume instructions resolved to empty text');
+            }
+            const resumeParams = {
+                threadId: record.threadId,
+                model: session.model,
+                cwd: session.cwd,
+                approvalPolicy: 'never',
+                ...(this.options.deniedReadPaths?.length
+                    ? { permissions: 'host-workspace' }
+                    : { sandbox: session.sandbox }),
+                config: this.threadConfig(session),
+            };
+            if (resumeInstructions) {
+                resumeParams.baseInstructions = resumeInstructions;
+            }
+            let result;
+            try {
+                result = object(await this.request('thread/resume', resumeParams, session.requestTimeout));
+            }
+            catch (error) {
+                // Only an explicit missing-context rejection permits replacement. Transport,
+                // authentication and overloaded-server failures retain the durable thread.
+                if (error instanceof CodexAppServerRpcError &&
+                    /no rollout found|thread (?:[^\n]* )?not found/i.test(error.message)) {
+                    throw new types_js_2.NativeSessionUnavailableError(error.message, { cause: error });
+                }
+                throw error;
+            }
+            this.validateResponsePolicy(result, session);
+            this.validateInstructionMetadata(result, session);
+            const resumed = validateThread(result?.thread);
+            if (typeof resumed?.id !== 'string' || resumed.id !== record.threadId) {
+                throw new Error('Codex app-server resumed an unexpected thread');
+            }
+            // Instructions delivered through the protocol make the turn-text bootstrap
+            // redundant; without them the legacy <system-reminder> replay still applies.
+            return { threadId: record.threadId, bootstrapPending: resumeInstructions === undefined };
+        }
+        const threadStartParams = {
+            model: session.model,
+            cwd: session.cwd,
+            approvalPolicy: 'never',
+            ...(this.options.deniedReadPaths?.length
+                ? { permissions: 'host-workspace' }
+                : { sandbox: session.sandbox }),
+            baseInstructions: session.systemPrompt,
+            config: this.threadConfig(session),
+        };
+        if (session.hostToolBridge) {
+            threadStartParams.dynamicTools = session.hostToolBridge.tools;
+        }
+        const result = object(await this.request('thread/start', threadStartParams, session.requestTimeout));
+        this.validateResponsePolicy(result, session);
+        this.validateInstructionMetadata(result, session);
+        const thread = validateThread(result?.thread);
+        if (typeof thread?.id !== 'string' || !thread.id) {
+            throw new Error('Codex app-server thread/start returned no thread id');
+        }
+        this.registry.save({
+            sessionKey: session.sessionKey,
+            threadId: thread.id,
+            model: session.model,
+            cwd: session.cwd,
+            systemPromptFingerprint: this.policyFingerprint(session),
+            mcpConfigFingerprint: launch.fingerprint,
+        });
+        return { threadId: thread.id, bootstrapPending: false, unproven: true, startupPending: true };
+    }
+    policyFingerprint(session) {
+        const original = session.policyFingerprint ?? (0, codex_thread_registry_js_1.fingerprintText)(session.systemPrompt);
+        const base = this.options.deniedReadPaths?.length
+            ? (0, codex_thread_registry_js_1.fingerprintText)(JSON.stringify([original, this.options.deniedReadPaths]))
+            : original;
+        const tools = session.hostToolBridge?.tools;
+        const roots = session.restrictedReadRoots;
+        if (!tools?.length && !roots) {
+            return base;
+        }
+        return (0, codex_thread_registry_js_1.fingerprintText)(`${base}${tools?.length ? `\n${JSON.stringify(tools)}` : ''}` +
+            `${roots ? `\nrestrictedReadRoots=${JSON.stringify(roots)}` : ''}`);
+    }
+    /** Restrict Codex-native child creation only for a thread with a stated read boundary. */
+    threadConfig(session) {
+        return session.restrictedReadRoots
+            ? { features: { multi_agent: false, multi_agent_v2: false } }
+            : {};
+    }
+    validateInstructionMetadata(result, session) {
+        const sources = result?.instructionSources;
+        if (!Array.isArray(sources)) {
+            throw new Error('Codex app-server returned malformed instruction sources');
+        }
+        const managedRoots = [session.cwd, this.options.codexHome].map((root) => (0, node_fs_1.realpathSync)(root));
+        for (const source of sources) {
+            if (typeof source !== 'string') {
+                throw new Error('Codex app-server returned malformed instruction source');
+            }
+            let path;
+            try {
+                path = (0, node_fs_1.realpathSync)((0, node_path_1.resolve)(session.cwd, source));
+            }
+            catch (error) {
+                throw new Error('Codex app-server loaded an instruction source outside managed roots', {
+                    cause: error,
+                });
+            }
+            const allowed = managedRoots.some((root) => {
+                const childPath = (0, node_path_1.relative)(root, path);
+                return (childPath === '' ||
+                    (childPath !== '..' && !childPath.startsWith(`..${node_path_1.sep}`) && !(0, node_path_1.isAbsolute)(childPath)));
+            });
+            if (!allowed) {
+                throw new Error('Codex app-server loaded an instruction source outside managed roots');
+            }
+        }
+    }
+    validateResponsePolicy(result, session) {
+        if (!result) {
+            throw new Error('Codex app-server returned a malformed thread response');
+        }
+        if (typeof result.modelProvider !== 'string' ||
+            (result.serviceTier !== null && typeof result.serviceTier !== 'string') ||
+            !APPROVAL_REVIEWERS.has(String(result.approvalsReviewer)) ||
+            (result.reasoningEffort !== null && typeof result.reasoningEffort !== 'string')) {
+            throw new Error('Codex app-server returned malformed thread response metadata');
+        }
+        if (typeof result.model !== 'string' || result.model !== session.model) {
+            throw new Error('Codex app-server response model did not match the requested policy');
+        }
+        if (typeof result.cwd !== 'string' || (0, node_path_1.resolve)(result.cwd) !== session.cwd) {
+            throw new Error('Codex app-server response cwd did not match the requested policy');
+        }
+        if (result.approvalPolicy !== 'never') {
+            throw new Error('Codex app-server response approval policy was not never');
+        }
+        const sandbox = object(result.sandbox);
+        const expectedSandboxType = {
+            'read-only': 'readOnly',
+            'workspace-write': 'workspaceWrite',
+            'danger-full-access': 'dangerFullAccess',
+        }[session.sandbox];
+        if (typeof sandbox?.type !== 'string' || sandbox.type !== expectedSandboxType) {
+            throw new Error('Codex app-server response sandbox did not match the requested policy');
+        }
+        if (sandbox.type === 'readOnly' && typeof sandbox.networkAccess !== 'boolean') {
+            throw new Error('Codex app-server returned a malformed read-only sandbox policy');
+        }
+        if (sandbox.type === 'workspaceWrite' &&
+            (!Array.isArray(sandbox.writableRoots) ||
+                typeof sandbox.networkAccess !== 'boolean' ||
+                typeof sandbox.excludeTmpdirEnvVar !== 'boolean' ||
+                typeof sandbox.excludeSlashTmp !== 'boolean')) {
+            throw new Error('Codex app-server returned a malformed workspace-write sandbox policy');
+        }
+    }
+    startTurn(threadId, text, callbacks, requestTimeout, hostToolBridge, runTokenBudget, nativeInputId = (0, node_crypto_1.randomUUID)(), restrictedReadRoots) {
+        return new Promise((resolveTurn, rejectTurn) => {
+            const abortController = new AbortController();
+            const timer = setTimeout(() => {
+                const error = new Error(`Codex app-server turn timed out after ${requestTimeout}ms`);
+                this.timeoutTurn(threadId, error, requestTimeout);
+            }, requestTimeout);
+            timer.unref();
+            const pendingTurn = {
+                threadId,
+                agentMessagePhases: new Map(),
+                usage: { input_tokens: 0, output_tokens: 0 },
+                runTokenBudget,
+                timer,
+                requestTimeout,
+                queuedNotifications: [],
+                queuedToolRequests: [],
+                toolCallQueue: Promise.resolve(),
+                toolCallResults: new Map(),
+                stoppingCallIds: new Set(),
+                hostToolBridge,
+                abortController,
+                intentionalStop: false,
+                onDelta: callbacks?.onDelta,
+                onToolUse: callbacks?.onToolUse,
+                onToolComplete: callbacks?.onToolComplete,
+                onSubagentStart: callbacks?.onSubagentStart,
+                nativeItems: new Map(),
+                resolve: resolveTurn,
+                reject: rejectTurn,
+            };
+            this.turns.set(threadId, pendingTurn);
+            try {
+                callbacks?.onInputDispatch?.({
+                    backend: 'codex',
+                    sessionId: threadId,
+                    inputId: nativeInputId,
+                });
+            }
+            catch (error) {
+                this.failTurn(threadId, this.toError(error));
+                return;
+            }
+            this.request('turn/start', {
+                threadId,
+                input: [{ type: 'text', text, text_elements: [] }],
+                ...(restrictedReadRoots
+                    ? {
+                        sandboxPolicy: {
+                            type: 'readOnly',
+                            access: {
+                                type: 'restricted',
+                                includePlatformDefaults: true,
+                                readableRoots: [...restrictedReadRoots],
+                            },
+                        },
+                    }
+                    : {}),
+            }, requestTimeout)
+                .then((value) => {
+                const turn = validateTurn(object(value)?.turn, 'turn/start turn');
+                if (typeof turn?.id !== 'string' || !turn.id) {
+                    this.failTurn(threadId, new Error('Codex app-server turn/start returned no turn id'));
+                    return;
+                }
+                const activeTurn = this.turns.get(threadId);
+                if (activeTurn === pendingTurn) {
+                    activeTurn.turnId = turn.id;
+                    callbacks?.onAccepted?.({ backend: 'codex', sessionId: threadId, turnId: turn.id });
+                    const queued = activeTurn.queuedNotifications.splice(0);
+                    for (const notification of queued) {
+                        this.handleNotification(notification.method, notification.params);
+                    }
+                    const queuedToolRequests = activeTurn.queuedToolRequests.splice(0);
+                    for (const request of queuedToolRequests) {
+                        this.handleDynamicToolRequest(request, activeTurn);
+                    }
+                }
+                else if (this.turnStartReconciliations.has(threadId)) {
+                    void this.reconcileAcknowledgedTurn(threadId, turn.id, requestTimeout);
+                }
+            })
+                .catch((error) => {
+                if (this.turns.get(threadId) === pendingTurn) {
+                    this.failTurn(threadId, error instanceof CodexAppServerRpcError && error.code !== OVERLOADED_ERROR_CODE
+                        ? new CodexTurnRejectedError(this.redact(error.message))
+                        : this.toError(error));
+                    return;
+                }
+                const reconciliation = this.turnStartReconciliations.get(threadId);
+                if (!reconciliation) {
+                    return;
+                }
+                if (error instanceof CodexAppServerRpcError) {
+                    this.completeTurnStartReconciliation(threadId, reconciliation);
+                }
+                else if (!reconciliation.recoveryTimer) {
+                    void this.shutdown(this.toError(error)).finally(() => {
+                        this.completeTurnStartReconciliation(threadId, reconciliation);
+                    });
+                }
+            });
+        });
+    }
+    async request(method, params, requestTimeout = this.options.requestTimeout) {
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await this.requestOnce(method, params, requestTimeout);
+            }
+            catch (error) {
+                if (!(error instanceof CodexAppServerRpcError) ||
+                    error.code !== OVERLOADED_ERROR_CODE ||
+                    attempt >= OVERLOAD_RETRY_LIMIT - 1) {
+                    throw error;
+                }
+                const delay = OVERLOAD_RETRY_BASE_MS * 2 ** attempt + Math.floor(Math.random() * 10);
+                await new Promise((resolveDelay) => {
+                    const timer = setTimeout(resolveDelay, delay);
+                    timer.unref();
+                });
+            }
+        }
+    }
+    requestOnce(method, params, requestTimeout) {
+        const child = this.child;
+        if (!child?.stdin.writable) {
+            return Promise.reject(new Error('Codex app-server stdin is not writable'));
+        }
+        const id = ++this.nextId;
+        return new Promise((resolveRequest, rejectRequest) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                const error = new Error(`Codex app-server ${method} timed out after ${requestTimeout}ms`);
+                const threadId = method === 'turn/start' ? object(params)?.threadId : undefined;
+                if (typeof threadId === 'string' && threadId) {
+                    const reconciliation = this.getOrCreateTurnStartReconciliation(threadId);
+                    reconciliation.recoveryTimer = setTimeout(() => {
+                        this.lateTurnStarts.delete(id);
+                        void this.shutdown(error).finally(() => {
+                            this.completeTurnStartReconciliation(threadId, reconciliation);
+                        });
+                    }, Math.max(requestTimeout, TURN_START_RECONCILE_GRACE_MS));
+                    reconciliation.recoveryTimer.unref();
+                    this.lateTurnStarts.set(id, { threadId, requestTimeout, reconciliation });
+                    rejectRequest(error);
+                    return;
+                }
+                rejectRequest(error);
+                void this.shutdown(error);
+            }, requestTimeout);
+            timer.unref();
+            this.pending.set(id, { method, timer, resolve: resolveRequest, reject: rejectRequest });
+            child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
+        });
+    }
+    notify(method, params) {
+        if (!this.child?.stdin.writable) {
+            throw new Error('Codex app-server stdin is not writable');
+        }
+        const message = params === undefined ? { jsonrpc: '2.0', method } : { jsonrpc: '2.0', method, params };
+        this.child.stdin.write(`${JSON.stringify(message)}\n`);
+    }
+    handleLine(child, line) {
+        if (child !== this.child || !line.trim()) {
+            return;
+        }
+        let message;
+        try {
+            const parsed = JSON.parse(line);
+            const record = object(parsed);
+            if (!record) {
+                throw new Error('not an object');
+            }
+            message = record;
+        }
+        catch {
+            const error = new Error('Codex app-server emitted malformed JSON');
+            this.failAll(error);
+            void this.shutdown(error);
+            return;
+        }
+        // Codex 0.144 accepts JSON-RPC 2.0 requests but omits the `jsonrpc`
+        // member from its responses and notifications on the stdio wire.
+        if (message.jsonrpc !== undefined && message.jsonrpc !== '2.0') {
+            const error = new Error('Codex app-server emitted a malformed protocol message');
+            this.failAll(error);
+            void this.shutdown(error);
+            return;
+        }
+        const hasMethod = typeof message.method === 'string';
+        const hasResult = Object.hasOwn(message, 'result');
+        const hasError = Object.hasOwn(message, 'error');
+        const hasRequestId = typeof message.id === 'number' || typeof message.id === 'string';
+        const serverRequest = hasMethod && hasRequestId && !hasResult && !hasError;
+        const notification = hasMethod && !hasRequestId && !hasResult && !hasError;
+        const response = !hasMethod && typeof message.id === 'number' && hasResult !== hasError;
+        if ([serverRequest, notification, response].filter(Boolean).length !== 1) {
+            const error = new Error('Codex app-server emitted a malformed protocol message');
+            this.failAll(error);
+            void this.shutdown(error);
+            return;
+        }
+        if (typeof message.method === 'string' &&
+            (typeof message.id === 'number' || typeof message.id === 'string')) {
+            this.handleServerRequest(child, message.id, message.method, message.params);
+            return;
+        }
+        if (typeof message.id === 'number') {
+            const lateTurnStart = this.lateTurnStarts.get(message.id);
+            if (lateTurnStart) {
+                this.handleLateTurnStartResponse(message.id, lateTurnStart, message);
+                return;
+            }
+            const pending = this.pending.get(message.id);
+            if (!pending) {
+                const error = new Error('Codex app-server response id did not match a pending request');
+                this.failAll(error);
+                void this.shutdown(error);
+                return;
+            }
+            clearTimeout(pending.timer);
+            this.pending.delete(message.id);
+            if (message.error !== undefined) {
+                const rpcError = object(message.error);
+                const code = typeof rpcError?.code === 'number' ? rpcError.code : 0;
+                pending.reject(new CodexAppServerRpcError(code, this.redact(errorMessage(message.error, `${pending.method} failed`))));
+            }
+            else if (!Object.hasOwn(message, 'result')) {
+                pending.reject(new Error(`Codex app-server ${pending.method} returned a malformed response`));
+            }
+            else {
+                pending.resolve(message.result);
+            }
+            return;
+        }
+        if (typeof message.method === 'string') {
+            this.handleNotification(message.method, message.params);
+        }
+    }
+    handleNotification(method, params) {
+        const data = object(params);
+        if (!data || typeof data.threadId !== 'string') {
+            return;
+        }
+        if (this.handleSubagentNotification(method, data.threadId, data)) {
+            return;
+        }
+        const turn = this.turns.get(data.threadId);
+        if (!turn) {
+            return;
+        }
+        const completedTurn = method === 'turn/completed' ? object(data.turn) : undefined;
+        const eventTurnId = typeof data.turnId === 'string'
+            ? data.turnId
+            : typeof completedTurn?.id === 'string'
+                ? completedTurn.id
+                : undefined;
+        if (eventTurnId && !turn.turnId) {
+            turn.queuedNotifications.push({ method, params });
+            return;
+        }
+        if (eventTurnId && eventTurnId !== turn.turnId) {
+            return;
+        }
+        // TG-03/04/05/06: these notifications observe native effects; they are not
+        // pre-execution hooks. Dynamic/MCP calls retain their existing host bridge.
+        if (method === 'item/started' || method === 'item/completed') {
+            if (typeof data.turnId !== 'string' || data.turnId !== turn.turnId) {
+                return;
+            }
+            const item = object(data.item);
+            if (!item || typeof item.id !== 'string' || typeof item.type !== 'string') {
+                return;
+            }
+            if (item.type === 'agentMessage') {
+                this.refreshTurnIdleTimeout(turn);
+                const phase = item.phase === 'commentary' || item.phase === 'final_answer' ? item.phase : null;
+                turn.agentMessagePhases.set(item.id, phase);
+                if (method === 'item/completed' &&
+                    phase === 'final_answer' &&
+                    typeof item.text === 'string') {
+                    turn.finalText = item.text;
+                }
+                else if (method === 'item/completed' && phase === null && typeof item.text === 'string') {
+                    turn.lastUnphasedText = item.text;
+                }
+                else if (method === 'item/completed' && phase === 'commentary') {
+                    turn.lastUnphasedText = undefined;
+                }
+                return;
+            }
+            if (item.type === 'reasoning') {
+                // A completed reasoning item is the model making progress; at high effort a
+                // thinking phase can outlast the idle timeout between tool calls.
+                this.refreshTurnIdleTimeout(turn);
+                return;
+            }
+            if (!['commandExecution', 'fileChange', 'webSearch', 'collabAgentToolCall'].includes(item.type)) {
+                return;
+            }
+            this.refreshTurnIdleTimeout(turn);
+            this.observeNativeItem(turn, method, item, turn.threadId);
+            return;
+        }
+        if (method === 'item/agentMessage/delta') {
+            if (typeof data.turnId !== 'string' || data.turnId !== turn.turnId) {
+                return;
+            }
+            if (typeof data.delta !== 'string' || typeof data.itemId !== 'string') {
+                this.failTurn(turn.threadId, new Error('Codex app-server returned malformed agent message delta'));
+                return;
+            }
+            this.refreshTurnIdleTimeout(turn);
+            if (!turn.agentMessagePhases.has(data.itemId)) {
+                this.failTurn(turn.threadId, new Error('Codex app-server delta preceded its agent message item'));
+                return;
+            }
+            if (turn.agentMessagePhases.get(data.itemId) === 'final_answer') {
+                try {
+                    turn.onDelta?.(data.delta);
+                }
+                catch (error) {
+                    this.failTurn(turn.threadId, this.toError(error));
+                }
+            }
+            return;
+        }
+        if (method === 'thread/tokenUsage/updated') {
+            if (typeof data.turnId !== 'string' || data.turnId !== turn.turnId) {
+                return;
+            }
+            const tokenUsage = object(data.tokenUsage);
+            const last = object(tokenUsage?.last);
+            const total = object(tokenUsage?.total);
+            this.refreshTurnIdleTimeout(turn);
+            const num = (value) => (typeof value === 'number' ? value : 0);
+            if (total) {
+                // Turn usage = cumulative-thread delta. The baseline derives from the
+                // first total-bearing event (total minus its own call, minus any usage
+                // already accumulated from total-less events this turn), so a resumed
+                // thread's unseen history is never attributed to this turn, and a
+                // multi-call tool-loop turn keeps its earlier calls (recording only
+                // `last` undercounted ~5x against the rollout ground truth).
+                turn.usageBaseline ??= {
+                    input: num(total.inputTokens) - num(last?.inputTokens) - turn.usage.input_tokens,
+                    output: num(total.outputTokens) - num(last?.outputTokens) - turn.usage.output_tokens,
+                    cached: num(total.cachedInputTokens) -
+                        num(last?.cachedInputTokens) -
+                        (turn.usage.cache_read_input_tokens ?? 0),
+                };
+                // A total below the baseline (compaction/rollback resetting the thread
+                // counter) must never write negative usage into the metrics DB.
+                const input = num(total.inputTokens) - turn.usageBaseline.input;
+                const output = num(total.outputTokens) - turn.usageBaseline.output;
+                const cached = num(total.cachedInputTokens) - turn.usageBaseline.cached;
+                if ((input < 0 || output < 0 || cached < 0) && !turn.usageShrinkWarned) {
+                    turn.usageShrinkWarned = true;
+                    console.warn('[CodexAppServer] cumulative token total shrank below the turn baseline; clamping usage to 0');
+                }
+                turn.usage = {
+                    input_tokens: Math.max(0, input),
+                    output_tokens: Math.max(0, output),
+                    cache_read_input_tokens: Math.max(0, cached),
+                };
+                this.enforceTurnBudget(turn.threadId, turn);
+            }
+            else {
+                // No cumulative total on this event: accumulate per-call usage.
+                turn.usage = {
+                    input_tokens: turn.usage.input_tokens + num(last?.inputTokens),
+                    output_tokens: turn.usage.output_tokens + num(last?.outputTokens),
+                    cache_read_input_tokens: (turn.usage.cache_read_input_tokens ?? 0) + num(last?.cachedInputTokens),
+                };
+                this.enforceTurnBudget(turn.threadId, turn);
+            }
+            return;
+        }
+        if (method !== 'turn/completed') {
+            return;
+        }
+        const completed = completedTurn;
+        if (!completed ||
+            typeof completed.id !== 'string' ||
+            (turn.turnId && completed.id !== turn.turnId))
+            return;
+        const status = completed.status;
+        if (status === 'inProgress') {
+            return;
+        }
+        try {
+            validateTurn(completed, 'turn/completed turn');
+        }
+        catch (error) {
+            this.failTurn(turn.threadId, this.toError(error));
+            return;
+        }
+        if (turn.abortError) {
+            this.failTurn(turn.threadId, turn.abortError);
+            return;
+        }
+        if (status === 'failed') {
+            this.failTurn(turn.threadId, new Error(this.redact(errorMessage(completed.error, 'Codex app-server turn failed'))));
+            return;
+        }
+        if (status === 'interrupted') {
+            if (turn.abortError) {
+                this.failTurn(turn.threadId, turn.abortError);
+            }
+            else if (turn.intentionalStop) {
+                this.resolveTurn(turn);
+            }
+            else {
+                this.failTurn(turn.threadId, new Error('Codex app-server turn was interrupted'));
+            }
+            return;
+        }
+        if (status !== 'completed') {
+            this.failTurn(turn.threadId, new Error(`Codex app-server returned unknown turn status: ${String(status)}`));
+            return;
+        }
+        if (turn.finalText === undefined) {
+            for (const entry of completed.items) {
+                const item = object(entry);
+                if (item?.type === 'agentMessage' &&
+                    item.phase === 'final_answer' &&
+                    typeof item.text === 'string') {
+                    turn.finalText = item.text;
+                }
+                else if (item?.type === 'agentMessage' && typeof item.text === 'string') {
+                    if (item.phase === undefined || item.phase === null) {
+                        turn.lastUnphasedText = item.text;
+                    }
+                    else if (item.phase === 'commentary') {
+                        turn.lastUnphasedText = undefined;
+                    }
+                }
+            }
+        }
+        if (turn.finalText === undefined && turn.lastUnphasedText !== undefined) {
+            // Some supported Codex providers omit phase. Use their terminal item,
+            // never accumulated deltas, so known commentary cannot become the reply.
+            turn.finalText = turn.lastUnphasedText;
+        }
+        if (turn.finalText === undefined) {
+            this.failTurn(turn.threadId, new Error('Codex app-server completed without final_answer'));
+            return;
+        }
+        this.resolveTurn(turn);
+    }
+    resolveTurn(turn) {
+        if (this.turns.get(turn.threadId) !== turn) {
+            return;
+        }
+        this.turns.delete(turn.threadId);
+        clearTimeout(turn.timer);
+        this.clearTurnCallbacks(turn);
+        turn.resolve({
+            response: turn.finalText ?? '',
+            usage: turn.usage,
+            session_id: turn.threadId,
+            toolUseBlocks: undefined,
+            hasToolUse: false,
+        });
+    }
+    // ─── Codex-native subagents ───────────────────────────────────────────────
+    //
+    // Codex announces a child on the PARENT thread as a `subAgentActivity` item and then
+    // drives the child on its OWN thread id, which outlives the parent turn. Nothing here
+    // blocks a run. A child NEVER inherits the parent turn's bridge: the parent's envelope
+    // expires with the parent's wall and the child cannot renew it, so a child that
+    // inherited it would lose every tool mid-run and still report "done". The host issues
+    // the child its own authority instead (`createSubagentBridge`), or the child has none
+    // and its calls are refused loudly.
+    /** Returns true when this notification belongs to the subagent surface and was consumed. */
+    observeNativeItem(target, method, item, threadId, subagent = false) {
+        if (typeof item.id !== 'string' ||
+            typeof item.type !== 'string' ||
+            !['commandExecution', 'fileChange', 'webSearch', 'collabAgentToolCall'].includes(item.type))
+            return;
+        const observationId = nativeObservationId(threadId, item.id);
+        let observed = target.nativeItems.get(observationId);
+        if (!observed) {
+            observed = { name: item.type, completed: false };
+            target.nativeItems.set(observationId, observed);
+            const input = { nativeToolUseId: observationId, providerToolUseId: item.id };
+            if (subagent)
+                input.subagentThreadId = threadId;
+            // Input only: stdout, results and file diffs are not diagnostic inputs.
+            for (const key of ['command', 'cwd', 'action', 'query', 'queries', 'url']) {
+                if (item[key] !== undefined)
+                    input[key] = item[key];
+            }
+            if (Array.isArray(item.changes))
+                input.paths = item.changes.map((change) => object(change)?.path);
+            try {
+                target.onToolUse?.(item.type, input);
+            }
+            catch {
+                console.warn('[CodexAppServer] native observation failed');
+            }
+        }
+        if (method === 'item/completed' && !observed.completed) {
+            observed.completed = true;
+            const isError = (item.status !== undefined && item.status !== 'completed') ||
+                (typeof item.exitCode === 'number' && item.exitCode !== 0);
+            try {
+                target.onToolComplete?.(observed.name, observationId, isError);
+            }
+            catch {
+                console.warn('[CodexAppServer] native observation failed');
+            }
+        }
+    }
+    handleSubagentNotification(method, threadId, data) {
+        if (method === 'item/started' || method === 'item/completed') {
+            const item = object(data.item);
+            if (item?.type === 'subAgentActivity') {
+                // Only a thread this process actually drives may announce children.
+                if (!this.subagents.has(threadId) && !this.threadContexts.has(threadId)) {
+                    return false;
+                }
+                if (item.kind === 'started') {
+                    this.registerSubagent(threadId, item);
+                }
+                else if (item.kind === 'completed') {
+                    this.observeParentSideCompletion(threadId, item);
+                }
+                return true;
+            }
+            const child = this.subagents.get(threadId);
+            if (!child) {
+                return false;
+            }
+            this.refreshParentTurnIdleTimeout(child);
+            if (item)
+                this.observeNativeItem(child, method, item, threadId, true);
+            if (method === 'item/completed' &&
+                item?.type === 'agentMessage' &&
+                item.phase === 'final_answer' &&
+                typeof item.text === 'string') {
+                child.finalText = item.text.slice(0, SUBAGENT_FINAL_TEXT_LIMIT);
+            }
+            return true;
+        }
+        const child = this.subagents.get(threadId);
+        if (!child) {
+            return false;
+        }
+        this.refreshParentTurnIdleTimeout(child);
+        if (method !== 'turn/completed') {
+            return true;
+        }
+        const completed = object(data.turn);
+        const status = completed?.status;
+        if (status === 'inProgress') {
+            return true;
+        }
+        if (status !== 'completed' && status !== 'failed' && status !== 'interrupted') {
+            return true;
+        }
+        if (!child.finalText) {
+            child.finalText = this.subagentFinalText(completed?.items);
+        }
+        // The child's OWN turn/completed is the only completing event: the parent-side
+        // announcement carries neither status nor result.
+        this.finishSubagent(threadId, status, status === 'failed'
+            ? this.redact(errorMessage(completed?.error, 'Codex app-server subagent turn failed'))
+            : undefined);
+        return true;
+    }
+    subagentFinalText(items) {
+        if (!Array.isArray(items)) {
+            return '';
+        }
+        let text = '';
+        for (const entry of items) {
+            const item = object(entry);
+            if (item?.type === 'agentMessage' && typeof item.text === 'string') {
+                text = item.text;
+            }
+        }
+        return text.slice(0, SUBAGENT_FINAL_TEXT_LIMIT);
+    }
+    /** A working child keeps the parent's idle timeout alive (the parent may be in wait_agent). */
+    refreshParentTurnIdleTimeout(child) {
+        const parentTurn = this.turns.get(child.parentThreadId);
+        if (parentTurn) {
+            this.refreshTurnIdleTimeout(parentTurn);
+        }
+    }
+    /** Drop every thread context this session left behind on a previous thread id. */
+    pruneThreadContexts(sessionKey, currentThreadId) {
+        for (const [threadId, context] of this.threadContexts) {
+            if (context.sessionKey === sessionKey && threadId !== currentThreadId) {
+                this.threadContexts.delete(threadId);
+            }
+        }
+    }
+    knownThreadIds() {
+        const ids = new Set(this.threadContexts.keys());
+        for (const state of this.sessions.values()) {
+            if (state.threadId) {
+                ids.add(state.threadId);
+            }
+        }
+        for (const threadId of this.turns.keys()) {
+            ids.add(threadId);
+        }
+        return ids;
+    }
+    registerSubagent(parentThreadId, item) {
+        const agentThreadId = typeof item.agentThreadId === 'string' ? item.agentThreadId : '';
+        if (!agentThreadId || this.subagents.has(agentThreadId)) {
+            // The same `started` announcement arrives twice (item/started + item/completed views).
+            return;
+        }
+        if (this.finishedSubagents.has(agentThreadId)) {
+            // The second view of that announcement lost the race with the child's own
+            // turn/completed. Re-registering would resurrect a finished child.
+            console.warn(`[CodexAppServer] subagent announcement ignored: thread=${agentThreadId} already finished`);
+            return;
+        }
+        // A child may never claim a thread this process already drives: that would let one
+        // session's announcement capture another session's live parent thread.
+        if (this.knownThreadIds().has(agentThreadId)) {
+            console.warn(`[CodexAppServer] subagent announcement refused: thread=${agentThreadId} is a live thread`);
+            return;
+        }
+        // A grandchild's session comes from the child that announced it.
+        const parent = this.subagents.get(parentThreadId) ?? this.threadContexts.get(parentThreadId);
+        if (!parent) {
+            return;
+        }
+        const agentPath = typeof item.agentPath === 'string' ? item.agentPath : '';
+        // Observed admission: tell the PARENT'S live turn that this run handed work to a
+        // child. Nothing else on the item stream carries that fact - on codex-cli 0.153.4
+        // a spawn surfaces ONLY as `subAgentActivity`, which this handler consumes before
+        // the native-item path. Never routed through onToolUse (effect ledger, see
+        // PromptCallbacks.onSubagentStart).
+        const parentTurn = this.turns.get(parentThreadId);
+        if (parentTurn?.onSubagentStart) {
+            const itemId = typeof item.id === 'string' ? item.id : '';
+            try {
+                parentTurn.onSubagentStart({ agentThreadId, agentPath, itemId });
+            }
+            catch (error) {
+                console.warn(`[CodexAppServer] onSubagentStart callback failed: ${this.toError(error).message}`);
+            }
+        }
+        const factory = this.options.createSubagentBridge;
+        const child = {
+            parentThreadId,
+            sessionKey: parent.sessionKey,
+            agentPath,
+            onToolUse: parent.onToolUse,
+            onToolComplete: parent.onToolComplete,
+            nativeItems: new Map(),
+            finalText: '',
+            startedAt: Date.now(),
+            toolCallQueue: Promise.resolve(),
+            toolCallResults: new Map(),
+            stoppingCallIds: new Set(),
+            abortController: new AbortController(),
+            authorityWarned: false,
+            authority: factory
+                ? factory({
+                    sessionKey: parent.sessionKey,
+                    parentThreadId,
+                    agentThreadId,
+                    agentPath,
+                })
+                    .then((authority) => authority ? { ...authority, bridge: snapshotHostToolBridge(authority.bridge) } : null)
+                    .catch((error) => {
+                    console.warn(`[CodexAppServer] subagent authority factory failed thread=${agentThreadId}: ${this.toError(error).message}`);
+                    return null;
+                })
+                : Promise.resolve(null),
+        };
+        child.ttlTimer = setTimeout(() => {
+            child.ttlTimer = undefined;
+            this.finishSubagent(agentThreadId, 'failed', 'subagent produced no completion');
+        }, this.options.subagentTtlMs ?? SUBAGENT_TTL_MS);
+        child.ttlTimer.unref();
+        this.subagents.set(agentThreadId, child);
+        console.log(`[CodexAppServer] subagent started path=${agentPath} thread=${agentThreadId}`);
+        this.emitSubagentEvent({
+            kind: 'started',
+            sessionKey: parent.sessionKey,
+            parentThreadId,
+            agentThreadId,
+            agentPath,
+        });
+    }
+    /**
+     * The parent says a child finished. That is an announcement, not a result: it can win
+     * the race against the child's own `turn/completed`, which is what carries status and
+     * final text. Wait a bounded grace for the real event, then report `unknown`.
+     */
+    observeParentSideCompletion(announcingThreadId, item) {
+        const agentThreadId = typeof item.agentThreadId === 'string' ? item.agentThreadId : '';
+        const child = agentThreadId ? this.subagents.get(agentThreadId) : undefined;
+        if (!child) {
+            return;
+        }
+        if (child.parentThreadId !== announcingThreadId) {
+            console.warn(`[CodexAppServer] subagent completion refused: thread=${announcingThreadId} does not own ${agentThreadId}`);
+            return;
+        }
+        if (child.graceTimer) {
+            return;
+        }
+        child.graceTimer = setTimeout(() => {
+            child.graceTimer = undefined;
+            console.warn(`[CodexAppServer] subagent completion unconfirmed path=${child.agentPath} thread=${agentThreadId}`);
+            this.finishSubagent(agentThreadId, 'unknown');
+        }, this.options.subagentGraceMs ?? SUBAGENT_COMPLETION_GRACE_MS);
+        child.graceTimer.unref();
+    }
+    /**
+     * Emits exactly one completion per child thread and releases its authority with the
+     * same terminal status. Grandchildren keep their own entries.
+     */
+    finishSubagent(agentThreadId, status, error) {
+        const child = this.subagents.get(agentThreadId);
+        if (!child) {
+            return;
+        }
+        if (!child.completionEvent) {
+            for (const [callId, item] of child.nativeItems) {
+                if (item.completed)
+                    continue;
+                item.completed = true;
+                try {
+                    child.onToolComplete?.(item.name, callId, true, 'unknown');
+                }
+                catch {
+                    console.warn('[CodexAppServer] native observation failed');
+                }
+            }
+            this.clearSubagentTimers(child);
+            const finalText = child.finalText ? this.redact(child.finalText) : '';
+            child.completionEvent = {
+                kind: 'completed',
+                sessionKey: child.sessionKey,
+                parentThreadId: child.parentThreadId,
+                agentThreadId,
+                agentPath: child.agentPath,
+                status,
+                ...(finalText ? { finalText } : {}),
+                ...(error ? { error } : {}),
+            };
+        }
+        this.deliverSubagentCompletion(child);
+    }
+    deliverSubagentCompletion(child) {
+        const event = child.completionEvent;
+        if (!event || this.subagents.get(event.agentThreadId) !== child)
+            return;
+        if (!this.emitSubagentEvent(event)) {
+            if (!child.completionRetryTimer) {
+                child.completionRetryTimer = setTimeout(() => {
+                    child.completionRetryTimer = undefined;
+                    this.deliverSubagentCompletion(child);
+                }, 1_000);
+                child.completionRetryTimer.unref();
+            }
+            return;
+        }
+        this.subagents.delete(event.agentThreadId);
+        this.rememberFinishedSubagent(event.agentThreadId);
+        this.clearSubagentTimers(child);
+        console.log(`[CodexAppServer] subagent completed status=${event.status} path=${child.agentPath} thread=${event.agentThreadId}`);
+        void child.authority
+            .then(async (authority) => {
+            if (!authority) {
+                return;
+            }
+            await authority.release({
+                status: event.status ?? 'unknown',
+                ...(event.error ? { error: event.error } : {}),
+            });
+        })
+            .catch((releaseError) => {
+            console.warn(`[CodexAppServer] subagent authority release failed thread=${event.agentThreadId}: ${this.toError(releaseError).message}`);
+        });
+    }
+    /** FIFO-bounded identity of finished children; the oldest id is forgotten first. */
+    rememberFinishedSubagent(agentThreadId) {
+        this.finishedSubagents.add(agentThreadId);
+        while (this.finishedSubagents.size > MAX_FINISHED_SUBAGENTS) {
+            const oldest = this.finishedSubagents.values().next().value;
+            if (oldest === undefined) {
+                return;
+            }
+            this.finishedSubagents.delete(oldest);
+        }
+    }
+    clearSubagentTimers(child) {
+        if (child.ttlTimer) {
+            clearTimeout(child.ttlTimer);
+            child.ttlTimer = undefined;
+        }
+        if (child.graceTimer) {
+            clearTimeout(child.graceTimer);
+            child.graceTimer = undefined;
+        }
+        if (child.completionRetryTimer) {
+            clearTimeout(child.completionRetryTimer);
+            child.completionRetryTimer = undefined;
+        }
+    }
+    emitSubagentEvent(event) {
+        const emit = this.options.onSubagentEvent;
+        if (!emit) {
+            return true;
+        }
+        try {
+            emit(event);
+            return true;
+        }
+        catch (error) {
+            console.warn(`[CodexAppServer] subagent event listener failed: ${this.toError(error).message}`);
+            return false;
+        }
+    }
+    /** Every live child is reported interrupted and its authority released. */
+    terminateSubagents(reason) {
+        const safe = this.toError(reason);
+        for (const agentThreadId of [...this.subagents.keys()]) {
+            const child = this.subagents.get(agentThreadId);
+            if (!child) {
+                continue;
+            }
+            child.abortController.abort(safe);
+            this.finishSubagent(agentThreadId, 'interrupted', safe.message);
+        }
+    }
+    /** A reset/restart drops the thread's context and interrupts its children. */
+    discardSessionThreadState(sessionKey, reason) {
+        const threadId = this.sessions.get(sessionKey)?.threadId;
+        if (threadId) {
+            this.threadContexts.delete(threadId);
+        }
+        for (const agentThreadId of [...this.subagents.keys()]) {
+            const child = this.subagents.get(agentThreadId);
+            if (!child || child.sessionKey !== sessionKey) {
+                continue;
+            }
+            child.abortController.abort(new Error(`Codex app-server ${reason}`));
+            this.finishSubagent(agentThreadId, 'interrupted', reason);
+        }
+    }
+    handleSubagentToolRequest(request, agentThreadId, child, data) {
+        this.refreshParentTurnIdleTimeout(child);
+        // The child's authority is host-issued and asynchronous; its calls queue until it
+        // resolves rather than falling back to anything the parent held.
+        void child.authority.then((authority) => {
+            try {
+                const turnId = this.requiredToolString(data, 'turnId');
+                const callId = this.requiredToolString(data, 'callId');
+                const tool = this.requiredToolString(data, 'tool');
+                if (data.namespace !== null && typeof data.namespace !== 'string') {
+                    throw new Error('Codex app-server tool call namespace must be null or a string');
+                }
+                const input = object(data.arguments);
+                if (!input) {
+                    throw new Error('Codex app-server tool call arguments must be an object');
+                }
+                if (!authority) {
+                    if (!child.authorityWarned) {
+                        child.authorityWarned = true;
+                        console.warn(`[CodexAppServer] ${SUBAGENT_AUTHORITY_UNAVAILABLE} path=${child.agentPath} thread=${agentThreadId}`);
+                    }
+                    this.replyToolError(request, `${SUBAGENT_AUTHORITY_UNAVAILABLE}: ${tool} was refused`);
+                    return;
+                }
+                const bridge = authority.bridge;
+                if (!bridge.tools.some((definition) => definition.name === tool)) {
+                    throw new Error(`Codex app-server tool call ${tool} was not advertised`);
+                }
+                this.dispatchSubagentToolCall(request, agentThreadId, child, bridge, {
+                    turnId,
+                    callId,
+                    tool,
+                    namespace: data.namespace ?? null,
+                    input,
+                });
+            }
+            catch (error) {
+                // A child's protocol error is reported to the child only: the parent turn it was
+                // spawned from may already have resolved, and there is nothing here to fail.
+                this.replyToolError(request, this.toError(error).message);
+            }
+        });
+    }
+    dispatchSubagentToolCall(request, agentThreadId, child, bridge, call) {
+        const { turnId, callId, tool, namespace, input } = call;
+        const identity = JSON.stringify(stableJson({ threadId: agentThreadId, turnId, tool, namespace, arguments: input }));
+        const existing = child.toolCallResults.get(callId);
+        if (existing && existing.identity !== identity) {
+            throw new Error(`Codex app-server callId ${callId} had a conflicting request`);
+        }
+        let execution = existing?.execution;
+        if (!execution) {
+            execution = child.toolCallQueue
+                .then(async () => {
+                if (!this.isSubagentToolActive(request, agentThreadId, child)) {
+                    return {
+                        result: this.toolResult(false, 'Codex app-server tool call is no longer active'),
+                        stop: false,
+                        abortError: undefined,
+                    };
+                }
+                try {
+                    child.onToolUse?.(tool, {
+                        nativeToolUseId: nativeObservationId(agentThreadId, callId),
+                        providerToolUseId: callId,
+                        subagentThreadId: agentThreadId,
+                        agentPath: child.agentPath,
+                    });
+                }
+                catch (error) {
+                    console.warn(`[CodexAppServer] subagent onToolUse failed: ${this.toError(error).message}`);
+                }
+                let result;
+                try {
+                    result = await bridge.execute({
+                        callId,
+                        name: tool,
+                        input,
+                        signal: child.abortController.signal,
+                    });
+                }
+                catch (error) {
+                    result = { content: this.toError(error).message, isError: true };
+                }
+                const resultData = object(result);
+                if (!resultData ||
+                    typeof resultData.content !== 'string' ||
+                    typeof resultData.isError !== 'boolean') {
+                    this.reportSubagentToolComplete(child, tool, nativeObservationId(agentThreadId, callId), true);
+                    return {
+                        result: this.toolResult(false, 'Host tool returned a malformed result'),
+                        stop: false,
+                        abortError: undefined,
+                    };
+                }
+                this.reportSubagentToolComplete(child, tool, nativeObservationId(agentThreadId, callId), resultData.isError);
+                return {
+                    result: this.toolResult(!resultData.isError, resultData.content),
+                    stop: resultData.stop === true || resultData.abort === true,
+                    abortError: undefined,
+                };
+            })
+                .catch((error) => ({
+                result: this.toolResult(false, this.toError(error).message),
+                stop: false,
+                abortError: undefined,
+            }));
+            child.toolCallResults.set(callId, { identity, execution });
+            child.toolCallQueue = execution.then(() => undefined, () => undefined);
+        }
+        void execution.then(({ result, stop }) => {
+            if (!this.isSubagentToolActive(request, agentThreadId, child)) {
+                if (this.child === request.child) {
+                    this.replyToolError(request, 'Codex app-server tool call is no longer active');
+                }
+                return;
+            }
+            this.reply(request.child, { jsonrpc: '2.0', id: request.id, result });
+            if (stop && !child.stoppingCallIds.has(callId)) {
+                child.stoppingCallIds.add(callId);
+                child.abortController.abort(new Error('Codex app-server subagent tool stopped the run'));
+                void this.request('turn/interrupt', { threadId: agentThreadId, turnId }).catch((error) => console.warn(`[CodexAppServer] subagent interrupt failed: ${this.toError(error).message}`));
+            }
+        });
+    }
+    reportSubagentToolComplete(child, tool, callId, isError) {
+        try {
+            child.onToolComplete?.(tool, callId, isError);
+        }
+        catch (error) {
+            console.warn(`[CodexAppServer] subagent onToolComplete failed: ${this.toError(error).message}`);
+        }
+    }
+    isSubagentToolActive(request, agentThreadId, child) {
+        return (this.child === request.child &&
+            this.subagents.get(agentThreadId) === child &&
+            !child.abortController.signal.aborted);
+    }
+    handleServerRequest(child, id, method, params) {
+        if (method === 'item/tool/call') {
+            this.handleDynamicToolRequest({ child, id, params });
+            return;
+        }
+        const bodies = {
+            'item/tool/requestUserInput': { answers: {} },
+            'mcpServer/elicitation/request': { action: 'decline', content: null, _meta: null },
+            'item/commandExecution/requestApproval': { decision: 'decline' },
+            'item/fileChange/requestApproval': { decision: 'decline' },
+            'item/permissions/requestApproval': {
+                permissions: {},
+                scope: 'turn',
+                strictAutoReview: true,
+            },
+            applyPatchApproval: { decision: 'denied' },
+            execCommandApproval: { decision: 'denied' },
+        };
+        if (Object.hasOwn(bodies, method)) {
+            this.reply(child, { jsonrpc: '2.0', id, result: bodies[method] });
+        }
+        else {
+            this.reply(child, {
+                jsonrpc: '2.0',
+                id,
+                error: { code: -32601, message: `Unsupported app-server request: ${method}` },
+            });
+        }
+    }
+    handleDynamicToolRequest(request, expectedTurn) {
+        const data = object(request.params);
+        const threadId = typeof data?.threadId === 'string' ? data.threadId : undefined;
+        const turn = threadId ? this.turns.get(threadId) : undefined;
+        if (data && threadId && !turn && !expectedTurn) {
+            // A Codex-native child calls on ITS OWN thread id, which never holds a PendingTurn.
+            const child = this.subagents.get(threadId);
+            if (child) {
+                this.handleSubagentToolRequest(request, threadId, child, data);
+                return;
+            }
+        }
+        if (!data || !turn || !turn.hostToolBridge || (expectedTurn && turn !== expectedTurn)) {
+            this.replyDisabledTool(request);
+            return;
+        }
+        try {
+            const turnId = this.requiredToolString(data, 'turnId');
+            const callId = this.requiredToolString(data, 'callId');
+            const tool = this.requiredToolString(data, 'tool');
+            if (data.namespace !== null && typeof data.namespace !== 'string') {
+                throw new Error('Codex app-server tool call namespace must be null or a string');
+            }
+            const input = object(data.arguments);
+            if (!input) {
+                throw new Error('Codex app-server tool call arguments must be an object');
+            }
+            if (!turn.hostToolBridge.tools.some((definition) => definition.name === tool)) {
+                throw new Error(`Codex app-server tool call ${tool} was not advertised`);
+            }
+            if (!turn.turnId) {
+                turn.queuedToolRequests.push(request);
+                return;
+            }
+            if (turnId !== turn.turnId) {
+                this.failToolProtocol(request, turn, new Error('Codex app-server tool call did not match the active turn'));
+                return;
+            }
+            this.refreshTurnIdleTimeout(turn);
+            this.dispatchDynamicToolCall(request, turn, callId, tool, data.namespace, input);
+        }
+        catch (error) {
+            this.failToolProtocol(request, turn, this.toError(error));
+        }
+    }
+    failToolProtocol(request, turn, error) {
+        const failure = this.toError(error);
+        this.replyToolError(request, failure.message);
+        this.failTurn(turn.threadId, failure);
+        if (this.child === request.child && !this.shutdownPromise) {
+            void this.shutdown(failure);
+        }
+    }
+    requiredToolString(data, field) {
+        const value = data[field];
+        if (typeof value !== 'string' || !value) {
+            throw new Error(`Codex app-server tool call ${field} must be a string`);
+        }
+        return value;
+    }
+    dispatchDynamicToolCall(request, turn, callId, tool, namespace, input) {
+        const identity = JSON.stringify(stableJson({
+            threadId: turn.threadId,
+            turnId: turn.turnId,
+            tool,
+            namespace,
+            arguments: input,
+        }));
+        const existing = turn.toolCallResults.get(callId);
+        if (existing && existing.identity !== identity) {
+            throw new Error(`Codex app-server callId ${callId} had a conflicting request`);
+        }
+        let execution = existing?.execution;
+        if (!execution) {
+            const bridge = turn.hostToolBridge;
+            if (!bridge) {
+                this.replyDisabledTool(request);
+                return;
+            }
+            execution = turn.toolCallQueue
+                .then(async () => {
+                if (!this.isToolTurnActive(request, turn)) {
+                    return {
+                        result: this.toolResult(false, 'Codex app-server tool call is no longer active'),
+                        stop: false,
+                        abortError: undefined,
+                    };
+                }
+                let result;
+                try {
+                    result = await bridge.execute({
+                        callId,
+                        name: tool,
+                        input,
+                        signal: turn.abortController.signal,
+                    });
+                }
+                catch (error) {
+                    result = { content: this.toError(error).message, isError: true };
+                }
+                const resultData = object(result);
+                if (!resultData ||
+                    typeof resultData.content !== 'string' ||
+                    typeof resultData.isError !== 'boolean') {
+                    return {
+                        result: this.toolResult(false, 'Host tool returned a malformed result'),
+                        stop: false,
+                        abortError: undefined,
+                    };
+                }
+                const abortError = resultData.abort === true && resultData.isError
+                    ? (0, types_js_1.isHostToolTerminalCode)(resultData.terminalCode)
+                        ? new types_js_1.HostToolTerminalError(resultData.terminalCode, resultData.content)
+                        : new Error(resultData.content)
+                    : undefined;
+                if (abortError instanceof types_js_1.HostToolTerminalError) {
+                    turn.settledTerminalError ??= abortError;
+                }
+                return {
+                    result: this.toolResult(!resultData.isError, resultData.content),
+                    stop: resultData.stop === true && !resultData.isError,
+                    abortError,
+                };
+            })
+                .catch((error) => ({
+                result: this.toolResult(false, this.toError(error).message),
+                stop: false,
+                abortError: undefined,
+            }));
+            turn.toolCallResults.set(callId, { identity, execution });
+            turn.toolCallQueue = execution.then(() => undefined, () => undefined);
+        }
+        void execution.then(({ result, stop, abortError }) => {
+            if (!this.isToolTurnActive(request, turn)) {
+                if (this.child === request.child) {
+                    this.replyToolError(request, 'Codex app-server tool call is no longer active');
+                }
+                return;
+            }
+            this.refreshTurnIdleTimeout(turn);
+            this.reply(request.child, { jsonrpc: '2.0', id: request.id, result });
+            if (abortError && !turn.stoppingCallIds.has(callId)) {
+                turn.stoppingCallIds.add(callId);
+                turn.abortError = abortError;
+                void this.request('turn/interrupt', { threadId: turn.threadId, turnId: turn.turnId }).catch((error) => this.failTurn(turn.threadId, this.toError(error)));
+            }
+            else if (stop && !turn.stoppingCallIds.has(callId)) {
+                turn.stoppingCallIds.add(callId);
+                turn.intentionalStop = true;
+                void this.request('turn/interrupt', { threadId: turn.threadId, turnId: turn.turnId }).catch((error) => this.failTurn(turn.threadId, this.toError(error)));
+            }
+        });
+    }
+    isToolTurnActive(request, turn) {
+        return (this.child === request.child &&
+            this.turns.get(turn.threadId) === turn &&
+            !turn.intentionalStop &&
+            !turn.abortError &&
+            !turn.abortController.signal.aborted);
+    }
+    toolResult(success, content) {
+        return { success, contentItems: [{ type: 'inputText', text: content }] };
+    }
+    replyDisabledTool(request) {
+        this.reply(request.child, {
+            jsonrpc: '2.0',
+            id: request.id,
+            result: this.toolResult(false, 'Native app-server tools are disabled by MAMA'),
+        });
+    }
+    replyToolError(request, message) {
+        this.reply(request.child, {
+            jsonrpc: '2.0',
+            id: request.id,
+            error: { code: -32602, message },
+        });
+    }
+    reply(child, message) {
+        if (child.stdin.writable) {
+            child.stdin.write(`${JSON.stringify(message)}\n`);
+        }
+    }
+    handleStderr(line) {
+        this.stderrTail = `${this.stderrTail}${this.redact(line)}\n`.slice(-STDERR_LIMIT);
+    }
+    redact(value) {
+        return (0, cli_secret_redaction_js_1.redactConfiguredSecrets)(value, this.secrets);
+    }
+    toError(error) {
+        if (error instanceof types_js_1.HostToolTerminalError) {
+            return new types_js_1.HostToolTerminalError(error.terminalCode, this.redact(error.message));
+        }
+        if (error instanceof CodexTurnRejectedError) {
+            return new CodexTurnRejectedError(this.redact(error.message));
+        }
+        return error instanceof Error
+            ? new Error(this.redact(error.message))
+            : new Error(this.redact(String(error)));
+    }
+    refreshTurnIdleTimeout(turn) {
+        if (this.turns.get(turn.threadId) !== turn) {
+            return;
+        }
+        clearTimeout(turn.timer);
+        turn.timer = setTimeout(() => {
+            const error = new Error(`Codex app-server turn timed out after ${turn.requestTimeout}ms without progress`);
+            this.timeoutTurn(turn.threadId, error, turn.requestTimeout);
+        }, turn.requestTimeout);
+        turn.timer.unref();
+    }
+    failTurn(threadId, error) {
+        const turn = this.turns.get(threadId);
+        if (!turn) {
+            return;
+        }
+        this.turns.delete(threadId);
+        clearTimeout(turn.timer);
+        turn.abortController.abort(error);
+        turn.queuedNotifications.length = 0;
+        turn.queuedToolRequests.length = 0;
+        const safe = this.toError(error);
+        // A gateway mutation that cannot be interrupted must settle before the
+        // caller sees failure. This prevents retries from racing a late mutation.
+        void turn.toolCallQueue.finally(() => {
+            this.clearTurnCallbacks(turn);
+            const terminalError = turn.settledTerminalError ??
+                (turn.abortError instanceof types_js_1.HostToolTerminalError ? turn.abortError : undefined);
+            turn.reject(this.toError(terminalError ?? safe));
+        });
+    }
+    /** Interrupt a turn whose counted usage crossed its run budget; the loop reports stoppedBy. */
+    enforceTurnBudget(threadId, turn) {
+        const budget = turn.runTokenBudget ?? 0;
+        if (budget <= 0 || turn.budgetStopped) {
+            return;
+        }
+        // Codex reports inputTokens INCLUSIVE of cachedInputTokens (OpenAI usage semantics),
+        // so cached is not added again: 0.44.0 counted a 2.8M wiki turn as 5.5M.
+        const counted = turn.usage.input_tokens + turn.usage.output_tokens;
+        if (counted < budget) {
+            return;
+        }
+        turn.budgetStopped = true;
+        const error = new Error(`run budget stop: ${counted} >= ${budget} counted tokens inside one turn`);
+        error.code = 'RUN_BUDGET_STOP';
+        // The interrupted turn's usage rides on the error: the loop's success path never
+        // runs for it, and the most expensive run of the day must not count as zero.
+        error.usage = { ...turn.usage };
+        this.timeoutTurn(threadId, error, DEFAULT_TIMEOUT);
+    }
+    timeoutTurn(threadId, error, requestTimeout) {
+        const turn = this.turns.get(threadId);
+        if (!turn) {
+            return;
+        }
+        const turnId = turn.turnId;
+        if (!turnId) {
+            this.getOrCreateTurnStartReconciliation(threadId);
+        }
+        this.failTurn(threadId, error);
+        if (!turnId) {
+            return;
+        }
+        void this.request('turn/interrupt', { threadId, turnId }, requestTimeout).catch((interruptError) => {
+            if (this.child && !this.shutdownPromise) {
+                void this.shutdown(this.toError(interruptError));
+            }
+        });
+    }
+    getOrCreateTurnStartReconciliation(threadId) {
+        const existing = this.turnStartReconciliations.get(threadId);
+        if (existing) {
+            return existing;
+        }
+        let resolveReconciliation;
+        const promise = new Promise((resolvePromise) => {
+            resolveReconciliation = resolvePromise;
+        });
+        const reconciliation = {
+            promise,
+            resolve: () => resolveReconciliation?.(),
+        };
+        this.turnStartReconciliations.set(threadId, reconciliation);
+        return reconciliation;
+    }
+    completeTurnStartReconciliation(threadId, reconciliation) {
+        if (this.turnStartReconciliations.get(threadId) !== reconciliation) {
+            return;
+        }
+        if (reconciliation.recoveryTimer) {
+            clearTimeout(reconciliation.recoveryTimer);
+            reconciliation.recoveryTimer = undefined;
+        }
+        this.turnStartReconciliations.delete(threadId);
+        reconciliation.resolve();
+    }
+    async reconcileAcknowledgedTurn(threadId, turnId, requestTimeout) {
+        const reconciliation = this.turnStartReconciliations.get(threadId);
+        if (!reconciliation) {
+            return;
+        }
+        try {
+            await this.request('turn/interrupt', { threadId, turnId }, requestTimeout);
+            this.completeTurnStartReconciliation(threadId, reconciliation);
+        }
+        catch (error) {
+            await this.shutdown(this.toError(error));
+            this.completeTurnStartReconciliation(threadId, reconciliation);
+        }
+    }
+    handleLateTurnStartResponse(id, late, message) {
+        this.lateTurnStarts.delete(id);
+        if (late.reconciliation.recoveryTimer) {
+            clearTimeout(late.reconciliation.recoveryTimer);
+            late.reconciliation.recoveryTimer = undefined;
+        }
+        if (message.error !== undefined) {
+            this.completeTurnStartReconciliation(late.threadId, late.reconciliation);
+            return;
+        }
+        try {
+            const turn = validateTurn(object(message.result)?.turn, 'late turn/start turn');
+            if (typeof turn?.id !== 'string' || !turn.id) {
+                throw new Error('Codex app-server late turn/start returned no turn id');
+            }
+            void this.reconcileAcknowledgedTurn(late.threadId, turn.id, late.requestTimeout);
+        }
+        catch (error) {
+            void this.shutdown(this.toError(error)).finally(() => {
+                this.completeTurnStartReconciliation(late.threadId, late.reconciliation);
+            });
+        }
+    }
+    clearTurnCallbacks(turn) {
+        turn.queuedNotifications.length = 0;
+        turn.queuedToolRequests.length = 0;
+        turn.toolCallResults.clear();
+        turn.stoppingCallIds.clear();
+        turn.hostToolBridge = undefined;
+        turn.onDelta = undefined;
+    }
+    failAll(error) {
+        const safe = this.toError(error);
+        // Pending child tool calls abort exactly like a parent turn's.
+        for (const child of this.subagents.values()) {
+            child.abortController.abort(safe);
+        }
+        for (const threadId of [...this.turns.keys()]) {
+            this.failTurn(threadId, safe);
+        }
+        for (const [id, pending] of this.pending) {
+            clearTimeout(pending.timer);
+            this.pending.delete(id);
+            pending.reject(safe);
+        }
+    }
+    failProcess(child, error) {
+        if (child !== this.child) {
+            return;
+        }
+        const suffix = this.stderrTail ? `: ${this.stderrTail}` : '';
+        this.failAll(new Error(this.redact(`${error.message}${suffix}`)));
+        this.detach(child);
+    }
+    async restart() {
+        await this.shutdown(new Error('Codex app-server restarting after auth refresh'));
+        this.sessions.clear();
+    }
+    async shutdown(reason) {
+        if (this.shutdownPromise) {
+            return this.shutdownPromise;
+        }
+        const operation = this.performShutdown(reason);
+        this.shutdownPromise = operation;
+        try {
+            await operation;
+        }
+        finally {
+            if (this.shutdownPromise === operation) {
+                this.shutdownPromise = undefined;
+            }
+        }
+    }
+    async performShutdown(reason) {
+        const child = this.child;
+        if (!child) {
+            return;
+        }
+        this.failAll(reason);
+        await new Promise((resolveStop) => {
+            let settled = false;
+            const finish = () => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                if (this.killTimer) {
+                    clearTimeout(this.killTimer);
+                    this.killTimer = undefined;
+                }
+                if (this.finalKillTimer) {
+                    clearTimeout(this.finalKillTimer);
+                    this.finalKillTimer = undefined;
+                }
+                this.detach(child);
+                resolveStop();
+            };
+            child.once('exit', finish);
+            child.kill('SIGTERM');
+            this.killTimer = setTimeout(() => {
+                if (child.exitCode === null && child.signalCode === null) {
+                    child.kill('SIGKILL');
+                }
+                this.killTimer = undefined;
+                this.finalKillTimer = setTimeout(finish, STOP_GRACE_MS);
+                this.finalKillTimer.unref();
+            }, STOP_GRACE_MS);
+            this.killTimer.unref();
+            if (child.exitCode !== null || child.signalCode !== null) {
+                finish();
+            }
+        });
+    }
+    detach(child) {
+        if (this.child !== child) {
+            return;
+        }
+        this.stdout?.close();
+        this.stderr?.close();
+        child.removeAllListeners();
+        child.stdin.removeAllListeners();
+        child.stdout.removeAllListeners();
+        child.stderr.removeAllListeners();
+        this.stdout = undefined;
+        this.stderr = undefined;
+        this.child = undefined;
+        this.sessions.clear();
+        // The connection is gone, so every child is gone with it: say so once per child and
+        // release its authority instead of dropping the registry silently.
+        this.terminateSubagents(new Error('Codex app-server connection closed'));
+        this.threadContexts.clear();
+        this.lateTurnStarts.clear();
+        for (const [threadId, reconciliation] of this.turnStartReconciliations) {
+            this.completeTurnStartReconciliation(threadId, reconciliation);
+        }
+    }
+}
+exports.CodexAppServerProcess = CodexAppServerProcess;
+//# sourceMappingURL=codex-app-server-process.js.map