mixdog 0.9.36 → 0.9.38

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

@@ -168,10 +168,15 @@ function _prependDestructiveWarning(command, text) {
     return `${warnings.map((w) => `⚠️ ${w}`).join('\n')}\n${text}`;
 }
 
+export function formatShellToolFailure(message) {
+    const text = String(message ?? '').replace(/^Error:\s*/i, '').trim() || 'shell tool failed';
+    return `Error: [shell-tool-failed] ${text}`;
+}
+
 export async function executeBashTool(args, workDir, options = {}) {
     const requestedCwd = args.cwd ?? args.workdir;
     const cwdResult = resolveOptionalCwd(requestedCwd, workDir);
-    if (cwdResult.error) return cwdResult.error;
+    if (cwdResult.error) return formatShellToolFailure(cwdResult.error);
     // Session cwd carry-over (no live shell): when the model
     // passes an explicit cwd it wins and updates the store on the next probe;
     // otherwise reuse the last stored cwd for this session if it still exists.
@@ -199,7 +204,7 @@ export async function executeBashTool(args, workDir, options = {}) {
         // persistent:true. Run the full sweep here so both paths share the
         // same blocklist before dispatch.
         const _policyBlock = checkExecPolicyMessage(_rawCmd);
-        if (_policyBlock) return _policyBlock;
+        if (_policyBlock) return formatShellToolFailure(_policyBlock);
     }
 
     // An empty-string session_id is NOT a persistent-session request: `typeof
@@ -208,7 +213,7 @@ export async function executeBashTool(args, workDir, options = {}) {
     // error, which models then retry in a loop. Require a non-blank id.
     if (args.persistent === true || (typeof args.session_id === 'string' && args.session_id.trim().length > 0)) {
         if (process.platform === 'win32') {
-            return 'Error: persistent shell sessions are disabled on Windows native-shell mode; run one-shot PowerShell commands without persistent/session_id.';
+            return formatShellToolFailure('persistent shell sessions are disabled on Windows native-shell mode; run one-shot PowerShell commands without persistent/session_id.');
         }
         const { executeBashSessionTool } = await import('../bash-session.mjs');
         let persistAbort = null;
@@ -227,7 +232,7 @@ export async function executeBashTool(args, workDir, options = {}) {
     }
 
     let command = args.command;
-    if (!command) return 'Error: command is required';
+    if (!command) return formatShellToolFailure('command is required');
 
     // Resolve the shell up front so shell-type-specific handling (PS-only wmic
     // rewrite, PS UTF-8 prefix) can gate on it. kind 'default' is byte-identical
@@ -238,9 +243,9 @@ export async function executeBashTool(args, workDir, options = {}) {
     const resolvedSpec = resolveShellFor(shellKind);
     if (!resolvedSpec) {
         if (shellKind === 'bash') {
-            return "Error: Git Bash not found — install Git for Windows or omit shell:'bash'.";
+            return formatShellToolFailure("Git Bash not found — install Git for Windows or omit shell:'bash'.");
         }
-        return "Error: pwsh (PowerShell) not found — install PowerShell or omit shell:'powershell'.";
+        return formatShellToolFailure("pwsh (PowerShell) not found — install PowerShell or omit shell:'powershell'.");
     }
 
     // wmic→PowerShell rewrite is PowerShell-only; never mangle a command bound
@@ -251,7 +256,7 @@ export async function executeBashTool(args, workDir, options = {}) {
     const wmicRewrite = resolvedSpec.shellType === 'powershell'
         ? maybeRewriteWmicProcessCommand(command)
         : null;
-    if (wmicRewrite?.error) return `Error: ${wmicRewrite.error}`;
+    if (wmicRewrite?.error) return formatShellToolFailure(wmicRewrite.error);
     if (wmicRewrite?.command) command = wmicRewrite.command;
 
     // PowerShell hygiene preflight (Windows PS-only; POSIX no-op): losslessly
@@ -262,19 +267,19 @@ export async function executeBashTool(args, workDir, options = {}) {
         shellType: resolvedSpec.shellType,
         shellName: resolvedSpec.shell,
     });
-    if (psHygiene.block) return psHygiene.block;
+    if (psHygiene.block) return formatShellToolFailure(psHygiene.block);
     command = psHygiene.command;
 
     const _execPolicyBlock = checkExecPolicyMessage(command);
     if (_execPolicyBlock) {
-        return _execPolicyBlock;
+        return formatShellToolFailure(_execPolicyBlock);
     }
 
     let shellEffects;
     try {
         shellEffects = await analyzeShellCommandEffects(command, bashWorkDir);
     } catch (err) {
-        return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
+        return formatShellToolFailure(normalizeErrorMessage(err instanceof Error ? err.message : String(err)));
     }
     // Keep foreground commands on a long tool-owned timeout. The MCP dispatch
     // layer must not add a shorter fallback ceiling when timeout is omitted.
@@ -314,7 +319,7 @@ export async function executeBashTool(args, workDir, options = {}) {
             : Math.min(timeoutMs, wmicRewrite?.timeoutMs || MAX_BASH_TIMEOUT_MS));
     const mergeStderr = args.merge_stderr === true;
     const longForegroundHint = foregroundLongCommandHint(command, timeout, { ...args, run_in_background: runInBackground });
-    if (longForegroundHint) return longForegroundHint;
+    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
@@ -347,7 +352,7 @@ export async function executeBashTool(args, workDir, options = {}) {
             try {
                 wrappedCommand = await wrapCommandWithSnapshot(shell, command);
             } catch (wrapErr) {
-                return `Error: shell snapshot wrapper failed — ${normalizeErrorMessage(wrapErr instanceof Error ? wrapErr.message : String(wrapErr))}`;
+                return formatShellToolFailure(`shell snapshot wrapper failed — ${normalizeErrorMessage(wrapErr instanceof Error ? wrapErr.message : String(wrapErr))}`);
             }
         } else {
             wrappedCommand = command;
@@ -367,7 +372,7 @@ export async function executeBashTool(args, workDir, options = {}) {
                 // claude.exe pid (server-main threads callerSession.clientHostPid).
                 clientHostPid: options?.clientHostPid,
             });
-            if (job && job.error) return `Error: ${job.error}`;
+            if (job && job.error) return formatShellToolFailure(job.error);
             let task;
             try {
                 task = registerBackgroundTask({
@@ -395,7 +400,7 @@ export async function executeBashTool(args, workDir, options = {}) {
                 });
             } catch (err) {
                 try { killShellJob(job.jobId); } catch { /* best effort cleanup */ }
-                return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
+                return formatShellToolFailure(normalizeErrorMessage(err instanceof Error ? err.message : String(err)));
             }
             // Wire a one-shot completion push so the dispatching session learns
             // the background task finished (no polling tool is auto-driven). The
@@ -525,7 +530,9 @@ export async function executeBashTool(args, workDir, options = {}) {
             : (result.killed ? 'SIGKILL' : (result.signal || null));
         const exitCode = signal ? null : result.exitCode;
         const benignExitOne = _isBenignSearchExitOne(command, exitCode, signal, stderr);
-        const isReallyErrored = !!signal || (exitCode !== 0 && exitCode !== null && !benignExitOne);
+        const shellToolFailed = result.failurePhase === 'tool' || !!result.outputCaptureError;
+        const shellRunFailed = !shellToolFailed && (!!signal || (exitCode !== 0 && exitCode !== null && !benignExitOne));
+        const isReallyErrored = shellToolFailed || shellRunFailed;
         const _driftNote = '';
         // Distinct timeout marker so callers see "killed by timeout after Nms"
         // vs an external signal (e.g. user Ctrl-C, OOM kill). result.timedOut
@@ -538,11 +545,16 @@ export async function executeBashTool(args, workDir, options = {}) {
         const timeoutHint = result.timedOut
             ? ` — command killed after ${timeout} ms; if it legitimately needs longer, retry with a larger timeout`
             : '';
-        const statusMarker = result.timedOut
-            ? `[timeout: ${timeout}ms signal: ${signal || 'SIGTERM'}]${timeoutHint}`
-            : (signal
-                ? `[signal: ${signal}]`
-                : (isReallyErrored ? `[exit code: ${exitCode}]` : ''));
+        const statusDetail = shellToolFailed
+            ? `[${result.outputCaptureError ? 'output capture failed' : (result.failureReason || 'tool failed')}]`
+            : (result.timedOut
+                ? `[timeout: ${timeout}ms signal: ${signal || 'SIGTERM'}]${timeoutHint}`
+                : (signal
+                    ? `[signal: ${signal}]`
+                    : (shellRunFailed ? `[exit code: ${exitCode}]` : '')));
+        const statusMarker = shellToolFailed
+            ? `[shell-tool-failed] ${statusDetail}`
+            : (shellRunFailed ? `[shell-run-failed] ${statusDetail}` : '');
         const errorPrefix = isReallyErrored ? 'Error: ' : '';
         if (mergeStderr) {
             // Post-exit concatenation. True chunk-level interleaving would
@@ -569,6 +581,9 @@ export async function executeBashTool(args, workDir, options = {}) {
             const sizeKb = Math.round((result.stderrFileSize || 0) / 1024);
             spillBlock += `\n[stderr: ${normalizeOutputPath(result.stderrPath)} (${sizeKb} KB)]`;
         }
+        if (result.outputCaptureError) {
+            spillBlock += `\n[tool capture error: ${normalizeErrorMessage(result.outputCaptureError?.message || String(result.outputCaptureError))}]`;
+        }
         const warningBlock = [
             wmicRewrite?.note || '',
         ].filter(Boolean).join('\n');

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

@@ -31,7 +31,7 @@ function _shellMaxTimeoutMs() {
 // the 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:\\, && 미지원 시 ; 사용, $PID 예약.'
+        ? ' PowerShell: grep→Select-String, tail→Get-Content -Tail, head→Get-Content -TotalCount, /c/→C:\\, if && is unsupported use ;, $PID is reserved.'
         : '';
 
 export const BUILTIN_TOOLS = [
@@ -39,7 +39,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 verified file path(s). Unknown path → find first. Batch paths/regions as real arrays in one call. Not for directory listing.',
+        description: 'Read verified file path(s); guessed path → find first (same turn as other probes). Batch paths/regions as real arrays in one call. Not for directory listing.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -109,7 +109,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: 'Exact text/regex in a verified file/dir scope. Unknown scope → find/glob first. files_with_matches/count for broad anchors, content_with_context for narrow answers.',
+        description: 'Exact text/regex in verified scope (project root counts as verified — unscoped search needs no find). Only a guessed path fragment → find first, same turn. No path "." + guessed src/**. Broad: files_with_matches/count; narrow: content_with_context.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -125,14 +125,14 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Verified file or dir. Array = several scopes.',
+                    description: 'Verified file/dir, or project root; guessed → find first.',
                 },
                 glob: {
                     anyOf: [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Glob filter to narrow scope.',
+                    description: 'Glob filter; no guessed src/** under path ".".',
                 },
                 output_mode: { type: 'string', enum: ['content_with_context', 'content', 'files_with_matches', 'count'], description: 'Broad: files_with_matches/count; narrow: content_with_context.' },
                 head_limit: { type: 'number', minimum: 0, description: 'Max results.' },
@@ -148,7 +148,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: 'Find files by exact glob from verified roots. Batch patterns and roots as arrays in one call.',
+        description: 'Exact glob from verified roots (project root is verified). Guessed root/name → find first, same turn. No path "." + guessed src/**. Batch arrays.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -164,7 +164,7 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Base directory/directories. Batch multiple roots as path[] in one call.',
+                    description: 'Verified base dir(s) or project root; guessed → find first. Batch path[].',
                 },
                 head_limit: { type: 'number', description: 'Max entries.' },
                 offset: { type: 'number', description: 'Skip entries.' },
@@ -176,7 +176,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: 'Find files by partial path/name, including dot-directories. Use for unverified path/name guesses; returns verified paths. Batch query[].',
+        description: 'Partial path/name lookup incl dot dirs; verify roots before grep/glob. Batch query[].',
         inputSchema: {
             type: 'object',
             properties: {
@@ -197,7 +197,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 verified directories. Unknown dir → find first. Batch dirs as path[].',
+        description: 'List verified directories (project root included). Guessed dir → find first. Batch dirs as path[].',
         inputSchema: {
             type: 'object',
             properties: {

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

@@ -32,6 +32,7 @@ import {
 import { formatMtime, formatListSize } from './list-formatting.mjs';
 import { TOOL_OUTPUT_MAX_BYTES } from './tool-output-limit.mjs';
 import { runRg } from './rg-runner.mjs';
+import { hasSpareCapacity as childSpawnHasSpareCapacity } from '../../../../shared/child-spawn-gate.mjs';
 import { fuzzyRank } from './fuzzy-match.mjs';
 import { assertPathReachable } from './fs-reachability.mjs';
 
@@ -84,16 +85,30 @@ export async function executeListTool(args, workDir, options = {}) {
         const capped = list.length > 10;
         const targets = capped ? list.slice(0, 10) : list;
         if (targets.length > 1) {
-            const sections = [];
-            for (const p of targets) {
-                let body;
-                try {
-                    body = await executeListTool({ ...args, path: p }, workDir, options);
-                } catch (err) {
-                    body = `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
+            // Bounded 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;
+            const bodies = new Array(targets.length);
+            let cursor = 0;
+            const runWorker = async () => {
+                for (;;) {
+                    const i = cursor++;
+                    if (i >= targets.length) return;
+                    try {
+                        bodies[i] = await executeListTool({ ...args, path: targets[i] }, workDir, options);
+                    } catch (err) {
+                        bodies[i] = `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
+                    }
                 }
-                sections.push(`# list ${p}\n${body}`);
-            }
+            };
+            await Promise.all(
+                Array.from({ length: Math.min(LIST_FANOUT_CONCURRENCY, targets.length) }, runWorker),
+            );
+            const sections = targets.map((p, i) => `# list ${p}\n${bodies[i]}`);
             if (capped) sections.push(`... [capped at 10 of ${list.length} paths]`);
             return sections.join('\n\n');
         }
@@ -349,8 +364,9 @@ export async function executeTreeTool(args, workDir, options = {}) {
 // key with in-flight promise dedup (N concurrent callers share ONE sweep)
 // plus a short TTL for serial reuse. Truncated/partial sweeps are
 // known-incomplete and are NEVER cached.
-const FIND_ENUM_CACHE = new Map(); // key -> { files, expiresAt }
+const FIND_ENUM_CACHE = new Map(); // key -> { files, expiresAt, gen }
 const FIND_ENUM_INFLIGHT = new Map(); // key -> Promise<{files,truncated,partial}>
+let FIND_ENUM_GEN = 0;
 
 // The broad enumeration is a DERIVED cache the scope/path invalidation layer
 // does not otherwise know about — a file created/renamed after a sweep would
@@ -358,6 +374,7 @@ const FIND_ENUM_INFLIGHT = new Map(); // key -> Promise<{files,truncated,partial
 // write-invalidation event (TTL remains the secondary bound). Full clear is
 // fine: entries are cheap to rebuild.
 registerCacheInvalidationListener(() => {
+    FIND_ENUM_GEN += 1;
     FIND_ENUM_CACHE.clear();
     FIND_ENUM_INFLIGHT.clear();
 });
@@ -390,18 +407,31 @@ function parseRgFileList(stdout) {
 // must treat it as read-only. `rgArgs` must be the broad-pass args (no per-query
 // narrowing); the cache key is the 4 dims only, so any caller producing an
 // equivalent sweep for the same dims reuses the result.
-async function getBroadEnumeration({ root, hidden, depth, includeNoise, rgArgs, cwd, runRgImpl = runRg }) {
+async function getBroadEnumeration({ root, hidden, depth, includeNoise, rgArgs, cwd, runRgImpl = runRg, bestEffort = false }) {
     const ttl = findEnumTtlMs();
     const key = findEnumKey({ root, hidden, depth, includeNoise });
     if (ttl > 0) {
         const hit = FIND_ENUM_CACHE.get(key);
-        if (hit && hit.expiresAt > Date.now()) {
+        if (hit && hit.gen === FIND_ENUM_GEN && hit.expiresAt > Date.now()) {
             return { files: hit.files, truncated: false, partial: false };
         }
         if (hit) FIND_ENUM_CACHE.delete(key); // expired
-        const inflight = FIND_ENUM_INFLIGHT.get(key);
-        if (inflight) return inflight;
     }
+    // Single-flight is independent of the persistent TTL cache. Even when
+    // MIXDOG_FIND_ENUM_CACHE_TTL_MS=0 disables reuse across calls, concurrent
+    // query[] fan-out should still share the one broad `rg --files` sweep
+    // instead of spawning N identical enumerations.
+    const inflight = FIND_ENUM_INFLIGHT.get(key);
+    if (inflight) return inflight;
+    // Non-competing prewarm: past the cache/single-flight fast paths this runs
+    // a fresh `rg` sweep (a child-spawn slot). Best-effort warmers skip that
+    // spawn when the gate has no spare capacity, returning a known-incomplete
+    // result — and skipping BEFORE registering FIND_ENUM_INFLIGHT so a real
+    // caller is never attached to (or cache-poisoned by) a skipped warm.
+    if (bestEffort && !childSpawnHasSpareCapacity()) {
+        return { files: [], truncated: false, partial: true };
+    }
+    const genAtStart = FIND_ENUM_GEN;
     const run = (async () => {
         const stdout = await runRgImpl(rgArgs, { cwd });
         const truncated = Boolean(stdout && typeof stdout === 'object' && stdout.truncated);
@@ -409,17 +439,18 @@ async function getBroadEnumeration({ root, hidden, depth, includeNoise, rgArgs,
         const files = parseRgFileList(stdout);
         // Never cache a truncated/partial sweep — it is known-incomplete, so a
         // later query with a larger head_limit must re-run the enumeration.
-        if (ttl > 0 && !truncated && !partial) {
-            FIND_ENUM_CACHE.set(key, { files, expiresAt: Date.now() + ttl });
+        // Also never let an in-flight prewarm/real sweep repopulate after a
+        // write invalidation cleared the cache during the sweep.
+        if (ttl > 0 && !truncated && !partial && FIND_ENUM_GEN === genAtStart) {
+            FIND_ENUM_CACHE.set(key, { files, expiresAt: Date.now() + ttl, gen: genAtStart });
         }
         return { files, truncated, partial };
     })();
-    if (ttl > 0) {
-        FIND_ENUM_INFLIGHT.set(key, run);
-        try { return await run; }
-        finally { FIND_ENUM_INFLIGHT.delete(key); }
+    FIND_ENUM_INFLIGHT.set(key, run);
+    try { return await run; }
+    finally {
+        if (FIND_ENUM_INFLIGHT.get(key) === run) FIND_ENUM_INFLIGHT.delete(key);
     }
-    return run;
 }
 
 // Best-effort warm of the broad enumeration for a root using the `find` tool's
@@ -435,7 +466,7 @@ export async function prewarmFindEnumeration(root) {
         await getBroadEnumeration({
             root: normalizeOutputPath(root),
             hidden, depth, includeNoise,
-            rgArgs, cwd: root,
+            rgArgs, cwd: root, bestEffort: true,
         });
     } catch { /* best-effort warm; never surface */ }
 }
@@ -450,16 +481,31 @@ export async function executeFuzzyFindTool(args, workDir, options = {}) {
         const capped = list.length > 5;
         const targets = capped ? list.slice(0, 5) : list;
         if (targets.length > 1) {
-            const sections = [];
-            for (const q of targets) {
-                let body;
-                try {
-                    body = await executeFuzzyFindTool({ ...args, query: q }, workDir, options);
-                } catch (err) {
-                    body = `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
+            // Bounded parallel fan-out: every query shares ONE broad `rg --files`
+            // sweep via the enumeration cache's in-flight single-flight dedup, so
+            // running them concurrently collapses N broad sweeps into one and
+            // overlaps the tiny per-query narrowed passes. Bodies land at a fixed
+            // index so the emitted section order still matches the caller's
+            // query[] order — only wall-clock cost changes. Concurrency is capped
+            // so a 5-query batch cannot exhaust the child-spawn budget.
+            const FIND_FANOUT_CONCURRENCY = 4;
+            const bodies = new Array(targets.length);
+            let cursor = 0;
+            const runWorker = async () => {
+                for (;;) {
+                    const i = cursor++;
+                    if (i >= targets.length) return;
+                    try {
+                        bodies[i] = await executeFuzzyFindTool({ ...args, query: targets[i] }, workDir, options);
+                    } catch (err) {
+                        bodies[i] = `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
+                    }
                 }
-                sections.push(`# find ${q}\n${body}`);
-            }
+            };
+            await Promise.all(
+                Array.from({ length: Math.min(FIND_FANOUT_CONCURRENCY, targets.length) }, runWorker),
+            );
+            const sections = targets.map((q, i) => `# find ${q}\n${bodies[i]}`);
             if (capped) sections.push(`... [capped at 5 of ${list.length} queries]`);
             return sections.join('\n\n');
         }

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

@@ -24,11 +24,20 @@ function _stripLineCoordForReach(s) {
         .replace(/:\d+(?:-\d+)?(?::.*)?$/, '');
 }
 
+// Batch fan-out cap: array/object read shapes read only the first N entries
+// (the >N slice below truncates the rest with a `_batchCapNote`). The
+// reachability preflight must honour the SAME cap so a path that will be
+// capped away is never stat-probed and can never reject the batch via a guard.
+const READ_BATCH_PATH_CAP = 10;
+
 function _collectReachCandidates(p) {
     const out = [];
     const push = (s) => { if (typeof s === 'string' && s) out.push(s); };
     if (typeof p === 'string') push(p);
-    else if (Array.isArray(p)) for (const e of p) push((e && typeof e === 'object') ? (e.path ?? e.file_path) : e);
+    // Only the first READ_BATCH_PATH_CAP entries survive the fan-out cap, so
+    // preflight only the paths that will actually be read. Capped-away paths
+    // (incl. UNC/device) must NOT be probed or allowed to fail the batch.
+    else if (Array.isArray(p)) for (const e of p.slice(0, READ_BATCH_PATH_CAP)) push((e && typeof e === 'object') ? (e.path ?? e.file_path) : e);
     return out;
 }
 
@@ -66,11 +75,17 @@ async function _readReachPreflight(rawPath, workDir, helpers) {
     // line-coordinate strip only needs to land in the right directory — exact
     // suffix parsing is not required for the stat to be representative.
     const candidates = [];
+    const seenFull = new Set();
     for (const raw of _collectReachCandidates(rawPath)) {
         const stripped = _stripLineCoordForReach(normalizeInputPath(raw));
         const full = resolveAgainstCwd(stripped, workDir);
         const guardMsg = _guardedReadError(stripped, helpers) || _guardedReadError(full, helpers);
         if (guardMsg) return guardMsg;
+        // Dedup by resolved path so a batch repeating the same file (or the
+        // same union window) issues one stat probe, not one per entry —
+        // bounding the preflight's FS work to the distinct target set.
+        if (seenFull.has(full)) continue;
+        seenFull.add(full);
         candidates.push(full);
     }
     if (candidates.length === 0) return null;
@@ -113,7 +128,14 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
     args.path = coerceReadFamilyPathArg(args.path, workDir);
     // Reachability preflight up front (all shapes) — before readPathStringGuardError /
     // image stat, all of which can touch sync FS.
-    {
+    // options._skipReachPreflight: set only by the batch dispatcher on its
+    // child reads (below). The parent batch call already ran this exact
+    // preflight over EVERY candidate path in the array (_collectReachCandidates
+    // covers array/object shapes), so re-running it per child re-stats the same
+    // mounts N times. The UNC/device/ADS string guards still run inside the
+    // child (readPathStringGuardError / image fast-path) — only the async
+    // reachability stat is skipped, never the security guards.
+    if (options?._skipReachPreflight !== true) {
         const _reErr = await _readReachPreflight(args.path, workDir, helpers);
         if (_reErr) return _reErr;
     }
@@ -289,7 +311,7 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
                 // document/image content-block object that would stringify to
                 // "[object Object]" and drop the payload. Scalar reads (the
                 // single-file path below) keep the rich block shapes.
-                const body = await executeChildBuiltinTool('read', readEntry, workDir, { suppressReadUnchangedStub: true, mediaTextOnly: true });
+                const body = await executeChildBuiltinTool('read', readEntry, workDir, { suppressReadUnchangedStub: true, mediaTextOnly: true, _skipReachPreflight: true });
                 results[index] = { path: entry.path, mode: entry.mode || 'full', n: entry.n, body };
             };
             const key = entry.path || `#missing-${index}`;

package/src/runtime/agent/orchestrator/tools/builtin/search-builders.mjs

@@ -31,6 +31,7 @@ export function buildGrepCacheKey(parts) {
         onlyMatching,
         pcre2,
         withFilename,
+        patternCapTotal = 0,
     } = parts;
     return [
         'grep',
@@ -50,6 +51,10 @@ export function buildGrepCacheKey(parts) {
         Array.isArray(fileType) ? fileType.join('\x01') : (fileType || ''),
         pcre2 ? 'p1' : 'p0',
         withFilename ? 'H1' : 'H0',
+        // Cap total keeps a capped request (first-N of M patterns, carrying the
+        // "[capped at N of M]" notice) from colliding with an exact N-pattern
+        // request or with a differently-capped one (of 15 vs of 20).
+        'pc' + String(patternCapTotal || 0),
     ].join('|');
 }
 
@@ -126,13 +131,15 @@ export function buildGrepRgArgs(parts) {
     return rgArgs;
 }
 
-export function buildGlobCacheKey({ patterns, basePath, headLimit, offset, extraIgnore, sort }) {
+export function buildGlobCacheKey({ patterns, basePath, headLimit, offset, extraIgnore, sort, patternCapTotal = 0 }) {
     // extraIgnore (rg ignore globs from _extraIgnoreDirs) alters which files
     // match, so it MUST partake in the key — otherwise calls that differ only
     // by extra ignores collide and return stale over-/under-filtered results.
     // Sorted so the same ignore set in any order maps to one key.
     const extra = Array.isArray(extraIgnore) && extraIgnore.length ? [...extraIgnore].sort().join('\x01') : '';
-    return ['glob', patterns.join('\x01'), basePath, headLimit ?? '', offset ?? '', sort || 'natural', extra].join('|');
+    // patternCapTotal: a capped pattern set (first-N of M) must not collide with
+    // an exact N-pattern request or a differently-capped one.
+    return ['glob', patterns.join('\x01'), basePath, headLimit ?? '', offset ?? '', sort || 'natural', extra, 'pc' + String(patternCapTotal || 0)].join('|');
 }
 
 export function buildListCacheKey(parts) {