open-multi-agent-kit 0.95.1 → 0.96.0

package/dist/core/agent-session.js

@@ -14,9 +14,11 @@
  */
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, dirname } from "node:path";
+import { basename, dirname, join as joinPath } from "node:path";
 import { isDeepStrictEqual } from "node:util";
-import { clampThinkingLevel, cleanupSessionResources, getSupportedThinkingLevels, isContextOverflow, modelsAreEqual, resetApiProviders, streamSimple, } from "omk-ai";
+import { getVisionRouteModel, isVisionRouteModel } from "omk-agent-core";
+import { clampThinkingLevel, cleanupSessionResources, deriveContextPromptCacheKey, getSupportedThinkingLevels, isContextOverflow, modelsAreEqual, resetApiProviders, streamSimple, } from "omk-ai";
+import { APP_NAME, VERSION } from "../config.js";
 import { theme } from "../modes/interactive/theme/theme.js";
 import { stripFrontmatter } from "../utils/frontmatter.js";
 import { resolvePath } from "../utils/paths.js";
@@ -31,6 +33,7 @@ import { createCompactionHysteresisConfig, createCompactionHysteresisState, step
 import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateProjectedContextTokens, generateBranchSummary, prepareCompaction, resolveCompactionModel, } from "./compaction/index.js";
 import { compactionEmitWillRetry } from "./compaction/resume-policy.js";
 import { estimateToolResultReserve, } from "./context-budget-reserved-tokens.js";
+import { createDiskContextBudgetCacheProviderV2, DiskContextBudgetCacheProviderV2, } from "./context-budget-v2-cache-disk.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";
@@ -41,21 +44,49 @@ import { emitSessionShutdownEvent } from "./extensions/runner.js";
 import { assertTextChatModelForCompletion } from "./grok-harness.js";
 import { grokPlaybookAppendForProvider } from "./grok-playbook.js";
 import { decideLoadoutAccess } from "./loadout-access-policy.js";
+import { loadMcpServerConfigs } from "./mcp/config.js";
+import { McpManager } from "./mcp/manager.js";
+import { buildRuntimeProvenance } from "./runtime-provenance.js";
+import { TurnMetricsSink } from "./turn-metrics.js";
+/** Values that disable a session-level feature through its environment variable. */
+const DISABLED_ENV_VALUES = new Set(["0", "false", "off", "disable", "disabled"]);
+const MAX_OVERFLOW_RECOVERY_ATTEMPTS = 2;
+const OVERFLOW_RECOVERY_EMERGENCY_TOKENS = 4_096;
+function isDisabledEnvValue(value) {
+    return value !== undefined && DISABLED_ENV_VALUES.has(value.trim().toLowerCase());
+}
+/** Extract the first text block of a tool result, for failure classification only. */
+function firstTextContent(result) {
+    const content = result?.content;
+    if (!Array.isArray(content))
+        return undefined;
+    for (const block of content) {
+        if (block && typeof block === "object" && block.type === "text") {
+            const text = block.text;
+            if (typeof text === "string")
+                return text;
+        }
+    }
+    return undefined;
+}
+import { redactCredentialShapedContent } from "./compaction/transaction.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 { isContentSafetyStopMessage, isQuotaExhaustionMessage, isStickySafetyModel, isTransientProviderErrorMessage, pickFailoverCandidate, resolveProviderResilience, stickySafetyBlockMessage, } from "./provider-resilience.js";
+import { getBiasStepsForCell, parseRouterBiasSnapshot } from "./reasoning-router-bias.js";
+import { classifyTaskV4, deriveRouterFeedbackFeaturesV4, resolveThinkingLevelV4WithUncertainty, TASK_CLASS_THINKING_LEVELS_V4, } from "./reasoning-router-v4.js";
+import { redactSensitiveText, redactSensitiveTextForced } from "./redaction.js";
+import { getRepositoryRouterLearningPaths } from "./repository-learning-scope.js";
+import { appendRouterFeedbackRecord, ROUTER_FEEDBACK_LEVELS, } from "./router-feedback-collector.js";
 import { RunJournalStore } from "./run-journal-store.js";
 import { SessionBashRuntime } from "./session-bash-runtime.js";
 import { SessionBashService } from "./session-bash-service.js";
 import { SessionCompactionService } from "./session-compaction-service.js";
 import { CURRENT_SESSION_VERSION, getLatestCompactionEntry } from "./session-manager.js";
+import { acquireSessionOwnerLeaseSync } from "./session-owner-lease.js";
 import { classifySessionTermination, } from "./session-termination.js";
 import { createSyntheticSourceInfo } from "./source-info.js";
-import { buildSystemPrompt } from "./system-prompt.js";
+import { buildSystemPromptPlan } from "./system-prompt.js";
 import { createLocalBashOperations } from "./tools/bash.js";
 import { createAllToolDefinitions } from "./tools/index.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
