open-multi-agent-kit 0.90.8 → 0.91.0

package/dist/core/agent-session.js

@@ -12,19 +12,30 @@
  *
  * Modes use this class and add their own I/O layer on top.
  */
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { repairTranscriptIntegrity, } from "omk-agent-core";
 import { clampThinkingLevel, cleanupSessionResources, getSupportedThinkingLevels, isContextOverflow, modelsAreEqual, resetApiProviders, streamSimple, } from "omk-ai";
 import { theme } from "../modes/interactive/theme/theme.js";
 import { stripFrontmatter } from "../utils/frontmatter.js";
 import { resolvePath } from "../utils/paths.js";
+import { sanitizeBinaryOutput } from "../utils/shell.js";
 import { sleep } from "../utils/sleep.js";
+import { createAdaptorchBridge } from "./adaptorch-bridge.js";
+import { applyCategoryTimeoutDefaults, resolveAgentToolSettings, resolveToolTimeoutCategory, } from "./agent-tool-settings.js";
 import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.js";
 import { parseBangInvocation } from "./bang-skill-invocation.js";
 import { executeBashWithOperations } from "./bash-executor.js";
 import { classifyShellCommand } from "./command-safety.js";
-import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateProjectedContextTokens, generateBranchSummary, prepareCompaction, resolveCompactionModel, shouldCompact, } from "./compaction/index.js";
+import { getCompactionHeadroomThreshold } from "./compaction/compaction.js";
+import { createCompactionHysteresisConfig, createCompactionHysteresisState, stepCompactionHysteresis, } from "./compaction/hysteresis.js";
+import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateProjectedContextTokens, generateBranchSummary, prepareCompaction, resolveCompactionModel, } from "./compaction/index.js";
 import { compactionEmitWillRetry } from "./compaction/resume-policy.js";
+import { createCompactionEnvelope, createCompactionSourceIdentity, createCompactionTransaction, decideCompactionCommit, evaluateCompactionBarrier, validateCompactionEnvelope, } from "./compaction/transaction.js";
+import { estimateToolResultReserve, } from "./context-budget-reserved-tokens.js";
+import { applyContextCacheInvalidation, createContextCacheInvalidationSnapshot, } from "./context-budget-v2-cache-invalidation.js";
 import { createMemoryContextBudgetCacheProviderV2 } from "./context-budget-v2-cache-provider.js";
 import { DEFAULT_THINKING_LEVEL } from "./defaults.js";
 import { exportSessionToHtml } from "./export-html/index.js";
@@ -37,11 +48,16 @@ import { grokPlaybookAppendForProvider } from "./grok-playbook.js";
 import { assertLoadoutAccess, decideLoadoutAccess } from "./loadout-access-policy.js";
 import { findExactModelReferenceMatch } from "./model-resolver.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
+import { isContentSafetyStopMessage, isStickySafetyModel, isTransientProviderErrorMessage, pickFailoverCandidate, resolveProviderResilience, stickySafetyBlockMessage, } from "./provider-resilience.js";
 import { getBiasStepsForCell, getDefaultRouterBiasSnapshotPath, parseRouterBiasSnapshot, } from "./reasoning-router-bias.js";
 import { classifyTaskV4, resolveThinkingLevelV4WithUncertainty } from "./reasoning-router-v4.js";
+import { redactSensitiveText } from "./redaction.js";
 import { appendRouterFeedbackRecord, } from "./router-feedback-collector.js";
+import { RunJournalStore } from "./run-journal-store.js";
 import { detectSandboxBackend } from "./sandbox/backend.js";
+import { inspectSessionIntegrity } from "./session-integrity.js";
 import { CURRENT_SESSION_VERSION, getLatestCompactionEntry } from "./session-manager.js";
+import { classifySessionTermination, } from "./session-termination.js";
 import { createSyntheticSourceInfo } from "./source-info.js";
 import { buildSystemPrompt } from "./system-prompt.js";
 import { createLocalBashOperations } from "./tools/bash.js";
@@ -73,6 +89,23 @@ function mergePromptActiveSkillNames(first, second) {
     }
     return names;
 }
+const PENDING_TOOL_RESULT_TOKENS = {
+    text: 1024,
+    image: 4096,
+    "large-output": 16_384,
+};
+const TEXT_RESULT_TOOLS = new Set(["edit", "find", "grep", "ls", "read", "write"]);
+const IMAGE_PATH_PATTERN = /\.(?:avif|gif|jpe?g|png|webp)$/iu;
+function pendingToolResultClass(name, args) {
+    if (name === "read" &&
+        typeof args === "object" &&
+        args !== null &&
+        typeof Reflect.get(args, "path") === "string" &&
+        IMAGE_PATH_PATTERN.test(Reflect.get(args, "path"))) {
+        return "image";
+    }
+    return TEXT_RESULT_TOOLS.has(name) ? "text" : "large-output";
+}
 // ============================================================================
 // Constants
 // ============================================================================
@@ -98,6 +131,102 @@ function buildSandboxDeniedBashResult(reason) {
         truncated: false,
     };
 }
+function snapshotContractError(reason) {
+    return new Error(`Finalized message replacement must be a plain serializable snapshot: ${reason}`);
+}
+/**
+ * Clone a finalized message replacement into the JSON-compatible snapshot
+ * persisted by SessionManager. Undefined remains allowed as ordinary optional
+ * message data: JSON omits object properties with undefined values and writes
+ * undefined array elements as null.
+ */
+function clonePlainSnapshot(value, ancestors = new WeakSet(), copies = new WeakMap()) {
+    if (value === null)
+        return value;
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+        case "undefined":
+            return value;
+        case "number":
+            if (!Number.isFinite(value)) {
+                throw snapshotContractError("non-finite number values are not allowed");
+            }
+            return value;
+        case "bigint":
+            throw snapshotContractError("bigint values are not allowed");
+        case "function":
+        case "symbol":
+            throw snapshotContractError(`${typeof value} values are not allowed`);
+        case "object":
+            break;
+        default:
+            throw snapshotContractError(`${typeof value} values are not allowed`);
+    }
+    if (ancestors.has(value)) {
+        throw snapshotContractError("cyclic values are not allowed");
+    }
+    if (copies.has(value)) {
+        return copies.get(value);
+    }
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            const copy = new Array(value.length);
+            copies.set(value, copy);
+            for (const key of Reflect.ownKeys(value)) {
+                if (key === "length")
+                    continue;
+                if (typeof key !== "string" || !/^(0|[1-9]\d*)$/.test(key) || Number(key) >= value.length) {
+                    throw snapshotContractError("arrays may only contain indexed values");
+                }
+                const descriptor = Object.getOwnPropertyDescriptor(value, key);
+                if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
+                    throw snapshotContractError("accessor or non-enumerable properties are not allowed");
+                }
+                copy[Number(key)] = clonePlainSnapshot(descriptor.value, ancestors, copies);
+            }
+            return copy;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw snapshotContractError("non-plain objects are not allowed");
+        }
+        const copy = Object.create(prototype);
+        copies.set(value, copy);
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key !== "string") {
+                throw snapshotContractError("symbol-keyed properties are not allowed");
+            }
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
+                throw snapshotContractError("accessor or non-enumerable properties are not allowed");
+            }
+            Object.defineProperty(copy, key, {
+                value: clonePlainSnapshot(descriptor.value, ancestors, copies),
+                enumerable: true,
+                configurable: true,
+                writable: true,
+            });
+        }
+        return copy;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function freezeSnapshot(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== "object" || seen.has(value))
+        return value;
+    seen.add(value);
+    for (const child of Object.values(value)) {
+        freezeSnapshot(child, seen);
+    }
+    return Object.freeze(value);
+}
+function createImmutableMessageSnapshot(message) {
+    return freezeSnapshot(clonePlainSnapshot(message));
+}
 // ============================================================================
 // AgentSession Class
 // ============================================================================
