@leanandmean/coding-agent 0.74.1-scramjet.7 → 0.74.1-scramjet.71

package/dist/core/agent-session.js

@@ -14,19 +14,25 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
-import { clampThinkingLevel, cleanupSessionResources, flattenSystemPrompt, getSupportedThinkingLevels, isContextOverflow, modelsAreEqual, resetApiProviders, } from "@leanandmean/ai";
+// SCRAMJET-DIVERGENCE: provider-safe harness tool-call id generation for the persisted-settlement
+// acknowledgement key (#341).
+import { generateHarnessToolCallId } from "@leanandmean/agent";
+import { blocksFailureRecovery, clampThinkingLevel, cleanupSessionResources, flattenSystemPrompt, getSupportedThinkingLevels, inspectFailureEvidence, isContextOverflow, modelsAreEqual, resetApiProviders, } from "@leanandmean/ai";
 import { theme } from "../modes/interactive/theme/theme.js";
 import { stripFrontmatter } from "../utils/frontmatter.js";
 import { sleep } from "../utils/sleep.js";
 import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.js";
 import { executeBashWithOperations } from "./bash-executor.js";
-import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
+import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
 import { DEFAULT_THINKING_LEVEL } from "./defaults.js";
 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,35 +59,80 @@ 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);
+}
+function validRecordedCost(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
 export class AgentSession {
     agent;
     sessionManager;
     settingsManager;
+    outputThroughputHistoryPath;
     _scopedModels;
     // Event subscription state
     _unsubscribeAgent;
     _eventListeners = [];
     _agentEventQueue = Promise.resolve();
+    // SCRAMJET-DIVERGENCE: execution ownership survives final-event queue latency until append succeeds (#598).
+    _toolCostExecutions = new Map();
+    _pendingToolCosts = new Set();
+    _historicalCostDefinitions = new Map();
+    _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;
+    _manualCompactionDrain;
     _autoCompactionAbortController = undefined;
     _overflowRecoveryAttempted = false;
     // 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 = [];
@@ -104,6 +155,9 @@ export class AgentSession {
     _extensionErrorUnsubscriber;
     // Model registry for API key resolution
     _modelRegistry;
+    // SCRAMJET-DIVERGENCE: Ephemeral routes retain live preferences and journal changes without changing shared defaults.
+    _persistModelPreferences;
+    _sessionThinkingLevelPreference;
     // Tool registry for extension getTools/setTools
     _toolRegistry = new Map();
     _toolDefinitions = new Map();
@@ -114,15 +168,28 @@ 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 ?? [];
         this._cwd = config.cwd;
         this._modelRegistry = config.modelRegistry;
+        this._persistModelPreferences = config.persistModelPreferences ?? true;
         this._extensionRunnerRef = config.extensionRunnerRef;
         this._initialActiveToolNames = config.initialActiveToolNames;
         this._allowedToolNames = config.allowedToolNames ? new Set(config.allowedToolNames) : undefined;
@@ -161,8 +228,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 +308,200 @@ 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));
+        if (this._disposed)
+            return;
+        this._captureOutputThroughput(event);
+        const toolCost = this._captureToolCost(event);
+        const runSettlement = this._captureAgentRunSettlement(event);
+        const harnessAck = this._harnessPersistenceAckForEvent(event);
+        const processing = this._agentEventQueue.then(() => this._processAgentEventTracked(event, runSettlement, harnessAck, toolCost), () => this._processAgentEventTracked(event, runSettlement, harnessAck, toolCost));
+        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: scalar reports are captured before mutable events enter async hooks (#598).
+    _captureToolCost(event) {
+        if (event.type === "tool_execution_start") {
+            const execution = {};
+            this._toolCostExecutions.set(event.toolCallId, execution);
+            this._pendingToolCosts.add(execution);
             return;
         }
-        const settings = this.settingsManager.getRetrySettings();
-        if (!settings.enabled) {
+        let toolCallId;
+        let reported;
+        const final = event.type === "message_end" && event.message.role === "toolResult";
+        if (event.type === "tool_execution_update" || event.type === "tool_execution_end") {
+            toolCallId = event.toolCallId;
+            reported = event.type === "tool_execution_update" ? event.partialResult?.cost : event.result?.cost;
+        }
+        else if (event.type === "message_end" && event.message.role === "toolResult") {
+            toolCallId = event.message.toolCallId;
+            reported = event.message.cost;
+        }
+        else {
             return;
         }
-        const lastAssistant = this._findLastAssistantInMessages(event.messages);
-        if (!lastAssistant || !this._isRetryableError(lastAssistant)) {
+        let execution = this._toolCostExecutions.get(toolCallId);
+        if (!execution && validRecordedCost(reported)) {
+            execution = {};
+            this._toolCostExecutions.set(toolCallId, execution);
+            this._pendingToolCosts.add(execution);
+        }
+        if (execution && validRecordedCost(reported))
+            execution.cost = reported;
+        if (final) {
+            this._toolCostExecutions.delete(toolCallId);
+            return execution;
+        }
+        return;
+    }
+    // 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;
         }
-        this._retryPromise = new Promise((resolve) => {
-            this._retryResolve = resolve;
-        });
+        const generation = this._outputThroughputGeneration;
+        if (generation === undefined)
+            return;
+        if (event.type === "message_update" && event.message.role === "assistant") {
+            this._outputThroughputTracker.observe(generation, event.assistantMessageEvent);
+        }
+        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);
+            }
+        }
     }
