mixdog 0.7.1

package/src/agent/orchestrator/tools/bash-session.mjs

@@ -0,0 +1,721 @@
+// bash_session — persistent shell with state preserved across calls.
+//
+// Companion to the stateless `bash` tool. The default `bash` spawns a fresh
+// subshell every call: cwd, exports, `source`d virtualenvs, shell functions
+// all vanish between invocations. That's the safe default but it's clumsy
+// for the common "cd into a project → activate venv → run three commands"
+// workflow; each step has to reconstruct the prior shell context by hand.
+//
+// bash_session keeps a long-lived `bash` child process per session_id. The
+// caller writes commands to stdin; we frame each command with a sentinel
+// so we know when the command has finished and what its exit code was.
+// State carried automatically: $PWD, exports, shell vars, readline history
+// (not that we use it), aliases, function defs, `source`d files.
+//
+// Session lifecycle:
+//   - session_id omitted         → mint a fresh id, spawn child, run command
+//   - session_id matches pool    → reuse existing child
+//   - session_id misses pool     → spawn child for that id (pool empty after
+//                                  orchestrator restart or idle eviction)
+//   - close:true                 → terminate child after command returns
+//   - idle > IDLE_TIMEOUT_MS     → reaper removes & kills the child
+//   - pool > MAX_SESSIONS        → oldest-idle evicted at spawn time
+//
+// Output protocol:
+//   write:  <command>\necho "__MIXDOG_END__:$?"\n
+//   read:   everything on stdout up to (not including) the marker line
+//   exit:   the N in __MIXDOG_END__:N
+//   stderr: captured in parallel; sentinel not echoed there, so we flush
+//           whatever arrived up to the command's completion. Small
+//           quiescence window (STDERR_DRAIN_MS) after the stdout marker
+//           so trailing writes on stderr don't get cut off.
+//
+// Safety: same BLOCKED_PATTERNS as the `bash` tool. The session holds state
+// so a dangerous command can't hide in an earlier turn (we scan per call).
+// Same ANSI strip + smart middle-truncate applied to stdout/stderr.
+//
+// This tool takes a command, not a file path — no path-safety check applies.
+
+import { spawn } from 'node:child_process';
+import * as nodeUtil from 'node:util';
+import { existsSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { invalidateBuiltinResultCache, analyzeShellCommandEffects, preflightShellLargeFileProbe } from './builtin.mjs';
+import { markCodeGraphDirtyPaths, drainCodeGraphCache } from './code-graph.mjs';
+import { isBlockedCommand, maybeRewriteWmicProcessCommand } from './shell-policy.mjs';
+import { stripQuotedAndHeredoc, extractShellCInner } from './destructive-warning.mjs';
+import { _maybeEncodePowerShellCommand } from './shell-command.mjs';
+import { _captureTrackedMtimes, _trackedDriftNoteAfter, _injectionBlockTargets, getDedupedDestructiveWarnings } from './builtin/bash-tool.mjs';
+import { scrubLoaderVars, scrubProviderSecrets } from './env-scrub.mjs';
+
+// Default 600 s (10 min), max 1800 s. Aligned with the one-shot bash tool's
+// 600 s default (builtin/bash-tool.mjs); the persistent shell carries
+// longer-running pipelines (build/test/install) than one-shot calls, so a
+// 120 s default left those workflows timing out at 2 min. Per-call `timeout`
+// still overrides, capped at MAX_TIMEOUT_MS.
+const DEFAULT_TIMEOUT_MS = 600_000;
+const MAX_TIMEOUT_MS = 1_800_000;
+const IDLE_TIMEOUT_MS = 5 * 60_000;
+const MAX_SESSIONS = 10;
+const STDERR_DRAIN_MS = 25;
+const STDERR_DRAIN_MAX_MS = 250;
+const STDERR_QUIESCENT_MS = 25;
+// SHELL_OUTPUT_MAX_CHARS — output preview cap, matches the `bash` tool.
+// Duplicated here so bash-session stays decoupled from builtin.mjs private constants.
+const SHELL_OUTPUT_MAX_CHARS = 30_000;
+// STREAM_BUF_BYTE_CAP — hard byte cap per in-memory stream buffer. Past the
+// cap data is dropped and a truncation marker injected so a runaway command
+// (e.g. `cat /dev/urandom`) can't OOM the orchestrator.
+const STREAM_BUF_BYTE_CAP = 4 * 1024 * 1024; // 4 MB per stream
+const STREAM_TRUNC_MARKER = '\n... [TRUNCATED — stream cap reached] ...\n';
+// Output truncation runtime envelope: 400 lines / 30 KB total;
+// head=80 + tail=80 lines preserved on middle-truncation.
+const SMART_BASH_MAX_LINES = 400;
+const SMART_BASH_MAX_BYTES = 30 * 1024;
+const SMART_BASH_HEAD_LINES = 80;
+const SMART_BASH_TAIL_LINES = 80;
+
+// Marker prefix for per-command sentinels. A random suffix is added on each
+// command so user output that happens to contain the static prefix does not
+// terminate the command early.
+const MARKER_PREFIX = '__MIXDOG_END__';
+
+// --- ANSI strip (self-contained; mirrors builtin.mjs's implementation) ---
+const _ANSI_REGEX = /\u001B(?:\[[0-?]*[ -/]*[@-~]|\][\s\S]*?(?:\u0007|\u001B\\|\u009C))/g;
+const _stripAnsi = typeof nodeUtil.stripVTControlCharacters === 'function'
+    ? (s) => nodeUtil.stripVTControlCharacters(s)
+    : (s) => s.replace(_ANSI_REGEX, () => '');
+function stripAnsi(s) {
+    if (typeof s !== 'string' || s.length === 0) return s;
+    return _stripAnsi(s);
+}
+
+function escapeRegex(s) {
+    return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// --- Smart middle-truncate (shared with bash tool) ---
+function smartMiddleTruncate(content) {
+    const s = typeof content === 'string' ? content : String(content ?? '');
+    if (s.length <= SMART_BASH_MAX_BYTES) {
+        const fastLines = s.split('\n');
+        if (fastLines.length <= SMART_BASH_MAX_LINES) return s;
+        const head = fastLines.slice(0, SMART_BASH_HEAD_LINES).join('\n');
+        const tail = fastLines.slice(-SMART_BASH_TAIL_LINES).join('\n');
+        const middle = fastLines.length - SMART_BASH_HEAD_LINES - SMART_BASH_TAIL_LINES;
+        return `${head}\n\n... [TRUNCATED — ${middle} lines middle elided; total ${fastLines.length} lines. Rerun with tighter filters for more] ...\n\n${tail}`;
+    }
+    const lines = s.split('\n');
+    if (lines.length <= SMART_BASH_MAX_LINES) {
+        const head = s.slice(0, SMART_BASH_MAX_BYTES);
+        return `${head}\n\n... [TRUNCATED — output exceeded ${Math.round(SMART_BASH_MAX_BYTES / 1024)} KB on a single line] ...`;
+    }
+    const head = lines.slice(0, SMART_BASH_HEAD_LINES).join('\n');
+    const tail = lines.slice(-SMART_BASH_TAIL_LINES).join('\n');
+    const middle = lines.length - SMART_BASH_HEAD_LINES - SMART_BASH_TAIL_LINES;
+    const totalKb = Math.round(s.length / 1024);
+    return `${head}\n\n... [TRUNCATED — ${middle} lines middle elided; total ${lines.length} lines / ${totalKb} KB. Rerun with tighter filters for more] ...\n\n${tail}`;
+}
+
+function _prependDestructiveWarning(command, text) {
+    const warnings = getDedupedDestructiveWarnings(command);
+    if (!warnings.length) return text;
+    return `${warnings.map((w) => `⚠️ ${w}`).join('\n')}\n${text}`;
+}
+
+// Blocked command check delegated to shell-policy.mjs (shared with
+// builtin.mjs). See that module for the full pattern set and rationale.
+// Locate a usable bash binary on POSIX. Windows intentionally does not
+// support persistent shell sessions; one-shot commands use PowerShell
+// through builtin/bash-tool.mjs. We deliberately pin bash (not sh) since
+// the feature set depended on by the sentinel echo and `$?` is bash-shaped.
+function resolveBash() {
+    if (process.platform === 'win32') {
+        throw new Error('persistent shell sessions are not supported on Windows; use one-shot PowerShell commands');
+    }
+    if (existsSync('/bin/bash')) return '/bin/bash';
+    if (existsSync('/usr/bin/bash')) return '/usr/bin/bash';
+    return '/bin/sh'; // fallback; `$?` + echo still work
+}
+
+// --- Session pool ---
+// Map<id, { proc, lastUsed, stdoutBuf, stderrBuf, busy }>
+const _sessions = new Map();
+let _reaperTimer = null;
+// R17 parent-exit hook installed exactly once at first _spawnSession. Without
+// it, persistent bash shells orphan on server-main death (the async
+// 'process-exit' path at the bottom of this module never gets to run its
+// awaits when the host dies abruptly). Sync iteration of _sessions + direct
+// _killProcessTree (sync taskkill on win, sync process.kill on posix).
+let _parentExitInstalled = false;
+function _installParentExitHook() {
+    if (_parentExitInstalled) return;
+    _parentExitInstalled = true;
+    const sweep = () => {
+        for (const [, s] of _sessions) {
+            try { _killProcessTree(s.proc); } catch { /* ignore */ }
+        }
+    };
+    try { process.on('exit', sweep); } catch { /* ignore */ }
+    try { process.on('SIGTERM', sweep); } catch { /* ignore */ }
+    try { process.on('SIGINT', sweep); } catch { /* ignore */ }
+}
+
+function _startReaper() {
+    if (_reaperTimer) return;
+    _reaperTimer = setInterval(() => {
+        const now = Date.now();
+        for (const [id, s] of _sessions) {
+            if (!s.busy && now - s.lastUsed > IDLE_TIMEOUT_MS) {
+                _killSession(id, 'idle-timeout');
+            }
+        }
+        if (_sessions.size === 0) {
+            clearInterval(_reaperTimer);
+            _reaperTimer = null;
+        }
+    }, 30_000);
+    // Don't keep the event loop alive just for the reaper.
+    if (typeof _reaperTimer.unref === 'function') _reaperTimer.unref();
+}
+
+// Kill a spawned shell along with any child processes it forked. Posix path
+// signals the process group (pgid == pid because we spawn with detached:true),
+// so `sleep 1000 &` or a node server started inside the session is reaped
+// instead of being left orphaned holding pipes open. Windows uses taskkill
+// /T /F to walk the process tree. SIGTERM is sent first so well-behaved
+// children can shut down cleanly; a SIGKILL escalation timer (3 s) forces the
+// issue if they don't. Safe to call multiple times — all errors swallowed.
+function _killProcessTree(proc) {
+    // proc.killed flips to true the moment a signal is *sent*, NOT when the
+    // child actually exits — escalation off `proc.killed` was a no-op. We
+    // instead track the real exit/close state via a flag and only escalate
+    // when neither has fired by the timer deadline.
+    if (!proc) return;
+    const pid = proc.pid;
+    if (!pid) return;
+    let exited = false;
+    const onDone = () => { exited = true; };
+    try { proc.once('exit', onDone); } catch {}
+    try { proc.once('close', onDone); } catch {}
+    // Already dead from a prior call? Skip the SIGTERM but still let the
+    // listener wiring above clean up if a future exit/close arrives.
+    if (proc.exitCode !== null && proc.exitCode !== undefined) {
+        exited = true;
+    } else if (proc.signalCode) {
+        exited = true;
+    }
+    try {
+        if (process.platform === 'win32') {
+            // /T walks the tree, /F forces — no graceful SIGTERM on win.
+            spawn('taskkill', ['/pid', String(pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' });
+        } else if (!exited) {
+            try { process.kill(-pid, 'SIGTERM'); }
+            catch { try { proc.kill('SIGTERM'); } catch { /* ignore */ } }
+        }
+    } catch { /* ignore */ }
+    // Escalate to SIGKILL if the child hasn't actually exited by the
+    // deadline. Windows taskkill /F is already forceful, so only posix
+    // needs the escalation timer.
+    if (process.platform !== 'win32') {
+        const esc = setTimeout(() => {
+            if (exited) return;
+            try { process.kill(-pid, 'SIGKILL'); }
+            catch { try { proc.kill('SIGKILL'); } catch { /* ignore */ } }
+        }, 3000);
+        if (typeof esc.unref === 'function') esc.unref();
+    }
+}
+
+async function _killSession(id, _reason) {
+    const s = _sessions.get(id);
+    if (!s) return;
+    _sessions.delete(id);
+    const exited = new Promise((resolve) => {
+        s.proc.once('exit', resolve);
+        s.proc.once('close', resolve);
+    });
+    try { s.proc.stdin?.end(); } catch { /* ignore */ }
+    _killProcessTree(s.proc);
+    await Promise.race([exited, new Promise((r) => setTimeout(r, 3000))]);
+}
+
+function shellQuoteSingle(s) {
+    return `'${String(s).replace(/'/g, `'\"'\"'`)}'`;
+}
+
+function _hostPathToShellPath(p) {
+    let s = String(p || '').replace(/\\/g, '/');
+    return s;
+}
+
+function _shellPwdToHostPath(p) {
+    return String(p || '').trim();
+}
+
+function _cwdKey(p) {
+    let s = _hostPathToShellPath(p).replace(/\/+$/, '');
+    if (process.platform === 'win32') s = s.toLowerCase();
+    return s || '/';
+}
+
+async function _ensureSessionCwd(entry, targetCwd, timeoutMs) {
+    if (!targetCwd || _cwdKey(entry.cwd) === _cwdKey(targetCwd)) return null;
+    const cdTarget = _hostPathToShellPath(targetCwd);
+    const result = await _runCommand(entry, `cd ${shellQuoteSingle(cdTarget)}`, Math.min(timeoutMs, 5000));
+    if (result?.exit_code !== 0) {
+        const stderr = stripAnsi(result?.stderr || '').trim();
+        return `Error: failed to set persistent cwd: ${targetCwd}${stderr ? `\n\n[stderr]\n${stderr}` : ''}`;
+    }
+    entry.cwd = targetCwd;
+    return null;
+}
+
+function _evictOldestIfFull() {
+    if (_sessions.size < MAX_SESSIONS) return;
+    // Prefer an idle session. If all are busy we can't evict safely; throw.
+    let oldestId = null;
+    let oldestTs = Infinity;
+    for (const [id, s] of _sessions) {
+        if (s.busy) continue;
+        if (s.lastUsed < oldestTs) {
+            oldestTs = s.lastUsed;
+            oldestId = id;
+        }
+    }
+    if (oldestId) {
+        _killSession(oldestId, 'pool-full');
+        return;
+    }
+    throw new Error(`bash_session pool full (${MAX_SESSIONS} concurrent sessions, all busy)`);
+}
+
+// Build the env handed to the child bash. This path is POSIX-only; Windows
+// one-shot commands use PowerShell and persistent shell sessions are disabled.
+function buildBashEnv() {
+    const env = { ...process.env, LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8' };
+    // R5 secret scrub — strip provider/cloud tokens before handing env to
+    // the persistent shell. The stateless `bash` tool applies this same
+    // sweep in builtin/bash-tool.mjs; the persistent shell's env is
+    // constructed here and returns before that site runs, so it must be
+    // done independently. Shared with shell-jobs and shell-snapshot via
+    // env-scrub.mjs so the prefix/suffix lists never drift.
+    scrubProviderSecrets(env);
+    // R11 loader/execution scrub (NODE_OPTIONS, LD_PRELOAD, DYLD_*, …).
+    scrubLoaderVars(env);
+    return env;
+}
+
+function _spawnSession(id, initialCwd = process.cwd()) {
+    _installParentExitHook();
+    _evictOldestIfFull();
+    const shell = resolveBash();
+    const proc = spawn(shell, [], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: buildBashEnv(),
+        cwd: initialCwd,
+        windowsHide: true,
+        // detached:true on posix gives the child its own process group so
+        // _killProcessTree can signal the whole group (catches `sleep 1000 &`
+        // and similar backgrounded children). Skipped on win32 where
+        // detached has different semantics (no console attached, used for
+        // daemonization — unwanted here).
+        detached: process.platform !== 'win32',
+    });
+    proc.stdout.setEncoding('utf-8');
+    proc.stderr.setEncoding('utf-8');
+    const entry = {
+        proc,
+        lastUsed: Date.now(),
+        cwd: initialCwd,
+        stdoutBuf: '',
+        stderrBuf: '',
+        busy: false,
+        dead: false,
+        exitInfo: null,
+    };
+    // Hard-capped concat: past STREAM_BUF_BYTE_CAP we drop further
+    // chunks and stamp a truncation marker once. Without this a runaway
+    // command (e.g. `cat /dev/urandom`) blocks until OOM long before any
+    // smartMiddleTruncate downstream gets a chance to trim.
+    entry.stdoutCapped = false;
+    entry.stderrCapped = false;
+    proc.stdout.on('data', (chunk) => {
+        if (entry.stdoutCapped) return;
+        entry.stdoutBuf += chunk;
+        if (entry.stdoutBuf.length >= STREAM_BUF_BYTE_CAP) {
+            entry.stdoutBuf = entry.stdoutBuf.slice(0, STREAM_BUF_BYTE_CAP) + STREAM_TRUNC_MARKER;
+            entry.stdoutCapped = true;
+        }
+    });
+    proc.stderr.on('data', (chunk) => {
+        if (entry.stderrCapped) return;
+        entry.stderrBuf += chunk;
+        if (entry.stderrBuf.length >= STREAM_BUF_BYTE_CAP) {
+            entry.stderrBuf = entry.stderrBuf.slice(0, STREAM_BUF_BYTE_CAP) + STREAM_TRUNC_MARKER;
+            entry.stderrCapped = true;
+        }
+    });
+    proc.on('error', (err) => {
+        entry.dead = true;
+        entry.exitInfo = { error: err?.message || String(err) };
+    });
+    proc.on('exit', (code, signal) => {
+        entry.dead = true;
+        entry.exitInfo = { code, signal };
+        _sessions.delete(id);
+    });
+    _sessions.set(id, entry);
+    _startReaper();
+    return entry;
+}
+
+function _getOrCreate(sessionId, initialCwd = process.cwd(), opts = {}) {
+    const explicit = typeof sessionId === 'string' && sessionId.length > 0;
+    const id = explicit ? sessionId : `sess_${randomUUID()}`;
+    let entry = _sessions.get(id);
+    if (entry && entry.dead) {
+        _sessions.delete(id);
+        entry = null;
+    }
+    if (!entry) {
+        if (explicit && opts.create !== true) {
+            return { error: `Error: unknown session_id "${id}" (pass create:true to start a new persistent session)` };
+        }
+        entry = _spawnSession(id, initialCwd);
+    }
+    return { id, entry };
+}
+
+// Core command-run: frame with sentinel, wait for marker on stdout, flush
+// stderr with a small drain window, return { stdout, stderr, exit_code }.
+function _runCommand(entry, command, timeoutMs, abortSignal = null) {
+    return new Promise((resolve, reject) => {
+        entry.busy = true;
+        // Reset buffers for this command. Anything left from a prior run is
+        // unexpected (we only return after the marker), but be defensive.
+        entry.stdoutBuf = '';
+        entry.stderrBuf = '';
+
+        let finished = false;
+        let timeoutHandle = null;
+        let abortHandler = null;
+        const marker = `${MARKER_PREFIX}:${randomUUID()}`;
+        const markerRe = new RegExp(`^${escapeRegex(marker)}:(-?\\d+)\\s*$`, 'm');
+
+        const onExit = () => {
+            if (finished) return;
+            fail(new Error('bash_session: shell exited before command completed'));
+        };
+
+        const cleanup = () => {
+            finished = true;
+            entry.busy = false;
+            entry.lastUsed = Date.now();
+            if (timeoutHandle) clearTimeout(timeoutHandle);
+            if (abortSignal && abortHandler) {
+                try { abortSignal.removeEventListener('abort', abortHandler); } catch {}
+            }
+            entry.proc.stdout.removeListener('data', onStdout);
+            entry.proc.removeListener('exit', onExit);
+        };
+
+        const settle = (result) => {
+            if (finished) return;
+            cleanup();
+            resolve(result);
+        };
+
+        const fail = (err) => {
+            if (finished) return;
+            cleanup();
+            reject(err);
+        };
+
+        const onStdout = () => {
+            const m = markerRe.exec(entry.stdoutBuf);
+            if (!m) return;
+            const exitCode = Number(m[1]);
+            // Everything before the marker line is the real stdout.
+            const before = entry.stdoutBuf.slice(0, m.index);
+            // Drain pending stderr writes adaptively. The fixed 25 ms
+            // window dropped late stderr from forked children that
+            // flushed slightly after the parent shell exited. Loop
+            // instead: poll the stderr buffer length and finish only
+            // once it's been quiescent for STDERR_QUIESCENT_MS, the
+            // child closed stderr, or we hit the absolute ceiling.
+            const drainStart = Date.now();
+            let lastLen = entry.stderrBuf.length;
+            let lastChange = drainStart;
+            let stderrClosed = false;
+            const onStderrEnd = () => { stderrClosed = true; };
+            try { entry.proc.stderr.once('end', onStderrEnd); } catch {}
+            const finish = () => {
+                try { entry.proc.stderr.removeListener('end', onStderrEnd); } catch {}
+                const stderr = entry.stderrBuf;
+                entry.stdoutBuf = '';
+                entry.stderrBuf = '';
+                settle({ stdout: before, stderr, exit_code: exitCode });
+            };
+            const tick = () => {
+                if (finished) { try { entry.proc.stderr.removeListener('end', onStderrEnd); } catch {} return; }
+                const now = Date.now();
+                const curLen = entry.stderrBuf.length;
+                if (curLen !== lastLen) {
+                    lastLen = curLen;
+                    lastChange = now;
+                }
+                if (stderrClosed) return finish();
+                if (now - drainStart >= STDERR_DRAIN_MAX_MS) return finish();
+                if (now - lastChange >= STDERR_QUIESCENT_MS) return finish();
+                setTimeout(tick, 10);
+            };
+            setTimeout(tick, STDERR_DRAIN_MS);
+        };
+
+        // Caller-driven abort (ESC / new prompt / session close). Kill the
+        // shell immediately and resolve with an aborted marker so the agent
+        // sees the cancellation rather than waiting for timeoutMs.
+        if (abortSignal) {
+            const fireAbort = () => {
+                if (finished) return;
+                const partialOut = entry.stdoutBuf || '';
+                const partialErr = entry.stderrBuf || '';
+                entry.stdoutBuf = '';
+                entry.stderrBuf = '';
+                _killProcessTree(entry.proc);
+                // Mark dead and remove from pool immediately so the next call
+                // doesn't pick up a killed shell entry.
+                entry.dead = true;
+                for (const [sid, s] of _sessions) { if (s === entry) { _sessions.delete(sid); break; } }
+                cleanup();
+                resolve({
+                    stdout: partialOut,
+                    stderr: partialErr,
+                    exit_code: null,
+                    signal: 'SIGTERM',
+                    aborted: true,
+                });
+            };
+            if (abortSignal.aborted) { fireAbort(); return; }
+            abortHandler = fireAbort;
+            abortSignal.addEventListener('abort', abortHandler, { once: true });
+        }
+
+        entry.proc.stdout.on('data', onStdout);
+        // Check the buffer in case the marker already arrived (tiny commands).
+        onStdout();
+
+        entry.proc.on('exit', onExit);
+
+        timeoutHandle = setTimeout(() => {
+            // Timeout: surface what we have but don't leave the shell in a
+            // half-run state. Killing the process is the only reliable way
+            // to interrupt a stuck command; the caller can mint a new session.
+            const partialOut = entry.stdoutBuf;
+            const partialErr = entry.stderrBuf;
+            entry.stdoutBuf = '';
+            entry.stderrBuf = '';
+            _killProcessTree(entry.proc);
+            cleanup();
+            // Return a structured result (not a reject) so the caller
+            // renders a proper exit/stderr block instead of a bare Error.
+            resolve({
+                stdout: partialOut,
+                stderr: partialErr,
+                exit_code: null,
+                signal: 'SIGTERM',
+                timed_out: true,
+                timeout_ms: timeoutMs,
+            });
+        }, timeoutMs);
+
+        // Write the command + sentinel. Newline before `echo` in case the
+        // command didn't end with one. `$?` captures the final pipeline's
+        // exit status as of bash semantics.
+        const _preEncodePolicy = checkExecPolicyMessage(command);
+        if (_preEncodePolicy) {
+            fail(new Error(_preEncodePolicy.replace(/^Error: /, '')));
+            return;
+        }
+        const encoded = _maybeEncodePowerShellCommand(command);
+        const payload = `${encoded}\necho "${marker}:$?"\n`;
+        try {
+            entry.proc.stdin.write(payload, 'utf-8');
+        } catch (err) {
+            fail(err);
+        }
+    });
+}
+
+async function _syncSessionCwd(entry, timeoutMs) {
+    try {
+        const result = await _runCommand(entry, 'pwd', Math.min(timeoutMs, 2000));
+        if (result?.exit_code !== 0) return;
+        const stdout = stripAnsi(result.stdout || '').trim();
+        if (!stdout) return;
+        const lines = stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        if (lines.length > 0) entry.cwd = _shellPwdToHostPath(lines[lines.length - 1]);
+    } catch (err) {
+        entry.syncError = `[bash-session] persistent-session cwd sync failed: ${err.message}`;
+    }
+}
+
+async function bash_session(args, cwd = process.cwd(), opts = {}) {
+    if (process.platform === 'win32') {
+        return 'Error: persistent shell sessions are not supported on Windows; use one-shot PowerShell commands without persistent/session_id.';
+    }
+    const abortSignal = opts && opts.abortSignal ? opts.abortSignal : null;
+    let command = typeof args?.command === 'string' ? args.command : '';
+    const close = args?.close === true;
+    const implicitSessionId = args?.persistent === true && typeof opts?.sessionId === 'string'
+        ? `__default__${opts.sessionId}`
+        : '';
+    const requestedSessionId = typeof args?.session_id === 'string' ? args.session_id : implicitSessionId;
+    if (!command && close) {
+        if (!requestedSessionId) return 'Error: command is required';
+        const existing = _sessions.get(requestedSessionId);
+        if (existing?.busy) return `Error: session "${requestedSessionId}" is busy executing a prior command`;
+        if (existing) await _killSession(requestedSessionId, 'close-requested');
+        return `[session: ${requestedSessionId}]\n[closed]\n\n${existing ? '(no output)' : '(no active session)'}`;
+    }
+    if (!command) return 'Error: command is required';
+    const wmicRewrite = maybeRewriteWmicProcessCommand(command);
+    if (wmicRewrite?.error) return `Error: ${wmicRewrite.error}`;
+    if (wmicRewrite?.command) command = wmicRewrite.command;
+    // R5-③: match the stateless one-shot path's full sweep so callers that
+    // reach bash_session directly (via session_id without going through
+    // executeBashTool) still get stripQuotedAndHeredoc + extractShellCInner
+    // + unquote-span coverage. Persistent:true callers funnel through
+    // executeBashTool which now pre-sweeps, but bash_session is also reached
+    // by close:true session reuse and by direct tool dispatch.
+    const _bsPolicy = checkExecPolicyMessage(command);
+    if (_bsPolicy) return _bsPolicy;
+    const explicitCwd = typeof args?.cwd === 'string' && args.cwd.trim().length > 0;
+    const requestedCwd = cwd || process.cwd();
+    const baseCwd = (() => {
+        if (explicitCwd) return requestedCwd;
+        if (requestedSessionId) {
+            const existing = _sessions.get(requestedSessionId);
+            if (existing?.cwd) return existing.cwd;
+        }
+        return requestedCwd;
+    })();
+    const largeProbe = await preflightShellLargeFileProbe(command, baseCwd);
+    if (largeProbe) return `Error: ${largeProbe.message}`;
+    const rawTimeout = typeof args?.timeout === 'number' ? args.timeout : DEFAULT_TIMEOUT_MS;
+    // Accept seconds OR milliseconds for ergonomics: values ≤ 600 are
+    // treated as seconds (matches the spec's "max 600s"); larger values
+    // are taken as ms. Cap either way.
+    const timeoutMs = rawTimeout <= 600 ? rawTimeout * 1000 : rawTimeout;
+    const effectiveTimeout = Math.min(Math.max(timeoutMs, 1000), 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;
+    if (entry.syncError) {
+        const msg = entry.syncError;
+        delete entry.syncError;
+        throw new Error(msg);
+    }
+    if (entry.busy) {
+        return `Error: session "${id}" is busy executing a prior command`;
+    }
+    if (explicitCwd) {
+        const cwdErr = await _ensureSessionCwd(entry, requestedCwd, effectiveTimeout);
+        if (cwdErr) return cwdErr;
+    }
+
+    let shellEffects;
+    try {
+        shellEffects = await analyzeShellCommandEffects(command, entry.cwd || baseCwd);
+    } catch (err) {
+        return `Error: ${err?.message || String(err)}`;
+    }
+
+    const _bsScope = opts?.readStateScope ?? opts?.sessionId ?? null;
+    const _bsPreDrift = _captureTrackedMtimes(_bsScope);
+    let result;
+    try {
+        result = await _runCommand(entry, command, effectiveTimeout, abortSignal);
+    } catch (err) {
+        return `Error: ${err?.message || String(err)}`;
+    }
+    if (result.exit_code === 0 && shellEffects.finalCwd) {
+        entry.cwd = shellEffects.finalCwd;
+    }
+    // Skip cwd sync on abort: the shell was already killed, so issuing
+    // another `pwd` would either hang on a dead pipe or spawn a fresh
+    // session against caller intent. Mark dead so the next call mints a
+    // new shell rather than reusing this one. Same logic for timeouts.
+    if (result.aborted) {
+        entry.dead = true;
+    } else if (!close && !result.timed_out) {
+        await _syncSessionCwd(entry, effectiveTimeout);
+    }
+    if (shellEffects.mutationMode === 'paths') {
+        invalidateBuiltinResultCache(shellEffects.paths);
+        markCodeGraphDirtyPaths(shellEffects.paths);
+    } else if (shellEffects.mutationMode === 'global') {
+        invalidateBuiltinResultCache();
+        drainCodeGraphCache();
+    }
+    const _bsDriftNote = _trackedDriftNoteAfter(_bsScope, _bsPreDrift);
+
+    if (close) {
+        await _killSession(id, 'close-requested');
+    }
+
+    const stdoutClean = stripAnsi(result.stdout || '');
+    const stderrClean = stripAnsi(result.stderr || '');
+    const stdoutT = smartMiddleTruncate(stdoutClean);
+    const stderrT = stderrClean ? smartMiddleTruncate(stderrClean) : '';
+
+    // Structured header so the agent can parse session_id + exit_code out
+    // of the text response without bespoke JSON. Keeps parity with the
+    // `bash` tool's free-form `[exit code: N]` marker but additive.
+    const headerLines = [`[session: ${id}]`];
+    if (wmicRewrite?.note) headerLines.push(wmicRewrite.note);
+    if (result.aborted) {
+        headerLines.push(`[aborted: caller cancelled — session killed]`);
+    } else if (result.timed_out) {
+        headerLines.push(`[timeout: ${result.timeout_ms} ms — session killed]`);
+    } else if (result.exit_code !== 0 && result.exit_code !== null) {
+        headerLines.push(`[exit code: ${result.exit_code}]`);
+    }
+    if (close) headerLines.push(`[closed]`);
+    const header = headerLines.join('\n');
+
+    const body = stdoutT || (stderrT ? '' : '(no output)');
+    const stderrBlock = stderrT ? `\n\n[stderr]\n${stderrT}` : '';
+    return _prependDestructiveWarning(command, `${header}\n\n${body}${stderrBlock}${_bsDriftNote}`);
+}
+
+// BASH_SESSION_TOOL_DEFS removed in 0.1.126: the `bash` tool's
+// `persistent:true` option absorbed every use case; the dedicated
+// `bash_session` schema only added prompt bytes and triggered LLM
+// hallucinations of the legacy name. Implementation (executeBashSessionTool,
+// closeBashSession) stays — `bash` with persistent:true routes here.
+export async function executeBashSessionTool(name, args, _cwd, opts = {}) {
+    switch (name) {
+        case 'bash_session':
+            return bash_session(args || {}, _cwd || process.cwd(), opts);
+        default:
+            throw new Error(`Unknown bash-session tool: ${name}`);
+    }
+}
+
+export function closeBashSession(sessionId, reason = 'external-close') {
+    if (!sessionId || !_sessions.has(sessionId)) return false;
+    _killSession(sessionId, reason);
+    return true;
+}
+
+// Best-effort cleanup on process exit so orphan bash children don't linger
+// when the plugin host shuts down. drain-registry runs this on signal exit
+// paths; the bare 'exit' hook stays as an idempotent backup.
+export function drainBashSessions() {
+    for (const id of [..._sessions.keys()]) _killSession(id, 'process-exit');
+}
+if (typeof process?.on === 'function') {
+    process.on('exit', drainBashSessions);
+}