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

package/dist/engine/engine.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";
@@ -53,16 +53,16 @@ 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 { 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
@@ -266,6 +266,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
@@ -654,7 +655,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 +667,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 +681,7 @@ export class Engine {
             sessionId,
             id: entryId,
             clientMessageId,
+            attachmentCount: attachments?.length ?? 0,
             activeRunSessionId,
             queueLength: next.length,
         });
@@ -715,6 +718,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) {
@@ -807,139 +817,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}). ` +
@@ -1128,40 +1015,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,8 +1138,14 @@ 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;
         };
@@ -1724,17 +1584,20 @@ export class Engine {
             // 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 +1606,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 +1623,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 +1640,27 @@ 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,
                     // 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 +1670,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.
@@ -1815,8 +1702,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 +1739,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 +1750,9 @@ export class Engine {
                             this.activeGoalHook = null;
                     }
                 },
+                updateGoalJudgeContext: (context) => {
+                    goalJudgeContext = context;
+                },
                 ctxOverheadStore: {
                     get: (s) => this.ctxOverheadBySid.get(s) ?? 0,
                     set: (s, n) => {
@@ -1863,6 +1777,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,
@@ -1910,9 +1825,31 @@ 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;
+                // 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;
             try {
                 result = await turnLoop.run(messages);
+                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,
@@ -1974,6 +1911,7 @@ export class Engine {
                             break;
                         }
                         result = await turnLoop.run([...result.messages, injected]);
+                        applyGoalTermination(result.goalTermination);
                     }
                 }
             }
@@ -1993,7 +1931,8 @@ 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,
@@ -2648,11 +2587,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) {

package/dist/engine/goal.d.ts

@@ -47,6 +47,21 @@ export interface GoalConfig {
      */
     setAtMs?: number;
 }
+/** A forced terminal outcome for one concrete persisted goal instance. */
+export type GoalTerminationReason = "stop_blocks_exhausted" | "token_budget_exhausted" | "time_budget_exhausted" | "max_turns_exhausted";
+/**
+ * Persisted terminal marker used to prevent a stale whole-state writer from
+ * making an exhausted goal armable again. `objective + setAtMs` is the goal
+ * instance identity; `terminatedAtMs` only orders competing tombstones.
+ */
+export interface GoalTerminal {
+    objective: string;
+    setAtMs?: number;
+    reason: GoalTerminationReason;
+    terminatedAtMs?: number;
+}
+/** True only when both values identify the same concrete goal instance. */
+export declare function isSameGoalInstance(left: Pick<GoalConfig, "objective" | "setAtMs"> | undefined, right: Pick<GoalConfig, "objective" | "setAtMs"> | undefined): boolean;
 /**
  * Default consecutive-stop-block cap for goal runs. The real safety net for an
  * unattended goal is the token/time budget + maxTurns; this cap only stops a
@@ -185,3 +200,5 @@ export declare function recordGoalUsage(tracker: GoalBudgetTracker, turnTokens:
  * pass the current clock (and tests pass a fixed value).
  */
 export declare function goalBudgetExceeded(tracker: GoalBudgetTracker, nowMs: number): boolean;
+/** Identify which goal budget forced termination, preserving token-first precedence. */
+export declare function goalBudgetTerminationReason(tracker: GoalBudgetTracker, nowMs: number): Extract<GoalTerminationReason, "token_budget_exhausted" | "time_budget_exhausted"> | undefined;

package/dist/engine/goal.js

@@ -10,6 +10,10 @@
  * it accumulates total tokens across turns and stamps a wall-clock start,
  * so an unattended goal run can't burn tokens or wall time without bound.
  */
+/** True only when both values identify the same concrete goal instance. */
+export function isSameGoalInstance(left, right) {
+    return !!left && !!right && left.objective === right.objective && left.setAtMs === right.setAtMs;
+}
 /**
  * Default consecutive-stop-block cap for goal runs. The real safety net for an
  * unattended goal is the token/time budget + maxTurns; this cap only stops a
@@ -94,7 +98,7 @@ export function normalizeGoal(raw) {
  */
 export function resolveGoalSetAt(explicitObjective, stored, nowMs) {
     const sameGoalContinues = !!stored && stored.objective === explicitObjective;
-    return sameGoalContinues ? stored.setAtMs ?? nowMs : nowMs;
+    return sameGoalContinues ? (stored.setAtMs ?? nowMs) : nowMs;
 }
 /** Interactive (no-goal) turn ceiling — a single prompt rarely needs more. */
 export const INTERACTIVE_DEFAULT_MAX_TURNS = 100;
@@ -187,10 +191,16 @@ export function recordGoalUsage(tracker, turnTokens) {
  * pass the current clock (and tests pass a fixed value).
  */
 export function goalBudgetExceeded(tracker, nowMs) {
+    return goalBudgetTerminationReason(tracker, nowMs) !== undefined;
+}
+/** Identify which goal budget forced termination, preserving token-first precedence. */
+export function goalBudgetTerminationReason(tracker, nowMs) {
     const { tokenBudget, timeBudgetMs } = tracker.goal;
-    if (typeof tokenBudget === "number" && tracker.tokensUsed > tokenBudget)
-        return true;
-    if (typeof timeBudgetMs === "number" && nowMs - tracker.startedAtMs > timeBudgetMs)
-        return true;
-    return false;
+    if (typeof tokenBudget === "number" && tracker.tokensUsed > tokenBudget) {
+        return "token_budget_exhausted";
+    }
+    if (typeof timeBudgetMs === "number" && nowMs - tracker.startedAtMs > timeBudgetMs) {
+        return "time_budget_exhausted";
+    }
+    return undefined;
 }