mixdog 0.9.150 → 0.9.151

package/src/runtime/agent/orchestrator/session/manager/session-lifecycle.mjs

@@ -41,11 +41,7 @@ import { ensureCodexWireSessionId, mintSessionId, mintUuidV7 } from './session-i
 import { providerCacheKey } from './provider-cache-key.mjs';
 import { clearTurnCheckpoint, recoverTurnCheckpoint } from './turn-checkpoint.mjs';
 import { IMPLICIT_APPROVAL_MODE } from '../approval-mode.mjs';
-import {
-    describeGitStartupState,
-    describeShellStartupPolicy,
-    detectPathCapabilities,
-} from '../../tools/builtin/runtime-capabilities.mjs';
+import { describeGitStartupState } from '../../tools/builtin/runtime-capabilities.mjs';
 import { captureOriginalUserCwd } from '../../../../shared/user-cwd.mjs';
 import { refreshSessionBp3Environment } from './prompt-utils.mjs';
 
@@ -315,12 +311,7 @@ export function createSession(opts) {
     // resolves explicit session signals first and never leaks the daemon's
     // install root (user-cwd.mjs safe fallback chain).
     const sessionCwdLine = opts.cwd || captureOriginalUserCwd();
-    const wantsShellStartupLine = toolsForRouting.some((tool) => tool?.name === 'shell');
     const wantsGitStartupLine = toolsForRouting.some((tool) => tool?.name === 'git');
-    // One PATH walk feeds every startup line below.
-    const startupCapabilities = wantsShellStartupLine || wantsGitStartupLine
-        ? detectPathCapabilities()
-        : null;
     const shellEnvironmentContext = [
         sessionCwdLine
             ? `- Cwd: ${sessionCwdLine} — the active Project root; relative paths and shell commands resolve here.`
@@ -328,18 +319,15 @@ export function createSession(opts) {
         !ownerIsAgent
             ? `- Shell: ${process.platform === 'win32' ? 'PowerShell' : 'Bash'}. Use ${process.platform === 'win32' ? 'PowerShell' : 'Bash'} syntax unless the user specifies otherwise.`
             : '',
-        wantsShellStartupLine
-            ? describeShellStartupPolicy({ capabilities: startupCapabilities })
-            : '',
-        // Whether the cwd is inside a repository is the fact the git tool
-        // needs and cannot infer: a PATH listing only says the binary exists.
-        // Without it a session spends a call discovering `exited 128`, and
+        // A startup inventory of PATH binaries used to sit here; see
+        // runtime-capabilities.mjs for why it cannot be stated truthfully
+        // before a command has run. Whether the cwd is inside a repository is
+        // different: it is a property of this directory, true at startup and
+        // observable without spawning anything, and the git tool cannot infer
+        // it. Without it a session spends a call discovering `exited 128`, and
         // repeats it per candidate path.
         wantsGitStartupLine
-            ? describeGitStartupState({
-                capabilities: startupCapabilities,
-                ...(sessionCwdLine ? { cwd: sessionCwdLine } : {}),
-            })
+            ? describeGitStartupState(sessionCwdLine ? { cwd: sessionCwdLine } : {})
             : '',
     ].filter(Boolean).join('\n');
     const { baseRules, stableSystemContext, sessionMarkerCore, sessionEnvironment } = composeSystemPrompt({

package/src/runtime/agent/orchestrator/tools/builtin/absolute-glob-expand.test.mjs

@@ -0,0 +1,63 @@
+// An absolute glob is expanded straight off the filesystem when the inventory
+// walker cannot see its targets (symlink farms such as /sys and /proc). The
+// pattern bounds the walk; anything unbounded or unsupported declines.
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+
+import { expandAbsoluteGlob, expandAbsoluteGlobs } from './lib/absolute-glob-expand.mjs';
+
+async function withBlockTree(run) {
+    const root = await mkdtemp(join(tmpdir(), 'mixdog-abs-glob-'));
+    try {
+        for (const disk of ['sda', 'sdb', 'nvme0n1']) {
+            await mkdir(join(root, 'block', disk, 'device'), { recursive: true });
+            await writeFile(join(root, 'block', disk, 'size'), '2048\n');
+            await writeFile(join(root, 'block', disk, 'device', 'model'), `${disk}-model\n`);
+        }
+        return await run(root);
+    } finally {
+        await rm(root, { recursive: true, force: true });
+    }
+}
+
+test('a magic middle segment expands to every matching path', async () => {
+    await withBlockTree(async (root) => {
+        const sizes = await expandAbsoluteGlob(join(root, 'block', 'sd*', 'size'));
+        assert.equal(sizes.length, 2);
+        assert.ok(sizes.every((p) => p.endsWith('/size')));
+        assert.ok(sizes.some((p) => p.includes('/sda/')));
+        assert.ok(sizes.some((p) => p.includes('/sdb/')));
+
+        const models = await expandAbsoluteGlob(join(root, 'block', '*', 'device', 'model'));
+        assert.equal(models.length, 3);
+    });
+});
+
+test('a pattern with no matches answers empty, not null', async () => {
+    await withBlockTree(async (root) => {
+        assert.deepEqual(await expandAbsoluteGlob(join(root, 'block', 'hd*', 'size')), []);
+    });
+});
+
+test('unbounded or non-absolute patterns decline so the caller keeps its answer', async () => {
+    await withBlockTree(async (root) => {
+        assert.equal(await expandAbsoluteGlob(join(root, '**', 'size')), null);
+        assert.equal(await expandAbsoluteGlob('block/sd*/size'), null);
+        assert.equal(await expandAbsoluteGlob(join(root, 'block', 'sda', 'size')), null);
+    });
+});
+
+test('the batch form dedupes and honours its limit', async () => {
+    await withBlockTree(async (root) => {
+        const found = await expandAbsoluteGlobs([
+            join(root, 'block', 'sd*', 'size'),
+            join(root, 'block', 's*a', 'size'),
+        ], { limit: 5 });
+        assert.equal(found.length, 2);
+        const limited = await expandAbsoluteGlobs([join(root, 'block', '*', 'size')], { limit: 1 });
+        assert.equal(limited.length, 1);
+    });
+});

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

@@ -1,4 +1,4 @@
-import { statSync, createWriteStream } from 'fs';
+import { statSync, lstatSync, realpathSync, createWriteStream } from 'fs';
 import * as fsPromises from 'fs/promises';
 import { basename, dirname, join } from 'path';
 import { performance } from 'perf_hooks';
@@ -73,6 +73,21 @@ async function cleanupEmptyWxTarget(targetPath) {
     } catch { /* already gone or unreadable — leave it */ }
 }
 
+// The real file a write aimed at `targetPath` must land on when the leaf is a
+// symlink, or null when it is not a link (or is dangling, so there is nothing
+// to resolve). Writers rename a temp file into place, which would replace the
+// LINK itself with a regular file and silently detach layouts like nginx's
+// sites-enabled/default from sites-available/default. Engines that write a
+// path themselves use this as "do not hand this target to the engine".
+export function symlinkWriteTarget(targetPath) {
+    try {
+        if (!lstatSync(targetPath).isSymbolicLink()) return null;
+        return realpathSync(targetPath);
+    } catch {
+        return null;
+    }
+}
+
 export async function atomicWrite(targetPath, content, {
     mode,
     signal,
@@ -95,12 +110,16 @@ export async function atomicWrite(targetPath, content, {
     };
     if (resolvedSignal?.aborted) throw abortReason();
 
-    const dir = dirname(targetPath);
+    // Write THROUGH a leaf symlink: resolve it first so the rename replaces the
+    // file the link points at, not the link. Resolving also keeps the temp file
+    // beside the real target, so the rename stays on one filesystem.
+    const writeTarget = symlinkWriteTarget(targetPath) ?? targetPath;
+    const dir = dirname(writeTarget);
     const rnd = randomBytes(4).toString('hex');
-    const tmp = join(dir, `.${basename(targetPath)}.mixdog-tmp-${rnd}`);
+    const tmp = join(dir, `.${basename(writeTarget)}.mixdog-tmp-${rnd}`);
     let effectiveMode = mode;
     let existingStat = null;
-    try { existingStat = statSync(targetPath); } catch { /* target doesn't exist */ }
+    try { existingStat = statSync(writeTarget); } catch { /* target doesn't exist */ }
     if (effectiveMode === undefined && existingStat) {
         effectiveMode = existingStat.mode & 0o777;
     }
@@ -165,7 +184,7 @@ export async function atomicWrite(targetPath, content, {
     if (flags === 'wx') {
         let excl = null;
         try {
-            excl = await fsPromises.open(targetPath, 'wx');
+            excl = await fsPromises.open(writeTarget, 'wx');
             await excl.close();
         } catch (exclErr) {
             if (excl) try { await excl.close(); } catch { /* already closed */ }
@@ -179,7 +198,7 @@ export async function atomicWrite(targetPath, content, {
 
     if (resolvedSignal?.aborted) {
         try { await fsPromises.unlink(tmp); } catch { /* already gone */ }
-        if (flags === 'wx') await cleanupEmptyWxTarget(targetPath);
+        if (flags === 'wx') await cleanupEmptyWxTarget(writeTarget);
         throw abortReason();
     }
 
@@ -188,16 +207,16 @@ export async function atomicWrite(targetPath, content, {
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
         if (expectedTargetSnapshot) {
             let currentStat = null;
-            try { currentStat = statSync(targetPath); } catch { currentStat = null; }
+            try { currentStat = statSync(writeTarget); } catch { currentStat = null; }
             if (expectedTargetSnapshotChanged(currentStat, expectedTargetSnapshot)) {
                 try { await fsPromises.unlink(tmp); } catch { /* already gone */ }
-                const err = new Error(`target changed between preflight and rename (TOCTOU): ${targetPath}`);
+                const err = new Error(`target changed between preflight and rename (TOCTOU): ${writeTarget}`);
                 err.code = 'ESTALE_TARGET';
                 throw err;
             }
         }
         try {
-            await fsPromises.rename(tmp, targetPath);
+            await fsPromises.rename(tmp, writeTarget);
             // When fsync is requested, also fsync the parent directory so
             // the rename itself is durable across power-loss. Directory
             // fsync is a no-op / unsupported on Windows; swallow EPERM /
@@ -231,6 +250,6 @@ export async function atomicWrite(targetPath, content, {
         }
     }
     try { await fsPromises.unlink(tmp); } catch { /* already gone */ }
-    if (flags === 'wx') await cleanupEmptyWxTarget(targetPath);
+    if (flags === 'wx') await cleanupEmptyWxTarget(writeTarget);
     throw lastErr;
 }

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

@@ -44,7 +44,7 @@ export const BUILTIN_TOOLS = [
         name: 'read',
         title: 'Read',
         annotations: { title: 'Read', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false },
-        description: 'Read-only; safe to batch in parallel. Known-file contents or line ranges. Read only lines not already returned by another tool, using the smallest anchored range needed; never read an entire file when an existing result provides the relevant location. Do not read an output artifact after a still-valid passed check has established the needed facts. Images render for viewing; not directories. Replaces cat/head/tail.',
+        description: 'Read-only; safe to batch in parallel. Known-file contents or line ranges, bounded to the narrowest range that answers the question — when the answer depends on content not yet seen, read the wider range once instead of deciding from a partial view. Images render for viewing; not directories. Replaces cat/head/tail.',
         inputSchema: {
             type: 'object',
             properties: {

package/src/runtime/agent/orchestrator/tools/builtin/enoent-outside-project.test.mjs

@@ -0,0 +1,56 @@
+// A missing ABSOLUTE path outside the project is recovered from its OWN
+// filesystem, never from a project-wide scan: no file inside the project can
+// be the correction for /sys/block/sd*/size, and the scan is what turned three
+// such reads into 17.5s each.
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+
+import { executeBuiltinTool } from '../builtin.mjs';
+
+async function withDirs(run) {
+    const project = await mkdtemp(join(tmpdir(), 'mixdog-enoent-project-'));
+    const outside = await mkdtemp(join(tmpdir(), 'mixdog-enoent-outside-'));
+    try {
+        return await run({ project, outside });
+    } finally {
+        await rm(project, { recursive: true, force: true });
+        await rm(outside, { recursive: true, force: true });
+    }
+}
+
+test('an outside absolute miss names its own nearest directory, not the project', async () => {
+    await withDirs(async ({ project, outside }) => {
+        await mkdir(join(project, 'src'), { recursive: true });
+        await writeFile(join(project, 'src', 'size'), 'decoy\n');
+        await mkdir(join(outside, 'block'), { recursive: true });
+        await writeFile(join(outside, 'block', 'sda'), 'disk\n');
+
+        const out = String(await executeBuiltinTool('read', {
+            file_path: join(outside, 'block', 'sd*', 'size'),
+        }, project));
+
+        assert.match(out, /\[path absent\]/);
+        assert.match(out, /nearest existing directory/);
+        assert.match(out, /"sda"/);
+        // The decoy inside the project must never be offered for an outside path.
+        assert.doesNotMatch(out, /same filename exists at/);
+        assert.doesNotMatch(out, /project scan/);
+    });
+});
+
+test('a miss INSIDE the project keeps its same-name recovery', async () => {
+    await withDirs(async ({ project }) => {
+        await mkdir(join(project, 'src', 'tools'), { recursive: true });
+        await writeFile(join(project, 'src', 'tools', 'widget.mjs'), 'export const widget = 1;\n');
+
+        const out = String(await executeBuiltinTool('read', {
+            file_path: join(project, 'lib', 'widget.mjs'),
+        }, project));
+
+        assert.match(out, /widget\.mjs/);
+        assert.doesNotMatch(out, /nearest existing directory/);
+    });
+});

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

@@ -13,7 +13,7 @@
 // the existing EXTERNAL_TOOL_REDIRECTS guidance message in that case.
 import { readFileSync, mkdirSync, existsSync, lstatSync, realpathSync, statSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { atomicWrite } from './atomic-write.mjs';
+import { atomicWrite, symlinkWriteTarget } from './atomic-write.mjs';
 import { assertPathsReachable } from './fs-reachability.mjs';
 import { normalizeInputPath, resolveAgainstCwd, normalizeOutputPath } from './path-utils.mjs';
 import { isUncPath, isWindowsDevicePath, hasUnsafeWin32Component, isBlockedDevicePath, isSpecialFileStat } from './device-paths.mjs';
@@ -587,7 +587,11 @@ async function adaptStrReplace(args, workDir, options) {
     // An unverified native edit session never receives work: the in-process
     // apply below is the fallback, so a stale/spoofed engine cannot touch bytes.
     const nativeEditVerified = await nativeEditSessionSatisfiesContract();
-    if (!nativeEditVerified || fileEnc.encoding !== 'utf8' || editPlan.rebased || !editPlan.uniform) {
+    // A symlinked target never reaches the native engine either: it writes the
+    // path it is handed, which would replace the link with a regular file. The
+    // in-process apply goes through atomicWrite, which writes through the link.
+    const symlinkedTarget = symlinkWriteTarget(fullPath) !== null;
+    if (!nativeEditVerified || symlinkedTarget || fileEnc.encoding !== 'utf8' || editPlan.rebased || !editPlan.uniform) {
         const occurrences = editPlan.positions.length;
         if (occurrences === 0) {
             const message = 'old_string not found';

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

@@ -21,21 +21,31 @@ import {
 const DEFAULT_TIMEOUT_MS = 120_000;
 const MAX_CAPTURE_BYTES = 128 * 1024 * 1024;
 const GIT_OUTPUT_LIMIT_MAX = 200;
-const SUPPORTED = new Set([
-    'add', 'am', 'apply', 'archive', 'bisect', 'blame', 'branch', 'bundle',
-    'cat-file', 'check-attr', 'check-ignore', 'check-ref-format', 'checkout',
-    'cherry', 'cherry-pick', 'clean', 'clone', 'commit', 'config',
-    'count-objects', 'describe', 'diff', 'diff-files', 'diff-index', 'diff-tree',
-    'fetch', 'filter-branch', 'for-each-ref', 'format-patch', 'fsck', 'gc',
-    'grep', 'hash-object', 'help', 'init', 'log', 'ls-files', 'ls-remote',
-    'ls-tree', 'maintenance', 'merge', 'merge-base', 'merge-tree', 'mv',
-    'name-rev', 'notes', 'pack-refs', 'prune', 'pull', 'push', 'range-diff',
-    'rebase', 'reflog', 'remote', 'repack', 'replace', 'reset', 'restore',
-    'revert', 'rev-list', 'rev-parse', 'rm', 'shortlog', 'show', 'show-branch',
-    'show-ref', 'sparse-checkout', 'stash', 'status', 'submodule', 'switch',
-    'symbolic-ref', 'tag', 'update-ref', 'verify-commit', 'verify-pack',
-    'verify-tag', 'version', 'whatchanged', 'worktree', 'write-tree',
-]);
+// git's subcommand namespace is open-ended: any `git-*` executable on PATH
+// (git-filter-repo, git-lfs, in-house wrappers) dispatches as a subcommand, so
+// a finite allowlist can never keep up. It rejected `git filter-repo` as an
+// "unsupported subcommand" while the shell tool still ran the very same
+// command unblocked — buying no safety and costing a whole turn. So nothing is
+// pre-rejected for being unknown: git itself reports a genuinely unknown
+// subcommand, and that error tells the model what to do next.
+//
+// Destructive history/tree rewrites stay allowed on purpose. They are usually
+// the actual job, reflog and loose objects make most of them recoverable, and
+// the workflow already gates destructive git work.
+//
+// What this tool genuinely cannot host is a command that never returns, since
+// each call occupies one synchronous turn. The classic hangs are already dead
+// via the pinned GIT_PAGER / GIT_EDITOR / GIT_SEQUENCE_EDITOR /
+// GIT_TERMINAL_PROMPT environment in runProcess, which leaves two shapes.
+//
+// A GUI subcommand blocks on a window or a stdin prompt that this process has
+// no way to satisfy.
+const GUI_OPERATIONS = new Set(['gui', 'citool', 'gitk', 'difftool', 'mergetool']);
+// A resident server's correct behaviour IS to keep running, so it can only
+// burn the full timeout here. It is not a bad command, just one in the wrong
+// tool: shell promotes a long-running process to a background task, so point
+// there instead of failing it outright.
+const SERVER_OPERATIONS = new Set(['daemon', 'instaweb']);
 // `git --version` / `git --help` are the standard availability probes and
 // arrive in global-flag position, not as subcommands. Map them onto their
 // subcommand form so the probe answers instead of erroring out.
@@ -197,7 +207,13 @@ function parseCommand(command, workDir) {
     }
     const rawOperation = String(tokens[index] || '').toLowerCase();
     const operation = OPERATION_ALIASES.get(rawOperation) ?? rawOperation;
-    if (!SUPPORTED.has(operation)) throw new Error(`unsupported git subcommand: ${rawOperation || '(missing)'}`);
+    if (!operation) throw new Error('git requires a subcommand');
+    if (GUI_OPERATIONS.has(operation)) {
+        throw new Error(`git ${operation} opens an interactive GUI and would never return here; use its non-interactive form (diff, merge, add -p)`);
+    }
+    if (SERVER_OPERATIONS.has(operation)) {
+        throw new Error(`git ${operation} is a long-running server; start it with the shell tool so it becomes a background task`);
+    }
     return { command: String(command), cwd, globalArgs, operation, args: tokens.slice(index + 1) };
 }
 

package/src/runtime/agent/orchestrator/tools/builtin/git-command-tool.test.mjs

@@ -229,6 +229,34 @@ test('git availability probes answer instead of erroring', async (t) => {
     assert.match(probe, /git version/i);
 });
 
+// git dispatches any `git-*` executable on PATH as a subcommand, so a finite
+// allowlist could only ever go stale. An unknown name must reach git itself —
+// whatever git answers is actionable, an "unsupported subcommand" refusal was
+// not, and the shell tool ran the same command anyway.
+test('git forwards unknown subcommands to git instead of pre-rejecting them', async (t) => {
+    const root = mkdtempSync(join(tmpdir(), 'mixdog-git-open-'));
+    t.after(() => rmSync(root, { recursive: true, force: true }));
+    const repo = join(root, 'repo');
+    parseOk(await executeGitTool({ command: `git init ${quote(repo)}` }, root));
+    for (const command of ['git filter-repo --version', 'git fast-export --help']) {
+        assert.doesNotMatch(String(await executeGitTool({ command }, repo)), /unsupported git subcommand/);
+    }
+});
+
+// The only commands this tool cannot host are the ones that never return: a
+// GUI blocks on a window nobody can click, and a resident server burns the
+// full timeout by working correctly. The server case is a routing hint, not a
+// verdict — shell can hold it as a background task.
+test('git refuses only non-returning subcommands and routes servers to shell', async (t) => {
+    const root = mkdtempSync(join(tmpdir(), 'mixdog-git-deny-'));
+    t.after(() => rmSync(root, { recursive: true, force: true }));
+    const repo = join(root, 'repo');
+    parseOk(await executeGitTool({ command: `git init ${quote(repo)}` }, root));
+    assert.match(String(await executeGitTool({ command: 'git mergetool' }, repo)), /interactive GUI/i);
+    assert.match(String(await executeGitTool({ command: 'git daemon --export-all' }, repo)), /shell tool/i);
+    assert.match(String(await executeGitTool({ command: 'git' }, repo)), /requires a subcommand/i);
+});
+
 test('git stages selected change IDs and rejects stale diff snapshots without touching the index', async (t) => {
     const root = mkdtempSync(join(tmpdir(), 'mixdog-git-stage-'));
     t.after(() => rmSync(root, { recursive: true, force: true }));

package/src/runtime/agent/orchestrator/tools/builtin/grep-single-file-rescue.test.mjs

@@ -0,0 +1,106 @@
+// A file scope the shared native search server could not serve is answered by
+// reading that one file, so a starved queue costs a bounded wait instead of a
+// whole turn. The scanner declines whenever it cannot reproduce the request.
+import assert from 'node:assert/strict';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+
+import { runGrepSingleFileRescue } from './lib/grep-single-file-rescue.mjs';
+
+const STATUS = 'Name:\tnode\nUid:\t0\t0\t0\t0\nGid:\t0\t0\t0\t0\nCapEff:\t000001ffffffffff\n';
+
+function request(overrides) {
+    return {
+        caseInsensitive: false,
+        multilineMode: false,
+        onlyMatching: false,
+        fileType: null,
+        outputMode: 'content',
+        showLineNumbers: true,
+        withFilename: false,
+        filenameOmitted: true,
+        beforeN: 0,
+        afterN: 0,
+        contextN: 0,
+        headLimit: 250,
+        offset: 0,
+        patternCapNote: '',
+        globPatterns: [],
+        ...overrides,
+    };
+}
+
+async function withStatusFile(run) {
+    const root = await mkdtemp(join(tmpdir(), 'mixdog-grep-rescue-'));
+    try {
+        const file = join(root, 'status');
+        await writeFile(file, STATUS);
+        return await run({ root, file });
+    } finally {
+        await rm(root, { recursive: true, force: true });
+    }
+}
+
+test('a missed file scope is scanned directly and reports the same matches', async () => {
+    await withStatusFile(async ({ root, file }) => {
+        const out = await runGrepSingleFileRescue(request({
+            filePath: file,
+            searchPath: file,
+            grepResolvedPath: file,
+            workDir: root,
+            patterns: ['^(Uid|Gid|Cap(Inh|Prm|Eff|Bnd|Amb))'],
+        }));
+        assert.match(out, /2:Uid:/);
+        assert.match(out, /3:Gid:/);
+        assert.match(out, /4:CapEff:/);
+        assert.doesNotMatch(out, /Name:/);
+        assert.match(out, /scanned directly/);
+    });
+});
+
+test('counts and no-match answers keep the ordinary grep shapes', async () => {
+    await withStatusFile(async ({ root, file }) => {
+        const counted = await runGrepSingleFileRescue(request({
+            filePath: file,
+            searchPath: file,
+            grepResolvedPath: file,
+            workDir: root,
+            outputMode: 'count',
+            patterns: ['^(Uid|Gid)'],
+        }));
+        assert.match(counted, /\b2\b/);
+
+        const empty = await runGrepSingleFileRescue(request({
+            filePath: file,
+            searchPath: file,
+            grepResolvedPath: file,
+            workDir: root,
+            patterns: ['NoSuchFieldHere'],
+        }));
+        assert.match(empty, /\(no matches\)/);
+    });
+});
+
+test('a request the scanner cannot reproduce declines instead of guessing', async () => {
+    await withStatusFile(async ({ root, file }) => {
+        const base = {
+            filePath: file,
+            searchPath: file,
+            grepResolvedPath: file,
+            workDir: root,
+        };
+        // Regex JS cannot compile: the caller keeps the native error.
+        assert.equal(await runGrepSingleFileRescue(request({
+            ...base,
+            patterns: ['a{2,1}'],
+        })), null);
+        // Multiline matching spans lines; this scanner is line-oriented.
+        assert.equal(await runGrepSingleFileRescue(request({
+            ...base,
+            patterns: ['Uid'],
+            multilineMode: true,
+        })), null);
+    });
+});

package/src/runtime/agent/orchestrator/tools/builtin/lib/absolute-glob-expand.mjs

@@ -0,0 +1,129 @@
+// Direct filesystem expansion for an ABSOLUTE glob pattern.
+//
+// The inventory walker never follows a symlinked directory — the right call on
+// a project tree, where following them means cycles and duplicated subtrees.
+// But a virtual filesystem is built almost entirely out of symlinks:
+// /sys/block/sda is a link into /sys/devices, and /sys/block/sda/device is
+// another one. A pattern like /sys/block/sd*/size therefore enumerates NOTHING
+// through the walker, and the caller is told the path does not exist while it
+// plainly does.
+//
+// The pattern itself is the bound here: only segments that match are descended,
+// one readdir per surviving directory, no recursive `**`, plus a candidate cap
+// and a wall-clock deadline. Returns the matches (possibly empty), or null when
+// the pattern is not expandable this way and the caller should keep its own
+// answer.
+import { readdir, stat } from 'node:fs/promises';
+import { isAbsolute, join, parse } from 'node:path';
+
+import { hasGlobMagic, normalizeOutputPath } from '../path-utils.mjs';
+
+const DEFAULT_DEADLINE_MS = 1_500;
+const DEFAULT_CANDIDATE_CAP = 200;
+
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** One path SEGMENT's matcher, or null when the segment uses a construct this
+ *  expander will not approximate. */
+function segmentMatcher(segment) {
+    if (segment.includes('**')) return null;
+    let source = '';
+    for (let index = 0; index < segment.length; index += 1) {
+        const char = segment[index];
+        if (char === '*') { source += '[^/]*'; continue; }
+        if (char === '?') { source += '[^/]'; continue; }
+        if (char === '[') {
+            const end = segment.indexOf(']', index + 1);
+            if (end < 0) return null;
+            source += segment.slice(index, end + 1);
+            index = end;
+            continue;
+        }
+        if (char === '{') {
+            const end = segment.indexOf('}', index + 1);
+            if (end < 0) return null;
+            const alternatives = segment.slice(index + 1, end).split(',').map(escapeRegExp);
+            source += `(?:${alternatives.join('|')})`;
+            index = end;
+            continue;
+        }
+        source += escapeRegExp(char);
+    }
+    try {
+        return new RegExp(`^${source}$`, process.platform === 'win32' ? 'i' : '');
+    } catch {
+        return null;
+    }
+}
+
+export async function expandAbsoluteGlob(pattern, {
+    limit = 25,
+    deadlineMs = DEFAULT_DEADLINE_MS,
+    candidateCap = DEFAULT_CANDIDATE_CAP,
+} = {}) {
+    const raw = String(pattern || '').replace(/\\/g, '/');
+    if (!raw || !isAbsolute(raw) || !hasGlobMagic(raw)) return null;
+    const root = parse(raw).root;
+    if (!root) return null;
+    const segments = raw.slice(root.length).split('/').filter(Boolean);
+    if (segments.length === 0) return null;
+    const stopAt = Date.now() + Math.max(1, deadlineMs);
+
+    let current = [root];
+    for (const segment of segments) {
+        if (Date.now() >= stopAt) return null;
+        if (!hasGlobMagic(segment)) {
+            current = current.map((dir) => join(dir, segment));
+            continue;
+        }
+        const matcher = segmentMatcher(segment);
+        if (!matcher) return null;
+        const next = [];
+        for (const dir of current) {
+            if (next.length >= candidateCap || Date.now() >= stopAt) break;
+            let entries;
+            try { entries = await readdir(dir); } catch { continue; }
+            for (const name of entries) {
+                if (!matcher.test(name)) continue;
+                next.push(join(dir, name));
+                if (next.length >= candidateCap) break;
+            }
+        }
+        current = next;
+        if (current.length === 0) return [];
+    }
+
+    // stat (not lstat) so a symlinked target counts as the file/dir it names —
+    // that is the whole point of expanding these scopes.
+    const found = [];
+    for (const candidate of current) {
+        if (found.length >= limit || Date.now() >= stopAt) break;
+        try {
+            const info = await stat(candidate);
+            if (info.isFile() || info.isDirectory()) found.push(normalizeOutputPath(candidate));
+        } catch { /* a pattern match that cannot be stat'ed is not a result */ }
+    }
+    return found;
+}
+
+/** Expand every absolute pattern in a list; returns deduped matches in order. */
+export async function expandAbsoluteGlobs(patterns, options = {}) {
+    const list = (Array.isArray(patterns) ? patterns : [patterns]).filter(
+        (value) => typeof value === 'string' && value,
+    );
+    const seen = new Set();
+    const out = [];
+    for (const pattern of list) {
+        if (out.length >= (options.limit ?? 25)) break;
+        const matches = await expandAbsoluteGlob(pattern, options);
+        if (!matches) continue;
+        for (const match of matches) {
+            if (seen.has(match)) continue;
+            seen.add(match);
+            out.push(match);
+        }
+    }
+    return out;
+}