mixdog 0.7.1

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

@@ -0,0 +1,256 @@
+// --- Tool definitions for external models ---
+//
+// Ordered to match the previous hand-maintained tools.json entries
+// (read / edit / write / bash / grep / glob) so
+// build-tools-manifest reproduces the legacy ordering.
+// CANONICAL SOURCE for all tool annotations (compressible, readOnlyHint,
+// destructiveHint, etc.). tools.json is GENERATED from this array by
+// dev/scripts/build-tools-manifest.mjs — do not edit annotations in tools.json
+// directly. To verify sync: node dev/scripts/check-tools-sync.mjs
+export const BUILTIN_TOOLS = [
+    {
+        name: 'read',
+        title: 'Mixdog Read',
+        annotations: { title: 'Mixdog Read', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false },
+        description: 'Read file contents (path required). symbol=NAME = whole definition; offset/limit or line/context = window; mode/max_lines = whole-file glance. Batch all regions of a file in one call. Output is the file text verbatim (line-number prefix only, no character escaping) — a \\uXXXX you see is literally in the file.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string' },
+                offset: { type: 'number', description: 'Start line for a windowed read (1-based).' },
+                limit: { type: 'number', description: 'Max lines to read (default 2000; full:true uncaps).' },
+                line: { type: 'number' },
+                context: { type: 'number', description: 'Lines around `line` (default 20).' },
+                pages: { type: 'string' },
+                symbol: { type: 'string', description: 'Read a whole symbol body (function/class/const) via the code graph.' },
+                language: { type: 'string', description: 'Language hint for symbol resolution.' },
+                mode: { type: 'string', enum: ['head', 'tail', 'count', 'summary', 'hex'], description: 'Whole-file glance: head/tail (first/last n), count (line/word/byte stats), summary (stats+head), hex (binary preview). For a window use offset/limit.' },
+                n: { type: 'number', description: 'Line count for mode head/tail/summary (default 20).' },
+                full: { type: 'boolean', description: 'Default false. true = return whole file (bypass 2000-line cap; still byte-capped).' },
+                max_lines: { type: 'number', description: 'Whole-file read: cap output to ~N lines. Ignored with offset/limit/mode.' },
+                budget: { type: 'string', enum: ['compact'], description: 'Auto-shrink: whole-file -> count; line -> context<=20; range -> limit<=120.' },
+            },
+        },
+    },
+    {
+        name: 'edit',
+        title: 'Mixdog Edit',
+        annotations: { title: 'Mixdog Edit', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+        description: 'Exact-string editor for small known substitutions; for large or structural changes prefer apply_patch. operation: replace (default) | notebook | rename.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                operation: { type: 'string', enum: ['replace', 'notebook', 'rename'], description: 'Edit mode: "replace" (default, exact text edit), "notebook" (Jupyter cell edit), or "rename" (symbol rename).' },
+                path: { type: 'string' },
+                old_string: { type: 'string' },
+                new_string: { type: 'string' },
+                replace_all: { type: 'boolean' },
+                edits: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string' },
+                            old_string: { type: 'string' },
+                            new_string: { type: 'string' },
+                            replace_all: { type: 'boolean' },
+                        },
+                        required: ['old_string', 'new_string'],
+                        additionalProperties: false,
+                    },
+                    minItems: 1,
+                    description: 'Batch replacements (operation:"replace").',
+                },
+                notebook_path: { type: 'string', description: 'operation:"notebook" — path to the .ipynb notebook to edit.' },
+                cell_id: { type: 'string', description: 'operation:"notebook" — target cell: a real cell.id or a cell-N index. For insert, the new cell is placed after this cell (or at the start if omitted).' },
+                new_source: { type: 'string', description: 'operation:"notebook" — new source for the cell (not required for delete).' },
+                cell_type: { type: 'string', enum: ['code', 'markdown'], description: 'operation:"notebook" — cell type. Required for insert; otherwise defaults to the current cell type.' },
+                edit_mode: { type: 'string', enum: ['replace', 'insert', 'delete'], description: 'operation:"notebook" — replace (default), insert, or delete.' },
+                symbol: { type: 'string', description: 'operation:"rename" — identifier to rename.' },
+                new_name: { type: 'string', description: 'operation:"rename" — new identifier.' },
+                file: { type: 'string', description: 'operation:"rename" — optional file to scope the reference search.' },
+                apply: { type: 'boolean', description: 'operation:"rename" — default false (preview). Set true to perform the rename.' },
+            },
+        },
+    },
+    {
+        name: 'write',
+        title: 'Mixdog Write',
+        annotations: { title: 'Mixdog Write', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+        description: 'Write a whole file — new, or a full rewrite of one already read. For partial edits use apply_patch; never overwrite an unread file.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string' },
+                content: { type: 'string' },
+                allow_unread_overwrite: { type: 'boolean', description: 'Default false. true = skip ONLY the read-before-overwrite snapshot gate when you already know the full intended content; all other write safety checks still apply.' },
+                writes: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string' },
+                            content: { type: 'string' },
+                        },
+                        required: ['path', 'content'],
+                        additionalProperties: false,
+                    },
+                    minItems: 1,
+                    description: 'Batch writes.',
+                },
+            },
+        },
+    },
+    {
+        name: 'diagnostics',
+        title: 'Mixdog Diagnostics',
+        annotations: { title: 'Mixdog Diagnostics', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true, compressible: true },
+        description: 'Run the matching type/lint checker under path (tsc/eslint/ruff/etc.). Default cwd; no LSP.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File or directory to diagnose. Defaults to cwd.' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'open_config',
+        title: 'Open Config UI',
+        annotations: { title: 'Open Config UI', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        description: 'Open the mixdog settings UI (Providers + Presets) in the browser. Starts the resident config server if needed and returns the UI URL. No params.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'bash',
+        title: 'Mixdog Shell',
+        annotations: { title: 'Mixdog Shell', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true, compressible: true },
+        description: "Shell for git/build/test/run. Use current-OS syntax: Windows default = PowerShell; POSIX default = /bin/sh. Always pass shell matching your syntax: 'bash' = POSIX via Git Bash, 'powershell' = PS cmdlets; omitting uses the OS default and mis-parses the other. run_in_background works for both shells, including Windows shell:'bash' (Git Bash). Single shell entry point; not for inline code you were asked to return.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                command: { type: 'string' },
+                cwd: { type: 'string' },
+                timeout: { type: 'number', description: 'Timeout in ms, or seconds when <=600.' },
+                merge_stderr: { type: 'boolean' },
+                run_in_background: { type: 'boolean' },
+                persistent: { type: 'boolean' },
+                session_id: { type: 'string' },
+                create: { type: 'boolean', description: 'Allow creating a new persistent session for an explicit session_id.' },
+                close: { type: 'boolean' },
+                shell: { type: 'string', enum: ['bash', 'powershell'], description: "Force the shell. On Windows: 'bash' runs the command through Git Bash (POSIX syntax), 'powershell' forces PowerShell. On POSIX: 'powershell' resolves pwsh if installed (errors if absent); 'bash' is /bin/sh (already the default). Always set this explicitly; omitting uses the OS default (PowerShell on Windows), where POSIX syntax fails to parse." },
+            },
+            required: ['command'],
+        },
+    },
+    {
+        name: 'job_wait',
+        title: 'Background Job Control',
+        annotations: { title: 'Background Job Control', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        description: 'Control a bash run_in_background job by job_id. action: wait (default) | peek | kill. Not for bridge_*/sess_* ids.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                job_id: { type: 'string', description: 'job_id from bash with run_in_background:true.' },
+                action: { type: 'string', enum: ['wait', 'peek', 'kill'], description: 'wait (default) = block until done; peek = non-blocking status + output tail; kill = terminate.' },
+                timeout_ms: { type: 'number' },
+                poll_ms: { type: 'number' },
+            },
+            required: ['job_id'],
+        },
+    },
+    {
+        name: 'grep',
+        title: 'Mixdog Grep',
+        annotations: { title: 'Mixdog Grep', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
+        description: 'Search file contents (ripgrep): free-text / non-symbol content. For a symbol by name use code_graph, not grep. pattern (regex) or glob. output_mode: content (default) | files_with_matches | count. Array pattern matches several in ONE call. -A/-B/-C is line-based — useless on minified/single-line files; use -o or multiline.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pattern: {
+                    anyOf: [
+                        { type: 'string' },
+                        { type: 'array', items: { type: 'string' }, minItems: 1 },
+                    ],
+                    description: 'Ripgrep regex, or an array of regexes (OR-matched; <=20, <=5 with multiline) to match several in one call.',
+                },
+                path: { type: 'string' },
+                glob: {
+                    anyOf: [
+                        { type: 'string' },
+                        { type: 'array', items: { type: 'string' }, minItems: 1 },
+                    ],
+                    description: 'Glob, or an array of globs, to filter files.',
+                },
+                output_mode: { type: 'string', enum: ['files_with_matches', 'content', 'count'], description: 'Default content (matching lines). files_with_matches = paths only; count = per-file counts.' },
+                head_limit: { type: 'number', description: 'Max result lines (default 80; 0 = unlimited). Truncated output says how many results remain.' },
+                offset: { type: 'number', description: 'Skip N result lines before head_limit applies — for paging large result sets.' },
+                '-i': { type: 'boolean' },
+                '-n': { type: 'boolean' },
+                '-A': { type: 'number' },
+                '-B': { type: 'number' },
+                '-C': { type: 'number', description: 'Context lines (with -A/-B). Line-based; no effect on single-line/minified files — use -o.' },
+                context: { type: 'number' },
+                multiline: { type: 'boolean', description: 'Dot matches newlines; patterns span lines (rg -U). Pair with -o on single-line/minified files.' },
+                '-o': { type: 'boolean', description: 'Only matching parts (rg --only-matching).' },
+                type: { type: 'string' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'glob',
+        title: 'Mixdog Glob',
+        annotations: { title: 'Mixdog Glob', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
+        description: 'Find files by glob pattern (mtime-sorted). For name/size/date filters use list mode:find.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pattern: {
+                    anyOf: [
+                        { type: 'string' },
+                        { type: 'array', items: { type: 'string' }, minItems: 1 },
+                    ],
+                    description: 'Glob or array.',
+                },
+                path: {
+                    anyOf: [
+                        { type: 'string' },
+                        { type: 'array', items: { type: 'string' }, minItems: 1 },
+                    ],
+                    description: 'Base dir or array.',
+                },
+                head_limit: { type: 'number', description: 'Max entries returned (mtime-sorted). A truncated listing ends with "pass offset:N to continue" — re-call with that offset to page.' },
+                offset: { type: 'number', description: 'Skip N entries before head_limit applies; use the footer-suggested value to page.' },
+            },
+            required: ['pattern'],
+        },
+    },
+    {
+        name: 'list',
+        title: 'Mixdog List Directory',
+        annotations: { title: 'Mixdog List Directory', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
+        description: 'List or find directory entries. mode: list | tree | find (name/size/date filter). fuzzy ranks by partial name. Default cwd.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string' },
+                mode: { type: 'string', enum: ['list', 'tree', 'find'], description: 'Default list (flat dir). tree = recursive tree; find = name/size/date filter.' },
+                depth: { type: 'number' },
+                hidden: { type: 'boolean' },
+                sort: { type: 'string', enum: ['name', 'mtime', 'size'] },
+                type: { type: 'string', enum: ['any', 'file', 'dir'] },
+                head_limit: { type: 'number', description: 'Max entries returned. A truncated listing ends with "[entries X-Y of T; pass offset:N to continue]" — re-call with that offset to page.' },
+                offset: { type: 'number', description: 'Skip N entries before head_limit applies; use the footer-suggested value to page.' },
+                include_noise: { type: 'boolean' },
+                name: { type: 'string' },
+                min_size: { type: 'number' },
+                max_size: { type: 'number' },
+                modified_after: { type: 'string' },
+                modified_before: { type: 'string' },
+                fuzzy: { type: 'string', description: 'Rank files by subsequence match of this partial name; overrides mode. e.g. "edeng" -> edit-engine.mjs.' },
+            },
+            required: [],
+        },
+    },
+];

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

