pi-supernova 0.3.0 → 0.3.2

package/README.md

@@ -109,6 +109,68 @@ options, not mandatory stages of source resolution. Ordinary calls also get:
 Distant edit regions have separate windows and continuation pointers for omitted
 lines. Structural warnings and source windows are not substitutes for tests.
 
+### Safe read-modify-write
+
+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
+replacements, or reconstruct exact `resolve:true` windows before writing.
+Writes reject Supernova truncation markers, including legacy host-result markers.
+For intentionally writing literal marker documentation only, opt in with
+`write({path,content,allowReadArtifacts:true})`. This is a data-loss guard, not
+full dataflow tracking or a security sandbox.
+
+Explicit read arrays reject missing/failed paths. For typed partial outcomes use
+`Promise.allSettled(paths.map(path => read(path)))`. Successful arrays remain arrays.
+For embedded source with backslash escapes, use `String.raw` template literals
+(and escape delimiter backticks), or JSON-quoted strings. Validate generated code.
+
+On hosts exposing `sessionManager.getArtifactsDir()`, bare `agent://<id>` and
+`artifact://<number>` read files from the calling session's artifact directory.
+They preserve ID casing and support offset/limit and structured continuation.
+These resources are read-only; ambiguous artifact IDs and escaping symlinks fail.
+This is not the full OMP URI language: cross-session search, nested path/query
+selectors and other schemes are not implemented. Hosts without an artifact
+directory report that limitation rather than treating the URI as a local path.
+
+For unstructured logs/text, `read(path,{about:"STT database"})` returns bounded,
+line-numbered matching windows, or explicitly reports no matching text. It is not
+a complete-file read. Write temporary investigation files under the workspace
+(e.g. `.work/probe.py`): ordinary `write`/`edit` paths cannot escape it, including
+absolute `/tmp` paths. Shell execution is a separate trusted boundary, not a sandbox.
+
+### 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
+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
+per-program rollback. Missing files are created. Multiple invocations are not
+one atomic transaction: for an all-or-nothing publication, assemble a new staging
+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
+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.
+
+Large returned objects are bounded previews, not retained artifacts. Select fields
+and array windows before returning, rather than parsing a truncated preview:
+
+```js
+const report = JSON.parse(await read({path:"report.json",complete:true}));
+return {verdict:report.verdict, values:report.values.slice(5000,5003)};
+```
+
+If the raw JSON exceeds the read budget, reconstruct exact source windows or run
+a bounded parser through `bash`. There is no implicit continuation handle for
+arbitrary guest objects. For embedded code, JSON-encode the source string once;
+do not nest shell, JavaScript, and Python quoting unless it is necessary.
+
 ## Execution and automatic batching
 
 Compatible independently started reads coalesce at the worker/host boundary.
@@ -161,6 +223,32 @@ Default limits are in `src/config/config.default.json`. Configuration loads from
 Text limits are character budgets, not tokenizer counts. `/supernova` reports
 programs and output characters without labelling characters as tokens.
 
+## Optional workspace change notifications
+
+Supernova works without another search package. On hosts exposing `pi.events`, it
+provides an advisory `workspace:changed` event for independent cache/index consumers:
+
+```js
+{ version: 1, cwd: "/absolute/workspace", paths: ["/absolute/workspace/file.js"] }
+```
+
+`cwd` identifies the calling workspace. `paths` contains absolute file paths after
+a successful disk flush; paths may contain filesystem aliases. The frozen event
+and path array contain no source text. Checkpoint merges, restored rollbacks, and
+read-only programs emit nothing. A shell boundary can flush paths before a later
+program failure, so notifications are not conditional on overall tool success.
+
+`paths: null` means the changed paths are unknown: shell or delegated mutation
+attempts emit this even on failure, as does an incomplete commit recovery. Consumers
+should invalidate conservatively, not interpret it as an empty change list or a
+guarantee that shell effects stayed inside `cwd`.
+
+Subscribe with `pi.events.on("workspace:changed", handler)`. Mark cached state dirty
+synchronously, then refresh when queried; asynchronous listeners are not awaited.
+Observer failures cannot roll back writes. This is an optional extension convention,
+not a built-in host standard, durable event log, or cross-process filesystem watcher.
+There is no dependency on or automatic routing to any consumer package.
+
 ## Security and host boundary
 
 CodeMode executes trusted JavaScript in a terminable worker, **not a security
@@ -182,6 +270,16 @@ cover batching fidelity, image/context retention, checkpoints, mutation ordering
 external symlinks, deadlines, worker isolation and execution-context environment.
 The former deleted suite has not been silently reinstated.
 
+Test user-visible contracts through registered programs: exact source, on-disk
+results, failure/rollback, isolation, bounded output, and usable host rendering.
+Inject filesystem faults only to exercise real failure paths; do not prescribe
+private helper layouts, staging filenames, or syscall counts. New regressions must
+fail before the fix; for existing behavior, verify that a named deliberate defect
+makes the intended test fail before accepting it. Keep the original 12 acceptance
+tests unchanged. Cost gates cover avoidable search processes, per-read budgets and
+progress flooding; latency claims belong in the explicit measurement lane, not
+arbitrary wall-clock assertions.
+
 ```bash
 npm test --prefix packages/pi-supernova
 npm run lint:supernova

package/docs/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.3.2] - 2026-09-07
+
+- Focus `read(path,{about})` on matching line windows in unstructured logs/text instead of returning a truncated unrelated prefix; report no matches explicitly.
+- Create recursive source watchers as non-persistent so Linux/Node 24 hosts can exit naturally; add a child-process regression verified on Spark.
+- Expose the configured program-length cap in the schema and add transactional `write({path,content,append:true})` for large-document chunks without bounded read-back. Document typed partial reads, embedded-source quoting and bounded report projections.
+- Emit optional, producer-independent `workspace:changed` v1 notifications at disk commit boundaries, with conservative unknown-path invalidation for external mutations. Staging and restored rollbacks emit nothing; observer failures cannot break writes.
+
+- Refuse writes containing truncated-read payload markers; add `read({path,complete:true})` for fail-closed full-file reads. Preserve ordinary bounded views and exact source continuation.
+- Explicit read arrays now reject failed paths; use `Promise.allSettled` over independent reads for typed partial results.
+- Resolve bare `agent://` and `artifact://` IDs from the calling host session’s artifact directory, with read-only scope, ambiguity checks and bounded pagination. This does not implement the full host URI language.
+- Document embedded-source escaping and add regressions for the reported read/write corruption, batch errors and session-resource isolation, including actual OMP execution.
+
+## [0.3.1] - 2026-09-06
+
+### Fixed
+
+- Preserve post-edit coordinates for patch deletions, including zero-length new ranges. After an earlier hunk inserts lines, the edit result now opens the actual deletion region rather than an unrelated earlier source window. File mutation semantics are unchanged.
+
+### Tests
+
+- Add a focused shifted-deletion regression and an opt-in stress runner that can target an isolated npm installation. Cover concurrent programs, 129-read batches, contended writes, cancellation after confirmed staging, immutable progress frames, source fidelity and cold lookup across 5,000 files.
+
 ## [0.3.0] - 2026-09-05
 
 ### Source operations

package/index.js

@@ -90,14 +90,15 @@ read("symbol or question") → locate and open source in one call, without an in
 read({query, resolve:true}) → {status,path,line,lines,text,complete,nextOffset?} for a direct resolve→edit handoff
 read(path, {about: question}) → relevant file bodies, or source selection inside a directory
 read({query, evidence:true}) → ranked evidence; read({path, outline:true}) → structural declarations
