@cruxy/cli 0.12.0 → 0.14.0

package/dist/sandbox/policy.js

@@ -0,0 +1,90 @@
+import { homedir } from "node:os";
+import { isAbsolute, resolve as resolvePath } from "node:path";
+import { configInvalid } from "../errors/index.js";
+import { globalDir } from "../config/paths.js";
+/**
+ * Turn a validated {@link SandboxConfig} + the run's cwd into a fully-resolved
+ * {@link IsolationPolicy}. This is where the security posture is decided, and
+ * every default here is deny/minimal:
+ *
+ * - the ONLY read-write mount is the project workdir (at its identical absolute
+ *   path, so paths stay coherent with the host and the C.32 checkpoint);
+ * - extra mounts come solely from `sandbox.mounts` (explicit by construction),
+ *   and a mount of the docker socket, the cruxy home, or the user's home root
+ *   is rejected — those are the escape hatches we refuse to open;
+ * - the container runs as the host's non-root uid:gid so mounted edits are
+ *   writable and never left root-owned;
+ * - network defaults to `none`; any widening can only come from explicit config.
+ */
+export function buildPolicy(cfg, cwd) {
+    const workdir = {
+        source: cwd,
+        target: cwd,
+        readonly: false,
+    };
+    return {
+        image: cfg.image,
+        network: cfg.network,
+        user: resolveUser(),
+        memory: cfg.memory,
+        pids: cfg.pids,
+        cpus: cfg.cpus,
+        workdir,
+        mounts: cfg.mounts.map((spec) => parseMount(spec, cwd)),
+        tmpfs: "/tmp",
+    };
+}
+/** Host `uid:gid` — non-root (the human isn't uid 0) and keeps mounted files
+ * writable without leaving them root-owned. Falls back to a conventional
+ * non-root id where `getuid` is unavailable (non-POSIX). */
+function resolveUser() {
+    const getuid = process.getuid?.bind(process);
+    const getgid = process.getgid?.bind(process);
+    if (getuid && getgid)
+        return `${getuid()}:${getgid()}`;
+    return "1000:1000";
+}
+/** Sources we refuse to bind-mount into the box — the whole point is that the
+ * container cannot reach the docker socket, the cruxy credential store, or the
+ * user's home. Matched by resolved absolute path. */
+function forbiddenMountSource(source) {
+    const resolved = resolvePath(source);
+    const home = homedir();
+    if (resolved === "/var/run/docker.sock" || resolved.endsWith("docker.sock")) {
+        return "the docker socket (would grant full host control)";
+    }
+    if (resolved === globalDir() || resolved.startsWith(globalDir() + "/")) {
+        return "the cruxy home (holds credentials)";
+    }
+    if (resolved === home)
+        return "the home directory root";
+    if (resolved === "/")
+        return "the filesystem root";
+    return undefined;
+}
+/** Parse one `src:dst[:ro|:rw]` mount spec into a validated {@link BindMount}.
+ * Relative sources resolve against the run's cwd; a forbidden source throws a
+ * config error (never silently dropped). */
+function parseMount(spec, cwd) {
+    // Split on ":" but keep it simple — sources/targets are absolute POSIX-ish
+    // paths; a Windows drive letter is out of scope for this build.
+    const parts = spec.split(":");
+    if (parts.length < 2 || parts.length > 3) {
+        throw configInvalid(`sandbox.mounts entry "${spec}" must be "src:dst" or "src:dst:ro|rw"`);
+    }
+    const [rawSource, target, mode] = parts;
+    if (!target || !isAbsolute(target)) {
+        throw configInvalid(`sandbox.mounts entry "${spec}" needs an absolute container path (dst)`);
+    }
+    if (mode !== undefined && mode !== "ro" && mode !== "rw") {
+        throw configInvalid(`sandbox.mounts entry "${spec}" mode must be "ro" or "rw"`);
+    }
+    const source = isAbsolute(rawSource)
+        ? rawSource
+        : resolvePath(cwd, rawSource);
+    const forbidden = forbiddenMountSource(source);
+    if (forbidden) {
+        throw configInvalid(`sandbox.mounts refuses to mount ${forbidden}: "${spec}"`);
+    }
+    return { source, target, readonly: mode === "ro" };
+}

package/dist/sandbox/service.d.ts

