@cruxy/cli 0.12.0 → 0.14.0

package/dist/approval/prompt.js

@@ -37,16 +37,30 @@ export async function promptForApproval(request, io) {
 export function render(request, color) {
     const t = themeForColor(color);
     const destructive = request.tier === "destructive";
-    // The risk mark carries meaning by shape (`!` vs `?`), not by color alone —
-    // so it survives NO_COLOR (U.1 accessibility groundwork).
+    // Risk survives all three degradations (U.11): the mark carries it by *shape*
+    // (`!` vs `?`) for NO_COLOR, and the label carries it by *word*
+    // (`(destructive)` / `(mutate)` / `(read)`) — never by hue alone, and legible
+    // to a screen reader that would otherwise read `!` as "exclamation mark".
     const mark = destructive ? t.danger(t.strong("!")) : t.warning("?");
-    const label = destructive ? t.danger(t.strong(" (destructive)")) : "";
+    const label = tierLabel(request.tier, t);
     const lines = [];
     lines.push(`${mark} cruxy wants to ${t.strong(request.summary)}${label}`);
     lines.push(detail(request, t));
     lines.push(choices(request.scope, t));
     return lines.filter((l) => l !== "").join("\n") + " ";
 }
+/** The worded risk tag, colored by tier — always present, so meaning never
+ * rides on the `!`/`?` shape or its color alone. */
+function tierLabel(tier, t) {
+    switch (tier) {
+        case "destructive":
+            return t.danger(t.strong(" (destructive)"));
+        case "mutate":
+            return t.warning(" (mutate)");
+        case "read":
+            return t.muted(" (read)");
+    }
+}
 /** The action detail: a diff for file actions, the command + cwd for shell/test. */
 function detail(request, t) {
     if (request.action.kind === "shell" || request.action.kind === "test") {

package/dist/cli/commands/run.js

@@ -5,6 +5,7 @@ import { authMissingKey, shouldUseColor, usageError, } from "../../errors/index.
 import { createRenderer } from "../../render/index.js";
 import { themeForColor } from "../../theme/index.js";
 import { CheckpointService } from "../../checkpoint/index.js";
+import { SandboxService } from "../../sandbox/index.js";
 import { runInteractive } from "../repl.js";
 import { buildAgentSession } from "../session-factory.js";
 import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
@@ -13,6 +14,7 @@ export function runCommand() {
         .description("run cruxy on a prompt (one-shot), or with no prompt for an interactive session")
         .argument("[prompt...]", "the task for cruxy to perform (omit for interactive)")
         .option("--plan", "plan mode: propose a step-by-step plan for approval before executing")
+        .option("--sandbox", "run shell + test commands inside an isolated container (fails loud if no runtime)")
         .action(async (promptParts, opts) => {
         const prompt = promptParts.join(" ").trim();
         const t = themeForColor(shouldUseColor(process.stdout));
@@ -61,7 +63,23 @@ export function runCommand() {
         const checkpoints = config.checkpoint.enabled
             ? new CheckpointService({ root: process.cwd(), config })
             : undefined;
-        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode, renderer, checkpoints);
+        // Sandbox (C.16): opt-in via --sandbox or sandbox.enabled. Resolving the
+        // service probes the runtime and THROWS CRUXY_E_SANDBOX_UNAVAILABLE if it
+        // is missing — fail loud here, before the agent starts, rather than
+        // silently running un-sandboxed. When off, ctx.sandbox stays undefined and
+        // execution runs on the host, unchanged.
+        const sandboxEnabled = opts.sandbox ?? config.sandbox.enabled;
+        const sandbox = sandboxEnabled
+            ? await SandboxService.create({
+                config,
+                cwd: process.cwd(),
+                reporter: renderer,
+            })
+            : undefined;
+        if (sandbox) {
+            logger.info(t.muted(`sandbox: ${sandbox.runtimeName} (network ${config.sandbox.network})`));
+        }
+        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode, renderer, checkpoints, sandbox);
         if (interactive) {
             await runInteractive(session, undefined, renderer, checkpoints);
             return;

package/dist/cli/session-factory.d.ts

@@ -1,6 +1,7 @@
 import type { CruxyConfig } from "../config/index.js";
 import type { ApprovalDecision } from "../approval/index.js";
 import type { CheckpointService } from "../checkpoint/index.js";
+import type { SandboxService } from "../sandbox/index.js";
 import type { StreamRenderer } from "../render/index.js";
 import { type ApproveAction } from "../tools/index.js";
 import { Session } from "../agent/index.js";
@@ -23,4 +24,4 @@ export declare function withCheckpointGate(requestApproval: (action: ApproveActi
  * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
  * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
  */
-export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean, renderer?: StreamRenderer, checkpoints?: CheckpointService): Session;
+export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean, renderer?: StreamRenderer, checkpoints?: CheckpointService, sandbox?: SandboxService): Session;

package/dist/cli/session-factory.js

@@ -87,7 +87,7 @@ export function withCheckpointGate(requestApproval, checkpoints, cwd) {
  * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
  * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
  */
-export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false, renderer, checkpoints) {
+export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false, renderer, checkpoints, sandbox) {
     const provider = createProvider({
         provider: config.model.provider,
         apiKey,
@@ -120,6 +120,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
         git,
         projectInstructions,
         renderer,
+        sandbox,
         makeChildApproval: () => gate(new ApprovalService({ cwd, interactive: ttyInteractive, io })),
     });
     if (config.subagent.maxDepth > 0) {
@@ -136,7 +137,13 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             policy: planPolicy,
             io,
         });
-        const ctx = { cwd, config, logger, requestApproval: gate(approval) };
+        const ctx = {
+            cwd,
+            config,
+            logger,
+            requestApproval: gate(approval),
+            sandbox,
+        };
         const planRunner = ({ messages, projectInstructions, renderer: turnRenderer, }) => runPlanSession({
             provider,
             config,
@@ -166,7 +173,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
         interactive: ttyInteractive,
         io,
     });
-    const ctx = { cwd, config, logger, requestApproval: gate(approval) };
+    const ctx = { cwd, config, logger, requestApproval: gate(approval), sandbox };
     return new Session({
         provider,
         registry: execRegistry,

package/dist/components/fuzzy.js

@@ -106,7 +106,9 @@ export async function fuzzyFind(items, opts, io = defaultComponentIO()) {
             lines.push(t.heading(opts.title));
         lines.push(`${t.accent(g.caret)} ${query}${t.muted(g.cursorBar)}`);
         if (ranked.length === 0) {
-            lines.push(t.muted("  no results — backspace to widen"));
+            // No dead-end: the only escapes (backspace, esc) stay advertised even
+            // when nothing matches — the user is never stranded with no visible exit.
+            lines.push(t.muted("  no results — backspace to widen · esc cancel"));
         }
         else {
             // Keep the highlighted row inside the viewport.
@@ -122,6 +124,10 @@ export async function fuzzyFind(items, opts, io = defaultComponentIO()) {
             if (hidden > 0)
                 lines.push(t.muted(`  ${g.ellipsis} ${hidden} more`));
         }
+        // Persistent key hint (U.11 keyboard-completeness): every operable key is
+        // advertised, mirroring selectList — type filters, arrows move, enter
+        // selects, esc cancels. Present in both the results and no-results states.
+        lines.push(t.muted(`  type to filter ${g.sep} ${g.caretUp}/${g.caretDown} move ${g.sep} enter select ${g.sep} esc cancel`));
         frame.render(lines);
     };
     io.keys.begin();

package/dist/config/schema.d.ts

@@ -283,6 +283,62 @@ export declare const SubagentConfigSchema: z.ZodObject<{
         timeoutMs?: number | undefined;
     } | undefined;
 }>;
+/**
+ * Sandbox / container execution (C.16): defense-in-depth beneath the U.3 gate.
+ * When enabled, `run_command` and `run_tests` execute inside an isolated,
+ * network-denied, resource-capped, non-root container with only the project
+ * workdir mounted — never on the host directly. OFF by default (a container
+ * runtime isn't universal); turning it on is a hard promise, so if the runtime
+ * is missing execution FAILS LOUD rather than silently falling back to the host.
+ */
+export declare const SandboxConfigSchema: z.ZodObject<{
+    /** Master switch. When true, shell + test commands run in the sandbox. */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Base image the container runs. Must ship a POSIX `sh`. Pin by digest
+     * (`name@sha256:…`) where possible; cruxy never builds or substitutes one.
+     */
+    image: z.ZodDefault<z.ZodString>;
+    /**
+     * Egress policy. `none` denies all network (default deny); `host-loopback`
+     * permits reaching services on the host; `full` allows outbound. Anything
+     * other than `none` is a deliberate widening the user must opt into.
+     */
+    network: z.ZodDefault<z.ZodEnum<["none", "host-loopback", "full"]>>;
+    /** Memory cap (docker `--memory` syntax, e.g. `512m`, `2g`). */
+    memory: z.ZodDefault<z.ZodString>;
+    /** Process/thread cap (`--pids-limit`) — a fork-bomb guard. */
+    pids: z.ZodDefault<z.ZodNumber>;
+    /** CPU cap (docker `--cpus`, fractional allowed). */
+    cpus: z.ZodDefault<z.ZodNumber>;
+    /** Wall-clock timeout in ms; falls back to `shell.timeoutMs` when unset. */
+    timeout: z.ZodOptional<z.ZodNumber>;
+    /**
+     * Extra bind mounts beyond the workdir + tmp, each `src:dst[:ro|:rw]`.
+     * Explicit by construction — the default exposes ONLY the workdir. The
+     * docker socket and the cruxy home are rejected here (see policy.ts).
+     */
+    mounts: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    image: string;
+    enabled: boolean;
+    memory: string;
+    network: "none" | "host-loopback" | "full";
+    pids: number;
+    cpus: number;
+    mounts: string[];
+    timeout?: number | undefined;
+}, {
+    image?: string | undefined;
+    enabled?: boolean | undefined;
+    memory?: string | undefined;
+    network?: "none" | "host-loopback" | "full" | undefined;
+    pids?: number | undefined;
+    cpus?: number | undefined;
+    timeout?: number | undefined;
+    mounts?: string[] | undefined;
+}>;
+export type SandboxConfig = z.infer<typeof SandboxConfigSchema>;
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export declare const McpServerSchema: z.ZodObject<{
     command: z.ZodOptional<z.ZodString>;
@@ -551,6 +607,53 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         command?: string | undefined;
         captureBytes?: number | undefined;
     }>>;
+    sandbox: z.ZodDefault<z.ZodObject<{
+        /** Master switch. When true, shell + test commands run in the sandbox. */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * Base image the container runs. Must ship a POSIX `sh`. Pin by digest
+         * (`name@sha256:…`) where possible; cruxy never builds or substitutes one.
+         */
+        image: z.ZodDefault<z.ZodString>;
+        /**
+         * Egress policy. `none` denies all network (default deny); `host-loopback`
+         * permits reaching services on the host; `full` allows outbound. Anything
+         * other than `none` is a deliberate widening the user must opt into.
+         */
+        network: z.ZodDefault<z.ZodEnum<["none", "host-loopback", "full"]>>;
+        /** Memory cap (docker `--memory` syntax, e.g. `512m`, `2g`). */
+        memory: z.ZodDefault<z.ZodString>;
+        /** Process/thread cap (`--pids-limit`) — a fork-bomb guard. */
+        pids: z.ZodDefault<z.ZodNumber>;
+        /** CPU cap (docker `--cpus`, fractional allowed). */
+        cpus: z.ZodDefault<z.ZodNumber>;
+        /** Wall-clock timeout in ms; falls back to `shell.timeoutMs` when unset. */
+        timeout: z.ZodOptional<z.ZodNumber>;
+        /**
+         * Extra bind mounts beyond the workdir + tmp, each `src:dst[:ro|:rw]`.
+         * Explicit by construction — the default exposes ONLY the workdir. The
+         * docker socket and the cruxy home are rejected here (see policy.ts).
+         */
+        mounts: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        image: string;
+        enabled: boolean;
+        memory: string;
+        network: "none" | "host-loopback" | "full";
+        pids: number;
+        cpus: number;
+        mounts: string[];
+        timeout?: number | undefined;
+    }, {
+        image?: string | undefined;
+        enabled?: boolean | undefined;
+        memory?: string | undefined;
+        network?: "none" | "host-loopback" | "full" | undefined;
+        pids?: number | undefined;
+        cpus?: number | undefined;
+        timeout?: number | undefined;
+        mounts?: string[] | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         command: z.ZodOptional<z.ZodString>;
         args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -634,6 +737,16 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         captureBytes: number;
         command?: string | undefined;
     };
+    sandbox: {
+        image: string;
+        enabled: boolean;
+        memory: string;
+        network: "none" | "host-loopback" | "full";
+        pids: number;
+        cpus: number;
+        mounts: string[];
+        timeout?: number | undefined;
+    };
     mcpServers: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;
@@ -709,6 +822,16 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         command?: string | undefined;
         captureBytes?: number | undefined;
     } | undefined;
+    sandbox?: {
+        image?: string | undefined;
+        enabled?: boolean | undefined;
+        memory?: string | undefined;
+        network?: "none" | "host-loopback" | "full" | undefined;
+        pids?: number | undefined;
+        cpus?: number | undefined;
+        timeout?: number | undefined;
+        mounts?: string[] | undefined;
+    } | undefined;
     mcpServers?: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;

package/dist/config/schema.js

@@ -194,6 +194,45 @@ export const SubagentConfigSchema = z
         .default({}),
 })
     .strict();
+/**
+ * Sandbox / container execution (C.16): defense-in-depth beneath the U.3 gate.
+ * When enabled, `run_command` and `run_tests` execute inside an isolated,
+ * network-denied, resource-capped, non-root container with only the project
+ * workdir mounted — never on the host directly. OFF by default (a container
+ * runtime isn't universal); turning it on is a hard promise, so if the runtime
+ * is missing execution FAILS LOUD rather than silently falling back to the host.
+ */
+export const SandboxConfigSchema = z
+    .object({
+    /** Master switch. When true, shell + test commands run in the sandbox. */
+    enabled: z.boolean().default(false),
+    /**
+     * Base image the container runs. Must ship a POSIX `sh`. Pin by digest
+     * (`name@sha256:…`) where possible; cruxy never builds or substitutes one.
+     */
+    image: z.string().min(1).default("node:20-bookworm-slim"),
+    /**
+     * Egress policy. `none` denies all network (default deny); `host-loopback`
+     * permits reaching services on the host; `full` allows outbound. Anything
+     * other than `none` is a deliberate widening the user must opt into.
+     */
+    network: z.enum(["none", "host-loopback", "full"]).default("none"),
+    /** Memory cap (docker `--memory` syntax, e.g. `512m`, `2g`). */
+    memory: z.string().min(1).default("512m"),
+    /** Process/thread cap (`--pids-limit`) — a fork-bomb guard. */
+    pids: z.number().int().positive().default(512),
+    /** CPU cap (docker `--cpus`, fractional allowed). */
+    cpus: z.number().positive().default(1),
+    /** Wall-clock timeout in ms; falls back to `shell.timeoutMs` when unset. */
+    timeout: z.number().int().positive().optional(),
+    /**
+     * Extra bind mounts beyond the workdir + tmp, each `src:dst[:ro|:rw]`.
+     * Explicit by construction — the default exposes ONLY the workdir. The
+     * docker socket and the cruxy home are rejected here (see policy.ts).
+     */
+    mounts: z.array(z.string().min(1)).default([]),
+})
+    .strict();
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export const McpServerSchema = z
     .object({
@@ -216,6 +255,7 @@ export const CruxyConfigSchema = z
     checkpoint: CheckpointConfigSchema.default({}),
     subagent: SubagentConfigSchema.default({}),
     test: TestConfigSchema.default({}),
+    sandbox: SandboxConfigSchema.default({}),
     mcpServers: z.record(z.string(), McpServerSchema).default({}),
     logLevel: z.enum(LOG_LEVELS).default("info"),
 })

package/dist/errors/constructors.d.ts

@@ -25,6 +25,27 @@ export declare function permissionDenied(path: string, underlying?: unknown): Cr
 export declare function indexEmbedderUnavailable(underlying?: unknown): CruxyError;
 export declare function indexStoreUnavailable(underlying?: unknown): CruxyError;
 export declare function indexFailed(underlying?: unknown): CruxyError;
+/**
+ * Sandboxing was requested (`--sandbox` / `sandbox.enabled`) but no container
+ * runtime is available — docker isn't installed, or its daemon isn't running.
+ * THE CRITICAL RULE: this is fatal. A user who turned on the sandbox must never
+ * be silently dropped back onto un-sandboxed host execution, so we fail loud
+ * here rather than run the command anyway.
+ */
+export declare function sandboxUnavailable(runtime?: string, underlying?: unknown): CruxyError;
+/**
+ * The pinned sandbox base image could not be made available (the first-run
+ * pull failed, or the image does not exist). Fatal — without the image there
+ * is nothing to execute inside, and we never substitute another image.
+ */
+export declare function sandboxImage(image: string, underlying?: unknown): CruxyError;
+/**
+ * The container itself failed to start or run (a docker-level failure — bad
+ * flags, daemon error, `docker run` exit 125), as opposed to the command
+ * inside exiting non-zero (which is an ordinary result). Fatal: a sandbox that
+ * can't launch is never papered over with a host run.
+ */
+export declare function sandboxExec(underlying?: unknown): CruxyError;
 /**
  * A side-effecting action needs approval but cruxy can't ask (non-interactive,
  * no policy). Default-deny — never auto-approve. A distinct exit code (10) so CI

package/dist/errors/constructors.js

@@ -224,6 +224,64 @@ export function indexFailed(underlying) {
         underlying,
     });
 }
+// ── sandbox (exit 12) ─────────────────────────────────────────────────────────
+/**
+ * Sandboxing was requested (`--sandbox` / `sandbox.enabled`) but no container
+ * runtime is available — docker isn't installed, or its daemon isn't running.
+ * THE CRITICAL RULE: this is fatal. A user who turned on the sandbox must never
+ * be silently dropped back onto un-sandboxed host execution, so we fail loud
+ * here rather than run the command anyway.
+ */
+export function sandboxUnavailable(runtime = "docker", underlying) {
+    return new CruxyError({
+        code: ErrorCode.SandboxUnavailable,
+        title: `sandbox is enabled but the ${runtime} runtime is unavailable`,
+        cause: messageOf(underlying) ??
+            `${runtime} is not installed or its daemon is not reachable`,
+        nextSteps: [
+            `install ${runtime} and make sure its daemon is running`,
+            "or disable the sandbox: `cruxy config set sandbox.enabled false` (or drop --sandbox)",
+        ],
+        underlying,
+        meta: { runtime },
+    });
+}
+/**
+ * The pinned sandbox base image could not be made available (the first-run
+ * pull failed, or the image does not exist). Fatal — without the image there
+ * is nothing to execute inside, and we never substitute another image.
+ */
+export function sandboxImage(image, underlying) {
+    return new CruxyError({
+        code: ErrorCode.SandboxImage,
+        title: `could not pull the sandbox image "${image}"`,
+        cause: messageOf(underlying),
+        nextSteps: [
+            "check the image name/tag and your network access to the registry",
+            'set a reachable image, e.g. `cruxy config set sandbox.image "node:20-bookworm-slim"`',
+        ],
+        underlying,
+        meta: { image },
+    });
+}
+/**
+ * The container itself failed to start or run (a docker-level failure — bad
+ * flags, daemon error, `docker run` exit 125), as opposed to the command
+ * inside exiting non-zero (which is an ordinary result). Fatal: a sandbox that
+ * can't launch is never papered over with a host run.
+ */
+export function sandboxExec(underlying) {
+    return new CruxyError({
+        code: ErrorCode.SandboxExec,
+        title: "the sandbox container failed to start",
+        cause: messageOf(underlying),
+        nextSteps: [
+            "re-run with --verbose for the underlying docker error",
+            "verify the docker daemon is healthy (`docker info`)",
+        ],
+        underlying,
+    });
+}
 // ── approval (exit 10) ────────────────────────────────────────────────────────
 /**
  * A side-effecting action needs approval but cruxy can't ask (non-interactive,

package/dist/errors/types.d.ts

@@ -52,6 +52,11 @@ export declare const ErrorCode: {
     readonly TestCommandNotFound: "CRUXY_E_TEST_COMMAND_NOT_FOUND";
     /** Carried inside a run_tests result (informational) — never fatal by itself. */
     readonly TestIterationLimit: "CRUXY_E_TEST_ITERATION_LIMIT";
+    /** Sandbox was enabled but no container runtime is available — fail loud,
+     * NEVER fall back to un-sandboxed host execution. */
+    readonly SandboxUnavailable: "CRUXY_E_SANDBOX_UNAVAILABLE";
+    readonly SandboxImage: "CRUXY_E_SANDBOX_IMAGE";
+    readonly SandboxExec: "CRUXY_E_SANDBOX_EXEC";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** The process exit code for an error code (defaults to 1 for safety). */

package/dist/errors/types.js

@@ -64,6 +64,12 @@ export const ErrorCode = {
     TestCommandNotFound: "CRUXY_E_TEST_COMMAND_NOT_FOUND",
     /** Carried inside a run_tests result (informational) — never fatal by itself. */
     TestIterationLimit: "CRUXY_E_TEST_ITERATION_LIMIT",
+    // sandbox (exit 12)
+    /** Sandbox was enabled but no container runtime is available — fail loud,
+     * NEVER fall back to un-sandboxed host execution. */
+    SandboxUnavailable: "CRUXY_E_SANDBOX_UNAVAILABLE",
+    SandboxImage: "CRUXY_E_SANDBOX_IMAGE",
+    SandboxExec: "CRUXY_E_SANDBOX_EXEC",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -112,6 +118,11 @@ const EXIT_CODES = {
     // surfaces inside a run_tests result and is never fatal by itself.
     [ErrorCode.TestCommandNotFound]: 2,
     [ErrorCode.TestIterationLimit]: 11,
+    // A requested sandbox that can't be honored is fatal (fail loud, no host
+    // fallback) — its own exit code so CI/scripts can tell it apart.
+    [ErrorCode.SandboxUnavailable]: 12,
+    [ErrorCode.SandboxImage]: 12,
+    [ErrorCode.SandboxExec]: 12,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

package/dist/onboarding/steps.js

@@ -93,7 +93,10 @@ export async function firstWinStep(io, deps) {
     io.write(`\nRun a quick demo now — let cruxy summarize this repo? ${col.muted("[Y/n]")} `);
     const key = (await io.readKey()).toLowerCase();
     io.write("\n");
-    if (key === "n")
+    // Decline on an explicit `n`, and treat Ctrl-C / EOF / escape (readKey → "")
+    // as a clean cancel rather than "proceed": a cancel must never launch a task.
+    // Enter (readKey → "\n") keeps the `[Y/n]` default and runs the demo.
+    if (key === "n" || key === "")
         return { status: "skipped" };
     await deps.runTask(FIRST_WIN_PROMPT);
     return { status: "ok" };

package/dist/render/capabilities.d.ts

@@ -1,4 +1,11 @@
 import type { RenderCapabilities, RenderStream } from "./types.js";
+/**
+ * Reduced-motion (U.11) — the ecosystem `NO_MOTION` signal, the explicit cruxy
+ * knob `CRUXY_REDUCED_MOTION`, and `CRUXY_NO_SPINNER` kept as an alias flowing
+ * through this one axis. A screen reader implies it (no live region to animate).
+ * The single source of the spinner gate.
+ */
+export declare function detectReducedMotion(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Probe the environment once and reduce it to {@link RenderCapabilities}. Pure
  * given its inputs (stream + env are injectable), so every row of the
@@ -6,7 +13,8 @@ import type { RenderCapabilities, RenderStream } from "./types.js";
  *
  * Color reuses {@link shouldUseColor} (NO_COLOR / FORCE_COLOR / TTY) with one
  * refinement: `TERM=dumb` terminals get no color even though they are TTYs.
- * Cursor control and color are independent axes — a NO_COLOR terminal still
- * supports in-place status updates; a dumb terminal supports neither.
+ * The axes are independent (U.1/U.11): a NO_COLOR terminal still supports
+ * in-place status updates; a dumb terminal supports neither; reduced motion and
+ * screen-reader mode compose orthogonally with color and unicode.
  */
 export declare function detectCapabilities(stream?: RenderStream, env?: NodeJS.ProcessEnv): RenderCapabilities;

package/dist/render/capabilities.js

@@ -1,5 +1,21 @@
 import { shouldUseColor } from "../errors/index.js";
-import { detectUnicode } from "../theme/index.js";
+import { detectScreenReader, detectUnicode } from "../theme/index.js";
+/** Set-and-non-empty (the NO_COLOR convention): any non-empty value counts. */
+function isSet(value) {
+    return value !== undefined && value !== "";
+}
+/**
+ * Reduced-motion (U.11) — the ecosystem `NO_MOTION` signal, the explicit cruxy
+ * knob `CRUXY_REDUCED_MOTION`, and `CRUXY_NO_SPINNER` kept as an alias flowing
+ * through this one axis. A screen reader implies it (no live region to animate).
+ * The single source of the spinner gate.
+ */
+export function detectReducedMotion(env = process.env) {
+    return (isSet(env.NO_MOTION) ||
+        isSet(env.CRUXY_REDUCED_MOTION) ||
+        isSet(env.CRUXY_NO_SPINNER) ||
+        detectScreenReader(env));
+}
 /**
  * Probe the environment once and reduce it to {@link RenderCapabilities}. Pure
  * given its inputs (stream + env are injectable), so every row of the
@@ -7,20 +23,24 @@ import { detectUnicode } from "../theme/index.js";
  *
  * Color reuses {@link shouldUseColor} (NO_COLOR / FORCE_COLOR / TTY) with one
  * refinement: `TERM=dumb` terminals get no color even though they are TTYs.
- * Cursor control and color are independent axes — a NO_COLOR terminal still
- * supports in-place status updates; a dumb terminal supports neither.
+ * The axes are independent (U.1/U.11): a NO_COLOR terminal still supports
+ * in-place status updates; a dumb terminal supports neither; reduced motion and
+ * screen-reader mode compose orthogonally with color and unicode.
  */
 export function detectCapabilities(stream = process.stdout, env = process.env) {
     const tty = Boolean(stream.isTTY);
     const dumb = env.TERM === "dumb";
     const cursor = tty && !dumb;
+    const reducedMotion = detectReducedMotion(env);
     return {
         tty,
         color: shouldUseColor(stream, env) && !dumb,
         cursor,
-        // Same set-and-non-empty convention as NO_COLOR: any value disables.
-        spinner: cursor &&
-            !(env.CRUXY_NO_SPINNER !== undefined && env.CRUXY_NO_SPINNER !== ""),
+        // Motion is the single gate now: CRUXY_NO_SPINNER flows through it (alias),
+        // as do NO_MOTION / CRUXY_REDUCED_MOTION and an implied screen reader.
+        spinner: cursor && !reducedMotion,
+        reducedMotion,
+        screenReader: detectScreenReader(env),
         // Unicode glyph safety (U.1) — independent of color. dumb / CRUXY_ASCII →
         // ASCII glyphs; everything else (incl. pipes) keeps unicode.
         unicode: detectUnicode(env),

package/dist/render/index.d.ts

@@ -1,15 +1,19 @@
 import type { RenderStream, StreamRenderer } from "./types.js";
 export type { ProgressState, RenderCapabilities, RenderPhase, RenderStream, StreamRenderer, TokenUsage, ToolLifecycleEvent, } from "./types.js";
-export { detectCapabilities } from "./capabilities.js";
+export { detectCapabilities, detectReducedMotion } from "./capabilities.js";
 export { composeStatusLine, describePhase, ELAPSED_AFTER_MS, formatElapsed, formatTokens, phaseIdentity, } from "./state.js";
 export { renderActionPreview, PREVIEW_MAX_LINES } from "./diff.js";
 export { createStreamHighlighter, defaultLineHighlighter, type HighlightCarry, type LineHighlighter, type StreamHighlighter, } from "./highlight.js";
 export { PlainRenderer } from "./plain-renderer.js";
+export { ScreenReaderRenderer } from "./screen-reader-renderer.js";
 export { TtyRenderer } from "./tty-renderer.js";
 /**
- * Build the renderer for the detected environment: the managed-live-region
- * {@link TtyRenderer} when cursor control is safe, otherwise the append-only
- * {@link PlainRenderer} (pipes, CI, `TERM=dumb`). Everything downstream talks
- * to the {@link StreamRenderer} interface and never re-probes the terminal.
+ * Build the renderer for the detected environment (U.11 adds the first branch):
+ * - `screenReader` → the linear, worded {@link ScreenReaderRenderer}, regardless
+ *   of cursor support (a screen-reader TTY must not get the live region);
+ * - else cursor-safe → the managed-live-region {@link TtyRenderer} (static, no
+ *   timer, when `reducedMotion`);
+ * - else → the append-only {@link PlainRenderer} (pipes, CI, `TERM=dumb`).
+ * Everything downstream talks to {@link StreamRenderer} and never re-probes.
  */
 export declare function createRenderer(out?: RenderStream, err?: RenderStream, env?: NodeJS.ProcessEnv): StreamRenderer;

package/dist/render/index.js

@@ -1,20 +1,27 @@
 import { detectCapabilities } from "./capabilities.js";
 import { PlainRenderer } from "./plain-renderer.js";
+import { ScreenReaderRenderer } from "./screen-reader-renderer.js";
 import { TtyRenderer } from "./tty-renderer.js";
-export { detectCapabilities } from "./capabilities.js";
+export { detectCapabilities, detectReducedMotion } from "./capabilities.js";
 export { composeStatusLine, describePhase, ELAPSED_AFTER_MS, formatElapsed, formatTokens, phaseIdentity, } from "./state.js";
 export { renderActionPreview, PREVIEW_MAX_LINES } from "./diff.js";
 export { createStreamHighlighter, defaultLineHighlighter, } from "./highlight.js";
 export { PlainRenderer } from "./plain-renderer.js";
+export { ScreenReaderRenderer } from "./screen-reader-renderer.js";
 export { TtyRenderer } from "./tty-renderer.js";
 /**
- * Build the renderer for the detected environment: the managed-live-region
- * {@link TtyRenderer} when cursor control is safe, otherwise the append-only
- * {@link PlainRenderer} (pipes, CI, `TERM=dumb`). Everything downstream talks
- * to the {@link StreamRenderer} interface and never re-probes the terminal.
+ * Build the renderer for the detected environment (U.11 adds the first branch):
+ * - `screenReader` → the linear, worded {@link ScreenReaderRenderer}, regardless
+ *   of cursor support (a screen-reader TTY must not get the live region);
+ * - else cursor-safe → the managed-live-region {@link TtyRenderer} (static, no
+ *   timer, when `reducedMotion`);
+ * - else → the append-only {@link PlainRenderer} (pipes, CI, `TERM=dumb`).
+ * Everything downstream talks to {@link StreamRenderer} and never re-probes.
  */
 export function createRenderer(out = process.stdout, err = process.stderr, env = process.env) {
     const caps = detectCapabilities(out, env);
+    if (caps.screenReader)
+        return new ScreenReaderRenderer(caps, out, err);
     return caps.cursor
         ? new TtyRenderer(caps, out)
         : new PlainRenderer(caps, out, err);