@leanandmean/coding-agent 0.74.1-scramjet.6 → 0.74.1-scramjet.60

package/dist/core/agent-session.js

@@ -14,7 +14,11 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
+// SCRAMJET-DIVERGENCE: provider-safe harness tool-call id generation for the persisted-settlement
+// 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";
@@ -26,7 +30,10 @@ import { exportSessionToHtml } from "./export-html/index.js";
 import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
 import { ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
 import { emitSessionShutdownEvent, spliceContributedSections } from "./extensions/runner.js";
+import { OutputThroughputTracker } from "./output-throughput.js";
+import { OutputThroughputHistoryStore } from "./output-throughput-history.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
+import { indexScramjetCommandStarts, restoreScramjetCommandInvocation } from "./scramjet-command-parser.js";
 import { CURRENT_SESSION_VERSION, getLatestCompactionEntry } from "./session-manager.js";
 import { createSyntheticSourceInfo } from "./source-info.js";
 import { buildSystemPromptSections } from "./system-prompt.js";
@@ -53,24 +60,59 @@ export function parseSkillBlock(text) {
 // ============================================================================
 /** Standard thinking levels */
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high"];
-// ============================================================================
-// AgentSession Class
-// ============================================================================
+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;
     settingsManager;
+    outputThroughputHistoryPath;
     _scopedModels;
     // Event subscription state
     _unsubscribeAgent;
     _eventListeners = [];
     _agentEventQueue = Promise.resolve();
+    _outputThroughputTracker = new OutputThroughputTracker();
+    _outputThroughputHistory;
+    _outputThroughputGeneration;
+    _latestOutputThroughputSample;
+    // SCRAMJET-DIVERGENCE: harness-tool persisted-settlement state (#341). `_disposed` gates post-
+    // teardown invocations; the map keys each in-flight invocation's tool-call id to its persistence
+    // acknowledgement so `_processAgentEvent` can settle it after the matching tool-result is persisted.
+    _disposed = false;
+    _harnessPersistenceAcks = new Map();
     /** Tracks pending steering messages for UI display. Removed when delivered. */
     _steeringMessages = [];
     /** Tracks pending follow-up messages for UI display. Removed when delivered. */
     _followUpMessages = [];
     /** Messages queued to be included with the next user prompt as context ("asides"). */
     _pendingNextTurnMessages = [];
+    _inputSessionEntries = new WeakMap();
     // Compaction state
     _compactionAbortController = undefined;
     _autoCompactionAbortController = undefined;
@@ -78,10 +120,12 @@ export class AgentSession {
     // Branch summarization state
     _branchSummaryAbortController = undefined;
     // Retry state
-    _retryAbortController = undefined;
-    _retryAttempt = 0;
-    _retryPromise = undefined;
-    _retryResolve = undefined;
+    _retry = undefined;
+    _runRetryCount = 0;
+    _activeAgentRunSettlement = undefined;
+    _pendingAgentRunStart = undefined;
+    _unsettledAgentRuns = new Set();
+    _unsettledRetryChains = new Set();
     // Bash execution state
     _bashAbortController = undefined;
     _pendingBashMessages = [];
@@ -114,10 +158,22 @@ export class AgentSession {
     // can apply per-section cache control.
     _baseSystemPromptSections = [];
     _baseSystemPromptOptions;
+    // SCRAMJET-DIVERGENCE: active-tool prompt rebuilds preserve the current top-level run's
+    // before_agent_start composition while new prompts and reloads establish a fresh composition (#524).
+    _runPromptComposition = { kind: "generated-base" };
     constructor(config) {
         this.agent = config.agent;
         this.sessionManager = config.sessionManager;
         this.settingsManager = config.settingsManager;
+        this.outputThroughputHistoryPath = config.outputThroughputHistoryPath;
+        this._outputThroughputHistory = new OutputThroughputHistoryStore(this.outputThroughputHistoryPath, (diagnostic) => {
+            this._extensionRunner.emitError({
+                extensionPath: "output-throughput-history",
+                event: diagnostic.operation,
+                error: `${diagnostic.message} (${diagnostic.path})`,
+                stack: diagnostic.cause instanceof Error ? diagnostic.cause.stack : undefined,
+            });
+        });
         this._scopedModels = config.scopedModels ?? [];
         this._resourceLoader = config.resourceLoader;
         this._customTools = config.customTools ?? [];
@@ -161,8 +217,8 @@ export class AgentSession {
         throw new Error(formatNoApiKeyFoundMessage(model.provider));
     }
     // SCRAMJET-DIVERGENCE: _drainAgentEventQueue ensures all queued async extension event
-    // processing has settled before proceeding. Used by beforeToolBatch (pre-extraction drain)
-    // and beforeToolCall (per-tool drain).
+    // processing has settled before proceeding. Used by beforeToolBatch (pre-extraction drain),
+    // beforeToolCall (per-tool drain), and the awaited turn_end listener barrier.
     async _drainAgentEventQueue() {
         await this._agentEventQueue;
     }
@@ -241,46 +297,147 @@ 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) => {
-        // 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._processAgentEvent(event), () => this._processAgentEvent(event));
+        this._captureOutputThroughput(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")
+            return this._agentEventQueue;
     };
-    _createRetryPromiseForAgentEnd(event) {
-        if (event.type !== "agent_end" || this._retryPromise) {
+    // SCRAMJET-DIVERGENCE: Capture provider events synchronously and reset stale throughput lifecycles (#476).
+    _captureOutputThroughput(event) {
+        if (event.type === "message_start" && event.message.role === "assistant" && event.message.origin === "provider") {
+            this._outputThroughputGeneration = this._outputThroughputTracker.start({
+                provider: event.message.provider,
+                model: event.message.model,
+            });
             return;
         }
-        const settings = this.settingsManager.getRetrySettings();
-        if (!settings.enabled) {
+        const generation = this._outputThroughputGeneration;
+        if (generation === undefined)
             return;
+        if (event.type === "message_update" && event.message.role === "assistant") {
+            this._outputThroughputTracker.observe(generation, event.assistantMessageEvent);
         }
-        const lastAssistant = this._findLastAssistantInMessages(event.messages);
-        if (!lastAssistant || !this._isRetryableError(lastAssistant)) {
-            return;
+        else if (event.type === "message_end" && event.message.role === "assistant") {
+            const sample = this._outputThroughputTracker.finalize(generation, event.message);
+            this._outputThroughputGeneration = undefined;
+            if (sample) {
+                this._latestOutputThroughputSample = sample;
+                this._outputThroughputHistory.submit(sample);
+            }
         }
-        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;
+    _resetOutputThroughput() {
+        this._outputThroughputTracker.reset();
+        this._outputThroughputGeneration = undefined;
+    }
+    // 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, run, harnessAck !== undefined);
+        }
+        catch (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;
+        }
+    }
+    _harnessPersistenceAckForEvent(event) {
+        let toolCallId;
+        switch (event.type) {
+            case "tool_execution_start":
+            case "tool_execution_update":
+            case "tool_execution_end":
+                toolCallId = event.toolCallId;
+                break;
+            case "message_start":
+            case "message_end": {
+                const message = event.message;
+                if (message.role === "toolResult") {
+                    toolCallId = message.toolCallId;
+                }
+                else if (message.role === "assistant") {
+                    for (const block of message.content) {
+                        if (block.type === "toolCall" && this._harnessPersistenceAcks.has(block.id)) {
+                            toolCallId = block.id;
+                            break;
+                        }
+                    }
+                }
+                break;
             }
         }
-        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") {
@@ -307,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
@@ -317,51 +476,123 @@ export class AgentSession {
             else if (event.message.role === "user" ||
                 event.message.role === "assistant" ||
                 event.message.role === "toolResult") {
-                // Regular LLM message - persist as SessionMessageEntry
-                this.sessionManager.appendMessage(event.message);
-            }
-            // 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;
+                // 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;
                 }
-                // 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 === "user") {
+                    const sessionEntries = this._inputSessionEntries.get(event.message);
+                    this._inputSessionEntries.delete(event.message);
+                    // This try/catch observes only failures thrown synchronously by
+                    // appendCustomEntry. On the buffered first-turn path (before any
+                    // assistant message) _persist stores the entry in memory with no I/O,
+                    // so only metadata *serialization* failures surface here; the deferred
+                    // disk write happens later in the unguarded appendMessage(assistant)
+                    // flush, whose throw is swallowed by the _agentEventQueue.catch on the
+                    // event-handler chain and degrades exact restoration silently.
+                    for (const entry of sessionEntries ?? []) {
+                        try {
+                            this.sessionManager.appendCustomEntry(entry.customType, entry.data, messageEntryId);
+                        }
+                        catch (err) {
+                            this._extensionRunner.emitError({
+                                extensionPath: `session-entry:${entry.customType}`,
+                                event: "session_entry_persistence",
+                                error: `Failed to persist attached input metadata after its user message; exact input restoration may be unavailable: ${err instanceof Error ? err.message : String(err)}`,
+                                stack: err instanceof Error ? err.stack : undefined,
+                            });
+                        }
+                    }
                 }
             }
+            // Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere
+            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")
@@ -519,7 +750,67 @@ export class AgentSession {
      * Call this when completely done with the session.
      */
     dispose() {
+        // 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-
+        // running tool work may finish afterward; teardown revokes the old-session guarantee but cannot
+        // roll back arbitrary side effects.
+        const disposeError = new Error("AgentSession disposed before the harness tool invocation settled.");
+        for (const ack of this._harnessPersistenceAcks.values()) {
+            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);
@@ -547,9 +838,51 @@ export class AgentSession {
     get systemPrompt() {
         return flattenSystemPrompt(this.agent.state.systemPrompt);
     }
+    get liveOutputRate() {
+        const model = this.state.model;
+        const identity = this._outputThroughputTracker.activeIdentity;
+        if (!model || identity?.provider !== model.provider || identity.model !== model.id)
+            return undefined;
+        return this._outputThroughputTracker.liveRate();
+    }
+    get outputThroughputActive() {
+        return this._outputThroughputTracker.outputActive;
+    }
+    get outputThroughputGeneration() {
+        return this._outputThroughputTracker.generation;
+    }
+    get medianOutputRate() {
+        const model = this.state.model;
+        if (!model)
+            return undefined;
+        const history = this._outputThroughputHistory.snapshot();
+        const local = this._latestOutputThroughputSample;
+        if (local?.provider === model.provider &&
+            local.model === model.id &&
+            !history
+                .samples(model.provider, model.id)
+                .some((sample) => sample.provider === local.provider &&
+                sample.model === local.model &&
+                sample.responseModel === local.responseModel &&
+                sample.outputTokens === local.outputTokens &&
+                sample.durationMs === local.durationMs &&
+                sample.observedAt === local.observedAt)) {
+            history.add(local);
+        }
+        return history.median(model.provider, model.id);
+    }
+    get outputThroughputHistory() {
+        return this._outputThroughputHistory.snapshot();
+    }
+    refreshOutputThroughputHistory() {
+        return this._outputThroughputHistory.refresh();
+    }
+    flushOutputThroughputHistory() {
+        return this._outputThroughputHistory.flush();
+    }
     /** Current retry attempt (0 if not retrying) */
     get retryAttempt() {
-        return this._retryAttempt;
+        return this._retry?.attempt ?? 0;
     }
     /**
      * Get the names of currently active tools.
@@ -582,6 +915,14 @@ export class AgentSession {
         const tools = [];
         const validToolNames = [];
         for (const name of toolNames) {
+            // SCRAMJET-DIVERGENCE: harness-only tools are never placed in the provider-visible tool
+            // set, even when explicitly requested (#244). This is the single choke point for
+            // `agent.state.tools`, so filtering here structurally guarantees a harness-only tool can
+            // never masquerade as a model-callable one — while it stays resolvable in `_toolRegistry`
+            // for `invokeHarnessTool`.
+            if (this._toolDefinitions.get(name)?.definition.activation === "harness-only") {
+                continue;
+            }
             const tool = this._toolRegistry.get(name);
             if (tool) {
                 tools.push(tool);
@@ -592,6 +933,106 @@ export class AgentSession {
         // Rebuild base system prompt with new tool set
         this._rebuildSystemPrompt(validToolNames);
     }
+    // SCRAMJET-DIVERGENCE: harness-tool invocation (#244), persisted-settlement boundary (#341).
+    /**
+     * Execute a registered tool as a harness-originated call (not requested by the model).
+     *
+     * Resolves the wrapped tool from the full registry — including `"harness-only"` tools that are
+     * never provider-visible — so its `execute` still receives the extension context and its
+     * `tool_call`/`tool_result` hooks still fire. Delegates to {@link Agent.runHarnessTool}, which
+     * runs the call through the real prepare/execute/finalize pipeline: identical live
+     * `tool_execution_*`/message events, persisted session entries, and extension hooks, but no
+     * run/turn framing. The idle-vs-mid-run branch lives in `runHarnessTool` (keyed on the agent's
+     * active run, which tracks `isStreaming`): idle calls execute immediately, mid-run calls queue
+     * and drain before the next intra-run LLM call.
+     *
+     * **Persisted settlement (#341).** This is a strictly stronger boundary than
+     * {@link Agent.runHarnessTool}: the returned promise resolves only after (1) the Agent-core
+     * pipeline fulfills *and* (2) `_processAgentEvent` has persisted the matching tool-result
+     * `message_end` via `SessionManager.appendMessage`. Because the event queue preserves order,
+     * that also proves the preceding synthetic assistant tool-call message was persisted first. It
+     * rejects on Agent-core failure, on failure to process/persist a matching event, on disposal
+     * before settlement, on a post-disposal call, on an unknown tool, or on a duplicate explicit
+     * tool-call id that is already pending. **Rejection means the promised pipeline did not complete —
+     * it does not prove artifact absence** (Agent state and persistence may have partially or fully
+     * completed before a late failure), so callers must not blindly retry. A tool's own `execute()`
+     * error is *not* a rejection: it becomes a normal `isError: true` result and the promise resolves
+     * after that error-result pipeline is persisted.
+     *
+     * **Reentrancy.** As with `runHarnessTool`, do not `await` this from work whose return is required
+     * for the Agent to reach the drain point or for the event queue to persist the matching result.
+     */
+    async invokeHarnessTool(name, args, options) {
+        if (this._disposed) {
+            throw new Error(`Cannot invoke harness tool "${name}": the session has been disposed.`);
+        }
+        const tool = this._toolRegistry.get(name);
+        if (!tool) {
+            throw new Error(`Cannot invoke harness tool "${name}": no tool with that name is registered.`);
+        }
+        const toolCallId = this._allocateHarnessToolCallId(options?.toolCallId);
+        // 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 ack.promise;
+        }
+        finally {
+            // Identity-checked cleanup: only drop the entry if it is still this invocation's ack (disposal
+            // may have cleared the map, and a later same-id invocation must not have its entry removed).
+            if (this._harnessPersistenceAcks.get(toolCallId) === ack) {
+                this._harnessPersistenceAcks.delete(toolCallId);
+            }
+        }
+    }
+    // SCRAMJET-DIVERGENCE: harness-tool persisted-settlement (#341). Allocate the tool-call id used as
+    // the acknowledgement key: reject a duplicate explicit id that is still pending, retry a generated
+    // id on the (astronomically unlikely) collision with a pending one.
+    _allocateHarnessToolCallId(explicit) {
+        if (explicit !== undefined) {
+            // Validate at the public trust boundary (invokeHarnessTool is on ExtensionAPI): an explicit
+            // id flows straight into the synthetic assistant message and on to the provider, so it must
+            // meet the provider-safe shape generateHarnessToolCallId guarantees (Anthropic's
+            // ^[a-zA-Z0-9_-]+$, bounded length).
+            if (!/^[a-zA-Z0-9_-]{1,64}$/.test(explicit)) {
+                throw new Error(`Cannot invoke harness tool with tool-call id "${explicit}": ids must be 1-64 characters of [a-zA-Z0-9_-].`);
+            }
+            if (this._harnessPersistenceAcks.has(explicit)) {
+                throw new Error(`Cannot invoke harness tool with tool-call id "${explicit}": an invocation with that id is already pending.`);
+            }
+            return explicit;
+        }
+        let id = generateHarnessToolCallId();
+        while (this._harnessPersistenceAcks.has(id)) {
+            id = generateHarnessToolCallId();
+        }
+        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 before any invocation event can be emitted.
+    _registerHarnessPersistenceAck(toolCallId) {
+        const ack = { ...createDeferred(), persistenceTail: Promise.resolve() };
+        this._harnessPersistenceAcks.set(toolCallId, ack);
+        return ack;
+    }
     /** Whether compaction or branch summarization is currently running */
     get isCompacting() {
         return (this._autoCompactionAbortController !== undefined ||
@@ -656,6 +1097,19 @@ export class AgentSession {
         }
         return Array.from(unique);
     }
+    _applyRunPromptComposition() {
+        switch (this._runPromptComposition.kind) {
+            case "generated-base":
+                this.agent.state.systemPrompt = this._baseSystemPromptSections.slice();
+                break;
+            case "contributed-sections":
+                this.agent.state.systemPrompt = spliceContributedSections(this._baseSystemPromptSections, this._runPromptComposition.sections);
+                break;
+            case "authoritative-string":
+                this.agent.state.systemPrompt = this._runPromptComposition.systemPrompt;
+                break;
+        }
+    }
     /** Rebuild `_baseSystemPromptSections` from the current resources and tool set and apply it to agent state. */
     _rebuildSystemPrompt(toolNames) {
         const validToolNames = toolNames.filter((name) => this._toolRegistry.has(name));
@@ -676,6 +1130,7 @@ export class AgentSession {
         const appendSystemPrompt = loaderAppendSystemPrompt.length > 0 ? loaderAppendSystemPrompt.join("\n\n") : undefined;
         const loadedSkills = this._resourceLoader.getSkills().skills;
         const loadedContextFiles = this._resourceLoader.getAgentsFiles().agentsFiles;
+        // SCRAMJET-DIVERGENCE: pass session file path for volatile environment fact (issue 348)
         this._baseSystemPromptOptions = {
             cwd: this._cwd,
             skills: loadedSkills,
@@ -685,9 +1140,10 @@ export class AgentSession {
             selectedTools: validToolNames,
             toolSnippets,
             promptGuidelines,
+            sessionFile: this.sessionManager.getSessionFile(),
         };
         this._baseSystemPromptSections = buildSystemPromptSections(this._baseSystemPromptOptions);
-        this.agent.state.systemPrompt = this._baseSystemPromptSections.slice();
+        this._applyRunPromptComposition();
     }
     // =========================================================================
     // Prompting
@@ -705,6 +1161,8 @@ export class AgentSession {
         const expandPromptTemplates = options?.expandPromptTemplates ?? true;
         const preflightResult = options?.preflightResult;
         let messages;
+        let inputSessionEntries;
+        let acceptInput;
         try {
             // Handle extension commands first (execute immediately, even during streaming)
             // Extension commands manage their own LLM interaction via pi.sendMessage()
@@ -716,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;
@@ -728,6 +1187,8 @@ export class AgentSession {
                 if (inputResult.action === "transform") {
                     currentText = inputResult.text;
                     currentImages = inputResult.images ?? currentImages;
+                    inputSessionEntries = inputResult.sessionEntries;
+                    acceptInput = inputResult.onAccepted;
                 }
             }
             // Expand skill commands (/skill:name args) and prompt templates (/template args)
@@ -743,11 +1204,12 @@ export class AgentSession {
                         "deliverAs when calling dispatchUserInput() or sendUserMessage() — to queue the message.");
                 }
                 if (options.streamingBehavior === "followUp") {
-                    await this._queueFollowUp(expandedText, currentImages);
+                    await this._queueFollowUp(expandedText, currentImages, inputSessionEntries);
                 }
                 else {
-                    await this._queueSteer(expandedText, currentImages);
+                    await this._queueSteer(expandedText, currentImages, inputSessionEntries);
                 }
+                acceptInput?.();
                 preflightResult?.(true);
                 return;
             }
@@ -778,16 +1240,21 @@ export class AgentSession {
             if (currentImages) {
                 userContent.push(...currentImages);
             }
-            messages.push({
+            const userMessage = {
                 role: "user",
                 content: userContent,
                 timestamp: Date.now(),
-            });
+            };
+            messages.push(userMessage);
+            if (inputSessionEntries?.length) {
+                this._inputSessionEntries.set(userMessage, inputSessionEntries);
+            }
             // Inject any pending "nextTurn" messages as context alongside the user message
             for (const msg of this._pendingNextTurnMessages) {
                 messages.push(msg);
             }
             this._pendingNextTurnMessages = [];
+            this._runPromptComposition = { kind: "generated-base" };
             // Emit before_agent_start extension event
             const result = await this._extensionRunner.emitBeforeAgentStart(expandedText, currentImages, this._baseSystemPromptSections, this._baseSystemPromptOptions);
             // Add all custom messages from extensions
@@ -807,15 +1274,18 @@ export class AgentSession {
             // replacement is authoritative (even an empty string): it wins for the
             // whole prompt and any contributed sections are dropped for this turn.
             if (result?.systemPrompt !== undefined) {
-                this.agent.state.systemPrompt = result.systemPrompt;
+                this._runPromptComposition = {
+                    kind: "authoritative-string",
+                    systemPrompt: result.systemPrompt,
+                };
             }
             else if (result?.systemPromptSections) {
-                this.agent.state.systemPrompt = spliceContributedSections(this._baseSystemPromptSections, result.systemPromptSections);
-            }
-            else {
-                // Ensure we're using the base prompt (in case previous turn had modifications)
-                this.agent.state.systemPrompt = this._baseSystemPromptSections.slice();
+                this._runPromptComposition = {
+                    kind: "contributed-sections",
+                    sections: result.systemPromptSections.map((section) => ({ ...section })),
+                };
             }
+            this._applyRunPromptComposition();
         }
         catch (error) {
             preflightResult?.(false);
@@ -824,9 +1294,9 @@ export class AgentSession {
         if (!messages) {
             return;
         }
+        acceptInput?.();
         preflightResult?.(true);
-        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.
@@ -923,34 +1393,42 @@ export class AgentSession {
     /**
      * Internal: Queue a steering message (already expanded, no extension command check).
      */
-    async _queueSteer(text, images) {
+    async _queueSteer(text, images, sessionEntries) {
         this._steeringMessages.push(text);
         this._emitQueueUpdate();
         const content = [{ type: "text", text }];
         if (images) {
             content.push(...images);
         }
-        this.agent.steer({
+        const message = {
             role: "user",
             content,
             timestamp: Date.now(),
-        });
+        };
+        if (sessionEntries?.length) {
+            this._inputSessionEntries.set(message, sessionEntries);
+        }
+        this.agent.steer(message);
     }
     /**
      * Internal: Queue a follow-up message (already expanded, no extension command check).
      */
-    async _queueFollowUp(text, images) {
+    async _queueFollowUp(text, images, sessionEntries) {
         this._followUpMessages.push(text);
         this._emitQueueUpdate();
         const content = [{ type: "text", text }];
         if (images) {
             content.push(...images);
         }
-        this.agent.followUp({
+        const message = {
             role: "user",
             content,
             timestamp: Date.now(),
-        });
+        };
+        if (sessionEntries?.length) {
+            this._inputSessionEntries.set(message, sessionEntries);
+        }
+        this.agent.followUp(message);
     }
     /**
      * Throw an error if the text is an extension command.
@@ -996,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);
@@ -1093,6 +1571,7 @@ export class AgentSession {
      */
     async abort() {
         this.abortRetry();
+        this._resetOutputThroughput();
         this.agent.abort();
         await this.agent.waitForIdle();
     }
@@ -1280,6 +1759,7 @@ export class AgentSession {
      * @param customInstructions Optional instructions for the compaction summary
      */
     async compact(customInstructions) {
+        this._resetOutputThroughput();
         this._disconnectFromAgent();
         await this.abort();
         this._compactionAbortController = new AbortController();
@@ -1417,6 +1897,7 @@ export class AgentSession {
         // Skip if message was aborted (user cancelled) - unless skipAbortedCheck is false
         if (skipAbortedCheck && assistantMessage.stopReason === "aborted")
             return;
+        // SCRAMJET-DIVERGENCE: Total context and independent input limits are separate constraints.
         const contextWindow = this.model?.contextWindow ?? 0;
         // Skip overflow check if the message came from a different model.
         // This handles the case where user switched from a smaller-context model (e.g. opus)
@@ -1432,7 +1913,8 @@ export class AgentSession {
             return;
         }
         // Case 1: Overflow - LLM returned context overflow error
-        if (sameModel && isContextOverflow(assistantMessage, contextWindow)) {
+        if (sameModel &&
+            isContextOverflow(assistantMessage, Math.min(contextWindow, this.model?.maxInputTokens ?? Infinity))) {
             if (this._overflowRecoveryAttempted) {
                 this._emit({
                     type: "compaction_end",
@@ -1477,7 +1959,8 @@ export class AgentSession {
         else {
             contextTokens = calculateContextTokens(assistantMessage.usage);
         }
-        if (shouldCompact(contextTokens, contextWindow, settings)) {
+        if (shouldCompact(contextTokens, contextWindow, settings) ||
+            (contextWindow > settings.reserveTokens && contextTokens > (this.model?.maxInputTokens ?? Infinity))) {
             await this._runAutoCompaction("threshold", false);
         }
     }
@@ -1773,6 +2256,8 @@ export class AgentSession {
             getActiveTools: () => this.getActiveToolNames(),
             getAllTools: () => this.getAllTools(),
             setActiveTools: (toolNames) => this.setActiveToolsByName(toolNames),
+            // SCRAMJET-DIVERGENCE: harness-tool invocation (#244).
+            invokeHarnessTool: (name, args, options) => this.invokeHarnessTool(name, args, options),
             refreshTools: () => this._refreshToolRegistry(),
             getCommands,
             setModel: async (model) => {
@@ -1785,6 +2270,7 @@ export class AgentSession {
             setThinkingLevel: (level) => this.setThinkingLevel(level),
         }, {
             getModel: () => this.model,
+            getScopedModels: () => this.scopedModels,
             isIdle: () => !this.isStreaming,
             getSignal: () => this.agent.signal,
             abort: () => this.abort(),
@@ -1931,10 +2417,21 @@ export class AgentSession {
     }
     async reload() {
         const previousFlagValues = this._extensionRunner.getFlagValues();
-        await emitSessionShutdownEvent(this._extensionRunner, { type: "session_shutdown", reason: "reload" });
+        // SCRAMJET-DIVERGENCE: the Scramjet builtin is a required product component, so reload must validate
+        // the replacement loader before any irreversible runtime mutation. settingsManager.reload() runs first —
+        // it commits fresh settings before the loader can throw, but the re-read is idempotent, so a failed reload
+        // leaves the runtime itself untouched. It also runs first
+        // because the loader's path resolution reads live settings (the loader defers its own settings/source-map
+        // commit until after the builtin init succeeds, so on this path the shared manager is intentionally read
+        // twice). resourceLoader.reload() then re-runs the required
+        // builtin and throws RequiredBuiltinInitError on failure — before session_shutdown is emitted and before
+        // resetApiProviders(). A throwing builtin therefore leaves the current runner, resources, and providers
+        // intact and fires no session_shutdown; only a validated candidate proceeds to teardown and rebuild.
         await this.settingsManager.reload();
-        resetApiProviders();
         await this._resourceLoader.reload();
+        await emitSessionShutdownEvent(this._extensionRunner, { type: "session_shutdown", reason: "reload" });
+        resetApiProviders();
+        this._runPromptComposition = { kind: "generated-base" };
         this._buildRuntime({
             activeToolNames: this.getActiveToolNames(),
             flagValues: previousFlagValues,
@@ -1952,114 +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, contextWindow))
-            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) {
+    _finishRetry(record, end) {
+        const retry = this._retry;
+        this._retry = undefined;
+        try {
+            this._appendAutoRetryRecord(record);
+        }
+        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._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();
-        if (!settings.enabled) {
-            this._resolveRetry();
+        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;
         }
-        // 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;
-            });
-        }
-        this._retryAttempt++;
-        if (this._retryAttempt > settings.maxRetries) {
-            // Max retries exceeded, emit final failure and reset
-            this._emit({
+        if (this._runRetryCount > cumulativeCap) {
+            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._retryAttempt - 1,
-                finalError: message.errorMessage,
+                attempt: attemptsCompleted,
+                finalError: `Repeated retry failures (${attemptsCompleted} total attempts this prompt). ${message.errorMessage ?? ""}`.trim(),
             });
-            this._retryAttempt = 0;
-            this._resolveRetry(); // Resolve so waitForRetry() completes
             return false;
         }
-        const delayMs = settings.baseDelayMs * 2 ** (this._retryAttempt - 1);
+        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),
+            });
+        }
+        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() {
@@ -2279,7 +2973,7 @@ export class AgentSession {
             if (targetEntry.type === "message" && targetEntry.message.role === "user") {
                 // User message: leaf = parent (null if root), text goes to editor
                 newLeafId = targetEntry.parentId;
-                editorText = this._extractUserMessageText(targetEntry.message.content);
+                editorText = restoreScramjetCommandInvocation(targetEntry, this.sessionManager.getEntries());
             }
             else if (targetEntry.type === "custom_message") {
                 // Custom message: leaf = parent (null if root), text goes to editor
@@ -2343,30 +3037,20 @@ export class AgentSession {
      */
     getUserMessagesForForking() {
         const entries = this.sessionManager.getEntries();
+        const commandStarts = indexScramjetCommandStarts(entries);
         const result = [];
         for (const entry of entries) {
             if (entry.type !== "message")
                 continue;
             if (entry.message.role !== "user")
                 continue;
-            const text = this._extractUserMessageText(entry.message.content);
+            const text = restoreScramjetCommandInvocation(entry, commandStarts);
             if (text) {
                 result.push({ entryId: entry.id, text });
             }
         }
         return result;
     }
-    _extractUserMessageText(content) {
-        if (typeof content === "string")
-            return content;
-        if (Array.isArray(content)) {
-            return content
-                .filter((c) => c.type === "text")
-                .map((c) => c.text)
-                .join("");
-        }
-        return "";
-    }
     /**
      * Get session statistics.
      */