pi-supernova 0.0.15 → 0.2.0

package/host-bridge.js

@@ -1,7 +1,7 @@
 
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { packageHostResult } from "./bottleneck.js";
+import { packageHostResult, hostResultFailed } from "./bottleneck.js";
 import { isString, isNumber, isFunction, isObject } from "./decode.js";
 import { isMutatingTool, runParallelWave } from "./parallel.js";
 import { unknownToolMessage } from "./catalog.js";
@@ -55,15 +55,15 @@ function looksLikePath(target) {
   );
 }
 
-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;
+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 };
   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;
+    return { path: targetPath, directory: st.isDirectory() };
   } catch (err) {
     if (err?.code !== "ENOENT" && err?.code !== "ENOTDIR") throw err;
+    if (vfs.getOverlayPaths().some(file => file.startsWith(targetPath + path.sep))) return { path: targetPath, directory: true };
     return null;
   }
 }
@@ -79,7 +79,7 @@ function applyReplacements(target, content, requestedEdits) {
     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)`);
     }
-    if (content.indexOf(replacement.oldText, index + replacement.oldText.length) >= 0) {
+    if (content.indexOf(replacement.oldText, index + 1) >= 0) {
       throw new Error(`edit target is not unique in ${target}: include more surrounding lines in oldText, or pass edits:[{oldText,newText},…]`);
     }
     return { ...replacement, index, end: index + replacement.oldText.length };
@@ -96,6 +96,11 @@ function applyReplacements(target, content, requestedEdits) {
   return { updated, matches };
 }
 
+function formatDirectoryEntry(name, type, size = 0) {
+  const sizeSuffix = size ? `, ${size} bytes` : "";
+  return `${name}${type === "dir" ? "/" : ""} (${type}${sizeSuffix})`;
+}
+
 async function formatLsEntry(dirPath, entry) {
   const isDir = entry.isDirectory();
   const isSym = entry.isSymbolicLink();
@@ -107,46 +112,55 @@ async function formatLsEntry(dirPath, entry) {
       size = st.size;
     }
   } catch {}
-  const sizeSuffix = size ? `, ${size} bytes` : "";
-  return `${entry.name}${isDir ? "/" : ""} (${typeLabel}${sizeSuffix})`;
+  return formatDirectoryEntry(entry.name, typeLabel, size);
 }
 
 function createNativeAdapters(getCwd, vfs, config, index, ledger) {
-  async function readAdapter(params, signal) {
-      const cwd = getCwd();
-      const targetParam = params?.path ?? params?.target;
-
-      if (Array.isArray(targetParam)) {
-        const results = await Promise.all(
-          targetParam.map((p) => readAdapter({ path: p, offset: params?.offset, limit: params?.limit }, signal)),
-        );
-        const items = results.map((r) => r.content[0].text);
-        return textResult(items.join("\n---\n"), { count: results.length, batch: true, items });
-      }
-
-      if (looksLikePath(targetParam)) {
-        const targetPath = await resolveWorkspacePath(cwd, targetParam, "read", false);
-        return readFile(targetPath, params);
-      }
-
-      const existing = await probeExistingFile(cwd, targetParam, vfs);
-      if (existing) return readFile(existing, params);
+  async function sourceRead(query, searchDir, signal) {
+    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,
+      overlayText: p => vfs.getOverlay(p), pendingPaths: vfs.getOverlayPaths(), signal });
+    return textResult(JSON.stringify(result, null, 2), { ...result, isSnap: true });
+  }
 
-      if (isString(targetParam) && targetParam.trim()) {
-        try {
-          const snapRes = await executeSnap({
-            query: targetParam,
-            searchDir: cwd,
-            index,
-            overlayText: (p) => vfs.getOverlay(p),
-            pendingPaths: vfs.getOverlayPaths(),
-          });
-          return textResult(JSON.stringify(snapRes, null, 2), { ...snapRes, isSnap: true });
-        } catch {}
-      }
+  async function readDirectory(dirPath, signal) {
+    signal?.throwIfAborted();
+    const rows = new Map();
+    for (const file of vfs.getOverlayPaths()) {
+      const relative = path.relative(dirPath, file);
+      if (!relative || relative === ".." || relative.startsWith(".." + path.sep) || path.isAbsolute(relative)) continue;
+      const [name, child] = relative.split(path.sep);
+      rows.set(name, child === undefined
+        ? formatDirectoryEntry(name, "file", Buffer.byteLength(vfs.getOverlay(file), "utf8"))
+        : formatDirectoryEntry(name, "dir"));
+    }
+    let entries;
+    try { entries = await fs.readdir(dirPath, { withFileTypes: true }); } catch (error) {
+      if (error.code !== "ENOENT" || rows.size === 0) throw error;
+      entries = [];
+    }
+    for (const entry of entries) if (!rows.has(entry.name)) rows.set(entry.name, await formatLsEntry(dirPath, entry));
+    return textResult([...rows.values()].join("\n"), { path: dirPath, count: rows.size });
+  }
 
-      const targetPath = await resolveWorkspacePath(cwd, targetParam, "read", false);
-      return readFile(targetPath, params);
+  async function readAdapter(params, signal) {
+    signal?.throwIfAborted();
+    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) });
+    }
+    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 (!looksLikePath(targetParam)) return sourceRead(targetParam, cwd, signal);
+    const targetPath = await resolveWorkspacePath(cwd, targetParam, "read", false);
+    return readFile(targetPath, params);
   }
 
   /** Plain text, a line window, or (with `about`) a relevance-folded outline of the whole file. */
@@ -281,7 +295,8 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger) {
       const cwd = getCwd();
       const target = await resolveWorkspacePath(cwd, params?.path, "write", false);
       if (signal?.aborted) throw new Error("aborted");
-      const content = String(params?.content ?? "");
+      if (!isString(params?.content)) throw new Error("write requires string content");
+      const content = params.content;
       let prevText = "";
       try {
         prevText = await vfs.read(target);
@@ -308,7 +323,6 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger) {
         matches.length === 1
           ? buildEditDiff(target, content, matches[0].oldText, matches[0].newText)
           : buildMultiEditDiff(target, content, matches);
-      const tag = speculative ? " (speculative)" : "";
       const summary = await editSummary(cwd, target, content, updated, diff);
       return textResult(summary, { path: target, speculative, diff });
     },
@@ -356,6 +370,7 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger) {
         index,
         overlayText: (p) => vfs.getOverlay(p),
         pendingPaths: vfs.getOverlayPaths(),
+        signal,
       });
       return textResult(JSON.stringify(res, null, 2), res);
     },
@@ -367,7 +382,7 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger) {
       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 });
+      const res = await selectEvidence({ query: params.query, root: cwd, searchDir, index, overlayText: (p) => vfs.getOverlay(p), pendingPaths: vfs.getOverlayPaths(), options });
       for (const span of res.spans) ledger.recordOrigin(span.path, span.lines[0], span.text.split("\n"));
       return textResult(JSON.stringify(res), { route: res.route, count: res.spans.length });
     },
@@ -408,7 +423,7 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger) {
       if (res.exitCode !== 0) text += sourceForReferences(cwd, text);
       return {
         content: [{ type: "text", text }],
-        details: { exitCode: res.exitCode, outputTruncated: res.outputTruncated, transactionBarrier },
+        details: { exitCode: res.exitCode, signal: res.signal, outputTruncated: res.outputTruncated, transactionBarrier },
         isError: res.exitCode !== 0,
       };
     },
@@ -463,30 +478,29 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger) {
     async ls(params, signal) {
       const cwd = getCwd();
       const dirPath = params?.path ? await resolveWorkspacePath(cwd, params.path, "ls", true) : cwd;
-      if (signal?.aborted) throw new Error("aborted");
-      const entries = await fs.readdir(dirPath, { withFileTypes: true });
-      const lines = [];
-      for (const entry of entries) {
-        lines.push(await formatLsEntry(dirPath, entry));
-      }
-      return textResult(lines.join("\n"), { path: dirPath, count: entries.length });
+      return readDirectory(dirPath, signal);
     },
   };
 }
 
-export function createHostBridge({ pi, config, getCwd }) {
-  const index = new WorkspaceIndex((argv, opts) => runCommand(argv, opts));
-  const ledger = new SeenLedger({ window: config.seenWindow ?? 40 });
+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 executors = new Map();
+  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);
   let callCount = 0;
   let activeCtx = null;
+  let hostSession = null;
+  let boundSessionId;
   let activeSignal = undefined;
   let trace = [];
   let callListener = null;
 
-  if (pi && isFunction(pi.registerTool)) {
+  if (!registry && pi && isFunction(pi.registerTool)) {
     const original = pi.registerTool.bind(pi);
     const excluded = new Set(config.excludeTools || []);
     pi.registerTool = (tool) => {
@@ -498,6 +512,7 @@ export function createHostBridge({ pi, config, getCwd }) {
         !excluded.has(tool.name)
       ) {
         executors.set(tool.name, tool.execute.bind(tool));
+        definitions.set(tool.name, tool);
       }
       return original(tool);
     };
@@ -505,10 +520,56 @@ export function createHostBridge({ pi, config, getCwd }) {
 
   function bindCallContext(ctx, signal) {
     activeCtx = ctx || null;
+    const sessionId = ctx?.sessionManager?.getSessionId?.();
+    boundSessionId = sessionId;
+    const registry = pi?.pi?.AgentRegistry?.global?.();
+    hostSession = sessionId && registry?.list
+      ? registry.list().map(ref => ref.session).find(session => !session?.isDisposed && session?.sessionManager?.getSessionId?.() === sessionId) ?? null
+      : null;
     activeSignal = signal;
+    vfs.signal = signal;
+  }
+
+  function hostTool(name) {
+    if (!hostSession) return undefined;
+    const metadata = definitions.get(name);
+    // Keep Supernova's transactional adapters for ordinary built-ins. Respect overrides.
+    if (Object.hasOwn(natives, name) && metadata?.sourceInfo?.source === "builtin") return undefined;
+    return hostSession.getToolForEvalBridge?.(name);
+  }
+
+  function isCallable(name) {
+    if (name === "supernova" || (config.excludeTools ?? []).includes(name)) return false;
+    if (hostSession && (hostSession.isDisposed || hostSession.sessionManager.getSessionId() !== boundSessionId)) return false;
+    // An internal adapter belongs to Supernova, not the host's visible tool list.
+    const nativeOwned = Object.hasOwn(natives, name) && !executors.has(name)
+      && (!hostSession || !definitions.has(name) || definitions.get(name).sourceInfo?.source === "builtin");
+    if (nativeOwned) return true;
+    if (hostSession) {
+      if (!hostSession.getEvalBridgeToolNames().includes(name) && definitions.has(name)) return false;
+      return !!hostTool(name) || (Object.hasOwn(natives, name) && (!definitions.has(name) || definitions.get(name).sourceInfo?.source === "builtin"));
+    }
+    if (definitions.has(name) && isFunction(pi?.getActiveTools) && !pi.getActiveTools().includes(name)) return false;
+    return executors.has(name) || Object.hasOwn(natives, name);
+  }
+
+  function refreshTools() {
+    const tools = pi?.getAllTools?.() ?? [];
+    for (const tool of tools) {
+      if (!isString(tool?.name)) continue;
+      definitions.set(tool.name, { ...definitions.get(tool.name), ...tool });
+      if (!hostSession && isFunction(tool.execute)) executors.set(tool.name, tool.execute.bind(tool));
+    }
+    return [...definitions.values()].filter(tool => isCallable(tool.name));
+  }
+
+  function externalNames() {
+    return [...definitions.keys()].filter(name => !!hostTool(name) || executors.has(name));
   }
 
   function resetCallBudget() {
+    closed = false;
+    vfs.closed = false;
     callCount = 0;
     trace = [];
     // Files may change between programs (editor, git); never serve a stale run.
@@ -556,6 +617,7 @@ export function createHostBridge({ pi, config, getCwd }) {
   }
 
   function checkCallBudget(name) {
+    if (closed) throw new Error("program is already complete");
     const maxCalls = config.maxBridgeCalls ?? 256;
     callCount += 1;
     if (callCount > maxCalls) {
@@ -598,23 +660,35 @@ export function createHostBridge({ pi, config, getCwd }) {
 
   async function invokeRaw(name, args) {
     checkCallBudget(name);
+    const callId = ++sharedRegistry.callSeq;
     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() };
     trace.push(record);
     notifyCall(record);
 
     try {
-      const exec = executors.get(name);
+      const delegated = hostTool(name);
+      const exec = delegated ? delegated.execute.bind(delegated) : hostSession ? undefined : executors.get(name);
       if (exec) {
         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);
-        completeRecord(record, res, fallbackDiff);
-        return res;
+        const mutating = isMutatingTool(name, config, args, definitions.get(name));
+        if (mutating) await vfs.prepareExternalMutation(name);
+        if (activeSignal?.aborted || closed) throw new Error("aborted");
+        if (!isCallable(name)) throw new Error("tool is no longer enabled in this session: " + name);
+        try {
+          const res = await exec(`supernova:${name}:${callId}`, args || {}, activeSignal, undefined, delegated
+            ? { ...activeCtx, settings: hostSession.settings, toolNames: hostSession.getEvalBridgeToolNames(), autoApprove: false }
+            : activeCtx);
+          completeRecord(record, res, fallbackDiff);
+          return res;
+        } finally {
+          if (mutating) { vfs.invalidateCache(); index.invalidate(); clearPathCache(); }
+        }
       }
 
-      const native = natives[name];
+      const native = Object.hasOwn(natives, name) ? natives[name] : undefined;
       if (native) {
         const res = await native(args || {}, activeSignal);
         completeRecord(record, res);
@@ -633,7 +707,7 @@ export function createHostBridge({ pi, config, getCwd }) {
 
   function finishRecord(record, res) {
     record.ms = Date.now() - record.time;
-    record.ok = res?.isError !== true && res?.details?.ok !== false;
+    record.ok = !hostResultFailed(res);
     const exitCode = isObject(res?.details) ? res.details.exitCode : undefined;
     if (Number.isInteger(exitCode) && exitCode !== 0) record.exitCode = exitCode;
   }
@@ -645,14 +719,16 @@ export function createHostBridge({ pi, config, getCwd }) {
   }
 
   async function callMany(calls) {
-    const list = Array.isArray(calls) ? calls : [];
+    if (!Array.isArray(calls)) throw new TypeError("nova.callMany requires an array");
+    const list = calls;
+    if (list.some(item => !isString(item?.name) || !item.name)) throw new TypeError("nova.callMany entries require a tool name");
     const thunks = list.map((item) => {
       const n = item?.name;
       const a = item?.args;
       return () => call(n, a);
     });
     const names = list.map((item) => item?.name).filter((n) => isString(n));
-    const wave = await runParallelWave(thunks, { names }, { mode: "auto", config });
+    const wave = await runParallelWave(thunks, { names, calls: list, definitions: names.map(name => definitions.get(name)) }, { mode: "auto", config });
     // Return a results array that also carries .mode/.reason, and is directly
     // iterable so `for (const r of await nova.callMany([...]))` works.
     const results = Array.isArray(wave.results) ? wave.results.slice() : [];
@@ -666,7 +742,16 @@ export function createHostBridge({ pi, config, getCwd }) {
 
   return {
     executors,
+    definitions,
     natives,
+    refreshTools,
+    isCallable,
+    externalNames,
+    supportsBatchRead: () => !hostTool("read") && !executors.has("read"),
+    fork(options) {
+      return createHostBridge({ pi, config, getCwd: options.getCwd, registry: sharedRegistry, ledger: ledger.fork() });
+    },
+    close() { closed = true; vfs.closed = true; },
     bindCallContext,
     resetCallBudget,
     getTrace,

package/index.js

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import { isString, isFunction, isObject } from "./decode.js";
+import { isString, isFunction } from "./decode.js";
 import { buildCatalog, searchCatalog, describeTool, mergeNativeToolDefinitions } from "./catalog.js";
 import { loadConfig } from "./config.js";
 import { createHostBridge } from "./host-bridge.js";
@@ -82,22 +82,22 @@ function errorText(outcome, call) {
 
 function successText(outcome, call) {
   const truncated = outcome.returnTruncated ? " [return truncated]" : "";
-  const hint = outcome.undefinedReturn ? " (no return statement; add \`return\` to get a value)" : "";
+  const hint = outcome.undefinedReturn ? " (no return statement; add `return` to get a value)" : "";
   return `ok #${call} ${outcome.wallMs}ms${truncated}${logsBlock(outcome, "\n--- result")}\n${outcome.resultText}${hint}`;
 }
