@qduc/term2 0.22.1 → 0.24.0

package/dist/gateway/gateway.js

@@ -7,12 +7,17 @@ import { createSafeLogMetadata, GatewayAuditLog } from './safe-log.js';
 import { AssertionVerifier } from './assertion.js';
 import { SqliteReplayLedger } from './replay-ledger.js';
 import { GatewayServer } from './server.js';
+import { RuntimeFactoryError } from './runtime-factory.js';
+import { projectConversationMessage } from '../services/conversation/conversation-message-projection.js';
+import { normalizeRunItem } from '../services/conversation/run-item-normalizer.js';
 import { FROZEN_AGENT_EVENT_TYPES, GatewayPersistenceError, TERMINAL_AGENT_EVENT_TYPES, } from './persistence/contracts.js';
-import { createSessionProjectionSource, } from './persistence/projection.js';
+import { createSessionProjectionSource, hydrateConversationService, } from './persistence/projection.js';
 import { decideInteraction, InteractionProtocolError, projectPendingInteraction, validatePendingInteractionDto, } from './interaction-protocol.js';
-import { GatewayAdmissionPersistence } from './persistence/admission-persistence.js';
+import { GatewayAdmissionPersistence, normalizedBodyHash } from './persistence/admission-persistence.js';
 import { GATEWAY_EVENT_HEARTBEAT_INTERVAL_MS, GATEWAY_EVENT_STREAM_CONTENT_TYPE, GATEWAY_EVENT_STREAM_HEARTBEAT, } from './server.js';
 import { ServerSession } from './server-session.js';
+import { createSessionSettingsSnapshot } from './launcher-seam.js';
+import { readSessionSnapshot, writeSessionSnapshot } from './persistence/session-snapshot.js';
 import { ServerSessionError } from './server-session.js';
 import { DynamicWorkspaceRegistry, DynamicWorkspaceRegistryError } from './dynamic-workspace-registry.js';
 import { accessSync, constants as fsConstants, realpathSync, statSync } from 'node:fs';
@@ -28,7 +33,30 @@ import { loginToCodex } from '../providers/codex-auth.js';
 import { loginToGrok } from '../providers/grok-auth.js';
 const MAX_BUFFERED_SSE_EVENTS = 256;
 const NONCRITICAL_RUNTIME_EVENT_TYPES = new Set(['text_delta', 'reasoning_delta']);
+let malformedCommandMessageDrops = 0;
 const isCriticalRuntimeEvent = (event) => !NONCRITICAL_RUNTIME_EVENT_TYPES.has(event.type);