@@ -0,0 +1,57 @@
+import type { CruxyConfig } from "../config/index.js";
+import type { ExecOptions, ExecResult, IsolationPolicy, SandboxCapability, SandboxRuntime } from "./types.js";
+/**
+ * The minimal surface the sandbox needs to report a first-run image pull
+ * through the U.4 state layer. `StreamRenderer` satisfies it structurally, so
+ * callers pass the renderer directly and the sandbox stays render-decoupled.
+ */
+export interface SandboxReporter {
+    status(text: string | null): void;
+}
+export interface SandboxServiceDeps {
+    config: CruxyConfig;
+    /** The run's working directory — mounted read-write as the workdir. */
+    cwd: string;
+    /** Execution runtime seam (defaults to Docker). */
+    runtime?: SandboxRuntime;
+    /** Capability probe seam (defaults to real docker detection). */
+    detect?: () => Promise<SandboxCapability>;
+    /** U.4 sink for the "pulling sandbox image…" line (optional). */
+    reporter?: SandboxReporter;
+}
+/**
+ * The sandbox execution service (C.16) — what `ToolContext.sandbox` points at.
+ * It is only ever constructed when the sandbox is enabled, and constructing it
+ * is where the fail-loud guarantee lives: {@link SandboxService.create} probes
+ * the runtime and throws {@link sandboxUnavailable} if it isn't available, so a
+ * user who asked for the box either gets the box or a loud, coded error — never
+ * a silent drop back to host execution. `exec` then contains an approved
+ * command inside the isolation policy, ensuring the image on first use.
+ */
+export declare class SandboxService {
+    private readonly runtime;
+    private readonly policy;
+    private readonly reporter?;
+    private imageReady?;
+    private constructor();
+    /**
+     * Resolve the runtime and build the policy. THROWS {@link sandboxUnavailable}
+     * when the runtime is missing/unreachable — the caller (session wiring) lets
+     * it propagate so the run stops before any command executes. There is no code
+     * path from here to host execution.
+     */
+    static create(deps: SandboxServiceDeps): Promise<SandboxService>;
+    /** The runtime backing this service (e.g. "docker") — for logging. */
+    get runtimeName(): string;
+    /** The resolved isolation policy — exposed for logging/inspection. */
+    get isolationPolicy(): IsolationPolicy;
+    /**
+     * Execute an already-approved command inside the box. Ensures the image once
+     * (surfacing the pull via U.4), then delegates to the runtime. A container
+     * that fails to start throws a coded error; an ordinary non-zero command exit
+     * comes back as a normal {@link ExecResult} — exit code is truth.
+     */
+    exec(command: string, opts: ExecOptions): Promise<ExecResult>;
+    /** Ensure the image is present, at most once per service (memoized). */
+    private ensureImage;
+}

package/dist/sandbox/service.js

@@ -0,0 +1,64 @@
+import { sandboxUnavailable } from "../errors/index.js";
+import { detectDocker } from "./detect.js";
+import { DockerRuntime } from "./docker-runtime.js";
+import { buildPolicy } from "./policy.js";
+/**
+ * The sandbox execution service (C.16) — what `ToolContext.sandbox` points at.
+ * It is only ever constructed when the sandbox is enabled, and constructing it
+ * is where the fail-loud guarantee lives: {@link SandboxService.create} probes
+ * the runtime and throws {@link sandboxUnavailable} if it isn't available, so a
+ * user who asked for the box either gets the box or a loud, coded error — never
+ * a silent drop back to host execution. `exec` then contains an approved
+ * command inside the isolation policy, ensuring the image on first use.
+ */
+export class SandboxService {
+    runtime;
+    policy;
+    reporter;
+    imageReady;
+    constructor(runtime, policy, reporter) {
+        this.runtime = runtime;
+        this.policy = policy;
+        this.reporter = reporter;
+    }
+    /**
+     * Resolve the runtime and build the policy. THROWS {@link sandboxUnavailable}
+     * when the runtime is missing/unreachable — the caller (session wiring) lets
+     * it propagate so the run stops before any command executes. There is no code
+     * path from here to host execution.
+     */
+    static async create(deps) {
+        const runtime = deps.runtime ?? new DockerRuntime();
+        const detect = deps.detect ?? (() => detectDocker());
+        const capability = await detect();
+        if (!capability.available) {
+            throw sandboxUnavailable(capability.runtime, capability.detail);
+        }
+        const policy = buildPolicy(deps.config.sandbox, deps.cwd);
+        return new SandboxService(runtime, policy, deps.reporter);
+    }
+    /** The runtime backing this service (e.g. "docker") — for logging. */
+    get runtimeName() {
+        return this.runtime.name;
+    }
+    /** The resolved isolation policy — exposed for logging/inspection. */
+    get isolationPolicy() {
+        return this.policy;
+    }
+    /**
+     * Execute an already-approved command inside the box. Ensures the image once
+     * (surfacing the pull via U.4), then delegates to the runtime. A container
+     * that fails to start throws a coded error; an ordinary non-zero command exit
+     * comes back as a normal {@link ExecResult} — exit code is truth.
+     */
+    async exec(command, opts) {
+        await this.ensureImage();
+        return this.runtime.exec(command, this.policy, opts);
+    }
+    /** Ensure the image is present, at most once per service (memoized). */
+    ensureImage() {
+        return (this.imageReady ??= this.runtime
+            .ensureImage(this.policy.image, () => this.reporter?.status(`pulling sandbox image ${this.policy.image}…`))
+            .then(() => this.reporter?.status(null)));
+    }
+}

