pi-supernova 0.8.0 → 0.8.1

package/README.md

@@ -12,47 +12,56 @@ Ordinary JavaScript control flow remains available; the guest command bindings
 are only `read`, `edit`, `write`, and `bash`. Supernova supplies retrieval,
 transactional file operations, batching, bounded results and the grouped nova UI.
 
-## Unreleased
+## What is new in 0.8.0
 
 - **Shared program source:** top-level `code` or `file` supplies a batch default;
-  entries may override it. No temporary program file is required for inline reuse.
+  entries may override it. A shared program is sent once instead of in every entry,
+  and defaults count once against the 48,000-character admission cap.
 - **Explicit object defaults:** `mergeData:true` shallowly overlays per-entry data
-  onto common data. Existing whole-input replacement remains the default.
-
-- Failed `edit` checkpoints now roll back and **throw**. Catch explicitly when
-  rejecting a candidate is intentional; ignored failures no longer report success.
-- Read errors state both size limits and executable recovery examples. Markdown
-  edits skip code-reference searches; exact-symbol usage evidence excludes generic
-  matches and keeps late references inside the returned window.
-- Returned image sets over 16 images / 20 MiB fail with aggregate counts and bytes,
-  rather than silently omitting attachments. Pending file changes roll back.
-
-- **`parallel: true` on `programs`:** independent entries run at once (up to 8),
-  keep result order, and do not stop siblings on failure. Sequential is still
-  the default.
-- **JSON `.length`:** `read({path, json:".items.length"})` returns the array
-  length without dumping the array.
-- Prefer `edit` for a file you already read; `write` still replaces the file.
-
-## What is new in 0.7.0
-
-- **Faster batches:** guest workers pipeline their successor, so sequential
-  programs run about twice as fast with no token cost.
-- **Hardened guest:** `process.kill` is sealed out; patch hunks report
-  relocation and ambiguous hunks fail instead of misapplying.
-- **Leaner receipts:** multi-edit output caps at 32 matches with exact totals,
-  write receipts go workspace-relative, evidence/outline reads go compact.
-
-## What is new in 0.6.0
-
-- **Shared batch input:** supply top-level `data` once; each program gets an
-  independent copy unless it supplies its own replacement data.
-- **Conflict protection:** byte snapshots survive partial reads and body-cache
-  eviction; receipt generation cannot silently rebase a pending write.
-- **Read fidelity:** staged declarations remain discoverable in large/new files,
-  line windows preserve source endings, and `complete` always means the whole file.
-- **Explicit failures:** incompatible read modes, budget-limited matches, captured
-  overrides and conflicting new-file aliases no longer silently change outcomes.
+  onto common data (entry keys win; nested objects are replaced). Whole-input
+  replacement remains the default.
+- **Checkpoint failures throw:** a failed `edit(async () => {...})` rolls back and
+  rethrows its original cause; catch explicitly when rejecting a candidate is
+  intentional. Ignored failures no longer report success.
+- **Accurate failure cards:** the nova card reads the host's error flag, shows the
+  original cause and `committed`/`rolledBack` totals, marks writes whose
+  persistence cannot be attributed as attempted, and labels pure JavaScript runs
+  instead of "complete".
+- **Bounded, explicit reads:** errors state both limits (`160 lines / 8192
+  characters`) with copyable recovery (`offset`, `about`, `complete:true`, and
+  `Promise.allSettled` for optional siblings). Markdown edits skip code-reference
+  searches; exact-symbol evidence excludes generic matches.
+- **Fail-closed images:** unsupported formats (for example BMP) fail before model
+  delivery with PNG-conversion guidance, and sets over 16 images / 20 MiB report
+  aggregate sizes instead of silently omitting attachments. Pending changes roll back.
+- **Shell follows the program clock:** `bash()` inherits the program's `timeoutMs`;
+  explicit per-command limits still win.
+
+### Tokens: 0.7.1 to 0.8.0 (`js-tiktoken`, `o200k_base` / `cl100k_base`)
+
+| Metric | 0.7.1 | 0.8.0 | Change |
+|---|---:|---:|---:|
+| Standing definition per request | 596 / 588 | 631 / 626 | +35 / +38 |
+| Frozen 6-call mixed workload, total traffic | 9,596 / 9,458 | 9,841 / 9,724 | +2.6% / +2.8% |
+| 16-program job with shared source + data (32 files) | 17,771 / 17,595 | 3,587 / 3,533 | -79.8% / -79.9% |
+| 8 programs sharing a 48-path input | 16,309 / 14,649 | 5,499 / 5,197 | -66.3% / -64.5% |
+
+Rows 3-4 deliver identical complete outputs and files; only argument placement
+changes. Row 2 repeats no inputs, so it pays the +35-token guidance and nothing
+else. Method, gates and limits: [TOKEN_COSTS.md](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/docs/TOKEN_COSTS.md).
+
+### Speed: engine micro-benchmarks (Apple M5 Max, Node 26.7)
+
+| Benchmark | Before | After | Change |
+|---|---:|---:|---:|
+| Package 200-row report (median, 10k iterations) | 0.1665 ms | 0.1314 ms | -21% |
+| Package nested source object (median) | 0.0366 ms | 0.0240 ms | -35% |
+| Idle worker exit | 267 ms | 17 ms | -94% |
+| 8-file read wave p50 / p95 (300 samples) | 1.90 / 2.74 ms | 1.77 / 2.53 ms | -7% / -8% |
+| Cold unbatched p95 vs coalesced warm p95 (8 reads) | 13.85 ms | 2.39 ms | -83% |
+
+Identical output hashes before and after. Local engine benchmarks, not end-to-end
+agent latency or provider time.
 
 See the [changelog](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/docs/CHANGELOG.md)
 and [token measurements](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/docs/TOKEN_COSTS.md).

