@leanandmean/coding-agent 0.74.1-scramjet.53 → 0.74.1-scramjet.55

package/dist/core/agent-session.js

@@ -18,6 +18,7 @@ import { basename, dirname, resolve } from "node:path";
 // acknowledgement key (#341).
 import { generateHarnessToolCallId } from "@leanandmean/agent";
 import { clampThinkingLevel, cleanupSessionResources, flattenSystemPrompt, getSupportedThinkingLevels, isContextOverflow, modelsAreEqual, resetApiProviders, } from "@leanandmean/ai";
+import { validateResponsesProviderFailure } from "@leanandmean/ai/openai-responses";
 import { theme } from "../modes/interactive/theme/theme.js";
 import { stripFrontmatter } from "../utils/frontmatter.js";
 import { sleep } from "../utils/sleep.js";
@@ -59,6 +60,33 @@ export function parseSkillBlock(text) {
 // ============================================================================
 /** Standard thinking levels */
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high"];
+function createDeferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    promise.catch(() => { });
+    return { promise, resolve, reject, settled: false };
+}
+function resolveDeferred(deferred, value) {
+    if (deferred.settled)
+        return false;
+    deferred.settled = true;
+    deferred.resolve(value);
+    return true;
+}
+function rejectDeferred(deferred, error) {
+    if (deferred.settled)
+        return false;
+    deferred.settled = true;
+    deferred.reject(error);
+    return true;
+}
+function settleDeferred(deferred, error) {
+    return error ? rejectDeferred(deferred, error) : resolveDeferred(deferred, undefined);
+}
 export class AgentSession {
     agent;
     sessionManager;
@@ -92,11 +120,12 @@ export class AgentSession {
     // Branch summarization state
     _branchSummaryAbortController = undefined;
     // Retry state
-    _retryAbortController = undefined;
-    _retryAttempt = 0;
+    _retry = undefined;
     _runRetryCount = 0;
-    _retryPromise = undefined;
-    _retryResolve = undefined;
+    _activeAgentRunSettlement = undefined;
+    _pendingAgentRunStart = undefined;
+    _unsettledAgentRuns = new Set();
+    _unsettledRetryChains = new Set();
     // Bash execution state
     _bashAbortController = undefined;
     _pendingBashMessages = [];
@@ -268,20 +297,17 @@ export class AgentSession {
             followUp: [...this._followUpMessages],
         });
     }
