pi-supernova 0.2.0 → 0.3.0

package/src/bridge/native-tools.js

@@ -0,0 +1,155 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { homedir } from "node:os";
+import { loadConfig } from "../config/config.js";
+import { isString } from "../shared/decode.js";
+import { createHostBridge } from "./host-bridge.js";
+import { buildPatchDiff } from "../fs/diff.js";
+import { createNativeScheduler } from "../runtime/parallel.js";
+import { truncateChars } from "../output/format.js";
+import { clearPathCache, resolveWorkspacePath } from "../fs/workspace.js";
+
+export const NATIVE_NAMES = Object.freeze(["read", "edit", "write", "bash"]);
+
+function userPath(cwd, input) {
+  if (!isString(input) || !input.trim()) throw new Error("path must be a non-empty string");
+  const value = input.trim().replace(/^@/, "");
+  return path.resolve(cwd, value === "~" ? homedir() : value.startsWith("~/") ? path.join(homedir(), value.slice(2)) : value);
+}
+
+function boundText(result, maxChars) {
+  const total = result.content.reduce((sum, block) => sum + (block.type === "text" ? block.text.length : 0), 0);
+  const truncated = total > maxChars;
+  const notice = truncated ? truncateChars("\n[Truncated: read files individually or narrow the line range/question.]", maxChars, "read-result").text : "";
+  let remaining = maxChars - notice.length;
+  const content = result.content.map(block => {
+    if (block.type !== "text") return block; // Images remain image attachments.
+    const bounded = truncateChars(block.text, remaining, "read-result");
+    remaining -= bounded.text.length;
+    return { ...block, text: bounded.text };
+  });
+  if (notice) content.push({ type: "text", text: notice });
+  const details = { ...result.details };
+  if (truncated) details.outputTruncated = true;
+  return { ...result, content, details };
+}
+
+/** Familiar Pi tool definitions with Supernova's source engine and atomic VFS. */
+export function registerNativeTools(pi, host, config = loadConfig()) {
+  let cwd = process.cwd();
+  const base = createHostBridge({ pi: null, config: { ...config, seenWindow: 0 }, getCwd: () => cwd });
+  const scheduler = createNativeScheduler();
+  const factories = {
+    read: host.createReadToolDefinition,
+    edit: host.createEditToolDefinition,
+    write: host.createWriteToolDefinition,
+    bash: host.createBashToolDefinition,
+  };
+
+  function settingsFor(ctx) {
+    return host.SettingsManager?.create(ctx.cwd, undefined, { projectTrusted: ctx.isProjectTrusted?.() === true });
+  }
+
+  async function readOne(args, signal, ctx, bridge, id) {
+    const target = userPath(ctx.cwd, args.path);
+    let stat;
+    try { stat = await fs.stat(target); }
+    catch (error) { if (error.code !== "ENOENT" && error.code !== "ENOTDIR") throw error; }
+    signal?.throwIfAborted();
+    const image = /\.(png|jpe?g|gif|webp|bmp)$/i.test(target);
+    if (stat?.isFile() && (args.about === undefined || image)) {
+      // Pi retains image handling, full text, line windows, truncation metadata,
+      // and actionable continuation offsets. Do not summarize or dedupe these.
+      return factories.read(ctx.cwd, { autoResizeImages: image ? settingsFor(ctx)?.getImageAutoResize() : undefined }).execute(id, { ...args, path: target }, signal, undefined, ctx);
+    }
+    return boundText(await bridge.natives.read({ ...args, path: stat ? target : args.path }, signal), config.maxCallResultChars);
+  }
+
+  async function execute(name, id, args, signal, onUpdate, context) {
+    const ctx = { ...context, cwd: context?.cwd || cwd };
+    const bridge = base.fork({ getCwd: () => ctx.cwd });
+    bridge.bindCallContext(ctx, signal);
+    signal?.throwIfAborted();
+    try {
+      if (name === "read") {
+        if (!Array.isArray(args.path)) return await readOne(args, signal, ctx, bridge, id);
+        if (args.path.some(p => !isString(p) || !p.trim())) throw new Error("read paths must be non-empty strings");
+        if (args.path.length > 64) throw new Error("read path arrays support at most 64 entries; use smaller batches");
+        const groups = [], errors = [];
+        // Bound fan-out even when a model submits a large path array.
+        for (let offset = 0; offset < args.path.length; offset += 8) {
+          const results = await Promise.all(args.path.slice(offset, offset + 8).map(async file => {
+            try {
+              const result = await readOne({ ...args, path: file }, signal, ctx, bridge, id);
+              return { content: [{ type: "text", text: "File: " + file }, ...result.content] };
+            } catch (error) {
+              signal?.throwIfAborted();
+              errors.push({ path: file, message: error.message });
+              return { content: [{ type: "text", text: "[read error: " + file + "] " + error.message }] };
+            }
+          }));
+          groups.push(...results);
+        }
+        const content = [];
+        let remaining = config.maxCallResultChars, outputTruncated = false;
+        for (let i = 0; i < groups.length; i++) {
+          const bounded = boundText(groups[i], Math.floor(remaining / (groups.length - i)));
+          remaining -= bounded.content.reduce((sum, block) => sum + (block.type === "text" ? block.text.length : 0), 0);
+          outputTruncated ||= bounded.details.outputTruncated === true;
+          content.push(...bounded.content);
+        }
+        return { content, details: { batch: true, count: args.path.length, errors, outputTruncated } };
+      }
+      if (name === "bash") {
+        const settings = settingsFor(ctx);
+        try { return await factories.bash(ctx.cwd, { shellPath: settings?.getShellPath(), commandPrefix: settings?.getShellCommandPrefix() }).execute(id, args, signal, onUpdate, ctx); }
+        finally { bridge.invalidateFiles(); }
+      }
+      clearPathCache();
+      const target = await resolveWorkspacePath(ctx.cwd, userPath(ctx.cwd, args.path), name);
+      const ops = bridge.fileOperations;
+      let before, after;
+      const tool = factories[name](ctx.cwd, { operations: {
+        ...ops,
+        async readFile(file) { const buffer = await ops.readFile(file); before = buffer.toString("utf8"); return buffer; },
+        async writeFile(file, content) { await ops.writeFile(file, content); after = content; },
+      } });
+      // Pi's edit/write implementations hold its shared canonical per-file queue
+      // over the entire mutation, including our atomic replacement operation.
+      const result = await tool.execute(id, { ...args, path: target }, signal, onUpdate, ctx);
+      if (name === "edit" && before !== undefined && after !== undefined && result.details?.patch) {
+        const summary = await bridge.summarizeEdit(target, before, after, buildPatchDiff(target, result.details.patch));
+        result.content = [{ type: "text", text: summary }];
+      }
+      return result;
+    } finally { bridge.close(); }
+  }
+
+  for (const name of NATIVE_NAMES) {
+    const definition = factories[name](cwd);
+    const tool = {
+      ...definition,
+      execute(id, args, signal, onUpdate, ctx) {
+        return scheduler.schedule(name, () => execute(name, id, args, signal, onUpdate, ctx), signal);
+      },
+    };
+    if (name === "read") {
+      tool.description += " Also reads directories or finds source from a symbol/question passed as path. Use about to focus a file or directory on a question. An array of paths returns all readable files and labels individual errors.";
+      tool.parameters = { ...definition.parameters, properties: {
+        ...definition.parameters.properties,
+        path: { anyOf: [{ type: "string" }, { type: "array", items: { type: "string" }, maxItems: 64 }], description: "File, directory, source question, or up to 64 paths to read" },
+        about: { type: "string", description: "Focus on this question or symbol; source selection reports uncertainty instead of guessing" },
+      } };
+      tool.promptGuidelines = [...(definition.promptGuidelines || []), "read can find source from a symbol or question; check its selection status before choosing a file. Plain file reads preserve full text within the stated limits."];
+    }
+    pi.registerTool(tool);
+  }
+  pi.on("session_start", (_event, ctx) => {
+    cwd = ctx?.cwd || cwd;
+    base.invalidateFiles();
+  });
+  pi.registerCommand("supernova", {
+    description: "Show Supernova native runtime status",
+    handler: async (_args, ctx) => ctx.ui.notify("Supernova runtime: read, edit, write, bash; " + scheduler.stats.calls + " calls, " + scheduler.stats.readWaves + " read waves, peak " + scheduler.stats.peakParallelReads + " parallel reads. Mutations are ordered; plain reads are not summarized or deduplicated.", "info"),
+  });
+}