-    _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, toolCost) {
+        try {
+            await this._processAgentEvent(event, run, harnessAck !== undefined, toolCost);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            if (this._manualCompactionDrain)
+                this._manualCompactionDrain.firstError ??= error;
+            if (harnessAck) {
+                harnessAck.firstPersistenceError ??= error;
+            }
+            else if (run && !this._manualCompactionDrain) {
+                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, toolCost) {
+        if (this._disposed)
+            return;
+        // SCRAMJET-DIVERGENCE: queued lifecycle events must respect manual compaction ownership (#598).
+        if (this._manualCompactionDrain && event.type !== "message_end" && event.type !== "agent_end")
+            return;
+        if (this._manualCompactionDrain && event.type === "agent_end") {
+            if (this._retry)
+                this._finishCancelledRetry("cancelled_during_continuation");
+            if (run)
+                this._completeAgentRun(run, this._manualCompactionDrain.firstError);
+            return;
+        }
         // 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") {
@@ -305,8 +526,22 @@ export class AgentSession {
         }
         // Emit to extensions first
         await this._emitExtensionEvent(event);
+        if (event.type === "message_end" && event.message.role === "toolResult" && toolCost?.cost !== undefined) {
+            event.message.cost = toolCost.cost;
+        }
+        // An awaited hook may have acquired manual ownership while this event was in flight.
+        if (this._manualCompactionDrain && event.type !== "message_end") {
+            if (event.type === "agent_end" && run) {
+                if (this._retry)
+                    this._finishCancelledRetry("cancelled_during_continuation");
+                this._completeAgentRun(run, this._manualCompactionDrain.firstError);
+            }
+            return;
+        }
         // 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 +552,132 @@ 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);
+                // 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 (toolCost)
+                    this._pendingToolCosts.delete(toolCost);
+                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);
+                    // 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
-            // 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._manualCompactionDrain) {
+                this._overflowRecoveryAttempted = false;
+                if (this._retry)
+                    this._retry = { ...this._retry, attempt: 0 };
+            }
+        }
+        if (event.type === "agent_end") {
+            if (this._disposed || !run)
+                return;
+            if (this._manualCompactionDrain) {
+                if (this._retry)
+                    this._finishCancelledRetry("cancelled_during_continuation");
+                this._completeAgentRun(run, this._manualCompactionDrain.firstError);
+                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;
             }
-        }
-        // 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);
+            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;
+            }
+            else {
+                const { kind: _kind, ...cause } = classification;
+                this._finishRetryWithoutSuccess({ schemaVersion: 1, outcome: "not_attempted", ...cause }, msg);
             }
