open-multi-agent-kit 0.90.7 → 0.90.9

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 { 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";
 import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
@@ -34,12 +45,17 @@ import { emitSessionShutdownEvent } from "./extensions/runner.js";
 import { assertTextChatModelForCompletion } from "./grok-harness.js";
 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 { 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";
@@ -71,6 +87,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
 // ============================================================================
@@ -96,6 +129,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
 // ============================================================================
@@ -128,6 +257,7 @@ export class AgentSession {
     // 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. */
@@ -138,6 +268,8 @@ export class AgentSession {
     _compactionAbortController = undefined;
     _autoCompactionAbortController = undefined;
     _overflowRecoveryAttempted = false;
+    _thresholdCompactionEmergency = false;
+    _compactionHysteresisState = createCompactionHysteresisState();
     // Branch summarization state
     _branchSummaryAbortController = undefined;
     // Retry state
@@ -169,8 +301,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();
@@ -188,6 +336,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;
@@ -196,10 +351,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,
@@ -209,6 +388,347 @@ 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" };
+        }
+        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" };
+        }
+        if (/tool.+timed? out|tool.+timeout/i.test(text))
+            return { area: "tool", code: "timeout" };
+        if (/tool/i.test(text))
+            return { area: "tool", code: "fatal" };
+        if (/network|fetch failed|connection|socket|websocket|timed? out|timeout|dns|econn/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) {
@@ -319,6 +839,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") {
@@ -341,28 +863,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;
                 }
@@ -413,19 +944,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) {
@@ -476,7 +1007,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") {
@@ -643,10 +1175,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 ||
@@ -744,7 +1294,11 @@ export class AgentSession {
         return undefined;
     }
     _getContextBudgetOptions() {
-        if (process.env.OMK_CONTEXT_GOVERNOR !== "1") {
+        const contextGovernorOverride = process.env.OMK_CONTEXT_GOVERNOR;
+        if (contextGovernorOverride === "0") {
+            return undefined;
+        }
+        if (contextGovernorOverride !== "1" && !this.settingsManager.getContextBudgetEnabled()) {
             return undefined;
         }
         const contextWindow = this.model?.contextWindow ?? 0;
@@ -782,6 +1336,9 @@ export class AgentSession {
             responseReserveTokens =
                 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) {
             maxPromptTokens = MIN_PROMPT_TOKENS;
@@ -797,6 +1354,7 @@ export class AgentSession {
             tokenizerMode: parseTokenizerModeEnv(process.env.OMK_CONTEXT_GOVERNOR_TOKENIZER),
             activeSkillNames: parseCommaSeparatedEnv(process.env.OMK_CONTEXT_GOVERNOR_ACTIVE_SKILLS),
             queryContext: this._extractCurrentQuery(),
+            cacheProvider,
         };
     }
     /**
@@ -859,6 +1417,10 @@ export class AgentSession {
                 await this.agent.continue();
             }
         }
+        catch (error) {
+            this._publishRuntimeFailure(error);
+            throw error;
+        }
         finally {
             this._flushPendingBashMessages();
         }
@@ -900,7 +1462,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;
@@ -948,6 +1510,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) {
@@ -1047,6 +1610,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) {
@@ -1121,14 +1697,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.
@@ -1138,19 +1715,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 }];
@@ -1211,6 +1790,7 @@ export class AgentSession {
             details: message.details,
             timestamp: Date.now(),
         };
+        this._recordEvidenceReceiptInvalidation(message.customType);
         if (options?.deliverAs === "nextTurn") {
             this._pendingNextTurnMessages.push(appMessage);
         }
@@ -1302,16 +1882,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,
@@ -1649,6 +2256,331 @@ 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 configured = findExactModelReferenceMatch(configuredModel, availableModels);
+            if (!configured) {
+                throw new Error(`Configured compaction model "${configuredModel}" is unavailable or unauthenticated.`);
+            }
+            model = configured;
+        }
+        else {
+            model = resolveCompactionModel(sessionModel, availableModels);
+        }
+        this._invalidateContextBudgetCache({
+            type: "compactionModelId",
+            value: this._contextCacheModelId(model),
+        });
+        return model;
+    }
     /**
      * Manually compact the session context.
      * Aborts current agent operation first.
@@ -1659,14 +2591,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 = resolveCompactionModel(this.model, this._modelRegistry.getAvailable());
+            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
@@ -1716,25 +2650,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",
@@ -1747,6 +2678,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",
@@ -1792,8 +2735,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;
     }
@@ -1874,15 +2818,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();
@@ -1897,7 +2842,7 @@ export class AgentSession {
                 });
                 return false;
             }
-            const compactionModel = resolveCompactionModel(this.model, this._modelRegistry.getAvailable());
+            const compactionModel = this._resolveCompactionModel(this.model);
             let apiKey;
             let headers;
             if (this.agent.streamFn === streamSimple) {
@@ -1921,7 +2866,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({
@@ -1987,25 +2933,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) {
@@ -2173,6 +3115,7 @@ export class AgentSession {
             },
             appendEntry: (customType, data) => {
                 this.sessionManager.appendCustomEntry(customType, data);
+                this._recordEvidenceReceiptInvalidation(customType);
             },
             setSessionName: (name) => {
                 this.setSessionName(name);
@@ -2391,6 +3334,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({