@kenkaiiii/ggcoder 5.67.1 → 5.68.1

package/dist/core/agent-session.js

@@ -1,4 +1,4 @@
-import { agentLoop, isAbortError, isUsageLimitError, } from "@kenkaiiii/gg-agent";
+import { agentLoop, isAbortError, isUsageLimitError, repairToolPairingAdjacent, } from "@kenkaiiii/gg-agent";
 import { ProviderError, stream, } from "@kenkaiiii/gg-ai";
 import { EventBus } from "./event-bus.js";
 import { COMPLETION_REVIEW_STATE_KIND, } from "./completion-review.js";
@@ -36,9 +36,13 @@ 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 { 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";
@@ -57,6 +61,7 @@ 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";
@@ -130,6 +135,7 @@ export class AgentSession {
     // transcript rows the live run showed.
     appMarkers = [];
     turnMetrics = [];
+    cacheDiagnostics = new CacheDiagnostics();
     /** Internal-only (GG_INTERNAL): live per-session cost/reliability recorder.
      * Absent entirely in public builds — see core/internal-diagnostics.ts. */
     diagnosticsRecorder;
@@ -216,6 +222,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. */
@@ -923,6 +948,7 @@ export class AgentSession {
         kind: "prompt",
         visibility: "transcript",
     }, options = {}) {
+        this.prewarmController?.abort();
         await this.settlePostTurnCompaction();
         await this.adoptDeferredCheckpointBeforePrompt();
         const slash = await this.resolveSlashInput(content);
@@ -958,6 +984,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);
@@ -2035,14 +2062,22 @@ export class AgentSession {
             content: `${String(message.content)}\n\n${notes.join(" ")}`,
         };
     }
-    /** Auto-compact if needed, run agent loop with auth retry, and persist messages. */
+    /** Wraps the real run: cancels an in-flight cache prewarm and tracks run
+     *  activity / last real request time for {@link prewarm}. */
     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();
+        this.prewarmController?.abort();
+        this.runLoopDepth++;
+        try {
+            await this.runLoopInner(options);
+        }
+        finally {
+            this.runLoopDepth--;
+            this.lastRealRequestAt = Date.now();
+        }
+    }
+    /** Auto-compact if needed, run agent loop with auth retry, and persist messages. */
+    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`.
@@ -2137,11 +2172,14 @@ export class AgentSession {
         }
         const 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,
@@ -2189,6 +2227,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,
@@ -2225,6 +2290,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),
@@ -2265,6 +2331,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,
@@ -2272,8 +2341,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
@@ -2594,7 +2665,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;
@@ -2643,6 +2714,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
@@ -2651,7 +2815,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"))
@@ -2664,15 +2830,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,
@@ -2691,9 +2860,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",
@@ -2747,6 +2919,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 () => {
@@ -2784,7 +2957,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;
@@ -2858,6 +3031,10 @@ export class AgentSession {
                 }
             });
         }
+        if (this.lastCompactionCompacted) {
+            this.cacheDiagnostics.noteEdit("compaction");
+            this.recordPlanStepCompaction(contextTokensBefore);
+        }
         this.eventBus.emit("compaction_end", {
             compacted: this.lastCompactionCompacted,
             originalCount,
@@ -2877,6 +3054,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) {
@@ -2924,6 +3102,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 });
@@ -2954,6 +3133,7 @@ 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?.();
@@ -3243,6 +3423,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;
@@ -3341,6 +3533,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,
@@ -3726,6 +3929,123 @@ 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) {
+                // gg-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();
+            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` (Ken sessions). */
     isSpeedOptimized() {
@@ -3760,6 +4080,7 @@ export class AgentSession {
         // 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();
@@ -3799,8 +4120,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]