@@ -110,7 +141,13 @@ function pendingToolResultClass(name, args) {
 /** Standard thinking levels */
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high"];
 function normalizeToolNames(toolNames) {
-    return [...new Set(toolNames.map((name) => name.trim()).filter((name) => name !== ""))].sort();
+    return [...new Set(toolNames.map((name) => name.trim()).filter((name) => name !== ""))].sort((left, right) => {
+        if (left < right)
+            return -1;
+        if (left > right)
+            return 1;
+        return 0;
+    });
 }
 function toolNameSetsEqual(left, right) {
     const normalizedLeft = normalizeToolNames(left);
@@ -159,7 +196,8 @@ function clonePlainSnapshot(value, ancestors = new WeakSet(), copies = new WeakM
     ancestors.add(value);
     try {
         if (Array.isArray(value)) {
-            const copy = new Array(value.length);
+            const copy = [];
+            copy.length = value.length;
             copies.set(value, copy);
             for (const key of Reflect.ownKeys(value)) {
                 if (key === "length")
@@ -243,6 +281,7 @@ export class AgentSession {
      */
     _reasoningRouterBiasSnapshot = null;
     _reasoningRouterBiasSnapshotLoaded = false;
+    _lastAutoRouterDecision;
     /**
      * AdaptOrch advisory bridge (default-off, global-only opt-in via
      * `adaptorchBridge.enabled` in ~/.omk/agent/settings.json). Lazily
@@ -265,7 +304,7 @@ export class AgentSession {
     // Compaction state
     _compactionAbortController = undefined;
     _autoCompactionAbortController = undefined;
-    _overflowRecoveryAttempted = false;
+    _overflowRecoveryAttempts = 0;
     _thresholdCompactionEmergency = false;
     _compactionHysteresisState = createCompactionHysteresisState();
     // Branch summarization state
@@ -285,7 +324,12 @@ export class AgentSession {
     _resourceLoader;
     _customTools;
     _baseToolDefinitions = new Map();
+    _mcpManager;
+    _mcpToolNames = new Set();
+    _turnMetricsSink;
+    _turnMetricsState;
     _cwd;
+    _repositoryRouterLearningPaths;
     _extensionRunnerRef;
     _initialActiveToolNames;
     _allowedToolNames;
@@ -302,6 +346,7 @@ export class AgentSession {
     _extensionErrorUnsubscriber;
     // Required durable run/audit chain, persisted next to the session file.
     _runJournalStore;
+    _ownedSessionOwnerLease;
     _activeRunId = null;
     _pendingRuntimeTerminationCause;
     _activeRunToolTermination;
@@ -326,7 +371,13 @@ export class AgentSession {
     _toolPromptGuidelines = new Map();
     // Base system prompt (without extension appends) - used to apply fresh appends each turn
     _baseSystemPrompt = "";
+    _baseSystemPromptCacheBoundary;
     _baseSystemPromptOptions;
+    _promptCacheKey;
+    _promptCacheKeyChanges = 0;
+    _promptCacheBoundaryBypasses = 0;
+    _promptCacheStablePrefixCharacters = 0;
+    _promptCacheLastBreakReason;
     constructor(config) {
         this.agent = config.agent;
         this.sessionManager = config.sessionManager;
@@ -389,31 +440,55 @@ export class AgentSession {
             recordCommit: () => this._recordCompactionCommitForHysteresis(),
         });
         const sessionFile = this.sessionManager.getSessionFile();
-        this._runJournalStore = RunJournalStore.open({
-            ...(sessionFile ? { journalPath: `${sessionFile}.runjournal` } : {}),
-            sessionId: this.sessionManager.getSessionId(),
-        });
-        const startupRecords = this._runJournalStore.records;
-        const startupTerminal = startupRecords[startupRecords.length - 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,
+        let ownerLease = this.sessionManager.getOwnerLease();
+        try {
+            if (sessionFile && !ownerLease) {
+                ownerLease = acquireSessionOwnerLeaseSync(sessionFile);
+                this._ownedSessionOwnerLease = ownerLease;
+                this.sessionManager.setOwnerLease(ownerLease);
+            }
+            this._runJournalStore = RunJournalStore.open({
+                ...(sessionFile ? { journalPath: `${sessionFile}.runjournal` } : {}),
+                sessionId: this.sessionManager.getSessionId(),
+                ...(ownerLease ? { ownerLease } : {}),
+            });
+            const startupRecords = this._runJournalStore.records;
+            const startupTerminal = startupRecords[startupRecords.length - 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,
             });
         }
-        this._buildRuntime({
-            activeToolNames: this._initialActiveToolNames,
-            includeAllExtensionTools: true,
-        });
+        catch (error) {
+            const ownedLease = this._ownedSessionOwnerLease;
+            if (ownedLease) {
+                try {
+                    ownedLease.release();
+                    if (this.sessionManager.getOwnerLease() === ownedLease)
+                        this.sessionManager.setOwnerLease(undefined);
+                    this._ownedSessionOwnerLease = undefined;
+                }
+                catch {
+                    throw new Error("AgentSession initialization cleanup failed");
+                }
+            }
+            throw error;
+        }
     }
     /** Model registry for API key resolution and model discovery */
     get modelRegistry() {
@@ -512,12 +587,15 @@ export class AgentSession {
         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" };
         }
+        // Quota/billing exhaustion is checked BEFORE the generic 401/403 auth
+        // patterns: "403 ... usage limit for this billing cycle" is transient per
+        // cycle and must fail over, not terminate the turn as an auth error.
+        if (isQuotaExhaustionMessage(text) || /rate.?limit|too many requests|429/i.test(text)) {
+            return { area: "provider", code: "rate_limit" };
+        }
         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)) {
@@ -536,6 +614,9 @@ export class AgentSession {
         if (!this.model || /no model|model selected|model is required/i.test(message)) {
             return { area: "configuration", code: "invalid" };
         }
+        if (isQuotaExhaustionMessage(message)) {
+            return { area: "provider", code: "rate_limit" };
+        }
         if (/auth|api key|unauthori[sz]ed|forbidden|401|403|\/login/i.test(message)) {
             return { area: "provider", code: "auth" };
         }
@@ -564,9 +645,14 @@ export class AgentSession {
     }
     _classifyRunTermination(runId, event) {
         const timestamp = new Date().toISOString();
-        const assistant = [...event.messages]
-            .reverse()
-            .find((message) => message.role === "assistant");
+        let assistant;
+        for (let index = event.messages.length - 1; index >= 0; index -= 1) {
+            const message = event.messages[index];
+            if (message?.role === "assistant") {
+                assistant = message;
+                break;
+            }
+        }
         let cause;
         let message;
         let sideEffects = this._sessionRiskLevel === "elevated" ? "possible" : "none";
@@ -595,6 +681,12 @@ export class AgentSession {
             cause = { area: "completed" };
             message = "Run completed.";
         }
+        let provider = this.model?.provider;
+        if (assistant?.provider)
+            provider = assistant.provider;
+        let model = this.model?.id;
+        if (assistant?.model)
+            model = assistant.model;
         return classifySessionTermination({
             sessionId: this.sessionId,
             runId,
@@ -603,12 +695,8 @@ export class AgentSession {
             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 } : {}),
+            ...(provider ? { provider } : {}),
+            ...(model ? { model } : {}),
             ...(toolCallId ? { toolCallId } : {}),
             ...(toolName ? { toolName } : {}),
         });
@@ -637,11 +725,13 @@ export class AgentSession {
         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 message = "The AgentSession runtime failed before completing the run.";
+        if (cause.area === "persistence") {
+            message = "A required runtime persistence operation failed.";
+        }
+        else if (cause.area === "compaction") {
+            message = "Runtime compaction failed.";
+        }
         let termination = classifySessionTermination({
             sessionId: this.sessionId,
             runId,
@@ -884,7 +974,7 @@ export class AgentSession {
         // 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") {
-            this._overflowRecoveryAttempted = false;
+            this._overflowRecoveryAttempts = 0;
             const messageText = this._getUserMessageText(event.message);
             if (messageText) {
                 // Check steering queue first
@@ -935,7 +1025,7 @@ export class AgentSession {
                 this._lastAssistantMessage = finalizedEvent.message;
                 const assistantMsg = finalizedEvent.message;
                 if (assistantMsg.stopReason !== "error") {
-                    this._overflowRecoveryAttempted = false;
+                    this._overflowRecoveryAttempts = 0;
                 }
                 // Reset retry counter immediately on successful assistant response
                 // This prevents accumulation across multiple LLM calls within a turn
@@ -993,9 +1083,13 @@ export class AgentSession {
                 ? "Finalized message was not found in agent state"
                 : "Finalized message is ambiguous in agent state");
         }
+        const matchingIndex = matchingIndexes[0];
+        if (matchingIndex === undefined) {
+            throw new Error("Finalized message was not found in agent state");
+        }
         const finalizedReplacement = createImmutableMessageSnapshot(replacement);
-        const nextMessages = messages.slice();
-        nextMessages[matchingIndexes[0]] = finalizedReplacement;
+        const nextMessages = [...messages];
+        nextMessages[matchingIndex] = finalizedReplacement;
         this.agent.state.messages = nextMessages;
         return finalizedReplacement;
     }
@@ -1009,6 +1103,13 @@ export class AgentSession {
             await this._extensionRunner.emit({ type: "agent_end", messages: event.messages });
         }
         else if (event.type === "turn_start") {
+            this._turnMetricsState = {
+                startedAtEpochMs: Date.now(),
+                toolCalls: [],
+                toolStarts: new Map(),
+                requestedModel: this.model ? `${this.model.provider}/${this.model.id}` : null,
+                requestedThinking: this.thinkingMode === "auto" ? "auto" : this.thinkingLevel,
+            };
             const extensionEvent = {
                 type: "turn_start",
                 turnIndex: this._turnIndex,
@@ -1017,6 +1118,7 @@ export class AgentSession {
             await this._extensionRunner.emit(extensionEvent);
         }
         else if (event.type === "turn_end") {
+            this._recordTurnMetrics(event.message);
             const extensionEvent = {
                 type: "turn_end",
                 turnIndex: this._turnIndex,
@@ -1053,6 +1155,7 @@ export class AgentSession {
             }
         }
         else if (event.type === "tool_execution_start") {
+            this._turnMetricsState?.toolStarts.set(event.toolCallId, Date.now());
             const extensionEvent = {
                 type: "tool_execution_start",
                 toolCallId: event.toolCallId,
@@ -1072,6 +1175,7 @@ export class AgentSession {
             await this._extensionRunner.emit(extensionEvent);
         }
         else if (event.type === "tool_execution_end") {
+            this._recordToolMetric(event.toolCallId, event.toolName, event.isError === true, event.result);
             const extensionEvent = {
                 type: "tool_execution_end",
                 toolCallId: event.toolCallId,
@@ -1082,6 +1186,81 @@ export class AgentSession {
             await this._extensionRunner.emit(extensionEvent);
         }
     }
+    /**
+     * Turn metrics sink for this session, created on first use.
+     *
+     * Writes to `<cwd>/.omk/metrics/`. Set `OMK_TURN_METRICS=0` to disable, or
+     * `OMK_TURN_METRICS_DIR` to relocate. Returns `undefined` when disabled, so
+     * every call site is a no-op rather than a branch.
+     */
+    _metricsSink() {
+        if (isDisabledEnvValue(process.env.OMK_TURN_METRICS))
+            return undefined;
+        if (!this._turnMetricsSink) {
+            const dir = process.env.OMK_TURN_METRICS_DIR ?? joinPath(this._cwd, ".omk", "metrics");
+            this._turnMetricsSink = new TurnMetricsSink({ dir });
+        }
+        return this._turnMetricsSink;
+    }
+    _recordToolMetric(toolCallId, toolName, isError, result) {
+        const state = this._turnMetricsState;
+        if (!state)
+            return;
+        const startedAt = state.toolStarts.get(toolCallId);
+        state.toolStarts.delete(toolCallId);
+        state.toolCalls.push({
+            name: toolName,
+            durationMs: startedAt === undefined ? 0 : Date.now() - startedAt,
+            ok: !isError,
+            ...(isError ? { error: firstTextContent(result) } : {}),
+        });
+    }
+    /** Persist one turn. Metrics are advisory: a failure here never affects the turn. */
+    _recordTurnMetrics(message) {
+        const state = this._turnMetricsState;
+        this._turnMetricsState = undefined;
+        if (!state)
+            return;
+        const sink = this._metricsSink();
+        if (!sink)
+            return;
+        const assistant = message.role === "assistant" ? message : undefined;
+        const usage = assistant?.usage;
+        const selectedModel = this.model ? `${this.model.provider}/${this.model.id}` : null;
+        const runtimeProvenance = buildRuntimeProvenance({
+            requestedModel: state.requestedModel,
+            selectedModel,
+            responseModel: assistant?.responseModel ?? (assistant ? `${assistant.provider}/${assistant.model}` : null),
+            requestedThinking: state.requestedThinking,
+            effectiveThinking: this.thinkingLevel,
+            source: "session",
+        });
+        try {
+            sink.record({
+                sessionId: this.sessionId,
+                turnIndex: this._turnIndex,
+                provider: this.model?.provider,
+                model: this.model?.id,
+                startedAtEpochMs: state.startedAtEpochMs,
+                endedAtEpochMs: Date.now(),
+                stopReason: assistant?.stopReason,
+                runtimeProvenance,
+                usage: usage
+                    ? {
+                        input: usage.input,
+                        output: usage.output,
+                        cacheRead: usage.cacheRead,
+                        cacheWrite: usage.cacheWrite,
+                        costUsd: usage.cost.total,
+                    }
+                    : undefined,
+                toolCalls: state.toolCalls,
+            });
+        }
+        catch {
+            // Never let observability break a turn.
+        }
+    }
     /**
      * Subscribe to agent events.
      * Session persistence is handled internally (saves messages on message_end).
@@ -1123,19 +1302,59 @@ export class AgentSession {
      */
     dispose() {
         try {
-            this.abortRetry();
-            this.abortCompaction();
-            this.abortBranchSummary();
-            this.abortBash();
-            this.agent.abort();
+            try {
+                this.abortRetry();
+                this.abortCompaction();
+                this.abortBranchSummary();
+                this.abortBash();
+                this.agent.abort();
+            }
+            catch {
+                // Dispose must succeed even if an abort hook throws.
+            }
+            this._extensionRunner.invalidate("This extension ctx is stale after session replacement or reload. Do not use a captured extension API or command ctx after ctx.newSession(), ctx.fork(), ctx.switchSession(), or ctx.reload(). For newSession, fork, and switchSession, move post-replacement work into withSession and use the ctx passed to withSession. For reload, do not use the old ctx after await ctx.reload().");
+            this._disconnectFromAgent();
+            this._eventListeners = [];
+            if (this._contextBudgetCacheProvider instanceof DiskContextBudgetCacheProviderV2) {
+                // Persist whatever the session rendered; a failed flush is never fatal.
+                this._contextBudgetCacheProvider.close();
+            }
+            this._mcpManager?.close();
+            this._mcpManager = undefined;
+            cleanupSessionResources(this.sessionId);
+        }
+        finally {
+            const ownerLease = this._ownedSessionOwnerLease;
+            if (ownerLease) {
+                ownerLease.release();
+                if (this.sessionManager.getOwnerLease() === ownerLease)
+                    this.sessionManager.setOwnerLease(undefined);
+                this._ownedSessionOwnerLease = undefined;
+            }
+        }
+    }
+    /**
+     * Build the context-budget cache provider for this session.
+     *
+     * Defaults to a workspace-layer provider persisted under `<cwd>/.omk/cache`,
+     * so a second session reuses representations the first one already rendered
+     * (representation keys are content-addressed; see
+     * `context-budget-v2-cache-keys.ts`). Set
+     * `OMK_CONTEXT_GOVERNOR_CACHE=memory` to opt out, or
+     * `OMK_CONTEXT_GOVERNOR_CACHE_DIR` to relocate the snapshot.
+     */
+    _createContextBudgetCacheProvider() {
+        if (process.env.OMK_CONTEXT_GOVERNOR_CACHE === "memory") {
+            return createMemoryContextBudgetCacheProviderV2("session");
+        }
+        const dir = process.env.OMK_CONTEXT_GOVERNOR_CACHE_DIR ?? joinPath(this._cwd, ".omk", "cache", "context-budget-v2");
+        try {
+            return createDiskContextBudgetCacheProviderV2({ dir, layer: "workspace" });
         }
         catch {
-            // Dispose must succeed even if an abort hook throws.
+            // An unusable cache directory must not take the session down.
+            return createMemoryContextBudgetCacheProviderV2("session");
         }
-        this._extensionRunner.invalidate("This extension ctx is stale after session replacement or reload. Do not use a captured extension API or command ctx after ctx.newSession(), ctx.fork(), ctx.switchSession(), or ctx.reload(). For newSession, fork, and switchSession, move post-replacement work into withSession and use the ctx passed to withSession. For reload, do not use the old ctx after await ctx.reload().");
-        this._disconnectFromAgent();
-        this._eventListeners = [];
-        cleanupSessionResources(this.sessionId);
     }
     // =========================================================================
     // Read-only State Access
@@ -1220,6 +1439,9 @@ export class AgentSession {
         // Rebuild base system prompt with new tool set
         this._baseSystemPrompt = this._rebuildSystemPrompt(validToolNames);
         this.agent.state.systemPrompt = this._baseSystemPrompt;
+        this.agent.state.systemPromptCacheBoundary = this._baseSystemPromptCacheBoundary;
+        this.agent.state.systemPromptCacheBoundaryBypass = false;
+        this._recordPromptCachePlan("tool-set");
     }
     /**
      * Recompute the Agent's per-name timeout map for the active tool set:
@@ -1316,7 +1538,7 @@ export class AgentSession {
         const recent = messages.slice(-3);
         for (let i = recent.length - 1; i >= 0; i--) {
             const msg = recent[i];
-            if (!("role" in msg) || msg.role !== "user") {
+            if (!msg || !("role" in msg) || msg.role !== "user") {
                 continue;
             }
             const content = msg.content;
@@ -1325,9 +1547,7 @@ export class AgentSession {
                 return trimmed.length > 0 ? trimmed : undefined;
             }
             if (Array.isArray(content)) {
-                const textParts = content
-                    .filter((c) => "type" in c && c.type === "text")
-                    .map((c) => c.text);
+                const textParts = content.flatMap((item) => (item.type === "text" ? [item.text] : []));
                 const joined = textParts.join("\n").trim();
                 return joined.length > 0 ? joined : undefined;
             }
@@ -1377,7 +1597,7 @@ export class AgentSession {
             responseReserveTokens =
                 parsePositiveIntegerEnv("OMK_CONTEXT_GOVERNOR_RESPONSE_RESERVE_TOKENS") ?? LEGACY_RESPONSE_RESERVE_TOKENS;
         }
-        const cacheProvider = this._contextBudgetCacheProvider ?? createMemoryContextBudgetCacheProviderV2("session");
+        const cacheProvider = this._contextBudgetCacheProvider ?? this._createContextBudgetCacheProvider();
         cacheProvider.setInvalidationSnapshot?.(this._contextCacheInvalidationSnapshot);
         this._contextBudgetCacheProvider = cacheProvider;
         // Enforce floor
@@ -1411,6 +1631,32 @@ export class AgentSession {
         const ratio = overrideRatio ?? RESPONSE_RESERVE_RATIO;
         return Math.max(Math.floor(contextWindow * ratio), LEGACY_RESPONSE_RESERVE_TOKENS);
     }
+    _recordPromptCachePlan(reason) {
+        const boundary = this.agent.state.systemPromptCacheBoundary;
+        const scope = this.model ? `${this.model.provider}/${this.model.id}` : "unknown";
+        const nextKey = deriveContextPromptCacheKey({
+            systemPrompt: this.agent.state.systemPrompt,
+            systemPromptCacheBoundary: boundary,
+            systemPromptCacheBoundaryBypass: this.agent.state.systemPromptCacheBoundaryBypass,
+            messages: [],
+            tools: this.agent.state.tools,
+        }, scope);
+        if (!nextKey) {
+            this._promptCacheBoundaryBypasses += 1;
+            this._promptCacheStablePrefixCharacters = 0;
+            if (this._promptCacheKey !== undefined) {
+                this._promptCacheLastBreakReason = reason;
+            }
+            this._promptCacheKey = undefined;
+            return;
+        }
+        if (this._promptCacheKey !== undefined && this._promptCacheKey !== nextKey) {
+            this._promptCacheKeyChanges += 1;
+            this._promptCacheLastBreakReason = reason;
+        }
+        this._promptCacheKey = nextKey;
+        this._promptCacheStablePrefixCharacters = boundary ?? 0;
+    }
     _rebuildSystemPrompt(toolNames) {
         const validToolNames = toolNames.filter((name) => this._toolRegistry.has(name));
         const toolSnippets = {};
@@ -1446,7 +1692,9 @@ export class AgentSession {
             promptGuidelines,
             contextBudget: this._getContextBudgetOptions(),
         };
-        return buildSystemPrompt(this._baseSystemPromptOptions);
+        const built = buildSystemPromptPlan(this._baseSystemPromptOptions);
+        this._baseSystemPromptCacheBoundary = built.cacheBoundary;
+        return built.prompt;
     }
     // =========================================================================
     // Prompting
@@ -1625,9 +1873,9 @@ export class AgentSession {
                 ...(promptActiveSkillNames.length > 0 ? { activeSkillNames: promptActiveSkillNames } : {}),
                 ...(promptActiveSkillSource ? { activeSkillSource: promptActiveSkillSource } : {}),
             };
-            const turnSystemPrompt = buildSystemPrompt(turnSystemPromptOptions);
+            const turnSystemPrompt = buildSystemPromptPlan(turnSystemPromptOptions);
             // Emit before_agent_start extension event
-            const result = await this._extensionRunner.emitBeforeAgentStart(expandedText, currentImages, turnSystemPrompt, turnSystemPromptOptions);
+            const result = await this._extensionRunner.emitBeforeAgentStart(expandedText, currentImages, turnSystemPrompt.prompt, turnSystemPromptOptions);
             // Add all custom messages from extensions
             if (result?.messages) {
                 for (const msg of result.messages) {
@@ -1641,14 +1889,22 @@ export class AgentSession {
                     });
                 }
             }
-            // Apply extension-modified system prompt, or reset to base
+            // Apply extension-modified system prompt, or reset to the turn plan.
             if (result?.systemPrompt) {
+                const preservesCacheBoundary = result.systemPrompt === turnSystemPrompt.prompt;
                 this.agent.state.systemPrompt = result.systemPrompt;
+                this.agent.state.systemPromptCacheBoundary = preservesCacheBoundary
+                    ? turnSystemPrompt.cacheBoundary
+                    : undefined;
+                this.agent.state.systemPromptCacheBoundaryBypass = !preservesCacheBoundary;
             }
             else {
-                // Ensure we're using the base prompt (in case previous turn had modifications)
-                this.agent.state.systemPrompt = turnSystemPrompt;
+                // Ensure we're using the turn prompt (in case the previous turn had modifications).
+                this.agent.state.systemPrompt = turnSystemPrompt.prompt;
+                this.agent.state.systemPromptCacheBoundary = turnSystemPrompt.cacheBoundary;
+                this.agent.state.systemPromptCacheBoundaryBypass = false;
             }
+            this._recordPromptCachePlan(result?.systemPrompt ? "extension-override" : "turn-plan");
             await this._checkProjectedCompaction(messages);
         }
         catch (error) {
@@ -2080,6 +2336,18 @@ export class AgentSession {
             });
         }
     }
+    /** Apply an explicit user choice and retain it as bounded router feedback. */
+    setUserThinkingLevel(level) {
+        const overridesAuto = this._thinkingMode === "auto";
+        this.setThinkingMode("manual");
+        this.setThinkingLevel(level);
+        if (overridesAuto) {
+            this._recordUserThinkingOverride(this.thinkingLevel);
+        }
+        else {
+            this._lastAutoRouterDecision = undefined;
+        }
+    }
     /**
      * Set the thinking mode. "auto" resolves a level per turn via the reasoning
      * router; "manual" keeps the explicitly selected level. The mode persists for
@@ -2107,21 +2375,20 @@ export class AgentSession {
      * context-pressure bucket, routed through the confidence-bearing v4 classifier
      * and its uncertainty-aware resolver. No
      * `laneType` applies to the main session (always "none"/`undefined`);
-     * `hint` is permanently `null` -- the Adaptorch advisory bridge has no
-     * transport wired into the session (out of this lane's scope; see
-     * adaptorch-bridge.ts). `bias` stays `0` unless BOTH hold: (a) the global,
+     * the default-off Adaptorch bridge is wired but its current transport returns
+     * no advisory hint. `bias` stays `0` unless BOTH hold: (a) the global,
      * owner-only `reasoningRouterLearning.enabled` setting is `true` (default
      * off; a project-scope `.omk/settings.json` value for this key is never
      * consulted -- see settings-manager.ts), and (b) a compiled
      * `RouterBiasSnapshot` was found and passed strict validation at the
-     * configured/default path, loaded and cached ("pinned") at most once per
-     * session (see `_getReasoningRouterBiasSnapshot`). When learning is
-     * enabled, exactly one bounded "accepted" feedback record (no raw prompt/
-     * path/diff/session/model/provider/tool/hook content; see
-     * router-feedback-collector.ts's exact ten-key schema) is appended to the
-     * local ledger after every v4 auto-turn resolution, for a future, separate
-     * offline compile step to learn from -- this lane never records an
-     * override/fail/hook-outcome signal, only the neutral "accepted" one. The
+     * configured path or opaque repository/worktree-scoped default, loaded and
+     * cached ("pinned") at most once per session (see
+     * `_getReasoningRouterBiasSnapshot`). When learning is enabled, one bounded
+     * "accepted" record (no raw prompt/path/diff/session/model/provider/tool/hook
+     * content; see router-feedback-collector.ts's exact ten-key schema) is
+     * appended after every v4 auto-turn. A later explicit user level records one
+     * bounded `s1-override` direction for the same cell. Both remain inert until
+     * a future, separate offline compile step. The
      * resolver's own confidence-band/fallback-reason escalation (see
      * reasoning-router-v4.ts) still applies on top of the base+lane+bias
      * target, so a low-confidence or fallback-decided verdict can still only
@@ -2129,17 +2396,17 @@ export class AgentSession {
      */
     _applyAutoThinkingLevelV4(promptText) {
         const availableLevels = this.getAvailableThinkingLevels();
+        const features = deriveRouterFeedbackFeaturesV4(promptText);
         const verdict = classifyTaskV4({
             prompt: promptText,
             history: this._taskClassHistory,
             pressureBucket: this._computePressureBucket(),
-        });
+        }, undefined, features);
         this._taskClassHistory.unshift(verdict.taskClass);
         if (this._taskClassHistory.length > 8)
             this._taskClassHistory.length = 8;
         const learningEnabled = this.settingsManager.getReasoningRouterLearningEnabled();
         const snapshot = learningEnabled ? this._getReasoningRouterBiasSnapshot() : null;
-        const features = this._deriveRouterFeedbackFeatures(promptText);
         const bias = snapshot === null
             ? 0
             : getBiasStepsForCell(snapshot, {
@@ -2150,22 +2417,23 @@ export class AgentSession {
                 hadDiff: features.hadDiff,
             });
         const resolved = resolveThinkingLevelV4WithUncertainty(verdict, availableLevels, undefined, bias, this._getAdaptorchHint(verdict, features));
+        this._lastAutoRouterDecision = undefined;
         if (learningEnabled && resolved !== "off") {
-            const record = {
+            const decision = {
                 routerVersion: "v4",
                 laneType: "none",
                 predictedClass: verdict.taskClass,
                 resolvedLevel: resolved,
-                acceptedLevel: resolved,
-                signal: "s2-accept",
-                outcome: "accepted",
                 lenBucket: features.lenBucket,
                 hadFence: features.hadFence,
                 hadDiff: features.hadDiff,
             };
-            appendRouterFeedbackRecord(record, {
-                enabled: true,
-                ledgerPath: this.settingsManager.getReasoningRouterLearningFeedbackLedgerPath(),
+            this._lastAutoRouterDecision = decision;
+            this._appendRouterFeedback({
+                ...decision,
+                acceptedLevel: resolved,
+                signal: "s2-accept",
+                outcome: "accepted",
             });
         }
         const previousLevel = this.agent.state.thinkingLevel;
@@ -2175,21 +2443,44 @@ export class AgentSession {
         this.sessionManager.appendThinkingLevelChange(resolved);
         this._emit({ type: "thinking_level_changed", level: resolved });
     }
+    _getRepositoryRouterLearningPaths() {
+        if (this._repositoryRouterLearningPaths === undefined) {
+            this._repositoryRouterLearningPaths = getRepositoryRouterLearningPaths(this._cwd);
+        }
+        return this._repositoryRouterLearningPaths;
+    }
+    _appendRouterFeedback(record) {
+        appendRouterFeedbackRecord(record, {
+            enabled: this.settingsManager.getReasoningRouterLearningEnabled(),
+            ledgerPath: this.settingsManager.getReasoningRouterLearningFeedbackLedgerPath() ??
+                this._getRepositoryRouterLearningPaths().ledgerPath,
+        });
+    }
+    _recordUserThinkingOverride(acceptedLevel) {
+        const decision = this._lastAutoRouterDecision;
+        this._lastAutoRouterDecision = undefined;
+        if (!this.settingsManager.getReasoningRouterLearningEnabled() || !decision || acceptedLevel === "off")
+            return;
+        const resolvedIndex = ROUTER_FEEDBACK_LEVELS.indexOf(decision.resolvedLevel);
+        const acceptedIndex = ROUTER_FEEDBACK_LEVELS.indexOf(acceptedLevel);
+        const outcome = acceptedIndex > resolvedIndex ? "up" : acceptedIndex < resolvedIndex ? "down" : "same";
+        this._appendRouterFeedback({
+            ...decision,
+            acceptedLevel,
+            signal: "s1-override",
+            outcome,
+        });
+    }
     /**
-     * Loads and strictly validates the compiled reasoning-router bias snapshot
-     * for the opt-in v4 learning path (Goal 010 Lane I), at most once per
-     * session ("pinned"): the first call attempts the read and caches whatever
-     * it finds (including a `null` miss/failure); every later call in the same
-     * session reuses that cached result without touching disk again. Returns
-     * `null` when no file exists at the configured/default path, the file
-     * cannot be read, or its contents fail `parseRouterBiasSnapshot`'s schema
-     * validation -- never throws.
+     * Strictly load the compiled bias snapshot once per session. The first call
+     * pins either a valid snapshot or a null miss; later calls never touch disk.
      */
     _getReasoningRouterBiasSnapshot() {
         if (this._reasoningRouterBiasSnapshotLoaded)
             return this._reasoningRouterBiasSnapshot;
         this._reasoningRouterBiasSnapshotLoaded = true;
-        const path = this.settingsManager.getReasoningRouterLearningBiasSnapshotPath() ?? getDefaultRouterBiasSnapshotPath();
+        const path = this.settingsManager.getReasoningRouterLearningBiasSnapshotPath() ??
+            this._getRepositoryRouterLearningPaths().biasSnapshotPath;
         try {
             if (existsSync(path)) {
                 this._reasoningRouterBiasSnapshot = parseRouterBiasSnapshot(readFileSync(path, "utf-8"));
@@ -2200,29 +2491,6 @@ export class AgentSession {
         }
         return this._reasoningRouterBiasSnapshot;
     }
-    /**
-     * Locally derives the same three bounded, privacy-safe feedback-ledger
-     * features (`lenBucket`, `hadFence`, `hadDiff`) the v4 classifier computes
-     * internally (reasoning-router-v4.ts keeps those helpers file-private, so
-     * they cannot be imported here). Mirrors reasoning-router-v4.ts's
-     * length-bucket, `hasCodeFence`, and `hasDiffMarkers` helpers. Operates on the same trimmed prompt text
-     * the classifier scores; never returns raw prompt content or its exact
-     * length, only the clamped [0,7] bucket and two booleans.
-     */
-    _deriveRouterFeedbackFeatures(promptText) {
-        const trimmed = promptText.trim();
-        let lenBucket = 0;
-        let remaining = trimmed.length + 1;
-        while (remaining > 1 && lenBucket < 7) {
-            remaining >>= 1;
-            lenBucket++;
-        }
-        const hadFence = trimmed.includes("```");
-        const hadDiff = /^@@[^\n]*@@/m.test(trimmed) ||
-            /^diff --git /m.test(trimmed) ||
-            (/^\+(?!\+)/m.test(trimmed) && /^-(?!-)/m.test(trimmed));
-        return { lenBucket: lenBucket, hadFence, hadDiff };
-    }
     /**
      * Context-pressure band 0..3 from the projected token estimate over the
      * model context window (reuses estimateProjectedContextTokens). 0..<0.5,
@@ -2298,20 +2566,7 @@ export class AgentSession {
         // 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 };
+        return { level: TASK_CLASS_THINKING_LEVELS_V4[hint.taskClass], confidence };
     }
     /**
      * Cycle to next thinking level.
@@ -2324,7 +2579,12 @@ export class AgentSession {
         const currentIndex = levels.indexOf(this.thinkingLevel);
         const nextIndex = (currentIndex + 1) % levels.length;
         const nextLevel = levels[nextIndex];
+        const overridesAuto = this._thinkingMode === "auto";
         this.setThinkingLevel(nextLevel);
+        if (overridesAuto) {
+            this.setThinkingMode("manual");
+            this._recordUserThinkingOverride(nextLevel);
+        }
         return nextLevel;
     }
     /**
@@ -2340,7 +2600,7 @@ export class AgentSession {
      * Check if current model supports thinking/reasoning.
      */
     supportsThinking() {
-        return !!this.model?.reasoning;
+        return Boolean(this.model?.reasoning);
     }
     _getThinkingLevelForModelSwitch(explicitLevel) {
         if (explicitLevel !== undefined) {
@@ -2490,8 +2750,8 @@ export class AgentSession {
      * @param customInstructions Optional instructions for the compaction summary
      */
     async compact(customInstructions) {
-        this._disconnectFromAgent();
         await this.abort();
+        this._disconnectFromAgent();
         this._compactionAbortController = new AbortController();
         this._emit({ type: "compaction_start", reason: "manual" });
         let committedCompaction = false;
@@ -2554,7 +2814,7 @@ export class AgentSession {
                 throw new Error("Compaction cancelled");
             }
             const compactionResult = {
-                summary: redactSensitiveText(summary),
+                summary: redactCredentialShapedContent(redactSensitiveTextForced(summary)),
                 firstKeptEntryId,
                 tokensBefore,
                 details,
@@ -2582,6 +2842,11 @@ export class AgentSession {
             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);
+            let compactionCode = "failed";
+            if (aborted)
+                compactionCode = "aborted";
+            else if (stale)
+                compactionCode = "stale";
             const timestamp = new Date().toISOString();
             this._publishTermination(classifySessionTermination({
                 sessionId: this.sessionId,
@@ -2589,7 +2854,7 @@ export class AgentSession {
                 timestamp,
                 source: "observed",
                 message: this._terminationMessage(message, "Manual compaction failed."),
-                cause: { area: "compaction", code: aborted ? "aborted" : stale ? "stale" : "failed" },
+                cause: { area: "compaction", code: compactionCode },
                 sideEffects: committedCompaction ? "confirmed" : "none",
                 ...(this.model ? { provider: this.model.provider, model: this.model.id } : {}),
             }));
@@ -2621,11 +2886,46 @@ export class AgentSession {
     abortBranchSummary() {
         this._branchSummaryAbortController?.abort();
     }
+    /** True when the transcript carries image content that forces a vision-route turn. */
+    _transcriptHasImages(messages) {
+        return messages.some((m) => {
+            const content = m.content;
+            if (!Array.isArray(content))
+                return false;
+            return content.some((part) => {
+                return typeof part === "object" && part !== null && part.type === "image";
+            });
+        });
+    }
+    /**
+     * Effective context window for the upcoming turn.
+     * Image-bearing turns with a text-only session model are auto-routed to the
+     * vision model (gpt-5.6-luna, 400K) — that window is the real limit. Text-only
+     * turns keep the session model's (typically much larger) window.
+     */
+    _effectiveTurnContextWindow(pendingMessages, sessionWindow) {
+        // Vision routing keys off the full transcript, not just the pending turn:
+        // images retained in history keep every subsequent request on the vision model.
+        const hasImages = this._transcriptHasImages(this.agent.state.messages) || this._transcriptHasImages(pendingMessages);
+        const model = this.model;
+        if (!hasImages || !model || (model.input ?? []).includes("image")) {
+            return sessionWindow;
+        }
+        return Math.min(sessionWindow, getVisionRouteModel(model).contextWindow);
+    }
     async _checkProjectedCompaction(pendingMessages) {
         const settings = this.settingsManager.getCompactionSettings();
         if (!settings.enabled || pendingMessages.length === 0)
             return false;
-        const contextWindow = this.model?.contextWindow ?? 0;
+        const sessionWindow = this.model?.contextWindow ?? 0;
+        if (sessionWindow <= 0)
+            return false;
+        // Image-bearing turns are served by the auto-routed vision model, not the
+        // session model. Its window (not the session model's) is the real limit the
+        // provider enforces, so threshold compaction must use it or the vision
+        // request overflows (context_length_exceeded) before deepseek-based
+        // compaction would fire.
+        const contextWindow = this._effectiveTurnContextWindow(pendingMessages, sessionWindow);
         if (contextWindow <= 0)
             return false;
         const messages = [...this.agent.state.messages, ...pendingMessages];
@@ -2640,7 +2940,7 @@ export class AgentSession {
         }
         const decision = this._runtimeCompactionDecision(estimate.tokens, contextWindow, settings);
         if (decision.compact) {
-            return await this._runThresholdCompaction(decision.emergency);
+            return this._runThresholdCompaction(decision.emergency);
         }
         return false;
     }
@@ -2668,6 +2968,13 @@ export class AgentSession {
         // to a larger-context model (e.g. codex) - the overflow error from the old model
         // shouldn't trigger compaction for the new model.
         const sameModel = this.model && assistantMessage.provider === this.model.provider && assistantMessage.model === this.model.id;
+        // Image-bearing turns are auto-routed to a vision-capable model (gpt-5.6-luna)
+        // while the session model stays text-only (deepseek). An overflow from that
+        // routed model must still count as the session's own overflow: compaction is
+        // the fix, and the raw context_length_exceeded error must never reach the user.
+        const visionRouteOverflow = this.model != null &&
+            !(this.model.input ?? []).includes("image") &&
+            isVisionRouteModel({ provider: assistantMessage.provider, id: assistantMessage.model });
         // Skip compaction checks if this assistant message is older than the latest
         // compaction boundary. This prevents a stale pre-compaction usage/error
         // from retriggering compaction on the first prompt after compaction.
@@ -2677,26 +2984,26 @@ export class AgentSession {
             return false;
         }
         // Case 1: Overflow - LLM returned context overflow error
-        if (sameModel && isContextOverflow(assistantMessage, contextWindow)) {
-            if (this._overflowRecoveryAttempted) {
+        if ((sameModel || visionRouteOverflow) && isContextOverflow(assistantMessage, contextWindow)) {
+            if (this._overflowRecoveryAttempts >= MAX_OVERFLOW_RECOVERY_ATTEMPTS) {
                 this._emit({
                     type: "compaction_end",
                     reason: "overflow",
                     result: undefined,
                     aborted: false,
                     willRetry: false,
-                    errorMessage: "Context overflow recovery failed after one compact-and-retry attempt. Try reducing context or switching to a larger-context model.",
+                    errorMessage: "Context overflow recovery failed after two staged compact-and-retry attempts. Reduce the latest input or switch to a model with a larger effective context window.",
                 });
                 return false;
             }
-            this._overflowRecoveryAttempted = true;
+            this._overflowRecoveryAttempts++;
             // Remove the error message from agent state (it IS saved to session for history,
             // but we don't want it in context for the retry)
             const messages = this.agent.state.messages;
             if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
                 this.agent.state.messages = messages.slice(0, -1);
             }
-            return await this._runAutoCompaction("overflow", true);
+            return this._runAutoCompaction("overflow", true);
         }
         // Case 2: Threshold - context is getting large
         // For error messages (no usage data), estimate from last successful response.
@@ -2723,15 +3030,28 @@ export class AgentSession {
         }
         const decision = this._runtimeCompactionDecision(contextTokens, contextWindow, settings);
         if (decision.compact) {
-            return await this._runThresholdCompaction(decision.emergency);
+            return this._runThresholdCompaction(decision.emergency);
         }
         return false;
     }
+    _overflowCompactionSettings(settings, attempt) {
+        if (attempt < MAX_OVERFLOW_RECOVERY_ATTEMPTS)
+            return settings;
+        return {
+            ...settings,
+            reserveTokens: Math.min(settings.reserveTokens, OVERFLOW_RECOVERY_EMERGENCY_TOKENS),
+            reservedOutputTokens: Math.min(settings.reservedOutputTokens ?? settings.reserveTokens, OVERFLOW_RECOVERY_EMERGENCY_TOKENS),
+            keepRecentTokens: Math.min(settings.keepRecentTokens, OVERFLOW_RECOVERY_EMERGENCY_TOKENS),
+        };
+    }
     /**
      * Internal: Run auto-compaction with events.
      */
     async _runAutoCompaction(reason, willRetry, emergency = reason === "overflow" || this._thresholdCompactionEmergency) {
-        const settings = this.settingsManager.getCompactionSettings();
+        const configuredSettings = this.settingsManager.getCompactionSettings();
+        const settings = reason === "overflow"
+            ? this._overflowCompactionSettings(configuredSettings, this._overflowRecoveryAttempts)
+            : configuredSettings;
         this._emit({ type: "compaction_start", reason });
         this._autoCompactionAbortController = new AbortController();
         try {
@@ -2837,7 +3157,7 @@ export class AgentSession {
                 return false;
             }
             const result = {
-                summary: redactSensitiveText(summary),
+                summary: redactCredentialShapedContent(redactSensitiveTextForced(summary)),
                 firstKeptEntryId,
                 tokensBefore,
                 details,
@@ -2953,6 +3273,9 @@ export class AgentSession {
         this._resourceLoader.extendResources(extensionPaths);
         this._baseSystemPrompt = this._rebuildSystemPrompt(this.getActiveToolNames());
         this.agent.state.systemPrompt = this._baseSystemPrompt;
+        this.agent.state.systemPromptCacheBoundary = this._baseSystemPromptCacheBoundary;
+        this.agent.state.systemPromptCacheBoundaryBypass = false;
+        this._recordPromptCachePlan("resource-reload");
     }
     buildExtensionResourcePaths(entries) {
         return entries.map((entry) => {
@@ -3108,6 +3431,54 @@ export class AgentSession {
             },
         });
     }
+    /**
+     * Connect configured MCP servers and register their tools for this session.
+     *
+     * Connection is lazy by construction: nothing is spawned until this is called,
+     * and a server that fails to start is reported in the returned status instead
+     * of taking the session down. Calling it twice replaces the previously
+     * attached MCP tools rather than duplicating them.
+     *
+     * Returns per-server status so a caller can surface failures; an empty
+     * configuration returns an empty array without spawning anything.
+     */
+    async attachMcpServers(options) {
+        const servers = options?.servers ?? loadMcpServerConfigs(this._cwd);
+        this._mcpManager?.close();
+        this._mcpManager = undefined;
+        this._customTools = this._customTools.filter((definition) => !this._mcpToolNames.has(definition.name));
+        this._mcpToolNames = new Set();
+        if (servers.length === 0) {
+            this._refreshToolRegistry();
+            return [];
+        }
+        const manager = new McpManager({
+            servers,
+            cwd: this._cwd,
+            clientInfo: { name: APP_NAME, version: VERSION },
+            callTimeoutMs: options?.callTimeoutMs,
+        });
+        this._mcpManager = manager;
+        const definitions = await manager.listToolDefinitions();
+        // A builtin always wins a name collision; MCP must never shadow `bash`.
+        const usable = definitions.filter((definition) => !this._baseToolDefinitions.has(definition.name));
+        this._mcpToolNames = new Set(usable.map((definition) => definition.name));
+        this._customTools = [...this._customTools, ...usable];
+        this._refreshToolRegistry();
+        return manager.status();
+    }
+    /** Status of MCP servers attached to this session. Empty when none were attached. */
+    mcpServerStatus() {
+        return this._mcpManager?.status() ?? [];
+    }
+    /**
+     * Ping attached MCP servers and return fresh status, so callers (e.g. the
+     * status rail) can keep displaying real connectivity instead of the last
+     * handshake result. Resolves to [] when no manager is attached.
+     */
+    mcpCheckHealth(options) {
+        return this._mcpManager?.checkHealth(options) ?? Promise.resolve([]);
+    }
     _refreshToolRegistry(options) {
         const previousRegistryNames = new Set(this._toolRegistry.keys());
         const previousActiveToolNames = this.getActiveToolNames();
@@ -3128,15 +3499,17 @@ export class AgentSession {
                 throw new Error(`loadout extension tool shadows builtin: ${shadowedBuiltins.join(", ")}`);
             }
         }
-        const definitionRegistry = new Map(Array.from(this._baseToolDefinitions.entries())
-            .filter(([name]) => isAllowedTool(name))
-            .map(([name, definition]) => [
-            name,
-            {
-                definition,
-                sourceInfo: createSyntheticSourceInfo(`<builtin:${name}>`, { source: "builtin" }),
-            },
-        ]));
+        const definitionRegistry = new Map(Array.from(this._baseToolDefinitions.entries()).flatMap(([name, definition]) => isAllowedTool(name)
+            ? [
+                [
+                    name,
+                    {
+                        definition,
+                        sourceInfo: createSyntheticSourceInfo(`<builtin:${name}>`, { source: "builtin" }),
+                    },
+                ],
+            ]
+            : []));
         for (const tool of allCustomTools) {
             definitionRegistry.set(tool.definition.name, {
                 definition: tool.definition,
@@ -3144,26 +3517,29 @@ export class AgentSession {
             });
         }
         this._toolDefinitions = definitionRegistry;
-        this._toolPromptSnippets = new Map(Array.from(definitionRegistry.values())
-            .map(({ definition }) => {
+        this._toolPromptSnippets = new Map(Array.from(definitionRegistry.values()).flatMap(({ definition }) => {
             const snippet = this._normalizePromptSnippet(definition.promptSnippet);
-            return snippet ? [definition.name, snippet] : undefined;
-        })
-            .filter((entry) => entry !== undefined));
-        this._toolPromptGuidelines = new Map(Array.from(definitionRegistry.values())
-            .map(({ definition }) => {
+            return snippet ? [[definition.name, snippet]] : [];
+        }));
+        this._toolPromptGuidelines = new Map(Array.from(definitionRegistry.values()).flatMap(({ definition }) => {
             const guidelines = this._normalizePromptGuidelines(definition.promptGuidelines);
-            return guidelines.length > 0 ? [definition.name, guidelines] : undefined;
-        })
-            .filter((entry) => entry !== undefined));
+            return guidelines.length > 0 ? [[definition.name, guidelines]] : [];
+        }));
+        // Tools contributed by extensions the harness itself loads (`<builtin:*>`),
+        // as opposed to user/project/SDK extensions.
+        const builtinExtensionToolNames = new Set(allCustomTools.flatMap((tool) => (tool.sourceInfo.path.startsWith("<builtin:") ? [tool.definition.name] : [])));
         const runner = this._extensionRunner;
         const wrappedExtensionTools = wrapRegisteredTools(allCustomTools, runner);
-        const wrappedBuiltInTools = wrapRegisteredTools(Array.from(this._baseToolDefinitions.values())
-            .filter((definition) => isAllowedTool(definition.name))
-            .map((definition) => ({
-            definition,
-            sourceInfo: createSyntheticSourceInfo(`<builtin:${definition.name}>`, { source: "builtin" }),
-        })), runner);
+        const wrappedBuiltInTools = wrapRegisteredTools(Array.from(this._baseToolDefinitions.values()).flatMap((definition) => isAllowedTool(definition.name)
+            ? [
+                {
+                    definition,
+                    sourceInfo: createSyntheticSourceInfo(`<builtin:${definition.name}>`, {
+                        source: "builtin",
+                    }),
+                },
+            ]
+            : []), runner);
         const toolRegistry = new Map(wrappedBuiltInTools.map((tool) => [tool.name, tool]));
         for (const tool of wrappedExtensionTools) {
             toolRegistry.set(tool.name, tool);
@@ -3186,7 +3562,14 @@ export class AgentSession {
             }
         }
         else if (options?.includeAllExtensionTools) {
+            // "Keep extension tools on" is about the *user's* extensions. Tools shipped
+            // by a built-in extension (e.g. update_todo) are part of the harness's own
+            // tool surface, so they follow the built-in policy: when the caller asked
+            // for no built-in tools, they stay off too.
+            const builtinToolsDisabled = options.activeToolNames?.length === 0;
             for (const tool of wrappedExtensionTools) {
+                if (builtinToolsDisabled && builtinExtensionToolNames.has(tool.name))
+                    continue;
                 nextActiveToolNames.push(tool.name);
             }
         }
@@ -3217,12 +3600,14 @@ export class AgentSession {
                 canWritePath: (path) => loadoutAccessGuard({ operation: "write", toolName: "write", path }).allowed,
             }
             : {};
-        const baseToolDefinitions = this._baseToolsOverride
-            ? Object.fromEntries(Object.entries(this._baseToolsOverride).map(([name, tool]) => [
-                name,
-                createToolDefinitionFromAgentTool(tool),
-            ]))
-            : createAllToolDefinitions(this._cwd, {
+        const baseToolDefinitions = (() => {
+            if (this._baseToolsOverride) {
+                return Object.fromEntries(Object.entries(this._baseToolsOverride).map(([name, tool]) => [
+                    name,
+                    createToolDefinitionFromAgentTool(tool),
+                ]));
+            }
+            return createAllToolDefinitions(this._cwd, {
                 read: { autoResizeImages, ...loadoutReadOptions },
                 bash: {
                     commandPrefix: shellCommandPrefix,
@@ -3255,6 +3640,7 @@ export class AgentSession {
                 edit: loadoutWriteOptions,
                 write: loadoutWriteOptions,
             });
+        })();
         this._baseToolDefinitions = new Map(Object.entries(baseToolDefinitions).map(([name, tool]) => [name, tool]));
         const extensionsResult = this._resourceLoader.getExtensions();
         if (options.flagValues) {
@@ -3301,9 +3687,6 @@ export class AgentSession {
     // =========================================================================
     // Auto-Retry
     // =========================================================================
-    _isNonRetryableProviderLimitError(errorMessage) {
-        return /GoUsageLimitError|FreeUsageLimitError|Monthly usage limit reached|available balance|insufficient_quota|out of budget|quota exceeded|billing/i.test(errorMessage);
-    }
     /**
      * Check if an error is retryable (overloaded, rate limit, server errors).
      * Context overflow errors are NOT retryable (handled by compaction instead).
@@ -3316,8 +3699,11 @@ export class AgentSession {
         if (isContextOverflow(message, contextWindow))
             return false;
         const err = message.errorMessage;
-        if (this._isNonRetryableProviderLimitError(err))
-            return false;
+        // Billing/quota exhaustion: useless to retry the same model until the
+        // cycle resets, but the turn may still be saved by failing over to the
+        // next candidate, so let _prepareRetry run its failover path.
+        if (isQuotaExhaustionMessage(err))
+            return true;
         // Shared contract with provider-resilience.ts (Fable safety stop, K3 orphan tool_call_id, terminated).
         return isTransientProviderErrorMessage(err);
     }
@@ -3363,7 +3749,9 @@ export class AgentSession {
             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 (!next)
+                return false;
+            return this._modelRegistry.hasConfiguredAuth(next);
         });
         if (!pick) {
             throw new Error(stickySafetyBlockMessage(current.id, current.provider));
@@ -3385,8 +3773,11 @@ export class AgentSession {
         const resilience = resolveProviderResilience(this.settingsManager.getProviderResilienceSettings());
         if (!resilience.autoFailoverOnSafetyStop)
             return undefined;
-        if (!isContentSafetyStopMessage(message.errorMessage))
+        // Fire on safety-stop FPs AND on billing/quota exhaustion: both mean the
+        // current model cannot finish this turn and same-model retry is useless.
+        if (!isContentSafetyStopMessage(message.errorMessage) && !isQuotaExhaustionMessage(message.errorMessage)) {
             return undefined;
+        }
         const current = this.model;
         // v10.0-Ω: do NOT gate on isStickySafetyModel(source).
         // claude-opus-5 emits the same stop_reason=refusal FP; same-model retry is useless.
@@ -3398,7 +3789,9 @@ export class AgentSession {
             if (this._refusedModels.has(`${c.provider}/${c.id}`))
                 return false;
             const next = this._modelRegistry.find(c.provider, c.id);
-            return !!next && this._modelRegistry.hasConfiguredAuth(next);
+            if (!next)
+                return false;
+            return this._modelRegistry.hasConfiguredAuth(next);
         });
         if (!pick)
             return undefined;
@@ -3623,6 +4016,8 @@ export class AgentSession {
             let summaryDetails;
             if (options.summarize && entriesToSummarize.length > 0 && !extensionSummary) {
                 const model = this.model;
+                if (!model)
+                    throw new Error("No model available for summarization");
                 const { apiKey, headers } = await this._getRequiredRequestAuth(model);
                 const branchSummarySettings = this.settingsManager.getBranchSummarySettings();
                 const result = await generateBranchSummary(entriesToSummarize, {
@@ -3664,13 +4059,18 @@ export class AgentSession {
             else if (targetEntry.type === "custom_message") {
                 // Custom message: leaf = parent (null if root), text goes to editor
                 newLeafId = targetEntry.parentId;
-                editorText =
-                    typeof targetEntry.content === "string"
-                        ? targetEntry.content
-                        : targetEntry.content
-                            .filter((c) => c.type === "text")
-                            .map((c) => c.text)
-                            .join("");
+                if (typeof targetEntry.content === "string") {
+                    editorText = targetEntry.content;
+                }
+                else {
+                    editorText = targetEntry.content
+                        .flatMap((item) => {
+                        if (item.type === "text")
+                            return [item.text];
+                        return [];
+                    })
+                        .join("");
+                }
             }
             else {
                 // Non-user message: leaf = selected node
@@ -3741,8 +4141,7 @@ export class AgentSession {
             return content;
         if (Array.isArray(content)) {
             return content
-                .filter((c) => c.type === "text")
-                .map((c) => c.text)
+                .flatMap((item) => (item.type === "text" && typeof item.text === "string" ? [item.text] : []))
                 .join("");
         }
         return "";
@@ -3772,6 +4171,7 @@ export class AgentSession {
                 totalCost += assistantMsg.usage.cost.total;
             }
         }
+        const providerEligibleInputTokens = totalInput + totalCacheRead + totalCacheWrite;
         return {
             sessionFile: this.sessionFile,
             sessionId: this.sessionId,
@@ -3787,6 +4187,14 @@ export class AgentSession {
                 cacheWrite: totalCacheWrite,
                 total: totalInput + totalOutput + totalCacheRead + totalCacheWrite,
             },
+            promptCache: {
+                providerEligibleInputTokens,
+                providerHitRate: providerEligibleInputTokens > 0 ? totalCacheRead / providerEligibleInputTokens : 0,
+                keyChanges: this._promptCacheKeyChanges,
+                boundaryBypasses: this._promptCacheBoundaryBypasses,
+                stablePrefixCharacters: this._promptCacheStablePrefixCharacters,
+                ...(this._promptCacheLastBreakReason ? { lastBreakReason: this._promptCacheLastBreakReason } : {}),
+            },
             cost: totalCost,
             contextUsage: this.getContextUsage(),
         };
@@ -3845,7 +4253,7 @@ export class AgentSession {
             theme,
             cwd: this.sessionManager.getCwd(),
         });
-        return await exportSessionToHtml(this.sessionManager, this.state, {
+        return exportSessionToHtml(this.sessionManager, this.state, {
             outputPath,
             themeName,
             toolRenderer,
@@ -3891,18 +4299,18 @@ export class AgentSession {
      * @returns Text content, or undefined if no assistant message exists
      */
     getLastAssistantText() {
-        const lastAssistant = this.messages
-            .slice()
-            .reverse()
-            .find((m) => {
-            if (m.role !== "assistant")
-                return false;
-            const msg = m;
+        let lastAssistant;
+        for (let index = this.messages.length - 1; index >= 0; index -= 1) {
+            const message = this.messages[index];
+            if (message?.role !== "assistant")
+                continue;
+            const assistant = message;
             // Skip aborted messages with no content
-            if (msg.stopReason === "aborted" && msg.content.length === 0)
-                return false;
-            return true;
-        });
+            if (assistant.stopReason === "aborted" && assistant.content.length === 0)
+                continue;
+            lastAssistant = assistant;
+            break;
+        }
         if (!lastAssistant)
             return undefined;
         let text = "";