-const TOOL_DESCRIPTION = `Run one JavaScript program that composes host tools. Async body or arrow; \`return\` a small shaped value (compact literal, capped; strings raw; console.log is captured).
+const TOOL_DESCRIPTION = `Run one JavaScript program with four familiar commands: read, write, edit, bash. Use an async body or arrow. Return a small value; strings stay raw.
 
-Globals (async):
-read(path|paths, offset?, limit?) → text | text[] · read(path, {about}) → whole-file outline, only relevant bodies expanded
-write(path, text) · edit(path, oldText, newText) → post-edit lines (no re-read needed) · patch(path, unifiedDiff)
-bash(cmd, {cwd?, timeoutMs?}) → output, throws on non-zero exit · exec(cmd, argv?) quotes argv
-evidence(query, {k?}) → {spans: [{path, lines, name, text}]} top-K spans that answer a question; use before read
-snap(query, root?) → {path, line, signature, context} · surface(path) → {items: [{name, kind, line}]}
-nova.call(name, args) → {ok, value} for any host tool · nova.callMany([{name, args}]) parallel when read-only
-nova.search(query) → [{name, description}] · nova.describe(name) → parameters · nova.has(name) sync
-parallel(thunks) · pipeline(items, ...stages)
+Native commands (async):
+read(path|paths, offset?, limit?) → file text or text[]; read(directory) → directory entries
+read("symbol or question") → JSON text with source location and context; no separate search tool needed
+read(path, {about: question}) → relevant file bodies, or source selection inside a directory
+write(path, text) → write a file
+edit(path, oldText, newText) → post-edit lines, checks, and references; no verification read needed
+bash(command, {cwd?, timeoutMs?}) → bounded output; throws on non-zero exit
 
