pi-supernova 0.2.0 → 0.3.0

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

@@ -1,14 +1,18 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { isString } from "./decode.js";
+import { isString } from "../shared/decode.js";
 import { randomUUID } from "node:crypto";
 
 const VFS_CACHE_MAX = 1024;
+// Serialize validation + replacement across Supernova transactions in this host.
+let commitTail = Promise.resolve();
 
 export class CausalVfs {
-  constructor(onNewFile) {
+  constructor(onNewFile, validateWrite) {
+    this.validateWrite = validateWrite;
     this.cache = new Map();
     this.overlays = [];
+    this.expected = new Map();
     this.onNewFile = onNewFile;
     this.closed = false;
     this.signal = undefined;
@@ -34,19 +38,19 @@ export class CausalVfs {
     return [...new Set(this.overlays.flatMap(overlay => [...overlay.keys()]))];
   }
 
-  async read(target) {
+  async read(target, { preserveRead = false } = {}) {
     const overlay = this.getOverlay(target);
     if (overlay !== undefined) return overlay;
     // External editors and captured tools can change a file between any two reads.
     try {
       const text = await fs.readFile(target, "utf8");
-      this.setCache(target, text);
+      if (!preserveRead || !this.cache.has(target)) this.setCache(target, text);
       return text;
     } catch (err) {
       this.cache.delete(target);
       if (err.code === "EISDIR") throw new Error("read path is a directory, not a file: " + target);
       if (err.code === "ENOENT") {
-        const missing = new Error("no such file: " + target + ' (locate it with nova.call("glob", {pattern}) or snap(query))');
+        const missing = new Error("no such file: " + target + ' (locate it with read using a directory path or source question)');
         missing.code = "ENOENT";
         throw missing;
       }
@@ -63,6 +67,13 @@ export class CausalVfs {
       if (err.code !== "ENOENT") throw err;
     }
     this.assertWritable();
+    if (this.getOverlay(target) === undefined) {
+      let original;
+      try { original = this.cache.has(target) ? this.cache.get(target) : await fs.readFile(target, "utf8"); }
+      catch (error) { if (error.code !== "ENOENT") throw error; original = null; }
+      this.expected.set(target, original);
+    }
+    this.assertWritable();
     if (this.overlays.length) {
       this.overlays.at(-1).set(target, content);
       return { speculative: true };
@@ -79,7 +90,14 @@ export class CausalVfs {
 
   /** Stage every file and its backup before replacing any destination. */
   async flush(writes) {
+    const work = commitTail.then(() => this.flushWrites(writes));
+    commitTail = work.catch(() => {});
+    return work;
+  }
+
+  async flushWrites(writes) {
     const staged = [];
+    const targets = new Set();
     const createdDirs = [];
     let failed = false;
     try {
@@ -94,6 +112,15 @@ export class CausalVfs {
         } catch (err) {
           if (err.code !== "ENOENT") throw err;
         }
+        await this.validateWrite?.(logicalPath);
+        if (targets.has(target)) throw new Error("conflicting write aliases: " + logicalPath);
+        targets.add(target);
+        if (this.expected.has(logicalPath)) {
+          const current = stat ? await fs.readFile(target, "utf8") : null;
+          if (current !== this.expected.get(logicalPath)) {
+            throw new Error("write conflict: file changed since it was read: " + logicalPath + "; read it again before retrying");
+          }
+        }
         const parent = path.dirname(target);
         const missing = [];
         let probe = parent;
@@ -109,18 +136,27 @@ export class CausalVfs {
         const token = ".supernova-" + randomUUID();
         const entry = { logicalPath, target, content, temporary: path.join(parent, token + ".new"), backup: path.join(parent, token + ".bak"), existed: !!stat, replaced: false };
         staged.push(entry);
-        await fs.writeFile(entry.temporary, content, { encoding: "utf8", flag: "wx", mode: stat ? stat.mode & 0o7777 : 0o666 });
-        if (stat) {
-          await fs.chmod(entry.temporary, stat.mode & 0o7777);
-          await fs.copyFile(target, entry.backup, fs.constants.COPYFILE_EXCL);
-        }
+        const replacement = (async () => {
+          await fs.writeFile(entry.temporary, content, { encoding: "utf8", flag: "wx", mode: stat ? stat.mode & 0o7777 : 0o666 });
+          if (stat) await fs.chmod(entry.temporary, stat.mode & 0o7777);
+        })();
+        // These touch separate staging files. Settle both before cleanup, even
+        // on failure: Promise.all could leave a late backup after rollback.
+        const staging = [replacement];
+        if (stat) staging.push(fs.copyFile(target, entry.backup, fs.constants.COPYFILE_EXCL));
+        const outcomes = await Promise.allSettled(staging);
+        const failure = outcomes.find(outcome => outcome.status === "rejected");
+        if (failure) throw failure.reason;
       }
       for (const entry of staged) {
         this.signal?.throwIfAborted();
         await fs.rename(entry.temporary, entry.target);
         entry.replaced = true;
       }
-      for (const entry of staged) this.setCache(entry.logicalPath, entry.content);
+      for (const entry of staged) {
+        this.setCache(entry.logicalPath, entry.content);
+        this.expected.delete(entry.logicalPath);
+      }
       if (staged.length) this.onNewFile?.();
     } catch (error) {
       failed = true;
@@ -141,8 +177,10 @@ export class CausalVfs {
       throw error;
     } finally {
       for (const entry of staged) {
-        await fs.rm(entry.temporary, { force: true }).catch(() => {});
-        if (!entry.keepBackup) await fs.rm(entry.backup, { force: true }).catch(() => {});
+        // A successful rename consumed the temporary path. These are known
+        // files, so unlink avoids rm's extra type probe; missing files stay benign.
+        if (!entry.replaced) await fs.unlink(entry.temporary).catch(() => {});
+        if (entry.existed && !entry.keepBackup) await fs.unlink(entry.backup).catch(() => {});
       }
       if (failed) for (const dir of createdDirs.toReversed()) await fs.rmdir(dir).catch(() => {});
     }
@@ -163,12 +201,15 @@ export class CausalVfs {
 
   rollback() {
     const top = this.overlays.pop();
+    for (const target of top?.keys() ?? []) {
+      if (this.getOverlay(target) === undefined) this.expected.delete(target);
+    }
     return { rolledBack: top?.size ?? 0, depth: this.overlays.length };
   }
 
   async prepareExternalMutation(name) {
     this.assertWritable();
-    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 > 1) throw new Error(name + " cannot run inside an edit checkpoint because external mutations cannot be rolled back");
     if (!this.overlays.length) return false;
     const pending = this.overlays[0];
     await this.flush(pending);

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

@@ -2,7 +2,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { spawn } from "node:child_process";
 import { constants } from "node:os";
-import { isString } from "./decode.js";
+import { isString } from "../shared/decode.js";
 
 let cachedCwd = null;
 let cachedResolvedCwd = null;
@@ -56,7 +56,7 @@ export function isTestPath(filePath) {
   return segments.some((s) => TEST_SEGMENTS.has(s)) || /\.(test|spec)\./.test(base);
 }
 
-export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = false) {
+export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = false, fresh = false) {
   if (inputPath == null || !isString(inputPath) || !inputPath.trim()) {
     throw new Error(`${opName} requires path`);
   }
@@ -71,7 +71,7 @@ export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = f
     realRoot = await fs.realpath(resolvedCwd);
     realRoots.set(resolvedCwd, realRoot);
   }
-  let probe = realNearest.get(target);
+  let probe = fresh ? undefined : realNearest.get(target);
   if (!probe) {
     probe = await realpathNearest(target);
     if (realNearest.size >= PATH_CACHE_MAX) realNearest.clear();
@@ -88,7 +88,7 @@ export async function runCommand(argv, options = {}) {
   const maxOutputChars = options.maxOutputChars ?? 2 * 1024 * 1024;
   return new Promise((resolve, reject) => {
     const child = spawn(argv[0], argv.slice(1), {
-      cwd, env: process.env, stdio: ["ignore", "pipe", "pipe"], detached: process.platform !== "win32",
+      cwd, env: options.env ?? process.env, stdio: ["ignore", "pipe", "pipe"], detached: process.platform !== "win32",
     });
     let stdout = "";
     let stderr = "";
@@ -105,6 +105,13 @@ export async function runCommand(argv, options = {}) {
       if (settled) return;
       settled = true;
       cleanup();
+      // Keep bounded diagnostic output when a command times out or is cancelled.
+      error.stdout = stdout;
+      error.stderr = stderr;
+      error.outputTruncated = outputTruncated;
+      const output = [stdout, stderr].filter(Boolean).join("\n").trimEnd();
+      if (output) error.message += "\n" + output;
+      if (outputTruncated) error.message += "\n[output truncated]";
       reject(error);
     };
     const signalTree = signal => {
@@ -124,7 +131,7 @@ export async function runCommand(argv, options = {}) {
       escalation = setTimeout(() => { signalTree("SIGKILL"); fail(error); }, 150);
     };
     const onAbort = () => terminate(new Error("aborted"));
-    const timer = setTimeout(() => terminate(new Error("command timed out after " + timeoutMs + "ms: " + argv.join(" "))), timeoutMs);
+    const timer = setTimeout(() => terminate(new Error("command timed out after " + timeoutMs + "ms: " + (options.commandLabel ?? argv.join(" ")))), timeoutMs);
     const append = (current, chunk) => {
       const remaining = Math.max(0, maxOutputChars - stdout.length - stderr.length);
       if (chunk.length > remaining) outputTruncated = true;
@@ -136,7 +143,16 @@ export async function runCommand(argv, options = {}) {
     child.stderr.on("data", chunk => { stderr = append(stderr, chunk); });
     child.on("error", fail);
     child.on("close", (code, signal) => {
-      if (settled || terminationError) return;
+      if (settled) return;
+      if (terminationError) {
+        // A closed pipe alone says nothing about descendants. Only ESRCH proves
+        // the owned POSIX group is gone; otherwise retain the escalation timer.
+        if (process.platform !== "win32" && child.pid) {
+          try { process.kill(-child.pid, 0); }
+          catch (error) { if (error.code === "ESRCH") fail(terminationError); }
+        }
+        return;
+      }
       settled = true;
       cleanup();
       resolve({ stdout, stderr, exitCode: code ?? (128 + (constants.signals[signal] ?? 1)), signal, outputTruncated });

package/{bottleneck.js → src/output/bottleneck.js}

@@ -1,8 +1,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
-import { isString, isObject } from "./decode.js";
-import { truncateChars, formatValue } from "./format.js";
+import { isString, isObject } from "../shared/decode.js";
+import { truncateChars, formatReturn } from "./format.js";
 
 function json(value) {
   try { return JSON.stringify(value) ?? "null"; } catch { return JSON.stringify(String(value)); }
@@ -80,12 +80,15 @@ export function packageHostResult(raw, config) {
   const text = batch ? "" : extractRawString(raw);
   const capped = truncateChars(text, maxChars, "host-result");
   let truncated = capped.truncated || details?.outputTruncated === true;
-  const result = { ok: !hostResultFailed(raw), value: capped.text, truncated };
+  const image = raw?.content?.find(part => part?.type === "image");
+  const result = { ok: !hostResultFailed(raw), value: image ?? capped.text, truncated };
   if (details !== undefined) result.details = summarizeDetails(batch ? { ...details, items: undefined } : details);
   if (batch) {
+    result.itemErrors = (details.itemErrors ?? []).map(error => error == null ? null : truncateChars(String(error), Math.max(1, Math.floor(maxChars / batch.length)), "error").text);
     let remaining = maxChars;
     result.items = batch.map((item, index) => {
-      const bounded = truncateChars(item, Math.floor(remaining / (batch.length - index)), "host-result");
+      if (item?.type === "image") return item;
+      const bounded = truncateChars(item, details.independent === true ? maxChars : Math.floor(remaining / (batch.length - index)), "host-result");
       remaining -= bounded.text.length;
       truncated ||= bounded.truncated;
       return bounded.text;
@@ -111,7 +114,21 @@ export function packageHostResult(raw, config) {
 }
 
 export function packageFinalReturn(value, logs, config) {
-  const serialized = truncateChars(isString(value) ? value : formatValue(value), config.maxReturnChars ?? 32000, "return");
+  const images = [];
+  let imageBytes = 0;
+  const collect = input => {
+    if (input?.type === "image" && isString(input.data) && isString(input.mimeType) && input.mimeType.startsWith("image/")) {
+      imageBytes += Buffer.byteLength(input.data, "base64");
+      if (images.length >= 16 || imageBytes > 20 * 1024 * 1024) throw new Error("returned images exceed 16 attachments or 20 MiB; return fewer or smaller images");
+      images.push({ type: "image", data: input.data, mimeType: input.mimeType });
+      return `[image ${images.length}: ${input.mimeType}]`;
+    }
+    if (Array.isArray(input)) return input.map(collect);
+    if (isObject(input)) return Object.fromEntries(Object.entries(input).map(([key, child]) => [key, collect(child)]));
+    return input;
+  };
+  value = collect(value);
+  const serialized = truncateChars(formatReturn(value), config.maxReturnChars ?? 32000, "return");
   const maxLines = config.maxLogLines ?? 100;
   let logTruncated = logs.length > maxLines;
   const clipped = logs.slice(0, maxLines).map(line => {
@@ -120,5 +137,5 @@ export function packageFinalReturn(value, logs, config) {
     return result.text;
   });
   return { returnValue: serialized.truncated ? serialized.text : value, returnText: serialized.text,
-    returnTruncated: serialized.truncated, logs: clipped, logTruncated };
+    returnTruncated: serialized.truncated, logs: clipped, logTruncated, images };
 }

package/{format.js → src/output/format.js}

@@ -1,4 +1,4 @@
-import { isString, isObject } from "./decode.js";
+import { isString, isObject } from "../shared/decode.js";
 
 export function truncateChars(text, maxChars, label = "value") {
   const normalized = isString(text) ? text : String(text ?? "");
@@ -43,6 +43,25 @@ function tailStartIndex(text, tail) {
   return code >= 0xdc00 && code <= 0xdfff ? start + 1 : start;
 }
 
+// Unicode mode matches lone surrogate code points, not valid UTF-16 pairs.
+const UNPAIRED_SURROGATE = /[\uD800-\uDFFF]/u;
+
+function hasWellFormedStrings(values) {
+  for (const value of values) if (!isString(value) || UNPAIRED_SURROGATE.test(value)) return false;
+  return true;
+}
+
+/** Lossless framing for source arrays, not string escaping or source compression. */
+export function formatReturn(value) {
+  if (isString(value)) return value;
+  if (Array.isArray(value) && value.length && hasWellFormedStrings(value) && value.some(text => text.includes("\n"))) {
+    const raw = "strings[" + value.length + "]\n" + value.map((text, i) => "[" + i + "] " + text.length + " UTF-16 units\n" + text + "\n").join("");
+    const escapedSize = value.reduce((sum, text) => sum + JSON.stringify(text).length, value.length + 1);
+    if (raw.length < escapedSize) return raw;
+  }
+  return formatValue(value);
+}
+
 const IDENT_KEY = /^[A-Za-z_$][\w$]*$/;
 const FORMAT_WIDTH = 120;
 

package/{guest-worker.js → src/runtime/guest-worker.js}

@@ -1,14 +1,14 @@
 import { parentPort } from "node:worker_threads";
-import { parallel as runParallel, pipeline as runPipeline } from "./parallel.js";
-import { isString, isObject, toPlain } from "./decode.js";
-import { truncateChars } from "./format.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { isString, isObject, isFunction, toPlain } from "../shared/decode.js";
+import { truncateChars } from "../output/format.js";
 
 // Guest programs run here, off the host thread. The host can terminate() this
 // worker mid-loop, so a runaway "while (true) {}" or process.exit() in guest
 // code cannot take the harness down with it.
 
 const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor;
-const PARAMS = ["nova", "console", "parallel", "pipeline", "read", "write", "edit", "patch", "surface", "snap", "evidence", "bash", "exec", "speculate"];
+const PARAMS = ["console", "read", "edit", "write", "bash"];
 const BODY_LINE_OFFSET = 2;
 /** Best-effort guest line:col from an error stack (V8 "<anonymous>:L:C", JSC "eval code").*/
 function guestLocation(err) {
@@ -67,9 +67,15 @@ function leanEnvelope(res) {
   return res;
 }
 
-function buildGuestApi(available, batchRead, runId) {
+function buildGuestApi(available, batchRead, runId, nativeArgv) {
   const rpc = (method, args) => callRpc(runId, method, args);
   const availableSet = new Set(available);
+  const checkpointScope = new AsyncLocalStorage();
+  let checkpoint = null;
+  const assertScope = () => {
+    const token = checkpointScope.getStore();
+    if (token ? token !== checkpoint : checkpoint !== null) throw new Error("await the active edit checkpoint before issuing other commands; completed checkpoints cannot issue commands");
+  };
   const nova = {
     search: (query, limit) => rpc("search", [query, limit]),
     describe: (name) => rpc("describe", [name]),
@@ -85,15 +91,23 @@ function buildGuestApi(available, batchRead, runId) {
       return results;
     },
     async speculate(fn) {
-      await rpc("speculateBegin", []);
+      if (checkpoint) throw new Error("edit checkpoints cannot overlap or nest; await the current checkpoint");
+      const token = {};
+      checkpoint = token;
+      let began = false;
       try {
-        const value = await fn();
+        flushReads();
+        await rpc("speculateBegin", []);
+        began = true;
+        const value = await checkpointScope.run(token, fn);
+        flushReads();
         await rpc("speculateCommit", []);
         return { ok: true, committed: true, value };
       } catch (err) {
-        await rpc("speculateRollback", []);
+        flushReads();
+        if (began) await rpc("speculateRollback", []);
         return { ok: false, committed: false, error: err instanceof Error ? err.message : String(err) };
-      }
+      } finally { checkpoint = null; }
     },
     surface: async (filePath) => unwrapJsonValue(await rpc("call", ["surface", { path: filePath }])),
     evidence: async (query, opts) => unwrapJsonValue(await rpc("call", ["evidence", { query, ...opts }])),
@@ -101,24 +115,80 @@ function buildGuestApi(available, batchRead, runId) {
     has: (name) => availableSet.has(name),
   };
 
-  // read(path, offset?, limit?) or read(path, { about, offset, limit, maxChars })
-  const readArgs = (p, a, b) => (isObject(a) && !Array.isArray(a) ? { path: p, ...a } : { path: p, offset: a, limit: b });
+  // Coalesce already-started compatible reads without rewriting JS control flow.
+  let queuedReads = [];
+  function flushReads() {
+    const pending = queuedReads;
+    queuedReads = [];
+    for (let start = 0; start < pending.length; start += 64) {
+      const wave = pending.slice(start, start + 64);
+      const args = { ...wave[0].args, path: wave.map(job => job.args.path), _independent: true };
+      const run = wave.length === 1
+        ? nova.call("read", wave[0].args).then(res => ({ values: [unwrapValue(res)], errors: [] }))
+        : nova.call("read", args).then(res => { unwrapValue(res); return { values: res.items, errors: res.itemErrors ?? [] }; });
+      void run.then(({ values, errors }) => {
+        if (!Array.isArray(values) || values.length !== wave.length) throw new Error("invalid batch read response");
+        for (let i = 0; i < wave.length; i++) {
+          const value = values[i];
+          if (errors[i]) wave[i].reject(new Error(errors[i]));
+          else wave[i].resolve(value);
+        }
+      }).catch(error => { for (const job of wave) job.reject(error); });
+    }
+  }
+  const invoke = (name, args) => { assertScope(); flushReads(); return nova.call(name, args); };
+  const readArgs = (p, a, b) => isObject(p) && !Array.isArray(p)
+    ? { ...p, path: p.path ?? p.query }
+    : isObject(a) && !Array.isArray(a) ? { path: p, ...a } : { path: p, offset: a, limit: b };
   const read = async (p, a, b) => {
+    assertScope();
+    const args = readArgs(p, a, b);
+    const evidencePath = isObject(p) && !Array.isArray(p) ? p.path : args.about ? p : undefined;
+    p = args.path;
+    if (args.evidence) return unwrapJsonValue(await invoke("evidence", { ...args, path: evidencePath, query: args.about ?? args.query ?? p }));
+    if (args.outline) return unwrapJsonValue(await invoke("surface", args));
     if (Array.isArray(p)) {
-      if (!batchRead) return Promise.all(p.map(item => read(item, a, b)));
-      const res = await nova.call("read", readArgs(p, a, b));
+      if (p.length > 64) throw new Error("read accepts at most 64 paths per batch");
+      if (p.some(item => !isString(item) || !item.trim())) throw new Error("read paths must be non-empty strings");
+      const readEach = () => Promise.all(p.map(async item => {
+        try { return await read({ ...args, path: item }); }
+        catch (error) { return `[read error: ${item}] ${error.message}`; }
+      }));
+      if (!batchRead || args.resolve) return readEach();
+      const res = await invoke("read", args);
       unwrapValue(res);
       if (Array.isArray(res?.items)) return res.items;
       // Captured host executor without batch support: fan out.
-      return Promise.all(p.map((item) => read(item, a, b)));
+      return readEach();
     }
-    return unwrapValue(await nova.call("read", readArgs(p, a, b)));
+    if (!batchRead) return args.resolve ? unwrapJsonValue(await invoke("read", args)) : unwrapValue(await invoke("read", args));
+    const key = JSON.stringify({ ...args, path: undefined });
+    if (queuedReads.length && queuedReads[0].key !== key) flushReads();
+    return new Promise((resolve, reject) => {
+      queuedReads.push({ args, key, resolve, reject });
+      if (queuedReads.length === 1) queueMicrotask(flushReads);
+    }).then(value => args.resolve ? JSON.parse(value) : value);
+  };
+  const write = async (p, content) => unwrapValue(await invoke("write", isObject(p) ? p : { path: p, content }));
+  const edit = async (p, oldText, newText) => {
+    if (isFunction(p)) return nova.speculate(p);
+    const args = isObject(p) ? p : Array.isArray(oldText) ? { path: p, edits: oldText } : { path: p, oldText, newText };
+    return unwrapValue(await invoke(args.patch === undefined ? "edit" : "apply_patch", args));
   };
-  const write = async (p, content) => unwrapValue(await nova.call("write", { path: p, content }));
-  const edit = async (p, oldText, newText) => unwrapValue(await nova.call("edit", { path: p, oldText, newText }));
   const patch = async (p, diff) => unwrapValue(await nova.call("apply_patch", { path: p, patch: diff }));
   const bash = async (command, opts) => {
-    const res = await nova.call("bash", { command, ...opts });
+    const args = isObject(command) ? { ...command } : { command, ...opts };
+    if (args.args !== undefined) {
+      if (!isString(args.command) || !Array.isArray(args.args) || args.args.some(arg => !isString(arg))) throw new Error("bash argv requires a command string and an array of string args");
+      if (nativeArgv) args._directArgv = true;
+      else {
+        delete args._directArgv;
+        args.command = [args.command, ...args.args].map(quoteShellArg).join(" ");
+      }
+    }
+    command = args.command;
+    if (args.timeout !== undefined && args.timeoutMs === undefined) args.timeoutMs = args.timeout * 1000;
+    const res = await invoke("bash", args);
     if (res?.ok === false) {
       let exitCode;
       try {
@@ -188,12 +258,11 @@ async function handleRun(msg) {
     postFailure(runId, err);
     return;
   }
-  const api = buildGuestApi(available, batchRead, runId);
+  const api = buildGuestApi(available, batchRead, runId, msg.nativeArgv === true);
   const scopedConsole = makeConsole(runId, limits);
   try {
     const value = await compiled.fn(
-      api.nova, scopedConsole, runParallel, runPipeline,
-      api.read, api.write, api.edit, api.patch, api.surface, api.snap, api.evidence, api.bash, api.exec, api.speculate,
+      scopedConsole, api.read, api.edit, api.write, api.bash,
     );
     if (runId !== activeRunId) return;
     let plain;

package/{parallel.js → src/runtime/parallel.js}

@@ -1,4 +1,4 @@
-import { isFunction } from "./decode.js";
+import { isFunction } from "../shared/decode.js";
 
 const READ_ONLY_TOOLS = new Set(["read", "grep", "glob", "find", "ls", "snap", "evidence", "surface", "asgrep_search", "asgrep_status", "ast_grep", "web_search"]);
 const READ_ONLY_LSP = new Set(["definition", "references", "hover", "symbols", "diagnostics", "implementation", "type_definition", "incoming_calls", "outgoing_calls"]);
@@ -19,6 +19,73 @@ export function isMutatingTool(name, config = {}, args = {}, definition) {
   return !READ_ONLY_TOOLS.has(name);
 }
 
+/** FIFO read waves with mutation barriers; callers keep independent promises. */
+export function createNativeScheduler({ maxParallelReads = 8 } = {}) {
+  if (!Number.isInteger(maxParallelReads) || maxParallelReads < 1) throw new Error("maxParallelReads must be a positive integer");
+  const queue = [];
+  const stats = { calls: 0, readWaves: 0, peakParallelReads: 0 };
+  let draining = false;
+
+  async function drain() {
+    try {
+      while (queue.length) {
+        const first = queue.shift();
+        if (first.cancelled) continue;
+        const wave = [first];
+        if (first.name === "read") {
+          while (wave.length < maxParallelReads && queue[0]?.name === "read") {
+            const next = queue.shift();
+            if (!next.cancelled) wave.push(next);
+          }
+          stats.readWaves++;
+          stats.peakParallelReads = Math.max(stats.peakParallelReads, wave.length);
+        }
+        // Settle each promise separately: one failed read must not discard its
+        // siblings or release a write barrier while other reads are still active.
+        await Promise.all(wave.map(async job => {
+          if (job.cancelled) return;
+          job.started = true;
+          job.signal?.removeEventListener("abort", job.abort);
+          try {
+            job.signal?.throwIfAborted();
+            const result = await job.run();
+            job.signal?.throwIfAborted();
+            job.resolve(result);
+          } catch (error) { job.reject(error); }
+        }));
+      }
+    } finally { draining = false; }
+  }
+
+  return {
+    stats,
+    schedule(name, run, signal) {
+      if (!["read", "edit", "write", "bash"].includes(name) || !isFunction(run)) {
+        return Promise.reject(new Error("scheduler requires a native tool and an executor"));
+      }
+      if (signal?.aborted) return Promise.reject(signal.reason ?? new Error("aborted"));
+      stats.calls++;
+      return new Promise((resolve, reject) => {
+        const job = { name, run, signal, resolve, reject, started: false, cancelled: false };
+        job.abort = () => {
+          if (job.started) return;
+          job.cancelled = true;
+          signal.removeEventListener("abort", job.abort);
+          reject(signal.reason ?? new Error("aborted"));
+        };
+        signal?.addEventListener("abort", job.abort, { once: true });
+        queue.push(job);
+        if (!draining) {
+          draining = true;
+          // Pi submits sibling tools in the same turn without model-side code.
+          // Collect those submissions before selecting the first read wave.
+          queueMicrotask(() => { void drain(); });
+        }
+      });
+    },
+  };
+}
+
 function requireArray(value, name) {
   if (!Array.isArray(value)) throw new TypeError(name + " requires an array");
   return value;

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

@@ -1,8 +1,9 @@
 import { Worker } from "node:worker_threads";
 import { parse } from "acorn";
 import { performance } from "node:perf_hooks";
-import { packageFinalReturn } from "./bottleneck.js";
-import { isFunction, isObject, isString } from "./decode.js";
+import { packageFinalReturn } from "../output/bottleneck.js";
+import { truncateChars } from "../output/format.js";
+import { isFunction, isObject, isString } from "../shared/decode.js";
 
 const WORKER_URL = new URL("./guest-worker.js", import.meta.url);
 const ABORT_MESSAGE = "supernova timed out or aborted: pass timeoutMs to allow longer runs, or split the program";
@@ -52,7 +53,10 @@ function prepareProgram(code) {
 
 function spawnWorker(config) {
   const maxHeapMb = config.maxHeapMb ?? 512;
-  const worker = new Worker(WORKER_URL, { resourceLimits: { maxOldGenerationSizeMb: maxHeapMb } });
+  // An inline bootstrap accepts inherited --input-type from stdin/eval SDK hosts.
+  // Keep Node's automatic flag inheritance: explicitly copying execArgv can
+  // reintroduce process-only V8 flags that Worker rejects under node --test.
+  const worker = new Worker("import(" + JSON.stringify(WORKER_URL.href) + ")", { eval: true, resourceLimits: { maxOldGenerationSizeMb: maxHeapMb } });
   const handle = { worker, maxHeapMb, dead: false, ready: null };
   // This listener also owns errors between readiness and a run's listeners.
   worker.on("error", () => { handle.dead = true; });
@@ -111,6 +115,10 @@ export function warmGuestWorker(config = {}) {
   return handle.ready;
 }
 
+export function stopWarmGuestWorker() {
+  return killWorker(idleWorker);
+}
+
 const RPC_METHODS = {
   call: (nova, args) => nova.call(args[0], args[1]),
   callMany: async (nova, args) => {
@@ -128,7 +136,7 @@ export async function runGuestProgram({ code, nova = {}, config = {}, signal, on
   const started = performance.now();
   const wall = () => Math.round(performance.now() - started);
   const logs = [];
-  const fail = (error) => ({ ok: false, error, logs, logTruncated, wallMs: wall() });
+  const fail = (error) => ({ ok: false, error: truncateChars(String(error), config.maxReturnChars ?? 32000, "error").text, logs, logTruncated, wallMs: wall() });
   let logTruncated = false;
   if (!isString(code) || !code.trim()) return fail("code must be a non-empty string");
   if (code.length > (config.maxCodeChars ?? 48000)) return fail("code exceeds " + (config.maxCodeChars ?? 48000) + " characters");
@@ -234,7 +242,7 @@ export async function runGuestProgram({ code, nova = {}, config = {}, signal, on
         try {
           const packed = packageFinalReturn(msg.value, logs, config);
           void complete({ ok: true, result: packed.returnValue, resultText: packed.returnText,
-            returnTruncated: packed.returnTruncated, undefinedReturn: msg.undefinedReturn === true,
+            returnTruncated: packed.returnTruncated, images: packed.images, undefinedReturn: msg.undefinedReturn === true,
             logs: packed.logs, logTruncated: logTruncated || packed.logTruncated });
         } catch (err) {
           void complete(fail(err.message));
@@ -260,6 +268,7 @@ export async function runGuestProgram({ code, nova = {}, config = {}, signal, on
         if (wall() >= timeoutMs) return abort();
         handle.worker.postMessage({ op: "run", runId, prepared, available,
           batchRead: nova.batchRead !== false,
+          nativeArgv: nova.nativeArgv === true,
           limits: { maxLogLines: config.maxLogLines ?? 100, maxLogLineChars: config.maxLogLineChars ?? 4096 } });
       } catch (err) {
         cancelHost();

package/{omp-frame.js → src/ui/omp-frame.js}

@@ -6,7 +6,7 @@
  */
 
 import { clampLine, measureWidth } from "./render-measure.js";
-import { isFunction, isString } from "./decode.js";
+import { isFunction, isString } from "../shared/decode.js";
 
 const DEFAULT_BOX = {
 	topLeft: "╭",