pi-supernova 0.8.1 → 0.9.0

package/src/runtime/runtime.js

@@ -1,210 +1,41 @@
-import { Worker } from "node:worker_threads";
+import {acquireWorker,killWorker} from './worker-pool.js';
+export {warmGuestWorker,stopWarmGuestWorker} from './worker-pool.js';
+import {admitGuest,prepareProgram,normalizeGuestLocation} from './program.js';
+
 import { readProgramFile } from "./program-file.js";
-import { parse } from "acorn";
+
 import { performance } from "node:perf_hooks";
 import { packageFinalReturn } from "../output/bottleneck.js";
 import { truncateChars } from "../output/format.js";
-import { isFunction, isObject, isString } from "../shared/decode.js";
-import { guestImportMessage, isDeniedGuestImport } from "./guest-deny-imports.js";
-import { errorContext } from "../shared/syntax-context.js";
+import { errorMessage, 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";
+import { errorContext } from "../shared/syntax-context.js";
+import {validateReturnedImages} from "../shared/image.js";
 
-const MEMORY_POLL_MS = 50;
+const ABORT_MESSAGE = "supernova aborted";
+const TIMEOUT_MESSAGE = "supernova timed out: increase the outer timeoutMs (and any shorter bash timeoutMs), or split the program; sleeps count toward the deadline";
 
 const MEMORY_SLACK = 1.5;
 
-const rssBytes = isFunction(process.memoryUsage?.rss) ? () => process.memoryUsage.rss() : () => process.memoryUsage().rss;
-
 const toMb = bytes => Math.max(0, bytes / 1048576);
 
-/** Pure attribution for a memory-limit trip: which operation, and how much of the RSS growth supernova can account for. */
-export function formatMemoryAttribution({ limitMb, rssBytes: now, startBytes, ms, op, calls, tracked }) {
-  const deltaMb = toMb(now - startBytes);
+/** Only worker-local usage can trip the guard; host structures are diagnostic. */
+export function formatMemoryAttribution({ limitMb, heapBytes, externalBytes, ms, op, calls, tracked }) {
   const parts = tracked
     ? [["vfs cache", tracked.vfsCacheBytes], ["index entries", tracked.indexBytes], ["overlays", tracked.overlayBytes]]
     : [];
-  const trackedMb = parts.reduce((sum, [, bytes]) => sum + toMb(Number(bytes) || 0), 0);
-  const untrackedMb = Math.max(0, deltaMb - trackedMb);
   const where = op ? ` during ${op} (${calls} host calls)` : ` (${calls} host calls)`;
   const seen = parts.length
-    ? `; supernova-tracked host bytes: ${parts.map(([name, bytes]) => `${name} ${toMb(Number(bytes) || 0).toFixed(1)}MB`).join(", ")} in ${tracked.overlayFiles ?? 0} overlay files`
+    ? `; supernova-tracked host bytes (not charged to guest): ${parts.map(([name, bytes]) => `${name} ${toMb(Number(bytes) || 0).toFixed(1)}MB`).join(", ")} in ${tracked.overlayFiles ?? 0} overlay files`
     : "";
 
-  return `guest exceeded memory limit (maxHeapMb=${limitMb}): process RSS +${deltaMb.toFixed(1)}MB in ${Math.round(ms)}ms${where}${seen}; `
-    + `~${untrackedMb.toFixed(1)}MB untracked (worker heap, transient buffers, or host/concurrent growth outside supernova)`;
+  return `guest exceeded memory limit (maxHeapMb=${limitMb}): worker heap ${toMb(heapBytes).toFixed(1)}MB + external ${toMb(externalBytes).toFixed(1)}MB in ${Math.round(ms)}ms${where}${seen}`;
 }
 
-let idleWorker = null;
-
 let runSeq = 0;
 
-const PARSE_OPTIONS = { ecmaVersion: "latest", sourceType: "module", allowReturnOutsideFunction: true, allowAwaitOutsideFunction: true };
-
-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);
-    const statements = program.body.filter(node => node.type !== "EmptyStatement");
-    const statement = statements.length === 1 ? statements[0] : undefined;
-    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 };
-  } catch (bodyError) {
-    const expressionSource = code.trimEnd().replace(/;+\s*$/, "");
-
-    try {
-      const wrapped = parse("(" + expressionSource + "\n)", PARSE_OPTIONS);
-      const expression = wrapped.body[0]?.expression;
-
-      if (!expression || !FUNCTION_TYPES.has(expression.type)) throw bodyError;
-
-      return { expression, expressionSource };
-    } catch { throw bodyError; }
-  }
-}
-
-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(ast) {
-  function walk(node) {
-    if (Array.isArray(node)) { node.forEach(walk); return; }
-    if (!isObject(node)) return;
-    if (node.type === "ImportDeclaration" || node.type === "ImportExpression") {
-      const spec = deniedSpecifier(node.source);
-      throw new Error((spec && isDeniedGuestImport(spec) ? guestImportMessage(spec) : "guest cannot import modules; use read, edit, write, or bash") + "; no commands ran");
-    }
-    if (node.type === "CallExpression" && node.callee?.type === "Identifier" && node.callee.name === "require") {
-      const spec = deniedSpecifier(node.arguments?.[0]);
-      throw new Error((spec && isDeniedGuestImport(spec) ? guestImportMessage(spec) : "guest cannot import modules; use read, edit, write, or bash") + "; no commands ran");
-    }
-    for (const key of Object.keys(node)) {
-      if (key === "start" || key === "end" || key === "loc" || key === "range") continue;
-      walk(node[key]);
-    }
-  }
-
-  walk(ast);
-}
-
-function prepareProgram(code) {
-  const parsed = parseExpressionFunction(code);
-  assertGuestImports(parsed.program ?? 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 };
-}
-
-function spawnWorker(config) {
-  const maxHeapMb = config.maxHeapMb ?? 512;
-  // 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; });
-  worker.on("exit", () => {
-    handle.dead = true;
-
-    if (idleWorker === handle) idleWorker = null;
-  });
-  handle.ready = new Promise((resolve, reject) => {
-    const cleanup = () => {
-      worker.off("message", onMessage);
-      worker.off("error", onFail);
-      worker.off("exit", onFail);
-    };
-
-    const onMessage = (msg) => {
-      if (msg?.op !== "ready") return;
-      cleanup();
-      resolve();
-    };
-
-    const onFail = (err) => {
-      cleanup();
-      reject(err instanceof Error ? err : new Error("guest worker exited before ready (code " + err + ")"));
-    };
-
-    worker.on("message", onMessage);
-    worker.on("error", onFail);
-    worker.on("exit", onFail);
-  });
-  handle.ready.catch(() => {});
-
-  return handle;
-}
-
-function killWorker(handle) {
-  if (!handle) return;
-
-  if (idleWorker === handle) idleWorker = null;
-  handle.dead = true;
-
-  return handle.worker.terminate();
-}
-
-function acquireWorker(config) {
-  const candidate = idleWorker;
-  idleWorker = null;
-  const reusable = candidate && !candidate.dead && candidate.maxHeapMb === (config.maxHeapMb ?? 512);
-
-  if (candidate && !reusable) void killWorker(candidate);
-  const handle = reusable ? candidate : spawnWorker(config);
-  handle.worker.ref?.();
-
-  // Pipeline the successor while this run executes. A consumed worker's
-  // replacement starts at once; a cold start's replacement waits for ready,
-  // so the two constructions never overlap. The finish-time warm usually
-  // becomes a no-op, so steady-state spawn count is unchanged.
-  if (reusable) warmGuestWorker(config).catch(() => {});
-  else handle.ready.then(() => warmGuestWorker(config).catch(() => {}), () => {});
-
-  return handle;
-}
-
-/** Only pristine workers may be prewarmed. A used worker is never pooled. */
-export function warmGuestWorker(config = {}) {
-  if (idleWorker && !idleWorker.dead) return idleWorker.ready;
-  const handle = spawnWorker(config);
-  idleWorker = handle;
-  handle.ready.then(() => {
-    if (idleWorker === handle) handle.worker.unref?.();
-  }, () => {});
-
-  return handle.ready;
-}
-
-export function stopWarmGuestWorker() {
-  return killWorker(idleWorker);
-}
-
 const RPC_METHODS = {
-  call: (nova, args) => nova.call(args[0], args[1]),
+  call: (nova, args, onItem) => nova.call(args[0], args[1], onItem),
   callMany: async (nova, args) => {
     const wave = await nova.callMany(args[0]);
 
@@ -215,50 +46,8 @@ const RPC_METHODS = {
   speculateRollback: (nova) => nova.speculateRollback(),
 };
 
-function admitData(data, cap) {
-  if (data === undefined) return { data };
-
-  try {
-    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) };
-  } catch { return { error: "data must be JSON-serializable" }; }
-}
-
-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" };
-}
-
-function admitTimeout(config) {
-  const requestedTimeout = Number(config.timeoutMs === undefined ? 60000 : config.timeoutMs);
-
-  if (!Number.isFinite(requestedTimeout) || requestedTimeout <= 0) return { error: "timeoutMs must be a positive finite number" };
-
-  return { timeoutMs: Math.max(1, Math.min(2_147_483_647, Math.floor(requestedTimeout))) };
-}
-
-function admitGuest({ code, file, data, config }) {
-  const cap = config.maxCodeChars ?? 48000;
-  const codeError = admitCode({ code, file, cap });
-
-  if (codeError) return codeError;
-  const admitted = admitData(data, cap);
-
-  if (admitted.error) return admitted;
-  const timeout = admitTimeout(config);
-
-  if (timeout.error) return timeout;
-
-  return { data: admitted.data, timeoutMs: timeout.timeoutMs };
-}
-
 class GuestRun {
-  constructor({ code, file, cwd, data, nova, config, signal, onTimeout, runId, timeoutMs, rssLimit, rssStart }) {
+  constructor({ code, file, cwd, data, nova, config, signal, onTimeout, runId, timeoutMs }) {
     this.code = code;
     this.file = file;
     this.cwd = cwd;
@@ -269,8 +58,6 @@ class GuestRun {
     this.onTimeout = onTimeout;
     this.runId = runId;
     this.timeoutMs = timeoutMs;
-    this.rssLimit = rssLimit;
-    this.rssStart = rssStart;
     this.started = performance.now();
     this.logs = [];
     this.logTruncated = false;
@@ -281,8 +68,14 @@ class GuestRun {
     this.hostError = undefined;
     this.notifyingHost = false;
     this.aborting = false;
+    this.abortOutcome = undefined;
     this.pending = new Set();
     this.inputController = new AbortController();
+    this.deliveries = new Map();
+    this.inputController.signal.addEventListener("abort", () => {
+      for (const delivery of this.deliveries.values()) delivery.reject(new Error("aborted"));
+      this.deliveries.clear();
+    }, {once:true});
     this.rpcCount = 0;
     this.lastRpcMethod = null;
   }
@@ -298,7 +91,6 @@ class GuestRun {
   cleanup() {
     this.inputController.abort();
     clearTimeout(this.timer);
-    clearInterval(this.memTimer);
     this.signal?.removeEventListener("abort", this.signalAbort);
     this.handle?.worker.off("message", this.onMessage);
     this.handle?.worker.off("error", this.onError);
@@ -320,31 +112,57 @@ class GuestRun {
     try { this.nova.cancel?.(); } catch {} finally { this.notifyingHost = false; }
   }
 
-  abort() {
+  abort(timedOut = false) {
     if (this.finished || this.aborting) return;
     this.aborting = true;
+    this.accepting = false;
+    this.abortOutcome = this.fail((timedOut ? TIMEOUT_MESSAGE : ABORT_MESSAGE) + " (ran " + this.wall() + "ms of " + this.timeoutMs + "ms)");
     this.cancelHost();
 
-    try { this.onTimeout?.(); } catch {}
+    if (timedOut) { try { this.onTimeout?.(); } catch {} }
 
-    this.aborting = false;
-    this.finish(this.fail(ABORT_MESSAGE + " (ran " + Math.round(this.wall()) + "ms of " + this.timeoutMs + "ms)"));
+    // Stop the guest immediately, then use the bounded host drain to retain
+    // shell diagnostics and wait for process-tree termination before returning.
+    void this.complete(this.abortOutcome);
   }
 
   postResult(message) {
-    if (!this.accepting || this.finished) return;
+    if (!this.accepting || this.finished) return false;
 
     try {
       this.handle.worker.postMessage({ ...message, runId: this.runId });
+      return true;
     } catch (err) {
       try {
         this.handle.worker.postMessage({ op: "rpc:result", id: message.id, runId: this.runId, ok: false, error: "result not transferable: " + err.message });
       } catch (error) {
         this.onError(error);
       }
+      return false;
     }
   }
 
+  deliverReadItem(id, index, value) {
+    if (!this.accepting) return Promise.reject(new Error("aborted"));
+    const key = id + ":" + index;
+    return new Promise((resolve,reject) => {
+      this.deliveries.set(key,{resolve,reject});
+      if (!this.postResult({op:"rpc:item",id,index,value})) {
+        this.deliveries.delete(key);
+        reject(new Error("read result not transferable"));
+      }
+    });
+  }
+
+  onReadAck(msg) {
+    const key = msg.id + ":" + msg.index;
+    const delivery = this.deliveries.get(key);
+    if (!delivery) return;
+    this.deliveries.delete(key);
+    if (msg.error) delivery.reject(new Error(msg.error));
+    else delivery.resolve();
+  }
+
   async drainPending(outcome) {
     if (this.pending.size || !outcome.ok) this.cancelHost();
     if (!this.pending.size) return;
@@ -360,11 +178,16 @@ class GuestRun {
     if (this.finished || this.completing) return;
     this.completing = true;
     this.accepting = false;
+    this.inputController.abort();
     this.handle?.worker.off("error", this.onError);
     this.handle?.worker.off("exit", this.onExit);
     void killWorker(this.handle);
     await this.drainPending(outcome);
     if (this.finished) return;
+    if (this.abortOutcome) {
+      const diagnostic = this.hostError && this.hostError !== "aborted" ? "\n" + this.hostError : "";
+      outcome = this.fail(this.abortOutcome.error + diagnostic);
+    }
     this.finish(outcome.ok && this.hostError ? this.fail(this.hostError) : outcome);
   }
 
@@ -385,39 +208,63 @@ class GuestRun {
     const work = Promise.resolve().then(() => {
       if (!method) throw new Error("unknown nova method: " + msg.method);
 
-      return method(this.nova, msg.args);
+      const onItem = msg.streamRead && msg.method === "call" && msg.args?.[0] === "read"
+        ? (index,value) => this.deliverReadItem(msg.id,index,value) : undefined;
+      return method(this.nova, msg.args, onItem);
     });
 
     this.pending.add(work);
     work.then(
       value => this.postResult({ op: "rpc:result", id: msg.id, ok: true, value }),
       err => {
-        if (!this.accepting) this.hostError ??= err instanceof Error ? err.message : String(err);
-        this.postResult({ op: "rpc:result", id: msg.id, ok: false, error: err instanceof Error ? err.message : String(err) });
+        if (!this.accepting) this.hostError ??= errorMessage(err);
+        this.postResult({ op: "rpc:result", id: msg.id, ok: false, error: errorMessage(err) });
       },
     ).finally(() => this.pending.delete(work));
   }
 
-  onDone(msg) {
+  async onDone(msg) {
+    // A completed guest cannot submit more work while attachments are decoded.
+    // The outer timer stays armed; no commit occurs before validation completes.
+    this.accepting = false;
     try {
-      const packed = packageFinalReturn(msg.value, this.logs, this.config);
+      const packed = msg.output ?? packageFinalReturn(msg.value, this.logs, this.config);
+      if (packed.images?.length) await validateReturnedImages(packed.images,this.inputController.signal);
       void this.complete({ ok: true, result: packed.returnValue, resultText: packed.returnText,
         returnTruncated: packed.returnTruncated, images: packed.images, undefinedReturn: msg.undefinedReturn === true,
-        logs: packed.logs, logTruncated: this.logTruncated || packed.logTruncated });
+        logs: this.logs, logTruncated: this.logTruncated || packed.logTruncated });
     } catch (err) {
       void this.complete(this.fail(err.message));
     }
   }
 
   guestError(msg) {
-    const where = msg.location ? " (line " + msg.location.line + ":" + msg.location.col + ")" : "";
+    const location = normalizeGuestLocation(this.prepared.body, msg.location);
+    const where = location ? " (line " + location.line + ":" + location.col + ")" : "";
     void this.complete(this.fail(msg.message + where));
   }
 
+  onMemory(msg) {
+    const { heapUsed, external } = msg;
+    if (![heapUsed, external].every(bytes => Number.isFinite(bytes) && bytes >= 0)) return;
+    if (heapUsed + external <= (this.config.maxHeapMb ?? 512) * MEMORY_SLACK * 1048576) return;
+    let tracked = null;
+
+    try { tracked = isFunction(this.nova?.describeMemory) ? this.nova.describeMemory() : null; } catch {}
+    // Use the same cancellation/drain path as other failures, not an early
+    // finish that can return while a host command is still mutating files.
+    void this.complete(this.fail(formatMemoryAttribution({
+      limitMb: this.config.maxHeapMb ?? 512, heapBytes: heapUsed, externalBytes: external,
+      ms: this.wall(), op: this.lastRpcMethod, calls: this.rpcCount, tracked,
+    })));
+  }
+
   dispatchGuest(msg) {
     if (msg.op === "log") this.onLog(msg);
     else if (msg.op === "logTruncated") this.logTruncated = true;
+    else if (msg.op === "memory") this.onMemory(msg);
     else if (msg.op === "rpc") this.onRpc(msg);
+    else if (msg.op === "rpc:ack") this.onReadAck(msg);
     else if (msg.op === "done") this.onDone(msg);
     else if (msg.op === "error") this.guestError(msg);
   }
@@ -448,7 +295,7 @@ class GuestRun {
   }
 
   async attachWorker() {
-    if (this.wall() >= this.timeoutMs) { this.abort(); return false; }
+    if (this.wall() >= this.timeoutMs) { this.abort(true); return false; }
     this.handle = acquireWorker(this.config);
     await this.handle.ready;
     if (this.finished || this.signal?.aborted) { this.abort(); return false; }
@@ -459,7 +306,7 @@ class GuestRun {
     this.handle.worker.on("message", this.onMessage);
     this.handle.worker.on("error", this.onError);
     this.handle.worker.on("exit", this.onExit);
-    if (this.wall() >= this.timeoutMs) { this.abort(); return false; }
+    if (this.wall() >= this.timeoutMs) { this.abort(true); return false; }
     this.available = available;
 
     return true;
@@ -469,7 +316,8 @@ class GuestRun {
     this.handle.worker.postMessage({ op: "run", runId: this.runId, prepared: this.prepared, data: this.data, available: this.available,
       batchRead: this.nova.batchRead !== false,
       nativeArgv: this.nova.nativeArgv === true,
-      limits: { maxLogLines: this.config.maxLogLines ?? 100, maxLogLineChars: this.config.maxLogLineChars ?? 4096 } });
+      formatResult:true,
+      limits: { maxReturnChars:this.config.maxReturnChars ?? 32000, maxLogLines: this.config.maxLogLines ?? 100, maxLogLineChars: this.config.maxLogLineChars ?? 4096 } });
   }
 
   async boot() {
@@ -488,20 +336,7 @@ class GuestRun {
   start() {
     return new Promise((resolve) => {
       this.resolve = resolve;
-      this.timer = setTimeout(() => this.abort(), Math.min(this.timeoutMs, 2147483647));
-      this.memTimer = setInterval(() => {
-        const now = rssBytes();
-
-        if (now <= this.rssLimit) return;
-        this.cancelHost();
-        let tracked = null;
-
-        try { tracked = isFunction(this.nova?.describeMemory) ? this.nova.describeMemory() : null; } catch {}
-        this.finish(this.fail(formatMemoryAttribution({
-          limitMb: this.config.maxHeapMb ?? 512, rssBytes: now, startBytes: this.rssStart ?? now,
-          ms: this.wall(), op: this.lastRpcMethod, calls: this.rpcCount, tracked,
-        })));
-      }, MEMORY_POLL_MS);
+      this.timer = setTimeout(() => this.abort(true), Math.min(this.timeoutMs, 2147483647));
       this.signal?.addEventListener("abort", this.signalAbort, { once: true });
       void this.boot();
     });
@@ -514,12 +349,10 @@ export async function runGuestProgram({ code, file, cwd = process.cwd(), data, n
 
   if (admitted.error) return fail(admitted.error);
   if (signal?.aborted) return fail(ABORT_MESSAGE);
-  const rssStart = rssBytes();
 
   return new GuestRun({
     code, file, cwd, data: admitted.data, nova, config, signal, onTimeout,
     runId: ++runSeq,
     timeoutMs: admitted.timeoutMs,
-    rssLimit: rssStart + (config.maxHeapMb ?? 512) * MEMORY_SLACK * 1048576, rssStart,
   }).start();
 }

package/src/runtime/worker-pool.js

@@ -0,0 +1,91 @@
+import {Worker} from 'node:worker_threads';
+
+const WORKER_URL = new URL("./guest-worker.js", import.meta.url);
+
+let idleWorker = null;
+
+function spawnWorker(config) {
+  const maxHeapMb = config.maxHeapMb ?? 512;
+  // 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; });
+  worker.on("exit", () => {
+    handle.dead = true;
+
+    if (idleWorker === handle) idleWorker = null;
+  });
+  handle.ready = new Promise((resolve, reject) => {
+    const cleanup = () => {
+      worker.off("message", onMessage);
+      worker.off("error", onFail);
+      worker.off("exit", onFail);
+    };
+
+    const onMessage = (msg) => {
+      if (msg?.op !== "ready") return;
+      cleanup();
+      resolve();
+    };
+
+    const onFail = (err) => {
+      cleanup();
+      reject(err instanceof Error ? err : new Error("guest worker exited before ready (code " + err + ")"));
+    };
+
+    worker.on("message", onMessage);
+    worker.on("error", onFail);
+    worker.on("exit", onFail);
+  });
+  handle.ready.catch(() => {});
+
+  return handle;
+}
+
+function killWorker(handle) {
+  if (!handle) return;
+
+  if (idleWorker === handle) idleWorker = null;
+  handle.dead = true;
+
+  return handle.worker.terminate();
+}
+
+function acquireWorker(config) {
+  const candidate = idleWorker;
+  idleWorker = null;
+  const reusable = candidate && !candidate.dead && candidate.maxHeapMb === (config.maxHeapMb ?? 512);
+
+  if (candidate && !reusable) void killWorker(candidate);
+  const handle = reusable ? candidate : spawnWorker(config);
+  handle.worker.ref?.();
+
+  // Pipeline the successor while this run executes. A consumed worker's
+  // replacement starts at once; a cold start's replacement waits for ready,
+  // so the two constructions never overlap. The finish-time warm usually
+  // becomes a no-op, so steady-state spawn count is unchanged.
+  if (reusable) warmGuestWorker(config).catch(() => {});
+  else handle.ready.then(() => warmGuestWorker(config).catch(() => {}), () => {});
+
+  return handle;
+}
+
+/** Only pristine workers may be prewarmed. A used worker is never pooled. */
+export function warmGuestWorker(config = {}) {
+  if (idleWorker && !idleWorker.dead) return idleWorker.ready;
+  const handle = spawnWorker(config);
+  idleWorker = handle;
+  handle.ready.then(() => {
+    if (idleWorker === handle) handle.worker.unref?.();
+  }, () => {});
+
+  return handle.ready;
+}
+
+export function stopWarmGuestWorker() {
+  return killWorker(idleWorker);
+}
+export { acquireWorker, killWorker };

package/src/shared/decode.js

@@ -26,10 +26,9 @@ export function mapChangedChildren(value, visit, context) {
   if (!array && !isObject(value)) return value;
   let out = value;
 
-  for (const key of array ? value.keys() : Object.keys(value)) {
-    if (array && !(key in value)) continue;
+  for (const key of childKeys(value)) {
     const before = value[key];
-    const after = visit(before, context);
+    const after = visit(before, context, key);
 
     if (Object.is(before, after)) continue;
     if (out === value) out = array ? value.slice() : { ...value };
@@ -49,6 +48,15 @@ export function assertModelImageMime(mimeType) {
   }
 }
 
+/** Node's base64 decoder is permissive; model attachments must not be. */
+export function decodeImageData(data) {
+  const bytes = Buffer.from(data,"base64");
+  if (!data || bytes.toString("base64") !== String(data)) {
+    throw new Error("invalid image base64; use canonical padded base64 without a data-URL prefix or extra characters; no image attached");
+  }
+  return bytes;
+}
+
 const MAX_DEPTH = 64;
 
 const MAX_TYPED_ARRAY = 4096;
@@ -85,7 +93,7 @@ function plainFromCollection(value, seen, depth) {
   if (value instanceof Map) return plainFromMap(value, seen, depth);
   const out = Object.create(null);
 
-  for (const k of Object.keys(value)) out[k] = toPlain(value[k], seen, depth + 1);
+  for (const k of childKeys(value)) out[k] = toPlain(value[k], seen, depth + 1);
 
   return out;
 }
@@ -102,9 +110,7 @@ function functionLabel(value) {
 }
 
 function plainByTag(value, tag) {
-  if (tag === "[object String]") return { hit: true, out: value.valueOf() };
-
-  if (tag === "[object Number]" || tag === "[object Boolean]") return { hit: true, out: value.valueOf() };
+  if (["[object String]", "[object Number]", "[object Boolean]"].includes(tag)) return { hit: true, out: value.valueOf() };
 
   if (tag === "[object BigInt]") return { hit: true, out: value.toString() + "n" };
 
@@ -168,4 +174,12 @@ export function toPlain(value, seen = new Set(), depth = 0) {
   return withSeen(value, seen, () => plainFromCollection(value, seen, depth));
 }
 
-// ---- RPC to the host thread ----
+export function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// Arrays visit present indexes (including inherited ones), not extra properties.
+function* childKeys(value) {
+  if (!Array.isArray(value)) { yield* Object.keys(value); return; }
+  for (const key of value.keys()) if (key in value) yield key;
+}