mixdog 0.9.149 → 0.9.151

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

@@ -10,6 +10,16 @@ import { coerceReadFamilyPathArg, hasGlobMagic } from './path-utils.mjs';
 import { readIoAdmission } from '../../../../shared/tool-workload-gates.mjs';
 import { currentToolExecutionOwner } from '../../../../shared/tool-execution-owner.mjs';
 
+// Per-entry status in a batch. A conclusively missing file is not a failed
+// read — that is why its body is `[path absent]` and not `Error:` — but it is
+// not `ok` either: the header said `missing.png [ok]` above a body saying the
+// file does not exist, which is the one line a skimming reader trusts. Absence
+// gets its own tag so the header and the body agree.
+function batchEntryStatus(body, failed, textBody) {
+    if (failed) return 'error';
+    return /^\s*\[path absent\]/.test(String(textBody ?? body ?? '')) ? 'absent' : 'ok';
+}
+
 function hasLineCoordinate(path) {
     return typeof path === 'string' && /(?:#L\d+|:\d+(?:-\d+)?(?::|$))/i.test(path);
 }
@@ -94,6 +104,18 @@ async function _readReachPreflight(rawPath, workDir, helpers) {
     }
 }
 
+// Per-file hard cap for glob fan-out. Sampling many files at the single-file
+// default turns one call into thousands of context lines, while format/shape
+// evidence needs only a small head from each file. Exact-path reads keep the
+// standard defaults.
+// MIXDOG_READ_GLOB_SURVEY_LIMIT overrides for A/B runs.
+const READ_GLOB_SURVEY_LIMIT = 25;
+const READ_GLOB_OUTPUT_BUDGET_BYTES = 10 * 1024;
+function _readGlobSurveyLimit() {
+    const parsed = parseInt(process.env.MIXDOG_READ_GLOB_SURVEY_LIMIT ?? '', 10);
+    return parsed > 0 ? parsed : READ_GLOB_SURVEY_LIMIT;
+}
+
 export async function executeReadTool(args, workDir, readStateScope, executeChildBuiltinTool, options = {}, helpers = {}) {
     const {
         classifyResultKind,
@@ -211,9 +233,23 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
                 const _capNote = _globFiles.length > READ_GLOB_CAP
                     ? `\n[glob expansion capped at ${READ_GLOB_CAP} files (newest first); narrow the pattern for the rest]`
                     : '';
+                const _surveyArgs = { ...args, path: _capped, file_path: undefined };
+                const _survey = _readGlobSurveyLimit();
+                const _requestedLimit = Number(_surveyArgs.limit);
+                _surveyArgs.limit = Number.isFinite(_requestedLimit) && _requestedLimit > 0
+                    ? Math.min(Math.trunc(_requestedLimit), _survey)
+                    : _survey;
                 const _expanded = await executeReadTool(
-                    { ...args, path: _capped, file_path: undefined },
-                    workDir, readStateScope, executeChildBuiltinTool, { ...options }, helpers,
+                    _surveyArgs,
+                    workDir, readStateScope, executeChildBuiltinTool, {
+                        ...options,
+                        readOutputBudgetBytes: Math.min(
+                            Number(options?.readOutputBudgetBytes) > 0
+                                ? Number(options.readOutputBudgetBytes)
+                                : READ_GLOB_OUTPUT_BUDGET_BYTES,
+                            READ_GLOB_OUTPUT_BUDGET_BYTES,
+                        ),
+                    }, helpers,
                 );
                 if (!_capNote) return _expanded;
                 if (typeof _expanded === 'string') return _expanded + _capNote;
@@ -512,12 +548,18 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
         // reject_partial:true — when the caller asked for all-or-none,
         // refuse to return a mixed payload that downstream parsers
         // would have to disambiguate per-entry.
-        if (failedReads > 0 && args.reject_partial === true) {
-            const reasons = orderedResults
-                .filter((r) => bodyFailed(r.body))
+        // All-or-none is about DELIVERY: an entry that returned no content did
+        // not deliver, whether it failed outright or was conclusively absent.
+        // Counting only hard failures let a batch with a missing file through
+        // as a mixed payload — exactly what the caller asked not to receive.
+        const undelivered = orderedResults.filter(
+            (r) => batchEntryStatus(r.body, bodyFailed(r.body), bodyTextFor(r.body)) !== 'ok',
+        );
+        if (undelivered.length > 0 && args.reject_partial === true) {
+            const reasons = undelivered
                 .map((r) => `${normalizeOutputPath(r.path)}: ${bodyTextFor(r.body).split('\n')[0] || 'structured media read failed'}`)
                 .join('; ');
-            return `Error: batch read rejected (${failedReads} of ${orderedResults.length} failed; reject_partial:true) — ${reasons}`;
+            return `Error: batch read rejected (${undelivered.length} of ${orderedResults.length} failed; reject_partial:true) — ${reasons}`;
         }
         // Default: surface per-entry status tags ([ok]/[error]) so a
         // downstream classifyResultKind treats the aggregate as a
@@ -538,8 +580,8 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
                 const mode = r.n !== undefined ? `${r.mode} n=${r.n}` : r.mode;
                 // Default full mode carries no information — tag only non-default modes.
                 const modeTag = mode && mode !== 'full' ? ` [${mode}]` : '';
-                const status = bodyFailed(r.body) ? 'error' : 'ok';
                 const textBody = bodyTextFor(r.body);
+                const status = batchEntryStatus(r.body, bodyFailed(r.body), textBody);
                 const match = /\[TRUNCATED (?:—|-) file is (\d+) lines \/ (\d+) KB\./.exec(textBody);
                 const suffix = match ? ` (truncated ${match[1]}L/${match[2]}KB)` : '';
                 const entryHeader = `${path}${modeTag} [${status}]${suffix}`;
@@ -582,7 +624,11 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
             const path = normalizeOutputPath(r.path);
             const mode = r.n !== undefined ? `${r.mode} n=${r.n}` : r.mode;
             const modeTag = mode && mode !== 'full' ? ` [${mode}]` : '';
-            const status = classifyResultKind(String(r.body || '')) === 'error' ? 'error' : 'ok';
+            const status = batchEntryStatus(
+                r.body,
+                classifyResultKind(String(r.body || '')) === 'error',
+                String(r.body || ''),
+            );
             const dupKey = JSON.stringify([path, mode, r.body || '']);
             const priorIdx = _seenEntryBody.get(dupKey);
             if (priorIdx !== undefined) {

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

@@ -1,6 +1,11 @@
-import { accessSync, constants as fsConstants, statSync } from 'node:fs';
-import { basename, delimiter as pathDelimiter, join as pathJoin } from 'node:path';
-import { resolveShellFor } from './shell-runtime.mjs';
+import { accessSync, constants as fsConstants, readFileSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import {
+    delimiter as pathDelimiter,
+    dirname as pathDirname,
+    join as pathJoin,
+    resolve as pathResolveAbsolute,
+} from 'node:path';
 
 export const SHELL_RUNTIME_CANDIDATES = Object.freeze([
     'node',
@@ -23,31 +28,6 @@ export const SHELL_RUNTIME_CANDIDATES = Object.freeze([
     'bash',
 ]);
 
-export const SHELL_DEPENDENCY_CANDIDATES = Object.freeze([
-    'git',
-    'rg',
-    'jq',
-    'curl',
-    'wget',
-    'gcc',
-    'clang',
-    'make',
-    'cmake',
-    'ninja',
-    'cargo',
-    'sqlite3',
-    'psql',
-    'docker',
-    'kubectl',
-    'openssl',
-    'tar',
-]);
-
-export const SHELL_CAPABILITY_CANDIDATES = Object.freeze([
-    ...SHELL_RUNTIME_CANDIDATES,
-    ...SHELL_DEPENDENCY_CANDIDATES,
-]);
-
 function _pathDirectory(value) {
     const text = String(value || '').trim();
     return text.length >= 2 && text.startsWith('"') && text.endsWith('"')
@@ -89,35 +69,94 @@ export function findPathExecutable(name, {
     return null;
 }
 
-export function detectPathCapabilities({
-    candidates = SHELL_CAPABILITY_CANDIDATES,
-    ...pathOptions
-} = {}) {
-    const available = [];
-    const unavailable = [];
-    for (const name of candidates) {
-        (findPathExecutable(name, pathOptions) ? available : unavailable).push(name);
+// A startup PATH inventory is deliberately not rendered into the prompt: it
+// would be measured in this process's PATH while commands run under the
+// login-shell snapshot (shell-snapshot.mjs), which does not exist until the
+// first shell call, and it would freeze at session start while an install
+// during the session changes the answer. bash-tool's _exitClassDiagnostic
+// reports a missing command after it has run, from the environment that ran it.
+
+// Walk up for a `.git` marker instead of shelling out to `git rev-parse`: it
+// costs no process spawn, and it still answers on images where the git binary
+// is absent. `.git` is a directory in a normal clone and a file in a worktree
+// or submodule, so both count as "inside a repository".
+export function findRepositoryRoot(startDirectory, { maxDepth = 64 } = {}) {
+    let current;
+    try {
+        current = pathResolveAbsolute(String(startDirectory || '.'));
+    } catch {
+        return null;
     }
-    return { available, unavailable };
+    for (let depth = 0; depth < maxDepth; depth += 1) {
+        const marker = pathJoin(current, '.git');
+        try {
+            const stats = statSync(marker);
+            return { root: current, gitDirectory: stats.isDirectory() ? marker : null };
+        } catch {}
+        const parent = pathDirname(current);
+        if (parent === current) break;
+        current = parent;
+    }
+    return null;
 }
 
-export function describeShellStartupPolicy({
-    os = process.platform,
-    shell = null,
+function _headBranch(gitDirectory) {
+    if (!gitDirectory) return null;
+    try {
+        const head = readFileSync(pathJoin(gitDirectory, 'HEAD'), 'utf8').trim();
+        // Detached HEAD holds a raw object id and names no branch.
+        return /^ref:\s*refs\/heads\/(.+)$/.exec(head)?.[1] ?? null;
+    } catch {
+        return null;
+    }
+}
+
+function _repositoryChangeState(root) {
+    try {
+        const result = spawnSync('git', [
+            '--no-optional-locks',
+            '-C',
+            root,
+            'status',
+            '--porcelain=v1',
+            '--untracked-files=normal',
+        ], {
+            encoding: 'utf8',
+            env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' },
+            maxBuffer: 64 * 1024,
+            timeout: 1500,
+            windowsHide: true,
+        });
+        const output = String(result.stdout || '').trim();
+        if (result.status === 0) return output ? 'changes present' : 'clean';
+        if (result.error?.code === 'ENOBUFS' && output) return 'changes present';
+    } catch {}
+    return null;
+}
+
+// Startup snapshot, same contract as the shell line above: it states what was
+// true when the session opened, not a permanent rule. `git init` or a move to
+// another directory changes it, which is why this reports the observation
+// rather than forbidding calls.
+export function describeGitStartupState({
+    cwd = process.cwd(),
     ...pathOptions
 } = {}) {
-    const { available, unavailable } = detectPathCapabilities(pathOptions);
-    const resolvedShell = shell || basename(String(resolveShellFor('default')?.shell || 'unknown'));
-    // Shell networking is independent from the web-search tool surface:
-    // applyShellEgressPolicy leaves the spawn env untouched, so package
-    // managers, source-control clients, and proxies keep working even with
-    // MIXDOG_FEATURE_WEB_SEARCH=0. This line therefore never claims an
-    // egress block the runtime does not enforce.
-    return `- Shell startup environment: OS=${os}; shell=${resolvedShell}; available=${available.join(', ') || 'none'}; unavailable=${unavailable.join(', ') || 'none'}. For shell commands, treat every unavailable entry as absent. Invoke one only if the same command first installs it or exposes it on PATH.`;
+    const installed = Boolean(findPathExecutable('git', pathOptions));
+    if (!installed) {
+        return '- Git startup state: git is not installed here; git tool calls fail until something installs it.';
+    }
+    const found = findRepositoryRoot(cwd);
+    if (!found) {
+        return `- Git startup state: ${cwd} was not inside a git repository at startup; git commands that require one fail until a repository exists.`;
+    }
+    const branch = _headBranch(found.gitDirectory);
+    const changeState = _repositoryChangeState(found.root);
+    return `- Git startup state: repository root ${found.root}${branch ? ` on branch ${branch}` : ' with a detached HEAD'}${changeState ? `; ${changeState}` : ''}.`;
 }
 
-export function appendShellStartupPolicy(rules, tools, options = {}) {
+export function appendGitStartupState(rules, tools, options = {}) {
     const text = String(rules || '').trimEnd();
-    if (!text || !Array.isArray(tools) || !tools.some((tool) => tool?.name === 'shell')) return text;
-    return `${text}\n${describeShellStartupPolicy(options)}`;
+    if (!text || !Array.isArray(tools) || !tools.some((tool) => tool?.name === 'git')) return text;
+    return `${text}\n${describeGitStartupState(options)}`;
 }

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

@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import test from 'node:test';
+
+import { describeGitStartupState } from './runtime-capabilities.mjs';
+
+const gitAvailable = spawnSync('git', ['--version'], {
+    encoding: 'utf8',
+    windowsHide: true,
+}).status === 0;
+
+test('Git startup state reports clean and dirty repository snapshots', {
+    skip: gitAvailable ? false : 'git is unavailable',
+}, () => {
+    const root = mkdtempSync(join(tmpdir(), 'mixdog-git-startup-'));
+    try {
+        assert.equal(spawnSync('git', ['init', '-q'], {
+            cwd: root,
+            encoding: 'utf8',
+            windowsHide: true,
+        }).status, 0);
+
+        const clean = describeGitStartupState({
+            cwd: root,
+            capabilities: { available: ['git'] },
+        });
+        assert.match(clean, /Git startup state: repository root /);
+        assert.match(clean, /; clean\.$/);
+
+        writeFileSync(join(root, 'dirty.txt'), 'dirty\n');
+        const dirty = describeGitStartupState({
+            cwd: root,
+            capabilities: { available: ['git'] },
+        });
+        assert.match(dirty, /; changes present\.$/);
+    } finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+
+test('Git startup state preserves the non-repository message', () => {
+    const root = mkdtempSync(join(tmpdir(), 'mixdog-nonrepo-startup-'));
+    try {
+        const state = describeGitStartupState({
+            cwd: root,
+            capabilities: { available: ['git'] },
+        });
+        assert.match(state, /was not inside a git repository at startup/);
+        assert.doesNotMatch(state, /; (?:clean|changes present)\./);
+    } finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});

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

@@ -13,6 +13,20 @@ export const DEFAULT_IGNORE_GLOBS = [
     '!**/lpt[1-9]',
 ];
 
+// Kernel-virtual trees mounted at the filesystem root hold no user files and
+// can stall or poison a full-root walk: procfs re-enumerates every pid on each
+// pass and /proc/kcore presents as a terabyte-scale sparse file. A scan rooted
+// at `/` prunes them up front; the globs are ROOT-ANCHORED (no `**/` prefix),
+// so a scan rooted at or inside one of them (path /proc/...) keeps full
+// visibility, and ordinary project directories named `proc`/`sys`/`dev` are
+// never affected because the exclusion only applies when the walk root is `/`.
+export function rootScanIgnoreGlobs(resolvedRoot, platform = process.platform) {
+    if (platform === 'win32') return [];
+    return String(resolvedRoot || '') === '/'
+        ? ['!proc/**', '!sys/**', '!dev/**']
+        : [];
+}
+
 export function buildGrepCacheKey(parts) {
     const {
         patterns,
@@ -123,11 +137,22 @@ export function buildGrepRgArgs(parts) {
     // globs (no trailing /**) always apply. searchPath is normalized to forward
     // slashes and de-trailing-slashed for the comparison.
     const _sp = String(searchPath || '').replace(/\\/g, '/').replace(/\/+$/, '');
+    // A positive --glob filter that NAMES a pruned directory is asking to
+    // search inside it; only the path operand used to count, so
+    // `glob:"__pycache__/*.pyc"` matched nothing while the files were there.
+    // Negative filters never re-admit their own target.
+    const _namedByGlobs = new Set(
+        (Array.isArray(globPatterns) ? globPatterns : [])
+            .filter((g) => typeof g === 'string' && g && !g.startsWith('!'))
+            .flatMap((g) => g.replace(/\\/g, '/').split('/'))
+            .filter((segment) => segment && !/[*?[\]{}]/.test(segment)),
+    );
     for (const ex of DEFAULT_IGNORE_GLOBS) {
         const m = /^!\*\*\/([^/]+)\/\*\*$/.exec(ex);
         if (m) {
             const name = m[1];
             if (_sp === name || _sp.endsWith(`/${name}`) || _sp.includes(`/${name}/`) || _sp.startsWith(`${name}/`)) continue;
+            if (_namedByGlobs.has(name)) continue;
         }
         rgArgs.push('--glob', ex);
     }

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

@@ -0,0 +1,16 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { rootScanIgnoreGlobs } from './search-builders.mjs';
+
+test('root-anchored kernel-tree prunes apply only to a posix filesystem-root scan', () => {
+    assert.deepEqual(
+        rootScanIgnoreGlobs('/', 'linux'),
+        ['!proc/**', '!sys/**', '!dev/**'],
+    );
+    // Scans rooted elsewhere — including inside a kernel tree — are untouched.
+    assert.deepEqual(rootScanIgnoreGlobs('/proc', 'linux'), []);
+    assert.deepEqual(rootScanIgnoreGlobs('/home/user/project', 'linux'), []);
+    assert.deepEqual(rootScanIgnoreGlobs('', 'linux'), []);
+    // Windows has no kernel-virtual mounts; the helper is a no-op there.
+    assert.deepEqual(rootScanIgnoreGlobs('/', 'win32'), []);
+});

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

@@ -3,6 +3,7 @@ import { stat } from 'node:fs/promises';
 import { createHash } from 'crypto';
 import { isAbsolute, resolve } from 'path';
 import { trueCasePath } from './path-utils.mjs';
+import { expandAbsoluteGlobs } from './lib/absolute-glob-expand.mjs';
 import {
     canonicalizeGlobSlashes,
     coerceReadFamilyPathArg,
@@ -48,6 +49,7 @@ import {
     buildGrepCacheKey,
     buildGrepRgArgs,
     DEFAULT_IGNORE_GLOBS,
+    rootScanIgnoreGlobs,
 } from './search-builders.mjs';
 import { runRg, runRgWindowedLines, rgSupportsPcre2 } from './native-search-runner.mjs';
 import { markScopedCacheIncomplete } from '../../session/cache/scoped-cache-outcome.mjs';
@@ -408,13 +410,28 @@ export async function executeGlobTool(args, workDir, options = {}) {
             const base = String(rel).split('/').filter(Boolean).pop() || '';
             return base !== '' && !hasGlobMagic(base);
         });
+        // A pattern that NAMES a pruned directory is asking for it: only the
+        // wildcard basename decided this before, so `node_modules/**/index.js`
+        // was answered while `__pycache__/*.pyc` returned "(no files found)"
+        // for a file sitting right there. The yield is per-directory — every
+        // other prune stays on — and a negative pattern never counts as a
+        // request for its own target.
+        const namedDirs = new Set([
+            ...rels.flatMap((rel) => String(rel).replace(/^!/, '').split('/')),
+            ...String(root || '').replace(/\\/g, '/').split('/'),
+        ].filter((segment) => segment && !hasGlobMagic(segment)));
         for (const ex of DEFAULT_IGNORE_GLOBS) {
-            if (explicitBasenames && /^!\*\*\/[^/]+\/\*\*$/.test(ex)) continue;
+            const pruned = /^!\*\*\/([^/]+)\/\*\*$/.exec(ex);
+            if (pruned && (explicitBasenames || namedDirs.has(pruned[1]))) continue;
             rgArgs.push('--glob', ex);
         }
         for (const ex of extraIgnoreGlobs) rgArgs.push('--glob', ex);
         for (const rel of rels) rgArgs.push('--glob', rel);
         const rgCwd = resolvedForSearchRoot(root);
+        // Root-anchored kernel-tree prunes trail every positive glob so
+        // rg's later-glob-wins rule can never re-admit /proc//sys//dev on a
+        // full-root scan.
+        for (const ex of rootScanIgnoreGlobs(rgCwd)) rgArgs.push('--glob', ex);
         rgArgs.push('.');
         const cwdStat = await statCached(rgCwd);
         if (cwdStat.err) {
@@ -589,6 +606,18 @@ export async function executeGlobTool(args, workDir, options = {}) {
         : (rgStdoutTruncated ? '\n... [truncated at rg stdout cap (20MB); results incomplete]' : '')
             + (rgStdoutPartial ? '\n... [warning] rg exit 2 (partial results); listing may be incomplete' : '');
     const errSuffix = (rgErrors.length > 0 ? `\n... [warning] ${rgErrors.join(' | ')}` : '') + truncSuffix;
+    // An absolute pattern that enumerated nothing may still have real matches
+    // the inventory walker cannot see: it does not follow symlinked
+    // directories, and /sys, /proc and friends are made of them. Expand those
+    // patterns straight off the filesystem before declaring the miss.
+    if (capped.length === 0 && rgErrors.length === 0) {
+        const direct = await expandAbsoluteGlobs(patterns, {
+            limit: headLimit === Infinity ? 50 : offset + headLimit,
+        });
+        const window = offset > 0 ? direct.slice(offset) : direct;
+        const shown = headLimit === Infinity ? window : window.slice(0, headLimit);
+        if (shown.length > 0) return globPatternCapNote + shown.join('\n');
+    }
     let emptyDiag = '';
     if (capped.length === 0 && rgErrors.length === 0) {
         const patternStr = patterns.length === 1 ? JSON.stringify(patterns[0]) : JSON.stringify(patterns);

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

@@ -69,6 +69,10 @@ import { runGrepPathFanout } from './lib/grep-path-fanout.mjs';
 import { runGrepPatternFanout } from './lib/grep-pattern-fanout.mjs';
 import { runGrepChunkMerge } from './lib/grep-chunk-merge.mjs';
 import { runGrepFixedStringFallback } from './lib/grep-fixed-fallback.mjs';
+import {
+    MAX_RESCUE_BYTES as GREP_RESCUE_MAX_BYTES,
+    runGrepSingleFileRescue,
+} from './lib/grep-single-file-rescue.mjs';
 
 // A single glob string may pack multiple filters
 // separated by whitespace or commas, e.g. "*.ts,*.tsx" or "*.ts *.tsx". Split
@@ -95,6 +99,15 @@ function _grepDefaultHeadLimit() {
     return parsed > 0 ? parsed : 250;
 }
 
+// One explicit FILE is scanned directly by the native server — there is no tree
+// to walk — so a long deadline on a file scope can only ever be spent QUEUED
+// behind another request's walk. A scope rooted in a virtual filesystem
+// (/proc, /sys) is exactly that walk, and it starved the searches behind it:
+// a six-line /proc/self/status failed after 17.7s while a plain read of the
+// same file answered in 7ms. Bound the file case to a fraction of the turn and
+// let the JS rescue below answer it instead of spending the turn waiting.
+const SINGLE_FILE_SEARCH_DEADLINE_MS = 2_500;
+
 function _grepContextCharBudget(options = {}) {
     const explicit = Number(options?._grepContextCharBudget);
     if (Number.isFinite(explicit) && explicit > 0) return Math.floor(explicit);
@@ -542,7 +555,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
                 fileType,
                 onlyMatching: false,
             });
-            const probeOut = await runRg(probeArgs, { cwd: rgSpawnCwd, signal: sharedSignal });
+            const probeOut = await runRg(probeArgs, searchExecOptions);
             if (String(probeOut).split('\n').some(Boolean)) {
                 return ' (case-insensitive would match — try -i)';
             }
@@ -560,6 +573,18 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
         : null;
 
     const GREP_CONTENT_HARD_CAP = 300;
+    const singleFileScope = grepStat.isFile();
+    // Bound ONLY the file sizes the JS rescue below can actually answer. A
+    // bigger file keeps the full budget, so the short deadline can never cost
+    // a caller an answer it would otherwise have received. (A procfs file
+    // reports size 0 and is therefore always bounded — exactly the case that
+    // motivated the bound.)
+    const boundSingleFile = singleFileScope && Number(grepStat.size) <= GREP_RESCUE_MAX_BYTES;
+    const searchExecOptions = {
+        cwd: rgSpawnCwd,
+        signal: sharedSignal,
+        ...(boundSingleFile ? { timeout: SINGLE_FILE_SEARCH_DEADLINE_MS } : {}),
+    };
     try {
         const callerExplicitUnlimited = headLimitCoerced === 0;
         const effectiveHeadLimit = headLimit === Infinity
@@ -620,7 +645,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
                 let ctxPartialSuffix = '';
                 const streamed = await runRgWindowedLines(
                     anchorArgs,
-                    { cwd: rgSpawnCwd, signal: sharedSignal },
+                    searchExecOptions,
                     { offset: 0, limit: anchorCap, summaryLimit: 0 },
                 );
                 let ctxTotalKnown = streamed.complete;
@@ -689,7 +714,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
                 ? GREP_CONTEXT_LINE_HARD_CAP
                 : Math.min(GREP_CONTEXT_LINE_HARD_CAP, Math.max(200, blockBudget * Math.max(1, perBlock) + 8));
             let ctxPartialSuffix = '';
-            const streamed = await runRgWindowedLines(rgArgs, { cwd: rgSpawnCwd, signal: sharedSignal }, { offset: 0, limit: lineCap, summaryLimit: 0 });
+            const streamed = await runRgWindowedLines(rgArgs, searchExecOptions, { offset: 0, limit: lineCap, summaryLimit: 0 });
             const allLines = streamed.lines;
             let ctxTotalKnown = streamed.complete;
             if (streamed.partial) {
@@ -739,7 +764,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
         let rgPartialSuffix = '';
         if (effectiveHeadLimit !== Infinity) {
             const summaryLimit = outputMode === 'content' ? 120 : 0;
-            const streamed = await runRgWindowedLines(rgArgs, { cwd: rgSpawnCwd, signal: sharedSignal }, {
+            const streamed = await runRgWindowedLines(rgArgs, searchExecOptions, {
                 offset,
                 limit: effectiveHeadLimit,
                 summaryLimit,
@@ -757,7 +782,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
                     : '\n[warning] rg exit 2 (partial results)';
             }
         } else {
-            const stdout = await runRg(rgArgs, { cwd: rgSpawnCwd, signal: sharedSignal });
+            const stdout = await runRg(rgArgs, searchExecOptions);
             const allLines = String(stdout).split('\n').filter(Boolean);
             windowed = offset > 0 ? allLines.slice(offset) : allLines;
             totalWindowed = windowed.length;
@@ -857,6 +882,36 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
     }
     catch (err) {
         if (sharedSignal?.aborted) throw err;
+        // A file scope the native server could not serve is answered by reading
+        // the file; only a scanner that cannot reproduce the request declines.
+        const nativeMissed = err?.code === 'NATIVE_SEARCH_TIMEOUT'
+            || err?.code === 'NATIVE_SEARCH_UNAVAILABLE'
+            || err?.code === 'NATIVE_SEARCH_UNSUPPORTED';
+        if (nativeMissed && singleFileScope) {
+            const rescued = await runGrepSingleFileRescue({
+                filePath: grepResolvedPath,
+                searchPath,
+                patterns,
+                caseInsensitive,
+                multilineMode,
+                onlyMatching: args['-o'] === true,
+                fileType,
+                outputMode,
+                showLineNumbers,
+                withFilename: forceGrepFilename,
+                filenameOmitted,
+                beforeN,
+                afterN,
+                contextN,
+                headLimit,
+                offset,
+                workDir,
+                grepResolvedPath,
+                patternCapNote,
+                globPatterns: normalizedGlobPatterns,
+            });
+            if (rescued !== null) return rescued;
+        }
         if (isRgRegexParseError(err) && !multilineMode) {
             // Fixed-string rescue lives in lib/grep-fixed-fallback.mjs;
             // null falls through to the original rg error below.