pi-supernova 0.7.0 → 0.8.0

package/README.md

@@ -14,6 +14,19 @@ transactional file operations, batching, bounded results and the grouped nova UI
 
 ## Unreleased
 
+- **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.
+- **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.
@@ -162,6 +175,13 @@ lines. Structural warnings and source windows are not substitutes for tests.
 
 ### Safe read-modify-write
 
+Path-only `read(path)` requires at most **160 lines and 8192 UTF-16 characters**.
+A short document can exceed the character limit. For larger files use
+`read(path,{offset:1,limit:80})` (one-based lines), `read(path,{about:"keywords"})`,
+or `read(path,{complete:true})`. The default raw-text read budget is **31,744
+characters**, derived from the configured call/return budgets, not an unlimited
+full-file buffer. Large JSONL needs a bounded parser through `bash({command,args})`.
+
 Plain reads are bounded views, not guaranteed full-file buffers. Use
 `read({path:"file.txt",complete:true})` when code needs the complete file; it
 throws rather than handing back partial text. Prefer `edit` for large-file
@@ -252,12 +272,21 @@ for short one-off operations. See [token measurements](https://github.com/Aditya
 }
 ~~~
 
-Use programs instead of top-level code/file. Supply 1--32 entries, each with
-code OR file and optional data. Top-level data supplies an optional default for
-each entry; explicit entry data replaces it entirely, including null, false, 0
-and empty strings. Every guest receives its own copy, not a shared mutable heap.
-The JSON-encoded array (or `{programs,data}` when defaults are supplied) must fit
-maxCodeChars. Common input counts once; result representations and output limits are unchanged.
+Supply 1--32 `programs` entries. Top-level `code` OR `file` supplies an optional
+source default; an entry's own `code` OR `file` replaces it. Without a shared
+source, every entry still requires its own. A shared file is reread when each
+entry runs, so earlier commits can create or update it.
+
+Top-level `data` supplies an optional input default. By default, explicit entry
+`data` replaces it entirely, including null, false, 0 and empty strings. With
+**`mergeData:true`**, both the default and every explicit entry input must be
+objects: own entry fields override default fields in a **shallow** merge. Nested
+objects are replaced, not recursively merged. Each guest receives its own copy;
+mutations cannot leak between guests or back into caller-owned inputs.
+
+The JSON-encoded array plus any shared code/file/data must fit `maxCodeChars`.
+Common source/input counts once, before expansion. Every entry is validated
+before any program runs. Result representations and output limits are unchanged.
 Entries run sequentially in fresh guests and commit separately. A successful
 entry can create the file executed by a later entry. No implicit retries,
 reordering, shared heap or nested batches are introduced.
@@ -278,6 +307,26 @@ This avoids repeating literal arguments, without a compression codec or result e
 Mutating `data` in one guest cannot affect the next. An entry with `data:null`
 receives null, not the shared object; there is no implicit object merge.
 
+For the same program with varying inputs, no temporary script or input file is
+needed. For example, audit both files with a common term:
+
+```json
+{
+  "code": "const text=await read({path:data.path,complete:true}); return {path:data.path,found:text.includes(data.term),text};",
+  "data": {"term":"TODO"},
+  "mergeData": true,
+  "programs": [
+    {"data":{"path":"src/a.js"}},
+    {"data":{"path":"src/b.js"}}
+  ]
+}
+```
+
+The complete source is still returned twice, once for each requested file; shared
+arguments do not authorize result deduplication or context rewriting. Existing
+programs that depend on whole-input replacement keep that behavior unless the
+caller explicitly requests `mergeData:true`.
+
 The batch stops on the first failed entry, cancellation/deadline, or exhausted
 output/log/image budget. Earlier successful commits remain; only the active
 program's uncommitted writes roll back. Admission errors throw before any program.