+/**
+ * `retry-turn` replays the canonical transcript verbatim, so a retry is only
+ * meaningful while that transcript still ends on the user message of a turn
+ * that never produced output. Assistant output or a tool result after the last
+ * genuine user message means the turn committed something; synthetic user
+ * items (shell context, mode notices, local summaries) are not turns.
+ */
+const hasFailedTurnToRetry = (history) => {
+    for (let index = history.length - 1; index >= 0; index -= 1) {
+        const item = history[index];
+        if (normalizeRunItem(item).some((normalized) => normalized.type === 'tool_result'))
+            return false;
+        const message = projectConversationMessage(item);
+        if (!message || message.isSynthetic)
+            continue;
+        if (message.role === 'user')
+            return true;
+        if (message.role === 'assistant')
+            return false;
+    }
+    return false;
+};
 const INTERACTION_METRICS = [
     'interaction_presented',
     'interaction_updated',
@@ -91,6 +119,37 @@ const PUBLIC_EVENT_PAYLOAD_KEYS = new Set([
     'riskLevel',
     'deniedRead',
     'runBudgetEvidence',
+    'agentId',
+    'name',
+    'task',
+    'async',
+    'toolCallId',
+    'commandMessages',
+    'status',
+    'output',
+    'error',
+    'finalText',
+    'finalTextTruncated',
+    'toolsUsed',
+    'count',
+    'terminalCause',
+    'provider',
+    'attempt',
+    'maxRetries',
+    'errorMessage',
+    'retryType',
+    'errorKind',
+    'delayMs',
+    'retryAfterMs',
+    'attempts',
+    'maxAttempts',
+    'canRetry',
+    'sessionId',
+    'inputTokensBefore',
+    'inputTokensAfter',
+    'durationMs',
+    'strategy',
+    'errorCategory',
 ]);
 const LOCAL_OWNER_PURPOSES = new Set([
     'settings_read',
@@ -188,8 +247,15 @@ export class Term2Gateway {
     #persisted = new Map();
     #admissions;
     #interactionBindings = new Map();
+    #childTurnIds = new Map();
+    #childRoles = new Map();
+    #lastTurnIds = new Map();
     #interactionCounters = new Map();
     #eventPersistenceTails = new Map();
+    #inflightCommands = new Map();
+    // Keyed by owner and session: an in-flight revival belongs to the owner who
+    // started it, and no other caller may inherit its result.
+    #sessionRestores = new Map();
     #shutdownInProgress = false;
     #shutdownPromise;
     #server;
@@ -234,6 +300,7 @@ export class Term2Gateway {
                 otpTtlMs: config.pairing.otpTtlMs,
                 maxAttempts: config.pairing.maxAttempts,
                 trustStore: trustedStore,
+                ...(config.pairing.printOtp ? { printOtp: config.pairing.printOtp } : {}),
             })
             : undefined;
         this.#audit = new GatewayAuditLog(config.auditWriter);
@@ -373,6 +440,8 @@ export class Term2Gateway {
                 return await this.#submitMessage(claims, input.body);
             if (claims.purpose === 'abort')
                 return await this.#abortSession(claims, input.body);
+            if (claims.purpose === 'command_invoke')
+                return await this.#invokeCommand(claims, input.body, input.correlationId);
             if (claims.purpose === 'interaction_resolve')
                 return await this.#resolveInteraction(claims, route.interactionId, input.body);
             if (claims.purpose === 'events_connect')
@@ -672,6 +741,7 @@ export class Term2Gateway {
             turnId,
             variant: dto.variant,
             dto,
+            owner: 'root',
         };
         this.#interactionBindings.set(sessionId, binding);
         this.#countInteraction('interaction_presented');
@@ -680,6 +750,56 @@ export class Term2Gateway {
     #countInteraction(metric) {
         this.#interactionCounters.set(metric, (this.#interactionCounters.get(metric) ?? 0) + 1);
     }
+    #backgroundInteractionBinding(sessionId, turnId, event, session) {
+        const publicInteractionId = crypto.randomUUID();
+        if (event.type === 'subagent_approval_required') {
+            const snapshot = session.service.backgroundSubagentApprovals.getSnapshot();
+            const entry = snapshot.current;
+            if (!entry)
+                return undefined;
+            const dto = projectPendingInteraction({
+                agentName: event.role,
+                toolName: entry.toolName,
+                callId: entry.toolCallId,
+                argumentsText: entry.argumentsText,
+            }, publicInteractionId, 1);
+            const binding = {
+                publicInteractionId,
+                expectedInteractionId: 0,
+                continuationGeneration: crypto.randomUUID(),
+                revision: 1,
+                turnId,
+                variant: dto.variant,
+                dto,
+                owner: 'background_approval',
+                childRunId: event.agentId,
+                childRole: event.role,
+                backgroundEntry: entry,
+                backgroundRevision: snapshot.revision,
+            };
+            this.#interactionBindings.set(sessionId, binding);
+            return binding;
+        }
+        const argumentsText = JSON.stringify({
+            questions: [{ question: event.question, options: [], is_multi_select: false }],
+        });
+        const dto = projectPendingInteraction({ agentName: event.role, toolName: 'ask_user', argumentsText }, publicInteractionId, 1);
+        const binding = {
+            publicInteractionId,
+            expectedInteractionId: 0,
+            continuationGeneration: crypto.randomUUID(),
+            revision: 1,
+            turnId,
+            variant: dto.variant,
+            dto,
+            owner: 'background_question',
+            childRunId: event.runId,
+            childMessageId: event.messageId,
+            childRole: event.role,
+        };
+        this.#interactionBindings.set(sessionId, binding);
+        return binding;
+    }
     async #ensurePersistedSession(ownerUserId, sessionId) {
         const existing = this.#persisted.get(sessionId);
         if (existing) {
@@ -754,10 +874,25 @@ export class Term2Gateway {
             return publicError(503, 'persistence_unavailable', 'gateway persistence unavailable', true);
         if (!isMessageBody(body))
             return publicError(400, 'validation_error', 'message request is invalid');
-        const session = this.#sessions.get(claims.sessionId);
-        const persisted = this.#persisted.get(claims.sessionId);
+        let session = this.#sessions.get(claims.sessionId);
+        let persisted = this.#persisted.get(claims.sessionId);
+        if (!(session instanceof ServerSession) || !persisted) {
+            // A session from a previous gateway process has no live runtime; revive
+            // it through the same factory path a fresh session uses.
+            const restored = await this.#ensureLiveRuntime(claims.sub, claims.sessionId);
+            if (restored && 'body' in restored)
+                return restored;
+            if (restored) {
+                session = restored.session;
+                persisted = restored.persisted;
+            }
+        }
         if (!(session instanceof ServerSession) || !persisted)
             return publicError(409, 'session_not_admitting', 'session is not admitting messages');
+        // Owner scoping holds on every path that reaches admission, live or
+        // restored: a session owned by someone else does not exist for this caller.
+        if (session.binding.ownerUserId !== claims.sub)
+            return publicError(404, 'not_found', 'session not found');
         const turnId = crypto.randomUUID();
         try {
             const result = await this.#admissions.admit({
@@ -850,6 +985,401 @@ export class Term2Gateway {
             };
         return publicError(409, 'session_not_admitting', 'session is interrupted');
     }
+    async #invokeCommand(claims, body, correlationId) {
+        if (!isCommandBody(body))
+            return publicError(400, 'validation_error', 'command request is invalid');
+        let session = this.#sessions.get(claims.sessionId);
+        if (!session || session.binding.ownerUserId !== claims.sub) {
+            // A restored session has no live runtime; commands revive it the same
+            // way message_submit does. Sessions unknown to this owner keep the 404.
+            const restored = await this.#ensureLiveRuntime(claims.sub, claims.sessionId);
+            if (restored && 'body' in restored)
+                return restored;
+            if (restored)
+                session = restored.session;
+        }
+        if (!session || session.binding.ownerUserId !== claims.sub) {
+            return publicError(404, 'not_found', 'session not found');
+        }
+        if (!(session instanceof ServerSession)) {
+            return publicError(409, 'session_not_admitting', 'session is not admitting commands');
+        }
+        if (session.status === 'running' || session.status === 'awaiting_interaction') {
+            return publicError(409, 'session_busy', 'session is busy');
+        }
+        if (!COMMAND_ALLOWLIST.has(body.commandId)) {
+            return publicError(422, 'command_not_allowed', 'command is not allowed');
+        }
+        await this.#audit.write(createSafeLogMetadata({
+            operation: 'command_invoke',
+            outcome: 'allowed',
+            reasonCode: 'accepted',
+            sessionId: session.sessionId,
+            workspaceId: session.binding.workspaceId,
+            grantVersion: session.binding.grantVersion,
+            access: session.binding.access,
+            ...(correlationId ? { correlationId } : {}),
+        }));
+        const inflightKey = `${claims.sub}:${session.sessionId}:${body.clientRequestId}`;
+        const bodyHash = normalizedBodyHash(body);
+        const inflight = this.#inflightCommands.get(inflightKey);
+        if (inflight) {
+            if (inflight.bodyHash !== bodyHash) {
+                throw new GatewayPersistenceError('conflict', 'idempotency key has a different body');
+            }
+            const existing = await inflight.promise;
+            return {
+                ...existing,
+                body: {
+                    ...existing.body,
+                    replayed: true,
+                },
+            };
+        }
+        if (this.#admissions) {
+            const lookup = this.#admissions.lookup(claims.sub, session.sessionId, body.clientRequestId, body);
+            if (lookup.kind === 'conflict') {
+                throw new GatewayPersistenceError('conflict', 'idempotency key has a different body');
+            }
+            if (lookup.kind === 'replayed') {
+                if (body.commandId === 'compact') {
+                    const parts = lookup.record.turnId.split(':');
+                    if (lookup.record.result === 'failed' || parts[1] === 'failed') {
+                        return publicError(409, 'compact_failed', 'compaction failed', false);
+                    }
+                    if (parts[1] === 'in_progress') {
+                        return publicError(409, 'compact_interrupted', 'compaction was interrupted', false);
+                    }
+                    if (parts[1] !== 'completed' && parts[1] !== 'not_reduced' && parts[1] !== 'nothing_to_retry') {
+                        return publicError(500, 'compact_invalid_state', 'invalid compaction record state', false);
+                    }
+                    const outcome = parts[1];
+                    const tokensBefore = parts[2] ? Number(parts[2]) : undefined;
+                    const tokensAfter = parts[3] ? Number(parts[3]) : undefined;
+                    return {
+                        status: 200,
+                        body: {
+                            commandId: body.commandId,
+                            outcome,
+                            ...(tokensBefore !== undefined && !Number.isNaN(tokensBefore) ? { tokensBefore } : {}),
+                            ...(tokensAfter !== undefined && !Number.isNaN(tokensAfter) ? { tokensAfter } : {}),
+                            replayed: true,
+                        },
+                    };
+                }
+                if (lookup.record.turnId === 'nothing_to_retry') {
+                    return {
+                        status: 200,
+                        body: {
+                            commandId: body.commandId,
+                            outcome: 'nothing_to_retry',
+                            replayed: true,
+                        },
+                    };
+                }
+                if (lookup.record.result === 'failed') {
+                    return publicError(409, 'retry_failed', 'retry failed', false);
+                }
+                return {
+                    status: 200,
+                    body: {
+                        commandId: body.commandId,
+                        outcome: 'accepted',
+                        turnId: lookup.record.turnId,
+                        replayed: true,
+                    },
+                };
+            }
+        }
+        const persisted = this.#persisted.get(claims.sessionId);
+        if (this.#config.persistence && !persisted) {
+            return publicError(503, 'persistence_unavailable', 'gateway persistence unavailable', true);
+        }
+        const inflightPromise = (async () => {
+            try {
+                if (body.commandId === 'compact') {
+                    if (this.#admissions) {
+                        this.#admissions.prepare({
+                            ownerUserId: claims.sub,
+                            sessionId: session.sessionId,
+                            clientRequestId: body.clientRequestId,
+                            body,
+                            turnId: 'compact:in_progress',
+                        });
+                        this.#config.persistence?.index.updateAdmission(claims.sub, session.sessionId, body.clientRequestId, {
+                            state: 'accepted',
+                            result: 'accepted',
+                            phase: 'committed',
+                            turnId: 'compact:in_progress',
+                        });
+                    }
+                    // The outcome is mapped from the typed compaction result, never from
+                    // result text, so the response agrees with the journaled compaction
+                    // events: failed compactions return { outcome: 'failed', reason } with
+                    // a bounded reason code, and 'nothing_to_retry' is reserved for
+                    // genuinely nothing to compact (contract 13 §8).
+                    let outcome;
+                    let tokensBefore;
+                    let tokensAfter;
+                    let failureReason;
+                    const compactTurnId = crypto.randomUUID();
+                    try {
+                        const result = await session.withCommandTurn(compactTurnId, () => session.service.compactContextDetailed());
+                        switch (result.kind) {
+                            case 'compacted': {
+                                tokensBefore = result.tokensBefore;
+                                tokensAfter = result.tokensAfter;
+                                // A compaction that grew the context is not a completed one; the
+                                // numbers come from the same estimator on both sides.
+                                outcome =
+                                    tokensBefore !== undefined && tokensAfter !== undefined && tokensAfter >= tokensBefore
+                                        ? 'not_reduced'
+                                        : 'completed';
+                                break;
+                            }
+                            case 'nothing_to_compact':
+                                outcome = 'nothing_to_retry';
+                                break;
+                            case 'failed':
+                                outcome = 'failed';
+                                failureReason = result.reason;
+                                break;
+                        }
+                        if (this.#admissions) {
+                            const turnId = outcome === 'failed'
+                                ? `compact:failed:${failureReason}`
+                                : `compact:${outcome}:${tokensBefore ?? ''}:${tokensAfter ?? ''}`;
+                            this.#config.persistence?.index.updateAdmission(claims.sub, session.sessionId, body.clientRequestId, {
+                                state: 'terminal',
+                                result: outcome === 'failed' ? 'failed' : 'accepted',
+                                phase: 'committed',
+                                turnId,
+                            });
+                        }
+                    }
+                    catch (error) {
+                        if (this.#admissions) {
+                            try {
+                                this.#config.persistence?.index.updateAdmission(claims.sub, session.sessionId, body.clientRequestId, {
+                                    state: 'terminal',
+                                    result: 'failed',
+                                    phase: 'committed',
+                                    turnId: 'compact:failed',
+                                });
+                            }
+                            catch {
+                                // ignore
+                            }
+                        }
+                        throw error;
+                    }
+                    return {
+                        status: 200,
+                        body: {
+                            commandId: 'compact',
+                            outcome,
+                            ...(outcome === 'failed' ? { reason: failureReason } : {}),
+                            ...(tokensBefore !== undefined ? { tokensBefore } : {}),
+                            ...(tokensAfter !== undefined ? { tokensAfter } : {}),
+                        },
+                    };
+                }
+                if (body.commandId === 'retry-tool') {
+                    const lastTool = session.service.peekLastToolOutput();
+                    if (!lastTool) {
+                        if (this.#admissions) {
+                            this.#admissions.prepare({
+                                ownerUserId: claims.sub,
+                                sessionId: session.sessionId,
+                                clientRequestId: body.clientRequestId,
+                                body,
+                                turnId: 'nothing_to_retry',
+                            });
+                            this.#config.persistence?.index.updateAdmission(claims.sub, session.sessionId, body.clientRequestId, {
+                                state: 'terminal',
+                                result: 'accepted',
+                                phase: 'committed',
+                                turnId: 'nothing_to_retry',
+                            });
+                        }
+                        return {
+                            status: 200,
+                            body: {
+                                commandId: 'retry-tool',
+                                outcome: 'nothing_to_retry',
+                            },
+                        };
+                    }
+                    const turnId = crypto.randomUUID();
+                    if (this.#admissions && persisted) {
+                        const runtime = session.createRetryRuntime('retry-tool');
+                        try {
+                            const result = await this.#admissions.admit({
+                                ownerUserId: claims.sub,
+                                sessionId: session.sessionId,
+                                clientRequestId: body.clientRequestId,
+                                body,
+                                turnId,
+                                runtime,
+                                persistence: persisted.persistence.critical,
+                                acceptedEvent: {
+                                    sessionId: session.sessionId,
+                                    type: 'assistant_started',
+                                    payload: { turnId, clientRequestId: body.clientRequestId },
+                                },
+                            });
+                            if (result.kind === 'rejected') {
+                                return result.reason === 'queue_full'
+                                    ? publicError(429, 'queue_full', 'message queue is full', true)
+                                    : publicError(409, 'session_not_admitting', 'session is not admitting commands');
+                            }
+                            return {
+                                status: 200,
+                                body: {
+                                    commandId: 'retry-tool',
+                                    outcome: 'accepted',
+                                    turnId: result.record.turnId,
+                                    ...(result.replayed ? { replayed: true } : {}),
+                                },
+                            };
+                        }
+                        catch (error) {
+                            try {
+                                await this.#enqueueEventPersistence(session.sessionId, async () => {
+                                    const events = persisted.persistence.journal.events();
+                                    const hasStarted = events.some((e) => e.type === 'assistant_started' && e.payload?.turnId === turnId);
+                                    const hasTerminal = events.some((e) => (e.type === 'turn_completed' || e.type === 'turn_failed' || e.type === 'turn_aborted') &&
+                                        e.payload?.turnId === turnId);
+                                    if (hasStarted && !hasTerminal) {
+                                        await persisted.persistence.critical.appendJournalCritical({
+                                            sessionId: session.sessionId,
+                                            type: 'turn_failed',
+                                            payload: { turnId, outcome: 'failed', reason: 'runtime_error' },
+                                        });
+                                    }
+                                });
+                            }
+                            catch {
+                                // ignore secondary journal error
+                            }
+                            return this.#mapError(error);
+                        }
+                    }
+                    void session.service.retryLastToolOutput({ preferredMessageId: turnId }).catch(() => undefined);
+                    return {
+                        status: 200,
+                        body: {
+                            commandId: 'retry-tool',
+                            outcome: 'accepted',
+                            turnId,
+                        },
+                    };
+                }
+                if (body.commandId === 'retry-turn') {
+                    const state = session.service.exportState();
+                    if (!hasFailedTurnToRetry(state.history)) {
+                        if (this.#admissions) {
+                            this.#admissions.prepare({
+                                ownerUserId: claims.sub,
+                                sessionId: session.sessionId,
+                                clientRequestId: body.clientRequestId,
+                                body,
+                                turnId: 'nothing_to_retry',
+                            });
+                            this.#config.persistence?.index.updateAdmission(claims.sub, session.sessionId, body.clientRequestId, {
+                                state: 'terminal',
+                                result: 'accepted',
+                                phase: 'committed',
+                                turnId: 'nothing_to_retry',
+                            });
+                        }
+                        return {
+                            status: 200,
+                            body: {
+                                commandId: 'retry-turn',
+                                outcome: 'nothing_to_retry',
+                            },
+                        };
+                    }
+                    const turnId = crypto.randomUUID();
+                    if (this.#admissions && persisted) {
+                        const runtime = session.createRetryRuntime('retry-turn');
+                        try {
+                            const result = await this.#admissions.admit({
+                                ownerUserId: claims.sub,
+                                sessionId: session.sessionId,
+                                clientRequestId: body.clientRequestId,
+                                body,
+                                turnId,
+                                runtime,
+                                persistence: persisted.persistence.critical,
+                                acceptedEvent: {
+                                    sessionId: session.sessionId,
+                                    type: 'assistant_started',
+                                    payload: { turnId, clientRequestId: body.clientRequestId },
+                                },
+                            });
+                            if (result.kind === 'rejected') {
+                                return result.reason === 'queue_full'
+                                    ? publicError(429, 'queue_full', 'message queue is full', true)
+                                    : publicError(409, 'session_not_admitting', 'session is not admitting commands');
+                            }
+                            return {
+                                status: 200,
+                                body: {
+                                    commandId: 'retry-turn',
+                                    outcome: 'accepted',
+                                    turnId: result.record.turnId,
+                                    ...(result.replayed ? { replayed: true } : {}),
+                                },
+                            };
+                        }
+                        catch (error) {
+                            try {
+                                await this.#enqueueEventPersistence(session.sessionId, async () => {
+                                    const events = persisted.persistence.journal.events();
+                                    const hasStarted = events.some((e) => e.type === 'assistant_started' && e.payload?.turnId === turnId);
+                                    const hasTerminal = events.some((e) => (e.type === 'turn_completed' || e.type === 'turn_failed' || e.type === 'turn_aborted') &&
+                                        e.payload?.turnId === turnId);
+                                    if (hasStarted && !hasTerminal) {
+                                        await persisted.persistence.critical.appendJournalCritical({
+                                            sessionId: session.sessionId,
+                                            type: 'turn_failed',
+                                            payload: { turnId, outcome: 'failed', reason: 'runtime_error' },
+                                        });
+                                    }
+                                });
+                            }
+                            catch {
+                                // ignore secondary journal error
+                            }
+                            return this.#mapError(error);
+                        }
+                    }
+                    void session.service.retryLastFailedTurn({ preferredMessageId: turnId }).catch(() => undefined);
+                    return {
+                        status: 200,
+                        body: {
+                            commandId: 'retry-turn',
+                            outcome: 'accepted',
+                            turnId,
+                        },
+                    };
+                }
+                return publicError(422, 'command_not_allowed', 'command is not allowed');
+            }
+            finally {
+                this.#inflightCommands.delete(inflightKey);
+            }
+        })();
+        this.#inflightCommands.set(inflightKey, { promise: inflightPromise, bodyHash });
+        try {
+            return await inflightPromise;
+        }
+        catch (error) {
+            return this.#mapError(error);
+        }
+    }
     async #resolveInteraction(claims, interactionId, body) {
         if (!isInteractionResolveRequest(body))
             return publicError(400, 'validation_error', 'interaction request is invalid');