-Already-seen lines collapse to "⋯ N lines same as #12 · path:a–b ⋯"; read(path, a, n) re-shows them.`;
+Source selection reports found, ambiguous, not_found, or incomplete. Only found selects a path. Narrow the directory for uncertain results.
+Optional composition: parallel(thunks), pipeline(items, ...stages), nova.call(name, args), nova.callMany(calls). Use nova.search/describe only for other host tools.
+Already-seen lines collapse to references; read(path, firstLine, lineCount) shows them again. console.log is captured.`;
 
 export default function piSupernova(pi) {
   const config = loadConfig();
@@ -111,50 +111,38 @@ export default function piSupernova(pi) {
     getCwd: () => cwd,
   });
 
-  function refreshCatalog() {
-    let tools = [];
-    try {
-      if (isFunction(pi.getAllTools)) {
-        tools = pi.getAllTools() || [];
-      }
-    } catch {
-      tools = [];
-    }
-    const discoverable = mergeNativeToolDefinitions(tools, bridge.executors.keys());
+  function refreshCatalog(target = bridge) {
+    const tools = target.refreshTools();
+    const discoverable = mergeNativeToolDefinitions(tools, target.externalNames())
+      .filter(tool => target.isCallable(tool.name))
+      .map(tool => {
+        const schema = tool.parameters;
+        try {
+          if (isFunction(schema?.toJsonSchema)) return { ...tool, parameters: schema.toJsonSchema() };
+          if (schema && !schema.type && pi.zod?.toJSONSchema && (schema._zod || schema._def)) {
+            return { ...tool, parameters: pi.zod.toJSONSchema(schema, { io: "input" }) };
+          }
+          return tool;
+        } catch (error) {
+          return { ...tool, parameters: undefined, schemaError: error.message };
+        }
+      });
     catalog = buildCatalog(discoverable, config.excludeTools || []);
     return catalog;
   }
 
-  function makeNovaApi() {
+  function makeNovaApi(runBridge, runCatalog, cancel) {
     return {
-      async search(query, limit) {
-        const cat = catalog.length ? catalog : refreshCatalog();
-        const lim = Number.isInteger(limit) ? limit : config.maxSearchResults;
-        return searchCatalog(cat, query, lim);
-      },
-      async describe(name) {
-        const cat = catalog.length ? catalog : refreshCatalog();
-        return describeTool(cat, name);
-      },
-      async call(name, args) {
-        return bridge.call(name, args);
-      },
-      async callMany(calls) {
-        return bridge.callMany(calls);
-      },
-      speculateBegin() {
-        bridge.beginSpeculation();
-      },
-      async speculateCommit() {
-        await bridge.commitSpeculation();
-      },
-      speculateRollback() {
-        bridge.rollbackSpeculation();
-      },
-      names() {
-        const cat = catalog.length ? catalog : refreshCatalog();
-        return [...new Set([...cat.map((t) => t.name), ...bridge.executors.keys(), ...Object.keys(bridge.natives)])];
-      },
+      search: async (query, limit) => searchCatalog(runCatalog, query, Number.isInteger(limit) ? limit : config.maxSearchResults),
+      describe: async (name) => describeTool(runCatalog, name),
+      call: (name, args) => runBridge.call(name, args),
+      callMany: (calls) => runBridge.callMany(calls),
+      speculateBegin: () => runBridge.beginSpeculation(),
+      speculateCommit: () => runBridge.commitSpeculation(),
+      speculateRollback: () => runBridge.rollbackSpeculation(),
+      names: () => runCatalog.map(tool => tool.name),
+      batchRead: runBridge.supportsBatchRead(),
+      cancel,
     };
   }
 
@@ -162,9 +150,9 @@ export default function piSupernova(pi) {
     name: "supernova",
     label: "Supernova",
     description: TOOL_DESCRIPTION,
-    promptSnippet: "Compose host tools in one JavaScript program",
+    promptSnippet: "Use read, write, edit, and bash in one program",
     promptGuidelines: [
-      "Use supernova for multi-step tool work: loops, filtering, parallel reads, read→edit chains. To understand code: evidence(question) across the repo, or read(path, {about: question}) for one file: full structure, only relevant bodies expanded. Plain read(path) only for lines you will edit. Return a compact shaped value; keep raw tool output inside the program.",
+      "Use read, write, edit, and bash inside supernova. Start with read(question), or read(directory, {about: question}) for scoped source selection. Read file bodies with read(file, {about: question}). Check source selection status before using its path. Return a compact value.",
     ],
     parameters: Type.Object({
       code: Type.String({ description: "JavaScript program: async body or arrow function." }),
@@ -177,70 +165,62 @@ export default function piSupernova(pi) {
     renderCall: renderSupernovaCall,
     renderResult: renderSupernovaResult,
     async execute(_id, params, signal, onUpdate, ctx) {
-      if (ctx && isString(ctx.cwd) && ctx.cwd) cwd = ctx.cwd;
+      const runCwd = ctx?.cwd || cwd;
       const runController = new AbortController();
       const abortRun = () => runController.abort(signal?.reason);
       if (signal?.aborted) abortRun();
       else signal?.addEventListener("abort", abortRun, { once: true });
+      const runBridge = bridge.fork({ getCwd: () => runCwd });
+      runBridge.bindCallContext(ctx, runController.signal);
+      runBridge.resetCallBudget();
 
-      bridge.bindCallContext(ctx, runController.signal);
-      bridge.resetCallBudget();
-      refreshCatalog();
-      bridge.beginSpeculation();
       const call = ++programSeq;
-      bridge.ledger.beginProgram(call);
+      runBridge.ledger.beginProgram(call);
       const emitProgress = progressEmitter(onUpdate);
-      bridge.setCallListener((_record, allTrace) => emitProgress(allTrace));
+      runBridge.setCallListener((_record, trace) => emitProgress(trace));
       emitProgress([]);
-
+      const started = performance.now();
       let outcome;
       try {
-        outcome = await runProgram(params, runController.signal, abortRun);
+        const runCatalog = refreshCatalog(runBridge);
+        runBridge.beginSpeculation();
+        outcome = await runGuestProgram({
+          code: params?.code,
+          nova: makeNovaApi(runBridge, runCatalog, abortRun),
+          config: { ...config, timeoutMs: Number.isInteger(params?.timeoutMs) ? params.timeoutMs : config.timeoutMs },
+          signal: runController.signal,
+          onTimeout: abortRun,
+        });
+        runBridge.close();
+        if (outcome.ok) {
+          if (runBridge.getOverlayDepth() !== 1) throw new Error("program ended with an unfinished nova.speculate branch; await it before returning");
+          await runBridge.commitSpeculation();
+        }
+        else runBridge.rollbackSpeculation();
+      } catch (error) {
+        abortRun();
+        runBridge.close();
+        runBridge.rollbackSpeculation();
+        outcome = { ok: false, error: error instanceof Error ? error.message : String(error), logs: outcome?.logs ?? [], wallMs: Math.round(performance.now() - started) };
       } finally {
-        bridge.setCallListener(null);
+        runBridge.setCallListener(null);
         emitProgress.flush();
         signal?.removeEventListener("abort", abortRun);
       }
-
-      const trace = bridge.getTrace();
-      if (!outcome.ok) {
-        bridge.rollbackSpeculation();
-        return result(bridge.ledger.dedupe(errorText(outcome, call), call), { ok: false, error: outcome.error, wallMs: outcome.wallMs, logs: outcome.logs, trace });
-      }
-      await bridge.commitSpeculation();
-      return result(bridge.ledger.dedupe(successText(outcome, call), call), {
-        ok: true,
-        wallMs: outcome.wallMs,
-        returnTruncated: outcome.returnTruncated,
-        logTruncated: outcome.logTruncated,
-        logs: outcome.logs,
-        result: outcome.result,
-        trace,
+      const trace = runBridge.getTrace();
+      const text = outcome.ok ? successText(outcome, call) : errorText(outcome, call);
+      return result(runBridge.ledger.dedupe(text, call), {
+        ok: outcome.ok, error: outcome.error, wallMs: outcome.wallMs,
+        returnTruncated: outcome.returnTruncated, logTruncated: outcome.logTruncated,
+        logs: outcome.logs, result: outcome.result, trace,
       });
     },
   });
 
-  async function runProgram(params, signal, onTimeout) {
-    const runStartedAt = performance.now();
-    const runConfig = {
-      ...config,
-      timeoutMs: Number.isInteger(params?.timeoutMs) ? params.timeoutMs : config.timeoutMs,
-    };
-    try {
-      return await runGuestProgram({ code: String(params?.code || ""), nova: makeNovaApi(), config: runConfig, signal, onTimeout });
-    } catch (error) {
-      return {
-        ok: false,
-        error: error instanceof Error ? error.message : String(error),
-        logs: [],
-        wallMs: Math.round(performance.now() - runStartedAt),
-      };
-    }
-  }
-
   pi.on("session_start", (_event, ctx) => {
     if (ctx && isString(ctx.cwd) && ctx.cwd) cwd = ctx.cwd;
     // A new session is a new model context: nothing has been seen yet.
+    bridge.bindCallContext(ctx);
     bridge.ledger.reset();
     programSeq = 0;
     refreshCatalog();
@@ -248,14 +228,15 @@ export default function piSupernova(pi) {
   });
 
   pi.registerCommand("supernova", {
-    description: "Show pi-supernova status (catalog size, captured executors)",
+    description: "Show pi-supernova status (callable tools and session statistics)",
     handler: async (_args, ctx) => {
+      bridge.bindCallContext(ctx);
       refreshCatalog();
-      const captured = [...bridge.executors.keys()].sort();
-      const natives = Object.keys(bridge.natives).sort();
+      const external = bridge.externalNames().filter(bridge.isCallable).sort();
+      const natives = Object.keys(bridge.natives).filter(name => bridge.isCallable(name) && !external.includes(name)).sort();
       const lines = [
         `pi-supernova catalog: ${catalog.length} tools`,
-        `captured executors: ${captured.length ? captured.join(", ") : "(none yet; load this package early)"}`,
+        `external tools: ${external.length ? external.join(", ") : "(none)"}`,
         `native adapters: ${natives.join(", ")}`,
         `timeoutMs=${config.timeoutMs} maxCallResultChars=${config.maxCallResultChars} maxReturnChars=${config.maxReturnChars} maxBridgeCalls=${config.maxBridgeCalls} maxHeapMb=${config.maxHeapMb}`,
         sessionStats(bridge.ledger.stats),