@@ -290,7 +339,7 @@ Set `parallel: true` with `programs` to run independent entries concurrently
 (up to 8 at once). Each still gets a fresh guest and its own commit; results stay
 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` is invalid on a lone `code` or `file` call.
+default. `parallel` and `mergeData` are invalid on a lone `code` or `file` call.
 
 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
@@ -306,7 +355,10 @@ settings, hide observations, or infer a plan on the agent's behalf.
 ### Large inputs and report outputs
 
 The default program limit is 48,000 UTF-16 code units (configurable via
-`maxCodeChars` and exposed in the tool schema). Split larger documents into
+`maxCodeChars` and exposed in the tool schema). The same cap applies separately
+to serialized JSON `data`, including quote/newline escaping and object keys.
+Oversized input fails before commands run and reports its actual serialized size.
+Split larger documents into
 separate invocations: first `write(path, firstChunk)`, then
 `write({path,content:nextChunk,append:true})`. Append uses the complete internal
 file buffer, never a bounded model-facing read; it retains conflict checks and
@@ -316,7 +368,9 @@ file and publish it only when complete. External write overrides reject append.
 
 Supernova is a bounded foreground executor, not a durable background-job manager.
 For long archive scans, use resumable chunks or a host background-job tool and write
-progress records under `.work`. Set the inner `bash` timeout shorter than the
+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
@@ -344,12 +398,21 @@ Inputs are capped at 16 MiB, including staged files. JSON reads require regular
 files and reject named pipes without waiting for a writer. The entire input must
 be valid JSON before any selection. Each selector is budgeted before allocating
 the next slice; sparse selector/path/edit arrays are rejected. Selected JSON must
-fit the ordinary read budget or the
-read throws; it is never returned as malformed/truncated JSON. Oversized unwindowed
+fit the ordinary read budget. Oversized selections return a routing object
+`{status:"too_large",path,keys}` (or `length` for an array), not the requested
+array/object: check `status` before calling `.map` or `.filter`, then select
+narrower fields or slices. The input-size cap still throws before projection;
+JSON is never returned malformed or silently truncated. Oversized unwindowed
 plain .json reads also fail with a projection hint. Explicit offset/limit or
 resolve:true still allow raw inspection, but line windows are not JSON documents.
 Do not combine json with complete, line windows, or source views. External read
 overrides reject JSON projection rather than silently ignoring the option.
+Uncaught read errors abort the program, including `return {a:await read(...),
+b:await read(...)}`; earlier successful values are not an implicit partial return.
+For optional sources, explicitly return `await Promise.allSettled(paths.map(path =>
+read(path)))`. This keeps successful text and per-path errors without weakening
+rollback for uncaught failures.
+
 Other read options, even false-valued flags, do not bypass a captured external
 read executor; its policy, transforms and failures remain authoritative.
 
@@ -386,9 +449,11 @@ recovery backups before retrying. Import-based mutations and shell side effects
 are outside the VFS counters; this is not a filesystem audit.
 
 `edit(async () => {...})` creates a nested filesystem checkpoint. It returns
-`{ok:true,committed:true,value}` on success or `{ok:false,committed:false,error}` on
-failure. Shell commands, overlapping/nested checkpoints, and concurrent commands
-outside the active callback are rejected. Await the checkpoint before proceeding.
+`{ok:true,committed:true,value}` on success. On failure it rolls back and rethrows
+the cause, so an ignored failed checkpoint cannot report program success. Use
+`try { await edit(async () => {...}); } catch (error) {...}` for deliberate recovery.
+Shell commands, overlapping/nested checkpoints, and concurrent commands outside
+the active callback are rejected. Await the checkpoint before proceeding.
 
 ## Context, caching and failure fidelity
 
@@ -396,9 +461,15 @@ outside the active callback are rejected. Await the checkpoint before proceeding
   is not proof the model still retains an earlier result after compaction.
 - Oversized text reads provide an exact next-line offset. A single line too large
   for the budget fails explicitly instead of pretending it was read completely.
+- Model attachments support PNG, JPEG, GIF and WebP. BMP and other unsupported
+  MIME types fail before attachment or commit, rather than causing a provider
+  HTTP 400 on the next request. Convert those sources to PNG first; Supernova
+  does not silently convert, resize or modify the original image.
 - Returned images remain image content blocks, including in arrays/objects. Images
   not returned by the program stay out of model output. Returned images are limited
-  to 16 attachments / 20 MiB; resize or return fewer when necessary.
+  to 16 attachments / 20 MiB. Overflow fails the program with the aggregate count
+  and byte size, returns no images, and rolls back pending writes. Resize or return
+  fewer images when necessary.
 - Dense multiline string arrays can render as verbatim source blocks instead of
   escaped string literals. Each block gives its array index and exact UTF-16 length;
   strings and result types are unchanged. This is output framing, not source
@@ -455,7 +526,10 @@ There is no dependency on or automatic routing to any consumer package.
 
 CodeMode executes trusted JavaScript in a terminable worker, **not a security
 sandbox**. The four adapters constrain writes/edits to the workspace and allow
-explicit external reads. JavaScript imports and shell commands still have process
+explicit external reads. Absolute temporary-directory paths outside the workspace
+are not write destinations: use a workspace path such as `.work/verification.log`,
+or a separately authorized external command. Errors identify the rejected path
+and workspace, including symlink escapes. JavaScript imports and shell commands still have process
 privileges. Do not run untrusted programs as though these adapters isolate them.
 
 Pi preflights the outer `supernova` call. Internal primitives do not emit ordinary

package/docs/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 ## Unreleased
 
+## [0.8.0] - 2026-09-19
+
+### Added
+
+- Program batches accept a top-level `code` OR `file` as a source default, so a
+  shared program is sent once instead of in every entry. Entries may still
+  override it, defaults count once against the 48,000-character admission cap,
+  and every entry keeps its own fresh guest and its own commit.
+- `mergeData: true` opts into a shallow object overlay of the top-level `data`
+  object and each entry's own object data (entry keys win; nested objects are
+  replaced, not merged). Whole-input replacement stays the default.
+
+### Changed
+
+- Standing reference now states the read limits and their recovery forms
+  (path-only `160 lines / 8192 characters`, `offset`/`about`/`complete:true`,
+  one-based windows, the complete-read budget) and the optional-read contract
+  (`Promise.allSettled` keeps successful siblings): +35/+38 definition tokens per
+  request versus 0.7.1, paid back many times over on repeated-source batches.
+- `bash()` inherits the program's `timeoutMs` instead of an independent 60s
+  default; explicit per-command limits still win.
+- Missing-file errors point at directory/source-question recovery and
+  `Promise.allSettled`.
+- Result packaging reuses decoded result branches and skips escaped rendering
+  when the complete raw framing is provably shorter; settled programs no longer
+  arm a 250 ms drain timer.
+
+### Fixed
+
+- Failed `edit(async () => {...})` checkpoints roll back and rethrow the original
+  cause instead of reporting success; an explicit `catch` still recovers.
+- Pi failure cards render as failures: the renderer reads the host's error flag
+  from render context, shows the original cause, prints `committed`/`rolledBack`
+  totals, marks writes whose persistence cannot be attributed as attempted, and
+  labels pure JavaScript execution instead of "complete".
+- Unsupported image formats (for example BMP) fail before model delivery or
+  commit with PNG-conversion guidance instead of attaching unusable data.
+- Oversized image sets report aggregate sizes instead of silently dropping
+  attachments; pending writes roll back.
+- Rust lifetimes and loop labels no longer produce false edit/write warnings;
+  genuinely broken strings, brackets and character literals still warn.
+- Markdown/MDX/RST/TXT edits skip declaration-reference searches for fenced code
+  and capital labels; usage evidence ignores declarations, generic calls and
+  prefix-only matches.
+- Missing argv data identifies the offending argument index; oversized `data`
+  reports its serialized size and a lossless chunked-write recovery.
+
+### Internals
+
+- 243 package tests, actual Pi and OMP host smoke, isolated Spark run, a
+  536-program stress pass, and both frozen token gates. `docs/TOKEN_COSTS.md`
+  records the traffic baselines, their limits and the measured 0.7.1 comparisons.
+
+## [0.7.1] - 2026-09-17
+
+### Fixed
+
+- Guest worker links on hosts without `module.registerHooks` (Bun, Node <22.15):
+  `node:module` is now a namespace import with runtime feature detection, so the
+  `register` fallback — and hosts with neither hook mechanism — no longer fail at
+  module-eval time. Previously every program failed before its first command with
+  "Export named 'registerHooks' not found", e.g. under OMP/Bun.
+
 ## [0.7.0] - 2026-09-17
 
 ### Internals

package/docs/TOKEN_COSTS.md

@@ -21,6 +21,154 @@ The benchmark uses js-tiktoken 1.0.21, pinned as a development dependency. It ru
 real Supernova programs in temporary workspaces without provider calls or downloads.
 The token regression gate also runs in the normal test suite.
 
+## Unreleased explicit batch reuse (2026-09-19)
+
+**79.82% / 79.92% less traffic on the shared-source/object-input workload, not a
+claim of 80% savings on every task.** Source and object defaults remove repeated
+arguments without compression, citations, result elision, context rewriting,
+reduced limits or changes to reasoning settings. Every program still executes in
+a fresh guest with its own commit. No model decision point is removed.
+
+The missing capability was combining common executable/input values with distinct
+per-entry inputs without repeating them or first saving helper files. Batches now
+accept top-level `code` OR `file` as a source default. `mergeData:true` explicitly
+opts into a shallow object overlay; the legacy whole-input replacement remains
+the default. Entries can override the source, and nested data objects are replaced,
+not recursively merged. Nothing is inferred or automatically deduplicated.
+
+### Frozen eligible workload
+
+The pre-feature working tree, including the earlier unreleased papercut fixes,
+ran 16 independent package-doc scaffolds. Each program wrote a LICENSE and README,
+reread both exact staged contents, and returned its complete receipts. The control
+repeated the same executable and literal license/introduction with a distinct
+directory per entry. Its encoded program array was **32,353 characters**, within
+the existing 48,000-character admission cap. This is not an inadmissible baseline.
+
+The candidate supplies the same complete code and common data once, plus those
+same per-entry directories. Both arms use **one tool invocation plus the final
+model handoff**, the same 16-program schedule, and all 32 final files. The baseline
+was captured before the implementation; neither program source nor data was padded
+or changed to meet the gate.
+
+| Tokenizer | Before | After | Reduction | Argument tokens before / after | Unchanged result tokens |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| o200k_base | 17,771 | 3,587 | **79.82%** | 7,685 / 643 | 1,039 |
+| cl100k_base | 17,595 | 3,533 | **79.92%** | 7,619 / 637 | 1,007 |
+
+Accounting is `2*definition + 2*arguments + complete result`. It includes both
+requests' standing definitions, generated arguments and their replay. The complete
+normalized output equals the pre-feature snapshot byte-for-byte, and the contents
+and complete inventory of all 32 files are checked. Only run counters and elapsed
+times are normalized, as in the existing benchmark. No hidden helper files appear.
+
+The new gate requires **at least 78% on both tokenizers**, not an argument-only
+percentage. Its fixture is
+[`batch-reuse-baseline.json`](https://github.com/AdityaVG13/pi-stack/blob/main/packages/pi-supernova/tests/efficiency/batch-reuse-baseline.json),
+with SHA-256 `589960c417006630872c16fae9ae5be4f5cdbdddbf86dda9fd9377651352055a`.
+
+This workload benefits from substantial repeated source and input. Unique-input,
+large-result, or already-file-backed jobs need not see that gain. Saving a reusable
+program/input file was already an alternative when extra workspace artifacts and
+setup were acceptable; this is not a claim of 80% over that different workflow.
+
+### Existing workload stays separate
+
+The original six-call schedule, its argument hash, all 13 logical operations,
+failures, decision boundaries and complete outputs remain unchanged. It already
+uses saved programs and does not exercise the new source defaults. Clearer shorter
+standing guidance offsets the new option's schema cost:
+
+| Tokenizer | At start of this pass | Now | Additional reduction | Versus original non-batched baseline |
+| --- | ---: | ---: | ---: | ---: |
+| o200k_base | 10,191 | 9,841 | **3.43%** | 65.02% |
+| cl100k_base | 10,067 | 9,724 | **3.41%** | 65.07% |
+
+The definition measures 631/626 tokens, versus 681/675 at the start. The original
+traffic gate was strengthened from 40% to 65%, without changing its baseline. An
+initial shorter guidance draft failed the existing recovery/surface checks; the
+copyable offset recovery and explicit selector/view guidance were restored rather
+than removing those requirements. There is no claim of 70--80% on this workload.
+
+### Verification and boundaries
+
+New source/overlay regressions and the reuse gate failed before implementation.
+The strengthened existing traffic gate also failed first. Current verification:
+239 package tests, both tokenizers' gates, lint, actual Pi argument validation and
+TUI smoke, actual network-denied OMP execution, and 71 targeted tests on an isolated
+Spark copy under Node v24.16.0. The actual-host probes exercise shared source,
+object overlays and independent guest copies.
+
+The existing stress runner passed 33,024 independent reads, 20 commits/140 conflicts,
+cancellation, complete-source fidelity and program batches. On Apple M5 Max,
+Node v26.7.0, the 300-sample, eight-file check measured pristine-warm median/p95
+1.645/2.390 ms versus unbatched-cold p95 13.848 ms; its existing acceptance check
+passed. This is a runtime smoke measurement, **not a new end-to-end speedup claim**.
+
+Complete-output and file equality prove the tested contracts, not unchanged
+live-model quality. There was no provider/model A/B evaluation, no reasoning-budget
+change, and no compression feature enabled. Deployment, session restart and
+publication are separate; installed OMP packages were not changed by this pass.
+
+## Unreleased optimization pass (2026-09-19)
+
+Measured against the working tree immediately before this pass, **including the
+unreleased papercut fixes**, not against a published release or the older baselines
+below. Machine: Apple M5 Max, 18 CPUs, 48 GiB RAM, macOS arm64, Node v26.7.0.
+
+| Measurement | Before | After | Reduction |
+| --- | ---: | ---: | ---: |
+| Definition tokens, o200k_base | 699 | 658 | 5.87% |
+| Definition tokens, cl100k_base | 691 | 651 | 5.79% |
+| Fixed six-call traffic, o200k_base | 10,317 | 10,030 | 2.78% |
+| Fixed six-call traffic, cl100k_base | 10,179 | 9,899 | 2.75% |
+| 200-row report packaging, median | 0.1665 ms | 0.1314 ms | 21.09% |
+| Nested source packaging, median | 0.0366 ms | 0.0240 ms | 34.53% |
+
+A subsequent Cortex papercut follow-up adds explicit data-limit, workspace-write,
+and inherited-timeout guidance. That later definition measures 674/667 tokens
+(o200k_base/cl100k_base), with fixed-workload totals of 10,142/10,011. The table
+above records the optimization checkpoint, before that additional guidance.
+
+The Mac/Spark recheck adds optional-read recovery and removes the unsupported BMP
+attachment advertisement. The resulting definition is 681/675 tokens, with fixed
+traffic totals of 10,191/10,067. Both frozen-workload gates still pass. Verification
+now includes 235 Mac package tests, 51 focused tests on an isolated Spark source
+copy (Node v24.16.0), and actual Pi/OMP smoke on Mac. Installed OMP packages were
+not updated by either follow-up.
+
+Token savings come only from shorter standing guidance. Arguments, decision
+boundaries and complete logical result text remain unchanged. No compression,
+elision, lower output limits, or history rewriting was introduced or enabled.
+
+Packaging now copies only changed branches and skips an escaped-source rendering
+when the existing complete raw rendering is provably shorter. The benchmark runs
+10,000 measured iterations per payload after warmup. Complete packaged-output
+SHA-256 hashes match before/after, including typed values, emitted text, images,
+logs and truncation flags. Local acceptance: identical hashes and at least 10%
+lower median packaging time for both fixtures; this is not a timing-sensitive CI
+gate or an end-to-end agent speed claim.
+
+Successful runs no longer leave a 250 ms drain timer alive; early completion of
+pending calls clears its fallback timer. A cold child-process probe exited at
+267 ms before versus 17 ms after, while result delivery itself remained about
+17 ms in both. Cancellation and the 250 ms bound on stuck calls remain tested.
+The 300-sample, eight-file benchmark measured prewarmed median/p95 of
+1.904/2.743 ms before and 1.765/2.530 ms after. These filesystem timings are noisy;
+no generalized I/O speedup is claimed, and prewarming/model latency is excluded.
+
+Reproduce the local latency and stress checks:
+
+~~~sh
+SUPERNOVA_MEASURE_SAMPLES=300 npm run measure --prefix packages/pi-supernova
+node packages/pi-supernova/tests/efficiency/stress.mjs
+~~~
+
+Verification: 229 package tests, both tokenizers' existing frozen-workload gates,
+lint, actual Pi loader/TUI and OMP execution smoke tests, plus the stress runner
+(33,024 independent reads, write contention, cancellation and source fidelity).
+No version bump, installation update, commit or publication is part of this pass.
+
 ## Workload
 
 The baseline is a frozen, non-batched implementation snapshot with program-file
@@ -72,12 +220,12 @@ text contributes to totals through later history, not as a second charge.
 
 Observed for 0.6.0 on 2026-09-15, on an Apple M5 Max running macOS and Node v26.7.0.
 
-| Tokenizer | Non-batched baseline | Batched baseline (d444eb7) | Current | Further reduction | Total reduction |
+| Tokenizer | Non-batched baseline | Batched baseline (d444eb7) | 0.6.0 | Further reduction | Total reduction |
 | --- | ---: | ---: | ---: | ---: | ---: |
 | o200k_base | 28,130 | 18,535 | 9,843 | **46.90%** | **65.01%** |
 | cl100k_base | 27,841 | 18,310 | 9,726 | **46.88%** | **65.07%** |
 
-The gate requires at least 40% reduction on **each tokenizer for the complete
+The gate now requires at least 65% reduction on **each tokenizer for the complete
 workload**, not for every scenario individually. Token counts and reductions are
 computed from the recorded baseline and fresh execution results, not constants
 returned by the runtime. A second gate requires another 19% against the measured
@@ -86,7 +234,7 @@ as the original workload: removing a decision boundary cannot satisfy this gate.
 
 ### Definition and result accounting
 
-The current serialized definition is 602 tokens with o200k_base and 595 with
+The 0.6.0 serialized definition was 602 tokens with o200k_base and 595 with
 cl100k_base, versus 908 and 901 in the frozen non-batched baseline. It retains
 command signatures, complete-read and JSON limits, array-read failure rules,
 transaction boundaries, batch defaults and edit/view guidance on every request.

package/index.js

@@ -212,6 +212,7 @@ export function registerCodeMode(pi) {
 
   function rejectLoneParallel(params) {
     if (params?.parallel !== undefined) throw new Error("parallel applies to the programs array; no commands ran");
+    if (params?.mergeData !== undefined) throw new Error("mergeData applies to the programs array; no commands ran");
   }
 
   function bindRunSignal(signal) {
@@ -224,8 +225,8 @@ export function registerCodeMode(pi) {
     return { runController, abortRun };
   }
 
-  function openRunBridge(ctx, runCwd, budget, runController) {
-    const runBridge = bridge.fork({ getCwd: () => runCwd, budget });
+  function openRunBridge(ctx, runCwd, budget, runController, timeoutMs) {
+    const runBridge = bridge.fork({ getCwd: () => runCwd, budget, timeoutMs });
     runBridge.bindCallContext(ctx, runController.signal);
     runBridge.resetCallBudget();
 
@@ -332,6 +333,7 @@ export function registerCodeMode(pi) {
         data: Type.Optional(Type.Unknown()),
       }, {additionalProperties:false}), {minItems:1,maxItems:32})),
       parallel: Type.Optional(Type.Boolean()),
+      mergeData: Type.Optional(Type.Boolean()),
     }),
     // One self-owned result frame is shared by Pi and OMP; renderCall stays empty
     // so separate call/result slots cannot duplicate the lifecycle card.
@@ -345,7 +347,7 @@ export function registerCodeMode(pi) {
       cancelWarmTimer();
       const runCwd = isString(ctx?.cwd) && ctx.cwd ? ctx.cwd : cwd;
       const { runController, abortRun } = bindRunSignal(signal);
-      const runBridge = openRunBridge(ctx, runCwd, budget, runController);
+      const runBridge = openRunBridge(ctx, runCwd, budget, runController, params?.timeoutMs);
       const call = ++programSeq;
       runBridge.ledger.beginProgram(call);
       const emitProgress = progressEmitter(onUpdate);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-supernova",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "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

@@ -43,7 +43,7 @@ export function createBash(ctx) {
           cwd: targetCwd,
           env: hooks.commandEnv(),
           commandLabel: literal ? command : undefined,
-          timeoutMs: params?.timeoutMs,
+          timeoutMs: params?.timeoutMs === undefined ? config.timeoutMs : params.timeoutMs,
           signal,
           maxOutputChars: config.maxCallResultChars,
         });

package/src/adapters/edit.js

@@ -131,6 +131,7 @@ export function createEdit(ctx) {
   }
 
   async function changedDeclarationRefs(cwd, target, original, updated, diff, signal) {
+    if (/\.(md|mdx|rst|txt)$/i.test(target)) return "";
     const names = collectChangedNames(target, original, updated, diff);
 
     if (names.size === 0) return "";
@@ -143,7 +144,7 @@ export function createEdit(ctx) {
     } catch (error) {
       signal?.throwIfAborted();
 
-      return "references unavailable: " + error.message;
+      return "references unavailable: " + String(error.message).slice(0, 512);
     }
   }
 

package/src/adapters/errors.js

@@ -25,7 +25,7 @@ export function imageTooLarge(rel, size) {
 }
 
 export function missingFile(targetPath) {
-  const error = new Error("no such file: " + targetPath + " (locate it with read using a directory path or source question)");
+  const error = new Error("no such file: " + targetPath + " (locate it with read using a directory path or source question; use Promise.allSettled for optional reads to retain successful siblings)");
   error.code = "ENOENT";
   return error;
 }

package/src/adapters/read.js

@@ -1,6 +1,6 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { isString, isNumber } from "../shared/decode.js";
+import { isString, isNumber, assertModelImageMime } from "../shared/decode.js";
 import { extractStructuralSurface } from "../context/surface.js";
 import { pickSpan } from "../context/spans.js";
 import { executeSnap, tokenizeQuery, stem } from "../context/snap.js";
@@ -646,7 +646,8 @@ export function createRead(ctx) {
     const lines = contentLineInfo(loaded.text).count;
 
     if (n > RAW_SOURCE_CHARS || lines > RAW_SOURCE_LINES) {
-      throw new Error("raw read of " + rel + " is " + lines + " lines; use about, offset/limit, or complete:true");
+      const p = JSON.stringify(rel);
+      throw new Error(`raw read of ${rel} is ${lines} lines / ${n} characters; path-only limit is ${RAW_SOURCE_LINES} lines / ${RAW_SOURCE_CHARS} characters. Use read(${p}, {offset:1, limit:80}) for a window, read(${p}, {about:"keywords"}) for matches, or read(${p}, {complete:true}) for the whole file within the read budget`);
     }
 
     return null;
@@ -656,6 +657,7 @@ export function createRead(ctx) {
     const mime = IMAGE_MIME[path.extname(targetPath).toLowerCase()];
 
     if (!mime) return null;
+    assertModelImageMime(mime);
     const bytes = await readImage(rel, targetPath, mime, signal);
 
     if (bytes.length > IMAGE_MAX_BYTES) throw imageTooLarge(rel, bytes.length);
@@ -684,7 +686,7 @@ export function createRead(ctx) {
 
   function assertComplete(rel, sliced, loaded, budget, params) {
     if (params.complete === true && (sliced !== loaded.text || sliced.length > budget || (params.resolve && !jsonFits(sliced, budget)))) {
-      throw new Error(`incomplete read of ${rel}: complete:true requires the entire file within the read budget; use json:".field" for JSON reports, about for text selection, edit() for replacements, or reconstruct resolve:true source windows`);
+      throw new Error(`incomplete read of ${rel}: complete:true requires the entire file within the read budget (${budget} characters). Use read(${JSON.stringify(rel)}, {offset:1, limit:80}) for a window, json:".field" for JSON reports, edit() for replacements, or bash({command,args}) with a bounded parser for large text/JSONL files`);
     }
   }
 

package/src/bridge/host-bridge.js

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

package/src/context/evidence.js

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

package/src/contract/bash.js

@@ -11,7 +11,12 @@ function normalizeArgv(args) {
   if (args.args === undefined) return;
   if (!isString(args.command) || !Array.isArray(args.args)) throw new Error(ARGV_ERROR);
 
-  for (let i = 0; i < args.args.length; i++) if (!isString(args.args[i])) throw new Error(ARGV_ERROR);
+  for (let i = 0; i < args.args.length; i++) {
+    if (!isString(args.args[i])) {
+      const type = args.args[i] === undefined ? "undefined" : "not a string";
+      throw new Error(`${ARGV_ERROR}; args[${i}] is ${type}; check the supplied data fields and pass each argument as a string`);
+    }
+  }
   args.args = args.args.map(String);
 
   if (process.platform === "win32") {

package/src/fs/check.js

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

package/src/fs/vfs.js

@@ -91,7 +91,7 @@ function remapReadError(err, target) {
   if (err.code === "EISDIR") throw new Error("read path is a directory, not a file: " + target);
 
   if (err.code === "ENOENT") {
-    const missing = new Error("no such file: " + target + ' (locate it with read using a directory path or source question)');
+    const missing = new Error("no such file: " + target + ' (locate it with read using a directory path or source question; use Promise.allSettled for optional reads to retain successful siblings)');
     missing.code = "ENOENT";
     throw missing;
   }

package/src/fs/workspace.js

@@ -100,7 +100,7 @@ export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = f
   const trimmed = assertFilesystemPath(inputPath, opName);
   const resolvedCwd = getResolvedCwd(cwd);
   const target = path.resolve(resolvedCwd, trimmed);
-  assertInside(path.relative(resolvedCwd, target), `${opName} path escapes workspace: paths resolve relative to ${resolvedCwd}`);
+  assertInside(path.relative(resolvedCwd, target), `${opName} path escapes workspace: ${JSON.stringify(trimmed)} resolves to ${target}, outside ${resolvedCwd}. Use a workspace-relative path (for example artifacts/output.log); external destinations require a separately authorized command`);
 
   if (!allowRoot && target === resolvedCwd) {
     throw new Error(`${opName} path cannot be the workspace root directory`);
@@ -122,7 +122,7 @@ export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = f
     realNearest.set(target, probe);
   }
 
-  assertInside(path.relative(realRoot, probe), `${opName} path escapes workspace through symlink`);
+  assertInside(path.relative(realRoot, probe), `${opName} path escapes workspace through symlink: ${JSON.stringify(trimmed)} resolves through ${probe}, outside ${realRoot}. Use a workspace-relative path without an external symlink`);
 
   return target;
 }

package/src/output/bottleneck.js

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

package/src/output/format.js

@@ -1,4 +1,4 @@
-import { isString, isObject } from "../shared/decode.js";
+import { isString, isObject, mapChangedChildren } from "../shared/decode.js";
 
 function normalizeText(text) {
   return isString(text) ? text : String(text ?? "");
@@ -109,33 +109,41 @@ function formatRawStringArray(value) {
   return raw.length < escapedSize ? raw : null;
 }
 
-function shouldFrameRaw(input) {
-  return isString(input) && input.includes("\n") && !hasUnpairedSurrogate(input) && JSON.stringify(input).length - input.length > 64;
+function rawStringSize(input) {
+  if (!isString(input) || !input.includes("\n") || hasUnpairedSurrogate(input)) return 0;
+  const size = JSON.stringify(input).length;
+
+  return size - input.length > 64 ? size : 0;
 }
 
-function visitRawStrings(input, strings) {
-  if (shouldFrameRaw(input)) {
-    const index = strings.push(input) - 1;
+function visitRawStrings(input, acc) {
+  const size = rawStringSize(input);
+
+  if (size) {
+    const index = acc.strings.push(input) - 1;
+    acc.escapedChars += size;
 
     return { [RAW_TEXT]: "raw[" + index + "]" };
   }
 
-  if (Array.isArray(input)) return input.map(child => visitRawStrings(child, strings));
-
-  if (isObject(input)) return Object.fromEntries(Object.entries(input).map(([key, child]) => [key, visitRawStrings(child, strings)]));
-
-  return input;
+  return mapChangedChildren(input, visitRawStrings, acc);
 }
 
-function framedReturn(value, escaped) {
-  const strings = [];
-  const referencedValue = visitRawStrings(value, strings);
+function framedReturn(value) {
+  const acc = { strings: [], escapedChars: 0 };
+  const referencedValue = visitRawStrings(value, acc);
+  const { strings } = acc;
 
-  if (!strings.length) return escaped;
+  if (!strings.length) return formatValue(value);
   // Keep every key, value, duplicate string and byte. References are unquoted
   // expressions, so literal "raw[0]" values and header-like source cannot collide.
   const framed = formatValue(referencedValue) + "\nraw strings[" + strings.length + "]\n" + strings.map((text, i) => "raw[" + i + "] " + text.length + " UTF-16 units\n" + text + "\n").join("");
 
+  // The ordinary rendering contains at least these complete escaped literals.
+  // If framing beats even that lower bound, do not build the discarded rendering.
+  if (framed.length < acc.escapedChars) return framed;
+  const escaped = formatValue(value);
+
   return framed.length < escaped.length ? framed : escaped;
 }
 
@@ -146,7 +154,7 @@ export function formatReturn(value) {
 
   if (rawArray !== null) return rawArray;
 
-  return framedReturn(value, formatValue(value));
+  return framedReturn(value);
 }
 
 const RAW_TEXT = Symbol("raw text reference");

package/src/runtime/guest-worker.js

@@ -1,6 +1,6 @@
 import { parentPort } from "node:worker_threads";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { register, registerHooks } from "node:module";
+import * as nodeModule from "node:module";
 import { isString, isObject, isFunction, toPlain, looksLikePath } from "../shared/decode.js";
 import { truncateChars } from "../output/format.js";
 import { gatherReadArgs, normalizeRead, decodeReadValue, assertReadPaths } from "../contract/read.js";
@@ -8,6 +8,8 @@ import { classifyEdit } from "../contract/edit.js";
 import { normalizeBash } from "../contract/bash.js";
 import { guestImportMessage, isDeniedGuestImport } from "./guest-deny-imports.js";
 
+const { register, registerHooks } = nodeModule;
+
 if (isFunction(registerHooks)) {
   registerHooks({
     resolve(specifier, context, nextResolve) {
@@ -20,8 +22,13 @@ if (isFunction(registerHooks)) {
       return nextResolve(specifier, context);
     },
   });
-} else {
-  register("./guest-deny-imports.js", import.meta.url);
+} else if (isFunction(register)) {
+  try {
+    register("./guest-deny-imports.js", import.meta.url);
+  } catch {
+    // Hosts whose module.register cannot run loader hooks lose the deny list;
+    // the guest remains trusted code, not a sandbox boundary.
+  }
 }
 
 // Guest programs run here, off the host thread. The host can terminate() this
@@ -235,7 +242,7 @@ async function runSpeculation(fn, token, checkpointScope, drainReads, enqueueHos
 
     if (began) await enqueueHost(() => rpc("speculateRollback", []));
 
-    return { ok: false, committed: false, error: err instanceof Error ? err.message : String(err) };
+    throw err;
   }
 }
 

package/src/runtime/program-batch.js

@@ -28,42 +28,56 @@ export function programBatchText(results, total, stopped = "", failed = 0) {
     }).join("");
 }
 
-function assertProgramEntry(p) {
+function assertProgramEntry(p, defaults = {}) {
+  const source = p?.code === undefined && p?.file === undefined ? defaults : p;
+
   if (!isObject(p) || Array.isArray(p) || Object.keys(p).some(key => !["code","file","data"].includes(key)) ||
-      ((p.code === undefined) === (p.file === undefined)) || !isString(p.code ?? p.file) || !(p.code ?? p.file).trim()) {
-    throw new Error("each program requires code OR file, with optional data; no nested batches or per-entry timeouts; no programs ran");
+      ((source.code === undefined) === (source.file === undefined)) || !isString(source.code ?? source.file) || !(source.code ?? source.file).trim()) {
+    throw new Error("each program requires code OR file (own or shared), with optional data; no nested batches or per-entry timeouts; no programs ran");
   }
 }
 
-function encodeBatchPayload(params) {
-  const hasDefault = params.data !== undefined;
-  let encoded;
+const objectData = value => isObject(value) && !Array.isArray(value);
 
-  try { encoded = JSON.stringify(hasDefault ? {programs:params.programs,data:params.data} : params.programs); } catch { throw new Error("programs and data must be JSON-serializable; no programs ran"); }
+function applyBatchDefaults(parsed, mergeData) {
+  if (mergeData && !objectData(parsed.data)) throw new Error("mergeData requires top-level object data; no programs ran");
+  const source = parsed.code !== undefined ? {code:parsed.code} : parsed.file !== undefined ? {file:parsed.file} : {};
 
-  return { hasDefault, encoded };
-}
+  return parsed.programs.map(program => {
+    assertProgramEntry(program, source);
+    const entry = program.code === undefined && program.file === undefined ? {...source,...program} : program;
 
-function applyDefaultData(parsed, hasDefault) {
-  if (!hasDefault) return parsed;
-  if (!Object.hasOwn(parsed,"data")) throw new Error("data must be JSON-serializable; no programs ran");
+    if (mergeData) {
+      if (program.data !== undefined && !objectData(program.data)) throw new Error("mergeData requires object data in every explicit entry; no programs ran");
+      // Shallow own-property overlay, including literal __proto__ keys. The
+      // runtime snapshots data again per guest; no mutable heap is shared.
+      entry.data = {...parsed.data,...program.data};
+    } else if (program.data === undefined && Object.hasOwn(parsed,"data")) entry.data = parsed.data;
 
-  // The runtime snapshots data separately for each fresh guest. An explicit
-  // entry replaces the default wholesale; falsy values are not missing values.
-  return parsed.programs.map(program => program.data === undefined ? {...program,data:parsed.data} : program);
+    return entry;
+  });
 }
 
 function parseBatchPayload(params, config) {
-  if (["code","file"].some(key => params[key] !== undefined)) throw new Error("programs cannot combine with top-level code or file; no programs ran");
-
   if (!Array.isArray(params.programs) || !params.programs.length || params.programs.length > 32) throw new Error("programs requires 1..32 entries; no programs ran");
+  if (params.mergeData !== undefined && params.mergeData !== true && params.mergeData !== false) throw new Error("mergeData must be boolean; no programs ran");
+  const defaults = Object.fromEntries(["code","file","data"].filter(key => params[key] !== undefined).map(key => [key,params[key]]));
+
+  if (defaults.code !== undefined || defaults.file !== undefined) assertProgramEntry(defaults);
+  for (const p of params.programs) assertProgramEntry(p, defaults);
+  const hasDefaults = Object.keys(defaults).length > 0;
+  let encoded;
+
+  try { encoded = JSON.stringify(hasDefaults ? {programs:params.programs,...defaults} : params.programs); } catch { throw new Error("programs and defaults must be JSON-serializable; no programs ran"); }
 
-  for (const p of params.programs) assertProgramEntry(p);
-  const { hasDefault, encoded } = encodeBatchPayload(params);
+  if (encoded.length > (config.maxCodeChars ?? 48000)) throw new Error("programs JSON exceeds the code character budget (including shared code/file/data); no programs ran");
+  const parsed = hasDefaults ? JSON.parse(encoded) : {programs:JSON.parse(encoded)};
 
-  if (encoded.length > (config.maxCodeChars ?? 48000)) throw new Error("programs JSON exceeds the code character budget; no programs ran");
+  if (Object.hasOwn(defaults,"data") && !Object.hasOwn(parsed,"data")) throw new Error("data must be JSON-serializable; no programs ran");
 
-  return applyDefaultData(JSON.parse(encoded), hasDefault);
+  // Validate and expand every entry before executing any. Defaults count once
+  // against admission, not once for each independent guest receiving a copy.
+  return applyBatchDefaults(parsed, params.mergeData === true);
 }
 
 function batchTimeoutMs(params, config) {

package/src/runtime/reference.js

@@ -1,19 +1,15 @@
-// Standing tool description: sent on every request. One nova call, four commands inside.
-export const REFERENCE = `JavaScript async body or arrow with read, write, edit, bash. file:path runs that program file instead. Put Markdown/scripts/argv in data. Guest has no fs/import/require.
-
-read(path|paths, offset?, limit?) → raw text or text[]; read(directory) → entries[]
-read(imagePath) → image (PNG/JPEG/GIF/WebP/BMP)
-read({path,json:".field"}) → parsed JSON; .items[0:3], .items.length, quoted keys, or true; 16 MiB cap; no jq
-raw JSON or selections over budget return {status:"too_large",path,keys} (length for arrays); narrow with json:".field" or slices
-read("symbol or question") → same view as resolve:true
-read({query,resolve:true}) → {status,path,line,text,...}
-read(path,{about}) → matching windows; read({query,evidence:true}) → ranked evidence; read({path,outline:true}) → declarations
-write(path, text) → replace an unread file; write({path,content,append:true}) → append without a prior read. After read use edit; replace:true overrides.
-edit(path,oldText,newText) | edit({path,edits}) → numbered post-edit lines, checks, references
-edit(async () => {...}) → checkpoint: commit on success, rollback on throw
-bash(command,{cwd?,timeoutMs?}) → bounded output; nonzero throws
-bash({command,args}) → literal argv
-
-edit oldText is an exact substring of read(); a miss includes a numbered window. Found is a span, not the file. Check resolve:true status; edit(view,text) replaces that window; edit(view,old,new) is unique inside it. complete:true rejects partial files. Array reads reject failures. Edits stage until success; bash commits preceding writes. Batch known reads, edits, and tests in this program (Promise.all, or programs with parallel:true).
-programs:[{code|file,data?},...] sequential fresh guests, separate commits; top-level data defaults per entry. Stop on failure keeps earlier commits. parallel:true runs disjoint entries concurrently. Separate supernova calls only when the next step needs a model decision.
+// 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.
+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.
+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.
 `;

package/src/runtime/runtime.js

@@ -221,7 +221,7 @@ function admitData(data, cap) {
     const encoded = JSON.stringify(data);
 
     if (encoded === undefined) return { error: "data must be JSON-serializable" };
-    if (encoded.length > cap) return { error: "data exceeds " + cap + " characters; split literal inputs across invocations" };
+    if (encoded.length > cap) return { error: "data exceeds " + cap + " characters (serialized JSON: " + encoded.length + " UTF-16 characters); no commands ran. Split literal inputs across invocations; large text can use write({path,content,append:true}) chunks without omitting content" };
 
     return { data: JSON.parse(encoded) };
   } catch { return { error: "data must be JSON-serializable" }; }
@@ -346,7 +346,12 @@ class GuestRun {
 
   async drainPending(outcome) {
     if (this.pending.size || !outcome.ok) this.cancelHost();
-    await Promise.race([Promise.allSettled(this.pending), new Promise(resolve => setTimeout(resolve, 250))]);
+    if (!this.pending.size) return;
+    let timer;
+
+    try {
+      await Promise.race([Promise.allSettled(this.pending), new Promise(resolve => { timer = setTimeout(resolve, 250); })]);
+    } finally { clearTimeout(timer); }
     if (this.pending.size && outcome.ok) this.hostError ??= "program completed with a host call still running";
   }
 

package/src/shared/decode.js

@@ -19,6 +19,36 @@ export function looksLikePath(target) {
   );
 }
 
+/** Transform children without copying unchanged result trees. Never mutate the input. */
+export function mapChangedChildren(value, visit, context) {
+  const array = Array.isArray(value);
+
+  if (!array && !isObject(value)) return value;
+  let out = value;
+
+  for (const key of array ? value.keys() : Object.keys(value)) {
+    if (array && !(key in value)) continue;
+    const before = value[key];
+    const after = visit(before, context);
+
+    if (Object.is(before, after)) continue;
+    if (out === value) out = array ? value.slice() : { ...value };
+    // Define rather than assign: "__proto__" must remain an ordinary data key.
+    Object.defineProperty(out, key, { value: after, enumerable: true, writable: true, configurable: true });
+  }
+
+  return out;
+}
+
+const MODEL_IMAGE_MIMES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
+
+/** Reject unsupported attachments before they can poison the next model request. */
+export function assertModelImageMime(mimeType) {
+  if (!MODEL_IMAGE_MIMES.has(mimeType)) {
+    throw new Error("unsupported image attachment type " + mimeType + "; model images require PNG, JPEG, GIF, or WebP. Convert the image to PNG before reading/returning it; no image attached");
+  }
+}
+
 const MAX_DEPTH = 64;
 
 const MAX_TYPED_ARRAY = 4096;

package/src/ui/render.js

@@ -373,6 +373,8 @@ function formatTarget(op, budget) {
 function opMarker(theme, op, isPartial, isError) {
 	if (op.ok === false) return theme.fg("error", "×");
 
+	if (op.mutationAttempt) return theme.fg("warning", "·");
+
 	if (op.ok === true) return theme.fg("success", "✓");
 
 	if (isPartial) return theme.fg("dim", "·");
@@ -430,8 +432,9 @@ function formatOpRow(theme, op, width, isPartial, isError) {
 	const duration = theme.fg("dim", durationText.padStart(DURATION_COL));
 	const exit = appendExit(theme, op);
 	const counts = appendDiffCounts(theme, op);
-	const prefix = `${marker} ${tool} ${duration}  ` + exit.text + counts.text;
-	const used = 2 + toolText.length + 1 + DURATION_COL + 2 + exit.width + counts.width;
+	const outcome = op.mutationAttempt ? "attempted " : "";
+	const prefix = `${marker} ${tool} ${duration}  ` + exit.text + counts.text + theme.fg("warning", outcome);
+	const used = 2 + toolText.length + 1 + DURATION_COL + 2 + exit.width + counts.width + outcome.length;
 
 	return opRowSuffix(theme, op, prefix, Math.max(1, width - used));
 }
@@ -460,10 +463,22 @@ function appendOps(lines, theme, ops, maxOps, maxDiffLines, width, isPartial, is
 	if (ops.length > maxOps) lines.push(theme.fg("dim", `  … ${ops.length - maxOps} more calls`));
 }
 
-function appendError(lines, theme, payload, expanded, width) {
-	const error = "✗ " + (payload?.error ? cleanBlockText(payload.error) : "error");
+function appendError(lines, theme, payload, _expanded, width) {
+	const errors = [payload?.error || "error"];
+	for (const [i, program] of (payload?.programs ?? []).entries()) {
+		if (program.details?.ok === false) errors.push(`program ${i + 1}: ${program.details.error || resultTextContent(program)}`);
+	}
+	for (const error of errors) for (const line of resultLines("✗ " + cleanBlockText(error), width)) lines.push(theme.fg("error", line));
+}
 
-	for (const line of expanded ? resultLines(error, width) : error.split("\n")) lines.push(theme.fg("error", line));
+function appendMutations(lines, theme, payload, width) {
+	const m = payload?.mutations;
+	if (!m || !(m.committed || m.rolledBack || m.external || m.pendingCommits || m.recoveryFailed)) return;
+	const summary = `file versions: committed=${m.committed || 0} rolledBack=${m.rolledBack || 0}`
+		+ (m.external ? `; external calls attempted=${m.external}` : "")
+		+ (m.pendingCommits ? `; pendingCommits=${m.pendingCommits}` : "")
+		+ (m.recoveryFailed ? "; recovery failed: inspect files" : "");
+	for (const line of resultLines(summary, width)) lines.push(theme.fg(m.rolledBack || m.recoveryFailed ? "warning" : "dim", line));
 }
 
 function appendResult(lines, theme, payload, expanded, width) {
@@ -502,17 +517,22 @@ function appendOverflow(lines, theme, trace, maxOps, isPartial) {
 }
 
 function appendEmptyOps(lines, theme, ops, isError, isPartial) {
-	if (ops.length === 0 && !isError && !isPartial) lines.push(theme.fg("dim", "no adapter calls"));
+	if (ops.length === 0 && !isError && !isPartial) lines.push(theme.fg("dim", "JavaScript-only execution"));
 }
 
 function buildBodyLines(theme, width, { payload, context, expanded, isPartial, isError }) {
 	const trace = traceFor(payload, context);
 	const { maxOps, maxDiffLines } = bodyLimits(expanded, isPartial);
 	const ops = operationsFromTrace(visibleTrace(trace, maxOps, isPartial));
+	// Trace success records an operation, not persistence of every staged version.
+	// Mixed rollback/commit counts cannot safely be attributed to individual rows.
+	for (const op of ops) op.mutationAttempt = op.ok === true && ["write", "edit", "patch"].includes(op.tool)
+		&& (isPartial || isError || payload?.mutations?.rolledBack > 0 || payload?.mutations?.recoveryFailed);
 	const lines = [];
 	appendOps(lines, theme, ops, maxOps, maxDiffLines, width, isPartial, isError);
 	appendOverflow(lines, theme, trace, maxOps, isPartial);
-	appendEmptyOps(lines, theme, ops, isError, isPartial);
+	if (!isPartial) appendMutations(lines, theme, payload, width);
+	if (Array.isArray(payload?.trace)) appendEmptyOps(lines, theme, ops, isError, isPartial);
 	appendTail(lines, theme, payload, expanded, isError, width, ops.length === 0 && !isPartial);
 
 	return { lines, opCount: trace.length };
@@ -594,12 +614,14 @@ function syncState(context, payload) {
 	if (payload.wallMs != null && context.state.wallMs !== payload.wallMs) context.state.wallMs = payload.wallMs;
 }
 
-function errorPayload(result) {
-	return result?.isError ? { ok: false, error: result.content?.flatMap(block => block.type === "text" ? [block.text] : []).join("\n") } : undefined;
+function resultTextContent(result) {
+	return result?.content?.flatMap(block => block.type === "text" ? [block.text] : []).join("\n") || "";
 }
 
-function payloadFromResult(result) {
-	return result?.details ?? errorPayload(result);
+function payloadFromResult(result, hostError) {
+	const payload = result?.details;
+	if (hostError) return {...payload, ok:false, error:payload?.error || resultTextContent(result) || "tool execution failed"};
+	return payload ?? {result:resultTextContent(result)};
 }
 
 function bindResultCard(host, options, context) {
@@ -619,9 +641,11 @@ export function renderSupernovaResult(resultArg, optionsArg, themeArg, contextAr
 		themeArg,
 		contextArg,
 	);
-	const payload = payloadFromResult(result);
+	// Pi omits isError from result and supplies it through render context.
+	const hostError = result?.isError === true || context?.isError === true || options?.isError === true;
+	const payload = payloadFromResult(result, hostError);
 	syncState(context, payload);
-	const isError = result?.isError || payload?.ok === false;
+	const isError = hostError || payload?.ok === false;
 	const comp = bindResultCard(host, options, context);
 	comp.set(theme, { payload, context, args, expanded, isPartial, isError, host });