pi-supernova 0.7.1 → 0.8.1

package/src/adapters/read.js

@@ -1,6 +1,6 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { isString, isNumber } from "../shared/decode.js";
+import { isString, isNumber, assertModelImageMime } from "../shared/decode.js";
 import { extractStructuralSurface } from "../context/surface.js";
 import { pickSpan } from "../context/spans.js";
 import { executeSnap, tokenizeQuery, stem } from "../context/snap.js";
@@ -8,6 +8,7 @@ import { selectEvidence } from "../context/evidence.js";
 import { WorkspaceIndex } from "../context/repo-index.js";
 import { outlineFile } from "../context/outline.js";
 import { MAX_JSON_BYTES, jsonProjector } from "../fs/json-read.js";
+import { decodeUtf8Strict, decodeUtf8Window } from "../shared/utf8.js";
 import { normalizeRead, classifyRead, needsProbe, SESSION_URI, buildJsonRouting, buildSelectionRouting, routingText } from "../contract/read.js";
 import { resolveWorkspacePath, runCommand, relativeSlash } from "../fs/workspace.js";
 import {
@@ -19,6 +20,7 @@ import {
 } from "../fs/text-ops.js";
 import { imageTooLarge, missingFile, IMAGE_MAX_BYTES, LARGE_FILE_BYTES, ABOUT_TOKEN_MAX, IMAGE_MIME, RAW_JSON_CHARS, RAW_SOURCE_CHARS, RAW_SOURCE_LINES, ROUTING_MAX_CHARS } from "./errors.js";
 import { outlineOptions, recordOutlineOrigins, createReferenceFinder } from "./refs.js";
+import { sourceContext, parsePosition } from "../shared/syntax-context.js";
 
 export function createRead(ctx) {
   const { getCwd, vfs, config, index, ledger, hooks, reads } = ctx;
@@ -230,12 +232,18 @@ export function createRead(ctx) {
     try { return await fs.open(targetPath, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0)); }
     catch (error) {
       if (error.code === "ENOENT") throw missingFile(targetPath);
+      if (error.code === "ENOTDIR") throw new Error("cannot use path: a parent component of " + targetPath + " is a file, not a directory");
+      if (error.code === "EISDIR") throw new Error("path is a directory, not a file: " + targetPath);
+      if (error.code === "EACCES" || error.code === "EPERM") throw new Error("permission denied reading " + targetPath + ": check the file mode (for example bash chmod)");
       throw error;
     }
   }
 
   async function finishFileWindow(targetPath, stat, startLine, scan) {
-    const text = Buffer.concat(scan.parts, scan.collected).toString("utf8");
+    // A truncated window can cut a multi-byte character; a window that reached
+    // EOF must decode strictly, so a binary file cannot masquerade as text.
+    const bytes = Buffer.concat(scan.parts, scan.collected);
+    const text = scan.startByte + scan.collected >= stat.size ? decodeUtf8Strict(bytes, targetPath) : decodeUtf8Window(bytes);
     const satisfied = (scan.done && scan.startByte + scan.collected >= scan.doneByte) || scan.startByte + scan.collected >= stat.size;
     const whole = startLine === 1 && scan.startByte === 0 && scan.startByte + scan.collected >= stat.size;
     await vfs.recordExpected(targetPath, stat);
@@ -262,7 +270,11 @@ export function createRead(ctx) {
 
       if (!scan.started) return emptyWindow(targetPath, stat);
 
-      return finishFileWindow(targetPath, stat, startLine, scan);
+      // Await inside the try: returning the promise directly leaves its
+      // rejection unobserved while the finally awaits file.close().
+      const window = await finishFileWindow(targetPath, stat, startLine, scan);
+
+      return window;
     } finally {
       await file.close();
     }
@@ -501,13 +513,20 @@ export function createRead(ctx) {
     return parts;
   }
 
+  /** RFC 8259 lets parsers ignore one leading BOM; files from Windows tools carry it. */
+  const stripBom = text => text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+
   async function projectJson(rel, targetPath, params) {
     const project = jsonProjector(params.json);
     const text = await vfs.read(targetPath, { maxBytes: MAX_JSON_BYTES, label: "JSON input" });
     let document;
 
-    try { document = JSON.parse(text); }
-    catch { throw new Error("invalid JSON in " + rel + "; the entire document must parse before projection"); }
+    try { document = JSON.parse(stripBom(text)); }
+    catch (error) {
+      const position = parsePosition(error.message, text);
+
+      throw new Error("invalid JSON in " + rel + ": " + error.message + "; the entire document must parse before projection" + (position ? sourceContext(text, position.line, position.column) : ""));
+    }
 
     const many = Array.isArray(params.json);
     const selectors = many ? params.json.map(String) : [params.json === true ? "." : String(params.json)];
@@ -646,7 +665,8 @@ export function createRead(ctx) {
     const lines = contentLineInfo(loaded.text).count;
 
     if (n > RAW_SOURCE_CHARS || lines > RAW_SOURCE_LINES) {
-      throw new Error("raw read of " + rel + " is " + lines + " lines; use about, offset/limit, or complete:true");
+      const p = JSON.stringify(rel);
+      throw new Error(`raw read of ${rel} is ${lines} lines / ${n} characters; path-only limit is ${RAW_SOURCE_LINES} lines / ${RAW_SOURCE_CHARS} characters. Use read(${p}, {offset:1, limit:80}) for a window, read(${p}, {about:"keywords"}) for matches, or read(${p}, {complete:true}) for the whole file within the read budget`);
     }
 
     return null;
@@ -656,6 +676,7 @@ export function createRead(ctx) {
     const mime = IMAGE_MIME[path.extname(targetPath).toLowerCase()];
 
     if (!mime) return null;
+    assertModelImageMime(mime);
     const bytes = await readImage(rel, targetPath, mime, signal);
 
     if (bytes.length > IMAGE_MAX_BYTES) throw imageTooLarge(rel, bytes.length);
@@ -684,7 +705,7 @@ export function createRead(ctx) {
 
   function assertComplete(rel, sliced, loaded, budget, params) {
     if (params.complete === true && (sliced !== loaded.text || sliced.length > budget || (params.resolve && !jsonFits(sliced, budget)))) {
-      throw new Error(`incomplete read of ${rel}: complete:true requires the entire file within the read budget; use json:".field" for JSON reports, about for text selection, edit() for replacements, or reconstruct resolve:true source windows`);
+      throw new Error(`incomplete read of ${rel}: complete:true requires the entire file within the read budget (${budget} characters). Use read(${JSON.stringify(rel)}, {offset:1, limit:80}) for a window, json:".field" for JSON reports, edit() for replacements, or bash({command,args}) with a bounded parser for large text/JSONL files`);
     }
   }
 

package/src/adapters/write.js

@@ -44,7 +44,12 @@ function writeOutcome(rel, target, content, speculative, prevText, removedLines)
 export function createWrite(ctx) {
   const { getCwd, vfs, index } = ctx;
 
+  const WRITE_OPTION_KEYS = ["path", "content", "append", "replace", "allowReadArtifacts"];
+
   function assertWriteParams(params) {
+    const unknown = Object.keys(params ?? {}).filter(key => !WRITE_OPTION_KEYS.includes(key));
+
+    if (unknown.length) throw new Error("write does not accept option " + unknown.map(key => JSON.stringify(key)).join(", ") + "; supported options are " + WRITE_OPTION_KEYS.join(", "));
     if (!isString(params?.content)) throw new Error("write requires string content");
     assertWriteAppendFlag(params.append);
     assertWriteArtifactsFlag(params.allowReadArtifacts);
@@ -58,13 +63,17 @@ export function createWrite(ctx) {
   }
 
   async function applyAppend(target, content, snap) {
-    let { previous: prevText, overlay, existingBytes } = snap;
+    const { overlay, existingBytes } = snap;
 
     if (existingBytes > WRITE_APPEND_MAX_READ_BYTES) throw new Error("append input exceeds " + WRITE_APPEND_MAX_READ_BYTES + " bytes; stream it with bash redirection instead");
-
-    if (existingBytes !== undefined && existingBytes > WRITE_DIFF_MAX_READ_BYTES) {
-      try { prevText = overlay !== undefined ? overlay : await vfs.read(target, { maxBytes: WRITE_APPEND_MAX_READ_BYTES, preserveRead: true }); }
-      catch (error) { if (error.code !== "ENOENT") throw error; }
+    // Append needs the real content: the diff snapshot may be a lossy decode, and
+    // concatenating that would silently corrupt a non-UTF-8 file.
+    let prevText;
+
+    try { prevText = overlay !== undefined ? overlay : await vfs.read(target, { maxBytes: WRITE_APPEND_MAX_READ_BYTES, preserveRead: true }); }
+    catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      prevText = "";
     }
 
     return { content: prevText + content, prevText, removedLines: undefined };

package/src/bridge/host-bridge.js

@@ -426,7 +426,9 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
       },
     },
     fork(options) {
-      return createHostBridge({ pi, config, getCwd: options.getCwd, registry: sharedRegistry, ledger: ledger.fork(), budget: options.budget });
+      const runConfig = options.timeoutMs === undefined ? config : { ...config, timeoutMs: Number(options.timeoutMs) };
+
+      return createHostBridge({ pi, config: runConfig, getCwd: options.getCwd, registry: sharedRegistry, ledger: ledger.fork(), budget: options.budget });
     },
     close() { closed = true; vfs.closed = true; },
     bindCallContext,

package/src/context/evidence.js

@@ -36,7 +36,7 @@ const EVIDENCE_DEFAULTS = {
 const IDENT = /[A-Za-z_$][\w$]*/g;
 
 // Verb forms only: "call sites" is a concept, "who calls X" is a usage question.
-const RELATION_WORDS = new Set(["calls", "caller", "callers", "uses", "usages", "used", "using", "imports", "imported", "depends", "references", "referenced", "invokes", "invoked"]);
+const RELATION_WORDS = new Set(["calls", "called", "caller", "callers", "uses", "usages", "used", "using", "imports", "imported", "depends", "references", "referenced", "invokes", "invoked"]);
 
 const HUB_FRACTION = 0.25;
 
@@ -575,6 +575,23 @@ function collectSpans(chosenFiles, overlayText, index, maxSpanLines) {
   return spans;
 }
 
+// Usage queries naming an exact identifier must contain that identifier outside
+// its declaration. Keep the matching line in the bounded window, even in long bodies.
+function usageSpans(spans, profile, maxSpanLines) {
+  if (profile.answerType !== "usage" || !profile.subjects.length) return spans;
+  return spans.flatMap(span => {
+    for (let i = span.start - 1; i < span.sourceEnd; i++) {
+      const words = span.lines.idents[i];
+      const matched = profile.subjects.some(subject =>
+        words.filter(word => word === subject).length > Number(span.lines.defNames[i] === subject.toLowerCase()));
+      if (!matched) continue;
+      const start = Math.max(span.start, i - 1);
+      return [{ ...span, start, end: Math.min(span.sourceEnd, start + maxSpanLines - 1) }];
+    }
+    return [];
+  });
+}
+
 function fuseScores(profile, graphNorm, hierNorm, rho) {
   const [primary, secondary] = profile.route === "relational" ? [graphNorm, hierNorm] : [hierNorm, graphNorm];
 
@@ -626,7 +643,7 @@ export async function selectEvidence({ query, root, searchDir, index, overlayTex
 
   if (profile.keywords.length === 0) throw new Error("evidence requires at least one searchable concept keyword");
   const { files: chosenFiles, fileScores } = candidateFiles(await listedFiles(root, searchDir, pendingPaths, index), profile, index, opts.maxCandidateFiles, overlayText);
-  const spans = collectSpans(chosenFiles, overlayText, index, opts.maxSpanLines);
+  const spans = usageSpans(collectSpans(chosenFiles, overlayText, index, opts.maxSpanLines), profile, opts.maxSpanLines);
 
   if (spans.length === 0) return { route: profile.route, spans: [] };
   const { picks, fused } = pickEvidence(spans, fileScores, profile, opts);

package/src/contract/bash.js

@@ -11,7 +11,12 @@ function normalizeArgv(args) {
   if (args.args === undefined) return;
   if (!isString(args.command) || !Array.isArray(args.args)) throw new Error(ARGV_ERROR);
 
-  for (let i = 0; i < args.args.length; i++) if (!isString(args.args[i])) throw new Error(ARGV_ERROR);
+  for (let i = 0; i < args.args.length; i++) {
+    if (!isString(args.args[i])) {
+      const type = args.args[i] === undefined ? "undefined" : "not a string";
+      throw new Error(`${ARGV_ERROR}; args[${i}] is ${type}; check the supplied data fields and pass each argument as a string`);
+    }
+  }
   args.args = args.args.map(String);
 
   if (process.platform === "win32") {
@@ -21,8 +26,17 @@ function normalizeArgv(args) {
   } else args._directArgv = true;
 }
 
+const BASH_OPTION_KEYS = ["command", "args", "cwd", "timeout", "timeoutMs", "_directArgv"];
+
+/** Unknown options used to be dropped silently: env/maxOutputChars never applied. */
+function assertBashOptions(args) {
+  const unknown = Object.keys(args).filter(key => !BASH_OPTION_KEYS.includes(key));
+
+  if (unknown.length) throw new Error("bash does not accept option " + unknown.map(key => JSON.stringify(key)).join(", ") + "; supported options are command, args, cwd, timeout, timeoutMs");
+}
 export function normalizeBash(command, opts) {
   const args = isObject(command) ? { ...opts, ...command } : { command, ...opts };
+  assertBashOptions(args);
   normalizeArgv(args);
 
   if (args.timeout !== undefined && args.timeoutMs === undefined) args.timeoutMs = args.timeout * 1000;

package/src/contract/edit.js

@@ -1,6 +1,6 @@
 import { isString, isObject, isFunction, isNumber } from "../shared/decode.js";
 
-export const EDIT_USAGE = 'invalid edit signature; use edit(path,oldText,newText), edit({path,edits:[{oldText,newText}]}), or edit({path,patch:"@@ -1 +1 @@\n-old\n+new\n"})';
+export const EDIT_USAGE = 'invalid edit signature; use edit(path,oldText,newText), edit(path,{oldText,newText}), edit({path,edits:[{oldText,newText}]}), or edit({path,patch:"@@ -1 +1 @@\n-old\n+new\n"})';
 
 function spanStart(value) {
   return isNumber(value.start) ? value.start : Array.isArray(value.lines) ? value.lines[0] : value.line;
@@ -40,9 +40,17 @@ function namedEditObject(p, oldText, newText) {
 }
 
 function namedEditPositional(p, oldText, newText) {
-  if (isObject(oldText) && !Array.isArray(oldText)) throw new Error(EDIT_USAGE);
+  if (Array.isArray(oldText)) return { path: p, edits: oldText };
 
-  return Array.isArray(oldText) ? { path: p, edits: oldText } : { path: p, oldText, newText };
+  if (isObject(oldText)) {
+    // edit(path,{oldText,newText}|{edits}|{patch}): the path rides in either
+    // argument, but a conflicting path or third argument is still rejected.
+    if (newText !== undefined || (oldText.path !== undefined && oldText.path !== p)) throw new Error(EDIT_USAGE);
+
+    return { ...oldText, path: p };
+  }
+
+  return { path: p, oldText, newText };
 }
 
 function normalizeEditArgs(p, oldText, newText) {
@@ -79,9 +87,19 @@ function classifyReplacements(args) {
   return { kind: "edits", command: "edit", args };
 }
 
+const EDIT_OPTION_KEYS = ["path", "oldText", "newText", "edits", "patch"];
+
+/** A view object carries host fields; only named replacements are validated. */
+function assertEditOptions(args) {
+  const unknown = Object.keys(args).filter(key => !EDIT_OPTION_KEYS.includes(key));
+
+  if (unknown.length) throw new Error("edit does not accept option " + unknown.map(key => JSON.stringify(key)).join(", ") + "; supported options are path, oldText, newText, edits, patch");
+}
+
 function classifyNamedEdit(p, oldText, newText) {
   const args = namedEditArgs(p, oldText, newText);
   assertNamedEditMode(args, oldText, newText);
+  assertEditOptions(args);
 
   return args.patch !== undefined ? classifyPatch(args) : classifyReplacements(args);
 }

package/src/contract/read.js

@@ -5,6 +5,20 @@ export const SESSION_URI = /^(?:agent|artifact):\/\//i;
 
 const BOOL_KEYS = ["resolve", "complete", "outline", "evidence"];
 
+const READ_OPTION_KEYS = ["path", "target", "about", "query", "offset", "limit", "json", "resolve", "complete", "outline", "evidence", "maxChars", "_independent"];
+
+/** Unknown options used to be dropped silently: {start,end} read the whole file. */
+function assertReadOptions(args) {
+  const unknown = Object.keys(args).filter(key => !READ_OPTION_KEYS.includes(key));
+
+  if (unknown.length === 0) return;
+  const windowHint = unknown.some(key => key === "start" || key === "end")
+    ? " For a line window use read(path, {offset:1, limit:80}): offset is the first line and limit is the line count."
+    : "";
+
+  throw new Error("read does not accept option " + unknown.map(key => JSON.stringify(key)).join(", ") + "; supported options are " + READ_OPTION_KEYS.filter(key => key !== "_independent").join(", ") + "." + windowHint);
+}
+
 export function isSessionUri(value) {
   return isString(value) && SESSION_URI.test(value);
 }
@@ -62,6 +76,7 @@ export function normalizeRead(params) {
 
   const args = sessionJsonArgs({ ...params, path: params.path ?? params.target });
   validateJsonRead(args);
+  assertReadOptions(args);
   assertReadFlags(args);
   assertExclusiveRead(args);
   assertReadPaths(args.path);

package/src/fs/check.js

@@ -134,9 +134,17 @@ function consumeSlash(text, i, prev) {
 }
 
 /** Try to consume a comment, string, template, or regex at i. Returns { end, prev } | { error, at } | null. */
-function consumeLiteral(text, i, stack, prev) {
+function consumeLiteral(text, i, stack, prev, rust) {
   const c = text[i];
 
+  if (rust && c === "'") {
+    const lifetime = /^'[\p{ID_Start}_][\p{ID_Continue}]*/u.exec(text.slice(i));
+    const end = i + (lifetime?.[0].length ?? 0);
+
+    // A closing apostrophe makes this a character literal, not a lifetime/label.
+    if (lifetime && text[end] !== "'") return { end, prev: "value" };
+  }
+
   if (c === '"' || c === "'" || c === "`") return consumeQuoted(text, i, stack);
 
   if (c !== "/") return null;
@@ -163,13 +171,13 @@ function bracket(c, i, stack, stopDepth) {
 }
 
 /** Skips comments, strings, templates and regex literals; `prev` is the last code token, which decides regex-vs-division. */
-function scan(text, start, stack, stopDepth) {
+function scan(text, start, stack, stopDepth, rust = false) {
   let i = start;
   let prev = "";
 
   while (i < text.length) {
     const c = text[i];
-    const literal = consumeLiteral(text, i, stack, prev);
+    const literal = consumeLiteral(text, i, stack, prev, rust);
 
     if (literal) {
       if (literal.error) return literal;
@@ -204,7 +212,8 @@ export function quickCheck(text, ext) {
 
   if (ext === ".json") {
     try {
-      JSON.parse(text);
+      // RFC 8259: a single leading BOM is ignorable; do not flag valid JSON.
+      JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
 
       return { ok: true, kind: "json" };
     } catch (err) {
@@ -214,7 +223,7 @@ export function quickCheck(text, ext) {
 
   if (!CODE_EXT.has(ext)) return null;
   const stack = [];
-  const r = scan(text, 0, stack);
+  const r = scan(text, 0, stack, undefined, ext === ".rs");
 
   if (r.error) return { ok: false, kind: "balance", message: r.error + " at line " + lineOf(text, r.at) };
 

package/src/fs/text-ops.js

@@ -235,6 +235,22 @@ function duplicateEditError(target, content, index, second) {
   return new Error("edit target is not unique in " + target + ": lines " + a + " and " + b + "; include more surrounding lines in oldText, or pass edits:[{oldText,newText},…]\n" + formatNumberedLine(a, lineAt(content, a)) + "\n" + formatNumberedLine(b, lineAt(content, b)));
 }
 
+/** Exact bytes at the closest guess: a byte-for-byte miss is usually indentation drift. */
+function nearMissPreview(content, oldText) {
+  const first = String(oldText).split("\n").find(line => line.trim().length > 0);
+
+  if (!first) return null;
+  const at = content.indexOf(first.trim());
+
+  if (at < 0) return null;
+  const line = lineNumberAt(content, at);
+  const start = Math.max(1, line - 2);
+  const from = lineStartIndex(content, start);
+  const shown = content.slice(from, lineEndIndex(content, from, Math.min(5, line - start + 3))).replace(/\r?\n$/, "");
+
+  return "first oldText line matches line " + line + " only after trimming; exact bytes there:\n"
+    + shown.split("\n").map((text, index) => formatNumberedLine(start + index, text)).join("\n");
+}
 function matchReplacement(target, content, replacement) {
   if (!isString(replacement?.oldText) || replacement.oldText.length === 0) {
     throw new Error("edit requires non-empty oldText");
@@ -246,7 +262,7 @@ function matchReplacement(target, content, replacement) {
   const index = content.indexOf(oldText);
 
   if (index < 0) {
-    throw new Error("edit target not found in " + target + ": oldText must match the file byte-for-byte\n" + numberedPreview(content));
+    throw new Error("edit target not found in " + target + ": oldText must match the file byte-for-byte\n" + (nearMissPreview(content, oldText) ?? numberedPreview(content)));
   }
   const second = content.indexOf(oldText, index + 1);
 
@@ -263,7 +279,13 @@ function assertNoOverlap(target, matches) {
 
 export function applyReplacements(target, content, requestedEdits) {
   if (requestedEdits.length === 0) throw new Error("edit requires at least one replacement");
-  const matches = requestedEdits.map((replacement) => matchReplacement(target, content, replacement));
+  const matches = requestedEdits.map((replacement, index) => {
+    try { return matchReplacement(target, content, replacement); }
+    catch (error) {
+      // Name the failing entry: a multi-edit miss is otherwise a guessing game.
+      throw requestedEdits.length === 1 ? error : new Error("edit " + (index + 1) + " of " + requestedEdits.length + ": " + error.message);
+    }
+  });
   matches.sort((a, b) => a.index - b.index);
   assertNoOverlap(target, matches);
   let updated = content;
@@ -380,7 +402,8 @@ async function snapshotLargeFile(vfs, target, overlay, signal) {
 }
 
 async function snapshotSmallFile(vfs, target, overlay) {
-  try { return overlay !== undefined ? overlay : await vfs.read(target, { maxBytes: WRITE_DIFF_MAX_READ_BYTES, preserveRead: true }); }
+  // Diff/receipt snapshot only: a lossy decode is acceptable and must not block a replace.
+  try { return overlay !== undefined ? overlay : await vfs.read(target, { maxBytes: WRITE_DIFF_MAX_READ_BYTES, preserveRead: true, strict: false }); }
   catch (error) {
     if (error?.code !== "ENOENT") throw error;
 
@@ -391,6 +414,8 @@ async function snapshotSmallFile(vfs, target, overlay) {
 async function existingStat(target) {
   try { return await fs.stat(target); }
   catch (error) {
+    if (error.code === "ENOTDIR") throw new Error("cannot use path: a parent component of " + target + " is a file, not a directory");
+
     if (error.code !== "ENOENT") throw error;
   }
 }

package/src/fs/vfs.js

@@ -1,6 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { isString } from "../shared/decode.js";
+import { decodeUtf8Strict } from "../shared/utf8.js";
 import { createHash, randomUUID } from "node:crypto";
 
 // Serialize validation + replacement across Supernova transactions in this host.
@@ -67,9 +68,10 @@ function overlayOrThrow(overlay, maxBytes, label) {
 }
 
 function assertReadableFile(stat, target) {
-  if (stat.isDirectory()) throw new Error("read path is a directory, not a file: " + target);
+  // Callers are reads, writes, edits and patch application: name the path, not the caller.
+  if (stat.isDirectory()) throw new Error("path is a directory, not a file: " + target);
 
-  if (!stat.isFile()) throw new Error("read requires a regular file: " + target);
+  if (!stat.isFile()) throw new Error("path is not a regular file: " + target);
 }
 
 async function readLimitedBytes(file, stat, maxBytes, label, signal) {
@@ -88,10 +90,13 @@ async function readLimitedBytes(file, stat, maxBytes, label, signal) {
 }
 
 function remapReadError(err, target) {
-  if (err.code === "EISDIR") throw new Error("read path is a directory, not a file: " + target);
+  if (err.code === "EISDIR") throw new Error("path is a directory, not a file: " + target);
+
+  if (err.code === "ENOTDIR") throw new Error("cannot use path: a parent component of " + target + " is a file, not a directory");
+  if (err.code === "EACCES" || err.code === "EPERM") throw new Error("permission denied reading " + target + ": check the file mode (for example bash chmod)");
 
   if (err.code === "ENOENT") {
-    const missing = new Error("no such file: " + target + ' (locate it with read using a directory path or source question)');
+    const missing = new Error("no such file: " + target + ' (locate it with read using a directory path or source question; use Promise.allSettled for optional reads to retain successful siblings)');
     missing.code = "ENOENT";
     throw missing;
   }
@@ -134,7 +139,16 @@ async function collectMissingAncestors(parent) {
 }
 
 async function writeTemporary(entry, content, stat) {
-  await fs.writeFile(entry.temporary, content, { encoding: "utf8", flag: "wx", mode: stat ? stat.mode & 0o7777 : 0o666 });
+  try {
+    await fs.writeFile(entry.temporary, content, { encoding: "utf8", flag: "wx", mode: stat ? stat.mode & 0o7777 : 0o666 });
+  } catch (error) {
+    // Never leak the temporary name: name the destination and the real cause.
+    if (error?.code === "EACCES" || error?.code === "EPERM") throw new Error("permission denied writing " + entry.target + ": the directory or file is not writable");
+    if (error?.code === "EROFS") throw new Error("cannot write " + entry.target + ": the file system is read-only");
+    if (error?.code === "ENOSPC") throw new Error("cannot write " + entry.target + ": no space left on device");
+
+    throw error;
+  }
 
   if (stat) await fs.chmod(entry.temporary, stat.mode & 0o7777);
 }
@@ -258,7 +272,7 @@ export class CausalVfs {
     return [...new Set(this.overlays.flatMap(overlay => [...overlay.keys()]))];
   }
 
-  async read(target, { preserveRead = false, maxBytes, label = "read input" } = {}) {
+  async read(target, { preserveRead = false, maxBytes, label = "read input", strict = true } = {}) {
     const overlay = this.getOverlay(target);
 
     if (overlay !== undefined) return overlayOrThrow(overlay, maxBytes, label);
@@ -281,7 +295,7 @@ export class CausalVfs {
       // Hash the actual bytes, not a lossy UTF-8 decode/re-encode.
       if (!preserveRead || !this.expected.has(target)) this.expected.set(target, textSignature(bytes));
 
-      return bytes.toString("utf8");
+      return strict ? decodeUtf8Strict(bytes, target) : bytes.toString("utf8");
     } catch (err) {
       remapReadError(err, target);
     }

package/src/fs/workspace.js

@@ -100,7 +100,7 @@ export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = f
   const trimmed = assertFilesystemPath(inputPath, opName);
   const resolvedCwd = getResolvedCwd(cwd);
   const target = path.resolve(resolvedCwd, trimmed);
-  assertInside(path.relative(resolvedCwd, target), `${opName} path escapes workspace: paths resolve relative to ${resolvedCwd}`);
+  assertInside(path.relative(resolvedCwd, target), `${opName} path escapes workspace: ${JSON.stringify(trimmed)} resolves to ${target}, outside ${resolvedCwd}. Use a workspace-relative path (for example artifacts/output.log); external destinations require a separately authorized command`);
 
   if (!allowRoot && target === resolvedCwd) {
     throw new Error(`${opName} path cannot be the workspace root directory`);
@@ -122,7 +122,7 @@ export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = f
     realNearest.set(target, probe);
   }
 
-  assertInside(path.relative(realRoot, probe), `${opName} path escapes workspace through symlink`);
+  assertInside(path.relative(realRoot, probe), `${opName} path escapes workspace through symlink: ${JSON.stringify(trimmed)} resolves through ${probe}, outside ${realRoot}. Use a workspace-relative path without an external symlink`);
 
   return target;
 }
@@ -216,7 +216,12 @@ function attachCommandIO(state, options, argv, timeoutMs) {
   child.stderr.setEncoding("utf8");
   child.stdout.on("data", chunk => { state.stdout = appendCommandOutput(state, state.stdout, chunk); });
   child.stderr.on("data", chunk => { state.stderr = appendCommandOutput(state, state.stderr, chunk); });
-  child.on("error", error => failCommand(state, error));
+  child.on("error", error => {
+    if (error?.code === "EACCES" || error?.code === "EPERM") failCommand(state, new Error("cannot execute " + argv[0] + ": permission denied (is it executable?)"));
+    else if (error?.code === "ENOENT") failCommand(state, new Error("command not found: " + argv[0]));
+    else if (error?.code === "ENOTDIR") failCommand(state, new Error("cannot run " + argv[0] + ": the working directory is not a directory"));
+    else failCommand(state, error);
+  });
   child.on("close", (code, signal) => onCommandClose(state, code, signal));
   options.signal?.addEventListener("abort", onAbort, { once: true });
 

package/src/output/bottleneck.js

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
-import { isString, isObject } from "../shared/decode.js";
+import { isString, isObject, mapChangedChildren, assertModelImageMime } from "../shared/decode.js";
 import { truncateChars, formatReturn, formatBoundedStringArray } from "./format.js";
 
 function json(value) {
@@ -239,15 +239,15 @@ export function packageHostResult(raw, config) {
 
 function collectImage(input, acc) {
   if (!(input?.type === "image" && isString(input.data) && isString(input.mimeType) && input.mimeType.startsWith("image/"))) return null;
+  assertModelImageMime(input.mimeType);
   const size = Buffer.byteLength(input.data, "base64");
 
-  if (acc.images.length >= 16 || acc.imageBytes + size > 20 * 1024 * 1024) {
+  acc.imageCount += 1;
+  acc.imageBytes += size;
+  if (acc.imageCount > 16 || acc.imageBytes > 20 * 1024 * 1024) {
     acc.imageOverflow = true;
-
-    return "[image omitted: exceeds 16 attachments or 20 MiB]";
+    return "[image over budget]";
   }
-
-  acc.imageBytes += size;
   acc.images.push({ type: "image", data: input.data, mimeType: input.mimeType });
 
   return `[image ${acc.images.length}: ${input.mimeType}]`;
@@ -258,11 +258,7 @@ function collectImages(input, acc) {
 
   if (replaced !== null) return replaced;
 
-  if (Array.isArray(input)) return input.map(child => collectImages(child, acc));
-
-  if (isObject(input)) return Object.fromEntries(Object.entries(input).map(([key, child]) => [key, collectImages(child, acc)]));
-
-  return input;
+  return mapChangedChildren(input, collectImages, acc);
 }
 
 function serializeReturn(value, formatted, maxReturn, imageOverflow) {
@@ -293,8 +289,11 @@ function clipLogs(logs, config) {
 }
 
 export function packageFinalReturn(value, logs, config) {
-  const acc = { images: [], imageBytes: 0, imageOverflow: false };
+  const acc = { images: [], imageCount: 0, imageBytes: 0, imageOverflow: false };
   value = collectImages(value, acc);
+  if (acc.imageOverflow) {
+    throw new Error(`image attachment budget exceeded: ${acc.imageCount} images / ${acc.imageBytes} bytes; limit is 16 images / 20971520 bytes (20 MiB). No images returned; return fewer or smaller images per program`);
+  }
   const maxReturn = config.maxReturnChars ?? 32000;
   const serialized = serializeReturn(value, formatReturn(value), maxReturn, acc.imageOverflow);
   const clipped = clipLogs(logs, config);