mixdog 0.9.96 → 0.9.97

package/src/runtime/agent/orchestrator/session/store-summary-reader.mjs

@@ -345,6 +345,8 @@ function normalizedRow(row, heartbeatAt = 0) {
         preview: cleanText(row.preview),
         generation: typeof row.generation === 'number' ? row.generation : 0,
         implicitBashSessionId: row.implicitBashSessionId || null,
+        storageMtimeMs: positiveNumber(row.storageMtimeMs, 0),
+        storageSize: positiveNumber(row.storageSize, 0),
         detachedReason: row.detachedReason || null,
     };
 }
@@ -412,10 +414,15 @@ function sessionHeartbeatMtimes() {
  * Returns `null` when the directory itself is NOT enumerable (unreadable
  * stat / readdir): that is not "no sessions", and the caller must keep the
  * authority it already has (the index rows) instead of publishing an empty
- * catalog. `indexRowsById` carries those rows so a single UNREADABLE session
- * file also retains its last known row instead of vanishing.
+ * catalog. `indexRowsById` carries those rows so unchanged files can reuse the
+ * durable summary and a single UNREADABLE file retains its last known row
+ * instead of vanishing.
  */
-function scanSessionFiles(heartbeatMtimes = sessionHeartbeatMtimes(), indexRowsById = new Map()) {
+function scanSessionFiles(
+    heartbeatMtimes = sessionHeartbeatMtimes(),
+    indexRowsById = new Map(),
+    { indexMtimeMs = 0, forceRead = false } = {},
+) {
     const directory = join(dataDir(), 'sessions');
     const dirProbe = probePath(directory);
     if (dirProbe.state === PROBE_ABSENT) return [];
@@ -426,13 +433,37 @@ function scanSessionFiles(heartbeatMtimes = sessionHeartbeatMtimes(), indexRowsB
     for (const filename of entries) {
         if (!filename.endsWith('.json')) continue;
         const storageId = filename.slice(0, -5);
-        const read = readTextFile(join(directory, filename));
+        const path = join(directory, filename);
+        const retained = indexRowsById.get(storageId);
+        const probe = probePath(path);
+        // Provably gone: the row legitimately disappears with the file.
+        if (probe.state === PROBE_ABSENT) continue;
+        if (probe.state !== PROBE_PRESENT) {
+            if (retained) rows.push(retained);
+            continue;
+        }
+        if (!forceRead && retained) {
+            const exactFingerprint = retained.storageMtimeMs > 0
+                && retained.storageSize > 0
+                && retained.storageMtimeMs === probe.mtimeMs
+                && retained.storageSize === probe.size;
+            // Older v2 rows predate per-file fingerprints. Their global index
+            // timestamp remains a one-release compatibility fallback; every
+            // later save/rebuild stamps the exact (mtimeMs,size) pair.
+            const legacyUnchanged = retained.storageMtimeMs === 0
+                && indexMtimeMs > 0
+                && (probe.mtimeMs || 0) <= indexMtimeMs;
+            if (exactFingerprint || legacyUnchanged) {
+                rows.push(retained);
+                continue;
+            }
+        }
+        const read = readTextFile(path);
         // Provably gone: the row legitimately disappears with the file.
         if (read.state === PROBE_ABSENT) continue;
         if (read.state !== PROBE_PRESENT) {
             // Exists and could not be read (EACCES/EIO): retain the last known
             // row rather than let a transient IO error delete it from view.
-            const retained = indexRowsById.get(storageId);
             if (retained) rows.push(retained);
             continue;
         }
@@ -440,36 +471,16 @@ function scanSessionFiles(heartbeatMtimes = sessionHeartbeatMtimes(), indexRowsB
         // record or a foreign identity is not this file's session.
         const record = readTopLevelLifecycleRecord(read.text);
         if (isLifecycleUnreadable(record) || record.id !== storageId) continue;
-        const row = rowFromSession(record.doc, heartbeatMtimes.get(record.id) || 0);
+        const summary = rowFromSession(record.doc, heartbeatMtimes.get(record.id) || 0);
+        const row = summary
+            ? { ...summary, storageMtimeMs: probe.mtimeMs, storageSize: probe.size }
+            : null;
         if (row) rows.push(row);
     }
     return leadRowsWithAgentHeartbeat(rows).sort((left, right) =>
         (right.lastUsedAt || right.updatedAt || 0) - (left.lastUsedAt || left.updatedAt || 0));
 }
 
-function sessionFilesAreNewerThan(indexPath) {
-    const directory = join(dataDir(), 'sessions');
-    if (probePath(directory).state !== PROBE_PRESENT) return false;
-    const indexProbe = probePath(indexPath);
-    // Only a PROVABLY absent index makes the files newer by definition. An
-    // index that exists but cannot be stat'ed (EACCES/EIO) is still the
-    // authority we failed to consult — claiming "files are newer" there would
-    // replace the whole catalog on the strength of an IO error.
-    if (indexProbe.state === PROBE_ABSENT) return true;
-    if (indexProbe.state !== PROBE_PRESENT) return false;
-    const indexMtime = indexProbe.mtimeMs || 0;
-    let entries;
-    try { entries = readdirSync(directory); } catch { return false; }
-    for (const filename of entries) {
-        if (!filename.endsWith('.json')) continue;
-        // Absent (raced unlink) and unreadable both prove nothing about
-        // freshness: only an observed newer mtime does.
-        const probe = probePath(join(directory, filename));
-        if (probe.state === PROBE_PRESENT && (probe.mtimeMs || 0) > indexMtime) return true;
-    }
-    return false;
-}
-
 export function listStoredSessionSummaries(options = {}) {
     const heartbeatMtimes = sessionHeartbeatMtimes();
     const indexPath = join(dataDir(), 'session-summaries.json');
@@ -478,6 +489,7 @@ export function listStoredSessionSummaries(options = {}) {
     // an individual session file cannot be read.
     const indexRowsById = new Map();
     let indexRows = null;
+    let indexMtimeMs = 0;
     const indexRead = readTextFile(indexPath);
     if (indexRead.state === PROBE_PRESENT) {
         try {
@@ -490,25 +502,30 @@ export function listStoredSessionSummaries(options = {}) {
                 indexRows = leadRowsWithAgentHeartbeat(normalizedRows)
                     .sort((left, right) =>
                         (right.lastUsedAt || right.updatedAt || 0) - (left.lastUsedAt || left.updatedAt || 0));
+                const indexProbe = probePath(indexPath);
+                if (indexProbe.state === PROBE_PRESENT) indexMtimeMs = indexProbe.mtimeMs || 0;
             }
         } catch { /* malformed sidecar: the files below are the authority */ }
     }
     // An index that EXISTS but is unreadable (EACCES/EIO) is neither missing
     // nor empty: the scan below still runs, and when IT cannot enumerate
     // either, the catalog reports nothing rather than inventing an empty truth.
-    const scan = () => scanSessionFiles(heartbeatMtimes, indexRowsById);
-    if (options.refreshFromStorage === true) return scan() ?? indexRows ?? [];
+    const scan = (forceRead = false) => scanSessionFiles(
+        heartbeatMtimes,
+        indexRowsById,
+        { indexMtimeMs, forceRead },
+    );
+    if (options.refreshFromStorage === true) return scan(true) ?? indexRows ?? [];
     if (indexRows) {
-        // A crashed/non-blocking sidecar writer can leave a valid but old,
-        // non-empty index indefinitely. Detect only newer session JSONs
-        // (heartbeat churn does not count), then recover read-only from the
-        // authoritative files without trying to rewrite the stuck index.
-        if (options.rebuildIfMissing !== false && sessionFilesAreNewerThan(indexPath)) {
-            return scan() ?? indexRows;
-        }
-        if (indexRows.length > 0 || options.rebuildIfMissing === false) return indexRows;
+        if (options.rebuildIfMissing === false) return indexRows;
+        // Enumerate identities to detect deletions, stat known files, and parse
+        // only rows newer than the index. Cold-start cost therefore scales with
+        // changed transcripts rather than total transcript bytes.
+        return scan(false) ?? indexRows;
     }
-    return options.rebuildIfMissing === false ? [] : (scan() ?? indexRows ?? []);
+    // Missing/malformed index is the sole cold path that must rebuild every
+    // summary from canonical session bytes.
+    return options.rebuildIfMissing === false ? [] : (scan(true) ?? indexRows ?? []);
 }
 
 /** Exact, fail-closed existence check for a durable session address.
@@ -567,7 +584,7 @@ export async function readStoredSessionTranscript(id, options = {}) {
         restoreTranscriptItems,
         sessionContextSnapshotProjection,
     } = await import(
-        '../../../../tui/engine/session-api-ext.mjs'
+        '../../../../tui/session/session-api-ext.mjs'
     );
     let preparedContextProjection = null;
     try {
@@ -724,7 +741,7 @@ export async function createStoredSessionLiveViewer(id, options = {}) {
         clearStreamingTail: () => commit({ streamingTail: null }),
     };
     const { createLiveShare, liveSharePipePath } = await import(
-        '../../../../tui/engine/live-share.mjs'
+        '../../../../tui/session/live-share.mjs'
     );
     const share = createLiveShare({
         ownerSessionId: () => '',

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

@@ -257,8 +257,9 @@ export async function processToolBatch(ctx) {
                     _executeOk = true;
                 } else {
                 // Fallback for providers that don't stream tool calls early:
-                // start the whole remaining batch in parallel, including
-                // apply_patch and shell.
+                // dispatch the whole remaining batch. The eager dispatcher
+                // keeps independent calls parallel while making shell wait
+                // for earlier apply_patch calls.
                 if (isParallelDispatchable(call.name)) {
                     startEagerRun(calls, callIndex, _duplicateCallIds);
                 }

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

@@ -506,38 +506,24 @@ export async function executeBashTool(args, workDir, options = {}) {
         { backgroundTasksDisabled: _bgTasksDisabled },
     );
     if (longForegroundHint) return formatShellToolFailure(longForegroundHint);
-    // Auto-background threshold. Reference-CLI parity: sync commands run to
-    // their timeout without any default auto-promotion, so the default is 0
-    // (disabled) for ALL callers. It is an explicit opt-in only: set
-    // MIXDOG_SHELL_AUTO_BACKGROUND_MS (positive ms) to re-enable detaching a
-    // still-running foreground one-shot into a tracked shell-job. When enabled,
-    // the value stays a soft hint clamped below `timeout` so the hard ceiling
-    // remains a separate, later bound. Never applies to run_in_background
-    // (already detached) or persistent sessions (handled far above).
-    // Promotion threshold (Codex `yield_time_ms` / CC startBackgrounding
-    // analogue). Previously 0 = OFF, so every long command held the turn open
-    // to the full foreground timeout and, at the cap, produced a wasted wait.
-    // 30 s keeps ordinary builds/tests inline (measured shell p90 ~ 18 s) while
-    // detaching the long tail (measured: 111 calls/day above 30 s, 30 of them
-    // burning the entire 120 s cap) as a tracked job with partial output.
+    // Main-agent blocking budget. A timeout is the command's total deadline,
+    // not permission to hold the conversation open for that whole duration:
+    // after 15 s a still-running command becomes a tracked background task and
+    // completion is pushed to the owner. Explicit timeouts keep their remaining
+    // deadline after promotion. Never applies to run_in_background (already
+    // detached), persistent sessions, or commands barred from backgrounding.
     // MIXDOG_SHELL_AUTO_BACKGROUND_MS overrides; an explicit 0 disables.
     const _autoBgEnvRaw = process.env.MIXDOG_SHELL_AUTO_BACKGROUND_MS;
     const _autoBgEnvMs = Number(_autoBgEnvRaw);
     const DEFAULT_AUTO_BACKGROUND_MS = (_autoBgEnvRaw != null && String(_autoBgEnvRaw).trim() !== ''
       && Number.isFinite(_autoBgEnvMs) && _autoBgEnvMs >= 0)
       ? Math.floor(_autoBgEnvMs)
-      : 30_000;
+      : 15_000;
     // Gate on backgroundOnTimeout rather than just `runInBackground`: it already
     // encodes "promotion is available for this command" (not detached, background
     // tasks enabled, command shape allows it), so the soft threshold can never
     // promote something the hard timeout would refuse to.
-    // An EXPLICIT caller timeout is a deliberate "I intend to wait this long"
-    // (a long build/test/install), so the soft threshold never overrides it —
-    // the call stays inline until its own deadline, where backgroundOnTimeout
-    // still promotes instead of killing. Auto-promotion therefore only applies
-    // to the OMITTED-timeout default, which is exactly the case where nobody
-    // declared how long the command should be allowed to hold the turn.
-    const autoBackgroundMs = (!backgroundOnTimeout || hasExplicitTimeout || DEFAULT_AUTO_BACKGROUND_MS <= 0)
+    const autoBackgroundMs = (!backgroundOnTimeout || DEFAULT_AUTO_BACKGROUND_MS <= 0)
       ? 0
       : Math.min(DEFAULT_AUTO_BACKGROUND_MS, timeout);
 
@@ -712,6 +698,10 @@ export async function executeBashTool(args, workDir, options = {}) {
             // tracked background job (unlimited) instead of killing it.
             backgroundOnTimeout,
             promotedTimeoutMs,
+            // Soft/interrupt promotion happens before the foreground cap.
+            // Preserve an explicit total deadline by passing it separately;
+            // omitted-timeout promotions retain the existing unlimited job.
+            backgroundDeadlineMs: hasExplicitTimeout ? totalTimeout : 0,
             // Threaded so an auto-backgrounded foreground job is stamped with
             // the dispatching terminal's claude.exe pid (per-terminal scope).
             clientHostPid: options?.clientHostPid,

package/src/runtime/agent/orchestrator/tools/builtin/binary-file.mjs

@@ -1,17 +1,33 @@
 import { closeSync, openSync, readSync } from 'fs';
+import { open } from 'fs/promises';
+
+const HEAD_CAP = 64 * 1024;
+const TAIL_SIZE = 4 * 1024;
+
+function hasUtf16Bom(buf, length = buf?.length || 0) {
+    return length >= 2
+        && ((buf[0] === 0xff && buf[1] === 0xfe)
+            || (buf[0] === 0xfe && buf[1] === 0xff));
+}
+
+function containsNull(buf, length = buf?.length || 0) {
+    for (let i = 0; i < length; i++) {
+        if (buf[i] === 0) return true;
+    }
+    return false;
+}
 
 // Binary detection: reading a PNG / ELF / zip / compressed blob as utf-8
 // pollutes the context with U+FFFD characters and wastes tokens. Sample the
 // head and tail of the file and look for a null byte — the canonical signal
 // that the file is not plain text. Head window scales with file size:
 // min(fileSize, 64KB) head + 4KB tail, so a 250KB file with a null byte at
-// 9KB or 249KB is caught equally. The sampling is synchronous and cheap
-// relative to the 256KB read budget it guards.
+// 9KB or 249KB is caught equally. This synchronous form remains for legacy
+// mode readers. The main read path uses inspectBinaryFile(), which performs
+// the same probes asynchronously.
 // Callers inside the ≤READ_MAX_SIZE_BYTES branch should pass st.size so the
 // tail probe fires; callers above the cap pass the real size from err.size.
 export function isBinaryFile(fullPath, fileSize = 0) {
-    const HEAD_CAP = 64 * 1024;   // 64 KB max head window
-    const TAIL_SIZE = 4 * 1024;   // 4 KB tail probe
     const headBytes = fileSize > 0 ? Math.min(fileSize, HEAD_CAP) : HEAD_CAP;
     let fd = null;
     try {
@@ -25,20 +41,14 @@ export function isBinaryFile(fullPath, fileSize = 0) {
         // (detectReadEncodingFromBuffer/decodeReadBuffer support utf16le and
         // utf16be), so exempt it rather than reject the file as binary.
         // FF FE = UTF-16LE, FE FF = UTF-16BE.
-        if (nHead >= 2
-            && ((headBuf[0] === 0xff && headBuf[1] === 0xfe)
-                || (headBuf[0] === 0xfe && headBuf[1] === 0xff))) return false;
-        for (let i = 0; i < nHead; i++) {
-            if (headBuf[i] === 0) return true;
-        }
+        if (hasUtf16Bom(headBuf, nHead)) return false;
+        if (containsNull(headBuf, nHead)) return true;
         // Tail probe (only when file is larger than head window)
         if (fileSize > headBytes && fileSize > TAIL_SIZE) {
             const tailOffset = fileSize - TAIL_SIZE;
             const tailBuf = Buffer.allocUnsafe(TAIL_SIZE);
             const nTail = readSync(fd, tailBuf, 0, TAIL_SIZE, tailOffset);
-            for (let i = 0; i < nTail; i++) {
-                if (tailBuf[i] === 0) return true;
-            }
+            if (containsNull(tailBuf, nTail)) return true;
         }
         return false;
     } catch {
@@ -48,8 +58,71 @@ export function isBinaryFile(fullPath, fileSize = 0) {
     }
 }
 
+/** Classify an already-loaded whole file without another open/read cycle. */
+export function isBinaryBuffer(buf, fileSize = buf?.length || 0) {
+    if (!Buffer.isBuffer(buf) || buf.length === 0) return false;
+    const size = fileSize > 0 ? Math.min(fileSize, buf.length) : buf.length;
+    const headBytes = Math.min(size, HEAD_CAP);
+    if (hasUtf16Bom(buf, headBytes)) return false;
+    if (containsNull(buf, headBytes)) return true;
+    if (size > headBytes && size > TAIL_SIZE) {
+        const tail = buf.subarray(Math.max(0, size - TAIL_SIZE), size);
+        if (containsNull(tail)) return true;
+    }
+    return false;
+}
+
+/**
+ * Async binary probe that keeps one file handle for head, tail, and preview.
+ * Returns the head bytes even when the null marker is in the tail so callers
+ * can render a hex preview without reopening the file.
+ */
+export async function inspectBinaryFile(fullPath, fileSize = 0, { previewBytes = 256 } = {}) {
+    const headBytes = fileSize > 0 ? Math.min(fileSize, HEAD_CAP) : HEAD_CAP;
+    let fh;
+    try {
+        fh = await open(fullPath, 'r');
+        const headBuf = Buffer.allocUnsafe(Math.max(0, headBytes));
+        const { bytesRead: nHead } = await fh.read(headBuf, 0, headBytes, 0);
+        const head = headBuf.subarray(0, nHead);
+        const preview = head.subarray(0, Math.min(previewBytes, nHead));
+        if (nHead === 0 || hasUtf16Bom(head, nHead)) return { isBinary: false, preview };
+        if (containsNull(head, nHead)) return { isBinary: true, preview };
+        if (fileSize > headBytes && fileSize > TAIL_SIZE) {
+            const tailBuf = Buffer.allocUnsafe(TAIL_SIZE);
+            const { bytesRead: nTail } = await fh.read(
+                tailBuf,
+                0,
+                TAIL_SIZE,
+                fileSize - TAIL_SIZE,
+            );
+            if (containsNull(tailBuf, nTail)) return { isBinary: true, preview };
+        }
+        return { isBinary: false, preview };
+    } catch {
+        return { isBinary: false, preview: Buffer.alloc(0) };
+    } finally {
+        if (fh) { try { await fh.close(); } catch {} }
+    }
+}
+
 const BINARY_PREVIEW_BYTES = 256;
 
+export function formatBinaryReadPreviewFromBuffer(
+    buffer,
+    displayPath,
+    fileSize,
+    { previewBytes = BINARY_PREVIEW_BYTES } = {},
+) {
+    const source = Buffer.isBuffer(buffer) ? buffer : Buffer.alloc(0);
+    const slice = source.subarray(0, Math.min(previewBytes, source.length));
+    const hex = Array.from(slice).map((b) => b.toString(16).padStart(2, '0')).join(' ');
+    const disp = displayPath || '(binary file)';
+    const note = `binary, ${fileSize} byte${fileSize === 1 ? '' : 's'}`;
+    const text = `${disp}\n${note}\n${hex || '(empty)'}`;
+    return { text, snapshotMeta: { source: 'read_hex', ranges: [] } };
+}
+
 /** Short hex preview for read when null bytes mark the file as binary. */
 export function formatBinaryReadPreview(fullPath, displayPath, fileSize, { previewBytes = BINARY_PREVIEW_BYTES } = {}) {
     const n = Math.max(0, Math.min(previewBytes, fileSize > 0 ? fileSize : previewBytes));
@@ -58,12 +131,12 @@ export function formatBinaryReadPreview(fullPath, displayPath, fileSize, { previ
         fd = openSync(fullPath, 'r');
         const buf = Buffer.alloc(n);
         const bytesRead = readSync(fd, buf, 0, n, 0);
-        const slice = buf.subarray(0, bytesRead);
-        const hex = Array.from(slice).map((b) => b.toString(16).padStart(2, '0')).join(' ');
-        const disp = displayPath || fullPath;
-        const note = `binary, ${fileSize} byte${fileSize === 1 ? '' : 's'}`;
-        const text = `${disp}\n${note}\n${hex || '(empty)'}`;
-        return { text, snapshotMeta: { source: 'read_hex', ranges: [] } };
+        return formatBinaryReadPreviewFromBuffer(
+            buf.subarray(0, bytesRead),
+            displayPath || fullPath,
+            fileSize,
+            { previewBytes },
+        );
     } catch {
         const disp = displayPath || fullPath;
         return {

package/src/runtime/agent/orchestrator/tools/builtin/fs-reachability.mjs

@@ -47,6 +47,6 @@ export async function assertPathReachable(path, deadlineMs = FS_REACHABILITY_DEA
 // the wall-clock cost is one deadline, not N.
 export async function assertPathsReachable(paths, deadlineMs = FS_REACHABILITY_DEADLINE_MS) {
     const list = Array.isArray(paths) ? paths.filter((p) => typeof p === 'string' && p.length) : [];
-    if (list.length === 0) return;
-    await Promise.all(list.map((p) => assertPathReachable(p, deadlineMs)));
+    if (list.length === 0) return [];
+    return await Promise.all(list.map((p) => assertPathReachable(p, deadlineMs)));
 }

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

@@ -18,10 +18,12 @@ import {
     cacheGet,
     cacheSet,
     getCachedReadOnlyStat,
+    lstatPathsForMtime,
     statCacheSet,
     statPathsForMtime,
     registerCacheInvalidationListener,
 } from './cache-layers.mjs';
+import { formatListSize, formatMtime } from './list-formatting.mjs';
 import {
     compileSimpleGlob,
     NOISE_DIR_NAMES,

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

@@ -1,4 +1,4 @@
-import { readFileSync, statSync } from 'fs';
+import { readFile, stat } from 'fs/promises';
 import { extname } from 'path';
 import {
   API_IMAGE_MAX_BASE64_SIZE,
@@ -36,14 +36,14 @@ export function imageMimeForPath(p) {
 // sharp absent / resize failed: GRACEFUL fallback to the legacy
 // pass-through-with-cap behaviour (refuse over-cap originals with an isError
 // text result, else emit the raw base64 image block). No throw on missing sharp.
-export async function readImageAsContent(fullPath, displayPath) {
+export async function readImageAsContent(fullPath, displayPath, preflightStat = null) {
   const mimeType = imageMimeForPath(fullPath);
   if (!mimeType) return null;
   let st;
-  try { st = statSync(fullPath); } catch { return null; }
+  try { st = preflightStat || await stat(fullPath); } catch { return null; }
 
   let buf;
-  try { buf = readFileSync(fullPath); } catch { return null; }
+  try { buf = await readFile(fullPath); } catch { return null; }
   if (buf.length === 0) {
     return {
       content: [{ type: 'text', text: `Error: image "${displayPath}" is empty (0 bytes).` }],

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

@@ -1,4 +1,3 @@
-import { lstatSync, realpathSync, readdirSync, statSync } from 'fs';
 import * as fsPromises from 'fs/promises';
 import { readFile } from 'fs/promises';
 import { extname } from 'path';
@@ -7,7 +6,11 @@ import { buildNotFoundHint, finalizeReadFamilyEnoentTail, tryReadFamilyEnoentRed
 import { getReadSnapshot } from './read-snapshot-runtime.mjs';
 import { recordReadPathRedirect } from './snapshot-store.mjs';
 import { snapshotCoversFullFile, statMatchesSnapshot } from './snapshot-helpers.mjs';
-import { formatBinaryReadPreview } from './binary-file.mjs';
+import {
+    formatBinaryReadPreviewFromBuffer,
+    inspectBinaryFile,
+    isBinaryBuffer,
+} from './binary-file.mjs';
 
 function snapshotBodyWasReturnedByRead(snapshot) {
     return String(snapshot?.source || '').startsWith('read');
@@ -27,22 +30,27 @@ function withSymbolReadNote(text, args) {
 // decoding. utf8-with-BOM (EF BB BF) keeps the utf-8 decoder; its leading
 // U+FEFF is stripped for display downstream, so bomLen is reported but not
 // applied for utf8.
+function detectReadEncodingFromBuffer(head) {
+    const n = head?.length || 0;
+    if (n >= 2 && head[0] === 0xff && head[1] === 0xfe) {
+        return { encoding: 'utf16le', bomLen: 2 };
+    }
+    if (n >= 2 && head[0] === 0xfe && head[1] === 0xff) {
+        return { encoding: 'utf16be', bomLen: 2 };
+    }
+    if (n >= 3 && head[0] === 0xef && head[1] === 0xbb && head[2] === 0xbf) {
+        return { encoding: 'utf8', bomLen: 3 };
+    }
+    return { encoding: 'utf8', bomLen: 0 };
+}
+
 async function detectReadEncoding(fullPath) {
     let fh;
     try {
         fh = await fsPromises.open(fullPath, 'r');
         const head = Buffer.alloc(3);
         const { bytesRead: n } = await fh.read(head, 0, 3, 0);
-        if (n >= 2 && head[0] === 0xff && head[1] === 0xfe) {
-            return { encoding: 'utf16le', bomLen: 2 };
-        }
-        if (n >= 2 && head[0] === 0xfe && head[1] === 0xff) {
-            return { encoding: 'utf16be', bomLen: 2 };
-        }
-        if (n >= 3 && head[0] === 0xef && head[1] === 0xbb && head[2] === 0xbf) {
-            return { encoding: 'utf8', bomLen: 3 };
-        }
-        return { encoding: 'utf8', bomLen: 0 };
+        return detectReadEncodingFromBuffer(head.subarray(0, n));
     } catch {
         return { encoding: 'utf8', bomLen: 0 };
     } finally {
@@ -164,7 +172,7 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
     let st;
     let _statErr;
     try {
-        st = statSync(fullPath);
+        st = options?._preflightStats?.get?.(fullPath) || await fsPromises.stat(fullPath);
     } catch (err) {
         // Fall through to the existing similar-file recovery path below.
         st = null;
@@ -174,7 +182,7 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
         if (st.isDirectory()) {
             let entries = [];
             try {
-                entries = readdirSync(fullPath, { withFileTypes: true })
+                entries = (await fsPromises.readdir(fullPath, { withFileTypes: true }))
                     .slice(0, 20)
                     .map((entry) => `${entry.name}${entry.isDirectory() ? '/' : ''}`);
             } catch { /* best-effort preview */ }
@@ -191,14 +199,14 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
             return `Error: cannot read special file (FIFO / character / block device / socket): ${normalizeOutputPath(filePath)}`;
         // R1+R2: realpath the resolved path so a symlink → /dev/zero (or any
         // other blocked device, UNC, or Windows reserved name) is caught on
-        // the REAL target, not the symlink name. lstatSync detects whether
-        // the entry IS a symlink first so realpathSync is only called when
+        // the REAL target, not the symlink name. lstat detects whether
+        // the entry IS a symlink first so realpath is only called when
         // it would actually differ — saves a syscall on the common case.
         try {
-            const _lst = lstatSync(fullPath);
+            const _lst = await fsPromises.lstat(fullPath);
             if (_lst && typeof _lst.isSymbolicLink === 'function' && _lst.isSymbolicLink()) {
                 let _realTarget = null;
-                try { _realTarget = realpathSync(fullPath); } catch { _realTarget = null; }
+                try { _realTarget = await fsPromises.realpath(fullPath); } catch { _realTarget = null; }
                 if (_realTarget && _realTarget !== fullPath) {
                     if (isBlockedDevicePath(_realTarget))
                         return `Error: cannot read device file via symlink (would block or produce infinite output): ${normalizeOutputPath(filePath)} → ${normalizeOutputPath(_realTarget)}`;
@@ -211,7 +219,7 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
                     // the target stat could differ from the link stat in
                     // pathological cases (replaced under us).
                     try {
-                        const _rst = statSync(_realTarget);
+                        const _rst = await fsPromises.stat(_realTarget);
                         if (typeof isSpecialFileStat === 'function' && isSpecialFileStat(_rst))
                             return `Error: cannot read special file via symlink (FIFO / character / block device / socket): ${normalizeOutputPath(filePath)} → ${normalizeOutputPath(_realTarget)}`;
                     } catch { /* if the target is gone, let the normal path surface ENOENT */ }
@@ -430,11 +438,42 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
     // large UTF-16LE+BOM file is recognized as text up front and routed to
     // the bounded in-memory utf16le path below, never mis-decoded as utf-8
     // or rejected by the utf-8 streaming/binary branch (Bug 1).
-    const _readEnc = await detectReadEncoding(fullPath);
+    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;
+    let _prefetchedRawBuf = null;
+    let _prefetchedRawFromCache = false;
+    if (_preferBufferedRead) {
+        const _cachedRaw = _rawContentCacheGet ? _rawContentCacheGet(fullPath, st) : null;
+        if (_cachedRaw) {
+            _prefetchedRawBuf = _cachedRaw;
+            _prefetchedRawFromCache = true;
+        } else {
+            try { _prefetchedRawBuf = await readFile(fullPath); } catch { _prefetchedRawBuf = null; }
+        }
+    }
+    const _readEnc = _prefetchedRawBuf
+        ? detectReadEncodingFromBuffer(_prefetchedRawBuf.subarray(0, Math.min(3, _prefetchedRawBuf.length)))
+        : await detectReadEncoding(fullPath);
     // UTF-16 (LE or BE) reads share one constraint: the streaming/binary
     // paths decode chunks as utf-8, so a BOM-flagged UTF-16 file must route
     // to the bounded in-memory decode below regardless of byte order.
     const _isUtf16 = _readEnc.encoding === 'utf16le' || _readEnc.encoding === 'utf16be';
+    let _binaryInspection = null;
+    const _inspectBinary = async () => {
+        if (_binaryInspection) return _binaryInspection;
+        _binaryInspection = _prefetchedRawBuf
+            ? {
+                isBinary: isBinaryBuffer(_prefetchedRawBuf, st.size),
+                preview: _prefetchedRawBuf.subarray(0, Math.min(256, _prefetchedRawBuf.length)),
+            }
+            : await inspectBinaryFile(fullPath, st.size);
+        return _binaryInspection;
+    };
     if (st.size > READ_MAX_SIZE_BYTES) {
         // .pdf/.ipynb were already dispatched up front (MEDIA-WINS), so this
         // >10MiB branch only handles the non-media text path from here on.
@@ -450,8 +489,13 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
         if (!hasRangeArgs) {
             return `Error: file size ${st.size} bytes exceeds ${READ_MAX_SIZE_BYTES}-byte cap.`;
         }
-        if (isBinaryFile(fullPath, st.size)) {
-            const { text, snapshotMeta } = formatBinaryReadPreview(fullPath, normalizeOutputPath(filePath), st.size);
+        const _binary = await _inspectBinary();
+        if (_binary.isBinary) {
+            const { text, snapshotMeta } = formatBinaryReadPreviewFromBuffer(
+                _binary.preview,
+                normalizeOutputPath(filePath),
+                st.size,
+            );
             _recordReadSnapshot(fullPath, st, readStateScope, snapshotMeta);
             _cacheSet(cacheKey, text, { paths: [fullPath], readSnapshotMeta: snapshotMeta });
             return withSymbolReadNote(text, args);
@@ -510,11 +554,18 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
     // unambiguous TEXT signal, so classify it as utf16le up front and skip
     // NUL rejection. (_readEnc was detected above, before the >10MiB size
     // branch, so the large-file path can classify utf16le.)
-    if (!_isUtf16 && isBinaryFile(fullPath, st.size)) {
-        const { text, snapshotMeta } = formatBinaryReadPreview(fullPath, normalizeOutputPath(filePath), st.size);
-        _recordReadSnapshot(fullPath, st, readStateScope, snapshotMeta);
-        _cacheSet(cacheKey, text, { paths: [fullPath], readSnapshotMeta: snapshotMeta });
-        return withSymbolReadNote(text, args);
+    if (!_isUtf16) {
+        const _binary = await _inspectBinary();
+        if (_binary.isBinary) {
+            const { text, snapshotMeta } = formatBinaryReadPreviewFromBuffer(
+                _binary.preview,
+                normalizeOutputPath(filePath),
+                st.size,
+            );
+            _recordReadSnapshot(fullPath, st, readStateScope, snapshotMeta);
+            _cacheSet(cacheKey, text, { paths: [fullPath], readSnapshotMeta: snapshotMeta });
+            return withSymbolReadNote(text, args);
+        }
     }
     // Whole-file reads above READ_WHOLE_FILE_MAX_BYTES use stream smart-elide
     // (then READ_MAX_OUTPUT_BYTES truncation) instead of refusing. Absolute
@@ -588,8 +639,7 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
         }
     }
     try {
-        const cachedRawBuf = _rawContentCacheGet ? _rawContentCacheGet(fullPath, st) : null;
-        const rawBuf = cachedRawBuf || await readFile(fullPath);
+        const rawBuf = _prefetchedRawBuf || await readFile(fullPath);
         // Encoding-aware decode (fresh read AND raw-content cache hit both
         // flow through here). For a BOM-flagged UTF-16LE file, strip the
         // 2-byte FF FE BOM and decode as utf16le so it reverses the write
@@ -614,7 +664,7 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
         // the cache + snapshot record stale bytes.
         let _stPostRead;
         let _readStableForRawCache = true;
-        if (cachedRawBuf) {
+        if (_prefetchedRawFromCache) {
             _stPostRead = st;
         } else {
             try { _stPostRead = await fsPromises.stat(fullPath); } catch { _stPostRead = st; }