pi-supernova 0.0.8 → 0.0.15

package/host-bridge.js

@@ -8,9 +8,16 @@ import { unknownToolMessage } from "./catalog.js";
 import { extractStructuralSurface } from "./surface.js";
 import { buildEditDiff, buildMultiEditDiff, buildPatchDiff, buildWriteDiff } from "./diff.js";
 import { executeSnap } from "./snap.js";
+import { selectEvidence } from "./evidence.js";
+import { WorkspaceIndex } from "./repo-index.js";
+import { outlineFile } from "./outline.js";
+import { SeenLedger } from "./ledger.js";
+import { quickCheck } from "./check.js";
+import { declaredName } from "./repo-index.js";
 import { CausalVfs } from "./vfs.js";
 import { applyPatchToText } from "./patch.js";
-import { resolveWorkspacePath, runCommand } from "./workspace.js";
+import { resolveWorkspacePath, runCommand, clearPathCache, relativeSlash } from "./workspace.js";
+import { fuzzyFind, grepIndexed, listIndexed, listWithTools, rgGrepArgs } from "./search.js";
 
 function textResult(text, details) {
   return {
@@ -61,15 +68,6 @@ async function probeExistingFile(cwd, targetParam, vfs) {
   }
 }
 
-function patchModeOf(params) {
-  return (
-    isString(params?.patch) ||
-    (params?.newText === undefined &&
-      isString(params?.oldText) &&
-      (params.oldText.includes("@@ -") || params.oldText.startsWith("---")))
-  );
-}
-
 function applyReplacements(target, content, requestedEdits) {
   if (requestedEdits.length === 0) throw new Error("edit requires at least one replacement");
   const matches = requestedEdits.map((replacement) => {
@@ -113,7 +111,7 @@ async function formatLsEntry(dirPath, entry) {
   return `${entry.name}${isDir ? "/" : ""} (${typeLabel}${sizeSuffix})`;
 }
 
-function createNativeAdapters(getCwd, vfs, config) {
+function createNativeAdapters(getCwd, vfs, config, index, ledger) {
   async function readAdapter(params, signal) {
       const cwd = getCwd();
       const targetParam = params?.path ?? params?.target;
@@ -128,31 +126,153 @@ function createNativeAdapters(getCwd, vfs, config) {
 
       if (looksLikePath(targetParam)) {
         const targetPath = await resolveWorkspacePath(cwd, targetParam, "read", false);
-        const text = await vfs.read(targetPath);
-        return textResult(sliceLines(text, params?.offset, params?.limit), { path: targetPath });
+        return readFile(targetPath, params);
       }
 
       const existing = await probeExistingFile(cwd, targetParam, vfs);
-      if (existing) {
-        const text = await vfs.read(existing);
-        return textResult(sliceLines(text, params?.offset, params?.limit), { path: existing });
-      }
+      if (existing) return readFile(existing, params);
 
       if (isString(targetParam) && targetParam.trim()) {
         try {
           const snapRes = await executeSnap({
             query: targetParam,
             searchDir: cwd,
-            vfs,
-            runCommand: (argv, opts) => runCommand(argv, { cwd, signal, ...opts }),
+            index,
+            overlayText: (p) => vfs.getOverlay(p),
+            pendingPaths: vfs.getOverlayPaths(),
           });
           return textResult(JSON.stringify(snapRes, null, 2), { ...snapRes, isSnap: true });
         } catch {}
       }
 
       const targetPath = await resolveWorkspacePath(cwd, targetParam, "read", false);
-      const text = await vfs.read(targetPath);
-      return textResult(sliceLines(text, params?.offset, params?.limit), { path: targetPath });
+      return readFile(targetPath, params);
+  }
+
+  /** Plain text, a line window, or (with `about`) a relevance-folded outline of the whole file. */
+  async function readFile(targetPath, params) {
+    const cwd = getCwd();
+    const rel = relativeSlash(cwd, targetPath);
+    const text = await vfs.read(targetPath);
+    index.touch(rel);
+    if (isString(params?.about)) {
+      const pending = vfs.getOverlay(targetPath);
+      const entry = pending === undefined ? index.entry(targetPath) : WorkspaceIndex.fromText(targetPath, pending);
+      const outline = entry && outlineFile(entry, rel, params.about, outlineOptions(params, await referenceFinder(cwd, targetPath)));
+      if (outline) {
+        recordOutlineOrigins(rel, outline.text);
+        return textResult(outline.text, { path: targetPath, outline: true, expanded: outline.expanded, declarations: outline.declarations });
+      }
+    }
+    const explicit = isNumber(params?.offset) || isNumber(params?.limit);
+    const firstLine = isNumber(params?.offset) ? Math.max(1, Math.floor(params.offset)) : 1;
+    const sliced = sliceLines(text, params?.offset, params?.limit);
+    ledger.recordOrigin(rel, firstLine, sliced.split("\n"), explicit);
+    return textResult(sliced, { path: targetPath });
+  }
+
+  /**
+   * The edit result answers the follow-ups a model would otherwise spend turns on: the post-edit
+   * lines with numbers (so no verification re-read), a quick structural check, and every other
+   * place a changed declaration is referenced (so callers are not forgotten).
+   */
+  async function editSummary(cwd, target, original, updated, diff) {
+    const rel = relativeSlash(cwd, target);
+    const newLines = updated.split("\n");
+    const added = diff.lines.filter((l) => l.type === "add");
+    const first = added.length ? Math.max(1, added[0].lineNum - 2) : 1;
+    const last = added.length ? Math.min(newLines.length, added[added.length - 1].lineNum + 2) : Math.min(newLines.length, first + 6);
+    const window = [];
+    for (let l = first; l <= last && window.length < 40; l++) window.push(String(l).padStart(5) + " " + newLines[l - 1]);
+    ledger.recordOrigin(rel, first, newLines.slice(first - 1, first - 1 + window.length));
+    let out = `edited ${rel}:${first}–${first + window.length - 1}\n${window.join("\n")}`;
+    const check = quickCheck(updated, path.extname(target));
+    if (check && !check.ok) out += `\ncheck: ${check.message}`;
+    const refs = await changedDeclarationRefs(cwd, target, original, updated, diff);
+    if (refs) out += `\n${refs}`;
+    return out;
+  }
+
+  async function changedDeclarationRefs(cwd, target, original, updated, diff) {
+    // Diff rows carry the replaced fragments; declarations live on whole file lines.
+    const oldLines = original.split("\n");
+    const newLines = updated.split("\n");
+    const names = new Set();
+    for (const l of diff.lines) {
+      if (l.type === "context") continue;
+      const name = declaredName((l.type === "remove" ? oldLines : newLines)[l.lineNum - 1] ?? "");
+      if (name) names.add(name);
+    }
+    if (names.size === 0) return "";
+    const find = await referenceFinder(cwd, target);
+    const parts = [];
+    for (const name of [...names].slice(0, 3)) {
+      const refs = find(name).filter((r) => !r.startsWith(relativeSlash(cwd, target) + ":"));
+      if (refs.length) parts.push(`${name} also referenced in ${refs.slice(0, 6).join(", ")}${refs.length > 6 ? " (+" + (refs.length - 6) + ")" : ""}`);
+    }
+    return parts.join("\n");
+  }
+
+  const SOURCE_REF = /((?:[\w.@-]+\/)*[\w.@-]+\.(?:m?[jt]sx?|c[jt]s|py|rs|go|java|kt|rb|php|c|cc|cpp|h|hpp|cs|swift|json|ya?ml|toml))(?::|\()(\d+)/g;
+
+  /** Source window (±2 lines, ► on the cited line) for one path:line, or null when it is outside the workspace/index. */
+  function sourceWindow(cwd, file, lineNo) {
+    const candidate = path.resolve(cwd, file);
+    if (!candidate.startsWith(path.resolve(cwd) + path.sep)) return null;
+    const entry = index.entry(candidate);
+    if (!entry) return null;
+    const { raw } = WorkspaceIndex.linesOf(entry);
+    if (lineNo < 1 || lineNo > raw.length) return null;
+    const rel = relativeSlash(cwd, candidate);
+    const start = Math.max(1, lineNo - 2);
+    const rows = [];
+    for (let l = start; l <= Math.min(raw.length, lineNo + 2); l++) rows.push((l === lineNo ? "►" : " ") + String(l).padStart(4) + " " + raw[l - 1]);
+    ledger.recordOrigin(rel, start, rows);
+    return rel + ":" + lineNo + "\n" + rows.join("\n");
+  }
+
+  /** A failing command names path:line; the model wants those lines next. Attach them (≤4 sites). */
+  function sourceForReferences(cwd, output) {
+    const seen = new Set();
+    const blocks = [];
+    for (const m of output.matchAll(SOURCE_REF)) {
+      const key = m[1] + ":" + m[2];
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const block = sourceWindow(cwd, m[1], Number(m[2]));
+      if (block) blocks.push(block);
+      if (blocks.length >= 4) break;
+    }
+    return blocks.length ? "\n--- source\n" + blocks.join("\n") : "";
+  }
+
+  function outlineOptions(params, references) {
+    const options = { references };
+    if (params?.maxChars) options.maxChars = params.maxChars;
+    return options;
+  }
+
+  /** Outline lines carry their own line numbers ("  330 text"); provenance follows them. */
+  function recordOutlineOrigins(rel, outlineText) {
+    for (const line of outlineText.split("\n")) {
+      const m = /^\s*(\d+) (.*)$/.exec(line);
+      if (m && !/ … \d+ lines$/.test(line)) ledger.recordOrigin(rel, Number(m[1]), [line]);
+    }
+  }
+
+  /** Where else a name appears (declaration line excluded), for outlines and edit results. */
+  async function referenceFinder(cwd, targetPath) {
+    const files = await index.files(cwd);
+    if (!index.canScan(files)) return () => [];
+    return (name, excludeLine) => {
+      if (!name || name.length < 3) return [];
+      const escaped = name.replace(/[$]/g, (c) => "\\" + c);
+      const regex = new RegExp("\\b" + escaped + "\\b");
+      return index
+        .grepRows(files, regex, cwd)
+        .filter((r) => !(r.line === excludeLine && r.rel === relativeSlash(cwd, targetPath)))
+        .map((r) => r.rel + ":" + r.line);
+    };
   }
 
   return {
@@ -167,6 +287,7 @@ function createNativeAdapters(getCwd, vfs, config) {
         prevText = await vfs.read(target);
       } catch {}
       const { speculative } = await vfs.write(target, content);
+      index.touch(relativeSlash(cwd, target));
       const diff = buildWriteDiff(target, prevText, content);
       const tag = speculative ? " (speculative)" : "";
       return textResult(`wrote ${target}${tag}`, { path: target, speculative, diff });
@@ -176,33 +297,20 @@ function createNativeAdapters(getCwd, vfs, config) {
       const target = await resolveWorkspacePath(cwd, params?.path, "edit", false);
       if (signal?.aborted) throw new Error("aborted");
 
-      if (patchModeOf(params)) {
-        const patchContent = params.patch || params.oldText;
-        const original = await vfs.read(target);
-        const { resultText, hunkCount } = applyPatchToText(original, patchContent);
-        const { speculative } = await vfs.write(target, resultText);
-        const diff = buildPatchDiff(target, patchContent);
-        const tag = speculative ? " (speculative)" : "";
-        return textResult(`applied ${hunkCount} hunk(s) to ${target}${tag}`, {
-          path: target,
-          hunks: hunkCount,
-          speculative,
-          diff,
-        });
-      }
-
       const requestedEdits = Array.isArray(params?.edits)
         ? params.edits
         : [{ oldText: params?.oldText, newText: params?.newText }];
       const content = await vfs.read(target);
       const { updated, matches } = applyReplacements(target, content, requestedEdits);
       const { speculative } = await vfs.write(target, updated);
+      index.touch(relativeSlash(cwd, target));
       const diff =
         matches.length === 1
           ? buildEditDiff(target, content, matches[0].oldText, matches[0].newText)
           : buildMultiEditDiff(target, content, matches);
       const tag = speculative ? " (speculative)" : "";
-      return textResult(`edited ${target}${tag}`, { path: target, speculative, diff });
+      const summary = await editSummary(cwd, target, content, updated, diff);
+      return textResult(summary, { path: target, speculative, diff });
     },
     async apply_patch(params, signal) {
       const cwd = getCwd();
@@ -243,19 +351,26 @@ function createNativeAdapters(getCwd, vfs, config) {
       const res = await executeSnap({
         query: params.query,
         searchDir: snapTarget,
+        root: cwd,
         includeHidden,
-        vfs: {
-          read: async (candidate) => {
-            // Jail each snap candidate (symlink files must not escape the workspace).
-            const jailed = await resolveWorkspacePath(cwd, candidate, "snap", false);
-            return vfs.read(jailed);
-          },
-        },
-        runCommand: (argv, opts) => runCommand(argv, { cwd: snapTarget, signal, ...opts }),
+        index,
+        overlayText: (p) => vfs.getOverlay(p),
         pendingPaths: vfs.getOverlayPaths(),
       });
       return textResult(JSON.stringify(res, null, 2), res);
     },
+    async evidence(params, signal) {
+      const cwd = getCwd();
+      if (!isString(params?.query) || !params.query.trim()) throw new Error("evidence requires query");
+      if (signal?.aborted) throw new Error("aborted");
+      const searchDir = params?.path ? await resolveWorkspacePath(cwd, params.path, "evidence", true) : cwd;
+      const options = {};
+      if (Number.isInteger(params?.k) && params.k > 0) options.k = params.k;
+      if (Number.isInteger(params?.maxChars) && params.maxChars > 0) options.maxChars = params.maxChars;
+      const res = await selectEvidence({ query: params.query, root: cwd, searchDir, index, overlayText: (p) => vfs.getOverlay(p), options });
+      for (const span of res.spans) ledger.recordOrigin(span.path, span.lines[0], span.text.split("\n"));
+      return textResult(JSON.stringify(res), { route: res.route, count: res.spans.length });
+    },
     async surface(params, signal) {
       const cwd = getCwd();
       const target = await resolveWorkspacePath(cwd, params?.path, "surface", false);
@@ -286,9 +401,11 @@ function createNativeAdapters(getCwd, vfs, config) {
         });
       } finally {
         vfs.invalidateCache();
+        index.invalidate();
       }
       const { stdout, stderr } = res;
-      const text = stdout && stderr ? stdout + (stdout.endsWith("\n") ? "" : "\n") + stderr : stdout || stderr;
+      let text = stdout && stderr ? stdout + (stdout.endsWith("\n") ? "" : "\n") + stderr : stdout || stderr;
+      if (res.exitCode !== 0) text += sourceForReferences(cwd, text);
       return {
         content: [{ type: "text", text }],
         details: { exitCode: res.exitCode, outputTruncated: res.outputTruncated, transactionBarrier },
@@ -300,11 +417,10 @@ function createNativeAdapters(getCwd, vfs, config) {
       const pattern = String(params?.pattern || "");
       if (!pattern) throw new Error("grep requires pattern");
       const searchPath = params?.path ? await resolveWorkspacePath(cwd, params.path, "grep", true) : cwd;
-      const args = ["--line-number", "--no-heading", "--color", "never"];
-      if (params?.caseSensitive !== true) args.push("--ignore-case");
-      if (params?.glob) args.push("--glob", String(params.glob));
-      args.push("--", pattern, searchPath);
-      const res = await runCommand(["rg", ...args], { cwd, timeoutMs: 30_000, signal });
+      const indexed = await grepIndexed(index, pattern, params, searchPath, cwd);
+      if (indexed !== null) return textResult(indexed, { exitCode: indexed ? 0 : 1, via: "index" });
+      // Large tree: real rg keeps its own output format.
+      const res = await runCommand(["rg", ...rgGrepArgs(pattern, params, searchPath)], { cwd, timeoutMs: 30_000, signal });
       if (res.exitCode !== 0 && res.exitCode !== 1) {
         throw new Error(res.stderr.trim() || `rg exited ${res.exitCode}`);
       }
@@ -314,6 +430,10 @@ function createNativeAdapters(getCwd, vfs, config) {
       const cwd = getCwd();
       const pattern = String(params?.pattern || "");
       if (!pattern) throw new Error("glob requires pattern");
+      const fuzzy = await fuzzyFind(index, cwd, cwd, pattern);
+      if (fuzzy !== null) return textResult(fuzzy, { via: "fuzzy" });
+      const indexed = await listIndexed(index, cwd, cwd, pattern);
+      if (indexed !== null) return textResult(indexed, { via: "index" });
       const rg = await runCommand(["rg", "--files", "-g", pattern], { cwd, timeoutMs: 30_000, signal }).catch(
         () => null,
       );
@@ -333,16 +453,12 @@ function createNativeAdapters(getCwd, vfs, config) {
       const searchDir = params?.path ? await resolveWorkspacePath(cwd, params.path, "find", true) : cwd;
       const pattern = params?.pattern || params?.glob;
       if (signal?.aborted) throw new Error("aborted");
-      const args = ["--files"];
-      if (pattern) args.push("-g", String(pattern));
-      const res = await runCommand(["rg", ...args, searchDir], { cwd, timeoutMs: 30_000, signal }).catch(() => null);
-      if (res && (res.exitCode === 0 || res.exitCode === 1)) {
-        return textResult(res.stdout, { via: "rg" });
-      }
-      const findArgs = [searchDir];
-      if (pattern) findArgs.push("-name", String(pattern));
-      const findRes = await runCommand(["find", ...findArgs], { cwd, timeoutMs: 30_000, signal });
-      return textResult(findRes.stdout, { via: "find" });
+      const globPattern = pattern ? String(pattern) : null;
+      const fuzzy = await fuzzyFind(index, searchDir, cwd, globPattern);
+      if (fuzzy !== null) return textResult(fuzzy, { via: "fuzzy" });
+      const indexed = await listIndexed(index, searchDir, cwd, globPattern);
+      if (indexed !== null) return textResult(indexed, { via: "index" });
+      return listWithTools(searchDir, globPattern, cwd, signal);
     },
     async ls(params, signal) {
       const cwd = getCwd();
@@ -359,9 +475,11 @@ function createNativeAdapters(getCwd, vfs, config) {
 }
 
 export function createHostBridge({ pi, config, getCwd }) {
-  const vfs = new CausalVfs();
+  const index = new WorkspaceIndex((argv, opts) => runCommand(argv, opts));
+  const ledger = new SeenLedger({ window: config.seenWindow ?? 40 });
+  const vfs = new CausalVfs(() => index.invalidate());
   const executors = new Map();
-  const natives = createNativeAdapters(getCwd, vfs, config);
+  const natives = createNativeAdapters(getCwd, vfs, config, index, ledger);
   let callCount = 0;
   let activeCtx = null;
   let activeSignal = undefined;
@@ -395,6 +513,7 @@ export function createHostBridge({ pi, config, getCwd }) {
     trace = [];
     // Files may change between programs (editor, git); never serve a stale run.
     vfs.invalidateCache();
+    clearPathCache();
   }
 
   function getTrace() {
@@ -405,10 +524,6 @@ export function createHostBridge({ pi, config, getCwd }) {
     callListener = isFunction(fn) ? fn : null;
   }
 
-  function hasExecutor(name) {
-    return executors.has(name) || Object.hasOwn(natives, name);
-  }
-
   function beginSpeculation() {
     return vfs.begin();
   }
@@ -421,10 +536,6 @@ export function createHostBridge({ pi, config, getCwd }) {
     return vfs.rollback();
   }
 
-  function clearVfsCache() {
-    vfs.clear();
-  }
-
   function resultDiff(response) {
     let details = response?.details;
     if (isString(details)) {
@@ -514,6 +625,7 @@ export function createHostBridge({ pi, config, getCwd }) {
     } catch (error) {
       record.ok = false;
       record.ms = Date.now() - record.time;
+      record.error = error instanceof Error ? error.message : String(error);
       notifyCall(record);
       throw error;
     }
@@ -559,15 +671,13 @@ export function createHostBridge({ pi, config, getCwd }) {
     resetCallBudget,
     getTrace,
     setCallListener,
-    hasExecutor,
     beginSpeculation,
     commitSpeculation,
     rollbackSpeculation,
-    clearVfsCache,
     getVfsCacheSize: () => vfs.getCacheSize(),
     getOverlayDepth: () => vfs.getOverlayDepth(),
     call,
     callMany,
-    isMutating: (name) => isMutatingTool(name, config),
+    ledger,
   };
 }

package/index.js

@@ -4,16 +4,11 @@ import { buildCatalog, searchCatalog, describeTool, mergeNativeToolDefinitions }
 import { loadConfig } from "./config.js";
 import { createHostBridge } from "./host-bridge.js";
 import { runGuestProgram, warmGuestWorker } from "./runtime.js";
-import {
-  extractOperationsFromCode,
-  renderSupernovaCall,
-  renderSupernovaResult,
-  SafeText,
-} from "./render.js";
+import { renderSupernovaCall, renderSupernovaResult } from "./render.js";
 
-export { extractOperationsFromCode, renderSupernovaCall, renderSupernovaResult, SafeText };
+export { renderSupernovaCall, renderSupernovaResult };
 
-// Sync only — never top-level await. Dynamic import of host/deps hung OMP plugin load.
+// Sync only, never top-level await. Dynamic import of host/deps hung OMP plugin load.
 const require = createRequire(import.meta.url);
 let Type;
 try {
@@ -31,57 +26,84 @@ function result(text, details) {
   return { content: [{ type: "text", text }], details };
 }
 
-/** Live trace updates for the card; a throwing host callback must never break the run. */
+const PROGRESS_FRAME_MS = 40;
+
+/**
+ * Live trace updates for the card. The first update is immediate (seeds the result slot);
+ * later ones are coalesced to one host re-render per frame so a tight loop of nova.calls
+ * is not throttled by the TUI. A throwing host callback must never break the run.
+ */
 function progressEmitter(onUpdate) {
-  if (!isFunction(onUpdate)) return () => {};
-  return (trace) => {
+  if (!isFunction(onUpdate)) return Object.assign(() => {}, { flush() {} });
+  let pending = null;
+  let timer = null;
+  const send = (trace) => {
     try {
       onUpdate({ content: [{ type: "text", text: "" }], details: { trace, running: true } });
     } catch {}
   };
+  const flush = () => {
+    timer = null;
+    if (pending === null) return;
+    const trace = pending;
+    pending = null;
+    send(trace);
+  };
+  const emit = (trace) => {
+    if (timer === null && pending === null) {
+      send(trace);
+      timer = setTimeout(flush, PROGRESS_FRAME_MS);
+      return;
+    }
+    pending = trace;
+    if (timer === null) timer = setTimeout(flush, PROGRESS_FRAME_MS);
+  };
+  emit.flush = () => {
+    if (timer !== null) clearTimeout(timer);
+    pending = null;
+    timer = null;
+  };
+  return emit;
+}
+
+function sessionStats({ programs, returnedChars, collapsedChars, collapsedRuns }) {
+  const total = returnedChars + collapsedChars;
+  const pct = total ? Math.round((collapsedChars / total) * 100) : 0;
+  return `this session: ${programs} programs · ~${Math.round(returnedChars / 4)} tokens returned · ~${Math.round(collapsedChars / 4)} already-seen tokens not re-sent (${pct}%, ${collapsedRuns} runs)`;
 }
 
 function logsBlock(outcome, tail = "") {
   return outcome.logs?.length ? `\n--- logs\n${outcome.logs.join("\n")}${tail}` : "";
 }
 
-function errorText(outcome) {
-  return `error ${outcome.wallMs}ms: ${outcome.error}${logsBlock(outcome)}`;
+function errorText(outcome, call) {
+  return `error #${call} ${outcome.wallMs}ms: ${outcome.error}${logsBlock(outcome)}`;
 }
 
-function successText(outcome) {
+function successText(outcome, call) {
   const truncated = outcome.returnTruncated ? " [return truncated]" : "";
-  const hint = outcome.undefinedReturn ? " (no return statement — add \`return\` to get a value)" : "";
-  return `ok ${outcome.wallMs}ms${truncated}${logsBlock(outcome, "\n--- result")}\n${outcome.resultText}${hint}`;
+  const hint = outcome.undefinedReturn ? " (no return statement; add \`return\` to get a value)" : "";
+  return `ok #${call} ${outcome.wallMs}ms${truncated}${logsBlock(outcome, "\n--- result")}\n${outcome.resultText}${hint}`;
 }
-function unwrapStructuredResult(response, operation) {
-  if (response?.ok === false) {
-    throw new Error(response.value || response.error || `${operation} failed`);
-  }
-  const value = isObject(response) && "value" in response ? response.value : response;
-  if (!isString(value)) return value;
-  try {
-    return JSON.parse(value);
-  } catch {
-    return value;
-  }
-}
-
 const TOOL_DESCRIPTION = `Run one JavaScript program that composes host tools. Async body or arrow; \`return\` a small shaped value (compact literal, capped; strings raw; console.log is captured).
 
 Globals (async):
-read(path|paths, offset?, limit?) → text | text[]
-write(path, text) · edit(path, oldText, newText) · patch(path, unifiedDiff)
+read(path|paths, offset?, limit?) → text | text[] · read(path, {about}) → whole-file outline, only relevant bodies expanded
+write(path, text) · edit(path, oldText, newText) → post-edit lines (no re-read needed) · patch(path, unifiedDiff)
 bash(cmd, {cwd?, timeoutMs?}) → output, throws on non-zero exit · exec(cmd, argv?) quotes argv
+evidence(query, {k?}) → {spans: [{path, lines, name, text}]} top-K spans that answer a question; use before read
 snap(query, root?) → {path, line, signature, context} · surface(path) → {items: [{name, kind, line}]}
 nova.call(name, args) → {ok, value} for any host tool · nova.callMany([{name, args}]) parallel when read-only
 nova.search(query) → [{name, description}] · nova.describe(name) → parameters · nova.has(name) sync
-parallel(thunks) · pipeline(items, ...stages)`;
+parallel(thunks) · pipeline(items, ...stages)
+
+Already-seen lines collapse to "⋯ N lines same as #12 · path:a–b ⋯"; read(path, a, n) re-shows them.`;
 
 export default function piSupernova(pi) {
   const config = loadConfig();
   let cwd = process.cwd();
   let catalog = [];
+  let programSeq = 0;
 
   const bridge = createHostBridge({
     pi,
@@ -133,12 +155,6 @@ export default function piSupernova(pi) {
         const cat = catalog.length ? catalog : refreshCatalog();
         return [...new Set([...cat.map((t) => t.name), ...bridge.executors.keys(), ...Object.keys(bridge.natives)])];
       },
-      async surface(filePath) {
-        return unwrapStructuredResult(await bridge.call("surface", { path: filePath }), "surface");
-      },
-      async snap(query, targetPath) {
-        return unwrapStructuredResult(await bridge.call("snap", { query, path: targetPath }), "snap");
-      },
     };
   }
 
@@ -148,7 +164,7 @@ export default function piSupernova(pi) {
     description: TOOL_DESCRIPTION,
     promptSnippet: "Compose host tools in one JavaScript program",
     promptGuidelines: [
-      "Use supernova for multi-step tool work: loops, filtering, parallel reads, read→edit chains. Return a compact shaped value; keep raw tool output inside the program.",
+      "Use supernova for multi-step tool work: loops, filtering, parallel reads, read→edit chains. To understand code: evidence(question) across the repo, or read(path, {about: question}) for one file: full structure, only relevant bodies expanded. Plain read(path) only for lines you will edit. Return a compact shaped value; keep raw tool output inside the program.",
     ],
     parameters: Type.Object({
       code: Type.String({ description: "JavaScript program: async body or arrow function." }),
@@ -171,6 +187,8 @@ export default function piSupernova(pi) {
       bridge.resetCallBudget();
       refreshCatalog();
       bridge.beginSpeculation();
+      const call = ++programSeq;
+      bridge.ledger.beginProgram(call);
       const emitProgress = progressEmitter(onUpdate);
       bridge.setCallListener((_record, allTrace) => emitProgress(allTrace));
       emitProgress([]);
@@ -180,16 +198,17 @@ export default function piSupernova(pi) {
         outcome = await runProgram(params, runController.signal, abortRun);
       } finally {
         bridge.setCallListener(null);
+        emitProgress.flush();
         signal?.removeEventListener("abort", abortRun);
       }
 
       const trace = bridge.getTrace();
       if (!outcome.ok) {
         bridge.rollbackSpeculation();
-        return result(errorText(outcome), { ok: false, error: outcome.error, wallMs: outcome.wallMs, logs: outcome.logs, trace });
+        return result(bridge.ledger.dedupe(errorText(outcome, call), call), { ok: false, error: outcome.error, wallMs: outcome.wallMs, logs: outcome.logs, trace });
       }
       await bridge.commitSpeculation();
-      return result(successText(outcome), {
+      return result(bridge.ledger.dedupe(successText(outcome, call), call), {
         ok: true,
         wallMs: outcome.wallMs,
         returnTruncated: outcome.returnTruncated,
@@ -221,6 +240,9 @@ export default function piSupernova(pi) {
 
   pi.on("session_start", (_event, ctx) => {
     if (ctx && isString(ctx.cwd) && ctx.cwd) cwd = ctx.cwd;
+    // A new session is a new model context: nothing has been seen yet.
+    bridge.ledger.reset();
+    programSeq = 0;
     refreshCatalog();
     warmGuestWorker(config).catch(() => {});
   });
@@ -233,9 +255,10 @@ export default function piSupernova(pi) {
       const natives = Object.keys(bridge.natives).sort();
       const lines = [
         `pi-supernova catalog: ${catalog.length} tools`,
-        `captured executors: ${captured.length ? captured.join(", ") : "(none yet — load this package early)"}`,
+        `captured executors: ${captured.length ? captured.join(", ") : "(none yet; load this package early)"}`,
         `native adapters: ${natives.join(", ")}`,
         `timeoutMs=${config.timeoutMs} maxCallResultChars=${config.maxCallResultChars} maxReturnChars=${config.maxReturnChars} maxBridgeCalls=${config.maxBridgeCalls} maxHeapMb=${config.maxHeapMb}`,
+        sessionStats(bridge.ledger.stats),
       ];
       ctx.ui.notify(lines.join("\n"), "info");
     },