mixdog 0.9.23 → 0.9.24

package/src/runtime/agent/orchestrator/session/agent-loop.mjs

@@ -291,8 +291,10 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         if (iterations >= maxLoopIterations) {
             // Final-answer turn: instead of breaking mid-transcript (which
             // yields an empty final for locator-style agents that never got to
-            // answer), give the model ONE tool-less text turn to wrap up, then
-            // stop (empty sendTools + refusal stubs if tools are requested).
+            // answer), give the model ONE text-only turn to wrap up, then stop.
+            // Tool DEFINITIONS stay in-request (stable cache prefix) but tool
+            // USE is forbidden via tool_choice:'none'; any tool call a
+            // toolChoice-ignoring provider still emits gets a refusal stub.
             if (_capFinalTurnUsed) {
                 process.stderr.write(`[loop] hard iteration cap ${maxLoopIterations} reached (sess=${sessionId || 'unknown'}); stopping loop.\n`);
                 terminatedByCap = true;
@@ -362,15 +364,22 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         const nextIteration = iterations + 1;
         opts.iteration = nextIteration;
         opts.providerState = providerState;
-        if (forcedFirstTool && toolCallsTotal === 0) {
+        if (_capFinalToolsDisabled) {
+            // Hard-cap final turn: forbid tool USE (tool_choice:'none') instead
+            // of stripping tool DEFINITIONS. Sending tools:[] changed the
+            // tools→system→messages prefix chain, so Anthropic could no longer
+            // prefix-match and re-prefilled the whole prompt (~10k, cache
+            // read=0) on the final capped turn. Keeping the tools in-request
+            // holds the prefix byte-stable; 'none' makes the model emit text
+            // only. Overrides the forced-first-tool path below.
+            opts.toolChoice = 'none';
+        } else if (forcedFirstTool && toolCallsTotal === 0) {
             opts.toolChoice = 'required';
         } else {
             delete opts.toolChoice;
         }
-        // Hard-cap final turn: send NO tool definitions so the provider can
-        // only emit text. Overrides the forced-first-tool path.
         const sendTools = _capFinalToolsDisabled
-            ? []
+            ? tools
             : (forcedFirstToolDef && toolCallsTotal === 0 ? [forcedFirstToolDef] : tools);
         // Eager-dispatch queue: when the provider streams a tool-call event,
         // start read-only tools immediately so execution overlaps with the
@@ -387,7 +396,15 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             getNextIteration: () => nextIteration,
             repeatFailLimit: REPEAT_FAIL_LIMIT,
         });
-        opts.onToolCall = eager.onToolCall;
+        // Hard-cap final turn: forbid eager dispatch. Tools are still sent (to
+        // hold the cache prefix) but tool_choice:'none' means Anthropic emits
+        // no calls; a toolChoice-IGNORING provider could still stream calls,
+        // and an attached onToolCall would eager-run read-only tools mid-stream
+        // (real cost/UI/network side effects) whose results are then discarded
+        // by the refusal-stub path. Leave it unset so nothing dispatches; opts
+        // is reused across iterations but onToolCall is cleared to undefined
+        // after send() below, so non-cap iterations are unaffected.
+        opts.onToolCall = _capFinalToolsDisabled ? undefined : eager.onToolCall;
         // Reattach separated tool results, then drop only truly dangling
         // assistant/orphan pairs before the provider sees the transcript.
         repairTranscriptBeforeProviderSend(messages, sessionId);

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

@@ -108,6 +108,7 @@ export function markSessionAskStart(id) {
     entry.lastStreamDeltaAt = null;
     entry.lastToolCall = null;
     entry.toolStartedAt = null;
+    entry.toolSelfDeadlineMs = null;
     entry.lastError = null;
     // A new ask starts a fresh turn lifecycle — clear any stale empty-final
     // classification from the prior turn so inspectBridgeEntry doesn't keep
@@ -166,11 +167,18 @@ export async function markSessionStreamDelta(id) {
     }
     entry.updatedAt = now;
 }
-export function markSessionToolCall(id, toolName) {
+export function markSessionToolCall(id, toolName, selfDeadlineMs) {
     if (!id) return;
     const entry = _touchRuntime(id);
     entry.stage = 'tool_running';
     entry.lastToolCall = toolName || null;
+    // Self-enforced deadline (ms) for tools that kill themselves at a known
+    // budget (shell timeout / task wait). The watchdog raises the tool-running
+    // ceiling to this + grace instead of aborting at toolRunningMs. Null/<=0
+    // means unknown -> plain toolRunningMs behavior.
+    entry.toolSelfDeadlineMs = (typeof selfDeadlineMs === 'number' && selfDeadlineMs > 0)
+        ? selfDeadlineMs
+        : null;
     entry.toolStartedAt = Date.now();
     entry.lastProgressAt = entry.toolStartedAt;
     entry.updatedAt = entry.toolStartedAt;
@@ -289,6 +297,8 @@ export function getSessionProgressSnapshot(sessionId) {
         firstActivityAt,
         lastStreamDeltaAt: entry.lastStreamDeltaAt || 0,
         toolStartedAt: entry.toolStartedAt || 0,
+        currentTool: entry.lastToolCall || null,
+        toolSelfDeadlineMs: entry.toolSelfDeadlineMs || 0,
         lastProgressAt: entry.lastProgressAt || 0,
         updatedAt: entry.updatedAt || 0,
         hasFirstActivity: Boolean(firstActivityAt && (!askStartedAt || firstActivityAt >= askStartedAt)),

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

@@ -167,8 +167,9 @@ export function createSession(opts) {
     //   - read-only roles (reviewer / debugger / hidden retrieval, i.e. any
     //     session resolving to permission 'read') -> 'readonly' bundle:
     //     read builtins (code_graph/find/glob/list/grep/read) + retrieval
-    //     (explore/search/web_fetch/Skill), no apply_patch/shell/task, no
-    //     MCP-write. applyToolPermissionNarrowing('read') below trims the
+    //     (explore/search/web_fetch/Skill) + shell/task for self-verification
+    //     (agent-owned readonly bundle only), no apply_patch, no MCP-write.
+    //     applyToolPermissionNarrowing('read') below trims the
     //     bundle to AGENT_STRING_PERMISSION_READ_ALLOW so the final surface is
     //     bit-identical across these roles regardless of MCP registry state.
     //   - write roles (worker / heavy-worker / maintainer / …) -> 'full'
@@ -188,7 +189,10 @@ export function createSession(opts) {
     // fail closed (zero tools) rather than silently falling back to the full
     // preset, which would grant the role more surface than declared.
     if (ownerIsAgent) {
-        toolsForRouting = applyToolPermissionNarrowing(toolsForRouting, toolPermission, opts.agent || null);
+        // Pass the RESOLVED agent (opts.agent || opts.role): narrowing keys
+        // retrieval/locator roles (explore etc.) off this name to strip
+        // shell/task; verifying read roles (reviewer/debugger) keep them.
+        toolsForRouting = applyToolPermissionNarrowing(toolsForRouting, toolPermission, resolvedAgent);
     }
 
     const { baseRules, stableSystemContext, sessionMarker, volatileTail } = composeSystemPrompt({

package/src/runtime/agent/orchestrator/session/manager/tool-resolution.mjs

@@ -74,14 +74,39 @@ const AGENT_STRING_PERMISSION_READ_ALLOW = Object.freeze([
     'list',
     'grep',
     'read',
+    // shell/task: read-role agents (reviewer/debugger) must run their own
+    // verification (tests/repro). task is required because shell's
+    // auto-background transition settles with a bare jobId — agent sessions
+    // get no completion notification, so `task wait/read` is the only way to
+    // collect a long-running result. apply_patch stays excluded: read roles
+    // keep the no-edit contract.
+    'shell',
+    'task',
     'explore',
     'search',
     'web_fetch',
     'Skill',
 ]);
 
-function stringToolPermissionAllowList(toolPermission) {
-    if (toolPermission === 'read') return AGENT_STRING_PERMISSION_READ_ALLOW;
+// Retrieval/locator roles never self-verify, so they keep the historical
+// no-shell read surface. Covers hidden retrieval agents (kind 'retrieval')
+// AND public wrapper roles (explore + any invokedBy wrapper) — the same set
+// pre-dispatch-deny treats as recursive wrappers. Only verifying read roles
+// (reviewer/debugger) get shell/task.
+const AGENT_STRING_PERMISSION_READ_RETRIEVAL_ALLOW = Object.freeze(
+    AGENT_STRING_PERMISSION_READ_ALLOW.filter((n) => n !== 'shell' && n !== 'task'),
+);
+
+function isRetrievalToolRole(agent) {
+    if (!agent) return false;
+    if (getHiddenAgent(agent)?.kind === 'retrieval') return true;
+    return Boolean(recursiveWrapperToolNameForPublicAgent(agent));
+}
+
+function stringToolPermissionAllowList(toolPermission, { retrieval = false } = {}) {
+    if (toolPermission === 'read') {
+        return retrieval ? AGENT_STRING_PERMISSION_READ_RETRIEVAL_ALLOW : AGENT_STRING_PERMISSION_READ_ALLOW;
+    }
     if (toolPermission === 'read-write') return AGENT_STRING_PERMISSION_READ_WRITE_ALLOW;
     if (toolPermission === 'none') return [];
     return null;
@@ -109,7 +134,7 @@ const AGENT_STRING_PERMISSION_READ_WRITE_ALLOW = Object.freeze([
 
 export function applyToolPermissionNarrowing(tools, toolPermission, warnRole = null) {
     if (toolPermission === 'none') return [];
-    const allowList = stringToolPermissionAllowList(toolPermission);
+    const allowList = stringToolPermissionAllowList(toolPermission, { retrieval: isRetrievalToolRole(warnRole) });
     if (allowList) {
         const allowSet = new Set(allowList.map((n) => String(n).toLowerCase()));
         return tools.filter((t) => allowSet.has(String(t?.name || '').toLowerCase()));
@@ -203,7 +228,7 @@ export function resolveSessionTools(toolSpec, skills, { ownerIsAgentSession = fa
     // time (loop.mjs), so the schema bytes stay bit-identical across roles /
     // cwds and the provider cache shard does not fragment.
     const skillTools = buildSkillToolDefs(skills, { ownerIsAgentSession });
-    return _computeBaseTools(toolSpec, mcp, skillTools);
+    return _computeBaseTools(toolSpec, mcp, skillTools, { ownerIsAgentSession });
 }
 
 export function previewSessionTools(toolSpec, skills = [], options = {}) {
@@ -230,7 +255,7 @@ function _dedupByName(tools) {
 // Tools with agentHidden:true are stripped from agent sessions at schema
 // build time (see deny filtering below). No code-level name list needed.
 
-function _computeBaseTools(toolSpec, mcp, skillTools) {
+function _computeBaseTools(toolSpec, mcp, skillTools, { ownerIsAgentSession = false } = {}) {
     if (Array.isArray(toolSpec)) {
         if (toolSpec.length === 0) {
             // Explicit "no tools" — skill meta tools still travel so the model
@@ -285,7 +310,16 @@ function _computeBaseTools(toolSpec, mcp, skillTools) {
             return _dedupByName([...mcp, ...skillTools]);
         case 'readonly': {
             const readTools = ALL_BUILTIN_SESSION_TOOLS.filter(t => READONLY_TOOL_NAMES.has(t.name));
-            return _dedupByName([...readTools, ...mcp, ...skillTools]);
+            // Read-ROLE agent sessions (reviewer/debugger) must self-verify, so
+            // their base bundle carries shell/task defs. The 'read' permission
+            // allowlist (AGENT_STRING_PERMISSION_READ_ALLOW) is a pure FILTER —
+            // it can only keep tools already assembled here, so without this the
+            // allowlist's shell/task entries were dead letters. Non-agent
+            // 'readonly' profiles stay strictly read-only.
+            const verifyTools = ownerIsAgentSession
+                ? ALL_BUILTIN_SESSION_TOOLS.filter(t => t.name === 'shell' || t.name === 'task')
+                : [];
+            return _dedupByName([...readTools, ...verifyTools, ...mcp, ...skillTools]);
         }
         case 'full':
         default:

package/src/runtime/agent/orchestrator/session/tool-batch.mjs

@@ -11,6 +11,7 @@ import { takeApplyPatchUiDiff } from '../tools/patch.mjs';
 import { compressToolResult } from '../tools/result-compression.mjs';
 import { appendAgentTrace, traceAgentTool, traceAgentToolFailure } from '../agent-trace.mjs';
 import { markSessionToolCall, updateSessionStage } from './manager.mjs';
+import { resolveToolSelfDeadlineMs } from '../agent-runtime/agent-progress-watchdog.mjs';
 import { classifyResultKind } from './result-classification.mjs';
 import { normalizeToolEnvelope } from './tool-envelope.mjs';
 import { maybeOffloadToolResult } from './tool-result-offload.mjs';
@@ -150,7 +151,7 @@ export async function processToolBatch(ctx) {
                     continue;
                 }
             }
-            if (sessionId) markSessionToolCall(sessionId, call.name);
+            if (sessionId) markSessionToolCall(sessionId, call.name, resolveToolSelfDeadlineMs(call.name, call.arguments));
             let result;
             let toolStartedAt;
             let toolEndedAt;

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;