pi-supernova 0.10.1 → 0.11.0

package/src/runtime/parallel.js

@@ -1,6 +1,6 @@
 import { isFunction, isObject, isString } 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_TOOLS = new Set(["read", "grep", "glob", "find", "ls", "snap", "evidence", "surface", "asgrep_search", "asgrep_status", "ast_grep", "web_search", "isearch"]);
 
 const READ_ONLY_LSP = new Set(["definition", "references", "hover", "symbols", "diagnostics", "implementation", "type_definition", "incoming_calls", "outgoing_calls"]);
 
@@ -55,9 +55,11 @@ function compatibleScheduledJob(job, active) {
 
 async function prepareScheduledJob(job) {
   if (!job.resolveKey) return;
+
   // Key lookup is advisory. Invalid paths still run in isolation so the real
   // adapter reports the error through its normal trace/permission checks.
   try { job.key = await job.resolveKey(); } catch {}
+
   job.resolveKey = undefined;
 }
 
@@ -98,6 +100,7 @@ export function createNativeScheduler({ maxParallelReads = 8 } = {}) {
       if (!active.size) stats.readWaves++;
       stats.peakParallelReads = Math.max(stats.peakParallelReads, active.size + 1);
     }
+
     active.add(job);
     // Each promise settles independently. Barriers still wait for every active
     // sibling, including when Promise.all in the guest has already rejected.
@@ -107,15 +110,20 @@ export function createNativeScheduler({ maxParallelReads = 8 } = {}) {
   async function drain() {
     if (draining) return;
     draining = true;
+
     try {
       while (queue.length && active.size < maxParallelReads) {
         const job = queue[0];
+
         if (job.cancelled) { queue.shift(); continue; }
+
         // Resolve identities after shell/override barriers, which may change
         // symlinks. Check synchronously: a finishing job must not lose its wakeup.
         if (job.resolveKey && [...active].some(running => !isString(running.key))) break;
         await prepareScheduledJob(job);
+
         if (job.cancelled) continue;
+
         if (!compatibleScheduledJob(job, active)) break;
         queue.shift();
         start(job);
@@ -143,51 +151,3 @@ export function createNativeScheduler({ maxParallelReads = 8 } = {}) {
     },
   };
 }
-
-function requireArray(value, name) {
-  if (!Array.isArray(value)) throw new TypeError(name + " requires an array");
-
-  return value;
-}
-
-function waveMutates(list, meta, config) {
-  const names = meta?.names ?? [];
-
-  return names.length !== list.length || names.some((name, i) => isMutatingTool(name, config, meta?.calls?.[i]?.args, meta?.definitions?.[i]));
-}
-
-function shouldRunParallel(mutating, mode, length) {
-  return !mutating && (mode === "parallel" || (mode === "auto" && length > 1));
-}
-
-async function settleParallel(list) {
-  // Do not finish a wave while its already-started host calls are still running.
-  const settled = await Promise.allSettled(list.map(thunk => Promise.resolve().then(thunk)));
-  const failure = settled.find(item => item.status === "rejected");
-
-  if (failure) throw failure.reason;
-
-  return { results: settled.map(item => item.value), mode: "parallel", reason: "independent-reads" };
-}
-
-async function runSerial(list, mutating) {
-  const results = [];
-
-  for (const thunk of list) results.push(await thunk());
-
-  return { results, mode: "serial", reason: mutating ? "mutating" : "single-or-forced" };
-}
-
-export async function runParallelWave(thunks, meta, options = {}) {
-  const list = requireArray(thunks, "parallel wave");
-
-  if (list.some(item => !isFunction(item))) throw new TypeError("parallel wave requires functions");
-
-  if (!list.length) return { results: [], mode: "serial", reason: "empty" };
-  const { mode = "auto", config = {} } = options;
-  const mutating = waveMutates(list, meta, config);
-
-  if (shouldRunParallel(mutating, mode, list.length)) return settleParallel(list);
-
-  return runSerial(list, mutating);
-}

package/src/runtime/program-batch.js

@@ -13,8 +13,9 @@ const mutationTotals = results => results.reduce((total, result) => {
   return total;
 }, {committed:0,rolledBack:0,external:0,pendingCommits:0,recoveryFailed:false});
 
-export function programBatchText(results, total, stopped = "", failed = 0) {
+export function programBatchText(results, total, stopped = "", failed = 0, texts = results.map(textOf)) {
   const m = mutationTotals(results);
+
   const summary = stopped
     ? "error: programs stopped: " + stopped + " " + results.length + "/" + total
     : failed > 0
@@ -22,10 +23,8 @@ export function programBatchText(results, total, stopped = "", failed = 0) {
       : "ok: programs " + results.length + "/" + total;
 
   return summary +
-    (m.recoveryFailed || m.pendingCommits ? "; filesystem outcome uncertain: inspect disk" : "") + "\nresults (UTF-16 lengths):\n" + results.map((result,i) => {
-      const text = textOf(result);
-
-      return "[" + i + "] " + text.length + "\n" + text + "\n";
+    (m.recoveryFailed || m.pendingCommits ? "; filesystem outcome uncertain: inspect disk" : "") + "\nresults (UTF-16 lengths):\n" + texts.map((text,i) => {
+      return "[" + (results[i].details?.programIndex ?? i) + "] " + text.length + "\n" + text + "\n";
     }).join("");
 }
 
@@ -92,18 +91,16 @@ class ProgramBatch {
     return " (ran " + Math.round(performance.now() - this.started) + "ms of " + this.timeout + "ms)";
   }
   takeSettled(result, i) {
-    this.results.push(result);
+    this.results.push({...result,details:{...result.details,programIndex:i}});
     this.trace.push(...(result.details?.trace ?? []));
     this.collectImages(result, i);
   }
 
   parallelBudgetStop(settled) {
-    const results = settled.filter(Boolean);
     const {images, bytes} = imageTotals(settled);
-    let kind;
-    if (images > 16 || bytes > 20 * 1024 * 1024) kind = "image";
-    else if (results.some(result => result.details?.logTruncated) || results.reduce((n, result) => n + (result.details?.logs?.length ?? 0), 0) > (this.config.maxLogLines ?? 100)) kind = "log";
-    return kind ? "batch " + kind + " budget exceeded; completed commits remain" : "";
+
+    return images > 16 || bytes > 20 * 1024 * 1024
+      ? "batch image budget exceeded; completed commits remain" : "";
   }
 
   async runParallel() {
@@ -116,7 +113,9 @@ class ProgramBatch {
         const i = next++;
         settled[i] = await this.runOne(this.programs[i], i);
         this.live[i] = [];
-        this.stopped ||= this.parallelBudgetStop(settled);
+        this.stopped ||= this.parallelBudgetStop(settled) || this.sequentialStop(settled[i], i);
+
+        if (settled[i].details?.mutations?.recoveryFailed || settled[i].details?.mutations?.pendingCommits) this.controller.abort(new Error("batch stopped: filesystem outcome uncertain"));
       }
     }));
 
@@ -125,7 +124,7 @@ class ProgramBatch {
       this.takeSettled(settled[i], i);
     }
 
-    if ((!this.stopped && settled.includes(undefined)) || this.combined.aborted || performance.now() >= this.deadline) this.stopped = "batch deadline or cancellation; earlier commits remain" + this.deadlineNote();
+    if ((!this.stopped && settled.includes(undefined)) || this.combined.aborted || performance.now() >= this.deadline) this.stopped ||= "batch deadline or cancellation; earlier commits remain" + this.deadlineNote();
   }
 
   sequentialStop(result, i) {
@@ -133,11 +132,9 @@ class ProgramBatch {
 
     if (this.imageDropped) stopped = "batch image budget exceeded; remaining programs did not run";
 
-    if (result.details?.ok === false) stopped = "program " + (i+1) + " failed; remaining programs did not run; earlier commits remain";
-    // Display clipping is not an execution failure. Finish every requested entry
-    // unless a real execution/resource limit stops it; boundedText caps delivery.
-
-    if (result.details?.logTruncated) stopped ||= "batch log budget exceeded; remaining programs did not run; earlier commits remain";
+    if (!result.details?.mutations || result.details.mutations.recoveryFailed || result.details.mutations.pendingCommits || /host call budget exceeded/.test(result.details?.error ?? "")) stopped = "program " + (i+1) + " exhausted a shared budget or has an uncertain filesystem outcome; remaining programs did not run; earlier commits remain";
+    // Text/log clipping is not an execution failure. Finish every requested
+    // entry unless a real execution/resource limit stops it; delivery is bounded.
 
     // The deadline explains a killed program better than "program N failed".
     if (this.combined.aborted || performance.now() >= this.deadline) stopped = "batch deadline or cancellation; earlier commits remain" + this.deadlineNote();
@@ -159,30 +156,56 @@ class ProgramBatch {
   }
 
   failNote(failed) {
-    return this.stopped || (this.parallel && failed ? failed + " program" + (failed>1?"s":"") + " failed" : undefined);
+    return this.stopped || (failed ? failed + " program" + (failed>1?"s":"") + " failed" : undefined);
   }
 
-  boundedText(failed) {
-    const note = this.imageDropped && !this.stopped ? "some images dropped: batch image budget" : "";
+  boundedText(failed, logTruncated) {
+    const note = [
+      this.imageDropped && !this.stopped ? "some images dropped: batch image budget" : "",
+      logTruncated ? "logs truncated: batch log budget" : "",
+    ].filter(Boolean).join("; ");
+
+    const limit = Math.max(0, this.config.maxReturnChars - this.imageTextChars());
+    const texts = this.results.map(textOf);
+    const render = previews => programBatchText(this.results, this.programs.length, this.stopped, failed, previews) + (note ? "; " + note : "");
+    const text = render(texts);
+
+    if (text.length <= limit) return { text, truncated: false };
+    const marker = "\n[batch output truncated; per-program previews]";
+    // Reserve framing and length digits before dividing space. Clipping the
+    // combined string can erase an entire program, including its error reason.
+    const overhead = render(texts.map(() => "")).length + marker.length + texts.length * String(limit).length;
+    const share = Math.max(0, Math.floor((limit - overhead) / Math.max(1, texts.length)));
+    const previews = texts.map(value => truncateChars(value, share, "program output").text);
 
-    return truncateChars(programBatchText(this.results,this.programs.length,this.stopped,this.parallel ? failed : 0) + (note ? "; " + note : ""),Math.max(0,this.config.maxReturnChars-this.imageTextChars()),"batch output");
+    return { ...truncateChars(render(previews) + marker, limit, "batch output"), truncated: true };
   }
 
   finish() {
-    const failed = this.results.filter(result => result.details?.ok === false).length;
-    const bounded = this.boundedText(failed);
-    const content = [{type:"text",text:bounded.text}];
+    const failedPrograms = [];
+
+    for (const result of this.results) {
+      if (result.details?.ok === false) failedPrograms.push(result.details.programIndex);
+    }
+
+    const attempted = new Set(this.results.map(result => result.details.programIndex));
+    const notRunPrograms = this.programs.flatMap((_, i) => attempted.has(i) ? [] : [i]);
+    const failed = failedPrograms.length;
     const logs = this.results.flatMap(result => result.details?.logs ?? []);
     const logLimit = this.config.maxLogLines ?? 100;
+    const logTruncated = logs.length > logLimit || this.results.some(result=>result.details?.logTruncated);
+    const bounded = this.boundedText(failed, logTruncated);
+    const mutations = mutationTotals(this.results);
+    const content = [{type:"text",text:bounded.text}];
     this.images.forEach((image,i) => content.push({type:"text",text:this.imageLabels[i]},image));
 
     // Return a typed stop report instead of throwing away earlier results/images.
     // Single-program errors retain their existing throwing behavior.
-    return {content,isError:!!this.stopped || (this.parallel && failed>0),details:{ok:!this.stopped && !(this.parallel && failed),error:this.failNote(failed),wallMs:Math.round(performance.now()-this.started),
-      programs:this.results,attempted:this.results.length,total:this.programs.length,stopped:this.stopped,parallel:this.parallel,
+    return {content,isError:!!this.stopped || failed>0,details:{ok:!this.stopped && !failed,partial:failed>0 && mutations.committed>0,error:this.failNote(failed),wallMs:Math.round(performance.now()-this.started),
+      programs:this.results,attempted:this.results.length,failed,failedPrograms,notRunPrograms,notRun:this.programs.length-this.results.length,total:this.programs.length,stopped:this.stopped,parallel:this.parallel,
       result:bounded.truncated ? bounded.text : this.results.map(result=>result.details?.result),
       returnTruncated:bounded.truncated || this.results.some(result=>result.details?.returnTruncated),
-      logTruncated:logs.length > logLimit || this.results.some(result=>result.details?.logTruncated),logs:logs.slice(0,logLimit),trace:this.trace,mutations:mutationTotals(this.results)}};
+      logTruncated,logs:logs.slice(0,logLimit),trace:this.trace,mutations}};
   }
 
   async run() {
@@ -208,11 +231,13 @@ function imageBlocks(result) {
 
 function imageTotals(settled) {
   let images = 0, bytes = 0;
+
   for (const result of settled) {
     for (const block of imageBlocks(result)) {
       images++;
       bytes += Buffer.byteLength(block.data, "base64");
     }
   }
+
   return {images, bytes};
 }

package/src/runtime/program-file.js

@@ -1,4 +1,4 @@
-import { readLimitedBytes } from "../fs/file-io.js";
+import { readLimitedBytes, sameFileVersion } from "../fs/file-io.js";
 import * as fs from "node:fs/promises";
 import { resolveWorkspacePath } from "../fs/workspace.js";
 
@@ -24,6 +24,7 @@ export async function readProgramFile(file, cwd, maxChars, signal) {
 
     const bytes = await readLimitedBytes(handle, stat, maxBytes, file, signal, tooLarge);
 
+    if (!sameFileVersion(stat, await handle.stat())) throw new Error("program file changed while reading: " + file + "; retry with a stable source file");
     signal?.throwIfAborted();
     // Do not silently replace invalid bytes in executable source. Preserve BOMs.
     let code;

package/src/runtime/program.js

@@ -6,16 +6,6 @@ const PARSE_OPTIONS = { ecmaVersion: "latest", sourceType: "module", allowReturn
 
 const FUNCTION_TYPES = new Set(["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"]);
 
-function hasReturn(node) {
-  if (!isObject(node)) return false;
-
-  if (node.type === "ReturnStatement") return true;
-
-  if (FUNCTION_TYPES.has(node.type)) return false;
-
-  return Object.values(node).some(value => Array.isArray(value) ? value.some(hasReturn) : hasReturn(value));
-}
-
 function parseExpressionFunction(code) {
   try {
     const program = parse(code, PARSE_OPTIONS);
@@ -24,7 +14,7 @@ function parseExpressionFunction(code) {
     const candidate = statement?.type === "ExpressionStatement" ? statement.expression : statement;
 
     if (candidate && FUNCTION_TYPES.has(candidate.type)) {
-      return { program, expression: candidate, expressionSource: code.slice(statement.start, statement.end).replace(/;\s*$/, "") };
+      return { program, expression: candidate, sourceStart: statement.start, expressionSource: code.slice(statement.start, statement.end).replace(/;\s*$/, "") };
     }
 
     return { program };
@@ -44,28 +34,57 @@ function parseExpressionFunction(code) {
 
 function deniedSpecifier(node) {
   if (node?.type === "Literal" && isString(node.value)) return node.value;
+
   if (node?.type === "TemplateLiteral" && node.expressions.length === 0) return node.quasis[0]?.value?.cooked;
 }
 
-function assertGuestImports(node) {
-  if (Array.isArray(node)) { node.forEach(assertGuestImports); return; }
-  if (!isObject(node)) return;
-  if (["ImportDeclaration", "ImportExpression"].includes(node.type)) rejectGuestImport(node.source);
-  if (node.type === "CallExpression" && node.callee?.type === "Identifier" && node.callee.name === "require") rejectGuestImport(node.arguments?.[0]);
-  for (const key of Object.keys(node)) {
-    if (!["start", "end", "loc", "range"].includes(key)) assertGuestImports(node[key]);
+function inspectProgram(root, expression) {
+  let returns = expression?.type === "ArrowFunctionExpression" && expression.body.type !== "BlockStatement";
+  // Valid member chains can exceed the host call stack well below the code cap.
+  const pending = [{node:root,returnScope:true}];
+
+  while (pending.length) {
+    let {node,returnScope} = pending.pop();
+
+    if (Array.isArray(node)) {
+      for (let i = node.length - 1; i >= 0; i--) pending.push({node:node[i],returnScope});
+
+      continue;
+    }
+
+    // eslint-disable-next-line anti-slop/no-runtime-typeof -- This is an Acorn-owned AST, not unparsed host or guest data.
+    if (!node || typeof node !== "object") continue;
+    const type = node.type;
+
+    // Function scopes affect only return hints. Import checks must still visit
+    // nested/unreachable bodies, even after finding a return in the invoked scope.
+    if (FUNCTION_TYPES.has(type)) returnScope = node === expression;
+
+    if (type === "ReturnStatement" && returnScope) returns = true;
+
+    if (type === "ImportDeclaration" || type === "ImportExpression") rejectGuestImport(node.source);
+
+    if (type === "CallExpression" && node.callee?.type === "Identifier" && node.callee.name === "require") rejectGuestImport(node.arguments?.[0]);
+
+    const keys = Object.keys(node);
+
+    for (let i = keys.length - 1; i >= 0; i--) {
+      const value = node[keys[i]];
+
+      // eslint-disable-next-line anti-slop/no-runtime-typeof -- Acorn already parsed these fields; distinguish child objects from scalar AST metadata.
+      if (value && typeof value === "object") pending.push({node:value,returnScope});
+    }
   }
+
+  return returns;
 }
 
 function prepareProgram(code) {
   const parsed = parseExpressionFunction(code);
-  assertGuestImports(parsed.program ?? parsed.expression);
+  const returns = inspectProgram(parsed.program ?? parsed.expression, parsed.expression);
   const body = parsed.expression ? "return await (" + parsed.expressionSource + "\n)();" : code;
-  const returns = parsed.expression
-    ? parsed.expression.type === "ArrowFunctionExpression" && parsed.expression.body.type !== "BlockStatement" || hasReturn(parsed.expression.body)
-    : hasReturn(parsed.program);
 
-  return { body, hasReturn: returns };
+  return { body, hasReturn: returns, sourceStart: parsed.sourceStart ?? 0, prefixLength: parsed.expression ? "return await (".length : 0 };
 }
 
 function admitData(data, cap) {
@@ -75,6 +94,7 @@ function admitData(data, cap) {
     const encoded = JSON.stringify(data);
 
     if (encoded === undefined) return { error: "data must be JSON-serializable" };
+
     if (encoded.length > cap) return { error: "data exceeds " + cap + " characters (serialized JSON: " + encoded.length + " UTF-16 characters); no commands ran. Split literal inputs across invocations; large text can use write({path,content,append:true}) chunks without omitting content" };
 
     return { data: JSON.parse(encoded) };
@@ -83,7 +103,9 @@ function admitData(data, cap) {
 
 function admitCode({ code, file, cap }) {
   if ((code === undefined) === (file === undefined)) return { error: "supply exactly one of code or file; no commands ran" };
+
   if (file === undefined && (!isString(code) || !code.trim())) return { error: "code must be a non-empty string" };
+
   if (file === undefined && code.length > cap) return { error: "code exceeds " + cap + " characters; split large writes into write({path,content,append:true}) chunks" };
 }
 
@@ -109,6 +131,7 @@ function admitGuest({ code, file, data, config }) {
 
   return { data: admitted.data, timeoutMs: timeout.timeoutMs };
 }
+
 export { admitGuest, prepareProgram };
 
 function rejectGuestImport(source) {
@@ -117,25 +140,55 @@ function rejectGuestImport(source) {
   throw new Error(reason + "; no commands ran");
 }
 
-function containingAwait(node, offset) {
-  if (Array.isArray(node)) return node.map(child => containingAwait(child, offset)).find(Boolean);
-  if (!isObject(node) || offset < node.start || offset >= node.end) return null;
-  for (const child of Object.values(node)) {
-    const found = containingAwait(child, offset);
-    if (found) return found;
+function containingAwait(root, offset) {
+  const pending = [root];
+  let found = null;
+
+  while (pending.length) {
+    const node = pending.pop();
+
+    if (Array.isArray(node)) {
+      for (const child of node) pending.push(child);
+
+      continue;
+    }
+
+    if (!isObject(node) || offset < node.start || offset >= node.end) continue;
+
+    // Containing awaits nest; descendants supersede the enclosing await.
+    if (node.type === "AwaitExpression") found = node;
+
+    for (const child of Object.values(node)) pending.push(child);
   }
-  return node.type === "AwaitExpression" ? node : null;
+
+  return found;
 }
 
-// V8 points at 'await'; JSC points at the called function's parenthesis. Report
-// the enclosing await expression consistently, using source syntax, not offsets.
-export function normalizeGuestLocation(source, location) {
-  if (!location?.awaited) return location;
-  const {line, col} = location;
-  const prefix = source.split("\n").slice(0, line - 1).join("\n");
-  const offset = prefix.length + Number(line > 1) + col - 1;
-  try {
-    const node = containingAwait(parse(source, {...PARSE_OPTIONS, locations:true}), offset);
-    return node ? {line:node.loc.start.line, col:node.loc.start.column + 1} : location;
-  } catch { return location; }
+// V8 points at 'await'; JSC points at the call parenthesis. Resolve the await
+// in executable syntax, then undo wrapper/sliced-comment offsets. ECMAScript
+// line separators differ from file/JSONL LF framing.
+export function normalizeGuestLocation(source, location, prepared = { body: source }) {
+  if (!location) return location;
+  const body = prepared.body;
+  const lines = /\r\n|[\n\r\u2028\u2029]/g;
+  let start = 0;
+
+  for (let line = 1; line < location.line; line++) {
+    if (!lines.exec(body)) return null;
+    start = lines.lastIndex;
+  }
+
+  let offset = start + location.col - 1;
+
+  if (location.awaited) {
+    try { offset = containingAwait(parse(body, PARSE_OPTIONS), offset)?.start ?? offset; }
+    catch { /* Keep the engine's position when syntax cannot be recovered. */ }
+  }
+
+  offset += (prepared.sourceStart ?? 0) - (prepared.prefixLength ?? 0);
+
+  if (offset < 0 || offset > source.length) return null;
+  const original = source.slice(0, offset).split(/\r\n|[\n\r\u2028\u2029]/);
+
+  return { ...location, line: original.length, col: original.at(-1).length + 1 };
 }

package/src/runtime/reference.js

@@ -1,13 +1,14 @@
 // Standing tool description: sent on every request. No result or history compression.
-export const REFERENCE = `JS body/async arrow; read/write/edit/bash, no fs/import/require. file: workspace JS; data: literals ≤48000 JSON chars.
+export const REFERENCE = `JS body/async arrow; read/write/edit/bash, no fs/import/require. file: workspace JS; data: ≤48000 JSON chars.
 read(path|paths,offset=1,limit?) → text/text[]; dirs→entries; PNG/JPEG/GIF/WebP ≤16/20MiB.
-Text ≤64 MiB internally; complete:true requires whole file. Display capped: summarize or read(path,{offset:1,limit:80}); larger files via bash.
-read({path,json:true}) or json:".field" or json:[".a"] → JSON, no jq (16MiB input/64MiB selection). Values retain their types. selector is json's value; a leftover selector key folds.
+Text ≤64 MiB internally; complete:true whole file. Display capped: summarize or read(path,{offset:1,limit:80}); larger files via bash.
+read({path,json:true}) → JSON; json:".field" or json:[".a"] selects (16MiB input/64MiB selection; no jq). Values retain their types; leftover selector folds into json.
+read({query,indexed:true}): optional callable isearch, then an owned editable read.
 read("symbol or question") = read({query,resolve:true}) → view; check status; view.text is a span. read(path,{about}) windows; read({query,evidence:true}) evidence; read({path,outline:true}) declarations.
-write/edit workspace-only; external changes need separately authorized command. write(path,text) or {path,content,append:true}; after read edit or replace:true.
-edit(path,oldText,newText) or {path,edits:[{oldText,newText}]}; unique exact match; numbered windows. edit(view,text) or edit(view,old,new). edit(async()=>{...}) checkpoint: no bash; merge/rollback+rethrow.
-bash(command,{cwd?,timeoutMs?}) or {command,args}; nonzero throws. Outer timeout bounds foreground; bash inherits. Shell mutations flush edits.
-bash({command,background:true,pty?:true,timeoutMs?:1800000})→sessionId. bash({action:"list"}) or {sessionId,action:"poll"|"write"|"stop",cursor?,waitMs?,input?}→status/output/cursor/exitCode. PTY macOS/Linux; jobs end at shutdown.
-programs:[{code?,file?,data?}] inherit defaults; mergeData:true shallow. Fresh guests/commits; sequential failure stops, prior commits stay; parallel:true disjoint work.
-Promise.all ≤8 disjoint reads/mutations; same-file serial; bash/checkpoints barriers. Optional reads: Promise.allSettled retains successes. ONE call for known work.
+write/edit workspace-only; external changes need separately authorized command. write(path,text,opts?) or {path,content,append:true}; after read edit or replace:true.
+edit(path,oldText,newText) or {path,edits:[{oldText,newText}]}; unique exact match; numbered windows. edit(view,text) or edit(view,old,new). edit(async()=>{...}) atomic checkpoint: no bash; commit/rollback+rethrow. Other edits save; retry failures only.
+bash(command,opts?) or {command,args,cwd?,timeoutMs?}; nonzero throws. Capture≤2Mi chars; larger output via file; outer deadline.
+bash({command,background:true,pty?:true,timeoutMs?:1800000})→sessionId. bash({action:"list"}) or {sessionId,action:"poll"|"write"|"stop",cursor?,waitMs?,input?}→status/output/cursor/exitCode. poll waitMs 0..30000. PTY macOS/Linux; jobs end at shutdown.
+programs:[{code?,file?,data?}] inherit defaults; mergeData:true shallow. Fresh guests; failures continue; limits/uncertainty stop; parallel:true disjoint.
+Promise.all ≤8 disjoint; same-file serial; bash/checkpoints barriers. Independent: Promise.allSettled; uncaught errors stop JS.
 `;