@@ -127,9 +256,19 @@ export class AgentSession {
      */
     _reasoningRouterBiasSnapshot = null;
     _reasoningRouterBiasSnapshotLoaded = false;
+    /**
+     * AdaptOrch advisory bridge (default-off, global-only opt-in via
+     * `adaptorchBridge.enabled` in ~/.omk/agent/settings.json). Lazily
+     * constructed on the first v4 auto-turn when enabled; stays `null`
+     * otherwise. The bridge is advisory-only: its hint is fused into the
+     * resolver as a bounded ±2 step nudge, never as an override.
+     */
+    _adaptorchBridge = null;
+    _adaptorchBridgeInitAttempted = false;
     // Event subscription state
     _unsubscribeAgent;
     _eventListeners = [];
+    _messageEndReplacements = new WeakMap();
     /** Tracks pending steering messages for UI display. Removed when delivered. */
     _steeringMessages = [];
     /** Tracks pending follow-up messages for UI display. Removed when delivered. */
@@ -140,6 +279,8 @@ export class AgentSession {
     _compactionAbortController = undefined;
     _autoCompactionAbortController = undefined;
     _overflowRecoveryAttempted = false;
+    _thresholdCompactionEmergency = false;
+    _compactionHysteresisState = createCompactionHysteresisState();
     // Branch summarization state
     _branchSummaryAbortController = undefined;
     // Retry state
@@ -171,10 +312,24 @@ export class AgentSession {
     _extensionShutdownHandler;
     _extensionErrorListener;
     _extensionErrorUnsubscriber;
+    // Required durable run/audit chain, persisted next to the session file.
+    _runJournalStore;
+    _activeRunId = null;
+    _pendingRuntimeTerminationCause;
+    _activeRunToolTermination;
+    _lastTermination;
+    _userAbortRequested = false;
+    _replayLedger;
+    _replayGoalId;
+    _replayLaneId;
+    _transcriptRepair;
+    _sessionRiskLevel = "normal";
+    _workspaceMutationCount = 0;
     // Model registry for API key resolution
     _modelRegistry;
     /** Lazy, in-memory only; never shared across sessions or persisted. */
     _contextBudgetCacheProvider;
+    _contextCacheInvalidationSnapshot;
     // Tool registry for extension getTools/setTools
     _toolRegistry = new Map();
     _toolDefinitions = new Map();
@@ -192,6 +347,13 @@ export class AgentSession {
         this._customTools = config.customTools ?? [];
         this._cwd = config.cwd;
         this._modelRegistry = config.modelRegistry;
+        const initialModelId = this._contextCacheModelId(this.agent.state.model);
+        this._contextCacheInvalidationSnapshot = createContextCacheInvalidationSnapshot({
+            forkId: this.sessionManager.getSessionId(),
+            worktreeFingerprint: this._contextCacheWorktreeFingerprint(),
+            activeModelId: initialModelId,
+            compactionModelId: initialModelId,
+        });
         this._extensionRunnerRef = config.extensionRunnerRef;
         this._initialActiveToolNames = config.initialActiveToolNames;
         this._allowedToolNames = config.allowedToolNames ? new Set(config.allowedToolNames) : undefined;
@@ -200,10 +362,34 @@ export class AgentSession {
         this._loadoutAccessPolicy = config.loadoutAccessPolicy;
         this._configuredBashSandboxPreflight = config.bashSandboxPreflight;
         this._sessionStartEvent = config.sessionStartEvent ?? { type: "session_start", reason: "startup" };
+        this._transcriptRepair = config.transcriptRepair;
+        this._replayLedger = config.replayLedger;
+        this._replayGoalId = config.replayGoalId ?? config.replayLedger?.getLedger().goalId;
+        this._replayLaneId = config.replayLaneId;
+        if (this._replayLedger && this._replayGoalId !== this._replayLedger.getLedger().goalId) {
+            throw new Error("AgentSession replayGoalId does not match the replay ledger goal id");
+        }
+        const sessionFile = this.sessionManager.getSessionFile();
+        this._runJournalStore = RunJournalStore.open({
+            ...(sessionFile ? { journalPath: `${sessionFile}.runjournal` } : {}),
+            sessionId: this.sessionManager.getSessionId(),
+        });
+        const startupTerminal = this._runJournalStore.records.at(-1);
+        if (startupTerminal?.event === "run_recovered") {
+            this._lastTermination = startupTerminal.termination;
+        }
         // Always subscribe to agent events for internal handling
         // (session persistence, extensions, auto-compaction, retry logic)
         this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
         this._installAgentToolHooks();
+        // Durable transcript-repair audit for a repair applied on open/resume.
+        if (this._transcriptRepair) {
+            this._invalidateContextBudgetCache({ type: "transcriptRepair" });
+            this._appendRunJournalAudit("transcript_repaired", {
+                insertedToolCallIds: [...this._transcriptRepair.insertedToolCallIds],
+                reason: this._transcriptRepair.reason,
+            });
+        }
         this._buildRuntime({
             activeToolNames: this._initialActiveToolNames,
             includeAllExtensionTools: true,
@@ -213,6 +399,357 @@ export class AgentSession {
     get modelRegistry() {
         return this._modelRegistry;
     }
+    /** Transcript repair applied while this session was opened/resumed, if any. */
+    get transcriptRepair() {
+        return this._transcriptRepair;
+    }
+    /** Durable lifecycle and audit records appended by this session's run journal. */
+    get runJournalRecords() {
+        return this._runJournalStore.records;
+    }
+    /** Most recently observed or inferred termination for this session. */
+    get lastTermination() {
+        return this._lastTermination;
+    }
+    /** Exact trailing journal fragment quarantine performed during startup, if any. */
+    get runJournalQuarantineReport() {
+        return this._runJournalStore.quarantineReport;
+    }
+    /** Elevated once a late-settling potentially-writing tool may have mutated the workspace. */
+    get sessionRiskLevel() {
+        return this._sessionRiskLevel;
+    }
+    /** Monotonic count of workspace mutation/invalidation signals emitted by this session. */
+    get workspaceMutationCount() {
+        return this._workspaceMutationCount;
+    }
+    get contextCacheInvalidationSnapshot() {
+        return this._contextCacheInvalidationSnapshot;
+    }
+    _contextCacheModelId(model) {
+        return model
+            ? `model-${createHash("sha256").update(`${model.provider}\0${model.id}`, "utf8").digest("hex")}`
+            : "unknown";
+    }
+    _contextCacheWorktreeFingerprint() {
+        return createHash("sha256").update(`${this._cwd}\0${this._workspaceMutationCount}`, "utf8").digest("hex");
+    }
+    _invalidateContextBudgetCache(event) {
+        const result = applyContextCacheInvalidation(this._contextCacheInvalidationSnapshot, event);
+        this._contextCacheInvalidationSnapshot = result.snapshot;
+        if (result.status === "overflow") {
+            this._contextBudgetCacheProvider = undefined;
+            return;
+        }
+        this._contextBudgetCacheProvider?.setInvalidationSnapshot?.(result.snapshot);
+    }
+    _recordEvidenceReceiptInvalidation(customType) {
+        if (customType === "evidence_receipt" || customType === "evidence-receipt") {
+            this._invalidateContextBudgetCache({ type: "evidenceReceipt" });
+        }
+    }
+    _sessionRevision() {
+        return this.sessionManager.getEntries().length;
+    }
+    _appendReplayEvent(type, payload) {
+        if (!this._replayLedger || !this._replayGoalId)
+            return;
+        this._replayLedger.append({
+            type,
+            goalId: this._replayGoalId,
+            ...(this._replayLaneId ? { laneId: this._replayLaneId } : {}),
+            payload,
+        });
+        this._replayLedger.persist();
+    }
+    /** Append one required durable audit record. Persistence failures propagate. */
+    _appendRunJournalAudit(event, details) {
+        this._runJournalStore.audit({
+            event,
+            details,
+            sessionRevision: this._sessionRevision(),
+            timestamp: new Date().toISOString(),
+        });
+        this._appendReplayEvent(event, details);
+    }
+    _terminationMessage(value, fallback) {
+        const redacted = redactSensitiveText(value?.trim() || fallback)
+            .replace(/\0/g, "")
+            .slice(0, 512);
+        return redacted || fallback;
+    }
+    _providerFailureCause(message) {
+        const text = message.errorMessage ?? "";
+        if (isContextOverflow(message, this.model?.contextWindow ?? 0)) {
+            return { area: "provider", code: "context_overflow" };
+        }
+        // Fable/Claude often emit stop_reason=refusal on benign turns (false positive).
+        // Match broadly so we never mislabel these as provider.protocol.
+        if (/stop_reason\s*=\s*(refusal|sensitive)|content\/safety stop|safety stop|provider\.refusal|kind=provider_refusal/i.test(text)) {
+            return { area: "provider", code: "refusal" };
+        }
+        if (/auth|unauthori[sz]ed|forbidden|invalid.?api.?key|no api key|401|403|\/login/i.test(text)) {
+            return { area: "provider", code: "auth" };
+        }
+        if (/rate.?limit|too many requests|429|quota|available balance|billing/i.test(text)) {
+            return { area: "provider", code: "rate_limit" };
+        }
+        // Kimi/K3 + OpenAI-compat: orphan tool results after dropped error assistants.
+        // Sanitize-and-retry (transform-messages drops orphans), not a hard tool fatal.
+        if (/tool_call_id\s+is\s+not\s+found|tool_call_id\s+not\s+found|unknown\s+tool_call_id/i.test(text)) {
+            return { area: "provider", code: "protocol" };
+        }
+        if (/tool.+timed? out|tool.+timeout/i.test(text))
+            return { area: "tool", code: "timeout" };
+        if (/\btool\b/i.test(text) && !/tool_call_id/i.test(text))
+            return { area: "tool", code: "fatal" };
+        if (/network|fetch failed|connection|socket|websocket|timed? out|timeout|dns|econn|^terminated$/i.test(text)) {
+            return { area: "provider", code: "network" };
+        }
+        return { area: "provider", code: "protocol" };
+    }
+    _classifyPreflightCause(message) {
+        if (!this.model || /no model|model selected|model is required/i.test(message)) {
+            return { area: "configuration", code: "invalid" };
+        }
+        if (/auth|api key|unauthori[sz]ed|forbidden|401|403|\/login/i.test(message)) {
+            return { area: "provider", code: "auth" };
+        }
+        if (/context.+overflow|context window|too many tokens/i.test(message)) {
+            return { area: "provider", code: "context_overflow" };
+        }
+        if (/duplicate.?result/i.test(message))
+            return { area: "transcript", code: "duplicate_result" };
+        if (/orphan.?result/i.test(message))
+            return { area: "transcript", code: "orphan_result" };
+        if (/duplicate.?call/i.test(message))
+            return { area: "transcript", code: "duplicate_call_id" };
+        if (/transcript|missing.?result/i.test(message))
+            return { area: "transcript", code: "missing_result" };
+        if (/compaction/i.test(message))
+            return { area: "compaction", code: "failed" };
+        if (/fsync/i.test(message))
+            return { area: "persistence", code: "fsync_failed" };
+        if (/lock/i.test(message))
+            return { area: "persistence", code: "lock_failed" };
+        if (/append|persist|write/i.test(message))
+            return { area: "persistence", code: "append_failed" };
+        if (/tool/i.test(message))
+            return { area: "tool", code: "fatal" };
+        return { area: "internal", code: "unclassified" };
+    }
+    _classifyRunTermination(runId, event) {
+        const timestamp = new Date().toISOString();
+        const assistant = [...event.messages]
+            .reverse()
+            .find((message) => message.role === "assistant");
+        let cause;
+        let message;
+        let sideEffects = this._sessionRiskLevel === "elevated" ? "possible" : "none";
+        let toolCallId;
+        let toolName;
+        if (this._activeRunToolTermination) {
+            cause = { area: "tool", code: "timeout" };
+            message = `Tool ${this._activeRunToolTermination.toolName} timed out.`;
+            toolCallId = this._activeRunToolTermination.toolCallId;
+            toolName = this._activeRunToolTermination.toolName;
+            sideEffects = this._activeRunToolTermination.executionStarted ? "possible" : sideEffects;
+        }
+        else if (!assistant) {
+            cause = { area: "internal", code: "unclassified" };
+            message = "Agent run ended without an assistant result.";
+        }
+        else if (assistant.stopReason === "aborted") {
+            cause = this._userAbortRequested ? { area: "user", code: "abort" } : { area: "provider", code: "abort" };
+            message = this._terminationMessage(assistant.errorMessage, this._userAbortRequested ? "The user aborted the run." : "The provider aborted the run.");
+        }
+        else if (assistant.stopReason === "error") {
+            cause = this._providerFailureCause(assistant);
+            message = this._terminationMessage(assistant.errorMessage, "The provider request failed.");
+        }
+        else {
+            cause = { area: "completed" };
+            message = "Run completed.";
+        }
+        return classifySessionTermination({
+            sessionId: this.sessionId,
+            runId,
+            timestamp,
+            source: "observed",
+            message,
+            cause,
+            sideEffects,
+            ...(assistant?.provider
+                ? { provider: assistant.provider }
+                : this.model
+                    ? { provider: this.model.provider }
+                    : {}),
+            ...(assistant?.model ? { model: assistant.model } : this.model ? { model: this.model.id } : {}),
+            ...(toolCallId ? { toolCallId } : {}),
+            ...(toolName ? { toolName } : {}),
+        });
+    }
+    _publishTermination(termination) {
+        this._lastTermination = termination;
+        this._emit({ type: "session_termination", termination });
+    }
+    _runtimeFailureCause(error) {
+        if (this._pendingRuntimeTerminationCause)
+            return this._pendingRuntimeTerminationCause;
+        const code = typeof error === "object" && error !== null && "code" in error ? Reflect.get(error, "code") : undefined;
+        if (typeof code === "string" &&
+            new Set(["EACCES", "EDQUOT", "EFBIG", "EIO", "EISDIR", "EMFILE", "ENFILE", "ENOSPC", "EPERM", "EROFS"]).has(code)) {
+            return { area: "persistence", code: "append_failed" };
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        if (/compaction.+stale|session changed during compaction/i.test(message)) {
+            return { area: "compaction", code: "stale" };
+        }
+        if (/compaction/i.test(message))
+            return { area: "compaction", code: "failed" };
+        return { area: "internal", code: "unclassified" };
+    }
+    _publishRuntimeFailure(error) {
+        const cause = this._runtimeFailureCause(error);
+        const runId = this._activeRunId ?? `runtime-${randomUUID()}`;
+        const timestamp = new Date().toISOString();
+        const message = cause.area === "persistence"
+            ? "A required runtime persistence operation failed."
+            : cause.area === "compaction"
+                ? "Runtime compaction failed."
+                : "The AgentSession runtime failed before completing the run.";
+        let termination = classifySessionTermination({
+            sessionId: this.sessionId,
+            runId,
+            timestamp,
+            source: "observed",
+            message,
+            cause,
+            sideEffects: this._activeRunId === null ? "none" : "possible",
+            ...(this.model ? { provider: this.model.provider, model: this.model.id } : {}),
+        });
+        if (this._activeRunId !== null && this._runJournalStore.openRunId === this._activeRunId) {
+            try {
+                this._runJournalStore.finish({
+                    termination,
+                    sessionRevision: this._sessionRevision(),
+                    timestamp,
+                });
+            }
+            catch {
+                termination = classifySessionTermination({
+                    sessionId: this.sessionId,
+                    runId,
+                    timestamp,
+                    source: "observed",
+                    message: "The run journal could not persist the runtime termination.",
+                    cause: { area: "persistence", code: "append_failed" },
+                    sideEffects: "possible",
+                    ...(this.model ? { provider: this.model.provider, model: this.model.id } : {}),
+                });
+            }
+        }
+        this._activeRunId = null;
+        this._activeRunToolTermination = undefined;
+        this._pendingRuntimeTerminationCause = undefined;
+        this._userAbortRequested = false;
+        this._publishTermination(termination);
+    }
+    _handleRunLifecycleEvent(event) {
+        if (event.type === "agent_start") {
+            if (this._activeRunId !== null)
+                throw new Error("run journal already has an active AgentSession run");
+            const runId = randomUUID();
+            this._activeRunId = runId;
+            this._activeRunToolTermination = undefined;
+            this._pendingRuntimeTerminationCause = undefined;
+            this._userAbortRequested = false;
+            try {
+                this._runJournalStore.start({
+                    runId,
+                    sessionRevision: this._sessionRevision(),
+                    timestamp: new Date().toISOString(),
+                });
+            }
+            catch (error) {
+                this._pendingRuntimeTerminationCause = { area: "persistence", code: "append_failed" };
+                throw error;
+            }
+            return;
+        }
+        if (event.type !== "agent_end")
+            return;
+        if (this._activeRunId === null)
+            throw new Error("run journal received agent_end without run_started");
+        const termination = this._classifyRunTermination(this._activeRunId, event);
+        try {
+            this._runJournalStore.finish({
+                termination,
+                sessionRevision: this._sessionRevision(),
+                timestamp: termination.timestamp,
+            });
+        }
+        catch (error) {
+            this._pendingRuntimeTerminationCause = { area: "persistence", code: "append_failed" };
+            throw error;
+        }
+        this._activeRunId = null;
+        this._activeRunToolTermination = undefined;
+        this._pendingRuntimeTerminationCause = undefined;
+        this._userAbortRequested = false;
+        this._publishTermination(termination);
+    }
+    /**
+     * Handle tool timeout / late-settlement audit signals (ALG004-A/B). A late
+     * settlement of a potentially-writing tool raises session risk and emits a
+     * workspace mutation/invalidation signal for evidence freshness consumers.
+     */
+    _handleToolAuditEvent(event) {
+        if (event.type === "tool_execution_end") {
+            this._invalidateContextBudgetCache({ type: "toolResultDisposition" });
+            const envelope = event.result?.details?.omk;
+            if (envelope && envelope.schema === "tool-result/v2" && envelope.disposition === "timeout") {
+                const timeout = {
+                    toolCallId: event.toolCallId,
+                    toolName: event.toolName,
+                    ...(typeof envelope.timeoutMs === "number" ? { timeoutMs: envelope.timeoutMs } : {}),
+                    executionStarted: envelope.executionStarted === true,
+                };
+                this._activeRunToolTermination = timeout;
+                this._appendRunJournalAudit("tool_timeout", timeout);
+            }
+            return;
+        }
+        if (event.type !== "tool_execution_late_settlement") {
+            return;
+        }
+        // Fail closed: anything not classified as a read-category tool may write.
+        const potentiallyWriting = resolveToolTimeoutCategory(event.toolName) !== "read";
+        this._appendRunJournalAudit("tool_late_settlement", {
+            toolCallId: event.toolCallId,
+            toolName: event.toolName,
+            disposition: event.disposition,
+            outcome: event.outcome,
+            ...(potentiallyWriting ? { sessionRisk: "elevated" } : {}),
+        });
+        if (potentiallyWriting) {
+            this._sessionRiskLevel = "elevated";
+            this._workspaceMutationCount += 1;
+            this._invalidateContextBudgetCache({
+                type: "worktreeFingerprint",
+                value: this._contextCacheWorktreeFingerprint(),
+            });
+            const payload = { root: this._cwd, paths: [] };
+            this._appendReplayEvent("workspace_mutation", payload);
+            this._emit({
+                type: "workspace_mutation",
+                source: "tool_late_settlement",
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+                payload,
+            });
+        }
+    }
     _getBashSandboxPreflight(override) {
         const preflight = override ?? this._configuredBashSandboxPreflight;
         if (!preflight || preflight.policy.mode === "off" || preflight.backend) {
@@ -323,6 +860,8 @@ export class AgentSession {
     _lastAssistantMessage = undefined;
     /** Internal handler for agent events - shared by subscribe and reconnect */
     _handleAgentEvent = async (event) => {
+        // Required run lifecycle persistence executes before extension/user listeners.
+        this._handleRunLifecycleEvent(event);
         // 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") {
@@ -345,28 +884,37 @@ export class AgentSession {
                 }
             }
         }
+        // Durable tool timeout / late-settlement audits (ALG004-A/B).
+        this._handleToolAuditEvent(event);
         // Emit to extensions first
         await this._emitExtensionEvent(event);
+        const replacement = event.type === "message_end" ? this._messageEndReplacements.get(event) : undefined;
+        if (event.type === "message_end") {
+            this._messageEndReplacements.delete(event);
+        }
+        const finalizedEvent = replacement === undefined ? event : Object.freeze({ ...event, message: replacement });
         // Notify all listeners
-        this._emit(event.type === "agent_end" ? { ...event, willRetry: this._willRetryAfterAgentEnd(event) } : event);
+        this._emit(finalizedEvent.type === "agent_end"
+            ? { ...finalizedEvent, willRetry: this._willRetryAfterAgentEnd(finalizedEvent) }
+            : finalizedEvent);
         // Handle session persistence
-        if (event.type === "message_end") {
+        if (finalizedEvent.type === "message_end") {
             // Check if this is a custom message from extensions
-            if (event.message.role === "custom") {
+            if (finalizedEvent.message.role === "custom") {
                 // Persist as CustomMessageEntry
-                this.sessionManager.appendCustomMessageEntry(event.message.customType, event.message.content, event.message.display, event.message.details);
+                this.sessionManager.appendCustomMessageEntry(finalizedEvent.message.customType, finalizedEvent.message.content, finalizedEvent.message.display, finalizedEvent.message.details);
             }
-            else if (event.message.role === "user" ||
-                event.message.role === "assistant" ||
-                event.message.role === "toolResult") {
+            else if (finalizedEvent.message.role === "user" ||
+                finalizedEvent.message.role === "assistant" ||
+                finalizedEvent.message.role === "toolResult") {
                 // Regular LLM message - persist as SessionMessageEntry
-                this.sessionManager.appendMessage(event.message);
+                this.sessionManager.appendMessage(finalizedEvent.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 (finalizedEvent.message.role === "assistant") {
+                this._lastAssistantMessage = finalizedEvent.message;
+                const assistantMsg = finalizedEvent.message;
                 if (assistantMsg.stopReason !== "error") {
                     this._overflowRecoveryAttempted = false;
                 }
@@ -417,19 +965,19 @@ export class AgentSession {
         }
         return undefined;
     }
-    _replaceMessageInPlace(target, replacement) {
-        // Agent-core stores the finalized message object in its state before emitting message_end.
-        // SessionManager persistence happens later in _handleAgentEvent() with event.message.
-        // Mutating this object in place keeps agent state, later turn/agent events, listeners,
-        // and the eventual SessionManager.appendMessage(event.message) persistence in sync.
-        if (target === replacement) {
-            return;
-        }
-        const targetRecord = target;
-        for (const key of Object.keys(targetRecord)) {
-            delete targetRecord[key];
-        }
-        Object.assign(targetRecord, replacement);
+    _replaceFinalizedMessage(target, replacement) {
+        const messages = this.agent.state.messages;
+        const matchingIndexes = messages.flatMap((message, index) => (isDeepStrictEqual(message, target) ? [index] : []));
+        if (matchingIndexes.length !== 1) {
+            throw new Error(matchingIndexes.length === 0
+                ? "Finalized message was not found in agent state"
+                : "Finalized message is ambiguous in agent state");
+        }
+        const finalizedReplacement = createImmutableMessageSnapshot(replacement);
+        const nextMessages = messages.slice();
+        nextMessages[matchingIndexes[0]] = finalizedReplacement;
+        this.agent.state.messages = nextMessages;
+        return finalizedReplacement;
     }
     /** Emit extension events based on agent events */
     async _emitExtensionEvent(event) {
@@ -480,7 +1028,8 @@ export class AgentSession {
             };
             const replacement = await this._extensionRunner.emitMessageEnd(extensionEvent);
             if (replacement) {
-                this._replaceMessageInPlace(event.message, replacement);
+                const finalizedReplacement = this._replaceFinalizedMessage(event.message, replacement);
+                this._messageEndReplacements.set(event, finalizedReplacement);
             }
         }
         else if (event.type === "tool_execution_start") {
@@ -647,10 +1196,28 @@ export class AgentSession {
             }
         }
         this.agent.state.tools = tools;
+        this._applyToolTimeoutCategoryDefaults(validToolNames);
         // Rebuild base system prompt with new tool set
         this._baseSystemPrompt = this._rebuildSystemPrompt(validToolNames);
         this.agent.state.systemPrompt = this._baseSystemPrompt;
     }
+    /**
+     * Recompute the Agent's per-name timeout map for the active tool set:
+     * explicit user/settings entries always win; active tools without an entry
+     * receive their §6.3 category default (ALG004-C); uncategorized tools fall
+     * through to the global `toolTimeoutMs`.
+     */
+    _applyToolTimeoutCategoryDefaults(activeToolNames) {
+        try {
+            const resolved = resolveAgentToolSettings(this.settingsManager);
+            this.agent.toolTimeouts = applyCategoryTimeoutDefaults(activeToolNames, resolved.toolTimeouts);
+        }
+        catch {
+            // Invalid settings fail closed at session creation; keep current
+            // explicit entries and still fill category defaults for active tools.
+            this.agent.toolTimeouts = applyCategoryTimeoutDefaults(activeToolNames, this.agent.toolTimeouts ?? {});
+        }
+    }
     /** Whether compaction or branch summarization is currently running */
     get isCompacting() {
         return (this._autoCompactionAbortController !== undefined ||
@@ -791,6 +1358,7 @@ export class AgentSession {
                 parsePositiveIntegerEnv("OMK_CONTEXT_GOVERNOR_RESPONSE_RESERVE_TOKENS") ?? LEGACY_RESPONSE_RESERVE_TOKENS;
         }
         const cacheProvider = this._contextBudgetCacheProvider ?? createMemoryContextBudgetCacheProviderV2("session");
+        cacheProvider.setInvalidationSnapshot?.(this._contextCacheInvalidationSnapshot);
         this._contextBudgetCacheProvider = cacheProvider;
         // Enforce floor
         if (maxPromptTokens < MIN_PROMPT_TOKENS) {
@@ -870,6 +1438,10 @@ export class AgentSession {
                 await this.agent.continue();
             }
         }
+        catch (error) {
+            this._publishRuntimeFailure(error);
+            throw error;
+        }
         finally {
             this._flushPendingBashMessages();
         }
@@ -911,7 +1483,7 @@ export class AgentSession {
     async prompt(text, options) {
         const expandPromptTemplates = options?.expandPromptTemplates ?? true;
         const preflightResult = options?.preflightResult;
-        let currentText = text;
+        let currentText = redactSensitiveText(text);
         let promptActiveSkillNames = [...(options?.activeSkillNames ?? [])];
         let promptActiveSkillSource = options?.activeSkillSource;
         let isBangSkillInvocation = false;
@@ -959,6 +1531,7 @@ export class AgentSession {
                 expandedText = this._expandSkillCommand(expandedText);
                 expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
             }
+            expandedText = redactSensitiveText(expandedText);
             // If streaming, queue via steer() or followUp() based on option
             if (this.isStreaming) {
                 if (!options?.streamingBehavior) {
@@ -979,6 +1552,8 @@ export class AgentSession {
             if (!this.model) {
                 throw new Error(formatNoModelSelectedMessage());
             }
+            // Root-level: eject sticky safety models (Fable) before the turn leaves the machine.
+            await this._ejectStickySafetyModelIfNeeded();
             // Grok OAuth: refuse Imagine ids on the chat/completions path (tool-only).
             assertTextChatModelForCompletion(this.model.id, this.model.provider);
             if (!this._modelRegistry.hasConfiguredAuth(this.model)) {
@@ -1058,6 +1633,19 @@ export class AgentSession {
         }
         catch (error) {
             preflightResult?.(false);
+            const rawMessage = error instanceof Error ? error.message : String(error);
+            const cause = this._classifyPreflightCause(rawMessage);
+            const timestamp = new Date().toISOString();
+            this._publishTermination(classifySessionTermination({
+                sessionId: this.sessionId,
+                runId: `preflight-${randomUUID()}`,
+                timestamp,
+                source: "observed",
+                message: this._terminationMessage(rawMessage, "Prompt preflight failed."),
+                cause,
+                sideEffects: "none",
+                ...(this.model ? { provider: this.model.provider, model: this.model.id } : {}),
+            }));
             throw error;
         }
         if (!messages) {
@@ -1132,14 +1720,15 @@ export class AgentSession {
      * @throws Error if text is an extension command
      */
     async steer(text, images) {
+        const sanitizedText = redactSensitiveText(text);
         // Check for extension commands (cannot be queued)
-        if (text.startsWith("/")) {
-            this._throwIfExtensionCommand(text);
+        if (sanitizedText.startsWith("/")) {
+            this._throwIfExtensionCommand(sanitizedText);
         }
         // Expand skill commands and prompt templates
-        let expandedText = this._expandSkillCommand(text);
+        let expandedText = this._expandSkillCommand(sanitizedText);
         expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
-        await this._queueSteer(expandedText, images);
+        await this._queueSteer(redactSensitiveText(expandedText), images);
     }
     /**
      * Queue a follow-up message to be processed after the agent finishes.
@@ -1149,19 +1738,21 @@ export class AgentSession {
      * @throws Error if text is an extension command
      */
     async followUp(text, images) {
+        const sanitizedText = redactSensitiveText(text);
         // Check for extension commands (cannot be queued)
-        if (text.startsWith("/")) {
-            this._throwIfExtensionCommand(text);
+        if (sanitizedText.startsWith("/")) {
+            this._throwIfExtensionCommand(sanitizedText);
         }
         // Expand skill commands and prompt templates
-        let expandedText = this._expandSkillCommand(text);
+        let expandedText = this._expandSkillCommand(sanitizedText);
         expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
-        await this._queueFollowUp(expandedText, images);
+        await this._queueFollowUp(redactSensitiveText(expandedText), images);
     }
     /**
      * Internal: Queue a steering message (already expanded, no extension command check).
      */
     async _queueSteer(text, images) {
+        this._invalidateContextBudgetCache({ type: "userSteering" });
         this._steeringMessages.push(text);
         this._emitQueueUpdate();
         const content = [{ type: "text", text }];
@@ -1222,6 +1813,7 @@ export class AgentSession {
             details: message.details,
             timestamp: Date.now(),
         };
+        this._recordEvidenceReceiptInvalidation(message.customType);
         if (options?.deliverAs === "nextTurn") {
             this._pendingNextTurnMessages.push(appMessage);
         }
@@ -1313,16 +1905,43 @@ export class AgentSession {
      * Abort current operation and wait for agent to become idle.
      */
     async abort() {
+        this._userAbortRequested = this.isStreaming || this.isRetrying;
         this.abortRetry();
         this.agent.abort();
         await this.agent.waitForIdle();
     }
+    /** Record an observed process signal before a mode begins shutdown. */
+    recordProcessSignal(signal) {
+        const timestamp = new Date().toISOString();
+        const runId = this._activeRunId ?? `signal-${randomUUID()}`;
+        const termination = classifySessionTermination({
+            sessionId: this.sessionId,
+            runId,
+            timestamp,
+            source: "observed",
+            message: `Process received ${signal}.`,
+            cause: { area: "process", code: "signal", signal },
+            sideEffects: this._activeRunId === null ? "none" : "possible",
+            ...(this.model ? { provider: this.model.provider, model: this.model.id } : {}),
+        });
+        if (this._activeRunId !== null) {
+            this._runJournalStore.finish({
+                termination,
+                sessionRevision: this._sessionRevision(),
+                timestamp,
+            });
+            this._activeRunId = null;
+        }
+        this._publishTermination(termination);
+        return termination;
+    }
     // =========================================================================
     // Model Management
     // =========================================================================
     async _emitModelSelect(nextModel, previousModel, source) {
         if (modelsAreEqual(previousModel, nextModel))
             return;
+        this._invalidateContextBudgetCache({ type: "activeModelId", value: this._contextCacheModelId(nextModel) });
         await this._extensionRunner.emit({
             type: "model_select",
             model: nextModel,
@@ -1339,6 +1958,11 @@ export class AgentSession {
         if (!this._modelRegistry.hasConfiguredAuth(model)) {
             throw new Error(`No API key for ${model.provider}/${model.id}`);
         }
+        // Root-level: block sticky safety models (Fable) unless explicitly allowed in settings.
+        const resilience = resolveProviderResilience(this.settingsManager.getProviderResilienceSettings());
+        if (resilience.blockStickySafetyModels && isStickySafetyModel(model.id, model.provider)) {
+            throw new Error(stickySafetyBlockMessage(model.id, model.provider));
+        }
         // Grok OAuth: block selecting Imagine models as the session chat model.
         assertTextChatModelForCompletion(model.id, model.provider);
         const previousModel = this.model;
@@ -1363,7 +1987,15 @@ export class AgentSession {
         return this._cycleAvailableModel(direction);
     }
     async _cycleScopedModel(direction) {
-        const scopedModels = this._scopedModels.filter((scoped) => this._modelRegistry.hasConfiguredAuth(scoped.model));
+        const resilience = resolveProviderResilience(this.settingsManager.getProviderResilienceSettings());
+        const scopedModels = this._scopedModels.filter((scoped) => {
+            if (!this._modelRegistry.hasConfiguredAuth(scoped.model))
+                return false;
+            if (resilience.blockStickySafetyModels && isStickySafetyModel(scoped.model.id, scoped.model.provider)) {
+                return false;
+            }
+            return true;
+        });
         if (scopedModels.length <= 1)
             return undefined;
         const currentModel = this.model;
@@ -1374,20 +2006,19 @@ export class AgentSession {
         const nextIndex = direction === "forward" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;
         const next = scopedModels[nextIndex];
         const thinkingLevel = this._getThinkingLevelForModelSwitch(next.thinkingLevel);
-        // 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);
-        // Apply thinking level.
-        // - Explicit scoped model thinking level overrides current session level
-        // - Undefined scoped model thinking level inherits the current session preference
-        // setThinkingLevel clamps to model capabilities.
+        // Single path through setModel (sticky block + auth + Imagine guards).
+        await this.setModel(next.model);
+        // Explicit scoped thinking level still applies after switch.
         this.setThinkingLevel(thinkingLevel);
-        await this._emitModelSelect(next.model, currentModel, "cycle");
         return { model: next.model, thinkingLevel: this.thinkingLevel, isScoped: true };
     }
     async _cycleAvailableModel(direction) {
-        const availableModels = await this._modelRegistry.getAvailable();
+        const resilience = resolveProviderResilience(this.settingsManager.getProviderResilienceSettings());
+        const raw = await this._modelRegistry.getAvailable();
+        // Hard-kill sticky safety models from the cycle list (Fable must not re-enter via hotkey).
+        const availableModels = resilience.blockStickySafetyModels
+            ? raw.filter((m) => !isStickySafetyModel(m.id, m.provider))
+            : raw;
         if (availableModels.length <= 1)
             return undefined;
         const currentModel = this.model;
@@ -1397,13 +2028,8 @@ export class AgentSession {
         const len = availableModels.length;
         const nextIndex = direction === "forward" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;
         const nextModel = availableModels[nextIndex];
-        const thinkingLevel = this._getThinkingLevelForModelSwitch();
-        this.agent.state.model = nextModel;
-        this.sessionManager.appendModelChange(nextModel.provider, nextModel.id);
-        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");
+        // Always go through setModel so sticky blocks / auth / Imagine guards stay single-path.
+        await this.setModel(nextModel);
         return { model: nextModel, thinkingLevel: this.thinkingLevel, isScoped: false };
     }
     // =========================================================================
@@ -1503,7 +2129,7 @@ export class AgentSession {
                 hadFence: features.hadFence,
                 hadDiff: features.hadDiff,
             });
-        const resolved = resolveThinkingLevelV4WithUncertainty(verdict, availableLevels, undefined, bias, null);
+        const resolved = resolveThinkingLevelV4WithUncertainty(verdict, availableLevels, undefined, bias, this._getAdaptorchHint(verdict, features));
         if (learningEnabled && resolved !== "off") {
             const record = {
                 routerVersion: "v4",
@@ -1597,6 +2223,76 @@ export class AgentSession {
             return 1;
         return 0;
     }
+    /**
+     * AdaptOrch advisory bridge hint accessor (default-off, global-only).
+     * Lazily constructs the bridge on first call when enabled; returns `null`
+     * (no hint) otherwise. The bridge's `getFreshHint` is synchronous and
+     * cache-read-only, so this never blocks the turn-start path. A fire-and-
+     * forget `requestRefresh` is issued for the NEXT turn's benefit.
+     *
+     * The returned hint is shaped as `{ level, confidence }` for the resolver's
+     * hint-fusion slot: confidence is mapped from the bridge's closed
+     * `confidenceBand` enum (low=0.5, medium=0.75, high=0.95) and the level is
+     * derived from the bridge's `taskClass` via the same static rule table the
+     * resolver uses. The resolver's own HINT_CONFIDENCE_THRESHOLD (0.7) gates
+     * whether the hint actually fuses, so a "low" band hint is structurally
+     * inert.
+     */
+    _getAdaptorchHint(verdict, features) {
+        if (!this.settingsManager.getAdaptorchBridgeEnabled())
+            return null;
+        // Lazy init (at most once per session)
+        if (!this._adaptorchBridgeInitAttempted) {
+            this._adaptorchBridgeInitAttempted = true;
+            const bridgeSettings = this.settingsManager.getAdaptorchBridgeSettings();
+            this._adaptorchBridge = createAdaptorchBridge({
+                // The advisory function is a no-op stub until a real MCP transport
+                // is wired by a future lane. The bridge's circuit breaker and budget
+                // counter ensure this stub can never cause harm.
+                advisoryFn: async () => null,
+                ttlMs: bridgeSettings?.ttlMs,
+                timeoutMs: bridgeSettings?.timeoutMs,
+                maxConsultsPerSession: bridgeSettings?.maxConsultsPerSession,
+                failureThreshold: bridgeSettings?.failureThreshold,
+            });
+        }
+        const bridge = this._adaptorchBridge;
+        if (bridge === null)
+            return null;
+        const payload = {
+            schemaVersion: 1,
+            taskClass: verdict.taskClass,
+            runnerUp: verdict.taskClass,
+            marginBucket: "high",
+            lenBucket: features.lenBucket,
+            hadFence: features.hadFence,
+            hadDiff: features.hadDiff,
+            pressureBucket: this._computePressureBucket(),
+        };
+        // Fire-and-forget refresh for next turn
+        bridge.requestRefresh(payload);
+        // Synchronous cache read for this turn
+        const hint = bridge.getFreshHint(payload);
+        if (hint === null)
+            return null;
+        // Map confidenceBand -> numeric confidence for the resolver's threshold gate
+        const confidenceMap = { low: 0.5, medium: 0.75, high: 0.95 };
+        const confidence = confidenceMap[hint.confidenceBand] ?? 0.5;
+        // Map taskClass -> ThinkingLevel via the same rule table the resolver uses
+        const levelMap = {
+            trivial: "minimal",
+            "simple-edit": "low",
+            "code-gen": "medium",
+            debug: "high",
+            refactor: "high",
+            review: "high",
+            plan: "xhigh",
+        };
+        const level = levelMap[hint.taskClass];
+        if (level === undefined)
+            return null;
+        return { level, confidence };
+    }
     /**
      * Cycle to next thinking level.
      * @returns New level, or undefined if model doesn't support thinking
@@ -1660,17 +2356,330 @@ export class AgentSession {
     // =========================================================================
     // Compaction
     // =========================================================================
+    _captureCompactionState() {
+        return this.sessionManager.withCompactionCommitLock(() => this._captureCompactionStateLocked());
+    }
+    _captureCompactionStateLocked() {
+        const sessionFile = this.sessionManager.getSessionFile();
+        const bytes = sessionFile && existsSync(sessionFile)
+            ? new Uint8Array(readFileSync(sessionFile))
+            : new TextEncoder().encode(`${[this.sessionManager.getHeader(), ...this.sessionManager.getEntries()]
+                .filter((entry) => entry !== null)
+                .map((entry) => JSON.stringify(entry))
+                .join("\n")}\n`);
+        const report = inspectSessionIntegrity(bytes, { activeLeafId: this.sessionManager.getLeafId() });
+        const branchEntries = report.activeBranch;
+        let latestCompactionIndex = -1;
+        for (let index = branchEntries.length - 1; index >= 0; index -= 1) {
+            if (branchEntries[index]?.type === "compaction") {
+                latestCompactionIndex = index;
+                break;
+            }
+        }
+        const latestCompaction = branchEntries[latestCompactionIndex];
+        const firstKeptIndex = latestCompaction?.type === "compaction"
+            ? branchEntries.findIndex((entry) => entry.id === latestCompaction.firstKeptEntryId)
+            : -1;
+        const sourceEntries = branchEntries.slice(latestCompactionIndex < 0 ? 0 : firstKeptIndex < 0 ? latestCompactionIndex : firstKeptIndex);
+        const firstEntry = sourceEntries[0];
+        const lastEntry = sourceEntries.at(-1);
+        if (!firstEntry || !lastEntry || report.activeLeafId === null) {
+            const barrier = evaluateCompactionBarrier(report, [...this.agent.state.pendingToolCalls]);
+            if (barrier.status !== "ready")
+                throw this._barrierError(barrier);
+            throw new Error("Nothing to compact: the active session branch is empty");
+        }
+        const revision = this.sessionManager.getDurableHeadToken();
+        const source = createCompactionSourceIdentity({
+            sessionId: revision.sessionId,
+            entryIds: sourceEntries.map((entry) => entry.id),
+            firstEntryId: firstEntry.id,
+            lastEntryId: lastEntry.id,
+            sourceSha256: createHash("sha256")
+                .update(sourceEntries.map((entry) => JSON.stringify(entry)).join("\n"), "utf8")
+                .digest("hex"),
+            activeLeafId: report.activeLeafId,
+            messageCount: report.activeMessages.length,
+        });
+        return { report, branchEntries, revision, source };
+    }
+    _captureCompactionProvenance(capture) {
+        let latestIntent = "Continue the current session";
+        for (let index = capture.report.activeMessages.length - 1; index >= 0; index -= 1) {
+            const message = capture.report.activeMessages[index];
+            if (message?.role !== "user")
+                continue;
+            const candidate = sanitizeBinaryOutput(redactSensitiveText(this._getUserMessageText(message)).trim()).slice(0, 16_384);
+            if (candidate.length > 0)
+                latestIntent = candidate;
+            break;
+        }
+        const modelHistory = capture.branchEntries
+            .flatMap((entry) => {
+            if (entry.type === "model_change") {
+                return [{ entryId: entry.id, provider: entry.provider, modelId: entry.modelId }];
+            }
+            if (entry.type === "message" && entry.message.role === "assistant") {
+                return [{ entryId: entry.id, provider: entry.message.provider, modelId: entry.message.model }];
+            }
+            return [];
+        })
+            .slice(-256);
+        const customEntryIds = (customType) => capture.branchEntries
+            .filter((entry) => entry.type === "custom" && entry.customType === customType)
+            .map((entry) => entry.id);
+        return {
+            latestIntent,
+            openTasks: [],
+            laneIds: customEntryIds("lane"),
+            acceptancePredicateIds: customEntryIds("acceptance_predicate"),
+            evidenceReceiptIds: customEntryIds("evidence_receipt"),
+            blockerReasons: [],
+            repairEventIds: [
+                ...customEntryIds("transcript_repaired"),
+                ...customEntryIds("compaction_transcript_repaired"),
+            ],
+            branch: null,
+            worktree: this._cwd,
+            modelHistory,
+            nextAction: latestIntent,
+        };
+    }
+    _barrierError(barrier) {
+        if (barrier.status === "defer") {
+            return new Error(`Compaction deferred until the transcript closes (${barrier.reason})`);
+        }
+        return new Error(`Compaction failed closed on transcript integrity (${barrier.reason}). Run the session doctor before retrying.`);
+    }
+    _evaluateCompactionBarrier(capture, includeMissingTailAsPending, excludedPendingIds = new Set()) {
+        const pending = new Set([...this.agent.state.pendingToolCalls].filter((toolCallId) => !excludedPendingIds.has(toolCallId)));
+        if (includeMissingTailAsPending) {
+            for (const issue of capture.report.transcript?.issues ?? []) {
+                if (issue.kind === "missing_result")
+                    pending.add(issue.toolCallId);
+            }
+        }
+        return evaluateCompactionBarrier(capture.report, [...pending]);
+    }
+    _repairEmergencyCompactionTail(capture) {
+        const barrier = this._evaluateCompactionBarrier(capture, true);
+        if (barrier.status !== "defer" || barrier.reason !== "missing_active_tail_results") {
+            if (barrier.status !== "ready")
+                throw this._barrierError(barrier);
+            return { capture, repairedToolCallIds: new Set() };
+        }
+        const repairedMessages = repairTranscriptIntegrity([...capture.report.activeMessages], "Tool result missing; synthesized to close an emergency compaction barrier");
+        const inserted = repairedMessages.slice(capture.report.activeMessages.length);
+        const repairedToolCallIds = new Set();
+        for (const message of inserted) {
+            if (message.role !== "toolResult") {
+                throw new Error("Emergency compaction repair produced a non-tool result");
+            }
+            const toolResult = message;
+            repairedToolCallIds.add(toolResult.toolCallId);
+            this.sessionManager.appendMessage(toolResult);
+        }
+        this.sessionManager.appendCustomEntry("compaction_transcript_repaired", {
+            insertedToolCallIds: [...repairedToolCallIds],
+            reason: "emergency_compaction",
+        });
+        this._invalidateContextBudgetCache({ type: "transcriptRepair" });
+        const closedCapture = this._captureCompactionState();
+        const closedBarrier = this._evaluateCompactionBarrier(closedCapture, false, repairedToolCallIds);
+        if (closedBarrier.status !== "ready")
+            throw this._barrierError(closedBarrier);
+        this.agent.state.messages = this.sessionManager.buildSessionContext().messages;
+        return { capture: closedCapture, repairedToolCallIds };
+    }
+    _priorCommittedCompactionSourceDigests() {
+        const digests = [];
+        for (const entry of this.sessionManager.getEntries()) {
+            if (entry.type !== "compaction" || typeof entry.details !== "object" || entry.details === null)
+                continue;
+            if (!Object.hasOwn(entry.details, "compactionEnvelope"))
+                continue;
+            const envelope = validateCompactionEnvelope(Reflect.get(entry.details, "compactionEnvelope"));
+            if (envelope.summary !== entry.summary) {
+                throw new Error(`Compaction entry ${entry.id} has invalid provenance. Run the session doctor.`);
+            }
+            digests.push(envelope.source.sourceSha256);
+        }
+        return digests;
+    }
+    _beginCompactionTransaction(compactionModel, emergency) {
+        let capture = this._captureCompactionState();
+        if (emergency) {
+            capture = this._repairEmergencyCompactionTail(capture).capture;
+        }
+        else {
+            const barrier = this._evaluateCompactionBarrier(capture, false);
+            if (barrier.status !== "ready")
+                throw this._barrierError(barrier);
+        }
+        const transaction = createCompactionTransaction({
+            transactionId: randomUUID(),
+            baseRevision: capture.revision,
+            source: capture.source,
+            createdAt: new Date().toISOString(),
+            model: { provider: compactionModel.provider, id: compactionModel.id },
+            preserved: this._captureCompactionProvenance(capture),
+        });
+        if (this._priorCommittedCompactionSourceDigests().includes(transaction.source.sourceSha256)) {
+            throw new Error("This exact compaction source was already compacted");
+        }
+        return { capture, transaction };
+    }
+    _detailsWithCompactionEnvelope(details, envelope) {
+        if (typeof details === "object" && details !== null && !Array.isArray(details)) {
+            return { ...details, compactionEnvelope: envelope };
+        }
+        return {
+            compactionEnvelope: envelope,
+            ...(details === undefined ? {} : { resultDetails: details }),
+        };
+    }
+    _commitCompaction(begun, result, fromExtension) {
+        if (!begun.transaction.source.entryIds.includes(result.firstKeptEntryId)) {
+            throw new Error("Compaction first-kept entry is outside the captured source");
+        }
+        const committed = this.sessionManager.withCompactionCommitLock(() => {
+            const current = this._captureCompactionState();
+            const barrier = this._evaluateCompactionBarrier(current, false);
+            const decision = decideCompactionCommit({
+                transaction: begun.transaction,
+                currentRevision: current.revision,
+                currentSource: current.source,
+                barrier,
+                priorCommittedSourceDigests: this._priorCommittedCompactionSourceDigests(),
+            });
+            switch (decision.decision) {
+                case "duplicate":
+                    throw new Error("This exact compaction source was already compacted");
+                case "stale":
+                    throw new Error(`Session changed during compaction (${decision.reason}); generated summary was discarded`);
+                case "defer":
+                case "fail_closed":
+                    throw this._barrierError(barrier);
+                case "commit": {
+                    const envelope = createCompactionEnvelope({
+                        transaction: begun.transaction,
+                        decision,
+                        summary: result.summary,
+                        summarySha256: createHash("sha256").update(result.summary, "utf8").digest("hex"),
+                    });
+                    const entryId = this.sessionManager.appendCompaction(result.summary, result.firstKeptEntryId, result.tokensBefore, this._detailsWithCompactionEnvelope(result.details, envelope), fromExtension);
+                    const entry = this.sessionManager.getEntry(entryId);
+                    if (!entry || entry.type !== "compaction") {
+                        throw new Error("Compaction commit did not produce a compaction entry");
+                    }
+                    return { entry, envelope };
+                }
+            }
+        });
+        this._recordCompactionCommitForHysteresis();
+        return committed;
+    }
+    _pendingToolResultReserve(settings) {
+        const pendingIds = this.agent.state.pendingToolCalls;
+        const calls = new Map();
+        const streaming = this.agent.state.streamingMessage;
+        const messages = streaming ? [...this.agent.state.messages, streaming] : this.agent.state.messages;
+        for (const message of messages) {
+            if (message.role !== "assistant" || !Array.isArray(message.content))
+                continue;
+            for (const part of message.content) {
+                if (part.type === "toolCall" && pendingIds.has(part.id)) {
+                    calls.set(part.id, { name: part.name, args: part.arguments });
+                }
+            }
+        }
+        const counts = { text: 0, image: 0, "large-output": 0 };
+        for (const id of pendingIds) {
+            const call = calls.get(id);
+            const resultClass = call ? pendingToolResultClass(call.name, call.args) : "large-output";
+            counts[resultClass] += 1;
+        }
+        const requests = [];
+        for (const resultClass of ["text", "image", "large-output"]) {
+            if (counts[resultClass] > 0) {
+                requests.push({
+                    class: resultClass,
+                    count: counts[resultClass],
+                    tokensPerResult: PENDING_TOOL_RESULT_TOKENS[resultClass],
+                });
+            }
+        }
+        const configured = settings.reservedToolResultTokens ?? 0;
+        requests.push({ class: "large-output", count: 1, tokensPerResult: configured });
+        return estimateToolResultReserve(requests);
+    }
+    _compactionHysteresisConfig(contextWindow, settings) {
+        const threshold = getCompactionHeadroomThreshold(contextWindow, {
+            ...settings,
+            reservedToolResultTokens: this._pendingToolResultReserve(settings),
+        });
+        if (!threshold)
+            return undefined;
+        const triggerRatio = Math.min(1, Math.max(1 / Math.floor(contextWindow), threshold.triggerTokens / contextWindow));
+        const configuredRearm = settings.rearmRatio ?? triggerRatio * 0.75;
+        const rearmRatio = Math.min(configuredRearm, triggerRatio * 0.999);
+        const emergencyRatio = Math.max(triggerRatio, settings.emergencyRatio ?? 0.98);
+        return createCompactionHysteresisConfig({ rearmRatio, triggerRatio, emergencyRatio });
+    }
+    _runtimeCompactionDecision(contextTokens, contextWindow, settings) {
+        if (!Number.isFinite(contextTokens) || contextTokens < 0)
+            return { compact: false, emergency: false };
+        const config = this._compactionHysteresisConfig(contextWindow, settings);
+        if (!config)
+            return { compact: false, emergency: false };
+        const result = stepCompactionHysteresis({
+            config,
+            state: this._compactionHysteresisState,
+            ratio: Math.min(1, contextTokens / contextWindow),
+        });
+        this._compactionHysteresisState = result.nextState;
+        return { compact: result.action === "compact", emergency: result.reason === "emergency_threshold_reached" };
+    }
+    async _runThresholdCompaction(emergency) {
+        this._thresholdCompactionEmergency = emergency;
+        try {
+            return await this._runAutoCompaction("threshold", false);
+        }
+        finally {
+            this._thresholdCompactionEmergency = false;
+        }
+    }
+    _recordCompactionCommitForHysteresis() {
+        const contextWindow = this.model?.contextWindow ?? 0;
+        const config = this._compactionHysteresisConfig(contextWindow, this.settingsManager.getCompactionSettings());
+        if (!config)
+            return;
+        this._compactionHysteresisState = stepCompactionHysteresis({
+            config,
+            state: this._compactionHysteresisState,
+            ratio: 0,
+            outcome: "commit",
+        }).nextState;
+    }
     _resolveCompactionModel(sessionModel) {
         const configuredModel = this.settingsManager.getCompactionModel();
         const availableModels = this._modelRegistry.getAvailable();
+        let model;
         if (configuredModel) {
-            const model = findExactModelReferenceMatch(configuredModel, availableModels);
-            if (!model) {
+            const configured = findExactModelReferenceMatch(configuredModel, availableModels);
+            if (!configured) {
                 throw new Error(`Configured compaction model "${configuredModel}" is unavailable or unauthenticated.`);
             }
-            return model;
+            model = configured;
+        }
+        else {
+            model = resolveCompactionModel(sessionModel, availableModels);
         }
-        return resolveCompactionModel(sessionModel, availableModels);
+        this._invalidateContextBudgetCache({
+            type: "compactionModelId",
+            value: this._contextCacheModelId(model),
+        });
+        return model;
     }
     /**
      * Manually compact the session context.
@@ -1682,14 +2691,16 @@ export class AgentSession {
         await this.abort();
         this._compactionAbortController = new AbortController();
         this._emit({ type: "compaction_start", reason: "manual" });
+        let committedCompaction = false;
         try {
             if (!this.model) {
                 throw new Error(formatNoModelSelectedMessage());
             }
             const compactionModel = this._resolveCompactionModel(this.model);
             const { apiKey, headers } = await this._getCompactionRequestAuth(compactionModel);
-            const pathEntries = this.sessionManager.getBranch();
             const settings = this.settingsManager.getCompactionSettings();
+            const begun = this._beginCompactionTransaction(compactionModel, false);
+            const pathEntries = [...begun.capture.branchEntries];
             const preparation = prepareCompaction(pathEntries, settings);
             if (!preparation) {
                 // Check why we can't compact
@@ -1739,25 +2750,22 @@ export class AgentSession {
             if (this._compactionAbortController.signal.aborted) {
                 throw new Error("Compaction cancelled");
             }
-            this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension);
-            const newEntries = this.sessionManager.getEntries();
-            const sessionContext = this.sessionManager.buildSessionContext();
-            this.agent.state.messages = sessionContext.messages;
-            // Get the saved compaction entry for the extension event
-            const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
-            if (this._extensionRunner && savedCompactionEntry) {
-                await this._extensionRunner.emit({
-                    type: "session_compact",
-                    compactionEntry: savedCompactionEntry,
-                    fromExtension,
-                });
-            }
             const compactionResult = {
                 summary,
                 firstKeptEntryId,
                 tokensBefore,
                 details,
             };
+            const committed = this._commitCompaction(begun, compactionResult, fromExtension);
+            committedCompaction = true;
+            this.agent.state.messages = this.sessionManager.buildSessionContext().messages;
+            if (this._extensionRunner) {
+                await this._extensionRunner.emit({
+                    type: "session_compact",
+                    compactionEntry: committed.entry,
+                    fromExtension,
+                });
+            }
             this._emit({
                 type: "compaction_end",
                 reason: "manual",
@@ -1770,6 +2778,18 @@ export class AgentSession {
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             const aborted = message === "Compaction cancelled" || (error instanceof Error && error.name === "AbortError");
+            const stale = /stale|session changed during compaction|already compacted/i.test(message);
+            const timestamp = new Date().toISOString();
+            this._publishTermination(classifySessionTermination({
+                sessionId: this.sessionId,
+                runId: `compaction-${randomUUID()}`,
+                timestamp,
+                source: "observed",
+                message: this._terminationMessage(message, "Manual compaction failed."),
+                cause: { area: "compaction", code: aborted ? "aborted" : stale ? "stale" : "failed" },
+                sideEffects: committedCompaction ? "confirmed" : "none",
+                ...(this.model ? { provider: this.model.provider, model: this.model.id } : {}),
+            }));
             this._emit({
                 type: "compaction_end",
                 reason: "manual",
@@ -1815,8 +2835,9 @@ export class AgentSession {
                 return false;
             }
         }
-        if (shouldCompact(estimate.tokens, contextWindow, settings)) {
-            return await this._runAutoCompaction("threshold", false);
+        const decision = this._runtimeCompactionDecision(estimate.tokens, contextWindow, settings);
+        if (decision.compact) {
+            return await this._runThresholdCompaction(decision.emergency);
         }
         return false;
     }
@@ -1897,15 +2918,16 @@ export class AgentSession {
         else {
             contextTokens = calculateContextTokens(assistantMessage.usage);
         }
-        if (shouldCompact(contextTokens, contextWindow, settings)) {
-            return await this._runAutoCompaction("threshold", false);
+        const decision = this._runtimeCompactionDecision(contextTokens, contextWindow, settings);
+        if (decision.compact) {
+            return await this._runThresholdCompaction(decision.emergency);
         }
         return false;
     }
     /**
      * Internal: Run auto-compaction with events.
      */
-    async _runAutoCompaction(reason, willRetry) {
+    async _runAutoCompaction(reason, willRetry, emergency = reason === "overflow" || this._thresholdCompactionEmergency) {
         const settings = this.settingsManager.getCompactionSettings();
         this._emit({ type: "compaction_start", reason });
         this._autoCompactionAbortController = new AbortController();
@@ -1944,7 +2966,8 @@ export class AgentSession {
             else {
                 ({ apiKey, headers } = await this._getCompactionRequestAuth(compactionModel));
             }
-            const pathEntries = this.sessionManager.getBranch();
+            const begun = this._beginCompactionTransaction(compactionModel, emergency);
+            const pathEntries = [...begun.capture.branchEntries];
             const preparation = prepareCompaction(pathEntries, settings);
             if (!preparation) {
                 this._emit({
@@ -2010,25 +3033,21 @@ export class AgentSession {
                 });
                 return false;
             }
-            this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension);
-            const newEntries = this.sessionManager.getEntries();
-            const sessionContext = this.sessionManager.buildSessionContext();
-            this.agent.state.messages = sessionContext.messages;
-            // Get the saved compaction entry for the extension event
-            const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
-            if (this._extensionRunner && savedCompactionEntry) {
-                await this._extensionRunner.emit({
-                    type: "session_compact",
-                    compactionEntry: savedCompactionEntry,
-                    fromExtension,
-                });
-            }
             const result = {
                 summary,
                 firstKeptEntryId,
                 tokensBefore,
                 details,
             };
+            const committed = this._commitCompaction(begun, result, fromExtension);
+            this.agent.state.messages = this.sessionManager.buildSessionContext().messages;
+            if (this._extensionRunner) {
+                await this._extensionRunner.emit({
+                    type: "session_compact",
+                    compactionEntry: committed.entry,
+                    fromExtension,
+                });
+            }
             const emitWillRetry = compactionEmitWillRetry(willRetry, this.agent.hasQueuedMessages());
             this._emit({ type: "compaction_end", reason, result, aborted: false, willRetry: emitWillRetry });
             if (willRetry) {
@@ -2196,6 +3215,7 @@ export class AgentSession {
             },
             appendEntry: (customType, data) => {
                 this.sessionManager.appendCustomEntry(customType, data);
+                this._recordEvidenceReceiptInvalidation(customType);
             },
             setSessionName: (name) => {
                 this.setSessionName(name);
@@ -2414,6 +3434,7 @@ export class AgentSession {
         const previousFlagValues = this._extensionRunner.getFlagValues();
         await emitSessionShutdownEvent(this._extensionRunner, { type: "session_shutdown", reason: "reload" });
         await this.settingsManager.reload();
+        this._invalidateContextBudgetCache({ type: "settings" });
         resetApiProviders();
         await this._resourceLoader.reload();
         this._buildRuntime({
@@ -2450,13 +3471,68 @@ export class AgentSession {
         const err = message.errorMessage;
         if (this._isNonRetryableProviderLimitError(err))
             return false;
-        // 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);
+        // Shared contract with provider-resilience.ts (Fable safety stop, K3 orphan tool_call_id, terminated).
+        return isTransientProviderErrorMessage(err);
     }
     /**
      * Prepare a retryable error for continuation with exponential backoff.
      * @returns true if the caller should continue the agent, false otherwise
      */
+    /** Eject sticky safety model at prompt boundary (session resume / leftover default). */
+    async _ejectStickySafetyModelIfNeeded() {
+        const resilience = resolveProviderResilience(this.settingsManager.getProviderResilienceSettings());
+        if (!resilience.blockStickySafetyModels)
+            return;
+        const current = this.model;
+        if (!current || !isStickySafetyModel(current.id, current.provider))
+            return;
+        const pick = pickFailoverCandidate(resilience.failoverCandidates, { provider: current.provider, id: current.id }, (c) => {
+            const next = this._modelRegistry.find(c.provider, c.id);
+            return !!next && this._modelRegistry.hasConfiguredAuth(next);
+        });
+        if (!pick) {
+            throw new Error(stickySafetyBlockMessage(current.id, current.provider));
+        }
+        const next = this._modelRegistry.find(pick.provider, pick.id);
+        if (!next) {
+            throw new Error(stickySafetyBlockMessage(current.id, current.provider));
+        }
+        // Bypass setModel sticky check by temporarily allowing via direct state switch path:
+        // setModel itself blocks sticky targets, not sources — safe.
+        await this.setModel(next);
+    }
+    /**
+     * Sticky safety models (e.g. claude-fable-5) often false-positive on coding turns.
+     * Retrying the same model repeats the refusal — switch via provider-resilience chain first.
+     */
+    async _maybeFailoverFromSafetyStop(message) {
+        const resilience = resolveProviderResilience(this.settingsManager.getProviderResilienceSettings());
+        if (!resilience.autoFailoverOnSafetyStop)
+            return undefined;
+        if (!isContentSafetyStopMessage(message.errorMessage))
+            return undefined;
+        const current = this.model;
+        const currentId = message.model || current?.id || "";
+        const currentProvider = message.provider || current?.provider || "";
+        if (!isStickySafetyModel(currentId, currentProvider))
+            return undefined;
+        const pick = pickFailoverCandidate(resilience.failoverCandidates, current ? { provider: current.provider, id: current.id } : undefined, (c) => {
+            const next = this._modelRegistry.find(c.provider, c.id);
+            return !!next && this._modelRegistry.hasConfiguredAuth(next);
+        });
+        if (!pick)
+            return undefined;
+        const next = this._modelRegistry.find(pick.provider, pick.id);
+        if (!next)
+            return undefined;
+        try {
+            await this.setModel(next);
+            return `${next.provider}/${next.id}`;
+        }
+        catch {
+            return undefined;
+        }
+    }
     async _prepareRetry(message) {
         const settings = this.settingsManager.getRetrySettings();
         if (!settings.enabled) {
@@ -2468,13 +3544,21 @@ export class AgentSession {
             this._retryAttempt--;
             return false;
         }
-        const delayMs = settings.baseDelayMs * 2 ** (this._retryAttempt - 1);
+        // Content/safety stop on Fable: switch model BEFORE delay so the retry is not another Fable refusal.
+        const failoverTo = await this._maybeFailoverFromSafetyStop(message);
+        // Safety stops are usually immediate false positives — short delay after failover, full backoff otherwise.
+        const delayMs = failoverTo
+            ? Math.min(400, settings.baseDelayMs)
+            : settings.baseDelayMs * 2 ** (this._retryAttempt - 1);
+        const errorMessage = failoverTo
+            ? `${message.errorMessage || "content/safety stop"} → failover ${failoverTo}`
+            : message.errorMessage || "Unknown error";
         this._emit({
             type: "auto_retry_start",
             attempt: this._retryAttempt,
             maxAttempts: settings.maxRetries,
             delayMs,
-            errorMessage: message.errorMessage || "Unknown error",
+            errorMessage,
         });
         // Remove error message from agent state (keep in session for history)
         const messages = this.agent.state.messages;