mixdog 0.7.18 → 0.8.1

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

@@ -1,480 +0,0 @@
-import { getAbortSignalForSession } from '../../session/abort-lookup.mjs';
-import { execShellCommand, stripAnsi, extractPowerShellCommandInner } from '../shell-command.mjs';
-import { wrapCommandWithSnapshot } from '../shell-snapshot.mjs';
-import { stripQuotedAndHeredoc, extractShellCInner, getDestructiveCommandWarning } from '../destructive-warning.mjs';
-import { maybeRewriteWmicProcessCommand } from '../shell-policy.mjs';
-import { buildBashPolicyScanTargets, checkExecPolicyMessage, injectionBlockTargets } from '../bash-policy-scan.mjs';
-import { markCodeGraphDirtyPaths, drainCodeGraphCache } from '../code-graph.mjs';
-import {
-    buildJobNotFoundMessage,
-    startBackgroundShellJob,
-    waitForShellJob,
-    peekShellJob,
-    killShellJob,
-    watchBackgroundShellJob,
-    cancelBackgroundShellJobWatch,
-    beginShellJobWait,
-    endShellJobWait,
-    clearShellJobNotifyCtx,
-} from './shell-jobs.mjs';
-import {
-    analyzeShellCommandEffects,
-    foregroundLongCommandHint,
-    preflightShellLargeFileProbe,
-} from './shell-analysis.mjs';
-import { resolveShellFor } from './shell-runtime.mjs';
-import { smartMiddleTruncate } from './shell-output.mjs';
-import { normalizeOutputPath } from './path-utils.mjs';
-import { normalizeErrorMessage } from './path-diagnostics.mjs';
-import { invalidateBuiltinResultCache } from './cache-layers.mjs';
-import { resolveOptionalCwd } from './cwd-utils.mjs';
-import { scrubLoaderVars, scrubProviderSecrets } from '../env-scrub.mjs';
-
-// Post-exec drift detection. After a foreground shell command, compare the
-// live mtime+size of files mixdog has already read this session against their
-// pre-command state (captured just before exec). Files this command changed
-// surface as ONE compact reminder so the model re-reads before editing —
-// closing the "external write -> stale old_string -> code 8" gap when shell is
-// routed through this tool. Bounded to the tracked-read set (capped) so cost
-// stays off the whole-cwd path; emits nothing when no read file changed.
-const _DRIFT_SCAN_CAP = 256;
-export function _captureTrackedMtimes(scope) {
-    return new Map();
-}
-export function _trackedDriftNoteAfter(scope, pre) {
-    return '';
-}
-
-// Combine an existing session abort signal with an externally-supplied
-// AbortSignal (e.g. the MCP/request signal threaded through options.abortSignal).
-// Returns null when neither is present so existing session-only behavior is
-// preserved unchanged. Uses AbortSignal.any when available; falls back to a
-// manual controller + listener bridge otherwise. The returned signal aborts as
-// soon as either input signal aborts, which propagates to execShellCommand /
-// executeBashSessionTool and triggers the same child-kill path the session
-// signal already drives.
-function _combineAbortSignals(sessionSignal, externalSignal) {
-    const a = sessionSignal || null;
-    const b = externalSignal || null;
-    if (!a && !b) return null;
-    if (!a) return b;
-    if (!b) return a;
-    if (a === b) return a;
-    if (typeof AbortSignal !== 'undefined' && typeof AbortSignal.any === 'function') {
-        try { return AbortSignal.any([a, b]); } catch { /* fall through */ }
-    }
-    const ctl = new AbortController();
-    const onAbort = (sig) => {
-        if (ctl.signal.aborted) return;
-        try { ctl.abort(sig?.reason); } catch { try { ctl.abort(); } catch {} }
-    };
-    if (a.aborted) { onAbort(a); return ctl.signal; }
-    if (b.aborted) { onAbort(b); return ctl.signal; }
-    try { a.addEventListener('abort', () => onAbort(a), { once: true }); } catch {}
-    try { b.addEventListener('abort', () => onAbort(b), { once: true }); } catch {}
-    return ctl.signal;
-}
-
-// Decode ANSI-C $'…' and locale $"…" escapes so the blocklist scan sees the
-// literal command (e.g. $'\x72m' → "rm"). Defensive against quoting bypass.
-function _decodeAnsiCQuotes(s) {
-    if (typeof s !== 'string') return '';
-    if (s.indexOf('$') === -1) return s;
-    return s.replace(/\$(['"])((?:\\.|[^\\])*?)\1/g, (_full, _q, body) =>
-        body
-            .replace(/\\x([0-9a-fA-F]{1,2})/g, (_m, h) => String.fromCharCode(parseInt(h, 16)))
-            .replace(/\\u([0-9a-fA-F]{1,4})/g, (_m, h) => String.fromCharCode(parseInt(h, 16)))
-            .replace(/\\0([0-7]{1,3})/g, (_m, o) => String.fromCharCode(parseInt(o, 8)))
-            .replace(/\\([0-7]{1,3})/g, (_m, o) => String.fromCharCode(parseInt(o, 8)))
-            .replace(/\\n/g, '\n').replace(/\\t/g, '\t').replace(/\\r/g, '\r')
-            .replace(/\\\\/g, '\\').replace(/\\(['"])/g, '$1'),
-    );
-}
-
-// Extract $(…) and `…` command-substitution bodies so each is re-scanned by
-// isBlockedCommand (e.g. eval $(printf 'rm -rf ~')).
-function _extractSubstitutionBodies(s) {
-    if (typeof s !== 'string') return [];
-    const out = [];
-    const re = /\$\(([^()]*(?:\([^()]*\)[^()]*)*)\)|`([^`]*)`/g;
-    let m;
-    while ((m = re.exec(s)) !== null) {
-        const body = m[1] != null ? m[1] : m[2];
-        if (body && body.trim()) out.push(body);
-    }
-    return out;
-}
-
-// Combined injection-aware block targets: decoded form + substitution bodies
-// (and their decoded forms). Used on BOTH the persistent and stateless paths.
-export function _injectionBlockTargets(cmd) {
-    return injectionBlockTargets(cmd);
-}
-
-function _prefixPowerShellUtf8(command) {
-    const prefix = '[Console]::OutputEncoding=[System.Text.Encoding]::UTF8; $OutputEncoding=[System.Text.Encoding]::UTF8;';
-    const text = String(command || '');
-    return text.trimStart().startsWith(prefix) ? text : `${prefix}\n${text}`;
-}
-
-const _unquoteSpansForPolicy = (s) => s.replace(/"([^"\\]|\\.)*"|'([^'\\]|\\.)*'/g, (m) => m.slice(1, -1));
-
-// Same normalized + decoded target set as hard-block (strip/unquote/shell -c/PS).
-export { buildBashPolicyScanTargets } from '../bash-policy-scan.mjs';
-
-export function getDedupedDestructiveWarnings(command) {
-    const seenMsg = new Set();
-    const warnings = [];
-    for (const t of buildBashPolicyScanTargets(command)) {
-        const w = getDestructiveCommandWarning(t);
-        if (w && !seenMsg.has(w)) {
-            seenMsg.add(w);
-            warnings.push(w);
-        }
-    }
-    return warnings;
-}
-
-function _prependDestructiveWarning(command, text) {
-    const warnings = getDedupedDestructiveWarnings(command);
-    if (!warnings.length) return text;
-    return `${warnings.map((w) => `⚠️ ${w}`).join('\n')}\n${text}`;
-}
-
-export async function executeBashTool(args, workDir, options = {}) {
-    const cwdResult = resolveOptionalCwd(args.cwd, workDir);
-    if (cwdResult.error) return cwdResult.error;
-    const bashWorkDir = cwdResult.cwd;
-    const readStateScope = options?.readStateScope ?? options?.sessionId ?? null;
-
-    // Run hard-block policy BEFORE branching into the persistent-shell tool.
-    // The persistent path used to bypass the one-shot block scan because the
-    // normalization (stripQuotedAndHeredoc / extractShellCInner / unquoted
-    // span sweep) lived only on the one-shot side. Centralised policy in
-    // shell-policy.mjs already covers the literal scan + EncodedCommand
-    // decode + rm token guard; calling it here applies the same allowlist
-    // to both persistent and stateless paths.
-    const _rawCmd = String(args && args.command != null ? args.command : '');
-    if (_rawCmd) {
-        // R5-③: persistent:true used to route into bash_session BEFORE the
-        // stripQuotedAndHeredoc / extractShellCInner / unquote sweep ran
-        // (that sweep lived only on the stateless one-shot path below at
-        // ~:218). Result: `bash -c 'shutdown -h now'` / `sh -c 'mkfs ...'` /
-        // dd payloads were rejected stateless but accepted with
-        // persistent:true. Run the full sweep here so both paths share the
-        // same blocklist before dispatch.
-        const _policyBlock = checkExecPolicyMessage(_rawCmd);
-        if (_policyBlock) return _policyBlock;
-    }
-
-    // An empty-string session_id is NOT a persistent-session request: `typeof
-    // '' === 'string'` would otherwise route a stateless call into the
-    // persistent path and (on Windows) hard-fail with the disabled-sessions
-    // error, which models then retry in a loop. Require a non-blank id.
-    if (args.persistent === true || (typeof args.session_id === 'string' && args.session_id.trim().length > 0)) {
-        if (process.platform === 'win32') {
-            return 'Error: persistent shell sessions are disabled on Windows native-shell mode; run one-shot PowerShell commands without persistent/session_id.';
-        }
-        const { executeBashSessionTool } = await import('../bash-session.mjs');
-        let persistAbort = null;
-        try { persistAbort = (await getAbortSignalForSession(options?.sessionId)) || null; }
-        catch { persistAbort = null; }
-        const combinedPersistAbort = _combineAbortSignals(persistAbort, options?.abortSignal || null);
-        let effectiveArgs = (args.persistent === true && !args.session_id && options?.sessionId)
-            ? { ...args, session_id: `__default__${options.sessionId}` }
-            : (typeof args.session_id === 'string' && options?.sessionId)
-            ? { ...args, session_id: `${options.sessionId}__${args.session_id}` }
-            : args;
-        const userProvidedSession = typeof args.session_id === 'string' && args.session_id.trim().length > 0;
-        const shouldCreate = args.create === true || !userProvidedSession;
-        effectiveArgs = { ...effectiveArgs, create: shouldCreate };
-        return executeBashSessionTool('bash_session', effectiveArgs, bashWorkDir, { abortSignal: combinedPersistAbort, sessionId: options?.sessionId });
-    }
-
-    let command = args.command;
-    if (!command) return 'Error: command is required';
-
-    // Resolve the shell up front so shell-type-specific handling (PS-only wmic
-    // rewrite, PS UTF-8 prefix) can gate on it. kind 'default' is byte-identical
-    // to today's resolveShell(); kind 'bash' on Windows resolves Git Bash, and a
-    // null spec means it is genuinely not installed — surface a clear error with
-    // NO silent fallback to the other shell.
-    const shellKind = args.shell === 'bash' || args.shell === 'powershell' ? args.shell : 'default';
-    const resolvedSpec = resolveShellFor(shellKind);
-    if (!resolvedSpec) {
-        if (shellKind === 'bash') {
-            return "Error: Git Bash not found — install Git for Windows or omit shell:'bash'.";
-        }
-        return "Error: pwsh (PowerShell) not found — install PowerShell or omit shell:'powershell'.";
-    }
-
-    // wmic→PowerShell rewrite is PowerShell-only; never mangle a command bound
-    // for bash (gate on the resolved shell type).
-    // Note: gating this to powershell did NOT change POSIX behavior — wmic is a
-    // Windows-only tool, so the rewrite was already dead code on POSIX hosts;
-    // the gate just makes that explicit.
-    const wmicRewrite = resolvedSpec.shellType === 'powershell'
-        ? maybeRewriteWmicProcessCommand(command)
-        : null;
-    if (wmicRewrite?.error) return `Error: ${wmicRewrite.error}`;
-    if (wmicRewrite?.command) command = wmicRewrite.command;
-
-    const _execPolicyBlock = checkExecPolicyMessage(command);
-    if (_execPolicyBlock) {
-        return _execPolicyBlock;
-    }
-
-    const largeProbe = await preflightShellLargeFileProbe(command, bashWorkDir);
-    if (largeProbe) return `Error: ${largeProbe.message}`;
-    let shellEffects;
-    try {
-        shellEffects = await analyzeShellCommandEffects(command, bashWorkDir);
-    } catch (err) {
-        return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
-    }
-    // Keep foreground commands on a long tool-owned timeout. The MCP dispatch
-    // layer must not add a shorter fallback ceiling when timeout is omitted.
-    const DEFAULT_BASH_TIMEOUT_MS = 600_000;
-    const DEFAULT_BACKGROUND_BASH_TIMEOUT_MS = 600_000;
-    const MAX_BASH_TIMEOUT_MS = 1_800_000;
-    const defaultTimeoutMs = args.run_in_background === true
-        ? DEFAULT_BACKGROUND_BASH_TIMEOUT_MS
-        : DEFAULT_BASH_TIMEOUT_MS;
-    const rawTimeout = (typeof args.timeout === 'number' && args.timeout > 0)
-        ? args.timeout : defaultTimeoutMs;
-    const timeoutMs = rawTimeout <= 600 ? rawTimeout * 1000 : rawTimeout;
-    const timeout = Math.min(timeoutMs, wmicRewrite?.timeoutMs || MAX_BASH_TIMEOUT_MS);
-    const mergeStderr = args.merge_stderr === true;
-    const longForegroundHint = foregroundLongCommandHint(command, timeout, args);
-    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.
-    const DEFAULT_AUTO_BACKGROUND_MS = 30_000;
-    const autoBackgroundMs = args.run_in_background === true
-      ? 0
-      : Math.min(DEFAULT_AUTO_BACKGROUND_MS, timeout);
-
-    try {
-        const { shell, shellArg, shellArgs, shellType } = resolvedSpec;
-        const spawnEnv = { ...process.env, LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8' };
-        // R5/R11: same scrub as background/persistent spawn sites (env-scrub.mjs).
-        scrubProviderSecrets(spawnEnv);
-        scrubLoaderVars(spawnEnv);
-        let wrappedCommand;
-        // PowerShell UTF-8 prefix is PS-only: the Windows Git Bash path
-        // (shellType==='posix') must NOT receive it. Snapshot wrapper stays
-        // POSIX-host-only for now — no snapshot for Windows Git Bash initially.
-        if (process.platform === 'win32' && shellType === 'powershell') {
-            wrappedCommand = _prefixPowerShellUtf8(command);
-        } else if (process.platform !== 'win32' && (shell.includes('bash') || shell.includes('zsh'))) {
-            try {
-                wrappedCommand = await wrapCommandWithSnapshot(shell, command);
-            } catch (wrapErr) {
-                return `Error: shell snapshot wrapper failed — ${normalizeErrorMessage(wrapErr instanceof Error ? wrapErr.message : String(wrapErr))}`;
-            }
-        } else {
-            wrappedCommand = command;
-        }
-        if (args.run_in_background === true) {
-            const job = startBackgroundShellJob({
-                command: wrappedCommand,
-                timeoutMs: timeout,
-                workDir: bashWorkDir,
-                mergeStderr,
-                spawnEnv,
-                shell,
-                shellArg,
-                shellArgs,
-                shellType,
-                // Per-terminal session stamp: the dispatching terminal's
-                // claude.exe pid (server-main threads callerSession.clientHostPid).
-                clientHostPid: options?.clientHostPid,
-            });
-            if (job && job.error) return `Error: ${job.error}`;
-            // Wire a one-shot completion push so the dispatching session learns
-            // the background job finished (no polling tool is auto-driven). The
-            // notify ctx is threaded down from the MCP dispatch frame
-            // (server-main agentContext / _dispatchByModule) the same way the
-            // explore tool receives notifyFn/routingSessionId/clientHostPid.
-            // Missing notifyFn (e.g. a non-MCP caller) degrades to a stderr
-            // diagnostic inside watchBackgroundShellJob — never fails the spawn.
-            try {
-                watchBackgroundShellJob(job.jobId, {
-                    notifyFn: typeof options?.notifyFn === 'function' ? options.notifyFn : null,
-                    routingSessionId: options?.routingSessionId,
-                    clientHostPid: options?.clientHostPid,
-                });
-            } catch { /* watcher arm is best-effort; never blocks the spawn */ }
-            return _prependDestructiveWarning(command, [
-                `[job: ${job.jobId}]`,
-                `[pid: ${job.pid}]`,
-                `[stdout: ${normalizeOutputPath(job.stdoutPath)}]`,
-                mergeStderr ? null : `[stderr: ${normalizeOutputPath(job.stderrPath)}]`,
-                '',
-                `Background job started for command: ${command}`,
-            ].filter(Boolean).join('\n'));
-        }
-
-        let bashAbortSignal = null;
-        try { bashAbortSignal = (await getAbortSignalForSession(options?.sessionId)) || null; }
-        catch { bashAbortSignal = null; }
-        const combinedBashAbort = _combineAbortSignals(bashAbortSignal, options?.abortSignal || null);
-        const result = await execShellCommand({
-            shell, shellArg, shellArgs, command: wrappedCommand,
-            env: spawnEnv,
-            cwd: bashWorkDir,
-            timeoutMs: timeout,
-            abortSignal: combinedBashAbort,
-            autoBackgroundMs,
-            // Threaded so an auto-backgrounded foreground job is stamped with
-            // the dispatching terminal's claude.exe pid (per-terminal scope).
-            clientHostPid: options?.clientHostPid,
-            // MCP live-progress reporter (null unless the client subscribed via
-            // callTool onprogress). execShellCommand emits throttled "running
-            // Ns" frames while the foreground command runs.
-            onProgress: typeof options?.onProgress === 'function' ? options.onProgress : null,
-        });
-        // Auto-backgrounded: the command outlived autoBackgroundMs and is
-        // still running, now adopted as a tracked shell-job. Surface the
-        // jobId + partial output so the model can poll via job_wait instead
-        // of the tool call hanging until the hard timeout.
-        if (result.backgrounded) {
-            const partialStdout = smartMiddleTruncate(stripAnsi(result.stdout || ''));
-            const partialStderr = stripAnsi(result.stderr || '');
-            const lines = [
-                result.jobId ? `[job: ${result.jobId}]` : null,
-                result.stdoutPath ? `[stdout: ${normalizeOutputPath(result.stdoutPath)}]` : null,
-                (!mergeStderr && result.stderrPath) ? `[stderr: ${normalizeOutputPath(result.stderrPath)}]` : null,
-                '',
-                result.backgroundMessage || 'auto-backgrounded; still running',
-                partialStdout ? `\n[partial stdout]\n${partialStdout}` : '',
-                (!mergeStderr && partialStderr) ? `\n[partial stderr]\n${partialStderr}` : '',
-            ].filter((l) => l !== null && l !== '');
-            return _prependDestructiveWarning(command, lines.join('\n'));
-        }
-        const stdout = stripAnsi(result.stdout || '');
-        const stderr = stripAnsi(result.stderr || '');
-        const signal = result.timedOut
-            ? 'SIGTERM'
-            : (result.killed ? 'SIGKILL' : (result.signal || null));
-        const exitCode = signal ? null : result.exitCode;
-        const isReallyErrored = !!signal || (exitCode !== 0 && exitCode !== null);
-        const _driftNote = '';
-        // Distinct timeout marker so callers see "killed by timeout after Nms"
-        // vs an external signal (e.g. user Ctrl-C, OOM kill). result.timedOut
-        // is the runtime's own timeout escalation (SIGTERM → SIGKILL via
-        // treeKill on Windows taskkill), so report the timeout ceiling that
-        // fired alongside the actual signal used to kill the tree.
-        // 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 statusMarker = result.timedOut
-            ? `[timeout: ${timeout}ms signal: ${signal || 'SIGTERM'}]`
-            : (signal
-                ? `[signal: ${signal}]`
-                : (isReallyErrored ? `[exit code: ${exitCode}]` : ''));
-        if (mergeStderr) {
-            // Post-exit concatenation. True chunk-level interleaving would
-            // require shell-level `2>&1` redirection (bash) or `*>&1`
-            // (PowerShell) inside wrappedCommand, or an in-process ordered
-            // merged stream in shell-command.mjs. Current implementation
-            // preserves stdout/stderr ordering within each stream but loses
-            // cross-stream interleaving. Acceptable for most diagnostic
-            // outputs; flag in shell-command if exact interleaving is required.
-            const merged = stdout + stderr;
-            if (statusMarker) return _prependDestructiveWarning(command, smartMiddleTruncate(`${statusMarker}\n\n${merged || '(no output)'}`) + _driftNote);
-            return _prependDestructiveWarning(command, smartMiddleTruncate(merged || '(no output)') + _driftNote);
-        }
-        const truncatedStdout = smartMiddleTruncate(stdout);
-        const truncatedStderr = stderr ? smartMiddleTruncate(stderr) : '';
-        const body = truncatedStdout || (truncatedStderr ? '' : '(no output)');
-        const stderrBlock = truncatedStderr ? `\n\n[stderr]\n${truncatedStderr}` : '';
-        let spillBlock = '';
-        if (result.stdoutPath) {
-            const sizeKb = Math.round((result.stdoutFileSize || 0) / 1024);
-            spillBlock += `\n\n[stdout: ${normalizeOutputPath(result.stdoutPath)} (${sizeKb} KB)]`;
-        }
-        if (result.stderrPath && (result.stderrFileSize || 0) > 0) {
-            const sizeKb = Math.round((result.stderrFileSize || 0) / 1024);
-            spillBlock += `\n[stderr: ${normalizeOutputPath(result.stderrPath)} (${sizeKb} KB)]`;
-        }
-        const warningBlock = [
-            wmicRewrite?.note || '',
-        ].filter(Boolean).join('\n');
-        const payload = `${body}${stderrBlock}${spillBlock}${_driftNote}`;
-        if (statusMarker) return _prependDestructiveWarning(command, `${warningBlock ? `${warningBlock}\n` : ''}${statusMarker}\n\n${payload}`);
-        return _prependDestructiveWarning(command, warningBlock ? `${warningBlock}\n${payload}` : payload);
-    }
-    finally {
-        if (shellEffects.mutationMode === 'paths') {
-            invalidateBuiltinResultCache(shellEffects.paths);
-            markCodeGraphDirtyPaths(shellEffects.paths);
-        } else if (shellEffects.mutationMode === 'global') {
-            invalidateBuiltinResultCache();
-            drainCodeGraphCache();
-        }
-    }
-}
-
-export async function executeJobWaitTool(args) {
-    const jobId = typeof args.job_id === 'string' ? args.job_id : '';
-    if (!jobId) return 'Error: job_id is required';
-    // bridge_* / sess_* are bridge-worker / orchestrator session ids, not
-    // background shell jobs. job_wait only resolves `bash run_in_background`
-    // jobs, so surface a self-correcting hint instead of the bare
-    // "job not found" that otherwise invites a wrong-tool retry loop.
-    if (/^(?:bridge_|sess_)/.test(jobId)) {
-        return `Error: "${jobId}" is a bridge/session id, not a background shell job. job_wait only waits on ids returned by \`bash\` with run_in_background:true. Bridge workers are detached and reply asynchronously — check their status with bridge type=list.`;
-    }
-    const action = typeof args.action === 'string' ? args.action.toLowerCase() : 'wait';
-    if (action === 'peek') {
-        const job = peekShellJob(jobId);
-        return job ? JSON.stringify(job, null, 2) : buildJobNotFoundMessage(jobId);
-    }
-    if (action === 'kill') {
-        const job = killShellJob(jobId);
-        // kill forces completion the caller observes here, so cancel the armed
-        // watcher (before/after kill is equivalent) to avoid a double-notify.
-        cancelBackgroundShellJobWatch(jobId);
-        // Killed entry will never fire, so drop its persistent notify ctx too —
-        // cancel keeps the ctx (for re-arm) but kill has no re-arm path.
-        clearShellJobNotifyCtx(jobId);
-        return job ? JSON.stringify(job, null, 2) : buildJobNotFoundMessage(jobId);
-    }
-    // Register as a synchronous waiter and cancel the armed watcher BEFORE
-    // awaiting: the caller consumes the outcome via this job_wait, so no async
-    // push is wanted, and cancelling up front closes the race where the armed
-    // watcher (watch callback or 2s poll) fires during the await window. The
-    // persistent notify ctx survives the cancel for a possible re-arm.
-    beginShellJobWait(jobId);
-    cancelBackgroundShellJobWatch(jobId);
-    try {
-        const job = await waitForShellJob(jobId, {
-            timeoutMs: typeof args.timeout_ms === 'number' ? args.timeout_ms : 30_000,
-            pollMs: typeof args.poll_ms === 'number' ? args.poll_ms : 250,
-        });
-        if (!job) return buildJobNotFoundMessage(jobId);
-        return JSON.stringify(job, null, 2);
-    } finally {
-        // Only the LAST concurrent waiter (post-decrement count 0) may re-arm,
-        // and only for a still-running job (timed-out wait). Re-arm with no ctx
-        // arg — watchBackgroundShellJob falls back to the persistent ctx. This
-        // prevents the concurrent-waiter double-deliver: while any other waiter
-        // is still synchronously consuming the outcome, the watcher stays off.
-        const remaining = endShellJobWait(jobId);
-        if (remaining === 0) {
-            const latest = peekShellJob(jobId);
-            if (latest && latest.status === 'running') watchBackgroundShellJob(jobId);
-            // LAST waiter out and the job already finished — the outcome was
-            // consumed synchronously, so no re-arm. Drop the persisted ctx here
-            // or it leaks (cleanup only runs on a real watcher settle, which
-            // never happens for a never-re-armed entry).
-            else clearShellJobNotifyCtx(jobId);
-        }
-    }
-}