pi-supernova 0.8.0 → 0.8.2

package/README.md

@@ -12,47 +12,84 @@ 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.2
+
+This patch release fixes shell failure handling, cancellation and parallel-batch
+limits, and makes one-call batching guidance explicit.
+
+- **Shell quoting stays intact:** quoted executable paths are no longer unwrapped.
+  Shell syntax errors suggest literal `bash({command,args})` with `data` for
+  embedded scripts, or a quoted heredoc. Commands are not rewritten or retried.
+- **Validation before commit:** invalid timeouts and null-byte
+  arguments are rejected before the shell boundary flushes staged files.
+- **Useful failure output:** long command labels are bounded so the original
+  stderr is not crowded out by a repeated script.
+- **Timeouts retain diagnostics:** the outer program deadline stops the worker
+  and gives pending host calls a bounded drain to retain shell output. Explicit
+  cancellation is reported separately from timeout. The outer `timeoutMs` covers
+  every wait and command, including `sleep`.
+- **Parallel budgets fail honestly:** exceeding the shared output, log or image
+  allowance marks the batch failed and stops queued entries. Already-running
+  entries settle; their results and completed commits remain. Aggregate logs stay
+  capped rather than multiplying the allowance per guest.
+- **Batch known work in one call:** combine independent reads/checks with
+  `Promise.all`, then sequence edits and verification in the same program. Use
+  another invocation when returned evidence is needed for the next decision.
+
+Verified on **macOS / Node 26.7**: 267 package tests (384 repository tests),
+2,328 stress invocations, actual Pi/OMP host checks, lint and both token-budget
+checks. This is not a claim of exhaustive platform or formal mutation testing.
+
+## 0.8.0 features and measurements
 
 - **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).
@@ -72,14 +109,12 @@ Local checkout installs are for development, not distribution:
 pi install /path/to/pi-stack/packages/pi-supernova
 ```
 
-Git pushes do not update npm installations. Publish the new npm version first;
-then reinstall it in the host. Reinstall explicitly when an existing version
-range excludes the new minor version (`^0.6.0` excludes `0.7.0`). After 0.7.0 is
-published, pin that release with:
+Git pushes do not update npm installations. Publish the new npm version first,
+then reinstall it in your host. To pin **0.8.2** once it is published:
 
 ```bash
