mixdog 0.9.95 → 0.9.97

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/builtin-tools.mjs

@@ -5,7 +5,6 @@
 // only (behavior + argument shapes); usage policy lives in rules/shared/01-tool.md.
 import {
     TOOL_ASYNC_EXECUTION_CONTRACT,
-    TOOL_MANUAL_CONTROL_CONTRACT,
     executionModeSchemaDescription,
 } from '../../../../shared/background-tasks.mjs';
 
@@ -28,7 +27,7 @@ function _shellMaxTimeoutMs() {
 // process lifetime, so this is evaluated once at module load.
 const _shellSyntaxCheat =
     process.platform === 'win32'
-        ? ' PowerShell: grep→Select-String, tail→Get-Content -Tail, head→Get-Content -TotalCount, /c/→C:\\, if && is unsupported use ;, $PID is reserved.'
+        ? ' PowerShell: use ; between commands, /c/→C:\\, and note that $PID is reserved.'
         : '';
 
 export const BUILTIN_TOOLS = [
@@ -36,7 +35,7 @@ export const BUILTIN_TOOLS = [
         name: 'read',
         title: 'Mixdog Read',
         annotations: { title: 'Mixdog Read', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false },
-        description: 'Read file contents. Batch paths/regions as real arrays: path[] or {path,offset,limit}[] regions in one call. Not for directories.',
+        description: 'Read file contents or line ranges; not directories.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -99,12 +98,12 @@ export const BUILTIN_TOOLS = [
         name: 'task',
         title: 'Background Task Control',
         annotations: { title: 'Background Task Control', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-        description: `Control a shell async task_id: actions list/status/read/wait/cancel. ${TOOL_MANUAL_CONTROL_CONTRACT} Not sess_* or agent ids.`,
+        description: 'Control a shell background task_id; not session or agent ids.',
         inputSchema: {
             type: 'object',
             properties: {
                 task_id: { type: 'string', description: 'shell async task_id.' },
-                action: { type: 'string', enum: ['list', 'status', 'read', 'wait', 'cancel'], description: 'Defaults to list, or wait when task_id is set; avoid polling loops.' },
+                action: { type: 'string', enum: ['list', 'status', 'read', 'wait', 'cancel'], description: 'Default list; with task_id, default wait.' },
                 timeout_ms: { type: 'number', description: 'Wait timeout ms.' },
             },
             required: [],
@@ -115,7 +114,7 @@ export const BUILTIN_TOOLS = [
         name: 'grep',
         title: 'Mixdog Grep',
         annotations: { title: 'Mixdog Grep', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Content search by literal or regex over file/dir scopes; matches return copy-ready raw source spans.',
+        description: 'Literal/regex search over file/dir scopes; returns source blocks with context.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -156,7 +155,7 @@ export const BUILTIN_TOOLS = [
         name: 'glob',
         title: 'Mixdog Glob',
         annotations: { title: 'Mixdog Glob', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Match exact glob patterns from base directories; batch pattern[]/path[].',
+        description: 'Match glob patterns under base directories.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -185,7 +184,7 @@ export const BUILTIN_TOOLS = [
         name: 'find',
         title: 'Mixdog Find Files',
         annotations: { title: 'Mixdog Find Files', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Fuzzy lookup for partial paths/names (dot dirs included). Returns matching paths; not file contents.',
+        description: 'Fuzzy partial path/name lookup; returns paths only.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -207,7 +206,7 @@ export const BUILTIN_TOOLS = [
         name: 'list',
         title: 'Mixdog List Directory',
         annotations: { title: 'Mixdog List Directory', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'List directory entries (path + type); batch independent dirs as path[].',
+        description: 'List directory entries (path + type).',
         inputSchema: {
             type: 'object',
             properties: {

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

@@ -238,7 +238,7 @@ export function getCachedReadOnlyStat(fullPath, loader = statSync, now = Date.no
     return stat;
 }
 
-export async function statPathsForMtime(paths, workDir, concurrency = 64, opts = {}) {
+export async function statPathsForMtime(paths, workDir, concurrency = Infinity, opts = {}) {
     const items = Array.isArray(paths) ? paths : [];
     const out = new Array(items.length);
     const now = Date.now();
@@ -302,7 +302,7 @@ export async function statPathsForMtime(paths, workDir, concurrency = 64, opts =
 // lstat variant — does NOT follow symlinks. Use for directory-listing
 // surfaces where a symlink to a 200 GB file should report as a symlink,
 // not as the target's size/mtime.
-export async function lstatPathsForMtime(paths, workDir, concurrency = 64, opts = {}) {
+export async function lstatPathsForMtime(paths, workDir, concurrency = Infinity, opts = {}) {
     const items = Array.isArray(paths) ? paths : [];
     const out = new Array(items.length);
     const inflight = new Map();

package/src/runtime/agent/orchestrator/tools/builtin/device-paths.mjs

@@ -19,8 +19,8 @@ export function isBlockedDevicePath(p) {
 
 // R1: UNC / SMB share paths (\\server\share or //server/share). Reading these
 // causes Windows to auto-authenticate to the remote host, leaking the NTLM
-// hash of the current user to any attacker-controlled SMB target. CC parity:
-// FileReadTool.ts:461 rejects the same prefix before stat. Accepts both
+// hash of the current user to any attacker-controlled SMB target. The prefix
+// is rejected before stat. Accepts both
 // backslash and forward-slash leaders so a normalize that picked either form
 // is caught.
 export function isUncPath(p) {

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/lib/grep-context-expander.mjs

@@ -17,7 +17,6 @@ import {
 } from './search-input-helpers.mjs';
 
 export const GREP_CONTEXT_CHAR_BUDGET_DEFAULT = 10_000;
-const GREP_CONTEXT_READ_CONCURRENCY = 4;
 const GREP_FOCUSED_CONTEXT_RADIUS = 12;
 const GREP_FOCUSED_RAW_BLOCKS = 3;
 // Anchors must stay usable as evidence without a follow-up read: keep the
@@ -229,21 +228,13 @@ async function readAnchorSources(anchors, radius, signal) {
         groups.get(anchor.absolutePath).anchors.push(anchor);
     }
     const entries = [...groups.values()];
-    let next = 0;
-    const worker = async () => {
-        while (next < entries.length) {
-            const entry = entries[next++];
-            try {
-                entry.lines = await readFileWindows(entry, radius, signal);
-            } catch (err) {
-                entry.error = err;
-            }
+    await Promise.all(entries.map(async (entry) => {
+        try {
+            entry.lines = await readFileWindows(entry, radius, signal);
+        } catch (err) {
+            entry.error = err;
         }
-    };
-    await Promise.all(Array.from(
-        { length: Math.min(GREP_CONTEXT_READ_CONCURRENCY, entries.length) },
-        () => worker(),
-    ));
+    }));
     return groups;
 }
 

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,
@@ -88,16 +90,12 @@ export async function executeListTool(args, workDir, options = {}) {
     args.path = coerceReadFamilyPathArg(args.path, workDir);
     if (Array.isArray(args.path)) {
         const list = [...new Set(args.path.map((p) => (typeof p === 'string' ? p.trim() : '')).filter((p) => p.length > 0))];
-        const capped = list.length > 10;
-        const targets = capped ? list.slice(0, 10) : list;
+        const targets = list;
         if (targets.length > 1) {
-            // Bounded parallel fan-out: each target is an independent listing
+            // Full parallel fan-out: each target is an independent listing
             // (own guard/cache/reachability), so run them concurrently instead
             // of serially. Bodies land in a fixed-index array so the emitted
-            // section order still matches the caller's `path[]` order — only the
-            // wall-clock cost changes. Concurrency is capped so a 10-path batch
-            // cannot exhaust the child-spawn / FS-handle budget.
-            const LIST_FANOUT_CONCURRENCY = 4;
+            // section order still matches the caller's `path[]` order.
             // Collapse semantic-duplicate targets: two spellings that resolve to
             // the same directory (e.g. `foo` and `./foo`) are stat'd/walked ONCE.
             // Each caller label keeps its own `# list <p>` section reusing the
@@ -116,24 +114,14 @@ export async function executeListTool(args, workDir, options = {}) {
                 if (!repByKey.has(k)) { repByKey.set(k, targets[i]); uniqueKeys.push(k); }
             }
             const bodyByKey = new Map();
-            let cursor = 0;
-            const runWorker = async () => {
-                for (;;) {
-                    const i = cursor++;
-                    if (i >= uniqueKeys.length) return;
-                    const k = uniqueKeys[i];
-                    try {
-                        bodyByKey.set(k, await executeListTool({ ...args, path: repByKey.get(k) }, workDir, options));
-                    } catch (err) {
-                        bodyByKey.set(k, `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`);
-                    }
+            await Promise.all(uniqueKeys.map(async (k) => {
+                try {
+                    bodyByKey.set(k, await executeListTool({ ...args, path: repByKey.get(k) }, workDir, options));
+                } catch (err) {
+                    bodyByKey.set(k, `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`);
                 }
-            };
-            await Promise.all(
-                Array.from({ length: Math.min(LIST_FANOUT_CONCURRENCY, uniqueKeys.length) }, runWorker),
-            );
+            }));
             const sections = targets.map((p, i) => `# list ${p}\n${bodyByKey.get(keyByIndex[i])}`);
-            if (capped) sections.push(`... [capped at 10 of ${list.length} paths]`);
             return sections.join('\n\n');
         }
         args.path = targets[0];
@@ -582,8 +570,7 @@ async function getTargetedFindEnumeration({
 export async function executeFuzzyFindTool(args, workDir, options = {}) {
     if (Array.isArray(args.query)) {
         const list = [...new Set(args.query.map((q) => (typeof q === 'string' ? q.trim() : '')).filter((q) => q.length > 0))];
-        const capped = list.length > 5;
-        const targets = capped ? list.slice(0, 5) : list;
+        const targets = list;
         if (targets.length > 1) {
             // head_limit is one call-level result budget, not a multiplier per
             // query. Split it deterministically in caller order; if it cannot
@@ -601,7 +588,6 @@ export async function executeFuzzyFindTool(args, workDir, options = {}) {
                     + `retry query=${JSON.stringify(omittedByHeadLimit)}]`,
                 );
             }
-            if (capped) notes.push(`... [capped at 5 of ${list.length} queries]`);
             const sectionHeaders = activeTargets.map((query) => `# find ${query}\n`);
             const separatorBytes = Math.max(0, activeTargets.length + notes.length - 1) * 2;
             const fixedBytes = sectionHeaders.reduce(

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,
@@ -6,7 +6,7 @@ import {
   resizeImageBuffer,
 } from './read-image-resize.mjs';
 
-// Image extensions native Read renders as image blocks (FileReadTool.ts).
+// Image extensions that Read renders as image blocks.
 const IMAGE_MIME = {
   '.png': 'image/png',
   '.jpg': 'image/jpeg',
@@ -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 {
@@ -112,7 +120,7 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
     // R1: UNC / SMB share reject (\\server\share, //server/share). Reading
     // these on Windows auto-authenticates to the remote host and leaks the
     // NTLM hash of the current user to any attacker-controlled SMB target.
-    // CC parity: FileReadTool.ts:461 rejects the same prefix before stat.
+    // The prefix is rejected before stat.
     // Must run before resolveAgainstCwd so a relative path can't be coerced
     // into a UNC share by the cwd resolution.
     if (typeof isUncPath === 'function' && isUncPath(filePath))
@@ -142,7 +150,7 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
         return `Error: cannot read Windows device path (reserved name or raw-device namespace): ${normalizeOutputPath(fullPath)}`;
     if (typeof hasUnsafeWin32Component === 'function' && hasUnsafeWin32Component(fullPath))
         return `Error: cannot read Windows path with trailing dot/space or NTFS ADS suffix (bypasses device guard): ${normalizeOutputPath(fullPath)}`;
-    // Pre-read size cap (Anthropic FileReadTool/limits.ts pattern):
+    // Pre-read size cap:
     // throw a small error response when the file is too big rather
     // than truncating to 25K tokens of content. Throw is decisively
     // more token-efficient (Anthropic #21841 reverted truncation).
@@ -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; }
@@ -712,7 +762,7 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
                 out = appendReadContextAdvisory(out, { filePath, lineCount, bytes: st.size });
             }
         }
-        // CC parity: empty file gets a system-reminder instead of
+        // An empty file gets a system-reminder instead of
         // a bare `1│` line. The reminder makes the empty-state
         // explicit so the agent doesn't assume content was elided.
         if (content.length === 0) {