mixdog 1.1.1 → 1.2.0

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

@@ -0,0 +1,8 @@
+// The bounded cache validator can certify the whole file only within this
+// byte budget. Larger reads must not reuse metadata-only or prefix-only
+// content/line-position evidence: equal stats can hide edits past the prefix.
+export const READ_PREFIX_HASH_BYTES = 65536;
+
+export function canCacheReadFile(stat) {
+  return Number.isFinite(stat?.size) && stat.size >= 0 && stat.size <= READ_PREFIX_HASH_BYTES;
+}

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

@@ -1,6 +1,7 @@
 import { mkdir, open, readFile, readdir, stat, unlink } from 'node:fs/promises';
 import { statSync } from 'node:fs';
 import { fileVersion, sameFileVersion } from './file-version.mjs';
+import { canCacheReadFile, READ_PREFIX_HASH_BYTES } from './read-cache-policy.mjs';
 import { hashText as sha256Hex } from './hash-utils.mjs';
 import { join, normalize, resolve } from 'node:path';
 import { getPluginData } from '../../config.mjs';
@@ -83,7 +84,7 @@ function readRangeIndexMatches(row, fullPath, version) {
 // `prefixHash` they persist into the anchor index.
 async function computePrefixHashForIndex(fullPath, st, handle = null, prefixBuffer = null) {
   try {
-    const cap = Math.min(Number(st?.size) || 0, 65536);
+    const cap = Math.min(Number(st?.size) || 0, READ_PREFIX_HASH_BYTES);
     if (cap <= 0) return '';
     if (Buffer.isBuffer(prefixBuffer) && prefixBuffer.length === cap) {
       return sha256Hex(prefixBuffer);
@@ -269,6 +270,8 @@ function freshReadRangeIndex(fullPath, version = null) {
 export async function getReadRangeIndex(fullPath, st, handle = null, prefixBuffer = null) {
   const key = canonicalCachePath(fullPath);
   let slot = READ_RANGE_INDEX_CACHE.get(key);
+  // Reserve ownership before awaiting the real stat even when the hint is
+  // large: a now-small file must not renew a lookup invalidated during IO.
   if (!slot) slot = refreshReadRangeIndexSlot(key, freshReadRangeIndex(fullPath));
   const hint = fileVersion(st);
   const readStat = () => (handle ? handle.stat() : stat(fullPath));
@@ -280,8 +283,18 @@ export async function getReadRangeIndex(fullPath, st, handle = null, prefixBuffe
   } catch {
     return null;
   }
-  if (!version || READ_RANGE_INDEX_CACHE.get(key) !== slot) return null;
+  if (!version) return null;
   version = Object.freeze(version);
+  // Metadata and a bounded prefix cannot certify suffix line positions.
+  // Large scans own only this call's handle identity and byte-zero draft:
+  // never load, hash-validate, or publish cross-read anchors/counts.
+  if (!canCacheReadFile(version)) {
+    if (slot && READ_RANGE_INDEX_CACHE.get(key) === slot) dropReadRangeIndexSlot(key);
+    const draft = freshReadRangeIndex(fullPath, version);
+    READ_RANGE_INDEX_DRAFTS.set(draft, { slot: null, version, fullPath });
+    return draft;
+  }
+  if (READ_RANGE_INDEX_CACHE.get(key) !== slot) return null;
   if (!slot.fileVersion) slot.fileVersion = version;
   if (!sameFileVersion(slot.fileVersion, version)) {
     dropReadRangeIndexSlot(key);
@@ -314,27 +327,33 @@ export async function getReadRangeIndex(fullPath, st, handle = null, prefixBuffe
     anchors: new Map(source.anchors),
     ...(Number.isFinite(source.totalLines) ? { totalLines: source.totalLines } : {}),
   };
-  READ_RANGE_INDEX_DRAFTS.set(draft, { slot, version });
+  READ_RANGE_INDEX_DRAFTS.set(draft, { slot, version, fullPath });
   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) {
+// Successful small-file readers publish once, before closing their handle.
+// Large or detached scans remain private, but terminal validation can still
+// certify their producer identity via onValidated. Post-stat failures never
+// authorize relabelling bytes with a later version.
+export async function publishReadRangeIndex(index, handle, signal = null, beforePublish = null, onValidated = 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;
+  const { slot, version, fullPath } = owned;
+  const key = canonicalCachePath(fullPath);
+  if (signal?.aborted) return false;
+  // Detached cache-only publishers must not wait on validation IO. A streamed
+  // result requesting producer certification still owes its terminal stats.
+  if (slot && READ_RANGE_INDEX_CACHE.get(key) !== slot && !onValidated) return false;
   try {
-    if (!sameFileVersion(version, await handle.stat()) || !sameFileVersion(version, await stat(slot.fullPath)))
+    if (!sameFileVersion(version, await handle.stat()) || !sameFileVersion(version, await stat(fullPath)))
       return false;
   } catch {
     return false;
   }
-  if (signal?.aborted || READ_RANGE_INDEX_CACHE.get(key) !== slot) return false;
+  if (signal?.aborted) return false;
+  onValidated?.(fileVersion(version));
+  if (!slot || 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,

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

@@ -7,10 +7,11 @@
  */
 import * as fsPromises from 'node:fs/promises';
 import { readFile } from 'node:fs/promises';
+import { invalidateBuiltinResultCache } from './cache-layers.mjs';
 import { getReadSnapshot } from './read-snapshot-runtime.mjs';
 import { snapshotCoversFullFile, statMatchesSnapshot } from './snapshot-helpers.mjs';
-
-export const READ_PREFIX_HASH_BYTES = 65536;
+import { canCacheReadFile, READ_PREFIX_HASH_BYTES } from './read-cache-policy.mjs';
+export { READ_PREFIX_HASH_BYTES } from './read-cache-policy.mjs';
 
 // A mutation snapshot claims the full file because it knows the bytes it
 // wrote; it proves the session holds the body only when bodyDelivered says so.
@@ -25,14 +26,12 @@ function unchangedStub(filePath, helpers) {
 }
 
 /**
- * Race-guard prefix hash. Coarse filesystem timestamps can collide across a
- * same-size rewrite even with ctime in the cache key, so every cache write
- * records the hash of the first 64KiB (the whole body when it fits) and the
- * next hit recomputes it before trusting the entry. '' on any failure.
+ * Bounded raw-byte hash. Content caches only admit files that fit this
+ * budget, so validation covers their entire body. '' on any failure.
  */
 export async function readPrefixHash(fullPath, st, hashText) {
   try {
-    if (st.size <= READ_PREFIX_HASH_BYTES) return hashText(await readFile(fullPath, 'utf-8'));
+    if (st.size <= READ_PREFIX_HASH_BYTES) return hashText(await readFile(fullPath));
     const fh = await fsPromises.open(fullPath, 'r');
     try {
       const buf = Buffer.allocUnsafe(READ_PREFIX_HASH_BYTES);
@@ -49,15 +48,15 @@ export async function readPrefixHash(fullPath, st, hashText) {
 /**
  * A successful edit/apply_patch leaves a session-scoped full-file snapshot.
  * The model already knows the resulting body from the prior body plus its
- * mutation, so a follow-up Read needs only the stat tuple to prove that no
- * external write landed afterward — the file body is never reopened/hashed
- * merely to return the unchanged stub. `bodyDelivered` guards that the
+ * mutation. Keep the existing small-file stat fast path; a large file's
+ * matching tuple cannot exclude a deep external rewrite, so read it again.
+ * `bodyDelivered` guards that the
  * session actually received this file's body before the mutation: an
  * edit/patch on a file that was never read otherwise answered
  * "[file unchanged]" forever, with the body never delivered to the model.
  */
 export function mutationUnchangedStub({ fullPath, filePath, st, readStateScope, options }, helpers) {
-  if (options?.suppressReadUnchangedStub === true) return null;
+  if (options?.suppressReadUnchangedStub === true || !canCacheReadFile(st)) return null;
   const snapshot = readStateScope ? getReadSnapshot(fullPath, readStateScope) : null;
   const source = String(snapshot?.source || '');
   if (
@@ -71,43 +70,41 @@ export function mutationUnchangedStub({ fullPath, filePath, st, readStateScope,
   return null;
 }
 
-// Single-pass cache-hit guard. The cache key already pins mtimeMs+ctimeMs+
-// size, so a hit can differ only when all metadata collides across a rewrite
-// — caught by re-hashing the on-disk body. ≤64KiB: one full-body read
-// validates whichever hash the entry carries (prefix == full at this size;
-// the exact contentHash is preferred). >64KiB: contentHash may still be
-// stored, but validating it would sha a multi-megabyte body on every check,
-// so only the 64KiB head prefix is checked — it catches same-mtime/same-size
-// rewrites within the first 64KiB (the common case); writes through
-// edit/apply_patch/write invalidate by path and shell mutationMode='global'
-// wipes the caches, bounding stale risk past the head.
+// Only whole-body bounded validation can admit a result-cache hit.
+// The decoded snapshot hash remains a separate contract, never a fallback
+// after a raw-byte hash mismatch.
 async function cachedEntryStillValid(cachedEntry, fullPath, st, hashText) {
   const prefixHash = cachedEntry.contentPrefixHash;
   const snapHash = cachedEntry.readSnapshotMeta?.contentHash;
-  if (!prefixHash && !snapHash) return true;
-  if (st.size <= READ_PREFIX_HASH_BYTES) {
-    try {
-      const freshHash = hashText(await readFile(fullPath, 'utf-8'));
-      return !!freshHash && freshHash === (snapHash || prefixHash);
-    } catch {
-      return false;
-    }
+  if (prefixHash) {
+    const curHash = await readPrefixHash(fullPath, st, hashText);
+    return !!curHash && curHash === prefixHash;
+  }
+  if (!snapHash) return true;
+  try {
+    const freshHash = hashText(await readFile(fullPath, 'utf-8'));
+    return !!freshHash && freshHash === snapHash;
+  } catch {
+    return false;
   }
-  if (!prefixHash) return true;
-  const curHash = await readPrefixHash(fullPath, st, hashText);
-  return !!curHash && curHash === prefixHash;
 }
 
 /**
  * Validated result-cache hit.
- * @returns {Promise<{ result: unknown } | null>} null when there is no entry
- *   or the entry lost the race guard (fresh read follows).
+ * @returns {Promise<{ result: unknown } | { rejected: true } | null>}
+ *   A rejected entry requires fresh IO even if an older reader republishes.
  */
 export async function readCachedResult({ cacheKey, fullPath, filePath, st, readStateScope, options }, helpers) {
+  if (!canCacheReadFile(st)) return null;
   const { _cacheGetEntry, _hashText, _recordReadSnapshot, classifyResultKind } = helpers;
   const cachedEntry = _cacheGetEntry(cacheKey);
   if (cachedEntry === null) return null;
-  if (!(await cachedEntryStillValid(cachedEntry, fullPath, st, _hashText))) return null;
+  if (!(await cachedEntryStillValid(cachedEntry, fullPath, st, _hashText))) {
+    // The metadata no longer proves byte identity. Detach raw/in-flight
+    // reuse too, or the fresh-read fallback can return the rejected body.
+    invalidateBuiltinResultCache([fullPath]);
+    return { rejected: true };
+  }
   // Cross-session stub guard: RESULT_CACHE is process-global, so a cache hit
   // can be an entry SET BY ANOTHER SESSION whose body this conversation never
   // received. The stub assumes the full body is already in a prior

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

@@ -7,7 +7,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 { canCacheReadFile, READ_PREFIX_HASH_BYTES } from './read-cache-policy.mjs';
 import { decodeUtf16Body, isUtf16Encoding } from './snapshot-helpers.mjs';
 
 /**
@@ -133,13 +133,12 @@ function renderReadWindow(content, ctx, helpers) {
 
 /**
  * Describe exactly which lines the model saw. A full-file view pins the
- * whole body with one contentHash (also reused as the ≤64KiB race-guard
- * prefix hash — the same SHA-256 over the identical `content`); anything
+ * whole decoded body with one contentHash; anything
  * narrower records rangeHashes over the visible window so
  * snapshotCoversFullFile never green-lights an overwrite against bytes the
  * read never returned.
  */
-function bufferedReadSnapshotMeta(content, render, ctx, helpers) {
+function bufferedReadSnapshotMeta(content, rawBuf, render, ctx, helpers) {
   const { offset, limit } = ctx;
   const { _hashText, _rangeHashesForReadRanges } = helpers;
   const { lineCount, renderedLineCount, smartTruncated, smartVisibleRanges, byteCapTruncated } = render;
@@ -158,11 +157,9 @@ function bufferedReadSnapshotMeta(content, render, ctx, helpers) {
     ...(isFullFileView ? { contentHash: fullContentHash } : {}),
     ...(rangeHashes.length > 0 ? { rangeHashes } : {}),
   };
-  // For files ≤64KiB the prefix hash equals the full-content hash; otherwise
-  // hash the 64KiB head (enough to detect a same-mtime / same-size rewrite of
-  // any bytes within the first 64KiB — the common case).
-  const head = content.length <= READ_PREFIX_HASH_BYTES ? content : content.slice(0, READ_PREFIX_HASH_BYTES);
-  const contentPrefixHash = head === content && fullContentHash ? fullContentHash : _hashText(head);
+  // Cache validation hashes on-disk bytes, unlike the decoded snapshot.
+  // Use a byte boundary for every encoding, matching the streaming path.
+  const contentPrefixHash = canCacheReadFile(ctx.st) ? _hashText(rawBuf.subarray(0, READ_PREFIX_HASH_BYTES)) : '';
   return { snapshotMeta, contentPrefixHash };
 }
 
@@ -189,9 +186,11 @@ export async function bufferedReadResult(ctx, { prefetched, readEnc }, helpers)
   }
   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);
+    const { snapshotMeta, contentPrefixHash } = bufferedReadSnapshotMeta(content, rawBuf, render, ctx, helpers);
+    if (canCacheReadFile(st)) {
+      _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-stream.mjs

@@ -6,23 +6,25 @@
  */
 import { formatBinaryReadPreviewFromBuffer } from './binary-file.mjs';
 import { readPrefixHash } from './read-single-fast-paths.mjs';
+import { canCacheReadFile } from './read-cache-policy.mjs';
 
 export function binaryPreviewResult(ctx, preview, helpers) {
   const { fullPath, filePath, st, cacheKey, readStateScope } = ctx;
   const { normalizeOutputPath, _recordReadSnapshot, _cacheSet } = helpers;
   const { text, snapshotMeta } = formatBinaryReadPreviewFromBuffer(preview, normalizeOutputPath(filePath), st.size);
   _recordReadSnapshot(fullPath, st, readStateScope, snapshotMeta);
-  _cacheSet(cacheKey, text, { paths: [fullPath], readSnapshotMeta: snapshotMeta });
+  if (canCacheReadFile(st)) _cacheSet(cacheKey, text, { paths: [fullPath], readSnapshotMeta: snapshotMeta });
   return text;
 }
 
 async function commitStreamResult(ctx, out, snapshotMeta, prefixHash, helpers) {
   const { fullPath, st, cacheKey, readStateScope } = ctx;
   const { _cacheSet, _recordReadSnapshot, _hashText } = helpers;
-  // Prefix hash for the race guard on the next cache hit; async so a 64KB
-  // read never blocks the event loop on the large-file streaming path.
-  const contentPrefixHash = prefixHash || (await readPrefixHash(fullPath, st, _hashText));
-  _cacheSet(cacheKey, out, { paths: [fullPath], readSnapshotMeta: snapshotMeta, contentPrefixHash });
+  // Do not reopen a large file just to hash a prefix that cannot certify it.
+  if (canCacheReadFile(st)) {
+    const contentPrefixHash = prefixHash || (await readPrefixHash(fullPath, st, _hashText));
+    _cacheSet(cacheKey, out, { paths: [fullPath], readSnapshotMeta: snapshotMeta, contentPrefixHash });
+  }
   _recordReadSnapshot(fullPath, st, readStateScope, snapshotMeta);
   return out;
 }
@@ -50,7 +52,8 @@ export async function streamRangeResult(ctx, { source, fileHandle, prefixBuffer
     const ranges =
       res.firstEmitted && res.lastEmitted ? [{ startLine: res.firstEmitted, endLine: res.lastEmitted }] : [];
     const snapshotMeta = { source, ranges, rangeHashes: _rangeHashesFromRenderedReadText(res.text, ranges) };
-    return await commitStreamResult(ctx, res.text, snapshotMeta, res.prefixHash, helpers);
+    if (!res.readSnapshotStat) return res.text;
+    return await commitStreamResult({ ...ctx, st: res.readSnapshotStat }, res.text, snapshotMeta, res.prefixHash, helpers);
   } catch (err) {
     return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
   }

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

@@ -21,15 +21,16 @@ import { mutationUnchangedStub, pathSnapshotUnchangedStub, readCachedResult } fr
 import { readMediaFile } from './read-single-media.mjs';
 import { binaryPreviewResult, smartStreamResult, streamRangeResult } from './read-single-stream.mjs';
 import { bufferedReadResult } from './read-single-render.mjs';
+import { runReadCachePublication } from './cache-layers.mjs';
 
 // Buffered reads take the whole body up front: the raw-content cache first,
 // else one readFile shared with in-flight reads of the same path AND version.
-async function prefetchRawBody(fullPath, st, helpers) {
+async function prefetchRawBody(fullPath, st, helpers, forceFresh = false) {
   const { _rawContentCacheGet, _runRawContentInFlight } = helpers;
-  const cachedRaw = _rawContentCacheGet ? _rawContentCacheGet(fullPath, st) : null;
+  const cachedRaw = !forceFresh && _rawContentCacheGet ? _rawContentCacheGet(fullPath, st) : null;
   if (cachedRaw) return { buf: cachedRaw, fromCache: true };
   try {
-    const buf = _runRawContentInFlight
+    const buf = !forceFresh && _runRawContentInFlight
       ? await _runRawContentInFlight(fullPath, readFile, st)
       : await readFile(fullPath);
     return { buf, fromCache: false };
@@ -39,6 +40,12 @@ async function prefetchRawBody(fullPath, st, helpers) {
 }
 
 export async function executeSingleReadTool(args, workDir, readStateScope, options = {}, helpers = {}) {
+  // A coalesced batch must not publish its union window as delivered evidence.
+  // Its internal recorder holds the producer's lease until the caller slots
+  // are sliced; ordinary reads retain their existing snapshot path.
+  if (typeof options._readSnapshotRecorder === 'function') {
+    helpers = { ...helpers, _recordReadSnapshot: options._readSnapshotRecorder };
+  }
   const {
     parseLineLimitArg,
     parseOffsetArg,
@@ -64,69 +71,76 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
   const fullPath = resolveAgainstCwd(filePath, workDir);
   const resolvedRejected = readResolvedPathGuard(fullPath, helpers);
   if (resolvedRejected) return resolvedRejected;
-  const hasOffsetArg = args.offset !== undefined && args.offset !== null;
-  const hasLimitArg = args.limit !== undefined && args.limit !== null;
-  const hasRangeArgs = hasOffsetArg || hasLimitArg;
-  const wantFull = args.full === true;
-  let offset = parseOffsetArg(args.offset);
-  // full:true bypasses the default 2000-line cap so the whole file can be
-  // returned in one call; the byte cap still emits a compact truncation
-  // marker when rendered bytes overflow READ_MAX_OUTPUT_BYTES.
-  let limit = parseLineLimitArg(args.limit, wantFull ? Infinity : 2000);
-  let widenNote = '';
-  const target = await statReadTarget(fullPath, filePath, options, helpers);
-  if (target.error) return target.error;
-  if (!target.st) return readNotFoundResponse(target.statErr, { fullPath, filePath, workDir }, helpers);
-  const st = target.st;
-  // Reactive widen + window-history bookkeeping (ranged text reads only).
-  if (
-    readStateScope &&
-    typeof readStateScope === 'object' &&
-    hasOffsetArg &&
-    hasLimitArg &&
-    Number.isFinite(limit) &&
-    limit > 0
-  ) {
-    ({ offset, limit, widenNote } = widenReadWindow(readStateScope, fullPath, { offset, limit }));
-  }
-  const unchanged = mutationUnchangedStub({ fullPath, filePath, st, readStateScope, options }, helpers);
-  if (unchanged) return unchanged;
-  // MEDIA-WINS: media dispatch runs before every cache/snapshot fast path so
-  // a stale text entry can never short-circuit a media read.
-  const media = await readMediaFile({ fullPath, st, args, readStateScope, options, hasRangeArgs }, helpers);
-  if (media) return media.result;
-  const cacheKey = `read|${fullPath}|${st.mtimeMs}|${st.ctimeMs}|${st.size}|${hasOffsetArg ? offset : 'd'}|${hasLimitArg ? limit : 'd'}|${wantFull ? 'f' : 's'}|base:${readOffsetBase}|budget:${readMaxOutputBytes}`;
-  const ctx = {
-    fullPath,
-    filePath,
-    st,
-    cacheKey,
-    readStateScope,
-    options,
-    offset,
-    limit,
-    hasRangeArgs,
-    wantFull,
-    readMaxOutputBytes,
-    readOffsetBase,
-    widenNote,
-  };
-  const cached = await readCachedResult(ctx, helpers);
-  if (cached) return cached.result;
-  const pathStub = await pathSnapshotUnchangedStub(ctx, helpers);
-  if (pathStub) return pathStub;
-  // Pre-read size cap: a small error response beats 25K tokens of truncated
-  // content (Anthropic #21841 reverted truncation). With offset/limit the
-  // requested window streams instead; without range args the cap still
-  // refuses so the small-file default path can't pull megabytes by accident.
-  const preferRangeStream =
-    hasRangeArgs && !wantFull && (options?.forceReadRangeStream === true || st.size > READ_STREAM_RANGE_MIN_BYTES);
-  const preferSmartStream = !hasRangeArgs && !wantFull && st.size >= READ_SMART_STREAM_MIN_BYTES;
-  const preferBufferedRead = st.size <= READ_MAX_SIZE_BYTES && !preferRangeStream && !preferSmartStream;
-  const prefetched = preferBufferedRead
-    ? await prefetchRawBody(fullPath, st, helpers)
-    : { buf: null, fromCache: false };
-  return await readBodyResult(ctx, { prefetched, preferRangeStream, preferSmartStream }, helpers);
+  return runReadCachePublication(fullPath, async () => {
+    const hasOffsetArg = args.offset !== undefined && args.offset !== null;
+    const hasLimitArg = args.limit !== undefined && args.limit !== null;
+    const hasRangeArgs = hasOffsetArg || hasLimitArg;
+    const wantFull = args.full === true;
+    let offset = parseOffsetArg(args.offset);
+    // full:true bypasses the default 2000-line cap so the whole file can be
+    // returned in one call; the byte cap still emits a compact truncation
+    // marker when rendered bytes overflow READ_MAX_OUTPUT_BYTES.
+    let limit = parseLineLimitArg(args.limit, wantFull ? Infinity : 2000);
+    let widenNote = '';
+    const target = await statReadTarget(fullPath, filePath, options, helpers);
+    if (target.error) return target.error;
+    if (!target.st) return readNotFoundResponse(target.statErr, { fullPath, filePath, workDir }, helpers);
+    const st = target.st;
+    // Reactive widen + window-history bookkeeping (ranged text reads only).
+    if (
+      readStateScope &&
+      typeof readStateScope === 'object' &&
+      hasOffsetArg &&
+      hasLimitArg &&
+      Number.isFinite(limit) &&
+      limit > 0
+    ) {
+      ({ offset, limit, widenNote } = widenReadWindow(readStateScope, fullPath, { offset, limit }));
+    }
+    const unchanged = mutationUnchangedStub({ fullPath, filePath, st, readStateScope, options }, helpers);
+    if (unchanged) return unchanged;
+    // MEDIA-WINS: media dispatch runs before every cache/snapshot fast path so
+    // a stale text entry can never short-circuit a media read.
+    const media = await readMediaFile({ fullPath, st, args, readStateScope, options, hasRangeArgs }, helpers);
+    if (media) return media.result;
+    const cacheKey = `read|${fullPath}|${st.mtimeMs}|${st.ctimeMs}|${st.size}|${hasOffsetArg ? offset : 'd'}|${hasLimitArg ? limit : 'd'}|${wantFull ? 'f' : 's'}|base:${readOffsetBase}|budget:${readMaxOutputBytes}`;
+    const ctx = {
+      fullPath,
+      filePath,
+      st,
+      cacheKey,
+      readStateScope,
+      options,
+      offset,
+      limit,
+      hasRangeArgs,
+      wantFull,
+      readMaxOutputBytes,
+      readOffsetBase,
+      widenNote,
+    };
+    const cached = await readCachedResult(ctx, helpers);
+    if (cached && !cached.rejected) return cached.result;
+    const finishRead = async () => {
+      const pathStub = await pathSnapshotUnchangedStub(ctx, helpers);
+      if (pathStub) return pathStub;
+      // Pre-read size cap: a small error response beats 25K tokens of truncated
+      // content (Anthropic #21841 reverted). With offset/limit the
+      // requested window streams instead; without range args the cap still
+      // refuses so the small-file default path can't pull megabytes by accident.
+      const preferRangeStream =
+        hasRangeArgs && !wantFull && (options?.forceReadRangeStream === true || st.size > READ_STREAM_RANGE_MIN_BYTES);
+      const preferSmartStream = !hasRangeArgs && !wantFull && st.size >= READ_SMART_STREAM_MIN_BYTES;
+      const preferBufferedRead = st.size <= READ_MAX_SIZE_BYTES && !preferRangeStream && !preferSmartStream;
+      const prefetched = preferBufferedRead
+        ? await prefetchRawBody(fullPath, st, helpers, cached?.rejected === true)
+        : { buf: null, fromCache: false };
+      return await readBodyResult(ctx, { prefetched, preferRangeStream, preferSmartStream }, helpers);
+    };
+    // Rejection invalidates this lease too. Only the fresh continuation gets
+    // a new generation; readers still holding earlier bytes remain fenced.
+    return cached?.rejected ? runReadCachePublication(fullPath, finishRead) : finishRead();
+  });
 }
 
 // Body read: binary/encoding inspection, then the streamed (range or smart)

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

@@ -8,8 +8,9 @@ import {
   statMatchesSnapshot,
   decodeRawBufferForSnapshotCheck,
 } from './snapshot-helpers.mjs';
-import { rawContentCacheGet } from './cache-layers.mjs';
+import { canPublishReadCache, rawContentCacheGet } from './cache-layers.mjs';
 import { fileVersion } from './file-version.mjs';
+import { canCacheReadFile } from './read-cache-policy.mjs';
 import { publishRawContentAfterRead } from './raw-content-publication.mjs';
 import { rememberReadSnapshot, readFilesForScope, readScopeKey, scheduleScopePersist } from './snapshot-store.mjs';
 import {
@@ -118,11 +119,15 @@ function collectRangeHashRows(existing, sameFile, meta) {
 }
 
 export function recordReadSnapshot(fullPath, st, scope = null, meta = {}) {
+  if (!canPublishReadCache(fullPath)) return;
   const readFiles = readFilesForScope(scope);
   const identity = snapshotStatIdentity(fullPath, st);
   const { mtimeMs, ctimeMs, size, ino, dev } = identity || {};
   const incomingRanges = Array.isArray(meta.ranges) ? meta.ranges : [{ startLine: 1, endLine: Infinity }];
-  const replaceExisting = meta.replaceExisting === true;
+  // Equal metadata cannot carry a large file's old ranges or full-body proof
+  // into a new observation. Batched windows arrive together as one snapshot.
+  const freshLargeRead = !canCacheReadFile(identity) && !isMutationSource(meta.source);
+  const replaceExisting = meta.replaceExisting === true || freshLargeRead;
   const existing = replaceExisting ? null : readFiles.get(fullPath);
   const sameFile = existing && statMatchesSnapshot(identity, existing) && Array.isArray(existing.ranges);
   // A mutation snapshot claims the full range because it knows the bytes it
@@ -161,7 +166,7 @@ export function recordReadSnapshot(fullPath, st, scope = null, meta = {}) {
   const bodyDelivered = resolveBodyDelivered({
     next,
     meta,
-    priorSnapshot: readFiles.get(fullPath),
+    priorSnapshot: freshLargeRead ? null : readFiles.get(fullPath),
     identity,
     incomingIsGrep,
   });

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

@@ -1,4 +1,4 @@
-import { open } from 'node:fs/promises';
+import { open, stat } from 'node:fs/promises';
 import { hashText } from './hash-utils.mjs';
 import { runResultCacheInFlight } from './cache-layers.mjs';
 import {
@@ -9,6 +9,7 @@ import {
   publishReadRangeIndex,
 } from './read-range-index.mjs';
 import { READ_MAX_SCAN_BYTES, READ_STREAM_TIMEOUT_MS } from './read-constants.mjs';
+import { canCacheReadFile } from './read-cache-policy.mjs';
 
 // Raw, one-based inclusive source windows. Callers merge/sort intervals first.
 // Unlike the display reader, this never truncates a line into usable patch text.
@@ -16,6 +17,9 @@ export async function readSourceWindows(path, intervals, { signal } = {}) {
   signal?.throwIfAborted();
   if (!intervals.length) return new Map();
   const snapshot = intervals.map(({ start, end }) => ({ start, end }));
+  // A later caller must not join a scan that already observed old deep bytes.
+  // Preserve small-file fan-out and its per-subscriber cancellation contract.
+  if (!canCacheReadFile(await stat(path))) return scanSourceWindows(path, snapshot, signal);
   const key = `source-windows:${canonicalCachePath(path)}:${JSON.stringify(snapshot.map((w) => [w.start, w.end]))}`;
   const shared = await runResultCacheInFlight(
     key,

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

@@ -1,5 +1,6 @@
 import { createReadStream } from 'node:fs';
 import { sameFileVersion } from './file-version.mjs';
+import { canCacheReadFile, READ_PREFIX_HASH_BYTES } from './read-cache-policy.mjs';
 import * as fsPromises from 'node:fs/promises';
 import { createInterface } from 'node:readline';
 import { capShellOutput } from './shell-output.mjs';
@@ -55,7 +56,7 @@ async function readRangeFromHandle(fh, fullPath, offset, limit, stHint, hooks) {
   const anchor = nearestReadRangeAnchor(rangeIndex, offset);
   // Keep the first read large enough for the existing 64 KiB prefix hash.
   // Grow only while seeking distant lines; nearby windows avoid 1 MiB reads.
-  const MIN_CHUNK_BYTES = 64 * 1024;
+  const MIN_CHUNK_BYTES = READ_PREFIX_HASH_BYTES;
   const MAX_CHUNK_BYTES = 1024 * 1024;
   let chunkBytes = MIN_CHUNK_BYTES;
   let buf = Buffer.allocUnsafe(chunkBytes);
@@ -83,10 +84,14 @@ async function readRangeFromHandle(fh, fullPath, offset, limit, stHint, hooks) {
   while (!stop) {
     checkDeadline();
     if (buf.length < chunkBytes) buf = Buffer.allocUnsafe(chunkBytes);
+    // Process all bytes inside the absolute cap before rejecting a deeper
+    // window. At the cap, a one-byte probe distinguishes EOF from a partial
+    // final line; any returned byte is rejected before reaching the collector.
+    const readBytes = Math.min(chunkBytes, Math.max(1, READ_MAX_SCAN_BYTES - position));
     const prefix = position === 0 && Buffer.isBuffer(prefixBuffer) ? prefixBuffer : null;
     const bytesRead = prefix?.length
-      ? prefix.copy(buf, 0, 0, Math.min(prefix.length, chunkBytes))
-      : (await fh.read(buf, 0, chunkBytes, position)).bytesRead;
+      ? prefix.copy(buf, 0, 0, Math.min(prefix.length, readBytes))
+      : (await fh.read(buf, 0, readBytes, position)).bytesRead;
     if (bytesRead === 0) break;
     const chunkStart = position;
     position += bytesRead;
@@ -94,7 +99,7 @@ async function readRangeFromHandle(fh, fullPath, offset, limit, stHint, hooks) {
       throw new Error(`read scan exceeds ${READ_MAX_SCAN_BYTES} bytes`);
     }
     if (!prefixHash && chunkStart === 0) {
-      prefixHash = hashText(buf.subarray(0, Math.min(bytesRead, 65536)));
+      prefixHash = hashText(buf.subarray(0, Math.min(bytesRead, READ_PREFIX_HASH_BYTES)));
       if (rangeIndex && rangeIndex.prefixHash !== prefixHash) {
         rangeIndex.prefixHash = prefixHash;
       }
@@ -131,7 +136,10 @@ async function readRangeFromHandle(fh, fullPath, offset, limit, stHint, hooks) {
     if (start < bytesRead) lines.appendPartial(buf.subarray(start, bytesRead));
   }
   if (!stop) lines.finishTail();
-  if (!(await publishReadRangeIndex(rangeIndex, fh, null, checkDeadline))) checkDeadline();
+  let readSnapshotStat = null;
+  if (!(await publishReadRangeIndex(rangeIndex, fh, null, checkDeadline, (version) => {
+    readSnapshotStat = version;
+  }))) checkDeadline();
 
   ioTraceDone('read_range_stream', traceStart, {
     pathHash: hashText(fullPath).slice(0, 12),
@@ -147,6 +155,7 @@ async function readRangeFromHandle(fh, fullPath, offset, limit, stHint, hooks) {
     firstEmitted: lines.firstEmitted,
     lastEmitted: lines.lastEmitted,
     prefixHash,
+    readSnapshotStat,
   };
 }
 
@@ -269,8 +278,8 @@ export async function countLogicalLinesBytesSync(fullPath, size, stHint = null,
       const toRead = Math.min(buf.length, size - position);
       const { bytesRead } = await fh.read(buf, 0, toRead, position);
       if (bytesRead <= 0) break;
-      if (position === 0 && rangeIndex && !rangeIndex.prefixHash) {
-        rangeIndex.prefixHash = hashText(buf.subarray(0, Math.min(bytesRead, 65536)));
+      if (position === 0 && rangeIndex && canCacheReadFile(rangeIndex.fileVersion) && !rangeIndex.prefixHash) {
+        rangeIndex.prefixHash = hashText(buf.subarray(0, Math.min(bytesRead, READ_PREFIX_HASH_BYTES)));
       }
       let start = 0;
       while (start < bytesRead) {