package/dist/sandbox/types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Sandbox execution (C.16) — the isolation boundary beneath the U.3 gate.
+ *
+ * When the sandbox is enabled, the highest-risk tools (`run_command`,
+ * `run_tests`) execute inside a container instead of directly on the host: the
+ * project workdir is mounted so the agent edits real files, but the *process*
+ * cannot reach the network, cannot touch the host beyond that mount, and cannot
+ * exhaust the machine. Approval still gates every command (see U.3) — the
+ * sandbox contains what an approved command is able to do; it does not replace
+ * the decision to run it.
+ *
+ * Execution is abstracted behind {@link SandboxRuntime} (Docker ships; podman /
+ * none slot in without touching call sites), and the neutral {@link ExecResult}
+ * matches what host execution conceptually returns so `run_command`/`run_tests`
+ * stay substrate-agnostic — exit code is the source of truth on either path.
+ */
+/** Egress policy for the container. `none` is the default (deny all). */
+export type NetworkPolicy = "none" | "host-loopback" | "full";
+/** One resolved bind mount: an absolute host path exposed in the container. */
+export interface BindMount {
+    /** Absolute host path. */
+    readonly source: string;
+    /** Absolute container path (the workdir mount uses `source === target`). */
+    readonly target: string;
+    /** Read-only when true; the workdir mount is read-write. */
+    readonly readonly: boolean;
+}
+/**
+ * A fully-resolved isolation policy — every knob the runtime needs, already
+ * merged from config and validated. `docker-runtime` turns this (plus the
+ * command) into an argv; nothing here is optional or defaulted downstream.
+ */
+export interface IsolationPolicy {
+    /** Pinned base image the container runs (never chosen dynamically). */
+    readonly image: string;
+    /** Egress policy — `none` unless the user deliberately widened it. */
+    readonly network: NetworkPolicy;
+    /** Non-root `uid:gid` the container runs as (host uid, so mounts stay writable). */
+    readonly user: string;
+    /** Memory cap (`--memory`, also mirrored to `--memory-swap` to disable swap). */
+    readonly memory: string;
+    /** Process/thread cap (`--pids-limit`). */
+    readonly pids: number;
+    /** CPU cap (`--cpus`, fractional allowed). */
+    readonly cpus: number;
+    /** The project workdir, mounted read-write at the identical absolute path. */
+    readonly workdir: BindMount;
+    /** Extra explicit mounts beyond the workdir (from `sandbox.mounts`). */
+    readonly mounts: readonly BindMount[];
+    /** Writable in-memory tmp mount point; the rest of the root fs is read-only. */
+    readonly tmpfs: string;
+}
+/** Which end of the output to keep when the byte cap is exceeded. */
+export type CaptureBias = "head" | "tail";
+/** Per-exec bounds handed to a runtime. */
+export interface ExecOptions {
+    /** Host project directory → bind-mounted as the workdir (same absolute path). */
+    readonly cwd: string;
+    /** Wall-clock timeout in ms; overrun kills the container and returns a failure. */
+    readonly timeoutMs: number;
+    /** Cap on combined stdout+stderr bytes captured. */
+    readonly maxOutputBytes: number;
+    /**
+     * Head-bias keeps the start of the output (`run_command`); tail-bias keeps
+     * the end, where test runners print their failure summaries (`run_tests`).
+     */
+    readonly capture: CaptureBias;
+}
+/**
+ * The neutral outcome of one sandboxed execution — the SAME shape host
+ * execution conceptually produces, so both `run_command` and `run_tests` map it
+ * to their own result type without caring which substrate ran the command.
+ */
+export interface ExecResult {
+    /** Process exit code; `null` on a signal kill / timeout. Exit code is truth. */
+    readonly exitCode: number | null;
+    /** Combined stdout+stderr, already bias-capped to `maxOutputBytes`. */
+    readonly output: string;
+    /** True when output was dropped to honor the cap. */
+    readonly outputTruncated: boolean;
+    /** Measured wall-clock duration of the execution. */
+    readonly durationMs: number;
+    /** True when the wall-clock timeout fired and the container was killed. */
+    readonly timedOut: boolean;
+}
+/**
+ * The swappable execution seam. Docker ships as {@link DockerRuntime}; a future
+ * podman/other runtime implements this without touching the tools or service.
+ * `exec` never falls back to the host and never throws for an ordinary non-zero
+ * command exit — it throws only when the container itself cannot run (a coded
+ * {@link CruxyError}), so the fail-loud guarantee is structural.
+ */
+export interface SandboxRuntime {
+    /** Identifier surfaced in errors/logs (e.g. "docker"). */
+    readonly name: string;
+    /**
+     * Ensure `image` is present locally, pulling it if needed. `onPull` fires
+     * once, only if a pull actually starts (so callers can surface it via U.4).
+     * Throws a coded {@link CruxyError} on pull/build failure — never silently
+     * substitutes another image.
+     */
+    ensureImage(image: string, onPull?: () => void): Promise<void>;
+    /** Run `command` inside the box under `policy`, returning a neutral result. */
+    exec(command: string, policy: IsolationPolicy, opts: ExecOptions): Promise<ExecResult>;
+}
+/** Result of probing for a container runtime; presence is a capability. */
+export interface SandboxCapability {
+    /** True when the runtime binary exists AND its daemon is reachable. */
+    readonly available: boolean;
+    /** The runtime that was probed. */
+    readonly runtime: string;
+    /** Why it's unavailable (for the fail-loud error), when not available. */
+    readonly detail?: string;
+}

