@caupulican/pi-adaptative 0.80.85 → 0.80.88

package/dist/core/agent-session.js

@@ -21,12 +21,27 @@ import { stripFrontmatter } from "../utils/frontmatter.js";
 import { resolvePath } from "../utils/paths.js";
 import { sleep } from "../utils/sleep.js";
 import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.js";
+import { evaluateToolGate } from "./autonomy/gates.js";
+import { LaneTracker } from "./autonomy/lane-tracker.js";
+import { appendLaneRecordSnapshot, getLaneRecordSnapshots } from "./autonomy/session-lane-record.js";
+import { composeSubagentSystemPrompt } from "./autonomy/subagent-prompt.js";
 import { executeBashWithOperations } from "./bash-executor.js";
 import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
+import { createFileArtifactStore } from "./context/context-artifacts.js";
+import { runContextAudit } from "./context/context-audit.js";
+import { enforcePromptPolicy } from "./context/context-prompt-enforcement.js";
+import { correlateWithContextGc, planPromptPolicy, } from "./context/context-prompt-policy.js";
+import { defaultMemoryPromptInclusionReport, sanitizeMemoryRetrievalReportForDiagnostics, } from "./context/memory-diagnostics.js";
+import { buildMemoryPromptBlock } from "./context/memory-prompt-block.js";
+import { DEFAULT_LOCAL_MEMORY_EGRESS_POLICY, } from "./context/memory-provider-contract.js";
+import { retrieveMemoryForContext } from "./context/memory-retrieval.js";
+import { createOkfMemoryProvider } from "./context/okf-memory-provider.js";
 import { applyContextGc } from "./context-gc.js";
 import { aggregateDailyUsageFromSessionFiles, aggregateDailyUsageFromSessionRoot, formatDailyUsageBreakdown, getLocalDayWindow, } from "./cost/daily-usage.js";
 import { downgradeReasoning, estimateTurnCostUsd, evaluateCostGuard } from "./cost-guard.js";
 import { DEFAULT_THINKING_LEVEL } from "./defaults.js";
+import { appendWorkerResultSnapshot, getWorkerResultSnapshots } from "./delegation/session-worker-result.js";
+import { runWorker } from "./delegation/worker-runner.js";
 import { exportSessionToHtml } from "./export-html/index.js";
 import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
 import { createCoreDiagnosticsToolDefinitions } from "./extensions/builtin.js";