@@ -857,6 +1387,62 @@ export class Term2Gateway {
         const session = this.#sessions.get(claims.sessionId);
         const binding = this.#interactionBindings.get(claims.sessionId);
         const snapshot = session instanceof ServerSession ? session.service.getPendingInteractionSnapshot() : null;
+        if (session instanceof ServerSession &&
+            binding?.publicInteractionId === interactionId &&
+            binding.owner !== 'root') {
+            if (body.revision !== binding.revision)
+                return publicError(409, 'stale_interaction', 'interaction is stale');
+            let decision;
+            try {
+                decision = decideInteraction(binding.dto, body);
+            }
+            catch (error) {
+                if (error instanceof InteractionProtocolError)
+                    return publicError(400, 'validation_error', 'interaction decision is invalid');
+                throw error;
+            }
+            let accepted = false;
+            if (binding.owner === 'background_approval' &&
+                binding.backgroundEntry &&
+                binding.backgroundRevision !== undefined) {
+                const current = session.service.backgroundSubagentApprovals.getSnapshot();
+                if (current.revision !== binding.backgroundRevision || current.current?.runId !== binding.backgroundEntry.runId)
+                    return publicError(409, 'stale_interaction', 'interaction is stale');
+                const result = session.service.backgroundSubagentApprovals.resolve({
+                    revision: binding.backgroundRevision,
+                    entry: binding.backgroundEntry,
+                    decision: { answer: decision.answer, rejectionReason: decision.rejectionReason },
+                });
+                accepted = result.kind === 'resolved';
+            }
+            else if (binding.owner === 'background_question' && binding.childRunId && binding.childMessageId) {
+                accepted = session.service.answerBackgroundSubagentQuestion(binding.childRunId, binding.childMessageId, decision.approvalAnswer ?? decision.answer);
+            }
+            if (!accepted)
+                return publicError(409, 'stale_interaction', 'interaction is stale');
+            this.#countInteraction('interaction_resolved');
+            await this.#enqueueEventPersistence(claims.sessionId, async () => {
+                const persisted = this.#persisted.get(claims.sessionId);
+                if (!persisted)
+                    throw new GatewayPersistenceError('not_found', 'session persistence is unavailable');
+                persisted.persistence.interactionCheckpoint.clear();
+                await persisted.persistence.journal.append({
+                    sessionId: claims.sessionId,
+                    type: 'interaction_resolved',
+                    payload: {
+                        turnId: binding.turnId,
+                        interactionId,
+                        outcome: decision.outcome,
+                        variant: binding.variant,
+                    },
+                }, { durability: 'critical' });
+            });
+            this.#interactionBindings.delete(claims.sessionId);
+            return {
+                status: 202,
+                body: { sessionId: claims.sessionId, turnId: binding.turnId, interactionId, accepted: true },
+            };
+        }
         // A live runtime owns the current interaction. A public ID from an older
         // presentation is stale even when the durable journal still says the
         // interaction was recovered during startup.