@@ -0,0 +1,386 @@
+import { statSync } from 'fs';
+import * as fsPromises from 'fs/promises';
+import { isAbsolute, normalize, resolve, sep } from 'path';
+import { deleteReadRangeIndexForPath } from './read-range-index.mjs';
+import { resolveAgainstCwd } from './path-utils.mjs';
+
+const RESULT_CACHE = new Map(); // key → { ts, value, paths, scopes, readSnapshotMeta, contentPrefixHash, bytes }
+const RESULT_CACHE_TTL_MS = 30_000;
+const RESULT_CACHE_MAX_ENTRIES = 200;
+const RESULT_CACHE_MAX_BYTES = (() => {
+    const rawBytes = Number(process.env.MIXDOG_RESULT_CACHE_MAX_BYTES);
+    if (Number.isFinite(rawBytes) && rawBytes > 0) return Math.trunc(rawBytes);
+    const rawMb = Number(process.env.MIXDOG_RESULT_CACHE_MAX_MB);
+    if (Number.isFinite(rawMb) && rawMb > 0) return Math.trunc(rawMb * 1024 * 1024);
+    return 32 * 1024 * 1024;
+})();
+let RESULT_CACHE_BYTES = 0;
+function estimateResultBytes(value) {
+    if (value == null) return 0;
+    if (typeof value === 'string') return Buffer.byteLength(value, 'utf-8');
+    if (Buffer.isBuffer(value)) return value.length;
+    try { return Buffer.byteLength(JSON.stringify(value) ?? '', 'utf-8'); }
+    catch { return 0; }
+}
+function resultCacheDelete(key) {
+    const entry = RESULT_CACHE.get(key);
+    if (entry && typeof entry.bytes === 'number') {
+        RESULT_CACHE_BYTES = Math.max(0, RESULT_CACHE_BYTES - entry.bytes);
+    }
+    RESULT_CACHE.delete(key);
+}
+const STAT_CACHE = new Map(); // fullPath → { ts, stat }
+const STAT_CACHE_TTL_MS = 5_000;
+const STAT_CACHE_MAX_ENTRIES = 2_000;
+const RAW_CONTENT_CACHE = new Map(); // fullPath → { ts, mtimeMs, ctimeMs, size, rawBuf }
+const RAW_CONTENT_CACHE_TTL_MS = 30_000;
+const RAW_CONTENT_CACHE_MAX_ENTRIES = 16;
+const PATH_MUTATION_GENERATIONS = new Map(); // canonical path/root → monotonic generation
+const PATH_MUTATION_GENERATION_MAX_ENTRIES = 4096;
+let PATH_MUTATION_GLOBAL_GENERATION = 0;
+const RAW_CONTENT_CACHE_MAX_BYTES = (() => {
+    const rawBytes = Number(process.env.MIXDOG_RAW_CONTENT_CACHE_MAX_BYTES);
+    if (Number.isFinite(rawBytes) && rawBytes > 0) return Math.trunc(rawBytes);
+    const rawMb = Number(process.env.MIXDOG_RAW_CONTENT_CACHE_MAX_MB);
+    if (Number.isFinite(rawMb) && rawMb > 0) return Math.trunc(rawMb * 1024 * 1024);
+    return 64 * 1024 * 1024;
+})();
+let RAW_CONTENT_CACHE_BYTES = 0;
+
+function canonicalCachePath(p) {
+    const full = normalize(resolve(String(p || '')));
+    return process.platform === 'win32' ? full.toLowerCase() : full;
+}
+
+function normalizeCacheMetaPaths(values) {
+    if (!Array.isArray(values)) return [];
+    return Array.from(new Set(
+        values
+            .filter(Boolean)
+            .map((v) => canonicalCachePath(v)),
+    ));
+}
+
+function cachePathsOverlap(a, b) {
+    if (!a || !b) return false;
+    if (a === b) return true;
+    return a.startsWith(b.endsWith(sep) ? b : `${b}${sep}`)
+        || b.startsWith(a.endsWith(sep) ? a : `${a}${sep}`);
+}
+
+function bumpPathMutationGeneration(path) {
+    const key = canonicalCachePath(path);
+    PATH_MUTATION_GENERATIONS.set(key, (PATH_MUTATION_GENERATIONS.get(key) || 0) + 1);
+    while (PATH_MUTATION_GENERATIONS.size > PATH_MUTATION_GENERATION_MAX_ENTRIES) {
+        const oldest = PATH_MUTATION_GENERATIONS.keys().next().value;
+        if (!oldest) break;
+        PATH_MUTATION_GENERATIONS.delete(oldest);
+    }
+}
+
+export function getPathMutationGeneration(path) {
+    const key = canonicalCachePath(path);
+    let generation = PATH_MUTATION_GLOBAL_GENERATION;
+    for (const [changedPath, value] of PATH_MUTATION_GENERATIONS) {
+        if (cachePathsOverlap(key, changedPath)) generation += value;
+    }
+    return generation;
+}
+
+function cacheEntryOverlapsPaths(entry, affectedPaths) {
+    const entryPaths = Array.isArray(entry?.paths) ? entry.paths : [];
+    const entryScopes = Array.isArray(entry?.scopes) ? entry.scopes : [];
+    for (const affected of affectedPaths) {
+        for (const p of entryPaths) {
+            if (cachePathsOverlap(p, affected)) return true;
+        }
+        for (const scope of entryScopes) {
+            if (cachePathsOverlap(scope, affected)) return true;
+        }
+    }
+    return false;
+}
+
+export function cacheGetEntry(key) {
+    const entry = RESULT_CACHE.get(key);
+    if (!entry) {
+        return null;
+    }
+    if (Date.now() - entry.ts > RESULT_CACHE_TTL_MS) {
+        resultCacheDelete(key);
+        return null;
+    }
+    return entry;
+}
+
+export function cacheGet(key) {
+    return cacheGetEntry(key)?.value ?? null;
+}
+
+export function cacheSet(key, value, meta = {}) {
+    // Replace-in-place: clear old entry's byte accounting before write.
+    if (RESULT_CACHE.has(key)) resultCacheDelete(key);
+    const bytes = estimateResultBytes(value);
+    RESULT_CACHE.set(key, {
+        ts: Date.now(),
+        value,
+        paths: normalizeCacheMetaPaths(meta.paths),
+        scopes: normalizeCacheMetaPaths(meta.scopes),
+        readSnapshotMeta: meta.readSnapshotMeta || null,
+        contentPrefixHash: meta.contentPrefixHash || '',
+        bytes,
+    });
+    RESULT_CACHE_BYTES += bytes;
+    // Evict oldest (insertion-order) entries until under both the entry
+    // count cap and the byte budget. Mirrors RAW_CONTENT_CACHE shape.
+    while (RESULT_CACHE.size > RESULT_CACHE_MAX_ENTRIES || RESULT_CACHE_BYTES > RESULT_CACHE_MAX_BYTES) {
+        const oldest = RESULT_CACHE.keys().next().value;
+        if (!oldest || oldest === key) break;
+        resultCacheDelete(oldest);
+    }
+}
+
+function rawContentCacheDelete(key) {
+    const entry = RAW_CONTENT_CACHE.get(key);
+    if (entry?.rawBuf) RAW_CONTENT_CACHE_BYTES = Math.max(0, RAW_CONTENT_CACHE_BYTES - entry.rawBuf.length);
+    RAW_CONTENT_CACHE.delete(key);
+}
+
+export function rawContentCacheGet(fullPath, stat, now = Date.now()) {
+    if (!fullPath || !stat) return null;
+    const key = canonicalCachePath(fullPath);
+    const entry = RAW_CONTENT_CACHE.get(key);
+    if (!entry) return null;
+    if (now - entry.ts > RAW_CONTENT_CACHE_TTL_MS) {
+        rawContentCacheDelete(key);
+        return null;
+    }
+    if (entry.size !== stat.size
+        || Math.abs(entry.mtimeMs - stat.mtimeMs) > 1
+        || Math.abs(entry.ctimeMs - stat.ctimeMs) > 1) {
+        rawContentCacheDelete(key);
+        return null;
+    }
+    RAW_CONTENT_CACHE.delete(key);
+    RAW_CONTENT_CACHE.set(key, entry);
+    return entry.rawBuf;
+}
+
+export function rawContentCacheSet(fullPath, stat, rawBuf, now = Date.now()) {
+    if (!fullPath || !stat || !Buffer.isBuffer(rawBuf)) return;
+    if (rawBuf.length > RAW_CONTENT_CACHE_MAX_BYTES) return;
+    const key = canonicalCachePath(fullPath);
+    rawContentCacheDelete(key);
+    RAW_CONTENT_CACHE.set(key, {
+        ts: now,
+        mtimeMs: stat.mtimeMs,
+        ctimeMs: stat.ctimeMs,
+        size: stat.size,
+        rawBuf,
+    });
+    RAW_CONTENT_CACHE_BYTES += rawBuf.length;
+    while (RAW_CONTENT_CACHE.size > RAW_CONTENT_CACHE_MAX_ENTRIES || RAW_CONTENT_CACHE_BYTES > RAW_CONTENT_CACHE_MAX_BYTES) {
+        const oldest = RAW_CONTENT_CACHE.keys().next().value;
+        if (!oldest) break;
+        rawContentCacheDelete(oldest);
+    }
+}
+
+export function seedRawContentCacheAfterWrite(fullPath, content, st = null) {
+    try {
+        const rawBuf = Buffer.isBuffer(content) ? content : Buffer.from(String(content ?? ''), 'utf-8');
+        const writtenStat = st && typeof st.size === 'number' ? st : statSync(fullPath);
+        rawContentCacheSet(fullPath, writtenStat, rawBuf);
+        return writtenStat;
+    } catch { return st || null; }
+}
+
+function statCacheGet(fullPath, now = Date.now()) {
+    const entry = STAT_CACHE.get(fullPath);
+    if (!entry) return null;
+    if (now - entry.ts > STAT_CACHE_TTL_MS) {
+        STAT_CACHE.delete(fullPath);
+        return null;
+    }
+    return entry.stat;
+}
+
+export function statCacheSet(fullPath, stat, now = Date.now()) {
+    if (STAT_CACHE.size >= STAT_CACHE_MAX_ENTRIES) {
+        const oldest = STAT_CACHE.keys().next().value;
+        if (oldest) STAT_CACHE.delete(oldest);
+    }
+    STAT_CACHE.set(fullPath, { ts: now, stat });
+}
+
+export function getCachedReadOnlyStat(fullPath, loader = statSync, now = Date.now()) {
+    const cached = statCacheGet(fullPath, now);
+    if (cached) return cached;
+    const stat = loader(fullPath);
+    statCacheSet(fullPath, stat, now);
+    return stat;
+}
+
+export async function statPathsForMtime(paths, workDir, concurrency = 64, opts = {}) {
+    const items = Array.isArray(paths) ? paths : [];
+    const out = new Array(items.length);
+    const now = Date.now();
+    const inflight = new Map();
+    let next = 0;
+    // Hard per-stat deadline (0 = disabled, legacy behaviour). A hung stat
+    // (dead mount / unresponsive network path) must not pin a worker forever;
+    // on expiry the entry resolves to null (stat-failed) so glob's post-rg stat
+    // phase is bounded instead of running to the 600s bridge watchdog.
+    const deadlineMs = Number(opts.deadlineMs) > 0 ? Number(opts.deadlineMs) : 0;
+    // Injectable stat impl for testing hung-FS behaviour deterministically.
+    const statImpl = typeof opts._statImpl === 'function' ? opts._statImpl : fsPromises.stat;
+
+    async function resolveStat(full) {
+        let pending = inflight.get(full);
+        if (!pending) {
+            const statBase = statImpl(full)
+                .then((stat) => {
+                    statCacheSet(full, stat, now);
+                    return stat;
+                })
+                .catch(() => null);
+            let base = statBase;
+            if (deadlineMs > 0) {
+                // ref timer (not unref): the deadline MUST fire even when the
+                // hung stat is the only pending work — that is exactly the case
+                // we bound. clearTimeout on the normal path keeps a fast stat
+                // from holding the loop for the full deadline window.
+                base = new Promise((resolve) => {
+                    let settled = false;
+                    const timer = setTimeout(() => { if (!settled) { settled = true; resolve(null); } }, deadlineMs);
+                    statBase.then((v) => { if (!settled) { settled = true; clearTimeout(timer); resolve(v); } });
+                });
+            }
+            pending = base;
+            inflight.set(full, pending);
+        }
+        return pending;
+    }
+
+    async function worker() {
+        while (true) {
+            const index = next++;
+            if (index >= items.length) return;
+            const p = items[index];
+            const full = isAbsolute(p) ? p : resolveAgainstCwd(p, workDir);
+            try {
+                const stat = await resolveStat(full);
+                if (!stat) throw new Error('stat failed');
+                out[index] = { path: p, full, stat, size: stat.size, mtime: stat.mtimeMs, mtimeMs: stat.mtimeMs };
+            } catch {
+                out[index] = { path: p, full, stat: null, size: 0, mtime: 0, mtimeMs: 0 };
+            }
+        }
+    }
+    const workerCount = Math.min(Math.max(1, concurrency), Math.max(1, items.length));
+    await Promise.all(Array.from({ length: workerCount }, worker));
+    return out;
+}
+
+// lstat variant — does NOT follow symlinks. Use for directory-listing
+// surfaces where a symlink to a 200 GB file should report as a symlink,
+// not as the target's size/mtime.
+export async function lstatPathsForMtime(paths, workDir, concurrency = 64, opts = {}) {
+    const items = Array.isArray(paths) ? paths : [];
+    const out = new Array(items.length);
+    const inflight = new Map();
+    let next = 0;
+    // Hard per-lstat deadline (0 = disabled, legacy behaviour). A hung lstat
+    // (dead mount / unresponsive network path) must not pin a worker forever;
+    // on expiry the entry resolves to null (stat-failed) so list's stat phase
+    // is bounded instead of running to the 600s bridge watchdog.
+    const deadlineMs = Number(opts.deadlineMs) > 0 ? Number(opts.deadlineMs) : 0;
+    // Injectable lstat impl for testing hung-FS behaviour deterministically.
+    const lstatImpl = typeof opts._lstatImpl === 'function' ? opts._lstatImpl : fsPromises.lstat;
+
+    async function resolveLstat(full) {
+        let pending = inflight.get(full);
+        if (!pending) {
+            const lstatBase = lstatImpl(full).catch(() => null);
+            let base = lstatBase;
+            if (deadlineMs > 0) {
+                // ref timer (not unref): the deadline MUST fire even when the
+                // hung lstat is the only pending work — that is exactly the case
+                // we bound. clearTimeout on the normal path keeps a fast lstat
+                // from holding the loop for the full deadline window.
+                base = new Promise((resolve) => {
+                    let settled = false;
+                    const timer = setTimeout(() => { if (!settled) { settled = true; resolve(null); } }, deadlineMs);
+                    lstatBase.then((v) => { if (!settled) { settled = true; clearTimeout(timer); resolve(v); } });
+                });
+            }
+            pending = base;
+            inflight.set(full, pending);
+        }
+        return pending;
+    }
+
+    async function worker() {
+        while (true) {
+            const index = next++;
+            if (index >= items.length) return;
+            const p = items[index];
+            const full = isAbsolute(p) ? p : resolveAgainstCwd(p, workDir);
+            try {
+                const stat = await resolveLstat(full);
+                if (!stat) throw new Error('lstat failed');
+                out[index] = { path: p, full, stat, size: stat.size, mtime: stat.mtimeMs, mtimeMs: stat.mtimeMs };
+            } catch {
+                out[index] = { path: p, full, stat: null, size: 0, mtime: 0, mtimeMs: 0 };
+            }
+        }
+    }
+    const workerCount = Math.min(Math.max(1, concurrency), Math.max(1, items.length));
+    await Promise.all(Array.from({ length: workerCount }, worker));
+    return out;
+}
+
+function cacheInvalidateAll() {
+    RESULT_CACHE.clear();
+    RESULT_CACHE_BYTES = 0;
+    STAT_CACHE.clear();
+    RAW_CONTENT_CACHE.clear();
+    RAW_CONTENT_CACHE_BYTES = 0;
+    PATH_MUTATION_GENERATIONS.clear();
+    PATH_MUTATION_GLOBAL_GENERATION += 1;
+}
+
+function cacheInvalidatePaths(paths) {
+    const affectedPaths = normalizeCacheMetaPaths(Array.isArray(paths) ? paths : [paths]);
+    if (affectedPaths.length === 0) {
+        cacheInvalidateAll();
+        return;
+    }
+    for (const [key, entry] of RESULT_CACHE) {
+        if (cacheEntryOverlapsPaths(entry, affectedPaths)) {
+            resultCacheDelete(key);
+        }
+    }
+    for (const key of [...STAT_CACHE.keys()]) {
+        if (affectedPaths.some((affected) => cachePathsOverlap(canonicalCachePath(key), affected))) {
+            STAT_CACHE.delete(key);
+        }
+    }
+    for (const key of [...RAW_CONTENT_CACHE.keys()]) {
+        if (affectedPaths.some((affected) => cachePathsOverlap(key, affected))) {
+            rawContentCacheDelete(key);
+        }
+    }
+    for (const affected of affectedPaths) {
+        deleteReadRangeIndexForPath(affected);
+        bumpPathMutationGeneration(affected);
+    }
+}
+
+export function invalidateBuiltinResultCache(paths = null) {
+    if (Array.isArray(paths) ? paths.length > 0 : Boolean(paths)) {
+        cacheInvalidatePaths(paths);
+        return;
+    }
+    cacheInvalidateAll();
+}