@@ -34,7 +49,13 @@ import { ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
 import { disposeExtensionEventSubscriptions } from "./extensions/loader.js";
 import { emitSessionShutdownEvent } from "./extensions/runner.js";
 import { GatewayRegistry } from "./gateways/channel-provider.js";
+import { buildGoalContinuationPrompt, } from "./goals/goal-continuation-prompt.js";
+import { buildGoalRuntimeSnapshot, } from "./goals/goal-runtime-snapshot.js";
+import { appendGoalStateSnapshot, getLatestGoalStateSnapshot } from "./goals/session-goal-state.js";
+import { appendLearningAuditSnapshot, getLearningAuditSnapshots, proposalFromReflectionWrite, rollbackPlanForReflectionWrite, } from "./learning/learning-audit.js";
+import { evaluateLearningDecision } from "./learning/learning-gate.js";
 import { decideDemand, ReflectionEngine, } from "./learning/reflection-engine.js";
+import { appendLearningDecisionSnapshot, getLearningDecisionSnapshots } from "./learning/session-learning-decision.js";
 import { isPromotedFrontmatter, SkillCurator } from "./learning/skill-curator.js";
 import { EffectivenessTracker } from "./memory/effectiveness-tracker.js";
 import { MemoryManager } from "./memory/memory-manager.js";
@@ -42,21 +63,32 @@ import { FileStoreProvider } from "./memory/providers/file-store.js";
 import { TranscriptRecallProvider } from "./memory/providers/transcript-recall.js";
 import { compactToolResultDetailsForRetention } from "./message-retention.js";
 import { createCustomMessage } from "./messages.js";
+import { deriveModelCapabilityProfile, filterToolNamesForCapability, } from "./model-capability.js";
 import { resolveCliModel, resolveProfileModelSettings } from "./model-resolver.js";
 import { collectModelRouterConfigDiagnostics } from "./model-router/config-diagnostics.js";
-import { classifyModelRouterIntent } from "./model-router/intent-classifier.js";
+import { classifyModelRouterRoute } from "./model-router/intent-classifier.js";
+import { ROUTE_JUDGE_MAX_OUTPUT_TOKENS, runRouteJudge } from "./model-router/route-judge.js";
 import { bufferModelRouterSessionCustomMessage, bufferModelRouterSessionMessage, createModelRouterSessionBuffer, flushModelRouterSessionBuffer, } from "./model-router/session-buffer.js";
 import { formatModelRouterStatus, getRecentModelRouterDecisions, MODEL_ROUTER_DECISION_CUSTOM_TYPE, } from "./model-router/status.js";
 import { shouldEscalateModelRouterTool } from "./model-router/tool-escalation.js";
+import { FitnessStore } from "./models/fitness-store.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
+import { runModelFitnessProbe } from "./research/model-fitness.js";
+import { runResearch } from "./research/research-runner.js";
+import { appendEvidenceBundleSnapshot, getEvidenceBundleSnapshots, getLatestEvidenceBundleSnapshot, } from "./research/session-evidence-bundle.js";
 import { stripResourceProfileBlocks } from "./resource-profile-blocks.js";
 import { classifyToolTrust, UNTRUSTED_BOUNDARY_SYSTEM_RULE, wrapUntrustedText } from "./security/untrusted-boundary.js";
 import { CURRENT_SESSION_VERSION, getLatestCompactionEntry } from "./session-manager.js";
 import { matchesResourceProfilePattern, } from "./settings-manager.js";
 import { createSyntheticSourceInfo } from "./source-info.js";
 import { buildSystemPrompt } from "./system-prompt.js";
+import { executeToolkitScript } from "./toolkit/script-runner.js";
 import { createLocalBashOperations } from "./tools/bash.js";
+import { createDelegateToolDefinition } from "./tools/delegate.js";
+import { createGoalToolDefinition } from "./tools/goal.js";
 import { createAllToolDefinitions } from "./tools/index.js";
+import { createModelFitnessToolDefinition } from "./tools/model-fitness.js";
+import { createRunToolkitScriptToolDefinition } from "./tools/run-toolkit-script.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
 /**
  * Parse a skill block from message text.
@@ -89,10 +121,46 @@ function formatModelRouterModel(model) {
 function persistModelRouterDecision(sessionManager, decision) {
     sessionManager.appendCustomEntry(MODEL_ROUTER_DECISION_CUSTOM_TYPE, decision);
 }
+/** Read a packed grep/find tool result's `details.artifactId`, if present, without `any`. */
+function extractArtifactId(message) {
+    if (!message || message.role !== "toolResult")
+        return undefined;
+    const details = message.details;
+    if (typeof details !== "object" || details === null)
+        return undefined;
+    const artifactId = details.artifactId;
+    return typeof artifactId === "string" ? artifactId : undefined;
+}
+/**
+ * Text of the most recent user message, or "" if there is none (e.g. goal-continuation
+ * turns with no new user input). An empty query degrades to zero memory-retrieval results
+ * by construction (see memory-provider-contract.ts's score-on-empty-query-tokens rule) --
+ * no special-casing needed here beyond returning "".
+ */
+function latestUserMessageText(messages) {
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (message.role !== "user")
+            continue;
+        if (typeof message.content === "string")
+            return message.content;
+        const parts = [];
+        for (const part of message.content) {
+            if (part.type === "text")
+                parts.push(part.text);
+        }
+        return parts.join("\n");
+    }
+    return "";
+}
+function emptyMemoryRetrievalReport(maxResults) {
+    return { request: { query: "", maxResults }, providerReports: [], results: [], contextItems: [] };
+}
 export class AgentSession {
     agent;
     sessionManager;
     settingsManager;
+    capabilityEnvelope;
     _scopedModels;
     // Event subscription state
     _unsubscribeAgent;
@@ -108,11 +176,42 @@ export class AgentSession {
     _pendingNextTurnMessages = [];
     /** Serializes prompt() submissions made while streaming so queued steering/follow-ups keep user-typed FIFO order. */
     _streamingPromptSubmissionTail = Promise.resolve();
+    /** Pending idle timer that starts bounded goal continuation after the session becomes idle. */
+    _goalAutoContinueTimer;
+    /** Guards bounded idle autosteer so continuation prompts do not recursively trigger themselves. */
+    _isGoalAutoContinuing = false;
+    /** Pending idle timer that starts an autonomous research pass after the session becomes idle. */
+    _researchLaneTimer;
+    /** Single-flight guard: at most one research pass runs at a time per session. */
+    _isResearchLaneRunning = false;
+    /** Why the last idle research-lane evaluation skipped, for /autonomy diagnostics. */
+    _lastResearchLaneSkipReason;
+    /** Live lane registry — the real source for AutonomyStatusSnapshot.activeLaneCount. */
+    _laneTracker = new LaneTracker();
+    /** Session-lifetime abort for in-flight research passes (same pattern as _reflectionAbort). */
+    _researchLaneAbort = new AbortController();
+    /** Single-flight guard: at most one delegated worker runs at a time per session. */
+    _isWorkerDelegationRunning = false;
+    /** Session-lifetime abort for in-flight delegated workers. */
+    _workerDelegationAbort = new AbortController();
+    /**
+     * The last tool set requested via setActiveToolsByName BEFORE model-capability filtering, so
+     * switching from a small-window model back to a large one restores the full requested set.
+     */
+    _requestedActiveToolNames;
     // Compaction/context hygiene state
     _compactionAbortController = undefined;
     _autoCompactionAbortController = undefined;
     _overflowRecoveryAttempted = false;
     _latestContextGcReport = undefined;
+    _toolArtifactStore = undefined;
+    _latestContextAuditReport = undefined;
+    _latestPromptPolicyReport = undefined;
+    _latestPromptPolicyGcCorrelation = undefined;
+    _latestPromptEnforcementReport = undefined;
+    _memoryOkfProvider = undefined;
+    _latestMemoryRetrievalReport = undefined;
+    _latestMemoryPromptInclusionReport = undefined;
     // Branch summarization state
     _branchSummaryAbortController = undefined;
     // Retry state
@@ -151,9 +250,12 @@ export class AgentSession {
     _costGuardDowngraded = false;
     /** Active model-router intent for the current transient routed turn, if any. */
     _activeModelRouterIntent;
+    _activeModelRouterRoute;
     _modelRouterSessionBuffer;
     _modelRouterEscalationRequested = false;
+    _isModelRouterRetry = false;
     _lastModelRouterDecision;
+    _lastAutonomyGateOutcome;
     _lastModelRouterSkipReason;
     _lastModelRouterIntent;
     /** Lazily-built skill curator (#32) over `<agentDir>/skills`. */
@@ -295,7 +397,7 @@ export class AgentSession {
             const authoritativeMessages = this.agent.state.messages.length > 0 ? this.agent.state.messages : transformed;
             let currentMessages = authoritativeMessages;
             try {
-                const settings = this.settingsManager.getCompactionSettings();
+                const settings = this._getAdaptedCompactionSettings();
                 const contextWindow = this.model?.contextWindow ?? 0;
                 if (settings.enabled && contextWindow > 0 && !this.isCompacting) {
                     const contextTokens = this._estimateCurrentContextTokens(authoritativeMessages);
@@ -316,7 +418,18 @@ export class AgentSession {
             if (this._extensionRunner.hasHandlers("context")) {
                 finalMessages = await this._extensionRunner.emitContext(currentMessages);
             }
-            const gcMessages = this._applyContextGc(finalMessages, true).messages;
+            const auditReport = this._runContextAudit(finalMessages);
+            const shadowReport = this._runPromptPolicyPlanning(auditReport);
+            const memoryReport = await this._runMemoryRetrieval(finalMessages);
+            const gcResult = this._applyContextGc(finalMessages, true);
+            this._correlatePromptPolicyWithContextGc(gcResult.report);
+            const enforcementResult = this._runPromptEnforcement(gcResult.messages, shadowReport);
+            // Appended LAST, after gc and enforcement, so the bounded evidence block is
+            // never packed/stubbed/reshaped by either pass and always reflects this turn's
+            // fresh retrieval. Because nothing downstream trims it, memory-prompt-block.ts's
+            // character caps are the only budget protection for this block -- load-bearing,
+            // not merely defensive.
+            const gcMessages = this._maybeAppendMemoryEvidenceBlock(enforcementResult.messages, memoryReport);
             this._applyCostGuard(gcMessages);
             return gcMessages;
         };
@@ -421,15 +534,366 @@ export class AgentSession {
     _contextGcStorageDir() {
         return join(this._agentDir, "context-gc", this.sessionManager.getSessionId());
     }
+    _toolArtifactsDir() {
+        return join(this._agentDir, "context-artifacts", this.sessionManager.getSessionId());
+    }
+    /**
+     * Session-scoped, filesystem-backed artifact store for first-capture-then-bound tool
+     * output (grep/find only, for now -- see tool-output-artifacts.md). Lazily created and
+     * cached so every tool construction in this session shares one store instance.
+     *
+     * `packToolOutput()` registers a reference (the packing tool call's id) at pack time
+     * and fails closed, so packed artifacts are never prematurely collected.
+     * `_releaseGcPackedArtifactReferences()` (called from `_applyContextGc()`) releases
+     * that reference once context-gc packs the result out of live context, and
+     * opportunistically reclaims now-unreferenced artifacts via `cleanup()`.
+     * Remaining carry-forward gap: cleanup() now also runs at dispose(), but only reclaims
+     * already-released (zero-reference) artifacts. A session that ends before context-gc
+     * ever evicts a result never releases that reference, so its artifact stays on disk by
+     * design (resolvable on resume). Reclaiming those requires an explicit cross-session
+     * expiry/liveness policy, not just a sweep.
+     */
+    _getToolArtifactStore() {
+        this._toolArtifactStore ??= createFileArtifactStore({ baseDir: this._toolArtifactsDir() });
+        return this._toolArtifactStore;
+    }
+    /**
+     * Fixed path for this slice's local Pi OKF memory documents, shared across sessions
+     * under this agentDir (not session-scoped, unlike tool-artifacts/context-gc, since OKF
+     * memory represents durable cross-session knowledge, not a per-session capture). Not
+     * yet user-configurable -- see the memory-retrieval settings doc comment.
+     */
+    _memoryOkfDir() {
+        return join(this._agentDir, "okf-memory");
+    }
+    /**
+     * Session-scoped, read-only local OKF memory provider. Lazily created ONLY when memory
+     * retrieval is enabled (see `_runMemoryRetrieval`) -- never force-created, so a session
+     * with the setting off never touches `_memoryOkfDir()` at all (no directory access, no
+     * creation; `createOkfMemoryProvider` itself never writes/mkdirs either way).
+     */
+    _getMemoryOkfProvider() {
+        this._memoryOkfProvider ??= createOkfMemoryProvider({ rootDir: this._memoryOkfDir() });
+        return this._memoryOkfProvider;
+    }
+    /**
+     * One pass over the current branch, mapping each toolResult's toolCallId to its
+     * persisted session-entry id. Rebuilt every audit pass (O(branch) per turn), so this is
+     * O(n^2) over a long session. Fine at current scale; after the artifact-read fix this is
+     * the next per-turn audit cost to optimize if it ever matters (e.g. cache/incrementally
+     * update instead of a full rebuild).
+     */
+    _buildSessionEntryIdLookup() {
+        const map = new Map();
+        for (const entry of this.sessionManager.getBranch()) {
+            if (entry.type === "message" && entry.message.role === "toolResult") {
+                map.set(entry.message.toolCallId, entry.id);
+            }
+        }
+        return (toolCallId) => map.get(toolCallId);
+    }
+    /**
+     * Phase 1 observe-only audit pass (see context/context-audit.ts): converts live
+     * toolResult messages into ContextItems and runs the existing retention/hard-constraint
+     * evaluators over them, storing the latest deterministic report for tests/debugging.
+     * Read-only with respect to messages, the transcript, and artifact references -- uses
+     * `_toolArtifactStore` (the field), not `_getToolArtifactStore()` (the getter), so a
+     * session that never packed anything doesn't force-create a store/dir just to audit.
+     * Never throws into a live turn: any failure degrades to an empty report.
+     */
+    _runContextAudit(messages) {
+        try {
+            const report = runContextAudit(messages, {
+                turnIndex: this._turnIndex,
+                artifactStore: this._toolArtifactStore,
+                sessionEntryIdForToolCallId: this._buildSessionEntryIdLookup(),
+            });
+            this._latestContextAuditReport = report;
+            return report;
+        }
+        catch {
+            const report = { turnIndex: this._turnIndex, items: [] };
+            this._latestContextAuditReport = report;
+            return report;
+        }
+    }
+    /**
+     * Read-only inspection of the context audit. With `messages`, recomputes fresh against
+     * the given array (still no mutation of messages/transcript/artifact refs); without,
+     * returns the last report computed during a real transform pass.
+     */
+    getContextAuditReport(messages) {
+        if (messages)
+            return this._runContextAudit(messages);
+        return this._latestContextAuditReport ?? { turnIndex: this._turnIndex, items: [] };
+    }
+    /**
+     * Observe-first shadow/planning pass (see context/context-prompt-policy.ts): re-shapes
+     * the audit report into a per-item policy plan whose `appliedAction` is always
+     * "keep_raw" -- this never enforces anything, it only records what the policy engine
+     * would say. Never throws into a live turn: any failure degrades to an empty report.
+     */
+    _runPromptPolicyPlanning(auditReport) {
+        try {
+            const report = planPromptPolicy(auditReport);
+            this._latestPromptPolicyReport = report;
+            return report;
+        }
+        catch {
+            const report = { turnIndex: this._turnIndex, items: [] };
+            this._latestPromptPolicyReport = report;
+            return report;
+        }
+    }
+    /**
+     * Read-only inspection of the shadow policy plan. With `messages`, recomputes fresh
+     * (audit + plan) against the given array; without, returns the last plan computed
+     * during a real transform pass. Never mutates messages/transcript/artifact refs.
+     */
+    getPromptPolicyReport(messages) {
+        if (messages)
+            return this._runPromptPolicyPlanning(this._runContextAudit(messages));
+        return this._latestPromptPolicyReport ?? { turnIndex: this._turnIndex, items: [] };
+    }
+    /**
+     * Report-only correlation between the shadow plan just computed this turn and what the
+     * legacy context-gc pass actually packed. Runs after `_applyContextGc()` has already
+     * produced its report; never influences context-gc itself. Never throws into a live
+     * turn: any failure degrades to an empty correlation.
+     */
+    _correlatePromptPolicyWithContextGc(gcReport) {
+        const shadowReport = this._latestPromptPolicyReport ?? { turnIndex: this._turnIndex, items: [] };
+        try {
+            this._latestPromptPolicyGcCorrelation = correlateWithContextGc(shadowReport, gcReport);
+        }
+        catch {
+            this._latestPromptPolicyGcCorrelation = { turnIndex: this._turnIndex, entries: [] };
+        }
+    }
+    /** Read-only inspection of the latest shadow-plan/legacy-gc correlation, for tests/debugging. */
+    getPromptPolicyGcCorrelation() {
+        return this._latestPromptPolicyGcCorrelation ?? { turnIndex: this._turnIndex, entries: [] };
+    }
+    /**
+     * First enforcement pilot (see context/context-prompt-enforcement.ts): opt-in,
+     * default-disabled stub-in-place of stale artifact-backed tool_output results in the
+     * provider-visible message array only. Runs on `messages` AFTER context-gc has already
+     * produced its own result, so legacy context-gc's own packing/reporting is completely
+     * unaffected by this pass -- it only ever acts on messages gc left untouched this turn.
+     * Never throws into a live turn: any failure degrades to returning `messages` unchanged.
+     */
+    _runPromptEnforcement(messages, shadowReport) {
+        try {
+            const persistedSettings = this.settingsManager.getContextPromptEnforcementSettings();
+            const settings = {
+                ...persistedSettings,
+                // Runtime fact, never assumed: artifact_retrieve is a companion affordance
+                // (auto-activated alongside grep/find), not a default/global tool, so active
+                // tools can differ turn to turn -- see context-prompt-enforcement.ts's doc
+                // comment on why this is checked separately from hasAvailableRetrievalPath.
+                retrievalToolAvailable: this.getActiveToolNames().includes("artifact_retrieve"),
+            };
+            const result = enforcePromptPolicy(messages, shadowReport, settings);
+            this._latestPromptEnforcementReport = result.report;
+            return result;
+        }
+        catch {
+            const report = { turnIndex: this._turnIndex, items: [] };
+            this._latestPromptEnforcementReport = report;
+            return { messages, report };
+        }
+    }
+    /** Read-only inspection of the latest prompt-enforcement report, for tests/debugging. */
+    getPromptEnforcementReport() {
+        return this._latestPromptEnforcementReport ?? { turnIndex: this._turnIndex, items: [] };
+    }
+    /**
+     * Observe-only local memory retrieval (see context/memory-retrieval.ts and
+     * context/okf-memory-provider.ts): default disabled, opt-in setting. When disabled,
+     * never constructs the OKF provider (no directory access under `_memoryOkfDir()` at
+     * all) and returns an empty report -- fully fail-closed. When enabled, queries the
+     * local, read-only OKF provider with the latest user message text (empty if there is
+     * none, e.g. a goal-continuation turn -- degrades to zero results by construction, see
+     * `latestUserMessageText`'s doc comment) under `DEFAULT_LOCAL_MEMORY_EGRESS_POLICY`.
+     * Retrieved items are only ever stored in the report; nothing here touches `messages`,
+     * the transcript, or the provider-visible prompt. Never throws into a live turn: any
+     * failure (including a provider search error) degrades to an empty report.
+     */
+    async _runMemoryRetrieval(messages) {
+        try {
+            const settings = this.settingsManager.getMemoryRetrievalSettings();
+            if (!settings.enabled) {
+                const report = emptyMemoryRetrievalReport(settings.maxResults);
+                this._latestMemoryRetrievalReport = report;
+                return report;
+            }
+            const report = await retrieveMemoryForContext([this._getMemoryOkfProvider()], { query: latestUserMessageText(messages), maxResults: settings.maxResults }, {
+                createdAtTurn: this._turnIndex,
+                maxResults: settings.maxResults,
+                defaultLocalPolicy: DEFAULT_LOCAL_MEMORY_EGRESS_POLICY,
+            });
+            this._latestMemoryRetrievalReport = report;
+            return report;
+        }
+        catch {
+            const report = emptyMemoryRetrievalReport(0);
+            this._latestMemoryRetrievalReport = report;
+            return report;
+        }
+    }
+    /** Read-only inspection of the latest memory-retrieval report, for tests/debugging. */
+    getMemoryRetrievalReport() {
+        return this._latestMemoryRetrievalReport ?? emptyMemoryRetrievalReport(0);
+    }
+    /**
+     * Bounded prompt-surfacing pilot for local memory evidence (see
+     * context/memory-prompt-block.ts): opt-in, default disabled, and gated on TWO settings
+     * (`enabled` AND `includeInPrompt`) plus a non-empty `report.contextItems` -- the first
+     * two are belt-and-suspenders on top of the fact that `_runMemoryRetrieval` already
+     * leaves `contextItems` empty whenever `enabled` is false, regardless of
+     * `includeInPrompt`. Reuses the `report` this pass's `_runMemoryRetrieval` call already
+     * computed -- never re-queries the provider here.
+     *
+     * Appends exactly one ephemeral `custom`/"memory_evidence" message wrapped by
+     * `wrapUntrustedText` (the same nonce-fenced boundary + always-on system-prompt rule
+     * used for other untrusted content) to the END of `messages`. This is purely additive
+     * (never mutates an existing message) and purely transient: `messages` here is the
+     * array about to be sent to the provider, not `this.agent.state.messages` or anything
+     * persisted via `sessionManager` -- so the injected message can never reach the
+     * transcript, regardless of how many times this pass runs.
+     *
+     * Also records a `MemoryPromptInclusionReport` (context/memory-diagnostics.ts) at each
+     * branch below, for context_audit's diagnostic surface only -- this is pure bookkeeping
+     * alongside the existing branches, not a new branch/condition: the messages returned
+     * are unchanged by this recording.
+     */
+    _maybeAppendMemoryEvidenceBlock(messages, report) {
+        try {
+            const settings = this.settingsManager.getMemoryRetrievalSettings();
+            const base = {
+                enabled: settings.enabled,
+                includeInPrompt: settings.includeInPrompt,
+                selectedItemCount: report.contextItems.length,
+            };
+            if (!settings.enabled) {
+                this._latestMemoryPromptInclusionReport = {
+                    ...base,
+                    status: "disabled",
+                    includedCount: 0,
+                    omittedCount: 0,
+                    blockChars: 0,
+                };
+                return messages;
+            }
+            if (!settings.includeInPrompt) {
+                this._latestMemoryPromptInclusionReport = {
+                    ...base,
+                    status: "include_disabled",
+                    includedCount: 0,
+                    omittedCount: 0,
+                    blockChars: 0,
+                };
+                return messages;
+            }
+            if (report.contextItems.length === 0) {
+                this._latestMemoryPromptInclusionReport = {
+                    ...base,
+                    status: "no_results",
+                    includedCount: 0,
+                    omittedCount: 0,
+                    blockChars: 0,
+                };
+                return messages;
+            }
+            const block = buildMemoryPromptBlock(report.contextItems);
+            if (!block.text) {
+                this._latestMemoryPromptInclusionReport = {
+                    ...base,
+                    status: "empty_block",
+                    includedCount: block.includedCount,
+                    omittedCount: block.omittedCount,
+                    blockChars: 0,
+                };
+                return messages;
+            }
+            const wrapped = wrapUntrustedText(block.text, "memory:pi-okf");
+            const evidenceMessage = {
+                role: "custom",
+                customType: "memory_evidence",
+                content: [{ type: "text", text: wrapped }],
+                display: false,
+                timestamp: Date.now(),
+            };
+            this._latestMemoryPromptInclusionReport = {
+                ...base,
+                status: "included",
+                includedCount: block.includedCount,
+                omittedCount: block.omittedCount,
+                blockChars: wrapped.length,
+                sourceLabel: "memory:pi-okf",
+            };
+            return [...messages, evidenceMessage];
+        }
+        catch {
+            // `base` may not exist yet if the throw happened before it was computed (e.g.
+            // settings access or `report.contextItems` itself threw), so this branch cannot
+            // rely on it -- fall back to safe, fixed defaults rather than risk referencing
+            // a partially-evaluated value.
+            this._latestMemoryPromptInclusionReport = {
+                enabled: false,
+                includeInPrompt: false,
+                selectedItemCount: 0,
+                status: "failed",
+                includedCount: 0,
+                omittedCount: 0,
+                blockChars: 0,
+            };
+            return messages;
+        }
+    }
+    /** Read-only inspection of the latest memory-prompt-inclusion decision, for tests/debugging and context_audit. */
+    getMemoryPromptInclusionReport() {
+        return this._latestMemoryPromptInclusionReport ?? defaultMemoryPromptInclusionReport();
+    }
+    /**
+     * Combines the already-stored, no-arg latest reports (never re-queries the provider or
+     * touches the OKF directory) into the safe, allow-list-projected shape context_audit
+     * exposes. See context/memory-diagnostics.ts for why this projection is allow-list
+     * based rather than a spread-then-delete of the raw report.
+     */
+    _getMemoryAuditDiagnostics() {
+        const settings = this.settingsManager.getMemoryRetrievalSettings();
+        return {
+            retrieval: sanitizeMemoryRetrievalReportForDiagnostics(this.getMemoryRetrievalReport(), settings),
+            promptInclusion: this.getMemoryPromptInclusionReport(),
+        };
+    }
     _applyContextGc(messages, writePayloads) {
         try {
+            const settings = this.settingsManager.getContextGcSettings();
+            // Merge the ACTIVE memory providers' own page markers (e.g. transcript-recall's
+            // "<memory_context") into the semantic-memory marker list. The settings default is
+            // provider-agnostic and non-empty, so without this merge the recall pages the bundled
+            // default provider actually emits are never recognized as semantic-memory pages and
+            // accumulate raw for the life of the session — the exact growth Bug #7 GC exists to stop.
+            const providerMarkers = this._memoryManager.getContextMarkers();
             const result = applyContextGc(messages, {
-                ...this.settingsManager.getContextGcSettings(),
+                ...settings,
+                semanticMemory: {
+                    ...settings.semanticMemory,
+                    markers: [...new Set([...settings.semanticMemory.markers, ...providerMarkers])],
+                },
                 cwd: this._cwd,
                 storageDir: this._contextGcStorageDir(),
                 writePayloads,
             });
             this._latestContextGcReport = result.report;
+            // Only release/reclaim on the real per-turn pass (writePayloads=true), never on
+            // the read-only status-report path (getContextGcReport with writePayloads=false),
+            // so merely inspecting the report can't have side effects.
+            if (writePayloads && result.report.packedCount > 0) {
+                this._releaseGcPackedArtifactReferences(messages, result.report);
+            }
             return result;
         }
         catch {
@@ -445,6 +909,39 @@ export class AgentSession {
             return { messages, report };
         }
     }
+    /**
+     * Reference-release + cleanup lifecycle: once context-gc has packed a grep/find tool
+     * result out of the live prompt (the message is no longer current/active working
+     * context -- see contracts-and-retention.md's "ephemeral"/"expired" retention
+     * classes), release the pack-time reference `packToolOutput()` registered for it, and
+     * opportunistically reclaim now-unreferenced artifacts. This is the other half of the
+     * D2b-1 gate: artifacts were being registered but never released, so they accumulated
+     * for the life of the session.
+     *
+     * `record.toolCallId` (from context-gc's packed record) is exactly the holder id
+     * `packToolOutput()` used when it called `addReference()` -- both trace back to the
+     * same tool call's id -- so no separate bookkeeping is needed to find it.
+     */
+    _releaseGcPackedArtifactReferences(messages, report) {
+        const store = this._toolArtifactStore;
+        if (!store)
+            return; // no store was ever constructed, so nothing could have been packed to one
+        let releasedAny = false;
+        for (const record of report.records) {
+            if (record.toolName !== "grep" && record.toolName !== "find")
+                continue;
+            const artifactId = extractArtifactId(messages[record.messageIndex]);
+            if (!artifactId)
+                continue;
+            if (store.removeReference(artifactId, record.toolCallId))
+                releasedAny = true;
+        }
+        // Cleanup only runs immediately after a release actually happened in this pass, so
+        // a long session doesn't re-scan the artifact directory on every turn once nothing
+        // new became eligible for release.
+        if (releasedAny)
+            store.cleanup();
+    }
     getContextGcReport(messages) {
         if (messages)
             return this._applyContextGc(messages, false).report;
@@ -476,8 +973,8 @@ export class AgentSession {
     }
     _installAgentToolHooks() {
         this.agent.beforeToolCall = async ({ toolCall, args }) => {
-            if (this._activeModelRouterIntent &&
-                shouldEscalateModelRouterTool({ intent: this._activeModelRouterIntent, toolName: toolCall.name, args })) {
+            if (this._activeModelRouterRoute &&
+                shouldEscalateModelRouterTool({ tier: this._activeModelRouterRoute.tier, toolName: toolCall.name, args })) {
                 this._modelRouterEscalationRequested = true;
                 this.agent.abort();
                 return {
@@ -485,6 +982,22 @@ export class AgentSession {
                     reason: "Model router escalation required: a cheap research turn attempted a mutating tool. Retry the turn on the configured expensive model.",
                 };
             }
+            // Autonomy tool gating
+            const gateResult = evaluateToolGate({
+                toolName: toolCall.name,
+                args,
+                cwd: this._cwd,
+                envelope: this.capabilityEnvelope,
+            });
+            if (this.capabilityEnvelope) {
+                this._lastAutonomyGateOutcome = gateResult;
+            }
+            if (gateResult.outcome === "block" || gateResult.outcome === "ask-user") {
+                return {
+                    block: true,
+                    reason: `Tool execution blocked by autonomy gate [${gateResult.gate}]: ${gateResult.message} (${gateResult.reasonCode})`,
+                };
+            }
             const runner = this._extensionRunner;
             if (!runner.hasHandlers("tool_call")) {
                 return undefined;
@@ -584,8 +1097,13 @@ export class AgentSession {
         }
         // Emit to extensions first
         await this._emitExtensionEvent(event);
+        const suppressRetryPromptEvent = this._isModelRouterRetry &&
+            (event.type === "message_start" || event.type === "message_end") &&
+            (event.message.role === "user" || event.message.role === "custom");
         // Notify all listeners
-        this._emit(event.type === "agent_end" ? { ...event, willRetry: this._willRetryAfterAgentEnd(event) } : event);
+        if (!suppressRetryPromptEvent) {
+            this._emit(event.type === "agent_end" ? { ...event, willRetry: this._willRetryAfterAgentEnd(event) } : event);
+        }
         // Handle session/context retention. Tool result details are UI/log metadata,
         // not provider-visible content, and large graph/search payloads can otherwise
         // accumulate until the interactive Node process hits the V8 heap limit.
@@ -829,6 +1347,8 @@ export class AgentSession {
      */
     dispose() {
         try {
+            this._clearGoalAutoContinueTimer();
+            this._clearResearchLaneTimer();
             this.abortRetry();
             this.abortCompaction();
             this.abortBranchSummary();
@@ -840,6 +1360,10 @@ export class AgentSession {
             // write memory/skills against this now-disposed session.
             this._disposed = true;
             this._reflectionAbort.abort();
+            // Abort any in-flight research pass or delegated worker for the same reason: a disposed
+            // session must not keep spending tokens or persist evidence against dead state.
+            this._researchLaneAbort.abort();
+            this._workerDelegationAbort.abort();
             // Bug #20: clear the hooks this session installed on the shared agent so their closures stop
             // pinning this (deactivated) session — and all its history/maps — in memory if the agent
             // instance outlives the session.
@@ -856,6 +1380,19 @@ export class AgentSession {
         // true session-end hook (P3); file-store shutdown is a no-op.
         void this._memoryManager.shutdownAll().catch(() => { });
         cleanupSessionResources(this.sessionId);
+        // Best-effort final sweep for any grep/find artifact already released (reference
+        // count zero) but not yet reclaimed -- e.g. a release whose cleanup() call failed
+        // transiently. This is conservative: it never releases a still-referenced
+        // artifact, so a session that ends before context-gc ever evicts a result (too
+        // short to cross preserveRecentMessages) correctly leaves that artifact in place,
+        // resolvable if the same session is resumed later. It does not sweep OTHER
+        // sessions' artifact directories.
+        try {
+            this._toolArtifactStore?.cleanup();
+        }
+        catch {
+            // Best-effort; dispose must succeed regardless.
+        }
     }
     // =========================================================================
     // Read-only State Access
@@ -911,21 +1448,47 @@ export class AgentSession {
      * Only tools in the registry can be enabled. Unknown tool names are ignored.
      * Also rebuilds the system prompt to reflect the new tool set.
      * Changes take effect on the next agent turn.
+     *
+     * artifact_retrieve is auto-activated as a companion whenever grep or find ends up
+     * in the resulting active set and artifact_retrieve is registered (i.e. not excluded/
+     * blocked/outside an allowlist -- the registry itself is built with that same filter,
+     * so registry presence already tracks "allowed"). This is enforced here, not just in
+     * the settings/profile refresh flow, because this method is a public, extension-
+     * exposed activation path (`setActiveTools`) on its own: without this, grep/find could
+     * end up active while still being handed an artifact store (gated on "allowed" in
+     * `_buildRuntime`) with no active tool able to resolve the resulting
+     * "Full output: artifact tool-output:<id>" handle.
      */
     setActiveToolsByName(toolNames) {
+        // Model capability: small-window models get a reduced tool surface derived from the model's
+        // own metadata. The unfiltered request is remembered so a later switch to a larger model
+        // restores it (the filter is re-applied on every model change).
+        this._requestedActiveToolNames = [...toolNames];
+        const capabilityFiltered = filterToolNamesForCapability(toolNames, this.getModelCapabilityProfile());
         const tools = [];
         const validToolNames = [];
-        for (const name of toolNames) {
+        const seen = new Set();
+        const addIfRegistered = (name) => {
+            if (seen.has(name))
+                return;
             const tool = this._toolRegistry.get(name);
-            if (tool) {
-                tools.push(tool);
-                validToolNames.push(name);
-            }
+            if (!tool)
+                return;
+            seen.add(name);
+            tools.push(tool);
+            validToolNames.push(name);
+        };
+        for (const name of capabilityFiltered) {
+            addIfRegistered(name);
+        }
+        if (validToolNames.includes("grep") || validToolNames.includes("find")) {
+            addIfRegistered("artifact_retrieve");
         }
         this.agent.state.tools = tools;
         // Rebuild base system prompt with new tool set
         this._baseSystemPrompt = this._rebuildSystemPrompt(validToolNames);
         this.agent.state.systemPrompt = this._baseSystemPrompt;
+        this._checkContextWindowUsageWarning();
     }
     /** Whether compaction or branch summarization is currently running */
     get isCompacting() {
@@ -1127,35 +1690,166 @@ export class AgentSession {
             await this._drainQueuedExtensionCommands();
         }
     }
-    _resolveModelRouterModelForIntent(intent) {
+    _isModelAvailableAndAuthed(pattern) {
+        const resolved = resolveCliModel({ cliModel: pattern, modelRegistry: this._modelRegistry });
+        if (!resolved.model)
+            return false;
+        return this._modelRegistry.hasConfiguredAuth(resolved.model);
+    }
+    _resolveModelRouterTurnRoute(prompt) {
         const settings = this.settingsManager.getModelRouterSettings();
-        const modelLabel = intent === "research" ? "cheap model" : "expensive model";
         if (!settings.enabled) {
             this._lastModelRouterSkipReason = "disabled";
             return undefined;
         }
-        const modelPattern = intent === "research" ? settings.cheapModel : settings.expensiveModel;
+        const decision = classifyModelRouterRoute(prompt);
+        this._lastModelRouterIntent = decision.tier === "cheap" ? "research" : "modify";
+        // Learning tier must not be selected for normal user prompts
+        if (decision.tier === "learning") {
+            this._lastModelRouterSkipReason = "learning tier not supported for user prompts";
+            return undefined;
+        }
+        const modelPattern = settings[decision.tier === "cheap" ? "cheapModel" : decision.tier === "medium" ? "mediumModel" : "expensiveModel"];
+        const label = decision.tier === "cheap" ? "cheap model" : decision.tier === "medium" ? "medium model" : "expensive model";
+        if (decision.tier === "medium" && (!modelPattern || !this._isModelAvailableAndAuthed(modelPattern))) {
+            const expensivePattern = settings.expensiveModel;
+            if (expensivePattern && this._isModelAvailableAndAuthed(expensivePattern)) {
+                const resolvedExpensive = resolveCliModel({
+                    cliModel: expensivePattern,
+                    modelRegistry: this._modelRegistry,
+                });
+                if (resolvedExpensive.model) {
+                    decision.fallbackFrom = "medium";
+                    decision.tier = "expensive";
+                    decision.reasonCode = "medium_unavailable_fallback_expensive";
+                    decision.reasons = [...decision.reasons, "Medium model is unavailable, falling back to expensive model"];
+                    decision.model = formatModelRouterModel(resolvedExpensive.model);
+                    this._lastModelRouterSkipReason = undefined;
+                    return { decision, model: resolvedExpensive.model };
+                }
+            }
+            this._lastModelRouterSkipReason = "medium model and expensive fallback are unavailable";
+            return undefined;
+        }
         if (!modelPattern) {
-            this._lastModelRouterSkipReason = `${modelLabel} unset`;
+            this._lastModelRouterSkipReason = `${label} unset`;
             return undefined;
         }
         const resolved = resolveCliModel({ cliModel: modelPattern, modelRegistry: this._modelRegistry });
         if (!resolved.model) {
-            this._lastModelRouterSkipReason = `${modelLabel} unresolved: ${modelPattern}`;
+            this._lastModelRouterSkipReason = `${label} unresolved: ${modelPattern}`;
             return undefined;
         }
         const resolvedName = formatModelRouterModel(resolved.model);
         if (!this._modelRegistry.hasConfiguredAuth(resolved.model)) {
-            this._lastModelRouterSkipReason = `${modelLabel} missing auth: ${resolvedName}`;
+            this._lastModelRouterSkipReason = `${label} missing auth: ${resolvedName}`;
             return undefined;
         }
         this._lastModelRouterSkipReason = undefined;
+        decision.model = resolvedName;
+        return { decision, model: resolved.model };
+    }
+    _resolveModelRouterModelForIntent(intent) {
+        const settings = this.settingsManager.getModelRouterSettings();
+        const modelPattern = intent === "research" ? settings.cheapModel : settings.expensiveModel;
+        if (!modelPattern)
+            return undefined;
+        const resolved = resolveCliModel({ cliModel: modelPattern, modelRegistry: this._modelRegistry });
+        if (!resolved.model)
+            return undefined;
+        if (!this._modelRegistry.hasConfiguredAuth(resolved.model))
+            return undefined;
+        return resolved.model;
+    }
+    _resolveConfiguredTierModel(tier) {
+        const settings = this.settingsManager.getModelRouterSettings();
+        const pattern = tier === "cheap" ? settings.cheapModel : tier === "medium" ? settings.mediumModel : settings.expensiveModel;
+        if (!pattern)
+            return undefined;
+        const resolved = resolveCliModel({ cliModel: pattern, modelRegistry: this._modelRegistry });
+        if (!resolved.model)
+            return undefined;
+        if (!this._modelRegistry.hasConfiguredAuth(resolved.model))
+            return undefined;
         return resolved.model;
     }
+    /**
+     * Router resolution with the routing judge (auto-on with the router): the regex classifier's
+     * decision is the baseline; when a judge model resolves (judgeModel, else mediumModel), one
+     * bounded, tool-less completion may move the tier between cheap/medium/expensive — never to
+     * learning. Core rule encoded in the judge prompt: planning is never cheap unless genuinely
+     * trivial. Every fallback stays visible in the decision reasons, and judge spend reports
+     * through spawned-usage accounting.
+     */
+    async _resolveModelRouterTurnRouteJudged(prompt, options) {
+        const baseline = this._resolveModelRouterTurnRoute(prompt);
+        if (!baseline)
+            return undefined;
+        if (options?.skipJudge)
+            return baseline;
+        const settings = this.settingsManager.getModelRouterSettings();
+        if (!settings.judgeEnabled)
+            return baseline;
+        const judgePattern = settings.judgeModel ?? settings.mediumModel;
+        if (!judgePattern)
+            return baseline;
+        const judgeModel = this._resolveLaneModel(judgePattern);
+        if (!judgeModel)
+            return baseline;
+        let spentUsage;
+        const judged = await runRouteJudge({
+            prompt,
+            baseline: baseline.decision,
+            signal: this._reflectionAbort.signal,
+            complete: async ({ systemPrompt, userPrompt, signal }) => {
+                const completion = await this.runIsolatedCompletion({
+                    systemPrompt,
+                    messages: [{ role: "user", content: [{ type: "text", text: userPrompt }], timestamp: Date.now() }],
+                    model: judgeModel,
+                    thinkingLevel: "off",
+                    maxTokens: ROUTE_JUDGE_MAX_OUTPUT_TOKENS,
+                    signal,
+                    // The judge system prompt is static — the provider can cache the prefix.
+                    cacheRetention: "short",
+                });
+                spentUsage = completion.usage;
+                return {
+                    text: completion.text,
+                    costUsd: completion.usage.cost.total,
+                    stopReason: String(completion.stopReason),
+                };
+            },
+        });
+        if (spentUsage && (spentUsage.cost.total > 0 || spentUsage.totalTokens > 0)) {
+            this.addSpawnedUsage(spentUsage, { label: "router-judge" });
+        }
+        if (!judged.verdict || judged.decision.tier === baseline.decision.tier) {
+            // Same tier (or judge fell back): keep the baseline model, carry the annotated decision.
+            return { decision: judged.decision, model: baseline.model };
+        }
+        const judgedTier = judged.decision.tier;
+        if (judgedTier !== "cheap" && judgedTier !== "medium" && judgedTier !== "expensive") {
+            return { decision: baseline.decision, model: baseline.model };
+        }
+        const judgedModel = this._resolveConfiguredTierModel(judgedTier);
+        if (!judgedModel) {
+            return {
+                decision: {
+                    ...baseline.decision,
+                    reasons: [
+                        ...baseline.decision.reasons,
+                        `Route judge chose ${judgedTier} but no model resolves for that tier; baseline kept`,
+                    ],
+                },
+                model: baseline.model,
+            };
+        }
+        return { decision: { ...judged.decision, model: formatModelRouterModel(judgedModel) }, model: judgedModel };
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: test seam
     _resolveModelRouterTurnModel(prompt) {
-        const intent = classifyModelRouterIntent(prompt);
-        this._lastModelRouterIntent = intent;
-        return this._resolveModelRouterModelForIntent(intent);
+        const resolved = this._resolveModelRouterTurnRoute(prompt);
+        return resolved?.model;
     }
     getModelRouterStatus(formatLabel) {
         const recentDecisions = getRecentModelRouterDecisions(this.sessionManager.getEntries());
@@ -1174,7 +1868,7 @@ export class AgentSession {
         }
         return lines.join("\n");
     }
-    async _runAgentPromptWithModelRouter(messages, routedModel, routedIntent, persistDecision = true) {
+    async _runAgentPromptWithModelRouter(messages, routedModel, routeDecision, persistDecision = true) {
         if (!routedModel) {
             await this._runAgentPrompt(messages);
             return;
@@ -1182,23 +1876,30 @@ export class AgentSession {
         const previousModel = this.agent.state.model;
         const previousThinkingLevel = this.agent.state.thinkingLevel;
         const previousActiveModelRouterIntent = this._activeModelRouterIntent;
+        const previousActiveModelRouterRoute = this._activeModelRouterRoute;
         const previousModelRouterSessionBuffer = this._modelRouterSessionBuffer;
         const previousModelRouterEscalationRequested = this._modelRouterEscalationRequested;
-        const bufferRoutedTurn = routedIntent === "research";
+        const bufferRoutedTurn = routeDecision?.tier === "cheap";
         const originalHistoryLength = this.agent.state.messages.length;
         let retryModel;
-        let completedDecision = routedIntent
+        let completedDecision = routeDecision
             ? {
-                intent: routedIntent,
+                route: routeDecision,
                 routedModel: formatModelRouterModel(routedModel),
                 outcome: "routed",
+                intent: routeDecision.tier === "cheap" ? "research" : "modify",
             }
             : undefined;
         let thrownError;
-        if (routedIntent) {
+        if (routeDecision) {
             this._lastModelRouterDecision = completedDecision;
         }
-        this._activeModelRouterIntent = routedIntent;
+        this._activeModelRouterIntent = routeDecision
+            ? routeDecision.tier === "cheap"
+                ? "research"
+                : "modify"
+            : undefined;
+        this._activeModelRouterRoute = routeDecision;
         if (bufferRoutedTurn) {
             this._modelRouterSessionBuffer = createModelRouterSessionBuffer();
             this._modelRouterEscalationRequested = false;
@@ -1213,10 +1914,11 @@ export class AgentSession {
                 this.agent.state.messages.splice(originalHistoryLength);
                 retryModel = this._resolveModelRouterModelForIntent("modify") ?? previousModel;
                 completedDecision = {
-                    intent: routedIntent,
+                    route: routeDecision,
                     routedModel: formatModelRouterModel(routedModel),
                     outcome: "escalated",
                     retryModel: formatModelRouterModel(retryModel),
+                    intent: routeDecision.tier === "cheap" ? "research" : "modify",
                 };
                 this._lastModelRouterDecision = completedDecision;
             }
@@ -1236,15 +1938,36 @@ export class AgentSession {
             }
         }
         finally {
-            this.agent.state.model = previousModel;
-            this.agent.state.thinkingLevel = previousThinkingLevel;
+            // Restore the pre-route model ONLY if the routed model is still in place: a command
+            // handler may have legitimately changed the session model mid-turn (setModel or a
+            // provider re-registration), and clobbering that would silently undo the change.
+            if (modelsAreEqual(this.agent.state.model, routedModel)) {
+                this.agent.state.model = previousModel;
+                this.agent.state.thinkingLevel = previousThinkingLevel;
+                // The registry may have changed mid-turn (command-time registerProvider): re-resolve
+                // the restored model so a provider override is not dropped with the routed model.
+                this._refreshCurrentModelFromRegistry();
+            }
             this._activeModelRouterIntent = previousActiveModelRouterIntent;
+            this._activeModelRouterRoute = previousActiveModelRouterRoute;
             this._modelRouterSessionBuffer = previousModelRouterSessionBuffer;
             this._modelRouterEscalationRequested = previousModelRouterEscalationRequested;
         }
         if (retryModel && !thrownError) {
+            const previousIsModelRouterRetry = this._isModelRouterRetry;
             try {
-                await this._runAgentPromptWithModelRouter(messages, retryModel, "modify", false);
+                this._isModelRouterRetry = true;
+                const retryDecision = {
+                    tier: "expensive",
+                    risk: "high-impact",
+                    confidence: 1.0,
+                    reasonCode: "cheap_mutating_tool_escalation",
+                    reasons: ["Cheap research turn attempted a mutating tool and escalated"],
+                    fallbackFrom: "cheap",
+                    model: formatModelRouterModel(retryModel),
+                };
+                await this._runAgentPromptWithModelRouter(messages, retryModel, retryDecision, false);
+                this._lastModelRouterDecision = completedDecision;
             }
             catch (error) {
                 thrownError = error;
@@ -1253,6 +1976,9 @@ export class AgentSession {
                     this._lastModelRouterDecision = completedDecision;
                 }
             }
+            finally {
+                this._isModelRouterRetry = previousIsModelRouterRetry;
+            }
         }
         if (persistDecision && completedDecision) {
             persistModelRouterDecision(this.sessionManager, completedDecision);
@@ -1296,6 +2022,9 @@ export class AgentSession {
      * @throws Error if no model selected or no API key available (when not streaming)
      */
     async prompt(text, options) {
+        if (options?.autoContinueGoal !== false) {
+            this._clearGoalAutoContinueTimer();
+        }
         if ((this.isStreaming || this.isRetrying) && options?.streamingBehavior) {
             const run = this._streamingPromptSubmissionTail.then(() => this._promptUnserialized(text, options), () => this._promptUnserialized(text, options));
             this._streamingPromptSubmissionTail = run.catch(() => { });
@@ -1325,7 +2054,7 @@ export class AgentSession {
         const preflightResult = options?.preflightResult;
         let messages;
         let routedTurnModel;
-        let routedTurnIntent;
+        let routedTurnRouteDecision;
         // R4 effectiveness feedback: remember the recall page + the query so we can score, after the
         // response, whether the agent actually used the recalled context.
         let injectedRecall = "";
@@ -1388,8 +2117,13 @@ export class AgentSession {
             }
             // Flush any pending bash messages before the new prompt
             this._flushPendingBashMessages();
-            routedTurnModel = this._resolveModelRouterTurnModel(expandedText);
-            routedTurnIntent = routedTurnModel ? classifyModelRouterIntent(expandedText) : undefined;
+            const resolvedRouteInfo = await this._resolveModelRouterTurnRouteJudged(expandedText, {
+                // Internally generated turns (goal continuation, lane follow-ups) never consult the judge:
+                // the regex floor already classified them, and a 20-turn loop must not buy 20 judge calls.
+                skipJudge: options?.autoContinueGoal === false,
+            });
+            routedTurnModel = resolvedRouteInfo?.model;
+            routedTurnRouteDecision = resolvedRouteInfo?.decision;
             const requestModel = routedTurnModel ?? this.model;
             // Validate model
             if (!requestModel) {
@@ -1404,6 +2138,7 @@ export class AgentSession {
                 }
                 throw new Error(formatNoApiKeyFoundMessage(requestModel.provider));
             }
+            this._checkContextWindowUsageWarning();
             // Check if we need to compact before sending (catches aborted responses).
             // Do not call agent.continue() here: the next model turn must include the
             // user's pending prompt, not an empty continuation after compaction.
@@ -1481,7 +2216,7 @@ export class AgentSession {
             return;
         }
         preflightResult?.(true);
-        await this._runAgentPromptWithModelRouter(messages, routedTurnModel, routedTurnIntent);
+        await this._runAgentPromptWithModelRouter(messages, routedTurnModel, routedTurnRouteDecision);
         // R4: score whether the agent actually used the recalled context, so the recall gate can adapt.
         if (injectedRecall) {
             const response = this._findLastAssistantMessage();
@@ -1495,6 +2230,8 @@ export class AgentSession {
                 this._effectivenessTracker.recordRecallOutcome(injectedRecall, recallQuery, responseText);
             }
         }
+        this._scheduleGoalAutoContinueFromIdle(options);
+        this._scheduleResearchLaneFromIdle();
     }
     /**
      * Try to execute an extension command. Returns true if command was found and executed.
@@ -1814,6 +2551,20 @@ export class AgentSession {
         // Re-clamp thinking level for new model's capabilities
         this.setThinkingLevel(thinkingLevel, { persistSettings });
         await this._emitModelSelect(model, previousModel, "set");
+        this._checkContextWindowUsageWarning();
+        // Re-derive the model-capability tool surface for the new model (restores the full requested
+        // set when moving small -> large, reduces it when moving large -> small).
+        if (this._requestedActiveToolNames) {
+            const before = this.getActiveToolNames().join(",");
+            this.setActiveToolsByName(this._requestedActiveToolNames);
+            const capability = this.getModelCapabilityProfile();
+            if (capability.class !== "full" && this.getActiveToolNames().join(",") !== before) {
+                this._emit({
+                    type: "warning",
+                    message: `Small-context model detected (${capability.contextWindow ?? "unknown"} tokens, class '${capability.class}'): active tools reduced to [${this.getActiveToolNames().join(", ")}]; background lanes ${capability.backgroundLanesEnabled ? "enabled" : "disabled"}.`,
+                });
+            }
+        }
     }
     /**
      * Cycle to next/previous model.
@@ -1849,6 +2600,7 @@ export class AgentSession {
         // setThinkingLevel clamps to model capabilities.
         this.setThinkingLevel(thinkingLevel);
         await this._emitModelSelect(next.model, currentModel, "cycle");
+        this._checkContextWindowUsageWarning();
         return { model: next.model, thinkingLevel: this.thinkingLevel, isScoped: true };
     }
     async _cycleAvailableModel(direction) {
@@ -1869,6 +2621,7 @@ export class AgentSession {
         // Re-clamp thinking level for new model's capabilities
         this.setThinkingLevel(thinkingLevel);
         await this._emitModelSelect(nextModel, currentModel, "cycle");
+        this._checkContextWindowUsageWarning();
         return { model: nextModel, thinkingLevel: this.thinkingLevel, isScoped: false };
     }
     // =========================================================================
@@ -1980,7 +2733,7 @@ export class AgentSession {
             const compactionModel = this._resolveCompactionModel(this.model);
             const { apiKey, headers } = await this._getCompactionRequestAuth(compactionModel);
             const pathEntries = this.sessionManager.getBranch();
-            const settings = this.settingsManager.getCompactionSettings();
+            const settings = this._getAdaptedCompactionSettings();
             const preparation = prepareCompaction(pathEntries, settings);
             if (!preparation) {
                 // Check why we can't compact
@@ -2100,8 +2853,57 @@ export class AgentSession {
      * @param assistantMessage The assistant message to check
      * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
      */
-    async _checkCompaction(assistantMessage, skipAbortedCheck = true) {
+    _getAdaptedCompactionSettings() {
         const settings = this.settingsManager.getCompactionSettings();
+        if (!this.model)
+            return settings;
+        const contextWindow = this.model.contextWindow ?? 0;
+        if (contextWindow <= 0)
+            return settings;
+        // Adapt reserveTokens: at most 25% of context window
+        const maxReserve = Math.floor(contextWindow * 0.25);
+        const reserveTokens = Math.min(settings.reserveTokens, maxReserve);
+        // Adapt keepRecentTokens: at most 50% of context window
+        const maxKeepRecent = Math.floor(contextWindow * 0.5);
+        const keepRecentTokens = Math.min(settings.keepRecentTokens, maxKeepRecent);
+        return {
+            ...settings,
+            reserveTokens,
+            keepRecentTokens,
+        };
+    }
+    _checkContextWindowUsageWarning() {
+        if (!this.model)
+            return;
+        const contextWindow = this.model.contextWindow ?? 0;
+        if (contextWindow <= 0)
+            return;
+        const systemPromptTokens = Math.ceil((this.agent.state.systemPrompt ?? "").length / 4);
+        let toolsChars = 0;
+        for (const tool of this.agent.state.tools || []) {
+            toolsChars += tool.name.length;
+            toolsChars += tool.description?.length ?? 0;
+            if (tool.parameters) {
+                toolsChars += JSON.stringify(tool.parameters).length;
+            }
+        }
+        const toolsTokens = Math.ceil(toolsChars / 4);
+        const baseTokens = systemPromptTokens + toolsTokens;
+        if (baseTokens >= contextWindow) {
+            this._emit({
+                type: "warning",
+                message: `Base configuration (system prompt and active tools) consumes ${baseTokens} tokens, which exceeds the model's context window of ${contextWindow} tokens. The model cannot process any prompts in this state.`,
+            });
+        }
+        else if (baseTokens >= contextWindow * 0.7) {
+            this._emit({
+                type: "warning",
+                message: `Base configuration (system prompt and active tools) consumes ${baseTokens} tokens (${Math.round((baseTokens / contextWindow) * 100)}% of the ${contextWindow} context window). This leaves very little room for conversation history and may cause immediate compaction or context overflow.`,
+            });
+        }
+    }
+    async _checkCompaction(assistantMessage, skipAbortedCheck = true) {
+        const settings = this._getAdaptedCompactionSettings();
         if (!settings.enabled)
             return false;
         // Skip if message was aborted (user cancelled) - unless skipAbortedCheck is false
@@ -2185,7 +2987,7 @@ export class AgentSession {
      * Internal: Run auto-compaction with events.
      */
     async _runAutoCompaction(reason, willRetry) {
-        const settings = this.settingsManager.getCompactionSettings();
+        const settings = this._getAdaptedCompactionSettings();
         this._emit({ type: "compaction_start", reason });
         this._autoCompactionAbortController = new AbortController();
         try {
@@ -2695,7 +3497,10 @@ export class AgentSession {
     }
     _refreshToolRegistry(options) {
         const previousRegistryNames = new Set(this._toolRegistry.keys());
-        const previousActiveToolNames = this.getActiveToolNames();
+        // Re-derive from the pre-filter REQUEST, never from agent.state.tools: the active set is
+        // capability/profile-filtered, so feeding it back through setActiveToolsByName would
+        // permanently shrink what a later switch to a larger model (or permissive profile) restores.
+        const previousActiveToolNames = this._requestedActiveToolNames ?? this.getActiveToolNames();
         const allowedToolNames = this._allowedToolNames;
         const excludedToolNames = this._excludedToolNames;
         const toolProfileFilter = this._toolProfileFilter;
@@ -2767,27 +3572,40 @@ export class AgentSession {
             toolRegistry.set(tool.name, tool);
         }
         this._toolRegistry = toolRegistry;
-        const nextActiveToolNames = (options?.activeToolNames ? [...options.activeToolNames] : [...previousActiveToolNames]).filter((name) => isAllowedTool(name));
+        const requestedBase = options?.activeToolNames ? [...options.activeToolNames] : [...previousActiveToolNames];
+        const nextActiveToolNames = requestedBase.filter((name) => isAllowedTool(name));
+        const autoActivated = [];
         if (allowedToolNames) {
             for (const toolName of this._toolRegistry.keys()) {
                 if (allowedToolNames.has(toolName)) {
                     nextActiveToolNames.push(toolName);
+                    autoActivated.push(toolName);
                 }
             }
         }
         else if (options?.includeAllExtensionTools) {
             for (const tool of wrappedExtensionTools) {
                 nextActiveToolNames.push(tool.name);
+                autoActivated.push(tool.name);
             }
         }
         else if (!options?.activeToolNames) {
             for (const toolName of this._toolRegistry.keys()) {
                 if (!previousRegistryNames.has(toolName)) {
                     nextActiveToolNames.push(toolName);
+                    autoActivated.push(toolName);
                 }
             }
         }
+        // artifact_retrieve companion auto-activation is enforced inside
+        // setActiveToolsByName() itself (not duplicated here), so every activation path --
+        // including the public, extension-exposed setActiveTools() -- gets the same
+        // guarantee, not just this settings/profile refresh flow.
         this.setActiveToolsByName([...new Set(nextActiveToolNames)]);
+        // setActiveToolsByName just stored the profile-filtered ACTIVE set as the request; restore
+        // the true pre-filter request (plus this refresh's auto-activations) so an internal refresh
+        // can never permanently narrow it.
+        this._requestedActiveToolNames = [...new Set([...requestedBase, ...autoActivated])];
     }
     _createReloadRuntimeSnapshot() {
         return {
@@ -2842,6 +3660,14 @@ export class AgentSession {
         const autoResizeImages = this.settingsManager.getImageAutoResize();
         const shellCommandPrefix = this.settingsManager.getShellCommandPrefix();
         const shellPath = this.settingsManager.getShellPath();
+        // grep/find must not emit a "Full output: artifact tool-output:<id>" handle that
+        // nothing can resolve. If artifact_retrieve is explicitly excluded/blocked/outside
+        // an active allowlist, don't hand grep/find an artifact store at all: they fall
+        // back to their pre-existing bounded preview/truncation behavior, with no
+        // payload/meta files ever written and no retrieval promise made.
+        const toolArtifactStore = this._isToolOrCommandAllowedByProfile("artifact_retrieve")
+            ? this._getToolArtifactStore()
+            : undefined;
         const baseToolDefinitions = this._baseToolsOverride
             ? Object.fromEntries(Object.entries(this._baseToolsOverride).map(([name, tool]) => [
                 name,
@@ -2850,12 +3676,37 @@ export class AgentSession {
             : createAllToolDefinitions(this._cwd, {
                 read: { autoResizeImages },
                 bash: { commandPrefix: shellCommandPrefix, shellPath },
+                grep: { artifactStore: toolArtifactStore },
+                find: { artifactStore: toolArtifactStore },
+                artifact_retrieve: { artifactStore: toolArtifactStore },
             });
         this._baseToolDefinitions = new Map(Object.entries(baseToolDefinitions).map(([name, tool]) => [name, tool]));
         if (!this._baseToolsOverride) {
-            for (const definition of createCoreDiagnosticsToolDefinitions(() => this.getActiveToolNames(), () => this.getAllTools(), (messages) => this.getContextGcReport(messages))) {
+            for (const definition of createCoreDiagnosticsToolDefinitions(() => this.getActiveToolNames(), () => this.getAllTools(), (messages) => this.getContextGcReport(messages), () => this._getMemoryAuditDiagnostics())) {
                 this._baseToolDefinitions.set(definition.name, definition);
             }
+            const goalToolDefinition = createGoalToolDefinition({
+                getGoalState: () => this.getGoalStateSnapshot(),
+                saveGoalState: (state) => {
+                    this.saveGoalStateSnapshot(state);
+                },
+            });
+            this._baseToolDefinitions.set(goalToolDefinition.name, goalToolDefinition);
+            const delegateToolDefinition = createDelegateToolDefinition({
+                runWorkerDelegation: (args) => this.runWorkerDelegationOnce(args),
+            });
+            this._baseToolDefinitions.set(delegateToolDefinition.name, delegateToolDefinition);
+            // Registered but not default-active: probes spend tokens on the probed model, so
+            // activation is an explicit choice (settings/profile/setActiveTools or /autonomy fitness).
+            const modelFitnessToolDefinition = createModelFitnessToolDefinition({
+                runProbe: (args) => this.runModelFitness(args),
+            });
+            this._baseToolDefinitions.set(modelFitnessToolDefinition.name, modelFitnessToolDefinition);
+            const runToolkitScriptToolDefinition = createRunToolkitScriptToolDefinition({
+                getScripts: () => this.settingsManager.getToolkitScripts(),
+                execute: (script, scriptArgs) => executeToolkitScript({ script, scriptArgs, cwd: this._cwd }),
+            });
+            this._baseToolDefinitions.set(runToolkitScriptToolDefinition.name, runToolkitScriptToolDefinition);
         }
         const extensionsResult = this._resourceLoader.getExtensions();
         if (options.flagValues) {
@@ -2875,7 +3726,7 @@ export class AgentSession {
         this._applyExtensionBindings(this._extensionRunner);
         const defaultActiveToolNames = this._baseToolsOverride
             ? Object.keys(this._baseToolsOverride)
-            : ["read", "bash", "edit", "write", "context_audit"];
+            : ["read", "bash", "edit", "write", "context_audit", "goal", "delegate", "run_toolkit_script"];
         const baseActiveToolNames = options.activeToolNames ?? defaultActiveToolNames;
         this._refreshToolRegistry({
             activeToolNames: baseActiveToolNames,
@@ -2891,7 +3742,9 @@ export class AgentSession {
         }
         const previousRunner = this._extensionRunner;
         const snapshot = this._createReloadRuntimeSnapshot();
-        const activeToolNames = this.getActiveToolNames();
+        // Preserve the pre-filter tool REQUEST across the rebuild, not the capability/profile-filtered
+        // active set — otherwise a reload under a small model permanently shrinks the restorable set.
+        const activeToolNames = this._requestedActiveToolNames ?? this.getActiveToolNames();
         const previousFlagValues = previousRunner.getFlagValues();
         const reloadErrors = [];
         let newRunner;
@@ -2984,7 +3837,7 @@ export class AgentSession {
             // Remove from loaded extensions
             this._resourceLoader.removeLoadedExtension(extensionPath);
             // Rebuild runtime with new extension set
-            const activeToolNames = this.getActiveToolNames();
+            const activeToolNames = this._requestedActiveToolNames ?? this.getActiveToolNames();
             const previousFlagValues = previousRunner.getFlagValues();
             this._buildRuntime({
                 activeToolNames,
@@ -3027,7 +3880,7 @@ export class AgentSession {
                 throw new Error(error || `Failed to load extension: ${extensionPath}`);
             }
             // Rebuild runtime to aggregate tools/commands/handlers/providers
-            const activeToolNames = this.getActiveToolNames();
+            const activeToolNames = this._requestedActiveToolNames ?? this.getActiveToolNames();
             const previousFlagValues = previousRunner.getFlagValues();
             this._buildRuntime({
                 activeToolNames,
@@ -3702,6 +4555,671 @@ export class AgentSession {
     getDailyUsageBreakdown(formatLabel, now = new Date()) {
         return formatDailyUsageBreakdown(this.getDailyUsageTotals(now), formatLabel);
     }
+    /**
+     * Save a snapshot of the goal state to the session log.
+     *
+     * @returns the id of the appended custom entry
+     */
+    saveGoalStateSnapshot(state) {
+        return appendGoalStateSnapshot(this.sessionManager, state);
+    }
+    /**
+     * Retrieve the latest valid goal state snapshot from the session log.
+     */
+    getGoalStateSnapshot() {
+        return getLatestGoalStateSnapshot(this.sessionManager.getEntries());
+    }
+    /**
+     * Save a snapshot of the evidence bundle to the session log.
+     *
+     * @returns the id of the appended custom entry
+     */
+    saveEvidenceBundleSnapshot(bundle) {
+        return appendEvidenceBundleSnapshot(this.sessionManager, bundle);
+    }
+    /**
+     * Retrieve the latest valid evidence bundle snapshot from the session log.
+     */
+    getEvidenceBundleSnapshot() {
+        return getLatestEvidenceBundleSnapshot(this.sessionManager.getEntries());
+    }
+    getEvidenceBundleSnapshots() {
+        return getEvidenceBundleSnapshots(this.sessionManager.getEntries());
+    }
+    /** Live lane records tracked by this process (running and terminal). */
+    getLaneRecords() {
+        return this._laneTracker.getRecords();
+    }
+    saveWorkerResultSnapshot(result) {
+        return appendWorkerResultSnapshot(this.sessionManager, result);
+    }
+    getWorkerResultSnapshots() {
+        return getWorkerResultSnapshots(this.sessionManager.getEntries());
+    }
+    saveLearningDecisionSnapshot(decision) {
+        return appendLearningDecisionSnapshot(this.sessionManager, decision);
+    }
+    getLearningDecisionSnapshots() {
+        return getLearningDecisionSnapshots(this.sessionManager.getEntries());
+    }
+    getGoalRuntimeSnapshot(settings) {
+        return buildGoalRuntimeSnapshot({
+            entries: this.sessionManager.getEntries(),
+            settings,
+        });
+    }
+    _clearGoalAutoContinueTimer() {
+        if (this._goalAutoContinueTimer !== undefined) {
+            clearTimeout(this._goalAutoContinueTimer);
+            this._goalAutoContinueTimer = undefined;
+        }
+    }
+    _scheduleGoalAutoContinueFromIdle(options) {
+        if (options?.autoContinueGoal === false || this._isGoalAutoContinuing || this._disposed)
+            return;
+        // Small-window models cannot afford multi-thousand-token continuation prompts per idle turn.
+        if (!this.getModelCapabilityProfile().backgroundLanesEnabled)
+            return;
+        const { maxStallTurns, goalAutoContinue, goalAutoContinueDelayMs } = this.settingsManager.getAutonomySettings();
+        if (!goalAutoContinue)
+            return;
+        const snapshot = this.getGoalRuntimeSnapshot({ maxStallTurns });
+        if (snapshot.continuation.action !== "continue")
+            return;
+        this._clearGoalAutoContinueTimer();
+        this._goalAutoContinueTimer = setTimeout(() => {
+            this._goalAutoContinueTimer = undefined;
+            void this._runScheduledGoalAutoContinue();
+        }, goalAutoContinueDelayMs);
+        const timer = this._goalAutoContinueTimer;
+        if (typeof timer === "object" && timer && "unref" in timer) {
+            const { unref } = timer;
+            unref?.call(timer);
+        }
+    }
+    async _runScheduledGoalAutoContinue() {
+        if (this._isGoalAutoContinuing || this._disposed)
+            return;
+        const { maxStallTurns, goalContinueTurns, goalContinueMaxWallClockMinutes, goalAutoContinue } = this.settingsManager.getAutonomySettings();
+        if (!goalAutoContinue)
+            return;
+        const snapshot = this.getGoalRuntimeSnapshot({ maxStallTurns });
+        if (snapshot.continuation.action !== "continue")
+            return;
+        this._isGoalAutoContinuing = true;
+        try {
+            await this.continueGoalLoop({
+                maxTurns: goalContinueTurns,
+                maxStallTurns,
+                maxWallClockMinutes: goalContinueMaxWallClockMinutes,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this._emit({ type: "warning", message: `Goal auto-continuation failed: ${message}` });
+        }
+        finally {
+            this._isGoalAutoContinuing = false;
+        }
+    }
+    _clearResearchLaneTimer() {
+        if (this._researchLaneTimer !== undefined) {
+            clearTimeout(this._researchLaneTimer);
+            this._researchLaneTimer = undefined;
+        }
+    }
+    /**
+     * Derive the research demand from durable goal state: an active goal with open requirements,
+     * deduplicated against the latest persisted bundle so the same requirement set is never
+     * researched twice (the query is deterministic, so dedupe survives session reload).
+     */
+    _buildResearchLaneDemand() {
+        const goal = this.getGoalStateSnapshot();
+        if (!goal || goal.status !== "active") {
+            this._lastResearchLaneSkipReason = "no_active_goal";
+            return undefined;
+        }
+        const open = goal.requirements.filter((requirement) => requirement.status === "open");
+        if (open.length === 0) {
+            this._lastResearchLaneSkipReason = "no_open_requirements";
+            return undefined;
+        }
+        const query = `goal:${goal.goalId} requirements:${open
+            .map((requirement) => requirement.id)
+            .sort()
+            .join(",")}`;
+        if (this.getEvidenceBundleSnapshot()?.query === query) {
+            this._lastResearchLaneSkipReason = "recent_evidence_sufficient";
+            return undefined;
+        }
+        const context = [
+            `Goal: ${goal.userGoal}`,
+            "Open requirements:",
+            ...open.slice(0, 20).map((requirement) => `- ${requirement.text}`),
+        ].join("\n");
+        return { query, context, goalId: goal.goalId };
+    }
+    /**
+     * Idle trigger for the autonomous research lane (mirrors {@link _scheduleGoalAutoContinueFromIdle}).
+     * All skips are recorded in `_lastResearchLaneSkipReason` and surfaced via diagnostics — the lane
+     * informs, it never prompts or blocks the foreground.
+     */
+    _scheduleResearchLaneFromIdle() {
+        if (this._isResearchLaneRunning || this._disposed || this._isChildSession)
+            return;
+        if (!this.getModelCapabilityProfile().backgroundLanesEnabled) {
+            this._lastResearchLaneSkipReason = "model_context_too_small";
+            return;
+        }
+        const research = this.settingsManager.getResearchLaneSettings();
+        if (!research.enabled) {
+            this._lastResearchLaneSkipReason = "research_lane_disabled";
+            return;
+        }
+        const { mode } = this.settingsManager.getAutonomySettings();
+        if (mode === "off") {
+            this._lastResearchLaneSkipReason = "autonomy_mode_off";
+            return;
+        }
+        const priorRuns = getLaneRecordSnapshots(this.sessionManager.getEntries()).filter((record) => record.type === "research").length;
+        if (priorRuns >= research.maxRunsPerSession) {
+            this._lastResearchLaneSkipReason = "max_runs_reached";
+            return;
+        }
+        if (!this._buildResearchLaneDemand())
+            return;
+        this._clearResearchLaneTimer();
+        this._researchLaneTimer = setTimeout(() => {
+            this._researchLaneTimer = undefined;
+            void this._runScheduledResearchLane();
+        }, research.idleDelayMs);
+        const timer = this._researchLaneTimer;
+        if (typeof timer === "object" && timer && "unref" in timer) {
+            const { unref } = timer;
+            unref?.call(timer);
+        }
+    }
+    async _runScheduledResearchLane() {
+        if (this._isResearchLaneRunning || this._disposed)
+            return;
+        const research = this.settingsManager.getResearchLaneSettings();
+        const { mode } = this.settingsManager.getAutonomySettings();
+        if (!research.enabled || mode === "off")
+            return;
+        try {
+            await this.runResearchLaneOnce();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this._emit({ type: "warning", message: `Research lane failed: ${message}` });
+        }
+    }
+    /**
+     * Capability profile derived from the CURRENT session model's own metadata (context window),
+     * honoring the modelCapability.mode setting ("off" disables, a class name forces).
+     */
+    getModelCapabilityProfile() {
+        return deriveModelCapabilityProfile({
+            contextWindow: this.model?.contextWindow,
+            mode: this.settingsManager.getModelCapabilitySettings().mode,
+        });
+    }
+    /** Capability profile for a specific lane model (lane budgets scale to the lane model's window). */
+    _laneCapabilityProfile(model) {
+        return deriveModelCapabilityProfile({
+            contextWindow: model.contextWindow,
+            mode: this.settingsManager.getModelCapabilitySettings().mode,
+        });
+    }
+    /**
+     * Resolve the model for a background lane. Lanes are shipped BY this session, so they inherit
+     * the session's own model unless a lane-specific model is explicitly configured — a single-model
+     * setup (e.g. one local open model) runs its lanes on that same model. An explicitly configured
+     * pattern that cannot resolve/authenticate is a visible skip, not a silent fallback.
+     */
+    _resolveLaneModel(configuredPattern) {
+        if (configuredPattern) {
+            const resolved = resolveCliModel({ cliModel: configuredPattern, modelRegistry: this._modelRegistry });
+            if (resolved.model && this._modelRegistry.hasConfiguredAuth(resolved.model)) {
+                return resolved.model;
+            }
+            return undefined;
+        }
+        return this.model ?? undefined;
+    }
+    /**
+     * Resolve what a lane ships with. Precedence: explicit lane model setting, then the lane
+     * profile's model (a shipped profile with a model MUST be obeyed — unresolvable is a visible
+     * skip, never a fallback), then generic inheritance of the session model.
+     */
+    _resolveLaneShipment(laneSettings, missingModelReason) {
+        let laneProfile;
+        if (laneSettings.profile) {
+            laneProfile = this.settingsManager.getProfileRegistry().getProfile(laneSettings.profile);
+            if (!laneProfile) {
+                return { ok: false, skipReason: "lane_profile_not_found" };
+            }
+        }
+        let model;
+        if (laneSettings.model) {
+            model = this._resolveLaneModel(laneSettings.model);
+            if (!model)
+                return { ok: false, skipReason: missingModelReason };
+        }
+        else if (laneProfile?.model) {
+            model = this._resolveLaneModel(laneProfile.model);
+            if (!model)
+                return { ok: false, skipReason: "no_lane_profile_model" };
+        }
+        else {
+            model = this.model ?? undefined;
+            if (!model)
+                return { ok: false, skipReason: missingModelReason };
+        }
+        return { ok: true, model, laneProfile };
+    }
+    /** UAC tool grants from a shipped lane profile, recorded on the lane envelope. */
+    _laneProfileToolGrants(laneProfile) {
+        const toolsFilter = laneProfile?.resources.tools;
+        return {
+            ...(toolsFilter?.allow && toolsFilter.allow.length > 0 ? { allowedTools: [...toolsFilter.allow] } : {}),
+            ...(toolsFilter?.block && toolsFilter.block.length > 0 ? { deniedTools: [...toolsFilter.block] } : {}),
+        };
+    }
+    /** Stripped research envelope — never the foreground/architect envelope. */
+    _buildResearchLaneEnvelope(maxUsd, laneProfile) {
+        return {
+            id: `research-${this.sessionId}-${Date.now()}`,
+            profileId: laneProfile?.name,
+            capabilities: ["research", "read_files", "memory_read"],
+            ...this._laneProfileToolGrants(laneProfile),
+            maxEstimatedUsd: Math.min(maxUsd, this.capabilityEnvelope?.maxEstimatedUsd ?? Number.POSITIVE_INFINITY),
+            createdAt: new Date().toISOString(),
+        };
+    }
+    /**
+     * Run one bounded, read-only research pass and persist its results: evidence bundle snapshot,
+     * terminal lane record, and spawned-usage cost report (single-hop invariant, idempotent on the
+     * lane's reportId). Explicit calls (e.g. `/autonomy research`) express user intent and bypass the
+     * enabled/mode/dedupe gates the idle scheduler enforces; budget and capability gates always apply.
+     */
+    async runResearchLaneOnce(request) {
+        if (this._isResearchLaneRunning) {
+            return { started: false, skipReason: "research_lane_already_running" };
+        }
+        if (this._disposed) {
+            return { started: false, skipReason: "session_disposed" };
+        }
+        const settings = this.settingsManager.getResearchLaneSettings();
+        const demand = request?.query
+            ? { query: request.query, context: request.context ?? "", goalId: request.goalId }
+            : this._buildResearchLaneDemand();
+        if (!demand) {
+            return { started: false, skipReason: this._lastResearchLaneSkipReason ?? "no_research_demand" };
+        }
+        const shipment = this._resolveLaneShipment(settings, "no_research_model");
+        if (!shipment.ok) {
+            this._lastResearchLaneSkipReason = shipment.skipReason;
+            return { started: false, skipReason: shipment.skipReason };
+        }
+        const { model, laneProfile } = shipment;
+        this._isResearchLaneRunning = true;
+        this._laneTracker.ensureCounterAtLeast(getLaneRecordSnapshots(this.sessionManager.getEntries()).length + 1);
+        const startedRecord = this._laneTracker.start({ type: "research", goalId: demand.goalId });
+        try {
+            let spentUsage;
+            const result = await runResearch({
+                query: demand.query,
+                context: demand.context,
+                envelope: this._buildResearchLaneEnvelope(settings.maxUsd, laneProfile),
+                maxUsd: settings.maxUsd,
+                maxSources: settings.maxSources,
+                maxFindings: settings.maxFindings,
+                maxWallClockMs: settings.maxWallClockMs,
+                signal: this._researchLaneAbort.signal,
+                complete: async ({ systemPrompt, userPrompt, signal }) => {
+                    const completion = await this.runIsolatedCompletion({
+                        // Level-0 core always survives; profile soul and role prompt are the replaceable
+                        // layers; a settings-provided prompt replaces everything above the core.
+                        systemPrompt: composeSubagentSystemPrompt({
+                            soul: laneProfile?.soul,
+                            rolePrompt: systemPrompt,
+                            override: settings.systemPrompt,
+                        }),
+                        messages: [{ role: "user", content: [{ type: "text", text: userPrompt }], timestamp: Date.now() }],
+                        model,
+                        thinkingLevel: laneProfile?.thinking ?? "off",
+                        maxTokens: this._laneCapabilityProfile(model).laneMaxOutputTokens,
+                        signal,
+                        // Core/soul/role are all static per configuration — the provider can cache the prefix.
+                        cacheRetention: "short",
+                    });
+                    spentUsage = completion.usage;
+                    return {
+                        text: completion.text,
+                        costUsd: completion.usage.cost.total,
+                        stopReason: String(completion.stopReason),
+                    };
+                },
+            });
+            // Bug #21 pattern: if the session was disposed while the completion was in flight, do NOT
+            // persist evidence/records/usage against the dead session.
+            if (this._disposed) {
+                const record = this._laneTracker.complete(startedRecord.laneId, {
+                    status: "canceled",
+                    reasonCode: "session_disposed",
+                });
+                return { started: true, record, result };
+            }
+            let evidenceEntryId;
+            if (result.bundle) {
+                evidenceEntryId = this.saveEvidenceBundleSnapshot(result.bundle);
+            }
+            if (spentUsage && (spentUsage.cost.total > 0 || spentUsage.totalTokens > 0)) {
+                this.addSpawnedUsage(spentUsage, {
+                    label: "research-lane",
+                    reportId: `research:${this.sessionId}:${startedRecord.laneId}`,
+                });
+            }
+            const record = this._laneTracker.complete(startedRecord.laneId, {
+                status: result.status,
+                reasonCode: result.reasonCode,
+                costUsd: result.costUsd,
+                evidenceEntryId,
+            });
+            if (record) {
+                appendLaneRecordSnapshot(this.sessionManager, record);
+            }
+            return { started: true, record, result };
+        }
+        catch (error) {
+            const record = this._laneTracker.complete(startedRecord.laneId, {
+                status: "failed",
+                reasonCode: "research_lane_error",
+            });
+            if (record && !this._disposed) {
+                appendLaneRecordSnapshot(this.sessionManager, record);
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            this._emit({ type: "warning", message: `Research lane failed: ${message}` });
+            return { started: true, record };
+        }
+        finally {
+            this._isResearchLaneRunning = false;
+        }
+    }
+    /**
+     * Run one bounded scout-worker delegation: build a WorkerRequest with a stripped read-only
+     * envelope, execute it as an isolated completion on a cheap lane, validate the result via
+     * {@link validateWorkerResult} before acceptance, and persist result + lane record + spawned
+     * usage (idempotent per-lane reportId). Consumed by the `delegate` tool.
+     */
+    async runWorkerDelegationOnce(request) {
+        if (this._isWorkerDelegationRunning) {
+            return { started: false, skipReason: "worker_delegation_already_running" };
+        }
+        if (this._disposed) {
+            return { started: false, skipReason: "session_disposed" };
+        }
+        const instructions = request.instructions.trim();
+        if (instructions.length === 0) {
+            return { started: false, skipReason: "missing_instructions" };
+        }
+        const settings = this.settingsManager.getWorkerDelegationSettings();
+        if (!settings.enabled) {
+            return { started: false, skipReason: "worker_delegation_disabled" };
+        }
+        const shipment = this._resolveLaneShipment(settings, "no_worker_model");
+        if (!shipment.ok) {
+            return { started: false, skipReason: shipment.skipReason };
+        }
+        const { model, laneProfile } = shipment;
+        this._isWorkerDelegationRunning = true;
+        this._laneTracker.ensureCounterAtLeast(getLaneRecordSnapshots(this.sessionManager.getEntries()).length + 1);
+        const startedRecord = this._laneTracker.start({ type: "worker" });
+        const maxUsd = Math.min(settings.maxUsd, this.capabilityEnvelope?.maxEstimatedUsd ?? Number.POSITIVE_INFINITY);
+        const workerRequest = {
+            id: startedRecord.laneId,
+            instructions,
+            route: {
+                tier: "cheap",
+                risk: "read-only",
+                confidence: 1,
+                reasonCode: "scout_worker",
+                reasons: ["Read-only scout delegation"],
+            },
+            envelope: {
+                id: `worker-${this.sessionId}-${startedRecord.laneId}`,
+                profileId: laneProfile?.name,
+                capabilities: ["read_files"],
+                ...this._laneProfileToolGrants(laneProfile),
+                maxEstimatedUsd: maxUsd,
+                createdAt: new Date().toISOString(),
+            },
+            maxEstimatedUsd: maxUsd,
+            createdAt: new Date().toISOString(),
+        };
+        const usageReportId = `worker:${this.sessionId}:${startedRecord.laneId}`;
+        try {
+            let spentUsage;
+            const outcome = await runWorker({
+                request: workerRequest,
+                maxUsd,
+                maxWallClockMs: settings.maxWallClockMs,
+                usageReportId,
+                signal: this._workerDelegationAbort.signal,
+                complete: async ({ systemPrompt, userPrompt, signal }) => {
+                    const completion = await this.runIsolatedCompletion({
+                        // Level-0 core always survives. A model-provided prompt (delegate tool) is the most
+                        // specific override, then the settings-level prompt, then profile soul + role prompt.
+                        systemPrompt: composeSubagentSystemPrompt({
+                            soul: laneProfile?.soul,
+                            rolePrompt: systemPrompt,
+                            override: request.systemPrompt ?? settings.systemPrompt,
+                        }),
+                        messages: [{ role: "user", content: [{ type: "text", text: userPrompt }], timestamp: Date.now() }],
+                        model,
+                        thinkingLevel: laneProfile?.thinking ?? "off",
+                        maxTokens: this._laneCapabilityProfile(model).laneMaxOutputTokens,
+                        signal,
+                        // Core/soul/role are all static per configuration — the provider can cache the prefix.
+                        cacheRetention: "short",
+                    });
+                    spentUsage = completion.usage;
+                    return {
+                        text: completion.text,
+                        costUsd: completion.usage.cost.total,
+                        stopReason: String(completion.stopReason),
+                    };
+                },
+            });
+            // Bug #21 pattern: never persist against a disposed session.
+            if (this._disposed) {
+                const record = this._laneTracker.complete(startedRecord.laneId, {
+                    status: "canceled",
+                    reasonCode: "session_disposed",
+                });
+                return { started: true, record, outcome };
+            }
+            this.saveWorkerResultSnapshot(outcome.result);
+            if (spentUsage && (spentUsage.cost.total > 0 || spentUsage.totalTokens > 0)) {
+                this.addSpawnedUsage(spentUsage, { label: "worker-delegation", reportId: usageReportId });
+            }
+            const record = this._laneTracker.complete(startedRecord.laneId, {
+                status: outcome.laneStatus,
+                reasonCode: outcome.reasonCode,
+                costUsd: outcome.costUsd,
+            });
+            if (record) {
+                appendLaneRecordSnapshot(this.sessionManager, record);
+            }
+            return { started: true, record, outcome };
+        }
+        catch (error) {
+            const record = this._laneTracker.complete(startedRecord.laneId, {
+                status: "failed",
+                reasonCode: "worker_delegation_error",
+            });
+            if (record && !this._disposed) {
+                appendLaneRecordSnapshot(this.sessionManager, record);
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            this._emit({ type: "warning", message: `Worker delegation failed: ${message}` });
+            return { started: true, record };
+        }
+        finally {
+            this._isWorkerDelegationRunning = false;
+        }
+    }
+    /**
+     * Probe a candidate model against the subagent contracts (research/worker/judge/search/
+     * tool-call surfaces) via {@link runModelFitnessProbe}. The model must resolve and
+     * authenticate; every probe call runs as an isolated completion on that model, and probe
+     * spend is reported through spawned-usage accounting.
+     */
+    async runModelFitness(args) {
+        if (this._disposed)
+            return { started: false, skipReason: "session_disposed" };
+        const resolved = this._resolveLaneModel(args.model.trim() || undefined);
+        if (!resolved)
+            return { started: false, skipReason: "model_unresolved_or_unauthenticated" };
+        const capability = this._laneCapabilityProfile(resolved);
+        const spent = {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            totalTokens: 0,
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+        };
+        const report = await runModelFitnessProbe({
+            trials: args.trials,
+            signal: this._researchLaneAbort.signal,
+            complete: async ({ systemPrompt, userPrompt, signal }) => {
+                const callStarted = Date.now();
+                const completion = await this.runIsolatedCompletion({
+                    systemPrompt,
+                    messages: [{ role: "user", content: [{ type: "text", text: userPrompt }], timestamp: Date.now() }],
+                    model: resolved,
+                    thinkingLevel: "off",
+                    maxTokens: capability.laneMaxOutputTokens,
+                    signal,
+                    cacheRetention: "short",
+                });
+                const callMs = Date.now() - callStarted;
+                spent.input += completion.usage.input;
+                spent.output += completion.usage.output;
+                spent.cacheRead += completion.usage.cacheRead;
+                spent.cacheWrite += completion.usage.cacheWrite;
+                spent.totalTokens += completion.usage.totalTokens;
+                spent.cost.input += completion.usage.cost.input;
+                spent.cost.output += completion.usage.cost.output;
+                spent.cost.cacheRead += completion.usage.cost.cacheRead;
+                spent.cost.cacheWrite += completion.usage.cost.cacheWrite;
+                spent.cost.total += completion.usage.cost.total;
+                return {
+                    text: completion.text,
+                    costUsd: completion.usage.cost.total,
+                    stopReason: String(completion.stopReason),
+                    // Wall-clock fallback for tok/s: providers don't expose pure eval time, so the
+                    // measured call time stands in — slightly conservative (includes network/queue).
+                    outputTokens: completion.usage.output,
+                    evalMs: callMs,
+                };
+            },
+        });
+        if (!this._disposed && (spent.cost.total > 0 || spent.totalTokens > 0)) {
+            this.addSpawnedUsage(spent, { label: "model-fitness" });
+        }
+        const modelRef = `${resolved.provider}/${resolved.id}`;
+        // Fitness is a property of a model ON a host — persist the report host-keyed so role
+        // assignments stay per-machine (a model can await better hardware without being forgotten).
+        // Best-effort: a disk problem must not fail the probe itself.
+        try {
+            if (!this._disposed) {
+                FitnessStore.forAgentDir(this._agentDir).save(modelRef, report);
+            }
+        }
+        catch {
+            // best-effort persistence
+        }
+        return { started: true, model: modelRef, report };
+    }
+    /** Fitness reports persisted for THIS host (measured evidence for architect/profile decisions). */
+    getStoredFitnessReports() {
+        try {
+            return FitnessStore.forAgentDir(this._agentDir).getForHost();
+        }
+        catch {
+            return [];
+        }
+    }
+    async continueGoalOnce(options) {
+        const snapshot = this.getGoalRuntimeSnapshot({ maxStallTurns: options.maxStallTurns });
+        if (snapshot.continuation.action !== "continue") {
+            return { submitted: false, snapshot };
+        }
+        const prompt = buildGoalContinuationPrompt({ snapshot, limits: options.promptLimits });
+        await this.prompt(prompt.text, {
+            expandPromptTemplates: false,
+            processSlashCommands: false,
+            autoContinueGoal: false,
+        });
+        return { submitted: true, snapshot, prompt };
+    }
+    async continueGoalLoop(options) {
+        let turnsSubmitted = 0;
+        const now = options.now ?? Date.now;
+        const maxWallClockMs = typeof options.maxWallClockMinutes === "number" && options.maxWallClockMinutes > 0
+            ? options.maxWallClockMinutes * 60_000
+            : undefined;
+        const startedAt = now();
+        const hasReachedWallClockBudget = () => maxWallClockMs !== undefined && now() - startedAt >= maxWallClockMs;
+        const snapshot = () => this.getGoalRuntimeSnapshot({ maxStallTurns: options.maxStallTurns });
+        if (options.maxTurns <= 0) {
+            return {
+                turnsSubmitted: 0,
+                stopReason: "max_turns_reached",
+                finalSnapshot: snapshot(),
+            };
+        }
+        if (hasReachedWallClockBudget()) {
+            return { turnsSubmitted, stopReason: "wall_clock_budget_reached", finalSnapshot: snapshot() };
+        }
+        while (turnsSubmitted < options.maxTurns) {
+            const beforeSnapshot = snapshot();
+            if (beforeSnapshot.continuation.action !== "continue") {
+                return { turnsSubmitted, stopReason: "continuation_not_allowed", finalSnapshot: beforeSnapshot };
+            }
+            const state = beforeSnapshot.goalState;
+            const beforeKey = state
+                ? `${state.goalId}:${state.updatedAt}:${state.events.length}:${state.stallTurns}:${state.status}`
+                : undefined;
+            const result = await this.continueGoalOnce(options);
+            if (result.submitted) {
+                turnsSubmitted++;
+            }
+            if (hasReachedWallClockBudget()) {
+                return { turnsSubmitted, stopReason: "wall_clock_budget_reached", finalSnapshot: snapshot() };
+            }
+            const afterSnapshot = snapshot();
+            if (afterSnapshot.continuation.action !== "continue") {
+                return { turnsSubmitted, stopReason: "continuation_not_allowed", finalSnapshot: afterSnapshot };
+            }
+            const afterState = afterSnapshot.goalState;
+            const afterKey = afterState
+                ? `${afterState.goalId}:${afterState.updatedAt}:${afterState.events.length}:${afterState.stallTurns}:${afterState.status}`
+                : undefined;
+            if (beforeKey === afterKey) {
+                return { turnsSubmitted, stopReason: "goal_state_not_advanced", finalSnapshot: afterSnapshot };
+            }
+        }
+        return {
+            turnsSubmitted,
+            stopReason: "max_turns_reached",
+            finalSnapshot: snapshot(),
+        };
+    }
     /**
      * Run a one-shot LLM completion fully ISOLATED from the main session — the load-bearing
      * primitive for the native reflection engine (adaptive-agent design §6c/§7).
@@ -3807,8 +5325,60 @@ export class AgentSession {
         // or skills against the dead session.
         if (this._disposed)
             return result;
+        // Learning apply policy: every durable write is converted to a proposal, decided by the
+        // learning gate, and audited with a rollback plan. With the policy disabled (default) the
+        // legacy direct-apply behavior is preserved — but now leaves audit records with rollback info.
+        const policy = this.settingsManager.getLearningPolicySettings();
+        // The audit id sequence counts STORED snapshots only: it reseeds from the stored count on
+        // every pass, so advancing it for a no-op (which stores nothing) would make later passes
+        // reuse ids — and rollback keys on the id, so a collision blocks or misdirects rollback.
+        let auditSequence = getLearningAuditSnapshots(this.sessionManager.getEntries()).length;
+        let writeIndex = 0;
         for (const write of result.writes) {
-            await this._applyReflectionWrite(write, signal);
+            writeIndex += 1;
+            const proposalId = `${input.reportId ?? "reflection"}-w${writeIndex}`;
+            const proposal = proposalFromReflectionWrite(write, proposalId);
+            const rollback = rollbackPlanForReflectionWrite(write);
+            const decision = policy.enabled
+                ? evaluateLearningDecision({
+                    proposal,
+                    confidence: policy.reflectionSourceConfidence,
+                    observations: 1,
+                    contradictions: 0,
+                    settings: {
+                        enabled: true,
+                        autoApplyEnabled: policy.autoApplyEnabled,
+                        confidenceThreshold: policy.confidenceThreshold,
+                        minObservations: policy.minObservations,
+                        allowedAutoApplyLayers: policy.allowedAutoApplyLayers,
+                        requireRollbackPlan: policy.requireRollbackPlan,
+                    },
+                })
+                : {
+                    kind: "apply",
+                    reasonCode: "learning_policy_disabled_legacy_apply",
+                    confidence: 0,
+                    summary: proposal.summary,
+                    requiresApproval: false,
+                };
+            this.saveLearningDecisionSnapshot(decision);
+            if (decision.kind === "apply") {
+                await this._applyReflectionWrite(write, signal);
+            }
+            if (decision.kind !== "no-op") {
+                auditSequence += 1;
+                appendLearningAuditSnapshot(this.sessionManager, {
+                    id: `audit-${auditSequence}`,
+                    proposalId,
+                    layer: proposal.layer,
+                    action: decision.kind === "apply" ? "apply" : "propose",
+                    summary: proposal.summary,
+                    reasonCode: decision.reasonCode,
+                    decision,
+                    rollback,
+                    createdAt: new Date().toISOString(),
+                });
+            }
         }
         // Account the reflection's spend so it surfaces in the footer roll-up (net-token visibility).
         // Idempotent on reportId so a retried/duplicated pass cannot double-count.
@@ -3817,6 +5387,76 @@ export class AgentSession {
         }
         return result;
     }
+    getLearningAuditRecords() {
+        return getLearningAuditSnapshots(this.sessionManager.getEntries());
+    }
+    /**
+     * Roll back one applied durable learning change by executing the inverse operation recorded in
+     * its audit record (memory ops run through the same bundled memory-tool path as the original
+     * apply; promoted skills are archived). Appends a linked "rollback" audit record on success so
+     * the change history stays complete and a change cannot be rolled back twice.
+     */
+    async rollbackLearningWrite(auditId) {
+        if (this._disposed)
+            return { ok: false, reason: "session_disposed" };
+        const audits = this.getLearningAuditRecords();
+        const audit = audits.find((record) => record.id === auditId);
+        if (!audit)
+            return { ok: false, reason: "audit_not_found" };
+        if (audit.action !== "apply")
+            return { ok: false, reason: "not_an_applied_change" };
+        if (audits.some((record) => record.action === "rollback" && record.rollbackOf === auditId)) {
+            return { ok: false, reason: "already_rolled_back" };
+        }
+        const rollback = audit.rollback;
+        if (!rollback)
+            return { ok: false, reason: "no_rollback_plan" };
+        switch (rollback.kind) {
+            case "memory_remove": {
+                if (!rollback.target)
+                    return { ok: false, reason: "missing_rollback_target" };
+                await this._applyReflectionWrite({ kind: "memory_remove", target: rollback.target });
+                break;
+            }
+            case "memory_restore": {
+                if (!rollback.target || rollback.previous === undefined) {
+                    return { ok: false, reason: "missing_rollback_target" };
+                }
+                await this._applyReflectionWrite({
+                    kind: "memory_replace",
+                    target: rollback.target,
+                    text: rollback.previous,
+                });
+                break;
+            }
+            case "memory_add": {
+                if (rollback.previous === undefined)
+                    return { ok: false, reason: "missing_rollback_target" };
+                await this._applyReflectionWrite({ kind: "memory_add", section: "MEMORY", text: rollback.previous });
+                break;
+            }
+            case "archive_skill": {
+                if (!rollback.target)
+                    return { ok: false, reason: "missing_rollback_target" };
+                if (!this.archivePromotedSkill(rollback.target)) {
+                    return { ok: false, reason: "skill_archive_failed" };
+                }
+                break;
+            }
+        }
+        appendLearningAuditSnapshot(this.sessionManager, {
+            id: `${audit.id}-rollback`,
+            proposalId: audit.proposalId,
+            layer: audit.layer,
+            action: "rollback",
+            summary: `Rolled back: ${audit.summary}`,
+            reasonCode: "user_requested_rollback",
+            decision: audit.decision,
+            rollbackOf: audit.id,
+            createdAt: new Date().toISOString(),
+        });
+        return { ok: true, reason: "rollback_applied" };
+    }
     /**
      * Apply one reflection write through the bundled `memory` tool. `memory_replace`/`memory_remove`
      * don't carry a target file, so we try MEMORY.md first and fall back to USER.md when the substring
@@ -4018,6 +5658,182 @@ export class AgentSession {
     // =========================================================================
     // Extension System
     // =========================================================================
+    getAutonomyStatusSnapshot() {
+        const snapshot = {};
+        if (this._lastModelRouterDecision?.route) {
+            snapshot.latestRoute = {
+                tier: this._lastModelRouterDecision.route.tier,
+                reasonCode: this._lastModelRouterDecision.route.reasonCode,
+                risk: this._lastModelRouterDecision.route.risk,
+            };
+        }
+        if (this._lastAutonomyGateOutcome) {
+            snapshot.latestGate = {
+                outcome: this._lastAutonomyGateOutcome.outcome,
+                gate: this._lastAutonomyGateOutcome.gate,
+                reasonCode: this._lastAutonomyGateOutcome.reasonCode,
+            };
+        }
+        const currentCost = this.getSessionStats().cost;
+        if (currentCost > 0) {
+            snapshot.currentCostUsd = currentCost;
+        }
+        const spawnedCost = this.getSpawnedUsage().cost;
+        if (spawnedCost > 0) {
+            snapshot.spawnedCostUsd = spawnedCost;
+        }
+        const dailyCost = this.getDailyUsageTotals?.()?.totalCost;
+        if (dailyCost !== undefined && dailyCost > 0) {
+            snapshot.dailyCostUsd = dailyCost;
+        }
+        const goal = this.getGoalStateSnapshot();
+        if (goal) {
+            snapshot.activeGoal = {
+                goalId: goal.goalId,
+                status: goal.status,
+                openRequirements: goal.requirements.filter((requirement) => requirement.status === "open").length,
+                stallTurns: goal.stallTurns,
+            };
+        }
+        // Real live count from the lane tracker — never inferred from historical snapshots. Absent
+        // while zero, matching the presence-means-signal convention of the sibling fields.
+        const activeLaneCount = this._laneTracker.getActiveCount();
+        if (activeLaneCount > 0) {
+            snapshot.activeLaneCount = activeLaneCount;
+        }
+        return snapshot;
+    }
+    /**
+     * Aggregate an effectiveness/autonomy dashboard: what Pi has actually been doing (recent
+     * route choices, latest gate outcome, cost, and any research/delegation/learning/goal
+     * activity). Read-only — combines existing session-log getters, never mutates state or
+     * recomputes a route/gate decision.
+     */
+    getAutonomyDiagnosticSnapshot(options) {
+        const maxEntriesPerFamily = options?.maxEntriesPerFamily ?? 10;
+        const snapshot = {};
+        const goal = this.getGoalStateSnapshot();
+        const recentDecisions = getRecentModelRouterDecisions(this.sessionManager.getEntries(), maxEntriesPerFamily);
+        if (recentDecisions.length > 0) {
+            snapshot.routes = recentDecisions.map((decision) => ({
+                title: decision.route.tier,
+                summary: decision.routedModel,
+                reasonCode: decision.route.reasonCode,
+                metadata: { risk: decision.route.risk, outcome: decision.outcome, intent: decision.intent },
+            }));
+        }
+        if (this._lastAutonomyGateOutcome) {
+            const gate = this._lastAutonomyGateOutcome;
+            snapshot.gates = [
+                {
+                    title: gate.gate,
+                    summary: gate.message,
+                    reasonCode: gate.reasonCode,
+                    metadata: { outcome: gate.outcome, reversible: gate.reversible },
+                },
+            ];
+        }
+        const costs = [];
+        const currentCostForDiagnostics = this.getSessionStats().cost;
+        if (currentCostForDiagnostics > 0) {
+            costs.push({ title: "current", summary: `$${currentCostForDiagnostics.toFixed(4)}` });
+        }
+        const spawnedCost = this.getSpawnedUsage().cost;
+        if (spawnedCost > 0)
+            costs.push({ title: "spawned", summary: `$${spawnedCost.toFixed(4)}` });
+        const dailyCostForDiagnostics = this.getDailyUsageTotals?.()?.totalCost;
+        if (dailyCostForDiagnostics !== undefined && dailyCostForDiagnostics > 0) {
+            costs.push({ title: "daily", summary: `$${dailyCostForDiagnostics.toFixed(4)}` });
+        }
+        if (costs.length > 0)
+            snapshot.costs = costs;
+        const researchEntries = [];
+        const researchLaneRecords = getLaneRecordSnapshots(this.sessionManager.getEntries()).filter((record) => record.type === "research");
+        for (const record of researchLaneRecords.slice(-maxEntriesPerFamily)) {
+            researchEntries.push({
+                title: `Lane ${record.laneId} (${record.status})`,
+                reasonCode: record.reasonCode,
+                metadata: {
+                    costUsd: record.costUsd,
+                    startedAt: record.startedAt,
+                    completedAt: record.completedAt,
+                    goalId: record.goalId,
+                },
+            });
+        }
+        for (const bundle of this.getEvidenceBundleSnapshots().slice(-maxEntriesPerFamily)) {
+            researchEntries.push({
+                title: `Research: ${bundle.query}`,
+                metadata: { sourceCount: bundle.sources.length, findingCount: bundle.findings.length },
+            });
+        }
+        if (this._lastResearchLaneSkipReason) {
+            researchEntries.push({ title: "Last skip", reasonCode: this._lastResearchLaneSkipReason });
+        }
+        if (researchEntries.length > 0) {
+            snapshot.research = researchEntries;
+        }
+        const delegationEntries = [];
+        const workerLaneRecords = getLaneRecordSnapshots(this.sessionManager.getEntries()).filter((record) => record.type === "worker");
+        for (const record of workerLaneRecords.slice(-maxEntriesPerFamily)) {
+            delegationEntries.push({
+                title: `Lane ${record.laneId} (${record.status})`,
+                reasonCode: record.reasonCode,
+                metadata: { costUsd: record.costUsd, startedAt: record.startedAt, completedAt: record.completedAt },
+            });
+        }
+        const workerResults = this.getWorkerResultSnapshots();
+        for (const result of workerResults.slice(-maxEntriesPerFamily)) {
+            delegationEntries.push({
+                title: `Worker ${result.requestId} (${result.status})`,
+                summary: result.summary,
+                metadata: {
+                    changedFileCount: result.changedFiles.length,
+                    blockerCount: result.blockers?.length ?? 0,
+                    usageReportId: result.usageReportId,
+                },
+            });
+        }
+        if (delegationEntries.length > 0) {
+            snapshot.delegation = delegationEntries;
+        }
+        const learningEntries = [];
+        const learningDecisions = this.getLearningDecisionSnapshots();
+        for (const decision of learningDecisions.slice(-maxEntriesPerFamily)) {
+            learningEntries.push({
+                title: `Learning (${decision.kind})`,
+                summary: decision.summary,
+                reasonCode: decision.reasonCode,
+                metadata: { confidence: decision.confidence, requiresApproval: decision.requiresApproval },
+            });
+        }
+        for (const audit of this.getLearningAuditRecords().slice(-maxEntriesPerFamily)) {
+            learningEntries.push({
+                title: `Audit ${audit.id} (${audit.action})`,
+                summary: audit.summary,
+                reasonCode: audit.reasonCode,
+                metadata: { layer: audit.layer, proposalId: audit.proposalId, rollbackOf: audit.rollbackOf },
+            });
+        }
+        if (learningEntries.length > 0) {
+            snapshot.learning = learningEntries;
+        }
+        if (goal) {
+            snapshot.goals = [
+                {
+                    title: `Goal ${goal.goalId}`,
+                    summary: goal.userGoal,
+                    reasonCode: goal.status,
+                    metadata: {
+                        openRequirementCount: goal.requirements.filter((requirement) => requirement.status === "open").length,
+                        stallTurns: goal.stallTurns,
+                        blockedReason: goal.blockedReason,
+                    },
+                },
+            ];
+        }
+        return snapshot;
+    }
     createReplacedSessionContext() {
         const context = Object.defineProperties({}, Object.getOwnPropertyDescriptors(this._extensionRunner.createCommandContext()));
         context.sendMessage = (message, options) => this.sendCustomMessage(message, options);