pi-supernova 0.5.0 → 0.6.0

package/src/fs/workspace.js

@@ -16,6 +16,9 @@ const realNearest = new Map();
 const PATH_CACHE_MAX = 2048;
 
 export function clearPathCache() {
+  cachedCwd = null;
+  cachedResolvedCwd = null;
+  realRoots.clear();
   realNearest.clear();
 }
 
@@ -126,7 +129,10 @@ export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = f
 export async function runCommand(argv, options = {}) {
   options.signal?.throwIfAborted();
   const cwd = options.cwd || process.cwd();
-  const timeoutMs = options.timeoutMs ?? 60_000;
+  const requestedTimeout = Number(options.timeoutMs === undefined ? 60_000 : options.timeoutMs);
+
+  if (!Number.isFinite(requestedTimeout) || requestedTimeout <= 0) throw new Error("command timeoutMs must be a positive finite number");
+  const timeoutMs = Math.max(1, Math.min(2_147_483_647, Math.floor(requestedTimeout)));
   const maxOutputChars = options.maxOutputChars ?? 2 * 1024 * 1024;
 
   return new Promise((resolve, reject) => {

package/src/output/bottleneck.js

@@ -19,7 +19,7 @@ function detailsOf(raw) {
 export function hostResultFailed(raw) {
   const details = detailsOf(raw);
 
-  return raw?.isError === true || details?.ok === false || (Number.isInteger(details?.exitCode) && details.exitCode !== 0);
+  return raw?.isError === true || raw?.ok === false || details?.ok === false || (Number.isInteger(details?.exitCode) && details.exitCode !== 0);
 }
 
 function extractRawString(raw) {
@@ -92,12 +92,16 @@ function summarizeDetails(value, budget = 2000) {
 }
 
 function spill(fullText, config) {
-  if (!isString(config.spillDir) || !config.spillDir) return undefined;
-  fs.mkdirSync(config.spillDir, { recursive: true, mode: 0o700 });
-  const file = path.join(config.spillDir, Date.now() + "-" + randomUUID().slice(0, 8) + ".txt");
-  fs.writeFileSync(file, fullText, { encoding: "utf8", mode: 0o600, flag: "wx" });
-
-  return file;
+  try {
+    if (!isString(config.spillDir) || !config.spillDir) return undefined;
+    fs.mkdirSync(config.spillDir, { recursive: true, mode: 0o700 });
+    const file = path.join(config.spillDir, Date.now() + "-" + randomUUID().slice(0, 8) + ".txt");
+    fs.writeFileSync(file, fullText, { encoding: "utf8", mode: 0o600, flag: "wx" });
+
+    return file;
+  } catch {
+    return undefined;
+  }
 }
 
 export function packageHostResult(raw, config) {
@@ -108,7 +112,10 @@ export function packageHostResult(raw, config) {
   const capped = truncateChars(text, maxChars, "host-result");
   let truncated = capped.truncated || details?.outputTruncated === true;
   const image = raw?.content?.find(part => part?.type === "image");
-  const result = { ok: !hostResultFailed(raw), value: image ?? capped.text, truncated };
+  const directoryEntries = image === undefined && details?.directory === true && Array.isArray(details.entries) && json(details.entries).length <= maxChars
+    ? details.entries
+    : undefined;
+  const result = { ok: !hostResultFailed(raw), value: image ?? directoryEntries ?? capped.text, truncated };
 
   if (details !== undefined) result.details = summarizeDetails(batch ? { ...details, items: undefined } : details);
 
@@ -117,7 +124,25 @@ export function packageHostResult(raw, config) {
     let remaining = maxChars;
     result.items = batch.map((item, index) => {
       if (item?.type === "image") return item;
-      const bounded = truncateChars(item, details.independent === true ? maxChars : Math.floor(remaining / (batch.length - index)), "host-result");
+      const share = details.independent === true ? maxChars : Math.floor(remaining / (batch.length - index));
+
+      if (!isString(item)) {
+        const encoded = json(item);
+
+        if (encoded.length <= share) {
+          remaining -= encoded.length;
+
+          return item;
+        }
+
+        const bounded = truncateChars(encoded, share, "host-result");
+        remaining -= bounded.text.length;
+        truncated ||= bounded.truncated;
+
+        return bounded.text;
+      }
+
+      const bounded = truncateChars(item, share, "host-result");
       remaining -= bounded.text.length;
       truncated ||= bounded.truncated;
 
@@ -128,10 +153,10 @@ export function packageHostResult(raw, config) {
   result.truncated = truncated;
 
   if (truncated) {
-    result.originalChars = batch ? batch.reduce((sum, item) => sum + String(item).length, 0) : text.length;
+    result.originalChars = batch ? batch.reduce((sum, item) => sum + (isString(item) ? item.length : json(item).length), 0) : text.length;
 
     if (config.spillDir) {
-      const pointer = spill(batch ? batch.join("\n---\n") : text, config);
+      const pointer = spill(batch ? batch.map(item => isString(item) ? item : json(item)).join("\n---\n") : text, config);
 
       if (pointer) {
         result.spill = pointer;

package/src/output/format.js

@@ -143,7 +143,8 @@ function formatPrimitive(value) {
 
   if (Number.isNaN(value) || value === Infinity || value === -Infinity) return String(value);
 
-  return JSON.stringify(value) ?? String(value);
+  try { return JSON.stringify(value) ?? String(value); }
+  catch { return String(value); }
 }
 
 /**
@@ -168,39 +169,46 @@ function formatFlatWithin(value, limit) {
     return true;
   };
 
-  return walkFlat(value, push) ? parts.join("") : null;
+  return walkFlat(value, push, new Set()) ? parts.join("") : null;
 }
 
-function walkFlat(value, push) {
+function walkFlat(value, push, seen) {
   if (value?.[RAW_TEXT] !== undefined) return push(value[RAW_TEXT]);
 
   if (!isObject(value) && !Array.isArray(value)) return push(formatPrimitive(value));
 
-  if (Array.isArray(value)) {
-    if (value.length === 0) return push("[]");
+  if (seen.has(value)) return push("[Circular]");
+  seen.add(value);
 
-    if (!push("[")) return false;
+  try {
+    if (Array.isArray(value)) {
+      if (value.length === 0) return push("[]");
 
-    for (let i = 0; i < value.length; i++) {
-      if (i && !push(",")) return false;
+      if (!push("[")) return false;
 
-      if (!walkFlat(value[i] === undefined ? null : value[i], push)) return false;
+      for (let i = 0; i < value.length; i++) {
+        if (i && !push(",")) return false;
+
+        if (!walkFlat(value[i] === undefined ? null : value[i], push, seen)) return false;
+      }
+
+      return push("]");
     }
 
-    return push("]");
-  }
+    const keys = Object.keys(value).filter((key) => value[key] !== undefined);
 
-  const keys = Object.keys(value).filter((key) => value[key] !== undefined);
+    if (keys.length === 0) return push("{}");
 
-  if (keys.length === 0) return push("{}");
+    for (let i = 0; i < keys.length; i++) {
+      if (!push((i ? "," : "{") + formatKey(keys[i]) + ":")) return false;
 
-  for (let i = 0; i < keys.length; i++) {
-    if (!push((i ? "," : "{") + formatKey(keys[i]) + ":")) return false;
+      if (!walkFlat(value[keys[i]], push, seen)) return false;
+    }
 
-    if (!walkFlat(value[keys[i]], push)) return false;
+    return push("}");
+  } finally {
+    seen.delete(value);
   }
-
-  return push("}");
 }
 
 /**
@@ -209,24 +217,31 @@ function walkFlat(value, push) {
  * indent is one space. Whitespace is what costs tokens: this measures ~43% fewer
  * than JSON.stringify(value, null, 2) on typical shaped returns (gpt-tokenizer).
  */
-export function formatValue(value, indent = "", width = FORMAT_WIDTH) {
+export function formatValue(value, indent = "", width = FORMAT_WIDTH, seen = new Set()) {
   if (value?.[RAW_TEXT] !== undefined) return value[RAW_TEXT];
 
   if (!isObject(value) && !Array.isArray(value)) return formatPrimitive(value);
-  const flat = formatFlatWithin(value, width - indent.length);
+  if (seen.has(value)) return "[Circular]";
+  seen.add(value);
 
-  if (flat !== null) return flat;
-  const pad = indent + " ";
+  try {
+    const flat = formatFlatWithin(value, width - indent.length);
 
-  if (Array.isArray(value)) {
-    if (value.length === 0) return "[]";
+    if (flat !== null) return flat;
+    const pad = indent + " ";
 
-    return "[\n" + value.map((item) => pad + formatValue(item === undefined ? null : item, pad, width)).join(",\n") + "\n" + indent + "]";
-  }
+    if (Array.isArray(value)) {
+      if (value.length === 0) return "[]";
+
+      return "[\n" + value.map((item) => pad + formatValue(item === undefined ? null : item, pad, width, seen)).join(",\n") + "\n" + indent + "]";
+    }
 
-  const keys = Object.keys(value).filter((key) => value[key] !== undefined);
+    const keys = Object.keys(value).filter((key) => value[key] !== undefined);
 
-  if (keys.length === 0) return "{}";
+    if (keys.length === 0) return "{}";
 
-  return "{\n" + keys.map((key) => pad + formatKey(key) + ":" + formatValue(value[key], pad, width)).join(",\n") + "\n" + indent + "}";
+    return "{\n" + keys.map((key) => pad + formatKey(key) + ":" + formatValue(value[key], pad, width, seen)).join(",\n") + "\n" + indent + "}";
+  } finally {
+    seen.delete(value);
+  }
 }

package/src/runtime/guest-worker.js

@@ -110,18 +110,41 @@ function buildGuestApi(available, batchRead, runId, _nativeArgv) {
     if (token ? token !== checkpoint : checkpoint !== null) throw new Error("await the active edit checkpoint before issuing other commands; completed checkpoints cannot issue commands");
   };
 
+  let operationTail = Promise.resolve();
+
+  const enqueueHost = operation => {
+    const next = operationTail.then(operation);
+    operationTail = next.then(() => {}, () => {});
+
+    return next;
+  };
+
   const nova = {
-    call: async (name, args) => leanEnvelope(await rpc("call", [name, args])),
-    async callMany(calls) {
-      const wave = await rpc("callMany", [calls]);
-      const results = Array.isArray(wave?.results) ? wave.results : Array.isArray(wave) ? wave : [];
-      Object.defineProperties(results, {
-        mode: { value: wave?.mode, enumerable: false },
-        reason: { value: wave?.reason, enumerable: false },
-        results: { value: results, enumerable: false },
+    call(name, args) {
+      assertScope(); flushReads();
+      const promise = enqueueHost(() => rpc("call", [name, args]).then(leanEnvelope));
+
+      promise.catch(() => {});
+
+      return promise;
+    },
+    callMany(calls) {
+      assertScope(); flushReads();
+      const promise = enqueueHost(async () => {
+        const wave = await rpc("callMany", [calls]);
+        const results = Array.isArray(wave?.results) ? wave.results : Array.isArray(wave) ? wave : [];
+        Object.defineProperties(results, {
+          mode: { value: wave?.mode, enumerable: false },
+          reason: { value: wave?.reason, enumerable: false },
+          results: { value: results, enumerable: false },
+        });
+
+        return results;
       });
 
-      return results;
+      promise.catch(() => {});
+
+      return promise;
     },
     async speculate(fn) {
       if (checkpoint) throw new Error("edit checkpoints cannot overlap or nest; await the current checkpoint");
@@ -130,30 +153,31 @@ function buildGuestApi(available, batchRead, runId, _nativeArgv) {
       let began = false;
 
       try {
-        flushReads();
-        await rpc("speculateBegin", []);
+        await drainReads();
+        await enqueueHost(() => rpc("speculateBegin", []));
         began = true;
         const value = await checkpointScope.run(token, fn);
-        flushReads();
-        await rpc("speculateCommit", []);
+        await drainReads();
+        await enqueueHost(() => rpc("speculateCommit", []));
 
         return { ok: true, committed: true, value };
       } catch (err) {
-        flushReads();
+        await drainReads();
 
-        if (began) await rpc("speculateRollback", []);
+        if (began) await enqueueHost(() => 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 }])),
-    snap: async (query, targetPath) => unwrapJsonValue(await rpc("call", ["snap", { query, path: targetPath }])),
+    surface(filePath) { assertScope(); flushReads(); const promise = enqueueHost(() => rpc("call", ["surface", { path: filePath }]).then(unwrapJsonValue)); promise.catch(() => {}); return promise; },
+    evidence(query, opts) { assertScope(); flushReads(); const promise = enqueueHost(() => rpc("call", ["evidence", { query, ...opts }]).then(unwrapJsonValue)); promise.catch(() => {}); return promise; },
+    snap(query, targetPath) { assertScope(); flushReads(); const promise = enqueueHost(() => rpc("call", ["snap", { query, path: targetPath }]).then(unwrapJsonValue)); promise.catch(() => {}); return promise; },
     has: (name) => availableSet.has(name),
   };
 
   // Coalesce already-started compatible reads without rewriting JS control flow.
   let queuedReads = [];
+  const pendingReadWaves = new Set();
 
   function flushReads() {
     const pending = queuedReads;
@@ -163,13 +187,13 @@ function buildGuestApi(available, batchRead, runId, _nativeArgv) {
       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: [unwrapRead(res, wave[0].args)], errors: [] }))
-        : nova.call("read", args).then(res => { unwrapRead(res, args);
+      const run = enqueueHost(() => wave.length === 1
+        ? rpc("call", ["read", wave[0].args]).then(leanEnvelope).then(res => ({ values: [unwrapRead(res, wave[0].args)], errors: [] }))
+        : rpc("call", ["read", args]).then(leanEnvelope).then(res => { unwrapRead(res, args);
 
- return { values: res.items, errors: res.itemErrors ?? [] }; });
+ return { values: res.items, errors: res.itemErrors ?? [] }; }));
 
-      void run.then(({ values, errors }) => {
+      const delivery = 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++) {
@@ -179,31 +203,80 @@ function buildGuestApi(available, batchRead, runId, _nativeArgv) {
           else wave[i].resolve(value);
         }
       }).catch(error => { for (const job of wave) job.reject(error); });
+
+      pendingReadWaves.add(delivery);
+      void delivery.finally(() => pendingReadWaves.delete(delivery));
     }
   }
 
-  const invoke = (name, args) => { assertScope(); flushReads();
+  async function drainReads() {
+    for (;;) {
+      flushReads();
+      const waves = [...pendingReadWaves];
+
+      if (!waves.length) return;
+      await Promise.allSettled(waves);
+    }
+  }
+
+  const invoke = (name, args) => {
+    assertScope(); flushReads();
+    const promise = nova.call(name, args);
+
+    promise.catch(() => {});
+
+    return promise;
+  };
+
+  const readArgs = (p, a, b) => {
+    if (isObject(p) && !Array.isArray(p)) {
+      const args = { ...p, path: p.path ?? p.target ?? p.query };
 
- return nova.call(name, args); };
+      if (p.path === undefined && p.target !== undefined) delete args.target;
 
-  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 };
+      return args;
+    }
+
+    return isObject(a) && !Array.isArray(a) ? { path: p, ...a } : { path: p, offset: a, limit: b };
+  };
 
   const read = async (p, a, b) => {
     assertScope();
     const args = sessionJsonArgs(readArgs(p, a, b));
-    if (isString(args.path) && args.resolve === undefined && args.json === undefined && !looksLikePath(args.path) && !/^(?:agent|artifact):\/\//i.test(args.path)) {
+    if (isString(args.path) && args.resolve === undefined && args.complete !== true && args.json === undefined && args.about === undefined && args.query === undefined && !looksLikePath(args.path) && !/^(?:agent|artifact):\/\//i.test(args.path)) {
       args.resolve = true;
     }
     validateJsonRead(args);
-    const decode = value => args.resolve || args.json !== undefined ? JSON.parse(value) : value;
 
-    if (args.complete === true && (args.outline || args.evidence || args.about)) throw new Error("complete:true requires a raw file read, not an outline or evidence view");
-    const evidencePath = isObject(p) && !Array.isArray(p) ? p.path : args.about ? p : undefined;
+    for (const [key, value] of [["resolve", args.resolve], ["complete", args.complete], ["outline", args.outline], ["evidence", args.evidence]]) {
+      if (value !== undefined && typeof value !== "boolean") throw new Error("read " + key + " must be a boolean");
+    }
+
+    if (args.about !== undefined && !isString(args.about)) throw new Error("read about must be a string");
+    if (args.query !== undefined && !isString(args.query)) throw new Error("read query must be a string");
+    const focusModes = [args.about !== undefined, args.query !== undefined, args.outline === true].filter(Boolean).length;
+
+    if (focusModes > 1 || (args.outline === true && args.evidence === true)) throw new Error("read accepts only one of about, query, outline, or evidence");
+    if (args.resolve === true && args.complete === true) throw new Error("read accepts either resolve or complete, not both");
+    const decode = value => {
+      if ((!args.resolve && args.json === undefined) || !isString(value)) return value;
+
+      try {
+        return JSON.parse(value);
+      } catch (error) {
+        const selector = args.json === undefined ? "" : " (" + (Array.isArray(args.json) ? args.json.join(", ") : String(args.json)) + ")";
+        throw new Error("JSON read failed for " + String(args.path ?? args.target ?? "resource") + selector + ": " + (error instanceof Error ? error.message : String(error)));
+      }
+    };
+
+    if (args.complete === true && (args.outline || args.evidence || args.about || args.query)) throw new Error("complete:true requires a raw file read, not a source view");
+    const evidencePath = isObject(p) && !Array.isArray(p) ? p.path : (isString(p) && looksLikePath(p) ? p : undefined);
     p = args.path;
 
-    if (args.evidence) return unwrapJsonValue(await invoke("evidence", { ...args, path: evidencePath, query: args.about ?? args.query ?? p }));
+    if (args.evidence) {
+      const query = args.about ?? args.query ?? (isString(p) ? p : undefined);
+      return unwrapJsonValue(await invoke("evidence", { ...args, path: evidencePath, query }));
+    }
 
     if (args.outline) return unwrapJsonValue(await invoke("surface", args));
 
@@ -211,9 +284,24 @@ function buildGuestApi(available, batchRead, runId, _nativeArgv) {
       if (p.length > 64) throw new Error("read accepts at most 64 paths per batch");
 
       for (const item of p) if (!isString(item) || !item.trim()) throw new Error("read paths must be non-empty strings");
-      const readEach = () => Promise.all(p.map(item => read({ ...args, path: item })));
+      const readEach = async () => {
+        const values = await Promise.all(p.map(item => read({ ...args, path: item })));
+        const missing = args.resolve ? values.findIndex((value, index) => value?.status === "not_found" && looksLikePath(p[index])) : -1;
 
-      if (!batchRead || args.resolve || p.some(item => /^(agent|artifact):\/\/.*\?/i.test(item))) return readEach();
+        if (missing >= 0) throw new Error(`read failed for ${p[missing]}: not_found; use Promise.allSettled(paths.map(path => read(path))) for per-path outcomes`);
+
+        return values;
+      };
+
+      const guardedReadEach = () => {
+        const promise = readEach();
+
+        promise.catch(() => {});
+
+        return promise;
+      };
+
+      if (!batchRead || args.resolve || p.some(item => /^(agent|artifact):\/\/.*\?/i.test(item))) return guardedReadEach();
       const res = await invoke("read", args);
       const failed = res?.itemErrors?.findIndex(error => error != null) ?? -1;
 
@@ -223,7 +311,7 @@ function buildGuestApi(available, batchRead, runId, _nativeArgv) {
       if (Array.isArray(res?.items)) return res.items.map(decode);
 
       // Captured host executor without batch support: fan out.
-      return readEach();
+      return guardedReadEach();
     }
 
     if (!batchRead) {
@@ -237,11 +325,15 @@ function buildGuestApi(available, batchRead, runId, _nativeArgv) {
 
     if (queuedReads.length && queuedReads[0].key !== key) flushReads();
 
-    return new Promise((resolve, reject) => {
+    const promise = new Promise((resolve, reject) => {
       queuedReads.push({ args, key, resolve, reject });
 
       if (queuedReads.length === 1) queueMicrotask(flushReads);
     }).then(decode);
+
+    promise.catch(() => {});
+
+    return promise;
   };
 
   const write = async (p, content) => unwrapValue(await invoke("write", isObject(p) ? p : { path: p, content }));
@@ -301,6 +393,7 @@ function buildGuestApi(available, batchRead, runId, _nativeArgv) {
       if (!isString(args.command) || !Array.isArray(args.args)) throw new Error("bash argv requires a command string and an array of string args");
 
       for (let i = 0; i < args.args.length; i++) if (!isString(args.args[i])) throw new Error("bash argv requires a command string and an array of string args");
+      args.args = args.args.map(String);
 
       // Literal argv is a Supernova-owned contract. Host bash tools often ignore
       // `args` and would run only `command` (bare `ssh`). Windows still needs a shell.
@@ -335,7 +428,7 @@ function buildGuestApi(available, batchRead, runId, _nativeArgv) {
     return text;
   };
 
-  return { read, write, edit, bash };
+  return { read, write, edit, bash, nova };
 }
 
 function makeConsole(runId, limits) {
@@ -359,7 +452,10 @@ function makeConsole(runId, limits) {
         if (isString(a)) return a;
 
         try {
-          return JSON.stringify(toPlain(a));
+          const plain = toPlain(a);
+          const encoded = JSON.stringify(plain);
+
+          return encoded === undefined ? String(plain) : encoded;
         } catch {
           return String(a);
         }

package/src/runtime/parallel.js

@@ -1,10 +1,13 @@
-import { isFunction } from "../shared/decode.js";
+import { isFunction, isObject } 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"]);
 
 export function isMutatingTool(name, config = {}, args = {}, definition) {
+  if (!isObject(args)) args = {};
+  name = String(name);
+
   if ((config.mutatingTools ?? []).includes(name)) return true;
 
   if ((config.mutatingPrefixes ?? []).some(prefix => prefix && name.startsWith(prefix))) return true;

package/src/runtime/program-batch.js

@@ -1,7 +1,7 @@
 import { isObject, isString } from "../shared/decode.js";
 import { truncateChars } from "../output/format.js";
 
-const textOf = result => result.content.filter(block => block.type === "text").map(block => block.text).join("\n");
+const textOf = result => (Array.isArray(result?.content) ? result.content : []).filter(block => block?.type === "text").map(block => block.text).join("\n");
 
 const mutationTotals = results => results.reduce((total, result) => {
   const m = result.details?.mutations;
@@ -24,7 +24,7 @@ export function programBatchText(results, total, stopped = "") {
 }
 
 function batchInputs(params, config) {
-  if (["code","file","data"].some(key => params[key] !== undefined)) throw new Error("programs cannot combine with top-level code, file or data; no programs ran");
+  if (["code","file"].some(key => params[key] !== undefined)) throw new Error("programs cannot combine with top-level code or file; no programs ran");
 
   if (!Array.isArray(params.programs) || !params.programs.length || params.programs.length > 32) throw new Error("programs requires 1..32 entries; no programs ran");
 
@@ -35,20 +35,31 @@ function batchInputs(params, config) {
     }
   }
 
+  const hasDefault = params.data !== undefined;
   let encoded;
 
-  try { encoded = JSON.stringify(params.programs); } catch { throw new Error("programs must be JSON-serializable; no programs ran"); }
+  try { encoded = JSON.stringify(hasDefault ? {programs:params.programs,data:params.data} : params.programs); } catch { throw new Error("programs and data must be JSON-serializable; no programs ran"); }
 
   if (encoded.length > (config.maxCodeChars ?? 48000)) throw new Error("programs JSON exceeds the code character budget; no programs ran");
 
-  return JSON.parse(encoded);
+  const parsed = JSON.parse(encoded);
+
+  if (!hasDefault) return parsed;
+  if (!Object.hasOwn(parsed,"data")) throw new Error("data must be JSON-serializable; no programs ran");
+
+  // The runtime snapshots data separately for each fresh guest. An explicit
+  // entry replaces the default wholesale; falsy values are not missing values.
+  return parsed.programs.map(program => program.data === undefined ? {...program,data:parsed.data} : program);
 }
 
 /** Explicit known continuations, not inferred plans, retries, or a shared heap. */
 export async function runProgramBatch(id, params, signal, onUpdate, ctx, config, execute) {
   const programs = batchInputs(params,config);
+  const requestedTimeout = params.timeoutMs === undefined ? config.timeoutMs : Number(params.timeoutMs);
+
+  if (!Number.isFinite(requestedTimeout) || requestedTimeout <= 0) throw new Error("program batch timeoutMs must be a positive finite number");
   const started = performance.now();
-  const timeout = Number.isInteger(params.timeoutMs) ? params.timeoutMs : config.timeoutMs;
+  const timeout = requestedTimeout;
   const deadline = started + timeout;
   const controller = new AbortController();
   const combined = signal ? AbortSignal.any([signal,controller.signal]) : controller.signal;
@@ -76,7 +87,7 @@ export async function runProgramBatch(id, params, signal, onUpdate, ctx, config,
       trace.push(...(result.details?.trace ?? []));
       let image = 0;
 
-      for (const block of result.content) if (block.type === "image") {
+      for (const block of Array.isArray(result?.content) ? result.content : []) if (block?.type === "image" && isString(block.data)) {
         imageBytes += Buffer.byteLength(block.data,"base64");
 
         if (images.length >= 16 || imageBytes > 20*1024*1024) { stopped = "batch image budget exceeded; remaining programs did not run"; break; }

package/src/runtime/program-file.js

@@ -4,6 +4,9 @@ import { resolveWorkspacePath } from "../fs/workspace.js";
 /** Explicit source reuse, never a cached program or a persistent guest heap. */
 export async function readProgramFile(file, cwd, maxChars, signal) {
   signal?.throwIfAborted();
+  const chars = Number(maxChars);
+
+  if (!Number.isInteger(chars) || chars <= 0) throw new Error("program file maxChars must be a positive integer");
   const target = await resolveWorkspacePath(cwd, file, "program file", false, true);
   // A FIFO must fail without waiting for a writer or occupying an I/O worker.
   const handle = await fs.open(target, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
@@ -15,8 +18,8 @@ export async function readProgramFile(file, cwd, maxChars, signal) {
     if (!stat.isFile()) throw new Error("program file requires a regular file");
     // Every UTF-16 unit needs at most three UTF-8 bytes. Also check streamed size:
     // another editor can grow the file after stat. No prefix-only execution.
-    const maxBytes = maxChars * 3;
-    const tooLarge = () => new Error("code exceeds " + maxChars + " characters; split the program");
+    const maxBytes = chars * 3;
+    const tooLarge = () => new Error("code exceeds " + chars + " characters; split the program");
 
     if (stat.size > maxBytes) throw tooLarge();
     const chunks = [];
@@ -33,7 +36,7 @@ export async function readProgramFile(file, cwd, maxChars, signal) {
     // Do not silently replace invalid bytes in executable source. Preserve BOMs.
     const code = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Buffer.concat(chunks));
 
-    if (code.length > maxChars) throw tooLarge();
+    if (code.length > chars) throw tooLarge();
 
     return code;
   } finally { await handle.close(); }

package/src/runtime/reference.js

@@ -1,11 +1,11 @@
 // Complete model-facing API reference; kept in every request, not moved into history.
 export const REFERENCE = `JavaScript async body or arrow with read, write, edit, bash. Strings stay raw. Exactly one of code or file; file rereads that program (same limits, cwd, fresh guest). Caps are UTF-16. Put Markdown/scripts/argv in data.
 
-read(path|paths, offset?, limit?) → raw text or text[]; read(directory) → entries
-read(imagePath) → image (PNG/JPEG/GIF/WebP/BMP)
-read({path,json:".field"}) → parsed JSON; .items[0:3], quoted keys, selector arrays, or true; 16 MiB cap; no jq
+read(path|paths, offset?, limit?) → raw text or text[]; read(directory) → entries[]; up to 64 paths
+read(imagePath) → image (PNG/JPEG/GIF/WebP/BMP); 20 MiB max, 16 attachments max
+read({path,json:".field"}) → parsed JSON; .items[0:3], quoted keys, 1-64 selectors, or true; 16 MiB cap; no jq
 read("agent://id?q=.answer") → JSON field from session artifacts
-read("symbol or question") → same view as resolve:true
+read("symbol or question") → same view as resolve:true; source questions use at most 16 keywords
 read({query,resolve:true}) → {status,path,line,lines,text,complete,nextOffset?}
 read(path,{about}) → matching windows; read({query,evidence:true}) → ranked evidence; read({path,outline:true}) → declarations
 write(path, text) → replace; write({path,content,append:true}) → append without a prior read
@@ -15,4 +15,4 @@ bash(command,{cwd?,timeoutMs?}) → bounded output; nonzero throws
 bash({command,args}) → literal argv, no shell expansion of args
 
 edit oldText is an exact substring of read(); a miss includes a numbered window. Found is a span, not the file; uncertain returns ambiguous, not_found, or incomplete. Check resolve:true status; edit(view,text) replaces that window; edit(view,old,new) is unique inside it. complete:true rejects partial files; use about or offset/limit for large audits. Array reads reject failures; Promise.allSettled for per-path outcomes. Edits stage until success; bash commits preceding writes.
-programs:[{code|file,data?},...] sequential fresh guests, separate commits; stop on failure keeps earlier commits. Separate calls when the next step needs a model decision.`;
+programs:[{code|file,data?},...] sequential fresh guests, separate commits; top-level data defaults per entry, explicit entry data replaces it. Stop on failure keeps earlier commits. Separate calls when the next step needs a model decision.`;