pi-fovea 0.22.2 → 0.24.0

package/README.md

@@ -58,7 +58,7 @@ and test commands in your loop. CI has the final say.
 | `fovea_sketch` | where is everything? | production-first silhouette plus explicit discovery/extraction coverage; test and fixture architecture stays collapsed |
 | `fovea_focus` | what is this? | exact symbols/routes/protocol ids, evidenced relationships, path-gap reasons, suggested reads, scopes, and deterministic `fresh` views |
 | `fovea_dwell` | what else? | widens the current focus, or expires safely when its graph generation changed |
-| `fovea_impact` | what does this touch? | hunk-precise seeds, evidenced review paths, unmet co-change companions, and a persistent obligation checklist |
+| `fovea_impact` | what does this touch? | hunk-precise seeds, evidenced review paths, unmet co-change companions, and bounded, revision-aware review memory |
 | `grep` *(default hybrid)* | graph or text? | bare identifiers, qualified symbols, repo paths, and routes use Fovea; search options and obvious regex retain native grep |
 
 Focus normalizes camelCase and common inflections. An approximate name such as
@@ -303,47 +303,29 @@ environment override still turns sync off with:
 FOVEA_TURN_SYNC=off pi
 ```
 
-## Salience and obligations
-
-`fovea_impact` keeps two clocks on the same graph.
-
-Heat finds what matters now. Seeds come from the diff. Hunk parsing maps each
-change to the symbols that contain it. One unit of mass goes to each changed
-file: `0.2` on the file node, `0.8` over the touched symbols in proportion to
-`sqrt(changed lines)`. Heat then spreads along static edges and along co-change
-partners, and decays with wall-clock time. Edits that resist symbol-level
-location fall back to the old file-node seed. New files, deletions, renames,
-untracked paths, and oversized diffs all take that path.
-
-Historical co-change is a decaying **heat prior**, never a permanent graph edge.
-It counts up to 400 first-parent integration boundaries: merge net changes count
-once, not again through their constituent commits. Explicit `fixup!`/`squash!`
-followups join only uniquely resolved older subjects in that window. Time,
-author, shared issue numbers, and unlabeled "forgot this" do not group work.
-Boundaries are not proof of a semantic feature (release merges can mix work).
-Aggregates above 24 tracked files emit no pairs but retain directional touch
-counts; two distinct retained units are needed for a pair, three for expectations.
-Raw history caching includes shallow-state identity; recency still applies at use.
-Focus, sketch, and the structural diffusion operator remain unchanged.
-
-The obligation ledger keeps the list. Every cascade merges its per-file
-residual mass into a session epoch. Entries stay until evidence moves them. A
-read marks `inspected`. An edit marks `changed` and raises the generation. A
-verified run marks `verified`. A reset clears the epoch. Wall-clock time
-touches nothing here, and disclosure removes nothing. A model that saw a file
-still owes the work the ledger records.
-
-Impact details carry three separate signals:
-
-- `expectedButUnchanged`: files with strong directional co-change history that
-stayed out of this diff. A Wilson lower bound drives the score, with lift,
-support, and recency gates. Treat it as the alarm for the serializer nobody
-edited.
-- `conservedMass`: the same cascade under degree-corrected random-walk heat.
-Total mass stays fixed per connected component, so file masses compare across
-repos of different sizes. Sync gates stay on the older raw scale.
-- `obligations` and `epoch`: the strongest unresolved entries with their
-reasons and generations, plus epoch totals.
+## Salience and review memory
+
+`fovea_impact` separates current salience from remembered source exposure.
+
+Heat finds what matters now. Seeds come from the diff. Hunk parsing maps each change to the symbols that contain it. One unit of mass goes to each changed file: `0.2` on the file node, `0.8` over the touched symbols in proportion to `sqrt(changed lines)`. Heat then spreads along static edges and along co-change partners, and decays with wall-clock time. Edits that resist symbol-level location fall back to the old file-node seed. New files, deletions, renames, untracked paths, and oversized diffs all take that path.
+
+Historical co-change is a decaying **heat prior**, never a permanent graph edge. It counts up to 400 first-parent integration boundaries: merge net changes count once, not again through their constituent commits. Explicit `fixup!`/`squash!` followups join only uniquely resolved older subjects in that window. Time, author, shared issue numbers, and unlabeled "forgot this" do not group work. Boundaries are not proof of a semantic feature (release merges can mix work). Aggregates above 24 tracked files emit no pairs but retain directional touch counts; two distinct retained units are needed for a pair, three for expectations. Raw history caching includes shallow-state identity; recency still applies at use. Focus, sketch, and the structural diffusion operator remain unchanged.
+
+Review memory is **hysteretic**, not conserved work: like a resettable thermal history indicator, its state remembers an earlier event after the heat changes. Each suggested file has independent current `salience` and exposure state: `unseen`, `seen`, or `stale`. Repeated impact calls replace salience rather than accumulating invocation-count debt. Cooling and disclosure do not acknowledge a read. This memory neither proves correctness nor gates completion or starts turns.
+
+A successful local `read` records only returned source windows at a content SHA-1. `seen` means source exposure, not whole-file inspection or understanding. The host checks matching text and stable before/after snapshots; requested limits are not treated as returned lines. Failed, diagnostic-only, rewritten, or racing reads earn no acknowledgment. Snapshot capture is bounded to 1 MiB per retained file, with at most 16 merged windows per revision (`windowsOmitted` reports loss). Reads before a file enters review memory are not tracked. Thus `unread` means **no matching read observed while retained**, not proof that nobody read it.
+
+A changed content hash makes previous exposure `stale`, including comment-only, shell, Fabric, and editor changes when the graph next refreshes. Reverting a file does not erase the stale marker; another matching read does. This is file-local exposure history, not a sound dependency-based verification system. Semantic surprise and turn steering retain their existing separate rules.
+
+Memory holds at most 512 files, preferring current salience. `evicted` counts retained entries actually forgotten; `omitted` counts new candidates not retained in the latest cascade. Repeated omitted candidates do not accumulate debt. A disjoint seed set starts a new review epoch and reports the discarded totals as `review.previous`; overlapping/growing changes retain their epoch. Reset, reload, and session replacement clear this advisory memory rather than persist it.
+
+Impact details carry three distinct signals:
+
+- `expectedButUnchanged`: likely missing companions inferred from directional co-change history. These are review suggestions, not required edits.
+- `conservedMass`: degree-corrected random-walk heat; mathematical conservation of diffusion mass is unrelated to review accounting. Sync keeps its raw scale.
+- `review`: retained entries with salience, reasons, revision, exposure windows, `unseen`/`seen`/`stale` totals, epoch, and retention-loss information. This replaces the former `obligations` and top-level `epoch` fields; the verification transition has been removed rather than relabeled.
+
+The budgeted trailer says `review memory · 3 unread · 1 stale · 2 seen (windows only)` and names the strongest pending suggestions. Evictions and prior-epoch loss appear there when budget permits and always in structured details. Cold pending entries remain accessible in the full impact overflow list. Zero unread or stale entries means no pending *retained review suggestions*, never feature completion. The CLI has no host read events; inspection tracking belongs to the in-session extension.
 
 `docs/heat-diffusion.md` has the full mechanics.
 

package/dist/cli.mjs

@@ -377,13 +377,13 @@ var buildCsr = (g) => {
     pairs.push([a, b, w2]);
   }
   pairs.sort((x, y) => x[0] - y[0]);
-  const counts = new Uint32Array(n);
+  const counts2 = new Uint32Array(n);
   for (const [a, b] of pairs) {
-    counts[a]++;
-    counts[b]++;
+    counts2[a]++;
+    counts2[b]++;
   }
   const rowPtr = new Uint32Array(n + 1);
-  for (let i = 0; i < n; i++) rowPtr[i + 1] = rowPtr[i] + counts[i];
+  for (let i = 0; i < n; i++) rowPtr[i + 1] = rowPtr[i] + counts2[i];
   const col = new Uint32Array(rowPtr[n]);
   const w = new Float64Array(rowPtr[n]);
   const cursor = new Uint32Array(n);
@@ -726,12 +726,13 @@ ${allItems.join("\n")}
 var revealGroups = (groups, opts) => {
   const ordered = [...groups].sort((a, b) => b.mass - a.mass || (a.label < b.label ? -1 : 1));
   const artifactNote = opts.overflowTo ? ` \u2014 full list saved to ${opts.overflowTo}` : "";
-  const renderK = (k, note = artifactNote) => {
+  const renderK = (k, note = artifactNote, tail = opts.trailer ? `
+${opts.trailer}` : "") => {
     const body = ordered.slice(0, k).map((gl) => `${gl.label.padEnd(2)} ${gl.detail}`);
     const rest = ordered.length - k;
     const footer = rest > 0 ? [`
 \u2026 ${rest} more groups omitted${note} \u2014 use fovea_focus for detail`] : [];
-    return [opts.header, ...body, ...footer].join("\n");
+    return [opts.header, ...body, ...footer].join("\n") + tail;
   };
   let hi = ordered.length;
   let kBest = ordered.length;
@@ -758,6 +759,7 @@ var revealGroups = (groups, opts) => {
       text = renderK(kBest, "");
     }
   }
+  if (opts.trailer && tokenEstimate(text) > opts.budget) text = renderK(kBest, artifactNote, "");
   return {
     text,
     tokens: tokenEstimate(text),
@@ -771,6 +773,83 @@ var revealGroups = (groups, opts) => {
 
 // src/core/session.ts
 import { isAbsolute, relative, resolve, sep } from "node:path";
+
+// src/core/review.ts
+var FILE_LIMIT = 512;
+var counts = (memory) => {
+  const result = {
+    total: memory?.entries.size ?? 0,
+    unseen: 0,
+    seen: 0,
+    stale: 0,
+    evicted: memory?.evicted ?? 0,
+    omitted: memory?.omitted ?? 0
+  };
+  for (const entry of memory?.entries.values() ?? []) result[entry.status]++;
+  return result;
+};
+var bySalience = (a, b) => b[1].salience - a[1].salience || a[0].localeCompare(b[0]);
+var observeReviewRevision = (memory, file, revision) => {
+  const entry = memory?.entries.get(file);
+  if (!entry || entry.revision === revision) return;
+  entry.revision = revision;
+  entry.status = entry.exposure ? "stale" : "unseen";
+};
+var updateReviewMemory = (session, seeds, samples) => {
+  const incoming = [...new Set(seeds)];
+  let memory = session.reviewMemory;
+  if (!memory || incoming.length && !incoming.some((file) => memory.seeds.has(file))) {
+    const previous = memory ? counts(memory) : void 0;
+    const epoch = (memory?.epoch ?? 0) + 1;
+    memory?.entries.clear();
+    memory = { epoch, seeds: new Set(incoming), entries: /* @__PURE__ */ new Map(), evicted: 0, omitted: 0, previous };
+    session.reviewMemory = memory;
+  }
+  const retained = new Set(memory.entries.keys());
+  for (const entry of memory.entries.values()) entry.salience = 0;
+  for (const [file, sample] of samples) {
+    if (!Number.isFinite(sample.salience) || sample.salience <= 0) continue;
+    let entry = memory.entries.get(file);
+    if (!entry) {
+      entry = { salience: 0, reasons: [], revision: sample.revision, status: "unseen" };
+      memory.entries.set(file, entry);
+    }
+    observeReviewRevision(memory, file, sample.revision);
+    entry.salience = sample.salience;
+    entry.reasons = [...new Set(sample.reasons)].sort();
+  }
+  memory.omitted = 0;
+  for (const [file] of [...memory.entries].sort(bySalience).slice(FILE_LIMIT)) {
+    memory.entries.delete(file);
+    if (retained.has(file)) memory.evicted++;
+    else memory.omitted++;
+  }
+  return memory;
+};
+var reviewReport = (memory) => ({
+  ...counts(memory),
+  epoch: memory?.epoch,
+  previous: memory?.previous ? { ...memory.previous } : void 0,
+  entries: [...memory?.entries ?? []].sort((a, b) => Number(a[1].status === "seen") - Number(b[1].status === "seen") || bySalience(a, b)).map(([file, entry]) => ({
+    ...entry,
+    file,
+    reasons: [...entry.reasons],
+    exposure: entry.exposure ? { ...entry.exposure, windows: entry.exposure.windows.map((w) => ({ ...w })) } : void 0
+  }))
+});
+var reviewTrailer = (report) => {
+  if (!report.total && !report.previous && !report.evicted && !report.omitted) return "";
+  const files = report.entries.filter((entry) => entry.status !== "seen").slice(0, 3).map((entry) => entry.file);
+  const notes = [
+    files.length ? files.join(", ") : "",
+    report.evicted ? `${report.evicted} entries evicted` : "",
+    report.omitted ? `${report.omitted} candidates not retained` : "",
+    report.previous ? `prior epoch cleared: ${report.previous.total} entries (${report.previous.unseen} unread, ${report.previous.stale} stale)` : ""
+  ].filter(Boolean);
+  return `review memory \xB7 ${report.unseen} unread \xB7 ${report.stale} stale \xB7 ${report.seen} seen (windows only)` + (notes.length ? ` \xB7 ${notes.join(" \xB7 ")}` : "");
+};
+
+// src/core/session.ts
 var FOCUS_T0 = 2;
 var TK_ORDER = 80;
 var sessions = /* @__PURE__ */ new Map();
@@ -795,7 +874,11 @@ var getSession = (root) => {
     tkKey: ""
   };
   sessions.set(root, s);
-  while (sessions.size > ROOT_CACHE_LIMIT) sessions.delete(sessions.keys().next().value);
+  while (sessions.size > ROOT_CACHE_LIMIT) {
+    const oldest = sessions.keys().next().value;
+    sessions.get(oldest)?.reviewMemory?.entries.clear();
+    sessions.delete(oldest);
+  }
   return s;
 };
 var repoRelativePath = (root, input) => {
@@ -818,6 +901,10 @@ var observeSessionPaths = (root, paths) => {
   }
   return [...session.syncScopes].sort();
 };
+var refreshSessionReviews = (root, revisionFor) => {
+  const memory = sessions.get(root)?.reviewMemory;
+  for (const file of memory?.entries.keys() ?? []) observeReviewRevision(memory, file, revisionFor(file));
+};
 var clearSessionFocus = (session) => {
   session.t = FOCUS_T0;
   session.seeds = [];
@@ -2199,92 +2286,6 @@ var groupPairs = (pairs, commits) => {
   return out;
 };
 
-// src/core/obligations.ts
-var LEDGER_LIMIT = 512;
-var seedFingerprint = (seedFiles) => {
-  const files = [...new Set(seedFiles)].sort();
-  let hash = 2166136261;
-  for (const file of files) {
-    for (let i = 0; i < file.length; i++) {
-      hash = Math.imul(hash ^ file.charCodeAt(i), 16777619);
-    }
-    hash = Math.imul(hash ^ 0, 16777619);
-  }
-  return (hash >>> 0).toString(36);
-};
-var nextEpochOrdinal = (session) => {
-  const encoded = session.obligationEpoch?.epochId.match(/^obligation-([0-9a-z]+)-/)?.[1];
-  const previous = encoded === void 0 ? 0 : Number.parseInt(encoded, 36);
-  return Number.isSafeInteger(previous) && previous >= 0 ? previous + 1 : 1;
-};
-var openEpoch = (session, seedFiles) => {
-  const ordinal = nextEpochOrdinal(session);
-  session.obligationEpoch?.ledger.clear();
-  const epoch = {
-    epochId: `obligation-${ordinal.toString(36)}-${seedFingerprint(seedFiles)}`,
-    ledger: /* @__PURE__ */ new Map()
-  };
-  session.obligationEpoch = epoch;
-  return epoch;
-};
-var activeEpoch = (session) => session.obligationEpoch ?? openEpoch(session, []);
-var enforceBound = (ledger) => {
-  if (ledger.size <= LEDGER_LIMIT) return;
-  const weakest = [...ledger.entries()].sort(
-    (a, b) => a[1].mass - b[1].mass || b[0].localeCompare(a[0])
-  );
-  for (let i = 0; i < weakest.length - LEDGER_LIMIT; i++) {
-    ledger.delete(weakest[i][0]);
-  }
-};
-var mergeWarmed = (session, fileMass, reason) => {
-  const ledger = activeEpoch(session).ledger;
-  for (const [file, mass] of fileMass) {
-    if (!Number.isFinite(mass) || mass <= 0) continue;
-    const entry = ledger.get(file);
-    if (entry) {
-      const sum = entry.mass + mass;
-      entry.mass = Number.isFinite(sum) ? sum : Number.MAX_VALUE;
-      if (reason && !entry.reasons.includes(reason)) entry.reasons.push(reason);
-      continue;
-    }
-    ledger.set(file, {
-      mass,
-      reasons: reason ? [reason] : [],
-      generation: 0,
-      status: "unresolved"
-    });
-  }
-  enforceBound(ledger);
-};
-var residual = (session) => {
-  const ledger = session.obligationEpoch?.ledger;
-  if (!ledger) return [];
-  return [...ledger.entries()].filter(([, entry]) => entry.status === "unresolved").sort((a, b) => b[1].mass - a[1].mass || a[0].localeCompare(b[0])).map(([file, entry]) => ({
-    file,
-    mass: entry.mass,
-    reasons: [...entry.reasons],
-    generation: entry.generation,
-    status: "unresolved"
-  }));
-};
-var epochStats = (session) => {
-  const stats = {
-    total: 0,
-    unresolved: 0,
-    inspected: 0,
-    changed: 0,
-    verified: 0,
-    mass: 0
-  };
-  for (const entry of session.obligationEpoch?.ledger.values() ?? []) {
-    stats.total++;
-    stats.mass += entry.mass;
-    stats[entry.status]++;
-  }
-  return stats;
-};
-
 // src/core/state.ts
 import { createHash as createHash4 } from "node:crypto";
 import { stat as stat2 } from "node:fs/promises";
@@ -4815,14 +4816,17 @@ var ensureState = (root, opts = {}) => {
   const pending = inflight.get(root);
   if (pending) return pending;
   const warm = touch(root);
-  const p = warm ? refreshState(warm, opts.hints, opts.force) : (async () => {
+  const p = (warm ? refreshState(warm, opts.hints, opts.force) : (async () => {
     const st = await stat2(root).catch(() => void 0);
     if (!st?.isDirectory()) throw new Error(`fovea: root does not exist or is not a directory: ${root}`);
     const state = await buildState(root);
     states.set(root, state);
     evictLru();
     return state;
-  })();
+  })()).then((state) => {
+    refreshSessionReviews(root, (file) => state.facts[file]?.sha1 ?? state.store.failedSha.get(file));
+    return state;
+  });
   inflight.set(root, p);
   const clear = () => {
     if (inflight.get(root) === p) inflight.delete(root);
@@ -5569,10 +5573,14 @@ var impact = async (root, args, ensured) => {
     const gaps = requestedCoverage.filter((entry) => entry.status !== "indexed").map((entry) => `
 ! ${entry.path ?? entry.requested}: ${entry.reason}.`).join("");
     const text = `fovea impact: no seed files (repo clean or paths unknown). Pass files: [...] or symbols: [...] for a what-if cascade.${gaps}`;
+    const session = getSession(root);
+    if (session.reviewMemory) updateReviewMemory(session, [], /* @__PURE__ */ new Map());
+    const review2 = reviewReport(session.reviewMemory);
+    const fit2 = revealGroups([], { header: text, budget: B, trailer: reviewTrailer(review2) });
     return {
-      text,
-      tokens: tokenEstimate(text),
-      details: { seeds: 0, requestedCoverage, ...extractionDetails(state) }
+      text: fit2.text,
+      tokens: fit2.tokens,
+      details: { seeds: 0, requestedCoverage, ...extractionDetails(state), review: review2 }
     };
   }
   const seeds = [...seedSet];
@@ -5710,10 +5718,18 @@ var impact = async (root, args, ensured) => {
     warmed.sort((a, b) => b[1].m - a[1].m);
     for (const [k, v] of warmed.slice(0, 2e3)) warmedNodes[k] = v;
   }
-  const foveaSession = getSession(root);
-  if (!foveaSession.obligationEpoch) openEpoch(foveaSession, seedFiles);
-  if (companionResiduals.size) mergeWarmed(foveaSession, companionResiduals, "unmet co-change companion");
-  if (fileAgg.size) mergeWarmed(foveaSession, fileAgg, "diffusion residual");
+  const samples = /* @__PURE__ */ new Map();
+  for (const file of /* @__PURE__ */ new Set([...fileAgg.keys(), ...companionResiduals.keys()])) {
+    samples.set(file, {
+      salience: Math.max(fileAgg.get(file) ?? 0, companionResiduals.get(file) ?? 0),
+      reasons: [
+        ...reasonByFile.get(file) ?? [],
+        ...companionResiduals.has(file) ? ["unmet co-change companion"] : []
+      ],
+      revision: state.facts[file]?.sha1 ?? state.store.failedSha?.get(file)
+    });
+  }
+  const review = reviewReport(updateReviewMemory(getSession(root), seedFiles, samples));
   const fileEntries = [...fileAgg.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
   const fileGroups = [];
   for (const [file, mass] of fileEntries) {
@@ -5725,12 +5741,15 @@ var impact = async (root, args, ensured) => {
       detail: `via ${reasons.join(", ")}${top ? ` \xB7 top: ${top}` : ""}`
     });
   }
-  const groups = [...anchorHits, ...fileGroups];
+  const remembered = review.entries.filter((entry) => entry.status !== "seen" && !fileAgg.has(entry.file)).map((entry) => ({ label: entry.file, mass: entry.salience, detail: `review memory: ${entry.status}` }));
+  const groups = [...anchorHits, ...fileGroups, ...remembered];
   const seedNames = seeds.slice(0, 5).map((i) => g.nodes[i].file).join(", ");
+  const trailer = reviewTrailer(review);
   const fit = revealGroups(groups, {
     header: `fovea impact \xB7 changed: ${seedNames}${seeds.length > 5 ? ", \u2026" : ""} \xB7 likely review order${extractionSuffix(state)}`,
     budget: B,
-    overflowTo: overflowArtifact("impact", `${root}|${(args.files ?? []).join(",")}`)
+    overflowTo: overflowArtifact("impact", `${root}|${(args.files ?? []).join(",")}`),
+    trailer
   });
   return {
     text: fit.text,
@@ -5738,7 +5757,7 @@ var impact = async (root, args, ensured) => {
     details: {
       seeds: seeds.length,
       historyPartners,
-      warmed: groups.length,
+      warmed: anchorHits.length + fileGroups.length,
       truncated: fit.truncated,
       requestedCoverage,
       ...extractionDetails(state),
@@ -5769,10 +5788,8 @@ var impact = async (root, args, ensured) => {
       conservedMass: Object.fromEntries(
         [...conservedByFile.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([file, mass]) => [file, Number(mass.toFixed(6))])
       ),
-      // Persistent obligation checklist: survives disclosure and wall-clock
-      // time; cleared only by evidence transitions or an epoch reset.
-      obligations: residual(foveaSession).slice(0, 10),
-      epoch: epochStats(foveaSession)
+      // Bounded exposure history, not a completion or verification ledger.
+      review
     }
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fovea",
-  "version": "0.22.2",
+  "version": "0.24.0",
   "description": "Token-budgeted repo mapping for agent sessions: foveated heat diffusion over a cross-language code graph, with progressive disclosure.",
   "type": "module",
   "license": "MIT",

package/skills/pi-fovea/SKILL.md

@@ -12,7 +12,7 @@ pi-fovea maintains a cross-language code graph of the working repository — rou
 1. **`fovea_sketch`** — production-first silhouette. Shipped routes and source regions lead; test and fixture architecture is collapsed. Start here in an unfamiliar repo. ~256–1024 tokens.
 2. **`fovea_focus` `<query>`** — point at a symbol name (close spellings work), route, env key, or file. The active seed and direct relationships always remain visible; previously seen periphery is suppressed only within that focus. A different focus resets to sharp context. Use `path`, `language`, or `kind` to scope output and `fresh: true` for a reproducible full view. Structured details include nodes and suggested read windows.
 3. **`fovea_dwell`** — optional second look. If focus says more results remain, dwell widens only the current focus and returns newly relevant neighbors.
-4. **`fovea_impact`**: blast radius. Seed with repo-relative `files`, symbols, uncommitted changes, or a PR `base`. Output is likely review order with causal channels (calls, imports, literals, routes, tests, inheritance, co-change). Structured details add `expectedButUnchanged` (co-coupled files missing from this diff), `conservedMass` (per-file heat that compares across repo sizes), and `obligations`/`epoch` (a checklist that survives disclosure and time). Check `obligations` before you call a feature done.
+4. **`fovea_impact`**: blast radius. Seed with repo-relative `files`, symbols, uncommitted changes, or a PR `base`. Output is likely review order with causal channels (calls, imports, literals, routes, tests, inheritance, co-change). Structured details add `expectedButUnchanged` (likely co-change companions, not required edits), `conservedMass` (comparable diffusion heat), and `review` (bounded, hysteretic source-exposure memory). The trailer reports unread/stale/seen suggestions, not unfinished obligations. Matching successful reads record returned windows at a content revision; later content drift makes that exposure stale. Repeated impact replaces salience rather than accumulating work. Eviction and disjoint-epoch loss are disclosed; reset/reload clears the memory. `seen` means only that source windows were returned, and zero pending suggestions never means the feature is complete. Keep tests and acceptance checks in the host workflow.
 
 All four accept `maxTokens` (256–16000). Budget is roughly 4 chars per token.
 

package/src/core/ops.ts

@@ -14,7 +14,7 @@ import { detectBasins } from "./basins.js";
 import { classifyLiteral, normalizeLiteral } from "./join.js";
 import { isTestFile } from "./extract.js";
 import { effectiveWeight, expectationResiduals, type CoChangeHistory } from "./cochange.js";
-import { epochStats, mergeWarmed, openEpoch, residual } from "./obligations.js";
+import { reviewReport, reviewTrailer, updateReviewMemory, type ReviewSample } from "./review.js";
 import type { EdgeEvidence, Graph, NodeKind, NodeRec } from "./types.js";
 import { ensureState, explainPathCoverage } from "./state.js";
 import type { RepoState } from "./state.js";
@@ -813,10 +813,14 @@ export const impact = async (root: string, args: ImpactArgs, ensured?: RepoState
       .map((entry) => `\n! ${entry.path ?? entry.requested}: ${entry.reason}.`)
       .join("");
     const text = `fovea impact: no seed files (repo clean or paths unknown). Pass files: [...] or symbols: [...] for a what-if cascade.${gaps}`;
+    const session = getSession(root);
+    if (session.reviewMemory) updateReviewMemory(session, [], new Map());
+    const review = reviewReport(session.reviewMemory);
+    const fit = revealGroups([], { header: text, budget: B, trailer: reviewTrailer(review) });
     return {
-      text,
-      tokens: tokenEstimate(text),
-      details: { seeds: 0, requestedCoverage, ...extractionDetails(state) },
+      text: fit.text,
+      tokens: fit.tokens,
+      details: { seeds: 0, requestedCoverage, ...extractionDetails(state), review },
     };
   }
   const seeds = [...seedSet];
@@ -1000,14 +1004,18 @@ export const impact = async (root: string, args: ImpactArgs, ensured?: RepoState
     for (const [k, v] of warmed.slice(0, 2000)) warmedNodes[k] = v;
   }
 
-  // Obligation ledger: merge this cascade's residual mass additively. Unlike
-  // novelty heat, entries persist until evidence transitions them (read/edit/
-  // verify) or the epoch resets — the conservation half of the
-  // salience/obligation split.
-  const foveaSession = getSession(root);
-  if (!foveaSession.obligationEpoch) openEpoch(foveaSession, seedFiles);
-  if (companionResiduals.size) mergeWarmed(foveaSession, companionResiduals, "unmet co-change companion");
-  if (fileAgg.size) mergeWarmed(foveaSession, fileAgg, "diffusion residual");
+  // Current salience ranks; hysteretic exposure survives cooling. Repeating
+  // this cascade cannot manufacture more work or certify its completion.
+  const samples = new Map<string, ReviewSample>();
+  for (const file of new Set([...fileAgg.keys(), ...companionResiduals.keys()])) {
+    samples.set(file, {
+      salience: Math.max(fileAgg.get(file) ?? 0, companionResiduals.get(file) ?? 0),
+      reasons: [...(reasonByFile.get(file) ?? []),
+        ...(companionResiduals.has(file) ? ["unmet co-change companion"] : [])],
+      revision: state.facts[file]?.sha1 ?? state.store.failedSha?.get(file),
+    });
+  }
+  const review = reviewReport(updateReviewMemory(getSession(root), seedFiles, samples));
 
   const fileEntries = [...fileAgg.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
   const fileGroups: GroupLine[] = [];
@@ -1024,12 +1032,17 @@ export const impact = async (root: string, args: ImpactArgs, ensured?: RepoState
       detail: `via ${reasons.join(", ")}${top ? ` · top: ${top}` : ""}`,
     });
   }
-  const groups: GroupLine[] = [...anchorHits, ...fileGroups];
+  // Retained cold suggestions remain reachable in the full overflow artifact.
+  const remembered = review.entries.filter((entry) => entry.status !== "seen" && !fileAgg.has(entry.file))
+    .map((entry) => ({ label: entry.file, mass: entry.salience, detail: `review memory: ${entry.status}` }));
+  const groups: GroupLine[] = [...anchorHits, ...fileGroups, ...remembered];
   const seedNames = seeds.slice(0, 5).map((i) => g.nodes[i]!.file).join(", ");
+  const trailer = reviewTrailer(review);
   const fit = revealGroups(groups, {
     header: `fovea impact · changed: ${seedNames}${seeds.length > 5 ? ", …" : ""} · likely review order${extractionSuffix(state)}`,
     budget: B,
     overflowTo: overflowArtifact("impact", `${root}|${(args.files ?? []).join(",")}`),
+    trailer,
   });
   return {
     text: fit.text,
@@ -1037,7 +1050,7 @@ export const impact = async (root: string, args: ImpactArgs, ensured?: RepoState
     details: {
       seeds: seeds.length,
       historyPartners,
-      warmed: groups.length,
+      warmed: anchorHits.length + fileGroups.length,
       truncated: fit.truncated,
       requestedCoverage,
       ...extractionDetails(state),
@@ -1073,10 +1086,8 @@ export const impact = async (root: string, args: ImpactArgs, ensured?: RepoState
           .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
           .map(([file, mass]) => [file, Number(mass.toFixed(6))]),
       ),
-      // Persistent obligation checklist: survives disclosure and wall-clock
-      // time; cleared only by evidence transitions or an epoch reset.
-      obligations: residual(foveaSession).slice(0, 10),
-      epoch: epochStats(foveaSession),
+      // Bounded exposure history, not a completion or verification ledger.
+      review,
     },
   };
 };

package/src/core/render.ts

@@ -300,15 +300,17 @@ export interface GroupLine { label: string; mass: number; detail: string; }
 
 export const revealGroups = (
   groups: GroupLine[],
-  opts: { header: string; budget: number; overflowTo?: string },
+  opts: { header: string; budget: number; overflowTo?: string; trailer?: string },
 ): FitResult => {
   const ordered = [...groups].sort((a, b) => b.mass - a.mass || (a.label < b.label ? -1 : 1));
   const artifactNote = opts.overflowTo ? ` — full list saved to ${opts.overflowTo}` : "";
-  const renderK = (k: number, note = artifactNote): string => {
+  // The trailer is constant across every candidate prefix, so the budget fit
+  // stays monotonic in k while still paying for its cost.
+  const renderK = (k: number, note = artifactNote, tail = opts.trailer ? `\n${opts.trailer}` : ""): string => {
     const body = ordered.slice(0, k).map((gl) => `${gl.label.padEnd(2)} ${gl.detail}`);
     const rest = ordered.length - k;
     const footer = rest > 0 ? [`\n… ${rest} more groups omitted${note} — use fovea_focus for detail`] : [];
-    return [opts.header, ...body, ...footer].join("\n");
+    return [opts.header, ...body, ...footer].join("\n") + tail;
   };
   let hi = ordered.length;
   let kBest = ordered.length;
@@ -335,6 +337,9 @@ export const revealGroups = (
       text = renderK(kBest, "");
     }
   }
+  // The trailer is advisory; it never gets to break the hard budget a caller
+  // paid for, even when the header alone already exceeds it.
+  if (opts.trailer && tokenEstimate(text) > opts.budget) text = renderK(kBest, artifactNote, "");
   return {
     text,
     tokens: tokenEstimate(text),

package/src/core/review-read.ts

@@ -0,0 +1,66 @@
+// Best-effort local read exposure. Unknown/rewritten results remain unacknowledged.
+import { createHash } from "node:crypto";
+import { open } from "node:fs/promises";
+import { join } from "node:path";
+import { observeReviewRevision, recordReviewRead, type ReviewMemory } from "./review.js";
+
+// Keep snapshot work bounded even for a read of a giant or growing file.
+const MAX_BYTES = 1024 * 1024;
+const snapshot = async (path: string): Promise<{ revision: string; text: string } | undefined> => {
+  const handle = await open(path, "r").catch(() => undefined);
+  if (!handle) return;
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size > MAX_BYTES) return;
+    const bytes = Buffer.alloc(Math.min(stat.size + 1, MAX_BYTES + 1));
+    let size = 0;
+    while (size < bytes.length) {
+      const read = await handle.read(bytes, size, bytes.length - size, size);
+      if (!read.bytesRead) break;
+      size += read.bytesRead;
+    }
+    if (size > stat.size || size > MAX_BYTES) return;
+    const content = bytes.subarray(0, size);
+    return { revision: createHash("sha1").update(content).digest("hex"), text: content.toString("utf8") };
+  } catch {
+    return undefined;
+  } finally {
+    await handle.close();
+  }
+};
+
+export const captureReviewRead = async (
+  memory: ReviewMemory | undefined, root: string, file: string, args: { offset?: unknown; limit?: unknown },
+) => {
+  const entry = memory?.entries.get(file);
+  if (!memory || !entry) return;
+  const start = args.offset === undefined ? 1 : args.offset;
+  const limit = args.limit;
+  if (typeof start !== "number" || !Number.isSafeInteger(start) || start < 1 ||
+    (limit !== undefined && (typeof limit !== "number" || !Number.isSafeInteger(limit) || limit < 1))) return;
+  const before = await snapshot(join(root, file));
+  if (!before || memory.entries.get(file) !== entry) return;
+  return { memory, entry, root, file, start, limit: limit as number | undefined, before };
+};
+
+export const finishReviewRead = async (
+  capture: NonNullable<Awaited<ReturnType<typeof captureReviewRead>>>, result: unknown,
+): Promise<void> => {
+  const { memory, entry, root, file, before, start, limit } = capture;
+  if (memory.entries.get(file) !== entry) return;
+  const after = await snapshot(join(root, file));
+  if (memory.entries.get(file) !== entry) return;
+  observeReviewRevision(memory, file, after?.revision);
+  if (!after || after.revision !== before.revision) return;
+  const content = (result as { content?: Array<{ type?: string; text?: string }> } | undefined)?.content;
+  if (!Array.isArray(content) || content.length !== 1 || content[0]?.type !== "text" || typeof content[0].text !== "string") return;
+  // Native read appends either a user-limit notice or a byte/line truncation
+  // notice. Compare the actual returned source prefix, never the requested limit.
+  const body = content[0].text.replace(/\n\n\[(?:\d+ more lines in file\. Use offset=\d+ to continue\.|Showing lines \d+-\d+ of \d+(?: \([^\n]*\))?\. Use offset=\d+ to continue\.)\]$/, "");
+  if (!body.length) return;
+  const lines = body.split("\n").length;
+  if (limit !== undefined && lines > limit) return;
+  const source = before.text.split("\n");
+  if (start + lines - 1 > source.length || source.slice(start - 1, start - 1 + lines).join("\n") !== body) return;
+  recordReviewRead(memory, file, after.revision, { start, end: start + lines - 1 });
+};

package/src/core/review.ts

@@ -0,0 +1,136 @@
+// Hysteretic review memory: salience changes with each cascade, while exposure
+// survives cooling. This is bounded navigation memory, never completion evidence.
+import type { FoveaSession } from "./session.js";
+
+interface ReadWindow { start: number; end: number }
+interface Exposure {
+  revision: string;
+  windows: ReadWindow[];
+  windowsOmitted: boolean;
+}
+interface ReviewEntry {
+  salience: number;
+  reasons: string[];
+  revision: string | undefined;
+  status: "unseen" | "seen" | "stale";
+  exposure?: Exposure;
+}
+interface ReviewCounts {
+  total: number;
+  unseen: number;
+  seen: number;
+  stale: number;
+  evicted: number;
+  omitted: number;
+}
+export interface ReviewMemory {
+  epoch: number;
+  seeds: Set<string>;
+  entries: Map<string, ReviewEntry>;
+  evicted: number;
+  omitted: number;
+  previous?: ReviewCounts;
+}
+export interface ReviewSample {
+  salience: number;
+  reasons: string[];
+  revision: string | undefined;
+}
+const FILE_LIMIT = 512;
+const WINDOW_LIMIT = 16;
+const counts = (memory?: ReviewMemory): ReviewCounts => {
+  const result = { total: memory?.entries.size ?? 0, unseen: 0, seen: 0, stale: 0,
+    evicted: memory?.evicted ?? 0, omitted: memory?.omitted ?? 0 };
+  for (const entry of memory?.entries.values() ?? []) result[entry.status]++;
+  return result;
+};
+const bySalience = (a: [string, ReviewEntry], b: [string, ReviewEntry]): number =>
+  b[1].salience - a[1].salience || a[0].localeCompare(b[0]);
+
+/** A changed or unavailable source makes previous exposure stale, even on revert. */
+export const observeReviewRevision = (memory: ReviewMemory | undefined, file: string, revision: string | undefined): void => {
+  const entry = memory?.entries.get(file);
+  if (!entry || entry.revision === revision) return;
+  entry.revision = revision;
+  entry.status = entry.exposure ? "stale" : "unseen";
+};
+
+/** Replace current salience, never accumulate invocation-count debt. */
+export const updateReviewMemory = (
+  session: FoveaSession,
+  seeds: Iterable<string>,
+  samples: ReadonlyMap<string, ReviewSample>,
+): ReviewMemory => {
+  const incoming = [...new Set(seeds)];
+  let memory = session.reviewMemory;
+  if (!memory || (incoming.length && !incoming.some((file) => memory!.seeds.has(file)))) {
+    const previous = memory ? counts(memory) : undefined;
+    const epoch = (memory?.epoch ?? 0) + 1;
+    memory?.entries.clear();
+    memory = { epoch, seeds: new Set(incoming), entries: new Map(), evicted: 0, omitted: 0, previous };
+    session.reviewMemory = memory;
+  }
+  const retained = new Set(memory.entries.keys());
+  for (const entry of memory.entries.values()) entry.salience = 0;
+  for (const [file, sample] of samples) {
+    if (!Number.isFinite(sample.salience) || sample.salience <= 0) continue;
+    let entry = memory.entries.get(file);
+    if (!entry) {
+      entry = { salience: 0, reasons: [], revision: sample.revision, status: "unseen" };
+      memory.entries.set(file, entry);
+    }
+    observeReviewRevision(memory, file, sample.revision);
+    entry.salience = sample.salience;
+    entry.reasons = [...new Set(sample.reasons)].sort();
+  }
+  memory.omitted = 0;
+  for (const [file] of [...memory.entries].sort(bySalience).slice(FILE_LIMIT)) {
+    memory.entries.delete(file);
+    if (retained.has(file)) memory.evicted++;
+    else memory.omitted++;
+  }
+  return memory;
+};
+
+/** Record returned source lines, not whole-file inspection or understanding. */
+export const recordReviewRead = (memory: ReviewMemory, file: string, revision: string, window: ReadWindow): void => {
+  const entry = memory.entries.get(file);
+  if (!entry || !revision || !Number.isSafeInteger(window.start) || !Number.isSafeInteger(window.end) ||
+    window.start < 1 || window.end < window.start) return;
+  observeReviewRevision(memory, file, revision);
+  const previous = entry.exposure?.revision === revision ? entry.exposure : undefined;
+  const windows = [...(previous?.windows ?? []), { ...window }].sort((a, b) => a.start - b.start || a.end - b.end);
+  const merged: ReadWindow[] = [];
+  for (const next of windows) {
+    const last = merged[merged.length - 1];
+    if (last && next.start <= last.end + 1) last.end = Math.max(last.end, next.end);
+    else merged.push({ ...next });
+  }
+  entry.exposure = { revision, windows: merged.slice(0, WINDOW_LIMIT),
+    windowsOmitted: !!previous?.windowsOmitted || merged.length > WINDOW_LIMIT };
+  entry.status = "seen";
+};
+
+/** Snapshot all retained entries, pending first. Presentation never consumes them. */
+export const reviewReport = (memory?: ReviewMemory) => ({
+  ...counts(memory),
+  epoch: memory?.epoch,
+  previous: memory?.previous ? { ...memory.previous } : undefined,
+  entries: [...(memory?.entries ?? [])]
+    .sort((a, b) => Number(a[1].status === "seen") - Number(b[1].status === "seen") || bySalience(a, b))
+    .map(([file, entry]) => ({ ...entry, file, reasons: [...entry.reasons],
+      exposure: entry.exposure ? { ...entry.exposure, windows: entry.exposure.windows.map((w) => ({ ...w })) } : undefined })),
+});
+
+export const reviewTrailer = (report: ReturnType<typeof reviewReport>): string => {
+  if (!report.total && !report.previous && !report.evicted && !report.omitted) return "";
+  const files = report.entries.filter((entry) => entry.status !== "seen").slice(0, 3).map((entry) => entry.file);
+  const notes = [
+    files.length ? files.join(", ") : "",
+    report.evicted ? `${report.evicted} entries evicted` : "",
+    report.omitted ? `${report.omitted} candidates not retained` : "",
+    report.previous ? `prior epoch cleared: ${report.previous.total} entries (${report.previous.unseen} unread, ${report.previous.stale} stale)` : "",
+  ].filter(Boolean);
+  return `review memory · ${report.unseen} unread · ${report.stale} stale · ${report.seen} seen (windows only)` +
+    (notes.length ? ` · ${notes.join(" · ")}` : "");
+};

package/src/core/session.ts

@@ -6,6 +6,7 @@
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { ROOT_CACHE_LIMIT } from "./asyncutil.js";
 import type { NodeKind } from "./types.js";
+import { observeReviewRevision, type ReviewMemory } from "./review.js";
 
 interface FocusScope {
   path?: string;
@@ -27,16 +28,8 @@ export interface FoveaSession {
   syncScopes: Set<string>;
   tk: Float64Array[];
   tkKey: string;
-  /** Persistent review obligations for the active change epoch. */
-  obligationEpoch?: {
-    epochId: string;
-    ledger: Map<string, {
-      mass: number;
-      reasons: string[];
-      generation: number;
-      status: "unresolved" | "inspected" | "changed" | "verified";
-    }>;
-  };
+  /** Bounded, advisory exposure history; independent of current salience. */
+  reviewMemory?: ReviewMemory;
 }
 
 export const FOCUS_T0 = 2;
@@ -65,7 +58,11 @@ export const getSession = (root: string): FoveaSession => {
     tkKey: "",
   };
   sessions.set(root, s);
-  while (sessions.size > ROOT_CACHE_LIMIT) sessions.delete(sessions.keys().next().value!);
+  while (sessions.size > ROOT_CACHE_LIMIT) {
+    const oldest = sessions.keys().next().value!;
+    sessions.get(oldest)?.reviewMemory?.entries.clear();
+    sessions.delete(oldest);
+  }
   return s;
 };
 
@@ -96,7 +93,13 @@ export const observeSessionPaths = (root: string, paths: readonly string[]): str
   return [...session.syncScopes].sort();
 };
 
-/** Drop index-addressed focus state while preserving attention and obligations. */
+/** Reconcile content drift regardless of mutation path, without enrolling a session. */
+export const refreshSessionReviews = (root: string, revisionFor: (file: string) => string | undefined): void => {
+  const memory = sessions.get(root)?.reviewMemory;
+  for (const file of memory?.entries.keys() ?? []) observeReviewRevision(memory, file, revisionFor(file));
+};
+
+/** Drop index-addressed focus state while preserving attention and review memory. */
 export const clearSessionFocus = (session: FoveaSession): void => {
   session.t = FOCUS_T0;
   session.seeds = [];
@@ -111,11 +114,10 @@ export const clearSessionFocus = (session: FoveaSession): void => {
 
 // `/new` and friends: same repo, fresh eyes.
 export const resetSessions = (): void => {
-  // Clear ledgers before dropping sessions so callers retaining an old session
-  // cannot keep querying obligations across a conversation reset.
+  // Retained captures cannot acknowledge reads across a conversation reset.
   for (const session of sessions.values()) {
-    session.obligationEpoch?.ledger.clear();
-    delete session.obligationEpoch;
+    session.reviewMemory?.entries.clear();
+    delete session.reviewMemory;
   }
   // A fresh conversation cannot reuse disclosure or Chebyshev vectors; drop
   // the entries outright so large Float64Array stacks become collectible.

package/src/core/state.ts

@@ -20,6 +20,7 @@ import { buildCsr, type Csr } from "./heat.js";
 import type { JoinIndex } from "./join.js";
 import { coChangeHistory, type CoChangeHistory } from "./cochange.js";
 import type { EdgeEvidence, Graph } from "./types.js";
+import { refreshSessionReviews } from "./session.js";
 
 export interface RepoState {
   root: string;
@@ -385,7 +386,7 @@ export const ensureState = (root: string, opts: { hints?: string[]; force?: bool
   const pending = inflight.get(root);
   if (pending) return pending;
   const warm = touch(root);
-  const p: Promise<RepoState> = warm
+  const p: Promise<RepoState> = (warm
     ? refreshState(warm, opts.hints, opts.force)
     : (async () => {
         const st = await stat(root).catch(() => undefined);
@@ -394,7 +395,12 @@ export const ensureState = (root: string, opts: { hints?: string[]; force?: bool
         states.set(root, state);
         evictLru();
         return state;
-      })();
+      })()).then((state) => {
+        // Even comment-only and out-of-band changes stale prior source exposure;
+        // this does not alter sync's semantic surprise gate or trigger turns.
+        refreshSessionReviews(root, (file) => state.facts[file]?.sha1 ?? state.store.failedSha.get(file));
+        return state;
+      });
   inflight.set(root, p);
   const clear = (): void => {
     if (inflight.get(root) === p) inflight.delete(root);

package/src/index.ts

@@ -13,7 +13,9 @@ import { loadFoveaConfig, type FoveaConfig } from "./core/config.js";
 import { hasAstGrep } from "./core/astgrep.js";
 import { ROOT_CACHE_LIMIT } from "./core/asyncutil.js";
 import { coverageSummary, dwell, ensureStateBackground, focus, impact, sketch } from "./core/ops.js";
-import { observeSessionPaths, resetSessions } from "./core/session.js";
+import { getSession, observeSessionPaths, resetSessions } from "./core/session.js";
+import { observeReviewRevision } from "./core/review.js";
+import { captureReviewRead, finishReviewRead } from "./core/review-read.js";
 import { captureMutation, finishMutation, type MutationCapture } from "./core/provenance.js";
 import { resetSyncBaselines, sync, syncBaselineStore, warmSync } from "./core/sync.js";
 import type { NodeKind } from "./core/types.js";
@@ -302,6 +304,9 @@ export default function fovea(pi: ExtensionAPI) {
   const WARM_DEBOUNCE_MS = 250;
   const warmTimers = new Map<string, ReturnType<typeof setTimeout>>();
   const pendingMutations = new Map<string, MutationCapture>();
+  // Capture a bounded source snapshot; only matching successful returned
+  // windows become exposure. Reads are not verification or completion.
+  const pendingReads = new Map<string, NonNullable<Awaited<ReturnType<typeof captureReviewRead>>>>();
   const warmAfterEdit = (root: string, cfg: FoveaConfig): void => {
     const rels = turnFiles
       .map((p) => (p.startsWith(root + "/") ? p.slice(root.length + 1) : p))
@@ -319,6 +324,7 @@ export default function fovea(pi: ExtensionAPI) {
     for (const timer of warmTimers.values()) clearTimeout(timer);
     warmTimers.clear();
     pendingMutations.clear();
+    pendingReads.clear();
     lifecycleEpoch++;
     turnFiles = [];
     lastSyncError = undefined;
@@ -330,10 +336,17 @@ export default function fovea(pi: ExtensionAPI) {
     turnFiles = [];
   });
   pi.on("tool_execution_start", async (event, ctx) => {
-    const args = event.args as { path?: unknown };
+    const args = event.args as { path?: unknown; offset?: unknown; limit?: unknown };
     if (ATTENTION_PATH_TOOLS.has(event.toolName) && typeof args.path === "string") {
       const owner = roots.owner(ctx.cwd, args.path);
-      if (owner) observeSessionPaths(owner.root, [owner.path]);
+      if (owner) {
+        observeSessionPaths(owner.root, [owner.path]);
+        if (event.toolName === "read") {
+          const epoch = lifecycleEpoch;
+          const capture = await captureReviewRead(getSession(owner.root).reviewMemory, owner.root, owner.path, args);
+          if (capture && epoch === lifecycleEpoch) pendingReads.set(event.toolCallId, capture);
+        }
+      }
     }
     if (event.toolName !== "edit" && event.toolName !== "write") return;
     if (typeof args.path !== "string") return;
@@ -346,10 +359,22 @@ export default function fovea(pi: ExtensionAPI) {
   // Warm once the file is actually on disk (tool_execution_start fires during
   // preflight, before the write lands); the debounce also coalesces bursts.
   pi.on("tool_execution_end", async (event, ctx) => {
+    const read = pendingReads.get(event.toolCallId);
+    if (read) {
+      pendingReads.delete(event.toolCallId);
+      if (!event.isError) await finishReviewRead(read, event.result);
+    }
     if (event.toolName !== "edit" && event.toolName !== "write") return;
     const capture = pendingMutations.get(event.toolCallId);
     pendingMutations.delete(event.toolCallId);
     if (!event.isError && capture) {
+      // No-op writes preserve exposure. Other paths are reconciled against
+      // content hashes on refresh, independently of semantic turn steering.
+      const memory = getSession(capture.root).reviewMemory;
+      if (memory?.entries.has(capture.file)) {
+        const after = await captureMutation(capture.root, capture.file);
+        if (capture.beforeSha !== after?.beforeSha) observeReviewRevision(memory, capture.file, after?.beforeSha);
+      }
       await finishMutation(capture, ctx.sessionManager.getSessionId(), event.toolCallId).catch(() => false);
     }
     if (capture) warmAfterEdit(capture.root, targetConfig(capture.root, ctx));
@@ -513,7 +538,7 @@ export default function fovea(pi: ExtensionAPI) {
     name: "fovea_impact",
     label: "Fovea Impact",
     description:
-      "Predict review order from changed files, symbols, or a PR base. Returns warmed files with causal channels, deterministic edge evidence paths, explicit input coverage gaps, co-change history, and obligations.",
+      "Predict review order from changed files, symbols, or a PR base. Returns warmed files with causal channels, deterministic edge evidence paths, explicit input coverage gaps, co-change history, and advisory unread/stale review memory (not completion evidence).",
     promptSnippet: "Predict the likely review surface of a change",
     promptGuidelines: ["Use fovea_impact before broad or risky edits and when checking the blast radius of completed changes."],
     parameters: Type.Object({
@@ -568,10 +593,11 @@ export default function fovea(pi: ExtensionAPI) {
         for (const timer of warmTimers.values()) clearTimeout(timer);
         warmTimers.clear();
         pendingMutations.clear();
+        pendingReads.clear();
         turnFiles = [];
         resetSessions();
         resetSyncBaselines();
-        ctx.ui.notify("Fovea focus history and sync baseline reset.", "info");
+        ctx.ui.notify("Fovea focus history, review memory, and sync baseline cleared.", "info");
         return;
       }
       if (sub === "settings") {

package/src/core/obligations.ts

@@ -1,163 +0,0 @@
-// Persistent review obligations are deliberately separate from sync's
-// wall-clock-decayed novelty heat. This module has no timers or IO: callers
-// drive every state transition explicitly on the active Fovea session.
-
-import type { FoveaSession } from "./session.js";
-
-type ObligationEpoch = NonNullable<FoveaSession["obligationEpoch"]>;
-type ObligationEntry = ObligationEpoch["ledger"] extends Map<string, infer Entry> ? Entry : never;
-
-type ResidualObligation = ObligationEntry & { file: string };
-type EpochStats = {
-  total: number;
-  unresolved: number;
-  inspected: number;
-  changed: number;
-  verified: number;
-  mass: number;
-};
-
-const LEDGER_LIMIT = 512;
-
-const seedFingerprint = (seedFiles: Iterable<string>): string => {
-  // Canonicalizing a copy freezes the epoch's seed baseline without retaining
-  // a second mutable collection alongside the prescribed ledger state.
-  const files = [...new Set(seedFiles)].sort();
-  let hash = 0x811c9dc5;
-  for (const file of files) {
-    for (let i = 0; i < file.length; i++) {
-      hash = Math.imul(hash ^ file.charCodeAt(i), 0x01000193);
-    }
-    hash = Math.imul(hash ^ 0, 0x01000193);
-  }
-  return (hash >>> 0).toString(36);
-};
-
-const nextEpochOrdinal = (session: FoveaSession): number => {
-  const encoded = session.obligationEpoch?.epochId.match(/^obligation-([0-9a-z]+)-/)?.[1];
-  const previous = encoded === undefined ? 0 : Number.parseInt(encoded, 36);
-  return Number.isSafeInteger(previous) && previous >= 0 ? previous + 1 : 1;
-};
-
-/** Start a fresh obligation epoch and discard every obligation from the old one. */
-export const openEpoch = (session: FoveaSession, seedFiles: Iterable<string>): ObligationEpoch => {
-  const ordinal = nextEpochOrdinal(session);
-  session.obligationEpoch?.ledger.clear();
-  const epoch: ObligationEpoch = {
-    epochId: `obligation-${ordinal.toString(36)}-${seedFingerprint(seedFiles)}`,
-    ledger: new Map(),
-  };
-  session.obligationEpoch = epoch;
-  return epoch;
-};
-
-const activeEpoch = (session: FoveaSession): ObligationEpoch =>
-  session.obligationEpoch ?? openEpoch(session, []);
-
-const enforceBound = (ledger: ObligationEpoch["ledger"]): void => {
-  if (ledger.size <= LEDGER_LIMIT) return;
-  // Keep the strongest obligations. Path order makes equal-mass eviction
-  // deterministic; lexically earlier paths survive a tie.
-  const weakest = [...ledger.entries()].sort(
-    (a, b) => a[1].mass - b[1].mass || b[0].localeCompare(a[0]),
-  );
-  for (let i = 0; i < weakest.length - LEDGER_LIMIT; i++) {
-    ledger.delete(weakest[i]![0]);
-  }
-};
-
-/** Add durable file-level warmth to the current epoch. Existing state is preserved. */
-export const mergeWarmed = (
-  session: FoveaSession,
-  fileMass: ReadonlyMap<string, number>,
-  reason: string,
-): void => {
-  const ledger = activeEpoch(session).ledger;
-  for (const [file, mass] of fileMass) {
-    // Heat mass is non-negative. Ignoring invalid input keeps a malformed
-    // producer from reducing or poisoning an already-durable obligation.
-    if (!Number.isFinite(mass) || mass <= 0) continue;
-    const entry = ledger.get(file);
-    if (entry) {
-      const sum = entry.mass + mass;
-      entry.mass = Number.isFinite(sum) ? sum : Number.MAX_VALUE;
-      if (reason && !entry.reasons.includes(reason)) entry.reasons.push(reason);
-      continue;
-    }
-    ledger.set(file, {
-      mass,
-      reasons: reason ? [reason] : [],
-      generation: 0,
-      status: "unresolved",
-    });
-  }
-  enforceBound(ledger);
-};
-
-/** Record that the latest generation was inspected; verification remains explicit. */
-export const markRead = (session: FoveaSession, files: Iterable<string>): void => {
-  const ledger = session.obligationEpoch?.ledger;
-  if (!ledger) return;
-  for (const file of files) {
-    const entry = ledger.get(file);
-    if (entry?.status === "unresolved" || entry?.status === "changed") {
-      entry.status = "inspected";
-    }
-  }
-};
-
-/** Record a new file generation. A subsequent read can inspect this generation again. */
-export const markEdited = (session: FoveaSession, files: Iterable<string>): void => {
-  const ledger = session.obligationEpoch?.ledger;
-  if (!ledger) return;
-  for (const file of files) {
-    const entry = ledger.get(file);
-    if (!entry) continue;
-    entry.generation++;
-    entry.status = "changed";
-  }
-};
-
-/** Mark obligations verified without deleting their epoch history. */
-export const markVerified = (session: FoveaSession, files: Iterable<string>): void => {
-  const ledger = session.obligationEpoch?.ledger;
-  if (!ledger) return;
-  for (const file of files) {
-    const entry = ledger.get(file);
-    if (entry) entry.status = "verified";
-  }
-};
-
-/** Return a non-consuming, strongest-first snapshot for the checklist renderer. */
-export const residual = (session: FoveaSession): ResidualObligation[] => {
-  const ledger = session.obligationEpoch?.ledger;
-  if (!ledger) return [];
-  return [...ledger.entries()]
-    .filter(([, entry]) => entry.status === "unresolved")
-    .sort((a, b) => b[1].mass - a[1].mass || a[0].localeCompare(b[0]))
-    .map(([file, entry]) => ({
-      file,
-      mass: entry.mass,
-      reasons: [...entry.reasons],
-      generation: entry.generation,
-      status: "unresolved",
-    }));
-};
-
-/** Summarize all retained entries and their total, non-decaying mass. */
-export const epochStats = (session: FoveaSession): EpochStats => {
-  const stats: EpochStats = {
-    total: 0,
-    unresolved: 0,
-    inspected: 0,
-    changed: 0,
-    verified: 0,
-    mass: 0,
-  };
-  for (const entry of session.obligationEpoch?.ledger.values() ?? []) {
-    stats.total++;
-    stats.mass += entry.mass;
-    stats[entry.status]++;
-  }
-  return stats;
-};