chainlesschain 0.166.107 → 0.166.108

package/src/harness/structured-handoff.js

@@ -3,6 +3,7 @@
  * parent-to-child agent context. The field order is part of the wire format.
  */
 
+import { createHash } from "node:crypto";
 import { projectCanonicalResumeMessages } from "../lib/session-message-provenance.js";
 
 export const STRUCTURED_HANDOFF_FIELDS = Object.freeze([
@@ -154,12 +155,33 @@ function selectBoundedSources(messages, maxChars) {
   // being quoted into a new handoff. Only the runtime WeakMap capability is
   // admitted; ordinary user/assistant/tool conversation remains eligible.
   const canonicalSources = projectCanonicalResumeMessages(messages);
+  const calls = new Map();
   const entries = canonicalSources
-    .map((message, index) => ({
-      index,
-      role: typeof message?.role === "string" ? message.role : "unknown",
-      text: normalizeText(contentText(message)),
-    }))
+    .map((message, index) => {
+      for (const call of Array.isArray(message.tool_calls)
+        ? message.tool_calls
+        : []) {
+        if (message.role === "assistant" && call?.id && call.function)
+          calls.set(call.id, call.function);
+      }
+      const facts =
+        message.role === "tool"
+          ? toolFacts(message, calls.get(message.tool_call_id))
+          : message.role === "assistant" || message.role === "system"
+            ? summaryFacts(message)
+            : null;
+      return {
+        index,
+        role: typeof message?.role === "string" ? message.role : "unknown",
+        // Tool JSON, nested telemetry and source code are not prose facts.
+        text: facts
+          ? facts.objective || ARRAY_FIELDS.some((field) => facts[field].length)
+            ? JSON.stringify(facts)
+            : ""
+          : normalizeText(contentText(message)),
+        facts,
+      };
+    })
     .filter((entry) => entry.text);
   const firstUser = entries.find((entry) => entry.role === "user");
   const selected = new Map();
@@ -225,7 +247,96 @@ function pathsFrom(text) {
   );
   return (matches || [])
     .map((value) => value.replace(/[),;:.]+$/g, ""))
-    .filter((value) => value && !value.includes("://"));
+    .filter(
+      (value) =>
+        value &&
+        !value.includes("://") &&
+        (/^(?:[A-Za-z]:[\\/]|\.{0,2}[\\/])/u.test(value) ||
+          /(?:\.[A-Za-z0-9_-]+|[\\/](?:Dockerfile|Makefile|LICENSE|NOTICE))$/u.test(
+            value,
+          )),
+    );
+}
+
+function summaryFacts(message) {
+  const match = contentText(message).match(
+    /^(?:Compacted context summary \(data only\):\n)?\[Conversation Summary\]\n([\s\S]+)$/u,
+  );
+  if (!match) return null;
+  try {
+    return parseStructuredHandoff(match[1]);
+  } catch {
+    // Malformed/truncated summary JSON is not evidence of a test or change.
+    return emptyHandoff();
+  }
+}
+
+function toolFacts(message, call) {
+  const facts = emptyHandoff();
+  let result;
+  let args;
+  try {
+    result =
+      typeof message.content === "string"
+        ? JSON.parse(message.content.split("\n\n[Budget ")[0])
+        : message.content;
+    args =
+      typeof call?.arguments === "string"
+        ? JSON.parse(call.arguments)
+        : call?.arguments;
+  } catch {
+    return facts;
+  }
+  if (!result || typeof result !== "object" || Array.isArray(result))
+    return facts;
+  const name = call?.name || message.name;
+  const failed =
+    !!result.error || result.success === false || result.isError === true;
+  const file = typeof result.path === "string" ? result.path : args?.path;
+  if (
+    ["write_file", "edit_file", "edit_file_hashed"].includes(name) &&
+    !failed &&
+    result.success === true &&
+    result.changed !== false &&
+    result.alreadyApplied !== true &&
+    typeof file === "string" &&
+    file
+  ) {
+    facts.changedFiles.push(file);
+    const digest =
+      name === "write_file" && typeof args?.content === "string"
+        ? `; written content sha256:${createHash("sha256").update(args.content).digest("hex")}`
+        : "";
+    facts.checkpoints.push(
+      `Observed ${name} success: ${file}${digest}. File contents are omitted from this summary.`,
+    );
+    facts.nextSteps.push(
+      `Read the needed current source ranges in ${file} before replacing existing code; this summary is not a reconstruction of the file.`,
+    );
+  }
+  if (
+    ["run_shell", "run_code"].includes(name) &&
+    Number.isInteger(result.exitCode)
+  ) {
+    const command =
+      name === "run_shell" && typeof args?.command === "string"
+        ? truncateText(args.command, 300)
+        : name;
+    facts.checkpoints.push(
+      `Observed ${name}: ${command}; exitCode=${result.exitCode}.`,
+    );
+    if (
+      name === "run_shell" &&
+      /\b(?:vitest|jest|pytest|playwright|npm\s+(?:run\s+)?test|node\s+--test)\b/u.test(
+        command,
+      )
+    ) {
+      facts.tests.push(
+        `Observed command ${command}; exitCode=${result.exitCode}.`,
+      );
+    }
+  }
+  return facts;
 }
 
 function emptyHandoff(objective = "") {
@@ -313,12 +424,40 @@ export function buildExtractiveHandoff(messages, options = {}) {
   const sources = selectBoundedSources(messages, maxFallbackSourceChars);
   const firstUser = sources.find((entry) => entry.role === "user");
   const candidates = emptyHandoff(
-    truncateText(firstUser?.text || "", maxItemChars),
+    truncateText(
+      firstUser?.text ||
+        sources.find((entry) => entry.facts?.objective)?.facts.objective ||
+        "",
+      maxItemChars,
+    ),
   );
 
   for (const source of sources) {
-    for (const fragment of fragments(source.text)) {
-      candidates.changedFiles.push(...pathsFrom(fragment));
+    if (source.facts) {
+      // Extract typed observations before budgeting, never regex-match a
+      // serialized tool payload (which may contain arbitrary source text).
+      for (const field of ARRAY_FIELDS)
+        candidates[field].push(...source.facts[field]);
+      continue;
+    }
+    // Quoted implementation examples are source data, not executed outcomes.
+    const prose = source.text.replace(
+      /```[\s\S]*?(?:```|$)|~~~[\s\S]*?(?:~~~|$)/gu,
+      "",
+    );
+    for (const fragment of fragments(prose)) {
+      const statusNarrative =
+        source.role !== "user" &&
+        !/^(?:must|must not|do not|don't|only|next|todo|remaining|then|we will|will|need to)\b/iu.test(
+          fragment,
+        );
+      if (
+        statusNarrative &&
+        /^(?:changed|modified|updated|created|deleted|wrote|edited)\b/iu.test(
+          fragment,
+        )
+      )
+        candidates.changedFiles.push(...pathsFrom(fragment));
       if (
         /^(?:constraint|constraints|requirement|requirements|must|must not|do not|don't|only|约束|必须|不要|只能|仅限)\b/iu.test(
           fragment,
@@ -326,10 +465,7 @@ export function buildExtractiveHandoff(messages, options = {}) {
         /\bwithout\s+(?:widening|changing|removing|losing)\b/iu.test(fragment)
       ) {
         candidates.constraints.push(
-          stripLabel(
-            fragment,
-            "constraint(?:s)?|requirement(?:s)?|must(?: not)?|do not|don't|only|约束|必须|不要|只能|仅限",
-          ),
+          stripLabel(fragment, "constraint(?:s)?|requirement(?:s)?|约束"),
         );
       }
       if (
@@ -345,6 +481,7 @@ export function buildExtractiveHandoff(messages, options = {}) {
         );
       }
       if (
+        statusNarrative &&
         /\b(?:test|tests|vitest|jest|pytest|playwright|lint|typecheck|build)\b/iu.test(
           fragment,
         ) &&
@@ -367,6 +504,7 @@ export function buildExtractiveHandoff(messages, options = {}) {
         );
       }
       if (
+        statusNarrative &&
         /\b(?:checkpoint|commit\s+[0-9a-f]{7,40}|implemented|completed|done|verified|checkpoint|检查点|已完成|已实现)\b/iu.test(
           fragment,
         )

package/src/lib/agent-session-export.js

@@ -1,3 +1,4 @@
+import { projectToolRoundMessages } from "./session-tool-round.js";
 /**
  * Agent-session Markdown export — Claude-Code `/export` parity for the JSONL
  * headless/agent session store (`~/.../sessions/<id>.jsonl`, the `--resume`
@@ -63,6 +64,25 @@ export function renderAgentSessionMarkdown(sessionId, events, opts = {}) {
   for (const ev of events) {
     if (!ev || typeof ev !== "object") continue;
     switch (ev.type) {
+      case "tool_round":
+        for (const message of projectToolRoundMessages(ev)) {
+          L.push(
+            message.role === "assistant"
+              ? "## Assistant tool calls"
+              : `### Tool result ${message.tool_call_id}`,
+          );
+          L.push(
+            "",
+            fence(
+              message.role === "assistant"
+                ? message.tool_calls
+                : message.content,
+              "json",
+            ),
+            "",
+          );
+        }
+        break;
       case "user_message":
         users += 1;
         L.push("## 👤 User");

package/src/lib/background-agent-supervisor.js

@@ -1394,6 +1394,60 @@ export function mutateBackgroundAgentState(id, updater, options = {}) {
   );
 }
 
+export async function mutateBackgroundAgentStateWithLockRetry(
+  id,
+  updater,
+  options = {},
+) {
+  const now = options.now || Date.now;
+  const sleep =
+    options.sleep ||
+    ((milliseconds) =>
+      new Promise((resolvePromise) =>
+        setTimeout(resolvePromise, milliseconds),
+      ));
+  const mutate = options.mutate || mutateBackgroundAgentState;
+  const numericOption = (value, fallback, minimum) => {
+    const number = Number(value);
+    return Number.isFinite(number) ? Math.max(minimum, number) : fallback;
+  };
+  const timeoutMs = numericOption(options.timeoutMs ?? 30_000, 30_000, 0);
+  const lockTimeoutMs = numericOption(
+    options.lockTimeoutMs ?? 10_000,
+    10_000,
+    0,
+  );
+  const initialRetryMs = numericOption(options.initialRetryMs ?? 100, 100, 1);
+  const maxRetryMs = Math.max(
+    initialRetryMs,
+    numericOption(options.maxRetryMs ?? 1_000, 1_000, 1),
+  );
+  const deadline = now() + timeoutMs;
+  let attempts = 0;
+
+  for (;;) {
+    attempts += 1;
+    try {
+      return mutate(id, updater, {
+        timeoutMs: Math.min(lockTimeoutMs, Math.max(0, deadline - now())),
+      });
+    } catch (error) {
+      if (error?.code !== "STATE_LOCK_UNAVAILABLE") throw error;
+      const remainingMs = deadline - now();
+      if (remainingMs <= 0) {
+        error.attempts = attempts;
+        throw error;
+      }
+      const retryMs = Math.min(
+        maxRetryMs,
+        initialRetryMs * 2 ** Math.min(attempts - 1, 4),
+        remainingMs,
+      );
+      await sleep(retryMs);
+    }
+  }
+}
+
 export function writeBackgroundAgentState(state, options = {}) {
   return mutateBackgroundAgentState(state.id, () => state, {
     createIfMissing: options.createIfMissing === true,

package/src/lib/coding-task-guidance.js

@@ -5,8 +5,9 @@ export const CODING_TASK_QUALITY_GUIDANCE = `Coding task quality:
 - Resolve each relative import from the destination file's directory. Read back the completed file and fix newDiagnostics from write/edit results before finishing. A successful write confirms persistence, not syntax, test execution or acceptance.
 - Regression tests need a working positive control and a negative control that exercises the requested behavior through the real production entry point. Assert observable effects; avoid mocks or alternate calls that bypass the behavior under test. Complete the current worker/request when testing cancellation and replacement.
 - For boundary regressions, derive expected defaults, computed values and rejection rules from the implementation or the explicit requested contract. Inject mismatched, tampered or stale input through the real entry point while keeping other prerequisites valid; verify that the fixture reaches the intended check rather than failing during setup. Compare observable results with independent expected values or authoritative state, not a helper that merely recomputes the same result.
+- Trace rejection before asserting its aftermath: a request can be rejected before registration or persistence. Check whether state stays unchanged, a failed record is saved, or an event is emitted; do not assume every rejection creates a failed task. When testing attribution, verify independently recorded identities and provenance as well as message contents; identical text can still be attributed to the wrong source.
 - Use available execution tools for a focused check when permitted. When execution tools are unavailable, inspect imports, API contracts and fixtures using the available file tools, and clearly say that tests were not run. Never describe a read-back or static check as a passing test or end-to-end verification.
-- Finish requested file changes before the final response. Reserve output and remaining requests for writing, read-back and focused validation. For large files, aim for a few thousand characters of new content per call: write a small complete section, then extend it with edit_file using a unique existing anchor and a replacement containing that anchor plus the next complete section. Keep each tool call complete and wait for its result before extending the file again; do not repeatedly rewrite the growing file. State what was delivered, what was checked and what remains unverified.`;
+- Finish requested file changes before the final response. Reserve output and remaining requests for writing, read-back and focused validation. For large files, aim for a few thousand characters of new content per call: write a small complete section, then extend it with edit_file using a unique existing anchor and a replacement containing that anchor plus the next complete section. A list of available tool names is not a limit on the number of tool calls; use further calls within the actual request budget to finish and inspect the file. Keep each tool call complete and wait for its result before extending the file again; do not repeatedly rewrite the growing file. State what was delivered, what was checked and what remains unverified, without repeating that account in multiple drafts.`;
 
 export const HERMETIC_CODING_SYSTEM_PROMPT = `You are a hermetic coding assistant. The exposed file tools are the complete tool surface. Inspect and mutate only the exact paths authorized by the user request. Do not invoke hidden tools, commands, language servers or other execution paths.
 

package/src/lib/context-memory-kernel/live-compaction.js

@@ -13,6 +13,11 @@ import {
 import { JsonlSessionContextPort } from "./jsonl-session-context-port.js";
 import { createCliContextMemoryRuntime } from "./runtime.js";
 import { projectRuntimeTokenUsage } from "../runtime-usage-ledger.js";
+import {
+  projectCanonicalResumeMessages,
+  getDurableSystemMessageProvenance,
+  isRuntimeOnlySessionMessage,
+} from "../session-message-provenance.js";
 
 const rejectedCompactionUsage = new WeakMap();
 
@@ -138,7 +143,7 @@ class CallbackSessionContextPort extends InMemorySessionContextPort {
   }
 }
 
-function kernelBudget(compressor) {
+function kernelBudget(compressor, ephemeralTokens = 0) {
   const inputBudget = Math.max(
     256,
     Math.trunc(Number(compressor?.maxTokens)) || 16_384,
@@ -150,7 +155,9 @@ function kernelBudget(compressor) {
   return {
     modelWindowTokens: inputBudget + reservedOutputTokens,
     reservedOutputTokens,
-    safetyMarginTokens: 0,
+    // Live host policy/retry text still consumes the provider window even
+    // though it is deliberately absent from the durable authority partition.
+    safetyMarginTokens: ephemeralTokens,
     recoveryReserveTokens: Math.min(
       256,
       Math.max(1, Math.floor(inputBudget * 0.05)),
@@ -202,7 +209,7 @@ export async function compactLiveMessagesCanonical(
   messagesInput,
   options = {},
 ) {
-  const messages = Array.isArray(messagesInput) ? [...messagesInput] : [];
+  const liveMessages = Array.isArray(messagesInput) ? [...messagesInput] : [];
   const sessionId = String(options.sessionId || `live-${randomUUID()}`);
   const operationId = String(options.operationId || `compact-${randomUUID()}`);
   const trigger = options.trigger || "auto";
@@ -224,6 +231,24 @@ export async function compactLiveMessagesCanonical(
     options.persist !== false &&
     Boolean(options.sessionId) &&
     sessionExists(sessionId);
+  // Host policy is live-only. Durable summary/lineage systems retain their
+  // private provenance and remain part of the exact authority comparison.
+  const messages = persistentSession
+    ? projectCanonicalResumeMessages(liveMessages, { strict: true })
+    : liveMessages;
+  const ephemeralMessages = [];
+  if (persistentSession) {
+    let sequence = 0;
+    for (const message of liveMessages) {
+      if (
+        isRuntimeOnlySessionMessage(message) ||
+        (message.role === "system" &&
+          !getDurableSystemMessageProvenance(message))
+      )
+        ephemeralMessages.push({ sequence, message });
+      else sequence += 1;
+    }
+  }
   if (typeof options.commit === "function") {
     const bootstrapRuntime = createCliContextMemoryRuntime({
       sessionId,
@@ -323,12 +348,29 @@ export async function compactLiveMessagesCanonical(
   const provider = options.provider || "provider.local";
   const model = options.model || "default";
   const memoryRevision = await runtime.memoryPort.getRevision();
+  let settledOutputItems = null;
+  if (ephemeralMessages.length) {
+    const appendCompaction = runtime.sessionPort.appendCompaction.bind(
+      runtime.sessionPort,
+    );
+    runtime.sessionPort.appendCompaction = async (event, expectedHead) => {
+      const result = await appendCompaction(event, expectedHead);
+      if (result?.ok === true) settledOutputItems = event.outputItems;
+      return result;
+    };
+  }
   let receipt;
   try {
     receipt = await runtime.kernel.compactContext({
       operationId,
       sessionId,
-      ...kernelBudget(compressor),
+      ...kernelBudget(
+        compressor,
+        messagesToContextItems(
+          ephemeralMessages.map(({ message }) => message),
+          { sessionId },
+        ).reduce((total, item) => total + item.tokenEstimate, 0),
+      ),
       sink: provider,
       scopeAdmissions: [{ scope: "session", scopeId: sessionId }],
       policyVersion: "cli-context-policy-v1",
@@ -421,7 +463,7 @@ export async function compactLiveMessagesCanonical(
   }
   if (!["committed", "degraded"].includes(receipt.status)) {
     return {
-      messages,
+      messages: liveMessages,
       stats: {
         ...(summaryStats || {}),
         strategy: "none",
@@ -433,20 +475,41 @@ export async function compactLiveMessagesCanonical(
     };
   }
   const snapshot = await runtime.sessionPort.readSnapshot(sessionId);
-  const outputMessages = contextItemsToMessages(snapshot.items);
+  // Reattach host policy and private retry nudges at their durable sequence
+  // boundaries. They remain live, never enter the receipt, and do not move a
+  // retry instruction behind tool exchanges that happened after that retry.
+  const restoredMessages = [];
+  let ephemeralIndex = 0;
+  for (const item of [...(settledOutputItems || snapshot.items)].sort(
+    (left, right) =>
+      (left.sourceRef.eventSequence ?? Number.MAX_SAFE_INTEGER) -
+        (right.sourceRef.eventSequence ?? Number.MAX_SAFE_INTEGER) ||
+      left.itemId.localeCompare(right.itemId, "en"),
+  )) {
+    const sequence = item.sourceRef.eventSequence ?? Number.MAX_SAFE_INTEGER;
+    while (
+      ephemeralIndex < ephemeralMessages.length &&
+      ephemeralMessages[ephemeralIndex].sequence <= sequence
+    )
+      restoredMessages.push(ephemeralMessages[ephemeralIndex++].message);
+    restoredMessages.push(...contextItemsToMessages([item]));
+  }
+  restoredMessages.push(
+    ...ephemeralMessages.slice(ephemeralIndex).map(({ message }) => message),
+  );
   return {
-    messages: outputMessages,
+    messages: restoredMessages,
     stats: {
       ...(summaryStats || {}),
       strategy:
         receipt.status === "degraded" ? "deterministic-fallback" : "canonical",
-      originalMessages: messages.length,
-      compressedMessages: outputMessages.length,
-      originalTokens: estimatedTokens(messages),
-      compressedTokens: estimatedTokens(outputMessages),
+      originalMessages: liveMessages.length,
+      compressedMessages: restoredMessages.length,
+      originalTokens: estimatedTokens(liveMessages),
+      compressedTokens: estimatedTokens(restoredMessages),
       saved: Math.max(
         0,
-        estimatedTokens(messages) - estimatedTokens(outputMessages),
+        estimatedTokens(liveMessages) - estimatedTokens(restoredMessages),
       ),
       canonicalAlreadySettled: true,
       canonicalReceipt: receipt,

package/src/lib/read-file-loop-guard.js

@@ -32,6 +32,79 @@ export class ReadFileLoopGuard {
     this.batch = null;
     this.largeOutputs = new Set();
     this.editRecoveryReads = new Map();
+    this.visiblePages = null;
+    this.visibleRequest = 0;
+  }
+
+  /** Observe only the request actually selected for the provider, not history. */
+  observeVisibleMessages(messages) {
+    this.visibleRequest++;
+    this.visiblePages = [];
+    const retain = (value) => {
+      if (
+        typeof value?.path !== "string" ||
+        typeof value.fileVersion !== "string"
+      )
+        return;
+      if (typeof value.content === "string" && !value.contentOmitted) {
+        this.visiblePages.push(value);
+      }
+      for (const excerpt of Array.isArray(value.excerpts)
+        ? value.excerpts
+        : []) {
+        if (typeof excerpt?.content === "string")
+          this.visiblePages.push({
+            ...excerpt,
+            path: value.path,
+            fileVersion: value.fileVersion,
+          });
+      }
+    };
+    const retainContext = (context) => {
+      if (
+        typeof context !== "string" ||
+        !context.startsWith("[File excerpts retained across compaction")
+      )
+        return;
+      try {
+        const entries = JSON.parse(context.slice(context.indexOf("\n") + 1));
+        if (Array.isArray(entries)) entries.forEach(retain);
+      } catch {
+        /* A truncated hint provides no confirmed source evidence. */
+      }
+    };
+    for (const message of messages || []) {
+      if (message.role === "assistant") retainContext(message.content);
+      if (message.role !== "tool") continue;
+      let value;
+      try {
+        value =
+          typeof message.content === "string"
+            ? JSON.parse(message.content.split("\n\n[Budget ")[0])
+            : message.content;
+      } catch {
+        continue;
+      }
+      retain(value);
+      for (const context of Array.isArray(value?.retainedReadContext)
+        ? value.retainedReadContext
+        : []) {
+        retainContext(context);
+      }
+    }
+  }
+
+  isPageVisible(page) {
+    return (
+      this.visiblePages?.some(
+        (visible) =>
+          keyFor(visible.path, {}) === keyFor(page.path, {}) &&
+          visible.fileVersion === page.fileVersion &&
+          typeof page.content === "string" &&
+          page.content.length > 0 &&
+          visible.content.includes(page.content),
+      ) === true
+    );
   }
 
   recordEditRecovery(result) {
@@ -94,6 +167,7 @@ export class ReadFileLoopGuard {
         rereads: new Set(),
         summary: null,
         excerpts: [],
+        contextRestoreOffered: false,
       };
     }
     let page = readPage(args);
@@ -108,11 +182,11 @@ export class ReadFileLoopGuard {
         readProgress: { newContent: false },
       };
     }
-    const span = page.readSpan;
+    let span = page.readSpan;
     const covered = entry.spans.some(
       ([start, end]) => start <= span.start && end >= span.end,
     );
-    const targeted =
+    let targeted =
       Number(args.offset) > 0 &&
       Number(args.limit) > 0 &&
       Number(args.limit) <= 200 &&
@@ -122,20 +196,52 @@ export class ReadFileLoopGuard {
     );
     let newContent = !covered;
     const hadOutline = !!entry.summary?.outline;
+    // A planner can evict a read without compacting the transcript. Give one
+    // bounded landing page for that version, then require explicit ranges.
+    // Dropping the same evidence repeatedly must not reopen full-file scans.
+    if (
+      covered &&
+      entry.summary?.reachedEnd === true &&
+      !targeted &&
+      this.visiblePages !== null &&
+      entry.lastReadRequest < this.visibleRequest &&
+      !this.isPageVisible(page) &&
+      !entry.contextRestoreOffered &&
+      entry.rereads.size < 3
+    ) {
+      const offset =
+        Number.isSafeInteger(Number(args.offset)) && Number(args.offset) > 0
+          ? Number(args.offset)
+          : 1;
+      const bounded = readPage({ ...args, offset, limit: 80 });
+      if (!bounded.error && bounded.readSpan && !this.isPageVisible(bounded)) {
+        page = bounded;
+        span = page.readSpan;
+        targeted = true;
+        entry.contextRestoreOffered = true;
+      }
+    }
     if (covered || (coveredPrefix && !targeted)) {
       // Permit a bounded, explicit reread for editing or lost context. Broad
       // rescans and subsequent repeats recover automatically, including when
       // the model varies offset/limit inside an already covered region.
-      const fingerprint = createHash("sha256")
-        .update(JSON.stringify(span))
-        .digest("hex");
+      const restoring =
+        this.visiblePages !== null &&
+        entry.lastReadRequest < this.visibleRequest &&
+        !this.isPageVisible(page);
+      const fingerprint =
+        (restoring ? "restore:" : "review:") +
+        createHash("sha256").update(JSON.stringify(span)).digest("hex");
       if (
         targeted &&
         !entry.rereads.has(fingerprint) &&
         entry.rereads.size < 3
       ) {
         entry.rereads.add(fingerprint);
-        page.readRecovery = { action: "targeted-review" };
+        page.readRecovery = {
+          action: restoring ? "context-restore" : "targeted-review",
+        };
+        if (restoring) page.readRecovery.fileVersion = fileVersion;
       } else {
         const unread = entry.spans[0]?.[0] === 0 ? entry.spans[0][1] : 0;
         if (unread < span.total) {
@@ -162,12 +268,20 @@ export class ReadFileLoopGuard {
             ...(entry.summary?.outline
               ? { outline: entry.summary.outline }
               : {}),
-            hint: "The entire unchanged file has already been read during this run. Do not restart the scan. Use the retained outline/findings to perform the user's task; use search_files and a small explicit offset/limit only for missing details. Reading the file is not task completion.",
+            recoveryRead: {
+              path: filePath,
+              offset: 1,
+              limit: 80,
+              ...(args.hashed === true ? { hashed: true } : {}),
+              ...(args.raw === true ? { raw: true } : {}),
+            },
+            hint: "The unchanged file was read earlier, but historical coverage does not mean its source is visible now. Use any source excerpts actually present in this request. For missing details, use search_files or read_file with a specific offset and limit (at most 80 lines); recoveryRead is a bounded starting range, not permission to restart a full scan. Reading the file is not task completion.",
           };
         }
       }
     }
     entry.spans = mergeSpan(entry.spans, page.readSpan);
+    entry.lastReadRequest = this.visibleRequest;
     // Coverage alone cannot restore source code after compaction. Keep bounded
     // observed pages for every file type, not only large Markdown outlines.
     // Label truncation explicitly; a retained prefix is not the whole range.
@@ -232,6 +346,8 @@ export class ReadFileLoopGuard {
     if (tool === "read_file") {
       if (result?.readRecovery?.action === "edit-anchor-refresh")
         this.batch.advanced = true;
+      if (result?.readRecovery?.action === "context-restore")
+        this.batch.advanced = true;
       if (result?.readProgress?.newContent === true) this.batch.advanced = true;
       if (result?.readProgress?.newContent === false) this.batch.duplicates++;
     } else if (
@@ -308,7 +424,7 @@ export class ReadFileLoopGuard {
 
   get recoveryHint() {
     return this.repeatedBatches >= 1
-      ? "Repeated file reads or identical large command outputs detected. Do not switch to run_code/run_shell to dump the same file again. Filter/count locally and print only relevant rows, totals and source line numbers, or use a focused search. The runtime continues unfinished read_file scans automatically and returns use-findings after EOF. Use the retained outline to perform the user's task. Do not restart a whole-file scan after context compaction; answer once the requested evidence is sufficient."
+      ? "Repeated file reads or identical large command outputs detected. Do not switch to run_code/run_shell to dump the same file again. Filter/count locally and print only relevant rows, totals and source line numbers, or use a focused search. The runtime continues unfinished read_file scans automatically and returns use-findings after EOF. Use source evidence actually visible in this request; recover missing details with a specific offset and limit of at most 80 lines. Do not restart a whole-file scan after context compaction; answer once the requested evidence is sufficient."
       : null;
   }