@cjhyy/code-shell-core 0.7.0-beta.1 → 0.7.1

package/dist/engine/engine.js

@@ -11,7 +11,7 @@ import { applyDynamicToolDef } from "./dynamic-tool-defs.js";
 import { getMergedCatalog } from "../model-catalog/index.js";
 import { modelEntriesFromConnections } from "./model-connections-pool.js";
 import { resolveAuxKey } from "./aux-key.js";
-import { addCumulativeUsage, cumulativeCacheHitRate, foldRunUsage, normalizeCumulativeUsageCounters, } from "./session-usage.js";
+import { addTokenUsage, addCumulativeUsage, cumulativeCacheHitRate, foldRunUsage, normalizeCumulativeUsageCounters, } from "./session-usage.js";
 import { enqueueSteerItem, consumeSteerItems, removeSteerItem, } from "./steer-queue.js";
 import { resolveSandboxConfig } from "./sandbox-config.js";
 import { sandboxCacheKey } from "./sandbox-cache-key.js";
@@ -23,7 +23,7 @@ import { PermissionClassifier, HeadlessApprovalBackend, AutoApprovalBackend, Int
 import { HookRegistry } from "../hooks/registry.js";
 import { wrapHookMessages } from "../hooks/inject.js";
 import { createGoalStopHook } from "../hooks/goal-stop-hook.js";
-import { normalizeGoal, resolveGoalSetAt, resolveMaxTurns, resolveMaxStopBlocks, } from "./goal.js";
+import { normalizeGoal, resolveGoalSetAt, resolveMaxTurns, resolveMaxStopBlocks, isSameGoalInstance, } from "./goal.js";
 import { loadPluginHooks } from "../plugins/loadPluginHooks.js";
 import { pluginAgentDirs } from "../plugins/installer/loadPluginAgents.js";
 import { patchOrphanedToolUses } from "./patch-orphaned-tools.js";
@@ -32,7 +32,7 @@ import { ContextManager } from "../context/manager.js";
 import { estimateTokens, clampContextRatios as clampContextRatiosImpl, } from "../context/compaction.js";
 import { PLAN_MODE_ALLOWED_TOOLS } from "../tool-system/plan-mode-allowlist.js";
 import { PromptComposer } from "../prompt/composer.js";
-import { SessionManager } from "../session/session-manager.js";
+import { SessionManager, } from "../session/session-manager.js";
 import { ModelFacade } from "./model-facade.js";
 import { logger, runWithSid, getCurrentSid } from "../logging/logger.js";
 import { recordSessionStart, recordSessionEnd } from "../logging/session-recorder.js";
@@ -53,16 +53,17 @@ import { AgentDefinitionRegistry } from "../agent/agent-definition-registry.js";
 import { defaultCacheDir } from "../llm/model-cache.js";
 import { detectProviderFromApiKey, buildModelPool } from "../onboarding.js";
 import { detectPastedNoise } from "../utils/task-sanitizer.js";
-import { parseTaskWithImages } from "./parse-task.js";
-import { buildInputAttachmentContext } from "./input-attachments.js";
-import { enforceImagePolicy, byteLengthFromBase64, dropOversizedImages, collectAttachedImagePaths, } from "./image-policy.js";
-import { tryCompressImages } from "./image-compression.js";
+import { formatFriendlyError } from "./friendly-error.js";
 import { buildSessionTitle } from "./session-title.js";
-import { capabilitiesFor } from "../llm/capabilities/index.js";
 import { MemoryOrchestrator } from "../services/memory-orchestrator.js";
 import { runDreamConsolidation } from "../services/dream-consolidation.js";
-import { join, isAbsolute } from "node:path";
+import { buildRunUserMessageContent, prepareRunImageInput } from "./run-image-input.js";
+import { join } from "node:path";
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+const CACHE_READ_DROP_MIN_PREVIOUS_TOKENS = 100;
+const CACHE_READ_DROP_MAX_CURRENT_TOKENS = 64;
+const CACHE_READ_DROP_RATIO = 0.1;
+const CACHE_READ_DIAGNOSTIC_MAX_SESSIONS = 256;
 /**
  * Build ScanOptions.compatFileNames from the user's instruction compat toggles.
  * Primary file name stays hard-wired to CODESHELL.md (not exposed). Turning a
@@ -229,6 +230,8 @@ export class Engine {
     /** Shared resources supplied at construction (adapter pattern — null when self-constructed). */
     runtime;
     sandboxCache = new Map();
+    interactiveBackends = new WeakMap();
+    activeApprovalRouter;
     /** Active permission mode for this Engine instance. */
     permissionMode;
     /** True when permissionMode === "plan". */
@@ -245,7 +248,7 @@ export class Engine {
      */
     auxClientCache;
     // Live state from the current/most-recent run, retained for /compact and
-    // for live-mutating PermissionClassifier on permission-mode switch.
+    // run-boundary PermissionClassifier replacement/reconfiguration.
     lastContextManager;
     lastMessages;
     lastSessionId;
@@ -266,6 +269,7 @@ export class Engine {
      * LLM response arrives.
      */
     ctxOverheadBySid = new Map();
+    lastCacheReadBySid = new Map();
     /**
      * Step-gap steering queue (per sessionId, in-memory). Host pushes user
      * messages here via enqueueSteer while a run is in flight; the turn loop
@@ -299,6 +303,19 @@ export class Engine {
      * Null when idle; set at run start, cleared in run's finally.
      */
     activeRunSession = null;
+    /**
+     * Same-instance run guard. Engine owns single-valued live controls and one
+     * HookRegistry, so a second run must not enter until the first has completed
+     * all state persistence and end hooks. This prevents handle contamination and
+     * whole-state saveState overlap only within this Engine instance. It does not
+     * coordinate different Engine instances sharing a sessionId, Workers, or
+     * processes; session-level locking/CAS for those cases is a separate finding.
+     */
+    runInProgress = false;
+    /** Permission update requested while runInProgress. Applied in run() finally. */
+    pendingPermissionMode = null;
+    /** Plan update paired with pendingPermissionMode for one atomic boundary apply. */
+    pendingPlanMode = null;
     /** Public accessor so UI/clients can read the resolved per-model window. */
     get maxContextTokens() {
         return this.resolveMaxContextTokens();
@@ -334,10 +351,11 @@ export class Engine {
      * emits should go through this wrapper to keep the context envelope
      * uniform with TurnLoop.emitHook.
      */
-    async emitHook(event, data = {}) {
+    async emitHook(event, data = {}, signal) {
         return this.hooks.emit(event, {
             ...data,
             isSubAgent: this.config.isSubAgent === true,
+            signal,
         });
     }
     /**
@@ -654,7 +672,7 @@ export class Engine {
      * the queued draft) and is the handle `unsteer` uses to revoke a still-pending
      * entry. A blank id is tolerated but means the entry can't be revoked.
      */
-    enqueueSteer(sessionId, text, id = "", clientMessageId) {
+    enqueueSteer(sessionId, text, id = "", clientMessageId, attachments) {
         const q = this.steerQueueBySid.get(sessionId) ?? [];
         const entryId = id || `steer-${q.length}`;
         if (!sessionId)
@@ -666,12 +684,13 @@ export class Engine {
                 sessionId,
                 id: entryId,
                 clientMessageId,
+                attachmentCount: attachments?.length ?? 0,
                 activeRunSessionId: activeRunSessionId ?? null,
                 queueLength: q.length,
             });
             return { accepted: false, id: entryId };
         }
-        const next = enqueueSteerItem(q, entryId, text, clientMessageId);
+        const next = enqueueSteerItem(q, entryId, text, clientMessageId, attachments);
         if (next === q)
             return { accepted: false, id: entryId }; // blank text dropped
         this.steerQueueBySid.set(sessionId, next);
@@ -679,6 +698,7 @@ export class Engine {
             sessionId,
             id: entryId,
             clientMessageId,
+            attachmentCount: attachments?.length ?? 0,
             activeRunSessionId,
             queueLength: next.length,
         });
@@ -715,6 +735,13 @@ export class Engine {
         });
         return drained;
     }
+    /** Put failed steer preparation back ahead of messages queued while it was being prepared. */
+    restoreSteer(sessionId, items) {
+        if (items.length === 0)
+            return;
+        const queued = this.steerQueueBySid.get(sessionId) ?? [];
+        this.steerQueueBySid.set(sessionId, [...items, ...queued]);
+    }
     /** Wire the cookie→browser injection callback (InjectCredential tool). Same
      *  post-construction injection model as setBrowserBridge. */
     setInjectCredential(fn) {
@@ -737,10 +764,43 @@ export class Engine {
     sessionExistsOnDisk(sessionId) {
         return this.sessionManager.exists(sessionId);
     }
+    forkSession(sourceSessionId, options) {
+        return this.sessionManager.fork(sourceSessionId, options);
+    }
     /**
-     * Run a task from start to finish.
+     * Run a task from start to finish. Rejects immediately when this Engine
+     * instance already has a run in progress; hosts that want queueing own that
+     * policy (for example ChatSession's FIFO queue).
      */
     async run(task, options) {
+        if (this.runInProgress) {
+            throw new Error("Engine.run() cannot start while another run is in progress");
+        }
+        this.runInProgress = true;
+        try {
+            return await this.runExclusive(task, options);
+        }
+        finally {
+            try {
+                this.applyPendingPermissionState();
+            }
+            finally {
+                this.runInProgress = false;
+            }
+        }
+    }
+    async runExclusive(task, options) {
+        // Freeze permission context once, before the first await. Per-turn protocol
+        // overrides live only for this run; persistent setPermissionMode/setPlanMode
+        // calls made while busy are staged separately and cannot mutate this pair.
+        let runPermissionMode = options?.permissionMode ?? this.config.permissionMode ?? "acceptEdits";
+        if (options?.planMode === true) {
+            runPermissionMode = "plan";
+        }
+        else if (options?.planMode === false && runPermissionMode === "plan") {
+            runPermissionMode = "acceptEdits";
+        }
+        const runPlanMode = runPermissionMode === "plan";
         const workspaceResume = options?.sessionId && this.sessionManager.exists(options.sessionId)
             ? await this.sessionManager.resolveSessionWorkspaceForResume(options.sessionId)
             : undefined;
@@ -807,139 +867,16 @@ export class Engine {
         };
         if (options)
             options.onStream = wrappedOnStream;
-        // ── P2-6: image input ─────────────────────────────────────────────
-        // Parse `<codeshell-image>` blocks out of the raw task string before
-        // any other gate looks at it. Two concerns:
-        //   1. The noise detector below sees the raw base64 as gibberish and
-        //      would reject the whole turn — split images out first so it
-        //      only inspects the prose portion.
-        //   2. Models that don't accept vision must be refused immediately,
-        //      with the image bytes intact for the user to retry on another
-        //      model. Silent text-only fallback was the failure mode this
-        //      gate is here to prevent.
-        let parsedTask;
-        try {
-            parsedTask = parseTaskWithImages(task);
-        }
-        catch (err) {
-            const msg = err.message;
-            logger.warn("engine.run.image_parse_failed", { error: msg });
-            return {
-                text: `ERROR: image attachment is malformed (${msg}). Drop the image and try again, or re-attach it.`,
-                reason: "image_error",
-                sessionId: options?.sessionId ?? "image-parse-failed",
-                turnCount: 0,
-                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
-            };
-        }
-        const cap = capabilitiesFor((this.config.llm.providerKind ?? this.config.llm.provider), this.config.llm.model);
-        const attachmentContext = await buildInputAttachmentContext(options?.attachments, cwd, {
-            includeImageBytes: cap.supportsVision,
-            expectedSessionId: options?.sessionId,
+        const imageInput = await prepareRunImageInput({
+            task,
+            cwd,
+            llm: this.config.llm,
+            sessionId: options?.sessionId,
+            attachments: options?.attachments,
         });
-        if (attachmentContext.errors.length > 0) {
-            const detail = attachmentContext.errors.join("; ");
-            logger.warn("engine.run.input_attachment_failed", { error: detail });
-            return {
-                text: `ERROR: input attachment could not be read (${detail}). Re-attach it or choose a path inside the workspace.`,
-                reason: "image_error",
-                sessionId: options?.sessionId ?? "input-attachment-failed",
-                turnCount: 0,
-                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
-            };
-        }
-        if (attachmentContext.text || attachmentContext.hasStructuredImageAttachments) {
-            parsedTask = {
-                text: [parsedTask.text, attachmentContext.text].filter(Boolean).join("\n\n"),
-                images: [...parsedTask.images, ...attachmentContext.images],
-                hasImages: parsedTask.hasImages ||
-                    attachmentContext.images.length > 0 ||
-                    attachmentContext.hasStructuredImageAttachments,
-            };
-        }
-        if (parsedTask.hasImages) {
-            if (!cap.supportsVision) {
-                logger.warn("engine.run.vision_not_supported", {
-                    provider: this.config.llm.provider,
-                    model: this.config.llm.model,
-                    imageCount: parsedTask.images.length,
-                });
-                return {
-                    text: `ERROR: model "${this.config.llm.model}" does not accept image input. ` +
-                        `Switch to a vision-capable model (e.g. gpt-4o, claude-sonnet, gemini-1.5-pro) and resend.`,
-                    reason: "image_error",
-                    sessionId: options?.sessionId ?? "vision-not-supported",
-                    turnCount: 0,
-                    usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
-                };
-            }
-            // Size gate. Hosts (desktop renderer, TUI) are expected to
-            // pre-compress to IMAGE_TARGETS — if they didn't, we fail the turn
-            // fast with a clear message instead of letting the OpenAI client
-            // grind through three 16-second "Connection error" retries on a
-            // 4 MB body. See `image-policy.ts` for the rationale and limits.
-            let verdict = enforceImagePolicy(parsedTask.images);
-            if (!verdict.ok && verdict.code === "image_too_large") {
-                // One image blew the per-image cap. Try the engine-side
-                // compressor (jimp-backed when installed; no-op otherwise) so
-                // TUI / MCP paths that lack a host-side resize don't fail
-                // outright on a screenshot they could have rescaled. The
-                // re-check below is what decides whether we proceed.
-                const compressed = await tryCompressImages(parsedTask.images);
-                if (compressed.anyCompressed) {
-                    parsedTask.images = compressed.images;
-                    logger.info("engine.run.image_compressed", {
-                        before: verdict.offender?.bytes,
-                        after: compressed.images.reduce((s, i) => s + byteLengthFromBase64(i.base64), 0),
-                    });
-                    verdict = enforceImagePolicy(parsedTask.images);
-                }
-            }
-            // After compression, anything still over the per-image cap is
-            // dropped with a textual placeholder instead of failing the
-            // turn (TODO-week.md #9e). The "5MB brick session" failure
-            // mode from Claude Code (research doc §A) was the case where a
-            // poisoned image entered history and every subsequent request
-            // re-sent it; placeholders keep history clean while letting
-            // the rest of the turn run.
-            if (!verdict.ok && verdict.code === "image_too_large") {
-                const drop = dropOversizedImages(parsedTask.images);
-                if (drop.droppedCount > 0) {
-                    parsedTask.images = drop.kept;
-                    parsedTask.hasImages = drop.kept.length > 0;
-                    parsedTask.text = drop.placeholder + "\n\n" + parsedTask.text;
-                    logger.warn("engine.run.image_dropped", {
-                        droppedCount: drop.droppedCount,
-                        keptCount: drop.kept.length,
-                    });
-                    verdict = enforceImagePolicy(parsedTask.images);
-                }
-            }
-            if (!verdict.ok) {
-                // Cumulative / count caps can't be rescued by per-image
-                // dropping (well — too_many_images could trim by FIFO, but
-                // that's a bigger UX call than we want to make silently).
-                // Refuse the turn with the policy message.
-                logger.warn("engine.run.image_policy_failed", {
-                    code: verdict.code,
-                    imageCount: verdict.totals.imageCount,
-                    totalBytes: verdict.totals.totalBytes,
-                    offender: verdict.offender,
-                });
-                return {
-                    text: `ERROR: ${verdict.message}`,
-                    reason: "image_error",
-                    sessionId: options?.sessionId ?? `image-policy-${verdict.code}`,
-                    turnCount: 0,
-                    usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
-                };
-            }
-        }
-        // For downstream noise-detection + transcript persistence we want the
-        // *text* portion only — base64 bytes count as "noise" by the heuristic
-        // and would also bloat the transcript by megabytes per image. Image
-        // bytes ride in parsedTask.images and re-enter the message tree below.
-        const taskText = parsedTask.text;
+        if (!imageInput.ok)
+            return imageInput.result;
+        const { parsedTask, taskText } = imageInput;
         const noise = detectPastedNoise(taskText);
         if (noise.isNoise) {
             const hint = `Your input looks like pasted terminal output (${noise.reason}). ` +
@@ -962,7 +899,7 @@ export class Engine {
             describe: () => ({
                 cwd,
                 preset: this.preset.name,
-                permissionMode: this.config.permissionMode ?? "acceptEdits",
+                permissionMode: runPermissionMode,
             }),
             spawn: async (req) => {
                 // Anchor this sub-agent in the PARENT transcript at spawn time — before
@@ -997,7 +934,7 @@ export class Engine {
                     // rather surface failures than burn a 9 s exponential backoff loop.
                     clientDefaults: { ...(this.config.clientDefaults ?? {}), retryMaxAttempts: 2 },
                     cwd,
-                    permissionMode: this.config.permissionMode,
+                    permissionMode: runPermissionMode,
                     preset: this.preset.name,
                     enabledBuiltinTools: childEnabled,
                     disabledBuiltinTools: childDisabled,
@@ -1065,7 +1002,7 @@ export class Engine {
                     onStream: childStream,
                     sessionId: childSessionId,
                 });
-                return { text: result.text, sessionId: result.sessionId };
+                return { text: result.text, sessionId: result.sessionId, usage: result.usage };
             },
             sessionExists: (sessionId) => this.sessionManager.exists(sessionId),
         };
@@ -1100,6 +1037,9 @@ export class Engine {
         // after the assignment.
         const toolCtx = {
             ...this.buildToolContext(),
+            approvalRouter: options?.approvalRouter ?? this.config.approvalRouter,
+            permissionMode: runPermissionMode,
+            planMode: runPlanMode,
             subAgentSpawner,
             agentDefinitions: this.getAgentDefinitions(cwd),
             // Stamp the resolved network policy onto the backend the tools see so
@@ -1128,40 +1068,7 @@ export class Engine {
             preset: this.preset.name,
             imageCount: parsedTask.images.length,
         });
-        // Compose the user-turn payload once so resume + cold paths agree on
-        // shape. With images, content becomes a ContentBlock[] holding one
-        // text block (when prose is present) followed by one image block per
-        // attachment — the provider-specific clients translate this to OpenAI
-        // `image_url` or Anthropic `{type:image, source:base64}` downstream.
-        // When an attached image came from a workspace FILE (the desktop composer's
-        // path-attach flow sets ParsedImage.name = the absolute path), surface that
-        // path to the model as text. The image bytes still ride along for vision,
-        // but tools that operate on files — GenerateImage(referenceImages),
-        // Read, etc. — need the on-disk path, not just the pixels. Without this the
-        // path the composer already knew was silently dropped, and the model would
-        // answer "图片没落到项目文件夹，找不到路径" (the seedance 图生图 dead-end).
-        // Only names that resolve to an existing file qualify; a pasted screenshot
-        // whose name is just "screenshot.png" is not a path and is left out.
-        const attachedPaths = collectAttachedImagePaths(parsedTask.images, (name) => (isAbsolute(name) ? name : join(cwd, name)), existsSync);
-        const pathHint = attachedPaths.length > 0
-            ? `\n\n<attached-image-paths>\n${attachedPaths.join("\n")}\n</attached-image-paths>\n` +
-                `(上面附带的图片在工作区的真实路径，如需把它们作为工具输入（例如 GenerateImage 的 referenceImages、图生图参考图），直接使用这些路径。)`
-            : "";
-        const userMessageContent = parsedTask.hasImages
-            ? [
-                ...(parsedTask.text || pathHint
-                    ? [{ type: "text", text: `${parsedTask.text}${pathHint}` }]
-                    : []),
-                ...parsedTask.images.map((img) => ({
-                    type: "image",
-                    source: {
-                        type: "base64",
-                        media_type: img.mime,
-                        data: img.base64,
-                    },
-                })),
-            ]
-            : taskText;
+        const userMessageContent = buildRunUserMessageContent(parsedTask, cwd, taskText);
         // Create or resume session.
         //
         // Three valid shapes:
@@ -1284,12 +1191,18 @@ export class Engine {
         // notifications) attribute to the right session. toolCtx is created
         // before the session bundle is resolved (see ~line 635), so this is
         // the first point we can set it. After this assignment treat the
-        // field as immutable for the rest of the run.
+        // field follows the latest successfully injected user intent for the rest
+        // of the run, so tools launched after a steer attribute their side effects
+        // to that steer rather than this original submit.
         toolCtx.sessionId = session.state.sessionId;
+        toolCtx.originClientMessageId = options?.clientMessageId;
+        toolCtx.recordExternalFileChanges = (record) => {
+            session.transcript.append("external_file_changes", { ...record });
+        };
         toolCtx.setSessionWorkspace = (workspace) => {
             session.state.workspace = workspace;
         };
-        return runWithSid(session.state.sessionId, async () => {
+        const sessionRun = runWithSid(session.state.sessionId, async () => {
             recordSessionStart(session.state.sessionId, {
                 // Strip <codeshell-image> base64 payloads before they reach
                 // <repo>/log/. Reader still sees the marker + byte count, just
@@ -1298,7 +1211,7 @@ export class Engine {
                 cwd,
                 model: this.config.llm.model,
                 provider: this.config.llm.provider,
-                permissionMode: this.config.permissionMode ?? "acceptEdits",
+                permissionMode: runPermissionMode,
                 resumed: resumedFromDisk,
             });
             // Session-level hook: fired once per Engine.run() entry, regardless of
@@ -1311,7 +1224,7 @@ export class Engine {
                 cwd,
                 resumed: resumedFromDisk,
                 source: resumedFromDisk ? "resume" : "startup",
-            });
+            }, options?.signal);
             // Per-turn hook: fired every time a new user prompt enters the loop.
             // Equivalent to CC's UserPromptSubmit. Handlers can inject lightweight
             // reminders that should accompany each user turn (e.g. "skills
@@ -1325,7 +1238,7 @@ export class Engine {
                 // exfiltration risk a curious user-installed shell hook shouldn't carry.
                 prompt: taskText,
                 resumed: resumedFromDisk,
-            });
+            }, options?.signal);
             // updatedPrompt: handler rewrote the user's prompt text. Replace the
             // last user message we just pushed (cold-start: line ~511; resume:
             // line ~500). Original prompt is in the transcript already — we log
@@ -1412,8 +1325,14 @@ export class Engine {
             }
             // Kick off LLM client creation early (network handshake)
             const llmClientPromise = createLLMClient(this.config.llm, this.config.clientDefaults);
-            const mode = this.config.permissionMode ?? "acceptEdits";
-            const { rules: defaultRules, backend: approvalBackend } = this.buildPermissionConfig(mode, cwd);
+            // MCP connection below may keep us from awaiting this promise for a while.
+            // Observe rejection immediately so a fast client-init failure cannot become
+            // an unhandledRejection during that gap; Promise.all still receives the
+            // original promise and routes the same error through the lifecycle catch.
+            void llmClientPromise.catch(() => { });
+            const mode = runPermissionMode;
+            this.activeApprovalRouter = toolCtx.approvalRouter;
+            const { rules: defaultRules, backend: approvalBackend } = this.buildPermissionConfig(mode, cwd, toolCtx.approvalRouter);
             const permission = new PermissionClassifier(defaultRules, mode, approvalBackend);
             this.activePermission = permission;
             // If the backend is the interactive one, wire it for project-scope
@@ -1575,7 +1494,7 @@ export class Engine {
             // PLAN_MODE_ALLOWED_TOOLS so what the model SEES and what the executor
             // RUNS can't drift apart. (Bash is in the set; the executor additionally
             // gates Bash to read-only commands at call time.)
-            const toolDefs = this.planMode
+            const toolDefs = runPlanMode
                 ? allToolDefs.filter((t) => PLAN_MODE_ALLOWED_TOOLS.has(t.name))
                 : allToolDefs;
             const [llmClient, fullSystemPrompt, dynamicContextMsg] = await Promise.all([
@@ -1634,15 +1553,81 @@ export class Engine {
             //    These are tiny throwaway outputs ("Wrote design doc") fired every turn;
             //    that high-frequency, low-stakes chore is exactly what aux is for.
             const auxSummaryClient = await this.resolveAuxClient(llmClient);
+            // Auto-compaction runs inside TurnLoop.manageAsync(), after the loop has
+            // initialized its run-scoped Goal tracker. The closure is wired before
+            // construction but cannot execute until turnLoop.run() starts.
+            let turnLoop;
+            let autoCompactionGoalTermination;
+            let externalRunUsage = {
+                promptTokens: 0,
+                completionTokens: 0,
+                totalTokens: 0,
+                cacheReadTokens: 0,
+                cacheCreationTokens: 0,
+            };
+            let runAccountingFinalized = false;
             Object.assign(session.state, normalizeCumulativeUsageCounters(session.state, session.state.tokenUsage));
             const recordCumulativeUsage = (usage) => {
                 const next = addCumulativeUsage(session.state, usage);
                 Object.assign(session.state, next);
                 return next;
             };
-            contextManager.setSummarizeFn(this.buildSummarizeFn(llmClient, recordCumulativeUsage));
+            const recordExternalBilledUsage = (usage) => {
+                externalRunUsage = addTokenUsage(externalRunUsage, usage);
+                const cumulative = recordCumulativeUsage(usage);
+                autoCompactionGoalTermination = turnLoop.recordGoalJudgeUsage(usage);
+                if (runAccountingFinalized) {
+                    try {
+                        const latest = this.sessionManager.resume(sid).state;
+                        const lateCumulative = addCumulativeUsage(latest, usage);
+                        this.sessionManager.updateSessionState(sid, {
+                            tokenUsage: addTokenUsage(latest.tokenUsage, usage),
+                            ...lateCumulative,
+                            ...(this.config.costStore
+                                ? {
+                                    costState: this.config.costStore.serialize(),
+                                }
+                                : {}),
+                        });
+                    }
+                    catch (err) {
+                        logger.warn("engine.late_usage_persist_failed", {
+                            sessionId: sid,
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                    }
+                }
+                return cumulative;
+            };
+            contextManager.setSummarizeFn(this.buildSummarizeFn(llmClient, recordExternalBilledUsage));
             // Create components (requires resolved llmClient).
             const modelFacade = new ModelFacade(llmClient, session.transcript);
+            const getRunUsage = () => {
+                const visible = modelFacade.getUsage();
+                return {
+                    ...visible,
+                    totalPromptTokens: visible.totalPromptTokens + externalRunUsage.promptTokens,
+                    totalCompletionTokens: visible.totalCompletionTokens + externalRunUsage.completionTokens,
+                    totalTokens: visible.totalTokens + externalRunUsage.totalTokens,
+                    totalCacheReadTokens: visible.totalCacheReadTokens + (externalRunUsage.cacheReadTokens ?? 0),
+                    totalCacheCreationTokens: visible.totalCacheCreationTokens + (externalRunUsage.cacheCreationTokens ?? 0),
+                };
+            };
+            const callPrimaryModel = modelFacade.call.bind(modelFacade);
+            modelFacade.call = async (...args) => {
+                // A primary-model summary may itself exhaust the Goal budget. Do not
+                // issue the main turn request after that billed sub-call; return control
+                // to TurnLoop, whose existing post-response guard emits and persists the
+                // canonical goal_budget_exhausted termination.
+                if (autoCompactionGoalTermination) {
+                    return {
+                        text: "",
+                        toolCalls: [],
+                        stopReason: "stop",
+                    };
+                }
+                return callPrimaryModel(...args);
+            };
             // Session-cumulative usage baseline: the LLM client is recreated per run
             // (its getUsage() counts only THIS run), so to accumulate across runs we
             // capture the persisted total at run start and fold this run's usage onto
@@ -1650,23 +1635,25 @@ export class Engine {
             const usageBaseline = { ...session.state.tokenUsage };
             // Wire getOutputTokens for token budget tracking
             modelFacade.getOutputTokens = () => {
-                const usage = llmClient.getUsage();
+                const usage = getRunUsage();
                 return usage.totalCompletionTokens;
             };
-            // Wire summarize for tool use summaries (uses lightweight call).
-            // recordUsage=false keeps these auxiliary sub-calls out of the main usage
-            // tracker so session_end.cost reflects only the user-facing turns and
-            // turns/requestCount stay aligned.
+            // Wire summarize for tool use summaries (uses lightweight call). Keep the
+            // request out of the foreground tracker while billing and reporting it to
+            // the owning session/Goal budget.
             modelFacade.summarize = async (sysPrompt, userMsg) => {
                 const resp = await auxSummaryClient.createMessage({
                     systemPrompt: sysPrompt,
                     messages: [{ role: "user", content: userMsg }],
                     tools: [],
                     maxTokens: 256,
-                    recordUsage: false,
+                    billingEnabled: true,
+                    requestVisible: false,
                     // Auxiliary call — see contextManager.setSummarizeFn above.
                     reasoning: { mode: "off" },
                 });
+                if (resp.usage)
+                    recordExternalBilledUsage(resp.usage);
                 logger.debug("summarize.call", {
                     sysPromptLen: sysPrompt.length,
                     userMsgLen: userMsg.length,
@@ -1720,21 +1707,24 @@ export class Engine {
                 sessionId: session.state.sessionId,
                 task,
                 model: this.config.llm.model,
-            });
+            }, options?.signal);
             // Goal mode: register a GoalStopHook for the lifetime of THIS run so the
             // turn loop keeps going until the session model judges the goal met.
             // Registered per-run (and cleared in `finally`) so a later goal-less
-            // send doesn't inherit a stale goal. The judge runs on `auxSummaryClient`
-            // — the same cheap aux model used for summarize/compaction — not the
-            // (potentially expensive) session model: "is this goal met?" is a classic
-            // aux-tier task, and a goal run can invoke the judge up to maxStopBlocks
-            // times.
+            // send doesn't inherit a stale goal. The judge runs on the primary
+            // session client; auxSummaryClient remains dedicated to low-consequence
+            // summaries/titles and retains defaults.auxText routing/fallback behavior.
             // Normalize the raw goal (string | GoalConfig) once at the run boundary;
             // everything inward uses the GoalConfig. normalizeGoal() returns undefined
             // when there's effectively no goal (empty objective).
             //
             // PERSISTENT GOAL (CC /goal style): a goal set on one send survives across
-            // later sends and manual interrupts until met or cleared. Resolution:
+            // later sends and manual interrupts until met or cleared. Goal completion
+            // is a high-consequence decision, so V1 routes it to the primary session
+            // client, which is the model expected to interpret the supplied execution
+            // evidence. defaults.auxText remains in force for summaries, titles and
+            // other auxiliary work through auxSummaryClient.
+            // Resolution:
             //   1. options.goal — this send explicitly sets/replaces the goal.
             //   2. session.state.activeGoal — a goal set on an earlier send.
             //   3. config.goal — engine-level default (rare; e.g. headless).
@@ -1743,7 +1733,15 @@ export class Engine {
             // bare send with no options.goal inherits the stored active goal so the
             // model keeps working toward it — that's what makes it persistent.
             const explicitGoal = normalizeGoal(options?.goal);
-            const storedGoal = this.config.isSubAgent !== true ? session.state.activeGoal : undefined;
+            let storedGoal = this.config.isSubAgent !== true ? session.state.activeGoal : undefined;
+            // Defense in depth: a stale whole-state writer may have restored the
+            // activeGoal field after this exact goal instance was force-terminated.
+            // Refuse to arm it and converge the live bundle before hook registration.
+            if (storedGoal && isSameGoalInstance(storedGoal, session.state.goalTerminal)) {
+                session.state.activeGoal = undefined;
+                storedGoal = undefined;
+                this.sessionManager.saveState(session.state);
+            }
             if (explicitGoal && this.config.isSubAgent !== true) {
                 const replaced = !!storedGoal && storedGoal.objective !== explicitGoal.objective;
                 // Stamp WHEN this goal was set so the judge can anchor relative deadlines
@@ -1752,7 +1750,14 @@ export class Engine {
                 // or changed objective gets a fresh stamp; re-sending the SAME objective
                 // keeps the original anchor (the goal continues, the user didn't restate a
                 // new deadline). User input never carries setAtMs, so we set it here.
-                explicitGoal.setAtMs = resolveGoalSetAt(explicitGoal.objective, storedGoal, Date.now());
+                const resolvedSetAt = resolveGoalSetAt(explicitGoal.objective, storedGoal, Date.now());
+                // A user explicitly re-starting the same objective creates a new goal
+                // instance. Avoid a same-millisecond collision with its old tombstone.
+                explicitGoal.setAtMs =
+                    session.state.goalTerminal?.objective === explicitGoal.objective &&
+                        session.state.goalTerminal.setAtMs === resolvedSetAt
+                        ? resolvedSetAt + 1
+                        : resolvedSetAt;
                 session.state.activeGoal = explicitGoal;
                 this.sessionManager.saveState(session.state);
                 options?.onStream?.({
@@ -1762,18 +1767,35 @@ export class Engine {
                 });
             }
             const normalizedGoal = explicitGoal ?? storedGoal ?? normalizeGoal(this.config.goal);
+            // Snapshot the persisted goal identity owned by THIS run. Terminal
+            // cleanup compares against this immutable copy so an old run cannot
+            // delete a replacement goal installed while it was finishing.
+            const persistedRunGoal = normalizedGoal && isSameGoalInstance(session.state.activeGoal, normalizedGoal)
+                ? { ...normalizedGoal }
+                : undefined;
             let goalHookHandler = null;
+            let goalJudgeContext;
             if (normalizedGoal && this.config.isSubAgent !== true) {
                 goalHookHandler = createGoalStopHook({
                     goal: normalizedGoal,
-                    llm: auxSummaryClient,
+                    llm: llmClient,
                     log: logger,
+                    getJudgeContext: () => goalJudgeContext,
+                    onJudgeUsage: (usage) => {
+                        // The provider records this request into llmClient.getUsage() and the
+                        // process-wide CostTracker. This separate callback feeds the session
+                        // cumulative cache counters and the live Goal hard-budget tracker.
+                        if (usage)
+                            recordCumulativeUsage(usage);
+                        return turnLoop.recordGoalJudgeUsage(usage);
+                    },
                     // Clear the persisted active goal the moment the judge says it's met,
                     // so a later bare send doesn't re-inherit a satisfied goal. The hook
                     // calls this from inside its met branch (single source of truth for
                     // "goal achieved"); engine owns the persistence side-effect.
                     onMet: () => {
-                        if (session.state.activeGoal) {
+                        if (persistedRunGoal &&
+                            isSameGoalInstance(session.state.activeGoal, persistedRunGoal)) {
                             session.state.activeGoal = undefined;
                             this.sessionManager.saveState(session.state);
                         }
@@ -1783,7 +1805,7 @@ export class Engine {
                     // in-RAM session are untouched) actually stops the judge. Reads disk
                     // via readActiveGoal — authoritative and independent of which session
                     // instance the run closure holds.
-                    isGoalActive: (sid) => this.sessionManager.readActiveGoal(sid) !== undefined,
+                    isGoalActive: (sid) => isSameGoalInstance(this.sessionManager.readActiveGoal(sid), normalizedGoal),
                 });
                 this.hooks.register("on_stop", goalHookHandler, 0, "goal-stop");
                 // Expose for clearGoal() mid-run. Already guarded by isSubAgent above.
@@ -1799,7 +1821,7 @@ export class Engine {
                 options?.onStream?.({ type: "context_compact", ...info });
             });
             // Run turn loop
-            const turnLoop = new TurnLoop({
+            turnLoop = new TurnLoop({
                 model: modelFacade,
                 toolExecutor,
                 contextManager,
@@ -1815,8 +1837,31 @@ export class Engine {
                     return info;
                 },
                 consumeSteer: (source) => this.consumeSteer(sid, source),
+                restoreSteer: (items) => this.restoreSteer(sid, items),
+                buildSteerUserMessageContent: async (item) => {
+                    const steerImageInput = await prepareRunImageInput({
+                        task: item.text,
+                        cwd,
+                        llm: this.config.llm,
+                        sessionId: sid,
+                        attachments: item.attachments,
+                    });
+                    if (!steerImageInput.ok) {
+                        throw new Error(steerImageInput.result.text);
+                    }
+                    return buildRunUserMessageContent(steerImageInput.parsedTask, cwd, steerImageInput.taskText);
+                },
                 claimClientMessageId: (clientMessageId, source) => claimClientMessageId(session, clientMessageId, source),
+                releaseClientMessageId: (clientMessageId) => {
+                    claimedClientMessageIds.delete(clientMessageId);
+                },
+                setOriginClientMessageId: (clientMessageId) => {
+                    toolCtx.originClientMessageId = clientMessageId;
+                },
                 recordCumulativeUsage,
+                recordCacheReadDiagnostics: (usage) => {
+                    this.recordCacheReadDiagnostics(sid, usage);
+                },
                 recordContextUsageAnchor: (anchor) => {
                     session.state.contextUsageAnchor = {
                         ...anchor,
@@ -1829,7 +1874,8 @@ export class Engine {
                 // turns don't re-arm) AND persists it, and drops the in-flight stop
                 // hook so nothing re-blocks the stop we're about to return.
                 clearPersistedGoal: () => {
-                    if (session.state.activeGoal !== undefined) {
+                    if (persistedRunGoal &&
+                        isSameGoalInstance(session.state.activeGoal, persistedRunGoal)) {
                         session.state.activeGoal = undefined;
                         this.sessionManager.saveState(session.state);
                     }
@@ -1839,6 +1885,9 @@ export class Engine {
                             this.activeGoalHook = null;
                     }
                 },
+                updateGoalJudgeContext: (context) => {
+                    goalJudgeContext = context;
+                },
                 ctxOverheadStore: {
                     get: (s) => this.ctxOverheadBySid.get(s) ?? 0,
                     set: (s, n) => {
@@ -1863,6 +1912,7 @@ export class Engine {
                 onStream: options?.onStream,
                 signal: options?.signal,
                 freshImageMessages: freshImageMessage ? [freshImageMessage] : undefined,
+                volatileContextMessages: dynamicContextMsg ? [dynamicContextMsg] : undefined,
                 // Goal mode: the active goal is surfaced to the on_stop handler via
                 // ctx.data.goal; the GoalStopHook (registered above) judges it.
                 goal: normalizedGoal,
@@ -1874,7 +1924,7 @@ export class Engine {
                     session.state.turnCount = turnCount;
                     // baseline + this run's running total (idempotent per boundary,
                     // accumulates across runs; carries cacheRead/cacheCreation too).
-                    session.state.tokenUsage = foldRunUsage(usageBaseline, modelFacade.getUsage());
+                    session.state.tokenUsage = foldRunUsage(usageBaseline, getRunUsage());
                     // Surface the whole-session monotonic cache counts to the UI.
                     // Separate from turn-loop's authoritative per-response emit (which
                     // drives the live context reading and single-turn metric).
@@ -1901,6 +1951,7 @@ export class Engine {
                     this.sessionManager.saveState(session.state);
                 },
             });
+            toolCtx.recordBilledUsage = recordExternalBilledUsage;
             // Expose this run's loop for mid-run extension (TODO 3.1). Top-level only —
             // a sub-agent's loop is its own concern and isn't user-extendable.
             if (this.config.isSubAgent !== true)
@@ -1910,9 +1961,38 @@ export class Engine {
             // only — sub-agents don't carry user-clearable persistent goals.
             if (this.config.isSubAgent !== true)
                 this.activeRunSession = session;
+            const applyGoalTermination = (termination) => {
+                if (!termination || !persistedRunGoal)
+                    return;
+                // Judge prompt overflow ends only this run. The objective is unfinished
+                // and may be resumed after the user reduces fixed judge context, so it
+                // must not get a terminal tombstone or be cleared from activeGoal.
+                if (termination === "judge_prompt_too_large")
+                    return;
+                // Record the terminal identity even when a newer goal has already
+                // replaced it. Only clear activeGoal when it is still the run's goal.
+                session.state.goalTerminal = {
+                    objective: persistedRunGoal.objective,
+                    setAtMs: persistedRunGoal.setAtMs,
+                    reason: termination,
+                    terminatedAtMs: Date.now(),
+                };
+                if (isSameGoalInstance(session.state.activeGoal, persistedRunGoal)) {
+                    session.state.activeGoal = undefined;
+                }
+                this.sessionManager.saveState(session.state);
+                if (goalHookHandler) {
+                    this.hooks.unregister("on_stop", goalHookHandler);
+                    if (this.activeGoalHook === goalHookHandler)
+                        this.activeGoalHook = null;
+                }
+            };
             let result;
+            let firstGoalTermination;
             try {
                 result = await turnLoop.run(messages);
+                firstGoalTermination = result.goalTermination;
+                applyGoalTermination(result.goalTermination);
                 // ── Headless: drain background sub-agents before resolving ───────
                 // Unified background-work model (2026-06-17): the engine NO LONGER parks
                 // every run waiting on background work. Background work (sub-agents,
@@ -1966,14 +2046,19 @@ export class Engine {
                             role: "user",
                             content: `<system-reminder>\n${buildNotificationMessage(pending)}\n</system-reminder>`,
                         };
-                        if (aborted) {
+                        if (aborted || firstGoalTermination) {
                             // Mark injected: a synthetic notification, not the user's own input —
                             // the disk reader drops it on replay so no phantom user bubble.
+                            // A goal termination is also a hard boundary: retain the notification
+                            // for recovery, but never re-enter TurnLoop (which would reset its
+                            // run-scoped goal budget tracker and could overwrite the first reason).
                             session.transcript.appendMessage(injected.role, injected.content, { injected: true });
                             result = { ...result, messages: [...result.messages, injected] };
                             break;
                         }
                         result = await turnLoop.run([...result.messages, injected]);
+                        firstGoalTermination ??= result.goalTermination;
+                        applyGoalTermination(result.goalTermination);
                     }
                 }
             }
@@ -1993,17 +2078,18 @@ export class Engine {
                 this.hooks.unregister("on_tool_start", fileHistoryHandler);
             }
             this.lastMessages = result.messages;
-            this.compactedMessagesBySession.set(session.state.sessionId, this.stripUserContextMessage(result.messages, userContextMsg));
+            const cachedMessages = this.stripInjectedContextMessages(result.messages, userContextMsg, dynamicContextMsg);
+            this.compactedMessagesBySession.set(session.state.sessionId, cachedMessages);
             logger.info("engine.done", {
                 sessionId: session.state.sessionId,
                 reason: result.reason,
                 turns: turnLoop.currentTurn,
-                tokens: modelFacade.getUsage().totalTokens,
+                tokens: getRunUsage().totalTokens,
             });
             recordSessionEnd(session.state.sessionId, {
                 reason: result.reason,
                 turns: turnLoop.currentTurn,
-                cost: modelFacade.getUsage(),
+                cost: getRunUsage(),
             });
             // Session-level hook: fired symmetrically with on_session_start once
             // the turn loop has resolved (completion, error, or abort). Handlers
@@ -2013,11 +2099,11 @@ export class Engine {
                 sessionId: session.state.sessionId,
                 reason: result.reason,
                 turnCount: turnLoop.currentTurn,
-            });
+            }, options?.signal);
             // Fire-and-forget memory pipeline: extract durable memories from the
             // transcript, save a session summary, and conditionally trigger
             // auto-dream consolidation. Doesn't block the Engine result.
-            void this.runMemoryPipeline(session.transcript, session.state.sessionId, cwd, llmClient);
+            void this.runMemoryPipeline(session.transcript, session.state.sessionId, cwd, llmClient, recordExternalBilledUsage);
             // Fire-and-forget session title generation — only after the FIRST turn.
             // Reuses the already-resolved auxSummaryClient (aux model, cheap). Best-
             // effort: failures never touch the run result. The renderer writes the
@@ -2028,20 +2114,21 @@ export class Engine {
                 const userMsgCount = userMsgEvents.length;
                 const onStream = options?.onStream;
                 if (userMsgCount === 1 && onStream && result.text) {
+                    const sessionId = session.state.sessionId;
                     const rawContent = userMsgEvents[0]?.data?.content;
                     const firstUserText = typeof rawContent === "string" ? rawContent : JSON.stringify(rawContent ?? "");
-                    void buildSessionTitle(auxSummaryClient, firstUserText, result.text)
+                    void buildSessionTitle(auxSummaryClient, firstUserText, result.text, recordExternalBilledUsage)
                         .then((title) => {
                         if (title) {
                             // Persist the title so it survives a localStorage wipe / disk
                             // rebuild — it used to live only in the renderer's localStorage
-                            // index. This .then resolves AFTER the saveState below (:1892), so
-                            // it must save again itself rather than rely on that write.
-                            session.state.title = title;
-                            this.sessionManager.saveState(session.state);
+                            // index. Read the latest persisted state at callback time and
+                            // merge only title; the completed run's session.state snapshot
+                            // may already be stale after later serial session updates.
+                            this.sessionManager.updateSessionState(sessionId, { title });
                             onStream({
                                 type: "session_title",
-                                sessionId: session.state.sessionId,
+                                sessionId,
                                 title,
                             });
                         }
@@ -2054,32 +2141,82 @@ export class Engine {
             // failures (model_error, prompt_too_long, ...) — previously every
             // non-completed outcome collapsed to "errored", which threw away the
             // distinction and misled anyone reading state.json.
+            if (session.transcript.flushFailed()) {
+                const failure = session.transcript.getFlushFailure();
+                logger.error("engine.transcript_persistence_failed", {
+                    sessionId: session.state.sessionId,
+                    terminalReason: result.reason,
+                    degraded: true,
+                    ...failure,
+                });
+            }
             session.state.turnCount = turnLoop.currentTurn;
             session.state.status = result.reason;
             // Session-cumulative (baseline + this run) for persistence...
-            const usage = modelFacade.getUsage();
+            const usage = getRunUsage();
             session.state.tokenUsage = foldRunUsage(usageBaseline, usage);
             if (this.config.costStore) {
                 session.state.costState = this.config.costStore.serialize();
             }
+            // runInProgress excludes another whole-state writer only on this Engine
+            // instance. A different Engine using the same sessionId can still race
+            // this saveState (including an old run's abort cleanup vs a replacement
+            // Engine); cross-instance/process session serialization is a separate finding.
             this.sessionManager.saveState(session.state);
+            runAccountingFinalized = true;
             // Hook: agent end
             await this.emitHook("on_agent_end", {
                 sessionId: session.state.sessionId,
                 reason: result.reason,
                 turnCount: turnLoop.currentTurn,
-            });
+            }, options?.signal);
             // Emit completion
             options?.onStream?.({ type: "turn_complete", reason: result.reason });
             return {
                 text: result.text,
                 reason: result.reason,
+                goalTermination: firstGoalTermination,
                 sessionId: session.state.sessionId,
                 turnCount: turnLoop.currentTurn,
                 usage: {
                     promptTokens: usage.totalPromptTokens,
                     completionTokens: usage.totalCompletionTokens,
                     totalTokens: usage.totalTokens,
+                    cacheReadTokens: usage.totalCacheReadTokens,
+                    cacheCreationTokens: usage.totalCacheCreationTokens,
+                },
+            };
+        });
+        return Promise.resolve(sessionRun).catch((err) => {
+            // The session is already persisted as active before runWithSid starts.
+            // Initialization failures (client creation, MCP connection, prompt/hooks)
+            // therefore need the same terminal lifecycle treatment as turn-loop errors.
+            const error = formatFriendlyError(err);
+            session.state.status = "model_error";
+            this.sessionManager.saveState(session.state);
+            session.transcript.appendError(error, { phase: "initialization" });
+            logger.error("engine.run_lifecycle_failed", {
+                sessionId: session.state.sessionId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            recordSessionEnd(session.state.sessionId, {
+                reason: "model_error",
+                turns: session.state.turnCount,
+            });
+            options?.onStream?.({ type: "error", error });
+            options?.onStream?.({ type: "turn_complete", reason: "model_error" });
+            const usage = session.state.tokenUsage;
+            return {
+                text: `ERROR: ${error}`,
+                reason: "model_error",
+                sessionId: session.state.sessionId,
+                turnCount: session.state.turnCount,
+                usage: {
+                    promptTokens: usage.promptTokens ?? 0,
+                    completionTokens: usage.completionTokens ?? 0,
+                    totalTokens: usage.totalTokens ?? 0,
+                    cacheReadTokens: usage.cacheReadTokens ?? 0,
+                    cacheCreationTokens: usage.cacheCreationTokens ?? 0,
                 },
             };
         });
@@ -2102,16 +2239,19 @@ export class Engine {
      * run path and forceCompact share one definition of the summarization call.
      */
     buildSummarizeFn(auxSummaryClient, recordCumulativeUsage) {
-        return async (prompt) => {
+        return async (prompt, signal) => {
             const summaryResponse = await auxSummaryClient.createMessage({
                 systemPrompt: "You are a conversation summarizer. Be concise and factual.",
                 messages: [{ role: "user", content: prompt }],
                 tools: [],
                 maxTokens: 1024,
+                billingEnabled: true,
+                requestVisible: false,
                 // Auxiliary call — no need to burn reasoning tokens. On DeepSeek V4
                 // this flips thinking off (~3x faster, fewer tokens); on every other
                 // OpenAI-compatible provider the field is ignored.
                 reasoning: { mode: "off" },
+                signal,
             });
             if (summaryResponse.usage) {
                 recordCumulativeUsage?.(summaryResponse.usage);
@@ -2171,7 +2311,7 @@ export class Engine {
             return fallback;
         }
     }
-    async runMemoryPipeline(transcript, sessionId, cwd, primaryClient) {
+    async runMemoryPipeline(transcript, sessionId, cwd, primaryClient, recordBilledUsage) {
         try {
             // Background calls run on the auxiliary model when configured, so memory
             // book-keeping doesn't burn the expensive primary model every turn.
@@ -2211,12 +2351,22 @@ export class Engine {
                         messages: [{ role: "user", content: userMsg }],
                         tools: [],
                         maxTokens: 1024,
-                        recordUsage: false,
+                        billingEnabled: true,
+                        requestVisible: false,
                         reasoning: { mode: "off" },
                     });
+                    if (resp.usage)
+                        recordBilledUsage?.(resp.usage);
                     return resp.text;
                 },
-                runDream: async ({ systemPrompt, userPrompt, projectDir }) => this.runDreamLoop({ systemPrompt, userPrompt, projectDir, llmClient, sessionId }),
+                runDream: async ({ systemPrompt, userPrompt, projectDir }) => this.runDreamLoop({
+                    systemPrompt,
+                    userPrompt,
+                    projectDir,
+                    llmClient,
+                    sessionId,
+                    recordBilledUsage,
+                }),
                 projectDir: cwd,
                 // settings.memories.maxCount caps memories accepted per extraction;
                 // autoExtract=false turns the extractor off (summaries/dream stay).
@@ -2262,6 +2412,7 @@ export class Engine {
             toolContext: this.buildToolContext(),
             projectDir: opts.projectDir,
             sessionId: opts.sessionId,
+            onUsage: opts.recordBilledUsage,
         });
         return ran;
     }
@@ -2648,11 +2799,39 @@ export class Engine {
             strategy: after >= before ? "no compaction needed" : (compactStrategy ?? "compacted"),
         };
     }
-    stripUserContextMessage(messages, userContextMsg) {
+    stripInjectedContextMessages(messages, userContextMsg, dynamicContextMsg) {
+        const withoutDynamicContext = dynamicContextMsg
+            ? messages.filter((msg) => msg !== dynamicContextMsg)
+            : [...messages];
         if (!userContextMsg || messages[0] !== userContextMsg) {
-            return [...messages];
+            return withoutDynamicContext;
+        }
+        return withoutDynamicContext.slice(1);
+    }
+    recordCacheReadDiagnostics(sessionId, usage) {
+        const current = usage.cacheReadTokens;
+        if (current === undefined || !Number.isFinite(current))
+            return;
+        const previous = this.lastCacheReadBySid.get(sessionId);
+        this.lastCacheReadBySid.delete(sessionId);
+        this.lastCacheReadBySid.set(sessionId, current);
+        if (this.lastCacheReadBySid.size > CACHE_READ_DIAGNOSTIC_MAX_SESSIONS) {
+            const oldestSessionId = this.lastCacheReadBySid.keys().next().value;
+            if (oldestSessionId !== undefined)
+                this.lastCacheReadBySid.delete(oldestSessionId);
+        }
+        if (previous === undefined || previous < CACHE_READ_DROP_MIN_PREVIOUS_TOKENS)
+            return;
+        const dropRatio = previous > 0 ? current / previous : 1;
+        if (current <= CACHE_READ_DROP_MAX_CURRENT_TOKENS && dropRatio <= CACHE_READ_DROP_RATIO) {
+            logger.warn("engine.cache_read_drop", {
+                sessionId,
+                previousCacheReadTokens: previous,
+                currentCacheReadTokens: current,
+                dropRatio,
+                hint: "Prompt cache read tokens dropped sharply. Check for changed cacheable prefix, stale dynamic context in history, tool/schema changes, or provider cache eviction.",
+            });
         }
-        return messages.slice(1);
     }
     getSettingsManager() {
         if (!this.settingsManager) {
@@ -2681,7 +2860,7 @@ export class Engine {
         }
         return target;
     }
-    buildPermissionConfig(mode, cwd) {
+    buildPermissionConfig(mode, cwd, approvalRouter) {
         const rules = [...this.preset.defaultPermissionRules];
         // Memory tools: dream scope is the LLM's own workspace, so save/delete
         // there go through without prompting. user-scope save/delete have no
@@ -2734,7 +2913,16 @@ export class Engine {
             // every `ask` permission silently fell through to deny-all and
             // the user saw "Permission denied by user" with NO modal — exactly
             // the bug that motivated this fix.
-            const interactive = getInteractiveApprovalBackend();
+            let interactive;
+            if (approvalRouter) {
+                interactive =
+                    this.interactiveBackends.get(approvalRouter) ??
+                        new InteractiveApprovalBackend(approvalRouter);
+                this.interactiveBackends.set(approvalRouter, interactive);
+            }
+            else {
+                interactive = getInteractiveApprovalBackend();
+            }
             if (interactive.hasPromptFn()) {
                 backend = interactive;
             }
@@ -2749,21 +2937,38 @@ export class Engine {
         return { rules, backend };
     }
     /**
-     * Switch permission mode at runtime. Takes effect immediately for any
-     * in-flight ToolExecutor (which holds a reference to the same classifier),
-     * and the new mode is used for any subsequent run() calls.
+     * Switch permission mode at runtime. Idle updates apply immediately; busy
+     * updates are committed atomically when the current run settles, so its
+     * classifier and ToolContext retain the immutable start-of-run snapshot.
      * Session-only — does not persist to settings.
      */
     setPermissionMode(mode) {
+        if (this.runInProgress) {
+            this.pendingPermissionMode = mode;
+            this.pendingPlanMode = mode === "plan";
+            return;
+        }
+        this.applyPermissionState(mode, mode === "plan");
+    }
+    applyPermissionState(mode, planMode) {
         this.config = { ...this.config, permissionMode: mode };
         this.permissionMode = mode;
-        this.planMode = mode === "plan";
+        this.planMode = planMode;
         if (this.activePermission) {
             const cwd = this.config.cwd ?? process.cwd();
-            const { rules, backend } = this.buildPermissionConfig(mode, cwd);
+            const { rules, backend } = this.buildPermissionConfig(mode, cwd, this.activeApprovalRouter);
             this.activePermission.reconfigure(mode, backend, rules);
         }
     }
+    applyPendingPermissionState() {
+        if (this.pendingPermissionMode === null)
+            return;
+        const mode = this.pendingPermissionMode;
+        const planMode = this.pendingPlanMode ?? mode === "plan";
+        this.pendingPermissionMode = null;
+        this.pendingPlanMode = null;
+        this.applyPermissionState(mode, planMode);
+    }
     getPermissionMode() {
         return this.config.permissionMode ?? "acceptEdits";
     }
@@ -2785,8 +2990,7 @@ export class Engine {
      * rule set buildPermissionConfig does, without constructing a backend.
      */
     getPermissionRules() {
-        return this.buildPermissionConfig(this.getPermissionMode(), this.config.cwd ?? process.cwd())
-            .rules;
+        return this.buildPermissionConfig(this.getPermissionMode(), this.config.cwd ?? process.cwd(), this.activeApprovalRouter).rules;
     }
     /**
      * Toggle plan mode directly. Called by the Plan tool (Task 7) via ToolContext.engine.
@@ -2796,13 +3000,10 @@ export class Engine {
         if (value) {
             this.setPermissionMode("plan");
         }
-        else if (this.permissionMode === "plan") {
+        else if ((this.pendingPermissionMode ?? this.permissionMode) === "plan") {
             // Leaving plan mode: drop back to the default.
             this.setPermissionMode("acceptEdits");
         }
-        else {
-            this.planMode = value;
-        }
     }
     /**
      * Block until a background agent's state changes (finishes / its result is