mixdog 0.7.1

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

@@ -0,0 +1,480 @@
+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);
+        }
+    }
+}

package/src/agent/orchestrator/tools/builtin/binary-file.mjs

@@ -0,0 +1,76 @@
+import { closeSync, openSync, readSync } from 'fs';
+
+// Binary detection: reading a PNG / ELF / zip / compressed blob as utf-8
+// pollutes the context with U+FFFD characters and wastes tokens. Sample the
+// head and tail of the file and look for a null byte — the canonical signal
+// that the file is not plain text. Head window scales with file size:
+// min(fileSize, 64KB) head + 4KB tail, so a 250KB file with a null byte at
+// 9KB or 249KB is caught equally. The sampling is synchronous and cheap
+// relative to the 256KB read budget it guards.
+// Callers inside the ≤READ_MAX_SIZE_BYTES branch should pass st.size so the
+// tail probe fires; callers above the cap pass the real size from err.size.
+export function isBinaryFile(fullPath, fileSize = 0) {
+    const HEAD_CAP = 64 * 1024;   // 64 KB max head window
+    const TAIL_SIZE = 4 * 1024;   // 4 KB tail probe
+    const headBytes = fileSize > 0 ? Math.min(fileSize, HEAD_CAP) : HEAD_CAP;
+    let fd = null;
+    try {
+        fd = openSync(fullPath, 'r');
+        // Head probe
+        const headBuf = Buffer.allocUnsafe(headBytes);
+        const nHead = readSync(fd, headBuf, 0, headBytes, 0);
+        if (nHead === 0) return false;
+        // UTF-16 text has a null byte in every other position; a leading
+        // UTF-16 BOM marks it as text the read path can decode
+        // (detectReadEncodingFromBuffer/decodeReadBuffer support utf16le and
+        // utf16be), so exempt it rather than reject the file as binary.
+        // FF FE = UTF-16LE, FE FF = UTF-16BE.
+        if (nHead >= 2
+            && ((headBuf[0] === 0xff && headBuf[1] === 0xfe)
+                || (headBuf[0] === 0xfe && headBuf[1] === 0xff))) return false;
+        for (let i = 0; i < nHead; i++) {
+            if (headBuf[i] === 0) return true;
+        }
+        // Tail probe (only when file is larger than head window)
+        if (fileSize > headBytes && fileSize > TAIL_SIZE) {
+            const tailOffset = fileSize - TAIL_SIZE;
+            const tailBuf = Buffer.allocUnsafe(TAIL_SIZE);
+            const nTail = readSync(fd, tailBuf, 0, TAIL_SIZE, tailOffset);
+            for (let i = 0; i < nTail; i++) {
+                if (tailBuf[i] === 0) return true;
+            }
+        }
+        return false;
+    } catch {
+        return false;
+    } finally {
+        if (fd !== null) { try { closeSync(fd); } catch {} }
+    }
+}
+
+const BINARY_PREVIEW_BYTES = 256;
+
+/** Short hex preview for read when null bytes mark the file as binary. */
+export function formatBinaryReadPreview(fullPath, displayPath, fileSize, { previewBytes = BINARY_PREVIEW_BYTES } = {}) {
+    const n = Math.max(0, Math.min(previewBytes, fileSize > 0 ? fileSize : previewBytes));
+    let fd = null;
+    try {
+        fd = openSync(fullPath, 'r');
+        const buf = Buffer.alloc(n);
+        const bytesRead = readSync(fd, buf, 0, n, 0);
+        const slice = buf.subarray(0, bytesRead);
+        const hex = Array.from(slice).map((b) => b.toString(16).padStart(2, '0')).join(' ');
+        const disp = displayPath || fullPath;
+        const note = `binary, ${fileSize} byte${fileSize === 1 ? '' : 's'}`;
+        const text = `${disp}\n${note}\n${hex || '(empty)'}`;
+        return { text, snapshotMeta: { source: 'read_hex', ranges: [] } };
+    } catch {
+        const disp = displayPath || fullPath;
+        return {
+            text: `${disp}\nbinary, ${fileSize} bytes\n(preview unavailable)`,
+            snapshotMeta: { source: 'read_hex', ranges: [] },
+        };
+    } finally {
+        if (fd !== null) { try { closeSync(fd); } catch {} }
+    }
+}