@cruxy/cli 0.13.0 → 0.16.0

package/dist/render/screen-reader-renderer.js

@@ -0,0 +1,75 @@
+import { PlainRenderer } from "./plain-renderer.js";
+import { describePhase, phaseIdentity } from "./state.js";
+/**
+ * The screen-reader renderer (U.11): {@link PlainRenderer}'s linear,
+ * append-only, zero-cursor-control output — plus two things a screen reader
+ * needs that the plain path drops.
+ *
+ * 1. **Worded status.** Its theme resolves the {@link SCREEN_READER_GLYPHS}
+ *    table (via `caps.screenReader`), so every inherited code path that writes
+ *    `theme.glyph.success` prints `done` instead of `✓`, `failed` for `✗`, etc.
+ *    Nothing here special-cases it — the glyph table does the work.
+ *
+ * 2. **Announced state.** A screen reader cannot see an in-place live region, so
+ *    each state change is emitted as its own committed line (never a redraw):
+ *    a phase becomes `working: read_file src/x.ts`, a tool run brackets as
+ *    `working: …` → `done …`, and plan progress announces `step 2 of 5: title`.
+ *    Announcements are deduped by phase *identity* so token-count updates within
+ *    the same activity don't repeat a line.
+ *
+ * Everything else — text streaming, `endSegment`, `note`, `preview` — is
+ * inherited unchanged. This is the whole of screen-reader mode: no parallel
+ * path, no behavior change to the plain or TTY renderers.
+ */
+export class ScreenReaderRenderer extends PlainRenderer {
+    /** Identity of the last phase announced, so we speak each activity once. */
+    lastPhaseId = "";
+    /** Text of the last progress line announced, to avoid repeats. */
+    lastProgress = "";
+    constructor(caps, out, err) {
+        super(caps, out, err);
+    }
+    /**
+     * Announce a phase transition as a committed line. `null`, `awaiting-approval`
+     * (the prompt block is its own announcement), and `calling-tool` (announced by
+     * {@link toolLifecycle}) are silent; repeats of the same activity are deduped.
+     */
+    setPhase(phase) {
+        const id = phaseIdentity(phase);
+        if (id === this.lastPhaseId)
+            return;
+        this.lastPhaseId = id;
+        if (phase === null ||
+            phase.kind === "awaiting-approval" ||
+            phase.kind === "calling-tool") {
+            return;
+        }
+        this.note(describePhase(phase, this.theme.glyph));
+    }
+    /** Announce plan-step progress as `step i of n: title`, deduped. */
+    progress(state) {
+        if (state === null) {
+            this.lastProgress = "";
+            return;
+        }
+        const line = `step ${state.step} of ${state.of}: ${state.title}`;
+        if (line === this.lastProgress)
+            return;
+        this.lastProgress = line;
+        this.note(line);
+    }
+    /**
+     * Bracket a tool call with two committed lines — `working: label` on start,
+     * `done/failed label` on end — so a screen-reader user hears both that a call
+     * began (crucial for long ones) and how it resolved. The end note + honest
+     * duration is the inherited plain behavior; only the start line is added.
+     */
+    toolLifecycle(event) {
+        if (event.event === "start") {
+            super.toolLifecycle(event); // records the start time (silent in plain)
+            this.note(`${this.theme.glyph.running}: ${event.label}`);
+            return;
+        }
+        super.toolLifecycle(event); // commits `done/failed label (duration)`
+    }
+}

package/dist/render/types.d.ts

