mixdog 0.9.23 → 0.9.24

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) {

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

@@ -1,6 +1,7 @@
 import { statSync } from 'fs';
 import { assertPathReachable, assertPathsReachable } from './fs-reachability.mjs';
 import { isAbsolute, resolve } from 'path';
+import { WRAPPER_NAMES } from '../shell-policy.mjs';
 import {
     cwdRelativePath,
     normalizeInputPath,
@@ -651,3 +652,63 @@ export function foregroundLongCommandHint(command, timeoutMs, args = {}) {
     if (!longTimeout && !watchLike && !longSleep) return '';
     return 'Error: long foreground command detected.';
 }
+
+// Commands that must NOT be promoted to background on a foreground timeout —
+// they run in the foreground and are killed at their deadline instead. Mirrors
+// the reference CLI DISALLOWED_AUTO_BACKGROUND_COMMANDS: `sleep` on posix,
+// `start-sleep`/`sleep` (the PS built-in alias) on PowerShell. A `sleep`/
+// `Start-Sleep` the caller wants to survive must be launched with
+// run_in_background/async explicitly.
+const _DISALLOWED_AUTO_BACKGROUND_POSIX = ['sleep'];
+const _DISALLOWED_AUTO_BACKGROUND_PS = ['start-sleep', 'sleep'];
+
+// Whether one shell segment reaches a disallowed sleep-like command. Strips a
+// leading subshell/paren/brace/`&`, then walks tokens skipping VAR=val and
+// option flags (quotes stripped so `'Start-Sleep'` resolves). A disallowed base
+// name found anywhere reachable blocks promotion. Once a command-runner wrapper
+// (env/sudo/timeout/nice/…, shell-policy.mjs's WRAPPER_NAMES) has been seen we
+// do NOT model that wrapper's flag arity — we keep scanning EVERY later bare
+// token for a hidden `sleep`, so `sudo -u nobody sleep 5` / `setpriv --reuid
+// user sleep` are caught (erring toward NOT promoting). Without a wrapper the
+// first real command token decides the segment.
+function _segmentDisallowed(segment, disallowed) {
+    const stripped = String(segment || '').replace(/^[\s(){}&]+/, '');
+    const tokens = stripped.split(/\s+/).filter(Boolean);
+    let sawWrapper = false;
+    for (let tok of tokens) {
+        tok = tok.replace(/^['"]+|['"]+$/g, '');
+        if (!tok) continue;
+        if (/^[A-Za-z_]\w*=/.test(tok)) continue;            // VAR=val assignment
+        if (tok.startsWith('-')) continue;                    // option flag
+        const stem = tok.toLowerCase().replace(/^.*[\\/]/, '').replace(/\.exe$/, '');
+        if (disallowed.includes(stem)) return true;           // sleep reachable here
+        if (WRAPPER_NAMES.has(stem)) { sawWrapper = true; continue; }
+        if (/^\d+(?:\.\d+)?[smhd]?$/i.test(tok)) continue;    // numeric/duration arg
+        // First real command token. Without a preceding wrapper it IS the base
+        // command and it wasn't disallowed → segment is safe. With a wrapper,
+        // this may be a wrapper value arg (`sudo -u nobody …`); keep scanning
+        // for a hidden sleep instead of stopping here.
+        if (!sawWrapper) return false;
+    }
+    return false;
+}
+
+// Whether a still-running foreground one-shot may be promoted to a background
+// job when it hits its timeout (CC isAutobackgroundingAllowed analogue).
+// Scans EVERY segment of a &&/||/;/|/& chain and, per segment, peels wrappers
+// before reading the base command — so a sleep-like hidden behind a chain
+// (`cd x && sleep 5`) or a runner wrapper (`timeout 5 sleep`, `env sleep`) is
+// still caught. Errs toward NOT promoting: any disallowed base command in any
+// segment blocks promotion. shellType 'powershell' uses the PS disallow list.
+export function isAutobackgroundingAllowed(command, shellType) {
+    const cmd = String(command || '').trim();
+    if (!cmd) return true;
+    const disallowed = shellType === 'powershell'
+        ? _DISALLOWED_AUTO_BACKGROUND_PS
+        : _DISALLOWED_AUTO_BACKGROUND_POSIX;
+    const segments = cmd.split(/(?:&&|\|\||[;\n|&])/);
+    for (const seg of segments) {
+        if (_segmentDisallowed(seg, disallowed)) return false;
+    }
+    return true;
+}

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

@@ -402,6 +402,11 @@ export function startBackgroundShellJob({ command, timeoutMs, workDir, mergeStde
 // watcher never keeps the host process alive.
 const SHELL_JOB_WATCH_POLL_MS = 2000;
 const SHELL_JOB_WATCH_GRACE_MS = 5000;
+// 32-bit timer ceiling: setTimeout delays above 2^31-1 wrap to a tiny value
+// and fire immediately. The resolved timeout is already clamped at parse time
+// (bash-tool.mjs TIMER_MAX_MS), but sites that add grace to it can still exceed
+// the ceiling, so clamp the summed delay here too.
+const TIMER_MAX_MS = 2_147_483_647;
 // Registry of armed background-job watchers keyed by jobId. task wait
 // and `kill` actions already hold the completed outcome, so they cancel the
 // armed watcher here to prevent a double-notify when its next poll fires.
@@ -653,11 +658,16 @@ export function watchBackgroundShellJob(jobId, notifyCtx) {
         } catch { watcher = null; }
         pollTimer = setInterval(() => checkDone('poll'), SHELL_JOB_WATCH_POLL_MS);
         if (typeof pollTimer.unref === 'function') pollTimer.unref();
-        const startedAtMs = Date.parse(readShellJobDetail(jobId)?.startedAt || '') || Date.now();
         const timeoutMs = Number(readShellJobDetail(jobId)?.timeoutMs || 0);
-        const hardStopMs = Math.max(0, (startedAtMs + timeoutMs + SHELL_JOB_WATCH_GRACE_MS) - Date.now());
-        hardStopTimer = setTimeout(() => fire('timeout'), hardStopMs);
-        if (typeof hardStopTimer.unref === 'function') hardStopTimer.unref();
+        // Only arm the hard-stop when a timeout is enforced. timeoutMs<=0 means
+        // unlimited: arming it would fire ~grace ms after arm and mark the job
+        // failed. fs.watch + poll remain the completion paths for such jobs.
+        if (timeoutMs > 0) {
+            const startedAtMs = Date.parse(readShellJobDetail(jobId)?.startedAt || '') || Date.now();
+            const hardStopMs = Math.min(TIMER_MAX_MS, Math.max(0, (startedAtMs + timeoutMs + SHELL_JOB_WATCH_GRACE_MS) - Date.now()));
+            hardStopTimer = setTimeout(() => fire('timeout'), hardStopMs);
+            if (typeof hardStopTimer.unref === 'function') hardStopTimer.unref();
+        }
     } catch (err) {
         cleanup();
         try { process.stderr.write(`[shell-jobs] watchBackgroundShellJob arm failed: jobId=${jobId} err=${err?.message ?? String(err)}\n`); } catch { /* ignore */ }
@@ -755,7 +765,10 @@ function _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr
     const stderrPath = shellJobStderrPath(jobId);
     const exitPath = shellJobExitPath(jobId);
     const donePath = shellJobDonePath(jobId);
-    const timeoutSeconds = Math.max(1, Math.ceil(timeoutMs / 1000));
+    // timeoutMs <= 0 means unlimited (async omitted default): no kernel
+    // `timeout` wrapper, no enforced marker — exec the inner shell directly.
+    const enforceTimeout = Number(timeoutMs) > 0;
+    const timeoutSeconds = enforceTimeout ? Math.max(1, Math.ceil(timeoutMs / 1000)) : 0;
     // P2 fix: wrap with POSIX `timeout` so the kernel terminates the process
     // at deadline even if the JS-side timer is interrupted. --preserve-status
     // keeps the user command's exit code on success; on timeout the wrapper
@@ -787,7 +800,11 @@ function _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr
     // status for processes that actually exited 0. `rm -- "$0"` removes
     // the staged wrapper .cmd.sh after donePath is published so a host
     // crash before this point still leaves the file for the sweep to GC.
-    const wrapped = `{ if command -v timeout >/dev/null 2>&1; then _to=timeout; elif command -v gtimeout >/dev/null 2>&1; then _to=gtimeout; else _to=; fi; if [ -n "$_to" ]; then touch ${shellQuoteSingle(enforcedPath)}; "$_to" ${timeoutSeconds} ${innerShellQ} ${innerArgsQ} ${userCmdQuoted}; else ${innerShellQ} ${innerArgsQ} ${userCmdQuoted}; fi; rc=$?; printf '%s' "$rc" > ${shellQuoteSingle(exitPath)}; touch ${shellQuoteSingle(donePath)}; rm -- "$0" 2>/dev/null; exit $rc; }`;
+    const _innerRun = `${innerShellQ} ${innerArgsQ} ${userCmdQuoted}`;
+    const _execPart = enforceTimeout
+        ? `if command -v timeout >/dev/null 2>&1; then _to=timeout; elif command -v gtimeout >/dev/null 2>&1; then _to=gtimeout; else _to=; fi; if [ -n "$_to" ]; then touch ${shellQuoteSingle(enforcedPath)}; "$_to" ${timeoutSeconds} ${_innerRun}; else ${_innerRun}; fi`
+        : _innerRun;
+    const wrapped = `{ ${_execPart}; rc=$?; printf '%s' "$rc" > ${shellQuoteSingle(exitPath)}; touch ${shellQuoteSingle(donePath)}; rm -- "$0" 2>/dev/null; exit $rc; }`;
     // Stage the wrapped command to a .sh and let the script open its own
     // output files via `exec > … 2> …`. The parent does NOT pass file
     // descriptors via stdio inheritance (`stdio: 'ignore'` for all three).
@@ -841,8 +858,13 @@ function _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr
         startedAt: new Date().toISOString(),
     };
     writeShellJobDetail(detail);
-    const timer = setTimeout(() => { refreshShellJob(jobId); }, timeoutMs + 25);
-    if (typeof timer.unref === 'function') timer.unref();
+    // Deadline cleanup poke only when a timeout is enforced; an unlimited
+    // (timeoutMs<=0) job has no deadline — completion is observed via the
+    // fs.watch/poll watcher and refreshShellJob on task queries.
+    if (enforceTimeout) {
+        const timer = setTimeout(() => { refreshShellJob(jobId); }, Math.min(TIMER_MAX_MS, timeoutMs + 25));
+        if (typeof timer.unref === 'function') timer.unref();
+    }
     return detail;
 }
 
@@ -876,7 +898,10 @@ function startBackgroundPowerShellJob({ command, timeoutMs, workDir, mergeStderr
         `$exitPath = ${psSingleQuote(exitPath)}`,
         `$donePath = ${psSingleQuote(donePath)}`,
         `$mergeStderr = ${mergeLiteral}`,
-        `$timeoutMs = ${Math.max(1, Math.floor(timeoutMs || 0))}`,
+        // 0 (or negative) = unlimited: the wrapper's `if ($timeoutMs -gt 0 ...`
+        // guard falls through to a plain WaitForExit() with no deadline. Do NOT
+        // floor to 1 — that would enforce a 1ms timeout on unlimited jobs.
+        `$timeoutMs = ${Math.max(0, Math.floor(timeoutMs || 0))}`,
         '$code = 1',
         'try {',
         // -ExecutionPolicy Bypass: unlike -EncodedCommand, -File is subject to
@@ -986,21 +1011,23 @@ function startBackgroundPowerShellJob({ command, timeoutMs, workDir, mergeStderr
         pid: childPid,
         mergeStderr,
         timeoutMs,
-        timeoutSeconds: Math.max(1, Math.ceil(timeoutMs / 1000)),
+        timeoutSeconds: Number(timeoutMs) > 0 ? Math.max(1, Math.ceil(timeoutMs / 1000)) : 0,
         stdoutPath,
         stderrPath: mergeStderr ? stdoutPath : rawStderrPath,
         exitPath,
         donePath,
-        // The PS wrapper enforces timeoutMs unconditionally in-wrapper
-        // (WaitForExit($timeoutMs) → Stop-Process → 124), so the deadline
-        // invariant always holds for PowerShell jobs.
-        timeoutEnforced: true,
+        // The PS wrapper enforces the deadline (WaitForExit($timeoutMs) →
+        // Stop-Process → 124) only when timeoutMs>0; an unlimited job waits
+        // with no deadline, so don't falsely claim enforcement.
+        timeoutEnforced: Number(timeoutMs) > 0,
         // Per-terminal session stamp (see resolveJobOwnerHostPid).
         ownerHostPid: resolveJobOwnerHostPid(clientHostPid),
         startedAt: new Date().toISOString(),
     };
     writeShellJobDetail(detail);
-    const timer = setTimeout(() => { refreshShellJob(jobId); }, timeoutMs + 25);
-    if (typeof timer.unref === 'function') timer.unref();
+    if (Number(timeoutMs) > 0) {
+        const timer = setTimeout(() => { refreshShellJob(jobId); }, Math.min(TIMER_MAX_MS, timeoutMs + 25));
+        if (typeof timer.unref === 'function') timer.unref();
+    }
     return detail;
 }

package/src/runtime/agent/orchestrator/tools/code-graph/dispatch.mjs

@@ -180,13 +180,61 @@ async function codeGraph(args, cwd, signal = null, options = {}) {
   }
 
   if (mode === 'dependents') {
-    if (!rel) throw new Error('code_graph dependents: "file" is required');
-    if (!node) return _appendSameBasenameHint(`Error: code_graph dependents: file not found in graph: ${normFile || '(missing file)'}`, normFile, graph);
+    let depRel = rel;
+    let depNorm = normFile;
+    let subNote = null;
+    // (1) Symbol inference runs ONLY when no `file` arg was supplied at all —
+    // an explicit file (even a directory that yields no rel) is never overridden.
+    if (!depRel && !normFile) {
+      const symCandidates = [
+        ...(Array.isArray(args?.symbols) ? args.symbols : []),
+        args?.symbol,
+      ].map((s) => String(s || '').trim()).filter(Boolean);
+      const KNOWN_SRC_EXT = /\.(mjs|cjs|js|jsx|mts|cts|ts|tsx|json|py|go|rb|rs|java|kt|c|h|cc|cpp|hpp|cs|php|swift|scala|sh)$/i;
+      // (2) Symbol lookup FIRST — dotted names (e.g. obj.method) resolve here
+      // before any path classification.
+      for (const s of symCandidates) {
+        const hits = _findSymbolHits(graph, s, {});
+        const usable = hits.filter((h) => graph.nodes.get(h.rel));
+        const pool = usable.length ? usable : hits;
+        if (!pool.length) continue;
+        // (3) Deterministic pick: defining hit, else first by sorted rel.
+        const sorted = [...pool].sort((a, b) => String(a.rel).localeCompare(String(b.rel)));
+        const primary = sorted.find((h) => h.declarationLike) || sorted[0];
+        depRel = primary.rel; depNorm = primary.rel;
+        subNote = `# note: dependents resolved from symbol '${s}' → ${primary.rel}`;
+        const others = [...new Set(sorted.map((h) => h.rel))].filter((r) => r !== primary.rel);
+        if (others.length) subNote += `\n# note: '${s}' also defined in: ${others.join(', ')}`;
+        break;
+      }
+      // Path-classification only when the value has a slash or a known source
+      // extension — never for plain dotted symbol names.
+      if (!depRel) {
+        const pathLike = symCandidates.find((s) => /[\\/]/.test(s) || KNOWN_SRC_EXT.test(s));
+        if (pathLike) {
+          const pAbs = isAbsolute(pathLike) ? pathResolve(pathLike) : pathResolve(cwd, pathLike);
+          const pRel = _graphRel(pAbs, cwd);
+          if (graph.nodes.get(pRel)) {
+            depRel = pRel; depNorm = pathLike;
+            subNote = `# note: treated symbol '${pathLike}' as file`;
+          }
+        }
+      }
+      // (4) Nothing resolved → actionable hint naming the attempted values,
+      // with a distinct message when no symbol was supplied at all.
+      if (!depRel) {
+        throw new Error(symCandidates.length
+          ? `code_graph dependents: dependents needs file:<path>; got symbol only (tried: ${symCandidates.join(', ')})`
+          : 'code_graph dependents: "file" is required (no file or symbol supplied)');
+      }
+    }
+    const depFileNode = depRel ? graph.nodes.get(depRel) : null;
+    if (!depFileNode) return _appendSameBasenameHint(`Error: code_graph dependents: file not found in graph: ${depNorm || '(missing file)'}`, depNorm, graph);
     const GRAPH_LIST_CAP = 200;
-    const depsAll = [...(graph.reverse.get(rel) || [])].sort();
+    const depsAll = [...(graph.reverse.get(depRel) || [])].sort();
     if (!depsAll.length) return '(no dependents)';
     const deps = depsAll.slice(0, GRAPH_LIST_CAP);
-    const basename = rel.split('/').pop();
+    const basename = depRel.split('/').pop();
     const stem = basename.replace(/\.[^/.]+$/, '');
     const enriched = deps.map((dep) => {
       const depNode = graph.nodes.get(dep);
@@ -203,7 +251,8 @@ async function codeGraph(args, cwd, signal = null, options = {}) {
       }
       return dep;
     });
-    const out = enriched.join('\n');
+    const body = enriched.join('\n');
+    const out = subNote ? `${subNote}\n${body}` : body;
     return depsAll.length > deps.length
       ? `${out}\n[truncated — showing first ${GRAPH_LIST_CAP} of ${depsAll.length} dependents]`
       : out;