mixdog 1.2.0 → 1.2.1

package/src/runtime/agent/orchestrator/session/synthetic-user-envelope.mjs

@@ -16,6 +16,7 @@
 import { isActualUserInstructionMessage, isInjectedSkillBodyMessage, isSummaryMessage } from './compact/messages.mjs';
 import { ACTIVE_TURN_CONTINUATION_ANCHOR, ACTIVE_TURN_CONTINUATION_SOURCE } from './compact/continuation.mjs';
 import { parseTaskNotification } from '../../../shared/task-notification-envelope.mjs';
+import { isImportedMessage } from './imported-message.mjs';
 
 export const SYNTHETIC_USER_ENVELOPE_TAG = 'mixdog-runtime';
 
@@ -62,7 +63,8 @@ function isAlreadyEnveloped(text) {
 
 // null => a real user instruction (or nothing to wrap); otherwise the kind.
 export function classifySyntheticUserMessage(message) {
-  if (message?.role !== 'user') return null;
+  // Imported prose stays the user's own (unwrapped) voice.
+  if (message?.role !== 'user' || isImportedMessage(message)) return null;
   const text = messageText(message);
   if (!text.trim()) return null;
   if (isAlreadyEnveloped(text)) return null;

package/src/runtime/agent/orchestrator/session/tool-batch/pre-dispatch.mjs

@@ -92,7 +92,7 @@ function crossTurnStub(batch, call, ctSig) {
 // (which spans ONE assistant turn): when the model re-issues an IDENTICAL
 // normalized call that has already failed repeatFailLimit times in a row
 // across iterations, stop re-executing — the result will not change, and
-// each retry burns a full LLM round-trip until the hard iteration cap. The
+// each retry burns a full LLM round-trip with no iteration cap to end it. The
 // call stays unresolved; the guard only skips re-execution.
 function repeatFailureSkip(batch, call, sigs) {
   const { sessionRef, repeatFailLimit } = batch;

package/src/runtime/agent/orchestrator/session/transcript-restore/restore.mjs

@@ -6,7 +6,7 @@
  */
 import { contextMeasurementStats } from '../../../../shared/context-measurement.mjs';
 import { toolResultText } from './tool-result-text.mjs';
-import { restoredUserText } from './user-text.mjs';
+import { restoredUserImageRefs, restoredUserText } from './user-text.mjs';
 import {
   completionCardFromExecution,
   parseModelVisibleCompletionWrapper,
@@ -38,6 +38,7 @@ import {
 } from '../../../../shared/tool-execution-contract.mjs';
 import { toolResultTerminalStatus } from '../../../../shared/tool-status.mjs';
 import { transcriptRouteMetadataFields } from '../../../../shared/transcript-metadata.mjs';
+import { isImportedMessage } from '../imported-message.mjs';
 
 function restoredTranscriptMetadata(message) {
   const value = message?.meta?.transcript;
@@ -62,6 +63,10 @@ function restoredTranscriptMetadata(message) {
     ...(typeof value.sender === 'string' && value.sender ? { sender: value.sender } : {}),
     ...(typeof value.device === 'string' && value.device ? { device: value.device } : {}),
     ...(typeof value.checkpointId === 'string' && value.checkpointId ? { checkpointId: value.checkpointId } : {}),
+    // Skills this user turn explicitly loaded (header selection or `$name`).
+    ...(Array.isArray(value.appliedSkills) && value.appliedSkills.length
+      ? { appliedSkills: value.appliedSkills.filter((name) => typeof name === 'string' && name) }
+      : {}),
     ...(completion ? { completion } : {}),
   };
 }
@@ -322,6 +327,11 @@ function restoredUserTranscriptItems(message, nextId) {
   // skill bodies (meta:'skill'), hook/system reminders, and tag-wrapped context
   // blocks must not restore as user bubbles in any client.
   if (message?.meta === 'skill' || message?.meta === 'hook') return [];
+  // Imported prose renders verbatim: never a control row, card or display rewrite.
+  if (isImportedMessage(message)) {
+    const text = (typeof message.content === 'string' ? message.content : toolResultText(message.content)).trim();
+    return text ? [{ kind: 'user', id: nextId(), text, ...restoredTranscriptMetadata(message) }] : [];
+  }
   const text = restoredUserText(message?.content).trim();
   // Persisted async-completion wrappers ("Async shell task ... finished. Result:
   // > ...") are the only durable record of a background completion — the live
@@ -353,7 +363,16 @@ function restoredUserTranscriptItems(message, nextId) {
   }
   const synthetic = parseSyntheticAgentMessage(text);
   if (!synthetic) {
-    return [{ kind: 'user', id: nextId(), text, ...restoredTranscriptMetadata(message) }];
+    const imageRefs = restoredUserImageRefs(message?.content);
+    return [
+      {
+        kind: 'user',
+        id: nextId(),
+        text,
+        ...restoredTranscriptMetadata(message),
+        ...(imageRefs.length ? { imageRefs } : {}),
+      },
+    ];
   }
   return [restoredNotificationToolItem(synthetic, text, message, nextId, /^(failed|error|killed|cancelled)$/i)];
 }

package/src/runtime/agent/orchestrator/session/transcript-restore/user-text.mjs

@@ -21,9 +21,7 @@ const FEEDBACK_BLOCK = /<visualize_feedback>\n([\s\S]*?)\n?<\/visualize_feedback
 // on the blob itself: the reference's claimed sizeBytes is not trusted.
 const FEEDBACK_MAX_BYTES = 128 * 1024;
 const QUOTED = '("(?:[^"\\\\]|\\\\.)*")';
-const CHOICE_LINE = new RegExp(
-  `· group: (?:${QUOTED}|\\(none\\)) → choice: ${QUOTED}(?: \\(${QUOTED}\\))?$`
-);
+const CHOICE_LINE = new RegExp(`· group: (?:${QUOTED}|\\(none\\)) → choice: ${QUOTED}(?: \\(${QUOTED}\\))?$`);
 
 function unquote(value) {
   if (!value) return '';
@@ -53,7 +51,7 @@ function feedbackDisplay(body) {
       continue;
     }
     if (tweaks) {
-      const change = /^    (.+?) \([^)]*\): (.*) \(was (.*)\)$/.exec(line);
+      const change = /^ {4}(.+?) \([^)]*\): (.*) \(was (.*)\)$/.exec(line);
       if (change) tweaks.push(`${change[1]}: ${change[2]} (was ${change[3]})`);
       else if (line.startsWith('  - tab: ')) {
         tweaks = [];
@@ -118,23 +116,46 @@ function referencedFeedbackText(part) {
   }
 }
 
-export function restoredUserText(content) {
-  if (!Array.isArray(content)) {
-    return withVisualizeFeedbackDisplay(typeof content === 'string' ? content : toolResultText(content));
-  }
+/** The display lines of a stored prompt's parts, and for each image part the
+ *  line that draws it: the composer's metadata line right before it, else a
+ *  bare line of its own (a bare line never stands for the next image). */
+function restoredUserParts(content) {
   const texts = [];
-  let previous = '';
+  const images = [];
+  let pendingMetadata = '';
   for (const part of content) {
-    let text;
     if (part?.type === 'image' || part?.type === 'input_image') {
-      text = IMAGE_METADATA_LINE.test(previous) ? '' : `[Image: ${part.mimeType || part.mediaType || 'image'}]`;
-    } else if (isAttachmentReference(part)) {
-      text = referencedFeedbackText(part);
-    } else {
-      text = toolResultText([part]);
+      let line = pendingMetadata;
+      if (!line) {
+        line = `[Image: ${part.mimeType || part.mediaType || 'image'}]`;
+        texts.push(line);
+      }
+      pendingMetadata = '';
+      images.push({ part, line });
+      continue;
     }
-    previous = text;
+    const text = isAttachmentReference(part) ? referencedFeedbackText(part) : toolResultText([part]);
     if (text) texts.push(text);
+    pendingMetadata = IMAGE_METADATA_LINE.test(text) ? text.trimEnd().split(/\r?\n/).pop().trim() : '';
   }
-  return withVisualizeFeedbackDisplay(texts.join('\n'));
+  return { texts, images };
+}
+
+export function restoredUserText(content) {
+  if (!Array.isArray(content)) {
+    return withVisualizeFeedbackDisplay(typeof content === 'string' ? content : toolResultText(content));
+  }
+  return withVisualizeFeedbackDisplay(restoredUserParts(content).texts.join('\n'));
+}
+
+/** The stored original of each image the restored bubble draws, by the
+ *  `[Image: …]` line that draws it. Every image keeps its slot (one without a
+ *  stored original has no `ref`) so later images do not shift onto it; empty
+ *  when no image has a stored original. */
+export function restoredUserImageRefs(content) {
+  if (!Array.isArray(content)) return [];
+  const slots = restoredUserParts(content).images.map(({ part, line }) =>
+    isAttachmentReference(part) ? { line, ref: part.attachmentRef } : { line }
+  );
+  return slots.some((slot) => slot.ref) ? slots : [];
 }

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool/invocation-plan.mjs

@@ -3,13 +3,25 @@ import { buildPowerShellFilterTeePlan } from '../shell-analysis.mjs';
 import { normalizeErrorMessage } from '../path-diagnostics.mjs';
 import { planDirectExeSpawn } from '../shell-direct-exe.mjs';
 import { POWERSHELL_UTF8_PREFIX } from '../../../../../shared/shell-display.mjs';
+import { renderPowerShellSkillFunction, skillScriptRuntime } from '../../../../../shared/skill-script-runtime.mjs';
 import { buildShellSpawnEnv } from './spawn-env.mjs';
 import { formatShellToolFailure } from './result-format.mjs';
 
+// Every PowerShell model command defines `mixdog-skill-node` first, so the
+// skill launcher runs without the .cmd's cmd.exe argument re-parsing.
+// Injected whenever absent, independent of the UTF-8 prefix deduplication.
+function prefixPowerShellSkillFunction(command) {
+  const fn = renderPowerShellSkillFunction(skillScriptRuntime());
+  const text = String(command || '');
+  return text.trimStart().startsWith(`${fn}\n`) ? text : `${fn}\n${text}`;
+}
+
 function prefixPowerShellUtf8(command) {
   const prefix = POWERSHELL_UTF8_PREFIX;
   const text = String(command || '');
-  return text.trimStart().startsWith(prefix) ? text : `${prefix}\n${text}`;
+  const trimmed = text.trimStart();
+  const body = trimmed.startsWith(prefix) ? trimmed.slice(prefix.length).replace(/^[ \t]*\r?\n/, '') : text;
+  return `${prefix}\n${prefixPowerShellSkillFunction(body)}`;
 }
 
 // How the command reaches the child: a direct exe spawn, PowerShell with the
@@ -54,6 +66,10 @@ export async function planShellInvocation({ command, resolvedSpec, cwd }) {
     plan.wrappedCommand = prefixPowerShellUtf8(plan.teePlan ? plan.teePlan.command : command);
     return plan;
   }
+  if (shellType === 'powershell') {
+    plan.wrappedCommand = prefixPowerShellSkillFunction(command);
+    return plan;
+  }
   if (process.platform !== 'win32' && (shell.includes('bash') || shell.includes('zsh'))) {
     try {
       plan.wrappedCommand = await wrapCommandWithSnapshot(shell, command);

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool/spawn-env.mjs

@@ -1,4 +1,5 @@
 import { resourceAdmission } from '../../../../../shared/resource-admission.mjs';
+import { withSkillLauncherPath } from '../../../../../shared/skill-script-runtime.mjs';
 import {
   applyShellEgressPolicy,
   scrubLoaderVars,
@@ -24,5 +25,8 @@ export function buildShellSpawnEnv(cwd, baseEnv = process.env) {
   scrubLoaderVars(spawnEnv);
   scrubRuntimeRootVars(spawnEnv);
   applyShellEgressPolicy(spawnEnv);
+  // `mixdog-skill-node` (a skill's ${MIXDOG_SKILL_NODE}) resolves in every
+  // model shell; only this env gets the entry, never the daemon's own.
+  withSkillLauncherPath(spawnEnv);
   return spawnEnv;
 }

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-range-index.mjs

@@ -19,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 = () => {};
@@ -99,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 {
@@ -123,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;
@@ -161,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;
+  }
 }
 
-async function persistReadRangeIndex(index, evictedRow = null) {
+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;
+}
+
+// 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);
@@ -199,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;
   }
 }
 
@@ -213,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;
@@ -235,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));
@@ -255,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;
 }
@@ -346,8 +498,7 @@ export async function publishReadRangeIndex(index, handle, signal = null, before
   // 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(fullPath)))
-      return false;
+    if (!sameFileVersion(version, await handle.stat()) || !sameFileVersion(version, await stat(fullPath))) return false;
   } catch {
     return false;
   }

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

@@ -108,7 +108,9 @@ async function symlinkTargetGuard(fullPath, filePath, helpers) {
     if (typeof isSpecialFileStat === 'function' && isSpecialFileStat(targetStat)) {
       return guardResponse('special', helpers, filePath, realTarget);
     }
-  } catch {}
+  } catch {
+    /* vanished target: see above */
+  }
   return null;
 }
 
@@ -138,7 +140,9 @@ export async function statReadTarget(fullPath, filePath, options, helpers) {
       const error = await symlinkTargetGuard(fullPath, filePath, helpers);
       if (error) return { st, error };
     }
-  } catch {}
+  } catch {
+    /* lstat failure is non-fatal: see above */
+  }
   return { st };
 }
 