@@ -20,8 +20,22 @@ export interface RenderCapabilities {
     color: boolean;
     /** Cursor-control sequences are safe (`tty` and not `TERM=dumb`). */
     cursor: boolean;
-    /** Animation is welcome (`cursor` and CRUXY_NO_SPINNER unset). */
+    /** Animation is welcome (`cursor` and motion is not reduced). */
     spinner: boolean;
+    /**
+     * Motion is reduced (U.11): no spinner animation/timer, no in-place
+     * re-animation — state survives as static text, only movement stops. True
+     * under `CRUXY_NO_SPINNER` (alias) / `NO_MOTION` / `CRUXY_REDUCED_MOTION`, and
+     * implied by `screenReader`. The one axis the spinner gate keys off.
+     */
+    reducedMotion: boolean;
+    /**
+     * Screen-reader mode (U.11): plain, linear, announce-friendly output — no
+     * live-region redraws (each state change is a committed line), no spinners,
+     * status glyphs rendered as words. Opt-in via `CRUXY_SCREEN_READER` /
+     * `ACCESSIBLE`; routes rendering to the linear path regardless of `cursor`.
+     */
+    screenReader: boolean;
     /** Unicode glyphs are safe (U.1) — false under `TERM=dumb` / `CRUXY_ASCII`;
      * independent of `color`. Drives the theme's glyph table, not its stylers. */
     unicode: boolean;

package/dist/theme/resolve.d.ts

@@ -1,14 +1,15 @@
 import { type Theme, type ThemeCapabilities } from "./tokens.js";
 /**
- * Theme resolution (U.1) — the ONE place picocolors is used. The two axes are
+ * Theme resolution (U.1/U.11) — the ONE place picocolors is used. The axes are
  * fully independent by construction:
  *
  * - `color` drives the stylers only. `pc.createColors(false)` is the identity,
  *   so NO_COLOR yields zero ANSI bytes (dim/bold vanish too) — asserted in the
  *   tests.
- * - `unicode` drives the glyph table only. It never touches color: a NO_COLOR
- *   unicode terminal still prints ✓/✗ (glyphs aren't ANSI), and a colored
- *   CRUXY_ASCII terminal prints a colored `[ok]`.
+ * - the glyph table is chosen by `screenReader` (words) → else `unicode`
+ *   (✓/✗) → else ASCII (`[ok]`/`[x]`). Never touches color: a NO_COLOR unicode
+ *   terminal still prints ✓/✗ (glyphs aren't ANSI), a colored CRUXY_ASCII
+ *   terminal prints a colored `[ok]`, and a screen reader gets colorless words.
  */
 export declare function resolveTheme(caps: ThemeCapabilities): Theme;
 /**
@@ -23,10 +24,20 @@ export declare function resolveTheme(caps: ThemeCapabilities): Theme;
  * signature change.
  */
 export declare function detectUnicode(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether the user asked for screen-reader mode (U.11) — opt-in via
+ * `CRUXY_SCREEN_READER` or the ecosystem `ACCESSIBLE` flag (set-and-non-empty).
+ * Deliberately NOT inferred from a pipe: auto-wording every non-TTY stream would
+ * change existing CI/plain output. The single source of the rule, called by
+ * `render/capabilities.ts` (to fill `RenderCapabilities.screenReader`) and by
+ * the boolean-seam {@link themeForColor} surfaces (approval, plan, onboarding).
+ */
+export declare function detectScreenReader(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Build a theme for a surface that only knows a `color` boolean (the U.3
- * PromptIO, error formatting, plan/onboarding/CLI copy). Unicode is detected
- * from the environment so these surfaces still degrade on dumb terminals,
- * with no change to their public boolean signatures.
+ * PromptIO, error formatting, plan/onboarding/CLI copy). Unicode and
+ * screen-reader mode are detected from the environment so these surfaces still
+ * degrade on dumb terminals and speak words to a screen reader, with no change
+ * to their public boolean signatures.
  */
 export declare function themeForColor(color: boolean, env?: NodeJS.ProcessEnv): Theme;

package/dist/theme/resolve.js

@@ -1,19 +1,24 @@
 import pc from "picocolors";
-import { ASCII_GLYPHS, UNICODE_GLYPHS, } from "./tokens.js";
+import { ASCII_GLYPHS, SCREEN_READER_GLYPHS, UNICODE_GLYPHS, } from "./tokens.js";
 /**
- * Theme resolution (U.1) — the ONE place picocolors is used. The two axes are
+ * Theme resolution (U.1/U.11) — the ONE place picocolors is used. The axes are
  * fully independent by construction:
  *
  * - `color` drives the stylers only. `pc.createColors(false)` is the identity,
  *   so NO_COLOR yields zero ANSI bytes (dim/bold vanish too) — asserted in the
  *   tests.
- * - `unicode` drives the glyph table only. It never touches color: a NO_COLOR
- *   unicode terminal still prints ✓/✗ (glyphs aren't ANSI), and a colored
- *   CRUXY_ASCII terminal prints a colored `[ok]`.
+ * - the glyph table is chosen by `screenReader` (words) → else `unicode`
+ *   (✓/✗) → else ASCII (`[ok]`/`[x]`). Never touches color: a NO_COLOR unicode
+ *   terminal still prints ✓/✗ (glyphs aren't ANSI), a colored CRUXY_ASCII
+ *   terminal prints a colored `[ok]`, and a screen reader gets colorless words.
  */
 export function resolveTheme(caps) {
     const c = pc.createColors(caps.color);
-    const glyph = caps.unicode ? UNICODE_GLYPHS : ASCII_GLYPHS;
+    const glyph = caps.screenReader
+        ? SCREEN_READER_GLYPHS
+        : caps.unicode
+            ? UNICODE_GLYPHS
+            : ASCII_GLYPHS;
     const strong = c.bold;
     const indent = (text, level = 1) => {
         const pad = "  ".repeat(Math.max(0, level));
@@ -62,12 +67,29 @@ export function detectUnicode(env = process.env) {
         return false;
     return true;
 }
+/**
+ * Whether the user asked for screen-reader mode (U.11) — opt-in via
+ * `CRUXY_SCREEN_READER` or the ecosystem `ACCESSIBLE` flag (set-and-non-empty).
+ * Deliberately NOT inferred from a pipe: auto-wording every non-TTY stream would
+ * change existing CI/plain output. The single source of the rule, called by
+ * `render/capabilities.ts` (to fill `RenderCapabilities.screenReader`) and by
+ * the boolean-seam {@link themeForColor} surfaces (approval, plan, onboarding).
+ */
+export function detectScreenReader(env = process.env) {
+    const set = (v) => v !== undefined && v !== "";
+    return set(env.CRUXY_SCREEN_READER) || set(env.ACCESSIBLE);
+}
 /**
  * Build a theme for a surface that only knows a `color` boolean (the U.3
- * PromptIO, error formatting, plan/onboarding/CLI copy). Unicode is detected
- * from the environment so these surfaces still degrade on dumb terminals,
- * with no change to their public boolean signatures.
+ * PromptIO, error formatting, plan/onboarding/CLI copy). Unicode and
+ * screen-reader mode are detected from the environment so these surfaces still
+ * degrade on dumb terminals and speak words to a screen reader, with no change
+ * to their public boolean signatures.
  */
 export function themeForColor(color, env = process.env) {
-    return resolveTheme({ color, unicode: detectUnicode(env) });
+    return resolveTheme({
+        color,
+        unicode: detectUnicode(env),
+        screenReader: detectScreenReader(env),
+    });
 }

package/dist/theme/tokens.d.ts

@@ -90,10 +90,16 @@ export interface Theme {
     readonly color: boolean;
     readonly unicode: boolean;
 }
-/** The two axes a theme is resolved from — a structural subset of RenderCapabilities. */
+/** The axes a theme is resolved from — a structural subset of RenderCapabilities. */
 export interface ThemeCapabilities {
     color: boolean;
     unicode: boolean;
+    /**
+     * Screen-reader mode (U.11): status glyphs render as words. Optional so every
+     * existing `{color, unicode}` caller is unchanged (defaults to off). When set
+     * it takes precedence over `unicode` for the glyph table.
+     */
+    screenReader?: boolean;
 }
 /** The unicode glyph table (real terminals). */
 export declare const UNICODE_GLYPHS: ThemeGlyphs;
@@ -102,3 +108,12 @@ export declare const UNICODE_GLYPHS: ThemeGlyphs;
  * mojibake — the intentional U.1 degradation for unicode-unsafe terminals.
  */
 export declare const ASCII_GLYPHS: ThemeGlyphs;
+/**
+ * The screen-reader glyph table (U.11): the status glyphs a screen reader would
+ * otherwise announce as bare punctuation are spelled as words — `done`,
+ * `failed`, `working`, `pending` — so `✓ read_file` becomes `done read_file`.
+ * Structural glyphs stay ASCII-legible (a pointer/caret has no useful word).
+ * This is the entire "worded status" of screen-reader mode: swap the table,
+ * reuse every existing renderer/theme code path unchanged.
+ */
+export declare const SCREEN_READER_GLYPHS: ThemeGlyphs;

package/dist/theme/tokens.js

@@ -50,3 +50,30 @@ export const ASCII_GLYPHS = {
     spinnerFrames: ["-", "\\", "|", "/"],
     spinnerStatic: "~",
 };
+/**
+ * The screen-reader glyph table (U.11): the status glyphs a screen reader would
+ * otherwise announce as bare punctuation are spelled as words — `done`,
+ * `failed`, `working`, `pending` — so `✓ read_file` becomes `done read_file`.
+ * Structural glyphs stay ASCII-legible (a pointer/caret has no useful word).
+ * This is the entire "worded status" of screen-reader mode: swap the table,
+ * reuse every existing renderer/theme code path unchanged.
+ */
+export const SCREEN_READER_GLYPHS = {
+    success: "done",
+    failure: "failed",
+    pending: "pending",
+    running: "working",
+    pointer: ">",
+    caret: ">",
+    arrow: "->",
+    caretUp: "up",
+    caretDown: "down",
+    cursorBar: "",
+    bullet: "-",
+    sep: "-",
+    ellipsis: "...",
+    play: ">",
+    // Unused in the linear screen-reader path (no live region), kept legible.
+    spinnerFrames: ["working"],
+    spinnerStatic: "working",
+};

package/dist/tools/shell/exec.d.ts

@@ -0,0 +1,53 @@
+import type { ToolContext } from "../types.js";
+/**
+ * The ONE gated + sandboxed shell path (C.16 + C.19). Both `run_command` and the
+ * C.19 hook runner funnel through {@link runGatedShell}: a command reaches
+ * execution only after passing the SAME `ctx.requestApproval` gate and only
+ * through the SAME `ctx.sandbox` (or host) substrate. There is deliberately no
+ * second exec route, so a hook can never get a privileged path — proven by the
+ * fact that both callers invoke this exact function.
+ *
+ * The structured {@link ShellExecResult} carries the raw exit code (which
+ * `run_command`'s text `ToolResult` hides) so the hook runner can decide
+ * blocking pass/fail on exit 0 vs non-zero, while `run_command` maps the same
+ * result back to its byte-identical `ToolResult`.
+ */
+/** The raw outcome of executing a shell command (gate already passed). */
+export interface ShellExecResult {
+    /** The wall-clock timeout tripped and the process tree was killed. */
+    timedOut: boolean;
+    /** Numeric exit code, or null when killed / signalled / unknown. */
+    exitCode: number | null;
+    /** Terminating signal (host path only); null under the sandbox. */
+    signal: string | null;
+    /** Combined stdout+stderr, capped to `shell.maxOutputBytes`. */
+    output: string;
+    /** Output was truncated at the cap. */
+    truncated: boolean;
+    /** The host process failed to *start* (spawn error). Sandbox start failures
+     * throw a coded error instead (propagated, never returned here). */
+    spawnError?: string;
+}
+/** The result of the gate + (if allowed) execution. */
+export interface GatedShellOutcome {
+    /** The U.3 gate allowed the command. When false, nothing executed. */
+    approved: boolean;
+    /** The rejection feedback when `approved` is false. */
+    rejection?: string;
+    /** The execution result — present iff `approved`. */
+    exec?: ShellExecResult;
+}
+/**
+ * Gate `command` through `ctx.requestApproval`, then — only if allowed — execute
+ * it via the sandbox (when `ctx.sandbox` is set) or the bounded host spawn. A
+ * rejection returns `{ approved: false }` and runs nothing. A non-interactive
+ * gate throws `CRUXY_E_APPROVAL_REQUIRED` (propagated, never swallowed); a
+ * sandbox that can't run throws its coded error (fail loud, no host fallback).
+ */
+export declare function runGatedShell(command: string, ctx: ToolContext): Promise<GatedShellOutcome>;
+/**
+ * Execute an already-approved command. Substrate is chosen SOLELY by
+ * `ctx.sandbox`: present → the container (C.16), never the host; absent → the
+ * bounded host spawn. No fallback path — a sandbox that can't run throws.
+ */
+export declare function execShell(command: string, ctx: ToolContext): Promise<ShellExecResult>;

package/dist/tools/shell/exec.js

@@ -0,0 +1,128 @@
+import { spawn } from "node:child_process";
+/**
+ * Gate `command` through `ctx.requestApproval`, then — only if allowed — execute
+ * it via the sandbox (when `ctx.sandbox` is set) or the bounded host spawn. A
+ * rejection returns `{ approved: false }` and runs nothing. A non-interactive
+ * gate throws `CRUXY_E_APPROVAL_REQUIRED` (propagated, never swallowed); a
+ * sandbox that can't run throws its coded error (fail loud, no host fallback).
+ */
+export async function runGatedShell(command, ctx) {
+    const decision = await ctx.requestApproval({ kind: "shell", command });
+    if (!decision.allow) {
+        return { approved: false, rejection: decision.feedback };
+    }
+    return { approved: true, exec: await execShell(command, ctx) };
+}
+/**
+ * Execute an already-approved command. Substrate is chosen SOLELY by
+ * `ctx.sandbox`: present → the container (C.16), never the host; absent → the
+ * bounded host spawn. No fallback path — a sandbox that can't run throws.
+ */
+export function execShell(command, ctx) {
+    return ctx.sandbox ? runSandboxed(command, ctx) : runBounded(command, ctx);
+}
+/** Run in the sandbox and normalize its neutral ExecResult (start failures
+ * throw coded errors from `sandbox.exec` and propagate — never caught here). */
+async function runSandboxed(command, ctx) {
+    const { timeoutMs, maxOutputBytes } = ctx.config.shell;
+    const result = await ctx.sandbox.exec(command, {
+        cwd: ctx.cwd,
+        timeoutMs,
+        maxOutputBytes,
+        capture: "head",
+    });
+    return {
+        timedOut: result.timedOut,
+        exitCode: result.exitCode,
+        signal: null,
+        output: result.output,
+        truncated: result.outputTruncated,
+    };
+}
+/** Spawn the command on the host, capture bounded output, enforce the timeout. */
+function runBounded(command, ctx) {
+    const { timeoutMs, maxOutputBytes } = ctx.config.shell;
+    return new Promise((resolve) => {
+        // `detached` makes the child its own process-group leader so the whole tree
+        // (the shell plus anything it spawns) can be killed on timeout.
+        const child = spawn(command, { shell: true, cwd: ctx.cwd, detached: true });
+        const chunks = [];
+        let captured = 0;
+        let truncated = false;
+        const capture = (buf) => {
+            if (truncated)
+                return;
+            const room = maxOutputBytes - captured;
+            if (buf.length <= room) {
+                chunks.push(buf);
+                captured += buf.length;
+            }
+            else {
+                if (room > 0) {
+                    chunks.push(buf.subarray(0, room));
+                    captured += room;
+                }
+                truncated = true;
+            }
+        };
+        child.stdout?.on("data", capture);
+        child.stderr?.on("data", capture);
+        // A single guard so the timeout-kill and the natural close can't both fire.
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            killTree(child.pid);
+            resolve({
+                timedOut: true,
+                exitCode: null,
+                signal: null,
+                output: "",
+                truncated,
+            });
+        }, timeoutMs);
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                timedOut: false,
+                exitCode: null,
+                signal: null,
+                output: "",
+                truncated: false,
+                spawnError: err.message,
+            });
+        });
+        child.on("close", (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                timedOut: false,
+                exitCode: code,
+                signal: signal ?? null,
+                output: Buffer.concat(chunks).toString("utf8"),
+                truncated,
+            });
+        });
+    });
+}
+/**
+ * Kill the command's entire process group. POSIX-specific (negative pid targets
+ * the group); fine on our darwin/linux targets. Swallows errors — the process
+ * may already be gone.
+ */
+function killTree(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        // Already exited, or no group — nothing to kill.
+    }
+}