package/docs/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 ## Unreleased
 
+## [0.8.1] - 2026-09-19
+
+### Fixed
+
+- Reads, windows, edits and appends reject **non-UTF-8** files with the path and
+  a conversion hint instead of returning U+FFFD, which an edit or append could
+  have written back as corruption. Prefix windows still drop one partial
+  character at the byte cut; diff/receipt snapshots stay tolerant so an explicit
+  `replace:true` still overwrites any file.
+- Unknown options now fail loudly on every command: `read` (for example a
+  foreign `{start,end}` window, which used to return the whole file) and
+  `bash`/`write`/`edit` (`env`, `maxOutputChars`, `mode`, `all` were dropped
+  silently). Each error names the option and the supported set.
+- Filesystem failures name the path or command: write and edit no longer say
+  "read path is a directory"; `ENOTDIR`/`EACCES`/`EPERM`/`EROFS`/`ENOSPC` no
+  longer leak raw codes or the `.supernova-<uuid>.new` temporary; `bash cwd`
+  must be a directory (`spawn ENOTDIR` is gone).
+- `readWindow` no longer leaks an unhandled rejection while `finally` awaits
+  `file.close()`; failing window reads settle cleanly.
+- Edit target misses report the closest matching line with its exact bytes
+  instead of only the file head; multi-edit failures name the entry
+  (`edit 2 of 3`); `edit(path,{oldText,newText}|{edits}|{patch})` dispatches.
+- Syntax errors quote the offending source line and column with a caret;
+  `file:` programs name the file, and invalid UTF-8 names the file too.
+- JSON projection reports the parse position with the offending line when V8
+  provides one, and ignores one leading BOM (also in write checks).
+- Timeout and batch-deadline messages report elapsed time against the limit, and
+  a deadline-killed program is no longer reported as a plain program failure.
+
+### Internals
+
+- 259 package tests, actual Pi + OMP host smoke, isolated Spark run, a
+  536-program stress pass, and both frozen token gates.
+
 ## [0.8.0] - 2026-09-19
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-supernova",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "CodeMode for Pi and OMP: read, edit, write and bash, with transactional files, source views and shared-input program batches.",
   "type": "module",
   "author": "AdityaVG13",

package/src/adapters/bash.js

@@ -1,3 +1,4 @@
+import * as fs from "node:fs/promises";
 import { isString } from "../shared/decode.js";
 import { unwrapIfFullyQuoted } from "../fs/text-ops.js";
 import { sourceForReferences } from "../fs/source-window.js";
@@ -35,6 +36,12 @@ export function createBash(ctx) {
       const { literal, command, argv } = parseBash(params);
       const targetCwd = params?.cwd ? await resolveWorkspacePath(cwd, params.cwd, "bash cwd", true) : cwd;
 
+      if (params?.cwd !== undefined) {
+        const st = await fs.stat(targetCwd).catch(() => null);
+
+        if (!st?.isDirectory()) throw new Error("bash cwd is not a directory: " + params.cwd);
+      }
+
       const transactionBarrier = await vfs.prepareExternalMutation("bash");
       let res;
 

package/src/adapters/read.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)];

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/contract/bash.js

@@ -26,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

@@ -212,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) {

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,7 +90,10 @@ 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; use Promise.allSettled for optional reads to retain successful siblings)');
@@ -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

@@ -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/runtime/program-batch.js

@@ -146,6 +146,10 @@ class ProgramBatch {
     }
   }
 
