@ours.network/fleet 1.1.0-nightly.9 → 1.1.1

package/dist/session/acp.js

@@ -1,5 +1,5 @@
 import { spawn } from 'node:child_process';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, lstatSync, readFileSync, readlinkSync, realpathSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { Readable, Writable } from 'node:stream';
@@ -7,7 +7,8 @@ import * as acp from '@agentclientprotocol/sdk';
 import { normalizeSessionUpdate } from './conversation-normalizer.js';
 import { ConversationEventStore } from './conversation-store.js';
 import { SessionEvents } from './events.js';
-import { ACP_CANCEL_DEADLINE_EXCEEDED, SessionControlError, classifyChildExit, turnResult, } from './types.js';
+import { DEFAULT_STALL_TIMEOUT_MS, STALL_RECOVERY_PROMPT, StallWatchdog, StallToolHistory, hasStallRecoveryClaim } from './stall-watchdog.js';
+import { ACP_CANCEL_DEADLINE_EXCEEDED, SessionControlError, classifyChildExit, sessionBackendCapabilities, turnResult, } from './types.js';
 const CANCEL_SETTLE_GRACE_MS = 15_000;
 const CANCEL_TERMINATE_GRACE_MS = 5_000;
 /** A permission no human answered is eventually a decision nobody made. */
