@pugi/cli 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/tools/bash.js

@@ -0,0 +1,660 @@
+/**
+ * Class-aware bash tool — Sprint α5.2 (ADR-0056 PR-PUGI-CLI-M1-GAP-B).
+ *
+ * The agent loop invokes this tool through the registry name `bash`.
+ * It supersedes `file-tools.ts::bashTool`, which used the legacy
+ * blocklist gate. The tool-bridge wires this new entry point so the
+ * registry entry (`registry.ts` `bash`) is not duplicated.
+ *
+ * Behavioural changes vs the legacy tool:
+ *   1. Permission decision routes through `evaluateBashPermission`
+ *      (7-class taxonomy, mode-aware, destructive override gate).
+ *   2. Output cap is 32 KB combined stdout+stderr per call (down
+ *      from 64 KB). Overflow is persisted to
+ *      `.pugi/artifacts/<sessionId>/bash-<callId>.out` with the path
+ *      returned as `artifactRef`.
+ *   3. Cwd carry-over: the tool receives `cwd` from the previous
+ *      turn's session state and writes the new cwd back when the
+ *      command was a `cd <path>` that landed inside
+ *      `workspaceRoot ∪ additionalDirectories`. Escapes reset the
+ *      cwd to workspaceRoot and emit `bash.cwd_escape`.
+ *   4. Background jobs: when `background: true`, spawn detached,
+ *      track in `~/.pugi/jobs.json`, return immediately with
+ *      `jobId`. `listJobs()` and `killJob(jobId)` are exported.
+ *   5. 60s default timeout. SIGTERM at deadline, SIGKILL 5s later.
+ *      Emit `bash.timeout`.
+ *   6. POSIX-only (`/bin/sh`). The non-goal in ADR-0056 explicitly
+ *      drops Windows shell support for M1.
+ */
+import { randomUUID } from 'node:crypto';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { classifyBash } from '../core/bash-classifier.js';
+import { evaluateBashPermission } from '../core/permission.js';
+import { getJobRegistry, } from '../core/jobs/registry.js';
+import { recordToolCall, recordToolResult } from '../core/session.js';
+export const BASH_OUTPUT_CAP_BYTES = 32 * 1024;
+export const BASH_DEFAULT_TIMEOUT_MS = 60_000;
+export const BASH_SIGKILL_GRACE_MS = 5_000;
+/**
+ * Mid-stream cap. The 32 KB BASH_OUTPUT_CAP_BYTES is the report cap;
+ * this is the in-memory ceiling beyond which we stop buffering and
+ * SIGTERM the child to prevent a `yes`-style stream from pinning
+ * 60+ MB before the timeout watchdog fires.
+ *
+ * Code Reviewer P1 retro 2026-05-24: the async path previously
+ * accumulated stdout chunks without bound; only spawnSync had a
+ * 10 MB maxBuffer ceiling. Aligning the async path closes the gap.
+ */
+export const BASH_LIVE_OUTPUT_CAP_BYTES = 1024 * 1024;
+/**
+ * Bash tool entry point. Returns the standard shape the engine loop
+ * consumes; throws only on argument-shape errors (e.g. negative
+ * timeouts) and otherwise surfaces the failure through
+ * `{ exitCode: 126, stderr }`.
+ */
+export async function bashTool(input, ctx) {
+    const cmd = input.cmd ?? '';
+    const additionalDirectories = ctx.additionalDirectories ?? [];
+    const source = ctx.source ?? 'agent';
+    const toolCallId = recordToolCall(ctx.session, 'bash', cmd);
+    // Permission gate via the new class-aware engine.
+    const decision = evaluateBashPermission(cmd, ctx.settings.permissions.mode, {
+        workspaceRoot: ctx.root,
+        additionalDirectories,
+        source,
+    });
+    if (decision.decision !== 'allow') {
+        const reason = `Permission ${decision.decision}: ${decision.reason}`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        return {
+            stdout: '',
+            stderr: `Permission denied: ${decision.reason}`,
+            exitCode: 126,
+            nextCwd: ctx.lastBashCwd ?? ctx.root,
+            truncated: false,
+            timedOut: false,
+        };
+    }
+    // Cwd carry-over decision (also re-checked post-run).
+    const startCwd = resolveStartCwd(input.cwd ?? ctx.lastBashCwd, ctx.root, additionalDirectories);
+    // Background job branch.
+    if (input.background === true) {
+        return runBackground({ cmd, ctx, toolCallId, startCwd, additionalDirectories });
+    }
+    // Foreground branch with timeout watchdog.
+    const timeoutMs = sanitizeTimeout(input.timeoutMs);
+    const childEnv = buildChildEnv();
+    // POSIX-only `/bin/sh -c <cmd>`. The ADR-0056 non-goals explicitly
+    // exclude Windows for M1.
+    const child = spawn('/bin/sh', ['-c', cmd], {
+        cwd: startCwd,
+        env: childEnv,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        detached: false,
+    });
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    // We keep collecting beyond the report cap (BASH_OUTPUT_CAP_BYTES)
+    // for the artifact-overflow file but flag `truncated` so the
+    // agent-facing payload is the head. To prevent a runaway producer
+    // (`yes`, `cat /dev/urandom`) from pinning hundreds of megabytes
+    // before the timeout watchdog fires, we enforce a live ceiling
+    // (BASH_LIVE_OUTPUT_CAP_BYTES) and SIGTERM the child when crossed.
+    let truncatedMidStream = false;
+    const enforceLiveCap = () => {
+        if (truncatedMidStream)
+            return;
+        if (stdoutBytes + stderrBytes <= BASH_LIVE_OUTPUT_CAP_BYTES)
+            return;
+        truncatedMidStream = true;
+        try {
+            child.kill('SIGTERM');
+        }
+        catch {
+            // child already exited; the close handler will run
+        }
+    };
+    child.stdout?.on('data', (chunk) => {
+        if (truncatedMidStream)
+            return;
+        stdoutChunks.push(chunk);
+        stdoutBytes += chunk.length;
+        enforceLiveCap();
+    });
+    child.stderr?.on('data', (chunk) => {
+        if (truncatedMidStream)
+            return;
+        stderrChunks.push(chunk);
+        stderrBytes += chunk.length;
+        enforceLiveCap();
+    });
+    const timeoutOutcome = await waitWithTimeout(child, timeoutMs);
+    const stdoutFull = Buffer.concat(stdoutChunks).toString('utf8');
+    const stderrFull = Buffer.concat(stderrChunks).toString('utf8');
+    const combinedBytes = stdoutBytes + stderrBytes;
+    const truncated = combinedBytes > BASH_OUTPUT_CAP_BYTES || truncatedMidStream;
+    // Cwd carry-over: detect `cd <path> && <rest>` shapes from the
+    // command itself (we cannot observe the child's final cwd without
+    // a wrapper script). The classifier already flagged escapes; we
+    // re-validate here against allowed roots.
+    const nextCwd = computeNextCwd(cmd, startCwd, ctx.root, additionalDirectories, ctx.session);
+    // Overflow artifact when needed.
+    let artifactRef;
+    let stdoutOut = stdoutFull;
+    let stderrOut = stderrFull;
+    if (truncated) {
+        artifactRef = persistOverflow({
+            root: ctx.root,
+            sessionId: ctx.session.id,
+            toolCallId,
+            stdout: stdoutFull,
+            stderr: stderrFull,
+        });
+        stdoutOut = capToCombined(stdoutFull, stderrFull).stdout;
+        stderrOut = capToCombined(stdoutFull, stderrFull).stderr;
+    }
+    if (truncatedMidStream) {
+        // We killed the child because output cap exceeded mid-stream.
+        // Report that as the failure cause rather than as a timeout —
+        // the watchdog never fired, only our cap enforcer did.
+        const reason = `bash output cap exceeded mid-stream (cap=${BASH_LIVE_OUTPUT_CAP_BYTES} bytes)`;
+        emitEvent(ctx.session, 'bash.output_cap_exceeded', {
+            cmd,
+            capBytes: BASH_LIVE_OUTPUT_CAP_BYTES,
+        });
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        return {
+            stdout: stdoutOut,
+            stderr: stderrOut === '' ? reason : `${stderrOut}\n${reason}`,
+            exitCode: 137,
+            artifactRef,
+            nextCwd,
+            truncated: true,
+            timedOut: false,
+        };
+    }
+    if (timeoutOutcome.timedOut) {
+        emitEvent(ctx.session, 'bash.timeout', { cmd, timeoutMs });
+        recordToolResult(ctx.session, toolCallId, 'error', `bash timed out after ${timeoutMs}ms`);
+        return {
+            stdout: stdoutOut,
+            stderr: stderrOut === '' ? `bash timed out after ${timeoutMs}ms` : `${stderrOut}\nbash timed out after ${timeoutMs}ms`,
+            exitCode: 124,
+            artifactRef,
+            nextCwd,
+            truncated,
+            timedOut: true,
+        };
+    }
+    const exitCode = timeoutOutcome.exitCode;
+    recordToolResult(ctx.session, toolCallId, 'success', `bash exit=${exitCode} bytes=${combinedBytes}${artifactRef ? ` overflow=${artifactRef}` : ''}`);
+    return {
+        stdout: stdoutOut,
+        stderr: stderrOut,
+        exitCode,
+        artifactRef,
+        nextCwd,
+        truncated,
+        timedOut: false,
+    };
+}
+function sanitizeTimeout(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        return BASH_DEFAULT_TIMEOUT_MS;
+    }
+    // Cap user-supplied timeouts at 15 minutes so a runaway tool call
+    // cannot wedge the engine loop.
+    return Math.min(value, 15 * 60 * 1000);
+}
+function buildChildEnv() {
+    const childEnv = {};
+    const SAFE_ENV_ALLOW = new Set([
+        'PATH',
+        'HOME',
+        'USER',
+        'LOGNAME',
+        'SHELL',
+        'LANG',
+        'TZ',
+        'TERM',
+        'PWD',
+    ]);
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value === undefined)
+            continue;
+        if (SAFE_ENV_ALLOW.has(key) || key.startsWith('LC_')) {
+            childEnv[key] = value;
+        }
+    }
+    return childEnv;
+}
+function resolveStartCwd(requested, root, additionalDirectories) {
+    if (!requested)
+        return root;
+    const absolute = isAbsolute(requested) ? requested : resolve(root, requested);
+    const allowedRoots = [root, ...additionalDirectories];
+    for (const allowedRaw of allowedRoots) {
+        const allowed = allowedRaw.endsWith('/') ? allowedRaw.slice(0, -1) : allowedRaw;
+        if (absolute === allowed || absolute.startsWith(`${allowed}/`)) {
+            return absolute;
+        }
+    }
+    return root;
+}
+function computeNextCwd(cmd, startCwd, root, additionalDirectories, session) {
+    // We mirror the classifier's view: only `cd <path>` at the head of
+    // the command updates cwd for the next turn. We do not attempt to
+    // chase `cd` calls that fired inside subshells or compound chains
+    // (`(cd foo && ls)` leaves the parent cwd untouched).
+    const firstComponent = cmd.trim().split(/\s*(?:&&|\|\||;|\|)\s*/)[0]?.trim() ?? '';
+    const match = firstComponent.match(/^cd(?:\s+(\S+))?\s*$/);
+    if (!match)
+        return startCwd;
+    const target = match[1];
+    if (target === undefined || target === '-' || target === '~') {
+        emitEvent(session, 'bash.cwd_escape', { cmd, reason: 'cd to HOME or last dir' });
+        return root;
+    }
+    const resolved = isAbsolute(target) || target.startsWith('~')
+        ? resolve(target.startsWith('~') ? target.replace(/^~/, homedir()) : target)
+        : resolve(startCwd, target);
+    const allowedRoots = [root, ...additionalDirectories];
+    for (const allowedRaw of allowedRoots) {
+        const allowed = allowedRaw.endsWith('/') ? allowedRaw.slice(0, -1) : allowedRaw;
+        if (resolved === allowed || resolved.startsWith(`${allowed}/`)) {
+            return resolved;
+        }
+    }
+    emitEvent(session, 'bash.cwd_escape', { cmd, reason: 'cd target outside workspace' });
+    return root;
+}
+function emitEvent(session, name, body) {
+    if (!session.enabled)
+        return;
+    const line = JSON.stringify({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: new Date().toISOString(),
+        type: 'bash',
+        name,
+        ...body,
+    });
+    try {
+        appendFileSync(session.eventsPath, `${line}\n`, { encoding: 'utf8', mode: 0o600 });
+    }
+    catch {
+        // Event log is best-effort; never crash the tool because of it.
+    }
+}
+function persistOverflow(input) {
+    const dir = join(input.root, '.pugi', 'artifacts', input.sessionId);
+    try {
+        mkdirSync(dir, { recursive: true });
+        const path = join(dir, `bash-${input.toolCallId}.out`);
+        const body = `--- stdout ---\n${input.stdout}\n--- stderr ---\n${input.stderr}\n`;
+        writeFileSync(path, body, { encoding: 'utf8', mode: 0o600 });
+        return path;
+    }
+    catch {
+        return '';
+    }
+}
+function capToCombined(stdout, stderr) {
+    // Split the budget proportionally so the head of each stream is
+    // preserved. When one stream is empty the other gets the full
+    // budget.
+    if (stdout.length + stderr.length <= BASH_OUTPUT_CAP_BYTES) {
+        return { stdout, stderr };
+    }
+    if (stdout.length === 0) {
+        return { stdout: '', stderr: trimWithMarker(stderr, BASH_OUTPUT_CAP_BYTES) };
+    }
+    if (stderr.length === 0) {
+        return { stdout: trimWithMarker(stdout, BASH_OUTPUT_CAP_BYTES), stderr: '' };
+    }
+    const total = stdout.length + stderr.length;
+    const stdoutBudget = Math.max(1024, Math.floor((stdout.length / total) * BASH_OUTPUT_CAP_BYTES));
+    const stderrBudget = BASH_OUTPUT_CAP_BYTES - stdoutBudget;
+    return {
+        stdout: trimWithMarker(stdout, stdoutBudget),
+        stderr: trimWithMarker(stderr, stderrBudget),
+    };
+}
+function trimWithMarker(text, budget) {
+    if (text.length <= budget)
+        return text;
+    return `${text.slice(0, budget)}\n(...truncated at ${budget} bytes; full output in artifactRef)`;
+}
+async function waitWithTimeout(child, timeoutMs) {
+    return await new Promise((resolvePromise) => {
+        let settled = false;
+        const sigtermTimer = setTimeout(() => {
+            if (settled)
+                return;
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                // child already exited
+            }
+            const sigkillTimer = setTimeout(() => {
+                if (settled)
+                    return;
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    // already gone
+                }
+            }, BASH_SIGKILL_GRACE_MS);
+            sigkillTimer.unref();
+        }, timeoutMs);
+        sigtermTimer.unref();
+        const onClose = (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(sigtermTimer);
+            if (signal === 'SIGTERM' || signal === 'SIGKILL') {
+                // Heuristic: if we sent the signal because of the timer,
+                // report timeout. If the child raced and exited with the
+                // signal anyway (e.g. user pressed ^C through SIGINT trap)
+                // we still report timeout when the wall-clock crossed.
+                resolvePromise({ timedOut: true, exitCode: 124 });
+                return;
+            }
+            resolvePromise({ timedOut: false, exitCode: code ?? 1 });
+        };
+        child.on('close', onClose);
+        child.on('error', () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(sigtermTimer);
+            resolvePromise({ timedOut: false, exitCode: 1 });
+        });
+    });
+}
+function runBackground(input) {
+    const { cmd, ctx, toolCallId, startCwd } = input;
+    const childEnv = buildChildEnv();
+    const child = spawn('/bin/sh', ['-c', cmd], {
+        cwd: startCwd,
+        env: childEnv,
+        stdio: 'ignore',
+        detached: true,
+    });
+    child.unref();
+    const jobId = `pj-${randomUUID()}`;
+    const classification = classifyBash(cmd, {
+        workspaceRoot: ctx.root,
+        additionalDirectories: input.additionalDirectories,
+    });
+    const registry = getJobRegistry();
+    // Persist into the new registry. The promise is intentionally not
+    // awaited — `runBackground` is a synchronous control path inside the
+    // bash tool's async wrapper. The registry's atomic write is
+    // synchronous under the hood so the ledger is consistent before the
+    // caller observes the returned jobId, even when we drop the
+    // promise. Wire as a `.catch` so an unhandled-rejection never
+    // crashes the engine loop.
+    void registry
+        .add({
+        id: jobId,
+        pid: child.pid ?? -1,
+        command: cmd,
+        bashClass: classification.class,
+        cwd: startCwd,
+        sessionId: ctx.session.id,
+    })
+        .catch(() => {
+        // Best-effort persistence; the in-process tool still returned
+        // the jobId so the engine loop knows the spawn succeeded.
+    });
+    emitEvent(ctx.session, 'bash.background_started', {
+        jobId,
+        pid: child.pid ?? -1,
+        cmd,
+    });
+    recordToolResult(ctx.session, toolCallId, 'success', `bash background jobId=${jobId} pid=${child.pid ?? -1}`);
+    return {
+        stdout: `bash started in background as ${jobId}`,
+        stderr: '',
+        exitCode: 0,
+        jobId,
+        nextCwd: ctx.lastBashCwd ?? ctx.root,
+        truncated: false,
+        timedOut: false,
+    };
+}
+/**
+ * Legacy export preserved for α5.2 callers / tests. Delegates to the
+ * new JobRegistry and projects entries back into the historical
+ * `PugiJob` shape.
+ */
+export function listJobs() {
+    const entries = readRegistryEntriesSync();
+    return entries.map(entryToLegacyJob);
+}
+/**
+ * Legacy export preserved for α5.2 callers / tests. Delegates to the
+ * new JobRegistry. Returns the same `{ killed, reason? }` shape so the
+ * existing bash-tool test suite continues to pass without an
+ * end-to-end rewrite.
+ */
+export function killJob(jobId) {
+    const entries = readRegistryEntriesSync();
+    const target = entries.find((entry) => entry.id === jobId);
+    if (!target)
+        return { killed: false, reason: `unknown jobId: ${jobId}` };
+    // Mirror the legacy semantics: synchronous SIGTERM + best-effort
+    // SIGKILL escalation + remove the entry from the ledger so the
+    // bash-tool test suite's `listJobs().find(...) === undefined`
+    // assertion keeps holding. The richer `JobRegistry.kill` (status
+    // transitions, async exit polling) is what the new `pugi jobs kill`
+    // CLI command uses.
+    try {
+        process.kill(target.pid, 'SIGTERM');
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ESRCH') {
+            removeRegistryEntrySync(jobId);
+            return { killed: false, reason: 'job already exited' };
+        }
+        return { killed: false, reason: `kill failed: ${error.message}` };
+    }
+    setTimeout(() => {
+        try {
+            process.kill(target.pid, 0);
+            try {
+                process.kill(target.pid, 'SIGKILL');
+            }
+            catch {
+                // gone between the check and the signal
+            }
+        }
+        catch {
+            // already dead
+        }
+    }, BASH_SIGKILL_GRACE_MS).unref();
+    removeRegistryEntrySync(jobId);
+    return { killed: true };
+}
+function entryToLegacyJob(entry) {
+    return {
+        jobId: entry.id,
+        pid: entry.pid,
+        cwd: entry.cwd,
+        cmd: entry.command,
+        class: entry.bashClass,
+        startedAt: entry.startedAt,
+        sessionId: entry.sessionId,
+    };
+}
+/**
+ * Synchronous read of the registry file. Used by the legacy
+ * `listJobs()` / `killJob()` exports because they cannot return a
+ * promise without a breaking signature change. The new `JobRegistry`
+ * interface is the async path.
+ */
+function readRegistryEntriesSync() {
+    const path = join(homedir(), '.pugi', 'jobs.json');
+    // Inline read so the legacy listJobs/killJob entry points do not
+    // require an async hop into JobRegistry. The shape parsing mirrors
+    // `normalizeEntry` inside `core/jobs/registry.ts`.
+    if (!existsSync(path))
+        return [];
+    try {
+        const raw = readFileSync(path, 'utf8');
+        if (raw.trim() === '')
+            return [];
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        const out = [];
+        for (const candidate of parsed) {
+            if (typeof candidate !== 'object' || candidate === null)
+                continue;
+            const c = candidate;
+            const id = typeof c['id'] === 'string'
+                ? c['id']
+                : typeof c['jobId'] === 'string'
+                    ? c['jobId']
+                    : undefined;
+            const pid = typeof c['pid'] === 'number' ? c['pid'] : undefined;
+            const command = typeof c['command'] === 'string'
+                ? c['command']
+                : typeof c['cmd'] === 'string'
+                    ? c['cmd']
+                    : undefined;
+            if (!id || pid === undefined || command === undefined)
+                continue;
+            const bashClassRaw = typeof c['bashClass'] === 'string'
+                ? c['bashClass']
+                : typeof c['class'] === 'string'
+                    ? c['class']
+                    : 'unknown';
+            const status = c['status'] === 'finished' ||
+                c['status'] === 'killed' ||
+                c['status'] === 'failed' ||
+                c['status'] === 'abandoned'
+                ? c['status']
+                : 'running';
+            out.push({
+                id,
+                pid,
+                command,
+                bashClass: bashClassRaw,
+                cwd: typeof c['cwd'] === 'string' ? c['cwd'] : '',
+                startedAt: typeof c['startedAt'] === 'string'
+                    ? c['startedAt']
+                    : new Date().toISOString(),
+                status,
+                sessionId: typeof c['sessionId'] === 'string' ? c['sessionId'] : 'unknown',
+            });
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+function removeRegistryEntrySync(jobId) {
+    const path = join(homedir(), '.pugi', 'jobs.json');
+    const entries = readRegistryEntriesSync().filter((entry) => entry.id !== jobId);
+    try {
+        mkdirSync(join(homedir(), '.pugi'), { recursive: true });
+        writeFileSync(path, `${JSON.stringify(entries, null, 2)}\n`, {
+            encoding: 'utf8',
+            mode: 0o600,
+        });
+    }
+    catch {
+        // best-effort
+    }
+}
+/**
+ * Synchronous helper used by the legacy tool-bridge path. It wraps
+ * `spawnSync` for the simplest case (no background, no overflow
+ * artifact, default timeout) so callers that cannot await a promise
+ * still get the class-aware permission gate. Returns the same shape
+ * as the async tool minus the cwd carry-over (since spawnSync
+ * cannot stream we approximate the cap by post-truncation).
+ */
+export function bashToolSync(input, ctx) {
+    const cmd = input.cmd ?? '';
+    const additionalDirectories = ctx.additionalDirectories ?? [];
+    const source = ctx.source ?? 'agent';
+    const toolCallId = recordToolCall(ctx.session, 'bash', cmd);
+    const decision = evaluateBashPermission(cmd, ctx.settings.permissions.mode, {
+        workspaceRoot: ctx.root,
+        additionalDirectories,
+        source,
+    });
+    if (decision.decision !== 'allow') {
+        const reason = `Permission ${decision.decision}: ${decision.reason}`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        return {
+            stdout: '',
+            stderr: `Permission denied: ${decision.reason}`,
+            exitCode: 126,
+            nextCwd: ctx.lastBashCwd ?? ctx.root,
+            truncated: false,
+            timedOut: false,
+        };
+    }
+    const startCwd = resolveStartCwd(input.cwd ?? ctx.lastBashCwd, ctx.root, additionalDirectories);
+    const timeoutMs = sanitizeTimeout(input.timeoutMs);
+    const childEnv = buildChildEnv();
+    const result = spawnSync('/bin/sh', ['-c', cmd], {
+        cwd: startCwd,
+        env: childEnv,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: timeoutMs,
+        maxBuffer: 10 * 1024 * 1024,
+    });
+    const stdoutFull = (result.stdout ?? '').toString();
+    const stderrFull = (result.stderr ?? '').toString();
+    const truncated = stdoutFull.length + stderrFull.length > BASH_OUTPUT_CAP_BYTES;
+    let artifactRef;
+    let stdoutOut = stdoutFull;
+    let stderrOut = stderrFull;
+    if (truncated) {
+        artifactRef = persistOverflow({
+            root: ctx.root,
+            sessionId: ctx.session.id,
+            toolCallId,
+            stdout: stdoutFull,
+            stderr: stderrFull,
+        });
+        ({ stdout: stdoutOut, stderr: stderrOut } = capToCombined(stdoutFull, stderrFull));
+    }
+    const timedOut = result.error?.code === 'ETIMEDOUT' ||
+        result.signal === 'SIGTERM';
+    const exitCode = timedOut ? 124 : result.status ?? 1;
+    const nextCwd = computeNextCwd(cmd, startCwd, ctx.root, additionalDirectories, ctx.session);
+    if (timedOut) {
+        emitEvent(ctx.session, 'bash.timeout', { cmd, timeoutMs });
+        recordToolResult(ctx.session, toolCallId, 'error', `bash timed out after ${timeoutMs}ms`);
+    }
+    else {
+        recordToolResult(ctx.session, toolCallId, 'success', `bash exit=${exitCode} bytes=${stdoutFull.length + stderrFull.length}${artifactRef ? ` overflow=${artifactRef}` : ''}`);
+    }
+    return {
+        stdout: stdoutOut,
+        stderr: stderrOut,
+        exitCode,
+        artifactRef,
+        nextCwd,
+        truncated,
+        timedOut,
+    };
+}
+//# sourceMappingURL=bash.js.map