+  /** Elapsed and limit: 'deadline or cancellation' alone cannot tell them apart. */
+  deadlineNote() {
+    return " (ran " + Math.round(performance.now() - this.started) + "ms of " + this.timeout + "ms)";
+  }
   takeSettled(result, i) {
     this.results.push(result);
     this.trace.push(...(result.details?.trace ?? []));
@@ -170,7 +174,7 @@ class ProgramBatch {
       this.takeSettled(settled[i], i);
     }
 
-    if (settled.includes(undefined) || this.combined.aborted || performance.now() >= this.deadline) this.stopped = "batch deadline or cancellation; earlier commits remain";
+    if (settled.includes(undefined) || this.combined.aborted || performance.now() >= this.deadline) this.stopped = "batch deadline or cancellation; earlier commits remain" + this.deadlineNote();
   }
 
   sequentialStop(result, i) {
@@ -185,14 +189,15 @@ class ProgramBatch {
 
     if (result.details?.logTruncated) stopped ||= "batch log budget exceeded; remaining programs did not run; earlier commits remain";
 
-    if (this.combined.aborted || performance.now() >= this.deadline) stopped ||= "batch deadline or cancellation; earlier commits remain";
+    // 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();
 
     return stopped;
   }
 
   async runSequential() {
     for (const [i, program] of this.programs.entries()) {
-      if (this.combined.aborted || performance.now() >= this.deadline) { this.stopped = "deadline or cancellation; remaining programs did not run"; break; }
+      if (this.combined.aborted || performance.now() >= this.deadline) { this.stopped = "deadline or cancellation; remaining programs did not run" + this.deadlineNote(); break; }
 
       const result = await this.runOne(program, i);
       this.live[i] = [];

package/src/runtime/program-file.js

@@ -34,7 +34,10 @@ export async function readProgramFile(file, cwd, maxChars, signal) {
 
     signal?.throwIfAborted();
     // 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));
+    let code;
+
+    try { code = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Buffer.concat(chunks)); }
+    catch { throw new Error("program file " + file + " is not valid UTF-8 (encoded data could not be decoded); save it as UTF-8 text"); }
 
     if (code.length > chars) throw tooLarge();
 

package/src/runtime/runtime.js

@@ -6,6 +6,7 @@ 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";
 
 const WORKER_URL = new URL("./guest-worker.js", import.meta.url);
 
@@ -327,7 +328,7 @@ class GuestRun {
     try { this.onTimeout?.(); } catch {}
 
     this.aborting = false;
-    this.finish(this.fail(ABORT_MESSAGE));
+    this.finish(this.fail(ABORT_MESSAGE + " (ran " + Math.round(this.wall()) + "ms of " + this.timeoutMs + "ms)"));
   }
 
   postResult(message) {
@@ -434,7 +435,14 @@ class GuestRun {
     if (!this.code.trim()) { this.finish(this.fail("code must be a non-empty string; no commands ran")); return false; }
 
     try { this.prepared = prepareProgram(this.code); }
-    catch (error) { this.finish(this.fail("JavaScript syntax error: " + error.message + "; no commands ran. Put literal file/script content in the tool's data parameter and use write(data.path,data.content) or bash({command,args:data.args}).")); return false; }
+    catch (error) {
+      const guidance = this.file === undefined
+        ? " Put literal file/script content in the tool's data parameter and use write(data.path,data.content) or bash({command,args:data.args})."
+        : " Fix " + this.file + " and re-run.";
+
+      this.finish(this.fail("JavaScript syntax error" + (this.file === undefined ? "" : " in " + this.file) + ": " + error.message + "; no commands ran." + guidance + errorContext(this.code, error)));
+      return false;
+    }
 
     return true;
   }

package/src/shared/syntax-context.js

@@ -0,0 +1,31 @@
+/** Bounded source context for parse and syntax diagnostics. */
+
+export function sourceContext(source, line, column) {
+  if (!Number.isInteger(line) || line < 1) return "";
+  const text = String(source).split("\n")[line - 1];
+
+  if (text === undefined) return "";
+  const shown = text.length > 160 ? text.slice(0, 160) : text;
+  const caret = Number.isInteger(column) ? " ".repeat(Math.min(column, shown.length)) + "^" : "";
+
+  return "\n  " + shown + (caret ? "\n  " + caret : "");
+}
+
+/** acorn-style error that carries a loc, when it has one. */
+export function errorContext(source, error) {
+  return sourceContext(source, error?.loc?.line, error?.loc?.column);
+}
+
+/** V8 "(line 5 column 3)" or "at position 42" parse messages → a position. */
+export function parsePosition(message, source) {
+  const located = /\(line (\d+) column (\d+)\)/.exec(String(message));
+
+  if (located) return { line: Number(located[1]), column: Number(located[2]) };
+  const offsetMatch = /at position (\d+)/.exec(String(message));
+
+  if (!offsetMatch) return null;
+  const before = String(source).slice(0, Number(offsetMatch[1]));
+  const lines = before.split("\n");
+
+  return { line: lines.length, column: lines.at(-1).length };
+}

package/src/shared/utf8.js

@@ -0,0 +1,17 @@
+/** Strict decode: binary or non-UTF-8 text must fail loudly, never as U+FFFD. */
+export function decodeUtf8Strict(bytes, target) {
+  try { return new TextDecoder("utf-8", { fatal: true }).decode(bytes); }
+  catch {
+    throw new Error("not valid UTF-8 (binary or non-UTF-8 text): " + target + "; inspect or convert it with bash (for example iconv -f latin1 -t utf8 or xxd)");
+  }
+}
+
+/** Prefix window: the byte cut may split a character, so drop one partial tail. */
+export function decodeUtf8Window(bytes) {
+  for (let cut = 0; cut <= 3 && cut < bytes.length; cut++) {
+    try { return new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, bytes.length - cut)); }
+    catch { /* a partial character at the cut is expected */ }
+  }
+
+  return bytes.toString("utf8");
+}