package/src/bridge/pi-extension.ts

@@ -0,0 +1,2 @@
+// Compatibility for installations that still point at the former entrypoint.
+export { default } from "../../index.js";

package/{config.js → src/config/config.js}

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { createRequire } from "node:module";
-import { isString, isObject } from "./decode.js";
+import { isString, isObject } from "../shared/decode.js";
 
 const require = createRequire(import.meta.url);
 const DEFAULTS = require("./config.default.json");

package/{evidence.js → src/context/evidence.js}

@@ -1,7 +1,7 @@
 import * as path from "node:path";
 import { WorkspaceIndex } from "./repo-index.js";
-import { tokenizeQuery, scorePathTopology } from "./snap.js";
-import { isTestPath } from "./workspace.js";
+import { tokenizeQuery, scorePathTopology, stem } from "./snap.js";
+import { isTestPath } from "../fs/workspace.js";
 
 // Zero-token evidence selection over source code, after Zero-Mem (arXiv:2607.29377).
 // The codebase is the interaction history H; declared spans are the context units;
@@ -38,11 +38,7 @@ const RELATION_WORDS = new Set(["calls", "caller", "callers", "uses", "usages",
 const HUB_FRACTION = 0.25;
 const HUB_MIN = 8;
 
-/** Light suffix stripping so "terminated" ⊇ "terminat" matches "terminate"; deterministic, no dictionary. */
-export function stem(token) {
-  if (token.length < 5) return token;
-  return token.replace(/(ations?|ings?|ed|es|e|s|ly|ers?)$/, (m) => (token.length - m.length >= 4 ? "" : m));
-}
+export { stem } from "./snap.js";
 
 function splitIdentifier(name) {
   return name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
@@ -73,9 +69,9 @@ function spansOf(entry, filePath, maxSpanLines) {
   const base = { path: filePath, entry, lower: lines.lower, lines };
   const declared = WorkspaceIndex.spansOf(entry);
   if (declared.length === 0) {
-    return [{ ...base, id: filePath + ":1", start: 1, end: Math.min(lines.raw.length, maxSpanLines), name: path.basename(filePath), kind: "file" }];
+    return [{ ...base, id: filePath + ":1", start: 1, end: Math.min(lines.raw.length, maxSpanLines), name: path.basename(filePath), kind: "file", sourceEnd: lines.raw.length }];
   }
-  return declared.map((s, i) => ({ ...base, ...s, id: filePath + ":" + s.start, end: Math.min(s.end, s.start + maxSpanLines - 1), index: i }));
+  return declared.map((s, i) => ({ ...base, ...s, sourceEnd: s.end, id: filePath + ":" + s.start, end: Math.min(s.end, s.start + maxSpanLines - 1), index: i }));
 }
 
 function spanLines(span) {
@@ -316,7 +312,7 @@ function candidateFiles(files, profile, index, limit, overlayText) {
     if (s > 0) scored.push({ f, s });
   }
   scored.sort((a, b) => b.s - a.s);
-  const chosen = new Set(scored.slice(0, limit).map(({ f }) => f));
+  const chosen = new Set();
   const anchors = (profile.subjects.length ? profile.subjects : profile.keywords).map((a) => a.toLowerCase()).filter((a) => a.length > 2);
   const pendingHits = files.filter(file => {
     const pending = overlayText(file);
@@ -327,6 +323,10 @@ function candidateFiles(files, profile, index, limit, overlayText) {
     if (chosen.size >= limit) break;
     if (profile.flags.wantsTest || scorePathTopology(f, profile.keywords, profile.flags) > -50) chosen.add(f);
   }
+  for (const { f } of scored) {
+    if (chosen.size >= limit) break;
+    chosen.add(f);
+  }
   return { files: [...chosen], fileScores: new Map(scored.map(({ f, s }) => [f, s])) };
 }
 
@@ -370,11 +370,22 @@ function render(spans, picks, fused, opts, root) {
     const span = spans[i];
     const lines = span.lines.raw.slice(span.start - 1, span.end);
     let text = lines.join("\n");
-    if (text.length > budget) text = text.slice(0, Math.max(0, budget - 1)) + "…";
+    if (text.length > budget) {
+      const end = text.lastIndexOf("\n", budget);
+      if (end < 0) {
+        if (out.length) break;
+        throw new Error("evidence source line exceeds maxChars; increase the budget or read the file directly");
+      }
+      text = text.slice(0, end);
+    }
+    const lastLine = span.start + text.split("\n").length - 1;
+    const truncated = lastLine < span.sourceEnd;
     budget -= text.length;
     out.push({
       path: path.relative(root, span.path) || span.path,
-      lines: [span.start, span.start + lines.length - 1],
+      lines: [span.start, lastLine],
+      truncated: truncated || undefined,
+      nextOffset: truncated ? lastLine + 1 : undefined,
       name: span.name,
       kind: span.kind,
       why,

package/{outline.js → src/context/outline.js}

@@ -70,7 +70,7 @@ export function outlineFile(entry, relPath, about, options = {}) {
   const parts = [];
   const headerEnd = Math.min(spans[0].start - 1, opts.headerLines);
   if (headerEnd > 0) {
-    const header = raw.slice(0, headerEnd).filter((l) => l.trim());
+    const header = raw.slice(0, headerEnd);
     if (header.length) parts.push(header.map((l, i) => String(i + 1).padStart(5) + " " + l).join("\n"));
     if (spans[0].start - 1 > opts.headerLines) parts.push("      … " + (spans[0].start - 1 - opts.headerLines) + " more header lines");
   }

package/{repo-index.js → src/context/repo-index.js}

@@ -1,14 +1,15 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { extractStructuralSurface } from "./surface.js";
-import { isFunction } from "./decode.js";
+import { isFunction } from "../shared/decode.js";
 import { Frecency } from "./fuzzy.js";
-import { relativeSlash } from "./workspace.js";
+import { relativeSlash } from "../fs/workspace.js";
 
 // In-process workspace index: the gitignore-aware file list comes from one
 // \`rg --files\` spawn and is then reused; file text, lowercase text, and the
-// structural surface are cached per path and validated by mtime. snap/grep/glob
-// read from here instead of spawning, so a warm call is sub-millisecond.
+// structural surface are cached per path and validated by mtime. Explicit evidence
+// and internal indexed searches use this cache; ordinary source reads and mutation
+// reference hints do not require it. Metadata validation is not content identity.
 
 // With a working fs.watch the list only refreshes on change; the TTL is the fallback when watching fails.
 const LIST_TTL_MS = 10_000;
@@ -210,9 +211,9 @@ export class WorkspaceIndex {
   static linesOf(entry) {
     if (entry.lines) return entry.lines;
     const raw = entry.text.split("\n");
-    const lower = new Array(raw.length);
-    const defNames = new Array(raw.length);
-    const idents = new Array(raw.length);
+    const lower = [];
+    const defNames = [];
+    const idents = [];
     for (let i = 0; i < raw.length; i++) {
       const trimmed = raw[i].trim();
       lower[i] = trimmed.toLowerCase();
@@ -265,11 +266,12 @@ export class WorkspaceIndex {
   }
 
   /** Structured grep rows {rel, line, text, def}; def marks lines whose declared name itself matches. */
-  grepRows(files, regex, root) {
+  grepRows(files, regex, root, overlayText = () => undefined) {
     const out = [];
     const nameRegex = new RegExp(regex.source, "i");
     for (const filePath of files) {
-      const e = this.entry(filePath);
+      const pending = overlayText(filePath);
+      const e = pending === undefined ? this.entry(filePath) : WorkspaceIndex.fromText(filePath, pending);
       if (!e || !regex.test(e.text)) continue;
       const { raw, defNames } = WorkspaceIndex.linesOf(e);
       const rel = relativeSlash(root, filePath);

package/{search.js → src/context/search.js}

@@ -1,7 +1,8 @@
 import * as path from "node:path";
+import { isString } from "../shared/decode.js";
 import { WorkspaceIndex, globToRegExp } from "./repo-index.js";
 import { rankPaths, smartCase, fuzzyMatch } from "./fuzzy.js";
-import { runCommand, relativeSlash } from "./workspace.js";
+import { runCommand, relativeSlash } from "../fs/workspace.js";
 
 // Search served from the in-process index: fuzzy path find (fff port), smart-case grep with
 // definition-first rows and fuzzy fallback, glob listing. rg is spawned only for trees too
@@ -11,6 +12,38 @@ function textResult(text, details) {
   return { content: [{ type: "text", text: String(text ?? "") }], details: details || {} };
 }
 
+/** One bounded direct search for all changed names; no repository index or per-name spawn. */
+export async function referencesForNames({ root, names, excludePath, overlayText, pendingPaths, signal, run = runCommand }) {
+  const references = new Map(names.map(name => [name, []]));
+  const patterns = names.map(name => new RegExp("(?<![\\w$])" + name.replaceAll("$", "\\$") + "(?![\\w$])"));
+  const add = (file, line, text) => {
+    if (file === excludePath) return;
+    for (let i = 0; i < names.length; i++) {
+      const hits = references.get(names[i]);
+      if (hits.length < 7 && patterns[i].test(text)) hits.push(relativeSlash(root, file) + ":" + line);
+    }
+  };
+  const result = await run(["rg", "--json", "--fixed-strings", ...names.flatMap(name => ["-e", name]), "--", root],
+    { cwd: root, signal, timeoutMs: 5000, maxOutputChars: 65536 });
+  if (result.exitCode !== 0 && result.exitCode !== 1) throw new Error(result.stderr.trim() || "reference search failed");
+  const records = result.stdout.split("\n");
+  for (let i = 0; i < records.length; i++) {
+    signal?.throwIfAborted();
+    if (!records[i]) continue;
+    let record;
+    try { record = JSON.parse(records[i]); }
+    catch (error) { if (result.outputTruncated && i === records.length - 1) break; throw error; }
+    if (record.type !== "match" || !isString(record.data?.path?.text) || !isString(record.data.lines?.text)) continue;
+    const file = path.resolve(root, record.data.path.text);
+    if (overlayText(file) === undefined) add(file, record.data.line_number, record.data.lines.text);
+  }
+  for (const file of pendingPaths) {
+    const text = overlayText(file);
+    if (text !== undefined) text.split("\n").forEach((line, i) => add(file, i + 1, line));
+  }
+  return { references, incomplete: result.outputTruncated === true };
+}
+
 export function rgGrepArgs(pattern, params, searchPath) {
   const args = ["--line-number", "--no-heading", "--color", "never"];
   if (params?.caseSensitive !== true) args.push("--ignore-case");

package/{snap.js → src/context/snap.js}

@@ -1,20 +1,27 @@
 import * as path from "node:path";
-import { isString } from "./decode.js";
-import { truncateChars } from "./format.js";
-import { WorkspaceIndex } from "./repo-index.js";
+import { isString } from "../shared/decode.js";
+import { truncateChars } from "../output/format.js";
+import * as fs from "node:fs/promises";
 import { extractStructuralSurface } from "./surface.js";
-import { isTestPath } from "./workspace.js";
+import { rankPaths } from "./fuzzy.js";
+import { isTestPath, runCommand, relativeSlash } from "../fs/workspace.js";
 
 const STOP_WORDS = new Set([
   "the", "a", "an", "and", "or", "in", "on", "at", "to", "for", "of", "with",
   "by", "from", "is", "it", "this", "that", "where", "how", "what", "which",
-  "file", "code", "function", "class", "method", "find", "get", "look",
+  "file", "code", "function", "class", "method", "find", "get", "look", "are", "does", "do",
 ]);
 const SOURCE_EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".rs", ".py", ".go"]);
 const TYPED_EXT = new Set([".ts", ".tsx", ".rs", ".go"]);
 const MAX_SEARCH_CHARS = 2 * 1024 * 1024;
 const MAX_ALTERNATIVES = 3;
 
+/** Light suffix stripping so "terminated" ⊇ "terminat" matches "terminate"; deterministic, no dictionary. */
+export function stem(token) {
+  if (token.length < 5) return token;
+  return token.replace(/(ations?|ings?|ed|es|e|s|ly|ers?)$/, (m) => (token.length - m.length >= 4 ? "" : m));
+}
+
 export function tokenizeQuery(query) {
   if (!isString(query) || !query.trim()) return { tokens: [], wantsTest: false, wantsType: false, wantsDoc: false };
   const words = query.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-zA-Z0-9_]+/);
@@ -111,19 +118,20 @@ function inspectOverlay(candidate, text, needles, query, tokens) {
   for (let i = Math.max(0, candidate.line - 3); i < Math.min(lines.length, candidate.line + 4); i++) candidate.context.set(i + 1, truncateChars(lines[i], 240, "source line").text);
 }
 
-async function contentCandidates({ dir, includeHidden, query, tokens, flags, fileSet, index, overlayText, signal, exact, diskFiles }) {
+async function contentCandidates({ dir, includeHidden, query, tokens, flags, pendingPaths, run, overlayText, signal, exact, diskFiles }) {
   const needles = exact ? [query.toLowerCase()] : tokens;
   const args = ["rg", "--json", "--fixed-strings", "--ignore-case", "--before-context", "2", "--after-context", "4"];
   if (includeHidden) args.push("--hidden");
   args.push("-g", "!.git/**", "-g", "!**/.git/**");
   for (const needle of needles) args.push("-e", needle);
   args.push("--", dir);
-  const response = diskFiles ? await index.runCommand(args, { cwd: dir, timeoutMs: 15000, maxOutputChars: MAX_SEARCH_CHARS, signal })
+  const response = diskFiles ? await run(args, { cwd: dir, timeoutMs: 15000, maxOutputChars: MAX_SEARCH_CHARS, signal })
     : { stdout: "", stderr: "", exitCode: 1 };
   if (response.exitCode !== 0 && response.exitCode !== 1) throw new Error("source search failed: " + response.stderr.trim());
   const candidates = new Map();
   const records = response.stdout.split("\n");
   for (let i = 0; i < records.length; i++) {
+    if ((i & 127) === 0) signal?.throwIfAborted();
     if (!records[i]) continue;
     let record;
     try { record = JSON.parse(records[i]); } catch (error) {
@@ -134,7 +142,7 @@ async function contentCandidates({ dir, includeHidden, query, tokens, flags, fil
     const data = record.data;
     if (!data?.path?.text || !isString(data.lines?.text)) continue;
     const filePath = path.resolve(dir, data.path.text);
-    if (!fileSet.has(filePath) || overlayText(filePath) !== undefined) continue;
+    if (!inScope(filePath, dir, includeHidden) || overlayText(filePath) !== undefined) continue;
     let candidate = candidates.get(filePath);
     if (!candidate) {
       candidate = makeCandidate(filePath, dir, query, tokens, flags);
@@ -142,7 +150,7 @@ async function contentCandidates({ dir, includeHidden, query, tokens, flags, fil
     }
     inspectLine(candidate, data.line_number, data.lines.text, query, tokens, record.type === "match");
   }
-  for (const filePath of fileSet) {
+  for (const filePath of pendingPaths) {
     const pending = overlayText(filePath);
     if (pending === undefined) continue;
     const candidate = makeCandidate(filePath, dir, query, tokens, flags);
@@ -159,21 +167,15 @@ function rankScore(candidate, tokenCount) {
     + Math.max(-40, Math.min(20, candidate.pathScore / 5));
 }
 
-function location(candidate, root, index, overlayText) {
-  let context = candidate.context;
-  if (context.size === 0) {
-    const pending = overlayText(candidate.path);
-    const entry = pending === undefined ? index.entry(candidate.path) : WorkspaceIndex.fromText(candidate.path, pending);
-    const lines = entry?.text.split("\n") ?? [];
-    context = new Map(lines.slice(0, 7).map((line, i) => [i + 1, truncateChars(line, 240, "source line").text]));
-  }
+function location(candidate, root) {
+  const context = candidate.context;
   return { path: path.relative(root, candidate.path), line: candidate.line, signature: candidate.signature,
     context: [...context].sort((a, b) => a[0] - b[0]).map(([line, text]) => (line === candidate.line ? "►" : " ") + line + " " + text) };
 }
 
-export async function executeSnap({ query, searchDir, root, includeHidden = false, index, overlayText = () => undefined, pendingPaths = [], signal }) {
+export async function executeSnap({ query, searchDir, root, includeHidden = false, run = runCommand, overlayText = () => undefined, pendingPaths = [], pathContext = {}, signal }) {
   const flags = tokenizeQuery(query);
-  const { tokens } = flags;
+  const tokens = [...new Set(flags.tokens.map(stem))];
   if (tokens.length === 0) throw new Error("read requires a file path or a searchable source question");
   if (tokens.length > 16) throw new Error("source question is too broad; use at most 16 keywords");
   query = query.trim();
@@ -181,17 +183,25 @@ export async function executeSnap({ query, searchDir, root, includeHidden = fals
   if (dir.split(path.sep).includes(".git")) throw new Error("cannot search Git metadata");
   signal?.throwIfAborted();
   flags.wantsTest ||= isTestPath(path.relative(root ?? dir, dir));
-  const files = await index.files(dir, includeHidden, signal);
-  const fileSet = new Set(files.filter(file => inScope(file, dir, includeHidden)));
-  for (const pending of pendingPaths) if (inScope(pending, dir, includeHidden)) fileSet.add(path.resolve(pending));
-  const listing = index.lists.get(dir + "\0" + (includeHidden ? "h" : ""));
-  if (listing?.error && !(listing.missing && fileSet.size)) throw new Error("source file listing failed: " + listing.error);
+  pendingPaths = pendingPaths.filter(file => inScope(file, dir, includeHidden));
+  const diskFiles = await fs.stat(dir).then(stat => stat.isDirectory(), error => {
+    if (error.code !== "ENOENT" || !pendingPaths.length) throw error;
+    return false;
+  });
   const empty = { path: null, line: null, signature: "", confidence: 0, context: [] };
-  if (fileSet.size === 0 && !listing?.truncated) return { ...empty, status: "not_found" };
   const exact = /^[a-zA-Z_$][\w$]*$/.test(query);
-  const search = await contentCandidates({ dir, includeHidden, query, tokens, flags, fileSet, index, overlayText, signal, exact, diskFiles: files.length });
-  for (const filePath of fileSet) {
-    if (search.candidates.has(filePath)) continue;
+  const search = await contentCandidates({ dir, includeHidden, query, tokens, flags, pendingPaths, run, overlayText, signal, exact, diskFiles });
+  // A declaration hit needs no prerequisite file listing or persistent index.
+  // Bare names can name files, even when callers mention the same word.
+  const needsPaths = !search.candidates.size || (exact && ![...search.candidates.values()].some(candidate => candidate.exactDefinition));
+  const listing = needsPaths && !search.truncated && diskFiles
+    ? await run(["rg", "--files", "--null", ...(includeHidden ? ["--hidden"] : []), "-g", "!.git/**", "-g", "!**/.git/**", dir], { cwd: dir, signal, timeoutMs: 15000, maxOutputChars: MAX_SEARCH_CHARS })
+    : { stdout: "", exitCode: 1 };
+  if (listing.exitCode !== 0 && listing.exitCode !== 1) throw new Error("source file listing failed: " + listing.stderr.trim());
+  const paths = [...new Set([...listing.stdout.split("\0").filter(Boolean).map(file => path.resolve(dir, file)), ...pendingPaths])]
+    .filter(file => inScope(file, dir, includeHidden));
+  for (const filePath of paths) {
+    if (!inScope(filePath, dir, includeHidden) || search.candidates.has(filePath)) continue;
     const relative = path.relative(dir, filePath).toLowerCase();
     if (!tokens.some(token => relative.includes(token))) continue;
     if (exact && tokens.length > 1 && !relative.includes(query.toLowerCase())) continue;
@@ -201,11 +211,21 @@ export async function executeSnap({ query, searchDir, root, includeHidden = fals
   const ranked = [...search.candidates.values()].filter(candidate => candidate.pathScore > -50)
     .map(candidate => ({ ...candidate, score: rankScore(candidate, tokens.length) }))
     .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
-  const incomplete = search.truncated || listing?.truncated === true;
+  const incomplete = search.truncated || listing.outputTruncated === true;
   const relativeRoot = root ?? dir;
-  const candidates = ranked.slice(0, MAX_ALTERNATIVES).map(candidate => location(candidate, relativeRoot, index, overlayText));
+  const candidates = ranked.slice(0, MAX_ALTERNATIVES).map(candidate => location(candidate, relativeRoot));
   if (incomplete) return { ...empty, status: "incomplete", candidates, message: "Search output exceeded its budget. Narrow the directory with read(path, {about: question})." };
-  if (!ranked.length) return { ...empty, status: "not_found" };
+  if (!ranked.length) {
+    // Reuse bounded filename discovery; fuzzy rank never authorizes a source selection.
+    const eligible = exact && query.length >= 4 && query.length <= 64;
+    const limited = eligible && paths.length > 1024;
+    const fuzzy = eligible ? rankPaths(query, paths.slice(0, 1024).map(file => relativeSlash(relativeRoot, file)),
+      { ...pathContext, maxTypos: 1 }).filter(hit => hit.score > 0).slice(0, MAX_ALTERNATIVES) : [];
+    if (fuzzy.length || limited) return { ...empty, status: limited ? "incomplete" : "ambiguous",
+      candidates: fuzzy.map(hit => ({ path: hit.path, line: 1, context: [], match: "fuzzy" })),
+      message: limited ? "No literal match; fuzzy hints cover only 1024 paths. Narrow the directory." : "No literal match. Fuzzy filename hints are not selected source; read an explicit path." };
+    return { ...empty, status: "not_found" };
+  }
   const best = ranked[0];
   const second = ranked[1];
   const margin = second ? (best.score - second.score) / Math.max(1, best.score) : 1;

package/{surface.js → src/context/surface.js}

@@ -1,5 +1,5 @@
 
-import { isString } from "./decode.js";
+import { isString } from "../shared/decode.js";
 
 function scanPython(lines) {
   const items = [];

package/{diff.js → src/fs/diff.js}

@@ -1,5 +1,5 @@
 
-import { isString } from "./decode.js";
+import { isString } from "../shared/decode.js";
 
 export function buildEditDiff(filePath, originalText, oldText, newText) {
   const fileLines = contentLines(originalText);
@@ -40,12 +40,14 @@ export function buildMultiEditDiff(filePath, originalText, replacements) {
     buildEditDiff(filePath, originalText, oldText, newText),
   );
   const lines = [];
-  for (const part of parts) {
+  let shift = 0;
+  for (const [index, part] of parts.entries()) {
     for (const line of part.lines) {
-      const previous = lines.at(-1);
-      if (previous?.type === "context" && line.type === "context" && previous.lineNum === line.lineNum) continue;
-      lines.push(line);
+      if (line.type === "context") continue;
+      lines.push(line.type === "add" ? { ...line, lineNum: line.lineNum + shift }
+        : { ...line, newLineNum: Math.max(1, line.lineNum + shift) });
     }
+    shift += replacements[index].newText.split("\n").length - replacements[index].oldText.split("\n").length;
   }
   return {
     path: filePath,

package/{patch.js → src/fs/patch.js}

@@ -1,4 +1,4 @@
-import { isString } from "./decode.js";
+import { isString } from "../shared/decode.js";
 
 function parseHunkHeader(line) {
   const match = /^@@\s+-(\d+)(?:,(\d+))?\s+\+(\d+)(?:,(\d+))?\s+@@/.exec(line);