-pi install npm:pi-supernova@0.7.0
-omp install npm:pi-supernova@0.7.0
+pi install npm:pi-supernova@0.8.2
+omp install npm:pi-supernova@0.8.2
 ```
 
 In Pi, `pi list` shows the configured package sources. A local path uses that
@@ -126,6 +161,21 @@ payloads are not repeated in owned direct-execution errors;
 stdout/stderr, exit status and source context remain. Session environment variables are taken
 from the current execution context, not inherited from a different parent session.
 
+Shell strings are executed unchanged, including quoted executable paths. For inline
+Python/Node scripts, prefer literal argv with `data` instead of nested shell quotes:
+
+```json
+{
+  "code": "return await bash({command:\"python3\",args:[\"-c\",data.script]});",
+  "data": {"script": "q = {'name': 'example'}\nprint(f\"{q['name']}\")\n"}
+}
+```
+
+Shell syntax errors keep the original diagnostic and suggest argv or a quoted
+heredoc; commands are never automatically rewritten or retried. Invalid timeouts
+and null-byte arguments fail before flushing staged changes. Failure labels are
+bounded so a large script cannot crowd out its stderr.
+
 Source questions locate a declaration in one command. An exact
 declaration match uses one bounded direct ripgrep search, without a prerequisite
 file listing, persistent index, embeddings or summarization. A transient filename
@@ -340,6 +390,9 @@ Set `parallel: true` with `programs` to run independent entries concurrently
 in submission order. A failed entry does not stop siblings. Two entries writing
 the same file race: the losing commit reports a conflict. Sequential remains the
 default. `parallel` and `mergeData` are invalid on a lone `code` or `file` call.
+Budget overflow marks the batch failed and stops queued entries; already-running
+entries settle and their completed commits remain. Parallel execution does not
+multiply the aggregate output, log, or image allowance.
 
 The outer deadline, host-call budget, log allowance, text budget and image limits
 are shared across the batch. Individual read budgets are not reduced. Every
@@ -371,10 +424,13 @@ For long archive scans, use resumable chunks or a host background-job tool and w
 progress records under `.work`. Shell commands inherit the current program
 `timeoutMs` unless they specify their own; increasing the outer deadline no longer
 leaves a hidden 60-second shell cap. Set the inner `bash` timeout shorter than the
-outer program timeout (for example 10 seconds inside a 20-second program) to retain
-bounded shell diagnostics. A hard guest deadline cannot guarantee pending shell
-output delivery; progress files survive shell execution but staged VFS writes may
-roll back.
+outer program timeout (for example 10 seconds inside a 20-second program). The outer
+deadline covers **all** waits and commands, including `sleep`; a shell's own `timeout`
+command does not extend it. On a deadline or cancellation, the worker stops and
+pending host calls get a bounded 250ms drain to retain owned-shell diagnostics and
+finalize process termination. Non-cooperating host executors may still outlive that
+drain. Cancellation is reported separately from timeout; neither triggers a retry.
+Progress files survive shell execution but staged VFS writes may roll back.
 
 Large returned objects are bounded previews, not retained artifacts. Select fields
 and array windows before returning, rather than parsing a truncated preview.
@@ -423,6 +479,12 @@ continuation handles.
 
 ## Execution and automatic batching
 
+Put already-known independent reads and checks in **one** Supernova program using
+`Promise.all` (or `Promise.allSettled` when failures should remain independent).
+Sequence edits and their known verification in that same program. Start another
+invocation only when the returned evidence is needed to decide what to do next;
+use focused read windows to keep the combined result within its output budget.
+
 Compatible independently started reads coalesce at the worker/host boundary.
 No additional batching command is required. Individual promises preserve their
 values, errors and per-read budgets. File reads have bounded parallelism; writes,

package/docs/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 ## Unreleased
 
+## [0.8.2] - 2026-09-19
+
+### Fixed
+
+- Shell commands preserve quoted executable paths. Parser failures suggest
+  literal argv for embedded scripts or a quoted heredoc, without rewriting or
+  automatically retrying commands.
+- Invalid timeouts and null-byte arguments fail before flushing staged files.
+  Bounded command labels keep long scripts from crowding out diagnostics.
+- Program deadlines retain pending shell output during bounded termination;
+  explicit cancellation is no longer misreported as a timeout.
+- Parallel batches enforce shared output, log and image budgets instead of
+  reporting success after overflow. Queued entries stop, in-flight results and
+  completed commits remain, and aggregate logs stay capped.
+
+### Changed
+
+- Guidance explicitly batches known reads/checks and edits/verification in one
+  invocation, and states that the outer deadline includes all waits and commands.
+
+### Internals
+
+- 267 package tests (384 repository tests), 2,328 stress invocations, actual
+  Pi + OMP host checks, lint and both frozen token gates passed on macOS/Node 26.7.
+
+## [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.2",
   "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,5 +1,6 @@
+import * as fs from "node:fs/promises";
 import { isString } from "../shared/decode.js";
-import { unwrapIfFullyQuoted } from "../fs/text-ops.js";
+import { normalizeBash } from "../contract/bash.js";
 import { sourceForReferences } from "../fs/source-window.js";
 import { resolveWorkspacePath, runCommand, clearPathCache } from "../fs/workspace.js";
 
@@ -16,7 +17,7 @@ export function createBash(ctx) {
   function bashCommand(params, literal) {
     if (params?.command !== undefined && !isString(params.command)) throw new Error("bash command must be a string");
     if (literal && (!isString(params.command) || params.args.some(arg => !isString(arg)))) throw new Error("bash argv requires a command string and an array of string args");
-    const command = literal ? String(params.command) : unwrapIfFullyQuoted(String(params?.command ?? "").trim());
+    const command = String(params?.command ?? "");
 
     if (!command.trim()) throw new Error("bash requires command");
 
@@ -31,10 +32,17 @@ export function createBash(ctx) {
   }
 
   async function bash(params, signal) {
+      params = normalizeBash(params);
       const cwd = getCwd();
       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;
 
@@ -42,7 +50,7 @@ export function createBash(ctx) {
         res = await runCommand(argv, {
           cwd: targetCwd,
           env: hooks.commandEnv(),
-          commandLabel: literal ? command : undefined,
+          commandLabel: command,
           timeoutMs: params?.timeoutMs === undefined ? config.timeoutMs : params.timeoutMs,
           signal,
           maxOutputChars: config.maxCallResultChars,
@@ -60,7 +68,12 @@ export function createBash(ctx) {
       const { stdout, stderr } = res;
       let text = combineBashText(stdout, stderr);
 
-      if (res.exitCode !== 0) text += await sourceForReferences(cwd, targetCwd, text, signal, ledger);
+      if (res.exitCode !== 0) {
+        if (!literal && /\bbash: (?:-c: )?line \d+: (?:syntax error|unexpected EOF)/.test(stderr)) {
+          text += '\nhint: Bash could not parse the command. For embedded scripts use literal argv, e.g. bash({command:"python3",args:["-c",data.script]}), or a quoted heredoc for shell pipelines. Do not blindly retry: earlier commands may have run.';
+        }
+        text += await sourceForReferences(cwd, targetCwd, text, signal, ledger);
+      }
 
       return {
         content: [{ type: "text", text }],

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

@@ -17,7 +17,10 @@ function normalizeArgv(args) {
       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);
+  args.args = args.args.map((arg, i) => {
+    if (arg.includes("\0")) throw new Error(`bash args[${i}] must not contain null bytes`);
+    return String(arg);
+  });
 
   if (process.platform === "win32") {
     delete args._directArgv;
@@ -26,11 +29,28 @@ 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);
+  if (!isString(args.command) || !args.command.trim()) throw new Error("bash requires a non-empty command string");
+  if (args.command.includes("\0")) throw new Error("bash command must not contain null bytes");
   normalizeArgv(args);
 
   if (args.timeout !== undefined && args.timeoutMs === undefined) args.timeoutMs = args.timeout * 1000;
+  // Reject before the host's external-mutation barrier can flush staged files.
+  if (args.timeoutMs !== undefined) {
+    const timeout = Number(args.timeoutMs);
+    if (!Number.isFinite(timeout) || timeout <= 0) throw new Error("command timeoutMs must be a positive finite number");
+    args.timeoutMs = Math.max(1, Math.min(2_147_483_647, Math.floor(timeout)));
+  }
 
   return args;
 }

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

@@ -81,21 +81,6 @@ export function resultDiff(response) {
   return isObject(details) ? details.diff : undefined;
 }
 
-/** Unwrap a single matching quote pair around the whole string (`'git status'`). */
-export function unwrapIfFullyQuoted(s) {
-  if (s.length < 2) return s;
-  const q = s[0];
-
-  if (q !== "'" && q !== '"') return s;
-
-  if (s[s.length - 1] !== q) return s;
-  const inner = s.slice(1, -1);
-
-  if (inner.includes(q)) return s;
-
-  return inner;
-}
-
 function totalContentLines(text) {
   if (text === "") return 1;
 
@@ -235,6 +220,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 +247,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 +264,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 +387,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 +399,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

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import { spawn } from "node:child_process";
 import { constants } from "node:os";
 import { isString } from "../shared/decode.js";
+import { truncateChars } from "../output/format.js";
 
 let cachedCwd = null;
 
@@ -211,12 +212,20 @@ function attachCommandIO(state, options, argv, timeoutMs) {
     clearTimeout(state.escalation);
     options.signal?.removeEventListener("abort", onAbort);
   };
-  state.timer = setTimeout(() => terminateCommand(state, new Error("command timed out after " + timeoutMs + "ms: " + (options.commandLabel ?? argv.join(" ")))), timeoutMs);
+  state.timer = setTimeout(() => terminateCommand(state, new Error(
+    "command timed out after " + timeoutMs + "ms: " + truncateChars(options.commandLabel ?? argv.join(" "), 240, "command").text
+    + "\nhint: Increase this bash timeoutMs and the outer supernova timeoutMs, or split the work. Sleeps and every command in a shell chain share the same limit."
+  )), timeoutMs);
   child.stdout.setEncoding("utf8");
   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/guest-worker.js

@@ -256,7 +256,7 @@ function formatBashFailure(command, res) {
   const output = String(res.value).trimEnd();
   const suffix = Number.isInteger(exitCode) ? " (exit " + exitCode + ")" : "";
 
-  return "command failed" + suffix + ": " + command + (output ? "\n" + output : "");
+  return "command failed" + suffix + ": " + truncateChars(command, 240, "command").text + (output ? "\n" + output : "");
 }
 
 function markTruncatedOutput(res, text) {

package/src/runtime/program-batch.js

@@ -146,22 +146,45 @@ 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 ?? []));
     this.collectImages(result, i);
   }
 
+  parallelBudgetStop(settled) {
+    const results = settled.filter(Boolean);
+    let images = 0, bytes = 0, labelChars = 0;
+    for (const [i, result] of settled.entries()) {
+      let imageSeq = 0;
+      for (const block of result?.content ?? []) if (block.type === "image" && isString(block.data)) {
+        images++;
+        bytes += Buffer.byteLength(block.data, "base64");
+        labelChars += ("program " + (i + 1) + " image " + (++imageSeq)).length + 1;
+      }
+    }
+    let kind;
+    if (images > 16 || bytes > 20 * 1024 * 1024) kind = "image";
+    else if (results.some(result => result.details?.returnTruncated) || programBatchText(results, this.programs.length).length + labelChars > this.config.maxReturnChars) kind = "output";
+    else if (results.some(result => result.details?.logTruncated) || results.reduce((n, result) => n + (result.details?.logs?.length ?? 0), 0) > (this.config.maxLogLines ?? 100)) kind = "log";
+    return kind ? "batch " + kind + " budget exceeded; completed commits remain" : "";
+  }
+
   async runParallel() {
     const limit = Math.min(this.programs.length, MAX_PARALLEL_PROGRAMS);
     const settled = Array.from({ length: this.programs.length });
     let next = 0;
 
     await Promise.all(Array.from({length: limit}, async () => {
-      while (next < this.programs.length && !this.combined.aborted && performance.now() < this.deadline) {
+      while (next < this.programs.length && !this.stopped && !this.combined.aborted && performance.now() < this.deadline) {
         const i = next++;
         settled[i] = await this.runOne(this.programs[i], i);
         this.live[i] = [];
+        this.stopped ||= this.parallelBudgetStop(settled);
       }
     }));
 
@@ -170,7 +193,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 ((!this.stopped && settled.includes(undefined)) || this.combined.aborted || performance.now() >= this.deadline) this.stopped = "batch deadline or cancellation; earlier commits remain" + this.deadlineNote();
   }
 
   sequentialStop(result, i) {
@@ -185,14 +208,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] = [];
@@ -217,6 +241,8 @@ class ProgramBatch {
     const failed = this.results.filter(result => result.details?.ok === false).length;
     const bounded = this.boundedText(failed);
     const content = [{type:"text",text:bounded.text}];
+    const logs = this.results.flatMap(result => result.details?.logs ?? []);
+    const logLimit = this.config.maxLogLines ?? 100;
     this.images.forEach((image,i) => content.push({type:"text",text:this.imageLabels[i]},image));
 
     // Return a typed stop report instead of throwing away earlier results/images.
@@ -225,7 +251,7 @@ class ProgramBatch {
       programs:this.results,attempted:this.results.length,total:this.programs.length,stopped:this.stopped,parallel:this.parallel,
       result:bounded.truncated ? bounded.text : this.results.map(result=>result.details?.result),
       returnTruncated:bounded.truncated || this.results.some(result=>result.details?.returnTruncated),
-      logTruncated:this.results.some(result=>result.details?.logTruncated),logs:this.results.flatMap(result=>result.details?.logs ?? []),trace:this.trace,mutations:mutationTotals(this.results)}};
+      logTruncated:logs.length > logLimit || this.results.some(result=>result.details?.logTruncated),logs:logs.slice(0,logLimit),trace:this.trace,mutations:mutationTotals(this.results)}};
   }
 
   async run() {

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/reference.js

@@ -1,15 +1,15 @@
 // Standing tool description: sent on every request. No result or history compression.
-export const REFERENCE = `JS body/async arrow with read/write/edit/bash; no fs/import/require. file runs workspace scripts. data holds literal text/scripts/argv (≤48000 serialized JSON chars).
-read(path|paths,offset=1,limit?) → raw text/text[]; directories → entries; images: PNG/JPEG/GIF/WebP (≤16 attachments/20 MiB total).
-Path-only: ≤160 lines AND 8192 characters (UTF-16). Use read(path,{offset:1,limit:80}), about, or complete:true (whole file ≤31744 chars). Large JSONL: bounded parser via bash.
-read({path,json:selector}) → parsed JSON; selectors ".field", ".a[0:3]", ".a.length", quoted keys, true; 16 MiB input, no jq. Oversized → {status:"too_large",keys} (arrays: length); narrow selectors.
+export const REFERENCE = `JS body/async arrow: read/write/edit/bash; no fs/import/require. file: workspace scripts; data: literals (≤48000 JSON chars).
+read(path|paths,offset=1,limit?) → raw text/text[]; directories → entries; images: PNG/JPEG/GIF/WebP (≤16 images/20 MiB).
+Path-only ≤160 lines AND 8192 characters (UTF-16); larger: read(path,{offset:1,limit:80}), about, or complete:true (whole file ≤31744 chars). Large JSONL: bounded bash parser.
+read({path,json:selector}) → parsed JSON: ".field", ".a[0:3]", ".a.length", quoted keys, true; ≤16 MiB, no jq. {status:"too_large",keys|length} → narrow selector.
 read("symbol or question") = read({query,resolve:true}) → view; check status; view.text is a span, not the file.
 read(path,{about}) → windows; read({query,evidence:true}) → ranked evidence; read({path,outline:true}) → declarations.
 write(path,text) replaces unread workspace files; write({path,content,append:true}) appends without reading. After read: edit or replace:true.
-edit(path,oldText,newText) | edit({path,edits:[{oldText,newText}]}) exact unique read text; numbered windows (including misses), checks/references.
-edit(view,text) replaces the span; edit(view,old,new) matches uniquely within it. edit(async()=>{...}) checkpoint merges on success, rolls back/rethrows on failure; catch to recover.
-bash(command,{cwd?,timeoutMs?}) | bash({command,args}) literal argv; bounded output, nonzero throws; inherits program timeout unless overridden.
+edit(path,oldText,newText) | edit({path,edits:[{oldText,newText}]}) unique exact read text; returns numbered windows/checks/references.
+edit(view,text) replaces span; edit(view,old,new) uniquely matches within it. edit(async()=>{...}) checkpoint: merge on success, rollback/rethrow on failure.
+bash(command,{cwd?,timeoutMs?}) | bash({command,args}) literal argv for scripts; bounded output, nonzero throws. Outer timeoutMs caps ALL waits/commands; bash inherits unless overridden.
 Edits stage until success; bash commits first. Array errors abort; Promise.allSettled for optional reads.
-programs:[{code?,file?,data?}] inherits top-level code OR file and data. Entry source overrides; data replaces unless mergeData:true (shallow objects, entry keys win).
-Fresh guests/separate commits; sequential failure stops, prior commits stay. parallel:true for disjoint entries. Batch known work; separate calls only for new decisions.
+programs:[{code?,file?,data?}] inherits code OR file and data. Entries override source/data; mergeData:true shallow-merges objects (entry keys win).
+Fresh guests/separate commits; sequential failure stops, prior commits stay. parallel:true for disjoint entries. Batch known reads/checks (Promise.all) + edits/verification in ONE call; split for new decisions.
 `;

package/src/runtime/runtime.js

@@ -6,10 +6,12 @@ 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);
 
-const ABORT_MESSAGE = "supernova timed out or aborted: pass timeoutMs to allow longer runs, or split the program";
+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_POLL_MS = 50;
 
@@ -280,6 +282,7 @@ class GuestRun {
     this.hostError = undefined;
     this.notifyingHost = false;
     this.aborting = false;
+    this.abortOutcome = undefined;
     this.pending = new Set();
     this.inputController = new AbortController();
     this.rpcCount = 0;
@@ -319,15 +322,18 @@ 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));
+    // 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) {
@@ -364,6 +370,10 @@ class GuestRun {
     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);
   }
 
@@ -434,13 +444,20 @@ 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;
   }
 
   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; }
@@ -451,7 +468,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;
@@ -480,7 +497,7 @@ class GuestRun {
   start() {
     return new Promise((resolve) => {
       this.resolve = resolve;
-      this.timer = setTimeout(() => this.abort(), Math.min(this.timeoutMs, 2147483647));
+      this.timer = setTimeout(() => this.abort(true), Math.min(this.timeoutMs, 2147483647));
       this.memTimer = setInterval(() => {
         const now = rssBytes();
 

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");
+}