clinkx 0.3.0 → 1.1.0

package/dist/codex/app-server-registry.js

@@ -0,0 +1,1493 @@
+import { ExecutionError, InvalidParamsError } from "../errors.js";
+import { Semaphore } from "../concurrency.js";
+import { logger } from "../logger.js";
+import { CodexAppServerClient as RealCodexAppServerClient, sandboxPolicyFromMode, } from "./app-server-client.js";
+import { CODEX_EVENT_AGENT_MESSAGE_DELTA, CODEX_EVENT_ITEM_COMPLETED, CODEX_EVENT_ITEM_PLAN_DELTA, CODEX_EVENT_ITEM_STARTED, CODEX_EVENT_THREAD_TOKEN_USAGE_UPDATED, CODEX_EVENT_TURN_COMPLETED, CODEX_EVENT_TURN_DIFF_UPDATED, CODEX_EVENT_TURN_PLAN_UPDATED, CODEX_EVENT_TURN_STARTED, CODEX_REQUEST_COMMAND_EXECUTION_APPROVAL, CODEX_REQUEST_FILE_CHANGE_APPROVAL, CODEX_REQUEST_PERMISSIONS_APPROVAL, } from "./protocol.js";
+import { SessionRecord, } from "./session.js";
+import { buildObservedInvocationV1 } from "../../clinkx-workflows/dist/dashboard/invocation-contract.js";
+/** Typed sentinel for a withBudget timeout so callers can gate on the type,
+ *  not a fragile message substring (review fix). */
+class BudgetExceededError extends ExecutionError {
+    constructor(message = "app-server RPC budget exceeded") {
+        super(message);
+        this.name = "BudgetExceededError";
+    }
+}
+const DEFAULTS = {
+    maxActiveTurns: 5,
+    maxRetainedSessions: 20,
+    sessionTtlSeconds: 1800,
+    eventBuffer: 500,
+    turnTimeoutSeconds: 600,
+    approvalTimeoutSeconds: 120,
+    maxAgentDepth: 2,
+    maxResponseChars: 20_000,
+    maxEventTextChars: 2_000,
+    interruptBudgetSeconds: 10,
+    terminalWaitBudgetSeconds: 10,
+    startBudgetSeconds: 60,
+};
+function safeParseInt(val, fallback) {
+    if (val == null || val === "")
+        return fallback;
+    const n = Number(val);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+// Allow 0 (disables a timeout) but reject negatives / non-numbers.
+function safeParseNonNegInt(val, fallback) {
+    if (val == null || val === "")
+        return fallback;
+    const n = Number(val);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+let appServerActivityObserver;
+let appServerAdmissionClosed = false;
+/** Internal root-entrypoint activity sink; library callers leave it unset. */
+export function setAppServerActivityObserver(observer) {
+    appServerActivityObserver = observer;
+}
+/**
+ * Synchronously close process-wide app-server admission before root cleanup
+ * starts. This also latches the currently live registry, if any; the global
+ * bit is retained when no registry exists so a later get cannot create one
+ * during shutdown.
+ */
+export function latchAppServerAdmissionForShutdown(reason = "shutdown") {
+    appServerAdmissionClosed = true;
+    appServerRegistrySingleton?.beginShutdown(reason);
+}
+function notifyAppServerActivity() {
+    try {
+        appServerActivityObserver?.();
+    }
+    catch (error) {
+        logger.warn({ err: error instanceof Error ? error.message : String(error) }, "app-server activity observer failed");
+    }
+}
+function createDeferred() {
+    let resolve;
+    const promise = new Promise((res) => {
+        resolve = res;
+    });
+    return { promise, resolve };
+}
+function extractThreadId(result) {
+    // The result schemas are .passthrough() (additive vendor fields), whose index
+    // signature defeats union narrowing — read the id fields via a typed view.
+    const r = result;
+    if (typeof r.thread?.id === "string")
+        return r.thread.id;
+    if (typeof r.threadId === "string")
+        return r.threadId;
+    throw new ExecutionError("Codex app-server returned a thread result without a thread id.");
+}
+function extractTurnId(result) {
+    const r = result;
+    if (typeof r.turn?.id === "string")
+        return r.turn.id;
+    if (typeof r.turnId === "string")
+        return r.turnId;
+    throw new ExecutionError("Codex app-server returned a turn result without a turn id.");
+}
+function approvalTypeFromMethod(method) {
+    switch (method) {
+        case CODEX_REQUEST_COMMAND_EXECUTION_APPROVAL:
+            return "commandExecution";
+        case CODEX_REQUEST_FILE_CHANGE_APPROVAL:
+            return "fileChange";
+        case CODEX_REQUEST_PERMISSIONS_APPROVAL:
+            return "permissions";
+        default:
+            return null;
+    }
+}
+function registryHealthFromClient(activeLeases, retainedSessionCount, clientHealth) {
+    return {
+        activeLeases,
+        retainedSessionCount,
+        appServerProtocol: {
+            acceptedVersion: clientHealth.acceptedVersion,
+            minVersion: clientHealth.minVersion,
+            maxVersion: clientHealth.maxVersion,
+            strictVersion: clientHealth.strictVersion,
+        },
+        childRespawnCount: clientHealth.childRespawnCount,
+        recentFailures: {
+            count: clientHealth.recentFailures.length,
+            samples: [...clientHealth.recentFailures],
+        },
+    };
+}
+function pendingApprovalFromEvent(event, type, requestedAtMs) {
+    const base = {
+        id: event.id,
+        type,
+        requestedAtMs,
+    };
+    switch (event.method) {
+        case CODEX_REQUEST_COMMAND_EXECUTION_APPROVAL: {
+            const params = event.params;
+            return {
+                ...base,
+                reason: params.reason ?? null,
+                ...(hasOwn(params, "command") ? { command: params.command ?? null } : {}),
+                ...(hasOwn(params, "cwd") ? { cwd: params.cwd ?? null } : {}),
+                ...(hasOwn(params, "networkApprovalContext")
+                    ? { networkApprovalContext: params.networkApprovalContext ?? null }
+                    : {}),
+            };
+        }
+        case CODEX_REQUEST_FILE_CHANGE_APPROVAL: {
+            const params = event.params;
+            return {
+                ...base,
+                reason: params.reason ?? null,
+                ...(hasOwn(params, "grantRoot")
+                    ? { grantRoot: params.grantRoot ?? null }
+                    : {}),
+            };
+        }
+        case CODEX_REQUEST_PERMISSIONS_APPROVAL: {
+            const params = event.params;
+            return {
+                ...base,
+                reason: params.reason ?? null,
+                cwd: params.cwd,
+            };
+        }
+        default:
+            return {
+                ...base,
+                reason: null,
+            };
+    }
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function stringField(value, key) {
+    return typeof value[key] === "string" ? value[key] : null;
+}
+function joinedStringField(value, key) {
+    const field = value[key];
+    if (typeof field === "string")
+        return field;
+    if (!Array.isArray(field))
+        return null;
+    const strings = field.filter((entry) => typeof entry === "string");
+    return strings.length > 0 ? strings.join("\n") : null;
+}
+function turnInputText(input) {
+    const parts = [];
+    for (const entry of input) {
+        const item = asRecord(entry);
+        if (item != null &&
+            item["type"] === "text" &&
+            typeof item["text"] === "string") {
+            parts.push(item["text"]);
+        }
+    }
+    return parts.length > 0 ? parts.join("\n") : null;
+}
+function toolIdentity(item) {
+    const type = stringField(item, "type");
+    switch (type) {
+        case "commandExecution":
+            return {
+                toolName: type,
+                summary: stringField(item, "command") ?? type,
+            };
+        case "fileChange": {
+            const count = Array.isArray(item["changes"]) ? item["changes"].length : 0;
+            return {
+                toolName: type,
+                summary: count > 0
+                    ? `${count} file change${count === 1 ? "" : "s"}`
+                    : type,
+            };
+        }
+        case "mcpToolCall": {
+            const server = stringField(item, "server");
+            const tool = stringField(item, "tool");
+            const toolName = server != null && tool != null ? `${server}/${tool}` : tool ?? type;
+            return { toolName, summary: toolName };
+        }
+        case "dynamicToolCall": {
+            const namespace = stringField(item, "namespace");
+            const tool = stringField(item, "tool");
+            const toolName = namespace != null && tool != null
+                ? `${namespace}/${tool}`
+                : tool ?? type;
+            return { toolName, summary: toolName };
+        }
+        case "collabAgentToolCall": {
+            const toolName = stringField(item, "tool") ?? type;
+            return { toolName, summary: stringField(item, "prompt") ?? toolName };
+        }
+        case "webSearch":
+            return { toolName: type, summary: stringField(item, "query") ?? type };
+        case "imageView":
+            return { toolName: type, summary: stringField(item, "path") ?? type };
+        default:
+            return null;
+    }
+}
+function toolOutcome(item) {
+    const status = stringField(item, "status");
+    if (status === "failed")
+        return "failed";
+    if (status === "declined" ||
+        status === "cancelled" ||
+        status === "interrupted") {
+        return "cancelled";
+    }
+    const exitCode = item["exitCode"];
+    if (typeof exitCode === "number" && exitCode !== 0)
+        return "failed";
+    return "succeeded";
+}
+function itemObservation(itemValue, phase) {
+    const item = asRecord(itemValue);
+    if (item == null)
+        return null;
+    const itemId = stringField(item, "id");
+    const type = stringField(item, "type");
+    if (itemId == null || type == null)
+        return null;
+    if (phase === "completed" && type === "agentMessage") {
+        const content = stringField(item, "text");
+        if (content == null)
+            return null;
+        return {
+            kind: "assistant",
+            itemId,
+            content,
+            phase: stringField(item, "phase"),
+        };
+    }
+    if (phase === "completed" && type === "reasoning") {
+        const summary = joinedStringField(item, "summary");
+        if (summary == null)
+            return null;
+        return {
+            kind: "reasoning",
+            itemId,
+            summary,
+            content: joinedStringField(item, "content"),
+        };
+    }
+    const tool = toolIdentity(item);
+    if (tool == null)
+        return null;
+    if (phase === "started") {
+        return {
+            kind: "tool_call",
+            toolName: tool.toolName,
+            callId: itemId,
+            summary: tool.summary,
+        };
+    }
+    const resultSummary = stringField(item, "aggregatedOutput") ??
+        stringField(asRecord(item["error"]) ?? {}, "message") ??
+        tool.summary;
+    return {
+        kind: "tool_result",
+        toolName: tool.toolName,
+        callId: itemId,
+        outcome: toolOutcome(item),
+        summary: resultSummary,
+    };
+}
+function approvalAction(approval) {
+    return (approval.command ?? approval.grantRoot ?? approval.reason ?? approval.type);
+}
+function optionalTokenCount(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function mapTurnStatus(status) {
+    switch (status) {
+        case "completed":
+            return "completed";
+        case "interrupted":
+        case "cancelled":
+            return "interrupted";
+        case "failed":
+            return "failed";
+        default:
+            return "failed";
+    }
+}
+export function resolveRegistryConfig(override) {
+    const env = process.env;
+    const base = {
+        maxActiveTurns: safeParseInt(env["CLINKX_MAX_ACTIVE_TURNS"], DEFAULTS.maxActiveTurns),
+        maxRetainedSessions: safeParseInt(env["CLINKX_MAX_RETAINED_SESSIONS"], DEFAULTS.maxRetainedSessions),
+        sessionTtlMs: safeParseNonNegInt(env["CLINKX_SESSION_TTL_SECONDS"], DEFAULTS.sessionTtlSeconds) * 1000,
+        eventBuffer: safeParseInt(env["CLINKX_SESSION_EVENT_BUFFER"], DEFAULTS.eventBuffer),
+        turnTimeoutMs: safeParseNonNegInt(env["CLINKX_TURN_TIMEOUT_SECONDS"], DEFAULTS.turnTimeoutSeconds) * 1000,
+        approvalTimeoutMs: safeParseNonNegInt(env["CLINKX_APPROVAL_TIMEOUT_SECONDS"], DEFAULTS.approvalTimeoutSeconds) * 1000,
+        maxAgentDepth: safeParseInt(env["CLINKX_MAX_AGENT_DEPTH"], DEFAULTS.maxAgentDepth),
+        currentDepth: safeParseNonNegInt(env["CLINKX_AGENT_DEPTH"], 0),
+        maxResponseChars: safeParseInt(env["CLINKX_MAX_RESPONSE_CHARS"], DEFAULTS.maxResponseChars),
+        maxEventTextChars: safeParseInt(env["CLINKX_SESSION_EVENT_TEXT_MAX"], DEFAULTS.maxEventTextChars),
+        interruptBudgetMs: safeParseInt(env["CLINKX_TURN_INTERRUPT_BUDGET_SECONDS"], DEFAULTS.interruptBudgetSeconds) * 1000,
+        terminalWaitBudgetMs: safeParseInt(env["CLINKX_TERMINAL_WAIT_BUDGET_SECONDS"], DEFAULTS.terminalWaitBudgetSeconds) * 1000,
+        startBudgetMs: safeParseInt(env["CLINKX_APP_SERVER_START_BUDGET_SECONDS"], DEFAULTS.startBudgetSeconds) * 1000,
+    };
+    return { ...base, ...override };
+}
+/**
+ * Env marker to ADD to the spawned app-server child so the recursion guard
+ * survives the env sanitizer (2-6). Single source for both the registry's
+ * {@link AppServerRegistry.childEnvMarker} and the default-singleton spawn.
+ */
+function childEnvMarkerFor(currentDepth) {
+    return { CLINKX_AGENT_DEPTH: String(currentDepth + 1) };
+}
+const defaultSetTimer = (cb, ms) => {
+    const handle = setTimeout(cb, ms);
+    // Don't keep the STDIO server alive on dangling turn timers.
+    handle.unref?.();
+    return handle;
+};
+const defaultClearTimer = (handle) => {
+    clearTimeout(handle);
+};
+const DEFAULT_APP_SERVER_SPAWN_CONFIG = {
+    command: "codex",
+    args: ["app-server"],
+};
+/**
+ * Registry & lifecycle for long-lived Codex app-server sessions.
+ *
+ * CORE responsibilities (Phase 2): the active-turn lease (the SOLE concurrency
+ * gate — the request {@link Semaphore} is never acquired here), session record
+ * accounting, the bounded event ring, retained-cap + TTL reaping, turn and
+ * pending-approval timeouts with the shared interrupt → terminal-wait →
+ * process-group-kill + respawn escalation path, crash semantics, the recursion
+ * depth guard, and a standalone {@link shutdown}.
+ *
+ * Respawn ownership belongs to the client: the registry only calls
+ * {@link CodexAppServerClient.ensureReady} and the client's guarded
+ * {@link CodexAppServerClient.killProcessGroup}.
+ */
+export class AppServerRegistry {
+    client;
+    observer;
+    clock;
+    setTimer;
+    clearTimer;
+    config;
+    lease;
+    sessions = new Map();
+    /**
+     * Thread ids with an in-flight resume reservation. Held synchronously across
+     * startSession's awaited RPCs so two concurrent resumes of the same thread
+     * cannot both pass the in-flight check before either becomes visible as a
+     * running session (review fix A — closes the deferred-insertion race).
+     */
+    reservedResumeThreads = new Set();
+    unsubscribeProcessDied;
+    shuttingDown = false;
+    shutdownReason = "shutdown";
+    constructor(deps) {
+        this.client = deps.client;
+        this.observer = deps.observer;
+        this.clock = deps.clock ?? { now: () => Date.now() };
+        this.setTimer = deps.setTimer ?? defaultSetTimer;
+        this.clearTimer = deps.clearTimer ?? defaultClearTimer;
+        this.config = resolveRegistryConfig(deps.config);
+        this.lease = new Semaphore(this.config.maxActiveTurns);
+        this.unsubscribeProcessDied = this.client.onProcessDied((event) => this.handleProcessDied(event));
+    }
+    now() {
+        return this.clock.now();
+    }
+    get activeLeases() {
+        return this.lease.active;
+    }
+    get sessionCount() {
+        return this.sessions.size;
+    }
+    /**
+     * Synchronously stop new work on this registry. The asynchronous
+     * {@link shutdown} drain remains separate so callers can latch admission
+     * before any cleanup await begins.
+     */
+    beginShutdown(reason = "shutdown") {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        this.shutdownReason = reason;
+        this.client.beginShutdown(reason);
+    }
+    assertAdmissionOpen(action = "start an app-server session") {
+        if (this.shuttingDown || appServerAdmissionClosed) {
+            throw new InvalidParamsError(`Cannot ${action} after shutdown has started (${this.shutdownReason}).`);
+        }
+    }
+    health() {
+        return registryHealthFromClient(this.activeLeases, this.sessionCount, this.client.getHealth());
+    }
+    /**
+     * Env marker to ADD to the spawned app-server child so the recursion guard
+     * survives the env sanitizer (2-6). The client owns actual env injection
+     * into the AppServerSpawnConfig; the registry only supplies the marker.
+     */
+    childEnvMarker() {
+        return childEnvMarkerFor(this.config.currentDepth);
+    }
+    require(sessionId) {
+        const runtime = this.sessions.get(sessionId);
+        if (runtime == null) {
+            throw new InvalidParamsError(`Unknown session: ${sessionId}`);
+        }
+        return runtime;
+    }
+    /**
+     * Start a new (or resumed) session and its first turn. Returns once the turn
+     * is RUNNING (lease held); the turn proceeds asynchronously and the lease is
+     * released only on provable terminality — held even if the MCP call detaches
+     * (2-3). Use {@link waitForTurn} to await completion without consuming a lease.
+     */
+    async startSession(opts) {
+        this.assertAdmissionOpen();
+        // Opportunistic reap before admitting new work.
+        this.reapIdle();
+        // Recursion guard (2-6): refuse beyond the depth ceiling.
+        if (this.config.currentDepth >= this.config.maxAgentDepth) {
+            throw new ExecutionError(`Agent recursion depth limit reached (${this.config.currentDepth}/${this.config.maxAgentDepth}). ` +
+                "Refusing to start a nested Codex app-server session.");
+        }
+        if (this.sessions.has(opts.sessionId)) {
+            throw new InvalidParamsError(`Session already exists: ${opts.sessionId}`);
+        }
+        // Resume reservation (review fix A): claim the resumed thread SYNCHRONOUSLY
+        // — before any await — so two concurrent resumes of the same thread cannot
+        // both pass this check during startSession's awaited RPC sequence. The
+        // authoritative guard lives here, not in the caller's preflight.
+        const resumeThreadId = opts.resumeThreadId;
+        if (resumeThreadId != null) {
+            const heldByRunning = [...this.sessions.values()].some((rt) => rt.record.threadId === resumeThreadId && !rt.record.isIdle());
+            if (this.reservedResumeThreads.has(resumeThreadId) || heldByRunning) {
+                throw new InvalidParamsError(`Cannot resume thread ${resumeThreadId}: a turn is already in flight on it. ` +
+                    "Wait for that turn to complete before resuming.");
+            }
+            this.reservedResumeThreads.add(resumeThreadId);
+        }
+        let leaseHeld = false;
+        let runtime;
+        try {
+            // Active-turn lease: the SOLE gate, fail-fast when full (2-3). Acquired
+            // INSIDE the try — and after the synchronous reservation-add with no await
+            // between — so a pool-full throw here is caught below and releases the
+            // reservation (otherwise a saturated resume would leak it permanently).
+            this.lease.acquire();
+            leaseHeld = true;
+            // A silent child must not hang startSession forever holding the lease
+            // (review fix 3): bound the whole pre-turn RPC sequence with a budget.
+            const established = await this.withBudget((async () => {
+                await this.client.ensureReady();
+                this.assertAdmissionOpen();
+                let threadId;
+                if (opts.resumeThreadId != null) {
+                    const resumed = await this.client.threadResume({
+                        threadId: opts.resumeThreadId,
+                    });
+                    this.assertAdmissionOpen();
+                    threadId = extractThreadId(resumed);
+                }
+                else {
+                    const started = await this.client.threadStart(this.buildThreadStartParams(opts));
+                    this.assertAdmissionOpen();
+                    threadId = extractThreadId(started);
+                    try {
+                        const raw = started;
+                        const model = typeof raw.model === "string" && raw.model.length > 0 ? raw.model : undefined;
+                        const effort = typeof raw.reasoningEffort === "string" && raw.reasoningEffort.length > 0 ? raw.reasoningEffort : undefined;
+                        const observed = buildObservedInvocationV1("codex_app_server_thread_start", {
+                            ...(model === undefined ? {} : { model }),
+                            ...(effort === undefined ? {} : { effort }),
+                        });
+                        if (observed !== undefined && opts.activityObservation?.observe != null) {
+                            void opts.activityObservation.observe(observed).catch((err) => {
+                                logger.debug({ err: err instanceof Error ? err.message : String(err) }, "app-server observed invocation persistence failed open");
+                            });
+                        }
+                    }
+                    catch (err) {
+                        logger.debug({ err: err instanceof Error ? err.message : String(err) }, "app-server observed invocation failed open");
+                    }
+                }
+                const origin = this.config.currentDepth === 0 ? "root" : "nested";
+                const record = new SessionRecord({
+                    sessionId: opts.sessionId,
+                    threadId,
+                    sandbox: opts.sandbox,
+                    approval: opts.approval,
+                    origin,
+                    depth: this.config.currentDepth,
+                    createdAtMs: this.now(),
+                    eventBuffer: this.config.eventBuffer,
+                    maxEventTextChars: this.config.maxEventTextChars,
+                    maxFinalTextChars: this.config.maxResponseChars,
+                    cwd: opts.cwd,
+                    model: opts.model,
+                });
+                const rt = {
+                    record,
+                    hasLease: true,
+                    finalized: false,
+                    unsubscribe: undefined,
+                    turnTimer: undefined,
+                    approvalTimer: undefined,
+                    terminal: createDeferred(),
+                    attention: createDeferred(),
+                    turnTimeoutMs: opts.turnTimeoutMs,
+                    activityObservation: opts.activityObservation,
+                    sessionObserver: opts.sessionObserver,
+                    observerTail: Promise.resolve(),
+                    nextObservationSequence: 0,
+                };
+                runtime = rt;
+                this.sessions.set(opts.sessionId, rt);
+                this.observeUserInput(rt, opts.input, this.now());
+                // Subscribe before turn/start so early deltas are not lost.
+                rt.unsubscribe = this.client.on({ threadId }, (event) => {
+                    this.handleEvent(rt, event);
+                });
+                const turnResult = await this.client.turnStart(this.buildTurnStartParams(threadId, opts));
+                this.assertAdmissionOpen();
+                return { runtime: rt, turnId: extractTurnId(turnResult) };
+            })(), this.config.startBudgetMs);
+            const { runtime: rt, turnId } = established;
+            this.bindSessionObserverTurn(rt, turnId);
+            // turnStart flushes buffered provisional events before returning; a fast
+            // turn can fully finalize during that flush. Only establish the running
+            // turn if it has not already gone terminal (review fix 2).
+            if (!rt.finalized && rt.record.activeTurnId == null) {
+                rt.record.beginTurn(turnId, this.now());
+                this.scheduleTurnTimeout(rt);
+                this.observeRunning(rt);
+                this.observeLifecycle(rt, "running");
+                // Lease intentionally retained — the turn is now running.
+                leaseHeld = false;
+            }
+            else {
+                // Already finalized via turn/completed during the flush: the lease was
+                // released by finalizeTurn. Do not release it again.
+                leaseHeld = false;
+            }
+            // The session is now in the sessions map (running, or terminal if it
+            // finished during the flush). Subsequent resumes are gated by the
+            // in-flight session check, so the synchronous reservation can be released.
+            if (resumeThreadId != null) {
+                this.reservedResumeThreads.delete(resumeThreadId);
+            }
+            return rt.record.snapshot();
+        }
+        catch (err) {
+            // Release the resume reservation on every failure path so it never leaks.
+            if (resumeThreadId != null) {
+                this.reservedResumeThreads.delete(resumeThreadId);
+            }
+            // Failed before the turn was established: tear down, unregister, and
+            // release the lease (the session never reached a running turn). Guard the
+            // rare race where finalizeTurn already ran during the turnStart
+            // provisional flush (a fast turn went terminal) and the IIFE then threw
+            // afterwards (e.g. extractTurnId on a malformed turn result): that path
+            // already completed the turn and released the lease via finalizeTurn, so
+            // neither relabel the completed turn as "failed" nor double-release the
+            // lease. Once the runtime exists, runtime.hasLease/finalized are the
+            // source of truth (finalizeTurn flips them together); the local leaseHeld
+            // only covers a throw before the runtime was created.
+            if (runtime != null) {
+                if (!runtime.finalized) {
+                    runtime.unsubscribe?.();
+                    this.clearTimers(runtime);
+                    runtime.finalized = true;
+                    const failureReason = err instanceof Error ? err.message : String(err);
+                    const now = this.now();
+                    runtime.record.completeTurn("failed", { failureReason }, now);
+                    this.observeTerminal(runtime, "failed");
+                    this.observeError(runtime, failureReason, now, null);
+                    this.observeLifecycle(runtime, "failed", now, null);
+                    runtime.terminal.resolve();
+                    this.sessions.delete(opts.sessionId);
+                    if (runtime.hasLease) {
+                        this.lease.release();
+                        runtime.hasLease = false;
+                        notifyAppServerActivity();
+                    }
+                }
+            }
+            else if (leaseHeld) {
+                // Acquired the lease but threw before the runtime existed
+                // (ensureReady/threadResume/threadStart, or a pre-runtime budget
+                // timeout): release the lease taken at the top of the try.
+                this.lease.release();
+                leaseHeld = false;
+                notifyAppServerActivity();
+            }
+            // On a startup-budget timeout the child is presumed silent/hung: recycle
+            // it so the leaked pending request + provisional buffer in the client get
+            // cleared by handleChildClose (review fix 3).
+            if (err instanceof BudgetExceededError) {
+                await this.client
+                    .killProcessGroup("startSession budget exceeded")
+                    .catch(() => { });
+                // The kill terminated the SHARED child, so every OTHER running session
+                // is dead too. The client suppresses onProcessDied for intentional
+                // kills, so fan out here or their leases leak (review fix). The
+                // triggering session was already torn down + removed above.
+                this.finalizeCoActiveAfterSharedKill(undefined, "startSession budget exceeded");
+            }
+            throw err;
+        }
+    }
+    buildThreadStartParams(opts) {
+        const params = { sandbox: opts.sandbox };
+        if (opts.model != null)
+            params.model = opts.model;
+        if (opts.cwd != null)
+            params.cwd = opts.cwd;
+        if (opts.approvalPolicy != null)
+            params.approvalPolicy = opts.approvalPolicy;
+        return params;
+    }
+    buildTurnStartParams(threadId, opts) {
+        const params = { threadId, input: opts.input };
+        if (opts.cwd != null)
+            params.cwd = opts.cwd;
+        if (opts.model != null)
+            params.model = opts.model;
+        if (opts.approvalPolicy != null)
+            params.approvalPolicy = opts.approvalPolicy;
+        // turn/start requires the TAGGED-OBJECT sandboxPolicy, never the string.
+        // When the caller omits it, derive from the thread's sandbox mode so the
+        // client does not silently downgrade to read-only (review fix 8).
+        params.sandboxPolicy =
+            opts.sandboxPolicy ??
+                sandboxPolicyFromMode(opts.sandbox, opts.cwd != null ? { writableRoots: [opts.cwd] } : undefined);
+        if (opts.outputSchema != null)
+            params.outputSchema = opts.outputSchema;
+        return params;
+    }
+    /** Snapshot without consuming an active-turn lease (2-4). */
+    poll(sessionId) {
+        return this.require(sessionId).record.snapshot();
+    }
+    list(filter) {
+        const all = [...this.sessions.values()].map((rt) => rt.record.snapshot());
+        if (filter?.status != null) {
+            return all.filter((s) => s.status === filter.status);
+        }
+        return all;
+    }
+    /** Bounded event-log read with a monotonic cursor; never consumes a lease (2-4,2-5). */
+    getLog(sessionId, cursor, limit) {
+        return this.require(sessionId).record.events.read(cursor, limit);
+    }
+    /**
+     * Discovery passthrough for `model/list`. Spawns/initializes the app-server
+     * child if needed (via the client) but never starts a session or consumes a
+     * lease. Bounded by the start budget like other pre-turn RPCs.
+     */
+    async listModels(params) {
+        this.assertAdmissionOpen("list app-server models");
+        return this.withBudget(this.client.modelList(params), this.config.startBudgetMs, "model/list RPC budget exceeded");
+    }
+    /**
+     * Await the active turn's terminality WITHOUT consuming a lease. An optional
+     * `timeoutMs` bounds the wait only — the underlying turn keeps running and
+     * retains its lease on wait-timeout.
+     */
+    async waitForTurn(sessionId, opts) {
+        const runtime = this.require(sessionId);
+        if (runtime.finalized || runtime.record.status !== "running") {
+            return runtime.record.snapshot();
+        }
+        if (runtime.record.pendingApprovals.size > 0) {
+            return runtime.record.snapshot();
+        }
+        await this.raceTurnWait(runtime, opts?.timeoutMs, opts?.signal);
+        return runtime.record.snapshot();
+    }
+    /** Reply to a pending approval. The turn continues; the lease is NOT released. */
+    async respondApproval(sessionId, approvalId, decision) {
+        if (decision === "accept" || decision === "acceptForSession") {
+            this.assertAdmissionOpen("accept an app-server approval");
+        }
+        const runtime = this.require(sessionId);
+        const pending = runtime.record.getPendingApproval(approvalId);
+        if (pending == null) {
+            throw new InvalidParamsError(`stale or unknown approval: ${String(approvalId)}`);
+        }
+        this.clearApprovalTimer(runtime);
+        try {
+            // Defensive: permissions approvals are auto-handled on arrival and never
+            // surfaced, so this path normally only sees command/file. If a permissions
+            // pending somehow reaches here, use the empty-grant shape (not {decision}).
+            await this.withBudget(pending.type === "permissions"
+                ? this.client.respondPermissionsApproval(approvalId)
+                : this.client.respondApproval({ id: approvalId, decision }), this.config.interruptBudgetMs);
+        }
+        catch (err) {
+            // Restore the auto-decline/escalation backstop the timer provides before
+            // surfacing the failure (review fix 4).
+            if (runtime.record.pendingApprovals.size > 0) {
+                this.scheduleApprovalTimeout(runtime);
+            }
+            throw err;
+        }
+        const now = this.now();
+        runtime.record.clearPendingApproval(approvalId, now);
+        this.observeApprovalResolution(runtime, approvalId, decision, now);
+        if (runtime.record.pendingApprovals.size > 0) {
+            this.scheduleApprovalTimeout(runtime);
+        }
+        return runtime.record.snapshot();
+    }
+    /**
+     * Steer the currently active turn. This never starts a new turn and never
+     * acquires a new lease; it targets the active turn id captured in the record.
+     */
+    async steer(sessionId, input) {
+        this.assertAdmissionOpen("steer an app-server turn");
+        const runtime = this.require(sessionId);
+        if (runtime.finalized || runtime.record.status !== "running") {
+            throw new InvalidParamsError(`No active turn for session: ${sessionId}`);
+        }
+        const turnId = runtime.record.activeTurnId;
+        if (turnId == null) {
+            throw new InvalidParamsError(`No active turn for session: ${sessionId}`);
+        }
+        await this.withBudget(this.client.turnSteer({
+            threadId: runtime.record.threadId,
+            expectedTurnId: turnId,
+            input,
+        }), this.config.interruptBudgetMs, "turnSteer RPC budget exceeded");
+        this.observeUserInput(runtime, input, this.now());
+        return runtime.record.snapshot();
+    }
+    /** Explicit cancel → interrupted snapshot (decision 4). */
+    async interrupt(sessionId) {
+        const runtime = this.require(sessionId);
+        if (runtime.finalized || runtime.record.status !== "running") {
+            return runtime.record.snapshot();
+        }
+        await this.terminateTurn(runtime, "interrupted", "explicit interrupt");
+        return runtime.record.snapshot();
+    }
+    /** Remove a session. Running sessions are skipped unless force:true is supplied. */
+    async cleanup(sessionId, opts = {}) {
+        const runtime = this.require(sessionId);
+        if (!runtime.finalized && runtime.record.status === "running") {
+            if (opts.force !== true) {
+                return { sessionId, cleanedUp: false, skippedActive: true };
+            }
+            await this.terminateTurn(runtime, "interrupted", "session cleanup");
+        }
+        this.evict(sessionId, runtime, "cleanup");
+        return { sessionId, cleanedUp: true, skippedActive: false };
+    }
+    /**
+     * Standalone shutdown: interrupt every active turn, then kill the app-server
+     * child by process group via the client's guarded kill.
+     */
+    async shutdown(reason = "shutdown") {
+        this.beginShutdown(reason);
+        const running = [...this.sessions.values()].filter((rt) => !rt.finalized && rt.record.status === "running");
+        for (const runtime of running) {
+            await this.terminateTurn(runtime, "interrupted", reason);
+        }
+        try {
+            await this.client.killProcessGroup(reason);
+        }
+        catch (err) {
+            logger.error({ err, reason }, "app-server-registry: killProcessGroup during shutdown failed");
+        }
+        for (const [id, runtime] of [...this.sessions]) {
+            this.clearTimers(runtime);
+            runtime.unsubscribe?.();
+            runtime.unsubscribe = undefined;
+            this.sessions.delete(id);
+        }
+        this.unsubscribeProcessDied();
+    }
+    /** TTL + retained-cap reaping of idle sessions (2-4). Running sessions are never reaped. */
+    reapIdle() {
+        const now = this.now();
+        if (this.config.sessionTtlMs > 0) {
+            for (const [id, runtime] of [...this.sessions]) {
+                if (runtime.record.status === "running")
+                    continue;
+                if (now - runtime.record.lastActivityAtMs >= this.config.sessionTtlMs) {
+                    this.evict(id, runtime, "ttl");
+                }
+            }
+        }
+        const idle = [...this.sessions.entries()].filter(([, rt]) => rt.record.status !== "running");
+        const overflow = idle.length - this.config.maxRetainedSessions;
+        if (overflow > 0) {
+            idle.sort((a, b) => a[1].record.lastActivityAtMs - b[1].record.lastActivityAtMs);
+            for (let i = 0; i < overflow; i++) {
+                const entry = idle[i];
+                if (entry == null)
+                    break;
+                this.evict(entry[0], entry[1], "retained-cap");
+            }
+        }
+    }
+    // --- internal lifecycle --------------------------------------------------
+    handleEvent(runtime, event) {
+        if (runtime.finalized)
+            return;
+        const now = this.now();
+        runtime.record.appendEvent(event, now);
+        switch (event.method) {
+            case CODEX_EVENT_TURN_STARTED: {
+                const turnId = event.params.turn.id;
+                if (runtime.record.activeTurnId == null) {
+                    runtime.record.beginTurn(turnId, now);
+                    this.scheduleTurnTimeout(runtime);
+                    this.observeRunning(runtime);
+                    this.observeLifecycle(runtime, "running", now);
+                }
+                break;
+            }
+            case CODEX_EVENT_AGENT_MESSAGE_DELTA: {
+                // Streaming assistant text. Accumulate into the bounded running preview
+                // so a poller can watch a turn mid-stream without a second get_log; the
+                // delta is also retained verbatim (capped) in the ring via appendEvent.
+                runtime.record.appendAssistantDelta(event.params.delta, event.params.turnId, now);
+                break;
+            }
+            case CODEX_EVENT_ITEM_STARTED: {
+                const observation = itemObservation(event.params.item, "started");
+                if (observation != null) {
+                    this.runSessionObservation(runtime, observation, now);
+                }
+                break;
+            }
+            case CODEX_EVENT_ITEM_COMPLETED: {
+                const item = event.params.item;
+                if (item.type === "agentMessage" && typeof item.text === "string") {
+                    // Cache the latest final-answer text; capped at assignment so any
+                    // terminal path exposes a bounded value (review fix 7).
+                    runtime.record.setFinalText(item.text);
+                }
+                const observation = itemObservation(event.params.item, "completed");
+                if (observation != null) {
+                    this.runSessionObservation(runtime, observation, now);
+                }
+                break;
+            }
+            case CODEX_EVENT_THREAD_TOKEN_USAGE_UPDATED: {
+                runtime.record.recordTokenUsage(event.params.tokenUsage, now);
+                const last = event.params.tokenUsage.last;
+                this.runSessionObservation(runtime, {
+                    kind: "usage",
+                    inputTokens: optionalTokenCount(last.inputTokens),
+                    cachedInputTokens: optionalTokenCount(last.cachedInputTokens),
+                    outputTokens: optionalTokenCount(last.outputTokens),
+                    reasoningTokens: optionalTokenCount(last.reasoningOutputTokens),
+                    incomplete: runtime.record.tokenUsage.incomplete,
+                }, now);
+                break;
+            }
+            case CODEX_EVENT_TURN_COMPLETED: {
+                const status = mapTurnStatus(event.params.turn.status);
+                // finalText already cached from item/completed (if any).
+                const finalText = runtime.record.finalText;
+                this.finalizeTurn(runtime, status, { finalText });
+                break;
+            }
+            case CODEX_EVENT_TURN_DIFF_UPDATED: {
+                runtime.record.setLatestDiff(event.params.diff, now);
+                break;
+            }
+            case CODEX_EVENT_TURN_PLAN_UPDATED: {
+                runtime.record.setLatestPlan(event.params.plan, event.params.explanation ?? null, now);
+                break;
+            }
+            case CODEX_EVENT_ITEM_PLAN_DELTA:
+                // Streaming plan text; no snapshot field — it is already retained in the
+                // event ring via appendEvent above (get_log surfaces it).
+                break;
+            case CODEX_REQUEST_PERMISSIONS_APPROVAL: {
+                // Permissions (sandbox-escalation) approvals are never surfaced: under
+                // the read-only / approval:never posture we auto-decline on arrival with
+                // a protocol-valid empty grant (grants nothing). Best-effort and bounded;
+                // a failure here cannot stall the turn beyond the wall-clock timeout.
+                const pending = pendingApprovalFromEvent(event, "permissions", now);
+                this.observeApprovalRequest(runtime, pending, now);
+                void this.autoDeclinePermissionsApproval(runtime, event.id);
+                break;
+            }
+            case CODEX_REQUEST_COMMAND_EXECUTION_APPROVAL:
+            case CODEX_REQUEST_FILE_CHANGE_APPROVAL: {
+                const type = approvalTypeFromMethod(event.method);
+                if (type == null)
+                    break;
+                const pending = pendingApprovalFromEvent(event, type, now);
+                runtime.record.setPendingApproval(pending, now);
+                this.notifyAttention(runtime);
+                this.scheduleApprovalTimeout(runtime);
+                this.observeApprovalRequest(runtime, pending, now);
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    /**
+     * Finalize a turn on PROVABLE terminality. Idempotent. Clears timers,
+     * unsubscribes, releases the lease, and resolves the terminal deferred.
+     */
+    finalizeTurn(runtime, status, opts) {
+        if (runtime.finalized)
+            return;
+        runtime.finalized = true;
+        this.clearTimers(runtime);
+        runtime.unsubscribe?.();
+        runtime.unsubscribe = undefined;
+        const turnId = runtime.record.activeTurnId ?? null;
+        const now = this.now();
+        runtime.record.completeTurn(status, opts, now);
+        this.observeTerminal(runtime, status);
+        if (status === "failed" || status === "timeout") {
+            this.observeError(runtime, runtime.record.failureReason ??
+                (status === "timeout"
+                    ? "Codex app-server turn timed out."
+                    : "Codex app-server turn failed."), now, turnId);
+        }
+        this.observeLifecycle(runtime, status, now, turnId);
+        if (runtime.hasLease) {
+            this.lease.release();
+            runtime.hasLease = false;
+            notifyAppServerActivity();
+        }
+        runtime.terminal.resolve();
+    }
+    runSessionObservation(runtime, semantic, atMs = this.now(), turnId = runtime.record.activeTurnId ?? null) {
+        const observer = runtime.sessionObserver ?? this.observer;
+        if (observer == null)
+            return;
+        // Capture sequence and identity synchronously at the semantic reduction
+        // point. The async continuation receives only this immutable snapshot.
+        const observation = {
+            ...semantic,
+            sequence: runtime.nextObservationSequence++,
+            sessionId: runtime.record.sessionId,
+            threadId: runtime.record.threadId,
+            turnId,
+            atMs,
+        };
+        const deliver = async () => {
+            try {
+                await observer(observation);
+            }
+            catch (err) {
+                logger.debug({
+                    err: err instanceof Error ? err.message : String(err),
+                    sessionId: observation.sessionId,
+                    observationKind: observation.kind,
+                    sequence: observation.sequence,
+                }, "app-server-registry: session observation failed open");
+            }
+        };
+        runtime.observerTail = runtime.observerTail.then(deliver, deliver);
+    }
+    bindSessionObserverTurn(runtime, turnId) {
+        const observer = runtime.sessionObserver ?? this.observer;
+        if (observer?.bindTurn == null)
+            return;
+        const binding = Object.freeze({
+            sessionId: runtime.record.sessionId,
+            threadId: runtime.record.threadId,
+            turnId,
+        });
+        const deliver = async () => {
+            try {
+                await observer.bindTurn(binding);
+            }
+            catch {
+                logger.debug({ sessionId: binding.sessionId }, "app-server-registry: session turn binding failed open");
+            }
+        };
+        runtime.observerTail = runtime.observerTail.then(deliver, deliver);
+    }
+    observeUserInput(runtime, input, atMs = this.now()) {
+        const content = turnInputText(input);
+        if (content == null)
+            return;
+        this.runSessionObservation(runtime, { kind: "user", content }, atMs, runtime.record.activeTurnId ?? null);
+    }
+    observeApprovalRequest(runtime, approval, atMs = this.now()) {
+        this.runSessionObservation(runtime, {
+            kind: "approval_request",
+            approvalId: approval.id,
+            approvalType: approval.type,
+            action: approvalAction(approval),
+        }, atMs);
+    }
+    observeApprovalResolution(runtime, approvalId, decision, atMs = this.now()) {
+        this.runSessionObservation(runtime, {
+            kind: "approval_resolution",
+            approvalId,
+            decision,
+        }, atMs);
+    }
+    observeError(runtime, message, atMs = this.now(), turnId = runtime.record.activeTurnId ?? null) {
+        this.runSessionObservation(runtime, {
+            kind: "error",
+            code: "app_server_session_failed",
+            message,
+            retryable: false,
+        }, atMs, turnId);
+    }
+    observeLifecycle(runtime, status, atMs = this.now(), turnId = runtime.record.activeTurnId ?? null) {
+        this.runSessionObservation(runtime, {
+            kind: "lifecycle",
+            status,
+            failureReason: runtime.record.failureReason ?? null,
+        }, atMs, turnId);
+    }
+    observeRunning(runtime) {
+        const observation = runtime.activityObservation;
+        if (observation == null)
+            return;
+        this.runActivityObservation(runtime, "running", () => observation.transition("running"));
+    }
+    observeTerminal(runtime, status) {
+        const observation = runtime.activityObservation;
+        if (observation == null)
+            return;
+        const completion = status === "completed"
+            ? { status: "succeeded", outcomeKind: "success" }
+            : status === "interrupted"
+                ? { status: "cancelled", outcomeKind: "cancelled" }
+                : { status: "failed", outcomeKind: "error" };
+        this.runActivityObservation(runtime, "terminal", () => observation.complete(completion));
+    }
+    runActivityObservation(runtime, boundary, operation) {
+        const report = (err) => {
+            logger.debug({
+                err: err instanceof Error ? err.message : String(err),
+                sessionId: runtime.record.sessionId,
+            }, `app-server-registry: dashboard ${boundary} observation failed open`);
+        };
+        try {
+            void operation().catch(report);
+        }
+        catch (err) {
+            report(err);
+        }
+    }
+    /**
+     * Shared terminality/escalation path (2-8 / 2-9):
+     *   1. bounded interrupt RPC
+     *   2. bounded wait for terminal turn/completed
+     *   3. on hang/no-terminal → process-group kill + respawn + mark terminal
+     *
+     * The lease is released only via {@link finalizeTurn}, i.e. only once the
+     * turn is provably terminal.
+     */
+    async terminateTurn(runtime, statusOnKill, reason) {
+        if (runtime.finalized)
+            return;
+        const threadId = runtime.record.threadId;
+        const turnId = runtime.record.activeTurnId;
+        if (turnId != null) {
+            try {
+                await this.withBudget(this.client.turnInterrupt({ threadId, turnId }), this.config.interruptBudgetMs);
+                const reachedTerminal = await this.waitTerminalWithin(runtime, this.config.terminalWaitBudgetMs);
+                if (reachedTerminal)
+                    return; // finalized via turn/completed event
+            }
+            catch (err) {
+                logger.warn({ err, reason, sessionId: runtime.record.sessionId }, "app-server-registry: interrupt RPC failed or timed out — escalating");
+            }
+        }
+        if (runtime.finalized)
+            return;
+        await this.forceKill(runtime, statusOnKill, reason);
+    }
+    async forceKill(runtime, status, reason) {
+        if (runtime.finalized)
+            return;
+        try {
+            await this.client.killProcessGroup(reason);
+        }
+        catch (err) {
+            logger.error({ err, reason, sessionId: runtime.record.sessionId }, "app-server-registry: killProcessGroup failed during escalation");
+        }
+        // Release leases FIRST — the kill terminated the SHARED child, so every
+        // in-flight turn is dead. The client suppresses onProcessDied for
+        // intentional kills, so we must finalize here or leases leak forever
+        // (review fix). This must NOT depend on the respawn: a silent respawned
+        // child would otherwise block escalation before any lease is released.
+        // Future startSession calls re-ensureReady themselves.
+        this.finalizeTurn(runtime, status, { failureReason: reason });
+        this.finalizeCoActiveAfterSharedKill(runtime, reason);
+        if (this.shuttingDown || appServerAdmissionClosed)
+            return;
+        try {
+            // Best-effort respawn ownership is the client's — registry only nudges
+            // it, and bounds it so a silent child cannot hang escalation.
+            await this.withBudget(this.client.ensureReady(), this.config.startBudgetMs);
+        }
+        catch (err) {
+            logger.error({ err, sessionId: runtime.record.sessionId }, "app-server-registry: ensureReady (respawn) failed during escalation");
+        }
+    }
+    /**
+     * Finalize every co-active running session after the SHARED child was killed.
+     * The client suppresses onProcessDied for intentional kills, so without this
+     * their leases leak (review fix). finalizeTurn is idempotent; `except` is the
+     * triggering runtime, handled by the caller.
+     */
+    finalizeCoActiveAfterSharedKill(except, reason) {
+        for (const other of this.sessions.values()) {
+            if (other === except)
+                continue;
+            if (other.finalized || other.record.status !== "running")
+                continue;
+            this.finalizeTurn(other, "failed", {
+                failureReason: `shared app-server killed: ${reason}`,
+            });
+        }
+    }
+    async onTurnTimeout(runtime) {
+        if (runtime.finalized)
+            return;
+        logger.warn({ sessionId: runtime.record.sessionId }, "app-server-registry: turn wall-clock timeout — attempting interrupt");
+        await this.terminateTurn(runtime, "timeout", "turn wall-clock timeout");
+    }
+    async onApprovalTimeout(runtime) {
+        if (runtime.finalized)
+            return;
+        const pendingApprovals = [...runtime.record.pendingApprovals.values()];
+        if (pendingApprovals.length === 0)
+            return;
+        // Auto-decline is NOT terminal (2-9): the turn may continue, and the
+        // decline RPC can hang. Bound it, then await terminality, then escalate.
+        try {
+            for (const pending of pendingApprovals) {
+                if (runtime.finalized)
+                    return;
+                // Defensive: permissions approvals are auto-handled on arrival, so this
+                // path normally only sees command/file. Route any stray permissions
+                // pending to the empty-grant shape rather than {decision}.
+                await this.withBudget(pending.type === "permissions"
+                    ? this.client.respondPermissionsApproval(pending.id)
+                    : this.client.respondApproval({
+                        id: pending.id,
+                        decision: "decline",
+                    }), this.config.interruptBudgetMs);
+                const now = this.now();
+                runtime.record.clearPendingApproval(pending.id, now);
+                this.observeApprovalResolution(runtime, pending.id, "decline", now);
+            }
+            const reachedTerminal = await this.waitTerminalWithin(runtime, this.config.terminalWaitBudgetMs);
+            if (reachedTerminal)
+                return; // finalized via turn/completed event
+        }
+        catch (err) {
+            logger.warn({ err, sessionId: runtime.record.sessionId }, "app-server-registry: auto-decline RPC failed or timed out — escalating");
+        }
+        if (runtime.finalized)
+            return;
+        await this.forceKill(runtime, "failed", "pending-approval timeout");
+    }
+    /**
+     * Auto-decline a permissions (sandbox-escalation) approval the moment it
+     * arrives, with a protocol-valid empty grant. Never surfaced to the user
+     * (read-only / approval:never posture). Bounded: the decline RPC is capped by
+     * `interruptBudgetMs`.
+     *
+     * On decline failure/timeout we do NOT merely log: Codex's child is blocked on
+     * a response that never lands, and if the operator disabled the wall-clock
+     * turn timeout (`CLINKX_TURN_TIMEOUT_SECONDS=0`) there is no backstop until
+     * idle reap. So we escalate the turn directly under a bounded budget,
+     * independent of the global turn timeout, mirroring the command/file
+     * decline-failure recovery in {@link onApprovalTimeout}. terminateTurn is
+     * idempotent and no-ops if the turn already finalized, so this never
+     * double-finalizes.
+     */
+    async autoDeclinePermissionsApproval(runtime, id) {
+        try {
+            await this.withBudget(this.client.respondPermissionsApproval(id), this.config.interruptBudgetMs);
+            this.observeApprovalResolution(runtime, id, "decline", this.now());
+            logger.debug({ sessionId: runtime.record.sessionId, approvalId: id }, "app-server-registry: auto-declined permissions approval (empty grant)");
+        }
+        catch (err) {
+            logger.warn({ err, sessionId: runtime.record.sessionId, approvalId: id }, "app-server-registry: permissions auto-decline failed — escalating turn");
+            // Failure-safe backstop: the child is wedged awaiting a response we could
+            // not deliver. Escalate independently of the (possibly disabled) turn
+            // wall-clock timeout. Idempotent; bounded by interrupt/terminal budgets.
+            await this.terminateTurn(runtime, "failed", "permissions auto-decline failed").catch((escalationErr) => {
+                logger.error({ err: escalationErr, sessionId: runtime.record.sessionId, approvalId: id }, "app-server-registry: escalation after permissions auto-decline failure errored");
+            });
+        }
+    }
+    handleProcessDied(event) {
+        const reason = "app-server process died" +
+            (event.signal != null ? ` (signal ${event.signal})` : "") +
+            (event.exitCode != null ? ` (exit ${event.exitCode})` : "");
+        for (const runtime of this.sessions.values()) {
+            // Crash split (2-10): only active/in-flight turns are unrecoverable.
+            // Idle/completed sessions keep their resumable threadId untouched.
+            if (!runtime.finalized && runtime.record.status === "running") {
+                this.finalizeTurn(runtime, "failed", { failureReason: reason });
+            }
+        }
+    }
+    // --- timers --------------------------------------------------------------
+    scheduleTurnTimeout(runtime) {
+        // Honor an explicit per-session override (review fix B); fall back to the
+        // global default/backstop. A value of 0 disables the timeout, preserving
+        // the global's disabled semantics exactly.
+        const turnTimeoutMs = runtime.turnTimeoutMs ?? this.config.turnTimeoutMs;
+        if (turnTimeoutMs <= 0)
+            return;
+        if (runtime.turnTimer != null)
+            this.clearTimer(runtime.turnTimer);
+        runtime.turnTimer = this.setTimer(() => {
+            void this.onTurnTimeout(runtime);
+        }, turnTimeoutMs);
+    }
+    scheduleApprovalTimeout(runtime) {
+        if (this.config.approvalTimeoutMs <= 0)
+            return;
+        this.clearApprovalTimer(runtime);
+        runtime.approvalTimer = this.setTimer(() => {
+            void this.onApprovalTimeout(runtime);
+        }, this.config.approvalTimeoutMs);
+    }
+    clearApprovalTimer(runtime) {
+        if (runtime.approvalTimer != null) {
+            this.clearTimer(runtime.approvalTimer);
+            runtime.approvalTimer = undefined;
+        }
+    }
+    clearTimers(runtime) {
+        if (runtime.turnTimer != null) {
+            this.clearTimer(runtime.turnTimer);
+            runtime.turnTimer = undefined;
+        }
+        this.clearApprovalTimer(runtime);
+    }
+    evict(sessionId, runtime, why) {
+        this.clearTimers(runtime);
+        runtime.unsubscribe?.();
+        runtime.unsubscribe = undefined;
+        this.sessions.delete(sessionId);
+        logger.debug({ sessionId, why }, "app-server-registry: evicted session");
+    }
+    // --- bounded-wait helpers ------------------------------------------------
+    /** Reject if `promise` does not settle within `ms`. */
+    withBudget(promise, ms, message) {
+        if (ms <= 0)
+            return promise;
+        return new Promise((resolve, reject) => {
+            const handle = this.setTimer(() => {
+                reject(new BudgetExceededError(message));
+            }, ms);
+            promise.then((value) => {
+                this.clearTimer(handle);
+                resolve(value);
+            }, (err) => {
+                this.clearTimer(handle);
+                reject(err instanceof Error ? err : new Error(String(err)));
+            });
+        });
+    }
+    /** Resolve `true` if the terminal deferred settles within `ms`, else `false`. */
+    waitTerminalWithin(runtime, ms) {
+        if (runtime.finalized)
+            return Promise.resolve(true);
+        if (ms <= 0)
+            return Promise.resolve(false);
+        return new Promise((resolve) => {
+            let settled = false;
+            const handle = this.setTimer(() => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(false);
+            }, ms);
+            void runtime.terminal.promise.then(() => {
+                if (settled)
+                    return;
+                settled = true;
+                this.clearTimer(handle);
+                resolve(true);
+            });
+        });
+    }
+    notifyAttention(runtime) {
+        const attention = runtime.attention;
+        runtime.attention = createDeferred();
+        attention.resolve();
+    }
+    /**
+     * Await terminality, a wait-local timeout, or newly requested human attention.
+     * All outcomes are lease-free: a pending approval returns a running snapshot.
+     */
+    raceTurnWait(runtime, timeoutMs, signal) {
+        return new Promise((resolve) => {
+            let settled = false;
+            let handle;
+            let onAbort;
+            const done = () => {
+                if (settled)
+                    return;
+                settled = true;
+                if (handle != null)
+                    this.clearTimer(handle);
+                if (onAbort != null && signal != null) {
+                    signal.removeEventListener("abort", onAbort);
+                }
+                resolve();
+            };
+            if (signal?.aborted) {
+                // Already aborted: resolve immediately without arming a timer.
+                resolve();
+                return;
+            }
+            if (timeoutMs != null && timeoutMs > 0) {
+                handle = this.setTimer(done, timeoutMs);
+            }
+            if (signal != null) {
+                onAbort = done;
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+            void runtime.terminal.promise.then(done);
+            void runtime.attention.promise.then(done);
+        });
+    }
+}
+let appServerRegistrySingleton;
+let appServerRegistrySingletonSpawn;
+let appServerRegistryTestOverrides;
+/**
+ * Derive the registry spawn request from a resolved app_server adapter:
+ * `app_server.command` (falling back to the adapter's top-level `command`) and
+ * `app_server.args`.
+ */
+export function spawnRequestFor(adapter) {
+    return {
+        command: adapter.app_server?.command ?? adapter.command,
+        args: adapter.app_server?.args,
+    };
+}
+function resolveSpawnRequest(request) {
+    return {
+        command: request?.command ?? DEFAULT_APP_SERVER_SPAWN_CONFIG.command,
+        args: request?.args ?? [...DEFAULT_APP_SERVER_SPAWN_CONFIG.args],
+    };
+}
+function defaultAppServerSpawnConfig(spawn, env) {
+    return {
+        command: spawn.command,
+        args: [...spawn.args],
+        env,
+    };
+}
+function createDefaultAppServerRegistry(spawn) {
+    // Resolve config first so the spawned child and the registry share the same
+    // depth: the child must receive CLINKX_AGENT_DEPTH=currentDepth+1 so the
+    // recursion guard survives the env sanitizer (review fix 5).
+    const config = resolveRegistryConfig();
+    const childEnv = childEnvMarkerFor(config.currentDepth);
+    const client = appServerRegistryTestOverrides?.client ??
+        new RealCodexAppServerClient(defaultAppServerSpawnConfig(spawn, childEnv));
+    const registryFactory = appServerRegistryTestOverrides?.registryFactory ??
+        ((deps) => new AppServerRegistry(deps));
+    return registryFactory({ client, config });
+}
+/**
+ * Get the process-wide app-server registry, creating it on first call.
+ *
+ * The registry is a singleton: one long-lived `codex app-server` process
+ * multiplexes every session. The adapter's `app_server.command/args` therefore
+ * take effect only at FIRST creation. A later adapter requesting a spawn config
+ * that conflicts with the live one is rejected with {@link InvalidParamsError}
+ * (-32602) rather than silently ignored — building a registry-per-config map
+ * would be over-engineering for a singleton-by-design subsystem.
+ */
+export function getAppServerRegistry(spawn) {
+    if (appServerAdmissionClosed) {
+        throw new InvalidParamsError("Cannot access the app-server registry after shutdown has started.");
+    }
+    const resolved = resolveSpawnRequest(spawn);
+    if (appServerRegistrySingleton == null) {
+        appServerRegistrySingleton = createDefaultAppServerRegistry(resolved);
+        appServerRegistrySingletonSpawn = resolved;
+        return appServerRegistrySingleton;
+    }
+    // A no-arg call (e.g. clink_agent_manage) is a pure accessor — it never
+    // imposes a spawn config, so it cannot conflict with the live one.
+    if (spawn == null) {
+        return appServerRegistrySingleton;
+    }
+    const live = appServerRegistrySingletonSpawn;
+    if (live != null &&
+        (live.command !== resolved.command ||
+            live.args.length !== resolved.args.length ||
+            live.args.some((arg, i) => arg !== resolved.args[i]))) {
+        throw new InvalidParamsError(`Codex app-server spawn config conflict: the app-server process is already ` +
+            `running as "${live.command} ${live.args.join(" ")}" but this adapter requests ` +
+            `"${resolved.command} ${resolved.args.join(" ")}". The app-server registry is a ` +
+            `single shared process; all app_server adapters must agree on command/args.`);
+    }
+    return appServerRegistrySingleton;
+}
+/**
+ * Return the live process-wide registry WITHOUT creating it. Read-only manage
+ * ops (clink_agent_manage) must not lock in a default spawn config before a run
+ * has chosen one — otherwise a later run with a custom app_server.command would
+ * spuriously hit the spawn-config conflict (-32602). See {@link getAppServerRegistry}.
+ */
+export function peekAppServerRegistry() {
+    return appServerRegistrySingleton;
+}
+export async function shutdownAppServerRegistry(reason) {
+    const registry = appServerRegistrySingleton;
+    if (registry == null)
+        return;
+    await registry.shutdown(reason);
+    appServerRegistrySingleton = undefined;
+    appServerRegistrySingletonSpawn = undefined;
+}
+/** The spawn command/args the live singleton was created with (test inspection). */
+export function appServerRegistrySpawnForTest() {
+    return appServerRegistrySingletonSpawn;
+}
+export function configureAppServerRegistryForTest(overrides) {
+    appServerRegistryTestOverrides = overrides;
+    appServerRegistrySingleton = undefined;
+    appServerRegistrySingletonSpawn = undefined;
+}
+export async function resetAppServerRegistryForTest(reason = "test reset") {
+    const registry = appServerRegistrySingleton;
+    appServerRegistrySingleton = undefined;
+    appServerRegistrySingletonSpawn = undefined;
+    appServerRegistryTestOverrides = undefined;
+    try {
+        if (registry != null) {
+            await registry.shutdown(reason);
+        }
+    }
+    finally {
+        appServerAdmissionClosed = false;
+    }
+}
+//# sourceMappingURL=app-server-registry.js.map