-            this._resolveRetry();
+            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")
@@ -510,8 +826,8 @@ export class AgentSession {
      * Preserves all existing listeners.
      */
     _reconnectToAgent() {
-        if (this._unsubscribeAgent)
-            return; // Already connected
+        if (this._disposed || this._unsubscribeAgent)
+            return; // Already connected or disposed
         this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
     }
     /**
@@ -519,7 +835,69 @@ 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._toolCostExecutions.clear();
+        this._pendingToolCosts.clear();
+        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 +925,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.
@@ -600,7 +1020,7 @@ export class AgentSession {
         // Rebuild base system prompt with new tool set
         this._rebuildSystemPrompt(validToolNames);
     }
-    // SCRAMJET-DIVERGENCE: harness-tool invocation (#244).
+    // SCRAMJET-DIVERGENCE: harness-tool invocation (#244), persisted-settlement boundary (#341).
     /**
      * Execute a registered tool as a harness-originated call (not requested by the model).
      *
@@ -612,13 +1032,97 @@ export class AgentSession {
      * 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.`);
+        }
+        // SCRAMJET-DIVERGENCE: reject new session work before allocating invocation ownership (#598).
+        if (this._compactionAbortController) {
+            throw new Error(`Cannot invoke harness tool "${name}": manual compaction is in progress. Retry after it settles.`);
+        }
         const tool = this._toolRegistry.get(name);
         if (!tool) {
             throw new Error(`Cannot invoke harness tool "${name}": no tool with that name is registered.`);
         }
-        await this.agent.runHarnessTool(tool, args, options);
+        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() {
@@ -684,6 +1188,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));
@@ -704,6 +1221,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,
@@ -713,9 +1231,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
@@ -733,6 +1252,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()
@@ -744,6 +1265,7 @@ export class AgentSession {
                     return;
                 }
             }
+            this._assertRetryNotOwningIdleAgent();
             // Emit input event for extension interception (before skill/template expansion)
             let currentText = text;
             let currentImages = options?.images;
@@ -756,6 +1278,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)
@@ -771,11 +1295,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;
             }
@@ -797,7 +1322,7 @@ export class AgentSession {
             // Check if we need to compact before sending (catches aborted responses)
             const lastAssistant = this._findLastAssistantMessage();
             if (lastAssistant) {
-                await this._checkCompaction(lastAssistant, false);
+                await this._checkCompaction(lastAssistant, "new_prompt");
             }
             // Build messages array (custom message if any, then user message)
             messages = [];
@@ -806,16 +1331,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
@@ -835,15 +1365,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);
@@ -852,9 +1385,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.
@@ -951,34 +1484,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.
@@ -1024,7 +1565,7 @@ export class AgentSession {
             }
         }
         else if (options?.triggerTurn) {
-            await this.agent.prompt(appMessage);
+            await this._runAgentPrompt(appMessage);
         }
         else {
             this.agent.state.messages.push(appMessage);
@@ -1121,6 +1662,7 @@ export class AgentSession {
      */
     async abort() {
         this.abortRetry();
+        this._resetOutputThroughput();
         this.agent.abort();
         await this.agent.waitForIdle();
     }
@@ -1139,7 +1681,7 @@ export class AgentSession {
     }
     /**
      * Set model directly.
-     * Validates that auth is configured, saves to session and settings.
+     * Validates auth, journals selection, and optionally saves global defaults.
      * @throws Error if no auth is configured for the model
      */
     async setModel(model) {
@@ -1150,7 +1692,8 @@ export class AgentSession {
         const thinkingLevel = this._getThinkingLevelForModelSwitch();
         this.agent.state.model = model;
         this.sessionManager.appendModelChange(model.provider, model.id);
-        this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);
+        if (this._persistModelPreferences)
+            this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);
         // Re-clamp thinking level for new model's capabilities
         this.setThinkingLevel(thinkingLevel);
         await this._emitModelSelect(model, previousModel, "set");
@@ -1182,7 +1725,9 @@ export class AgentSession {
         // Apply model
         this.agent.state.model = next.model;
         this.sessionManager.appendModelChange(next.model.provider, next.model.id);
-        this.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id);
+        if (this._persistModelPreferences) {
+            this.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id);
+        }
         // Apply thinking level.
         // - Explicit scoped model thinking level overrides current session level
         // - Undefined scoped model thinking level inherits the current session preference
