pi-supernova 0.0.7 → 0.0.11

package/host-bridge.js

@@ -1,13 +1,18 @@
 
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { spawn } from "node:child_process";
 import { packageHostResult } from "./bottleneck.js";
 import { isString, isNumber, isFunction, isObject } from "./decode.js";
 import { isMutatingTool, runParallelWave } from "./parallel.js";
+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, globToRegExp } from "./repo-index.js";
+import { CausalVfs } from "./vfs.js";
+import { applyPatchToText } from "./patch.js";
+import { resolveWorkspacePath, runCommand, clearPathCache } from "./workspace.js";
 
 function textResult(text, details) {
   return {
@@ -27,341 +32,144 @@ function unwrapIfFullyQuoted(s) {
   return inner;
 }
 
-let cachedCwd = null;
-let cachedResolvedCwd = null;
-
-function getResolvedCwd(cwd) {
-  if (cwd === cachedCwd && cachedResolvedCwd) return cachedResolvedCwd;
-  cachedCwd = cwd;
-  cachedResolvedCwd = path.resolve(cwd);
-  return cachedResolvedCwd;
+function sliceLines(text, offset, limit) {
+  if (!isNumber(offset) && !isNumber(limit)) return text;
+  const lines = text.split("\n");
+  const startIndex = (isNumber(offset) ? Math.max(1, Math.floor(offset)) : 1) - 1;
+  const count = isNumber(limit) ? Math.max(0, Math.floor(limit)) : lines.length;
+  return lines.slice(startIndex, startIndex + count).join("\n");
 }
 
-async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = false) {
-  if (inputPath == null || !isString(inputPath) || !inputPath.trim()) {
-    throw new Error(`${opName} requires path`);
-  }
-  const resolvedCwd = getResolvedCwd(cwd);
-  const target = path.resolve(resolvedCwd, inputPath.trim());
-  const rel = path.relative(resolvedCwd, target);
-  if (rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
-    throw new Error(`${opName} path escapes workspace`);
-  }
-  if (!allowRoot && target === resolvedCwd) {
-    throw new Error(`${opName} path cannot be the workspace root directory`);
-  }
-
-  const realRoot = await fs.realpath(resolvedCwd);
-  let probe = target;
-  while (true) {
-    try {
-      probe = await fs.realpath(probe);
-      break;
-    } catch (err) {
-      if (err?.code !== "ENOENT" && err?.code !== "ENOTDIR") throw err;
-      const parent = path.dirname(probe);
-      if (parent === probe) throw err;
-      probe = parent;
-    }
-  }
-  const realRel = path.relative(realRoot, probe);
-  if (realRel === ".." || realRel.startsWith(`..${path.sep}`) || path.isAbsolute(realRel)) {
-    throw new Error(`${opName} path escapes workspace through symlink`);
-  }
-  return target;
+function looksLikePath(target) {
+  return (
+    isString(target) &&
+    (target.includes("/") ||
+      target.includes("\\") ||
+      target.startsWith(".") ||
+      (!/\s/.test(target) && path.extname(target).length > 0))
+  );
 }
 
-async function runCommand(argv, options = {}) {
-  const cwd = options.cwd || process.cwd();
-  const timeoutMs = options.timeoutMs ?? 60_000;
-  const maxOutputChars = options.maxOutputChars ?? 2 * 1024 * 1024;
-  return await new Promise((resolve, reject) => {
-    const child = spawn(argv[0], argv.slice(1), {
-      cwd,
-      env: process.env,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    let stdout = "";
-    let stderr = "";
-    let settled = false;
-    let outputTruncated = false;
-    let onAbort;
-
-    const cleanup = () => {
-      clearTimeout(timer);
-      if (options.signal && onAbort) options.signal.removeEventListener("abort", onAbort);
-    };
-    const fail = (err) => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      reject(err);
-    };
-    const append = (current, chunk) => {
-      const remaining = Math.max(0, maxOutputChars - current.length);
-      if (chunk.length > remaining) outputTruncated = true;
-      return remaining > 0 ? current + chunk.slice(0, remaining) : current;
-    };
-    const timer = setTimeout(() => {
-      child.kill("SIGTERM");
-      fail(new Error(`command timed out after ${timeoutMs}ms: ${argv.join(" ")}`));
-    }, timeoutMs);
-
-    child.stdout.setEncoding("utf8");
-    child.stderr.setEncoding("utf8");
-    child.stdout.on("data", (chunk) => {
-      stdout = append(stdout, chunk);
-    });
-    child.stderr.on("data", (chunk) => {
-      stderr = append(stderr, chunk);
-    });
-    child.on("error", fail);
-    child.on("close", (code) => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      resolve({ stdout, stderr, exitCode: code ?? 0, outputTruncated });
-    });
-    if (options.signal) {
-      onAbort = () => {
-        child.kill("SIGTERM");
-        fail(new Error("aborted"));
-      };
-      if (options.signal.aborted) onAbort();
-      else options.signal.addEventListener("abort", onAbort, { once: true });
-    }
-  });
-}
-
-function parseHunkHeader(line) {
-  const match = /^@@\s+-(\d+)(?:,(\d+))?\s+\+(\d+)(?:,(\d+))?\s+@@/.exec(line);
-  if (!match) return null;
-  return {
-    oldStart: parseInt(match[1], 10),
-    oldLength: match[2] !== undefined ? parseInt(match[2], 10) : 1,
-    newStart: parseInt(match[3], 10),
-    newLength: match[4] !== undefined ? parseInt(match[4], 10) : 1,
-    lines: [],
-  };
-}
-
-export function parsePatchHunks(patchText) {
-  const patchLines = patchText.replace(/\r\n/g, "\n").split("\n");
-  const hunks = [];
-  let current = null;
-
-  for (const line of patchLines) {
-    const header = parseHunkHeader(line);
-    if (header) {
-      if (current) hunks.push(current);
-      current = header;
-    } else if (current && (line.startsWith("+") || line.startsWith("-") || line.startsWith(" "))) {
-      current.lines.push(line);
-    }
-  }
-  if (current) hunks.push(current);
-  if (hunks.length === 0) {
-    throw new Error("no valid patch hunks found (expected @@ -old,len +new,len @@)");
-  }
-  return hunks;
-}
-
-function findHunkMatch(fileLines, expectedOld, nominal) {
-  const matchAt = (idx) => {
-    if (idx < 0 || idx + expectedOld.length > fileLines.length) return false;
-    for (let j = 0; j < expectedOld.length; j++) {
-      if (fileLines[idx + j] !== expectedOld[j]) return false;
-    }
-    return true;
-  };
-
-  if (matchAt(nominal)) return nominal;
-  const maxDelta = Math.max(fileLines.length, 100);
-  for (let delta = 1; delta <= maxDelta; delta++) {
-    if (matchAt(nominal + delta)) return nominal + delta;
-    if (matchAt(nominal - delta)) return nominal - delta;
+async function probeExistingFile(cwd, targetParam, vfs) {
+  const targetPath = await resolveWorkspacePath(cwd, targetParam, "read", false);
+  if (vfs.getOverlay(targetPath) !== undefined || vfs.cache.has(targetPath)) return targetPath;
+  try {
+    const st = await fs.stat(targetPath);
+    if (st.isDirectory()) throw new Error(`read path is a directory, not a file: ${targetPath} (use ls)`);
+    return targetPath;
+  } catch (err) {
+    if (err?.code !== "ENOENT" && err?.code !== "ENOTDIR") throw err;
+    return null;
   }
-  return -1;
 }
 
-export function applyPatchToText(originalText, patchText) {
-  if (!isString(patchText) || !patchText.trim()) {
-    throw new Error("apply_patch requires non-empty patch");
-  }
-
-  const hunks = parsePatchHunks(patchText);
-  let fileLines = originalText.replace(/\r\n/g, "\n").split("\n");
-  const hasTrailingNewline = originalText.endsWith("\n");
-  let offsetShift = 0;
-
-  for (let h = 0; h < hunks.length; h++) {
-    const hunk = hunks[h];
-    const expectedOld = [];
-    const newLines = [];
-
-    for (const hLine of hunk.lines) {
-      if (hLine.startsWith("-")) {
-        expectedOld.push(hLine.slice(1));
-      } else if (hLine.startsWith("+")) {
-        newLines.push(hLine.slice(1));
-      } else {
-        const val = hLine.startsWith(" ") ? hLine.slice(1) : "";
-        expectedOld.push(val);
-        newLines.push(val);
-      }
-    }
-
-    if (expectedOld.length !== hunk.oldLength || newLines.length !== hunk.newLength) {
-      throw new Error(`patch hunk ${h + 1} length does not match its header`);
-    }
-
-    const nominal = Math.max(0, hunk.oldStart - 1 + offsetShift);
-    const matchIdx = findHunkMatch(fileLines, expectedOld, nominal);
-    if (matchIdx === -1) {
-      throw new Error(`patch hunk ${h + 1} rejected at line ${hunk.oldStart}: context did not match`);
-    }
-
-    fileLines.splice(matchIdx, expectedOld.length, ...newLines);
-    offsetShift += (matchIdx - nominal) + (newLines.length - expectedOld.length);
-  }
-
-  let resultText = fileLines.join("\n");
-  if (hasTrailingNewline && !resultText.endsWith("\n")) resultText += "\n";
-  return { resultText, hunkCount: hunks.length };
+function patchModeOf(params) {
+  return (
+    isString(params?.patch) ||
+    (params?.newText === undefined &&
+      isString(params?.oldText) &&
+      (params.oldText.includes("@@ -") || params.oldText.startsWith("---")))
+  );
 }
 
-const VFS_CACHE_MAX = 1024;
-
-class CausalVfs {
-  constructor() {
-    this.cache = new Map();
-    this.overlays = [];
-  }
-
-  setCache(target, content) {
-    if (this.cache.size >= VFS_CACHE_MAX && !this.cache.has(target)) {
-      const oldest = this.cache.keys().next().value;
-      if (oldest !== undefined) this.cache.delete(oldest);
+function applyReplacements(target, content, requestedEdits) {
+  if (requestedEdits.length === 0) throw new Error("edit requires at least one replacement");
+  const matches = requestedEdits.map((replacement) => {
+    if (!isString(replacement?.oldText) || replacement.oldText.length === 0) {
+      throw new Error("edit requires non-empty oldText");
     }
-    this.cache.set(target, content);
-  }
-
-  getOverlay(target) {
-    for (let i = this.overlays.length - 1; i >= 0; i--) {
-      if (this.overlays[i].has(target)) return this.overlays[i].get(target);
+    if (!isString(replacement?.newText)) throw new Error("edit requires newText");
+    const index = content.indexOf(replacement.oldText);
+    if (index < 0) {
+      throw new Error(`edit target not found in ${target}: oldText must match the file byte-for-byte (read() it first; check whitespace and quotes)`);
     }
-    return undefined;
-  }
-
-  getOverlayPaths() {
-    const paths = new Set();
-    for (const overlay of this.overlays) {
-      for (const target of overlay.keys()) paths.add(target);
+    if (content.indexOf(replacement.oldText, index + replacement.oldText.length) >= 0) {
+      throw new Error(`edit target is not unique in ${target}: include more surrounding lines in oldText, or pass edits:[{oldText,newText},…]`);
     }
-    return [...paths];
-  }
-
-  async read(target) {
-    const overlay = this.getOverlay(target);
-    if (overlay !== undefined) return overlay;
-
-    const cached = this.cache.get(target);
-    if (cached !== undefined) return cached;
-
-    try {
-      const text = await fs.readFile(target, "utf8");
-      this.setCache(target, text);
-      return text;
-    } catch (err) {
-      if (err.code === "EISDIR") {
-        throw new Error(`read path is a directory, not a file: ${target}`);
-      }
-      throw err;
-    }
-  }
-
-  async write(target, content) {
-    if (this.overlays.length > 0) {
-      this.overlays[this.overlays.length - 1].set(target, content);
-      return { speculative: true };
-    }
-
-    try {
-      const stat = await fs.stat(target);
-      if (stat.isDirectory()) {
-        throw new Error(`cannot write to a directory: ${target}`);
-      }
-    } catch (err) {
-      if (err.code !== "ENOENT") throw err;
-    }
-
-    await fs.mkdir(path.dirname(target), { recursive: true });
-    await fs.writeFile(target, content, "utf8");
-    this.setCache(target, content);
-    return { speculative: false };
-  }
-
-  begin() {
-    this.overlays.push(new Map());
-    return this.overlays.length;
-  }
-
-  async commit() {
-    if (this.overlays.length === 0) return { committed: 0, depth: 0 };
-    const top = this.overlays.pop();
-    if (this.overlays.length > 0) {
-      const parent = this.overlays[this.overlays.length - 1];
-      for (const [k, v] of top.entries()) parent.set(k, v);
-      return { committed: top.size, depth: this.overlays.length };
-    }
-    for (const [filePath, fileContent] of top.entries()) {
-      await fs.mkdir(path.dirname(filePath), { recursive: true });
-      await fs.writeFile(filePath, fileContent, "utf8");
-      this.setCache(filePath, fileContent);
-    }
-    return { committed: top.size, depth: 0 };
+    return { ...replacement, index, end: index + replacement.oldText.length };
+  });
+  matches.sort((a, b) => a.index - b.index);
+  for (let i = 1; i < matches.length; i++) {
+    if (matches[i].index < matches[i - 1].end) throw new Error(`edit targets overlap in ${target}`);
   }
-
-  rollback() {
-    if (this.overlays.length === 0) return { rolledBack: 0, depth: 0 };
-    const top = this.overlays.pop();
-    return { rolledBack: top.size, depth: this.overlays.length };
+  let updated = content;
+  for (let i = matches.length - 1; i >= 0; i--) {
+    const match = matches[i];
+    updated = updated.slice(0, match.index) + match.newText + updated.slice(match.end);
   }
+  return { updated, matches };
+}
 
-  async prepareExternalMutation(name) {
-    if (this.overlays.length > 1) {
-      throw new Error(`${name} cannot run inside nova.speculate because external mutations cannot be rolled back`);
-    }
-    if (this.overlays.length === 0) return false;
-    const pending = this.overlays[0];
-    for (const [filePath, fileContent] of pending.entries()) {
-      await fs.mkdir(path.dirname(filePath), { recursive: true });
-      await fs.writeFile(filePath, fileContent, "utf8");
-      this.setCache(filePath, fileContent);
+async function formatLsEntry(dirPath, entry) {
+  const isDir = entry.isDirectory();
+  const isSym = entry.isSymbolicLink();
+  const typeLabel = isDir ? "dir" : isSym ? "sym" : "file";
+  let size = 0;
+  try {
+    if (!isDir && !isSym) {
+      const st = await fs.stat(path.join(dirPath, entry.name));
+      size = st.size;
     }
-    this.overlays[0] = new Map();
-    return pending.size > 0;
-  }
+  } catch {}
+  const sizeSuffix = size ? `, ${size} bytes` : "";
+  return `${entry.name}${isDir ? "/" : ""} (${typeLabel}${sizeSuffix})`;
+}
 
-  invalidateCache() {
-    this.cache.clear();
-  }
+function rgGrepArgs(pattern, params, searchPath) {
+  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);
+  return args;
+}
 
-  clear() {
-    this.invalidateCache();
-    this.overlays.length = 0;
-  }
+/** rg --files, then find(1) when rg is unavailable; both accept an optional glob/name pattern. */
+async function listWithTools(searchDir, pattern, cwd, signal) {
+  const args = ["--files"];
+  if (pattern) args.push("-g", 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", pattern);
+  const findRes = await runCommand(["find", ...findArgs], { cwd, timeoutMs: 30_000, signal });
+  return textResult(findRes.stdout, { via: "find" });
+}
 
-  getCacheSize() {
-    return this.cache.size;
-  }
+/** rg-compatible grep served from the index; null when the pattern or tree needs real rg. */
+async function grepIndexed(index, pattern, params, searchPath, cwd) {
+  let regex;
+  try {
+    regex = new RegExp(pattern, params?.caseSensitive === true ? "" : "i");
+  } catch {
+    return null;
+  }
+  let files = await index.files(searchPath);
+  if (!index.canScan(files)) return null;
+  if (params?.glob) {
+    const matcher = globToRegExp(String(params.glob));
+    files = files.filter((f) => matcher.test(path.relative(cwd, f).split(path.sep).join("/")));
+  }
+  const rows = index.grep(files, regex, cwd);
+  return rows.length ? rows.join("\n") + "\n" : "";
+}
 
-  getOverlayDepth() {
-    return this.overlays.length;
-  }
+/** rg --files [-g pattern] served from the index; null when the tree is too large. */
+async function listIndexed(index, root, cwd, pattern) {
+  const files = await index.files(root);
+  if (!index.canScan(files)) return null;
+  const rel = files.map((f) => path.relative(cwd, f).split(path.sep).join("/"));
+  if (!pattern) return rel.length ? rel.join("\n") + "\n" : "";
+  let matcher;
+  try {
+    matcher = globToRegExp(pattern);
+  } catch {
+    return null;
+  }
+  const hits = rel.filter((f) => matcher.test(f));
+  return hits.length ? hits.join("\n") + "\n" : "";
 }
 
-function createNativeAdapters(getCwd, vfs, config) {
+function createNativeAdapters(getCwd, vfs, config, index) {
   async function readAdapter(params, signal) {
       const cwd = getCwd();
       const targetParam = params?.path ?? params?.target;
@@ -370,57 +178,20 @@ function createNativeAdapters(getCwd, vfs, config) {
         const results = await Promise.all(
           targetParam.map((p) => readAdapter({ path: p, offset: params?.offset, limit: params?.limit }, signal)),
         );
-        return textResult(results.map((r) => r.value).join("\n---\n"), {
-          count: results.length,
-          batch: true,
-          items: results.map((r) => r.value),
-        });
+        const items = results.map((r) => r.content[0].text);
+        return textResult(items.join("\n---\n"), { count: results.length, batch: true, items });
       }
 
-      const looksLikePath =
-        isString(targetParam) &&
-        (targetParam.includes("/") ||
-          targetParam.includes("\\") ||
-          targetParam.startsWith(".") ||
-          (!/\s/.test(targetParam) && path.extname(targetParam).length > 0));
-
-      if (looksLikePath) {
+      if (looksLikePath(targetParam)) {
         const targetPath = await resolveWorkspacePath(cwd, targetParam, "read", false);
-        let text = await vfs.read(targetPath);
-        if (isNumber(params?.offset) || isNumber(params?.limit)) {
-          const lines = text.split("\n");
-          const offset = isNumber(params?.offset) ? Math.max(1, Math.floor(params.offset)) : 1;
-          const startIndex = offset - 1;
-          const limit = isNumber(params?.limit) ? Math.max(0, Math.floor(params.limit)) : lines.length;
-          text = lines.slice(startIndex, startIndex + limit).join("\n");
-        }
-        return textResult(text, { path: targetPath });
-      }
-
-      let isExistingFile = false;
-      let targetPath = await resolveWorkspacePath(cwd, targetParam, "read", false);
-      const overlay = vfs.getOverlay(targetPath);
-      if (overlay !== undefined || vfs.cache.has(targetPath)) {
-        isExistingFile = true;
-      } else {
-        try {
-          const st = await fs.stat(targetPath);
-          isExistingFile = !st.isDirectory();
-        } catch (err) {
-          if (err?.code !== "ENOENT" && err?.code !== "ENOTDIR") throw err;
-        }
+        const text = await vfs.read(targetPath);
+        return textResult(sliceLines(text, params?.offset, params?.limit), { path: targetPath });
       }
 
-      if (isExistingFile) {
-        let text = await vfs.read(targetPath);
-        if (isNumber(params?.offset) || isNumber(params?.limit)) {
-          const lines = text.split("\n");
-          const offset = isNumber(params?.offset) ? Math.max(1, Math.floor(params.offset)) : 1;
-          const startIndex = offset - 1;
-          const limit = isNumber(params?.limit) ? Math.max(0, Math.floor(params.limit)) : lines.length;
-          text = lines.slice(startIndex, startIndex + limit).join("\n");
-        }
-        return textResult(text, { path: targetPath });
+      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 (isString(targetParam) && targetParam.trim()) {
@@ -428,24 +199,17 @@ function createNativeAdapters(getCwd, vfs, config) {
           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 {}
       }
 
-      targetPath = await resolveWorkspacePath(cwd, targetParam, "read", false);
-
-      let text = await vfs.read(targetPath);
-      if (isNumber(params?.offset) || isNumber(params?.limit)) {
-        const lines = text.split("\n");
-        const offset = isNumber(params?.offset) ? Math.max(1, Math.floor(params.offset)) : 1;
-        const startIndex = offset - 1;
-        const limit = isNumber(params?.limit) ? Math.max(0, Math.floor(params.limit)) : lines.length;
-        text = lines.slice(startIndex, startIndex + limit).join("\n");
-      }
-      return textResult(text, { path: targetPath });
+      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 {
@@ -469,11 +233,7 @@ function createNativeAdapters(getCwd, vfs, config) {
       const target = await resolveWorkspacePath(cwd, params?.path, "edit", false);
       if (signal?.aborted) throw new Error("aborted");
 
-      const isPatchMode =
-        isString(params?.patch) ||
-        (params?.newText === undefined && isString(params?.oldText) && (params.oldText.includes("@@ -") || params.oldText.startsWith("---")));
-
-      if (isPatchMode) {
+      if (patchModeOf(params)) {
         const patchContent = params.patch || params.oldText;
         const original = await vfs.read(target);
         const { resultText, hunkCount } = applyPatchToText(original, patchContent);
@@ -491,31 +251,8 @@ function createNativeAdapters(getCwd, vfs, config) {
       const requestedEdits = Array.isArray(params?.edits)
         ? params.edits
         : [{ oldText: params?.oldText, newText: params?.newText }];
-      if (requestedEdits.length === 0) throw new Error("edit requires at least one replacement");
-
       const content = await vfs.read(target);
-      const matches = requestedEdits.map((replacement) => {
-        if (!isString(replacement?.oldText) || replacement.oldText.length === 0) {
-          throw new Error("edit requires non-empty oldText");
-        }
-        if (!isString(replacement?.newText)) throw new Error("edit requires newText");
-        const index = content.indexOf(replacement.oldText);
-        if (index < 0) throw new Error(`edit target not found in ${target}`);
-        if (content.indexOf(replacement.oldText, index + replacement.oldText.length) >= 0) {
-          throw new Error(`edit target is not unique in ${target}`);
-        }
-        return { ...replacement, index, end: index + replacement.oldText.length };
-      });
-      matches.sort((a, b) => a.index - b.index);
-      for (let i = 1; i < matches.length; i++) {
-        if (matches[i].index < matches[i - 1].end) throw new Error(`edit targets overlap in ${target}`);
-      }
-
-      let updated = content;
-      for (let i = matches.length - 1; i >= 0; i--) {
-        const match = matches[i];
-        updated = updated.slice(0, match.index) + match.newText + updated.slice(match.end);
-      }
+      const { updated, matches } = applyReplacements(target, content, requestedEdits);
       const { speculative } = await vfs.write(target, updated);
       const diff =
         matches.length === 1
@@ -563,19 +300,25 @@ 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 });
+      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);
@@ -606,8 +349,10 @@ function createNativeAdapters(getCwd, vfs, config) {
         });
       } finally {
         vfs.invalidateCache();
+        index.invalidate();
       }
-      const text = [res.stdout, res.stderr].filter(Boolean).join("\n");
+      const { stdout, stderr } = res;
+      const text = stdout && stderr ? stdout + (stdout.endsWith("\n") ? "" : "\n") + stderr : stdout || stderr;
       return {
         content: [{ type: "text", text }],
         details: { exitCode: res.exitCode, outputTruncated: res.outputTruncated, transactionBarrier },
@@ -619,11 +364,9 @@ 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" });
+      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}`);
       }
@@ -633,6 +376,8 @@ function createNativeAdapters(getCwd, vfs, config) {
       const cwd = getCwd();
       const pattern = String(params?.pattern || "");
       if (!pattern) throw new Error("glob requires pattern");
+      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,
       );
@@ -652,16 +397,10 @@ 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 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();
@@ -670,17 +409,7 @@ function createNativeAdapters(getCwd, vfs, config) {
       const entries = await fs.readdir(dirPath, { withFileTypes: true });
       const lines = [];
       for (const entry of entries) {
-        const isDir = entry.isDirectory();
-        const isSym = entry.isSymbolicLink();
-        const typeLabel = isDir ? "dir" : isSym ? "sym" : "file";
-        let size = 0;
-        try {
-          if (!isDir && !isSym) {
-            const st = await fs.stat(path.join(dirPath, entry.name));
-            size = st.size;
-          }
-        } catch {}
-        lines.push(`${entry.name}${isDir ? "/" : ""} (${typeLabel}${size ? `, ${size} bytes` : ""})`);
+        lines.push(await formatLsEntry(dirPath, entry));
       }
       return textResult(lines.join("\n"), { path: dirPath, count: entries.length });
     },
@@ -688,9 +417,10 @@ 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 vfs = new CausalVfs(() => index.invalidate());
   const executors = new Map();
-  const natives = createNativeAdapters(getCwd, vfs, config);
+  const natives = createNativeAdapters(getCwd, vfs, config, index);
   let callCount = 0;
   let activeCtx = null;
   let activeSignal = undefined;
@@ -722,6 +452,9 @@ export function createHostBridge({ pi, config, getCwd }) {
   function resetCallBudget() {
     callCount = 0;
     trace = [];
+    // Files may change between programs (editor, git); never serve a stale run.
+    vfs.invalidateCache();
+    clearPathCache();
   }
 
   function getTrace() {
@@ -771,15 +504,19 @@ export function createHostBridge({ pi, config, getCwd }) {
     } catch {}
   }
 
-  async function invokeRaw(name, args) {
+  function checkCallBudget(name) {
     const maxCalls = config.maxBridgeCalls ?? 256;
     callCount += 1;
     if (callCount > maxCalls) {
-      throw new Error(`supernova host call budget exceeded (${maxCalls})`);
+      throw new Error(
+        `host call budget exceeded (${maxCalls} calls per program): batch with read([paths]) or nova.callMany, or split the work across programs`,
+      );
     }
     if (activeSignal?.aborted) throw new Error("aborted");
     if (!isString(name) || !name) throw new Error("tool name required");
+  }
 
+  function assertCallableTarget(name) {
     // Never re-enter supernova or other excluded composition tools via the bridge.
     const excluded = new Set(config.excludeTools || []);
     if (name === "supernova" || excluded.has(name)) {
@@ -787,6 +524,30 @@ export function createHostBridge({ pi, config, getCwd }) {
         `nova.call("${name}") is blocked (excluded / non-reentrant). Use nova.search/describe for discovery, or call a concrete host tool.`,
       );
     }
+  }
+
+  async function writeFallbackDiff(name, args) {
+    if (name !== "write" || !isString(args?.path) || !isString(args?.content)) return undefined;
+    const target = await resolveWorkspacePath(getCwd(), args.path, "write", false);
+    let previous = "";
+    try {
+      previous = await vfs.read(target);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+    return buildWriteDiff(target, previous, args.content);
+  }
+
+  function completeRecord(record, res, fallbackDiff) {
+    const diff = resultDiff(res) || fallbackDiff;
+    finishRecord(record, res);
+    if (diff && record.ok) record.diff = diff;
+    notifyCall(record);
+  }
+
+  async function invokeRaw(name, args) {
+    checkCallBudget(name);
+    assertCallableTarget(name);
 
     const record = { name, args: args || {}, time: Date.now() };
     trace.push(record);
@@ -795,46 +556,37 @@ export function createHostBridge({ pi, config, getCwd }) {
     try {
       const exec = executors.get(name);
       if (exec) {
-        let fallbackDiff;
-        if (name === "write" && isString(args?.path) && isString(args?.content)) {
-          const target = await resolveWorkspacePath(getCwd(), args.path, "write", false);
-          let previous = "";
-          try {
-            previous = await vfs.read(target);
-          } catch (error) {
-            if (error?.code !== "ENOENT") throw error;
-          }
-          fallbackDiff = buildWriteDiff(target, previous, args.content);
-        }
+        const fallbackDiff = await writeFallbackDiff(name, args);
         if (isMutatingTool(name, config)) await vfs.prepareExternalMutation(name);
         const res = await exec(`supernova:${name}:${callCount}`, args || {}, activeSignal, undefined, activeCtx);
-        const diff = resultDiff(res) || fallbackDiff;
-        record.ok = res?.isError !== true && res?.details?.ok !== false;
-        if (diff && record.ok) record.diff = diff;
-        notifyCall(record);
+        completeRecord(record, res, fallbackDiff);
         return res;
       }
 
       const native = natives[name];
       if (native) {
         const res = await native(args || {}, activeSignal);
-        const diff = resultDiff(res);
-        record.ok = res?.isError !== true && res?.details?.ok !== false;
-        if (diff && record.ok) record.diff = diff;
-        notifyCall(record);
+        completeRecord(record, res);
         return res;
       }
 
-      throw new Error(
-        `no executor for tool "${name}" (not captured via registerTool and no native adapter). Use nova.describe to inspect; ensure pi-supernova loads before other extensions, or call a core adapter: ${Object.keys(natives).join(", ")}`,
-      );
+      throw new Error(unknownToolMessage(name, [...executors.keys(), ...Object.keys(natives)]));
     } catch (error) {
       record.ok = false;
+      record.ms = Date.now() - record.time;
+      record.error = error instanceof Error ? error.message : String(error);
       notifyCall(record);
       throw error;
     }
   }
 
+  function finishRecord(record, res) {
+    record.ms = Date.now() - record.time;
+    record.ok = res?.isError !== true && res?.details?.ok !== false;
+    const exitCode = isObject(res?.details) ? res.details.exitCode : undefined;
+    if (Number.isInteger(exitCode) && exitCode !== 0) record.exitCode = exitCode;
+  }
+
   async function call(name, args) {
     if (!isString(name) || !name) throw new Error("nova.call requires a tool name");
     const raw = await invokeRaw(name, args);