@@ -158,6 +159,7 @@ function canonicallyWithin(root, candidates) {
 function conversationSource(origin) {
     switch (origin?.kind) {
         case 'owner-admin-console': return { source: 'owner_admin_console', persistBody: true };
+        case 'stall-watchdog': return { source: 'fleet_monitor', persistBody: false };
         case 'startup': return { source: 'startup', persistBody: true };
         case 'owner': return { source: 'owner_channel', persistBody: false };
         case 'fleet-monitor': return { source: 'fleet_monitor', persistBody: false };
@@ -187,6 +189,12 @@ export function runtimeSelector(options, category) {
     const selected = choices.find(choice => choice.value === option.currentValue);
     return { value: option.currentValue, ...(selected?.name ? { label: selected.name } : {}) };
 }
+function reasoningFromModelId(modelId) {
+    if (typeof modelId !== 'string')
+        return undefined;
+    const match = modelId.match(/\[([^\]]+)\]$/u);
+    return match?.[1] ? { value: match[1] } : undefined;
+}
 /**
  * Classify an ACP `stopReason` into a terminal outcome. A refusal and a
  * cancellation are the two ways a delivered prompt ends without being carried
@@ -206,6 +214,7 @@ export function classifyStopReason(stopReason) {
 export class AcpSession {
     options;
     backend = 'acp';
+    capabilities;
     pid;
     child;
     events;
@@ -232,7 +241,7 @@ export class AcpSession {
     queueDepth = 0;
     exit = null;
     steeringSupported = false;
-    capabilities;
+    agentCapabilities;
     runtimeModel;
     reasoningEffort;
     controllerCount = 0;
@@ -258,6 +267,15 @@ export class AcpSession {
     terminate;
     /** ACP-authenticated in-flight calls, including independently reserved permissions. */
     activeToolCalls = new Map();
+    stallWatchdog;
+    stallToolHistory;
+    stallRecoveryClaimed = false;
+    managedTurnCount = 0;
+    steeringWasUsed = false;
+    steeringRequests = 0;
+    retryNativeTurnId;
+    stallTimer;
+    stallAttempt;
     toolBoundaryWaiters = new Set();
     activeTurn;
     constructor(options, child, connection) {
@@ -265,6 +283,7 @@ export class AcpSession {
         this.child = child;
         this.connection = connection;
         this.pid = child.pid ?? -1;
+        this.capabilities = sessionBackendCapabilities('acp', options.harness);
         this.events = new SessionEvents(join(options.stateDir, '.session-events.jsonl'));
         this.conversation = new ConversationEventStore(join(options.stateDir, '.conversation'), {
             roleId: options.name, log: line => options.log(`[${options.name}] ${line}`),
@@ -277,6 +296,9 @@ export class AcpSession {
         this.terminated.catch(() => undefined);
         child.stderr.on('data', chunk => options.log(`[${options.name}] acp: ${String(chunk).trimEnd()}`));
         child.once('exit', (code, signal) => {
+            if (this.stallTimer)
+                clearInterval(this.stallTimer);
+            this.stallTimer = undefined;
             if (this.cancelForceKill)
                 clearTimeout(this.cancelForceKill);
             this.cancelForceKill = undefined;
@@ -333,7 +355,8 @@ export class AcpSession {
         let instance;
         const app = acp.client({ name: 'ours-fleet' })
             .onNotification(acp.methods.client.session.update, ({ params }) => {
-            instance?.recordUpdate(params.update);
+            if (instance && (!instance.sessionId || params.sessionId === instance.sessionId))
+                instance.recordUpdate(params.update);
         })
             .onRequest(acp.methods.client.session.requestPermission, ({ params }) => {
             if (!instance)
@@ -345,6 +368,7 @@ export class AcpSession {
         instance = new AcpSession(options, child, connection);
         try {
             await instance.initialize();
+            instance.startStallWatchdog();
             instance.recoverOpenPrompts();
             return instance;
         }
@@ -463,10 +487,14 @@ export class AcpSession {
     reserveTool(toolCallId) {
         if (toolCallId)
             this.toolCall(toolCallId).lifecycle = true;
+        else if (this.activeTurn)
+            this.activeTurn.boundaryUnknown = true;
     }
     reservePermission(toolCallId, permissionId) {
         if (toolCallId)
             this.toolCall(toolCallId).permissions.set(permissionId, 'pending');
+        else if (this.activeTurn)
+            this.activeTurn.boundaryUnknown = true;
     }
     allowPermission(toolCallId, permissionId) {
         if (!toolCallId)
@@ -551,6 +579,8 @@ export class AcpSession {
      * steering response from becoming a tight replay loop.
      */
     async steerOrQueueWake(text, options) {
+        if (this.stallRecoveryClaimed)
+            return this.submitPrompt(text, { ...options, interrupt: false, steer: false });
         const steered = await this.steerPrompt(text);
         if (steered.accepted || steered.detail !== 'ACP steering failed'
             || this.closing || !this.isAlive())
@@ -614,6 +644,8 @@ export class AcpSession {
      * for it is what turned a busy agent into a timeout and then into "dead".
      */
     async queuePrompt(text, options = {}) {
+        if (this.stallRecoveryClaimed && options.origin?.kind === 'fleet-monitor')
+            options = { ...options, interrupt: false, steer: false };
         if (this.cancelRecoveryReason)
             throw new SessionControlError('control-unavailable', 'ACP adapter restart is in progress after the cancellation deadline', ACP_CANCEL_DEADLINE_EXCEEDED);
         if (this.closing || !this.sessionId || !this.isAlive())
@@ -773,6 +805,8 @@ export class AcpSession {
         }
     }
     async cancelActive(source) {
+        if (this.stallAttempt && source !== 'stall-watchdog' && source !== 'fleet-monitor')
+            this.stallAttempt.superseded = true;
         if (!this.sessionId)
             return;
         const active = this.activeTurn;
@@ -981,6 +1015,11 @@ export class AcpSession {
     }
     async close() {
         this.closing = true;
+        if (this.stallTimer)
+            clearInterval(this.stallTimer);
+        this.stallTimer = undefined;
+        if (this.stallAttempt)
+            this.stallAttempt.superseded = true;
         if (this.cancelEscalation)
             clearTimeout(this.cancelEscalation);
         this.cancelEscalation = undefined;
@@ -994,7 +1033,7 @@ export class AcpSession {
         for (const [permissionId, pending] of [...this.pendingPermissions])
             this.settlePendingAutomatically(permissionId, pending, 'cancelled', undefined, 'the session closed while this request was pending');
         this.releaseAllTools();
-        if (this.sessionId && this.capabilities?.sessionCapabilities?.close != null) {
+        if (this.sessionId && this.agentCapabilities?.sessionCapabilities?.close != null) {
             await this.connection.agent.request(acp.methods.agent.session.close, { sessionId: this.sessionId }).catch(() => undefined);
         }
         this.connection.close();
@@ -1020,7 +1059,7 @@ export class AcpSession {
         });
         if (initialized.protocolVersion !== acp.PROTOCOL_VERSION)
             throw new Error(`ACP protocol mismatch: agent selected ${initialized.protocolVersion}, client supports ${acp.PROTOCOL_VERSION}`);
-        this.capabilities = initialized.agentCapabilities;
+        this.agentCapabilities = initialized.agentCapabilities;
         const steering = initialized._meta?.steering;
         this.steeringSupported = steering !== null && typeof steering === 'object'
             && steering.supported === true;
@@ -1028,17 +1067,19 @@ export class AcpSession {
             ? readFileSync(this.sessionFile, 'utf8').trim()
             : '';
         let advertisedConfigOptions;
-        if (persisted && this.capabilities?.sessionCapabilities?.resume != null) {
+        let advertisedModelId;
+        if (persisted && this.agentCapabilities?.sessionCapabilities?.resume != null) {
             const resumed = await this.connection.agent.request(acp.methods.agent.session.resume, {
                 sessionId: persisted,
                 cwd: this.options.cwd,
                 mcpServers: this.declaredMcpServers(),
             });
             advertisedConfigOptions = resumed.configOptions;
-            this.captureRuntimeMetadata(advertisedConfigOptions);
+            advertisedModelId = resumed.models?.currentModelId;
+            this.captureRuntimeMetadata(advertisedConfigOptions, advertisedModelId);
             this.sessionId = persisted;
         }
-        else if (persisted && this.capabilities?.loadSession) {
+        else if (persisted && this.agentCapabilities?.loadSession) {
             // `session/load` replays prior history as ordinary updates before the
             // response; those records carry `agent_replay` provenance, never `agent`.
             this.replaying = true;
@@ -1049,7 +1090,8 @@ export class AcpSession {
                     mcpServers: this.declaredMcpServers(),
                 });
                 advertisedConfigOptions = loaded.configOptions;
-                this.captureRuntimeMetadata(advertisedConfigOptions);
+                advertisedModelId = loaded.models?.currentModelId;
+                this.captureRuntimeMetadata(advertisedConfigOptions, advertisedModelId);
             }
             finally {
                 this.replaying = false;
@@ -1064,11 +1106,16 @@ export class AcpSession {
             });
             this.sessionId = created.sessionId;
             advertisedConfigOptions = created.configOptions;
-            this.captureRuntimeMetadata(advertisedConfigOptions);
+            advertisedModelId = created.models?.currentModelId;
+            this.captureRuntimeMetadata(advertisedConfigOptions, advertisedModelId);
         }
         for (const selection of this.options.configSelections ?? []) {
-            if (!advertisedConfigOptions?.some(option => option.id === selection.configId))
+            if (!advertisedConfigOptions?.some(option => option.id === selection.configId)) {
+                if (selection.configId === 'reasoning_effort'
+                    && reasoningFromModelId(advertisedModelId)?.value === selection.value)
+                    continue;
                 throw new Error(`ACP agent did not advertise required session config option '${selection.configId}'`);
+            }
             let configured;
             try {
                 configured = await this.connection.agent.request(acp.methods.agent.session.setConfigOption, { sessionId: this.sessionId, configId: selection.configId, value: selection.value });
@@ -1078,7 +1125,7 @@ export class AcpSession {
                     + (error instanceof Error ? error.message : String(error)));
             }
             advertisedConfigOptions = configured.configOptions;
-            this.captureRuntimeMetadata(advertisedConfigOptions);
+            this.captureRuntimeMetadata(advertisedConfigOptions, advertisedModelId);
             const applied = advertisedConfigOptions.find(option => option.id === selection.configId);
             if (applied?.currentValue !== selection.value)
                 throw new Error(`ACP agent did not apply required session config option '${selection.configId}' value '${selection.value}'`);
@@ -1110,17 +1157,162 @@ export class AcpSession {
             acpSessionId: this.sessionId, payload: { status: 'idle' },
         });
     }
-    captureRuntimeMetadata(options) {
+    captureRuntimeMetadata(options, modelId) {
         this.runtimeModel = runtimeSelector(options, 'model');
-        this.reasoningEffort = runtimeSelector(options, 'thought_level');
+        this.reasoningEffort = runtimeSelector(options, 'thought_level') ?? reasoningFromModelId(modelId);
+    }
+    startStallWatchdog() {
+        if (!this.options.stallRecovery)
+            return;
+        const timeoutMs = this.options.stallRecovery.timeoutMs ?? DEFAULT_STALL_TIMEOUT_MS;
+        this.stallRecoveryClaimed = hasStallRecoveryClaim(this.options.stateDir, this.sessionId);
+        this.stallToolHistory = new StallToolHistory(this.options.stateDir, this.sessionId, this.options.mode === 'resume');
+        this.stallWatchdog = new StallWatchdog({
+            stateDir: this.options.stateDir, timeoutMs, previouslyClaimed: this.stallRecoveryClaimed, now: () => Date.now(),
+            observe: () => this.stallObservation(),
+            recover: (observed, report) => this.recoverStall(observed, report),
+            diagnostic: diagnostic => {
+                if (['interrupt_requested', 'blocked_previous_attempt', 'blocked_persistence'].includes(diagnostic.status))
+                    this.stallRecoveryClaimed = true;
+                this.events.emit('stall_recovery', { status: diagnostic.status, stallDiagnostic: diagnostic });
+                this.options.log(`[${this.options.name}] ACP stall recovery: ${diagnostic.status}; `
+                    + 'inspect structured session events before continuing; never replay uncertain side effects');
+            },
+        });
+        this.stallTimer = setInterval(() => this.checkStallWatchdog(), this.options.stallRecovery.tickMs ?? Math.min(10_000, timeoutMs));
+        this.stallTimer.unref?.();
+    }
+    checkStallWatchdog() {
+        void this.stallWatchdog?.tick();
+        const attempt = this.stallAttempt;
+        if (attempt?.recoveryStartedAt === undefined || attempt.blocked || attempt.superseded)
+            return;
+        const observed = this.stallObservation();
+        if (!observed?.safe || observed.turnId !== attempt.recoveryId)
+            return;
+        const last = observed.lastProgressAt || attempt.recoveryStartedAt;
+        const timeoutMs = this.options.stallRecovery?.timeoutMs ?? DEFAULT_STALL_TIMEOUT_MS;
+        if (Date.now() - last >= timeoutMs * 2) {
+            attempt.blocked = true;
+            try {
+                attempt.report('blocked_restall');
+            }
+            catch { /* durable claim already prevents retry */ }
+        }
+    }
+    stallObservation() {
+        const active = this.activeTurn;
+        if (!active || !this.sessionId)
+            return undefined;
+        return {
+            sessionId: this.sessionId, generation: this.sessionGeneration, turnId: active.id,
+            startedAt: active.startedAt, lastProgressAt: active.lastProgressAt, progressCount: active.progressCount,
+            transportFailures: active.transportFailures,
+            boundaryEvidenceAvailable: this.stallToolHistory?.available() !== false,
+            safe: this.isAlive() && !this.closing && this.readiness === 'running'
+                && !active.cancellationSource && !active.boundaryUnknown && !this.steeringOccupied
+                && this.steeringRequests === 0 && this.stallToolHistory?.available() !== false
+                && this.activeToolCalls.size === 0 && this.pendingPermissions.size === 0,
+        };
+    }
+    async recoverStall(observed, report) {
+        const current = this.stallObservation();
+        if (!current?.safe || current.turnId !== observed.turnId
+            || current.lastProgressAt !== observed.lastProgressAt || current.progressCount !== observed.progressCount) {
+            report('superseded');
+            return;
+        }
+        const active = this.activeTurn;
+        let resolveReady;
+        const ready = new Promise(resolve => { resolveReady = resolve; });
+        const attempt = this.stallAttempt = {
+            turnId: active.id, recoveryId: randomUUID(), ready, superseded: false,
+            report, resumed: false, blocked: false,
+        };
+        active.cancellationSource = 'stall-watchdog';
+        // This intentionally does not use cancelActive: automatic recovery may
+        // never enter its SIGTERM/SIGKILL escalation or settle a permission.
+        let timer;
+        try {
+            const completed = await Promise.race([
+                (async () => {
+                    await this.connection.agent.notify(acp.methods.agent.session.cancel, { sessionId: this.sessionId });
+                    await active.settled;
+                    return true;
+                })(),
+                new Promise(resolve => {
+                    timer = setTimeout(() => resolve(false), this.options.stallRecovery?.cancelWaitMs ?? CANCEL_SETTLE_GRACE_MS);
+                    timer.unref?.();
+                }),
+            ]);
+            if (!completed || attempt.superseded || this.closing || !this.isAlive()) {
+                attempt.blocked = true;
+                report(attempt.superseded || this.closing ? 'superseded' : 'blocked_cancel');
+                resolveReady(false);
+            }
+            else
+                resolveReady(true);
+        }
+        catch {
+            attempt.blocked = true;
+            try {
+                report('blocked_cancel');
+            }
+            finally {
+                resolveReady(false);
+            }
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
     }
+    /** Keep the original queue slot (including startup) until recovery finishes. */
     async runPrompt(text, turnId = randomUUID(), origin) {
+        const result = await this.runSinglePrompt(text, turnId, origin);
+        const attempt = this.stallAttempt;
+        if (!attempt || attempt.turnId !== turnId)
+            return result;
+        const ready = await attempt.ready;
+        if (attempt.superseded || this.closing)
+            return result;
+        if (!ready || result.outcome !== 'cancelled' || result.cancellationSource !== 'stall-watchdog') {
+            // An RPC error/refusal/ambiguous terminal answer to cancellation is not
+            // permission to replay work or to fail startup and restart the process.
+            if (!attempt.blocked) {
+                attempt.blocked = true;
+                try {
+                    attempt.report('blocked_cancel');
+                }
+                catch { /* claim remains durable */ }
+            }
+            return turnResult(true, 'cancelled', 'diagnostic cancellation requires operator attention', undefined, 'stall-watchdog');
+        }
+        try {
+            attempt.report('recovery_started');
+            attempt.recoveryStartedAt = Date.now();
+            const recoveryOrigin = origin?.kind === 'scheduled-loop'
+                ? origin : { kind: 'stall-watchdog' };
+            this.admitToLedger(attempt.recoveryId, STALL_RECOVERY_PROMPT, 0, { origin: recoveryOrigin });
+            const recovered = await this.runSinglePrompt(STALL_RECOVERY_PROMPT, attempt.recoveryId, recoveryOrigin);
+            attempt.report(attempt.superseded ? 'superseded'
+                : recovered.succeeded && attempt.resumed ? 'recovery_completed' : 'blocked_recovery');
+            // A failed diagnostic turn must not make startup tear down the session.
+            return recovered.succeeded && attempt.resumed ? recovered : turnResult(true, 'cancelled', 'diagnostic recovery requires operator attention', undefined, 'stall-watchdog');
+        }
+        catch {
+            return turnResult(true, 'cancelled', 'diagnostic recovery requires operator attention', undefined, 'stall-watchdog');
+        }
+    }
+    async runSinglePrompt(text, turnId = randomUUID(), origin) {
         if (!this.sessionId || !this.isAlive())
             return turnResult(false, 'failed', this.lastError ?? 'ACP session is offline');
         this.readiness = 'running';
+        this.managedTurnCount++;
+        this.retryNativeTurnId = undefined;
         let settle;
         const settled = new Promise(resolve => { settle = resolve; });
-        this.activeTurn = { id: turnId, output: '', origin, settled, settle };
+        this.activeTurn = { toolEvidence: new Map(), startedAt: Date.now(), toolIds: new Set(), lastProgressAt: 0, progressCount: 0, transportFailures: 0, boundaryUnknown: false, id: turnId, output: '', origin, settled, settle };
         this.events.emit('state', { turnId, status: 'running', origin });
         this.conversation.appendSafe({
             kind: 'prompt.started', sessionGeneration: this.sessionGeneration,
@@ -1164,7 +1356,8 @@ export class AcpSession {
             this.lastError = origin?.kind === 'scheduled-loop' ? 'scheduled-loop turn failed' : detail;
             this.readiness = this.isAlive() ? 'idle' : 'failed';
             this.events.emit('error', {
-                turnId, origin,
+                turnId, origin: this.activeTurn?.cancellationSource === 'stall-watchdog'
+                    ? { kind: 'stall-watchdog' } : origin,
                 text: origin?.kind === 'scheduled-loop' ? 'scheduled-loop turn failed' : this.lastError,
             });
             if (this.isAlive())
@@ -1192,8 +1385,10 @@ export class AcpSession {
         }
     }
     async steerPrompt(text) {
+        this.steeringWasUsed = true;
         if (!this.sessionId || !this.isAlive())
             return turnResult(false, 'failed', this.lastError ?? 'ACP session is offline');
+        this.steeringRequests++;
         try {
             const response = await Promise.race([
                 this.connection.agent.request('_session/steering', {
@@ -1218,6 +1413,9 @@ export class AcpSession {
             this.events.emit('error', { text: detail });
             return turnResult(false, 'failed', detail);
         }
+        finally {
+            this.steeringRequests--;
+        }
     }
     requestPermission(params) {
         // `kinds` is a PRIORITY order. Scanning the agent's option array instead
@@ -1393,6 +1591,48 @@ export class AcpSession {
             && params.options.some(option => option.optionId === 'allow_once' && option.kind === 'allow_once')
             && params.options.some(option => option.optionId === 'decline' && option.kind === 'reject_once');
     }
+    /** Pinned codex-acp 1.1.7 structured metadata, never stderr or assistant text. */
+    recordStallMetadata(update) {
+        if (this.options.permissionMetadataSource !== 'codex-acp'
+            || update.sessionUpdate !== 'session_info_update' || !this.activeTurn)
+            return;
+        const meta = update._meta?.codex;
+        if (!meta || typeof meta !== 'object' || Array.isArray(meta))
+            return;
+        const codex = meta;
+        const status = codex.threadStatus;
+        if (Object.prototype.hasOwnProperty.call(codex, 'threadStatus')) {
+            const value = status && typeof status === 'object' && !Array.isArray(status)
+                ? status : {};
+            // Unknown or modal thread status is a permanent conservative fence for
+            // this turn. A later delayed idle/active status must not clear it.
+            if (value.type !== 'active' || !Array.isArray(value.activeFlags)
+                || value.activeFlags.length > 0)
+                this.activeTurn.boundaryUnknown = true;
+        }
+        const error = codex.error;
+        if (!error || typeof error !== 'object' || Array.isArray(error))
+            return;
+        const value = error;
+        const info = value.codexErrorInfo;
+        if (value.willRetry !== true || typeof value.turnId !== 'string' || !value.turnId
+            || !info || typeof info !== 'object' || Array.isArray(info))
+            return;
+        if (!['responseStreamConnectionFailed', 'responseStreamDisconnected']
+            .some(key => Object.prototype.hasOwnProperty.call(info, key)))
+            return;
+        // ACP 1.1.7 does not expose a native-turn-to-prompt mapping. Only the first
+        // fresh managed turn with no steering can be correlated without guessing;
+        // later/resumed turns retain the conservative generic no-progress path.
+        if (this.options.mode !== 'fresh' || this.managedTurnCount !== 1 || this.steeringWasUsed)
+            return;
+        if (this.retryNativeTurnId && this.retryNativeTurnId !== value.turnId) {
+            this.activeTurn.boundaryUnknown = true;
+            return;
+        }
+        this.retryNativeTurnId = value.turnId;
+        this.activeTurn.transportFailures++;
+    }
     recordUpdate(update) {
         // Replayed history is not current activity: `session/load` would otherwise
         // make a cold session look like it had just been working. The same reason
@@ -1402,6 +1642,53 @@ export class AcpSession {
             this.lastUpdateAt = new Date().toISOString();
             this.refreshSteeringOccupancy();
         }
+        if (!this.replaying && this.activeTurn) {
+            this.recordStallMetadata(update);
+            const active = this.activeTurn;
+            const kind = update.sessionUpdate;
+            if (this.options.stallRecovery && (kind === 'tool_call' || kind === 'tool_call_update')) {
+                if (!update.toolCallId || active.toolIds.size >= 4096)
+                    active.boundaryUnknown = true;
+                else
+                    active.toolIds.add(update.toolCallId);
+                if (this.stallToolHistory?.observe(update.toolCallId, active.id) === false)
+                    active.boundaryUnknown = true;
+            }
+            let meaningful = ((kind === 'agent_message_chunk' || kind === 'agent_thought_chunk')
+                && (update.content.type !== 'text' || update.content.text.length > 0))
+                || kind === 'tool_call' || kind === 'tool_call_update' || kind === 'plan';
+            if (this.options.stallRecovery && (kind === 'tool_call' || kind === 'tool_call_update' || kind === 'plan')) {
+                const fingerprint = createHash('sha256').update(JSON.stringify(update)).digest('hex');
+                if (kind === 'plan') {
+                    meaningful = fingerprint !== active.planEvidence;
+                    active.planEvidence = fingerprint;
+                }
+                else if (active.toolEvidence.size < 4096 || active.toolEvidence.has(update.toolCallId)) {
+                    meaningful = fingerprint !== active.toolEvidence.get(update.toolCallId);
+                    active.toolEvidence.set(update.toolCallId, fingerprint);
+                }
+            }
+            if (this.options.stallRecovery && ![
+                'agent_message_chunk', 'agent_thought_chunk', 'tool_call', 'tool_call_update', 'plan',
+                'available_commands_update', 'current_mode_update', 'config_option_update', 'session_info_update', 'usage_update',
+            ].includes(kind))
+                active.boundaryUnknown = true;
+            if (meaningful) {
+                active.lastProgressAt = Date.now();
+                active.progressCount++;
+                active.transportFailures = 0;
+                const attempt = this.stallAttempt;
+                if (attempt?.recoveryId === active.id && !attempt.resumed) {
+                    attempt.resumed = true;
+                    try {
+                        attempt.report('progress_resumed');
+                    }
+                    catch {
+                        attempt.blocked = true;
+                    }
+                }
+            }
+        }
         const scheduled = this.activeTurn?.origin?.kind === 'scheduled-loop';
         const messagePhase = update.sessionUpdate === 'agent_message_chunk'
             ? this.codexMessagePhase(update) : undefined;
@@ -1459,6 +1746,9 @@ export class AcpSession {
                     this.releaseTool(update.toolCallId);
                 else if (update.status !== undefined)
                     this.reserveTool(update.toolCallId);
+                else if (this.options.stallRecovery && this.activeTurn
+                    && !this.activeToolCalls.has(update.toolCallId))
+                    this.activeTurn.boundaryUnknown = true;
                 break;
             default:
                 break;

package/dist/session/arbiter.d.ts

@@ -17,8 +17,9 @@ export type ScheduledAttempt = {
  */
 export declare class RoleTurnArbiter implements AgentSession {
     private readonly session;
-    readonly backend: "acp";
+    readonly backend: import("../config.js").SessionBackendId;
     readonly pid: number;
+    readonly capabilities: import("./types.js").AgentSessionCapabilities | undefined;
     private tail;
     private unsettled;
     private stopping;

package/dist/session/arbiter.js

@@ -25,6 +25,7 @@ export class RoleTurnArbiter {
     session;
     backend;
     pid;
+    capabilities;
     tail = Promise.resolve();
     unsettled = 0;
     stopping = false;
@@ -36,6 +37,7 @@ export class RoleTurnArbiter {
         this.session = session;
         this.backend = session.backend;
         this.pid = session.pid;
+        this.capabilities = session.capabilities;
     }
     /**
      * Waiters race the tail against their own generation's retirement, so a

package/dist/session/codex-app-server-transport.d.ts

@@ -0,0 +1,53 @@
+import { type ChildProcessWithoutNullStreams } from 'node:child_process';
+import type { ExitRecord } from './types.js';
+type JsonObject = Record<string, unknown>;
+type RequestId = string | number;
+export interface CodexAppServerTransportOptions {
+    name: string;
+    argv: string[];
+    cwd: string;
+    env: Record<string, string>;
+    log(line: string): void;
+    requestTimeoutMs?: number;
+    onNotification?(method: string, params: JsonObject): void;
+    onRequest?(method: string, id: RequestId, params: JsonObject): void;
+    onExit?(exit: ExitRecord): void;
+}
+export interface CodexAppServerConnection {
+    readonly pid: number;
+    readonly child: Pick<ChildProcessWithoutNullStreams, 'kill'>;
+    isAlive(): boolean;
+    exitResult(): ExitRecord | null;
+    request<T = unknown>(method: string, params?: JsonObject, timeoutMs?: number): Promise<T>;
+    notify(method: string, params?: JsonObject): void;
+    respond(id: RequestId, result: unknown): void;
+    respondError(id: RequestId, code: number, message: string): void;
+    close(): Promise<void>;
+}
+export type CodexAppServerTransportFactory = (options: CodexAppServerTransportOptions) => Promise<CodexAppServerConnection>;
+/** Minimal, version-tolerant JSONL client for Codex app-server's stdio transport. */
+export declare class CodexAppServerTransport implements CodexAppServerConnection {
+    private readonly options;
+    readonly child: ChildProcessWithoutNullStreams;
+    readonly pid: number;
+    private nextId;
+    private readonly pending;
+    private readonly requestTimeoutMs;
+    private readonly exited;
+    private resolveExited;
+    private closed;
+    private exit;
+    private constructor();
+    static start(options: CodexAppServerTransportOptions): Promise<CodexAppServerTransport>;
+    isAlive(): boolean;
+    exitResult(): ExitRecord | null;
+    request<T = unknown>(method: string, params?: JsonObject, timeoutMs?: number): Promise<T>;
+    notify(method: string, params?: JsonObject): void;
+    respond(id: RequestId, result: unknown): void;
+    respondError(id: RequestId, code: number, message: string): void;
+    close(): Promise<void>;
+    private waitForExit;
+    private write;
+    private receive;
+}
+export {};