@prestyj/cli 5.10.0 → 5.12.0

package/dist/core/agent-session.js

@@ -6,39 +6,54 @@ 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 { dualAuthProvider } from "@prestyj/core";
 import { getClaudeCliUserAgent } from "./claude-code-version.js";
 import { kimiCodingHeaders, isKimiCodingEndpoint } from "./oauth/kimi.js";
+import { isGrokCliEndpoint } from "./oauth/xai.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 } from "./compaction/compactor.js";
+import { shouldCompact, compact, } from "./compaction/compactor.js";
+import { getHistoryMessageVisibility, remapAnchorForCompaction, stripRecordedPosition, } from "./session-history.js";
+import { sourceFingerprint as computeSourceFingerprint } from "./session-compaction.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";
+import { buildSubAgentSystemPrompt, buildSystemPrompt, } from "../system-prompt.js";
 import { createTools, createWebSearchTool, } from "../tools/index.js";
+import { partitionToolsByTier } from "../tools/tool-tiers.js";
+import { buildProcessCompletionFollowUp } from "./process-gate.js";
 import { buildSubAgentCompletionFollowUp } from "./subagent-manager.js";
 import { applyAsyncSubagentPolicy } from "./subagent-policy.js";
+import { z } from "zod";
 import { MCPClientManager, getAllMcpServers } from "./mcp/index.js";
 import { DeferredToolCatalog } from "./mcp/deferred-catalog.js";
+import { McpCatalogCache } from "./mcp/catalog-cache.js";
+import { describeDropped, importForeignSession, } from "./foreign-session-import.js";
 import { createToolSearchTool } from "../tools/tool-search.js";
 import { log } from "./logger.js";
 import { setEstimatorModel, calibrateEstimatorFromUsage } from "./compaction/token-estimator.js";
 import { calculateActiveContextTokens } from "./compaction/active-context.js";
+import { resolveCompactionPolicy } from "./compaction/policy.js";
 import { pruneStaleToolResults } from "./compaction/tool-result-pruner.js";
 import { discoverAgents } from "./agents.js";
 import { enhancePrompt } from "../utils/prompt-enhancer.js";
 import { detectProjectStack } from "./language-detector.js";
-import { evaluateIdealReview, buildIdealReviewMessage, buildReviewCoverageMessage, withReviewCoverageRequirements, detectTestDrift, ReviewCoverageTracker, } from "./ideal-review.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 } from "./regrounding.js";
-import { wrapSteeringText, STEERING_PREFIX } from "./steering.js";
+import { wrapSteeringText, buildNotificationSteeringText, STEERING_PREFIX } from "./steering.js";
+import { AgentNotificationQueue } from "./agent-notifications.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 os from "node:os";
 import path from "node:path";
+/**
+ * A run whose tool calls fail more often than this is thrashing, not
+ * progressing — refuse to extend its turn budget.
+ */
+const TURN_EXTENSION_MAX_FAILURE_RATIO = 0.5;
 // ── Tool-result policy ─────────────────────────────────────
 /** Resolve the per-result cap passed to the agent loop for the active transport. */
 export function resolveSessionToolResultCharLimit(model, provider, accountId) {
@@ -57,6 +72,17 @@ 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));
 }