@@ -1205,7 +1750,9 @@ export class AgentSession {
         const thinkingLevel = this._getThinkingLevelForModelSwitch();
         this.agent.state.model = nextModel;
         this.sessionManager.appendModelChange(nextModel.provider, nextModel.id);
-        this.settingsManager.setDefaultModelAndProvider(nextModel.provider, nextModel.id);
+        if (this._persistModelPreferences) {
+            this.settingsManager.setDefaultModelAndProvider(nextModel.provider, nextModel.id);
+        }
         // Re-clamp thinking level for new model's capabilities
         this.setThinkingLevel(thinkingLevel);
         await this._emitModelSelect(nextModel, currentModel, "cycle");
@@ -1217,7 +1764,7 @@ export class AgentSession {
     /**
      * Set thinking level.
      * Clamps to model capabilities based on available thinking levels.
-     * Saves to session and settings only if the level actually changes.
+     * Journals actual changes and optionally saves global defaults.
      */
     setThinkingLevel(level) {
         const availableLevels = this.getAvailableThinkingLevels();
@@ -1229,7 +1776,12 @@ export class AgentSession {
         if (isChanging) {
             this.sessionManager.appendThinkingLevelChange(effectiveLevel);
             if (this.supportsThinking() || effectiveLevel !== "off") {
-                this.settingsManager.setDefaultThinkingLevel(effectiveLevel);
+                if (this._persistModelPreferences) {
+                    this.settingsManager.setDefaultThinkingLevel(effectiveLevel);
+                }
+                else {
+                    this._sessionThinkingLevelPreference = effectiveLevel;
+                }
             }
             this._emit({ type: "thinking_level_changed", level: effectiveLevel });
             void this._extensionRunner.emit({
@@ -1273,6 +1825,9 @@ export class AgentSession {
             return explicitLevel;
         }
         if (!this.supportsThinking()) {
+            if (!this._persistModelPreferences && this._sessionThinkingLevelPreference !== undefined) {
+                return this._sessionThinkingLevelPreference;
+            }
             return this.settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL;
         }
         return this.thinkingLevel;
@@ -1308,11 +1863,32 @@ export class AgentSession {
      * @param customInstructions Optional instructions for the compaction summary
      */
     async compact(customInstructions) {
-        this._disconnectFromAgent();
-        await this.abort();
-        this._compactionAbortController = new AbortController();
-        this._emit({ type: "compaction_start", reason: "manual" });
+        // SCRAMJET-DIVERGENCE: acquire one owner before awaits and drain terminal persistence (#598).
+        if (this._disposed)
+            throw new Error("Cannot compact a disposed session.");
+        if (this.isCompacting)
+            throw new Error("Compaction or branch summarization is already in progress. Retry after it settles.");
+        if (this.agent.hasActiveTransientHarnessTools) {
+            throw new Error("A harness tool is still executing outside an Agent run. Retry compaction after its persisted settlement.");
+        }
+        const controller = new AbortController();
+        this._compactionAbortController = controller;
+        const drain = {};
+        this._manualCompactionDrain = drain;
+        const runs = [...this._unsettledAgentRuns];
         try {
+            this._resetOutputThroughput();
+            this._disconnectFromAgent();
+            this._unsubscribeAgent = this.agent.subscribe((event) => this._handleAgentEvent(event));
+            this._emit({ type: "compaction_start", reason: "manual" });
+            await this.abort();
+            await this._agentEventQueue;
+            if (drain.firstError)
+                throw drain.firstError;
+            if (this._disposed)
+                throw new Error("Session disposed during compaction.");
+            if (controller.signal.aborted)
+                throw new Error("Compaction cancelled");
             if (!this.model) {
                 throw new Error(formatNoModelSelectedMessage());
             }
@@ -1336,7 +1912,7 @@ export class AgentSession {
                     preparation,
                     branchEntries: pathEntries,
                     customInstructions,
-                    signal: this._compactionAbortController.signal,
+                    signal: controller.signal,
                 }));
                 if (result?.cancel) {
                     throw new Error("Compaction cancelled");
@@ -1359,13 +1935,15 @@ export class AgentSession {
             }
             else {
                 // Generate compaction result
-                const result = await compact(preparation, this.model, apiKey, headers, customInstructions, this._compactionAbortController.signal, this.thinkingLevel);
+                const result = await compact(preparation, this.model, apiKey, headers, customInstructions, controller.signal, this.thinkingLevel);
                 summary = result.summary;
                 firstKeptEntryId = result.firstKeptEntryId;
                 tokensBefore = result.tokensBefore;
                 details = result.details;
             }
-            if (this._compactionAbortController.signal.aborted) {
+            if (this._disposed)
+                throw new Error("Session disposed during compaction.");
+            if (controller.signal.aborted) {
                 throw new Error("Compaction cancelled");
             }
             this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension);
@@ -1397,8 +1975,13 @@ export class AgentSession {
             return compactionResult;
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            const aborted = message === "Compaction cancelled" || (error instanceof Error && error.name === "AbortError");
+            const failure = drain.firstError ?? error;
+            const settlementError = failure instanceof Error ? failure : new Error(String(failure));
+            this._releaseRetryForFailedRun(settlementError);
+            for (const run of runs)
+                this._completeAgentRun(run, settlementError);
+            const message = settlementError.message;
+            const aborted = message === "Compaction cancelled" || settlementError.name === "AbortError";
             this._emit({
                 type: "compaction_end",
                 reason: "manual",
@@ -1407,9 +1990,11 @@ export class AgentSession {
                 willRetry: false,
                 errorMessage: aborted ? undefined : `Compaction failed: ${message}`,
             });
-            throw error;
+            throw failure;
         }
         finally {
+            this._disconnectFromAgent();
+            this._manualCompactionDrain = undefined;
             this._compactionAbortController = undefined;
             this._reconnectToAgent();
         }
@@ -1436,15 +2021,44 @@ export class AgentSession {
      * 2. Threshold: Context over threshold, compact, NO auto-retry (user continues manually)
      *
      * @param assistantMessage The assistant message to check
-     * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
      */
-    async _checkCompaction(assistantMessage, skipAbortedCheck = true) {
+    async _checkCompaction(assistantMessage, trigger = "settlement") {
+        if (this._manualCompactionDrain)
+            return;
         const settings = this.settingsManager.getCompactionSettings();
         if (!settings.enabled)
             return;
-        // Skip if message was aborted (user cancelled) - unless skipAbortedCheck is false
-        if (skipAbortedCheck && assistantMessage.stopReason === "aborted")
+        // SCRAMJET-DIVERGENCE: New prompts maintain context independently of failed-turn recovery.
+        if (trigger === "settlement" && blocksFailureRecovery(assistantMessage))
+            return;
+        if (trigger === "new_prompt") {
+            const boundary = getLatestCompactionEntry(this.sessionManager.getBranch());
+            const messages = this.agent.state.messages;
+            const reverseIndex = [...messages]
+                .reverse()
+                .findIndex((message) => message.role === "assistant" &&
+                message.origin !== "harness" &&
+                message.stopReason !== "error" &&
+                message.stopReason !== "aborted" &&
+                message.provider === this.model?.provider &&
+                message.model === this.model?.id &&
+                Number.isFinite(calculateContextTokens(message.usage)) &&
+                calculateContextTokens(message.usage) >= 0 &&
+                (!boundary || message.timestamp > new Date(boundary.timestamp).getTime()) &&
+                [message.usage.input, message.usage.output, message.usage.cacheRead, message.usage.cacheWrite].every((n) => Number.isFinite(n) && n >= 0));
+            if (reverseIndex < 0)
+                return;
+            const sourceIndex = messages.length - reverseIndex - 1;
+            const source = messages[sourceIndex];
+            const tokens = calculateContextTokens(source.usage) +
+                messages.slice(sourceIndex + 1).reduce((total, message) => total + estimateTokens(message), 0);
+            const window = this.model?.contextWindow ?? 0;
+            if (shouldCompact(tokens, window, settings) ||
+                (window > settings.reserveTokens && tokens > (this.model?.maxInputTokens ?? Infinity)))
+                await this._runAutoCompaction("threshold", false);
             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)
@@ -1460,7 +2074,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",
@@ -1505,7 +2120,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);
         }
     }
@@ -1514,9 +2130,10 @@ export class AgentSession {
      */
     async _runAutoCompaction(reason, willRetry) {
         const settings = this.settingsManager.getCompactionSettings();
-        this._emit({ type: "compaction_start", reason });
+        // SCRAMJET-DIVERGENCE: reentrant subscribers must observe compaction ownership (#598).
         this._autoCompactionAbortController = new AbortController();
         try {
+            this._emit({ type: "compaction_start", reason });
             if (!this.model) {
                 this._emit({
                     type: "compaction_end",
@@ -1815,6 +2432,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(),
@@ -1860,7 +2478,13 @@ export class AgentSession {
                 definition,
                 sourceInfo: createSyntheticSourceInfo(`<sdk:${definition.name}>`, { source: "sdk" }),
             })),
-        ].filter((tool) => isAllowedTool(tool.definition.name));
+        ];
+        // SCRAMJET-DIVERGENCE: historical interpretation follows definition collision winners, not execution allowlists (#598).
+        this._historicalCostDefinitions = new Map(this._baseToolDefinitions);
+        for (const tool of allCustomTools) {
+            this._historicalCostDefinitions.set(tool.definition.name, tool.definition);
+        }
+        const allowedCustomTools = allCustomTools.filter((tool) => isAllowedTool(tool.definition.name));
         const definitionRegistry = new Map(Array.from(this._baseToolDefinitions.entries())
             .filter(([name]) => isAllowedTool(name))
             .map(([name, definition]) => [
@@ -1870,7 +2494,7 @@ export class AgentSession {
                 sourceInfo: createSyntheticSourceInfo(`<builtin:${name}>`, { source: "builtin" }),
             },
         ]));
-        for (const tool of allCustomTools) {
+        for (const tool of allowedCustomTools) {
             definitionRegistry.set(tool.definition.name, {
                 definition: tool.definition,
                 sourceInfo: tool.sourceInfo,
@@ -1890,7 +2514,7 @@ export class AgentSession {
         })
             .filter((entry) => entry !== undefined));
         const runner = this._extensionRunner;
-        const wrappedExtensionTools = wrapRegisteredTools(allCustomTools, runner);
+        const wrappedExtensionTools = wrapRegisteredTools(allowedCustomTools, runner);
         const wrappedBuiltInTools = wrapRegisteredTools(Array.from(this._baseToolDefinitions.values())
             .filter((definition) => isAllowedTool(definition.name))
             .map((definition) => ({
@@ -1961,10 +2585,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,
@@ -1982,114 +2617,325 @@ 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) {
+        if ((message.origin === "harness" || message.stopReason === "aborted") && blocksFailureRecovery(message))
+            return { kind: "do_not_retry", reason: "non_provider_failure", evidence: "none" };
         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 = inspectFailureEvidence(message.diagnostics);
+        if (structured.status === "valid") {
+            if (structured.source !== "provider")
+                return { kind: "do_not_retry", reason: "non_provider_failure", evidence: "none" };
+            if (structured.suppression)
+                return { kind: "do_not_retry", reason: structured.suppression, evidence: structured.family };
+            if (structured.transient || ["missing_terminal_event", "missing_body"].includes(structured.category))
+                return { kind: "retry", evidence: structured.family };
+            return {
+                kind: "do_not_retry",
+                reason: ["unknown", "provider_error", "malformed_event"].includes(structured.category)
+                    ? "structured_unknown"
+                    : "structured_non_transient",
+                evidence: structured.family,
+            };
+        }
+        if (structured.status === "conflicting")
+            return { kind: "do_not_retry", reason: "invalid_failure_evidence", evidence: "none" };
+        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._manualCompactionDrain) {
+                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._manualCompactionDrain)
+            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;
+        const cumulativeCap = Math.min(Number.MAX_SAFE_INTEGER, settings.maxRetries * 2);
+        if ((this._retry?.attempt ?? 0) >= 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;
+            this._finishRetry({
+                schemaVersion: 1,
+                outcome: "exhausted",
+                reason: "cumulative_limit",
+                attemptsCompleted: this._bounded(attemptsCompleted),
+                maxAttempts: this._bounded(settings.maxRetries),
+                cumulativeErrors: this._bounded(this._runRetryCount + 1),
+            }, {
                 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);
+        this._runRetryCount++;
+        const delayMs = settings.baseDelayMs === 0
+            ? 0
+            : Math.min(2_147_483_647, settings.baseDelayMs * 2 ** Math.min(31, 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);
+        }
+        if (this._manualCompactionDrain)
+            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);
+        }
+        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 };
         }
-        await this._retryPromise;
+        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() {
@@ -2309,7 +3155,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
@@ -2373,29 +3219,56 @@ 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("");
+    // SCRAMJET-DIVERGENCE: whole-journal parent/tool costs plus reports awaiting successful append (#598).
+    getRecordedSessionCost() {
+        let total = 0;
+        for (const entry of this.sessionManager.getEntries()) {
+            if (entry.type !== "message")
+                continue;
+            const message = entry.message;
+            if (message.role === "assistant") {
+                if (validRecordedCost(message.usage?.cost?.total))
+                    total += message.usage.cost.total;
+            }
+            else if (message.role === "toolResult") {
+                if (validRecordedCost(message.cost)) {
+                    total += message.cost;
+                    continue;
+                }
+                const definition = this._historicalCostDefinitions.get(message.toolName);
+                if (!definition?.getHistoricalCost)
+                    continue;
+                try {
+                    const cost = definition.getHistoricalCost(message.details);
+                    if (validRecordedCost(cost))
+                        total += cost;
+                }
+                catch (error) {
+                    this._extensionRunner.emitError({
+                        extensionPath: `tool:${message.toolName}`,
+                        event: "historical_cost",
+                        error: `Failed to interpret historical tool cost: ${error instanceof Error ? error.message : String(error)}`,
+                    });
+                }
+            }
         }
-        return "";
+        for (const execution of this._pendingToolCosts)
+            total += execution.cost ?? 0;
+        return total;
     }
     /**
      * Get session statistics.