@prestyj/cli 5.28.0 → 5.29.0

package/dist/core/agent-session.js

@@ -1,6 +1,7 @@
-import { agentLoop, isAbortError, isUsageLimitError, } from "@prestyj/agent";
+import { agentLoop, isAbortError, isUsageLimitError, repairToolPairingAdjacent, } from "@prestyj/agent";
 import { ProviderError, stream, } from "@prestyj/ai";
 import { EventBus } from "./event-bus.js";
+import { flagUntrustedToolResult } from "./injection-detect.js";
 import { COMPLETION_REVIEW_STATE_KIND, } from "./completion-review.js";
 import { SlashCommandRegistry, createBuiltinCommands, } from "./slash-commands.js";
 import { PROMPT_COMMANDS, getPromptCommand } from "./prompt-commands.js";
@@ -23,8 +24,10 @@ import { ensureAppDirs } from "../config.js";
 import { buildSubAgentSystemPrompt, buildSystemPrompt, } from "../system-prompt.js";
 import { createTools, createWebSearchTool, } from "../tools/index.js";
 import { partitionToolsByTier } from "../tools/tool-tiers.js";
+import { formatImpactForVerification } from "./test-impact.js";
+import { autoBackgroundedId } from "../tools/bash.js";
 import { buildProcessCompletionFollowUp } from "./process-gate.js";
-import { buildSubAgentCompletionFollowUp, } from "./subagent-manager.js";
+import { buildSubAgentCompletionFollowUp } from "./subagent-manager.js";
 import { applyAsyncSubagentPolicy } from "./subagent-policy.js";
 import { z } from "zod";
 import { MCPClientManager, getAllMcpServers } from "./mcp/index.js";
@@ -36,27 +39,31 @@ import { createToolSearchTool } from "../tools/tool-search.js";
 import { createSessionStatsTool } from "../tools/session-stats.js";
 import { createDiagnoseCommand, isInternalDiagnosticsEnabled, SessionDiagnosticsRecorder, } from "./internal-diagnostics.js";
 import { log } from "./logger.js";
-import { setEstimatorModel, calibrateEstimatorFromUsage } from "./compaction/token-estimator.js";
+import { CacheDiagnostics } from "./cache-diagnostics.js";
+import { assessCacheExpiry, resolveCacheTtl } from "./cache-expiry.js";
+import { setEstimatorModel, calibrateEstimatorFromUsage, estimateConversationTokens, } from "./compaction/token-estimator.js";
 import { calculateActiveContextTokens } from "./compaction/active-context.js";
 import { resolveCompactionPolicy } from "./compaction/policy.js";
+import { decidePlanStepCompaction, DEFAULT_CACHE_WRITE_READ_RATIO, PLAN_STEP_KEEP_TOKENS, } from "./compaction/plan-step-policy.js";
+import { extractPlanSteps, findCompletedMarkers } from "../utils/plan-steps.js";
+import { readFileSync } from "node:fs";
 import { clampThinkingForPlanMode } from "./thinking-level.js";
 import { pruneStaleToolResults } from "./compaction/tool-result-pruner.js";
 import { discoverAgents } from "./agents.js";
 import { enhancePrompt } from "../utils/prompt-enhancer.js";
 import { detectLanguages, detectProjectStack } from "./language-detector.js";
-import { evaluateIdealReview, buildIdealReviewMessage, buildReviewCoverageEscalationMessage, buildReviewCoverageMessage, MAX_REVIEW_COVERAGE_INJECTIONS, withReviewCoverageRequirements, detectTestDrift, ReviewCoverageTracker, } from "./ideal-review.js";
 import { evaluateLoopBreak, buildLoopBreakMessage, CycleDetector, ToolCallProgressTracker, detectTextRepetition, } from "./loop-breaker.js";
 import { buildRegroundingMessage, requestTextForRegrounding } from "./regrounding.js";
 import { buildSemanticLoopJudgePrompt, buildSemanticLoopMessage, MAX_SEMANTIC_LOOP_CALLS, parseSemanticLoopVerdict, shouldRunSemanticLoopCheck, SEMANTIC_LOOP_JUDGE_TIMEOUT_MS, withJudgeTimeout, } from "./semantic-loop-check.js";
-import { buildIndependentReviewMessage, buildReviewerTask, INDEPENDENT_REVIEW_SCORE_THRESHOLD, parseReviewerFindings, REVIEWER_TOOLS, REVIEWER_WAIT_MS, } from "./ideal-review-subagent.js";
 import { buildEnvDeltaMessage } from "./env-delta.js";
 import { wrapSteeringText, buildNotificationSteeringText, STEERING_PREFIX } from "./steering.js";
 import { AgentNotificationQueue } from "./agent-notifications.js";
-import { VerificationGate, extractAddedLines, isCheckOwnFile, isCodeFilePath, VERIFICATION_STATE_KIND, isVerificationCommand, } from "./verification-gate.js";
+import { VerificationGate, isCheckOwnFile, extractAddedLines, isCodeFilePath, VERIFICATION_STATE_KIND, isVerificationCommand, } from "./verification-gate.js";
 import { classifyVerificationCommand } from "./verification-evidence.js";
 import { captureVerificationSnapshot } from "./verification-snapshot.js";
 import { findUserSessionPrompt, getUserSessionPrompt } from "./session-preview.js";
 import { normalizeMessageImages } from "./message-images.js";
+import { loadStreamRules } from "./stream-rules.js";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
@@ -66,14 +73,6 @@ import path from "node:path";
  * progressing — refuse to extend its turn budget.
  */
 const TURN_EXTENSION_MAX_FAILURE_RATIO = 0.5;
