mixdog 0.9.23 → 0.9.25

package/src/runtime/agent/orchestrator/tools/bash-session.mjs

@@ -54,12 +54,16 @@ globalThis.__mixdogBashSessionRuntimeLoaded = true;
 // Claude Code parity (refs/claude-code src/utils/timeouts.ts): default 120 s
 // (2 min), max 600 s (10 min), BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS
 // env overrides (max floored at default). Matches the one-shot bash tool
-// (builtin/bash-tool.mjs); per-call `timeout` still overrides, capped at
-// MAX_TIMEOUT_MS.
+// (builtin/bash-tool.mjs): an omitted `timeout` uses the 120 s default bounded
+// by MAX_TIMEOUT_MS; an explicit per-call `timeout` is honored uncapped, clamped
+// only by TIMER_MAX_MS so JS/PS 32-bit timers stay valid.
 const _envDefaultTimeout = parseInt(process.env.BASH_DEFAULT_TIMEOUT_MS ?? '', 10);
 const DEFAULT_TIMEOUT_MS = _envDefaultTimeout > 0 ? _envDefaultTimeout : 120_000;
 const _envMaxTimeout = parseInt(process.env.BASH_MAX_TIMEOUT_MS ?? '', 10);
 const MAX_TIMEOUT_MS = Math.max(_envMaxTimeout > 0 ? _envMaxTimeout : 600_000, DEFAULT_TIMEOUT_MS);
+// JS setTimeout / PS WaitForExit(ms) are 32-bit: a delay above 2^31-1 wraps and
+// fires immediately. Hard ceiling (~24.8 days) for an uncapped explicit timeout.
+const TIMER_MAX_MS = 2_147_483_647;
 const IDLE_TIMEOUT_MS = 5 * 60_000;
 const MAX_SESSIONS = 10;
 const STDERR_DRAIN_MS = 25;
@@ -645,9 +649,13 @@ async function bash_session(args, cwd = process.cwd(), opts = {}) {
         }
         return requestedCwd;
     })();
-    const rawTimeout = typeof args?.timeout === 'number' ? args.timeout : DEFAULT_TIMEOUT_MS;
-    const timeoutMs = rawTimeout;
-    const effectiveTimeout = Math.min(Math.max(timeoutMs, 1), wmicRewrite?.timeoutMs || MAX_TIMEOUT_MS);
+    const hasExplicitTimeout = typeof args?.timeout === 'number' && args.timeout > 0;
+    const timeoutMs = hasExplicitTimeout ? args.timeout : DEFAULT_TIMEOUT_MS;
+    // Explicit per-call timeout uncapped (only the wmic-rewrite ceiling or the
+    // 32-bit TIMER_MAX_MS still bound it); omitted default keeps MAX_TIMEOUT_MS.
+    const effectiveTimeout = hasExplicitTimeout
+        ? Math.min(Math.max(timeoutMs, 1), wmicRewrite?.timeoutMs || TIMER_MAX_MS)
+        : Math.min(Math.max(timeoutMs, 1), wmicRewrite?.timeoutMs || MAX_TIMEOUT_MS);
     const resolved = _getOrCreate(requestedSessionId || args?.session_id, baseCwd, { create: args?.create === true });
     if (resolved.error) return resolved.error;
     const { id, entry } = resolved;

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