+/** Marker the compactor prepends to the summary message it injects. */
+/**
+ * True when an assistant message ends a turn with tool calls still awaiting
+ * their results. Inserting a user message there would orphan the tool_use
+ * blocks and the provider rejects the next request.
+ */
+function hasUnresolvedToolCalls(message) {
+    if (typeof message.content === "string" || !Array.isArray(message.content))
+        return false;
+    return message.content.some((part) => part.type === "tool_call");
+}
 // ── Agent Session ──────────────────────────────────────────
 export class AgentSession {
     eventBus = new EventBus();
@@ -115,12 +141,20 @@ export class AgentSession {
     /** Runtime-only suppression while Nolan owns verification in autopilot mode. */
     idealReviewSuppressed = false;
     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;
+    /** Wall-clock start of the current run; scopes the background-process gate. */
+    runStartedAt = 0;
+    /** Gate injections spent this run, capped by MAX_PROCESS_GATE_INJECTIONS. */
+    processGateInjected = 0;
     compactionOccurred = false;
     lastCompactionCompacted = false;
     compactionRetryAfter = 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. */
     providerContext = null;
     originalRequest = "";
@@ -128,17 +162,39 @@ export class AgentSession {
     // mid-loop steering boundary (user steering wins over the hooks), mirroring
     // the TUI's getSteeringMessages. Each entry carries its own attachments so a
     // user can queue media (images/video/files) mid-run, not just plain text.
+    // Each entry carries a stable id so a client can cancel one specific pending
+    // message by identity. Index-based removal would race: the queue drains at
+    // every turn boundary, so an index captured by the UI can point at a
+    // different message (or past the end) by the time the cancel arrives.
     userQueue = [];
+    queueSeq = 0;
     processManager;
     lspManager;
     subAgentManager;
+    /**
+     * Out-of-band push notifications (finished children, background-process
+     * progress). Producers enqueue; `getHookSteeringMessages` drains into the
+     * live turn so the agent never has to spend a turn asking.
+     */
+    notifications = new AgentNotificationQueue();
     managerAbortSignal;
     managerAbortHandler = () => {
         void this.subAgentManager?.interruptAll();
     };
     mcpManager;
-    /** Deferred MCP tools awaiting discovery via tool_search (bench A win). */
+    /** Deferred MCP tools awaiting discovery via tool_search. */
     mcpCatalog;
+    /**
+     * Built-in tools held in the catalog instead of the live toolset. Their names
+     * still render as one-line hints in the prompt's Tools section, so the model
+     * can discover and promote them; a promoted name drops out of this list.
+     */
+    deferredBuiltinToolNames = [];
+    /** Live (connected) MCP tools by name — the reconcile target for cached stubs. */
+    liveMcpTools = new Map();
+    /** Server name for each cached-only tool, so a stub knows what to wait on. */
+    cachedMcpToolServers = new Map();
+    mcpCatalogCache = new McpCatalogCache();
     provider;
     model;
     cwd;
@@ -151,6 +207,8 @@ export class AgentSession {
     maxTokens;
     thinkingLevel;
     customSystemPrompt;
+    /** Sub-agent definition body composed into the standard prompt scaffolding. */
+    agentPrompt;
     /** Stable prompt prefix retained separately from the volatile uncached tail. */
     baseSystemPrompt = "";
     /** Shared with the tool layer so plan-mode restrictions read live state. */
@@ -162,6 +220,7 @@ export class AgentSession {
     /** Extra workspace roots added with `/add-dir` (resolved, de-duplicated). */
     additionalRoots = [];
     sessionId = "";
+    checkpointGeneration = 0;
     /** Stable identity shared by compaction and approved-plan checkpoint files. */
     conversationId = "";
     /** Original user-authored prompt, retained when internal messages replace history. */
@@ -171,6 +230,15 @@ export class AgentSession {
     transportSessionId = crypto.randomUUID();
     sessionPath = "";
     lastPersistedIndex = 0;
+    /**
+     * The array `agentLoop` is currently mutating, while a run is in flight.
+     *
+     * Normally identical to `this.messages`, but a mid-loop compaction rebinds
+     * `this.messages` to the compacted result while the loop keeps appending to
+     * its own array. Step-boundary flushes must follow the loop's array or they
+     * would silently persist nothing for the rest of the run.
+     */
+    activeLoopMessages = null;
     /**
      * Number of non-system messages guaranteed to be in the session file — the
      * anchor base for transcript markers (Nolan turns, autopilot verdicts, app
@@ -200,6 +268,7 @@ export class AgentSession {
         this.maxTokens = this.resolveMaxTokens(options.model);
         this.thinkingLevel = options.thinkingLevel;
         this.customSystemPrompt = options.systemPrompt;
+        this.agentPrompt = options.agentPrompt;
     }
     /**
      * Derive the output-token cap for a model. Follows the active model's
@@ -268,6 +337,19 @@ export class AgentSession {
                 mode: this.settingsManager.get("networkMode"),
                 allow: this.settingsManager.get("networkAllow"),
             }),
+            getSandboxPolicy: () => ({
+                mode: this.settingsManager.get("sandboxMode"),
+                // networkAllow always applies. Choosing "allowlist" is the user taking
+                // over network policy, so the built-in developer defaults drop out and
+                // only their hosts remain reachable.
+                allowedDomains: this.settingsManager.get("networkAllow"),
+                strictDomains: this.settingsManager.get("networkMode") === "allowlist",
+                // Same source of truth as getWriteGuardSettings, so bash and the write
+                // tool agree on which roots are writable.
+                additionalRoots: this.additionalRoots,
+                allowOutsideWorkspaceWrites: this.settingsManager.get("allowOutsideWorkspaceWrites"),
+            }),
+            getUseExternalGrep: () => this.settingsManager.get("grepUseRipgrep"),
             authStorage: this.authStorage,
             onFileRead: (filePath) => this.reviewCoverage.recordRead(filePath),
             onFileMutated: (filePath) => {
@@ -283,8 +365,12 @@ export class AgentSession {
             getBaseUrl: () => this.baseUrl,
             getCacheKey: () => this.getPromptCacheKey(),
             getMaxPerModel: () => this.settingsManager.get("subagentMaxPerModel"),
-            disableAsyncSubagents: this.opts.subagentWorker,
+            // A persistent child is already the single allowed fan-out level. Blocking
+            // `subagent` here created a timeout sandwich: the nested call could consume
+            // the child's entire 10-minute turn budget, discarding all nested results.
+            disableSubagents: this.opts.subagentWorker,
             onSubAgentState: (snapshot) => this.eventBus.emit("subagent_state", snapshot),
+            notifications: this.notifications,
             // Plan mode: only wired when the host supplies callbacks. The ref is
             // shared so bash/edit/write enforce read-only restrictions live.
             ...(this.opts.onEnterPlan || this.opts.onExitPlan
@@ -301,39 +387,45 @@ export class AgentSession {
         // a hallucinated call can't mutate the repo — and buildSystemPrompt below is
         // fed the same filtered names so the Tools section matches exactly.
         this.tools = this.opts.allowedTools ? tools.filter((t) => this.isToolAllowed(t.name)) : tools;
+        // Tier the built-ins: rarely reached schemas move into the tool_search
+        // catalog and cost one hint line each instead of a full parameter schema on
+        // every request. Allow-listed sessions keep the eager path — their fixed
+        // tool expectations predate the catalog, and tool_search isn't allow-listed.
+        if (!this.opts.allowedTools && this.settingsManager.get("deferredBuiltinTools")) {
+            const { core, deferred } = partitionToolsByTier(this.tools);
+            if (deferred.length > 0) {
+                // Append-only: `core` preserves the original relative order and
+                // tool_search is pushed after it, so the serialized tool block that
+                // sits inside the cached prefix stays byte-stable across turns.
+                this.tools = core;
+                this.deferredBuiltinToolNames = deferred.map((t) => t.name);
+                this.mcpCatalog ??= new DeferredToolCatalog();
+                this.mcpCatalog.add(deferred);
+                this.ensureToolSearchTool();
+            }
+        }
         this.rebuildReadTool = rebuildReadTool;
         this.processManager = processManager;
         this.lspManager = lspManager;
         this.subAgentManager = subAgentManager;
         this.bindManagerCancellation(this.opts.signal);
-        // Connect MCP servers (non-blocking — failures are logged and skipped).
-        // Child sessions (subagents and goal workers run via `--json` mode) get the
-        // provider defaults only — NOT user-configured servers. The defaults now
-        // resolve kencode-search to the locally installed bin instead of a flaky
-        // `npx` cold-spawn, so research tools are reliable here. We deliberately
-        // skip user servers: a single `/expand` fans out 5 parallel subagents, and
-        // cold-spawning every user MCP server (e.g. npx-based remotes) per
-        // short-lived child would be slow and could hammer rate-limited endpoints.
-        //
-        // The connect attempt itself can block for up to the per-server connect
-        // timeout (~30s) — a slow stdio server such as a first-run
-        // `npx -y @playwright/mcp` download stalls here. When the host gates its own
-        // readiness on initialize() (the ezcoder-app sidecar can't emit its
-        // listening handshake until this resolves), `backgroundMcpConnect` moves the
-        // connect off the critical path so the session becomes usable immediately
-        // and tools are appended whenever the servers come up.
-        this.mcpManager = new MCPClientManager();
+        // Connect MCP servers. Child sessions skip user-configured servers to avoid
+        // cold-spawning every server per short-lived worker. Background connection
+        // keeps slow first-run stdio servers off the host readiness path.
+        this.mcpManager = new MCPClientManager({
+            catalogCache: this.mcpCatalogCache,
+            modernProtocol: this.settingsManager.get("mcpModernProtocol"),
+            onElicit: this.opts.onMcpElicit,
+        });
         if (this.opts.backgroundMcpConnect) {
             void this.connectMcpServers();
         }
         else {
             await this.connectMcpServers();
         }
-        const basePrompt = this.customSystemPrompt ??
-            (await buildSystemPrompt(this.cwd, this.skills, false, undefined, this.tools.map((tool) => tool.name), undefined, this.provider, this.promptEnvironment()));
+        const basePrompt = await this.buildBasePrompt(false, undefined);
         this.baseSystemPrompt = basePrompt;
         this.messages = [{ role: "system", content: this.withSystemPromptTail(basePrompt) }];
-        this.syncUltraOrchestrationPrompt();
         // Load or create session. Transient sessions (subagent spawns) never
         // touch the session store — sessionPath stays empty and persistMessage
         // is a no-op so their transcripts can't pollute `ezcoder continue`.
@@ -486,6 +578,11 @@ export class AgentSession {
             if (this.opts.allowedTools && mcpWhitelist) {
                 servers = servers.filter((s) => mcpWhitelist.includes(s.name));
             }
+            // Seed the catalog from the on-disk cache BEFORE connecting. With
+            // `backgroundMcpConnect` the first turns would otherwise run against an
+            // empty catalog and tool_search would answer "the catalog is empty" for
+            // capabilities that genuinely exist — a wrong answer, not a slow one.
+            await this.seedMcpCatalogFromCache(servers);
             const connected = await this.mcpManager.connectAll(servers);
             // Defense-in-depth: even from a whitelisted server, only push tools that
             // pass the allow-list (no-op when there's no allow-list).
@@ -511,8 +608,8 @@ export class AgentSession {
     }
     /**
      * Route freshly connected MCP tools: deferred into the tool_search catalog
-     * (default — keeps ~8k tokens of schema out of every cache-miss turn, see
-     * bench/RESULTS.md bench A) or pushed eagerly when the user opted out.
+     * (default — keeps ~8k tokens of schema out of every cache-miss turn) or
+     * pushed eagerly when the user opted out.
      * Allow-listed sessions (Nolan) always get the eager path — their fixed tool
      * expectations predate the catalog, and tool_search isn't allow-listed.
      * Promotion pushes onto the live `this.tools` array the running agent loop
@@ -521,23 +618,149 @@ export class AgentSession {
     addMcpTools(mcpTools) {
         if (mcpTools.length === 0)
             return;
+        for (const tool of mcpTools) {
+            this.liveMcpTools.set(tool.name, tool);
+            this.cachedMcpToolServers.delete(tool.name);
+        }
         const defer = !this.opts.allowedTools && this.settingsManager.get("deferredMcpTools");
         if (!defer) {
-            this.tools.push(...mcpTools);
+            this.replaceOrPushTools(mcpTools);
             return;
         }
         this.mcpCatalog ??= new DeferredToolCatalog();
+        // `add` is name-keyed, so live definitions replace cached stubs in place.
         this.mcpCatalog.add(mcpTools);
-        if (!this.tools.some((t) => t.name === "tool_search")) {
-            this.tools.push(createToolSearchTool(this.mcpCatalog, (promoted) => {
-                this.tools.push(...promoted);
-            }));
+        // A stub the model already promoted lives in `this.tools`; swap it for the
+        // live tool so later calls dispatch directly instead of through the stub.
+        this.replaceLivePromotedTools(mcpTools);
+        this.ensureToolSearchTool();
+    }
+    /**
+     * Register `tool_search` once. Promotion of a cached-only entry waits for its
+     * server so the model is told immediately when that capability turns out to
+     * be unreachable, instead of promoting a tool that fails on first call.
+     *
+     * The catalog is created on demand rather than required up front: deferred
+     * built-in tools populate it with zero MCP servers connected, so gating
+     * registration on an existing catalog would leave those tools unreachable.
+     */
+    ensureToolSearchTool() {
+        this.mcpCatalog ??= new DeferredToolCatalog();
+        if (this.tools.some((t) => t.name === "tool_search"))
+            return;
+        this.tools.push(createToolSearchTool(this.mcpCatalog, (promoted) => {
+            this.tools.push(...promoted);
+        }, async (toolName) => {
+            if (this.liveMcpTools.has(toolName))
+                return undefined;
+            const serverName = this.cachedMcpToolServers.get(toolName);
+            if (!serverName)
+                return undefined;
+            const outcome = (await this.mcpManager?.whenConnected(serverName)) ?? {
+                ok: false,
+                error: "MCP is disabled for this session",
+            };
+            return outcome.ok
+                ? { serverName, ok: true }
+                : { serverName, ok: false, error: outcome.error };
+        }));
+    }
+    /** Append tools, replacing any same-named entry (cached stub → live tool). */
+    replaceOrPushTools(tools) {
+        for (const tool of tools) {
+            const index = this.tools.findIndex((t) => t.name === tool.name);
+            if (index >= 0)
+                this.tools[index] = tool;
+            else
+                this.tools.push(tool);
+        }
+    }
+    /** Swap already-promoted cached stubs for their live equivalents, in place. */
+    replaceLivePromotedTools(tools) {
+        for (const tool of tools) {
+            const index = this.tools.findIndex((t) => t.name === tool.name);
+            if (index >= 0)
+                this.tools[index] = tool;
         }
     }
     /**
-     * Process user input. Handles slash commands or runs agent loop.
+     * Publish cached tool definitions into the deferred catalog so `tool_search`
+     * answers correctly on turn 1. A cached stub carries the real name, one-line
+     * description and input schema; calling it waits for the live connection and
+     * then dispatches against the real client, or returns a clear error when that
+     * server ultimately failed. Live tools replace stubs on connect.
      */
-    async prompt(content) {
+    async seedMcpCatalogFromCache(servers) {
+        if (!this.opts.backgroundMcpConnect)
+            return;
+        if (this.opts.allowedTools || !this.settingsManager.get("deferredMcpTools"))
+            return;
+        let entries;
+        try {
+            entries = await this.mcpCatalogCache.entriesFor(servers);
+        }
+        catch {
+            return;
+        }
+        const stubs = [];
+        for (const [serverName, entry] of entries) {
+            for (const cached of entry.tools) {
+                if (this.liveMcpTools.has(cached.name))
+                    continue;
+                this.cachedMcpToolServers.set(cached.name, serverName);
+                stubs.push(this.buildCachedMcpTool(serverName, cached));
+            }
+        }
+        if (stubs.length === 0)
+            return;
+        log("INFO", "mcp", "Seeded deferred tool catalog from cache", {
+            tools: String(stubs.length),
+            servers: String(entries.size),
+        });
+        this.addCachedMcpTools(stubs);
+    }
+    /** Catalog-only registration for cached stubs — never marks them live. */
+    addCachedMcpTools(stubs) {
+        this.mcpCatalog ??= new DeferredToolCatalog();
+        this.mcpCatalog.add(stubs);
+        this.ensureToolSearchTool();
+    }
+    buildCachedMcpTool(serverName, cached) {
+        return {
+            name: cached.name,
+            description: cached.description,
+            parameters: z.record(z.string(), z.unknown()),
+            rawInputSchema: cached.rawInputSchema,
+            execute: async (args, context) => {
+                const live = this.liveMcpTools.get(cached.name);
+                if (live)
+                    return live.execute(args, context);
+                const outcome = (await this.mcpManager?.whenConnected(serverName)) ?? {
+                    ok: false,
+                    error: "MCP is disabled for this session",
+                };
+                if (!outcome.ok) {
+                    return (`MCP tool ${cached.name} is unavailable: server "${serverName}" did not connect ` +
+                        `(${outcome.error}). This tool was offered from a cached catalog. ` +
+                        `Use a different approach or ask the user to check their MCP configuration.`);
+                }
+                const connected = this.liveMcpTools.get(cached.name);
+                if (!connected) {
+                    return (`MCP tool ${cached.name} no longer exists: server "${serverName}" connected but ` +
+                        `does not expose it. The cached catalog entry was stale.`);
+                }
+                return connected.execute(args, context);
+            },
+        };
+    }
+    /**
+     * Resolve a `/name [args]` input to the prompt template it expands into, or
+     * null when it isn't a prompt-template command for THIS session (an ordinary
+     * message, a registry/action command, or any slash input on a non-coder
+     * agent). Shared by {@link prompt} and {@link willExpandPromptTemplate} so
+     * callers can't drift from the expansion that actually happens.
+     */
+    async resolveSlashInput(content) {
         const parsedInput = this.slashCommands.parse(content);
         const coderCommands = this.opts.coderSlashCommands !== false;
         // Non-coder agents only intercept commands registered in their own registry.
@@ -545,27 +768,53 @@ export class AgentSession {
         const parsed = parsedInput && (coderCommands || this.slashCommands.get(parsedInput.name))
             ? parsedInput
             : null;
-        if (parsed) {
-            // EZ Coder alone can resolve its prompt-template and project commands.
-            const builtinPromptCmd = coderCommands ? getPromptCommand(parsed.name) : undefined;
-            const customCmds = coderCommands ? await loadCustomCommands(this.cwd) : [];
-            const customPromptCmd = !builtinPromptCmd
-                ? customCmds.find((c) => c.name === parsed.name)
-                : undefined;
-            const promptText = builtinPromptCmd?.prompt ?? customPromptCmd?.prompt;
-            if (promptText) {
-                // Inject the prompt-template command as a user message to the agent
-                const fullPrompt = parsed.args
-                    ? `${promptText}\n\n## User Instructions\n\n${parsed.args}`
-                    : promptText;
-                // Run as a normal prompt (push message + agent loop)
-                const userMessage = { role: "user", content: fullPrompt };
-                this.messages.push(userMessage);
-                await this.persistMessage(userMessage);
-                this.lastPersistedIndex = this.messages.length;
-                await this.runLoop();
-                return;
-            }
+        if (!parsed)
+            return null;
+        // EZ Coder alone can resolve its prompt-template and project commands.
+        const builtinPromptCmd = coderCommands ? getPromptCommand(parsed.name) : undefined;
+        const customCmds = coderCommands ? await loadCustomCommands(this.cwd) : [];
+        const customPromptCmd = !builtinPromptCmd
+            ? customCmds.find((c) => c.name === parsed.name)
+            : undefined;
+        const promptText = builtinPromptCmd?.prompt ?? customPromptCmd?.prompt;
+        if (!promptText)
+            return { kind: "command" };
+        return {
+            kind: "template",
+            fullPrompt: parsed.args
+                ? `${promptText}\n\n## User Instructions\n\n${parsed.args}`
+                : promptText,
+        };
+    }
+    /**
+     * Whether {@link prompt} would expand this input into a template body and
+     * persist it as a user message. Hosts use it to record the typed `/name` for
+     * transcript restore — gating on anything looser risks tagging an unrelated
+     * message when the command turns out NOT to expand.
+     */
+    async willExpandPromptTemplate(content) {
+        return (await this.resolveSlashInput(content))?.kind === "template";
+    }
+    /**
+     * Process user input. Handles slash commands or runs agent loop.
+     */
+    async prompt(content, provenance = {
+        source: "human",
+        kind: "prompt",
+        visibility: "transcript",
+    }, options = {}) {
+        await this.adoptDeferredCheckpointBeforePrompt();
+        const slash = await this.resolveSlashInput(content);
+        if (slash?.kind === "template") {
+            // Prompt templates remain human-originated: the user invoked the command.
+            const userMessage = { role: "user", content: slash.fullPrompt, provenance };
+            this.messages.push(userMessage);
+            await this.persistMessage(userMessage);
+            this.lastPersistedIndex = this.messages.length;
+            await this.runLoop(options);
+            return;
+        }
+        if (slash?.kind === "command") {
             const cmdContext = this.createSlashCommandContext();
             const result = await this.slashCommands.execute(content, cmdContext);
             if (result) {
@@ -574,11 +823,11 @@ export class AgentSession {
             return;
         }
         // Push user message
-        const userMessage = { role: "user", content };
+        const userMessage = { role: "user", content, provenance };
         this.messages.push(userMessage);
         await this.persistMessage(userMessage);
         this.lastPersistedIndex = this.messages.length;
-        await this.runLoop();
+        await this.runLoop(options);
     }
     /**
      * Prompt with multimodal attachments (images / videos) alongside optional
@@ -588,10 +837,15 @@ export class AgentSession {
      * attachments are always a direct conversational turn.
      */
     async promptWithAttachments(text, attachments) {
+        await this.adoptDeferredCheckpointBeforePrompt();
         const parts = this.buildAttachmentParts(text, attachments);
         if (parts.length === 0)
             return;
-        const userMessage = { role: "user", content: parts };
+        const userMessage = {
+            role: "user",
+            content: parts,
+            provenance: { source: "human", kind: "prompt", visibility: "transcript" },
+        };
         this.messages.push(userMessage);
         await this.persistMessage(userMessage);
         this.lastPersistedIndex = this.messages.length;
@@ -680,9 +934,12 @@ export class AgentSession {
         this.hookFileEditCounts.clear();
         this.hookToolCalls.clear();
         this.reviewCoverage.reset();
+        this.reviewCoverageInjected = 0;
         this.idealReviewPhase = "idle";
         this.loopBreakInjected = 0;
         this.regroundingInjected = false;
+        this.runStartedAt = Date.now();
+        this.processGateInjected = 0;
         this.compactionOccurred = false;
         this.originalRequest = originalRequest;
     }
@@ -733,28 +990,94 @@ export class AgentSession {
                     }
                 }
                 await this.persistTurnMetric(event);
+                // The assistant message for this turn is now in the array.
+                await this.flushPendingMessages();
+                break;
+            case "checkpoint":
+                // 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.flushPendingMessages();
                 break;
         }
     }
     /**
-     * Mid-loop steering hook: fires the loop-breaker when the agent looks stuck,
-     * then post-compaction re-grounding. At most one of each per run. Mirrors the
-     * TUI's getSteeringMessages ordering (minus user steering, which the app
-     * delivers as normal prompts).
+     * Append every message added since the last flush to the session file.
+     *
+     * Safe to call mid-run: `agentLoop` mutates its message array in place, so
+     * the slice from `lastPersistedIndex` is always exactly the new tail.
+     * Transient sessions (subagent spawns) have no session file and
+     * `persistMessage` no-ops for them.
+     *
+     * Persistence failures must never take down a live run — the post-loop flush
+     * retries the same range.
+     */
+    async flushPendingMessages() {
+        const messages = this.activeLoopMessages ?? this.messages;
+        if (this.lastPersistedIndex >= messages.length)
+            return;
+        const target = messages.length;
+        try {
+            for (let i = this.lastPersistedIndex; i < target; i++) {
+                await this.persistMessage(messages[i]);
+                this.lastPersistedIndex = i + 1;
+            }
+        }
+        catch (err) {
+            log("WARN", "session", "Failed to flush messages at a step boundary", {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /**
+     * Mid-loop steering hook: delivers pushed notifications and queued user
+     * steering, fires the loop-breaker when the agent looks stuck, then
+     * post-compaction re-grounding. At most one loop-break/re-grounding per run.
+     * Mirrors the TUI's getSteeringMessages ordering.
      */
     getHookSteeringMessages() {
+        // Push notifications: a child that finished or a background build that
+        // exited is new *fact*, not a correction, and it is cheap (bounded to 1 KiB
+        // per drain). Drained above the loop-break checks so the agent can act on
+        // it in the very next turn instead of discovering it at the pre-stop
+        // completion gate — but it never displaces user steering, which rides out
+        // in the same batch when both are pending.
+        const notified = this.notifications.drain();
+        const notificationMessage = notified.length > 0
+            ? {
+                role: "user",
+                content: buildNotificationSteeringText(notified.map((entry) => entry.text)),
+                provenance: { source: "runtime", kind: "notification", visibility: "hidden" },
+            }
+            : null;
+        if (notificationMessage) {
+            log("INFO", "notifications", "Injecting pushed notifications", {
+                count: String(notified.length),
+                chars: String(notificationMessage.content.length),
+            });
+        }
         // User steering wins: drain any messages queued during this run first so the
         // agent sees them mid-loop instead of after it stops.
         if (this.userQueue.length > 0) {
             const queued = this.userQueue.splice(0);
+            // The agent has now consumed these. Announce the new depth immediately so
+            // clients can drop the "queued" affordance at the turn boundary rather
+            // than holding it until the whole run ends — the message is already in
+            // the loop, and showing it as still-pending for minutes is a lie.
+            this.eventBus.emit("queue_drained", { count: this.userQueue.length });
             // Frame each queued item as concurrent steering — without this wrapper
             // the model treats a mid-run message as a fresh request that supersedes
             // the original task and silently drops it. ONE message per queued item
             // (not merged): each persists as its own user message, so a resumed
             // session shows the same number of bubbles the live run did.
-            return queued.map((m) => {
+            const steeringMessages = queued.map((m) => {
+                const provenance = {
+                    source: "human",
+                    kind: "steering",
+                    visibility: "transcript",
+                };
                 if (m.attachments.length === 0) {
-                    return { role: "user", content: wrapSteeringText(m.text) };
+                    return { role: "user", content: wrapSteeringText(m.text), provenance };
                 }
                 // Queued attachments ride the same native-block path as a non-queued
                 // attachment prompt, prefixed with the steering framing.
@@ -762,9 +1085,12 @@ export class AgentSession {
                     { type: "text", text: STEERING_PREFIX },
                     ...this.buildAttachmentParts(m.text, m.attachments),
                 ];
-                return { role: "user", content: parts };
+                return { role: "user", content: parts, provenance };
             });
+            return notificationMessage ? [...steeringMessages, notificationMessage] : steeringMessages;
         }
+        if (notificationMessage)
+            return [notificationMessage];
         if (this.opts.selfCorrectionHooks === false)
             return null;
         if (!this.settingsManager.get("idealReviewEnabled"))
@@ -806,6 +1132,39 @@ export class AgentSession {
         }
         return null;
     }
+    /**
+     * Turn-budget extension gate. The loop consults this instead of stopping
+     * mid-task when it exhausts `maxTurns`. Grant ONLY on evidence of progress —
+     * handing more turns to a spinning agent just buys it more tokens to spin
+     * with — so reuse the same stuck signals that drive the loop-breaker.
+     */
+    shouldExtendTurnBudget(ctx) {
+        const refusals = [];
+        const stuck = evaluateLoopBreak({
+            consecutiveFailures: this.hookConsecutiveFailures,
+            repeatedNoProgressCalls: this.hookRepeatedNoProgressCalls,
+            textRepetitionDetected: detectTextRepetition(this.hookText),
+            ...(this.hookCyclicPattern ? { cyclicPattern: this.hookCyclicPattern } : {}),
+        });
+        if (stuck.shouldBreak)
+            refusals.push(...stuck.reasons);
+        // Stage 2 means the loop-breaker already detected spinning twice and told
+        // the agent to stop and report. Do not overrule that with more turns.
+        if (this.loopBreakInjected >= 2)
+            refusals.push("loop-breaker already escalated");
+        const { toolCalls, toolFailures } = this.hookStats;
+        if (toolCalls > 0 && toolFailures / toolCalls > TURN_EXTENSION_MAX_FAILURE_RATIO) {
+            refusals.push(`${toolFailures}/${toolCalls} tool calls failed`);
+        }
+        const granted = refusals.length === 0;
+        log("INFO", "turn-budget", granted ? "Extending turn budget" : "Refusing turn-budget extension", {
+            turn: String(ctx.turn),
+            maxTurns: String(ctx.maxTurns),
+            extension: String(ctx.extension),
+            ...(granted ? {} : { reasons: refusals.join(", ") }),
+        });
+        return granted;
+    }
     /**
      * Pre-stop Ideal review phase machine. Once review starts, completion is
      * blocked until harness-owned post-injection reads cover every changed file.
@@ -814,6 +1173,17 @@ export class AgentSession {
         const childCompletionFollowUp = buildSubAgentCompletionFollowUp(this.subAgentManager);
         if (childCompletionFollowUp)
             return childCompletionFollowUp;
+        // Background processes started this run and never read block completion:
+        // their progress/exit checkpoints only land on the steering path, which an
+        // agent about to stop never reaches.
+        const processFollowUp = buildProcessCompletionFollowUp(this.processManager?.list() ?? [], this.runStartedAt, this.processGateInjected);
+        if (processFollowUp) {
+            this.processGateInjected += 1;
+            log("INFO", "process-gate", "Injecting background-process completion gate", {
+                injected: String(this.processGateInjected),
+            });
+            return processFollowUp;
+        }
         if (this.opts.selfCorrectionHooks === false || this.idealReviewSuppressed)
             return null;
         if (this.idealReviewPhase === "reviewing") {
@@ -826,9 +1196,20 @@ export class AgentSession {
                 lspMissing: lspEvidence.missing,
             });
             if (coverage.missing.length > 0) {
-                return [
-                    this.withReviewLspEvidence(buildReviewCoverageMessage(coverage.missing), lspEvidence),
-                ];
+                if (this.reviewCoverageInjected < MAX_REVIEW_COVERAGE_INJECTIONS) {
+                    this.reviewCoverageInjected += 1;
+                    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";
+                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;
@@ -886,10 +1267,14 @@ export class AgentSession {
                 : []),
             "Do not describe those files as compiler-clean without other evidence.",
         ];
-        return { role: "user", content: `${String(message.content)}\n\n${notes.join(" ")}` };
+        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() {
+    async runLoop(options = {}) {
         this.refreshSystemPromptTail();
         // One-shot cache-key marker per session so turn_end cacheRead numbers
         // in the log can be traced back to a specific routing namespace —
@@ -917,6 +1302,10 @@ export class AgentSession {
         // Cache for sync callers (see field doc) — kept in step with `creds`
         // through the 401 force-refresh retry below.
         this.lastAccountId = creds.accountId;
+        // The access token most recently handed to the provider. Tracked separately
+        // from `creds` because the per-turn resolver can rotate it mid-run, and the
+        // 401 handler must name the token that was actually rejected.
+        let lastResolvedAccessToken = creds.accessToken;
         // 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. Failed/no-op attempts cool down across
@@ -926,7 +1315,14 @@ export class AgentSession {
                 provider: this.provider,
                 accountId: creds.accountId,
             });
-            const threshold = this.settingsManager.get("compactThreshold");
+            const policy = resolveCompactionPolicy({
+                provider: this.provider,
+                model: this.model,
+                contextWindow,
+                threshold: this.settingsManager.get("compactThreshold"),
+                accountId: creds.accountId,
+                approvedPlanPath: this.approvedPlanPath,
+            });
             let activeTokens;
             if (this.providerContext) {
                 const anchorIndex = this.messages.lastIndexOf(this.providerContext.anchor);
@@ -940,9 +1336,17 @@ export class AgentSession {
                     this.providerContext = null;
                 }
             }
-            if (shouldCompact(this.messages, contextWindow, threshold, activeTokens)) {
+            log("INFO", "compaction", "Pre-run compaction decision", {
+                provider: this.provider,
+                model: this.model,
+                transport: this.provider === "openai" && creds.accountId ? "codex_oauth" : "public_api",
+                contextWindow: String(contextWindow),
+                activeTokens: activeTokens === undefined ? "estimated" : String(activeTokens),
+                triggerLimit: String(policy.targetTokens),
+            });
+            if (shouldCompact(this.messages, contextWindow, policy.threshold, activeTokens)) {
                 try {
-                    await this.compact(creds);
+                    await this.compact(creds, "automatic");
                     if (this.lastCompactionCompacted) {
                         // Re-grounding hook keys off this — the context was just summarized.
                         this.compactionOccurred = true;
@@ -963,17 +1367,36 @@ export class AgentSession {
         const userAgent = this.provider === "anthropic" ? await getClaudeCliUserAgent() : undefined;
         const loopMessages = await this.prepareDynamicContext();
         const runAgentLoop = async (apiKey, accountId, projectId) => {
+            lastResolvedAccessToken = apiKey;
             const modelInfo = getModel(this.model);
             const effectiveBaseUrl = this.baseUrl ?? creds.baseUrl;
             const generator = agentLoop(loopMessages, {
                 provider: this.provider,
                 model: this.model,
-                tools: this.tools,
-                webSearch: true,
+                tools: options.disableTools ? [] : this.tools,
+                webSearch: !options.disableTools,
                 maxTokens: this.maxTokens,
                 maxTurns: this.opts.maxTurns,
+                maxTurnExtensions: this.opts.maxTurnExtensions,
                 thinking: this.thinkingLevel,
                 apiKey,
+                // Per-turn credential resolution. A run can span many minutes; if any
+                // process sharing auth.json refreshes this grant meanwhile, the token
+                // captured above is invalidated server-side and every remaining turn
+                // would fail with an authentication error until the user restarted.
+                // Static API keys resolve to the same value, so this is a no-op for them.
+                resolveCredentials: async () => {
+                    const live = await this.authStorage.resolveCredentials(this.provider, {
+                        storageKeys: this.currentAuthStorageKeys(),
+                    });
+                    this.lastAccountId = live.accountId;
+                    lastResolvedAccessToken = live.accessToken;
+                    return {
+                        apiKey: live.accessToken,
+                        ...(live.accountId !== undefined ? { accountId: live.accountId } : {}),
+                        ...(live.projectId !== undefined ? { projectId: live.projectId } : {}),
+                    };
+                },
                 baseUrl: effectiveBaseUrl,
                 signal: this.opts.signal,
                 accountId,
@@ -1000,6 +1423,7 @@ export class AgentSession {
                 // polled mid-loop; the ideal review is polled when the agent would stop.
                 getSteeringMessages: () => this.getHookSteeringMessages(),
                 getFollowUpMessages: () => this.getHookFollowUpMessages(),
+                onTurnBudgetExhausted: (ctx) => this.shouldExtendTurnBudget(ctx),
                 // 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.
@@ -1026,6 +1450,7 @@ export class AgentSession {
                             this.providerContext = null;
                             log("INFO", "compaction", "Pruned stale tool outputs", {
                                 prunedResults: String(pruneResult.prunedResults),
+                                compactedToolCalls: String(pruneResult.compactedToolCalls),
                                 freedTokens: String(pruneResult.freedTokens),
                             });
                         }
@@ -1050,12 +1475,27 @@ export class AgentSession {
                             provider: this.provider,
                             accountId,
                         });
-                        const threshold = this.settingsManager.get("compactThreshold");
+                        const policy = resolveCompactionPolicy({
+                            provider: this.provider,
+                            model: this.model,
+                            contextWindow,
+                            threshold: this.settingsManager.get("compactThreshold"),
+                            accountId,
+                            approvedPlanPath: this.approvedPlanPath,
+                        });
                         const activeTokens = calculateActiveContextTokens(messages, {
                             usage,
                             pendingMessages,
                         });
-                        if (!shouldCompact(messages, contextWindow, threshold, activeTokens))
+                        log("INFO", "compaction", "In-flight compaction decision", {
+                            provider: this.provider,
+                            model: this.model,
+                            transport: this.provider === "openai" && accountId ? "codex_oauth" : "public_api",
+                            contextWindow: String(contextWindow),
+                            activeTokens: String(activeTokens),
+                            triggerLimit: String(policy.targetTokens),
+                        });
+                        if (!shouldCompact(messages, contextWindow, policy.threshold, activeTokens))
                             return messages;
                     }
                     // compact() operates on this.messages, while an earlier transform may
@@ -1068,7 +1508,7 @@ export class AgentSession {
                             accountId,
                             projectId,
                             baseUrl: effectiveBaseUrl,
-                        });
+                        }, force ? "forced" : "automatic");
                     }
                     catch (error) {
                         this.messages = messages;
@@ -1088,9 +1528,15 @@ export class AgentSession {
                     return this.messages;
                 },
             });
-            for await (const event of generator) {
-                await this.trackHookEvent(event);
-                this.eventBus.forwardAgentEvent(event);
+            this.activeLoopMessages = loopMessages;
+            try {
+                for await (const event of generator) {
+                    await this.trackHookEvent(event);
+                    this.eventBus.forwardAgentEvent(event);
+                }
+            }
+            finally {
+                this.activeLoopMessages = null;
             }
         };
         const clearInvalidStaticApiKey = async (error) => {
@@ -1114,29 +1560,45 @@ export class AgentSession {
             if (isAbortError(err) || this.opts.signal?.aborted) {
                 return;
             }
-            // 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" &&
+            // A subscription OAuth plan ran out of usage (hard usage-limit stop, or an
+            // HTTP 402 billing stop). If the user ALSO configured that provider's 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.
+            //
+            // Grok adds one case Kimi doesn't have: xAI gates its CLI chat proxy by
+            // subscription tier, so an entitled-looking account can be refused outright
+            // with a 403. That means "OAuth cannot serve this", not a transient error,
+            // so it counts as exhausted too — otherwise a dual-configured user would
+            // hard-fail while holding a perfectly good API key.
+            //
+            // Guarded on the subscription endpoint actually being in use: if the API key
+            // was already active, the same error means BOTH are out and must surface.
+            const dualAuth = dualAuthProvider(this.provider);
+            const onSubscriptionEndpoint = (this.provider === "moonshot" && isKimiCodingEndpoint(creds.baseUrl)) ||
+                (this.provider === "xai" && isGrokCliEndpoint(creds.baseUrl));
+            const tierRefusal = this.provider === "xai" && err instanceof ProviderError && err.statusCode === 403;
+            const oauthIsOut = isUsageLimitError(err) ||
+                (err instanceof ProviderError && err.statusCode === 402) ||
+                tierRefusal;
+            if (dualAuth &&
                 !this.baseUrl &&
-                isKimiCodingEndpoint(creds.baseUrl) &&
-                (isUsageLimitError(err) || (err instanceof ProviderError && err.statusCode === 402)) &&
-                (await this.authStorage.hasCredentials("moonshot"))) {
+                onSubscriptionEndpoint &&
+                oauthIsOut &&
+                (await this.authStorage.hasCredentials(dualAuth.provider))) {
                 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" });
+                await this.authStorage.markUsageExhausted(dualAuth.oauthKey, resetsAt);
+                log("WARN", "auth", `${dualAuth.oauthLabel} usage limit reached — retrying this turn on the ${dualAuth.apiKeyLabel}`, { 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.
+                // API key's public baseUrl (api.moonshot.ai / api.x.ai) and drops the
+                // subscription endpoint's client-identity headers.
                 try {
                     await runAgentLoop(creds.accessToken, creds.accountId, creds.projectId);
                 }
@@ -1151,15 +1613,21 @@ export class AgentSession {
             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.
+                // credential and surface the error so the user re-logins. Subscription
+                // OAuth (active for `moonshot`/`xai` when present) is refreshable, so it
+                // falls through to the force-refresh path below.
                 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,
                     storageKeys: this.currentAuthStorageKeys(),
+                    // Name the token the provider actually rejected (which the per-turn
+                    // resolver may have rotated since the run started). If disk already
+                    // holds a newer one, adopt it instead of minting another — a fresh
+                    // refresh would invalidate the token every sibling process is using
+                    // and turn one 401 into a cascade of them.
+                    rejectedToken: lastResolvedAccessToken,
                 });
                 this.lastAccountId = creds.accountId;
                 await runAgentLoop(creds.accessToken, creds.accountId, creds.projectId);
@@ -1169,7 +1637,9 @@ export class AgentSession {
             }
         }
         this.messages = loopMessages;
-        // Persist new messages
+        // Backstop. Step-boundary flushes (checkpoint / turn_end) normally leave
+        // nothing here, but this still catches messages appended after the last
+        // checkpoint — an aborted final step, or a flush that failed mid-run.
         for (let i = this.lastPersistedIndex; i < this.messages.length; i++) {
             await this.persistMessage(this.messages[i]);
         }
@@ -1177,6 +1647,11 @@ export class AgentSession {
     }
     async switchModel(provider, model) {
         const prevProvider = this.provider;
+        const prevModel = this.model;
+        // Diff gate: a "switch" to the model already in use is not state change.
+        // Recording it anyway would write a redundant marker and a redundant
+        // history note on every no-op re-selection from the UI.
+        const changed = model !== prevModel || (Boolean(provider) && provider !== prevProvider);
         if (provider)
             this.provider = provider;
         this.model = model;
@@ -1185,7 +1660,6 @@ export class AgentSession {
         // the live selection after an in-session model switch.
         this.opts.provider = this.provider;
         this.opts.model = this.model;
-        this.syncUltraOrchestrationPrompt();
         setEstimatorModel(model);
         // maxTokens must follow the active model — it was frozen at the boot
         // model's `maxOutputTokens` in the constructor, so without this a session
@@ -1206,6 +1680,27 @@ export class AgentSession {
             const newReadTool = this.rebuildReadTool(model);
             this.tools = this.tools.map((t) => (t.name === "read" ? newReadTool : t));
         }
+        // Model-dependent guidance lives in the uncached tail, so this rewrites
+        // only the bytes after the cache marker — the cached prefix survives the
+        // switch intact and the next turn still reads from cache.
+        this.refreshSystemPromptTail();
+        if (changed) {
+            // Durable, replayable record of which model produced which segment. Rides
+            // the existing app-marker path (parentId null, anchored by message count)
+            // so a resumed session reconstructs the switch without the LLM seeing an
+            // extra transcript row.
+            await this.persistAppMarker("model_switch", {
+                from: prevModel,
+                to: this.model,
+                provider: this.provider,
+                fromProvider: prevProvider,
+            }).catch((error) => {
+                log("WARN", "session", "Failed to persist model-switch marker", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            });
+            this.appendModelSwitchNote(prevModel, prevProvider);
+        }
         // Update provider-specific tools when provider changes
         if (provider && provider !== prevProvider) {
             // Add/remove client-side web_search tool based on provider.
@@ -1252,6 +1747,8 @@ export class AgentSession {
                     // re-adding. Some tools may already have been promoted out of the catalog.
                     this.tools = this.tools.filter((t) => !t.name.startsWith("mcp__"));
                     this.mcpCatalog?.removeWhere((name) => name.startsWith("mcp__"));
+                    this.liveMcpTools.clear();
+                    this.cachedMcpToolServers.clear();
                     this.addMcpTools(mcpTools);
                 }
                 catch (err) {
@@ -1260,7 +1757,93 @@ export class AgentSession {
             }
         }
     }
-    async compact(existingCredentials) {
+    /**
+     * Record the switch as its own trailing message at the point it happened,
+     * rather than by rewriting the system prompt. Two reasons: the system prompt
+     * is the cached prefix and rewriting it costs a full cache write, and a
+     * resumed transcript can only attribute output to the right model if the
+     * switch sits in message order.
+     *
+     * Skipped before the conversation starts (nothing to disambiguate) and while
+     * an assistant turn has unresolved tool calls, where inserting a user message
+     * would break tool_use/tool_result pairing.
+     */
+    appendModelSwitchNote(prevModel, prevProvider) {
+        const last = this.messages[this.messages.length - 1];
+        if (!last || last.role === "system")
+            return;
+        if (last.role === "assistant" && hasUnresolvedToolCalls(last))
+            return;
+        const from = prevProvider === this.provider ? prevModel : `${prevProvider}/${prevModel}`;
+        const to = prevProvider === this.provider ? this.model : `${this.provider}/${this.model}`;
+        this.messages.push({
+            role: "user",
+            content: `[Model switched from ${from} to ${to}. Everything above was produced under the previous model; continue the current task from here.]`,
+            provenance: { source: "runtime", kind: "model_switch", visibility: "hidden" },
+        });
+    }
+    async adoptCompactionCheckpoint(loaded) {
+        const systemMessage = this.messages[0];
+        const loadedMessages = this.sessionManager.getMessages(loaded.entries, loaded.header.leafId);
+        this.messages = [systemMessage, ...loadedMessages];
+        this.sessionId = loaded.header.id;
+        this.conversationId = loaded.header.conversationId ?? loaded.header.id;
+        this.checkpointGeneration = loaded.header.generation ?? 0;
+        this.currentLeafId = loaded.header.leafId;
+        this.setSessionPath(loaded.path);
+        this.nolanTurns = this.sessionManager.getNolanTurns(loaded.entries, loaded.header.leafId);
+        this.autopilotMarkers = this.sessionManager.getAutopilotMarkers(loaded.entries, loaded.header.leafId);
+        this.appMarkers = this.sessionManager.getAppMarkers(loaded.entries, loaded.header.leafId);
+        this.turnMetrics = this.sessionManager.getTurnMetrics(loaded.entries);
+        this.lastPersistedIndex = this.messages.length;
+        this.providerContext = null;
+        await this.subAgentManager?.rebindParentSession(this.sessionId);
+    }
+    /** Canonicalize a deferred restore before a new prompt can fork stale history. */
+    async adoptDeferredCheckpointBeforePrompt() {
+        if (!this.deferredCompactionPending || !this.conversationId)
+            return;
+        this.deferredCompactionPending = false;
+        const canonicalPath = await this.sessionManager.resolveCanonicalSession(this.conversationId, this.cwd);
+        if (!canonicalPath || canonicalPath === this.sessionPath)
+            return;
+        await this.adoptCompactionCheckpoint(await this.sessionManager.load(canonicalPath));
+    }
+    async persistCompactionCheckpoint(sourceFingerprint, result) {
+        const parentSessionId = this.sessionId || undefined;
+        const session = await this.sessionManager.create(this.cwd, this.provider, this.model, {
+            conversationId: this.conversationId || undefined,
+            generation: this.checkpointGeneration + 1,
+            parentSessionId,
+            sourceFingerprint,
+            retainedMessageCount: result.retainedCount === 0
+                ? 0
+                : this.messages
+                    .slice(-result.retainedCount)
+                    .filter((message) => getHistoryMessageVisibility(message) !== "hidden").length,
+            preview: this.sessionPreview || undefined,
+        });
+        this.sessionId = session.id;
+        this.checkpointGeneration = session.header.generation ?? 0;
+        this.conversationId = session.header.conversationId ?? session.id;
+        this.currentLeafId = null;
+        this.setSessionPath(session.path);
+        await this.subAgentManager?.rebindParentSession(this.sessionId);
+        for (const message of this.messages) {
+            if (message.role !== "system")
+                await this.persistMessage(message);
+        }
+        this.lastPersistedIndex = this.messages.length;
+        await this.rePersistTurnMetrics();
+        await this.rePersistNolanTurns();
+        await this.rePersistAutopilotMarkers();
+        await this.rePersistAppMarkers();
+        await this.persistAppMarker("compaction", {
+            originalCount: result.originalCount,
+            newCount: result.newCount,
+        });
+    }
+    async compact(existingCredentials, mode = "manual") {
         this.lastCompactionCompacted = false;
         const creds = existingCredentials ??
             (await this.authStorage.resolveCredentials(this.provider, {
@@ -1270,71 +1853,141 @@ export class AgentSession {
             provider: this.provider,
             accountId: creds.accountId,
         });
-        this.eventBus.emit("compaction_start", { messageCount: this.messages.length });
-        const result = await compact(this.messages, {
+        const policy = resolveCompactionPolicy({
             provider: this.provider,
             model: this.model,
-            apiKey: creds.accessToken,
-            accountId: creds.accountId,
-            projectId: creds.projectId,
-            baseUrl: this.baseUrl ?? creds.baseUrl,
             contextWindow,
-            signal: this.opts.signal,
+            threshold: this.settingsManager.get("compactThreshold"),
+            accountId: creds.accountId,
+            approvedPlanPath: this.approvedPlanPath,
         });
-        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,
+        const originalCount = this.messages.length;
+        this.eventBus.emit("compaction_start", { messageCount: originalCount });
+        let contextSelection;
+        const runCompactor = async () => {
+            const output = await compact(this.messages, {
+                provider: this.provider,
+                model: this.model,
+                apiKey: creds.accessToken,
+                accountId: creds.accountId,
+                projectId: creds.projectId,
+                baseUrl: this.baseUrl ?? creds.baseUrl,
+                contextWindow,
+                targetTokens: policy.targetTokens,
+                signal: this.opts.signal,
+                approvedPlanPath: this.approvedPlanPath,
             });
-            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
-        // the "in-memory only" session into a persisted one — every later turn (and
-        // every further compaction) then leaked a Nolan transcript file into the
-        // project's session list. Compact in memory only and keep sessionPath empty.
-        if (this.opts.transient) {
-            this.lastPersistedIndex = this.messages.length;
+            contextSelection = output.result.contextSelection;
+            return output;
+        };
+        let finalCount = originalCount;
+        if (this.opts.transient || !this.conversationId) {
+            const result = await runCompactor();
+            finalCount = result.result.newCount;
+            this.messages = result.messages;
+            this.lastCompactionCompacted = result.result.compacted;
+            if (result.result.compacted) {
+                this.providerContext = null;
+                this.remapMarkerAnchors(result.result.anchorRemap);
+                this.lastPersistedIndex = this.messages.length;
+            }
         }
         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, {
-                conversationId: this.conversationId || undefined,
-                preview: this.sessionPreview || undefined,
-            });
-            this.sessionId = session.id;
-            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) {
-                if (msg.role === "system")
-                    continue;
-                await this.persistMessage(msg);
-            }
-            this.lastPersistedIndex = this.messages.length;
-            // Carry evidence and Nolan's advisory turns into the new file so they survive compaction.
-            await this.rePersistTurnMetrics();
-            await this.rePersistNolanTurns();
-            await this.rePersistAutopilotMarkers();
-            await this.rePersistAppMarkers();
-            // Persist the compaction counts so a resumed session's quiet notice can
-            // show the same "N → M messages" summary the live run did.
-            await this.persistAppMarker("compaction", {
-                originalCount: result.result.originalCount,
-                newCount: result.result.newCount,
+            const conversationId = this.conversationId;
+            await this.sessionManager.withCompactionLease(conversationId, this.opts.signal, async () => {
+                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);
+                    if (newest.header.sourceFingerprint === sourceFingerprint) {
+                        await this.adoptCompactionCheckpoint(newest);
+                        this.lastCompactionCompacted = true;
+                        finalCount = this.messages.length;
+                        return;
+                    }
+                    // The canonical branch contains different progress. Rebase onto it before
+                    // compacting so a stale caller cannot supersede newer history by generation.
+                    await this.adoptCompactionCheckpoint(newest);
+                    sourceFingerprint = computeSourceFingerprint(this.messages);
+                }
+                const attempt = await this.sessionManager.readCompactionAttemptState(conversationId);
+                const attemptActive = !attempt?.expiresAt || Date.parse(attempt.expiresAt) > Date.now();
+                if (mode === "automatic" &&
+                    attempt?.fingerprint === sourceFingerprint &&
+                    attempt.policyKey === policy.policyKey &&
+                    attemptActive) {
+                    if (attempt.outcome === "success" && attempt.checkpointId) {
+                        const checkpointPath = await this.sessionManager.findById(this.cwd, attempt.checkpointId);
+                        if (checkpointPath) {
+                            const checkpoint = await this.sessionManager.load(checkpointPath);
+                            if (checkpoint.header.sourceFingerprint === sourceFingerprint) {
+                                await this.adoptCompactionCheckpoint(checkpoint);
+                                this.lastCompactionCompacted = true;
+                                finalCount = this.messages.length;
+                                return;
+                            }
+                        }
+                    }
+                    else if (attempt.outcome === "failed" || attempt.outcome === "noop") {
+                        return;
+                    }
+                }
+                try {
+                    const result = await runCompactor();
+                    finalCount = result.result.newCount;
+                    this.messages = result.messages;
+                    this.lastCompactionCompacted = result.result.compacted;
+                    if (!result.result.compacted) {
+                        await this.sessionManager.writeCompactionAttemptState(conversationId, {
+                            fingerprint: sourceFingerprint,
+                            policyKey: policy.policyKey,
+                            outcome: "noop",
+                            updatedAt: new Date().toISOString(),
+                            expiresAt: new Date(Date.now() + 30_000).toISOString(),
+                        });
+                        return;
+                    }
+                    this.providerContext = null;
+                    this.remapMarkerAnchors(result.result.anchorRemap);
+                    await this.persistCompactionCheckpoint(sourceFingerprint, result.result);
+                    await this.sessionManager.writeCompactionAttemptState(conversationId, {
+                        fingerprint: sourceFingerprint,
+                        policyKey: policy.policyKey,
+                        outcome: "success",
+                        checkpointId: this.sessionId,
+                        updatedAt: new Date().toISOString(),
+                    });
+                }
+                catch (error) {
+                    await this.sessionManager
+                        .writeCompactionAttemptState(conversationId, {
+                        fingerprint: sourceFingerprint,
+                        policyKey: policy.policyKey,
+                        outcome: "failed",
+                        updatedAt: new Date().toISOString(),
+                        expiresAt: new Date(Date.now() + 30_000).toISOString(),
+                    })
+                        .catch(() => { });
+                    throw error;
+                }
             });
         }
         this.eventBus.emit("compaction_end", {
-            compacted: true,
-            originalCount: result.result.originalCount,
-            newCount: result.result.newCount,
+            compacted: this.lastCompactionCompacted,
+            originalCount,
+            newCount: finalCount,
+            ...(contextSelection
+                ? {
+                    selectionStrategy: contextSelection.strategy,
+                    selectedMessages: contextSelection.selectedMessages,
+                    selectedTokens: contextSelection.selectedTokens,
+                    droppedMessages: contextSelection.droppedMessages,
+                    queryTerms: contextSelection.queryTerms,
+                    ...(contextSelection.fallbackReason
+                        ? { selectionFallback: contextSelection.fallbackReason }
+                        : {}),
+                }
+                : {}),
         });
     }
     async newSession(preserveConversation = false) {
@@ -1342,6 +1995,7 @@ export class AgentSession {
         // explicit new sessions reset the conversation identity.
         if (!preserveConversation) {
             this.conversationId = "";
+            this.checkpointGeneration = 0;
             this.sessionPreview = "";
         }
         // A fresh session drops any in-flight plan state so its prompt is clean.
@@ -1355,11 +2009,9 @@ export class AgentSession {
         this.autopilotMarkers = [];
         this.appMarkers = [];
         this.turnMetrics = [];
-        const basePrompt = this.customSystemPrompt ??
-            (await buildSystemPrompt(this.cwd, this.skills, false, undefined, this.tools.map((tool) => tool.name), undefined, this.provider, this.promptEnvironment()));
+        const basePrompt = await this.buildBasePrompt(false, undefined);
         this.baseSystemPrompt = basePrompt;
         this.messages = [{ role: "system", content: this.withSystemPromptTail(basePrompt) }];
-        this.syncUltraOrchestrationPrompt();
         // 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
@@ -1370,6 +2022,7 @@ export class AgentSession {
         if (this.opts.transient) {
             this.sessionId = "";
             this.conversationId = "";
+            this.checkpointGeneration = 0;
             this.sessionPreview = "";
             this.setSessionPath("");
             this.lastPersistedIndex = this.messages.length;
@@ -1442,6 +2095,41 @@ export class AgentSession {
             accountId: this.lastAccountId,
         };
     }
+    /**
+     * Tokens currently in context and the window they are measured against.
+     *
+     * Uses the same accounting as the compaction decision: authoritative provider
+     * usage when we have it (it includes the system prompt and tool schemas),
+     * plus a local estimate of anything appended after that sample. A client
+     * reading this right after a compaction sees the drop, because compaction
+     * clears the retained provider sample along with the messages it measured.
+     *
+     * `costUsd` is present only when EVERY recorded turn has an authoritative
+     * price; a partial sum would read as a full session cost and understate it.
+     */
+    getContextUsage() {
+        const size = getContextWindow(this.model, {
+            provider: this.provider,
+            accountId: this.lastAccountId,
+        });
+        let used;
+        const anchorIndex = this.providerContext
+            ? this.messages.lastIndexOf(this.providerContext.anchor)
+            : -1;
+        if (this.providerContext && anchorIndex >= 0) {
+            used = calculateActiveContextTokens(this.messages, {
+                usage: this.providerContext.usage,
+                pendingMessages: this.messages.slice(anchorIndex + 1),
+            });
+        }
+        else {
+            used = calculateActiveContextTokens(this.messages);
+        }
+        const costUsd = this.turnMetrics.length > 0 && this.turnMetrics.every((m) => m.cost.status === "known")
+            ? this.turnMetrics.reduce((sum, m) => sum + (m.cost.status === "known" ? m.cost.usd : 0), 0)
+            : undefined;
+        return costUsd === undefined ? { used, size } : { used, size, costUsd };
+    }
     getPlanMode() {
         return this.planModeRef.current;
     }
@@ -1461,9 +2149,25 @@ export class AgentSession {
      *  as steering. Returns the new queue length. No-op semantics are the caller's
      *  concern. */
     queueMessage(text, attachments = []) {
-        this.userQueue.push({ text, attachments });
+        this.queueSeq += 1;
+        this.userQueue.push({ id: `q${this.queueSeq}`, text, attachments });
         return this.userQueue.length;
     }
+    /** Pending queued messages (id + text), oldest first, for client display. */
+    listQueuedMessages() {
+        return this.userQueue.map((m) => ({ id: m.id, text: m.text }));
+    }
+    /** Cancel one pending message by id. Returns true if it was still queued.
+     *  A false return is the normal race rather than an error: the message drained
+     *  into the run between the client rendering the cancel affordance and the
+     *  click arriving. */
+    cancelQueuedMessage(id) {
+        const index = this.userQueue.findIndex((m) => m.id === id);
+        if (index === -1)
+            return false;
+        this.userQueue.splice(index, 1);
+        return true;
+    }
     /** Number of messages currently queued. */
     getQueuedCount() {
         return this.userQueue.length;
@@ -1473,7 +2177,13 @@ export class AgentSession {
      *  reviewing (no run in flight to steer it into) — unlike {@link drainQueue},
      *  attachments survive so queued media isn't silently dropped. */
     takeNextQueuedMessage() {
-        return this.userQueue.shift() ?? null;
+        const next = this.userQueue.shift();
+        if (next === undefined)
+            return null;
+        // Strip the internal queue id: it exists only so clients can cancel a
+        // specific pending message, and callers here feed the result straight into
+        // a run.
+        return { text: next.text, attachments: next.attachments };
     }
     /** Clear the queue, returning the combined text (to restore to the composer).
      *  Queued attachments are dropped on cancel — the composer only restores text. */
@@ -1507,7 +2217,6 @@ export class AgentSession {
         else {
             this.messages.unshift({ role: "system", content });
         }
-        this.syncUltraOrchestrationPrompt();
     }
     /**
      * Toggle plan mode: flips the shared ref (so tools enforce read-only
@@ -1582,6 +2291,17 @@ export class AgentSession {
         await this.rebuildSystemPromptInPlace();
         return { ok: true, root: resolved };
     }
+    /**
+     * Names to advertise as available-on-demand. A tool the model already
+     * promoted lives in `this.tools` and carries its own schema, so it drops out
+     * of the index rather than being listed twice.
+     */
+    deferredToolNamesForPrompt(liveNames) {
+        if (this.deferredBuiltinToolNames.length === 0)
+            return [];
+        const live = new Set(liveNames);
+        return this.deferredBuiltinToolNames.filter((name) => !live.has(name));
+    }
     /** Environment facts that vary per session rather than per host. */
     promptEnvironment() {
         const networkAllow = this.settingsManager.get("networkMode") === "allowlist"
@@ -1589,11 +2309,37 @@ export class AgentSession {
             : [];
         return { additionalRoots: this.additionalRoots, networkAllow };
     }
+    /**
+     * Build the stable system-prompt prefix for the current tool set and state.
+     *
+     * Three modes, in precedence order: a full replacement (`systemPrompt`), a
+     * composed sub-agent prompt (`agentPrompt` — agent body plus Tools, project
+     * context, return contract and Environment), or the standard prompt.
+     */
+    async buildBasePrompt(planMode, approvedPlanPath) {
+        if (this.customSystemPrompt)
+            return this.customSystemPrompt;
+        const toolNames = this.tools.map((tool) => tool.name);
+        const deferredToolNames = this.deferredToolNamesForPrompt(toolNames);
+        if (this.agentPrompt !== undefined) {
+            return buildSubAgentSystemPrompt(this.agentPrompt, {
+                cwd: this.cwd,
+                toolNames,
+                deferredToolNames,
+                context: this.opts.agentContext,
+                environment: this.promptEnvironment(),
+            });
+        }
+        return buildSystemPrompt(this.cwd, this.skills, planMode, approvedPlanPath, toolNames, undefined, this.provider, this.promptEnvironment(), deferredToolNames);
+    }
     /** Rebuild messages[0] from current plan-mode + approved-plan state. */
     async rebuildSystemPromptInPlace() {
+        // A full replacement is verbatim by contract — there is nothing to rebuild.
+        // A composed agent prompt still must be: its Tools section has to follow
+        // late-arriving MCP tools, or a compacted child loses tools it can call.
         if (this.customSystemPrompt)
             return;
-        const rebuilt = await buildSystemPrompt(this.cwd, this.skills, this.planModeRef.current, this.approvedPlanPath, this.tools.map((tool) => tool.name), undefined, this.provider, this.promptEnvironment());
+        const rebuilt = await this.buildBasePrompt(this.planModeRef.current, this.approvedPlanPath);
         this.baseSystemPrompt = rebuilt;
         const content = this.withSystemPromptTail(rebuilt);
         if (this.messages[0]?.role === "system") {
@@ -1602,18 +2348,47 @@ export class AgentSession {
         else {
             this.messages.unshift({ role: "system", content });
         }
-        this.syncUltraOrchestrationPrompt();
     }
+    /**
+     * Compose the system message: stable prefix, then everything volatile behind
+     * the `<!-- uncached -->` marker that providers split on for cache control.
+     *
+     * Anything that varies with the live model/provider/thinking level belongs in
+     * the tail. Putting it in the prefix means every model switch rewrites cached
+     * bytes and the next turn pays a full cache write instead of a read.
+     */
     withSystemPromptTail(basePrompt) {
-        if (!this.opts.getSystemPromptTail)
+        const tailParts = [];
+        const orchestration = this.orchestrationPolicyTail();
+        if (orchestration)
+            tailParts.push(orchestration);
+        const hostTail = this.opts.getSystemPromptTail?.();
+        if (hostTail)
+            tailParts.push(hostTail);
+        if (tailParts.length === 0)
             return basePrompt;
-        return `${basePrompt}\n\n<!-- uncached -->\n${this.opts.getSystemPromptTail()}`;
+        return `${basePrompt}\n\n<!-- uncached -->\n${tailParts.join("\n\n")}`;
+    }
+    /**
+     * Sol/Terra async-orchestration guidance for the CURRENT model and thinking
+     * level. Per-switch volatile by definition, so it is rendered as a tail part
+     * rather than spliced into the cached prefix.
+     */
+    orchestrationPolicyTail() {
+        if (this.opts.orchestrationPrompt === false)
+            return "";
+        return applyAsyncSubagentPolicy("", this.provider, this.model, this.thinkingLevel, this.tools.map((tool) => tool.name)).trim();
     }
+    /**
+     * Re-render the uncached tail of messages[0] in place. The cached prefix is
+     * byte-identical afterwards, so this is safe to call on every model /
+     * thinking-level change.
+     */
     refreshSystemPromptTail() {
-        if (!this.opts.getSystemPromptTail)
-            return;
         const content = this.withSystemPromptTail(this.baseSystemPrompt);
         if (this.messages[0]?.role === "system") {
+            if (this.messages[0].content === content)
+                return;
             this.messages[0] = { role: "system", content };
         }
         else {
@@ -1668,6 +2443,29 @@ export class AgentSession {
     getAutopilotMarkers() {
         return this.autopilotMarkers;
     }
+    /** Non-system messages that are actually on disk. Transcript markers anchor
+     *  against this (not the in-memory list, which can run ahead after a failed
+     *  run), so hosts computing marker-derived values must use the same base. */
+    getPersistedTranscriptCount() {
+        return this.persistedTranscriptCount();
+    }
+    /**
+     * Rebase every transcript anchor (Nolan turns, autopilot verdicts, app markers)
+     * onto a freshly compacted message list. Called right after `this.messages`
+     * is replaced and before the markers are re-persisted into the continuation
+     * file, so the new file carries positions that match its own transcript.
+     */
+    remapMarkerAnchors(remap) {
+        if (!remap)
+            return;
+        const move = (payload) => ({
+            ...payload,
+            afterMessageCount: remapAnchorForCompaction(payload.afterMessageCount, remap),
+        });
+        this.nolanTurns = this.nolanTurns.map(move);
+        this.autopilotMarkers = this.autopilotMarkers.map(move);
+        this.appMarkers = this.appMarkers.map(move);
+    }
     /**
      * Record one Nolan Grout (mentor agent) turn against this build session: the
      * user's question + Nolan's reply. Kept in memory for the live transcript and
@@ -1708,7 +2506,7 @@ export class AgentSession {
                 id: crypto.randomUUID(),
                 parentId: null,
                 timestamp: new Date().toISOString(),
-                data: payload,
+                data: stripRecordedPosition(payload),
             };
             await this.sessionManager.appendEntry(this.sessionPath, entry);
         }
@@ -1756,7 +2554,7 @@ export class AgentSession {
                 id: crypto.randomUUID(),
                 parentId: null,
                 timestamp: new Date().toISOString(),
-                data: payload,
+                data: stripRecordedPosition(payload),
             };
             await this.sessionManager.appendEntry(this.sessionPath, entry);
         }
@@ -1792,6 +2590,33 @@ export class AgentSession {
         };
         await this.sessionManager.appendEntry(this.sessionPath, entry);
     }
+    /**
+     * Open the run journal for one `RunLifecycle` generation.
+     *
+     * Never throws and never blocks the run: a session with no file (transient
+     * children) writes nothing, and a write failure just means the run isn't
+     * journalled — which is strictly better than failing the run over it.
+     */
+    async persistRunStarted(generation) {
+        if (!this.sessionPath)
+            return;
+        await this.sessionManager.appendRunStarted(this.sessionPath, {
+            version: 1,
+            generation,
+            startedAt: new Date().toISOString(),
+            afterMessageCount: this.persistedTranscriptCount(),
+        });
+    }
+    /** Close the run journal. Its absence is what marks a run as crashed. */
+    async persistRunFinished(generation, outcome) {
+        if (!this.sessionPath)
+            return;
+        await this.sessionManager.appendRunFinished(this.sessionPath, {
+            version: 1,
+            generation,
+            outcome,
+        });
+    }
     /** Re-append the in-memory app markers to the current session file. Mirrors
      *  `rePersistNolanTurns` — called after a continuation/compaction file is
      *  created so display-only rows survive the rewrite. */
@@ -1805,7 +2630,7 @@ export class AgentSession {
                 id: crypto.randomUUID(),
                 parentId: null,
                 timestamp: new Date().toISOString(),
-                data: payload,
+                data: stripRecordedPosition(payload),
             };
             await this.sessionManager.appendEntry(this.sessionPath, entry);
         }
@@ -1851,16 +2676,7 @@ export class AgentSession {
      * effect on the next prompt, since the in-flight loop reads it at start. */
     setThinkingLevel(level) {
         this.thinkingLevel = level;
-        this.syncUltraOrchestrationPrompt();
-    }
-    /** Sol/Terra Ultra delegates proactively; lower levels require an explicit request. */
-    syncUltraOrchestrationPrompt() {
-        if (this.opts.orchestrationPrompt === false)
-            return;
-        const systemMessage = this.messages[0];
-        if (systemMessage?.role !== "system" || typeof systemMessage.content !== "string")
-            return;
-        systemMessage.content = applyAsyncSubagentPolicy(systemMessage.content, this.provider, this.model, this.thinkingLevel, this.tools.map((tool) => tool.name));
+        this.refreshSystemPromptTail();
     }
     /** Replace the abort signal (e.g. after cancellation). */
     setSignal(signal) {
@@ -1923,19 +2739,28 @@ export class AgentSession {
             this.sessionManager.registerActivePath(nextPath);
     }
     async createNewSession() {
+        const continuingConversation = Boolean(this.conversationId && this.sessionId);
         const session = await this.sessionManager.create(this.cwd, this.provider, this.model, {
             conversationId: this.conversationId || undefined,
+            generation: continuingConversation ? this.checkpointGeneration + 1 : 0,
+            parentSessionId: continuingConversation ? this.sessionId : undefined,
             preview: this.sessionPreview || undefined,
         });
         this.sessionId = session.id;
+        this.checkpointGeneration = session.header.generation ?? 0;
         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);
+        // 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);
         // Use the leaf from the header to walk the correct branch
         const loadedMessages = this.sessionManager.getMessages(loaded.entries, loaded.header.leafId);
+        this.checkpointGeneration = loaded.header.generation ?? 0;
         this.conversationId = loaded.header.conversationId ?? loaded.header.id;
         const legacyLabel = [...loaded.entries]
             .reverse()
@@ -1947,12 +2772,17 @@ export class AgentSession {
             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);
+        // The leaf lets marker replay retain its independent file-order position.
+        this.nolanTurns = this.sessionManager.getNolanTurns(loaded.entries, loaded.header.leafId);
         // Restore autopilot verdict markers the same way (not on the message DAG).
-        this.autopilotMarkers = this.sessionManager.getAutopilotMarkers(loaded.entries);
+        this.autopilotMarkers = this.sessionManager.getAutopilotMarkers(loaded.entries, loaded.header.leafId);
         // Restore app transcript markers (plan banner / task header / errors / hints).
-        this.appMarkers = this.sessionManager.getAppMarkers(loaded.entries);
+        this.appMarkers = this.sessionManager.getAppMarkers(loaded.entries, loaded.header.leafId);
         this.turnMetrics = this.sessionManager.getTurnMetrics(loaded.entries);
+        // A run that opened the journal and never closed it died mid-flight. Read
+        // it here, before anything rewrites the file, and report it once the
+        // transcript is in place.
+        const interruptedRuns = this.sessionManager.getUnfinishedRuns(loaded.entries);
         // Track the current leaf for subsequent entries
         this.currentLeafId = loaded.header.leafId;
         // Rebuild messages: keep system, add loaded. Older ezcoder-app sessions may
@@ -1977,63 +2807,41 @@ export class AgentSession {
             provider: this.provider,
             accountId: creds.accountId,
         });
+        this.sessionId = loaded.header.id;
+        this.setSessionPath(loaded.path);
+        this.lastPersistedIndex = this.messages.length;
+        const loadPolicy = resolveCompactionPolicy({
+            provider: this.provider,
+            model: this.model,
+            contextWindow,
+            threshold: this.settingsManager.get("compactThreshold"),
+            accountId: creds.accountId,
+            approvedPlanPath: this.approvedPlanPath,
+        });
+        log("INFO", "compaction", "Restore compaction decision", {
+            provider: this.provider,
+            model: this.model,
+            transport: this.provider === "openai" && creds.accountId ? "codex_oauth" : "public_api",
+            contextWindow: String(contextWindow),
+            activeTokens: "estimated",
+            triggerLimit: String(loadPolicy.targetTokens),
+        });
         const needsLoadCompaction = this.settingsManager.get("autoCompact") &&
-            shouldCompact(this.messages, contextWindow, this.settingsManager.get("compactThreshold"));
+            shouldCompact(this.messages, contextWindow, loadPolicy.threshold);
         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.
+            // Canonicalize again immediately before the first prompt is persisted:
+            // another process may create the shared checkpoint after this load.
+            this.deferredCompactionPending = true;
             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, {
-                provider: this.provider,
-                model: this.model,
-                apiKey: creds.accessToken,
-                accountId: creds.accountId,
-                projectId: creds.projectId,
-                baseUrl: this.baseUrl ?? creds.baseUrl,
-                contextWindow,
-                signal: this.opts.signal,
-            });
-            this.messages = compacted.messages;
-            log("INFO", "session", `Auto-compaction complete`, {
-                before: String(compacted.result.originalCount),
-                after: String(compacted.result.newCount),
-            });
-            // Compaction rewrote history, so the on-disk file no longer reflects
-            // 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, {
-                conversationId: this.conversationId || undefined,
-                preview: this.sessionPreview || undefined,
-            });
-            this.sessionId = session.id;
-            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
-            for (const msg of this.messages) {
-                if (msg.role === "system")
-                    continue;
-                await this.persistMessage(msg);
+            await this.compact(creds, "automatic");
+            if (this.lastCompactionCompacted) {
+                await this.recordInterruptedRuns(interruptedRuns);
+                return;
             }
-            this.lastPersistedIndex = this.messages.length;
-            // Carry restored evidence and Nolan turns into the continuation file.
-            await this.rePersistTurnMetrics();
-            await this.rePersistNolanTurns();
-            await this.rePersistAutopilotMarkers();
-            await this.rePersistAppMarkers();
-            // Record this load-time auto-compaction's counts for the resumed notice.
-            await this.persistAppMarker("compaction", {
-                originalCount: compacted.result.originalCount,
-                newCount: compacted.result.newCount,
-            });
-            return;
         }
         // Plain resume (no compaction needed): keep using the original session
         // file/id and append future turns to it in place. Forking a new file here
@@ -2043,13 +2851,39 @@ export class AgentSession {
         this.sessionId = loaded.header.id;
         this.setSessionPath(loaded.path);
         this.lastPersistedIndex = this.messages.length;
+        await this.recordInterruptedRuns(interruptedRuns);
+    }
+    /**
+     * Surface runs that died mid-flight, without resuming them.
+     *
+     * Deliberately NOT auto-resumed: the dead run's tools already wrote files,
+     * ran commands and made commits. Replaying it would duplicate those effects.
+     * The user gets a transcript row and decides.
+     *
+     * Each detected run is also closed as `aborted`, so reopening the session
+     * reports it once rather than on every load.
+     */
+    async recordInterruptedRuns(runs) {
+        for (const run of runs) {
+            log("WARN", "session", "Restored a session with an unfinished run", {
+                generation: String(run.generation),
+                startedAt: run.startedAt,
+            });
+            await this.persistAppMarker("interrupted_run", {
+                generation: run.generation,
+                startedAt: run.startedAt,
+            });
+            await this.persistRunFinished(run.generation, "aborted");
+        }
     }
     async prepareDynamicContext(_latestUserPrompt) {
         return this.messages;
     }
     async persistMessage(message) {
-        if (!this.sessionPreview && message.role === "user") {
-            this.sessionPreview = getUserSessionPrompt(message.content) ?? "";
+        if (!this.sessionPreview &&
+            message.role === "user" &&
+            (message.provenance?.source === "human" || !message.provenance)) {
+            this.sessionPreview = getUserSessionPrompt(message.content, message.provenance) ?? "";
         }
         // Transient sessions (subagent spawns) have no session file — skip.
         if (!this.sessionPath)
@@ -2069,7 +2903,7 @@ export class AgentSession {
     createSlashCommandContext() {
         return {
             switchModel: (provider, model) => this.switchModel(provider, model),
-            compact: () => this.compact(),
+            compact: () => this.compact(undefined, "manual"),
             newSession: () => this.newSession(),
             listSessions: async () => {
                 const sessions = await this.sessionManager.list(this.cwd);
@@ -2107,5 +2941,48 @@ export class AgentSession {
             getAdditionalRoots: () => this.getAdditionalRoots(),
         };
     }
+    /**
+     * Import a Claude Code / Codex / Cursor transcript as a resumable EZ Coder
+     * session in this session's sessions directory. Never throws — a bad path or
+     * an unrecognized format comes back as `{ ok: false, error }` so both the CLI
+     * and the desktop app can show it verbatim.
+     */
+    async importForeignTranscript(filePath, opts = {}) {
+        try {
+            const imported = await importForeignSession({
+                filePath: resolveHomePath(filePath),
+                sessionManager: this.sessionManager,
+                provider: this.provider,
+                model: this.model,
+                cwd: opts.cwd ?? undefined,
+            });
+            log("INFO", "import", "Imported foreign transcript", {
+                format: imported.format,
+                messages: String(imported.messageCount),
+            });
+            return {
+                ok: true,
+                sessionId: imported.sessionId,
+                sessionPath: imported.sessionPath,
+                cwd: imported.cwd,
+                format: imported.format,
+                messageCount: imported.messageCount,
+                dropped: describeDropped(imported.dropped),
+                ...(imported.preview ? { preview: imported.preview } : {}),
+            };
+        }
+        catch (err) {
+            return { ok: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+}
+/** Expand a leading `~` so `/import ~/.codex/...` works from any shell. */
+function resolveHomePath(filePath) {
+    if (filePath === "~")
+        return os.homedir();
+    if (filePath.startsWith("~/") || filePath.startsWith("~\\")) {
+        return path.join(os.homedir(), filePath.slice(2));
+    }
+    return filePath;
 }
 //# sourceMappingURL=agent-session.js.map