package/dist/sandbox/types.js

@@ -0,0 +1,17 @@
+/**
+ * Sandbox execution (C.16) — the isolation boundary beneath the U.3 gate.
+ *
+ * When the sandbox is enabled, the highest-risk tools (`run_command`,
+ * `run_tests`) execute inside a container instead of directly on the host: the
+ * project workdir is mounted so the agent edits real files, but the *process*
+ * cannot reach the network, cannot touch the host beyond that mount, and cannot
+ * exhaust the machine. Approval still gates every command (see U.3) — the
+ * sandbox contains what an approved command is able to do; it does not replace
+ * the decision to run it.
+ *
+ * Execution is abstracted behind {@link SandboxRuntime} (Docker ships; podman /
+ * none slot in without touching call sites), and the neutral {@link ExecResult}
+ * matches what host execution conceptually returns so `run_command`/`run_tests`
+ * stay substrate-agnostic — exit code is the source of truth on either path.
+ */
+export {};

package/dist/subagent/orchestrator.d.ts

@@ -3,6 +3,7 @@ import type { ApprovalDecision } from "../approval/types.js";
 import type { CruxyConfig } from "../config/index.js";
 import type { StreamRenderer } from "../render/index.js";
 import type { ApproveAction, ToolContext, ToolRegistry } from "../tools/index.js";
+import type { SandboxService } from "../sandbox/index.js";
 import type { SubagentResult, SubagentSpec } from "./types.js";
 /**
  * Everything a spawn needs from the surrounding session, injected by the
@@ -24,6 +25,12 @@ export interface SubagentOrchestratorDeps {
     } | null;
     projectInstructions?: string | null;
     renderer?: StreamRenderer;
+    /**
+     * The run's sandbox (C.16), when enabled. Threaded into the child ctx so a
+     * subagent's shell/test commands run in the SAME box as the parent's —
+     * sandboxing is never silently dropped for a child.
+     */
+    sandbox?: SandboxService;
     /**
      * Build a fresh, fully-wrapped approval gate for one child run: a NEW
      * `ApprovalService` (so the child gets its own empty session allowlist —

package/dist/subagent/orchestrator.js

@@ -65,6 +65,7 @@ export class SubagentOrchestrator {
                     recordArtifacts(action, artifacts, deps.cwd);
                 return decision;
             },
+            sandbox: deps.sandbox,
         };
         const label = taskLabel(spec.task);
         if (deps.renderer) {

package/dist/testing/run-tests-tool.d.ts

@@ -32,7 +32,11 @@ declare const parameters: z.ZodObject<{
     command?: string | undefined;
 }>;
 export interface RunTestsToolDeps {
-    /** Execution seam (tests inject a fake; default spawns the real command). */
+    /**
+     * Execution seam (tests inject a fake). When unset, the runner is chosen per
+     * run from `ctx.sandbox`: present → {@link SandboxTestRunner} (run in the box,
+     * C.16), absent → host {@link CommandTestRunner} — unchanged.
+     */
     runner?: TestRunner;
     /** Detection seam (defaults to config + package.json detection). */
     detect?: (ctx: ToolContext) => TestCommand | null;