-/** Terminal subagent states — mirrors SubAgentManager's private isTerminal. */
-function isTerminalSubAgentState(state) {
-    return (state === "completed" ||
-        state === "failed" ||
-        state === "interrupted" ||
-        state === "closed" ||
-        state === "reaped");
-}
 // ── Tool-result policy ─────────────────────────────────────
 /** Resolve the per-result cap passed to the agent loop for the active transport. */
 export function resolveSessionToolResultCharLimit(model, provider, accountId) {
@@ -130,6 +129,7 @@ export class AgentSession {
     // transcript rows the live run showed.
     appMarkers = [];
     turnMetrics = [];
+    cacheDiagnostics = new CacheDiagnostics();
     /** Internal-only (EZ_INTERNAL): live per-session cost/reliability recorder.
      * Absent entirely in public builds — see core/internal-diagnostics.ts. */
     diagnosticsRecorder;
@@ -138,20 +138,16 @@ export class AgentSession {
      *  creation). Called from switchModel so video-capable models get the
      *  read-tool's native-video path after a mid-session model change. */
     rebuildReadTool;
+    /** Forgets every file read; called whenever the conversation is replaced or
+     *  rewound, so the model must re-read a file before changing it. */
+    clearReadTracker;
+    recordBashReads;
     skills = [];
     cacheKeyLogged = false;
     // ── Self-correction hook state (mirrors the TUI's useAgentLoop refs) ──
     // Reset at the start of every run; observed from the event stream; read by
-    // the loop-break (mid-loop) and ideal-review (pre-stop) callbacks.
-    hookStats = {
-        changedLines: 0,
-        toolCalls: 0,
-        toolFailures: 0,
-        turns: 0,
-        writeCalls: 0,
-        editCalls: 0,
-        bashCalls: 0,
-    };
+    // the loop-break (mid-loop) callback.
+    hookStats = { toolCalls: 0, toolFailures: 0, turns: 0 };
     hookText = "";
     hookConsecutiveFailures = 0;
     hookRepeatedNoProgressCalls = 0;
@@ -161,20 +157,6 @@ export class AgentSession {
     hookFileEditCounts = new Map();
     hookToolCalls = new Map();
     backgroundVerification = new Map();
-    idealReviewPhase = "idle";
-    /** Runtime-only suppression while Nolan owns verification in autopilot mode. */
-    idealReviewSuppressed = false;
-    /** Mirror of the last `hook_armed` value broadcast this run, so the event
-     *  fires only on a real edge. */
-    idealReviewArmed = false;
-    /** Cached test-drift probe, keyed by the size of the edited-file set. Drift
-     *  depends only on WHICH files were edited and that set only grows, so this
-     *  keeps the arming check off the filesystem on most tool results — the probe
-     *  is several sync existsSync calls per edited file. */
-    idealDriftProbe = null;
-    reviewCoverage;
-    /** Coverage follow-ups spent this run, capped by MAX_REVIEW_COVERAGE_INJECTIONS. */
-    reviewCoverageInjected = 0;
     /** 0 = none; 1 = first nudge sent; 2 = final stop-and-report injected. */
     loopBreakInjected = 0;
     regroundingInjected = false;
@@ -184,8 +166,6 @@ export class AgentSession {
      *  injection at the next steering poll; judge failures fail open (no
      *  injection) and still consume budget + cooldown. */
     semanticLoop = { checksUsed: 0, lastCheckTurn: 0, pending: false, verdict: null, injected: false };
-    /** Independent Ideal reviewer spawned once per run (score-gated). */
-    independentReviewStarted = false;
     /**
      * The environment as the cached system prompt currently describes it.
      * Re-recorded on every prompt build, so a rebuild (e.g. `/add-dir`) needs no
@@ -196,11 +176,12 @@ export class AgentSession {
     runStartedAt = 0;
     /** Gate injections spent this run, capped by MAX_PROCESS_GATE_INJECTIONS. */
     processGateInjected = 0;
-    /** Verification gate: code edited this run, nothing proved it since. */
+    /** Verification gate: code edited this run, nothing proved it since. Always
+     *  tracks evidence for run status; the `verificationGateEnabled` setting
+     *  decides whether an unverified stop is also continued once. */
     verificationGate = new VerificationGate();
-    /** Mirror of the last verification `hook_armed` value, so the event fires
-     *  only on a real edge. */
-    verificationArmed = false;
+    /** Mirror of the last `hook_armed` value, so the event fires only on an edge. */
+    preFinalArmed = false;
     compactionOccurred = false;
     /**
      * Re-grounding carry-over for post-turn compaction. `resetHookState` clears
@@ -213,6 +194,25 @@ export class AgentSession {
     postTurnCompaction;
     lastCompactionCompacted = false;
     compactionRetryAfter = 0;
+    /**
+     * SoL-Pi plan-step compaction bookkeeping (see compaction/plan-step-policy.ts).
+     * Step progress comes from `[DONE:n]` markers in assistant text — the same
+     * contract the approved-plan UI tracks.
+     */
+    planStepState = {
+        planPath: undefined,
+        scanIndex: 0,
+        doneSteps: new Set(),
+        requestsInCompletedSteps: 0,
+        requestsThisStep: 0,
+        requests: 0,
+        grownTokens: 0,
+        lastContextTokens: 0,
+        compactions: 0,
+        writeCostBalance: 0,
+        savingPerRequest: 0,
+        requestsSinceLastCompaction: 0,
+    };
     /** A restored oversized checkpoint must be canonicalized before its first prompt is persisted. */
     deferredCompactionPending = false;
     /** Latest provider count, anchored to the assistant response it measured. */
@@ -228,8 +228,12 @@ export class AgentSession {
     // different message (or past the end) by the time the cancel arrives.
     userQueue = [];
     queueSeq = 0;
+    /** Instant interrupt: the running loop's preempt listeners, fired on queueMessage. */
+    steeringListeners = new Set();
     processManager;
     lspManager;
+    testImpact;
+    debugManager;
     subAgentManager;
     /**
      * Out-of-band push notifications (finished children, background-process
@@ -333,7 +337,6 @@ export class AgentSession {
         this.provider = options.provider;
         this.model = options.model;
         this.cwd = options.cwd;
-        this.reviewCoverage = new ReviewCoverageTracker(this.cwd);
         this.baseUrl = options.baseUrl;
         this.maxTokens = this.resolveMaxTokens(options.model);
         this.thinkingLevel = options.thinkingLevel;
@@ -399,7 +402,7 @@ export class AgentSession {
             : this.opts.globalSubagents
                 ? await discoverAgents({ globalAgentsDir: paths.agentsDir })
                 : [];
-        const { tools: builtInTools, processManager, rebuildReadTool, lspManager, subAgentManager, } = await createTools(this.cwd, {
+        const { tools: builtInTools, processManager, rebuildReadTool, clearReadTracker, recordBashReads, lspManager, testImpact, debugManager, subAgentManager, } = await createTools(this.cwd, {
             agents,
             skills: this.skills,
             contextLimits: this.contextLimits,
@@ -430,17 +433,14 @@ export class AgentSession {
             }),
             getUseExternalGrep: () => this.settingsManager.get("grepUseRipgrep"),
             authStorage: this.authStorage,
-            onFileRead: (filePath) => this.reviewCoverage.recordRead(filePath),
             onFileMutated: (filePath) => {
                 const relative = path.relative(this.cwd, filePath) || path.basename(filePath);
                 this.hookFileEditCounts.set(relative, (this.hookFileEditCounts.get(relative) ?? 0) + 1);
-                this.reviewCoverage.recordChanged(filePath);
             },
             // Lazy — sessionId/model/provider can change after createTools() runs, so
             // sub-agent spawns read the current parent state at execution time.
             getProvider: () => this.provider,
             getModel: () => this.model,
-            getThinkingLevel: () => this.thinkingLevel,
             getBaseUrl: () => this.baseUrl,
             getCacheKey: () => this.getPromptCacheKey(),
             getMaxPerModel: () => this.settingsManager.get("subagentMaxPerModel"),
@@ -486,11 +486,16 @@ export class AgentSession {
                 this.mcpCatalog ??= new DeferredToolCatalog(this.contextLimits);
                 this.mcpCatalog.add(deferred);
                 this.ensureToolSearchTool();
+                this.promoteWaitAgentAfterSpawn();
             }
         }
         this.rebuildReadTool = rebuildReadTool;
+        this.clearReadTracker = clearReadTracker;
+        this.recordBashReads = recordBashReads;
         this.processManager = processManager;
         this.lspManager = lspManager;
+        this.testImpact = testImpact;
+        this.debugManager = debugManager;
         this.subAgentManager = subAgentManager;
         this.bindManagerCancellation(this.opts.signal);
         // Connect MCP servers. Child sessions skip user-configured servers to avoid
@@ -775,6 +780,29 @@ export class AgentSession {
                 : { serverName, ok: false, error: outcome.error };
         }, this.contextLimits));
     }
+    /**
+     * `wait_agent` is deferred, yet nearly every `spawn_agent` is followed by it,
+     * so the model spent a whole turn on `tool_search` just to load it (bench 41:
+     * ~6 s per fan-out). Promote it as soon as a spawn succeeds instead: the tool
+     * list grows exactly as it would after that `tool_search`, one turn earlier,
+     * and sessions that never spawn keep the smaller prefix.
+     */
+    promoteWaitAgentAfterSpawn() {
+        const index = this.tools.findIndex((t) => t.name === "spawn_agent");
+        const spawn = index >= 0 ? this.tools[index] : undefined;
+        if (!spawn)
+            return;
+        this.tools[index] = {
+            ...spawn,
+            execute: async (args, context) => {
+                const result = await spawn.execute(args, context);
+                if (!this.tools.some((t) => t.name === "wait_agent")) {
+                    this.tools.push(...(this.mcpCatalog?.promote(["wait_agent"]) ?? []));
+                }
+                return result;
+            },
+        };
+    }
     /** Append tools, replacing any same-named entry (cached stub → live tool). */
     replaceOrPushTools(tools) {
         for (const tool of tools) {
@@ -905,12 +933,15 @@ export class AgentSession {
     }
     /**
      * Process user input. Handles slash commands or runs agent loop.
+     * `capThinking` holds reasoning effort at the plan-mode ceiling for this
+     * prompt — for turns that must answer quickly from what is already known.
      */
     async prompt(content, provenance = {
         source: "human",
         kind: "prompt",
         visibility: "transcript",
     }, options = {}) {
+        this.prewarmController?.abort();
         await this.settlePostTurnCompaction();
         await this.adoptDeferredCheckpointBeforePrompt();
         const slash = await this.resolveSlashInput(content);
@@ -946,6 +977,7 @@ export class AgentSession {
      * attachments are always a direct conversational turn.
      */
     async promptWithAttachments(text, attachments) {
+        this.prewarmController?.abort();
         await this.settlePostTurnCompaction();
         await this.adoptDeferredCheckpointBeforePrompt();
         const parts = this.buildAttachmentParts(text, attachments);
@@ -1044,15 +1076,7 @@ export class AgentSession {
     resetHookState(originalRequest) {
         this.opts.completionReview?.begin(originalRequest);
         this.lspManager?.clearPendingDiagnostics();
-        this.hookStats = {
-            changedLines: 0,
-            toolCalls: 0,
-            toolFailures: 0,
-            turns: 0,
-            writeCalls: 0,
-            editCalls: 0,
-            bashCalls: 0,
-        };
+        this.hookStats = { toolCalls: 0, toolFailures: 0, turns: 0 };
         this.hookText = "";
         this.hookConsecutiveFailures = 0;
         this.hookRepeatedNoProgressCalls = 0;
@@ -1061,13 +1085,6 @@ export class AgentSession {
         this.hookCyclicPattern = null;
         this.hookFileEditCounts.clear();
         this.hookToolCalls.clear();
-        this.reviewCoverage.reset();
-        this.reviewCoverageInjected = 0;
-        this.idealReviewPhase = "idle";
-        // No event here: clients reset their own hold on run_start.
-        this.idealReviewArmed = false;
-        this.verificationArmed = false;
-        this.idealDriftProbe = null;
         this.loopBreakInjected = 0;
         this.regroundingInjected = false;
         this.hookRecentCalls = [];
@@ -1078,7 +1095,6 @@ export class AgentSession {
             verdict: null,
             injected: false,
         };
-        this.independentReviewStarted = false;
         this.runStartedAt = Date.now();
         this.processGateInjected = 0;
         this.verificationGate.beginRun();
@@ -1099,8 +1115,8 @@ export class AgentSession {
     }
     /**
      * Fold one agent event into the hook stat accumulators. Pure bookkeeping —
-     * the same signals the TUI's useAgentLoop collects, so the loop-break and
-     * ideal-review decisions match across the CLI and the app.
+     * the same signals the TUI's useAgentLoop collects, so loop-break decisions
+     * match across the CLI and the app.
      */
     async trackHookEvent(event) {
         if (this.opts.completionReview) {
@@ -1145,7 +1161,14 @@ export class AgentSession {
                         if (call.sourceSnapshot === null)
                             this.verificationGate.requireFreshVerification(true, event.args.command);
                     }
-                    else {
+                    else if ((classification.accepted && event.args.persist !== true) ||
+                        (!classification.accepted && classification.mayMutate)) {
+                        // Flag the workspace unknown only when tool_call_end can resolve
+                        // it: a bounded check records pass/fail, a file-rewriting command
+                        // bumps the revision. An unrecognized read-only check (`biome ci`)
+                        // or a persistent-shell run records nothing at the end, so
+                        // flagging it left verified work Unverified forever — and
+                        // autopilot silently refused every later turn.
                         this.verificationGate.requireFreshVerification(!classification.accepted && classification.mayMutate, event.args.command);
                     }
                     await this.persistVerificationState();
@@ -1159,12 +1182,6 @@ export class AgentSession {
                 this.hookStats.toolCalls += 1;
                 if (event.isError)
                     this.hookStats.toolFailures += 1;
-                if (name === "write")
-                    this.hookStats.writeCalls += 1;
-                if (name === "edit")
-                    this.hookStats.editCalls += 1;
-                if (name === "bash")
-                    this.hookStats.bashCalls += 1;
                 this.hookConsecutiveFailures = event.isError ? this.hookConsecutiveFailures + 1 : 0;
                 this.hookRepeatedNoProgressCalls = this.hookProgressTracker.record(name, args, event.result, event.isError);
                 this.hookCyclicPattern = this.hookCycleDetector.record(name, args, event.result, event.isError);
@@ -1181,12 +1198,6 @@ export class AgentSession {
                 if (this.hookRecentCalls.length > MAX_SEMANTIC_LOOP_CALLS) {
                     this.hookRecentCalls.splice(0, this.hookRecentCalls.length - MAX_SEMANTIC_LOOP_CALLS);
                 }
-                if (name === "edit" && !event.isError) {
-                    const diff = event.details?.diff ?? event.result;
-                    const added = (diff.match(/^\+[^+]/gm) ?? []).length;
-                    const removed = (diff.match(/^-[^-]/gm) ?? []).length;
-                    this.hookStats.changedLines += added + removed;
-                }
                 // Only host-observed successful mutations and trustworthy check results
                 // affect approval. The model's text is never evidence.
                 let verificationChanged = false;
@@ -1209,8 +1220,13 @@ export class AgentSession {
                     const command = typeof args.command === "string" ? args.command : "";
                     const classification = classifyVerificationCommand(command);
                     if (classification.accepted || classification.snapshotEligible) {
-                        if (args.run_in_background === true && !event.isError && args.persist !== true) {
-                            const id = /^ID:\s*(\S+)/m.exec(event.result)?.[1];
+                        // A foreground check that outlived the default budget was moved to
+                        // the background, not failed: track it to its real exit the same way.
+                        const autoBackgroundId = event.isError ? undefined : autoBackgroundedId(event.result);
+                        if ((autoBackgroundId !== undefined || args.run_in_background === true) &&
+                            !event.isError &&
+                            args.persist !== true) {
+                            const id = autoBackgroundId ?? /^ID:\s*(\S+)/m.exec(event.result)?.[1];
                             // No parseable ID means the check cannot be tracked to a real exit
                             // code — no evidence either way. Recording a FAILURE here made
                             // every later green run of a different spelling look owed.
@@ -1281,10 +1297,35 @@ export class AgentSession {
                 // Tool results for this step are in the array and their side effects
                 // already hit the filesystem. Flushing here is what makes a crash lose
                 // at most the in-flight step instead of the entire turn.
+                await this.creditBashReads();
                 await this.flushPendingMessages();
                 break;
         }
     }
+    /**
+     * Count full-file `cat` output from the step that just finished as reads, so
+     * an edit after `cat` does not cost a second read. Uses the step's results as
+     * stored in the transcript (after per-turn trimming): only bytes the model
+     * actually received count.
+     */
+    async creditBashReads() {
+        if (!this.recordBashReads)
+            return;
+        const messages = this.activeLoopMessages ?? this.messages;
+        const toolMessage = messages.at(-1);
+        const assistant = messages.at(-2);
+        if (toolMessage?.role !== "tool" || assistant?.role !== "assistant")
+            return;
+        if (typeof assistant.content === "string")
+            return;
+        const calls = assistant.content.filter((part) => part.type === "tool_call");
+        try {
+            await this.recordBashReads(calls, toolMessage.content);
+        }
+        catch (err) {
+            log("WARN", "agent-session", "Crediting bash reads failed", { error: String(err) });
+        }
+    }
     /**
      * Append every message added since the last flush to the session file.
      *
@@ -1347,7 +1388,7 @@ export class AgentSession {
         const diagnosticText = this.lspManager?.drainDiagnostics(this.getVerificationProblem() !== null, { deferUnverified: true });
         if (diagnosticText)
             this.eventBus.emit("diagnostics", { text: diagnosticText });
-        this.refreshVerificationArmed();
+        this.refreshHookArming();
         const notified = this.notifications.drain();
         const notificationMessage = notified.length > 0 || diagnosticText
             ? {
@@ -1410,6 +1451,7 @@ export class AgentSession {
         }
         if (this.opts.selfCorrectionHooks === false)
             return null;
+        // Legacy key: the user-facing switch for loop-break and re-grounding nudges.
         if (!this.settingsManager.get("idealReviewEnabled"))
             return null;
         // Deterministic stuck verdict, computed once and shared: the semantic
@@ -1609,76 +1651,6 @@ export class AgentSession {
                 .join("\n")
             : "";
     }
-    /** Independent fresh-context review of the finished work (Codex Guardian
-     *  pattern). Spawns a READ-ONLY child on the ACTIVE model, waits bounded,
-     * and returns findings for the acting agent to address — or nothing when
-     *  the review passes, is unavailable, or fails (in-thread review remains the
-     *  fallback; the feature degrades, never blocks).
-     *
-     *  Runs inside the pre-stop poll, so the candidate final answer is already
-     *  held by arming and this wait cannot race a streamed answer. */
-    async runIndependentReview(decision) {
-        if (!this.subAgentManager)
-            return [];
-        if (this.independentReviewStarted)
-            return [];
-        // An allow-listed session (a subagent worker itself) must not spawn
-        // harness-owned grandchildren the tool policy never granted.
-        if (this.opts.allowedTools && !this.opts.allowedTools.includes("spawn_agent"))
-            return [];
-        if (decision.score < INDEPENDENT_REVIEW_SCORE_THRESHOLD)
-            return [];
-        this.independentReviewStarted = true;
-        const taskName = `ideal-reviewer-${Math.random().toString(36).slice(2, 8)}`;
-        let agentId;
-        try {
-            const task = buildReviewerTask({
-                originalRequest: this.originalRequest,
-                changedFiles: [...this.hookFileEditCounts.keys()],
-                stats: this.hookStats,
-                triggerReasons: decision.reasons,
-            });
-            // Active model forced at spawn time — never routed to a fast/review model.
-            const snapshot = await this.subAgentManager.spawn(taskName, task, undefined, {
-                model: this.model,
-                tools: REVIEWER_TOOLS,
-            });
-            agentId = snapshot.agent_id;
-            const waited = await this.subAgentManager.wait([agentId], "all", REVIEWER_WAIT_MS);
-            const agent = waited.agents[0];
-            if (!agent || !isTerminalSubAgentState(agent.state)) {
-                // Timeout: collect the straggler so the completion gate cannot fire on
-                // it later, then fall back to the in-thread review.
-                await this.subAgentManager.interrupt(agentId, true).catch(() => { });
-                log("WARN", "ideal", "Independent reviewer timed out; falling back to in-thread review", {
-                    agentId,
-                });
-                return [];
-            }
-            const findings = parseReviewerFindings(agent.output ?? "");
-            if (!findings) {
-                log("WARN", "ideal", "Independent reviewer output unparseable; falling back", { agentId });
-                return [];
-            }
-            if (findings.clean) {
-                log("INFO", "ideal", "Independent reviewer verdict: clean", { agentId });
-                return [];
-            }
-            log("INFO", "ideal", "Independent reviewer flagged findings", {
-                agentId,
-                count: String(findings.findings.length),
-            });
-            return [buildIndependentReviewMessage(findings.findings)];
-        }
-        catch (error) {
-            if (agentId)
-                await this.subAgentManager.interrupt(agentId, true).catch(() => { });
-            log("WARN", "ideal", "Independent reviewer failed; falling back to in-thread review", {
-                error: error instanceof Error ? error.message : String(error),
-            });
-            return [];
-        }
-    }
     /**
      * Turn-budget extension gate. The loop consults this instead of stopping
      * mid-task when it exhausts `maxTurns`. Grant ONLY on evidence of progress —
@@ -1712,98 +1684,45 @@ export class AgentSession {
         });
         return granted;
     }
-    /**
-     * Would the stop AFTER the current turn inject the Ideal review? Same inputs
-     * as the pre-stop gate below, evaluated early so clients know a candidate
-     * final answer is a review draft BEFORE it streams.
-     *
-     * The turn count is looked ahead by one on purpose. `hookStats.turns` only
-     * advances at `turn_end`, so while the model is writing the draft the counter
-     * still reads the PREVIOUS turn; the real gate sees one more. Without the
-     * lookahead a run sitting on score 3 crosses to 4 on the draft's own
-     * `turn_end` — after the text already streamed — which is precisely the
-     * appear-then-vanish flash. Over-arming by one turn point costs only live
-     * token streaming on a final answer that then shows whole; under-arming costs
-     * the flash, so this errs toward arming.
-     */
-    wouldInjectIdealReview() {
-        if (this.opts.completionReview?.armed)
-            return true;
-        if (this.opts.selfCorrectionHooks === false || this.idealReviewSuppressed)
-            return false;
-        // Mid-review a stop still injects: the coverage follow-up while files are
-        // unread, or its escalation once the budget is spent. Both make the model
-        // answer again, so the candidate answer is a draft exactly as it is before
-        // the review starts — without arming here it paints and the reviewed answer
-        // lands under it as a duplicate.
-        if (this.idealReviewPhase === "reviewing") {
-            return this.reviewCoverage.evidence().missing.length > 0;
-        }
-        if (this.idealReviewPhase !== "idle")
-            return false;
-        if (!this.settingsManager.get("idealReviewEnabled"))
+    /** Is the pre-stop verification gate active for this session? Off by the
+     *  `verificationGateEnabled` setting, by `selfCorrectionHooks: false`, and for
+     *  allow-listed sessions that cannot run commands at all. */
+    verificationGateActive() {
+        if (this.opts.selfCorrectionHooks === false)
             return false;
-        if (evaluateIdealReview({ ...this.hookStats, turns: this.hookStats.turns + 1 }).shouldReview) {
-            return true;
-        }
-        const files = this.hookFileEditCounts.size;
-        if (files === 0)
+        if (!this.settingsManager.get("verificationGateEnabled"))
             return false;
-        if (this.idealDriftProbe?.files !== files) {
-            this.idealDriftProbe = {
-                files,
-                drifted: detectTestDrift(this.hookFileEditCounts.keys(), this.cwd).length > 0,
-            };
-        }
-        return this.idealDriftProbe.drifted;
+        return !this.opts.allowedTools || this.opts.allowedTools.includes("bash");
     }
-    /** Would a stop right now inject the verification gate? Same conditions as
-     *  the pre-stop branch below, so arming and injection cannot disagree. */
-    wouldInjectVerification() {
+    /** Would a stop right now inject a pre-final follow-up? Queued LSP
+     *  diagnostics (real errors injected below), a mode-owned completion review,
+     *  or the verification gate can, so clients hold the candidate answer only
+     *  then. Same conditions as the pre-stop branch, so arming and injection
+     *  cannot disagree. */
+    wouldInjectBeforeFinal() {
+        if (this.opts.completionReview?.armed)
+            return true;
         if (this.lspManager?.hasQueuedDiagnostics())
             return true;
-        if (this.opts.selfCorrectionHooks === false)
-            return false;
-        if (!this.settingsManager.get("verificationGateEnabled"))
-            return false;
-        if (this.opts.allowedTools && !this.opts.allowedTools.includes("bash"))
-            return false;
-        return this.verificationGate.willInject();
+        return this.verificationGateActive() && this.verificationGate.willInject();
     }
     /** Broadcast pre-final hook arming on change. Both edges matter: armed=false
-     *  after the hook fires is what lets a client stream the REVIEWED final
-     *  answer live again.
-     *
-     *  Callable before `initialize()`: the sidecar sets Nolan's review suppression
-     *  on a freshly constructed session, and every arming predicate below reads
-     *  settings that `initialize()` has not loaded yet. Nothing can be armed
-     *  before the session can run a turn, and the first `tool_result`/`turn_end`
-     *  recomputes both edges — so skipping is the correct answer, not a patch. */
+     *  after the hook fires is what lets a client stream the final answer live
+     *  again. Callable before `initialize()`, when no manager exists yet. */
     refreshHookArming() {
+        // Before `initialize()` settings are not loaded, so nothing can be armed.
         if (!this.settingsManager)
             return;
-        this.refreshIdealReviewArmed();
-        this.refreshVerificationArmed();
-    }
-    refreshVerificationArmed() {
-        if (!this.settingsManager)
+        const armed = this.wouldInjectBeforeFinal();
+        if (armed === this.preFinalArmed)
             return;
-        const armed = this.wouldInjectVerification();
-        if (armed === this.verificationArmed)
-            return;
-        this.verificationArmed = armed;
+        this.preFinalArmed = armed;
         this.eventBus.emit("hook_armed", { kind: "verification", armed });
     }
-    refreshIdealReviewArmed() {
-        const armed = this.wouldInjectIdealReview();
-        if (armed === this.idealReviewArmed)
-            return;
-        this.idealReviewArmed = armed;
-        this.eventBus.emit("hook_armed", { kind: "ideal", armed });
-    }
     /**
-     * Pre-stop Ideal review phase machine. Once review starts, completion is
-     * blocked until harness-owned post-injection reads cover every changed file.
+     * Pre-stop follow-ups: LSP errors, unread child agents and background
+     * processes, the verification gate (when `verificationGateEnabled`), and a
+     * mode-owned completion review.
      */
     async getHookFollowUpMessages() {
         // Exit notifications and task_output refer to the same host process record.
@@ -1816,14 +1735,15 @@ export class AgentSession {
         if (backgroundChanged)
             await this.persistVerificationState();
         // Edits return immediately; only the completion boundary waits for remaining
-        // checks. Queued timeouts stay explicitly unverified, never a false all-clear.
+        // checks. Queued timeouts stay explicitly unverified, never a false
+        // all-clear; they join the verification demand below when the gate is on.
         await this.lspManager?.flushDiagnostics(this.opts.signal);
         if (this.opts.signal?.aborted)
             return null;
-        const diagnosticText = this.lspManager?.drainDiagnostics(this.getVerificationProblem() !== null);
+        const diagnosticText = this.lspManager?.drainDiagnostics(this.verificationGateActive() && this.getVerificationProblem() !== null);
         if (diagnosticText)
             this.eventBus.emit("diagnostics", { text: diagnosticText });
-        this.refreshVerificationArmed();
+        this.refreshHookArming();
         const diagnosticMessages = diagnosticText
             ? [
                 {
@@ -1848,18 +1768,29 @@ export class AgentSession {
             return [...diagnosticMessages, ...processFollowUp];
         }
         // Verification gate: code was edited but nothing verified since the last
-        // edit. Above the Ideal review so checks RUN before the read-based review
-        // starts; off for allow-listed sessions that cannot run commands at all.
-        if (this.opts.selfCorrectionHooks !== false &&
-            this.settingsManager.get("verificationGateEnabled") &&
-            (!this.opts.allowedTools || this.opts.allowedTools.includes("bash"))) {
+        // edit. Off via the `verificationGateEnabled` setting.
+        if (this.verificationGateActive()) {
             const verificationReason = this.verificationGate.pendingReason();
+            const pendingFiles = this.verificationGate.pendingFiles();
             const verificationFollowUp = this.verificationGate.followUp();
             if (verificationFollowUp) {
+                // Name the tests that actually reach the unverified files, with the
+                // command that runs exactly those, so the check is targeted rather
+                // than guessed. Best-effort: no index or no runner leaves it unchanged.
+                if (this.testImpact &&
+                    (verificationReason === "initial" || verificationReason === "recheck")) {
+                    const impactLine = await this.testImpact
+                        .impactFor(pendingFiles)
+                        .then(formatImpactForVerification)
+                        .catch(() => "");
+                    const first = verificationFollowUp[0];
+                    if (impactLine && first?.role === "user" && typeof first.content === "string") {
+                        verificationFollowUp[0] = { ...first, content: first.content + impactLine };
+                    }
+                }
                 log("INFO", "verification-gate", "Injecting verification follow-up", {});
                 // Announce, THEN disarm: clients release held text on disarm, so the
-                // reverse order paints the draft and immediately deletes it — the exact
-                // flash arming exists to prevent.
+                // reverse order paints the draft and immediately deletes it.
                 this.eventBus.emit("hook", {
                     kind: "verification",
                     ...(verificationReason === "tamper"
@@ -1872,7 +1803,7 @@ export class AgentSession {
                 return [...diagnosticMessages, ...verificationFollowUp];
             }
         }
-        // Address real errors before review; unavailable checks share the existing
+        // Address real errors before review; unavailable checks share the
         // verification demand above instead of manufacturing a separate hook.
         if (diagnosticMessages.length > 0)
             return diagnosticMessages;
@@ -1892,131 +1823,24 @@ export class AgentSession {
             }
             this.refreshHookArming();
         }
-        if (this.opts.selfCorrectionHooks === false || this.idealReviewSuppressed)
-            return null;
-        if (this.idealReviewPhase === "reviewing") {
-            const coverage = this.reviewCoverage.evidence();
-            const lspEvidence = this.reviewLspEvidence(coverage.expected);
-            log("INFO", "ideal", "Ideal review coverage check", {
-                covered: coverage.covered,
-                missing: coverage.missing,
-                lspLowConfidence: lspEvidence.lowConfidence,
-                lspMissing: lspEvidence.missing,
-            });
-            if (coverage.missing.length > 0) {
-                // Announce like any other pre-final injection: this follow-up makes the
-                // model answer again, so the answer it interrupts is a draft and the
-                // hook event is what tells clients to discard it. Injecting silently is
-                // what let the pre-coverage answer paint above the reviewed one.
-                this.eventBus.emit("hook", {
-                    kind: "ideal",
-                    coverageExpected: coverage.expected,
-                    coverageMissing: coverage.missing,
-                });
-                if (this.reviewCoverageInjected < MAX_REVIEW_COVERAGE_INJECTIONS) {
-                    this.reviewCoverageInjected += 1;
-                    // Stays armed (coverage is still outstanding) — this call is here so a
-                    // client that missed the earlier edge is armed before the next draft.
-                    this.refreshIdealReviewArmed();
-                    return [
-                        this.withReviewLspEvidence(buildReviewCoverageMessage(coverage.missing), lspEvidence),
-                    ];
-                }
-                // Budget spent: close the gate so the run cannot spin on a file that
-                // never becomes readable, and require the gap be reported to the user.
-                this.idealReviewPhase = "complete";
-                // The gate is shut, so this is the real disarm: the answer to the
-                // escalation is final and streams live.
-                this.refreshIdealReviewArmed();
-                log("INFO", "ideal", "Ideal review coverage escalated after retry budget", {
-                    injected: String(this.reviewCoverageInjected),
-                    missing: coverage.missing,
-                });
-                return [buildReviewCoverageEscalationMessage(coverage.missing)];
-            }
-            this.idealReviewPhase = "complete";
-            return null;
+        return null;
+    }
+    /** Wraps the real run: cancels an in-flight cache prewarm and tracks run
+     *  activity / last real request time for {@link prewarm}. */
+    async runLoop(options = {}) {
+        this.prewarmController?.abort();
+        this.runLoopDepth++;
+        try {
+            await this.runLoopInner(options);
+        }
+        finally {
+            this.runLoopDepth--;
+            this.lastRealRequestAt = Date.now();
         }
-        if (this.idealReviewPhase === "complete")
-            return null;
-        if (!this.settingsManager.get("idealReviewEnabled"))
-            return null;
-        const decision = evaluateIdealReview(this.hookStats);
-        // Test drift fires the review even on a small change the score would skip:
-        // a green-but-stale test is exactly what the volume gate sleeps through.
-        const driftedFiles = detectTestDrift(this.hookFileEditCounts.keys(), this.cwd).slice(0, 5);
-        if (!decision.shouldReview && driftedFiles.length === 0)
-            return null;
-        // Independent reviewer first (async, bounded): its findings ride in the
-        // SAME follow-up batch as the in-thread review + coverage requirements, so
-        // addressing everything still costs one extra turn.
-        this.reviewCoverage.start(this.hookFileEditCounts.keys());
-        this.idealReviewPhase = "reviewing";
-        const coverage = this.reviewCoverage.evidence();
-        const lspEvidence = this.reviewLspEvidence(coverage.expected);
-        this.eventBus.emit("hook", {
-            kind: "ideal",
-            coverageExpected: coverage.expected,
-            coverageMissing: coverage.missing,
-        });
-        // Recompute strictly AFTER the hook event: clients release held text on
-        // disarm, so the reverse order would paint the draft and then delete it —
-        // the exact flash arming exists to prevent. Arming normally PERSISTS here,
-        // because review starts with every changed file uncovered and a stop while
-        // coverage is outstanding injects again. Disarm lands later, on the read
-        // that closes the last gap (or when the retry budget escalates).
-        this.refreshIdealReviewArmed();
-        // Announce the phase before the reviewer starts, not after its bounded wait.
-        const independentMessages = await this.runIndependentReview(decision);
-        log("INFO", "ideal", "Injecting ideal review before final response", {
-            coverageExpected: coverage.expected,
-            coverageMissing: coverage.missing,
-            lspLowConfidence: lspEvidence.lowConfidence,
-            lspMissing: lspEvidence.missing,
-        });
-        return [
-            ...independentMessages,
-            this.withReviewLspEvidence(withReviewCoverageRequirements(buildIdealReviewMessage(decision.reasons, driftedFiles), coverage.missing), lspEvidence),
-        ];
-    }
-    reviewLspEvidence(files) {
-        const lowConfidence = [];
-        const missing = [];
-        for (const filePath of files) {
-            const outcome = this.lspManager?.getLatestOutcome(filePath);
-            if (outcome?.kind === "low_confidence")
-                lowConfidence.push(filePath);
-            else if (outcome?.kind !== "clean" && outcome?.kind !== "diagnostics")
-                missing.push(filePath);
-        }
-        return { lowConfidence, missing };
-    }
-    withReviewLspEvidence(message, evidence) {
-        if (evidence.lowConfidence.length === 0 && evidence.missing.length === 0)
-            return message;
-        const notes = [
-            ...(evidence.lowConfidence.length > 0
-                ? [`Diagnostics are low confidence while indexing: ${evidence.lowConfidence.join(", ")}.`]
-                : []),
-            ...(evidence.missing.length > 0
-                ? [`Diagnostics evidence is unavailable or missing: ${evidence.missing.join(", ")}.`]
-                : []),
-            "Do not describe those files as compiler-clean without other evidence.",
-        ];
-        return {
-            role: "user",
-            provenance: message.provenance,
-            content: `${String(message.content)}\n\n${notes.join(" ")}`,
-        };
     }
     /** Auto-compact if needed, run agent loop with auth retry, and persist messages. */
-    async runLoop(options = {}) {
-        // Languages are re-detected at each task boundary so a project scaffolded
-        // during the previous turn gets its packs; the prompt is rebuilt only when
-        // the set grows, keeping the cached prefix stable otherwise.
-        if (this.refreshActiveLanguages())
-            await this.rebuildSystemPromptInPlace();
-        this.refreshSystemPromptTail();
+    async runLoopInner(options = {}) {
+        await this.prepareSystemPromptForRequest();
         // One-shot cache-key marker per session so turn_end cacheRead numbers
         // in the log can be traced back to a specific routing namespace —
         // particularly useful when sub-agents inherit `parentKey:subagent`.
@@ -2115,11 +1939,14 @@ export class AgentSession {
         // so the new value transparently yields a correctly-identified client.
         let userAgent = this.provider === "anthropic" ? await getClaudeCliUserAgent() : undefined;
         const loopMessages = await this.prepareDynamicContext();
+        // Re-read every run so rule-file edits apply on the next turn; a few small files.
+        const streamRules = await loadStreamRules(this.cwd);
         const runAgentLoop = async (apiKey, accountId, projectId) => {
             lastResolvedAccessToken = apiKey;
             const modelInfo = getModel(this.model);
             const effectiveBaseUrl = this.baseUrl ?? creds.baseUrl;
             const generator = agentLoop(loopMessages, {
+                ...(streamRules.length > 0 ? { streamRules: { rules: streamRules } } : {}),
                 provider: this.provider,
                 model: this.model,
                 tools: options.disableTools ? [] : this.tools,
@@ -2130,8 +1957,9 @@ export class AgentSession {
                 // Plan mode caps effort at medium (Codex `plan_mode_reasoning_effort`
                 // preset): read-only exploration doesn't need xhigh/max reasoning, and
                 // deep-reasoning models left at the ceiling burn enormous thinking
-                // budgets re-deriving context they cannot act on.
-                thinking: this.planModeRef.current
+                // budgets re-deriving context they cannot act on. A capped prompt
+                // (a sub-agent's timed answer) gets the same ceiling for the same reason.
+                thinking: this.planModeRef.current || options.capThinking
                     ? clampThinkingForPlanMode(this.thinkingLevel)
                     : this.thinkingLevel,
                 apiKey,
@@ -2166,6 +1994,33 @@ export class AgentSession {
                 // + pre-warm before the first turn. "baseline": current 5-min default.
                 cacheRetention: this.isSpeedOptimized() ? "long" : "short",
                 promptCacheKey: this.getPromptCacheKey(),
+                onContextPrepared: (context) => {
+                    const report = this.cacheDiagnostics.prepare(context, {
+                        provider: this.provider,
+                        model: this.model,
+                        at: Date.now(),
+                        cacheRetention: this.isSpeedOptimized() ? "long" : "short",
+                        route: { baseUrl: effectiveBaseUrl, accountId: this.lastAccountId ?? accountId },
+                        settings: {
+                            thinking: this.planModeRef.current || options.capThinking
+                                ? clampThinkingForPlanMode(this.thinkingLevel)
+                                : this.thinkingLevel,
+                            webSearch: !options.disableTools,
+                            supportsImages: modelInfo?.supportsImages,
+                            promptCacheKey: this.getPromptCacheKey(),
+                        },
+                    });
+                    log("INFO", "cache", "Prepared context", {
+                        sessionId: this.sessionId || this.transportSessionId,
+                        data: JSON.stringify(report),
+                    });
+                    if (report.thinkingPrefixRiskBlocks > 0) {
+                        log("WARN", "cache", "Possible signed-thinking prefix mismatch; not server verified", {
+                            sessionId: this.sessionId || this.transportSessionId,
+                            blocks: String(report.thinkingPrefixRiskBlocks),
+                        });
+                    }
+                },
                 supportsImages: modelInfo?.supportsImages,
                 supportsVideo: modelInfo?.supportsVideo,
                 userAgent,
@@ -2174,9 +2029,15 @@ export class AgentSession {
                 maxToolResultChars: resolveSessionToolResultCharLimit(this.model, this.provider, accountId),
                 // Aggregate per-turn budget across parallel tool results (fan-out guard).
                 maxTurnToolResultChars: resolveSessionTurnToolResultCharLimit(this.model, this.provider, accountId),
+                // Warn when web/MCP output contains instruction-like text (see injection-detect.ts).
+                transformToolResult: flagUntrustedToolResult,
                 // Self-correction hooks (same as the TUI): loop-break + re-grounding are
                 // polled mid-loop; the ideal review is polled when the agent would stop.
                 getSteeringMessages: () => this.getHookSteeringMessages(),
+                onSteeringAvailable: (listener) => {
+                    this.steeringListeners.add(listener);
+                    return () => this.steeringListeners.delete(listener);
+                },
                 getFollowUpMessages: () => this.getHookFollowUpMessages(),
                 onTurnBudgetExhausted: (ctx) => this.shouldExtendTurnBudget(ctx),
                 // Check authoritative provider usage before every model/tool step.
@@ -2202,6 +2063,7 @@ export class AgentSession {
                         // retained usage afterwards since it counted the pruned content.
                         const pruneResult = pruneStaleToolResults(messages);
                         if (pruneResult.pruned) {
+                            this.cacheDiagnostics.noteEdit("tool_prune", pruneResult.freedTokens);
                             this.providerContext = null;
                             log("INFO", "compaction", "Pruned stale tool outputs", {
                                 prunedResults: String(pruneResult.prunedResults),
@@ -2242,6 +2104,9 @@ export class AgentSession {
                             usage,
                             pendingMessages,
                         });
+                        // An approved plan runs as ONE run, so step boundaries are only
+                        // visible here, between model steps — not after the run ends.
+                        const planStep = this.observePlanStepProgress(messages, contextWindow, activeTokens);
                         log("INFO", "compaction", "In-flight compaction decision", {
                             provider: this.provider,
                             model: this.model,
@@ -2249,8 +2114,10 @@ export class AgentSession {
                             contextWindow: String(contextWindow),
                             activeTokens: String(activeTokens),
                             triggerLimit: String(policy.targetTokens),
+                            ...(planStep ? { planStep: `${planStep.compact} (${planStep.reason})` } : {}),
                         });
-                        if (!shouldCompact(messages, contextWindow, policy.threshold, activeTokens, policy.targetTokens))
+                        if (!shouldCompact(messages, contextWindow, policy.threshold, activeTokens, policy.targetTokens) &&
+                            !planStep?.compact)
                             return messages;
                     }
                     // compact() operates on this.messages, while an earlier transform may
@@ -2583,7 +2450,7 @@ export class AgentSession {
         const canonicalPath = await this.sessionManager.resolveCanonicalSession(this.conversationId, this.cwd);
         if (!canonicalPath || canonicalPath === this.sessionPath)
             return;
-        await this.adoptCompactionCheckpoint(await this.sessionManager.load(canonicalPath));
+        await this.adoptCompactionCheckpoint(await this.sessionManager.load(canonicalPath, { canonical: true }));
     }
     async persistCompactionCheckpoint(sourceFingerprint, result) {
         const parentSessionId = this.sessionId || undefined;
@@ -2632,6 +2499,99 @@ export class AgentSession {
         if (this.postTurnCompaction)
             await this.postTurnCompaction;
     }
+    /**
+     * Advance plan-step bookkeeping over the messages added since the last
+     * observation and, when a plan step was newly completed (`[DONE:n]`), run
+     * the SoL-Pi cost rule. Called between model steps (in-flight) and once
+     * after the run; `scanIndex` and `doneSteps` make each message and each
+     * step count once across both paths. Returns undefined when no step
+     * completed since the last observation.
+     */
+    observePlanStepProgress(messages, contextWindow, activeTokens) {
+        const st = this.planStepState;
+        const planPath = this.approvedPlanPath;
+        if (st.planPath !== planPath) {
+            st.planPath = planPath;
+            st.doneSteps = new Set();
+            st.requestsInCompletedSteps = 0;
+            st.requestsThisStep = 0;
+        }
+        if (st.scanIndex > messages.length)
+            st.scanIndex = 0;
+        let requests = 0;
+        const newlyDone = [];
+        for (let i = st.scanIndex; i < messages.length; i++) {
+            const msg = messages[i];
+            if (msg?.role !== "assistant")
+                continue;
+            requests++;
+            const text = typeof msg.content === "string"
+                ? msg.content
+                : msg.content.map((part) => (part.type === "text" ? part.text : "")).join("\n");
+            for (const step of findCompletedMarkers(text)) {
+                if (!st.doneSteps.has(step))
+                    newlyDone.push(step);
+            }
+        }
+        st.scanIndex = messages.length;
+        const contextTokens = activeTokens ?? estimateConversationTokens(messages);
+        if (st.lastContextTokens > 0)
+            st.grownTokens += Math.max(0, contextTokens - st.lastContextTokens);
+        st.lastContextTokens = contextTokens;
+        st.requests += requests;
+        st.requestsThisStep += requests;
+        st.requestsSinceLastCompaction += requests;
+        if (st.writeCostBalance > 0)
+            st.writeCostBalance -= st.savingPerRequest * requests;
+        if (!planPath || newlyDone.length === 0)
+            return undefined;
+        for (const step of newlyDone)
+            st.doneSteps.add(step);
+        st.requestsInCompletedSteps += st.requestsThisStep;
+        st.requestsThisStep = 0;
+        let planText;
+        try {
+            planText = readFileSync(planPath, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+        const totalSteps = extractPlanSteps(planText).length;
+        const decision = decidePlanStepCompaction({
+            contextTokens,
+            keptTailTokens: PLAN_STEP_KEEP_TOKENS,
+            contextWindow,
+            // The model registry carries no cache price fields; use the SoL-Pi default.
+            cacheWriteReadRatio: DEFAULT_CACHE_WRITE_READ_RATIO,
+            stepsCompleted: st.doneSteps.size,
+            stepsRemaining: Math.max(0, totalSteps - st.doneSteps.size),
+            requestsInCompletedSteps: st.requestsInCompletedSteps,
+            requests: st.requests,
+            grownTokens: st.grownTokens,
+            priorCompactions: st.compactions,
+            writeCostBalance: st.writeCostBalance,
+            requestsSinceLastCompaction: st.compactions > 0 ? st.requestsSinceLastCompaction : undefined,
+        });
+        log("INFO", "compaction", "Plan-step compaction decision", {
+            compact: String(decision.compact),
+            reason: decision.reason,
+        });
+        return decision;
+    }
+    /**
+     * Plan-step bookkeeping after ANY successful compaction (as in the bench:
+     * every compaction leaves a cache-write cost to be repaid by later savings).
+     */
+    recordPlanStepCompaction(contextBefore) {
+        const st = this.planStepState;
+        const after = estimateConversationTokens(this.messages);
+        st.scanIndex = this.messages.length;
+        st.lastContextTokens = after;
+        st.requestsSinceLastCompaction = 0;
+        st.compactions++;
+        st.writeCostBalance += after * (DEFAULT_CACHE_WRITE_READ_RATIO - 1);
+        st.savingPerRequest = Math.max(0, contextBefore - after);
+    }
     /**
      * Post-turn compaction: once the final response has been delivered, compact
      * in the background while the user reads the answer, instead of making the
@@ -2640,7 +2600,9 @@ export class AgentSession {
      * Codex `model_post_turn_compact_threshold_percent` guards: skip when user
      * input is already queued (it would race the next turn), when the run was
      * aborted, or during the failure cooldown — and never let a compaction
-     * error surface in the completed turn.
+     * error surface in the completed turn. Besides the size trigger, a newly
+     * completed approved-plan step may compact when the cache-cost rule in
+     * compaction/plan-step-policy.ts says the shrink pays for itself.
      */
     maybeCompactPostTurn(creds) {
         if (!this.settingsManager.get("autoCompact"))
@@ -2653,15 +2615,18 @@ export class AgentSession {
             return;
         if (Date.now() < this.compactionRetryAfter)
             return;
-        // One compaction per turn boundary: a pre-run or overflow-recovery
-        // compaction already shrank this run's history — re-probing right after
-        // the final response would only re-derive that decision.
-        if (this.compactionOccurred)
-            return;
         const contextWindow = getContextWindow(this.model, {
             provider: this.provider,
             accountId: creds.accountId,
         });
+        // One compaction per turn boundary: a pre-run, in-flight or overflow
+        // compaction already shrank this run's history — re-probing right after
+        // the final response would only re-derive that decision. Still record the
+        // final response's `[DONE:n]` steps so plan bookkeeping stays current.
+        if (this.compactionOccurred) {
+            this.observePlanStepProgress(this.messages, contextWindow, undefined);
+            return;
+        }
         const policy = resolveCompactionPolicy({
             provider: this.provider,
             model: this.model,
@@ -2680,9 +2645,12 @@ export class AgentSession {
                 });
             }
         }
-        if (!shouldCompact(this.messages, contextWindow, policy.threshold, activeTokens, policy.targetTokens))
+        const planStep = this.observePlanStepProgress(this.messages, contextWindow, activeTokens);
+        if (!shouldCompact(this.messages, contextWindow, policy.threshold, activeTokens, policy.targetTokens) &&
+            !planStep?.compact)
             return;
         log("INFO", "compaction", "Post-turn compaction decision — compacting in background", {
+            trigger: planStep?.compact ? `plan-step (${planStep.reason})` : "size",
             provider: this.provider,
             model: this.model,
             transport: this.provider === "openai" && creds.accountId ? "codex_oauth" : "public_api",
@@ -2736,6 +2704,7 @@ export class AgentSession {
             approvedPlanPath: this.approvedPlanPath,
         });
         const originalCount = this.messages.length;
+        const contextTokensBefore = estimateConversationTokens(this.messages);
         this.eventBus.emit("compaction_start", { messageCount: originalCount });
         let contextSelection;
         const runCompactor = async () => {
@@ -2773,7 +2742,7 @@ export class AgentSession {
                 let sourceFingerprint = computeSourceFingerprint(this.messages);
                 const canonicalPath = await this.sessionManager.resolveCanonicalSession(conversationId, this.cwd);
                 if (canonicalPath && canonicalPath !== this.sessionPath) {
-                    const newest = await this.sessionManager.load(canonicalPath);
+                    const newest = await this.sessionManager.load(canonicalPath, { canonical: true });
                     if (newest.header.sourceFingerprint === sourceFingerprint) {
                         await this.adoptCompactionCheckpoint(newest);
                         this.lastCompactionCompacted = true;
@@ -2847,6 +2816,10 @@ export class AgentSession {
                 }
             });
         }
+        if (this.lastCompactionCompacted) {
+            this.cacheDiagnostics.noteEdit("compaction");
+            this.recordPlanStepCompaction(contextTokensBefore);
+        }
         this.eventBus.emit("compaction_end", {
             compacted: this.lastCompactionCompacted,
             originalCount,
@@ -2866,6 +2839,7 @@ export class AgentSession {
         });
     }
     async newSession(preserveConversation = false) {
+        this.cacheDiagnostics.reset();
         // Approved-plan execution is a clean checkpoint of the same conversation;
         // explicit new sessions reset the conversation identity.
         if (!preserveConversation) {
@@ -2889,6 +2863,7 @@ export class AgentSession {
         const basePrompt = await this.buildBasePrompt(false, undefined);
         this.baseSystemPrompt = basePrompt;
         this.messages = [{ role: "system", content: this.withSystemPromptTail(basePrompt) }];
+        this.clearReadTracker?.();
         // Fresh conversation — new entries must not chain onto the old DAG's leaf.
         this.currentLeafId = null;
         // Transient sessions (Nolan chat/autopilot, subagent spawns) never touch the
@@ -2912,6 +2887,7 @@ export class AgentSession {
     }
     async loadSession(sessionPath) {
         await this.loadExistingSession(sessionPath);
+        this.cacheDiagnostics.reset();
         if (this.sessionId)
             await this.subAgentManager?.hydrate(this.sessionId);
         this.eventBus.emit("session_start", { sessionId: this.sessionId });
@@ -2942,7 +2918,10 @@ export class AgentSession {
         const branchMessages = this.sessionManager.getMessages(loaded.entries, this.currentLeafId);
         const systemMsg = this.messages[0];
         this.messages = [systemMsg, ...branchMessages];
+        this.cacheDiagnostics.reset();
         this.lastPersistedIndex = this.messages.length;
+        // Reads made in the dropped messages are no longer in the model's context.
+        this.clearReadTracker?.();
         this.eventBus.emit("branch_created", {
             leafId: this.currentLeafId,
             messagesKept: branchMessages.length,
@@ -3007,23 +2986,33 @@ export class AgentSession {
             : undefined;
         return costUsd === undefined ? { used, size } : { used, size, costUsd };
     }
-    getPlanMode() {
-        return this.planModeRef.current;
-    }
     /**
-     * Suppress only the pre-final Ideal self-review for this live session.
-     * Autopilot uses this while Nolan independently owns verification; loop-break
-     * and post-compaction re-grounding remain active.
+     * Whether the provider's prompt cache has likely lapsed since the last
+     * successful request, and how many tokens the next message would re-read at
+     * full price. Null when the route has no known TTL or the chat is empty.
      */
-    setIdealReviewSuppressed(suppressed) {
-        this.idealReviewSuppressed = suppressed;
-        if (suppressed) {
-            this.idealReviewPhase = "idle";
-            this.reviewCoverage.reset();
-        }
-        // Suppression flips mid-run (autopilot takes over verification), so a client
-        // holding a draft under a stale arming must be released.
-        this.refreshHookArming();
+    getCacheExpiryStatus(now = Date.now()) {
+        const status = assessCacheExpiry({
+            current: {
+                provider: this.provider,
+                model: this.model,
+                policy: resolveCacheTtl({
+                    provider: this.provider,
+                    model: this.model,
+                    cacheRetention: this.isSpeedOptimized() ? "long" : "short",
+                    baseUrl: this.baseUrl,
+                    accountId: this.lastAccountId,
+                }),
+            },
+            lastTouch: this.cacheDiagnostics.lastCacheTouch(),
+            now,
+            prefixTokens: this.getContextUsage().used,
+            hasHistory: this.messages.some((m) => m.role === "user"),
+        });
+        return status && { ...status, sessionId: this.sessionId || this.transportSessionId };
+    }
+    getPlanMode() {
+        return this.planModeRef.current;
     }
     /** Queue a user message (optionally with attachments) to be injected mid-run
      *  as steering. Returns the new queue length. No-op semantics are the caller's
@@ -3031,6 +3020,9 @@ export class AgentSession {
     queueMessage(text, attachments = []) {
         this.queueSeq += 1;
         this.userQueue.push({ id: `q${this.queueSeq}`, text, attachments });
+        // Instant interrupt: preempt running tools so the steer lands right away.
+        for (const listener of [...this.steeringListeners])
+            listener();
         return this.userQueue.length;
     }
     /** Pending queued messages (id + text), oldest first, for client display. */
@@ -3083,6 +3075,15 @@ export class AgentSession {
             return `No background process with id "${id}"`;
         return this.processManager.stop(id);
     }
+    /**
+     * Force-stop every background process tree, synchronously. Background
+     * commands run in their own process group, so the daemon's group kill on
+     * quit never reaches them: this is the only thing that does. Callers on a
+     * shutdown deadline run it before awaiting anything that can hang.
+     */
+    stopBackgroundProcesses() {
+        this.processManager?.shutdownAll();
+    }
     /** Replace a host-owned system prompt in place without resetting conversation history. */
     setCustomSystemPrompt(systemPrompt, promptCacheKeyPrefix) {
         this.customSystemPrompt = systemPrompt;
@@ -3229,6 +3230,18 @@ export class AgentSession {
      * the standard prompt therefore needs a rebuild. Custom and sub-agent
      * prompts never render packs, so detection is skipped for them.
      */
+    /**
+     * Bring the system prompt to the exact state the next provider request will
+     * send. Shared by real runs and {@link prewarm} so both see one prefix.
+     */
+    async prepareSystemPromptForRequest() {
+        // Languages are re-detected at each task boundary so a project scaffolded
+        // during the previous turn gets its packs; the prompt is rebuilt only when
+        // the set grows, keeping the cached prefix stable otherwise.
+        if (this.refreshActiveLanguages())
+            await this.rebuildSystemPromptInPlace();
+        this.refreshSystemPromptTail();
+    }
     refreshActiveLanguages() {
         if (this.customSystemPrompt || this.agentPrompt !== undefined)
             return false;
@@ -3327,6 +3340,17 @@ export class AgentSession {
         }));
     }
     async persistTurnMetric(event) {
+        if (event.stopReason === "error")
+            this.cacheDiagnostics.discardAttempt();
+        const cache = this.cacheDiagnostics.complete(event.usage, event.timing);
+        if (cache) {
+            log("INFO", "cache", "Context cache outcome", {
+                sessionId: this.sessionId || this.transportSessionId,
+                provider: this.provider,
+                model: this.model,
+                data: JSON.stringify(cache),
+            });
+        }
         const payload = {
             version: 1,
             turn: event.turn,
@@ -3712,6 +3736,138 @@ export class AgentSession {
         if (signal?.aborted)
             this.managerAbortHandler();
     }
+    runLoopDepth = 0;
+    lastRealRequestAt = 0;
+    lastPrewarmAt = 0;
+    prewarmController = null;
+    /**
+     * Best-effort Anthropic prompt-cache prewarm before the user's next turn
+     * (desktop app calls this on the first keystroke after opening a chat or an
+     * idle pause). Sends the exact request prefix the next real turn will use —
+     * same system/tools/thinking/cache options — with `max_tokens: 1`, so the
+     * first real reply is a cache read instead of a cold write.
+     */
+    async prewarm(signal) {
+        if (this.provider !== "anthropic")
+            return { ok: false, reason: "provider" };
+        if (this.settingsManager?.get("cachePrewarm") === false) {
+            return { ok: false, reason: "disabled" };
+        }
+        if (this.runLoopDepth > 0)
+            return { ok: false, reason: "run_active" };
+        if (this.prewarmController)
+            return { ok: false, reason: "in_flight" };
+        const cacheRetention = this.isSpeedOptimized() ? "long" : "short";
+        const ttlMs = (cacheRetention === "long" ? 60 : 5) * 60_000;
+        const now = Date.now();
+        if (now - Math.max(this.lastPrewarmAt, this.lastRealRequestAt) < ttlMs) {
+            return { ok: false, reason: "cache_fresh" };
+        }
+        // Same preparation as the real run, BEFORE copying history: otherwise the
+        // warmed system block differs from the next request (language packs are
+        // detected at run start) and everything after it misses the cache.
+        await this.prepareSystemPromptForRequest();
+        // The await above yields: re-check that no run or other prewarm began.
+        if (this.runLoopDepth > 0)
+            return { ok: false, reason: "run_active" };
+        if (this.prewarmController)
+            return { ok: false, reason: "in_flight" };
+        // End at the last user/tool message: the next real turn appends a new user
+        // message after the trailing assistant reply, and its cache lookback hits
+        // the entry written at this boundary. A request must end on a user turn.
+        let end = this.messages.length;
+        while (end > 0 && this.messages[end - 1]?.role === "assistant")
+            end--;
+        // The loop repairs tool pairing in place before every request; apply the
+        // same repair to a copy so the warmed prefix is byte-identical to it.
+        const messages = structuredClone(this.messages.slice(0, end));
+        repairToolPairingAdjacent(messages);
+        if (!messages.some((m) => m.role === "user" || m.role === "tool")) {
+            return { ok: false, reason: "no_history" };
+        }
+        const tokens = estimateConversationTokens(messages);
+        if (tokens < 4_000)
+            return { ok: false, reason: "too_small" };
+        const controller = new AbortController();
+        const onAbort = () => controller.abort();
+        signal?.addEventListener("abort", onAbort, { once: true });
+        this.prewarmController = controller;
+        const started = Date.now();
+        try {
+            const creds = await this.authStorage.resolveCredentials(this.provider, {
+                storageKeys: this.currentAuthStorageKeys(),
+            });
+            if (controller.signal.aborted || this.runLoopDepth > 0) {
+                return { ok: false, reason: "aborted" };
+            }
+            const modelInfo = getModel(this.model);
+            const result = stream({
+                provider: this.provider,
+                model: this.model,
+                messages,
+                tools: this.tools,
+                webSearch: true,
+                maxTokens: this.maxTokens,
+                thinking: this.planModeRef.current
+                    ? clampThinkingForPlanMode(this.thinkingLevel)
+                    : this.thinkingLevel,
+                apiKey: creds.accessToken,
+                baseUrl: this.baseUrl ?? creds.baseUrl,
+                accountId: creds.accountId,
+                transportSessionId: this.sessionId || this.transportSessionId,
+                cacheRetention,
+                promptCacheKey: this.getPromptCacheKey(),
+                supportsImages: modelInfo?.supportsImages,
+                supportsVideo: modelInfo?.supportsVideo,
+                userAgent: await getClaudeCliUserAgent(),
+                prewarm: true,
+                signal: controller.signal,
+            });
+            const response = await result.response;
+            const usage = response.usage;
+            if (usage.inputTokens === 0 && usage.outputTokens === 0) {
+                // @prestyj/ai sent nothing: budget thinking can't stay identical at max_tokens 1.
+                log("INFO", "prewarm", "Cache prewarm skipped: budget thinking", {
+                    model: this.model,
+                });
+                return { ok: false, reason: "thinking_budget_incompatible" };
+            }
+            this.lastPrewarmAt = Date.now();
+            const warmedPolicy = resolveCacheTtl({
+                provider: this.provider,
+                model: this.model,
+                cacheRetention,
+                baseUrl: this.baseUrl ?? creds.baseUrl,
+                accountId: creds.accountId,
+            });
+            if (warmedPolicy) {
+                this.cacheDiagnostics.noteCacheTouch({
+                    at: started,
+                    provider: this.provider,
+                    model: this.model,
+                    policy: warmedPolicy,
+                });
+            }
+            log("INFO", "prewarm", "Cache prewarm complete", {
+                tokens: String(tokens),
+                cacheRead: String(usage.cacheRead ?? 0),
+                cacheWrite: String(usage.cacheWrite ?? 0),
+                ms: String(Date.now() - started),
+            });
+            return { ok: true, reason: "warmed", usage };
+        }
+        catch (error) {
+            if (isAbortError(error) || controller.signal.aborted)
+                return { ok: false, reason: "aborted" };
+            log("WARN", "prewarm", `Cache prewarm failed: ${error instanceof Error ? error.message : String(error)}`);
+            return { ok: false, reason: "error" };
+        }
+        finally {
+            signal?.removeEventListener("abort", onAbort);
+            if (this.prewarmController === controller)
+                this.prewarmController = null;
+        }
+    }
     /** True when speedProfile is "optimized" (1-h cache TTL + pre-warm), or the
      *  session was constructed with `forceLongCacheRetention` (Nolan sessions). */
     isSpeedOptimized() {
@@ -3740,16 +3896,22 @@ export class AgentSession {
         return this.getPromptCacheKey();
     }
     async dispose() {
+        // First and synchronous: nothing below may delay this, or a hung teardown
+        // step leaves background commands running after the app has quit.
+        this.stopBackgroundProcesses();
         // Quiesce any in-flight post-turn compaction BEFORE tearing down state:
         // the background compact() snapshots and replaces `this.messages`, so
         // letting it run past this point would checkpoint a near-empty history
         // and leak a junk session file after teardown.
         if (this.postTurnCompaction)
             await this.postTurnCompaction;
+        this.cacheDiagnostics.reset();
         this.diagnosticsRecorder?.finalize();
         this.managerAbortSignal?.removeEventListener("abort", this.managerAbortHandler);
-        this.processManager?.shutdownAll();
+        // Again, in case a turn racing teardown started one while we awaited.
+        this.stopBackgroundProcesses();
         this.lspManager?.shutdownAll();
+        this.debugManager?.shutdown();
         await Promise.all([this.subAgentManager?.shutdownAll(), this.mcpManager?.dispose()]);
         await this.extensionLoader.deactivateAll();
         this.setSessionPath("");
@@ -3785,8 +3947,10 @@ export class AgentSession {
         // A stale physical checkpoint is only an address, not the conversation tip.
         // Resolve every resume—not just over-threshold/deferred compaction resumes—
         // before reading history so the next prompt cannot continue an old branch.
-        const canonicalPath = (await this.sessionManager.resolveCanonicalSession(sessionPath, this.cwd)) ?? sessionPath;
-        const loaded = await this.sessionManager.load(canonicalPath);
+        const resolvedPath = await this.sessionManager.resolveCanonicalSession(sessionPath, this.cwd);
+        const loaded = resolvedPath
+            ? await this.sessionManager.load(resolvedPath, { canonical: true })
+            : await this.sessionManager.load(sessionPath);
         // Use the leaf from the header to walk the correct branch
         const loadedMessages = this.sessionManager.getMessages(loaded.entries, loaded.header.leafId);
         const savedCompletionReview = [...loaded.entries]
@@ -3840,6 +4004,8 @@ export class AgentSession {
         // not fail when Anthropic's stricter many-image limit activates later.
         const systemMsg = this.messages[0]; // Already built
         this.messages = [systemMsg, ...loadedMessages];
+        // Reads recorded for the previous conversation don't carry over.
+        this.clearReadTracker?.();
         const normalizedImageCount = await normalizeMessageImages(this.messages);
         if (normalizedImageCount > 0) {
             log("INFO", "session", `Resized ${normalizedImageCount} restored session image(s)`);