@@ -148,12 +152,12 @@ export async function statReadTarget(fullPath, filePath, options, helpers) {
  * recovery mode for an ordinary absence probe. Genuine not-found only —
  * EACCES/EPERM etc. keep failure semantics.
  */
-export function readNotFoundResponse(err, { fullPath, filePath, workDir }, helpers) {
+export async function readNotFoundResponse(err, { fullPath, filePath, workDir }, helpers) {
   const { findSimilarFile, normalizeErrorMessage, normalizeOutputPath } = helpers;
   const similar = findSimilarFile(fullPath);
   let hint = similar
     ? appendNotFoundCwdNote(` Did you mean "${normalizeOutputPath(similar)}"?`, workDir, err?.code)
-    : buildNotFoundHint(workDir, fullPath, 'Read', err?.code);
+    : await buildNotFoundHint(workDir, fullPath, 'Read', err?.code);
   hint = finalizeReadFamilyEnoentTail(hint, filePath, err?.code);
   const safeMsg = normalizeErrorMessage(err instanceof Error ? err.message : String(err), workDir);
   if (err?.code === 'ENOENT' || err?.code === 'ENOTDIR') return `[path absent] ${safeMsg}${hint}`;

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

@@ -30,9 +30,10 @@ async function prefetchRawBody(fullPath, st, helpers, forceFresh = false) {
   const cachedRaw = !forceFresh && _rawContentCacheGet ? _rawContentCacheGet(fullPath, st) : null;
   if (cachedRaw) return { buf: cachedRaw, fromCache: true };
   try {
-    const buf = !forceFresh && _runRawContentInFlight
-      ? await _runRawContentInFlight(fullPath, readFile, st)
-      : await readFile(fullPath);
+    const buf =
+      !forceFresh && _runRawContentInFlight
+        ? await _runRawContentInFlight(fullPath, readFile, st)
+        : await readFile(fullPath);
     return { buf, fromCache: false };
   } catch {
     return { buf: null, fromCache: false };
@@ -84,7 +85,7 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
     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);
+    if (!target.st) return await readNotFoundResponse(target.statErr, { fullPath, filePath, workDir }, helpers);
     const st = target.st;
     // Reactive widen + window-history bookkeeping (ranged text reads only).
     if (