@@ -1153,13 +1739,32 @@ export class Term2Gateway {
                 return;
             const session = this.#sessions.get(sessionId);
             const snapshot = session instanceof ServerSession ? session.service.getPendingInteractionSnapshot() : null;
-            const binding = event.type === 'approval_required' && snapshot
-                ? this.#interactionBindingFor(sessionId, snapshot, context.turnId)
+            const childBinding = session instanceof ServerSession &&
+                (event.type === 'subagent_approval_required' || event.type === 'subagent_question')
+                ? this.#backgroundInteractionBinding(sessionId, context.turnId, event, session)
                 : undefined;
+            const binding = childBinding ??
+                ((event.type === 'approval_required' || event.type === 'subagent_approval_required') && snapshot
+                    ? this.#interactionBindingFor(sessionId, snapshot, context.turnId)
+                    : undefined);
+            if (childBinding) {
+                persisted.persistence.interactionCheckpoint.save({
+                    turnId: childBinding.turnId,
+                    interaction: childBinding.dto,
+                    revision: childBinding.revision,
+                    generation: childBinding.continuationGeneration,
+                    settleOnRecovery: 'child_interrupted',
+                    ...(childBinding.childRunId
+                        ? { child: { agentId: childBinding.childRunId, role: childBinding.childRole ?? 'subagent' } }
+                        : {}),
+                });
+            }
             // An ask_user answer can advance the live binding before the original
             // awaitable approval sink reaches this queue. Do not republish that
             // old presentation as a second approval after interaction_updated.
-            if (event.type === 'approval_required' && binding?.revision && binding.revision > 1)
+            if ((event.type === 'approval_required' || event.type === 'subagent_approval_required') &&
+                binding?.revision &&
+                binding.revision > 1)
                 return;
             const mapped = mapConversationEvent(event, context.turnId, sessionId, binding, snapshot ?? undefined);
             if (!mapped)
@@ -1231,6 +1836,8 @@ export class Term2Gateway {
             return publicError(403, 'workspace_forbidden', 'workspace access denied');
         }
         if (error instanceof GatewayPersistenceError) {
+            if (error.code === 'snapshot_unwritable')
+                return publicError(503, 'snapshot_unwritable', 'session snapshot could not be persisted', true);
             if (error.code === 'not_found' || error.code === 'owner_mismatch')
                 return publicError(404, 'not_found', 'session not found');
             if (error.code === 'cursor_invalid')
@@ -1244,6 +1851,15 @@ export class Term2Gateway {
                 return publicError(409, 'stale_interaction', 'interaction is stale');
             return publicError(409, 'session_not_admitting', 'session is not admitting');
         }
+        if (error instanceof RuntimeFactoryError) {
+            if (error.code === 'resource_limit')
+                return publicError(429, 'resource_exhausted', 'session resource limit reached', true);
+            if (error.code === 'provider_unavailable')
+                return publicError(409, 'provider_unavailable', 'session provider is unavailable');
+            if (error.code === 'invalid_binding')
+                return publicError(409, 'session_not_admitting', 'session is not admitting');
+            return publicError(503, 'gateway_unavailable', 'gateway unavailable', true);
+        }
         return publicError(503, 'gateway_unavailable', 'gateway unavailable', true);
     }
     static create(config) {
@@ -1286,64 +1902,348 @@ export class Term2Gateway {
             throw new GatewayStartupError();
         const binding = this.#admission.admit(claims);
         if (this.#config.runtimeFactory) {
-            let persisted;
-            try {
-                persisted = await this.#config.persistence?.open(binding);
-                const session = await this.#config.runtimeFactory.create(binding, {
-                    eventSink: (event, context) => {
-                        const persistence = this.#persistConversationEvent(binding.sessionId, event, context);
-                        if (isCriticalRuntimeEvent(event))
-                            return persistence;
-                        // Streaming deltas remain observationally non-blocking, but their
-                        // persistence failure must be consumed so it cannot become an
-                        // unhandled rejection. A later critical event observes the
-                        // journal's failure latch and is awaited by the runtime.
-                        void persistence.catch(() => undefined);
-                        return undefined;
+            const { session } = await this.#composeRuntimeBackedSession(binding, {
+                auditOperation: 'session_create',
+                ownedBinding: true,
+                correlationId,
+            });
+            return session;
+        }
+        return this.#composeLegacyFixtureSession(claims, options, binding);
+    }
+    /**
+     * Compose a live runtime-backed session through the RuntimeFactory: open (or
+     * reuse) the persistence handle, create the runtime, then attach the shared
+     * gateway wiring (dispose hooks, lifecycle registration, event and
+     * background-subagent sinks). Fresh sessions and restart-restored sessions
+     * take the same path; a restored session additionally hydrates its history
+     * from the persisted transcript before the runtime becomes reachable.
+     */
+    async #composeRuntimeBackedSession(binding, options) {
+        const runtimeFactory = this.#config.runtimeFactory;
+        if (!runtimeFactory)
+            throw new GatewayStartupError();
+        const authority = runtimeFactory.settingsAuthority;
+        // A restored session runs on its persisted snapshot; a fresh session
+        // captures the launcher's current one. Either way the factory receives an
+        // explicit snapshot so it can never silently re-read a changed default.
+        const runtimeSnapshot = options.snapshot ??
+            (authority
+                ? createSessionSettingsSnapshot({
+                    settings: authority,
+                    effectiveToolPolicy: {
+                        allowWrite: this.#config.runtimeFactory?.allowWriteEnabled === true && binding.access === 'read_write',
                     },
-                });
-                if (persisted) {
-                    this.#persisted.set(binding.sessionId, persisted);
-                    session.addDisposeHook(async () => {
-                        await persisted.persistence.close();
-                        this.#persisted.delete(binding.sessionId);
-                        this.#interactionBindings.delete(binding.sessionId);
-                        await this.#config.persistence?.close(binding.sessionId, this.#shutdownInProgress ? 'interrupted' : 'closed');
+                })
+                : undefined);
+        let persisted = this.#persisted.get(binding.sessionId);
+        let createdSession;
+        try {
+            if (!persisted) {
+                persisted = await this.#config.persistence?.open(binding);
+            }
+            const session = await runtimeFactory.create(binding, {
+                settingsSnapshot: runtimeSnapshot,
+                eventSink: (event, context) => {
+                    if (context.turnId)
+                        this.#lastTurnIds.set(binding.sessionId, context.turnId);
+                    if (event.type === 'subagent_started' && event.agentId && context.turnId)
+                        this.#childTurnIds.set(event.agentId, context.turnId);
+                    if (event.type === 'subagent_approval_required')
+                        this.#childRoles.set(event.agentId, event.role);
+                    const persistence = this.#persistConversationEvent(binding.sessionId, event, context);
+                    if (isCriticalRuntimeEvent(event))
+                        return persistence;
+                    // Streaming deltas remain observationally non-blocking, but their
+                    // persistence failure must be consumed so it cannot become an
+                    // unhandled rejection. A later critical event observes the
+                    // journal's failure latch and is awaited by the runtime.
+                    void persistence.catch(() => undefined);
+                    return undefined;
+                },
+            });
+            createdSession = session;
+            options.hydrate?.(session);
+            if (runtimeSnapshot && !options.snapshot && persisted) {
+                // Session-creation durability: a session must not become reachable
+                // unless its provider/model identity is durably recorded, or a restart
+                // could silently substitute the launcher's current default. Failure
+                // rolls the whole composition back in the catch below.
+                try {
+                    await writeSessionSnapshot(persisted.persistence.directory, {
+                        schemaVersion: 1,
+                        providerId: runtimeSnapshot.providerId,
+                        modelId: runtimeSnapshot.modelId,
+                        reasoningEffort: runtimeSnapshot.reasoningEffort,
                     });
                 }
-                const release = this.#lifecycle.registerWorker({ close: () => session.dispose() });
-                session.addDisposeHook(() => {
-                    release();
-                    this.#admission.remove(binding.sessionId);
-                    this.#sessions.delete(binding.sessionId);
+                catch {
+                    throw new GatewayPersistenceError('snapshot_unwritable', 'session provider/model snapshot could not be persisted');
+                }
+            }
+            if (persisted) {
+                this.#persisted.set(binding.sessionId, persisted);
+                session.addDisposeHook(async () => {
+                    await persisted.persistence.close();
                     this.#persisted.delete(binding.sessionId);
                     this.#interactionBindings.delete(binding.sessionId);
+                    this.#lastTurnIds.delete(binding.sessionId);
+                    await this.#config.persistence?.close(binding.sessionId, this.#shutdownInProgress ? 'interrupted' : 'closed');
                 });
-                this.#sessions.set(binding.sessionId, session);
-                await this.#audit.write(createSafeLogMetadata({
-                    operation: 'session_create',
-                    outcome: 'allowed',
-                    reasonCode: 'accepted',
-                    sessionId: binding.sessionId,
-                    workspaceId: binding.workspaceId,
-                    grantVersion: binding.grantVersion,
-                    access: binding.access,
-                    ...(correlationId ? { correlationId } : {}),
-                }));
-                return session;
             }
-            catch (error) {
+            const release = this.#lifecycle.registerWorker({ close: () => session.dispose() });
+            session.addDisposeHook(() => {
+                release();
+                this.#admission.remove(binding.sessionId);
+                this.#sessions.delete(binding.sessionId);
+                this.#persisted.delete(binding.sessionId);
+                this.#interactionBindings.delete(binding.sessionId);
+            });
+            this.#sessions.set(binding.sessionId, session);
+            session.service.setBackgroundSubagentEventSink((event) => {
+                const agentId = event.type === 'subagent_question'
+                    ? event.runId
+                    : event.type === 'subagent_completed'
+                        ? event.result.agentId
+                        : event.agentId;
+                if (event.type === 'subagent_started' && event.agentId && session.activeTurnId) {
+                    this.#childTurnIds.set(event.agentId, session.activeTurnId);
+                    this.#childRoles.set(event.agentId, event.role);
+                }
+                const turnId = agentId
+                    ? this.#childTurnIds.get(agentId) ?? session.activeTurnId ?? this.#lastTurnIds.get(binding.sessionId)
+                    : session.activeTurnId ?? this.#lastTurnIds.get(binding.sessionId);
+                if (turnId)
+                    void this.#persistConversationEvent(binding.sessionId, event, { turnId, discardedTurnIds: [] });
+            });
+            session.service.backgroundSubagentApprovals.subscribe(() => {
+                const current = session.service.backgroundSubagentApprovals.getSnapshot().current;
+                if (!current)
+                    return;
+                const turnId = this.#childTurnIds.get(current.runId);
+                if (!turnId)
+                    return;
+                void this.#persistConversationEvent(binding.sessionId, {
+                    type: 'subagent_approval_required',
+                    agentId: current.runId,
+                    role: this.#childRoles.get(current.runId) ?? 'subagent',
+                }, { turnId, discardedTurnIds: [] });
+            });
+            await this.#audit.write(createSafeLogMetadata({
+                operation: options.auditOperation,
+                outcome: 'allowed',
+                reasonCode: 'accepted',
+                sessionId: binding.sessionId,
+                workspaceId: binding.workspaceId,
+                grantVersion: binding.grantVersion,
+                access: binding.access,
+                ...(options.correlationId ? { correlationId: options.correlationId } : {}),
+            }));
+            return { session, persisted };
+        }
+        catch (error) {
+            // The runtime was created but the composition failed (snapshot
+            // durability, hydration, ...): dispose it before the persistence it
+            // may still write to.
+            if (createdSession) {
+                try {
+                    await createdSession.dispose();
+                }
+                catch {
+                    // Preserve the original composition failure.
+                }
+            }
+            // Roll the persistence handle back whoever opened it — composition
+            // opened it, or #ensurePersistedSession installed it before the failed
+            // restore. A failed restore must not leave an open handle in #persisted;
+            // the read path and the next revival reopen on demand.
+            if (persisted) {
                 try {
-                    await persisted?.persistence.close();
+                    await persisted.persistence.close();
                     await this.#config.persistence?.close(binding.sessionId, 'interrupted');
                 }
                 catch {
-                    // Preserve the admission failure; persistence keeps its evidence.
+                    // Preserve the original composition failure; persistence keeps its evidence.
                 }
+                this.#persisted.delete(binding.sessionId);
+            }
+            if (options.ownedBinding)
                 this.#admission.remove(binding.sessionId);
+            throw error;
+        }
+    }
+    /**
+     * Lazily revive a persisted session whose runtime died with a previous
+     * gateway process. Returns the live runtime, a specific gateway error for a
+     * refused revival (revoked grant, unavailable provider or model, resource
+     * limits), or null when there is nothing this gateway can restore — callers
+     * keep their legacy not-found/not-admitting behavior for null. Concurrent
+     * first revivals of one session share a single creation promise.
+     */
+    async #ensureLiveRuntime(ownerUserId, sessionId, correlationId) {
+        const existing = this.#sessions.get(sessionId);
+        const existingPersisted = this.#persisted.get(sessionId);
+        if (existing instanceof ServerSession) {
+            // Owner scoping holds on every return path, live or restored: a session
+            // owned by someone else does not exist for this caller.
+            if (existing.binding.ownerUserId !== ownerUserId)
+                return publicError(404, 'not_found', 'session not found');
+            if (existingPersisted)
+                return { session: existing, persisted: existingPersisted };
+        }
+        if (!this.#config.runtimeFactory || !this.#config.persistence)
+            return null;
+        // A persisted session owned by another caller is a 404 for this caller,
+        // not the legacy fallback: the index is owner-scoped for a reason. This
+        // also stops a foreign caller from latching onto an in-flight revival.
+        let foreign;
+        try {
+            foreign = this.#config.persistence.index.get(sessionId);
+        }
+        catch {
+            foreign = null;
+        }
+        if (foreign && foreign.ownerUserId !== ownerUserId)
+            return publicError(404, 'not_found', 'session not found');
+        const restoreKey = `${ownerUserId}\u0000${sessionId}`;
+        const guardOwner = (result) => {
+            if (result && 'session' in result && result.session.binding.ownerUserId !== ownerUserId)
+                return publicError(404, 'not_found', 'session not found');
+            return result;
+        };
+        const inflight = this.#sessionRestores.get(restoreKey);
+        if (inflight)
+            return inflight.then(guardOwner);
+        const restore = this.#restoreRuntime(ownerUserId, sessionId, correlationId);
+        this.#sessionRestores.set(restoreKey, restore);
+        restore.then(() => {
+            if (this.#sessionRestores.get(restoreKey) === restore)
+                this.#sessionRestores.delete(restoreKey);
+        }, () => {
+            // A rejected revival must clear the single-flight entry too, or the
+            // session would stay wedged forever; everyone awaiting the shared
+            // promise already holds the rejection, so swallow it here.
+            if (this.#sessionRestores.get(restoreKey) === restore)
+                this.#sessionRestores.delete(restoreKey);
+        });
+        return restore.then(guardOwner);
+    }
+    async #restoreRuntime(ownerUserId, sessionId, correlationId) {
+        try {
+            const index = this.#config.persistence.index;
+            let record;
+            try {
+                record = index.getForOwner(ownerUserId, sessionId);
+            }
+            catch (error) {
+                if (error instanceof GatewayPersistenceError && error.code === 'not_found')
+                    return null;
                 throw error;
             }
+            if (record.status === 'closed')
+                return null;
+            const grantVersion = Number(record.grantVersion);
+            if (!Number.isSafeInteger(grantVersion))
+                throw new GatewayPersistenceError('readonly', 'session grant version is invalid');
+            // The admission layer is the grant authority: manifest and restored
+            // dynamic grants, enabled state, and the workspace boundary probe all
+            // revalidate before any runtime exists. A revoked grant fails here with
+            // a typed admission error instead of a generic not-found.
+            const binding = this.#admission.restore(sessionId, ownerUserId, record.workspaceId, grantVersion);
+            const persisted = await this.#ensurePersistedSession(ownerUserId, sessionId);
+            const snapshot = await this.#restoredSessionSnapshot(persisted, binding);
+            if (snapshot && 'body' in snapshot)
+                return snapshot;
+            const unavailable = await this.#sessionSnapshotUnavailable(snapshot);
+            if (unavailable)
+                return unavailable;
+            if (this.#lifecycle.state !== 'running')
+                return publicError(503, 'gateway_unavailable', 'gateway is not accepting sessions', true);
+            const directory = this.#config.persistence?.layout.existingSessionPath(binding.ownerUserId, binding.workspaceId, binding.sessionId);
+            const composed = await this.#composeRuntimeBackedSession(binding, {
+                auditOperation: 'session_resume',
+                ownedBinding: false,
+                correlationId,
+                snapshot,
+                hydrate: (session) => {
+                    if (directory)
+                        hydrateConversationService(session.service, directory, binding.sessionId);
+                    // Revival is complete: the coarse index lifecycle returns to the
+                    // resting state a fresh session holds; live turn state stays in the
+                    // ServerSession. The interrupted turn stays interrupted in the
+                    // journal; the next turn is a normal turn.
+                    this.#config.persistence?.index.update(binding.sessionId, {
+                        status: 'idle',
+                        interruptedAt: null,
+                        recoveryWarning: null,
+                    });
+                },
+            });
+            return { session: composed.session, persisted };
+        }
+        catch (error) {
+            return this.#mapError(error);
+        }
+    }
+    /**
+     * The snapshot a restored session must come back on: the per-session
+     * provider/model recorded when the session was created. Sessions created
+     * before that record existed (or whose record is unreadable) fall back to
+     * the launcher's current snapshot; the fallback is documented and is still
+     * validated below, so it is never a silent substitution of an unavailable
+     * provider or model. Only the production stack (settings authority) has a
+     * snapshot to restore against; fixture gateways compose without one.
+     */
+    async #restoredSessionSnapshot(persisted, binding) {
+        const settings = this.#config.runtimeFactory?.settingsAuthority;
+        if (!settings)
+            return undefined;
+        const stored = await readSessionSnapshot(persisted.persistence.directory);
+        // Absent is the documented pre-change compatibility state; a record that
+        // exists but cannot be trusted is corruption and is refused — falling
+        // back would silently change the session's provider/model identity.
+        if (stored.state === 'corrupt')
+            return publicError(500, 'session_snapshot_invalid', 'persisted session snapshot is unreadable or malformed');
+        const allowWrite = this.#config.runtimeFactory?.allowWriteEnabled === true;
+        const effectiveAllowWrite = allowWrite && binding.access === 'read_write';
+        if (stored.state === 'absent')
+            return createSessionSettingsSnapshot({ settings, effectiveToolPolicy: { allowWrite: effectiveAllowWrite } });
+        return createSessionSettingsSnapshot({
+            settings,
+            providerId: stored.snapshot.providerId,
+            modelId: stored.snapshot.modelId,
+            reasoningEffort: stored.snapshot.reasoningEffort,
+            effectiveToolPolicy: { allowWrite: effectiveAllowWrite },
+        });
+    }
+    /**
+     * A restored session replays into the runtime built from its snapshot.
+     * Refuse instead of silently substituting when that snapshot's provider or
+     * model is no longer available. Only the production stack (settings
+     * authority + model catalog) can answer this; fixture gateways skip the
+     * check.
+     */
+    async #sessionSnapshotUnavailable(snapshot) {
+        const settings = this.#config.runtimeFactory?.settingsAuthority;
+        const catalog = this.#modelCatalog;
+        if (!settings || !catalog || !snapshot)
+            return null;
+        const providerId = String(snapshot.providerId);
+        if (!getAvailableProviderIds(settings, getProviderIds()).includes(providerId))
+            return publicError(409, 'provider_unavailable', 'session provider is no longer available');
+        let models;
+        try {
+            ({ models } = await catalog.load(providerId));
+        }
+        catch {
+            return publicError(503, 'model_catalog_unavailable', 'model catalog unavailable', true);
         }
