@cruxy/cli 0.11.0 → 0.13.0

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,9 +65,12 @@ export class SubagentOrchestrator {
                     recordArtifacts(action, artifacts, deps.cwd);
                 return decision;
             },
+            sandbox: deps.sandbox,
         };
         const label = taskLabel(spec.task);
-        deps.renderer?.note(`⏵ subagent: ${label}`);
+        if (deps.renderer) {
+            deps.renderer.note(`${deps.renderer.theme.glyph.play} subagent: ${label}`);
+        }
         deps.renderer?.setPhase({ kind: "subagent", label });
         // The isolation seam: a brand-new history seeded with ONLY the task. The
         // parent's messages are never in scope here, and this array dies with the
@@ -96,7 +99,9 @@ export class SubagentOrchestrator {
                 deps.renderer?.setPhase(null);
                 throw err;
             }
-            deps.renderer?.note(`✗ subagent failed: ${label}`);
+            if (deps.renderer) {
+                deps.renderer.note(`${deps.renderer.theme.glyph.failure} subagent failed: ${label}`);
+            }
             deps.renderer?.setPhase(null);
             return {
                 status: "failed",
@@ -123,7 +128,9 @@ export class SubagentOrchestrator {
             usage: run.usage,
         };
         if (run.stop === "completed") {
-            this.deps.renderer?.note(`✓ subagent done: ${label}`);
+            const r = this.deps.renderer;
+            if (r)
+                r.note(`${r.theme.glyph.success} subagent done: ${label}`);
             return { status: "done", ...base };
         }
         // Both cap paths are the same outcome for the parent: a truncated, partial
@@ -132,7 +139,9 @@ export class SubagentOrchestrator {
         const reason = run.stop === "budget"
             ? (run.stopReason ?? "budget cap reached")
             : `agent.maxIterations ceiling reached (${this.deps.config.agent.maxIterations})`;
-        this.deps.renderer?.note(`✗ subagent stopped (budget): ${label}`);
+        const r = this.deps.renderer;
+        if (r)
+            r.note(`${r.theme.glyph.failure} subagent stopped (budget): ${label}`);
         return {
             status: "budget-exceeded",
             ...base,
@@ -195,12 +204,16 @@ function lastAssistantText(messages) {
  */
 class SubagentRenderer {
     caps;
+    theme;
     inner;
     label;
+    prefix;
     constructor(inner, label) {
         this.inner = inner;
         this.label = label;
         this.caps = inner.caps;
+        this.theme = inner.theme;
+        this.prefix = `subagent ${inner.theme.glyph.sep} `;
     }
     /** Turn framing belongs to the parent's turn — the child's is dropped. */
     beginTurn() { }
@@ -209,7 +222,7 @@ class SubagentRenderer {
     write() { }
     endSegment() { }
     note(text) {
-        this.inner.note(`subagent · ${text}`);
+        this.inner.note(`${this.prefix}${text}`);
     }
     preview(preview) {
         this.inner.preview(preview);
@@ -231,7 +244,10 @@ class SubagentRenderer {
     /** The plan executor owns the progress register (C.31) — never the child. */
     progress() { }
     toolLifecycle(event) {
-        this.inner.toolLifecycle({ ...event, label: `subagent · ${event.label}` });
+        this.inner.toolLifecycle({
+            ...event,
+            label: `${this.prefix}${event.label}`,
+        });
     }
     promptResolved() {
         this.inner.promptResolved();

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/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./tokens.js";
+export * from "./resolve.js";

package/dist/theme/index.js

@@ -0,0 +1,2 @@
+export * from "./tokens.js";
+export * from "./resolve.js";

package/dist/theme/resolve.d.ts

@@ -0,0 +1,32 @@
+import { type Theme, type ThemeCapabilities } from "./tokens.js";
+/**
+ * Theme resolution (U.1) — the ONE place picocolors is used. The two 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]`.
+ */
+export declare function resolveTheme(caps: ThemeCapabilities): Theme;
+/**
+ * Whether the terminal can render unicode glyphs. `TERM=dumb` and an explicit
+ * `CRUXY_ASCII` opt-in fall back to the ASCII table; everything else (real
+ * terminals AND pipes) keeps unicode — piping ✓/✗ to a file is fine, and this
+ * preserves pre-U.1 behavior for non-TTY output.
+ *
+ * The single source of the rule: `render/capabilities.ts` calls this to fill
+ * `RenderCapabilities.unicode`, and the boolean-seam surfaces (errors,
+ * approval, plan, onboarding, CLI commands) call it to build a theme without a
+ * signature change.
+ */
+export declare function detectUnicode(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.
+ */
+export declare function themeForColor(color: boolean, env?: NodeJS.ProcessEnv): Theme;

package/dist/theme/resolve.js

@@ -0,0 +1,73 @@
+import pc from "picocolors";
+import { ASCII_GLYPHS, UNICODE_GLYPHS, } from "./tokens.js";
+/**
+ * Theme resolution (U.1) — the ONE place picocolors is used. The two 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]`.
+ */
+export function resolveTheme(caps) {
+    const c = pc.createColors(caps.color);
+    const glyph = caps.unicode ? UNICODE_GLYPHS : ASCII_GLYPHS;
+    const strong = c.bold;
+    const indent = (text, level = 1) => {
+        const pad = "  ".repeat(Math.max(0, level));
+        return text
+            .split("\n")
+            .map((line) => (line === "" ? line : pad + line))
+            .join("\n");
+    };
+    return {
+        danger: c.red,
+        warning: c.yellow,
+        success: c.green,
+        accent: c.cyan,
+        muted: c.dim,
+        strong,
+        syntax: {
+            keyword: c.magenta,
+            string: c.green,
+            number: c.yellow,
+            comment: c.dim,
+        },
+        glyph,
+        heading: strong,
+        indent,
+        kv: (key, value, keyWidth) => `${strong(keyWidth ? key.padEnd(keyWidth) : key)}  ${value}`,
+        sep: ` ${glyph.sep} `,
+        color: caps.color,
+        unicode: caps.unicode,
+    };
+}
+/**
+ * Whether the terminal can render unicode glyphs. `TERM=dumb` and an explicit
+ * `CRUXY_ASCII` opt-in fall back to the ASCII table; everything else (real
+ * terminals AND pipes) keeps unicode — piping ✓/✗ to a file is fine, and this
+ * preserves pre-U.1 behavior for non-TTY output.
+ *
+ * The single source of the rule: `render/capabilities.ts` calls this to fill
+ * `RenderCapabilities.unicode`, and the boolean-seam surfaces (errors,
+ * approval, plan, onboarding, CLI commands) call it to build a theme without a
+ * signature change.
+ */
+export function detectUnicode(env = process.env) {
+    if (env.CRUXY_ASCII !== undefined && env.CRUXY_ASCII !== "")
+        return false;
+    if (env.TERM === "dumb")
+        return false;
+    return true;
+}
+/**
+ * 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.
+ */
+export function themeForColor(color, env = process.env) {
+    return resolveTheme({ color, unicode: detectUnicode(env) });
+}