mixdog 1.1.2 → 1.2.1

package/src/runtime/agent/orchestrator/tools/builtin/git-command-tool.mjs

@@ -6,7 +6,7 @@ import { tokenizeDirectArgv } from './shell-direct-exe.mjs';
 import { GIT_DIFF_EXIT_SIGNAL_FLAGS } from './bash-tool/benign-exit.mjs';
 import { withBuiltinPathLocks } from './path-locks.mjs';
 import { withAdvisoryLocks } from './advisory-lock.mjs';
-import { withGitRepoReadLock, withGitRepoWriteLock } from './git-repo-rw-lock.mjs';
+import { gitRepoLockKey, withGitRepoReadLock, withGitRepoWriteLock } from './git-repo-rw-lock.mjs';
 import { invalidateBuiltinResultCache } from './cache-layers.mjs';
 import { drainCodeGraphCache } from '../code-graph-state.mjs';
 import { ensureNativeSpawnServer, tryNativeSpawn } from '../lib/native-spawn-client.mjs';
@@ -460,22 +460,22 @@ function nearestGitDir(startDir) {
 
 function cachedRepoRoot(key, plan) {
   if (!key) return null;
-  const root = repoRootCache.get(key);
-  if (!root) return null;
+  const hit = repoRootCache.get(key);
+  if (!hit) return null;
   const nearest = nearestGitDir(plan.cwd);
-  if (!nearest || resolve(nearest) !== resolve(root)) {
+  if (!nearest || resolve(nearest) !== resolve(hit.root)) {
     repoRootCache.delete(key);
     return null;
   }
   repoRootCache.delete(key);
-  repoRootCache.set(key, root);
-  return root;
+  repoRootCache.set(key, hit);
+  return hit;
 }
 
-function rememberRepoRoot(key, root) {
-  if (!key || !root) return;
+function rememberRepoRoot(key, hit) {
+  if (!key || !hit?.root) return;
   repoRootCache.delete(key);
-  repoRootCache.set(key, root);
+  repoRootCache.set(key, hit);
   while (repoRootCache.size > REPO_ROOT_CACHE_MAX) {
     const oldest = repoRootCache.keys().next().value;
     if (oldest === undefined) break;
@@ -483,15 +483,22 @@ function rememberRepoRoot(key, root) {
   }
 }
 
+// `lockKey` is the repository's canonical common git dir: the main checkout
+// and its linked worktrees share one object store and ref namespace, so their
+// git calls serialize on one repository lock (managed worktree mutations take
+// the same key).
 async function resolveRepo(plan, signal) {
   const key = repoRootCacheKey(plan);
   const hit = cachedRepoRoot(key, plan);
-  if (hit) return { root: hit, probe: null };
-  const result = await runGit(plan, ['rev-parse', '--show-toplevel'], { signal });
+  if (hit) return { root: hit.root, lockKey: hit.lockKey, probe: null };
+  const result = await runGit(plan, ['rev-parse', '--show-toplevel', '--path-format=absolute', '--git-common-dir'], {
+    signal,
+  });
   if (succeeded(result)) {
-    const root = cleanText(result.stdout);
-    rememberRepoRoot(key, root);
-    return { root, probe: result };
+    const [root, commonDir] = cleanText(result.stdout).split('\n');
+    const resolved = { root, lockKey: gitRepoLockKey(commonDir || root) };
+    rememberRepoRoot(key, resolved);
+    return { ...resolved, probe: result };
   }
   // A bare repository (mirror clone, server-side repo) has no work tree, so
   // `--show-toplevel` refuses; that is still a repository. Answering
@@ -499,12 +506,13 @@ async function resolveRepo(plan, signal) {
   // to inspect objects it already had.
   if (/must be run in a work tree/i.test(String(result.stderr || ''))) {
     const bare = await runGit(plan, ['rev-parse', '--absolute-git-dir'], { signal });
-    if (!succeeded(bare)) return { root: null, probe: bare };
+    if (!succeeded(bare)) return { root: null, lockKey: null, probe: bare };
     const root = cleanText(bare.stdout);
-    rememberRepoRoot(key, root);
-    return { root, probe: bare };
+    const resolved = { root, lockKey: gitRepoLockKey(root) };
+    rememberRepoRoot(key, resolved);
+    return { ...resolved, probe: bare };
   }
-  return { root: null, probe: result };
+  return { root: null, lockKey: null, probe: result };
 }
 
 function localizeConfigPlan(plan) {
@@ -650,8 +658,9 @@ async function executeGitStage(input, workDir, options = {}) {
   const limit = outputLimit(input?.output_limit, 50);
   const signal = abortSignalOf(options);
   const repo = snapshot.repo;
+  const { lockKey } = await resolveRepo({ ...snapshot.plan, cwd: repo }, signal);
   return withGitRepoWriteLock(
-    repo,
+    lockKey || repo,
     () =>
       withGitMutationLocks(repo, async () => {
         const current = await runStageableDiff(snapshot.plan, snapshot.argv, repo, signal);
@@ -722,7 +731,7 @@ async function executeSingleGitTool(input, workDir, options = {}) {
   // ("git rev-parse exited 128") for a `git status` in a plain directory hid
   // git's own "fatal: not a git repository" line behind a command the model
   // never issued — and re-ran the probe just to build that message.
-  const { root: repo, probe } = await resolveRepo(plan, signal);
+  const { root: repo, lockKey, probe } = await resolveRepo(plan, signal);
   if (!repo) {
     const missing = probe ?? (await runGit(plan, ['rev-parse', '--show-toplevel'], { signal }));
     return commandResult(plan, missing, limit);
@@ -732,7 +741,7 @@ async function executeSingleGitTool(input, workDir, options = {}) {
   if (stageableRequest) prepared.argv.splice(1, 0, '--no-textconv', '--src-prefix=a/', '--dst-prefix=b/');
   if (isReadOnly(plan)) {
     return withGitRepoReadLock(
-      repo,
+      lockKey,
       async () => {
         const result = stageableRequest
           ? await runStageableDiff(plan, prepared.argv, repo, signal)
@@ -754,7 +763,7 @@ async function executeSingleGitTool(input, workDir, options = {}) {
     );
   }
   return withGitRepoWriteLock(
-    repo,
+    lockKey,
     () =>
       withGitMutationLocks(repo, async () => {
         const result = await runGit(plan, prepared.argv, { signal });
@@ -896,4 +905,5 @@ export const _gitCommandInternals = {
   localizeConfigPlan,
   parseCommand,
   prepare,
+  resolveRepo,
 };

package/src/runtime/agent/orchestrator/tools/builtin/git-repo-rw-lock.mjs

@@ -1,10 +1,17 @@
-import { resolve } from 'node:path';
+import { pathKey } from '../../../../shared/worktrees/paths.mjs';
 
 const states = new Map();
 
+// Callers key by the canonical `git rev-parse --git-common-dir`, so the main
+// checkout and every linked worktree of one repository share one lock. The key
+// is the real path (8.3 names, symlinked parents) and case-insensitive on
+// Windows, so two spellings of one directory never hold separate locks.
+export function gitRepoLockKey(repo) {
+  return pathKey(String(repo || '.'));
+}
+
 function keyFor(repo) {
-  const key = resolve(String(repo || '.'));
-  return process.platform === 'win32' ? key.toLowerCase() : key;
+  return gitRepoLockKey(repo);
 }
 
 function stateFor(key) {

package/src/runtime/agent/orchestrator/tools/builtin/lib/list-helpers.mjs

@@ -8,7 +8,7 @@ import { normalizeOutputPath, resolveAgainstCwd } from '../path-utils.mjs';
 /** Report the requested path's result; suggestions never retarget the operation. */
 export async function readFamilyPathEnoentOrError(workDir, fullPath, inputPath, err) {
   const safeMsg = normalizeErrorMessage(err instanceof Error ? err.message : String(err));
-  const hint = buildNotFoundHint(workDir, fullPath, 'List', err?.code);
+  const hint = await buildNotFoundHint(workDir, fullPath, 'List', err?.code);
   const tail = finalizeReadFamilyEnoentTail(hint, inputPath, err?.code);
   // Conclusive absence is the list's ANSWER, not a tool failure (matches
   // read's `[path absent]` and git's `repo:false` policy). Genuine
@@ -78,4 +78,4 @@ export async function countTextFileLines(fullPath, size) {
   } finally {
     await handle?.close().catch(() => {});
   }
-}
+}

package/src/runtime/agent/orchestrator/tools/builtin/path-diagnostics.mjs

@@ -97,7 +97,7 @@ const BASENAME_SCAN_SKIP_DIRS = new Set([
 // directories scanned and wall-clock. `visitEntry` decides what counts as a
 // match and which directories to queue, and returns true to stop reading the
 // current directory (its own limit break).
-function scanByBasename(searchRoot, { limit, maxDirs, deadlineMs }, visitEntry) {
+async function scanByBasename(searchRoot, { limit, maxDirs, deadlineMs }, visitEntry) {
   const matches = [];
   const queue = [searchRoot];
   const stopAt = Date.now() + Math.max(1, deadlineMs);
@@ -112,7 +112,7 @@ function scanByBasename(searchRoot, { limit, maxDirs, deadlineMs }, visitEntry)
     scanned++;
     let entries;
     try {
-      entries = readdirSync(dir, { withFileTypes: true });
+      entries = await readdir(dir, { withFileTypes: true });
     } catch {
       continue;
     }
@@ -127,7 +127,7 @@ function scanByBasename(searchRoot, { limit, maxDirs, deadlineMs }, visitEntry)
   return matches;
 }
 
-export function findFileByBasename(
+export async function findFileByBasename(
   searchRoot,
   fullPath,
   { limit = 3, maxDirs = 6000, deadlineMs = BASENAME_SCAN_DEADLINE_MS } = {}
@@ -136,7 +136,7 @@ export function findFileByBasename(
     if (typeof searchRoot !== 'string' || !searchRoot) return [];
     const target = basename(fullPath).toLowerCase();
     if (!target) return [];
-    return scanByBasename(searchRoot, { limit, maxDirs, deadlineMs }, (dir, ent, matches, queue) => {
+    return await scanByBasename(searchRoot, { limit, maxDirs, deadlineMs }, (dir, ent, matches, queue) => {
       const name = ent.name;
       if (ent.isDirectory()) {
         if (name.startsWith('.') || BASENAME_SCAN_SKIP_DIRS.has(name)) return false;
@@ -205,7 +205,7 @@ export function findBySuffixStrip(searchRoot, fullPath, { maxIterations = 12 } =
 
 // Same as findFileByBasename but for directories sharing the missing path's
 // final segment name (e.g. guessed `src/shared` → the real `lib/shared`).
-export function findDirectoryByBasename(
+export async function findDirectoryByBasename(
   searchRoot,
   fullPath,
   { limit = 3, maxDirs = 6000, deadlineMs = BASENAME_SCAN_DEADLINE_MS } = {}
@@ -214,7 +214,7 @@ export function findDirectoryByBasename(
     if (typeof searchRoot !== 'string' || !searchRoot) return [];
     const target = basename(fullPath).toLowerCase();
     if (!target) return [];
-    return scanByBasename(searchRoot, { limit, maxDirs, deadlineMs }, (dir, ent, matches, queue) => {
+    return await scanByBasename(searchRoot, { limit, maxDirs, deadlineMs }, (dir, ent, matches, queue) => {
       const name = ent.name;
       if (!ent.isDirectory()) return false;
       if (name.toLowerCase() === target) {

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';
@@ -18,6 +19,15 @@ const READ_RANGE_INDEX_SWEEP_CONCURRENCY = 8;
 const READ_RANGE_INDEX_CACHE = new Map();
 const READ_RANGE_INDEX_DRAFTS = new WeakMap();
 const READ_RANGE_INDEX_PERSIST_PENDING = new Map();
+const READ_RANGE_INDEX_INFLIGHT = new Map();
+const READ_RANGE_INDEX_LAST_PERSISTED = new Map();
+// key -> outstanding deletes whose unlink / cancelled write has not settled.
+const READ_RANGE_INDEX_DELETING = new Map();
+let readRangeIndexDeleteSeq = 0;
+const READ_RANGE_INDEX_LAST_PERSISTED_MAX = 256;
+const READ_RANGE_INDEX_WRITE_CONCURRENCY = 2;
+const READ_RANGE_INDEX_WRITE_WAITERS = [];
+let readRangeIndexWritesActive = 0;
 let readRangeIndexDiskSwept = false;
 
 let traceReadRangeIndex = () => {};
@@ -83,7 +93,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);
@@ -98,7 +108,9 @@ async function computePrefixHashForIndex(fullPath, st, handle = null, prefixBuff
       if (!handle) {
         try {
           await fh.close();
-        } catch {}
+        } catch {
+          /* close failure after a completed read is irrelevant */
+        }
       }
     }
   } catch {
@@ -122,14 +134,21 @@ async function loadReadRangeIndexFromDisk(fullPath, st, handle, prefixBuffer) {
   // No existsSync preflight: a missing file surfaces as an ENOENT from
   // readFile below, caught by the same try/catch — one FS pass, not two.
   if (!file || !st) return null;
+  // A delete wins over any disk content: while a cancelled write may still be
+  // landing the file is invisible, and a read that straddled a delete is void.
+  const key = canonicalCachePath(fullPath);
+  const deleteSeq = readRangeIndexDeleteSeq;
+  const deleted = () => READ_RANGE_INDEX_DELETING.has(key) || readRangeIndexDeleteSeq !== deleteSeq;
+  if (deleted()) return null;
   try {
     const row = JSON.parse(await readFile(file, 'utf-8'));
-    if (!readRangeIndexMatches(row, fullPath, st)) return null;
+    if (deleted() || !readRangeIndexMatches(row, fullPath, st)) return null;
     // 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) return null;
     }
+    if (deleted()) return null;
     const anchors = new Map([[0, 0]]);
     for (const entry of row.anchors) {
       if (!Array.isArray(entry) || entry.length < 2) continue;
@@ -160,35 +179,133 @@ function currentReadRangeIndex(index) {
   return !!index?.published && READ_RANGE_INDEX_CACHE.get(canonicalCachePath(index.fullPath)) === index;
 }
 
-function persistReadRangeIndexSync(index) {
+function rememberPersisted(key, text) {
+  READ_RANGE_INDEX_LAST_PERSISTED.delete(key);
+  READ_RANGE_INDEX_LAST_PERSISTED.set(key, text);
+  if (READ_RANGE_INDEX_LAST_PERSISTED.size > READ_RANGE_INDEX_LAST_PERSISTED_MAX) {
+    READ_RANGE_INDEX_LAST_PERSISTED.delete(READ_RANGE_INDEX_LAST_PERSISTED.keys().next().value);
+  }
+}
+
+// job = { index, row }: row is a pre-serialised evicted row (index no longer cached).
+// Returns false only when a write was needed but failed (e.g. lock contended).
+function persistReadRangeIndexSync(job) {
+  const { index, row: evictedRow } = job;
   const file = readRangeIndexFilePath(index?.fullPath);
-  if (!file || !currentReadRangeIndex(index)) return;
+  if (!file || (!evictedRow && !currentReadRangeIndex(index))) return true;
   try {
-    if (!sameFileVersion(index.fileVersion, statSync(index.fullPath))) return;
-    const row = serialiseReadRangeIndex(index);
-    if (row) writeJsonAtomicSync(file, row, { compact: true, lock: true, fsync: false });
-  } catch {}
+    if (!sameFileVersion(evictedRow?.fileVersion || index.fileVersion, statSync(index.fullPath))) return true;
+    const row = evictedRow || serialiseReadRangeIndex(index);
+    if (!row) return true;
+    const key = canonicalCachePath(index.fullPath);
+    const text = JSON.stringify(row);
+    if (READ_RANGE_INDEX_LAST_PERSISTED.get(key) === text) return true;
+    writeJsonAtomicSync(file, row, { compact: true, lock: true, fsync: false });
+    rememberPersisted(key, text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function acquireReadRangeIndexWriteSlot() {
+  if (readRangeIndexWritesActive < READ_RANGE_INDEX_WRITE_CONCURRENCY) {
+    readRangeIndexWritesActive += 1;
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => READ_RANGE_INDEX_WRITE_WAITERS.push(resolve));
+}
+
+function releaseReadRangeIndexWriteSlot() {
+  const next = READ_RANGE_INDEX_WRITE_WAITERS.shift();
+  if (next) next();
+  else readRangeIndexWritesActive -= 1;
 }
 
-async function persistReadRangeIndex(index, evictedRow = null) {
+// One write attempt. `state.epoch` changes when the path is deleted: a write
+// that straddles a delete removes what it just wrote instead of resurrecting it.
+async function persistReadRangeIndexOnce(key, job, state) {
+  const { index, row: evictedRow } = job;
   const file = readRangeIndexFilePath(index?.fullPath);
   if (!file || (!evictedRow && !currentReadRangeIndex(index))) return;
+  const epoch = state.epoch;
+  // Admission precedes every stat/lock so waiting writers hold no file lock.
+  await acquireReadRangeIndexWriteSlot();
   try {
+    if (state.epoch !== epoch || (!evictedRow && !currentReadRangeIndex(index))) return;
     if (!sameFileVersion(evictedRow?.fileVersion || index.fileVersion, await stat(index.fullPath))) return;
     await mkdir(READ_RANGE_INDEX_DISK_DIR, { recursive: true });
-    if (!evictedRow && !currentReadRangeIndex(index)) return;
+    if (state.epoch !== epoch || (!evictedRow && !currentReadRangeIndex(index))) return;
     const row = evictedRow || serialiseReadRangeIndex(index);
-    if (row) await writeJsonAtomicAsync(file, row, { compact: true, lock: true, fsync: false });
-  } catch {}
+    if (!row) return;
+    const text = JSON.stringify(row);
+    if (READ_RANGE_INDEX_LAST_PERSISTED.get(key) === text) return;
+    readRangeIndexPersistStats.concurrent += 1;
+    readRangeIndexPersistStats.maxConcurrent = Math.max(
+      readRangeIndexPersistStats.maxConcurrent,
+      readRangeIndexPersistStats.concurrent
+    );
+    try {
+      await writeJsonAtomicAsync(file, row, { compact: true, lock: true, fsync: false });
+      readRangeIndexPersistStats.writes += 1;
+    } finally {
+      readRangeIndexPersistStats.concurrent -= 1;
+    }
+    if (state.epoch !== epoch) {
+      await unlink(file).catch(() => {});
+      return;
+    }
+    rememberPersisted(key, text);
+  } catch {
+    /* persisting the index is best-effort */
+  } finally {
+    releaseReadRangeIndexWriteSlot();
+  }
+}
+
+// Single-flight per cache file: a request during an in-flight write only
+// replaces the pending job; one follow-up write persists the latest state.
+function requestReadRangeIndexPersist(key, job) {
+  const state = READ_RANGE_INDEX_INFLIGHT.get(key);
+  if (state) {
+    state.next = job;
+    return;
+  }
+  const fresh = { epoch: 0, next: null, cancelWaiters: [] };
+  READ_RANGE_INDEX_INFLIGHT.set(key, fresh);
+  const settleCancelled = () => {
+    for (const resolve of fresh.cancelWaiters.splice(0)) resolve();
+  };
+  void (async () => {
+    try {
+      let cur = job;
+      while (cur) {
+        await persistReadRangeIndexOnce(key, cur, fresh);
+        // A cancelled write has finished (and cleaned up) once Once returns.
+        settleCancelled();
+        cur = fresh.next;
+        fresh.next = null;
+      }
+    } finally {
+      settleCancelled();
+      READ_RANGE_INDEX_INFLIGHT.delete(key);
+    }
+  })();
 }
 
 export function scheduleReadRangeIndexPersist(index) {
   if (!READ_RANGE_INDEX_DISK_DIR || !currentReadRangeIndex(index)) return;
   const key = canonicalCachePath(index.fullPath);
+  const inflight = READ_RANGE_INDEX_INFLIGHT.get(key);
+  if (inflight) {
+    inflight.next = { index, row: null };
+    return;
+  }
   if (READ_RANGE_INDEX_PERSIST_PENDING.has(key)) return;
   const t = setTimeout(() => {
     READ_RANGE_INDEX_PERSIST_PENDING.delete(key);
-    void persistReadRangeIndex(index);
+    const latest = READ_RANGE_INDEX_CACHE.get(key);
+    if (latest) requestReadRangeIndexPersist(key, { index: latest, row: null });
   }, READ_RANGE_INDEX_PERSIST_DEBOUNCE_MS);
   t.unref();
   READ_RANGE_INDEX_PERSIST_PENDING.set(key, t);
@@ -198,10 +315,19 @@ export function flushReadRangeIndexesSync() {
   for (const [key, timer] of READ_RANGE_INDEX_PERSIST_PENDING) {
     try {
       clearTimeout(timer);
-    } catch {}
+    } catch {
+      /* a timer that cannot be cleared must not block the flush */
+    }
     READ_RANGE_INDEX_PERSIST_PENDING.delete(key);
     const index = READ_RANGE_INDEX_CACHE.get(key);
-    if (index) persistReadRangeIndexSync(index);
+    if (index) persistReadRangeIndexSync({ index, row: null });
+  }
+  // Writes queued behind an in-flight one are still pending state at exit.
+  for (const state of READ_RANGE_INDEX_INFLIGHT.values()) {
+    // Keep the job unless it was durably handled: when the async writer holds
+    // the lock, its follow-up still persists it if the process keeps running.
+    const job = state.next;
+    if (job && persistReadRangeIndexSync(job) && state.next === job) state.next = null;
   }
 }
 
@@ -212,11 +338,32 @@ function dropReadRangeIndexSlot(key) {
 }
 
 export function deleteReadRangeIndexForPath(fullPath) {
-  dropReadRangeIndexSlot(canonicalCachePath(fullPath));
+  const key = canonicalCachePath(fullPath);
+  dropReadRangeIndexSlot(key);
+  READ_RANGE_INDEX_LAST_PERSISTED.delete(key);
+  readRangeIndexDeleteSeq += 1;
+  // Disk loads for this path are void until the unlink and any cancelled
+  // in-flight write (which removes its own output) have settled.
+  READ_RANGE_INDEX_DELETING.set(key, (READ_RANGE_INDEX_DELETING.get(key) || 0) + 1);
+  const inflight = READ_RANGE_INDEX_INFLIGHT.get(key);
+  let cancelled = Promise.resolve();
+  if (inflight) {
+    inflight.epoch += 1;
+    inflight.next = null;
+    cancelled = new Promise((resolve) => inflight.cancelWaiters.push(resolve));
+  }
   const file = readRangeIndexFilePath(fullPath);
-  if (file) void unlink(file).catch(() => {});
+  const unlinked = file ? unlink(file).catch(() => {}) : Promise.resolve();
+  void Promise.all([unlinked, cancelled]).then(() => {
+    const left = (READ_RANGE_INDEX_DELETING.get(key) || 1) - 1;
+    if (left > 0) READ_RANGE_INDEX_DELETING.set(key, left);
+    else READ_RANGE_INDEX_DELETING.delete(key);
+  });
 }
 
+// Test observability for write coalescing and the concurrency cap.
+export const readRangeIndexPersistStats = { writes: 0, concurrent: 0, maxConcurrent: 0 };
+
 export async function sweepStaleReadRangeIndexes(directory = READ_RANGE_INDEX_DISK_DIR) {
   if (!directory) return;
   let entries;
@@ -234,8 +381,14 @@ export async function sweepStaleReadRangeIndexes(directory = READ_RANGE_INDEX_DI
       const full = join(directory, name);
       try {
         const st = await stat(full);
-        if (now - st.mtimeMs > READ_RANGE_INDEX_DISK_STALE_MS) await unlink(full);
-      } catch {}
+        if (now - st.mtimeMs > READ_RANGE_INDEX_DISK_STALE_MS) {
+          await unlink(full);
+          // A removed file invalidates the unchanged-content skip.
+          READ_RANGE_INDEX_LAST_PERSISTED.clear();
+        }
+      } catch {
+        /* best-effort sweep: a file that vanished or cannot be removed is skipped */
+      }
     }
   }
   await Promise.all(Array.from({ length: Math.min(READ_RANGE_INDEX_SWEEP_CONCURRENCY, entries.length) }, worker));
@@ -254,7 +407,7 @@ function refreshReadRangeIndexSlot(key, index) {
     // their slot immediately. Disk IO must not delay the foreground lookup.
     const row = serialiseReadRangeIndex(evicted);
     dropReadRangeIndexSlot(oldest);
-    if (row) void persistReadRangeIndex(evicted, row);
+    if (row) requestReadRangeIndexPersist(oldest, { index: evicted, row });
   }
   return index;
 }
@@ -269,6 +422,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 +435,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 +479,32 @@ 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)))
-      return false;
+    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,