+        if (!models.some((model) => model.id === snapshot.modelId))
+            return publicError(409, 'model_unavailable', 'session model is no longer available');
+        return null;
+    }
+    /** Legacy fixture composition without the production runtime factory. */
+    async #composeLegacyFixtureSession(_claims, options, binding, correlationId) {
         const providerProbe = this.#config.providerProbe;
         if (!providerProbe)
             throw new GatewayStartupError();
@@ -1378,6 +2278,17 @@ export class Term2Gateway {
         }));
         return session;
     }
+    /**
+     * Shutdown must not fail because its audit record could not be built or written, but
+     * losing an audit record is not silent: it goes to the launcher-supplied diagnostics
+     * sink when the launcher configured one.
+     */
+    #reportShutdownAuditFailure(error) {
+        this.#config.logger?.warn('gateway shutdown audit failed', {
+            errorCode: 'shutdown_audit_failed',
+            errorMessage: error instanceof Error ? error.message : String(error),
+        });
+    }
     async shutdown(graceMs = 5_000) {
         if (this.#shutdownPromise)
             return this.#shutdownPromise;
@@ -1413,14 +2324,36 @@ export class Term2Gateway {
             if (this.#config.runtimeFactory && !(await waitBounded(this.#config.runtimeFactory.shutdown(remaining()))))
                 markForced();
             this.#sessions.clear();
+            // Close persistence handles that outlived their session: read-path opens
+            // and compositions that failed before installing a dispose hook would
+            // otherwise keep file descriptors and locks past shutdown.
+            for (const [sessionId, persisted] of this.#persisted) {
+                try {
+                    await waitBounded(persisted.persistence.close());
+                    await waitBounded(this.#config.persistence?.close(sessionId, 'interrupted') ?? Promise.resolve());
+                }
+                catch {
+                    // Shutdown proceeds; the interrupted status is recorded in the index.
+                }
+            }
+            this.#persisted.clear();
             this.#replay.close();
-            // The audit record is bounded by the same deadline. A broken audit sink
-            // must not keep the local owner process alive indefinitely.
-            await waitBounded(this.#audit.write(createSafeLogMetadata({
-                operation: 'shutdown',
-                outcome: forced ? 'interrupted' : 'allowed',
-                reasonCode: forced ? 'forced_shutdown' : 'shutdown',
-            })));
+            // The audit record is bounded by the same deadline. A broken audit sink must not
+            // keep the local owner process alive indefinitely, and neither a synchronous
+            // build failure nor a rejected write may turn a finished shutdown into a
+            // rejection for the caller: the audit is best-effort, but never silent.
+            try {
+                await waitBounded(this.#audit
+                    .write(createSafeLogMetadata({
+                    operation: 'shutdown',
+                    outcome: forced ? 'interrupted' : 'allowed',
+                    reasonCode: forced ? 'forced_shutdown' : 'shutdown',
+                }))
+                    .catch((error) => this.#reportShutdownAuditFailure(error)));
+            }
+            catch (error) {
+                this.#reportShutdownAuditFailure(error);
+            }
         })();
         return this.#shutdownPromise;
     }
@@ -1461,7 +2394,7 @@ function matchPrivateRoute(method, pathname) {
         return { purpose: 'session_create' };
     if (method === 'GET' && pathname === '/private/agent/v1/sessions')
         return { purpose: 'session_list' };
-    const match = pathname.match(/^\/private\/agent\/v1\/sessions\/([A-Za-z0-9_-]{1,256})(?:\/(messages|abort|events|config|interactions\/([A-Za-z0-9_-]{1,256})))?$/);
+    const match = pathname.match(/^\/private\/agent\/v1\/sessions\/([A-Za-z0-9_-]{1,256})(?:\/(messages|abort|events|config|commands|interactions\/([A-Za-z0-9_-]{1,256})))?$/);
     if (!match)
         return null;
     const sessionId = match[1];
@@ -1475,6 +2408,8 @@ function matchPrivateRoute(method, pathname) {
         return { purpose: 'events_connect', sessionId };
     if (method === 'POST' && match[2] === 'config')
         return { purpose: 'session_update', sessionId };
+    if (method === 'POST' && match[2] === 'commands')
+        return { purpose: 'command_invoke', sessionId };
     if (method === 'POST' && match[2]?.startsWith('interactions/'))
         return { purpose: 'interaction_resolve', sessionId, interactionId: match[3] };
     return null;
@@ -1672,6 +2607,17 @@ function isTurnBody(body) {
         Object.keys(body).length === 1 &&
         isOpaqueId(body.turnId));
 }
+const COMMAND_ALLOWLIST = new Set(['compact', 'retry-tool', 'retry-turn']);
+function isCommandBody(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        return false;
+    const value = body;
+    return (Object.keys(value).length === 2 &&
+        typeof value.commandId === 'string' &&
+        value.commandId.length > 0 &&
+        value.commandId.length <= 256 &&
+        isOpaqueId(value.clientRequestId));
+}
 export function isInteractionResolveRequest(body) {
     if (!body || typeof body !== 'object' || Array.isArray(body))
         return false;
@@ -1721,7 +2667,9 @@ function isPublicEventEnvelope(event) {
     try {
         if (event.type === 'approval_required' ||
             event.type === 'interaction_updated' ||
-            event.type === 'interaction_recovered') {
+            event.type === 'interaction_recovered' ||
+            event.type === 'subagent_approval_required' ||
+            event.type === 'subagent_question') {
             if (!event.payload.interaction ||
                 typeof event.payload.interaction !== 'object' ||
                 !validatePendingInteractionDto(event.payload.interaction))
@@ -1758,6 +2706,98 @@ function isPublicEventEnvelope(event) {
 function boundedText(value, max = 8_192) {
     return typeof value === 'string' ? value.slice(0, max) : '';
 }
+function safeCounter(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0
+        ? Math.min(Math.floor(value), Number.MAX_SAFE_INTEGER)
+        : 0;
+}
+function boundedInteger(value, max) {
+    const number = safeCounter(value);
+    return Math.min(number, max);
+}
+function normalizedUsagePayload(usage) {
+    const inputTokens = safeCounter(usage.prompt_tokens);
+    const outputTokens = safeCounter(usage.completion_tokens);
+    return { inputTokens, outputTokens, totalTokens: safeCounter(usage.total_tokens) || inputTokens + outputTokens };
+}
+function commandStatus(value) {
+    switch (value) {
+        case 'pending':
+        case 'running':
+            return value;
+        case 'completed':
+            return 'completed';
+        case 'failed':
+            return 'failed';
+        case 'cancelled':
+        case 'interrupted':
+        case 'aborted':
+            return 'aborted';
+        case 'backgrounded':
+            return 'running';
+        default:
+            return null;
+    }
+}
+function commandMessagePayload(input) {
+    const message = input;
+    const callId = typeof message.callId === 'string' ? message.callId : '';
+    const toolName = typeof message.toolName === 'string' ? message.toolName : '';
+    const status = commandStatus(message.status);
+    if (!callId || !toolName || !status) {
+        malformedCommandMessageDrops = Math.min(malformedCommandMessageDrops + 1, 1_000_000);
+        return null;
+    }
+    return {
+        callId: boundedText(callId, 256),
+        toolName: boundedText(toolName, 256),
+        status,
+        ...(typeof message.output === 'string' ? { output: boundedText(message.output, 16_384) } : {}),
+        ...(typeof message.failureReason === 'string' ? { error: boundedText(message.failureReason, 10_000) } : {}),
+        message: {
+            id: boundedText(message.id, 256),
+            role: 'command',
+            text: boundedText(message.command, 16_384),
+        },
+    };
+}
+export function publicEventProjectionCounters() {
+    return Object.freeze({ malformedCommandMessageDrops });
+}
+function commandMessageCandidate(base, message, type) {
+    const projected = commandMessagePayload(message);
+    if (!projected)
+        return null;
+    return {
+        ...base,
+        type,
+        payload: { ...base.payload, ...projected },
+    };
+}
+function errorReason(kind) {
+    switch (kind) {
+        case 'provider':
+            return 'provider_error';
+        case 'network':
+            return 'network_error';
+        case 'rate_limit':
+            return 'rate_limit';
+        case 'authentication':
+            return 'authentication_error';
+        case 'cancelled':
+            return 'cancelled';
+        case 'validation':
+            return 'validation_error';
+        case 'compaction':
+            return 'compaction_failed';
+        case 'retry_exhausted':
+            return 'retry_exhausted';
+        case 'interaction_continuation_failed':
+            return 'interaction_continuation_failed';
+        default:
+            return 'runtime_error';
+    }
+}
 function interactionDtoFromApproval(approval, interactionId, revision) {
     return projectPendingInteraction(approval, interactionId, revision);
 }
@@ -1873,9 +2913,19 @@ function hasTerminalTurnEvent(events, turnId) {
 }
 function terminalTranscriptFact(event, turnId) {
     if (event.type === 'final') {
+        const finalText = boundedText(event.finalText, 16_384);
         const items = event.turnItems ? [...event.turnItems] : [];
-        if (!items.some((item) => item.type === 'assistant_text')) {
-            items.push({ type: 'assistant_text', text: boundedText(event.finalText, 16_384) });
+        const existingText = items.findIndex((item) => item.type === 'assistant_text');
+        if (existingText >= 0) {
+            // Derived turn items may carry an empty assistant_text entry when the
+            // stream produced no text parts; the terminal finalText is the
+            // authoritative text for the persisted turn.
+            const existing = items[existingText];
+            if (!existing.text && finalText)
+                items[existingText] = { ...existing, text: finalText };
+        }
+        else if (finalText) {
+            items.push({ type: 'assistant_text', text: finalText });
         }
         return { type: 'assistant_turn', turnId, turn: { items } };
     }
@@ -1888,7 +2938,7 @@ function terminalTranscriptFact(event, turnId) {
     }
     return null;
 }
-function mapConversationEvent(event, turnId, sessionId, interactionBinding, interactionSnapshot) {
+export function mapConversationEvent(event, turnId, sessionId, interactionBinding, interactionSnapshot) {
     const base = { sessionId, payload: { turnId } };
     switch (event.type) {
         // The gateway-owned assistant_started admission marker is appended before
@@ -1905,18 +2955,7 @@ function mapConversationEvent(event, turnId, sessionId, interactionBinding, inte
                 payload: { turnId, callId: event.toolCallId, toolName: boundedText(event.toolName, 256) },
             };
         case 'command_message':
-            return {
-                ...base,
-                type: 'command_message',
-                payload: {
-                    turnId,
-                    message: {
-                        id: boundedText(event.message.id, 256),
-                        role: boundedText(event.message.sender ?? event.message.role, 32),
-                        text: boundedText(event.message.text, 16_384),
-                    },
-                },
-            };
+            return commandMessageCandidate(base, event.message, 'command_message');
         case 'approval_required': {
             if (!interactionBinding)
                 return null;
@@ -1931,13 +2970,208 @@ function mapConversationEvent(event, turnId, sessionId, interactionBinding, inte
                 },
             };
         }
-        case 'usage_update':
+        case 'usage_update': {
+            const inputTokens = safeCounter(event.usage.prompt_tokens);
+            const outputTokens = safeCounter(event.usage.completion_tokens);
+            const totalTokens = safeCounter(event.usage.total_tokens) || inputTokens + outputTokens;
             return {
                 ...base,
                 type: 'usage_update',
                 payload: {
                     turnId,
-                    usage: { inputTokens: event.usage.prompt_tokens, outputTokens: event.usage.completion_tokens },
+                    inputTokens,
+                    outputTokens,
+                    totalTokens,
+                    usage: { inputTokens, outputTokens, totalTokens },
+                },
+            };
+        }
+        case 'retry':
+            return {
+                ...base,
+                type: 'retry',
+                payload: {
+                    turnId,
+                    ...(event.agentId ? { agentId: boundedText(event.agentId, 256) } : {}),
+                    toolName: boundedText(event.toolName, 256),
+                    attempt: boundedInteger(event.attempt, 512),
+                    maxRetries: boundedInteger(event.maxRetries, 512),
+                    errorMessage: boundedText(event.errorMessage),
+                    ...(event.retryType ? { retryType: event.retryType } : {}),
+                    ...(event.errorKind ? { errorKind: event.errorKind } : {}),
+                    ...(event.delayMs !== undefined ? { delayMs: boundedInteger(event.delayMs, 86_400_000) } : {}),
+                    ...(event.retryAfterMs !== undefined ? { retryAfterMs: boundedInteger(event.retryAfterMs, 86_400_000) } : {}),
+                },
+            };
+        case 'retry_exhausted':
+            return {
+                ...base,
+                type: 'retry_exhausted',
+                payload: {
+                    turnId,
+                    ...(event.provider ? { provider: boundedText(event.provider, 256) } : {}),
+                    errorKind: event.errorKind,
+                    attempts: boundedInteger(event.attempts, 512),
+                    maxAttempts: boundedInteger(event.maxAttempts, 512),
+                    message: boundedText(event.message),
+                    canRetry: event.canRetry,
+                },
+            };
+        case 'subagent_started':
+            return {
+                ...base,
+                type: 'subagent_started',
+                payload: {
+                    turnId,
+                    agentId: boundedText(event.agentId, 256),
+                    ...(event.name ? { name: boundedText(event.name, 256) } : {}),
+                    role: boundedText(event.role, 256),
+                    task: boundedText(event.task, 16_384),
+                    ...(event.async !== undefined ? { async: event.async } : {}),
+                },
+            };
+        case 'subagent_tool_started':
+            return {
+                ...base,
+                type: 'subagent_tool_started',
+                payload: {
+                    turnId,
+                    agentId: boundedText(event.agentId, 256),
+                    role: boundedText(event.role, 256),
+                    toolCallId: boundedText(event.toolCallId, 256),
+                    toolName: boundedText(event.toolName, 256),
+                    ...(event.commandMessages
+                        ? {
+                            commandMessages: event.commandMessages
+                                .slice(0, 64)
+                                .map((message) => commandMessagePayload(message))
+                                .filter(Boolean),
+                        }
+                        : {}),
+                },
+            };
+        case 'subagent_text_turn':
+            return {
+                ...base,
+                type: 'subagent_text_turn',
+                payload: {
+                    turnId,
+                    agentId: boundedText(event.agentId, 256),
+                    role: boundedText(event.role, 256),
+                    text: boundedText(event.text, 16_384),
+                },
+            };
+        case 'subagent_command_message':
+            return commandMessageCandidate({
+                ...base,
+                type: 'subagent_command_message',
+                payload: {
+                    turnId,
+                    agentId: boundedText(event.agentId, 256),
+                    role: boundedText(event.role, 256),
+                },
+            }, event.message, 'subagent_command_message');
+        case 'subagent_approval_required':
+            if (!interactionBinding)
+                return null;
+            return {
+                ...base,
+                type: 'subagent_approval_required',
+                payload: {
+                    turnId,
+                    agentId: boundedText(event.agentId, 256),
+                    role: boundedText(event.role, 256),
+                    interaction: interactionBinding.dto,
+                },
+            };
+        case 'subagent_completed': {
+            const result = event.result;
+            return {
+                ...base,
+                type: 'subagent_completed',
+                payload: {
+                    turnId,
+                    agentId: boundedText(result.agentId, 256),
+                    ...(result.name ? { name: boundedText(result.name, 256) } : {}),
+                    role: boundedText(result.role, 256),
+                    status: result.status,
+                    finalText: boundedText(result.finalText, 16_384),
+                    ...(result.finalTextTruncated !== undefined ? { finalTextTruncated: result.finalTextTruncated } : {}),
+                    toolsUsed: result.toolsUsed.slice(0, 64).map((tool) => ({
+                        toolName: boundedText(tool.toolName, 256),
+                        count: boundedInteger(tool.count, 1_000_000),
+                    })),
+                    ...(result.usage ? { usage: normalizedUsagePayload(result.usage) } : {}),
+                    ...(result.error ? { error: boundedText(result.error) } : {}),
+                    ...(result.terminalCause ? { terminalCause: boundedText(String(result.terminalCause), 128) } : {}),
+                    ...(event.async !== undefined ? { async: event.async } : {}),
+                },
+            };
+        }
+        case 'subagent_interrupted':
+            return {
+                ...base,
+                type: 'subagent_interrupted',
+                payload: {
+                    turnId,
+                    agentId: boundedText(event.agentId, 256),
+                    role: boundedText(event.role, 256),
+                    finalText: boundedText(event.finalText, 16_384),
+                },
+            };
+        case 'subagent_question':
+            return {
+                ...base,
+                type: 'subagent_question',
+                payload: {
+                    turnId,
+                    agentId: boundedText(event.runId, 256),
+                    runId: boundedText(event.runId, 256),
+                    messageId: boundedText(event.messageId, 256),
+                    role: boundedText(event.role, 256),
+                    ...(event.name ? { name: boundedText(event.name, 256) } : {}),
+                    question: boundedText(event.question),
+                    async: true,
+                    ...(interactionBinding ? { interaction: interactionBinding.dto } : {}),
+                },
+            };
+        case 'context_compaction_started':
+            return {
+                ...base,
+                type: 'context_compaction_started',
+                payload: {
+                    turnId,
+                    provider: boundedText(event.provider, 256),
+                    sessionId: boundedText(event.sessionId, 256),
+                    ...(event.inputTokensBefore !== undefined ? { inputTokensBefore: safeCounter(event.inputTokensBefore) } : {}),
+                    ...(event.strategy ? { strategy: event.strategy } : {}),
+                },
+            };
+        case 'context_compaction_completed':
+            return {
+                ...base,
+                type: 'context_compaction_completed',
+                payload: {
+                    turnId,
+                    provider: boundedText(event.provider, 256),
+                    sessionId: boundedText(event.sessionId, 256),
+                    ...(event.inputTokensBefore !== undefined ? { inputTokensBefore: safeCounter(event.inputTokensBefore) } : {}),
+                    ...(event.inputTokensAfter !== undefined ? { inputTokensAfter: safeCounter(event.inputTokensAfter) } : {}),
+                    durationMs: boundedInteger(event.durationMs, 86_400_000),
+                    ...(event.strategy ? { strategy: event.strategy } : {}),
+                },
+            };
+        case 'context_compaction_failed':
+            return {
+                ...base,
+                type: 'context_compaction_failed',
+                payload: {
+                    turnId,
+                    provider: boundedText(event.provider, 256),
+                    sessionId: boundedText(event.sessionId, 256),
+                    errorCategory: event.errorCategory,
+                    durationMs: boundedInteger(event.durationMs, 86_400_000),
+                    ...(event.strategy ? { strategy: event.strategy } : {}),
                 },
             };
         case 'final':
@@ -1947,7 +3181,16 @@ function mapConversationEvent(event, turnId, sessionId, interactionBinding, inte
                 payload: { turnId, outcome: 'completed', text: boundedText(event.finalText, 16_384) },
             };
         case 'error':
-            return { ...base, type: 'turn_failed', payload: { turnId, outcome: 'failed', reason: 'runtime_error' } };
+            return {
+                ...base,
+                type: 'turn_failed',
+                payload: {
+                    turnId,
+                    outcome: 'failed',
+                    reason: errorReason(event.kind),
+                    ...(event.finalText ? { finalText: boundedText(event.finalText, 16_384) } : {}),
+                },
+            };
         default:
             return null;
     }