package/dist/tools/shell/run-command.d.ts

@@ -4,6 +4,10 @@ import type { Tool } from "../types.js";
  * Run an arbitrary shell command in the project root. The highest-risk tool we
  * ship: it is gated on `ctx.approve` (a denial runs nothing) and bounded by a
  * timeout that kills the whole process tree plus a cap on captured output.
+ *
+ * Gate + execution live in the shared {@link runGatedShell} (also used by the
+ * C.19 hook runner — the single, un-bypassable shell path); this tool only maps
+ * the structured result back onto its `ToolResult` framing.
  */
 export declare const runCommandTool: Tool<z.ZodObject<{
     command: z.ZodString;

package/dist/tools/shell/run-command.js

@@ -1,9 +1,13 @@
-import { spawn } from "node:child_process";
 import { z } from "zod";
+import { runGatedShell } from "./exec.js";
 /**
  * Run an arbitrary shell command in the project root. The highest-risk tool we
  * ship: it is gated on `ctx.approve` (a denial runs nothing) and bounded by a
  * timeout that kills the whole process tree plus a cap on captured output.
+ *
+ * Gate + execution live in the shared {@link runGatedShell} (also used by the
+ * C.19 hook runner — the single, un-bypassable shell path); this tool only maps
+ * the structured result back onto its `ToolResult` framing.
  */
 export const runCommandTool = {
     name: "run_command",
@@ -14,129 +18,35 @@ export const runCommandTool = {
             .describe("The shell command to run (executed via the system shell)."),
     }),
     async execute(input, ctx) {
-        // Approve BEFORE anything runs; a denial executes nothing. A thrown
-        // CRUXY_E_APPROVAL_REQUIRED (non-interactive) propagates — do not catch.
-        const decision = await ctx.requestApproval({
-            kind: "shell",
-            command: input.command,
-        });
-        if (!decision.allow) {
+        // A thrown CRUXY_E_APPROVAL_REQUIRED (non-interactive) / sandbox coded error
+        // propagates from runGatedShell — do not catch (fail loud).
+        const outcome = await runGatedShell(input.command, ctx);
+        if (!outcome.approved) {
             return {
                 ok: false,
-                error: decision.feedback ?? "command denied by the user",
+                error: outcome.rejection ?? "command denied by the user",
             };
         }
-        // Substrate is chosen SOLELY by ctx.sandbox: present → run in the box (C.16),
-        // never on the host; absent → host, unchanged. There is no fallback path — a
-        // sandbox that can't run throws a coded error (see runSandboxed) rather than
-        // silently reaching runBounded.
-        return ctx.sandbox
-            ? runSandboxed(input.command, ctx)
-            : runBounded(input.command, ctx);
+        return mapExecResult(outcome.exec, ctx);
     },
 };
 /**
- * Run inside the sandbox and map the neutral ExecResult onto the IDENTICAL
- * ToolResult the host path produces — same "exit code N" framing, same
- * truncation note, same timeout message — so the tool is substrate-agnostic.
- * A container-start / image failure throws a coded CruxyError from
- * `sandbox.exec` and propagates; we deliberately do not catch it (fail loud).
+ * Map a {@link ShellExecResult} onto the tool's `ToolResult` — the same "exit
+ * code N" framing, truncation note, and timeout / spawn-error messages as
+ * before the shared-path refactor. `exitCode ?? signal ?? "unknown"` reproduces
+ * both the sandbox (`exitCode ?? "unknown"`, signal always null) and host
+ * (`code ?? signal ?? "unknown"`) framings from the original tool.
  */
-function runSandboxed(command, ctx) {
+function mapExecResult(r, ctx) {
     const { timeoutMs, maxOutputBytes } = ctx.config.shell;
-    return ctx
-        .sandbox.exec(command, {
-        cwd: ctx.cwd,
-        timeoutMs,
-        maxOutputBytes,
-        capture: "head",
-    })
-        .then((result) => {
-        if (result.timedOut) {
-            return { ok: false, error: `timed out after ${timeoutMs}ms` };
-        }
-        const exit = result.exitCode ?? "unknown";
-        let output = `exit code ${exit}\n${result.output}`;
-        if (result.outputTruncated) {
-            output += `\n… [output truncated at ${maxOutputBytes} bytes]`;
-        }
-        return { ok: true, output };
-    });
-}
-/** Spawn the command, capture bounded output, and enforce the timeout. */
-function runBounded(command, ctx) {
-    const { timeoutMs, maxOutputBytes } = ctx.config.shell;
-    return new Promise((resolve) => {
-        // `detached` makes the child its own process-group leader so the whole tree
-        // (the shell plus anything it spawns) can be killed on timeout.
-        const child = spawn(command, {
-            shell: true,
-            cwd: ctx.cwd,
-            detached: true,
-        });
-        const chunks = [];
-        let captured = 0;
-        let truncated = false;
-        const capture = (buf) => {
-            if (truncated)
-                return;
-            const room = maxOutputBytes - captured;
-            if (buf.length <= room) {
-                chunks.push(buf);
-                captured += buf.length;
-            }
-            else {
-                if (room > 0) {
-                    chunks.push(buf.subarray(0, room));
-                    captured += room;
-                }
-                truncated = true;
-            }
-        };
-        child.stdout?.on("data", capture);
-        child.stderr?.on("data", capture);
-        // A single guard so the timeout-kill and the natural close can't both fire.
-        let settled = false;
-        const timer = setTimeout(() => {
-            if (settled)
-                return;
-            settled = true;
-            killTree(child.pid);
-            resolve({ ok: false, error: `timed out after ${timeoutMs}ms` });
-        }, timeoutMs);
-        child.on("error", (err) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            resolve({ ok: false, error: err.message });
-        });
-        child.on("close", (code, signal) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            const exit = code ?? signal ?? "unknown";
-            let output = `exit code ${exit}\n${Buffer.concat(chunks).toString("utf8")}`;
-            if (truncated) {
-                output += `\n… [output truncated at ${maxOutputBytes} bytes]`;
-            }
-            resolve({ ok: true, output });
-        });
-    });
-}
-/**
- * Kill the command's entire process group. POSIX-specific (negative pid targets
- * the group); fine on our darwin/linux targets. Swallows errors — the process
- * may already be gone.
- */
-function killTree(pid) {
-    if (pid === undefined)
-        return;
-    try {
-        process.kill(-pid, "SIGKILL");
-    }
-    catch {
-        // Already exited, or no group — nothing to kill.
+    if (r.timedOut)
+        return { ok: false, error: `timed out after ${timeoutMs}ms` };
+    if (r.spawnError !== undefined)
+        return { ok: false, error: r.spawnError };
+    const exit = r.exitCode ?? r.signal ?? "unknown";
+    let output = `exit code ${exit}\n${r.output}`;
+    if (r.truncated) {
+        output += `\n… [output truncated at ${maxOutputBytes} bytes]`;
     }
+    return { ok: true, output };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.13.0",
+  "version": "0.16.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {