pi-supernova 0.9.0 → 0.10.0

package/src/fs/commit.js

@@ -60,7 +60,9 @@ async function writeTemporary(entry, content, stat) {
   } catch (error) {
     // Never leak the temporary name: name the destination and the real cause.
     if (error?.code === "EACCES" || error?.code === "EPERM") throw new Error("permission denied writing " + entry.target + ": the directory or file is not writable");
+
     if (error?.code === "EROFS") throw new Error("cannot write " + entry.target + ": the file system is read-only");
+
     if (error?.code === "ENOSPC") throw new Error("cannot write " + entry.target + ": no space left on device");
 
     throw error;
@@ -130,6 +132,9 @@ async function assertExpectedSignature(vfs, logicalPath, target, stat) {
 
 async function installStaged(vfs, staged) {
   for (const entry of staged) {
+    // Staging and earlier renames await I/O. Recheck before each disk effect;
+    // failCommit restores earlier replacements if ownership changed mid-commit.
+    vfs.assertCurrent?.();
     vfs.signal?.throwIfAborted();
     await fs.rename(entry.temporary, entry.target);
     entry.replaced = true;
@@ -158,4 +163,5 @@ async function failCommit(vfs, staged, error) {
   if (recoveryErrors.length) throw new AggregateError([error, ...recoveryErrors.map(message => new Error(message))], "commit failed: " + error.message + "; recovery failed: " + recoveryErrors.join("; "));
   throw error;
 }
+
 export {assertExpectedSignature,collectMissingAncestors,makeStageEntry,stageReplacement,installStaged,failCommit,cleanupStaged};

package/src/fs/file-io.js

@@ -1,4 +1,5 @@
 import * as fs from 'node:fs/promises';
+import path from 'node:path';
 import {createHash} from 'node:crypto';
 
 function textSignature(text) {
@@ -19,6 +20,7 @@ async function* fileChunks(file, signal, maxBytes = Infinity) {
     signal?.throwIfAborted();
     const { bytesRead } = await file.read(buffer, 0, Math.min(buffer.length, remaining), null);
     signal?.throwIfAborted();
+
     if (!bytesRead) break;
     remaining -= bytesRead;
     // Consumers retaining a chunk must copy it before the next read.
@@ -33,6 +35,7 @@ async function fileSignature(target, signal, observed) {
     const actual = await file.stat();
 
     if (!actual.isFile()) throw new Error("read requires a regular file: " + target);
+
     if (observed && !sameFileVersion(observed, actual)) throw new Error("file changed while reading: " + target);
     const hash = createHash("sha256");
 
@@ -83,10 +86,21 @@ async function readLimitedBytes(file, stat, maxBytes, label, signal, overflow =
   return Buffer.concat(chunks);
 }
 
-function remapReadError(err, target) {
+async function hasFileParent(target) {
+  for (let parent = path.dirname(target); ; parent = path.dirname(parent)) {
+    try { return !(await fs.stat(parent)).isDirectory(); }
+    catch (error) { if (error.code !== "ENOENT" && error.code !== "ENOTDIR") return false; }
+
+    if (parent === path.dirname(parent)) return false;
+  }
+}
+
+async function remapReadError(err, target) {
   if (err.code === "EISDIR") throw new Error("path is a directory, not a file: " + target);
 
-  if (err.code === "ENOTDIR") throw new Error("cannot use path: a parent component of " + target + " is a file, not a directory");
+  // Windows returns ENOENT, not ENOTDIR, for a file used as a parent.
+  if (err.code === "ENOTDIR" || err.code === "ENOENT" && await hasFileParent(target)) throw new Error("cannot use path: a parent component of " + target + " is a file, not a directory");
+
   if (err.code === "EACCES" || err.code === "EPERM") throw new Error("permission denied reading " + target + ": check the file mode (for example bash chmod)");
 
   if (err.code === "ENOENT") {
@@ -97,4 +111,5 @@ function remapReadError(err, target) {
 
   throw err;
 }
+
 export { textSignature, sameFileVersion, fileChunks, fileSignature, sameSignature, tooLargeRead, overlayOrThrow, assertReadableFile, readLimitedBytes, remapReadError };

package/src/fs/process-tree.js

@@ -0,0 +1,92 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { setTimeout as delay } from "node:timers/promises";
+
+const exec = promisify(execFile);
+
+// PTYs and shell job control can create groups distinct from the original
+// leader. Record those groups while ancestry exists, before signalling parents.
+async function descendantGroups(pid) {
+  const { stdout } = await exec("ps", ["-ax", "-o", "pid=,ppid=,pgid="], {timeout:1000, maxBuffer:4*1024*1024});
+  const children = new Map();
+
+  for (const line of stdout.trim().split("\n")) {
+    const [child, parent, group] = line.trim().split(/\s+/).map(Number);
+
+    if (!children.has(parent)) children.set(parent, []);
+    children.get(parent).push({pid:child,group});
+  }
+
+  const found = [];
+  const pending = [...(children.get(pid) ?? [])];
+
+  while (pending.length) {
+    const child = pending.pop();
+
+    if (child.group > 0) found.push(child.group);
+    pending.push(...(children.get(child.pid) ?? []));
+  }
+
+  return found;
+}
+
+function signalGroups(job, signal) {
+  for (const group of job.groups) {
+    // Once SIGKILL was delivered, wait for reaping. Darwin can return EPERM
+    // when signalling a zombie again; newly discovered groups still need a kill.
+    if (signal === "SIGKILL" && job.killedGroups.has(group)) continue;
+
+    try {
+      process.kill(-group, signal);
+
+      if (signal === "SIGKILL") job.killedGroups.add(group);
+    } catch (error) {
+      if (error.code === "EPERM") {
+        // Even signal 0 can encounter that race. Keep ownership until ESRCH;
+        // an inaccessible live group must fail at the deadline, not look gone.
+        job.signalError = `cannot signal process group ${group} with ${signal}: ${error.message}`;
+        continue;
+      }
+
+      if (error.code !== "ESRCH") throw error;
+      job.groups.delete(group);
+    }
+  }
+}
+
+// Both foreground and background commands own their POSIX groups until they
+// disappear, not merely until the leader exits or inherited output pipes close.
+// Callers update processExited/processClosed from the real child events and may
+// add PTY group identities while cleanup awaits. Windows remains best-effort.
+export async function retireProcessTree(job) {
+  let discoveryError;
+
+  if (process.platform === "win32") {
+    if (!job.processExited) await exec("taskkill", ["/pid", String(job.child.pid), "/t", "/f"], {timeout:2000,windowsHide:true});
+  } else {
+    if (!job.processExited) {
+      try { for (const group of await descendantGroups(job.child.pid)) job.groups.add(group); }
+      catch (error) { discoveryError = error; }
+    }
+
+    signalGroups(job, "SIGTERM");
+
+    if (job.groups.size) await delay(150);
+    signalGroups(job, "SIGKILL");
+  }
+
+  const deadline = Date.now() + 1000;
+
+  while (true) {
+    if (process.platform !== "win32") signalGroups(job, 0);
+
+    if (job.processClosed && (process.platform === "win32" || job.groups.size === 0)) break;
+
+    if (Date.now() >= deadline) throw new Error("owned process group or output pipes did not close" + (job.signalError ? ": " + job.signalError : ""));
+
+    if (process.platform !== "win32") signalGroups(job, "SIGKILL");
+    await delay(10);
+  }
+
+  if (discoveryError) throw new Error("descendant discovery failed: " + discoveryError.message);
+}

package/src/fs/read-window.js

@@ -7,67 +7,84 @@ import { fileChunks, remapReadError } from "./file-io.js";
 function advanceLines(bytes, start, remaining) {
   while (remaining > 0) {
     const newline = bytes.indexOf(10, start);
+
     if (newline < 0) return { offset: bytes.length, remaining };
     start = newline + 1;
     remaining--;
   }
+
   return { offset: start, remaining };
 }
 
 async function scanWindow(file, stat, startLine, lineCount, maxBytes, signal) {
   const scan = { parts: [], collected: 0, startByte: undefined, endByte: undefined };
   let skip = startLine - 1, take = lineCount ?? Infinity, position = 0;
+
   for await (const chunk of fileChunks(file, signal, stat.size)) {
     const head = advanceLines(chunk, 0, skip);
     skip = head.remaining;
     const start = position;
     position += chunk.length;
+
     if (skip) continue;
     scan.startByte ??= start + head.offset;
     const tail = advanceLines(chunk, head.offset, take);
     take = tail.remaining;
+
     if (take === 0) scan.endByte = start + tail.offset;
     const end = Math.min(tail.offset, head.offset + maxBytes + 1 - scan.collected);
+
     if (end > head.offset) {
       scan.parts.push(Buffer.from(chunk.subarray(head.offset, end)));
       scan.collected += end - head.offset;
     }
+
     if (take === 0 || scan.collected > maxBytes) break;
   }
+
   return scan;
 }
 
 function overlayWindow(overlay, startLine, lineCount) {
   const window = sliceLinesRawInfo(overlay, startLine, lineCount);
   const satisfied = lineCount === undefined || lineCount === 0 || window.text === "" || window.count >= lineCount || window.eof;
+
   return { text: window.text, satisfied, whole: window.whole };
 }
 
 async function openReadFile(target) {
   try { return await fs.open(target, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0)); }
-  catch (error) { remapReadError(error, target); }
+  catch (error) { await remapReadError(error, target); }
 }
 
 export function createWindowReader(vfs) {
   return async function readWindow(target, startLine, lineCount, maxBytes, signal) {
     const overlay = vfs.getOverlay(target);
+
     if (overlay !== undefined) {
       const window = overlayWindow(overlay,startLine,lineCount);
       window.satisfied &&= Buffer.byteLength(window.text,"utf8") <= maxBytes;
+
       return window;
     }
+
     const file = await openReadFile(target);
+
     try {
       const stat = await file.stat();
+
       if (!stat.isFile()) throw new Error("read requires a regular file: " + target);
+
       if (lineCount === 0) return { text: "", satisfied: true, whole: stat.size === 0 };
       const scan = await scanWindow(file, stat, startLine, lineCount, maxBytes, signal);
+
       if (scan.startByte === undefined) return { text: "", satisfied: true, whole: stat.size === 0 };
       const bytes = Buffer.concat(scan.parts, scan.collected);
       const end = scan.startByte + scan.collected;
       const eof = end >= stat.size;
       const text = eof ? decodeUtf8Strict(bytes, target) : decodeUtf8Window(bytes);
       await vfs.recordExpected(target, stat);
+
       return { text, satisfied: end >= scan.endByte || eof, whole: startLine === 1 && scan.startByte === 0 && eof };
     } finally { await file.close(); }
   };

package/src/fs/vfs.js

@@ -1,6 +1,8 @@
 import {textSignature,sameFileVersion,fileSignature,tooLargeRead,overlayOrThrow,assertReadableFile,readLimitedBytes,remapReadError} from './file-io.js';
 import {resolveCommitTarget,assertExpectedSignature,collectMissingAncestors,makeStageEntry,stageReplacement,installStaged,failCommit,cleanupStaged} from './commit.js';
+
 export {resolveCommitTarget} from './commit.js';
+
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { isString } from "../shared/decode.js";
@@ -10,8 +12,9 @@ import { decodeUtf8Strict } from "../shared/utf8.js";
 let commitTail = Promise.resolve();
 
 export class CausalVfs {
-  constructor(onNewFile, validateWrite) {
+  constructor(onNewFile, validateWrite, assertCurrent) {
     this.validateWrite = validateWrite;
+    this.assertCurrent = assertCurrent;
     // No body cache: every read hits disk (or its overlay) so observed bytes
     // are never stale. CAS baselines in `expected` are the only retained
     // per-file state, cleared only at external-mutation boundaries.
@@ -24,6 +27,8 @@ export class CausalVfs {
   }
 
   assertWritable() {
+    this.assertCurrent?.();
+
     if (this.closed) throw new Error("program is already complete");
     this.signal?.throwIfAborted();
   }
@@ -55,6 +60,7 @@ export class CausalVfs {
         bytes = maxBytes === undefined
           ? await file.readFile({ signal: this.signal })
           : await readLimitedBytes(file, stat, maxBytes, label, this.signal, () => tooLargeRead(label,maxBytes,target));
+
         if (!sameFileVersion(stat, await file.stat())) throw new Error("file changed while reading: " + target);
       } finally { await file.close(); }
 
@@ -63,7 +69,7 @@ export class CausalVfs {
 
       return strict ? decodeUtf8Strict(bytes, target) : bytes.toString("utf8");
     } catch (err) {
-      remapReadError(err, target);
+      await remapReadError(err, target);
     }
   }
 
@@ -139,6 +145,9 @@ export class CausalVfs {
     let failed = false;
 
     try {
+      // Admission may have preceded another transaction's asynchronous commit.
+      this.assertCurrent?.();
+
       for (const [logicalPath, content] of writes) {
         this.signal?.throwIfAborted();
         const { target, stat } = await resolveCommitTarget(logicalPath);
@@ -193,10 +202,14 @@ export class CausalVfs {
     return { rolledBack: top?.size ?? 0, depth: this.overlays.length };
   }
 
-  async prepareExternalMutation(name) {
+  assertExternalAllowed(name) {
     this.assertWritable();
 
-    if (this.overlays.length > 1) throw new Error(name + " cannot run inside an edit checkpoint because external mutations cannot be rolled back");
+    if (this.overlays.length > 1) throw new Error(name + " cannot run inside an edit checkpoint because external mutations cannot be rolled back; run bash after the checkpoint, or use explicit restoration outside checkpoints for mutation tests");
+  }
+
+  async prepareExternalMutation(name) {
+    this.assertExternalAllowed(name);
 
     if (!this.overlays.length) { this.mutations.external++;
 

package/src/fs/workspace.js

@@ -1,4 +1,5 @@
 import {remapReadError} from "./file-io.js";
+import { retireProcessTree } from "./process-tree.js";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { spawn } from "node:child_process";
@@ -45,7 +46,7 @@ async function realpathNearest(target) {
     try {
       return await fs.realpath(probe);
     } catch (err) {
-      if (err?.code !== "ENOENT" && err?.code !== "ENOTDIR") remapReadError(err, target);
+      if (err?.code !== "ENOENT" && err?.code !== "ENOTDIR") await remapReadError(err, target);
       const parent = path.dirname(probe);
 
       if (parent === probe) throw err;
@@ -137,21 +138,22 @@ function commandTimeoutMs(options) {
   return Math.max(1, Math.min(2_147_483_647, Math.floor(requestedTimeout)));
 }
 
-function spawnCommand(argv, options, cwd) {
-  return spawn(argv[0], argv.slice(1), {
-    cwd, env: options.env ?? process.env, stdio: ["ignore", "pipe", "pipe"], detached: process.platform !== "win32",
-  });
-}
+export function commandSpawnError(error, command) {
+  if (error?.code === "EACCES" || error?.code === "EPERM") return new Error("cannot execute " + command + ": permission denied (is it executable?)");
 
-function signalProcessTree(child, signal) {
-  if (!child.pid) return;
+  if (error?.code === "ENOENT") return new Error("command not found: " + command);
 
-  if (process.platform === "win32") {
-    const killer = spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], { stdio: "ignore" });
-    killer.on("error", () => child.kill(signal));
-  } else {
-    try { process.kill(-child.pid, signal); } catch (err) { if (err.code !== "ESRCH") child.kill(signal); }
-  }
+  if (error?.code === "ENOTDIR") return new Error("cannot run " + command + ": the working directory is not a directory");
+
+  return error;
+}
+
+export function spawnCommand(argv, options, cwd = options.cwd) {
+  try {
+    return spawn(argv[0], argv.slice(1), {
+      cwd, env: options.env ?? process.env, stdio: options.stdio ?? ["ignore", "pipe", "pipe"], detached: process.platform !== "win32", windowsHide:true,
+    });
+  } catch (error) { throw commandSpawnError(error,argv[0]); }
 }
 
 function failCommand(state, error) {
@@ -171,11 +173,29 @@ function failCommand(state, error) {
 }
 
 function terminateCommand(state, error) {
-  if (state.settled || state.terminationError) return;
-  state.terminationError = error;
-  signalProcessTree(state.child, "SIGTERM");
-  // Keep ownership after the direct child exits: descendants may ignore SIGTERM.
-  state.escalation = setTimeout(() => { signalProcessTree(state.child, "SIGKILL"); failCommand(state, error); }, 150);
+  if (state.settled) return;
+  state.terminationError ??= error;
+
+  if (state.stopping) return;
+  clearTimeout(state.timer);
+  state.stopping = retireProcessTree(state).then(()=>{
+    if (state.terminationError) {
+      failCommand(state,state.terminationError);
+
+      return;
+    }
+
+    state.settled = true;
+    state.cleanup();
+    state.resolve({ stdout:state.stdout, stderr:state.stderr,
+      exitCode:state.exitCode ?? (128 + (constants.signals[state.signal] ?? 1)),
+      signal:state.signal, outputTruncated:state.outputTruncated });
+  }).catch(cause=>{
+    state.child.stdout.destroy();
+    state.child.stderr.destroy();
+    const prefix = state.terminationError ? state.terminationError.message + "; " : "";
+    failCommand(state,new Error(prefix + "command cleanup failed: " + cause.message));
+  });
 }
 
 function appendCommandOutput(state, current, chunk) {
@@ -186,33 +206,14 @@ function appendCommandOutput(state, current, chunk) {
   return remaining ? current + chunk.slice(0, remaining) : current;
 }
 
-function onCommandClose(state, code, signal) {
-  if (state.settled) return;
-
-  if (state.terminationError) {
-    // A closed pipe alone says nothing about descendants. Only ESRCH proves
-    // the owned POSIX group is gone; otherwise retain the escalation timer.
-    if (process.platform !== "win32" && state.child.pid) {
-      try { process.kill(-state.child.pid, 0); }
-      catch (error) { if (error.code === "ESRCH") failCommand(state, state.terminationError); }
-    }
-
-    return;
-  }
-
-  state.settled = true;
-  state.cleanup();
-  state.resolve({ stdout: state.stdout, stderr: state.stderr, exitCode: code ?? (128 + (constants.signals[signal] ?? 1)), signal, outputTruncated: state.outputTruncated });
-}
-
 function attachCommandIO(state, options, argv, timeoutMs) {
   const { child } = state;
   const onAbort = () => terminateCommand(state, new Error("aborted"));
   state.cleanup = () => {
     clearTimeout(state.timer);
-    clearTimeout(state.escalation);
     options.signal?.removeEventListener("abort", onAbort);
   };
+
   state.timer = setTimeout(() => terminateCommand(state, new Error(
     "command timed out after " + timeoutMs + "ms: " + truncateChars(options.commandLabel ?? argv.join(" "), 240, "command").text
     + "\nhint: Increase this bash timeoutMs and the outer supernova timeoutMs, or split the work. Sleeps and every command in a shell chain share the same limit."
@@ -221,13 +222,16 @@ function attachCommandIO(state, options, argv, timeoutMs) {
   child.stderr.setEncoding("utf8");
   child.stdout.on("data", chunk => { state.stdout = appendCommandOutput(state, state.stdout, chunk); });
   child.stderr.on("data", chunk => { state.stderr = appendCommandOutput(state, state.stderr, chunk); });
-  child.on("error", error => {
-    if (error?.code === "EACCES" || error?.code === "EPERM") failCommand(state, new Error("cannot execute " + argv[0] + ": permission denied (is it executable?)"));
-    else if (error?.code === "ENOENT") failCommand(state, new Error("command not found: " + argv[0]));
-    else if (error?.code === "ENOTDIR") failCommand(state, new Error("cannot run " + argv[0] + ": the working directory is not a directory"));
-    else failCommand(state, error);
+  child.on("error", error => failCommand(state,commandSpawnError(error,argv[0])));
+  child.once("exit", (code, signal) => {
+    state.processExited = true;
+    state.exitCode = code;
+    state.signal = signal;
+    // An orphan can retain the pipes forever. Begin retirement at leader exit,
+    // then wait for close and group disappearance before reporting completion.
+    terminateCommand(state);
   });
-  child.on("close", (code, signal) => onCommandClose(state, code, signal));
+  child.once("close", () => { state.processClosed = true; });
   options.signal?.addEventListener("abort", onAbort, { once: true });
 
   if (options.signal?.aborted) onAbort();
@@ -243,7 +247,8 @@ export async function runCommand(argv, options = {}) {
     const child = spawnCommand(argv, options, cwd);
     attachCommandIO({
       child, resolve, reject, stdout: "", stderr: "", settled: false,
-      outputTruncated: false, terminationError: undefined, escalation: undefined,
+      outputTruncated: false, terminationError: undefined, stopping: undefined,
+      groups:new Set(child.pid ? [child.pid] : []), killedGroups:new Set(),
       maxOutputChars, timer: undefined, cleanup() {},
     }, options, argv, timeoutMs);
   });

package/src/output/bottleneck.js

@@ -167,6 +167,7 @@ function packageBatchItems(batch, details, maxChars) {
   const itemErrors = (details.itemErrors ?? []).map(error => boundItemError(error, maxChars, batch.length));
   let remaining = maxChars;
   let truncated = false;
+
   const items = batch.map((item, index) => {
     const share = details.independent === true ? maxChars : Math.floor(remaining / (batch.length - index));
     const bounded = boundBatchItem(item, share);
@@ -223,14 +224,26 @@ function attachTruncation(result, truncated, batch, text, config, maxChars, capp
 
 export function packageHostResult(raw, config) {
   const details = detailsOf(raw);
+
   if (raw && Object.hasOwn(raw, READ_VALUE)) {
     const batch = batchFromDetails(details);
     const result = {ok: !hostResultFailed(raw), value: raw[READ_VALUE], typed: true, cloneItems: details?.jsonMany === true, truncated: details?.outputTruncated === true};
     attachDetails(result, details, batch);
-    if (batch) { result.items = batch; result.itemErrors = details.itemErrors ?? []; }
+
+    if (isString(details?.sourcePath)) result.sourcePath = details.sourcePath;
+
+    if (batch) {
+      result.items = batch;
+      result.itemErrors = details.itemErrors ?? [];
+
+      if (details.sourcePaths) result.sourcePaths = details.sourcePaths;
+    }
+
     if (details?.streamed) result.streamed = true;
+
     return result;
   }
+
   const maxChars = config.maxCallResultChars ?? 65536;
   const batch = batchFromDetails(details);
   const text = batch ? "" : extractRawString(raw);

package/src/runtime/guest-api.js

@@ -15,16 +15,20 @@ function unwrapValue(res) {
   return res;
 }
 
-function unwrapRead(res, args) {
+function unwrapRead(res, args, observe) {
   const value = unwrapValue(res);
 
   if ((args.complete === true || args.json !== undefined) && res?.truncated) throw new Error("incomplete read: complete:true or json refuses truncated host output");
 
-  return decodeReadItem(args, value, res);
+  const decoded = decodeReadItem(args, value, res);
+  observe?.(args,res);
+
+  return decoded;
 }
 
 function decodeReadItem(args, value, res) {
   if (!res?.typed) return decodeReadValue(args, value);
+
   // JSON selectors used to cross RPC as separately encoded JSON values. Keep
   // their mutable results independent, but put the copies in the guest heap.
   return res.cloneItems ? value.map(item => structuredClone(item)) : value;
@@ -59,18 +63,22 @@ function missingResolvedIndex(values, paths) {
 
 function settleReadItem(wave, index, res) {
   const job = wave[index];
+
   if (!job) throw new Error("invalid streamed read index: " + index);
   wave[index] = null; // Release resolver closures and their potentially large values.
-  try { job.resolve(unwrapRead(res,job.args)); }
+
+  try { job.resolve(unwrapRead(res,job.args,job.observe)); }
   catch (error) { job.reject(error); }
 }
 
 function settleInlineWave(wave,res,received) {
   unwrapValue(res);
+
   if (received || !Array.isArray(res.items) || res.items.length !== wave.length) throw new Error("invalid batch read response");
+
   for (let i=0;i<wave.length;i++) {
     const error = res.itemErrors?.[i];
-    settleReadItem(wave,i,{...res,ok:!error,value:error ?? res.items[i],items:undefined});
+    settleReadItem(wave,i,{...res,ok:!error,value:error ?? res.items[i],sourcePath:res.sourcePaths?.[i],items:undefined});
   }
 }
 
@@ -78,24 +86,32 @@ async function rpcReadWave(rpc, wave) {
   if (wave.length === 1) {
     const res = leanEnvelope(await rpc("call",["read",wave[0].args]));
     settleReadItem(wave,0,res);
+
     return;
   }
+
   const args = {...wave[0].args,path:wave.map(job=>job.args.path),_independent:true};
   let received = 0, last;
+
   const onItem = (index,res) => {
     if (!Number.isInteger(index) || !wave[index] || last?.index === index) throw new Error("invalid streamed read response");
     received++;
+
     // Keep the final read pending until the host RPC/barrier itself has settled.
     // An awaited batch must never look complete while its host call is running.
     if (received === wave.length) last = {index,res};
     else settleReadItem(wave,index,res);
   };
+
   const res = leanEnvelope(await rpc("call",["read",args],onItem));
+
   if (res?.streamed) {
     if (received !== wave.length || !last) throw new Error("incomplete streamed read response");
     settleReadItem(wave,last.index,last.res);
+
     return;
   }
+
   settleInlineWave(wave,res,received);
 }
 
@@ -118,7 +134,7 @@ function enqueueCompatibleRead(readState, flushReads, args) {
   if (readState.queued.length && readState.queued[0].key !== key) flushReads();
 
   const promise = new Promise((resolve, reject) => {
-    readState.queued.push({ args, key, resolve, reject });
+    readState.queued.push({ args, key, resolve, reject, observe:readState.observe });
 
     if (readState.queued.length === 1) queueMicrotask(flushReads);
   });
@@ -128,12 +144,16 @@ function enqueueCompatibleRead(readState, flushReads, args) {
 
 async function readManyPaths(readOne, args, paths) {
   assertReadPaths(paths);
+
   const values = await Promise.all(paths.map(async item => {
     try { return await readOne({...args,path:item}); }
     catch (error) { throwReadPathError(item,error.message); }
   }));
+
   const missing = args.resolve ? missingResolvedIndex(values,paths) : -1;
+
   if (missing >= 0) throwReadPathError(paths[missing],"not_found");
+
   return values;
 }
 
@@ -193,12 +213,13 @@ export function buildGuestApi(rpc, batchRead) {
     if (checkpoint) throw new Error("edit checkpoints cannot overlap or nest; await the current checkpoint");
     const token = {};
     checkpoint = token;
+
     try { return await runSpeculation(fn, token, checkpointScope, drainReads, rpc); }
     finally { checkpoint = null; }
   }
 
   // Coalesce already-started compatible reads without rewriting JS control flow.
-  const readState = { queued: [], waves: new Set() };
+  const readState = { queued: [], waves: new Set(), observe:noteReadPath };
 
   function flushReads() {
     const pending = readState.queued;
@@ -227,26 +248,21 @@ export function buildGuestApi(rpc, batchRead) {
     const args = normalizeRead(gatherReadArgs(p, a, b));
     p = args.path;
 
-    if (Array.isArray(p)) {
-      const values = await readManyPaths(read, args, p);
-      for (const item of p) if (isString(item)) noteReadPath({ path: item }, values);
-
-      return values;
-    }
+    if (Array.isArray(p)) return await readManyPaths(read, args, p);
 
-    const readValue = !batchRead
-      ? unwrapRead(await invoke("read", args), args)
+    return !batchRead
+      ? unwrapRead(await invoke("read", args), args, noteReadPath)
       : await enqueueCompatibleRead(readState, flushReads, args);
-    noteReadPath(args, readValue);
-
-    return readValue;
   };
 
   const readFiles = new Set();
 
-  function noteReadPath(args, value) {
-    if (isString(args.path) && looksLikePath(args.path)) readFiles.add(args.path);
-    if (isObject(value) && isString(value.path) && looksLikePath(value.path)) readFiles.add(value.path);
+  function noteReadPath(args, envelope) {
+    if (isString(args.path) && args.resolve !== true && args.query === undefined && args.evidence !== true) readFiles.add(args.path);
+
+    // A document may itself contain path/status fields. Only adapter provenance,
+    // carried separately through scalar, inline and streamed replies, names a read.
+    if (isString(envelope.sourcePath)) readFiles.add(envelope.sourcePath);
   }
 
   const write = async (p, content) => {