package/dist/testing/run-tests-tool.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { ErrorCode } from "../errors/index.js";
 import { detectTestCommand } from "./detect.js";
 import { CommandTestRunner } from "./runner.js";
+import { SandboxTestRunner } from "./sandbox-runner.js";
 /**
  * The `run_tests` tool (C.13): execute the project's test suite and return a
  * structured result the model can iterate on (edit → re-run → repeat). The
@@ -58,7 +59,6 @@ function renderResult(result, command, iteration) {
 }
 /** Build the `run_tests` tool. One instance = one session's iteration budget. */
 export function makeRunTestsTool(deps = {}) {
-    const runner = deps.runner ?? new CommandTestRunner();
     const detect = deps.detect ??
         ((ctx) => detectTestCommand(ctx.cwd, ctx.config));
     const budget = new TestIterationBudget();
@@ -104,6 +104,13 @@ export function makeRunTestsTool(deps = {}) {
                     error: decision.feedback ?? "test run denied by the user",
                 };
             }
+            // Substrate chosen by ctx.sandbox (C.16): in the box when enabled, else
+            // host — identical result shape either way. An explicit deps.runner
+            // (tests) always wins. A sandbox that can't run throws (fail loud).
+            const runner = deps.runner ??
+                (ctx.sandbox
+                    ? new SandboxTestRunner(ctx.sandbox)
+                    : new CommandTestRunner());
             const result = await runner.run(resolved.command, {
                 cwd: ctx.cwd,
                 timeoutMs: ctx.config.shell.timeoutMs,

package/dist/testing/sandbox-runner.d.ts

@@ -0,0 +1,16 @@
+import type { SandboxService } from "../sandbox/index.js";
+import type { TestRunner, TestRunOptions, TestRunResult } from "./types.js";
+/**
+ * A {@link TestRunner} that runs the suite inside the C.16 sandbox instead of
+ * on the host. It maps the neutral sandbox {@link ExecResult} onto the exact
+ * same {@link TestRunResult} the host {@link CommandTestRunner} produces — so
+ * honest-green (`passed = exitCode === 0`), tail-biased capture, and the
+ * timeout note all hold identically inside the box. A container-start failure
+ * is NOT swallowed into a result: `sandbox.exec` throws a coded error that
+ * propagates (fail loud), never a fabricated pass.
+ */
+export declare class SandboxTestRunner implements TestRunner {
+    private readonly sandbox;
+    constructor(sandbox: SandboxService);
+    run(command: string, opts: TestRunOptions): Promise<TestRunResult>;
+}

package/dist/testing/sandbox-runner.js

@@ -0,0 +1,47 @@
+import { parseFailures } from "./parse.js";
+/**
+ * A {@link TestRunner} that runs the suite inside the C.16 sandbox instead of
+ * on the host. It maps the neutral sandbox {@link ExecResult} onto the exact
+ * same {@link TestRunResult} the host {@link CommandTestRunner} produces — so
+ * honest-green (`passed = exitCode === 0`), tail-biased capture, and the
+ * timeout note all hold identically inside the box. A container-start failure
+ * is NOT swallowed into a result: `sandbox.exec` throws a coded error that
+ * propagates (fail loud), never a fabricated pass.
+ */
+export class SandboxTestRunner {
+    sandbox;
+    constructor(sandbox) {
+        this.sandbox = sandbox;
+    }
+    async run(command, opts) {
+        const result = await this.sandbox.exec(command, {
+            cwd: opts.cwd,
+            timeoutMs: opts.timeoutMs,
+            maxOutputBytes: opts.captureBytes,
+            capture: "tail", // failures live at the end of test output
+        });
+        if (result.timedOut) {
+            return {
+                passed: false,
+                exitCode: null,
+                durationMs: result.durationMs,
+                failures: [],
+                output: result.output +
+                    `\n… [test run timed out after ${opts.timeoutMs}ms and was killed]`,
+                outputTruncated: result.outputTruncated,
+            };
+        }
+        // THE honest-green rule, unchanged by the substrate: exit 0 means passed.
+        const passed = result.exitCode === 0;
+        const parsed = passed ? { failures: [] } : parseFailures(result.output);
+        return {
+            passed,
+            exitCode: result.exitCode,
+            durationMs: result.durationMs,
+            ...(parsed.total !== undefined ? { total: parsed.total } : {}),
+            failures: parsed.failures,
+            output: result.output,
+            outputTruncated: result.outputTruncated,
+        };
+    }
+}

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",
+};