-    // Track last assistant message for auto-compaction check
-    _lastAssistantMessage = undefined;
     /** Internal handler for agent events - shared by subscribe and reconnect */
     _handleAgentEvent = (event) => {
         this._captureOutputThroughput(event);
-        // Create retry promise synchronously before queueing async processing.
-        // Agent.emit() calls this handler synchronously, and prompt() calls waitForRetry()
-        // as soon as agent.prompt() resolves. If _retryPromise is created only inside
-        // _processAgentEvent, slow earlier queued events can delay agent_end processing
-        // and waitForRetry() can miss the in-flight retry.
-        this._createRetryPromiseForAgentEnd(event);
-        this._agentEventQueue = this._agentEventQueue.then(() => this._processAgentEventTracked(event), () => this._processAgentEventTracked(event));
+        const runSettlement = this._captureAgentRunSettlement(event);
+        const harnessAck = this._harnessPersistenceAckForEvent(event);
+        const processing = this._agentEventQueue.then(() => this._processAgentEventTracked(event, runSettlement, harnessAck), () => this._processAgentEventTracked(event, runSettlement, harnessAck));
+        this._agentEventQueue = processing;
+        if (harnessAck)
+            harnessAck.persistenceTail = processing;
         // Keep queue alive if an event handler fails
-        this._agentEventQueue.catch(() => { });
+        processing.catch(() => { });
         // SCRAMJET-DIVERGENCE: turn_end tool/prompt changes must settle before Agent snapshots
         // live state for the next provider request (#524).
         if (event.type === "turn_end")
@@ -315,94 +341,103 @@ export class AgentSession {
         this._outputThroughputTracker.reset();
         this._outputThroughputGeneration = undefined;
     }
-    _createRetryPromiseForAgentEnd(event) {
-        if (event.type !== "agent_end" || this._retryPromise) {
-            return;
-        }
-        const settings = this.settingsManager.getRetrySettings();
-        if (!settings.enabled) {
-            return;
-        }
-        const lastAssistant = this._findLastAssistantInMessages(event.messages);
-        if (!lastAssistant || !this._isRetryableError(lastAssistant)) {
-            return;
-        }
-        this._retryPromise = new Promise((resolve) => {
-            this._retryResolve = resolve;
-        });
-    }
-    _findLastAssistantInMessages(messages) {
-        for (let i = messages.length - 1; i >= 0; i--) {
-            const message = messages[i];
-            if (message.role === "assistant") {
-                return message;
-            }
-        }
-        return undefined;
-    }
-    // SCRAMJET-DIVERGENCE: harness-tool persisted-settlement (#341). Wraps queue-side event processing
-    // so a harness-tool invocation's persistence acknowledgement resolves only after the matching
-    // tool-result message_end has been fully processed and persisted, and rejects if processing any of
-    // that invocation's events throws. Rethrows to preserve the queue's existing keep-processing
-    // behavior (the caller attaches `.catch(() => {})`).
-    async _processAgentEventTracked(event) {
-        const ackId = this._harnessAckIdForEvent(event);
-        const ack = ackId !== undefined ? this._harnessPersistenceAcks.get(ackId) : undefined;
-        // Decide from the ORIGINAL event, before _processAgentEvent runs, whether this is the
-        // ack-resolving tool-result: a message_end hook can replace event.message in place
-        // (_replaceMessageInPlace), so re-reading role/toolCallId after the await could miss the match
-        // and strand the acknowledgement.
-        const resolvesAck = ack !== undefined &&
-            event.type === "message_end" &&
-            event.message.role === "toolResult" &&
-            event.message.toolCallId === ackId;
+    // SCRAMJET-DIVERGENCE: every Agent run owns persistence state and a one-shot settlement token (#553).
+    _captureAgentRunSettlement(event) {
+        if (event.type === "agent_start") {
+            // A retry continuation's run adopts the chain its originating prompt awaits; the chain stays
+            // bound to the retry phase until this start consumes it, however late Agent emits it.
+            const chain = this._retry?.phase === "continuing" ? this._retry.chain : createDeferred();
+            this._unsettledRetryChains.add(chain);
+            const run = { ...createDeferred(), chain };
+            this._activeAgentRunSettlement = run;
+            this._unsettledAgentRuns.add(run);
+            const reservation = this._pendingAgentRunStart;
+            if (reservation) {
+                this._pendingAgentRunStart = undefined;
+                reservation.run = run;
+                resolveDeferred(reservation, run);
+            }
+            return run;
+        }
+        const run = this._activeAgentRunSettlement;
+        if (event.type === "agent_end" && this._activeAgentRunSettlement === run) {
+            this._activeAgentRunSettlement = undefined;
+        }
+        return run;
+    }
+    _settleAgentRun(run, error) {
+        if (settleDeferred(run, error))
+            this._unsettledAgentRuns.delete(run);
+    }
+    _settleRetryChain(chain, error) {
+        if (settleDeferred(chain, error))
+            this._unsettledRetryChains.delete(chain);
+    }
+    _completeAgentRun(run, error) {
+        this._settleAgentRun(run, error);
+        this._settleRetryChain(run.chain, error);
+    }
+    _reserveAgentRunStart() {
+        if (this._pendingAgentRunStart)
+            throw new Error("An Agent prompt is already waiting to start.");
+        const reservation = createDeferred();
+        this._pendingAgentRunStart = reservation;
+        return reservation;
+    }
+    _rejectAgentRunStart(reservation, error) {
+        if (this._pendingAgentRunStart === reservation)
+            this._pendingAgentRunStart = undefined;
+        rejectDeferred(reservation, error);
+    }
+    // SCRAMJET-DIVERGENCE: harness-tool persisted settlement (#341). Synchronous ownership keeps queued
+    // invocation events attributed after early failures; public settlement awaits execution and the final persistence tail.
+    async _processAgentEventTracked(event, run, harnessAck) {
         try {
-            await this._processAgentEvent(event);
+            await this._processAgentEvent(event, run, harnessAck !== undefined);
         }
         catch (err) {
-            if (ack) {
-                ack.reject(err instanceof Error ? err : new Error(String(err)));
+            const error = err instanceof Error ? err : new Error(String(err));
+            if (harnessAck) {
+                harnessAck.firstPersistenceError ??= error;
+            }
+            else if (run) {
+                if (event.type === "message_end" && event.message.role === "assistant") {
+                    run.assistantPersistenceError = error;
+                }
+                this._releaseRetryForFailedRun(error);
+                this._completeAgentRun(run, error);
             }
             throw err;
         }
-        // Resolving here counts as "persisted" only because SessionManager persistence is synchronous
-        // (appendFileSync): _processAgentEvent has already written the tool-result row by the time it
-        // returns. If _persist ever becomes async, this would resolve before persistence completes.
-        if (resolvesAck) {
-            ack?.resolve();
-        }
     }
-    // SCRAMJET-DIVERGENCE: harness-tool persisted-settlement (#341). The tool-call id an event belongs
-    // to for acknowledgement tracking — the synthetic assistant tool-call, the `tool_execution_*`
-    // events, or the tool-result message. Returns undefined for events unrelated to a pending harness
-    // invocation; a returned id that has no pending acknowledgement (an ordinary model tool call)
-    // resolves to no-op at the call site.
-    _harnessAckIdForEvent(event) {
+    _harnessPersistenceAckForEvent(event) {
+        let toolCallId;
         switch (event.type) {
             case "tool_execution_start":
             case "tool_execution_update":
             case "tool_execution_end":
-                return event.toolCallId;
+                toolCallId = event.toolCallId;
+                break;
             case "message_start":
             case "message_end": {
                 const message = event.message;
                 if (message.role === "toolResult") {
-                    return message.toolCallId;
+                    toolCallId = message.toolCallId;
                 }
-                if (message.role === "assistant") {
+                else if (message.role === "assistant") {
                     for (const block of message.content) {
                         if (block.type === "toolCall" && this._harnessPersistenceAcks.has(block.id)) {
-                            return block.id;
+                            toolCallId = block.id;
+                            break;
                         }
                     }
                 }
-                return undefined;
+                break;
             }
-            default:
-                return undefined;
         }
+        return toolCallId === undefined ? undefined : this._harnessPersistenceAcks.get(toolCallId);
     }
-    async _processAgentEvent(event) {
+    async _processAgentEvent(event, run, fromHarnessInvocation = false) {
         // When a user message starts, check if it's from either queue and remove it BEFORE emitting
         // This ensures the UI sees the updated queue state
         if (event.type === "message_start" && event.message.role === "user") {
@@ -429,6 +464,8 @@ export class AgentSession {
         await this._emitExtensionEvent(event);
         // Notify all listeners
         this._emit(event);
+        if (this._disposed)
+            return;
         // Handle session persistence
         if (event.type === "message_end") {
             // Check if this is a custom message from extensions
@@ -439,8 +476,15 @@ export class AgentSession {
             else if (event.message.role === "user" ||
                 event.message.role === "assistant" ||
                 event.message.role === "toolResult") {
-                // Regular LLM message - persist as SessionMessageEntry
-                const messageEntryId = this.sessionManager.appendMessage(event.message);
+                // SCRAMJET-DIVERGENCE: retry settlement classifies the exact JSON-safe assistant snapshot
+                // that crossed the persistence boundary, never a later-mutated live Agent message (#553).
+                const persistedMessage = event.message.role === "assistant"
+                    ? JSON.parse(JSON.stringify(event.message))
+                    : event.message;
+                const messageEntryId = this.sessionManager.appendMessage(persistedMessage);
+                if (persistedMessage.role === "assistant" && !fromHarnessInvocation && run) {
+                    run.persistedAssistantSnapshot = persistedMessage;
+                }
                 if (event.message.role === "user") {
                     const sessionEntries = this._inputSessionEntries.get(event.message);
                     this._inputSessionEntries.delete(event.message);
@@ -467,47 +511,88 @@ export class AgentSession {
                 }
             }
             // Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere
-            // Track assistant message for auto-compaction (checked on agent_end)
-            if (event.message.role === "assistant") {
-                this._lastAssistantMessage = event.message;
-                const assistantMsg = event.message;
-                if (assistantMsg.stopReason !== "error") {
-                    this._overflowRecoveryAttempted = false;
-                }
-                // Reset retry counter immediately on successful assistant response
-                // This prevents accumulation across multiple LLM calls within a turn
-                if (assistantMsg.stopReason !== "error" && this._retryAttempt > 0) {
-                    this._emit({
-                        type: "auto_retry_end",
-                        success: true,
-                        attempt: this._retryAttempt,
-                    });
-                    this._retryAttempt = 0;
-                }
+            if (event.message.role === "assistant" &&
+                event.message.stopReason !== "error" &&
+                event.message.stopReason !== "aborted" &&
+                !fromHarnessInvocation) {
+                this._overflowRecoveryAttempted = false;
+                if (this._retry)
+                    this._retry = { ...this._retry, attempt: 0 };
             }
         }
-        // Check auto-retry and auto-compaction after agent completes
-        if (event.type === "agent_end" && this._lastAssistantMessage) {
-            const msg = this._lastAssistantMessage;
-            this._lastAssistantMessage = undefined;
-            // Check for retryable errors first (overloaded, rate limit, server errors)
-            if (this._isRetryableError(msg)) {
-                const didRetry = await this._handleRetryableError(msg);
+        if (event.type === "agent_end") {
+            if (this._disposed || !run)
+                return;
+            if (run.assistantPersistenceError) {
+                const error = run.assistantPersistenceError;
+                run.assistantPersistenceError = undefined;
+                run.persistedAssistantSnapshot = undefined;
+                this._completeAgentRun(run, error);
+                return;
+            }
+            const msg = run.persistedAssistantSnapshot;
+            run.persistedAssistantSnapshot = undefined;
+            if (!msg) {
+                this._releaseRetryForFailedRun(new Error("Retry continuation ended without an assistant message."));
+                this._completeAgentRun(run);
+                return;
+            }
+            if (msg.stopReason === "aborted" && this._retry) {
+                this._finishCancelledRetry("cancelled_during_continuation");
+                this._completeAgentRun(run);
+                return;
+            }
+            if (msg.stopReason !== "error") {
+                if (this._retry) {
+                    const attempt = this._runRetryCount;
+                    this._finishRetry({
+                        schemaVersion: 1,
+                        outcome: "succeeded",
+                        attemptsCompleted: this._bounded(attempt),
+                        cumulativeErrors: this._bounded(attempt),
+                    }, { type: "auto_retry_end", success: true, attempt });
+                }
+                this._completeAgentRun(run);
+                await this._checkCompaction(msg);
+                return;
+            }
+            const classification = this._classifyRetry(msg);
+            if (classification.kind === "context_overflow") {
+                this._finishRetryWithoutSuccess({
+                    schemaVersion: 1,
+                    outcome: "not_attempted",
+                    reason: "context_overflow_compaction",
+                    evidence: "context_overflow",
+                }, msg);
+                this._completeAgentRun(run);
+                await this._checkCompaction(msg);
+                return;
+            }
+            const settings = this.settingsManager.getRetrySettings();
+            if (!settings.enabled) {
+                this._finishRetryWithoutSuccess({
+                    schemaVersion: 1,
+                    outcome: "not_attempted",
+                    reason: "retry_disabled",
+                    evidence: classification.evidence,
+                }, msg);
+                this._completeAgentRun(run);
+                await this._checkCompaction(msg);
+                return;
+            }
+            if (classification.kind === "retry") {
+                const didRetry = await this._handleRetryableError(msg, classification.evidence, run);
                 if (didRetry)
-                    return; // Retry was initiated, don't proceed to compaction
+                    return;
             }
-            this._resolveRetry();
+            else {
+                const { kind: _kind, ...cause } = classification;
+                this._finishRetryWithoutSuccess({ schemaVersion: 1, outcome: "not_attempted", ...cause }, msg);
+            }
+            this._completeAgentRun(run);
             await this._checkCompaction(msg);
         }
     }
-    /** Resolve the pending retry promise */
-    _resolveRetry() {
-        if (this._retryResolve) {
-            this._retryResolve();
-            this._retryResolve = undefined;
-            this._retryPromise = undefined;
-        }
-    }
     /** Extract text content from a message */
     _getUserMessageText(message) {
         if (message.role !== "user")
@@ -665,12 +750,49 @@ export class AgentSession {
      * Call this when completely done with the session.
      */
     dispose() {
-        // SCRAMJET-DIVERGENCE: idempotent disposal that revokes in-flight harness-tool invocations (#341).
+        // SCRAMJET-DIVERGENCE: idempotent disposal revokes harness invocations and closes retry settlement (#341, #553).
         // A second call must not re-reject already-settled acknowledgements or re-run teardown.
         if (this._disposed)
             return;
         this._disposed = true;
         this._resetOutputThroughput();
+        const retryDisposeError = new Error("AgentSession disposed before retry settlement completed.");
+        const unsettledRuns = [...this._unsettledAgentRuns];
+        const retry = this._retry;
+        const unclassifiedError = unsettledRuns.find((run) => run.persistedAssistantSnapshot?.stopReason === "error")?.persistedAssistantSnapshot;
+        if (retry)
+            this.agent.abort();
+        try {
+            if (retry) {
+                this._appendAutoRetryRecord({
+                    schemaVersion: 1,
+                    outcome: "cancelled",
+                    reason: "session_disposed",
+                    attempt: this._bounded(retry.attempt),
+                    cumulativeErrors: this._bounded(this._runRetryCount),
+                });
+            }
+            else if (unclassifiedError) {
+                const classification = this._classifyRetry(unclassifiedError);
+                this._appendAutoRetryRecord({
+                    schemaVersion: 1,
+                    outcome: "not_attempted",
+                    reason: "session_disposed",
+                    evidence: classification.kind === "context_overflow" ? "context_overflow" : classification.evidence,
+                });
+            }
+        }
+        catch (error) {
+            this._reportRetryFailure(error);
+        }
+        if (retry?.phase === "backoff")
+            retry.controller.abort();
+        this._retry = undefined;
+        this._activeAgentRunSettlement = undefined;
+        const pendingAgentRunStart = this._pendingAgentRunStart;
+        if (pendingAgentRunStart)
+            this._rejectAgentRunStart(pendingAgentRunStart, retryDisposeError);
+        const pendingRetryContinuation = retry?.phase === "continuing" ? retry.chain : undefined;
         this._extensionRunner.invalidate("This extension ctx is stale after session replacement or reload. Do not use a captured pi or command ctx after ctx.newSession(), ctx.fork(), ctx.switchSession(), or ctx.reload(). For newSession, fork, and switchSession, move post-replacement work into withSession and use the ctx passed to withSession. For reload, do not use the old ctx after await ctx.reload().");
         // Reject pending persistence acknowledgements before revoking Agent-side invocations, so a caller
         // awaiting invokeHarnessTool sees rejection rather than a promise that never settles. Already-
@@ -678,10 +800,17 @@ export class AgentSession {
         // roll back arbitrary side effects.
         const disposeError = new Error("AgentSession disposed before the harness tool invocation settled.");
         for (const ack of this._harnessPersistenceAcks.values()) {
-            ack.reject(disposeError);
+            this._settleHarnessPersistenceAck(ack, disposeError);
         }
         this._harnessPersistenceAcks.clear();
         this.agent.rejectUnsettledHarnessTools(disposeError);
+        const retryChains = new Set(this._unsettledRetryChains);
+        if (pendingRetryContinuation)
+            retryChains.add(pendingRetryContinuation);
+        for (const run of unsettledRuns)
+            this._settleAgentRun(run, retryDisposeError);
+        for (const chain of retryChains)
+            this._settleRetryChain(chain, retryDisposeError);
         this._disconnectFromAgent();
         this._eventListeners = [];
         cleanupSessionResources(this.sessionId);
@@ -753,7 +882,7 @@ export class AgentSession {
     }
     /** Current retry attempt (0 if not retrying) */
     get retryAttempt() {
-        return this._retryAttempt;
+        return this._retry?.attempt ?? 0;
     }
     /**
      * Get the names of currently active tools.
@@ -842,13 +971,12 @@ export class AgentSession {
             throw new Error(`Cannot invoke harness tool "${name}": no tool with that name is registered.`);
         }
         const toolCallId = this._allocateHarnessToolCallId(options?.toolCallId);
-        // Register the acknowledgement before Agent execution can emit events, so the queue-side handler
-        // always finds it. Await Agent execution and persistence concurrently: Agent-core failure or a
-        // persistence failure rejects, and the tool-call-id-keyed handler resolves after the matching
-        // tool-result is persisted.
+        // Register before Agent execution can emit events. The coordinator retains attribution until Agent
+        // execution and the invocation's final queued persistence task both settle.
         const ack = this._registerHarnessPersistenceAck(toolCallId);
+        void this._completeHarnessToolInvocation(this.agent.runHarnessTool(tool, args, { toolCallId }), ack);
         try {
-            await Promise.all([this.agent.runHarnessTool(tool, args, { toolCallId }), ack.promise]);
+            await ack.promise;
         }
         finally {
             // Identity-checked cleanup: only drop the entry if it is still this invocation's ack (disposal
@@ -881,17 +1009,27 @@ export class AgentSession {
         }
         return id;
     }
+    async _completeHarnessToolInvocation(execution, ack) {
+        let executionError;
+        try {
+            await execution;
+        }
+        catch (error) {
+            executionError = error instanceof Error ? error : new Error(String(error));
+        }
+        try {
+            await ack.persistenceTail;
+        }
+        catch { }
+        this._settleHarnessPersistenceAck(ack, ack.firstPersistenceError ?? executionError);
+    }
+    _settleHarnessPersistenceAck(ack, error) {
+        settleDeferred(ack, error);
+    }
     // SCRAMJET-DIVERGENCE: harness-tool persisted-settlement (#341). Register a deferred acknowledgement
-    // keyed by tool-call id. The caller awaits `ack.promise` inside the same synchronous frame that
-    // registers it, so a synchronous disposal rejection can never strand it as an unhandled rejection.
+    // keyed by tool-call id before any invocation event can be emitted.
     _registerHarnessPersistenceAck(toolCallId) {
-        let resolve;
-        let reject;
-        const promise = new Promise((res, rej) => {
-            resolve = res;
-            reject = rej;
-        });
-        const ack = { promise, resolve, reject };
+        const ack = { ...createDeferred(), persistenceTail: Promise.resolve() };
         this._harnessPersistenceAcks.set(toolCallId, ack);
         return ack;
     }
@@ -1036,6 +1174,7 @@ export class AgentSession {
                     return;
                 }
             }
+            this._assertRetryNotOwningIdleAgent();
             // Emit input event for extension interception (before skill/template expansion)
             let currentText = text;
             let currentImages = options?.images;
@@ -1157,9 +1296,7 @@ export class AgentSession {
         }
         acceptInput?.();
         preflightResult?.(true);
-        this._runRetryCount = 0;
-        await this.agent.prompt(messages);
-        await this.waitForRetry();
+        await this._runAgentPrompt(messages);
     }
     /**
      * Try to execute an extension command. Returns true if command was found and executed.
@@ -1337,7 +1474,7 @@ export class AgentSession {
             }
         }
         else if (options?.triggerTurn) {
-            await this.agent.prompt(appMessage);
+            await this._runAgentPrompt(appMessage);
         }
         else {
             this.agent.state.messages.push(appMessage);
@@ -2312,128 +2449,311 @@ export class AgentSession {
     // =========================================================================
     // Auto-Retry
     // =========================================================================
-    /**
-     * Check if an error is retryable (overloaded, rate limit, server errors).
-     * Context overflow errors are NOT retryable (handled by compaction instead).
-     */
-    _isRetryableError(message) {
-        if (message.stopReason !== "error" || !message.errorMessage)
-            return false;
-        // Context overflow is handled by compaction, not retry
+    // SCRAMJET-DIVERGENCE: persisted post-extension snapshots authoritatively classify and settle retries (#553).
+    _classifyRetry(message) {
         const contextWindow = this.model?.contextWindow ?? 0;
-        if (isContextOverflow(message, Math.min(contextWindow, this.model?.maxInputTokens ?? Infinity)))
-            return false;
-        const err = message.errorMessage;
-        // Match: overloaded_error, provider returned error, rate limit, 429, 500, 502, 503, 504, service unavailable, network/connection errors (including connection lost), WebSocket transport closes/errors, fetch failed, premature stream endings, HTTP/2 closed before response, terminated, retry delay exceeded
-        return /overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|network.?error|connection.?error|connection.?refused|connection.?lost|websocket.?closed|websocket.?error|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|ended without|stream ended before message_stop|http2 request did not get a response|timed? out|timeout|terminated|retry delay/i.test(err);
+        if (isContextOverflow(message, Math.min(contextWindow, this.model?.maxInputTokens ?? Infinity))) {
+            return { kind: "context_overflow" };
+        }
+        const structured = validateResponsesProviderFailure(message.diagnostics);
+        if (structured.status === "valid") {
+            if (structured.retryDisposition === "transient")
+                return { kind: "retry", evidence: "provider_failure" };
+            return {
+                kind: "do_not_retry",
+                reason: structured.retryDisposition === "non_transient" ? "structured_non_transient" : "structured_unknown",
+                evidence: "provider_failure",
+            };
+        }
+        if (structured.status === "malformed") {
+            return { kind: "do_not_retry", reason: "malformed_provider_diagnostic", evidence: "none" };
+        }
+        if (structured.status === "duplicate") {
+            return { kind: "do_not_retry", reason: "duplicate_provider_diagnostic", evidence: "none" };
+        }
+        if (!message.errorMessage) {
+            return { kind: "do_not_retry", reason: "missing_error_evidence", evidence: "none" };
+        }
+        if (this._isLegacyRetryableError(message.errorMessage))
+            return { kind: "retry", evidence: "legacy_text" };
+        return { kind: "do_not_retry", reason: "legacy_non_retryable", evidence: "legacy_text" };
+    }
+    _isLegacyRetryableError(errorMessage) {
+        return /overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|network.?error|connection.?error|connection.?refused|connection.?lost|websocket.?closed|websocket.?error|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|ended without|stream ended before message_stop|http2 request did not get a response|timed? out|timeout|terminated|retry delay/i.test(errorMessage);
+    }
+    _bounded(value) {
+        return Math.min(65_535, Math.max(0, Number.isFinite(value) ? Math.trunc(value) : 65_535));
+    }
+    _appendAutoRetryRecord(record) {
+        this.sessionManager.appendCustomEntry("coding-agent:auto-retry", record);
     }
     /**
-     * Handle retryable errors with exponential backoff.
-     * @returns true if retry was initiated, false if max retries exceeded or disabled
+     * Persist a terminal record, emit `auto_retry_end` when a retry phase was active, and clear the phase.
+     * The phase is released before persistence is attempted so a persistence failure can never strand it.
      */
-    async _handleRetryableError(message) {
-        const settings = this.settingsManager.getRetrySettings();
-        if (!settings.enabled) {
-            this._resolveRetry();
-            return false;
+    _finishRetry(record, end) {
+        const retry = this._retry;
+        this._retry = undefined;
+        try {
+            this._appendAutoRetryRecord(record);
         }
-        // Retry promise is created synchronously in _handleAgentEvent for agent_end.
-        // Keep a defensive fallback here in case a future refactor bypasses that path.
-        if (!this._retryPromise) {
-            this._retryPromise = new Promise((resolve) => {
-                this._retryResolve = resolve;
-            });
+        catch (error) {
+            if (retry) {
+                this._emit({
+                    type: "auto_retry_end",
+                    success: false,
+                    attempt: end?.attempt ?? retry.attempt,
+                    finalError: "Retry outcome persistence failed",
+                });
+            }
+            throw this._reportRetryFailure(error);
+        }
+        if (retry && end)
+            this._emit(end);
+    }
+    _finishRetryWithoutSuccess(record, message) {
+        const retry = this._retry;
+        if (retry?.attempt === 0) {
+            // The continuation already produced a successful message, so the retry recovered and this
+            // later failure is a fresh, non-retried error; close the retry as succeeded first.
+            const attempt = this._runRetryCount;
+            this._finishRetry({
+                schemaVersion: 1,
+                outcome: "succeeded",
+                attemptsCompleted: this._bounded(attempt),
+                cumulativeErrors: this._bounded(attempt),
+            }, { type: "auto_retry_end", success: true, attempt });
+            this._finishRetry(record);
+            return;
         }
-        this._retryAttempt++;
+        this._finishRetry(record, retry
+            ? { type: "auto_retry_end", success: false, attempt: retry.attempt, finalError: message.errorMessage }
+            : undefined);
+    }
+    /** A run that ends without a classifiable snapshot cannot continue the retry; close it so nothing stays wedged. */
+    _releaseRetryForFailedRun(error) {
+        const retry = this._retry;
+        if (!retry)
+            return;
+        try {
+            this._finishRetry({
+                schemaVersion: 1,
+                outcome: "failed",
+                reason: "run_failed",
+                attempt: this._bounded(retry.attempt),
+                cumulativeErrors: this._bounded(this._runRetryCount),
+            }, { type: "auto_retry_end", success: false, attempt: retry.attempt, finalError: error.message });
+        }
+        catch {
+            // Already reported and the phase is released; the run settles with its own error.
+        }
+    }
+    _reportRetryFailure(error) {
+        const normalized = error instanceof Error ? error : new Error(String(error));
+        this._extensionRunner.emitError({
+            extensionPath: "agent-session:auto-retry",
+            event: "retry_settlement",
+            error: normalized.message,
+            stack: normalized.stack,
+        });
+        return normalized;
+    }
+    async _handleRetryableError(message, evidence, run) {
+        const settings = this.settingsManager.getRetrySettings();
+        const attempt = (this._retry?.attempt ?? 0) + 1;
         this._runRetryCount++;
         const cumulativeCap = settings.maxRetries * 2;
+        if (attempt > settings.maxRetries) {
+            const attemptsCompleted = attempt - 1;
+            this._finishRetry({
+                schemaVersion: 1,
+                outcome: "exhausted",
+                reason: "attempt_limit",
+                attemptsCompleted: this._bounded(attemptsCompleted),
+                maxAttempts: this._bounded(settings.maxRetries),
+                cumulativeErrors: this._bounded(this._runRetryCount),
+            }, { type: "auto_retry_end", success: false, attempt: attemptsCompleted, finalError: message.errorMessage });
+            return false;
+        }
         if (this._runRetryCount > cumulativeCap) {
-            this._emit({
+            const attemptsCompleted = this._runRetryCount - 1;
+            this._finishRetry({
+                schemaVersion: 1,
+                outcome: "exhausted",
+                reason: "cumulative_limit",
+                attemptsCompleted: this._bounded(attemptsCompleted),
+                maxAttempts: this._bounded(settings.maxRetries),
+                cumulativeErrors: this._bounded(this._runRetryCount),
+            }, {
                 type: "auto_retry_end",
                 success: false,
-                attempt: this._runRetryCount - 1,
-                finalError: `Repeated retry failures (${this._runRetryCount - 1} total attempts this prompt). ${message.errorMessage ?? ""}`.trim(),
+                attempt: attemptsCompleted,
+                finalError: `Repeated retry failures (${attemptsCompleted} total attempts this prompt). ${message.errorMessage ?? ""}`.trim(),
             });
-            this._retryAttempt = 0;
-            this._resolveRetry();
             return false;
         }
-        if (this._retryAttempt > settings.maxRetries) {
-            // Max retries exceeded, emit final failure and reset
-            this._emit({
-                type: "auto_retry_end",
-                success: false,
-                attempt: this._retryAttempt - 1,
-                finalError: message.errorMessage,
+        const delayMs = settings.baseDelayMs * 2 ** (attempt - 1);
+        const previous = this._retry;
+        this._retry = undefined;
+        try {
+            this._appendAutoRetryRecord({
+                schemaVersion: 1,
+                outcome: "scheduled",
+                evidence,
+                attempt: this._bounded(attempt),
+                maxAttempts: this._bounded(settings.maxRetries),
+                cumulativeErrors: this._bounded(this._runRetryCount),
+                delayMs: this._bounded(delayMs),
             });
-            this._retryAttempt = 0;
-            this._resolveRetry(); // Resolve so waitForRetry() completes
-            return false;
         }
-        const delayMs = settings.baseDelayMs * 2 ** (this._retryAttempt - 1);
+        catch (error) {
+            if (previous) {
+                this._emit({
+                    type: "auto_retry_end",
+                    success: false,
+                    attempt: previous.attempt,
+                    finalError: "Retry outcome persistence failed",
+                });
+            }
+            throw this._reportRetryFailure(error);
+        }
+        const controller = new AbortController();
+        const backoff = { phase: "backoff", attempt, controller, run };
+        this._retry = backoff;
         this._emit({
             type: "auto_retry_start",
-            attempt: this._retryAttempt,
+            attempt,
             maxAttempts: settings.maxRetries,
             delayMs,
             errorMessage: message.errorMessage || "Unknown error",
             cumulativeErrors: this._runRetryCount,
         });
-        // Remove error message from agent state (keep in session for history)
+        if (controller.signal.aborted || this._disposed) {
+            return this._finishCancelledRetry("cancelled_during_backoff", backoff);
+        }
         const messages = this.agent.state.messages;
         if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
             this.agent.state.messages = messages.slice(0, -1);
         }
-        // Wait with exponential backoff (abortable)
-        this._retryAbortController = new AbortController();
         try {
-            await sleep(delayMs, this._retryAbortController.signal);
+            await sleep(delayMs, controller.signal);
+            await sleep(0, controller.signal);
         }
         catch {
-            // Aborted during sleep - emit end event so UI can clean up
-            const attempt = this._retryAttempt;
-            this._retryAttempt = 0;
-            this._retryAbortController = undefined;
-            this._emit({
-                type: "auto_retry_end",
-                success: false,
-                attempt,
-                finalError: "Retry cancelled",
-            });
-            this._resolveRetry();
-            return false;
-        }
-        this._retryAbortController = undefined;
-        // Retry via continue() - use setTimeout to break out of event handler chain
-        setTimeout(() => {
-            this.agent.continue().catch(() => {
-                // Retry failed - will be caught by next agent_end
-            });
-        }, 0);
+            return this._finishCancelledRetry("cancelled_during_backoff", backoff);
+        }
+        if (controller.signal.aborted || this._disposed) {
+            return this._finishCancelledRetry("cancelled_during_backoff", backoff);
+        }
+        // Hand the chain to the continuation before `continue()`; the run that eventually emits
+        // `agent_start` adopts it (see `_captureAgentRunSettlement`), however long Agent defers that start.
+        const continuing = { phase: "continuing", attempt, chain: run.chain };
+        this._retry = continuing;
+        const continuation = this.agent.continue();
+        this._settleAgentRun(run);
+        continuation.catch((error) => {
+            if (this._disposed || this._retry !== continuing)
+                return;
+            const continuationError = this._reportRetryFailure(error);
+            let settlementError = continuationError;
+            try {
+                this._finishRetry({
+                    schemaVersion: 1,
+                    outcome: "failed",
+                    reason: "continuation_rejected",
+                    attempt: this._bounded(attempt),
+                    cumulativeErrors: this._bounded(this._runRetryCount),
+                }, { type: "auto_retry_end", success: false, attempt, finalError: continuationError.message });
+            }
+            catch (persistenceError) {
+                settlementError = new AggregateError([continuationError, persistenceError], "Retry continuation and outcome persistence both failed.", { cause: continuationError });
+            }
+            this._settleRetryChain(run.chain, settlementError);
+        });
         return true;
     }
+    _finishCancelledRetry(reason, expected) {
+        if (this._disposed) {
+            this._retry = undefined;
+            throw new Error("AgentSession disposed before retry settlement completed.");
+        }
+        const retry = this._retry;
+        if (expected && retry !== expected)
+            return false;
+        const attempt = retry?.attempt ?? 0;
+        this._finishRetry({
+            schemaVersion: 1,
+            outcome: "cancelled",
+            reason,
+            attempt: this._bounded(attempt),
+            cumulativeErrors: this._bounded(this._runRetryCount),
+        }, { type: "auto_retry_end", success: false, attempt, finalError: "Retry cancelled" });
+        return false;
+    }
     /**
      * Cancel in-progress retry.
      */
     abortRetry() {
-        this._retryAbortController?.abort();
-        // Note: _retryAttempt is reset in the catch block of _autoRetry
-        this._resolveRetry();
-    }
-    /**
-     * Wait for any in-progress retry to complete.
-     * Returns immediately if no retry is in progress.
-     */
-    async waitForRetry() {
-        if (!this._retryPromise) {
+        const retry = this._retry;
+        if (!retry)
             return;
+        if (retry.phase === "backoff")
+            retry.controller.abort();
+        this.agent.abort();
+    }
+    /** Agent's own `activeRun` guard is false during backoff; the retry phase owns the idle Agent then. */
+    _assertRetryNotOwningIdleAgent() {
+        if (this._retry && !this.isStreaming) {
+            throw new Error("Automatic retry is in progress. Cancel the retry before starting another prompt.");
+        }
+    }
+    async _runAgentPrompt(messages) {
+        this._assertRetryNotOwningIdleAgent();
+        const start = this._reserveAgentRunStart();
+        this._runRetryCount = 0;
+        let promptFailure;
+        try {
+            await this.agent.prompt(messages);
         }
-        await this._retryPromise;
+        catch (error) {
+            promptFailure = { error };
+        }
+        if (!start.run && this._pendingAgentRunStart === start) {
+            const startError = promptFailure
+                ? promptFailure.error instanceof Error
+                    ? promptFailure.error
+                    : new Error(String(promptFailure.error))
+                : new Error("Agent prompt completed before agent_start.");
+            this._rejectAgentRunStart(start, startError);
+            if (promptFailure)
+                throw promptFailure.error;
+        }
+        let settlementFailure;
+        try {
+            const settlement = await start.promise;
+            await this.waitForRetry(settlement);
+        }
+        catch (error) {
+            settlementFailure = { error };
+        }
+        if (promptFailure && settlementFailure) {
+            throw new AggregateError([promptFailure.error, settlementFailure.error], "Agent prompt and retry settlement both failed.", { cause: promptFailure.error });
+        }
+        if (promptFailure)
+            throw promptFailure.error;
+        if (settlementFailure)
+            throw settlementFailure.error;
+    }
+    async waitForRetry(settlement) {
+        if (!settlement)
+            return;
+        await settlement.promise;
+        await settlement.chain.promise;
         await this.agent.waitForIdle();
     }
     /** Whether auto-retry is currently in progress */
     get isRetrying() {
-        return this._retryPromise !== undefined;
+        return this._retry !== undefined;
     }
     /** Whether auto-retry is enabled */
     get autoRetryEnabled() {