pi-fovea 0.22.2 → 0.23.0

package/README.md

@@ -328,11 +328,21 @@ 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
+successful `read` marks `inspected`; a landed `edit` or `write` marks
+`changed` and raises the generation, so a touched entry reopens until a later
+read inspects that generation. 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.
 
+The epoch follows the change. `fovea_impact` opens one on the first cascade and
+reuses it while the incoming seeds still share a file with it, so an
+uncommitted diff that keeps growing never loses its checklist. A diff that
+shares no seed with the active epoch is a different change, so the ledger
+rotates: the replacement starts empty and details report `epoch.rotated` with
+the `previous` totals, which keeps the discarded residual visible instead of
+dropping it silently. `markVerified` stays exported for callers that own a real
+verification signal; nothing here invents one.
+
 Impact details carry three separate signals:
 
 - `expectedButUnchanged`: files with strong directional co-change history that
@@ -343,7 +353,15 @@ edited.
 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.
+reasons and generations, plus epoch totals. A cascade that rotates the ledger
+adds `epoch.rotated` and `epoch.previous`.
+
+A model reads rendered text, not tool details, so `fovea_impact` also renders
+the convergence count as a one-line trailer — `obligations · 9 of 9 unresolved ·
+web/api.ts, server/main.go, openapi.yaml, …` — and drops it entirely once every
+entry is closed. Reads close entries, so the number only falls as work actually
+lands. The trailer is advisory: it never pushes a result past the budget it was
+called with.
 
 `docs/heat-diffusion.md` has the full mechanics.
 

package/dist/cli.mjs

@@ -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),
@@ -2219,9 +2221,11 @@ var nextEpochOrdinal = (session) => {
 };
 var openEpoch = (session, seedFiles) => {
   const ordinal = nextEpochOrdinal(session);
+  const seeds = new Set(seedFiles);
   session.obligationEpoch?.ledger.clear();
   const epoch = {
-    epochId: `obligation-${ordinal.toString(36)}-${seedFingerprint(seedFiles)}`,
+    epochId: `obligation-${ordinal.toString(36)}-${seedFingerprint(seeds)}`,
+    seeds,
     ledger: /* @__PURE__ */ new Map()
   };
   session.obligationEpoch = epoch;
@@ -2284,6 +2288,18 @@ var epochStats = (session) => {
   }
   return stats;
 };
+var ensureEpoch = (session, seedFiles) => {
+  const incoming = [...new Set(seedFiles)];
+  const current = session.obligationEpoch;
+  if (!current) {
+    openEpoch(session, incoming);
+    return { rotated: false };
+  }
+  if (!incoming.length || incoming.some((file) => current.seeds.has(file))) return { rotated: false };
+  const previous = epochStats(session);
+  openEpoch(session, incoming);
+  return { rotated: true, previous };
+};
 
 // src/core/state.ts
 import { createHash as createHash4 } from "node:crypto";
@@ -5711,9 +5727,11 @@ var impact = async (root, args, ensured) => {
     for (const [k, v] of warmed.slice(0, 2e3)) warmedNodes[k] = v;
   }
   const foveaSession = getSession(root);
-  if (!foveaSession.obligationEpoch) openEpoch(foveaSession, seedFiles);
+  const epochDecision = ensureEpoch(foveaSession, seedFiles);
   if (companionResiduals.size) mergeWarmed(foveaSession, companionResiduals, "unmet co-change companion");
   if (fileAgg.size) mergeWarmed(foveaSession, fileAgg, "diffusion residual");