-write(path, text) → write a file
+write(path, text) → write a file; write({path,content,append:true}) appends a chunk without a bounded read
 edit(path, oldText, newText) → post-edit lines, checks, and references
 edit(async () => {...}) → filesystem checkpoint: commit on success, rollback on throw; no shell commands, nesting, or concurrent outside commands
 bash(command, {cwd?, timeoutMs?}) → bounded output; throws on non-zero exit
 bash({command, args:[...]}) → literal argv without shell expansion of arguments
 
 Only found selects and opens a file. Uncertain reads return ambiguous, not_found, or incomplete with no selected path. Use resolve:true for structured status checks; narrow the directory with path+about when uncertain.
-Object arguments also work: read({path, offset?, limit?, about?, outline?, evidence?, resolve?}), edit({path, edits:[{oldText,newText}]}), edit({path,patch}), write({path,content}), bash({command,timeoutMs?}).
+For read-modify-write, use read({path,complete:true}); it rejects partial output. Prefer edit for large files. Array reads reject failures; use Promise.allSettled for per-path outcomes.
+Object arguments also work: read({path, offset?, limit?, about?, outline?, evidence?, resolve?, complete?}), edit({path, edits:[{oldText,newText}]}), edit({path,patch}), write({path,content}), bash({command,timeoutMs?}).
 Independent read starts batch automatically. Mutations preserve submission order. Plain reads remain self-contained; oversized reads provide continuation offsets. Return only what the model needs. console.log is captured.`;
 
 export default function piSupernova(pi) {
@@ -152,7 +153,7 @@ export function registerCodeMode(pi) {
       "Use read, write, edit, and bash inside supernova. Start with read(question), or read(directory, {about: question}) for scoped source selection. A source question already opens the selected file; do not issue a redundant read. Use read({query,resolve:true}) and check status before editing its path. Explicit about/outline/evidence reads remain available when needed. Return a compact value.",
     ],
     parameters: Type.Object({
-      code: Type.String({ description: "JavaScript program: async body or arrow function." }),
+      code: Type.String({ maxLength: config.maxCodeChars ?? 48000, description: `JavaScript program: async body or arrow function. Maximum ${config.maxCodeChars ?? 48000} UTF-16 code units; split large writes into write({path,content,append:true}) chunks.` }),
       timeoutMs: Type.Optional(Type.Integer({ minimum: 1000, description: "Hard timeout in ms." })),
     }, { required: ["code"] }),
     // One self-owned result frame is shared by Pi and OMP; renderCall stays empty

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-supernova",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "One CodeMode invocation for Pi and OMP, with four guest commands, automatic read batching and source context.",
   "type": "module",
   "author": "AdityaVG13",

package/src/bridge/catalog.js

@@ -13,11 +13,12 @@ const NATIVE_TOOL_DEFINITIONS = [
       about: { type: "string", description: "Question or symbol: expand file bodies, or locate and open source inside a directory" },
       query: { type: "string", description: "Source question; optional path scopes the search directory" },
       resolve: { type: "boolean", description: "Return structured source/status for a direct resolve-to-edit handoff" },
+      complete: { type: "boolean", description: "Fail unless the entire requested file fits without clipping" },
     } },
   },
   {
     name: "write", description: "Write UTF-8 content to a workspace file.",
-    parameters: { type: "object", properties: { path: { type: "string" }, content: { type: "string" } }, required: ["path", "content"] },
+    parameters: { type: "object", properties: { path: { type: "string" }, content: { type: "string" }, allowReadArtifacts: { type: "boolean", description: "Explicit opt-in for intentionally writing literal truncation-marker text" } }, required: ["path", "content"] },
   },
   {
     name: "edit", description: "Apply unique text replacements to a workspace file; returns the post-edit lines, a structural check, and references to changed declarations.",

package/src/bridge/host-bridge.js

@@ -134,11 +134,11 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger, hooks) {
     return openSource(result, params, signal);
   }
 
-  async function openSource(result, params, signal) {
+  async function openSource(result, params, signal, resolvedPath) {
     const cwd = getCwd();
     if (result.status !== "found") return textResult(JSON.stringify(result), { isSnap: true });
     signal?.throwIfAborted();
-    const opened = await readFile(path.resolve(cwd, result.path), { ...params, about: undefined }, result.line);
+    const opened = await readFile(resolvedPath ?? path.resolve(cwd, result.path), { ...params, about: undefined }, result.line, result.path);
     const block = opened.content[0];
     if (block.type !== "text") throw new Error("source resolution requires a text file; read the image path directly");
     const { firstLine, lastLine, sourceChars, nextOffset, complete } = opened.details;
@@ -185,12 +185,49 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger, hooks) {
         }
       }));
       signal?.throwIfAborted();
-      return textResult("", { count: results.length, batch: true, independent: params._independent === true, items: results.map(r => r.text), itemErrors: results.map(r => r.error?.message ?? null), errors: results.filter(r => r.error).map(r => r.error) });
+      const response = textResult("", { count: results.length, batch: true, independent: params._independent === true, items: results.map(r => r.text), itemErrors: results.map(r => r.error?.message ?? null), errors: results.filter(r => r.error).map(r => r.error) });
+      response.isError = params._independent !== true && results.some(r => r.error);
+      return response;
     }
     return reads.schedule("read", () => readSingle(params, cwd, targetParam, signal), signal);
   }
 
+  async function resolveSessionResource(uri, signal) {
+    const match = /^(agent|artifact):\/\/([^/?#]+)$/i.exec(uri);
+    if (!match) throw new Error("session resource reads support bare agent://<id> and artifact://<number>; use offset/limit for pagination");
+    const kind = match[1].toLowerCase();
+    const id = decodeURIComponent(match[2]);
+    if (!id || id === "." || id === ".." || (/[/\\]/u.test(id) || Array.from(id).some(char => char.charCodeAt(0) < 32)) || (kind === "artifact" && !/^\d+$/.test(id))) throw new Error("invalid session resource ID");
+    const dir = hooks.artifactsDir?.();
+    if (!isString(dir) || !dir) throw new Error("this host session does not expose an artifacts directory for " + uri);
+    signal?.throwIfAborted();
+    const root = await fs.realpath(dir);
+    let file = id + ".md";
+    if (kind === "artifact") {
+      const matches = [];
+      let count = 0;
+      for await (const entry of await fs.opendir(root)) {
+        signal?.throwIfAborted();
+        if (++count > 4096) throw new Error("session artifact lookup exceeded its directory budget");
+        if (entry.name.startsWith(id + ".") && !entry.isDirectory()) matches.push(entry.name);
+      }
+      if (matches.length !== 1) throw new Error(matches.length ? "ambiguous session artifact: " + uri : "session artifact not found: " + uri);
+      file = matches[0];
+    }
+    const target = await fs.realpath(path.join(root, file));
+    if (!target.startsWith(root + path.sep)) throw new Error("session resource escapes its artifacts directory");
+    if (!(await fs.stat(target)).isFile()) throw new Error("session resource is not a file: " + uri);
+    signal?.throwIfAborted();
+    return target;
+  }
+
   async function readSingle(params, cwd, targetParam, signal) {
+    if (isString(targetParam) && /^(?:agent|artifact):\/\//i.test(targetParam)) {
+      const target = await resolveSessionResource(targetParam, signal);
+      return params.resolve
+        ? openSource({status:"found",path:targetParam,line:params.offset ?? 1}, params, signal, target)
+        : readFile(target, params, undefined, targetParam);
+    }
     if (isString(params?.query)) {
       const scope = targetParam && targetParam !== params.query ? resolveReadPath(cwd, targetParam) : cwd;
       return sourceRead(params.query, scope, signal, params);
@@ -208,9 +245,9 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger, hooks) {
   }
 
   /** Plain text, a line window, or (with `about`) a relevance-folded outline of the whole file. */
-  async function readFile(targetPath, params, sourceLine) {
+  async function readFile(targetPath, params, sourceLine, displayPath) {
     const cwd = getCwd();
-    const rel = relativeSlash(cwd, targetPath);
+    const rel = displayPath ?? relativeSlash(cwd, targetPath);
     const mime = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp", ".bmp": "image/bmp" }[path.extname(targetPath).toLowerCase()];
     if (mime) {
       if ((await fs.stat(targetPath)).size > 20 * 1024 * 1024) throw new Error("image exceeds 20 MiB; resize it before reading");
@@ -233,6 +270,9 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger, hooks) {
     const offset = params?.offset ?? (sourceLine && text.length > budget ? Math.max(1, sourceLine - 2) : 1);
     const firstLine = isNumber(offset) ? Math.max(1, Math.floor(offset)) : 1;
     const sliced = sliceLines(text, offset, params?.limit);
+    if (params.complete === true && (sliced !== text || sliced.length > budget || (params.resolve && JSON.stringify(sliced).length > budget))) {
+      throw new Error(`incomplete read of ${rel}: complete:true requires the entire file within the read budget; use edit() for replacements or reconstruct resolve:true source windows`);
+    }
     if (sliced.length > budget || (params.resolve && JSON.stringify(sliced).length > budget)) {
       let cap = budget - 160;
       if (params.resolve) {
@@ -397,11 +437,16 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger, hooks) {
       const target = await resolveWorkspacePath(cwd, params?.path, "write", false);
       if (signal?.aborted) throw new Error("aborted");
       if (!isString(params?.content)) throw new Error("write requires string content");
-      const content = params.content;
+      if (params.append !== undefined && params.append !== true && params.append !== false) throw new Error("write append must be a boolean");
+      let content = params.content;
+      if (params.allowReadArtifacts !== true && /\[read truncated;|…\[(?:host-result|output|value) truncated \d+ chars\]…/u.test(content)) {
+        throw new Error("refusing to write truncated read output; use edit() or reconstruct complete source windows. Set allowReadArtifacts:true only to intentionally write literal truncation-marker text");
+      }
       let prevText = "";
       try {
         prevText = await vfs.read(target, { preserveRead: true });
       } catch (error) { if (error.code !== "ENOENT") throw error; }
+      if (params.append === true) content = prevText + content;
       const { speculative } = await vfs.write(target, content);
       index.touch(relativeSlash(cwd, target));
       const diff = buildWriteDiff(target, prevText, content);
@@ -527,6 +572,7 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger, hooks) {
         vfs.invalidateCache();
         index.invalidate();
         clearPathCache();
+        hooks.workspaceChanged();
       }
       const { stdout, stderr } = res;
       let text = stdout && stderr ? stdout + (stdout.endsWith("\n") ? "" : "\n") + stderr : stdout || stderr;
@@ -596,7 +642,10 @@ function createNativeAdapters(getCwd, vfs, config, index, ledger, hooks) {
 export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedger }) {
   const index = registry?.index ?? new WorkspaceIndex((argv, opts) => runCommand(argv, opts));
   const ledger = runLedger ?? new SeenLedger({ window: config.seenWindow ?? 40 });
-  const vfs = new CausalVfs(() => index.invalidate(), target => resolveWorkspacePath(getCwd(), target, "commit", false, true));
+  const vfs = new CausalVfs(paths => {
+    index.invalidate();
+    notifyWorkspaceChanged(paths);
+  }, target => resolveWorkspacePath(getCwd(), target, "commit", false, true));
   const executors = registry?.executors ?? new Map();
   const definitions = registry?.definitions ?? new Map();
   const sharedRegistry = registry ?? { executors, definitions, index, callSeq: 0 };
@@ -611,6 +660,18 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
   let trace = [];
   let callListener = null;
   const scheduler = createNativeScheduler();
+  // Advisory host event, not a tool or a transaction participant. Consumers
+  // invalidate synchronously; failures must never affect committed bytes.
+  function notifyWorkspaceChanged(paths = null) {
+    if (!isFunction(pi?.events?.emit)) return;
+    const event = Object.freeze({
+      version: 1, cwd: path.resolve(getCwd()),
+      paths: paths === null ? null : Object.freeze([...new Set(paths)]),
+    });
+    try { pi.events.emit("workspace:changed", event)?.catch?.(() => {}); } catch {}
+  }
+  hooks.workspaceChanged = notifyWorkspaceChanged;
+  hooks.artifactsDir = () => activeCtx?.sessionManager?.getArtifactsDir?.();
   hooks.commandEnv = () => {
     const env = { ...process.env };
     const current = {
@@ -800,6 +861,7 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
       const delegated = hostTool(name);
       const exec = delegated ? delegated.execute.bind(delegated) : hostSession ? undefined : executors.get(name);
       if (exec) {
+        if (name === "write" && args?.append === true) throw new Error("append requires the Supernova-owned write adapter, not an external override");
         const fallbackDiff = await writeFallbackDiff(name, args);
         const mutating = isMutatingTool(name, config, args, definitions.get(name));
         if (mutating) await vfs.prepareExternalMutation(name);
@@ -812,7 +874,7 @@ export function createHostBridge({ pi, config, getCwd, registry, ledger: runLedg
           completeRecord(record, res, fallbackDiff);
           return res;
         } finally {
-          if (mutating) { vfs.invalidateCache(); index.invalidate(); clearPathCache(); }
+          if (mutating) { vfs.invalidateCache(); index.invalidate(); clearPathCache(); notifyWorkspaceChanged(); }
         }
       }
 

package/src/context/outline.js

@@ -54,6 +54,26 @@ function expandedBlock(span, raw, opts) {
   return out.join("\n");
 }
 
+function focusedText(raw, lower, stems, relPath, opts) {
+  const hits = lower.map((line, i) => ({i, score: stems.filter(s => line.includes(s)).length}))
+    .filter(hit => hit.score > 0).sort((a, b) => b.score - a.score || a.i - b.i);
+  const parts = [];
+  const covered = new Set();
+  let budget = opts.maxChars;
+  for (const {i} of hits) {
+    if (parts.length >= opts.maxExpanded) break;
+    if (covered.has(i)) continue;
+    const start = Math.max(0, i - 3), end = Math.min(raw.length, i + 4);
+    const block = raw.slice(start, end).map((line, j) => String(start + j + 1).padStart(5) + " " + line).join("\n");
+    if (block.length > budget) continue;
+    parts.push(block); budget -= block.length;
+    for (let j = start; j < end; j++) covered.add(j);
+  }
+  const status = parts.length ? "focused text windows (not a complete file)"
+    : hits.length ? "matching text exceeds view budget; first match at line " + (hits[0].i + 1) : "no matching text";
+  return {text: "// " + relPath + " · " + status + "; read(path, line, count) for raw source\n" + parts.join("\n---\n"), expanded: parts.length, declarations: 0};
+}
+
 /**
  * @param entry index entry (text + cached lines/surface)
  * @param about question or symbol; empty ⇒ pure skeleton (every body folded)
@@ -63,8 +83,8 @@ export function outlineFile(entry, relPath, about, options = {}) {
   const { raw, lower } = WorkspaceIndex.linesOf(entry);
   const lineCount = raw.length;
   const spans = WorkspaceIndex.spansOf(entry).map((s) => ({ ...s, signature: raw[s.start - 1].trim() }));
-  if (spans.length === 0) return null; // no structure: caller falls back to plain text
   const stems = [...new Set(tokenizeQuery(about || "").tokens.map(stem))];
+  if (spans.length === 0) return about ? focusedText(raw, lower, stems, relPath, opts) : null;
   const expanded = chooseExpanded(spans, lower, stems, raw, opts);
 
   const parts = [];

package/src/context/repo-index.js

@@ -102,7 +102,7 @@ export class WorkspaceIndex {
     let ok = false;
     try {
       let timer = null;
-      const watcher = fs.watch(root, { recursive: true }, () => {
+      const watcher = fs.watch(root, { recursive: true, persistent: false }, () => {
         if (timer) return;
         timer = setTimeout(() => {
           timer = null;

package/src/fs/diff.js

@@ -74,10 +74,11 @@ export function buildPatchDiff(filePath, patchText) {
   let inHunk = false;
 
   for (const patchLine of patchLines) {
-    const headerMatch = (/^@@\s+-(\d+)(?:,\d+)?\s+\+(\d+)/).exec(patchLine);
+    const headerMatch = (/^@@\s+-(\d+)(?:,(\d+))?\s+\+(\d+)(?:,(\d+))?/).exec(patchLine);
     if (headerMatch) {
-      oldLineNum = Number(headerMatch[1]);
-      newLineNum = Number(headerMatch[2]);
+      // A zero-length range names the line before the insertion/deletion point.
+      oldLineNum = Number(headerMatch[1]) + Number(headerMatch[2] === "0");
+      newLineNum = Number(headerMatch[3]) + Number(headerMatch[4] === "0");
       inHunk = true;
       continue;
     }
@@ -86,7 +87,7 @@ export function buildPatchDiff(filePath, patchText) {
     if (!kind) continue;
     if (kind === "remove") {
       removed += 1;
-      lines.push({ type: "remove", lineNum: oldLineNum, text: patchLine.slice(1) });
+      lines.push({ type: "remove", lineNum: oldLineNum, newLineNum, text: patchLine.slice(1) });
       oldLineNum += 1;
     } else if (kind === "add") {
       added += 1;

package/src/fs/vfs.js

@@ -157,7 +157,7 @@ export class CausalVfs {
         this.setCache(entry.logicalPath, entry.content);
         this.expected.delete(entry.logicalPath);
       }
-      if (staged.length) this.onNewFile?.();
+      if (staged.length) this.onNewFile?.(staged.map(entry => entry.target));
     } catch (error) {
       failed = true;
       const recoveryErrors = [];
@@ -173,6 +173,7 @@ export class CausalVfs {
         }
       }
       this.invalidateCache();
+      if (recoveryErrors.length) this.onNewFile?.(null);
       if (recoveryErrors.length) throw new AggregateError([error, ...recoveryErrors.map(message => new Error(message))], "commit failed: " + error.message + "; recovery failed: " + recoveryErrors.join("; "));
       throw error;
     } finally {

package/src/fs/workspace.js

@@ -60,6 +60,7 @@ export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = f
   if (inputPath == null || !isString(inputPath) || !inputPath.trim()) {
     throw new Error(`${opName} requires path`);
   }
+  if (/^(?:agent|artifact):\/\//i.test(inputPath.trim())) throw new Error(`${opName} requires a filesystem path; session resource URIs are read-only`);
   const resolvedCwd = getResolvedCwd(cwd);
   const target = path.resolve(resolvedCwd, inputPath.trim());
   assertInside(path.relative(resolvedCwd, target), `${opName} path escapes workspace: paths resolve relative to ${resolvedCwd}`);

package/src/runtime/guest-worker.js

@@ -49,6 +49,12 @@ function unwrapValue(res) {
   return res;
 }
 
+function unwrapRead(res, args) {
+  const value = unwrapValue(res);
+  if (args.complete === true && res?.truncated) throw new Error("incomplete read: complete:true refuses truncated host output");
+  return value;
+}
+
 function unwrapJsonValue(res) {
   const value = unwrapValue(res);
   try {
@@ -124,8 +130,8 @@ function buildGuestApi(available, batchRead, runId, nativeArgv) {
       const wave = pending.slice(start, start + 64);
       const args = { ...wave[0].args, path: wave.map(job => job.args.path), _independent: true };
       const run = wave.length === 1
-        ? nova.call("read", wave[0].args).then(res => ({ values: [unwrapValue(res)], errors: [] }))
-        : nova.call("read", args).then(res => { unwrapValue(res); return { values: res.items, errors: res.itemErrors ?? [] }; });
+        ? nova.call("read", wave[0].args).then(res => ({ values: [unwrapRead(res, wave[0].args)], errors: [] }))
+        : nova.call("read", args).then(res => { unwrapRead(res, args); return { values: res.items, errors: res.itemErrors ?? [] }; });
       void run.then(({ values, errors }) => {
         if (!Array.isArray(values) || values.length !== wave.length) throw new Error("invalid batch read response");
         for (let i = 0; i < wave.length; i++) {
@@ -143,6 +149,7 @@ function buildGuestApi(available, batchRead, runId, nativeArgv) {
   const read = async (p, a, b) => {
     assertScope();
     const args = readArgs(p, a, b);
+    if (args.complete === true && (args.outline || args.evidence || args.about)) throw new Error("complete:true requires a raw file read, not an outline or evidence view");
     const evidencePath = isObject(p) && !Array.isArray(p) ? p.path : args.about ? p : undefined;
     p = args.path;
     if (args.evidence) return unwrapJsonValue(await invoke("evidence", { ...args, path: evidencePath, query: args.about ?? args.query ?? p }));
@@ -150,18 +157,21 @@ function buildGuestApi(available, batchRead, runId, nativeArgv) {
     if (Array.isArray(p)) {
       if (p.length > 64) throw new Error("read accepts at most 64 paths per batch");
       if (p.some(item => !isString(item) || !item.trim())) throw new Error("read paths must be non-empty strings");
-      const readEach = () => Promise.all(p.map(async item => {
-        try { return await read({ ...args, path: item }); }
-        catch (error) { return `[read error: ${item}] ${error.message}`; }
-      }));
+      const readEach = () => Promise.all(p.map(item => read({ ...args, path: item })));
       if (!batchRead || args.resolve) return readEach();
       const res = await invoke("read", args);
-      unwrapValue(res);
+      const failed = res?.itemErrors?.findIndex(error => error != null) ?? -1;
+      if (failed >= 0) throw new Error(`read failed for ${p[failed]}: ${res.itemErrors[failed]}; use Promise.allSettled(paths.map(path => read(path))) for per-path outcomes`);
+      unwrapRead(res, args);
       if (Array.isArray(res?.items)) return res.items;
       // Captured host executor without batch support: fan out.
       return readEach();
     }
-    if (!batchRead) return args.resolve ? unwrapJsonValue(await invoke("read", args)) : unwrapValue(await invoke("read", args));
+    if (!batchRead) {
+      const res = await invoke("read", args);
+      unwrapRead(res, args);
+      return args.resolve ? unwrapJsonValue(res) : unwrapRead(res, args);
+    }
     const key = JSON.stringify({ ...args, path: undefined });
     if (queuedReads.length && queuedReads[0].key !== key) flushReads();
     return new Promise((resolve, reject) => {

package/src/runtime/runtime.js

@@ -139,7 +139,7 @@ export async function runGuestProgram({ code, nova = {}, config = {}, signal, on
   const fail = (error) => ({ ok: false, error: truncateChars(String(error), config.maxReturnChars ?? 32000, "error").text, logs, logTruncated, wallMs: wall() });
   let logTruncated = false;
   if (!isString(code) || !code.trim()) return fail("code must be a non-empty string");
-  if (code.length > (config.maxCodeChars ?? 48000)) return fail("code exceeds " + (config.maxCodeChars ?? 48000) + " characters");
+  if (code.length > (config.maxCodeChars ?? 48000)) return fail("code exceeds " + (config.maxCodeChars ?? 48000) + " characters; split large writes into write({path,content,append:true}) chunks");
   if (signal?.aborted) return fail(ABORT_MESSAGE);
   const runId = ++runSeq;
   const timeoutMs = config.timeoutMs ?? 60000;