@cruxy/cli 0.11.0 → 0.13.0

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/frame.js

@@ -1,3 +1,4 @@
+import { resolveTheme } from "../theme/index.js";
 /** Erase the current line and return the cursor to column 0 (same as U.2). */
 const CLEAR_LINE = "\r\x1b[2K";
 /** Move the cursor up one row. */
@@ -11,6 +12,7 @@ export function stripAnsi(text) {
 }
 export function createFrame(write, caps) {
     let drawn = 0;
+    const ellipsis = resolveTheme(caps).glyph.ellipsis;
     /**
      * Truncate to width-1 (cursor rests after the last cell; a full-width row
      * would auto-wrap on some terminals). Width is measured on VISIBLE
@@ -23,7 +25,7 @@ export function createFrame(write, caps) {
         const plain = stripAnsi(line);
         if (plain.length <= room)
             return line;
-        return plain.slice(0, room - 1) + "…";
+        return plain.slice(0, room - 1) + ellipsis;
     };
     const erase = () => {
         if (drawn === 0)

package/dist/components/fuzzy.d.ts

@@ -1,4 +1,4 @@
-import pc from "picocolors";
+import { type Theme } from "../theme/index.js";
 import { type ComponentIO, type InteractiveResult } from "./input.js";
 /**
  * Fuzzy finding (U.7): a deterministic, honest subsequence scorer (pure,
@@ -36,10 +36,10 @@ export interface RankedItem<T> {
  */
 export declare function rankItems<T>(items: readonly T[], toLabel: (item: T) => string, query: string): RankedItem<T>[];
 /**
- * Bold the matched characters of a label. With color off (NO_COLOR, pipe)
- * picocolors' disabled palette is the identity — plain text, zero ANSI.
+ * Bold the matched characters of a label via the theme's accent role. With
+ * color off (NO_COLOR, pipe) the roles are identity — plain text, zero ANSI.
  */
-export declare function highlightMatch(label: string, positions: readonly number[], colors: ReturnType<typeof pc.createColors>): string;
+export declare function highlightMatch(label: string, positions: readonly number[], theme: Theme): string;
 export interface FuzzyFindOptions<T> {
     /** Label an item filters/renders under. Required — items are opaque. */
     toLabel: (item: T) => string;

package/dist/components/fuzzy.js

@@ -1,4 +1,4 @@
-import pc from "picocolors";
+import { resolveTheme } from "../theme/index.js";
 import { createFrame } from "./frame.js";
 import { defaultComponentIO, resolveNonInteractive, } from "./input.js";
 /** Word-boundary characters that earn the boundary bonus for the NEXT char. */
@@ -69,16 +69,16 @@ export function rankItems(items, toLabel, query) {
     return ranked.map(({ item, label, match }) => ({ item, label, match }));
 }
 /**
- * Bold the matched characters of a label. With color off (NO_COLOR, pipe)
- * picocolors' disabled palette is the identity — plain text, zero ANSI.
+ * Bold the matched characters of a label via the theme's accent role. With
+ * color off (NO_COLOR, pipe) the roles are identity — plain text, zero ANSI.
  */
-export function highlightMatch(label, positions, colors) {
+export function highlightMatch(label, positions, theme) {
     if (positions.length === 0)
         return label;
     const matched = new Set(positions);
     let out = "";
     for (let i = 0; i < label.length; i++) {
-        out += matched.has(i) ? colors.bold(colors.cyan(label[i])) : label[i];
+        out += matched.has(i) ? theme.strong(theme.accent(label[i])) : label[i];
     }
     return out;
 }
@@ -94,7 +94,8 @@ export async function fuzzyFind(items, opts, io = defaultComponentIO()) {
         return fallback;
     if (items.length === 0)
         return { kind: "cancelled" };
-    const colors = pc.createColors(io.caps.color);
+    const t = resolveTheme(io.caps);
+    const g = t.glyph;
     const maxVisible = opts.maxVisible ?? 10;
     const frame = createFrame(io.write, io.caps);
     let query = "";
@@ -102,10 +103,10 @@ export async function fuzzyFind(items, opts, io = defaultComponentIO()) {
     const paint = (ranked) => {
         const lines = [];
         if (opts.title)
-            lines.push(colors.bold(opts.title));
-        lines.push(`${colors.cyan("›")} ${query}${colors.dim("▏")}`);
+            lines.push(t.heading(opts.title));
+        lines.push(`${t.accent(g.caret)} ${query}${t.muted(g.cursorBar)}`);
         if (ranked.length === 0) {
-            lines.push(colors.dim("  no results — backspace to widen"));
+            lines.push(t.muted("  no results — backspace to widen"));
         }
         else {
             // Keep the highlighted row inside the viewport.
@@ -113,13 +114,13 @@ export async function fuzzyFind(items, opts, io = defaultComponentIO()) {
             const visible = ranked.slice(top, top + maxVisible);
             for (const [i, row] of visible.entries()) {
                 const selected = top + i === cursor;
-                const marker = selected ? colors.cyan("❯") : " ";
-                const label = highlightMatch(row.label, row.match.positions, colors);
-                lines.push(`${marker} ${selected ? label : colors.dim(label)}`);
+                const marker = selected ? t.accent(g.pointer) : " ";
+                const label = highlightMatch(row.label, row.match.positions, t);
+                lines.push(`${marker} ${selected ? label : t.muted(label)}`);
             }
             const hidden = ranked.length - visible.length;
             if (hidden > 0)
-                lines.push(colors.dim(`  … ${hidden} more`));
+                lines.push(t.muted(`  ${g.ellipsis} ${hidden} more`));
         }
         frame.render(lines);
     };

package/dist/components/select.js

@@ -1,4 +1,4 @@
-import pc from "picocolors";
+import { resolveTheme } from "../theme/index.js";
 import { createFrame } from "./frame.js";
 import { defaultComponentIO, resolveNonInteractive, } from "./input.js";
 /**
@@ -15,26 +15,27 @@ export async function selectList(items, opts = {}, io = defaultComponentIO()) {
     if (items.length === 0)
         return { kind: "cancelled" };
     const toLabel = opts.toLabel ?? ((item) => String(item));
-    const colors = pc.createColors(io.caps.color);
+    const t = resolveTheme(io.caps);
+    const g = t.glyph;
     const maxVisible = opts.maxVisible ?? 10;
     const frame = createFrame(io.write, io.caps);
     let cursor = Math.min(Math.max(opts.initialIndex ?? 0, 0), items.length - 1);
     const paint = () => {
         const lines = [];
         if (opts.title)
-            lines.push(colors.bold(opts.title));
+            lines.push(t.heading(opts.title));
         const top = Math.min(Math.max(0, cursor - maxVisible + 1), Math.max(0, items.length - maxVisible));
         const visible = items.slice(top, top + maxVisible);
         for (const [i, item] of visible.entries()) {
             const selected = top + i === cursor;
-            const marker = selected ? colors.cyan("❯") : " ";
+            const marker = selected ? t.accent(g.pointer) : " ";
             const label = toLabel(item);
-            lines.push(`${marker} ${selected ? label : colors.dim(label)}`);
+            lines.push(`${marker} ${selected ? label : t.muted(label)}`);
         }
         const hidden = items.length - visible.length;
         if (hidden > 0)
-            lines.push(colors.dim(`  … ${hidden} more`));
-        lines.push(colors.dim("  ↑/↓ move · enter select · esc cancel"));
+            lines.push(t.muted(`  ${g.ellipsis} ${hidden} more`));
+        lines.push(t.muted(`  ${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/format.js

@@ -1,4 +1,4 @@
-import pc from "picocolors";
+import { themeForColor } from "../theme/index.js";
 /**
  * Decide whether to colorize: honor `NO_COLOR` (disable) and `FORCE_COLOR`
  * (enable), otherwise color only when writing to a TTY.
@@ -13,27 +13,27 @@ export function shouldUseColor(stream = process.stderr, env = process.env) {
 /** The default terminal formatter: title, cause, next steps, code (+ verbose). */
 export class TerminalFormatter {
     format(err, opts) {
-        const c = pc.createColors(opts.color);
+        const t = themeForColor(opts.color);
         const lines = [];
         // 1. Title — one plain line, what failed.
-        lines.push(c.red(c.bold(err.title)));
+        lines.push(t.danger(t.strong(err.title)));
         // 2. Cause — the specific reason, when known.
         if (err.cause)
-            lines.push(`${c.dim("Cause:")} ${err.cause}`);
+            lines.push(`${t.muted("Cause:")} ${err.cause}`);
         // 3. Next step(s) — the concrete action(s) to take.
         if (err.nextSteps.length > 0) {
             lines.push("");
-            lines.push(c.bold("Next steps:"));
+            lines.push(t.heading("Next steps:"));
             for (const step of err.nextSteps)
-                lines.push(`  ${c.cyan("→")} ${step}`);
+                lines.push(`  ${t.accent(t.glyph.arrow)} ${step}`);
         }
         // 4. Code — the stable, greppable id.
         lines.push("");
-        lines.push(c.dim(`[${err.code}]`));
+        lines.push(t.muted(`[${err.code}]`));
         // Verbose-only: the preserved underlying error.
         if (opts.verbose && err.underlying !== undefined) {
             lines.push("");
-            lines.push(c.dim("Underlying error:"));
+            lines.push(t.muted("Underlying error:"));
             lines.push(indent(stackOf(err.underlying)));
         }
         return lines.join("\n");

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/flow.js

@@ -1,5 +1,5 @@
 import { AuthError, NetworkError, createProvider } from "@cruxy/sdk";
-import pc from "picocolors";
+import { themeForColor } from "../theme/index.js";
 import { resolveApiKey, writeCredential } from "../config/index.js";
 import { newOnboardingState, readOnboardingState, writeOnboardingState, } from "./detect.js";
 import { acquireKeyStep, firstWinStep, scaffoldStep } from "./steps.js";
@@ -11,8 +11,8 @@ import { acquireKeyStep, firstWinStep, scaffoldStep } from "./steps.js";
  */
 export async function runOnboarding(opts) {
     const { io, deps, provider } = opts;
-    const col = pc.createColors(io.color);
-    io.write(`${col.cyan(col.bold("Welcome to cruxy"))} — let's get you set up.\n`);
+    const t = themeForColor(io.color);
+    io.write(`${t.accent(t.strong("Welcome to cruxy"))} — let's get you set up.\n`);
     let state = deps.readState() ?? newOnboardingState();
     let apiKey = deps.resolveApiKey(provider);
     // ── key (mandatory; skipped if already resolvable unless forceKey) ─────────
@@ -24,7 +24,7 @@ export async function runOnboarding(opts) {
         if (result.status !== "ok") {
             // Failed (unreachable / rejected) — surface guidance, no marker.
             if (result.message)
-                io.write(`${col.dim(result.message)}\n`);
+                io.write(`${t.muted(result.message)}\n`);
             return { completed: false, aborted: false };
         }
         apiKey = result.apiKey;
@@ -32,7 +32,7 @@ export async function runOnboarding(opts) {
         deps.writeState(state);
     }
     else {
-        io.write(`${col.green("✓")} using your existing API key.\n`);
+        io.write(`${t.success(t.glyph.success)} using your existing API key.\n`);
         state = { ...state, keyConfigured: true };
     }
     // ── optional steps (Ctrl-C here just skips them; the key is already safe) ───
@@ -43,7 +43,7 @@ export async function runOnboarding(opts) {
     // ── complete ───────────────────────────────────────────────────────────────
     state = { ...state, completedAt: deps.now() };
     deps.writeState(state);
-    io.write(`${col.green(col.bold("✓ all set"))} — happy hacking.\n`);
+    io.write(`${t.success(t.strong(`${t.glyph.success} all set`))} — happy hacking.\n`);
     return { completed: true, aborted: false, apiKey };
 }
 /**