+  const obligations = residual(foveaSession);
+  const epochTotals = epochStats(foveaSession);
   const fileEntries = [...fileAgg.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
   const fileGroups = [];
   for (const [file, mass] of fileEntries) {
@@ -5727,10 +5745,12 @@ var impact = async (root, args, ensured) => {
   }
   const groups = [...anchorHits, ...fileGroups];
   const seedNames = seeds.slice(0, 5).map((i) => g.nodes[i].file).join(", ");
+  const trailer = epochTotals.unresolved > 0 ? `obligations \xB7 ${epochTotals.unresolved} of ${epochTotals.total} unresolved \xB7 ${obligations.slice(0, 3).map((entry) => entry.file).join(", ")}${epochTotals.unresolved > 3 ? ", \u2026" : ""}` : "";
   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,
@@ -5771,8 +5791,8 @@ var impact = async (root, args, ensured) => {
       ),
       // 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)
+      obligations: obligations.slice(0, 10),
+      epoch: epochDecision.rotated ? { ...epochTotals, rotated: true, previous: epochDecision.previous } : epochTotals
     }
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fovea",
-  "version": "0.22.2",
+  "version": "0.23.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` (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). The rendered result carries that same checklist as a one-line trailer — `N of M unresolved` plus its strongest files. Reads close entries, edits reopen them, and a diff sharing no seed with the epoch rotates it; the count only falls when work actually lands, so check it before you call a feature done.
 
 All four accept `maxTokens` (256–16000). Budget is roughly 4 chars per token.
 

package/src/core/obligations.ts

@@ -8,7 +8,7 @@ type ObligationEpoch = NonNullable<FoveaSession["obligationEpoch"]>;
 type ObligationEntry = ObligationEpoch["ledger"] extends Map<string, infer Entry> ? Entry : never;
 
 type ResidualObligation = ObligationEntry & { file: string };
-type EpochStats = {
+export type EpochStats = {
   total: number;
   unresolved: number;
   inspected: number;
@@ -42,9 +42,13 @@ const nextEpochOrdinal = (session: FoveaSession): number => {
 /** 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);
+  // The seed baseline is copied rather than aliased: rotation compares against
+  // it long after the caller's diff has moved on.
+  const seeds = new Set(seedFiles);
   session.obligationEpoch?.ledger.clear();
   const epoch: ObligationEpoch = {
-    epochId: `obligation-${ordinal.toString(36)}-${seedFingerprint(seedFiles)}`,
+    epochId: `obligation-${ordinal.toString(36)}-${seedFingerprint(seeds)}`,
+    seeds,
     ledger: new Map(),
   };
   session.obligationEpoch = epoch;
@@ -161,3 +165,25 @@ export const epochStats = (session: FoveaSession): EpochStats => {
   }
   return stats;
 };
+
+export type EpochDecision =
+  | { rotated: false }
+  | { rotated: true; previous: EpochStats };
+
+/** Open the active epoch, or rotate it when the incoming change shares no seed
+ * with it. A diff that keeps growing retains every earlier seed, so work in
+ * flight never rotates; a diff sharing nothing is the structural signal that
+ * the change the ledger was tracking is no longer the one being worked on. A
+ * seedless cascade carries no evidence either way and never discards a ledger. */
+export const ensureEpoch = (session: FoveaSession, seedFiles: Iterable<string>): EpochDecision => {
+  const incoming = [...new Set(seedFiles)];
+  const current = session.obligationEpoch;
+  if (!current) {
+    openEpoch(session, incoming);
+    return { rotated: false };
+  }
+  if (!incoming.length || incoming.some((file) => current.seeds.has(file))) return { rotated: false };
+  const previous = epochStats(session);
+  openEpoch(session, incoming);
+  return { rotated: true, previous };
+};

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 { ensureEpoch, epochStats, mergeWarmed, residual } from "./obligations.js";
 import type { EdgeEvidence, Graph, NodeKind, NodeRec } from "./types.js";
 import { ensureState, explainPathCoverage } from "./state.js";
 import type { RepoState } from "./state.js";
@@ -1005,9 +1005,11 @@ export const impact = async (root: string, args: ImpactArgs, ensured?: RepoState
   // verify) or the epoch resets — the conservation half of the
   // salience/obligation split.
   const foveaSession = getSession(root);
-  if (!foveaSession.obligationEpoch) openEpoch(foveaSession, seedFiles);
+  const epochDecision = ensureEpoch(foveaSession, seedFiles);
   if (companionResiduals.size) mergeWarmed(foveaSession, companionResiduals, "unmet co-change companion");
   if (fileAgg.size) mergeWarmed(foveaSession, fileAgg, "diffusion residual");
+  const obligations = residual(foveaSession);
+  const epochTotals = epochStats(foveaSession);
 
   const fileEntries = [...fileAgg.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
   const fileGroups: GroupLine[] = [];
@@ -1026,10 +1028,19 @@ export const impact = async (root: string, args: ImpactArgs, ensured?: RepoState
   }
   const groups: GroupLine[] = [...anchorHits, ...fileGroups];
   const seedNames = seeds.slice(0, 5).map((i) => g.nodes[i]!.file).join(", ");
+  // The model reads rendered text, not details, so the one number that says
+  // whether the change is still closing out has to reach the result itself.
+  // Counts and file names only: the ledger is evidence, never a verdict on the
+  // hypothesis being pursued.
+  const trailer = epochTotals.unresolved > 0
+    ? `obligations · ${epochTotals.unresolved} of ${epochTotals.total} unresolved · ` +
+      `${obligations.slice(0, 3).map((entry) => entry.file).join(", ")}${epochTotals.unresolved > 3 ? ", …" : ""}`
+    : "";
   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,
@@ -1075,8 +1086,8 @@ export const impact = async (root: string, args: ImpactArgs, ensured?: RepoState
       ),
       // 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),
+      obligations: obligations.slice(0, 10),
+      epoch: epochDecision.rotated ? { ...epochTotals, rotated: true, previous: epochDecision.previous } : epochTotals,
     },
   };
 };

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/session.ts

@@ -30,6 +30,8 @@ export interface FoveaSession {
   /** Persistent review obligations for the active change epoch. */
   obligationEpoch?: {
     epochId: string;
+    /** Repo-relative files that opened the epoch; rotation keys on these. */
+    seeds: Set<string>;
     ledger: Map<string, {
       mass: number;
       reasons: string[];

package/src/index.ts

@@ -13,7 +13,8 @@ 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 { markEdited, markRead } from "./core/obligations.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 +303,10 @@ 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>();
+  // A read closes an obligation only once it succeeds, so the target is held
+  // from tool_execution_start (which carries args) to tool_execution_end
+  // (which carries only the result).
+  const pendingReads = new Map<string, { root: string; path: string }>();
   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;
@@ -333,7 +339,10 @@ export default function fovea(pi: ExtensionAPI) {
     const args = event.args as { path?: 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") pendingReads.set(event.toolCallId, owner);
+      }
     }
     if (event.toolName !== "edit" && event.toolName !== "write") return;
     if (typeof args.path !== "string") return;
@@ -346,10 +355,19 @@ 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);
+      // A failed read revealed nothing, so it cannot close an obligation.
+      if (!event.isError) markRead(getSession(read.root), [read.path]);
+    }
     if (event.toolName !== "edit" && event.toolName !== "write") return;
     const capture = pendingMutations.get(event.toolCallId);
     pendingMutations.delete(event.toolCallId);
     if (!event.isError && capture) {
+      // A landed write is a new file generation: the obligation returns to the
+      // checklist until a later successful read inspects that generation.
+      markEdited(getSession(capture.root), [capture.file]);
       await finishMutation(capture, ctx.sessionManager.getSessionId(), event.toolCallId).catch(() => false);
     }
     if (capture) warmAfterEdit(capture.root, targetConfig(capture.root, ctx));
@@ -568,6 +586,7 @@ export default function fovea(pi: ExtensionAPI) {
         for (const timer of warmTimers.values()) clearTimeout(timer);
         warmTimers.clear();
         pendingMutations.clear();
+        pendingReads.clear();
         turnFiles = [];
         resetSessions();
         resetSyncBaselines();