@prestyj/cli 5.7.0 → 5.9.0

package/dist/core/agent-session.js

@@ -1,4 +1,4 @@
-import { agentLoop, isAbortError, } from "@prestyj/agent";
+import { agentLoop, isAbortError, isUsageLimitError, } from "@prestyj/agent";
 import { ProviderError, } from "@prestyj/ai";
 import { EventBus } from "./event-bus.js";
 import { SlashCommandRegistry, createBuiltinCommands, } from "./slash-commands.js";
@@ -6,12 +6,13 @@ import { PROMPT_COMMANDS, getPromptCommand } from "./prompt-commands.js";
 import { loadCustomCommands } from "./custom-commands.js";
 import { SettingsManager } from "./settings-manager.js";
 import { AuthStorage } from "./auth-storage.js";
+import { MOONSHOT_OAUTH_KEY } from "@prestyj/core";
 import { getClaudeCliUserAgent } from "./claude-code-version.js";
 import { kimiCodingHeaders, isKimiCodingEndpoint } from "./oauth/kimi.js";
 import { SessionManager, NOLAN_TURN_CUSTOM_KIND, AUTOPILOT_MARKER_CUSTOM_KIND, APP_MARKER_CUSTOM_KIND, } from "./session-manager.js";
 import { ExtensionLoader } from "./extensions/loader.js";
-import { shouldCompact, compact, getCompactionReserveTokens } from "./compaction/compactor.js";
-import { getAuthStorageKeys, getContextWindow, getModel, MODELS } from "./model-registry.js";
+import { shouldCompact, compact } from "./compaction/compactor.js";
+import { getAuthStorageKeys, getContextWindow, getModel, getToolResultCharLimit, MODELS, } from "./model-registry.js";
 import { discoverSkills } from "./skills.js";
 import { ensureAppDirs } from "../config.js";
 import { buildSystemPrompt } from "../system-prompt.js";
@@ -22,18 +23,39 @@ import { MCPClientManager, getAllMcpServers } from "./mcp/index.js";
 import { DeferredToolCatalog } from "./mcp/deferred-catalog.js";
 import { createToolSearchTool } from "../tools/tool-search.js";
 import { log } from "./logger.js";
-import { setEstimatorModel } from "./compaction/token-estimator.js";
+import { setEstimatorModel, calibrateEstimatorFromUsage } from "./compaction/token-estimator.js";
+import { calculateActiveContextTokens } from "./compaction/active-context.js";
+import { pruneStaleToolResults } from "./compaction/tool-result-pruner.js";
 import { discoverAgents } from "./agents.js";
-import { generateSessionTitle } from "../utils/session-title.js";
 import { enhancePrompt } from "../utils/prompt-enhancer.js";
 import { detectProjectStack } from "./language-detector.js";
-import { evaluateIdealReview, buildIdealReviewMessage, buildReviewCoverageMessage, detectTestDrift, ReviewCoverageTracker, } from "./ideal-review.js";
-import { evaluateLoopBreak, buildLoopBreakMessage, ToolCallProgressTracker, detectTextRepetition, } from "./loop-breaker.js";
+import { evaluateIdealReview, buildIdealReviewMessage, buildReviewCoverageMessage, withReviewCoverageRequirements, detectTestDrift, ReviewCoverageTracker, } from "./ideal-review.js";
+import { evaluateLoopBreak, buildLoopBreakMessage, CycleDetector, ToolCallProgressTracker, detectTextRepetition, } from "./loop-breaker.js";
 import { buildRegroundingMessage } from "./regrounding.js";
 import { wrapSteeringText, STEERING_PREFIX } from "./steering.js";
