mixdog 1.0.12 → 1.1.0

package/src/runtime/agent/orchestrator/tools/builtin/lib/grep-single-file-rescue.mjs

@@ -15,13 +15,14 @@
 // exactly — multiline patterns, type filters, a PCRE-only regex, a binary or
 // oversized file — declines (returns null) and the caller keeps the original
 // native error.
-import { readFile } from 'node:fs/promises';
+import { PATCH_SNAPSHOT_MAX_BYTES, readBoundedFile } from '../../../../../shared/bounded-file-read.mjs';
 
 import { formatGrepContextOutput, formatGrepOutput, grepNoMatchesBody } from './grep-output.mjs';
 
 /** Reading is the whole point of the rescue, so the file must stay small
- *  enough that reading it is cheaper than the failed search. */
-export const MAX_RESCUE_BYTES = 8 * 1024 * 1024;
+ *  enough that reading it is cheaper than the failed search. The read is
+ *  bounded: an oversized (or growing) file is declined without being read. */
+export const MAX_RESCUE_BYTES = PATCH_SNAPSHOT_MAX_BYTES;
 /** Bounds memory on a pathological match rate; a truncated window is reported
  *  as incomplete, exactly like a capped native result. */
 const MAX_RESCUE_LINES = 5_000;
@@ -69,11 +70,13 @@ export async function runGrepSingleFileRescue({
 
   let raw;
   try {
-    raw = await readFile(filePath);
+    const read = readBoundedFile(filePath, { maxBytes: MAX_RESCUE_BYTES });
+    if (read.state !== 'present') return null;
+    raw = read.content;
   } catch {
     return null;
   }
-  if (raw.length > MAX_RESCUE_BYTES || raw.includes(0)) return null;
+  if (raw.includes(0)) return null;
   const text = raw.toString('utf8');
   const fileLines = text.split(/\r?\n/);
   if (fileLines.length > 0 && fileLines[fileLines.length - 1] === '') fileLines.pop();

package/src/runtime/agent/orchestrator/tools/builtin/lib/shell-task-output.mjs

@@ -1,13 +1,20 @@
 import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
-import { StringDecoder } from 'node:string_decoder';
 import { stripAnsi } from '../../shell-exec-output.mjs';
+import { FileEncodingSniffer, ShellStreamDecoder, alignedOffset, oemTextEncoding } from '../../shell-codepage.mjs';
 
 const PAGE_BYTES = 8 * 1024;
 const COMPLETION_BYTES = 12 * 1024;
 const cursors = new WeakMap();
 
 function newCursor() {
-  return { offset: 0, preview: '', decoder: new StringDecoder('utf8'), ansi: '' };
+  return {
+    offset: 0,
+    preview: '',
+    decoder: new ShellStreamDecoder(),
+    ansi: '',
+    sniffer: new FileEncodingSniffer(),
+    committed: false,
+  };
 }
 
 // Only the introducer is retained, plus the ESC that may open a split OSC
@@ -85,20 +92,26 @@ export function readShellTaskOutput(task, result = {}, { output = 'new' } = {})
         cursor = newCursor();
         streams.set(key, cursor);
       }
-      const start = terminal || replay ? Math.max(cursor.offset, size - limit) : cursor.offset;
-      const skipped = start - cursor.offset;
-      if (skipped) {
-        cursor.decoder = new StringDecoder('utf8');
+      // Raw capture files carry the child's bytes. The stream's encoding is
+      // decided once, firmly (or when the task is terminal); until then only
+      // the ASCII prefix is read.
+      const label = cursor.sniffer.probe(fd, size, terminal);
+      if (label && !cursor.committed) {
+        cursor.committed = true;
+        cursor.decoder.force(label);
+      }
+      const readEnd = label ? size : cursor.sniffer.safeEnd(size);
+      let start = terminal || replay ? Math.max(cursor.offset, readEnd - limit) : cursor.offset;
+      if (start > cursor.offset) {
+        start = Math.min(readEnd, alignedOffset(fd, start, label || 'utf-8'));
+        sections.push(`[${stream}: ${start - cursor.offset} earlier bytes omitted; read ${path} for the original log]`);
+        cursor.decoder = new ShellStreamDecoder(oemTextEncoding(), label);
         cursor.ansi = '';
       }
-      const buffer = Buffer.alloc(Math.min(limit, Math.max(0, size - start)));
+      const buffer = Buffer.alloc(Math.min(limit, Math.max(0, readEnd - start)));
       const count = buffer.length ? readSync(fd, buffer, 0, buffer.length, start) : 0;
-      const prefix = skipped ? utf8Boundary(buffer, 0, count) : 0;
-      if (skipped + prefix) {
-        sections.push(`[${stream}: ${skipped + prefix} earlier bytes omitted; read ${path} for the original log]`);
-      }
       cursor.offset = start + count;
-      let decoded = cursor.decoder.write(buffer.subarray(prefix, count));
+      let decoded = cursor.decoder.write(buffer.subarray(0, count));
       if (terminal && cursor.offset === size) decoded += cursor.decoder.end();
       const text = visibleText(cursor, decoded);
       if (text) sections.push(`[${stream}]\n${text}`);

package/src/runtime/agent/orchestrator/tools/builtin/raw-content-publication.mjs

@@ -0,0 +1,17 @@
+import { statSync } from 'node:fs';
+import { rawContentCacheSet } from './cache-layers.mjs';
+import { sameFileVersion } from './file-version.mjs';
+
+// `before` is an owned version captured BEFORE the fresh read. A failed
+// post-read stat is uncertainty, never evidence that the bytes are stable.
+// Keep the current invocation's observation; do not retry or relabel it.
+export function publishRawContentAfterRead(fullPath, before, rawBuf, readStat = statSync) {
+  if (!before || !Buffer.isBuffer(rawBuf) || rawBuf.length !== before.size) return;
+  let after;
+  try {
+    after = readStat(fullPath);
+  } catch {
+    return;
+  }
+  if (sameFileVersion(before, after)) rawContentCacheSet(fullPath, before, rawBuf);
+}

package/src/runtime/agent/orchestrator/tools/builtin/read-range-index.mjs

@@ -1,4 +1,6 @@
 import { mkdir, open, readFile, readdir, stat, unlink } from 'node:fs/promises';
+import { statSync } from 'node:fs';
+import { fileVersion, sameFileVersion } from './file-version.mjs';
 import { hashText as sha256Hex } from './hash-utils.mjs';
 import { join, normalize, resolve } from 'node:path';
 import { getPluginData } from '../../config.mjs';
@@ -11,7 +13,10 @@ const READ_RANGE_INDEX_MAX_PERSISTED_ANCHORS = 8192;
 const READ_RANGE_INDEX_PERSIST_DEBOUNCE_MS = 750;
 const READ_RANGE_INDEX_SWEEP_CONCURRENCY = 8;
 
+// Slots own publication rights; readers only mutate private drafts. Deleting
+// or replacing a slot detaches outstanding lookups/scans without a tombstone log.
 const READ_RANGE_INDEX_CACHE = new Map();
+const READ_RANGE_INDEX_DRAFTS = new WeakMap();
 const READ_RANGE_INDEX_PERSIST_PENDING = new Map();
 let readRangeIndexDiskSwept = false;
 
@@ -43,7 +48,7 @@ function readRangeIndexFilePath(fullPath) {
 }
 
 function serialiseReadRangeIndex(index) {
-  if (!index?.fullPath || !index.anchors) return null;
+  if (!index?.published || !sameFileVersion(index.fileVersion, index.fileVersion)) return null;
   const anchors = [...index.anchors.entries()]
     .filter(
       ([line, byteOffset]) => Number.isFinite(line) && Number.isFinite(byteOffset) && line >= 0 && byteOffset >= 0
@@ -52,25 +57,22 @@ function serialiseReadRangeIndex(index) {
     .slice(-READ_RANGE_INDEX_MAX_PERSISTED_ANCHORS);
   if (!anchors.some(([line]) => line === 0)) anchors.unshift([0, 0]);
   return {
-    version: 1,
+    version: 2,
     path: index.fullPath,
-    size: index.size,
-    mtimeMs: index.mtimeMs,
+    fileVersion: index.fileVersion,
     prefixHash: index.prefixHash || '',
     totalLines: Number.isFinite(index.totalLines) ? index.totalLines : undefined,
     anchors,
   };
 }
 
-function readRangeIndexMatches(row, fullPath, st) {
+function readRangeIndexMatches(row, fullPath, version) {
+  // Version-1 rows lack replacement identity. Never upgrade their anchors by
+  // attaching today's metadata; rebuild them from current bytes instead.
   return (
-    row &&
-    row.version === 1 &&
+    row?.version === 2 &&
     row.path === fullPath &&
-    typeof row.size === 'number' &&
-    row.size === st.size &&
-    Number.isFinite(row.mtimeMs) &&
-    Math.abs(row.mtimeMs - st.mtimeMs) <= 1 &&
+    sameFileVersion(row.fileVersion, version) &&
     Array.isArray(row.anchors)
   );
 }
@@ -123,21 +125,10 @@ async function loadReadRangeIndexFromDisk(fullPath, st, handle, prefixBuffer) {
   try {
     const row = JSON.parse(await readFile(file, 'utf-8'));
     if (!readRangeIndexMatches(row, fullPath, st)) return null;
-    // Anchors are byte offsets into the file. A same-size / same-mtime
-    // rewrite (touch-restore, in-place edit of equal-length content)
-    // leaves the stat gate above happy but invalidates every persisted
-    // byte offset, causing seeks to land on the wrong line. When the
-    // persisted index carries a prefixHash, the current file's prefix
-    // must match; on mismatch drop the on-disk row so the caller
-    // rebuilds from scratch.
+    // The prefix is an extra check, not proof that later byte offsets survived.
     if (typeof row.prefixHash === 'string' && row.prefixHash) {
       const cur = await computePrefixHashForIndex(fullPath, st, handle, prefixBuffer);
-      if (!cur || cur !== row.prefixHash) {
-        try {
-          await unlink(file);
-        } catch {}
-        return null;
-      }
+      if (!cur || cur !== row.prefixHash) return null;
     }
     const anchors = new Map([[0, 0]]);
     for (const entry of row.anchors) {
@@ -149,8 +140,7 @@ async function loadReadRangeIndexFromDisk(fullPath, st, handle, prefixBuffer) {
     }
     const loaded = {
       fullPath,
-      size: st.size,
-      mtimeMs: st.mtimeMs,
+      fileVersion: fileVersion(st),
       prefixHash: typeof row.prefixHash === 'string' ? row.prefixHash : '',
       anchors,
     };
@@ -166,36 +156,41 @@ async function loadReadRangeIndexFromDisk(fullPath, st, handle, prefixBuffer) {
   }
 }
 
+function currentReadRangeIndex(index) {
+  return !!index?.published && READ_RANGE_INDEX_CACHE.get(canonicalCachePath(index.fullPath)) === index;
+}
+
 function persistReadRangeIndexSync(index) {
   const file = readRangeIndexFilePath(index?.fullPath);
-  if (!file) return;
-  const row = serialiseReadRangeIndex(index);
-  if (!row) return;
+  if (!file || !currentReadRangeIndex(index)) return;
   try {
-    writeJsonAtomicSync(file, row, { compact: true, lock: true, fsync: false });
+    if (!sameFileVersion(index.fileVersion, statSync(index.fullPath))) return;
+    const row = serialiseReadRangeIndex(index);
+    if (row) writeJsonAtomicSync(file, row, { compact: true, lock: true, fsync: false });
   } catch {}
 }
 
-async function persistReadRangeIndex(index) {
+async function persistReadRangeIndex(index, evictedRow = null) {
   const file = readRangeIndexFilePath(index?.fullPath);
-  if (!file) return;
-  const row = serialiseReadRangeIndex(index);
-  if (!row) return;
+  if (!file || (!evictedRow && !currentReadRangeIndex(index))) return;
   try {
+    if (!sameFileVersion(evictedRow?.fileVersion || index.fileVersion, await stat(index.fullPath))) return;
     await mkdir(READ_RANGE_INDEX_DISK_DIR, { recursive: true });
-    await writeJsonAtomicAsync(file, row, { compact: true, lock: true, fsync: false });
+    if (!evictedRow && !currentReadRangeIndex(index)) return;
+    const row = evictedRow || serialiseReadRangeIndex(index);
+    if (row) await writeJsonAtomicAsync(file, row, { compact: true, lock: true, fsync: false });
   } catch {}
 }
 
 export function scheduleReadRangeIndexPersist(index) {
-  if (!READ_RANGE_INDEX_DISK_DIR || !index?.fullPath) return;
+  if (!READ_RANGE_INDEX_DISK_DIR || !currentReadRangeIndex(index)) return;
   const key = canonicalCachePath(index.fullPath);
   if (READ_RANGE_INDEX_PERSIST_PENDING.has(key)) return;
   const t = setTimeout(() => {
     READ_RANGE_INDEX_PERSIST_PENDING.delete(key);
     void persistReadRangeIndex(index);
   }, READ_RANGE_INDEX_PERSIST_DEBOUNCE_MS);
-  if (t.unref) t.unref();
+  t.unref();
   READ_RANGE_INDEX_PERSIST_PENDING.set(key, t);
 }
 
@@ -210,16 +205,14 @@ export function flushReadRangeIndexesSync() {
   }
 }
 
-export function deleteReadRangeIndexForPath(fullPath) {
-  const key = canonicalCachePath(fullPath);
+function dropReadRangeIndexSlot(key) {
   READ_RANGE_INDEX_CACHE.delete(key);
-  const timer = READ_RANGE_INDEX_PERSIST_PENDING.get(key);
-  if (timer) {
-    try {
-      clearTimeout(timer);
-    } catch {}
-    READ_RANGE_INDEX_PERSIST_PENDING.delete(key);
-  }
+  clearTimeout(READ_RANGE_INDEX_PERSIST_PENDING.get(key));
+  READ_RANGE_INDEX_PERSIST_PENDING.delete(key);
+}
+
+export function deleteReadRangeIndexForPath(fullPath) {
+  dropReadRangeIndexSlot(canonicalCachePath(fullPath));
   const file = readRangeIndexFilePath(fullPath);
   if (file) void unlink(file).catch(() => {});
 }
@@ -248,46 +241,114 @@ export async function sweepStaleReadRangeIndexes(directory = READ_RANGE_INDEX_DI
   await Promise.all(Array.from({ length: Math.min(READ_RANGE_INDEX_SWEEP_CONCURRENCY, entries.length) }, worker));
 }
 
-// Re-insert so the entry moves to the LRU tail, then hand it back.
+// Re-insert so the entry moves to the LRU tail. All insertion paths obey the
+// same cap, including disk hits. Eviction also revokes unfinished readers.
 function refreshReadRangeIndexSlot(key, index) {
   READ_RANGE_INDEX_CACHE.delete(key);
   READ_RANGE_INDEX_CACHE.set(key, index);
+  while (READ_RANGE_INDEX_CACHE.size > READ_RANGE_INDEX_MAX_ENTRIES) {
+    const oldest = READ_RANGE_INDEX_CACHE.keys().next().value;
+    const evicted = READ_RANGE_INDEX_CACHE.get(oldest);
+    // Preserve only committed anchors before cancelling the debounce. The
+    // owned row may finish saving after eviction, but outstanding drafts lose
+    // their slot immediately. Disk IO must not delay the foreground lookup.
+    const row = serialiseReadRangeIndex(evicted);
+    dropReadRangeIndexSlot(oldest);
+    if (row) void persistReadRangeIndex(evicted, row);
+  }
   return index;
 }
 
-// A supplied handle is borrowed; validation never changes its position or closes it.
+function freshReadRangeIndex(fullPath, version = null) {
+  return { fullPath, fileVersion: version, prefixHash: '', anchors: new Map([[0, 0]]), published: false };
+}
+
+// A supplied handle is borrowed; validation uses positional IO and never closes
+// it. The stat argument is only a hint for a previously read prefix, not proof
+// of the current handle/path version. A cache miss always starts at byte zero.
 export async function getReadRangeIndex(fullPath, st, handle = null, prefixBuffer = null) {
-  if (!st) return null;
   const key = canonicalCachePath(fullPath);
-  const cached = READ_RANGE_INDEX_CACHE.get(key);
-  if (cached && cached.size === st.size && Math.abs(cached.mtimeMs - st.mtimeMs) <= 1) {
-    // In-memory anchors share the same byte-offset hazard as the
-    // on-disk row: a same-size / same-mtime overwrite would otherwise
-    // be reused with the wrong offsets. When a prefixHash was recorded
-    // for the cached index, verify it before refreshing the LRU slot;
-    // on mismatch evict and fall through to disk-load / fresh rebuild.
-    // When prefixHash is empty (e.g. a freshly-created index that no
-    // streaming read has populated yet) keep the prior stat-only
-    // behavior so genuinely unchanged files are not re-walked.
-    if (!cached.prefixHash) return refreshReadRangeIndexSlot(key, cached);
-    const cur = await computePrefixHashForIndex(fullPath, st, handle, prefixBuffer);
-    if (cur && cur === cached.prefixHash) return refreshReadRangeIndexSlot(key, cached);
-    READ_RANGE_INDEX_CACHE.delete(key);
+  let slot = READ_RANGE_INDEX_CACHE.get(key);
+  if (!slot) slot = refreshReadRangeIndexSlot(key, freshReadRangeIndex(fullPath));
+  const hint = fileVersion(st);
+  const readStat = () => (handle ? handle.stat() : stat(fullPath));
+  let version;
+  try {
+    const observed = await readStat();
+    if (!observed.isFile()) return null;
+    version = fileVersion(observed);
+  } catch {
+    return null;
   }
-  const loaded = await loadReadRangeIndexFromDisk(fullPath, st, handle, prefixBuffer);
-  if (loaded) {
-    READ_RANGE_INDEX_CACHE.set(key, loaded);
-    return loaded;
+  if (!version || READ_RANGE_INDEX_CACHE.get(key) !== slot) return null;
+  version = Object.freeze(version);
+  if (!slot.fileVersion) slot.fileVersion = version;
+  if (!sameFileVersion(slot.fileVersion, version)) {
+    dropReadRangeIndexSlot(key);
+    slot = refreshReadRangeIndexSlot(key, freshReadRangeIndex(fullPath, version));
   }
-  const fresh = { fullPath, size: st.size, mtimeMs: st.mtimeMs, prefixHash: '', anchors: new Map([[0, 0]]) };
-  READ_RANGE_INDEX_CACHE.set(key, fresh);
-  while (READ_RANGE_INDEX_CACHE.size > READ_RANGE_INDEX_MAX_ENTRIES) {
-    const oldest = READ_RANGE_INDEX_CACHE.keys().next().value;
-    const oldIndex = READ_RANGE_INDEX_CACHE.get(oldest);
-    if (oldIndex) void persistReadRangeIndex(oldIndex);
-    READ_RANGE_INDEX_CACHE.delete(oldest);
+  const prefix = sameFileVersion(hint, version) ? prefixBuffer : null;
+  let source = slot;
+  if (slot.published && slot.prefixHash) {
+    const cur = await computePrefixHashForIndex(fullPath, version, handle, prefix);
+    if (READ_RANGE_INDEX_CACHE.get(key) !== slot) return null;
+    if (!cur || cur !== slot.prefixHash) {
+      dropReadRangeIndexSlot(key);
+      slot = refreshReadRangeIndexSlot(key, freshReadRangeIndex(fullPath, version));
+      source = slot;
+    }
+  }
+  if (!slot.published) source = (await loadReadRangeIndexFromDisk(fullPath, version, handle, prefix)) || slot;
+  // Neither a delayed disk lookup nor a changed source can authorize offsets.
+  try {
+    if (!sameFileVersion(version, await readStat())) return null;
+  } catch {
+    return null;
+  }
+  if (READ_RANGE_INDEX_CACHE.get(key) !== slot) return null;
+  refreshReadRangeIndexSlot(key, slot);
+  const draft = {
+    fullPath,
+    fileVersion: version,
+    prefixHash: source.prefixHash,
+    anchors: new Map(source.anchors),
+    ...(Number.isFinite(source.totalLines) ? { totalLines: source.totalLines } : {}),
+  };
+  READ_RANGE_INDEX_DRAFTS.set(draft, { slot, version });
+  return draft;
+}
+
+// Successful readers publish once, before closing their handle. A failed,
+// cancelled or detached scan keeps its observation private. Post-stat failures
+// are cache misses, not reasons to retry the operation or relabel its anchors.
+export async function publishReadRangeIndex(index, handle, signal = null, beforePublish = null) {
+  const owned = READ_RANGE_INDEX_DRAFTS.get(index);
+  if (!owned) return false;
+  READ_RANGE_INDEX_DRAFTS.delete(index);
+  const { slot, version } = owned;
+  const key = canonicalCachePath(slot.fullPath);
+  if (signal?.aborted || READ_RANGE_INDEX_CACHE.get(key) !== slot) return false;
+  try {
+    if (!sameFileVersion(version, await handle.stat()) || !sameFileVersion(version, await stat(slot.fullPath)))
+      return false;
+  } catch {
+    return false;
   }
-  return fresh;
+  if (signal?.aborted || READ_RANGE_INDEX_CACHE.get(key) !== slot) return false;
+  if (slot.prefixHash && index.prefixHash && slot.prefixHash !== index.prefixHash) return false;
+  // The reader's synchronous deadline/cancellation decision belongs after all
+  // awaited validation and outside its best-effort stat catch. Once committed,
+  // the caller must not make a second deadline decision for this scan.
+  beforePublish?.();
+  // Same-version concurrent windows may contribute disjoint anchors. No draft
+  // shares this map, including the one whose successful read is being committed.
+  slot.anchors = new Map([...slot.anchors, ...index.anchors]);
+  slot.prefixHash = index.prefixHash || slot.prefixHash;
+  if (Number.isFinite(index.totalLines)) slot.totalLines = index.totalLines;
+  slot.published = true;
+  refreshReadRangeIndexSlot(key, slot);
+  scheduleReadRangeIndexPersist(slot);
+  return true;
 }
 
 export function nearestReadRangeAnchor(index, offset) {
@@ -309,6 +370,5 @@ export function maybeRecordReadRangeAnchor(index, line, byteOffset) {
   if (line === 0 || line % READ_RANGE_INDEX_STRIDE_LINES === 0) {
     if (index.anchors.get(line) === byteOffset) return;
     index.anchors.set(line, byteOffset);
-    scheduleReadRangeIndexPersist(index);
   }
 }

package/src/runtime/agent/orchestrator/tools/builtin/read-single-render.mjs

@@ -6,6 +6,7 @@
  */
 import * as fsPromises from 'node:fs/promises';
 import { readFile } from 'node:fs/promises';
+import { sameFileVersion } from './file-version.mjs';
 import { READ_PREFIX_HASH_BYTES } from './read-single-fast-paths.mjs';
 import { decodeUtf16Body, isUtf16Encoding } from './snapshot-helpers.mjs';
 
@@ -174,27 +175,24 @@ export async function bufferedReadResult(ctx, { prefetched, readEnc }, helpers)
   const { _cacheSet, _rawContentCacheSet, _recordReadSnapshot } = helpers;
   const rawBuf = prefetched.buf || (await readFile(fullPath));
   const content = decodeReadBuffer(rawBuf, readEnc);
-  // W1 M: re-stat after the async readFile so a concurrent Write that landed
-  // during the read is detected before the cache + snapshot record stale
-  // bytes. A raw-cache hit was already validated against `st`.
-  let st = ctx.st;
-  let readStableForRawCache = true;
+  // A cache hit was checked against this exact version. Fresh IO must
+  // also agree after reading, including ctime and replacement identity.
+  // Never relabel observed bytes with a later stat or certify a failed stat.
+  const st = ctx.st;
+  let readStable = sameFileVersion(st, st) && rawBuf.length === st.size;
   if (!prefetched.fromCache) {
-    let stPostRead;
     try {
-      stPostRead = await fsPromises.stat(fullPath);
+      readStable = readStable && sameFileVersion(st, await fsPromises.stat(fullPath));
     } catch {
-      stPostRead = st;
-    }
-    if (stPostRead.mtimeMs !== st.mtimeMs || stPostRead.size !== st.size) {
-      st = stPostRead;
-      readStableForRawCache = false;
+      readStable = false;
     }
   }
-  const render = renderReadWindow(content, { ...ctx, st }, helpers);
-  const { snapshotMeta, contentPrefixHash } = bufferedReadSnapshotMeta(content, render, ctx, helpers);
-  _cacheSet(cacheKey, render.out, { paths: [fullPath], readSnapshotMeta: snapshotMeta, contentPrefixHash });
-  if (readStableForRawCache) _rawContentCacheSet(fullPath, st, rawBuf);
-  _recordReadSnapshot(fullPath, st, readStateScope, snapshotMeta);
+  const render = renderReadWindow(content, ctx, helpers);
+  if (readStable) {
+    const { snapshotMeta, contentPrefixHash } = bufferedReadSnapshotMeta(content, render, ctx, helpers);
+    _cacheSet(cacheKey, render.out, { paths: [fullPath], readSnapshotMeta: snapshotMeta, contentPrefixHash });
+    _rawContentCacheSet(fullPath, st, rawBuf);
+    _recordReadSnapshot(fullPath, st, readStateScope, snapshotMeta);
+  }
   return render.out;
 }

package/src/runtime/agent/orchestrator/tools/builtin/read-single-tool.mjs

@@ -23,13 +23,15 @@ import { binaryPreviewResult, smartStreamResult, streamRangeResult } from './rea
 import { bufferedReadResult } from './read-single-render.mjs';
 
 // Buffered reads take the whole body up front: the raw-content cache first,
-// else one readFile shared with any in-flight read of the same path.
+// else one readFile shared with in-flight reads of the same path AND version.
 async function prefetchRawBody(fullPath, st, helpers) {
   const { _rawContentCacheGet, _runRawContentInFlight } = helpers;
   const cachedRaw = _rawContentCacheGet ? _rawContentCacheGet(fullPath, st) : null;
   if (cachedRaw) return { buf: cachedRaw, fromCache: true };
   try {
-    const buf = _runRawContentInFlight ? await _runRawContentInFlight(fullPath, readFile) : await readFile(fullPath);
+    const buf = _runRawContentInFlight
+      ? await _runRawContentInFlight(fullPath, readFile, st)
+      : await readFile(fullPath);
     return { buf, fromCache: false };
   } catch {
     return { buf: null, fromCache: false };

package/src/runtime/agent/orchestrator/tools/builtin/read-snapshot-runtime.mjs

@@ -8,7 +8,9 @@ import {
   statMatchesSnapshot,
   decodeRawBufferForSnapshotCheck,
 } from './snapshot-helpers.mjs';
-import { rawContentCacheGet, rawContentCacheSet } from './cache-layers.mjs';
+import { rawContentCacheGet } from './cache-layers.mjs';
+import { fileVersion } from './file-version.mjs';
+import { publishRawContentAfterRead } from './raw-content-publication.mjs';
 import { rememberReadSnapshot, readFilesForScope, readScopeKey, scheduleScopePersist } from './snapshot-store.mjs';
 import {
   isSnapshotStale as isSnapshotStaleImpl,
@@ -38,25 +40,24 @@ export function readTextForSnapshotCheck(fullPath, cache = null, st = null) {
     return cache.content;
   }
   const cachedRaw = getCachedRaw();
+  const before = fileVersion(statForRawCache);
   const rawBuf = cachedRaw || readFileSync(fullPath);
   const content = decodeRawBufferForSnapshotCheck(rawBuf);
   if (cache) {
     cache.rawBuf = rawBuf;
     cache.content = content;
   }
-  if (!cachedRaw && statForRawCache) rawContentCacheSet(fullPath, statForRawCache, rawBuf);
+  if (!cachedRaw) publishRawContentAfterRead(fullPath, before, rawBuf);
   return content;
 }
 
-// The stat identity a snapshot is keyed on: the caller's stat when it has
-// one, else a fresh stat; an unstattable path gets a never-matching identity.
+// Own the observed version. Supplied incomplete evidence must not be
+// replaced by a later stat, which could relabel previously observed bytes.
 function snapshotStatIdentity(fullPath, st) {
   try {
-    const source = st && typeof st.mtimeMs === 'number' ? st : statSync(fullPath);
-    return { mtimeMs: source.mtimeMs, ctimeMs: source.ctimeMs, size: source.size };
+    return fileVersion(st ?? statSync(fullPath));
   } catch {
-    const now = Date.now();
-    return { mtimeMs: now, ctimeMs: now, size: 0 };
+    return null;
   }
 }
 
@@ -119,7 +120,7 @@ function collectRangeHashRows(existing, sameFile, meta) {
 export function recordReadSnapshot(fullPath, st, scope = null, meta = {}) {
   const readFiles = readFilesForScope(scope);
   const identity = snapshotStatIdentity(fullPath, st);
-  const { mtimeMs, ctimeMs, size } = identity;
+  const { mtimeMs, ctimeMs, size, ino, dev } = identity || {};
   const incomingRanges = Array.isArray(meta.ranges) ? meta.ranges : [{ startLine: 1, endLine: Infinity }];
   const replaceExisting = meta.replaceExisting === true;
   const existing = replaceExisting ? null : readFiles.get(fullPath);
@@ -146,7 +147,7 @@ export function recordReadSnapshot(fullPath, st, scope = null, meta = {}) {
     preMutationStat: _omitPreMutationStat,
     ...restMeta
   } = meta;
-  const next = { ...restMeta, mtimeMs, ctimeMs, size, ranges: merged };
+  const next = { ...restMeta, mtimeMs, ctimeMs, size, ino, dev, ranges: merged };
   if (!next.contentHash && sameFile && existing.contentHash) {
     next.contentHash = existing.contentHash;
   }

package/src/runtime/agent/orchestrator/tools/builtin/read-source-windows.mjs

@@ -6,7 +6,7 @@ import {
   getReadRangeIndex,
   nearestReadRangeAnchor,
   maybeRecordReadRangeAnchor,
-  scheduleReadRangeIndexPersist,
+  publishReadRangeIndex,
 } from './read-range-index.mjs';
 import { READ_MAX_SCAN_BYTES, READ_STREAM_TIMEOUT_MS } from './read-constants.mjs';
 
@@ -74,9 +74,8 @@ async function scanSourceWindows(path, intervals, signal) {
       }
       scanned += bytesRead;
       if (scanned > READ_MAX_SCAN_BYTES) throw new Error('source context scan exceeds byte budget');
-      if (position === 0 && !index.prefixHash) {
+      if (position === 0 && index && !index.prefixHash) {
         index.prefixHash = hashText(buffer.subarray(0, bytesRead));
-        scheduleReadRangeIndexPersist(index);
       }
       let start = 0;
       while (start < bytesRead && interval < intervals.length) {
@@ -93,6 +92,9 @@ async function scanSourceWindows(path, intervals, signal) {
       }
       position += bytesRead;
     }
+    // Publication checks after its async stats, immediately before committing.
+    // An unpublished result still owes a final deadline/cancellation check.
+    if (!(await publishReadRangeIndex(index, handle, signal, check))) check();
     return lines;
   } finally {
     await handle.close();