pi-supernova 0.1.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;
@@ -150,7 +151,7 @@ export class WorkspaceIndex {
   }
 
   /** Absolute, sorted file list for a root; gitignore-aware via rg; cached for LIST_TTL_MS. */
-  async files(root, includeHidden = false) {
+  async files(root, includeHidden = false, signal) {
     const key = root + "\0" + (includeHidden ? "h" : "");
     const cached = this.lists.get(key);
     const ttl = this.watch(root) ? WATCHED_TTL_MS : LIST_TTL_MS;
@@ -159,13 +160,21 @@ export class WorkspaceIndex {
     if (includeHidden) args.push("--hidden");
     args.push("-g", "!.git/**", "-g", "!**/.git/**", root);
     let files = [];
+    let error;
+    let truncated = false;
+    let missing = false;
     try {
-      const res = await this.runCommand(args, { cwd: root, timeoutMs: 15_000 });
-      files = res.stdout.split("\n").map((f) => f.trim()).filter(Boolean).map((f) => path.resolve(root, f)).sort();
-    } catch {
-      files = [];
+      const res = await this.runCommand(args, { cwd: root, timeoutMs: 15_000, signal });
+      if (res.exitCode !== 0 && res.exitCode !== 1) error = res.stderr.trim() || "rg exited with status " + res.exitCode;
+      truncated = res.outputTruncated === true;
+      const output = truncated && !res.stdout.endsWith("\n") ? res.stdout.slice(0, res.stdout.lastIndexOf("\n") + 1) : res.stdout;
+      files = output.split("\n").filter(Boolean).map(f => path.resolve(root, f)).sort();
+    } catch (err) {
+      signal?.throwIfAborted();
+      error = err.message;
+      missing = !fs.existsSync(root);
     }
-    this.lists.set(key, { files, at: Date.now() });
+    this.lists.set(key, { files, at: Date.now(), error, truncated, missing });
     return files;
   }
 
@@ -202,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();
@@ -257,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/src/context/snap.js

@@ -0,0 +1,237 @@
+import * as path from "node:path";
+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 { 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", "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_]+/);
+  return {
+    tokens: [...new Set(words.filter(word => word.length > 1 && !STOP_WORDS.has(word)))],
+    wantsTest: words.some(word => ["test", "tests", "testing", "spec", "specs"].includes(word)),
+    wantsType: words.some(word => ["type", "types", "interface", "interfaces", "schema", "schemas"].includes(word)),
+    wantsDoc: words.some(word => ["doc", "docs", "documentation", "readme"].includes(word)),
+  };
+}
+
+export function scorePathTopology(filePath, tokens, flags) {
+  const normalized = filePath.replaceAll("\\", "/").toLowerCase();
+  const parts = normalized.split("/");
+  if (parts.some(part => ["node_modules", "dist", "target"].includes(part))) return -100;
+  const test = isTestPath(normalized);
+  if (test && !flags.wantsTest) return -50;
+  if (!test && flags.wantsTest) return -20;
+  const base = path.basename(normalized);
+  const words = normalized.split(/[^a-zA-Z0-9]+/);
+  const ext = path.extname(normalized);
+  let score = SOURCE_EXT.has(ext) && !flags.wantsDoc ? 5 : 0;
+  if (flags.wantsType && TYPED_EXT.has(ext)) score += 10;
+  for (const token of tokens) {
+    if (base === token || base.startsWith(token + ".")) score += 60;
+    else if (base.includes(token)) score += 30;
+    else if (words.includes(token)) score += 15;
+    else if (normalized.includes(token)) score += 5;
+  }
+  return score;
+}
+
+function inScope(filePath, dir, includeHidden) {
+  const relative = path.relative(dir, filePath);
+  if (relative === ".." || relative.startsWith(".." + path.sep) || path.isAbsolute(relative)) return false;
+  const parts = relative.split(path.sep);
+  return !parts.includes(".git") && (includeHidden || !parts.some(part => part.startsWith(".") && part.length > 1));
+}
+
+function makeCandidate(filePath, dir, query, tokens, flags) {
+  const relative = path.relative(dir, filePath);
+  const lower = relative.toLowerCase();
+  const base = path.basename(lower);
+  const exactPath = lower === query.toLowerCase() || base === query.toLowerCase()
+    || base.slice(0, -path.extname(base).length) === query.toLowerCase();
+  return { path: filePath, pathScore: scorePathTopology(relative, tokens, flags), exactPath,
+    pathCoverage: tokens.filter(token => lower.includes(token)).length,
+    matched: new Set(), exactDefinition: false, definitionCoverage: 0, lineCoverage: 0,
+    line: 1, signature: "", context: new Map(), recent: [], anchorScore: -1 };
+}
+
+function inspectLine(candidate, lineNumber, raw, query, tokens, isMatch) {
+  const text = raw.replace(/\r?\n$/, "");
+  const lower = text.toLowerCase();
+  if (isMatch) {
+    const matches = tokens.filter(token => lower.includes(token));
+    for (const token of matches) candidate.matched.add(token);
+    const ext = path.extname(candidate.path).toLowerCase();
+    const items = SOURCE_EXT.has(ext) ? extractStructuralSurface(text, ext).items : [];
+    let declaration;
+    let definitionCoverage = 0;
+    let exact = false;
+    for (const item of items) {
+      const name = item.name.toLowerCase();
+      const itemExact = name === query.toLowerCase();
+      const coverage = tokens.filter(token => name.includes(token)).length;
+      if (itemExact || coverage > definitionCoverage) { declaration = item; definitionCoverage = coverage; exact = itemExact; }
+      if (exact) break;
+    }
+    const score = (exact ? 10000 : 0) + definitionCoverage * 40 + matches.length;
+    if (score > candidate.anchorScore) {
+      candidate.anchorScore = score;
+      candidate.line = lineNumber;
+      candidate.signature = truncateChars(declaration?.signature ?? "", 240, "signature").text;
+      candidate.exactDefinition = exact;
+      candidate.definitionCoverage = definitionCoverage;
+      candidate.lineCoverage = matches.length;
+      candidate.context.clear();
+      for (const [number, line] of candidate.recent) if (number >= lineNumber - 2) candidate.context.set(number, line);
+    }
+  }
+  const excerpt = truncateChars(text, 240, "source line").text;
+  if (lineNumber >= candidate.line - 2 && lineNumber <= candidate.line + 4) candidate.context.set(lineNumber, excerpt);
+  candidate.recent.push([lineNumber, excerpt]);
+  if (candidate.recent.length > 2) candidate.recent.shift();
+}
+
+function inspectOverlay(candidate, text, needles, query, tokens) {
+  const lines = text.split("\n");
+  const matches = [];
+  for (let i = 0; i < lines.length; i++) if (needles.some(needle => lines[i].toLowerCase().includes(needle))) matches.push(i);
+  for (const i of matches) inspectLine(candidate, i + 1, lines[i], query, tokens, true);
+  candidate.context.clear();
+  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, 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 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) {
+      if (response.outputTruncated && i === records.length - 1) break;
+      throw error;
+    }
+    if (record.type !== "match" && record.type !== "context") continue;
+    const data = record.data;
+    if (!data?.path?.text || !isString(data.lines?.text)) continue;
+    const filePath = path.resolve(dir, data.path.text);
+    if (!inScope(filePath, dir, includeHidden) || overlayText(filePath) !== undefined) continue;
+    let candidate = candidates.get(filePath);
+    if (!candidate) {
+      candidate = makeCandidate(filePath, dir, query, tokens, flags);
+      candidates.set(filePath, candidate);
+    }
+    inspectLine(candidate, data.line_number, data.lines.text, query, tokens, record.type === "match");
+  }
+  for (const filePath of pendingPaths) {
+    const pending = overlayText(filePath);
+    if (pending === undefined) continue;
+    const candidate = makeCandidate(filePath, dir, query, tokens, flags);
+    inspectOverlay(candidate, pending, needles, query, tokens);
+    if (candidate.matched.size) candidates.set(filePath, candidate);
+  }
+  return { candidates, truncated: response.outputTruncated === true };
+}
+
+function rankScore(candidate, tokenCount) {
+  return (candidate.exactDefinition ? 10000 : 0) + (candidate.exactPath ? 500 : 0)
+    + candidate.definitionCoverage / tokenCount * 100 + candidate.matched.size / tokenCount * 30
+    + candidate.pathCoverage / tokenCount * 20 + candidate.lineCoverage / tokenCount * 10
+    + Math.max(-40, Math.min(20, candidate.pathScore / 5));
+}
+
+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, run = runCommand, overlayText = () => undefined, pendingPaths = [], pathContext = {}, signal }) {
+  const flags = tokenizeQuery(query);
+  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();
+  const dir = path.resolve(searchDir || process.cwd());
+  if (dir.split(path.sep).includes(".git")) throw new Error("cannot search Git metadata");
+  signal?.throwIfAborted();
+  flags.wantsTest ||= isTestPath(path.relative(root ?? dir, dir));
+  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: [] };
+  const exact = /^[a-zA-Z_$][\w$]*$/.test(query);
+  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;
+    const candidate = makeCandidate(filePath, dir, query, tokens, flags);
+    if (candidate.pathScore > 0) search.candidates.set(filePath, candidate);
+  }
+  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.outputTruncated === true;
+  const relativeRoot = root ?? dir;
+  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) {
+    // 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;
+  const coverage = Math.max(best.matched.size, best.pathCoverage) / tokens.length;
+  const uniqueExact = best.exactDefinition && !second?.exactDefinition || best.exactPath && !second?.exactPath && !second?.exactDefinition;
+  if (!uniqueExact && (coverage < 0.6 || margin < 0.15 || best.definitionCoverage / tokens.length < 0.5)) return { ...empty, status: "ambiguous", candidates };
+  const confidence = uniqueExact ? 0.95 : Math.min(0.85, 0.5 + coverage * 0.2 + margin * 0.15);
+  return { ...candidates[0], status: "found", confidence: Number(confidence.toFixed(2)) };
+}

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 = [];