@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.10

package/dist/tools/bash.js

@@ -1,1238 +0,0 @@
-/**
- * Class-aware bash tool — Sprint .
- *
- * 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  explicitly
- *     drops Windows shell support for M1.
- */
-import { randomUUID } from 'node:crypto';
-import { appendFileSync, closeSync, existsSync, mkdirSync, readFileSync, realpathSync, 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 { applyRedirect, finaliseRedirectFile, normalizeTailLines, openRedirectFile, resolveRedirectTarget, } from '../core/bash/redirect.js';
-import { evaluateBashPermission } from '../core/permission.js';
-import { writeAuditEvent } from '../core/audit/audit-trail.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: 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);
-    // Cwd carry-over decision (also re-checked post-run).
-    const startCwd = resolveStartCwd(input.cwd ?? ctx.lastBashCwd, ctx.root, additionalDirectories);
-    // Workspace-git-boundary guard (CEO P0 #51).
-    // Runs BEFORE the permission gate so the boundary escape message is
-    // the one the operator/engine sees, regardless of permission policy.
-    // The leak is structural (git silently writes to an ancestor .git
-    // when the workspace lacks one), not a policy violation, so the
-    // diagnostic must surface even when the permission gate would
-    // otherwise have asked or auto-allowed.
-    const boundaryBlock = enforceGitBoundary(cmd, startCwd, ctx.root);
-    if (boundaryBlock !== null) {
-        emitEvent(ctx.session, 'bash.git_boundary_escape', {
-            cmd,
-            workspaceRoot: ctx.root,
-            resolvedToplevel: boundaryBlock.resolvedToplevel ?? null,
-        });
-        recordToolResult(ctx.session, toolCallId, 'error', boundaryBlock.reason);
-        return {
-            stdout: '',
-            stderr: boundaryBlock.reason,
-            exitCode: 126,
-            nextCwd: ctx.lastBashCwd ?? ctx.root,
-            truncated: false,
-            timedOut: false,
-            cancelled: false,
-        };
-    }
-    // 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);
-        // #21 : emit `permission_denied` to
-        // the tenant-wide audit trail. Truncate the cmd preview to 200
-        // chars so a long here-doc does not bloat the JSONL row; the
-        // session log keeps the full text for forensic replay.
-        writeAuditEvent({
-            event: 'permission_denied',
-            sessionId: ctx.session.id,
-            workspaceRoot: ctx.root,
-            data: {
-                tool: 'bash',
-                source,
-                decision: decision.decision,
-                reason: decision.reason,
-                cmdPreview: cmd.slice(0, 200),
-            },
-        });
-        return {
-            stdout: '',
-            stderr: `Permission denied: ${decision.reason}`,
-            exitCode: 126,
-            nextCwd: ctx.lastBashCwd ?? ctx.root,
-            truncated: false,
-            timedOut: false,
-            cancelled: false,
-        };
-    }
-    // CEO P1 #25 — pre-spawn cancellation check. Fires
-    // AFTER the permission gate so a cancelled brief never reaches
-    // /bin/sh even when the command would have been allowed. Mirrors
-    // the `gateOnCancellation` pattern from file-tools.ts.
-    if (ctx.cancellation?.isAborted === true) {
-        const reason = 'operator_aborted: bash refused before spawn';
-        emitEvent(ctx.session, 'bash.cancelled', { cmd, phase: 'pre_spawn' });
-        recordToolResult(ctx.session, toolCallId, 'cancelled', reason);
-        return {
-            stdout: '',
-            stderr: reason,
-            exitCode: 130,
-            nextCwd: ctx.lastBashCwd ?? ctx.root,
-            truncated: false,
-            timedOut: false,
-            cancelled: true,
-        };
-    }
-    // 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();
-    // Pugi backlog P2 — redirect path. When the caller opted into
-    // stdout redirect, we open a write-only fd at the resolved log
-    // path and hand it directly to the child's stdio array so the
-    // child writes through the kernel pipe → file fd without buffering
-    // hundreds of MB in the Node process. The buffered code path below
-    // is the fallback for callers that did not opt in.
-    let redirectState = null;
-    if (input.redirect !== undefined) {
-        try {
-            const target = resolveRedirectTarget({
-                workspaceRoot: ctx.root,
-                sessionId: ctx.session.id,
-                toolCallId,
-                command: cmd,
-                override: input.redirect.path,
-            });
-            const { fd, tempPath } = openRedirectFile(target);
-            redirectState = {
-                target,
-                fd,
-                tempPath,
-                tailLines: normalizeTailLines(input.redirect.tailLines),
-            };
-        }
-        catch (error) {
-            // Bad caller-supplied path (absolute, traversal escape). Fall
-            // back to a structured error rather than crashing the engine
-            // loop. Mirrors how the permission gate surfaces a refusal —
-            // the model can adjust the redirect spec and retry.
-            const reason = `redirect refused: ${error.message}`;
-            recordToolResult(ctx.session, toolCallId, 'error', reason);
-            return {
-                stdout: '',
-                stderr: reason,
-                exitCode: 126,
-                nextCwd: ctx.lastBashCwd ?? ctx.root,
-                truncated: false,
-                timedOut: false,
-                cancelled: false,
-            };
-        }
-    }
-    // POSIX-only `/bin/sh -c <cmd>`. The  non-goals explicitly
-    // exclude Windows for M1.
-    //
-    // stdio layout:
-    //  - default: ['ignore', 'pipe', 'pipe'] — buffer chunks in
-    //               Node so the post-run capToCombined can size them
-    //               to the report cap.
-    //  - redirect: ['ignore', fd, fd] — kernel pipes stdout+stderr
-    //               straight into the log file fd. No Node-side
-    //               buffering, no truncation marker, no in-memory
-    //               ceiling. The tail-reader fishes the trailing
-    //               lines out of the file after the child exits.
-    const stdioLayout = redirectState !== null
-        ? ['ignore', redirectState.fd, redirectState.fd]
-        : ['ignore', 'pipe', 'pipe'];
-    const child = spawn('/bin/sh', ['-c', cmd], {
-        cwd: startCwd,
-        env: childEnv,
-        stdio: stdioLayout,
-        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;
-    // CEO P1 #25 — mid-stream operator cancellation. The
-    // listener registered against the CancellationToken below flips
-    // this flag and SIGTERMs the child. The close handler reads it to
-    // decide between `cancelled` (operator abort) and `timedOut`
-    // (watchdog).
-    let cancelledMidStream = 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
-        }
-    };
-    // CEO P1 #25 — live stream callback. When the REPL
-    // host wires `onStreamChunk`, we forward each stdout/stderr chunk
-    // in real time so the conversation pane / tool-stream pane paint
-    // bytes as they arrive instead of waiting for the child to exit.
-    // We invoke the callback inside a try/catch so a buggy sink
-    // (renderer crash, assertion error) never escalates to killing
-    // the bash dispatch. The buffered path below still captures the
-    // chunk so the model + audit trail stay consistent regardless of
-    // renderer health.
-    const onStreamChunk = ctx.onStreamChunk;
-    const emitStreamChunk = onStreamChunk
-        ? (stream, chunk) => {
-            try {
-                onStreamChunk({ stream, data: chunk.toString('utf8') });
-            }
-            catch {
-                // Sink crash — swallow.
-            }
-        }
-        : null;
-    // When redirect is on, child.stdout / child.stderr are null
-    // because the spawn handed the log-file fd in directly. The data
-    // listeners only fire on the buffered path, which is exactly what
-    // we want — the redirect contract is "no in-memory buffer, full
-    // output goes to disk".
-    if (redirectState === null) {
-        child.stdout?.on('data', (chunk) => {
-            if (truncatedMidStream || cancelledMidStream)
-                return;
-            stdoutChunks.push(chunk);
-            stdoutBytes += chunk.length;
-            if (emitStreamChunk)
-                emitStreamChunk('stdout', chunk);
-            enforceLiveCap();
-        });
-        child.stderr?.on('data', (chunk) => {
-            if (truncatedMidStream || cancelledMidStream)
-                return;
-            stderrChunks.push(chunk);
-            stderrBytes += chunk.length;
-            if (emitStreamChunk)
-                emitStreamChunk('stderr', chunk);
-            enforceLiveCap();
-        });
-    }
-    // CEO P1 #25 — wire the cancellation token to SIGTERM. We track
-    // the detach handle so a successful run releases the listener
-    // instead of leaving it pinned to a long-lived REPL
-    // CancellationToken (same anti-leak pattern as
-    // native-pugi.ts:262).
-    let detachCancelListener;
-    if (ctx.cancellation && !ctx.cancellation.isAborted) {
-        const onAbort = () => {
-            if (cancelledMidStream)
-                return;
-            cancelledMidStream = true;
-            emitEvent(ctx.session, 'bash.cancelled', { cmd, phase: 'mid_stream' });
-            try {
-                child.kill('SIGTERM');
-            }
-            catch {
-                // child already exited; close handler will run
-            }
-            // SIGKILL escalation if the child does not honour SIGTERM
-            // within the grace window. Mirrors the timeout watchdog's
-            // two-phase shutdown.
-            setTimeout(() => {
-                if (child.exitCode !== null || child.signalCode !== null)
-                    return;
-                try {
-                    child.kill('SIGKILL');
-                }
-                catch {
-                    // gone between the check and the signal
-                }
-            }, BASH_SIGKILL_GRACE_MS).unref();
-        };
-        detachCancelListener = ctx.cancellation.onAbort(onAbort);
-    }
-    const timeoutOutcome = await waitWithTimeout(child, timeoutMs);
-    // Detach the cancellation listener on completion so a long-lived
-    // REPL token does not retain a reference to the dead child + this
-    // closure.
-    if (detachCancelListener) {
-        try {
-            detachCancelListener();
-        }
-        catch { /* listener already drained */ }
-    }
-    // Pugi backlog P2 — redirect path. Close the log fd, rename
-    // the temp file into place, and return the envelope before the
-    // buffered-path code paths run. We do this for every exit shape
-    // (success, non-zero, timeout, cancel) so the log file always
-    // lands on disk and the tail reflects whatever the child produced
-    // before termination. The cancel/timeout branches still surface
-    // the appropriate exitCode through the envelope; the operator
-    // discovers the failure via `tail` + `exitCode`, not via the
-    // legacy stdout/stderr strings.
-    if (redirectState !== null) {
-        // Close our copy of the fd before rename so the inode is no
-        // longer held open by the parent process. The child's stdio
-        // already inherited a separate fd; closing ours does not affect
-        // the child's writes that already happened.
-        try {
-            closeSync(redirectState.fd);
-        }
-        catch {
-            // already closed (shouldn't happen on the happy path)
-        }
-        try {
-            finaliseRedirectFile(redirectState.target, redirectState.tempPath);
-        }
-        catch {
-            // best-effort — the temp file still exists on disk for the
-            // operator to inspect even if the rename failed.
-        }
-        const redirectExitCode = cancelledMidStream
-            ? 130
-            : timeoutOutcome.timedOut
-                ? 124
-                : timeoutOutcome.exitCode;
-        const envelope = applyRedirect({
-            target: redirectState.target,
-            exitCode: redirectExitCode,
-            tailLines: redirectState.tailLines,
-        });
-        const nextCwdRedirect = computeNextCwd(cmd, startCwd, ctx.root, additionalDirectories, ctx.session);
-        // Emit the same lifecycle events the buffered path emits so the
-        // session audit trail is symmetric across redirect vs non-redirect
-        // dispatches.
-        if (cancelledMidStream) {
-            recordToolResult(ctx.session, toolCallId, 'cancelled', `operator_aborted: bash killed mid-stream (redirect=${envelope.logPath})`);
-        }
-        else if (timeoutOutcome.timedOut) {
-            emitEvent(ctx.session, 'bash.timeout', { cmd, timeoutMs });
-            recordToolResult(ctx.session, toolCallId, 'error', `bash timed out after ${timeoutMs}ms (redirect=${envelope.logPath})`);
-        }
-        else {
-            recordToolResult(ctx.session, toolCallId, 'success', `bash exit=${redirectExitCode} redirect=${envelope.logPath}`);
-        }
-        return {
-            stdout: envelope.stdout,
-            stderr: envelope.stderr,
-            exitCode: redirectExitCode,
-            nextCwd: nextCwdRedirect,
-            truncated: envelope.truncated,
-            timedOut: timeoutOutcome.timedOut,
-            cancelled: cancelledMidStream,
-            logPath: envelope.logPath,
-            tail: envelope.tail,
-        };
-    }
-    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;
-    }
-    // CEO P1 #25 — cancellation wins races against timeout / cap
-    // overflow. The token already aborted by the time the close
-    // handler fires; we distinguish operator-driven termination from
-    // the watchdog so the REPL transcript reads "Aborted." rather
-    // than "Timed out."
-    if (cancelledMidStream) {
-        const reason = 'operator_aborted: bash killed mid-stream';
-        recordToolResult(ctx.session, toolCallId, 'cancelled', reason);
-        return {
-            stdout: stdoutOut,
-            stderr: stderrOut === '' ? reason : `${stderrOut}\n${reason}`,
-            exitCode: 130,
-            artifactRef,
-            nextCwd,
-            truncated,
-            timedOut: false,
-            cancelled: true,
-        };
-    }
-    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,
-            cancelled: 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,
-            cancelled: false,
-        };
-    }
-    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,
-        cancelled: 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,
-        cancelled: false,
-    };
-}
-/**
- * Legacy export preserved for 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 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 [];
-    }
-}
-/**
- * Workspace-git-boundary guard (CEO P0 #51).
- *
- * Background: CEO live REPL surfaced a scenario where the customer
- * workspace dir was created INSIDE another git repository (the Pugi
- * monorepo itself). The model emitted `git init && git add . && git
- * commit -m ...` against that workspace. The workspace had no `.git`
- * of its own so git silently walked up to the outer repo's `.git` and
- * committed the customer's files directly to the monorepo's main
- * branch. Had the outer remote been FF-permissive, those files would
- * have pushed to production. This is a customer-of-customer leak.
- *
- * The guard: when the agent emits a mutating git op (add / commit /
- * push / rebase / reset / checkout) and the effective git toplevel
- * (`git -C $cwd rev-parse --show-toplevel`) sits OUTSIDE the workspace
- * root, block the command. The model is steered (via the persona
- * prompt) to run `git init` first; the guard is the defensive net so
- * a careless model emission cannot cross the boundary.
- *
- * Exported so the spec can exercise the predicate in isolation without
- * having to drive the whole bash tool.
- */
-export const GIT_BOUNDARY_BLOCK_PREFIX = 'git boundary escape:';
-/**
- * Subcommands we treat as definitely mutating for the boundary check.
- * We intentionally OMIT subcommands that have common read-only modes
- * (`branch --list`, `tag --list`, `stash list`, `remote -v`) to keep
- * the guard precise. The CEO P0 #51 leak vector is files written to
- * an ancestor repo's working tree / refs, which the included set
- * fully covers. The omitted subcommands can still create refs in the
- * outer .git, but they do not move customer files into the outer
- * repo's commit graph, so the leak severity is lower and the
- * ergonomic cost of false positives on `--list` flags is higher.
- */
-const MUTATING_GIT_SUBCOMMANDS = new Set([
-    'add',
-    'commit',
-    'push',
-    'rebase',
-    'reset',
-    'checkout',
-    'merge',
-    'restore',
-    'switch',
-    'cherry-pick',
-    'am',
-    'apply',
-    'clean',
-    'rm',
-    'mv',
-]);
-/**
- * Inspect a shell command for mutating git operations. Returns the
- * first matching subcommand (e.g. 'commit') or null when none of the
- * components are mutating git ops.
- *
- * We split on `&&`, `||`, `;`, `|` so a compound like
- * `mkdir foo && cd foo && git add .` is correctly flagged on the
- * trailing git component.
- */
-export function detectMutatingGitOp(cmd) {
-    const components = cmd.split(/\s*(?:&&|\|\||;|\|)\s*/);
-    for (const raw of components) {
-        const component = raw.trim();
-        if (component === '')
-            continue;
-        // Strip leading `sudo` wrapper which would otherwise hide the verb.
-        const stripped = component.replace(/^sudo\s+/, '');
-        // Match `git [<global-flags>] <subcommand> ...`. Global flags we
-        // tolerate:
-        //  - long flag: `--no-pager`, `--git-dir=.git`
-        //  - short flag with attached value: `-C <path>`, `-c <k=v>`
-        //  - bare short flag: `-P`
-        // Anything weirder falls through and the predicate returns null,
-        // which means the guard does not fire on that component — safer
-        // to err open here because the destructive classifier and the
-        // outer permission gate are independent defences.
-        const match = stripped.match(/^git(?:\s+(?:--[A-Za-z][A-Za-z0-9-]*(?:=\S+)?|-[CcP](?:\s+\S+)?|-[A-Za-z]+))*\s+([a-z][a-z0-9-]*)\b/);
-        if (!match)
-            continue;
-        const subcommand = match[1];
-        if (subcommand && MUTATING_GIT_SUBCOMMANDS.has(subcommand)) {
-            return subcommand;
-        }
-    }
-    return null;
-}
-/**
- * Resolve the workspace's effective git boundary. Returns:
- *  - the absolute path of the .git toplevel that owns `cwd`
- *  - null when no .git ancestor exists at all (standalone, no repo)
- *
- * Pure filesystem walk so the guard does not depend on git being on
- * PATH. We look for either a `.git` directory or a `.git` file (the
- * worktree case where `.git` is a pointer file).
- */
-export function resolveGitToplevel(cwd) {
-    let dir = cwd;
-    while (true) {
-        const dotGit = join(dir, '.git');
-        if (existsSync(dotGit))
-            return dir;
-        const parent = resolve(dir, '..');
-        if (parent === dir)
-            return null;
-        dir = parent;
-    }
-}
-/**
- * The actual guard. Returns null when the command is allowed; returns
- * a block descriptor when it should be denied. The block message uses
- * the literal prefix `git boundary escape:` so callers (and the spec)
- * can pattern-match.
- */
-export function enforceGitBoundary(cmd, startCwd, workspaceRoot) {
-    const subcommand = detectMutatingGitOp(cmd);
-    if (subcommand === null)
-        return null;
-    // Resolve symlinks on both sides so a /var → /private/var macOS
-    // realpath divergence does not produce a false escape.
-    const root = safeRealpath(workspaceRoot);
-    const toplevel = resolveGitToplevel(safeRealpath(startCwd));
-    const resolvedToplevel = toplevel === null ? null : safeRealpath(toplevel);
-    if (resolvedToplevel === root)
-        return null;
-    // Either no .git anywhere (standalone) OR the .git that wins is an
-    // ancestor — both are escape scenarios. Operator must run `git init`
-    // explicitly inside the workspace.
-    if (resolvedToplevel === null) {
-        return {
-            subcommand,
-            resolvedToplevel: null,
-            reason: `${GIT_BOUNDARY_BLOCK_PREFIX} workspace root '${workspaceRoot}' has no .git ` +
-                `and no ancestor repository exists. Run \`git init\` in the workspace first ` +
-                `before \`git ${subcommand}\`.`,
-        };
-    }
-    return {
-        subcommand,
-        resolvedToplevel,
-        reason: `${GIT_BOUNDARY_BLOCK_PREFIX} workspace root '${workspaceRoot}' has no .git; ` +
-            `outer toplevel is '${resolvedToplevel}'. Run \`git init\` in the workspace ` +
-            `first before \`git ${subcommand}\` (otherwise the operation would write to ` +
-            `the ancestor repository, not the workspace).`,
-    };
-}
-function safeRealpath(path) {
-    try {
-        return realpathSync(path);
-    }
-    catch {
-        return path;
-    }
-}
-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 startCwd = resolveStartCwd(input.cwd ?? ctx.lastBashCwd, ctx.root, additionalDirectories);
-    // Workspace-git-boundary guard (CEO P0 #51). Fires
-    // BEFORE the permission gate so the structural boundary diagnostic
-    // is the one the operator sees. See the async path for the full
-    // rationale.
-    const boundaryBlock = enforceGitBoundary(cmd, startCwd, ctx.root);
-    if (boundaryBlock !== null) {
-        emitEvent(ctx.session, 'bash.git_boundary_escape', {
-            cmd,
-            workspaceRoot: ctx.root,
-            resolvedToplevel: boundaryBlock.resolvedToplevel ?? null,
-        });
-        recordToolResult(ctx.session, toolCallId, 'error', boundaryBlock.reason);
-        return {
-            stdout: '',
-            stderr: boundaryBlock.reason,
-            exitCode: 126,
-            nextCwd: ctx.lastBashCwd ?? ctx.root,
-            truncated: false,
-            timedOut: false,
-            cancelled: false,
-        };
-    }
-    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);
-        // #21: mirror the async-path emission so sync callers
-        // (spawnSync fallback) produce the same tenant-wide audit trail.
-        writeAuditEvent({
-            event: 'permission_denied',
-            sessionId: ctx.session.id,
-            workspaceRoot: ctx.root,
-            data: {
-                tool: 'bash',
-                source,
-                decision: decision.decision,
-                reason: decision.reason,
-                cmdPreview: cmd.slice(0, 200),
-            },
-        });
-        return {
-            stdout: '',
-            stderr: `Permission denied: ${decision.reason}`,
-            exitCode: 126,
-            nextCwd: ctx.lastBashCwd ?? ctx.root,
-            truncated: false,
-            timedOut: false,
-            cancelled: false,
-        };
-    }
-    // CEO P1 #25 — sync path observes pre-spawn cancellation too. The
-    // sync path is used by the engine-loop tool-bridge (`bashToolSync`
-    // from tool-bridge.ts:1385); we cannot mid-stream cancel that path
-    // without rewriting spawnSync, but the pre-spawn gate still gives
-    // the operator a quick-exit window between permission and shell
-    // launch.
-    if (ctx.cancellation?.isAborted === true) {
-        const reason = 'operator_aborted: bash refused before spawn';
-        emitEvent(ctx.session, 'bash.cancelled', { cmd, phase: 'pre_spawn_sync' });
-        recordToolResult(ctx.session, toolCallId, 'cancelled', reason);
-        return {
-            stdout: '',
-            stderr: reason,
-            exitCode: 130,
-            nextCwd: ctx.lastBashCwd ?? ctx.root,
-            truncated: false,
-            timedOut: false,
-            cancelled: true,
-        };
-    }
-    const timeoutMs = sanitizeTimeout(input.timeoutMs);
-    const childEnv = buildChildEnv();
-    // Pugi backlog P2 — redirect path for the sync entry. The
-    // engine loop's tool-bridge dispatches through `bashToolSync`, so
-    // the redirect contract has to be honoured here too — otherwise a
-    // model that asks for log discipline through the bash tool surface
-    // would get its stdout buffered + truncated through the legacy
-    // pipeline. `spawnSync` accepts file descriptors in `stdio` so we
-    // can hand the log fd in directly, same as the async path.
-    let redirectState = null;
-    if (input.redirect !== undefined) {
-        try {
-            const target = resolveRedirectTarget({
-                workspaceRoot: ctx.root,
-                sessionId: ctx.session.id,
-                toolCallId,
-                command: cmd,
-                override: input.redirect.path,
-            });
-            const { fd, tempPath } = openRedirectFile(target);
-            redirectState = {
-                target,
-                fd,
-                tempPath,
-                tailLines: normalizeTailLines(input.redirect.tailLines),
-            };
-        }
-        catch (error) {
-            const reason = `redirect refused: ${error.message}`;
-            recordToolResult(ctx.session, toolCallId, 'error', reason);
-            return {
-                stdout: '',
-                stderr: reason,
-                exitCode: 126,
-                nextCwd: ctx.lastBashCwd ?? ctx.root,
-                truncated: false,
-                timedOut: false,
-                cancelled: false,
-            };
-        }
-    }
-    const stdioLayout = redirectState !== null
-        ? ['ignore', redirectState.fd, redirectState.fd]
-        : ['ignore', 'pipe', 'pipe'];
-    const result = spawnSync('/bin/sh', ['-c', cmd], {
-        cwd: startCwd,
-        env: childEnv,
-        encoding: 'utf8',
-        stdio: stdioLayout,
-        timeout: timeoutMs,
-        maxBuffer: 10 * 1024 * 1024,
-    });
-    const timedOut = result.error?.code === 'ETIMEDOUT' ||
-        result.signal === 'SIGTERM';
-    const nextCwd = computeNextCwd(cmd, startCwd, ctx.root, additionalDirectories, ctx.session);
-    // Redirect short-circuit before the buffered-path artifact logic.
-    // We close our copy of the fd before rename so the inode is no
-    // longer held open by the parent process.
-    if (redirectState !== null) {
-        try {
-            closeSync(redirectState.fd);
-        }
-        catch {
-            // already closed
-        }
-        try {
-            finaliseRedirectFile(redirectState.target, redirectState.tempPath);
-        }
-        catch {
-            // best-effort
-        }
-        const redirectExitCode = timedOut ? 124 : result.status ?? 1;
-        const envelope = applyRedirect({
-            target: redirectState.target,
-            exitCode: redirectExitCode,
-            tailLines: redirectState.tailLines,
-        });
-        if (timedOut) {
-            emitEvent(ctx.session, 'bash.timeout', { cmd, timeoutMs });
-            recordToolResult(ctx.session, toolCallId, 'error', `bash timed out after ${timeoutMs}ms (redirect=${envelope.logPath})`);
-        }
-        else {
-            recordToolResult(ctx.session, toolCallId, 'success', `bash exit=${redirectExitCode} redirect=${envelope.logPath}`);
-        }
-        return {
-            stdout: envelope.stdout,
-            stderr: envelope.stderr,
-            exitCode: redirectExitCode,
-            nextCwd,
-            truncated: envelope.truncated,
-            timedOut,
-            cancelled: false,
-            logPath: envelope.logPath,
-            tail: envelope.tail,
-        };
-    }
-    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 exitCode = timedOut ? 124 : result.status ?? 1;
-    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,
-        cancelled: false,
-    };
-}
-//# sourceMappingURL=bash.js.map