+import { findUserSessionPrompt, getUserSessionPrompt } from "./session-preview.js";
+import { normalizeMessageImages } from "./message-images.js";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+// ── Tool-result policy ─────────────────────────────────────
+/** Resolve the per-result cap passed to the agent loop for the active transport. */
+export function resolveSessionToolResultCharLimit(model, provider, accountId) {
+    return (getToolResultCharLimit(model, { provider, accountId }) ??
+        Math.floor(getContextWindow(model, { provider, accountId }) * 3.5 * 0.3));
+}
+/**
+ * Aggregate budget for ALL tool results produced in one assistant turn.
+ * Individual results are already capped, but wide parallel fan-outs (GPT-5.6's
+ * signature behavior) were observed injecting 100k+ uncached tokens in a single
+ * turn. ~15% of the context window in chars (1 token ≈ 3.5 chars), floored at
+ * 100KB so small windows still fit two full-size reads, ceilinged at 240KB so
+ * 1M-context models don't waive the budget entirely.
+ */
+export function resolveSessionTurnToolResultCharLimit(model, provider, accountId) {
+    const contextChars = getContextWindow(model, { provider, accountId }) * 3.5;
+    return Math.max(100_000, Math.min(Math.floor(contextChars * 0.15), 240_000));
+}
 // ── Agent Session ──────────────────────────────────────────
 export class AgentSession {
     eventBus = new EventBus();
@@ -84,13 +106,22 @@ export class AgentSession {
     hookConsecutiveFailures = 0;
     hookRepeatedNoProgressCalls = 0;
     hookProgressTracker = new ToolCallProgressTracker();
+    hookCycleDetector = new CycleDetector();
+    hookCyclicPattern = null;
     hookFileEditCounts = new Map();
     hookToolCalls = new Map();
     idealReviewPhase = "idle";
+    /** Runtime-only suppression while Nolan owns verification in autopilot mode. */
+    idealReviewSuppressed = false;
     reviewCoverage;
-    loopBreakInjected = false;
+    /** 0 = none; 1 = first nudge sent; 2 = final stop-and-report injected. */
+    loopBreakInjected = 0;
     regroundingInjected = false;
     compactionOccurred = false;
+    lastCompactionCompacted = false;
+    compactionRetryAfter = 0;
+    /** Latest provider count, anchored to the assistant response it measured. */
+    providerContext = null;
     originalRequest = "";
     // Messages queued by the user while a run is in flight. Drained at the
     // mid-loop steering boundary (user steering wins over the hooks), mirroring
@@ -128,6 +159,10 @@ export class AgentSession {
      *  model emits step-completion markers the UI's plan-progress widget reads. */
     approvedPlanPath;
     sessionId = "";
+    /** Stable identity shared by compaction and approved-plan checkpoint files. */
+    conversationId = "";
+    /** Original user-authored prompt, retained when internal messages replace history. */
+    sessionPreview = "";
     /** Runtime conversation identity for provider transport headers. Transient
      *  children need one even though they intentionally have no persisted session. */
     transportSessionId = crypto.randomUUID();
@@ -206,6 +241,9 @@ export class AgentSession {
             provider: this.provider,
             model: this.model,
             lspDiagnostics: this.settingsManager.get("lspDiagnostics"),
+            getWriteGuardSettings: () => ({
+                allowOutsideWorkspaceWrites: this.settingsManager.get("allowOutsideWorkspaceWrites"),
+            }),
             authStorage: this.authStorage,
             onFileRead: (filePath) => this.reviewCoverage.recordRead(filePath),
             onFileMutated: (filePath) => {
@@ -220,6 +258,7 @@ export class AgentSession {
             getThinkingLevel: () => this.thinkingLevel,
             getBaseUrl: () => this.baseUrl,
             getCacheKey: () => this.getPromptCacheKey(),
+            getMaxPerModel: () => this.settingsManager.get("subagentMaxPerModel"),
             disableAsyncSubagents: this.opts.subagentWorker,
             onSubAgentState: (snapshot) => this.eventBus.emit("subagent_state", snapshot),
             // Plan mode: only wired when the host supplies callbacks. The ref is
@@ -294,6 +333,32 @@ export class AgentSession {
         }
         if (this.sessionId)
             await this.subAgentManager?.hydrate(this.sessionId);
+        // Maintenance is deliberately queued after initialization work and never
+        // awaited, so retention/compression cannot delay sidecar or CLI readiness.
+        if (!this.opts.transient) {
+            const retentionDays = this.settingsManager.get("sessionRetentionDays");
+            void Promise.resolve()
+                .then(() => this.sessionManager.runMaintenance({
+                retentionDays,
+                keepPaths: this.sessionPath ? [this.sessionPath] : [],
+            }))
+                .then((metrics) => {
+                if (metrics.deletedFiles > 0 || metrics.archivedFiles > 0 || metrics.failures > 0) {
+                    log("INFO", "session", "Session maintenance complete", {
+                        deletedFiles: String(metrics.deletedFiles),
+                        deletedMB: (metrics.deletedBytes / 1024 / 1024).toFixed(1),
+                        archivedFiles: String(metrics.archivedFiles),
+                        savedMB: (metrics.bytesSaved / 1024 / 1024).toFixed(1),
+                        failures: String(metrics.failures),
+                    });
+                }
+            })
+                .catch((error) => {
+                log("WARN", "session", "Session maintenance failed", {
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            });
+        }
         // EZ Coder owns its command registry. Other agents start with an isolated
         // empty registry and can register their own commands in their own file.
         if (this.opts.coderSlashCommands !== false) {
@@ -586,11 +651,13 @@ export class AgentSession {
         this.hookConsecutiveFailures = 0;
         this.hookRepeatedNoProgressCalls = 0;
         this.hookProgressTracker.reset();
+        this.hookCycleDetector.reset();
+        this.hookCyclicPattern = null;
         this.hookFileEditCounts.clear();
         this.hookToolCalls.clear();
         this.reviewCoverage.reset();
         this.idealReviewPhase = "idle";
-        this.loopBreakInjected = false;
+        this.loopBreakInjected = 0;
         this.regroundingInjected = false;
         this.compactionOccurred = false;
         this.originalRequest = originalRequest;
@@ -623,6 +690,7 @@ export class AgentSession {
                     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);
                 if (name === "edit" && !event.isError) {
                     const diff = event.details?.diff ?? event.result;
                     const added = (diff.match(/^\+[^+]/gm) ?? []).length;
@@ -633,6 +701,13 @@ export class AgentSession {
             }
             case "turn_end":
                 this.hookStats.turns = event.turn;
+                for (let index = this.messages.length - 1; index >= 0; index--) {
+                    const anchor = this.messages[index];
+                    if (anchor?.role === "assistant") {
+                        this.providerContext = { usage: { ...event.usage }, anchor };
+                        break;
+                    }
+                }
                 await this.persistTurnMetric(event);
                 break;
         }
@@ -670,19 +745,34 @@ export class AgentSession {
             return null;
         if (!this.settingsManager.get("idealReviewEnabled"))
             return null;
-        if (!this.loopBreakInjected) {
+        // Two-stage loop-breaker: stage 1 nudges; a FRESH detection after that
+        // injects the harsher final stop-and-report prompt. Signals reset after
+        // each injection so stage 2 only fires on new evidence.
+        if (this.loopBreakInjected < 2) {
             const decision = evaluateLoopBreak({
                 consecutiveFailures: this.hookConsecutiveFailures,
                 repeatedNoProgressCalls: this.hookRepeatedNoProgressCalls,
                 textRepetitionDetected: detectTextRepetition(this.hookText),
+                ...(this.hookCyclicPattern ? { cyclicPattern: this.hookCyclicPattern } : {}),
             });
             if (decision.shouldBreak) {
-                this.loopBreakInjected = true;
+                const stage = this.loopBreakInjected === 0 ? 1 : 2;
+                this.loopBreakInjected = stage;
+                this.hookProgressTracker.reset();
+                this.hookCycleDetector.reset();
+                this.hookCyclicPattern = null;
+                this.hookConsecutiveFailures = 0;
+                this.hookRepeatedNoProgressCalls = 0;
+                // Clear the text buffer too — otherwise a stage-1 text-repetition
+                // trigger still sees the same repeated tail on the next check and
+                // escalates to stage 2 on stale evidence.
+                this.hookText = "";
                 log("INFO", "loop-break", "Injecting loop-break nudge", {
+                    stage: String(stage),
                     reasons: decision.reasons.join(", "),
                 });
                 this.eventBus.emit("hook", { kind: "loop_break" });
-                return [buildLoopBreakMessage(decision.reasons)];
+                return [buildLoopBreakMessage(decision.reasons, stage === 2)];
             }
         }
         if (!this.regroundingInjected && this.compactionOccurred) {
@@ -700,7 +790,7 @@ export class AgentSession {
         const childCompletionFollowUp = buildSubAgentCompletionFollowUp(this.subAgentManager);
         if (childCompletionFollowUp)
             return childCompletionFollowUp;
-        if (this.opts.selfCorrectionHooks === false)
+        if (this.opts.selfCorrectionHooks === false || this.idealReviewSuppressed)
             return null;
         if (this.idealReviewPhase === "reviewing") {
             const coverage = this.reviewCoverage.evidence();
@@ -745,7 +835,7 @@ export class AgentSession {
             lspMissing: lspEvidence.missing,
         });
         return [
-            this.withReviewLspEvidence(buildIdealReviewMessage(decision.reasons, driftedFiles), lspEvidence),
+            this.withReviewLspEvidence(withReviewCoverageRequirements(buildIdealReviewMessage(decision.reasons, driftedFiles), coverage.missing), lspEvidence),
         ];
     }
     reviewLspEvidence(files) {
@@ -805,24 +895,45 @@ export class AgentSession {
         this.lastAccountId = creds.accountId;
         // Auto-compact if needed. This must happen after credential resolution so
         // OpenAI OAuth/Codex sessions use the Codex product context window instead
-        // of the public API model window.
-        if (this.settingsManager.get("autoCompact")) {
+        // of the public API model window. Failed/no-op attempts cool down across
+        // prompts; provider overflow recovery still bypasses this path entirely.
+        if (this.settingsManager.get("autoCompact") && Date.now() >= this.compactionRetryAfter) {
             const contextWindow = getContextWindow(this.model, {
                 provider: this.provider,
                 accountId: creds.accountId,
             });
             const threshold = this.settingsManager.get("compactThreshold");
-            // Reserve headroom for this model's real output budget (e.g. GPT-5.5 over
-            // Codex OAuth: 272K window but up to 128K max output) — without this the
-            // default 16K reserve lets compaction skip until input alone is near the
-            // window, then `input + max_tokens` exceeds it and the provider rejects
-            // the turn outright with "exceeds the context window". Mirrors the TUI's
-            // useContextCompaction hook.
-            const reserveTokens = getCompactionReserveTokens(this.maxTokens);
-            if (shouldCompact(this.messages, contextWindow, threshold, undefined, reserveTokens)) {
-                await this.compact(creds);
-                // Re-grounding hook keys off this — the context was just summarized.
-                this.compactionOccurred = true;
+            let activeTokens;
+            if (this.providerContext) {
+                const anchorIndex = this.messages.lastIndexOf(this.providerContext.anchor);
+                if (anchorIndex >= 0) {
+                    activeTokens = calculateActiveContextTokens(this.messages, {
+                        usage: this.providerContext.usage,
+                        pendingMessages: this.messages.slice(anchorIndex + 1),
+                    });
+                }
+                else {
+                    this.providerContext = null;
+                }
+            }
+            if (shouldCompact(this.messages, contextWindow, threshold, activeTokens)) {
+                try {
+                    await this.compact(creds);
+                    if (this.lastCompactionCompacted) {
+                        // Re-grounding hook keys off this — the context was just summarized.
+                        this.compactionOccurred = true;
+                        this.compactionRetryAfter = 0;
+                    }
+                    else {
+                        this.compactionRetryAfter = Date.now() + 30_000;
+                    }
+                }
+                catch (error) {
+                    this.compactionRetryAfter = Date.now() + 30_000;
+                    if (isAbortError(error) || this.opts.signal?.aborted)
+                        throw error;
+                    log("WARN", "compaction", `Pre-run compaction failed; cooling down for 30s: ${error instanceof Error ? error.message : String(error)}`);
+                }
             }
         }
         const userAgent = this.provider === "anthropic" ? await getClaudeCliUserAgent() : undefined;
@@ -856,29 +967,99 @@ export class AgentSession {
                 supportsImages: modelInfo?.supportsImages,
                 supportsVideo: modelInfo?.supportsVideo,
                 userAgent,
-                // clearToolUses disabled — causes model to output unsolicited context summaries
-                // Single tool result shouldn't exceed 30% of context window (in chars)
-                maxToolResultChars: Math.floor(getContextWindow(this.model, { provider: this.provider, accountId }) * 3.5 * 0.3),
+                // Codex caps each tool output at 10K tokens. Other transports retain the
+                // generic 30%-of-context allowance used before this provider policy.
+                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),
                 // 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(),
                 getFollowUpMessages: () => this.getHookFollowUpMessages(),
-                // Overflow recovery: the loop calls this with { force: true } when the
-                // provider rejects a turn as too large (request_too_large / context
-                // overflow). Force-compact the in-flight history and hand it back so the
-                // loop retries with a smaller request, instead of surfacing the error.
-                // Without this the desktop app (which drives the loop through
-                // AgentSession, not the TUI's useContextCompaction hook) had NO auto
-                // recovery on 413 — the error went straight to the user. The non-force
-                // pre-call invocations pass through untouched: pre-turn compaction is
-                // already handled above, so we only act on the overflow force path.
-                // `loopMessages === this.messages` (prepareDynamicContext returns it by
-                // reference) and the post-loop `this.messages = loopMessages` re-sync
-                // keeps persistence correct after compact() swaps the array.
+                // Check authoritative provider usage before every model/tool step.
+                // Forced overflow recovery bypasses settings and cooldown; proactive
+                // checks honor both and estimate only messages unseen by the provider.
                 transformContext: async (messages, transformOpts) => {
-                    if (!transformOpts?.force)
+                    if (transformOpts.usage) {
+                        const anchorIndex = messages.length - transformOpts.pendingMessages.length - 1;
+                        const anchor = messages[anchorIndex];
+                        if (anchor?.role === "assistant") {
+                            this.providerContext = { usage: { ...transformOpts.usage }, anchor };
+                            // Feed the authoritative usage back into the token estimator so
+                            // char-based estimates track this session's real tokenizer.
+                            calibrateEstimatorFromUsage(messages.slice(0, anchorIndex), transformOpts.usage);
+                        }
+                    }
+                    const force = transformOpts.force === true;
+                    if (!force) {
+                        if (!this.settingsManager.get("autoCompact"))
+                            return messages;
+                        // Cheap stale-tool-output pruning before the expensive LLM
+                        // compaction check. In-place mutation preserves anchors; drop the
+                        // retained usage afterwards since it counted the pruned content.
+                        const pruneResult = pruneStaleToolResults(messages);
+                        if (pruneResult.pruned) {
+                            this.providerContext = null;
+                            log("INFO", "compaction", "Pruned stale tool outputs", {
+                                prunedResults: String(pruneResult.prunedResults),
+                                freedTokens: String(pruneResult.freedTokens),
+                            });
+                        }
+                        if (Date.now() < this.compactionRetryAfter)
+                            return messages;
+                        // The turn's own usage also counted the pruned content — after a
+                        // prune, fall back to estimating the (now smaller) history so the
+                        // freed tokens actually defer the LLM compaction.
+                        let usage = pruneResult.pruned ? undefined : transformOpts.usage;
+                        let pendingMessages = transformOpts.pendingMessages;
+                        if (!usage && this.providerContext) {
+                            const anchorIndex = messages.lastIndexOf(this.providerContext.anchor);
+                            if (anchorIndex >= 0) {
+                                usage = this.providerContext.usage;
+                                pendingMessages = messages.slice(anchorIndex + 1);
+                            }
+                            else {
+                                this.providerContext = null;
+                            }
+                        }
+                        const contextWindow = getContextWindow(this.model, {
+                            provider: this.provider,
+                            accountId,
+                        });
+                        const threshold = this.settingsManager.get("compactThreshold");
+                        const activeTokens = calculateActiveContextTokens(messages, {
+                            usage,
+                            pendingMessages,
+                        });
+                        if (!shouldCompact(messages, contextWindow, threshold, activeTokens))
+                            return messages;
+                    }
+                    // compact() operates on this.messages, while an earlier transform may
+                    // have replaced the loop's in-flight array. Rebind before every attempt
+                    // so the current tool results are included in the summary.
+                    this.messages = messages;
+                    try {
+                        await this.compact({
+                            accessToken: apiKey,
+                            accountId,
+                            projectId,
+                            baseUrl: effectiveBaseUrl,
+                        });
+                    }
+                    catch (error) {
+                        this.messages = messages;
+                        this.compactionRetryAfter = Date.now() + 30_000;
+                        if (force || isAbortError(error) || this.opts.signal?.aborted)
+                            throw error;
+                        log("WARN", "compaction", `In-flight compaction failed; cooling down for 30s: ${error instanceof Error ? error.message : String(error)}`);
+                        return messages;
+                    }
+                    if (!this.lastCompactionCompacted) {
+                        this.messages = messages;
+                        this.compactionRetryAfter = Date.now() + 30_000;
                         return messages;
-                    await this.compact();
+                    }
+                    this.compactionRetryAfter = 0;
                     this.compactionOccurred = true;
                     return this.messages;
                 },
@@ -888,6 +1069,19 @@ export class AgentSession {
                 this.eventBus.forwardAgentEvent(event);
             }
         };
+        const clearInvalidStaticApiKey = async (error) => {
+            if (!(error instanceof ProviderError) || error.statusCode !== 401)
+                return false;
+            if (!(await this.authStorage.isStaticApiKey(this.provider)))
+                return false;
+            // Clear whichever key actually resolved (the request may have used a
+            // fallback key, not the model's first preference).
+            const badKey = (await this.authStorage.pickStorageKey(this.currentAuthStorageKeys())) ??
+                this.currentAuthStorageKeys()[0];
+            log("WARN", "auth", `Got 401 for ${this.provider} (${badKey}) — API key is invalid or revoked`);
+            await this.authStorage.clearCredentials(badKey);
+            return true;
+        };
         try {
             await runAgentLoop(creds.accessToken, creds.accountId, creds.projectId);
         }
@@ -896,21 +1090,48 @@ export class AgentSession {
             if (isAbortError(err) || this.opts.signal?.aborted) {
                 return;
             }
-            if (err instanceof ProviderError && err.statusCode === 401) {
+            // Kimi OAuth plan ran out of usage (hard usage-limit stop, or an HTTP 402
+            // billing stop). If the user ALSO configured a Moonshot API key, mark
+            // the OAuth credential usage-exhausted (honoring the provider-stated
+            // reset time when present) and retry this turn on the API key — OAuth
+            // stays the preferred credential and resumes automatically once the mark
+            // lapses. A generic 429 is deliberately excluded: it may be a transient
+            // rate limit and must not silently switch the user to a billed API key.
+            // Guarded on the Kimi managed endpoint actually being in use: if the API
+            // key was already active, the same error means BOTH are out and must surface.
+            if (this.provider === "moonshot" &&
+                !this.baseUrl &&
+                isKimiCodingEndpoint(creds.baseUrl) &&
+                (isUsageLimitError(err) || (err instanceof ProviderError && err.statusCode === 402)) &&
+                (await this.authStorage.hasCredentials("moonshot"))) {
+                const resetsAt = err instanceof ProviderError ? err.resetsAt : undefined;
+                await this.authStorage.markUsageExhausted(MOONSHOT_OAUTH_KEY, resetsAt);
+                log("WARN", "auth", "Kimi OAuth usage limit reached — retrying this turn on the Moonshot API key", { resetsAt: resetsAt !== undefined ? String(resetsAt) : "unknown" });
+                creds = await this.authStorage.resolveCredentials(this.provider, {
+                    storageKeys: this.currentAuthStorageKeys(),
+                });
+                this.lastAccountId = creds.accountId;
+                // The runAgentLoop closure re-reads `creds`, so the retry picks up the
+                // API key's baseUrl (api.moonshot.ai) and drops the Kimi coding headers.
+                try {
+                    await runAgentLoop(creds.accessToken, creds.accountId, creds.projectId);
+                }
+                catch (fallbackErr) {
+                    // The fallback is inside this catch branch, so its errors do not pass
+                    // through the outer 401 handler. Clear a rejected API key explicitly
+                    // before surfacing the error and prompting the user to log in again.
+                    await clearInvalidStaticApiKey(fallbackErr);
+                    throw fallbackErr;
+                }
+            }
+            else if (err instanceof ProviderError && err.statusCode === 401) {
                 // Static API-key providers (GLM, Moonshot API key, etc.) have no refresh
                 // mechanism — retrying with the same key is pointless. Clear the
                 // credential and surface the error so the user re-logins. Kimi OAuth
                 // (active for `moonshot` when present) is refreshable, so it falls
                 // through to the force-refresh path below.
-                if (await this.authStorage.isStaticApiKey(this.provider)) {
-                    // Clear whichever key actually resolved (the request may have used
-                    // a fallback key, not the model's first preference).
-                    const badKey = (await this.authStorage.pickStorageKey(this.currentAuthStorageKeys())) ??
-                        this.currentAuthStorageKeys()[0];
-                    log("WARN", "auth", `Got 401 for ${this.provider} (${badKey}) — API key is invalid or revoked`);
-                    await this.authStorage.clearCredentials(badKey);
+                if (await clearInvalidStaticApiKey(err))
                     throw err;
-                }
                 log("INFO", "auth", "Got 401, force-refreshing token and retrying");
                 creds = await this.authStorage.resolveCredentials(this.provider, {
                     forceRefresh: true,
@@ -935,6 +1156,7 @@ export class AgentSession {
         if (provider)
             this.provider = provider;
         this.model = model;
+        this.providerContext = null;
         // Keep host-provided option closures (notably chat delegation) aligned with
         // the live selection after an in-session model switch.
         this.opts.provider = this.provider;
@@ -1012,6 +1234,7 @@ export class AgentSession {
         }
     }
     async compact(existingCredentials) {
+        this.lastCompactionCompacted = false;
         const creds = existingCredentials ??
             (await this.authStorage.resolveCredentials(this.provider, {
                 storageKeys: this.currentAuthStorageKeys(),
@@ -1032,6 +1255,16 @@ export class AgentSession {
             signal: this.opts.signal,
         });
         this.messages = result.messages;
+        this.lastCompactionCompacted = result.result.compacted;
+        if (!result.result.compacted) {
+            this.eventBus.emit("compaction_end", {
+                compacted: false,
+                originalCount: result.result.originalCount,
+                newCount: result.result.newCount,
+            });
+            return;
+        }
+        this.providerContext = null;
         // Transient sessions (Nolan chat/autopilot, subagent spawns) must NEVER touch
         // the session store: without this guard, the first auto-compaction called
         // sessionManager.create() and assigned a real sessionPath, silently turning
@@ -1044,9 +1277,13 @@ export class AgentSession {
         else {
             // Persist compacted messages to a new session file so `ezcoder continue`
             // picks up the compacted state instead of the full original history.
-            const session = await this.sessionManager.create(this.cwd, this.provider, this.model);
+            const session = await this.sessionManager.create(this.cwd, this.provider, this.model, {
+                conversationId: this.conversationId || undefined,
+                preview: this.sessionPreview || undefined,
+            });
             this.sessionId = session.id;
-            this.sessionPath = session.path;
+            this.conversationId = session.header.conversationId ?? session.id;
+            this.setSessionPath(session.path);
             await this.subAgentManager?.rebindParentSession(this.sessionId);
             // Write compacted messages (skip system — it's rebuilt on load)
             for (const msg of this.messages) {
@@ -1068,11 +1305,18 @@ export class AgentSession {
             });
         }
         this.eventBus.emit("compaction_end", {
+            compacted: true,
             originalCount: result.result.originalCount,
             newCount: result.result.newCount,
         });
     }
-    async newSession() {
+    async newSession(preserveConversation = false) {
+        // Approved-plan execution is a clean checkpoint of the same conversation;
+        // explicit new sessions reset the conversation identity.
+        if (!preserveConversation) {
+            this.conversationId = "";
+            this.sessionPreview = "";
+        }
         // A fresh session drops any in-flight plan state so its prompt is clean.
         this.planModeRef.current = false;
         this.approvedPlanPath = undefined;
@@ -1098,7 +1342,9 @@ export class AgentSession {
         // polluted the project's session list.
         if (this.opts.transient) {
             this.sessionId = "";
-            this.sessionPath = "";
+            this.conversationId = "";
+            this.sessionPreview = "";
+            this.setSessionPath("");
             this.lastPersistedIndex = this.messages.length;
         }
         else {
@@ -1123,6 +1369,7 @@ export class AgentSession {
     async branch(stepsBack = 2) {
         // Load the full session to access the DAG
         const loaded = await this.sessionManager.load(this.sessionPath);
+        this.setSessionPath(loaded.path);
         const branch = this.sessionManager.getBranch(loaded.entries, this.currentLeafId);
         // Walk back stepsBack message entries
         const messageEntries = branch.filter((e) => e.type === "message");
@@ -1153,6 +1400,7 @@ export class AgentSession {
      */
     async listBranches() {
         const loaded = await this.sessionManager.load(this.sessionPath);
+        this.setSessionPath(loaded.path);
         return this.sessionManager.listBranches(loaded.entries);
     }
     getState() {
@@ -1170,6 +1418,18 @@ export class AgentSession {
     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.
+     */
+    setIdealReviewSuppressed(suppressed) {
+        this.idealReviewSuppressed = suppressed;
+        if (suppressed) {
+            this.idealReviewPhase = "idle";
+            this.reviewCoverage.reset();
+        }
+    }
     /** 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
      *  concern. */
@@ -1467,46 +1727,12 @@ export class AgentSession {
             await this.sessionManager.appendEntry(this.sessionPath, entry);
         }
     }
-    /**
-     * Generate a short LLM session title from the conversation so far (first user
-     * message + first assistant reply). Best-effort; returns null on failure or
-     * when there's no user message yet. Uses the cheapest model for the provider.
-     */
-    async generateTitle() {
-        const extractText = (content) => typeof content === "string"
-            ? content
-            : content
-                .map((c) => c.type === "text" && "text" in c && typeof c.text === "string" ? c.text : "")
-                .join(" ");
-        const userMsg = this.messages.find((m) => m.role === "user");
-        const assistantMsg = this.messages.find((m) => m.role === "assistant");
-        const userText = userMsg ? extractText(userMsg.content) : "";
-        if (!userText.trim())
-            return null;
-        try {
-            const creds = await this.authStorage.resolveCredentials(this.provider, {
-                storageKeys: this.currentAuthStorageKeys(),
-            });
-            const title = await generateSessionTitle({
-                provider: this.provider,
-                userMessage: userText,
-                assistantPreview: assistantMsg ? extractText(assistantMsg.content).slice(0, 200) : "",
-                apiKey: creds.accessToken,
-                baseUrl: this.baseUrl ?? creds.baseUrl,
-                accountId: creds.accountId,
-            });
-            return title || null;
-        }
-        catch {
-            return null;
-        }
-    }
     /**
      * Rewrite a draft prompt into a tighter, terminology-correct version using
      * the ACTIVE provider/model. A stateless one-off LLM call (no agent loop, no
      * tools, no session mutation) — safe to run even mid-run. Returns the plain
      * enhanced text plus typed segments marking each corrected term. Errors throw
-     * so the caller can surface them (unlike best-effort title generation).
+     * so the caller can surface them.
      */
     async enhancePrompt(text) {
         if (!text.trim())
@@ -1598,21 +1824,44 @@ export class AgentSession {
         this.lspManager?.shutdownAll();
         await Promise.all([this.subAgentManager?.shutdownAll(), this.mcpManager?.dispose()]);
         await this.extensionLoader.deactivateAll();
+        this.setSessionPath("");
         this.eventBus.removeAllListeners();
         this.messages = [];
         this.tools = [];
     }
     // ── Private ────────────────────────────────────────────
+    setSessionPath(nextPath) {
+        if (this.sessionPath === nextPath)
+            return;
+        if (this.sessionPath)
+            this.sessionManager.unregisterActivePath(this.sessionPath);
+        this.sessionPath = nextPath;
+        if (nextPath)
+            this.sessionManager.registerActivePath(nextPath);
+    }
     async createNewSession() {
-        const session = await this.sessionManager.create(this.cwd, this.provider, this.model);
+        const session = await this.sessionManager.create(this.cwd, this.provider, this.model, {
+            conversationId: this.conversationId || undefined,
+            preview: this.sessionPreview || undefined,
+        });
         this.sessionId = session.id;
-        this.sessionPath = session.path;
+        this.conversationId = session.header.conversationId ?? session.id;
+        this.setSessionPath(session.path);
         this.lastPersistedIndex = this.messages.length;
     }
     async loadExistingSession(sessionPath) {
         const loaded = 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);
+        this.conversationId = loaded.header.conversationId ?? loaded.header.id;
+        const legacyLabel = [...loaded.entries]
+            .reverse()
+            .find((entry) => entry.type === "label")
+            ?.label.replace(/\s+/g, " ")
+            .trim()
+            .slice(0, 80);
+        this.sessionPreview =
+            legacyLabel || loaded.header.preview || findUserSessionPrompt(loadedMessages);
         // Restore Nolan's advisory turns (custom entries, not on the message branch) so
         // they reappear in the transcript and survive into the continuation file.
         this.nolanTurns = this.sessionManager.getNolanTurns(loaded.entries);
@@ -1623,9 +1872,15 @@ export class AgentSession {
         this.turnMetrics = this.sessionManager.getTurnMetrics(loaded.entries);
         // Track the current leaf for subsequent entries
         this.currentLeafId = loaded.header.leafId;
-        // Rebuild messages: keep system, add loaded
+        // Rebuild messages: keep system, add loaded. Older ezcoder-app sessions may
+        // contain full-resolution attachments; repair them once on load so they do
+        // not fail when Anthropic's stricter many-image limit activates later.
         const systemMsg = this.messages[0]; // Already built
         this.messages = [systemMsg, ...loadedMessages];
+        const normalizedImageCount = await normalizeMessageImages(this.messages);
+        if (normalizedImageCount > 0) {
+            log("INFO", "session", `Resized ${normalizedImageCount} restored session image(s)`);
+        }
         // Auto-compact on load if the restored session exceeds the context window.
         // Without this, huge sessions (1M+ tokens) get loaded into memory and OOM.
         const creds = await this.authStorage.resolveCredentials(this.provider, {
@@ -1639,7 +1894,15 @@ export class AgentSession {
             provider: this.provider,
             accountId: creds.accountId,
         });
-        if (shouldCompact(this.messages, contextWindow, 0.8, undefined, getCompactionReserveTokens(this.maxTokens))) {
+        const needsLoadCompaction = this.settingsManager.get("autoCompact") &&
+            shouldCompact(this.messages, contextWindow, this.settingsManager.get("compactThreshold"));
+        if (needsLoadCompaction && this.opts.deferLoadCompaction) {
+            // Host readiness is gated on initialize() — don't block it on a summary
+            // LLM call (up to 30s). runLoop()'s pre-run auto-compaction picks this
+            // up on the first prompt and emits compaction_start/_end for the UI.
+            log("INFO", "session", "Restored session exceeds context — deferring compaction to first prompt");
+        }
+        else if (needsLoadCompaction) {
             await this.subAgentManager?.hydrate(loaded.header.id);
             log("INFO", "session", `Restored session exceeds context — auto-compacting`);
             const compacted = await compact(this.messages, {
@@ -1661,9 +1924,13 @@ export class AgentSession {
             // what's in memory — fork a fresh session file for the compacted state
             // (mirrors compact()'s own persistence) so `ezcoder continue` picks up
             // the summary instead of the full original transcript.
-            const session = await this.sessionManager.create(this.cwd, this.provider, this.model);
+            const session = await this.sessionManager.create(this.cwd, this.provider, this.model, {
+                conversationId: this.conversationId || undefined,
+                preview: this.sessionPreview || undefined,
+            });
             this.sessionId = session.id;
-            this.sessionPath = session.path;
+            this.conversationId = session.header.conversationId ?? session.id;
+            this.setSessionPath(session.path);
             await this.subAgentManager?.rebindParentSession(this.sessionId);
             this.currentLeafId = null;
             // Re-persist (compacted) messages — skip system, it's rebuilt on load
@@ -1691,13 +1958,16 @@ export class AgentSession {
         // session was merely reopened (e.g. app/window restart) with zero new
         // messages in between — the duplicate entries seen in the session list.
         this.sessionId = loaded.header.id;
-        this.sessionPath = sessionPath;
+        this.setSessionPath(loaded.path);
         this.lastPersistedIndex = this.messages.length;
     }
     async prepareDynamicContext(_latestUserPrompt) {
         return this.messages;
     }
     async persistMessage(message) {
+        if (!this.sessionPreview && message.role === "user") {
+            this.sessionPreview = getUserSessionPrompt(message.content) ?? "";
+        }
         // Transient sessions (subagent spawns) have no session file — skip.
         if (!this.sessionPath)
             return;