@@ -21,6 +21,7 @@ import {
 import {
     analyzeShellCommandEffects,
     foregroundLongCommandHint,
+    isAutobackgroundingAllowed,
 } from './shell-analysis.mjs';
 import {
     cancelBackgroundTask,
@@ -208,41 +209,56 @@ export async function executeBashTool(args, workDir, options = {}) {
     }
     // Keep foreground commands on a long tool-owned timeout. The MCP dispatch
     // layer must not add a shorter fallback ceiling when timeout is omitted.
-    // Claude Code parity (refs/claude-code src/utils/timeouts.ts): default
-    // 120 s (2 min), max 600 s (10 min); BASH_DEFAULT_TIMEOUT_MS /
-    // BASH_MAX_TIMEOUT_MS env overrides, max floored at default.
+    // Reference-CLI parity (opencode/codex/claude-code): sync-first, no hard
+    // upper ceiling on a caller-provided timeout. Default 120 s (2 min) when
+    // omitted; BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS env overrides keep
+    // their semantics (max floored at default) but only bound the *omitted*
+    // default — an explicit args.timeout is honored UNCAPPED.
     const _envDefaultTimeout = parseInt(process.env.BASH_DEFAULT_TIMEOUT_MS ?? '', 10);
     const DEFAULT_BASH_TIMEOUT_MS = _envDefaultTimeout > 0 ? _envDefaultTimeout : 120_000;
-    const DEFAULT_BACKGROUND_BASH_TIMEOUT_MS = DEFAULT_BASH_TIMEOUT_MS;
+    // Background (async / run_in_background) jobs get NO omitted default: 0
+    // means "unlimited" and flows unchanged through startBackgroundShellJob →
+    // task meta (detail.timeoutMs 0). An explicit args.timeout is still honored
+    // and enforced exactly as before. Sync path keeps the 120s omitted default.
+    const DEFAULT_BACKGROUND_BASH_TIMEOUT_MS = 0;
     const _envMaxTimeout = parseInt(process.env.BASH_MAX_TIMEOUT_MS ?? '', 10);
     const MAX_BASH_TIMEOUT_MS = Math.max(_envMaxTimeout > 0 ? _envMaxTimeout : 600_000, DEFAULT_BASH_TIMEOUT_MS);
     const defaultTimeoutMs = runInBackground
         ? DEFAULT_BACKGROUND_BASH_TIMEOUT_MS
         : DEFAULT_BASH_TIMEOUT_MS;
-    const rawTimeout = (typeof args.timeout === 'number' && args.timeout > 0)
-        ? args.timeout : defaultTimeoutMs;
-    const timeoutMs = rawTimeout;
-    const timeout = Math.min(timeoutMs, wmicRewrite?.timeoutMs || MAX_BASH_TIMEOUT_MS);
+    const hasExplicitTimeout = typeof args.timeout === 'number' && args.timeout > 0;
+    const timeoutMs = hasExplicitTimeout ? args.timeout : defaultTimeoutMs;
+    // Explicit caller timeout is uncapped (only the wmic-rewrite ceiling, when
+    // present, still bounds it); the omitted default keeps the MAX ceiling.
+    // JS timers (setTimeout) and PS WaitForExit(ms) are 32-bit: a delay above
+    // 2^31-1 wraps to a tiny/negative value and fires immediately. Clamp the
+    // uncapped explicit timeout once here (~24.8 days ceiling) so every
+    // downstream timer — foreground, background job, hard-stop watcher — stays
+    // valid without per-site guards.
+    const TIMER_MAX_MS = 2_147_483_647;
+    // timeoutMs <= 0 (omitted background default) means unlimited: pass it
+    // through untouched — the min() clamps below must not turn 0 into a bound.
+    const timeout = timeoutMs <= 0
+        ? 0
+        : (hasExplicitTimeout
+            ? Math.min(timeoutMs, wmicRewrite?.timeoutMs || TIMER_MAX_MS)
+            : Math.min(timeoutMs, wmicRewrite?.timeoutMs || MAX_BASH_TIMEOUT_MS));
     const mergeStderr = args.merge_stderr === true;
     const longForegroundHint = foregroundLongCommandHint(command, timeout, { ...args, run_in_background: runInBackground });
     if (longForegroundHint) return longForegroundHint;
-    // Auto-background threshold (CC ASSISTANT_BLOCKING_BUDGET_MS analogue):
-    // a foreground one-shot that is still running after this many ms is
-    // detached into a tracked shell-job instead of blocking the tool call
-    // indefinitely. Only the foreground one-shot path uses it — never
-    // run_in_background (already detached) or persistent sessions (handled
-    // far above). Capped below the hard timeout so the 600 s upper bound
-    // stays a separate, later ceiling.
-    // Soft config: reuse the sync task-wait budget (30 s, see waitForShellJob
-    // default in executeTaskTool) as the default promotion threshold. Override
-    // with MIXDOG_SHELL_AUTO_BACKGROUND_MS (positive ms). This is a soft hint,
-    // not a hard cap — the value is clamped below `timeout` so the hard ceiling
-    // stays a separate, later bound.
+    // Auto-background threshold. Reference-CLI parity: sync commands run to
+    // their timeout without any default auto-promotion, so the default is 0
+    // (disabled) for ALL callers. It is an explicit opt-in only: set
+    // MIXDOG_SHELL_AUTO_BACKGROUND_MS (positive ms) to re-enable detaching a
+    // still-running foreground one-shot into a tracked shell-job. When enabled,
+    // the value stays a soft hint clamped below `timeout` so the hard ceiling
+    // remains a separate, later bound. Never applies to run_in_background
+    // (already detached) or persistent sessions (handled far above).
     const _autoBgEnvMs = Number(process.env.MIXDOG_SHELL_AUTO_BACKGROUND_MS);
     const DEFAULT_AUTO_BACKGROUND_MS = Number.isFinite(_autoBgEnvMs) && _autoBgEnvMs > 0
       ? Math.floor(_autoBgEnvMs)
-      : 30_000;
-    const autoBackgroundMs = runInBackground
+      : 0;
+    const autoBackgroundMs = (runInBackground || DEFAULT_AUTO_BACKGROUND_MS <= 0)
       ? 0
       : Math.min(DEFAULT_AUTO_BACKGROUND_MS, timeout);
 
@@ -348,6 +364,19 @@ export async function executeBashTool(args, workDir, options = {}) {
                     : wrapBashWithCwdProbe(wrappedCommand, _stateFile);
             }
         } catch { syncCommand = wrappedCommand; }
+        // Promote-at-timeout (CC shouldAutoBackground parity). When a
+        // foreground one-shot hits its timeout and is still running, adopt it
+        // as a background job (task_id + notify) instead of tree-killing it.
+        // Opt-outs restore the old kill behavior: (a) disallowed sleep-like
+        // base commands (isAutobackgroundingAllowed), (b) the truthy
+        // MIXDOG_SHELL_DISABLE_BACKGROUND_TASKS env. Never applies to
+        // run_in_background (already detached, handled above).
+        const _bgTasksDisabled = /^(1|true|yes|on)$/i.test(
+            String(process.env.MIXDOG_SHELL_DISABLE_BACKGROUND_TASKS || '').trim(),
+        );
+        const backgroundOnTimeout = !runInBackground
+            && !_bgTasksDisabled
+            && isAutobackgroundingAllowed(command, shellType);
         const result = await execShellCommand({
             shell, shellArg, shellArgs, command: syncCommand,
             env: spawnEnv,
@@ -355,6 +384,9 @@ export async function executeBashTool(args, workDir, options = {}) {
             timeoutMs: timeout,
             abortSignal: combinedBashAbort,
             autoBackgroundMs,
+            // On a foreground timeout, promote the still-running child to a
+            // tracked background job (unlimited) instead of killing it.
+            backgroundOnTimeout,
             // Threaded so an auto-backgrounded foreground job is stamped with
             // the dispatching terminal's claude.exe pid (per-terminal scope).
             clientHostPid: options?.clientHostPid,
@@ -388,7 +420,10 @@ export async function executeBashTool(args, workDir, options = {}) {
                             stdout: result.stdoutPath ? normalizeOutputPath(result.stdoutPath) : null,
                             stderr: (!mergeStderr && result.stderrPath) ? normalizeOutputPath(result.stderrPath) : null,
                             cwd: bashWorkDir,
-                            timeoutMs: timeout,
+                            // Adopted foreground jobs run unlimited (timeoutMs 0)
+                            // — matches the async default; the original
+                            // foreground timeout no longer bounds the promoted job.
+                            timeoutMs: 0,
                         },
                         resultType: 'shell_task_result',
                         cancel: () => killShellJob(result.jobId),
@@ -430,8 +465,11 @@ export async function executeBashTool(args, workDir, options = {}) {
         // Timeout marker carries an inline recovery hint so the caller can
         // act in one round (increase ceiling or detach) instead of repeating
         // the same command and hitting the same wall.
+        const timeoutHint = result.timedOut
+            ? ` — command killed after ${timeout} ms; if it legitimately needs longer, retry with a larger timeout`
+            : '';
         const statusMarker = result.timedOut
-            ? `[timeout: ${timeout}ms signal: ${signal || 'SIGTERM'}]`
+            ? `[timeout: ${timeout}ms signal: ${signal || 'SIGTERM'}]${timeoutHint}`
             : (signal
                 ? `[signal: ${signal}]`
                 : (isReallyErrored ? `[exit code: ${exitCode}]` : ''));

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

@@ -12,10 +12,11 @@ import {
     executionModeSchemaDescription,
 } from '../../../../shared/background-tasks.mjs';
 
-// Shell timeout envelope surfaced in the tool schema. Mirrors Claude Code:
-// default 120 s / max 600 s, BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS
-// env overrides, max floored at default. Keep in sync with
-// builtin/bash-tool.mjs and bash-session.mjs.
+// Shell timeout envelope surfaced in the tool schema. Reference-CLI parity:
+// default 120 s when omitted; an explicit timeout is honored uncapped.
+// BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS env overrides only bound the
+// omitted default (max floored at default). Keep in sync with
+// builtin/bash-tool.mjs.
 function _shellDefaultTimeoutMs() {
     const parsed = parseInt(process.env.BASH_DEFAULT_TIMEOUT_MS ?? '', 10);
     return parsed > 0 ? parsed : 120_000;
@@ -72,7 +73,7 @@ export const BUILTIN_TOOLS = [
             properties: {
                 command: { type: 'string', description: 'Command.' },
                 cwd: { type: 'string', description: 'Working directory. Persists across shell calls in a session — omit to reuse the previous command\'s directory (e.g. after cd); pass an absolute path to change it.' },
-                timeout: { type: 'number', description: `Timeout ms. Default ${_shellDefaultTimeoutMs()} (${_shellDefaultTimeoutMs() / 60000} min); long-running commands may raise it up to ${_shellMaxTimeoutMs()} (${_shellMaxTimeoutMs() / 60000} min).` },
+                timeout: { type: 'number', description: `Timeout ms. Default ${_shellDefaultTimeoutMs()} (${_shellDefaultTimeoutMs() / 60000} min) when omitted; an explicit value is honored uncapped — long-running commands may set it higher. On timeout the command is MOVED TO BACKGROUND (a task_id you can wait/status/read/cancel) and keeps running instead of being killed; sleep-like commands and MIXDOG_SHELL_DISABLE_BACKGROUND_TASKS opt out (killed with a [timeout] marker). async/background runs with timeout omitted have NO timeout (run until done/cancelled); an explicit timeout is still enforced.` },
                 merge_stderr: { type: 'boolean', description: 'Merge stderr.' },
                 mode: { type: 'string', enum: ['sync', 'async'], description: executionModeSchemaDescription('sync') },
                 shell: { type: 'string', enum: ['bash', 'powershell'], description: 'Force shell. Windows defaults to PowerShell; bash = Git Bash/POSIX.' },
@@ -167,7 +168,7 @@ export const BUILTIN_TOOLS = [
         name: 'find',
         title: 'Mixdog Find Files',
         annotations: { title: 'Mixdog Find Files', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Find files by partial path/name. Returns verified paths. Batch names as query[].',
+        description: 'Find files by partial path/name, searching dot-directories (e.g. .git-adjacent, .mixdog) too. The right tool for locating a file at an unknown, possibly machine-wide path — run it from a verified broad root. Returns verified paths. Batch names as query[].',
         inputSchema: {
             type: 'object',
             properties: {

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

@@ -357,6 +357,22 @@ export async function lstatPathsForMtime(paths, workDir, concurrency = 64, opts
     return out;
 }
 
+// Extra invalidation listeners: sibling modules with their own derived caches
+// (e.g. the broad find-enumeration cache in list-tool) register a clear
+// callback here so every write-invalidation event that drops the result/stat/
+// raw caches also drops theirs. Full clear is intentional — those entries are
+// cheap to rebuild and a path-scoped diff is not worth the coupling.
+const EXTRA_INVALIDATION_LISTENERS = new Set();
+export function registerCacheInvalidationListener(fn) {
+    if (typeof fn === 'function') EXTRA_INVALIDATION_LISTENERS.add(fn);
+    return () => EXTRA_INVALIDATION_LISTENERS.delete(fn);
+}
+function runExtraInvalidationListeners() {
+    for (const fn of EXTRA_INVALIDATION_LISTENERS) {
+        try { fn(); } catch { /* best-effort: one listener must not block others */ }
+    }
+}
+
 function cacheInvalidateAll() {
     RESULT_CACHE.clear();
     RESULT_CACHE_INFLIGHT.clear();
@@ -366,6 +382,7 @@ function cacheInvalidateAll() {
     RAW_CONTENT_CACHE_BYTES = 0;
     PATH_MUTATION_GENERATIONS.clear();
     PATH_MUTATION_GLOBAL_GENERATION += 1;
+    runExtraInvalidationListeners();
 }
 
 function cacheInvalidatePaths(paths) {
@@ -394,6 +411,9 @@ function cacheInvalidatePaths(paths) {
         deleteReadRangeIndexForPath(affected);
         bumpPathMutationGeneration(affected);
     }
+    // Broad enumeration entries are not path-scoped, so any partial
+    // invalidation still fully drops them (cheap to rebuild).
+    runExtraInvalidationListeners();
 }
 
 export function invalidateBuiltinResultCache(paths = null) {

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

@@ -83,6 +83,20 @@ export function fuzzyScore(query, str) {
     return score;
 }
 
+// Below this per-query-char score, a subsequence-only match (query chars in
+// order but scattered mid-word, no contiguity/boundary structure) is treated
+// as noise rather than a real hit. Contiguous substring / basename matches
+// bypass the floor entirely — an exact hit must never be filtered.
+const SUBSEQUENCE_MIN_PER_CHAR = 4;
+
+// Separator/case-insensitive normalization used for the "contiguous substring"
+// strong-match test. Mirrors the query normalization in fuzzyScore so
+// "tool-events.log" matches a "tool-events.log" basename or a ".../tool-events.log"
+// path regardless of separators.
+function normalizeForContains(s) {
+    return String(s || '').toLowerCase().replace(/[\/\\_.\-\s]+/g, '');
+}
+
 /**
  * Rank candidates by fuzzy score against `query`, dropping non-matches.
  * @param {string} query
@@ -91,13 +105,30 @@ export function fuzzyScore(query, str) {
  * @returns {Array<{item:object, score:number}>}  sorted desc, then path asc
  */
 export function fuzzyRank(query, items, limit = 0) {
+    const normQuery = normalizeForContains(query);
+    // Floor scales with query length: a scattered subsequence earns ~1 point
+    // per char, while any contiguous run (+5/char) or word-boundary hit
+    // (+8) pushes a genuine match well past 4/char.
+    const floor = normQuery.length * SUBSEQUENCE_MIN_PER_CHAR;
     const scored = [];
     for (const item of items) {
-        const pathScore = fuzzyScore(query, item.path);
-        const base = String(item.path || '').split(/[\\/]/).pop() || '';
+        const p = String(item.path || '');
+        const pathScore = fuzzyScore(query, p);
+        const base = p.split(/[\\/]/).pop() || '';
         const baseScore = fuzzyScore(query, base);
         const sc = Math.max(pathScore ?? -Infinity, baseScore === null ? -Infinity : baseScore + 40);
-        if (Number.isFinite(sc)) scored.push({ item, score: sc });
+        if (!Number.isFinite(sc)) continue;
+        // Strong match: the query (separators stripped) is a contiguous
+        // substring of the basename or the full path. These ALWAYS pass so an
+        // exact substring/basename hit can never be starved out as noise.
+        const strong = normQuery.length > 0
+            && (normalizeForContains(base).includes(normQuery)
+                || normalizeForContains(p).includes(normQuery));
+        // Otherwise it is subsequence-only: keep it only if it clears the
+        // per-char floor. Weak scattered matches (the pgAdmin-style junk that
+        // merely contains the query chars in order) fall below it and drop out.
+        if (!strong && sc < floor) continue;
+        scored.push({ item, score: sc });
     }
     scored.sort((a, b) => (b.score - a.score) || (a.item.path < b.item.path ? -1 : a.item.path > b.item.path ? 1 : 0));
     return limit > 0 ? scored.slice(0, limit) : scored;

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

@@ -22,6 +22,7 @@ import {
     getCachedReadOnlyStat,
     statPathsForMtime,
     lstatPathsForMtime,
+    registerCacheInvalidationListener,
 } from './cache-layers.mjs';
 import {
     compileSimpleGlob,
@@ -339,6 +340,106 @@ export async function executeTreeTool(args, workDir, options = {}) {
     return out;
 }
 
+// ── Broad-enumeration cache (shared `rg --files` sweep) ──────────────────
+// A `rg --files` sweep of a root depends ONLY on (root, hidden, depth,
+// includeNoise) — NOT on the per-query narrowing. Yet both the fuzzy-find
+// broad pass and the find_files broad fast path re-run that full sweep for
+// every query item AND for every concurrent caller (measured 1-4s each when
+// 8 explorer sub-sessions hit the same root). Cache the PARSED file list per
+// key with in-flight promise dedup (N concurrent callers share ONE sweep)
+// plus a short TTL for serial reuse. Truncated/partial sweeps are
+// known-incomplete and are NEVER cached.
+const FIND_ENUM_CACHE = new Map(); // key -> { files, expiresAt }
+const FIND_ENUM_INFLIGHT = new Map(); // key -> Promise<{files,truncated,partial}>
+
+// The broad enumeration is a DERIVED cache the scope/path invalidation layer
+// does not otherwise know about — a file created/renamed after a sweep would
+// stay invisible to broad find reuse for the whole TTL. Drop all entries on any
+// write-invalidation event (TTL remains the secondary bound). Full clear is
+// fine: entries are cheap to rebuild.
+registerCacheInvalidationListener(() => {
+    FIND_ENUM_CACHE.clear();
+    FIND_ENUM_INFLIGHT.clear();
+});
+
+function findEnumTtlMs() {
+    const raw = process.env.MIXDOG_FIND_ENUM_CACHE_TTL_MS;
+    if (raw == null || raw === '') return 30000;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0) return 30000; // malformed → default
+    return Math.floor(n); // 0 = disabled
+}
+
+function findEnumKey({ root, hidden, depth, includeNoise }) {
+    return `${root}\u0000${hidden ? 1 : 0}\u0000${depth ?? ''}\u0000${includeNoise ? 1 : 0}`;
+}
+
+// Parse `rg --files` stdout into the same normalized relative-path list both
+// broad passes build (strip trailing CR, drop empties, strip leading `./`,
+// forward-slash). Module-level so the cache and both call sites agree.
+function parseRgFileList(stdout) {
+    return String(stdout)
+        .split('\n')
+        .map((p) => (p.endsWith('\r') ? p.slice(0, -1) : p))
+        .filter((p) => p.length > 0)
+        .map((p) => normalizeOutputPath(p.replace(/^\.[/\\]/, '')));
+}
+
+// Run (or reuse) the broad `rg --files` sweep for a root. Returns
+// { files, truncated, partial }. The returned `files` array is SHARED — callers
+// must treat it as read-only. `rgArgs` must be the broad-pass args (no per-query
+// narrowing); the cache key is the 4 dims only, so any caller producing an
+// equivalent sweep for the same dims reuses the result.
+async function getBroadEnumeration({ root, hidden, depth, includeNoise, rgArgs, cwd, runRgImpl = runRg }) {
+    const ttl = findEnumTtlMs();
+    const key = findEnumKey({ root, hidden, depth, includeNoise });
+    if (ttl > 0) {
+        const hit = FIND_ENUM_CACHE.get(key);
+        if (hit && hit.expiresAt > Date.now()) {
+            return { files: hit.files, truncated: false, partial: false };
+        }
+        if (hit) FIND_ENUM_CACHE.delete(key); // expired
+        const inflight = FIND_ENUM_INFLIGHT.get(key);
+        if (inflight) return inflight;
+    }
+    const run = (async () => {
+        const stdout = await runRgImpl(rgArgs, { cwd });
+        const truncated = Boolean(stdout && typeof stdout === 'object' && stdout.truncated);
+        const partial = Boolean(stdout && typeof stdout === 'object' && stdout.partial);
+        const files = parseRgFileList(stdout);
+        // Never cache a truncated/partial sweep — it is known-incomplete, so a
+        // later query with a larger head_limit must re-run the enumeration.
+        if (ttl > 0 && !truncated && !partial) {
+            FIND_ENUM_CACHE.set(key, { files, expiresAt: Date.now() + ttl });
+        }
+        return { files, truncated, partial };
+    })();
+    if (ttl > 0) {
+        FIND_ENUM_INFLIGHT.set(key, run);
+        try { return await run; }
+        finally { FIND_ENUM_INFLIGHT.delete(key); }
+    }
+    return run;
+}
+
+// Best-effort warm of the broad enumeration for a root using the `find` tool's
+// DEFAULT flags (hidden:true, includeNoise:false, depth:unbounded). Swallows
+// all errors — a failed prewarm must never surface or block the caller.
+export async function prewarmFindEnumeration(root) {
+    try {
+        if (!root || typeof root !== 'string') return;
+        const hidden = true, includeNoise = false, depth = null;
+        const rgArgs = ['--files', '--no-ignore', '--hidden'];
+        for (const ex of DEFAULT_IGNORE_GLOBS) rgArgs.push('--glob', ex);
+        rgArgs.push('.');
+        await getBroadEnumeration({
+            root: normalizeOutputPath(root),
+            hidden, depth, includeNoise,
+            rgArgs, cwd: root,
+        });
+    } catch { /* best-effort warm; never surface */ }
+}
+
  // Fuzzy filename search (nucleo-style): collect the file
 // list via `rg --files`, then rank by subsequence score. `list.fuzzy` still
 // routes here for hidden backward compatibility, but the model-facing tool is
@@ -372,7 +473,11 @@ export async function executeFuzzyFindTool(args, workDir, options = {}) {
     const fullPath = resolveAgainstCwd(inputPath, workDir);
     const guardFull = listGuardPath(fullPath);
     if (guardFull) return guardFull;
-    const hidden = Boolean(args.hidden);
+    // Fuzzy find defaults to searching dot-directories (hidden:true) so
+    // machine-wide discovery reaches paths like ~/.mixdog/data/…; callers
+    // opt out with hidden:false. .git and other noise dirs are still pruned
+    // via DEFAULT_IGNORE_GLOBS below (unless include_noise).
+    const hidden = args.hidden === false ? false : true;
     const includeNoise = Boolean(args.include_noise);
     // head_limit:0 means "no cap" per list semantics; default is intentionally
     // compact so ambiguous discovery does not dump a huge candidate list.
@@ -392,36 +497,108 @@ export async function executeFuzzyFindTool(args, workDir, options = {}) {
     });
     const cached = cacheGet(cacheKey);
     if (cached !== null) return cached;
-    const rgArgs = ['--files'];
-    if (hidden) rgArgs.push('--hidden');
-    if (depth != null) rgArgs.push('--max-depth', String(depth));
+    // --no-ignore: match the find_files fast path contract — do not consult
+    // .gitignore, so a .gitignored-but-present file is still discoverable.
+    // Noise dirs stay excluded via DEFAULT_IGNORE_GLOBS below.
+    // Shared rg flags for both enumeration passes below.
+    const baseRgArgs = ['--files', '--no-ignore'];
+    if (hidden) baseRgArgs.push('--hidden');
+    if (depth != null) baseRgArgs.push('--max-depth', String(depth));
+    // Noise-exclusion globs are kept SEPARATE and always appended LAST (after
+    // any positive --iglob). ripgrep's "last matching glob wins" rule means a
+    // positive include placed after these negations would re-admit e.g.
+    // `.git/<query>` — so the exclusions must trail the narrowed include.
+    const ignoreGlobs = [];
     if (!includeNoise) {
-        for (const ex of DEFAULT_IGNORE_GLOBS) rgArgs.push('--glob', ex);
+        for (const ex of DEFAULT_IGNORE_GLOBS) ignoreGlobs.push('--glob', ex);
     }
-    rgArgs.push('.');
-    let stdout;
-    try {
-        stdout = await runRg(rgArgs, { cwd: fullPath });
-    } catch (err) {
-        return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
-    }
-    const items = String(stdout)
+    // The narrowed pass must treat `query` as a LITERAL filename substring, not
+    // a glob. Wrap every globset metacharacter in a single-char character class
+    // (`[` → `[[]`, `*` → `[*]`, …): character-class quoting is the only form
+    // globset honors on Windows, where a backslash-escape (`\*`) is read as a
+    // literal path separator and does NOT escape. So a query like "[slug].tsx"
+    // still produces the intended `*[[]slug[]].tsx*` include instead of a
+    // character-class that matches one of s/l/u/g.
+    const escapeGlobLiteral = (s) => s.replace(/[*?[\]{}]/g, (c) => `[${c}]`);
+    // Test-only seam: allow a caller to inject a runRg stand-in (e.g. to
+    // simulate a truncated broad pass) without touching the production path.
+    // Never set on the real tool-execution options object.
+    const runRgImpl = (options && typeof options.__runRg === 'function') ? options.__runRg : runRg;
+    const parseRgFiles = (stdout) => String(stdout)
         .split('\n')
         // Strip only the trailing CR from rg's line split — do NOT trim, or a
         // filename with leading/trailing spaces would be corrupted.
         .map((p) => (p.endsWith('\r') ? p.slice(0, -1) : p))
         .filter((p) => p.length > 0)
-        .map((p) => ({ path: normalizeOutputPath(p.replace(/^\.[/\\]/, '')) }));
+        .map((p) => normalizeOutputPath(p.replace(/^\.[/\\]/, '')));
+    // Broad enumeration: every file under the scope, ranked by fuzzy score.
+    // Subject to rg's 20MB/20s cap — an exact-name hit deep in a huge tree can
+    // be dropped by cap lottery, so it is backstopped by the narrowed pass.
+    // Shared across queries/concurrent callers via the broad-enumeration cache
+    // (keyed on root+hidden+depth+includeNoise, i.e. exactly this pass's args).
+    let broadEnum;
+    try {
+        broadEnum = await getBroadEnumeration({
+            root: normalizeOutputPath(fullPath),
+            hidden, depth, includeNoise,
+            rgArgs: [...baseRgArgs, ...ignoreGlobs, '.'],
+            cwd: fullPath,
+            runRgImpl,
+        });
+    } catch (err) {
+        return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
+    }
+    const rgTruncated = broadEnum.truncated;
+    const rgPartial = broadEnum.partial;
+    // Narrowed enumeration: only files whose NAME contains the query
+    // (case-insensitive substring glob). This output is tiny and effectively
+    // never truncated, so exact/substring hits are guaranteed to reach ranking
+    // regardless of whether the broad pass was cut at the cap. Best-effort:
+    // failures here never fail the tool — the broad pass still stands.
+    let narrowPaths = [];
+    try {
+        // A positive --iglob whitelist makes ripgrep re-admit paths its own
+        // `!**/<noise>/**` negations would otherwise exclude (the whitelist
+        // wins regardless of glob order), so noise dirs are pruned in JS here
+        // instead — matching the broad pass's effective exclusion set.
+        const narrowStdout = await runRgImpl([...baseRgArgs, '--iglob', `*${escapeGlobLiteral(query)}*`, '.'], { cwd: fullPath });
+        narrowPaths = parseRgFiles(narrowStdout).filter((p) =>
+            includeNoise || !p.split('/').some((seg) => NOISE_DIR_NAMES.has(seg)));
+    } catch { /* best-effort backstop; broad pass already collected */ }
+    // Merge broad + narrowed, deduplicating by path (broad order preserved,
+    // narrowed-only exact-name candidates appended).
+    const seen = new Set();
+    const items = [];
+    for (const p of broadEnum.files) {
+        if (seen.has(p)) continue;
+        seen.add(p);
+        items.push({ path: p });
+    }
+    for (const p of narrowPaths) {
+        if (seen.has(p)) continue;
+        seen.add(p);
+        items.push({ path: p });
+    }
     const rankLimit = headLimit > 0 ? headLimit + 1 : headLimit;
     const rankedRaw = fuzzyRank(query, items, rankLimit);
     const hasMore = headLimit > 0 && rankedRaw.length > headLimit;
     const ranked = hasMore ? rankedRaw.slice(0, headLimit) : rankedRaw;
-    if (ranked.length === 0) return `(no fuzzy match for "${query}")`;
-    const out = ranked.map((r) => r.item.path).join('\n');
-    const result = hasMore
-        ? `${out}\n... (top ${headLimit}; raise head_limit for more)`
-        : out;
-    cacheSet(cacheKey, result, { scopes: [fullPath] });
+    // Build output lines uniformly for the hit and no-match cases so a
+    // truncated/partial broad pass ALWAYS surfaces its warning — otherwise a
+    // cut-off enumeration that happened to drop the sole match would silently
+    // report "(no fuzzy match …)" as if the tree were exhaustively searched.
+    const noMatch = ranked.length === 0;
+    const lines = noMatch ? [`(no fuzzy match for "${query}")`] : ranked.map((r) => r.item.path);
+    if (!noMatch && hasMore) lines.push(`... (top ${headLimit}; raise head_limit for more)`);
+    if (rgTruncated) lines.push('... [warning] rg stdout truncated at 20MB cap; broad ranking incomplete (exact-name hits still merged)');
+    if (rgPartial && !rgTruncated) lines.push('... [warning] rg exit 2 (partial results); broad ranking may be incomplete');
+    const result = lines.join('\n');
+    // Do not cache a truncated/partial enumeration — the broad ranking is
+    // known-incomplete, so a later call with a larger head_limit must re-run.
+    // A no-match result is also left uncached (mirrors the prior early return).
+    if (!noMatch && !rgTruncated && !rgPartial) {
+        cacheSet(cacheKey, result, { scopes: [fullPath] });
+    }
     if (typeof options?.onProgress === 'function') {
         try { options.onProgress(`${ranked.length} candidates`); } catch { /* best-effort */ }
     }
@@ -563,14 +740,30 @@ export async function executeFindFilesTool(args, workDir, options = {}) {
             // pre-filter matches the JS matcher; explicit globs pass through.
             if (namePattern) rgArgs.push('--iglob', nameIsGlob ? namePattern : `*${namePattern}*`);
             rgArgs.push('.');
-            const stdout = await runRg(rgArgs, { cwd: fullPath });
-            rgStdoutTruncated = Boolean(stdout && typeof stdout === 'object' && stdout.truncated);
-            rgStdoutPartial = Boolean(stdout && typeof stdout === 'object' && stdout.partial);
+            // No `name` filter → this is the pure broad sweep (rgArgs match the
+            // fuzzy-find broad pass), so share it via the enumeration cache.
+            // With a `name` filter the sweep is narrowed by --iglob and must
+            // NOT hit the broad cache — run it directly.
+            let relPaths;
+            if (!namePattern) {
+                const enumRes = await getBroadEnumeration({
+                    root: normalizeOutputPath(fullPath),
+                    hidden, depth, includeNoise,
+                    rgArgs, cwd: fullPath,
+                });
+                rgStdoutTruncated = enumRes.truncated;
+                rgStdoutPartial = enumRes.partial;
+                relPaths = enumRes.files;
+            } else {
+                const stdout = await runRg(rgArgs, { cwd: fullPath });
+                rgStdoutTruncated = Boolean(stdout && typeof stdout === 'object' && stdout.truncated);
+                rgStdoutPartial = Boolean(stdout && typeof stdout === 'object' && stdout.partial);
+                relPaths = parseRgFileList(stdout);
+            }
             const candidates = [];
-            for (const line of String(stdout).split('\n')) {
-                const trimmed = line.trim();
-                if (!trimmed) continue;
-                const candidate = resolveAgainstCwd(normalizeInputPath(trimmed), fullPath);
+            for (const rel of relPaths) {
+                if (!rel) continue;
+                const candidate = resolveAgainstCwd(normalizeInputPath(rel), fullPath);
                 if (!matchesFindNamePattern(basename(candidate), candidate)) continue;
                 candidates.push(candidate);
                 if (candidates.length >= FIND_ABSOLUTE_CAP) {