pi-supernova 0.2.0 → 0.3.1

package/{host-bridge.js → src/bridge/host-bridge.js}

@@ -1,23 +1,24 @@
 
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { packageHostResult, hostResultFailed } from "./bottleneck.js";
-import { isString, isNumber, isFunction, isObject } from "./decode.js";
-import { isMutatingTool, runParallelWave } from "./parallel.js";
+import { homedir } from "node:os";
+import { packageHostResult, hostResultFailed } from "../output/bottleneck.js";
+import { isString, isNumber, isFunction, isObject } from "../shared/decode.js";
+import { isMutatingTool, runParallelWave, createNativeScheduler } from "../runtime/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 } from "./repo-index.js";
-import { outlineFile } from "./outline.js";
-import { SeenLedger } from "./ledger.js";
-import { quickCheck } from "./check.js";
-import { declaredName } from "./repo-index.js";
-import { CausalVfs } from "./vfs.js";
-import { applyPatchToText } from "./patch.js";
-import { resolveWorkspacePath, runCommand, clearPathCache, relativeSlash } from "./workspace.js";
-import { fuzzyFind, grepIndexed, listIndexed, listWithTools, rgGrepArgs } from "./search.js";
+import { extractStructuralSurface } from "../context/surface.js";
+import { buildEditDiff, buildMultiEditDiff, buildPatchDiff, buildWriteDiff } from "../fs/diff.js";
+import { executeSnap } from "../context/snap.js";
+import { selectEvidence } from "../context/evidence.js";
+import { WorkspaceIndex } from "../context/repo-index.js";
+import { outlineFile } from "../context/outline.js";
+import { SeenLedger } from "../context/ledger.js";
+import { quickCheck } from "../fs/check.js";
+import { declaredName } from "../context/repo-index.js";
+import { CausalVfs } from "../fs/vfs.js";
+import { applyPatchToText } from "../fs/patch.js";
+import { resolveWorkspacePath, runCommand, clearPathCache, relativeSlash } from "../fs/workspace.js";
+import { fuzzyFind, grepIndexed, listIndexed, listWithTools, rgGrepArgs, referencesForNames } from "../context/search.js";
 
 function textResult(text, details) {
   return {
@@ -55,9 +56,15 @@ function looksLikePath(target) {
   );
 }
 
+function resolveReadPath(cwd, target) {
+  if (!isString(target) || !target.trim()) throw new Error("read requires path");
+  const input = target.trim();
+  return path.resolve(cwd, input === "~" ? homedir() : input.startsWith("~/") ? path.join(homedir(), input.slice(2)) : input);
+}
+
 async function probeExistingPath(cwd, targetParam, vfs) {
-  const targetPath = await resolveWorkspacePath(cwd, targetParam, "read", true);
-  if (vfs.getOverlay(targetPath) !== undefined || vfs.cache.has(targetPath)) return { path: targetPath, directory: false };
+  const targetPath = resolveReadPath(cwd, targetParam);
+  if (vfs.getOverlay(targetPath) !== undefined) return { path: targetPath, directory: false };
   try {
     const st = await fs.stat(targetPath);
     return { path: targetPath, directory: st.isDirectory() };
@@ -115,14 +122,30 @@ async function formatLsEntry(dirPath, entry) {
   return formatDirectoryEntry(entry.name, typeLabel, size);
 }
 
-function createNativeAdapters(getCwd, vfs, config, index, ledger) {
-  async function sourceRead(query, searchDir, signal) {
+function createNativeAdapters(getCwd, vfs, config, index, ledger, hooks) {
+  const reads = createNativeScheduler();
+  async function sourceRead(query, searchDir, signal, params = {}) {
     const cwd = getCwd();
     const includeHidden = path.relative(cwd, searchDir).split(path.sep)
       .some(segment => segment.startsWith(".") && segment.length > 1);
-    const result = await executeSnap({ query, searchDir, root: cwd, includeHidden, index,
+    const result = await executeSnap({ query, searchDir, root: cwd, includeHidden,
+      pathContext: { frecency: index.frecency, currentFile: index.lastTouched },
       overlayText: p => vfs.getOverlay(p), pendingPaths: vfs.getOverlayPaths(), signal });
-    return textResult(JSON.stringify(result, null, 2), { ...result, isSnap: true });
+    return openSource(result, params, signal);
+  }
+
+  async function openSource(result, params, signal) {
+    const cwd = getCwd();
+    if (result.status !== "found") return textResult(JSON.stringify(result), { isSnap: true });
+    signal?.throwIfAborted();
+    const opened = await readFile(path.resolve(cwd, result.path), { ...params, about: undefined }, result.line);
+    const block = opened.content[0];
+    if (block.type !== "text") throw new Error("source resolution requires a text file; read the image path directly");
+    const { firstLine, lastLine, sourceChars, nextOffset, complete } = opened.details;
+    const source = { status: "found", path: result.path, line: result.line, lines: [firstLine, lastLine],
+      text: block.text.slice(0, sourceChars), complete, nextOffset };
+    return textResult(params.resolve ? JSON.stringify(source) : "// " + result.path + ":" + firstLine + "-" + lastLine + "\n" + block.text,
+      { ...opened.details, isSnap: true });
   }
 
   async function readDirectory(dirPath, signal) {
@@ -150,28 +173,55 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger) {
     const cwd = getCwd();
     const targetParam = params?.path ?? params?.target;
     if (Array.isArray(targetParam)) {
-      const results = await Promise.all(targetParam.map(p => readAdapter({ ...params, path: p }, signal)));
-      return textResult("", { count: results.length, batch: true, items: results.map(r => r.content[0].text) });
+      if (targetParam.some(p => !isString(p) || !p.trim())) throw new Error("read paths must be non-empty strings");
+      if (targetParam.length > 64) throw new Error("read accepts at most 64 paths per batch");
+      const results = await Promise.all(targetParam.map(async p => {
+        try {
+          const block = (await readAdapter({ ...params, path: p }, signal)).content[0];
+          return { text: block.type === "image" ? block : block.text };
+        } catch (error) {
+          signal?.throwIfAborted();
+          return { text: `[read error: ${p}] ${error.message}`, error: { path: p, message: error.message } };
+        }
+      }));
+      signal?.throwIfAborted();
+      return textResult("", { count: results.length, batch: true, independent: params._independent === true, items: results.map(r => r.text), itemErrors: results.map(r => r.error?.message ?? null), errors: results.filter(r => r.error).map(r => r.error) });
+    }
+    return reads.schedule("read", () => readSingle(params, cwd, targetParam, signal), signal);
+  }
+
+  async function readSingle(params, cwd, targetParam, signal) {
+    if (isString(params?.query)) {
+      const scope = targetParam && targetParam !== params.query ? resolveReadPath(cwd, targetParam) : cwd;
+      return sourceRead(params.query, scope, signal, params);
     }
     const existing = await probeExistingPath(cwd, targetParam, vfs);
     if (existing) {
-      if (!existing.directory) return readFile(existing.path, params);
-      return isString(params?.about) ? sourceRead(params.about, existing.path, signal) : readDirectory(existing.path, signal);
+      if (!existing.directory) return params.resolve
+        ? openSource({ status: "found", path: relativeSlash(cwd, existing.path), line: params.offset ?? 1 }, params, signal)
+        : readFile(existing.path, params);
+      return isString(params?.about) ? sourceRead(params.about, existing.path, signal, params) : readDirectory(existing.path, signal);
     }
-    if (!looksLikePath(targetParam)) return sourceRead(targetParam, cwd, signal);
-    const targetPath = await resolveWorkspacePath(cwd, targetParam, "read", false);
+    if (!looksLikePath(targetParam)) return sourceRead(targetParam, cwd, signal, params);
+    const targetPath = resolveReadPath(cwd, targetParam);
     return readFile(targetPath, params);
   }
 
   /** Plain text, a line window, or (with `about`) a relevance-folded outline of the whole file. */
-  async function readFile(targetPath, params) {
+  async function readFile(targetPath, params, sourceLine) {
     const cwd = getCwd();
     const rel = relativeSlash(cwd, targetPath);
+    const mime = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp", ".bmp": "image/bmp" }[path.extname(targetPath).toLowerCase()];
+    if (mime) {
+      if ((await fs.stat(targetPath)).size > 20 * 1024 * 1024) throw new Error("image exceeds 20 MiB; resize it before reading");
+      const staged = vfs.getOverlay(targetPath);
+      const bytes = staged === undefined ? await fs.readFile(targetPath) : Buffer.from(staged);
+      return { content: [{ type: "image", mimeType: mime, data: bytes.toString("base64") }], details: { path: targetPath } };
+    }
     const text = await vfs.read(targetPath);
     index.touch(rel);
     if (isString(params?.about)) {
-      const pending = vfs.getOverlay(targetPath);
-      const entry = pending === undefined ? index.entry(targetPath) : WorkspaceIndex.fromText(targetPath, pending);
+      const entry = WorkspaceIndex.fromText(targetPath, text);
       const outline = entry && outlineFile(entry, rel, params.about, outlineOptions(params, await referenceFinder(cwd, targetPath)));
       if (outline) {
         recordOutlineOrigins(rel, outline.text);
@@ -179,65 +229,115 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger) {
       }
     }
     const explicit = isNumber(params?.offset) || isNumber(params?.limit);
-    const firstLine = isNumber(params?.offset) ? Math.max(1, Math.floor(params.offset)) : 1;
-    const sliced = sliceLines(text, params?.offset, params?.limit);
+    const budget = Math.max(1, Math.min(config.maxCallResultChars ?? 65536, config.maxReturnChars ?? 32000) - (params.resolve ? 1024 : 256));
+    const offset = params?.offset ?? (sourceLine && text.length > budget ? Math.max(1, sourceLine - 2) : 1);
+    const firstLine = isNumber(offset) ? Math.max(1, Math.floor(offset)) : 1;
+    const sliced = sliceLines(text, offset, params?.limit);
+    if (sliced.length > budget || (params.resolve && JSON.stringify(sliced).length > budget)) {
+      let cap = budget - 160;
+      if (params.resolve) {
+        // Budget the actual JSON string, not a pessimistic fixed escape multiplier.
+        let low = 0, high = Math.max(0, cap);
+        while (low < high) {
+          const mid = Math.ceil((low + high) / 2);
+          if (JSON.stringify(sliced.slice(0, mid)).length <= budget - 160) low = mid;
+          else high = mid - 1;
+        }
+        cap = low;
+      }
+      const end = sliced.lastIndexOf("\n", cap);
+      if (end < 0) throw new Error(`line ${firstLine} exceeds the read budget; use bash to inspect a bounded substring`);
+      const body = sliced.slice(0, end + 1);
+      const next = firstLine + body.split("\n").length - 1;
+      return textResult(body + `\n[read truncated; continue with read({path:${JSON.stringify(rel)}, offset:${next}})]`, { path: targetPath, outputTruncated: true, nextOffset: next, firstLine, lastLine: next - 1, sourceChars: body.length, complete: false });
+    }
     ledger.recordOrigin(rel, firstLine, sliced.split("\n"), explicit);
-    return textResult(sliced, { path: targetPath });
+    return textResult(sliced, { path: targetPath, firstLine, lastLine: firstLine + sliced.split("\n").length - 1 - Number(sliced.endsWith("\n")), sourceChars: sliced.length, complete: sliced === text });
   }
 
   /**
    * The edit result answers the follow-ups a model would otherwise spend turns on: the post-edit
-   * lines with numbers (so no verification re-read), a quick structural check, and every other
-   * place a changed declaration is referenced (so callers are not forgotten).
+   * lines with numbers, a quick structural check, and bounded lexical reference hints.
+   * These do not replace tests or semantic caller resolution.
    */
-  async function editSummary(cwd, target, original, updated, diff) {
+  async function editSummary(cwd, target, original, updated, diff, signal) {
     const rel = relativeSlash(cwd, target);
     const newLines = updated.split("\n");
-    const added = diff.lines.filter((l) => l.type === "add");
-    const first = added.length ? Math.max(1, added[0].lineNum - 2) : 1;
-    const last = added.length ? Math.min(newLines.length, added[added.length - 1].lineNum + 2) : Math.min(newLines.length, first + 6);
-    const window = [];
-    for (let l = first; l <= last && window.length < 40; l++) window.push(String(l).padStart(5) + " " + newLines[l - 1]);
-    ledger.recordOrigin(rel, first, newLines.slice(first - 1, first - 1 + window.length));
-    let out = `edited ${rel}:${first}–${first + window.length - 1}\n${window.join("\n")}`;
+    const ranges = [];
+    const positions = diff.lines.filter(row => row.type !== "context")
+      .map(row => Math.min(newLines.length, row.newLineNum ?? row.lineNum)).sort((a, b) => a - b);
+    for (const line of positions) {
+      const start = Math.max(1, line - 2), end = Math.min(newLines.length, line + 2);
+      if (ranges.length && start <= ranges.at(-1).end + 1) ranges.at(-1).end = Math.max(ranges.at(-1).end, end);
+      else ranges.push({ start, end });
+    }
+    const blocks = [];
+    const perRange = Math.max(1, Math.floor(40 / Math.max(1, ranges.length)));
+    for (const { start, end } of ranges) {
+      const last = Math.min(end, start + perRange - 1);
+      const lines = newLines.slice(start - 1, last);
+      ledger.recordOrigin(rel, start, lines);
+      blocks.push("edited " + rel + ":" + start + "-" + last + "\n" + lines.map((line, i) => String(start + i).padStart(5) + " " + line).join("\n"));
+      if (last < end) blocks.push("[continue with read({path:" + JSON.stringify(rel) + ",offset:" + (last + 1) + ",limit:" + (end - last) + "})]");
+    }
+    let out = blocks.join("\n");
     const check = quickCheck(updated, path.extname(target));
     if (check && !check.ok) out += `\ncheck: ${check.message}`;
-    const refs = await changedDeclarationRefs(cwd, target, original, updated, diff);
+    const refs = await changedDeclarationRefs(cwd, target, original, updated, diff, signal);
     if (refs) out += `\n${refs}`;
     return out;
   }
 
-  async function changedDeclarationRefs(cwd, target, original, updated, diff) {
+  async function changedDeclarationRefs(cwd, target, original, updated, diff, signal) {
     // Diff rows carry the replaced fragments; declarations live on whole file lines.
     const oldLines = original.split("\n");
     const newLines = updated.split("\n");
     const names = new Set();
+    const spans = new Map();
     for (const l of diff.lines) {
       if (l.type === "context") continue;
-      const name = declaredName((l.type === "remove" ? oldLines : newLines)[l.lineNum - 1] ?? "");
+      const number = l.type === "remove" ? l.lineNum : l.newLineNum ?? l.lineNum;
+      const name = declaredName((l.type === "remove" ? oldLines : newLines)[number - 1] ?? "");
       if (name) names.add(name);
+      else {
+        if (!spans.has(l.type)) spans.set(l.type, WorkspaceIndex.spansOf(WorkspaceIndex.fromText(target, l.type === "remove" ? original : updated)));
+        const owner = spans.get(l.type).find(span => span.start <= number && number <= span.end);
+        if (owner?.name) names.add(owner.name);
+      }
+      if (names.size >= 3) break;
     }
     if (names.size === 0) return "";
-    const find = await referenceFinder(cwd, target);
-    const parts = [];
-    for (const name of [...names].slice(0, 3)) {
-      const refs = find(name).filter((r) => !r.startsWith(relativeSlash(cwd, target) + ":"));
-      if (refs.length) parts.push(`${name} also referenced in ${refs.slice(0, 6).join(", ")}${refs.length > 6 ? " (+" + (refs.length - 6) + ")" : ""}`);
+    try {
+      const { references, incomplete } = await referencesForNames({ root: cwd, names: [...names].slice(0, 3),
+        excludePath: target, overlayText: file => vfs.getOverlay(file), pendingPaths: vfs.getOverlayPaths(), signal });
+      const parts = [];
+      for (const [name, refs] of references) {
+        if (refs.length) parts.push(name + " also referenced in " + refs.slice(0, 6).join(", ") + (refs.length > 6 ? " (more matches)" : ""));
+      }
+      if (incomplete) parts.push("references incomplete: search budget reached");
+      return parts.join("\n");
+    } catch (error) {
+      signal?.throwIfAborted();
+      return "references unavailable: " + error.message;
     }
-    return parts.join("\n");
   }
 
-  const SOURCE_REF = /((?:[\w.@-]+\/)*[\w.@-]+\.(?:m?[jt]sx?|c[jt]s|py|rs|go|java|kt|rb|php|c|cc|cpp|h|hpp|cs|swift|json|ya?ml|toml))(?::|\()(\d+)/g;
+  const SOURCE_REF = /((?:\/|[A-Za-z]:[\\/])?(?:[\w.@-]+[\\/])*[\w.@-]+\.(?:m?[jt]sx?|c[jt]s|py|rs|go|java|kt|rb|php|c|cc|cpp|h|hpp|cs|swift|json|ya?ml|toml))(?::|\()(\d+)/g;
 
-  /** Source window (±2 lines, ► on the cited line) for one path:line, or null when it is outside the workspace/index. */
-  function sourceWindow(cwd, file, lineNo) {
-    const candidate = path.resolve(cwd, file);
-    if (!candidate.startsWith(path.resolve(cwd) + path.sep)) return null;
-    const entry = index.entry(candidate);
-    if (!entry) return null;
-    const { raw } = WorkspaceIndex.linesOf(entry);
+  /** Fresh bounded source window for a diagnostic; no index warmup or stale cached bodies. */
+  async function sourceWindow(cwd, commandCwd, file, lineNo) {
+    const candidate = path.resolve(commandCwd, file);
+    let text, rel;
+    try {
+      const root = await fs.realpath(cwd);
+      if (!candidate.startsWith(path.resolve(cwd) + path.sep) && !candidate.startsWith(root + path.sep)) return null;
+      const real = await fs.realpath(candidate);
+      if (!real.startsWith(root + path.sep) || (await fs.stat(real)).size > 1024 * 1024) return null;
+      text = await fs.readFile(real, "utf8");
+      rel = relativeSlash(root, real);
+    } catch { return null; }
+    const raw = text.split("\n");
     if (lineNo < 1 || lineNo > raw.length) return null;
-    const rel = relativeSlash(cwd, candidate);
     const start = Math.max(1, lineNo - 2);
     const rows = [];
     for (let l = start; l <= Math.min(raw.length, lineNo + 2); l++) rows.push((l === lineNo ? "►" : " ") + String(l).padStart(4) + " " + raw[l - 1]);
@@ -246,16 +346,16 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger) {
   }
 
   /** A failing command names path:line; the model wants those lines next. Attach them (≤4 sites). */
-  function sourceForReferences(cwd, output) {
+  async function sourceForReferences(cwd, commandCwd, output) {
     const seen = new Set();
     const blocks = [];
     for (const m of output.matchAll(SOURCE_REF)) {
       const key = m[1] + ":" + m[2];
       if (seen.has(key)) continue;
+      if (seen.size >= 4) break;
       seen.add(key);
-      const block = sourceWindow(cwd, m[1], Number(m[2]));
+      const block = await sourceWindow(cwd, commandCwd, m[1], Number(m[2]));
       if (block) blocks.push(block);
-      if (blocks.length >= 4) break;
     }
     return blocks.length ? "\n--- source\n" + blocks.join("\n") : "";
   }
@@ -276,19 +376,20 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger) {
 
   /** Where else a name appears (declaration line excluded), for outlines and edit results. */
   async function referenceFinder(cwd, targetPath) {
-    const files = await index.files(cwd);
+    const files = [...new Set([...await index.files(cwd), ...vfs.getOverlayPaths()])];
     if (!index.canScan(files)) return () => [];
     return (name, excludeLine) => {
       if (!name || name.length < 3) return [];
       const escaped = name.replace(/[$]/g, (c) => "\\" + c);
       const regex = new RegExp("\\b" + escaped + "\\b");
       return index
-        .grepRows(files, regex, cwd)
+        .grepRows(files, regex, cwd, file => vfs.getOverlay(file))
         .filter((r) => !(r.line === excludeLine && r.rel === relativeSlash(cwd, targetPath)))
         .map((r) => r.rel + ":" + r.line);
     };
   }
 
+  hooks.summarizeEdit = editSummary;
   return {
     read: readAdapter,
     async write(params, signal) {
@@ -299,13 +400,15 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger) {
       const content = params.content;
       let prevText = "";
       try {
-        prevText = await vfs.read(target);
-      } catch {}
+        prevText = await vfs.read(target, { preserveRead: true });
+      } catch (error) { if (error.code !== "ENOENT") throw error; }
       const { speculative } = await vfs.write(target, content);
       index.touch(relativeSlash(cwd, target));
       const diff = buildWriteDiff(target, prevText, content);
       const tag = speculative ? " (speculative)" : "";
-      return textResult(`wrote ${target}${tag}`, { path: target, speculative, diff });
+      const check = quickCheck(content, path.extname(target));
+      const warning = check && !check.ok ? "\ncheck: " + check.message : "";
+      return textResult(`wrote ${target}${tag}${warning}`, { path: target, speculative, diff });
     },
     async edit(params, signal) {
       const cwd = getCwd();
@@ -323,7 +426,7 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger) {
         matches.length === 1
           ? buildEditDiff(target, content, matches[0].oldText, matches[0].newText)
           : buildMultiEditDiff(target, content, matches);
-      const summary = await editSummary(cwd, target, content, updated, diff);
+      const summary = await editSummary(cwd, target, content, updated, diff, signal);
       return textResult(summary, { path: target, speculative, diff });
     },
     async apply_patch(params, signal) {
@@ -343,8 +446,9 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger) {
       const { resultText, hunkCount } = applyPatchToText(original, params.patch);
       const { speculative } = await vfs.write(target, resultText);
       const diff = buildPatchDiff(target, params.patch);
-      const tag = speculative ? " (speculative)" : "";
-      return textResult(`applied ${hunkCount} hunk(s) to ${target}${tag}`, {
+      index.touch(relativeSlash(cwd, target));
+      const summary = await editSummary(cwd, target, original, resultText, diff, signal);
+      return textResult(summary, {
         path: target,
         hunks: hunkCount,
         speculative,
@@ -367,7 +471,6 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger) {
         searchDir: snapTarget,
         root: cwd,
         includeHidden,
-        index,
         overlayText: (p) => vfs.getOverlay(p),
         pendingPaths: vfs.getOverlayPaths(),
         signal,
@@ -397,30 +500,37 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger) {
     },
     async bash(params, signal) {
       const cwd = getCwd();
-      const command = unwrapIfFullyQuoted(String(params?.command ?? "").trim());
-      if (!command) throw new Error("bash requires command");
+      const literal = params?._directArgv === true;
+      if (literal && (!isString(params.command) || !Array.isArray(params.args) || params.args.some(arg => !isString(arg)))) throw new Error("bash argv requires a command string and an array of string args");
+      const command = literal ? String(params.command) : unwrapIfFullyQuoted(String(params?.command ?? "").trim());
+      if (!command.trim()) throw new Error("bash requires command");
       const targetCwd = params?.cwd ? await resolveWorkspacePath(cwd, params.cwd, "bash cwd", true) : cwd;
 
-      // Always shell. Splitting on spaces treated `git status` / quoted `exec("git status")`
-      // as a single binary name (`bash: git status: command not found`).
-      const argv = ["bash", "-c", command];
+      // String commands keep shell semantics; literal argv needs no quoting or shell startup.
+      const argv = literal ? [command, ...params.args] : ["bash", "-c", command];
 
       const transactionBarrier = await vfs.prepareExternalMutation("bash");
       let res;
       try {
         res = await runCommand(argv, {
           cwd: targetCwd,
+          env: hooks.commandEnv(),
+          commandLabel: literal ? command : undefined,
           timeoutMs: params?.timeoutMs,
           signal,
           maxOutputChars: config.maxCallResultChars,
         });
+      } catch (error) {
+        if (!signal?.aborted) error.message += await sourceForReferences(cwd, targetCwd, error.message);
+        throw error;
       } finally {
         vfs.invalidateCache();
         index.invalidate();
+        clearPathCache();
       }
       const { stdout, stderr } = res;
       let text = stdout && stderr ? stdout + (stdout.endsWith("\n") ? "" : "\n") + stderr : stdout || stderr;
-      if (res.exitCode !== 0) text += sourceForReferences(cwd, text);
+      if (res.exitCode !== 0) text += await sourceForReferences(cwd, targetCwd, text);
       return {
         content: [{ type: "text", text }],
         details: { exitCode: res.exitCode, signal: res.signal, outputTruncated: res.outputTruncated, transactionBarrier },
@@ -486,12 +596,13 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger) {
 export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedger }) {
   const index = registry?.index ?? new WorkspaceIndex((argv, opts) => runCommand(argv, opts));
   const ledger = runLedger ?? new SeenLedger({ window: config.seenWindow ?? 40 });
-  const vfs = new CausalVfs(() => index.invalidate());
+  const vfs = new CausalVfs(() => index.invalidate(), target => resolveWorkspacePath(getCwd(), target, "commit", false, true));
   const executors = registry?.executors ?? new Map();
   const definitions = registry?.definitions ?? new Map();
   const sharedRegistry = registry ?? { executors, definitions, index, callSeq: 0 };
   let closed = false;
-  const natives = createNativeAdapters(getCwd, vfs, config, index, ledger);
+  const hooks = {};
+  const natives = createNativeAdapters(getCwd, vfs, config, index, ledger, hooks);
   let callCount = 0;
   let activeCtx = null;
   let hostSession = null;
@@ -499,6 +610,22 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
   let activeSignal = undefined;
   let trace = [];
   let callListener = null;
+  const scheduler = createNativeScheduler();
+  hooks.commandEnv = () => {
+    const env = { ...process.env };
+    const current = {
+      PI_SESSION_ID: activeCtx?.sessionManager?.getSessionId?.(),
+      PI_SESSION_FILE: activeCtx?.sessionManager?.getSessionFile?.(),
+      PI_PROVIDER: activeCtx?.model?.provider,
+      PI_MODEL: activeCtx?.model?.id,
+      PI_REASONING_LEVEL: activeCtx?.thinkingLevel,
+    };
+    for (const [key, value] of Object.entries(current)) {
+      if (isString(value)) env[key] = value;
+      else delete env[key];
+    }
+    return env;
+  };
 
   if (!registry && pi && isFunction(pi.registerTool)) {
     const original = pi.registerTool.bind(pi);
@@ -622,7 +749,7 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     callCount += 1;
     if (callCount > 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`,
+        `host call budget exceeded (${maxCalls} calls per program): split the work across programs`,
       );
     }
     if (activeSignal?.aborted) throw new Error("aborted");
@@ -634,7 +761,7 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     const excluded = new Set(config.excludeTools || []);
     if (name === "supernova" || excluded.has(name)) {
       throw new Error(
-        `nova.call("${name}") is blocked (excluded / non-reentrant). Use nova.search/describe for discovery, or call a concrete host tool.`,
+        `${name} is blocked (excluded / non-reentrant).`,
       );
     }
   }
@@ -664,7 +791,8 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     assertCallableTarget(name);
     if (!isCallable(name)) throw new Error(unknownToolMessage(name, [...definitions.keys(), ...Object.keys(natives)].filter(isCallable)));
 
-    const record = { name, args: args || {}, time: Date.now() };
+    const command = { apply_patch: "edit", surface: "read", evidence: "read", snap: "read" }[name] ?? name;
+    const record = { name: command, adapter: name, args: args || {}, time: Date.now() };
     trace.push(record);
     notifyCall(record);
 
@@ -714,8 +842,9 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
 
   async function call(name, args) {
     if (!isString(name) || !name) throw new Error("nova.call requires a tool name");
-    const raw = await invokeRaw(name, args);
-    return packageHostResult(raw, config);
+    const invoke = async () => packageHostResult(await invokeRaw(name, args), config);
+    const kind = isMutatingTool(name, config, args, definitions.get(name)) ? "write" : "read";
+    return scheduler.schedule(kind, invoke, activeSignal);
   }
 
   async function callMany(calls) {
@@ -748,6 +877,21 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     isCallable,
     externalNames,
     supportsBatchRead: () => !hostTool("read") && !executors.has("read"),
+    // Windows command shims need shell handling; preserve the existing route there.
+    supportsNativeArgv: () => process.platform !== "win32" && !hostTool("bash") && !executors.has("bash"),
+    summarizeEdit: (target, before, after, diff) => hooks.summarizeEdit(getCwd(), target, before, after, diff),
+    invalidateFiles() { vfs.invalidateCache(); index.invalidate(); clearPathCache(); },
+    fileOperations: {
+      access: (target, mode) => fs.access(target, mode),
+      readFile: async target => Buffer.from(await vfs.read(target), "utf8"),
+      // VFS owns parent creation and atomic replacement, inside Pi's file queue.
+      mkdir: async () => {},
+      async writeFile(target, content) {
+        await resolveWorkspacePath(getCwd(), target, "write", false);
+        await vfs.write(target, content);
+        index.touch(relativeSlash(getCwd(), target));
+      },
+    },
     fork(options) {
       return createHostBridge({ pi, config, getCwd: options.getCwd, registry: sharedRegistry, ledger: ledger.fork() });
     },
@@ -756,6 +900,7 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
     resetCallBudget,
     getTrace,
     setCallListener,
+    barrier: run => scheduler.schedule("write", run, activeSignal),
     beginSpeculation,
     commitSpeculation,
     rollbackSpeculation,