mixdog 0.9.22 → 0.9.24

package/src/runtime/agent/orchestrator/session/manager/compaction-runner.mjs

@@ -74,6 +74,39 @@ function recallMemoryTimeoutMs(session) {
     // misconfigured tiny value can't turn the bound into a busy no-wait.
     return Math.max(250, configured || RECALL_MEMORY_CALL_TIMEOUT_MS);
 }
+// Cold-start allowance (clear/manual path only): a booting memory daemon can
+// miss the tight first bound (waitForPort + first-RPC warmup ~2-10s). On a
+// timeout we retry ONCE with a longer bound before honoring the bail-to-
+// semantic contract, so a rebooting runtime succeeds instead of instantly
+// failing. Non-timeout errors and outer aborts propagate immediately.
+// 15s: memory boot is ~2-4s warm-cache / ~10s worst since the PG fast-start
+// fix; keeping this tight bounds the clear path's worst case (2 memory calls
+// retried + 120s semantic) under the TUI auto-clear watchdog (180s).
+const RECALL_COLD_START_TIMEOUT_MS = 15_000;
+function isTimeoutError(err) {
+    return typeof err?.message === 'string' && err.message.includes('timed out after');
+}
+async function callMemoryColdStart(args, callerCtx, timeoutMs) {
+    try {
+        return await callMemoryBounded(args, callerCtx, timeoutMs);
+    } catch (err) {
+        if (!isTimeoutError(err) || callerCtx?.signal?.aborted) throw err;
+        const coldMs = Math.max(timeoutMs, RECALL_COLD_START_TIMEOUT_MS);
+        if (coldMs <= timeoutMs) throw err;
+        try { process.stderr.write(`[session] recall-fasttrack ${args?.action || 'call'} cold-start retry (${timeoutMs}ms -> ${coldMs}ms)\n`); } catch {}
+        return await callMemoryBounded(args, callerCtx, coldMs);
+    }
+}
+// Semantic-compact timeout scales with transcript size (clear/manual path):
+// default max(30s, ~10s per 25k estimated message tokens) capped at 120s, so a
+// large (~100k-token) transcript no longer dies on a fixed 30s bound.
+// session.compaction.timeoutMs still overrides.
+function semanticCompactTimeoutMs(session, messageTokens) {
+    const override = positiveContextWindow(session?.compaction?.timeoutMs);
+    if (override) return override;
+    const scaled = Math.ceil((messageTokens || 0) / 25_000) * 10_000;
+    return Math.min(120_000, Math.max(30_000, scaled));
+}
 async function callMemoryBounded(args, callerCtx, timeoutMs) {
     const ac = new AbortController();
     const outer = callerCtx?.signal;
@@ -118,7 +151,7 @@ async function runRecallFastTrackForSession(session, messages, opts = {}) {
         || Math.max(500, Math.min(5000, messages.length || 0));
     const memoryTimeoutMs = recallMemoryTimeoutMs(session);
     try {
-        await callMemoryBounded({
+        await callMemoryColdStart({
             action: 'ingest_session',
             sessionId,
             messages,
@@ -140,7 +173,7 @@ async function runRecallFastTrackForSession(session, messages, opts = {}) {
     // digest.
     let recallText = '';
     try {
-        const browsed = await callMemoryBounded({
+        const browsed = await callMemoryColdStart({
             action: 'search',
             sessionId,
             limit: positiveContextWindow(session?.compaction?.recallDigestLimit) || 30,
@@ -298,7 +331,7 @@ export async function runSessionCompaction(session, opts = {}) {
                             signal: opts.signal || null,
                             promptCacheKey: session.promptCacheKey || null,
                             providerCacheKey: session.promptCacheKey || null,
-                            timeoutMs: positiveContextWindow(session.compaction?.timeoutMs) || 30_000,
+                            timeoutMs: semanticCompactTimeoutMs(session, beforeMessageTokens),
                             tailTurns: positiveContextWindow(session.compaction?.tailTurns) || 2,
                             keepTokens: positiveContextWindow(session.compaction?.keepTokens ?? session.compaction?.keep?.tokens),
                             preserveRecentTokens: positiveContextWindow(session.compaction?.preserveRecentTokens),
@@ -341,7 +374,7 @@ export async function runSessionCompaction(session, opts = {}) {
                     signal: opts.signal || null,
                     promptCacheKey: session.promptCacheKey || null,
                     providerCacheKey: session.promptCacheKey || null,
-                    timeoutMs: positiveContextWindow(session.compaction?.timeoutMs) || 30_000,
+                    timeoutMs: semanticCompactTimeoutMs(session, beforeMessageTokens),
                     tailTurns: positiveContextWindow(session.compaction?.tailTurns) || 2,
                     keepTokens: positiveContextWindow(session.compaction?.keepTokens ?? session.compaction?.keep?.tokens),
                     preserveRecentTokens: positiveContextWindow(session.compaction?.preserveRecentTokens),

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({
@@ -314,6 +318,11 @@ export function createSession(opts) {
         },
         tools,
         preset: toolPreset,
+        // Persisted so the deferred call-through gate (deferred-call-through.mjs
+        // resolveDeferredSelectMode) can resolve the session's tool mode; without
+        // this every session read `undefined` and write-capable deferred tools
+        // (e.g. MCP) were permanently denied auto-promotion.
+        toolSpec,
         presetName: presetObj?.name || null,
         effort,
         fast,
@@ -459,6 +468,8 @@ export async function resumeSession(sessionId, preset) {
     if (ownerIsAgent) {
         toolsForRouting = applyToolPermissionNarrowing(toolsForRouting, session.toolPermission, session.agent || null);
     }
+    // Keep the persisted tool mode in sync on resume (see createSession note).
+    session.toolSpec = toolSpec;
     session.tools = finalizeSessionToolList(toolsForRouting, {
         schemaAllowedTools: Array.isArray(session.schemaAllowedTools) ? session.schemaAllowedTools : null,
         disallowedTools: getHiddenAgent(session.agent || null) ? ['Skill'] : null,

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/store.mjs

@@ -45,17 +45,20 @@ const _lastSaveError = new Map(); // id -> { message, at }
 // starving the model of the image mid-conversation. Returns the same object
 // reference when nothing changed (no-image sessions pay only a shallow scan).
 function _sessionForDisk(session) {
-    // Strip the in-flight live-turn alias (askSession sets session.liveTurnMessages
-    // for the turn duration so contextStatus() can estimate live context growth).
-    // It is a transient duplicate of the working transcript and must never be
-    // serialized: mid-turn saves (persistIterationMetrics) would otherwise bloat
-    // the session file and persist a non-canonical message array.
-    const hasLiveTurn = session && typeof session === 'object'
-        && Object.prototype.hasOwnProperty.call(session, 'liveTurnMessages');
+    // Strip transient in-flight aliases askSession sets for the turn duration:
+    //  - liveTurnMessages: live working transcript (so contextStatus() can
+    //    estimate live context growth) — a duplicate of the working transcript
+    //    that must never be serialized (mid-turn saves would bloat the file and
+    //    persist a non-canonical message array).
+    //  - toolApprovalHook: the askOpts.onToolApproval callback wired for the
+    //    turn — a function that must never be serialized.
+    const hasTransient = session && typeof session === 'object'
+        && (Object.prototype.hasOwnProperty.call(session, 'liveTurnMessages')
+            || Object.prototype.hasOwnProperty.call(session, 'toolApprovalHook'));
     const messages = Array.isArray(session?.messages) ? session.messages : null;
     if (!messages || messages.length === 0) {
-        if (!hasLiveTurn) return session;
-        const { liveTurnMessages: _drop, ...rest } = session;
+        if (!hasTransient) return session;
+        const { liveTurnMessages: _dropLTM, toolApprovalHook: _dropTAH, ...rest } = session;
         return rest;
     }
     let changed = false;
@@ -66,11 +69,11 @@ function _sessionForDisk(session) {
         return m;
     });
     if (!changed) {
-        if (!hasLiveTurn) return session;
-        const { liveTurnMessages: _drop, ...rest } = session;
+        if (!hasTransient) return session;
+        const { liveTurnMessages: _dropLTM, toolApprovalHook: _dropTAH, ...rest } = session;
         return rest;
     }
-    const { liveTurnMessages: _drop, ...rest } = session;
+    const { liveTurnMessages: _dropLTM, toolApprovalHook: _dropTAH, ...rest } = session;
     return { ...rest, messages: out };
 }
 
@@ -305,13 +308,26 @@ export function saveSessionAsync(session, opts) {
     setLiveSession(session);
     const reqId = ++_saveWorkerReqId;
     const safeOpts = opts || null;
+    // The Worker `postMessage` below structured-clones the whole session on the
+    // main thread. `session.liveTurnMessages` (live working transcript) and
+    // `session.toolApprovalHook` (askOpts.onToolApproval callback) are transient
+    // in-flight aliases askSession sets for the turn duration; both carry
+    // non-cloneable values (a function, and raw messages that can hold functions),
+    // which makes structuredClone throw "could not be cloned" for every mid-turn
+    // iteration save. The worker strips both via _sessionForDisk anyway, so drop
+    // them from the cloned payload here WITHOUT mutating the live session object.
+    const clonePayload = (session && typeof session === 'object'
+        && (Object.prototype.hasOwnProperty.call(session, 'liveTurnMessages')
+            || Object.prototype.hasOwnProperty.call(session, 'toolApprovalHook')))
+        ? (() => { const { liveTurnMessages: _dropLTM, toolApprovalHook: _dropTAH, ...rest } = session; return rest; })()
+        : session;
     return new Promise((resolve, reject) => {
         // Persist {session, opts} so drainSessionStore can sync-flush
         // outstanding writes if process exit interrupts the worker queue.
-        _saveWorkerPending.set(reqId, { resolve, reject, session, opts: safeOpts });
+        _saveWorkerPending.set(reqId, { resolve, reject, session: clonePayload, opts: safeOpts });
         try {
             const w = _getOrSpawnWorker();
-            w.postMessage({ session, opts: safeOpts, reqId });
+            w.postMessage({ session: clonePayload, opts: safeOpts, reqId });
             // Ref AFTER successful postMessage so a queue/throw failure path
             // does not leave the worker held alive with no pending message.
             // Paired with the unref in the message handler when count hits 0.

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