@cruxy/cli 0.11.0 → 0.13.0

package/dist/render/tty-renderer.d.ts

@@ -1,4 +1,5 @@
 import type { ActionPreview } from "../tools/types.js";
+import { type Theme } from "../theme/index.js";
 import type { ProgressState, RenderCapabilities, RenderPhase, RenderStream, StreamRenderer, ToolLifecycleEvent } from "./types.js";
 /**
  * The interactive renderer: committed content is append-only; the one transient
@@ -28,7 +29,7 @@ import type { ProgressState, RenderCapabilities, RenderPhase, RenderStream, Stre
 export declare class TtyRenderer implements StreamRenderer {
     readonly caps: RenderCapabilities;
     private readonly out;
-    private readonly colors;
+    readonly theme: Theme;
     private print;
     private highlighter;
     private wroteInSegment;

package/dist/render/tty-renderer.js

@@ -1,13 +1,10 @@
-import pc from "picocolors";
+import { resolveTheme } from "../theme/index.js";
 import { createStreamPrinter } from "../cli/stream-print.js";
 import { renderActionPreview } from "./diff.js";
 import { createStreamHighlighter, } from "./highlight.js";
 import { composeStatusLine, ELAPSED_AFTER_MS, formatElapsed, phaseIdentity, } from "./state.js";
 /** Erase the current line and return the cursor to column 0. */
 const CLEAR_LINE = "\r\x1b[2K";
-/** Spinner frames (braille); a static glyph when animation is disabled. */
-const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-const STATIC_FRAME = "◐";
 const SPINNER_INTERVAL_MS = 100;
 /**
  * The interactive renderer: committed content is append-only; the one transient
@@ -37,7 +34,7 @@ const SPINNER_INTERVAL_MS = 100;
 export class TtyRenderer {
     caps;
     out;
-    colors;
+    theme;
     print;
     highlighter;
     wroteInSegment = false;
@@ -59,8 +56,8 @@ export class TtyRenderer {
     constructor(caps, out) {
         this.caps = caps;
         this.out = out;
-        this.colors = pc.createColors(caps.color);
-        this.highlighter = createStreamHighlighter(this.colors);
+        this.theme = resolveTheme(caps);
+        this.highlighter = createStreamHighlighter(this.theme);
         this.print = this.newPrinter();
     }
     newPrinter() {
@@ -115,7 +112,7 @@ export class TtyRenderer {
         const elapsed = this.phase !== null && this.caps.spinner
             ? Date.now() - this.phaseStartedAt
             : undefined;
-        return composeStatusLine(this.progressState, this.phase, elapsed);
+        return composeStatusLine(this.progressState, this.phase, elapsed, this.theme.glyph);
     }
     /** Redraw the live line from current state, or hide it when there is none. */
     refresh() {
@@ -138,16 +135,19 @@ export class TtyRenderer {
     }
     drawLine(text) {
         this.lineVisible = true;
+        const frames = this.theme.glyph.spinnerFrames;
         const glyph = this.caps.spinner
-            ? FRAMES[this.frame % FRAMES.length]
-            : STATIC_FRAME;
+            ? frames[this.frame % frames.length]
+            : this.theme.glyph.spinnerStatic;
         // Reserve glyph + space; truncate so the live line can never soft-wrap.
         const room = Math.max(1, this.caps.width - 2);
-        const line = text.length > room ? text.slice(0, Math.max(0, room - 1)) + "…" : text;
-        this.out.write(`${CLEAR_LINE}${this.colors.cyan(glyph)} ${this.colors.dim(line)}`);
+        const line = text.length > room
+            ? text.slice(0, Math.max(0, room - 1)) + this.theme.glyph.ellipsis
+            : text;
+        this.out.write(`${CLEAR_LINE}${this.theme.accent(glyph)} ${this.theme.muted(line)}`);
     }
     beginTurn() {
-        this.highlighter = createStreamHighlighter(this.colors);
+        this.highlighter = createStreamHighlighter(this.theme);
         this.print = this.newPrinter();
         this.wroteInSegment = false;
     }
@@ -169,13 +169,15 @@ export class TtyRenderer {
         if (this.closed)
             return;
         const room = Math.max(1, this.caps.width);
-        const line = text.length > room ? text.slice(0, room - 1) + "…" : text;
-        this.commit(this.colors.dim(line) + "\n");
+        const line = text.length > room
+            ? text.slice(0, room - 1) + this.theme.glyph.ellipsis
+            : text;
+        this.commit(this.theme.muted(line) + "\n");
     }
     preview(preview) {
         if (this.closed)
             return;
-        const block = renderActionPreview(preview, this.colors);
+        const block = renderActionPreview(preview, this.theme);
         if (block)
             this.commit(block + "\n");
     }
@@ -237,7 +239,8 @@ export class TtyRenderer {
         // honest even with CRUXY_NO_SPINNER; shown only once it means something.
         const elapsed = started === null ? 0 : Date.now() - started.at;
         const suffix = elapsed >= ELAPSED_AFTER_MS ? ` (${formatElapsed(elapsed)})` : "";
-        this.note(`${event.ok ? "✓" : "✗"} ${event.label}${suffix}`);
+        const mark = event.ok ? this.theme.glyph.success : this.theme.glyph.failure;
+        this.note(`${mark} ${event.label}${suffix}`);
     }
     promptResolved() {
         if (this.closed)

package/dist/render/types.d.ts

@@ -1,4 +1,5 @@
 import type { ActionPreview } from "../tools/types.js";
+import type { Theme } from "../theme/index.js";
 /**
  * The streaming render seam (U.2): the agent loop talks to a
  * {@link StreamRenderer}, never to raw stdout. Two implementations exist —
@@ -21,6 +22,9 @@ export interface RenderCapabilities {
     cursor: boolean;
     /** Animation is welcome (`cursor` and CRUXY_NO_SPINNER unset). */
     spinner: boolean;
+    /** Unicode glyphs are safe (U.1) — false under `TERM=dumb` / `CRUXY_ASCII`;
+     * independent of `color`. Drives the theme's glyph table, not its stylers. */
+    unicode: boolean;
     /** Terminal columns; 80 when unknown (non-TTY). */
     width: number;
 }
@@ -97,6 +101,9 @@ export type ToolLifecycleEvent = {
  */
 export interface StreamRenderer {
     readonly caps: RenderCapabilities;
+    /** The one resolved design system (U.1) — glyphs/roles for chrome a
+     * surface emits through this renderer (e.g. the subagent trail notes). */
+    readonly theme: Theme;
     /** Start a user turn: reset leading-newline trim and code-fence state. */
     beginTurn(): void;
     /**

package/dist/sandbox/detect.d.ts

@@ -0,0 +1,22 @@
+import type { SandboxCapability } from "./types.js";
+/**
+ * Runtime detection (C.16): a container runtime is a *capability*, not an
+ * assumption. Presence means both that the binary exists AND its daemon
+ * answers — `docker` installed with a dead daemon is NOT available, and the
+ * caller must fail loud rather than pretend a box exists.
+ */
+/** Injectable probe seam — spawns a short command and reports how it exited. */
+export type RuntimeProbe = (bin: string, args: string[]) => Promise<{
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Detect the Docker runtime. `docker version --format {{.Server.Version}}`
+ * exits non-zero when the daemon is unreachable (even though the client is
+ * installed), so a zero exit with a server version is the honest "available"
+ * signal. Memoized for the process; pass a probe (tests) to bypass the cache.
+ */
+export declare function detectDocker(probe?: RuntimeProbe): Promise<SandboxCapability>;
+/** Clear the memoized capability (tests). */
+export declare function resetDetectionCache(): void;

package/dist/sandbox/detect.js

@@ -0,0 +1,67 @@
+import { spawn } from "node:child_process";
+/** Default probe: spawn the binary, capture output, treat a spawn error (e.g.
+ * ENOENT — binary missing) as a non-zero exit rather than a throw. */
+const spawnProbe = (bin, args) => new Promise((resolve) => {
+    let child;
+    try {
+        child = spawn(bin, args);
+    }
+    catch (err) {
+        resolve({ code: null, stdout: "", stderr: err.message });
+        return;
+    }
+    let out = "";
+    let errText = "";
+    let settled = false;
+    const done = (code, stderr = errText) => {
+        if (settled)
+            return;
+        settled = true;
+        resolve({ code, stdout: out, stderr });
+    };
+    // The daemon can hang; a probe must never wedge startup.
+    const timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        done(null, "timed out probing the runtime");
+    }, PROBE_TIMEOUT_MS);
+    timer.unref?.();
+    child.stdout?.on("data", (b) => (out += b.toString("utf8")));
+    child.stderr?.on("data", (b) => (errText += b.toString("utf8")));
+    child.on("error", (err) => done(null, err.message));
+    child.on("close", (code) => {
+        clearTimeout(timer);
+        done(code);
+    });
+});
+const PROBE_TIMEOUT_MS = 5000;
+let cached;
+/**
+ * Detect the Docker runtime. `docker version --format {{.Server.Version}}`
+ * exits non-zero when the daemon is unreachable (even though the client is
+ * installed), so a zero exit with a server version is the honest "available"
+ * signal. Memoized for the process; pass a probe (tests) to bypass the cache.
+ */
+export function detectDocker(probe) {
+    if (probe)
+        return probeDocker(probe);
+    cached ??= probeDocker(spawnProbe);
+    return cached;
+}
+/** Clear the memoized capability (tests). */
+export function resetDetectionCache() {
+    cached = undefined;
+}
+async function probeDocker(probe) {
+    const { code, stdout, stderr } = await probe("docker", [
+        "version",
+        "--format",
+        "{{.Server.Version}}",
+    ]);
+    if (code === 0 && stdout.trim().length > 0) {
+        return { available: true, runtime: "docker" };
+    }
+    const detail = code === null
+        ? "the docker binary is not installed or not on PATH"
+        : (stderr.trim().split("\n")[0] ?? "docker daemon is not reachable");
+    return { available: false, runtime: "docker", detail };
+}

package/dist/sandbox/docker-runtime.d.ts

@@ -0,0 +1,32 @@
+import type { ExecOptions, ExecResult, IsolationPolicy, SandboxRuntime } from "./types.js";
+/**
+ * The shipped {@link SandboxRuntime}: shells out to the `docker` CLI (no SDK —
+ * matches the no-vendor-client ethos). {@link buildRunArgs} is a pure function
+ * so the entire isolation posture can be asserted from the argv without a live
+ * daemon; `exec` spawns docker, captures bias-capped output, enforces the
+ * wall-clock timeout by force-killing the container, and maps the result.
+ *
+ * The exit code from `docker run` is the command's own — EXCEPT `125`, which
+ * docker reserves for "the run itself failed" (bad flags, daemon error): that,
+ * and a spawn failure, are the only container-start failures, surfaced as a
+ * coded {@link sandboxExec} error. An ordinary non-zero command exit is a
+ * normal result (exit code is truth), never a thrown error and never a host run.
+ */
+export declare class DockerRuntime implements SandboxRuntime {
+    private readonly bin;
+    readonly name = "docker";
+    constructor(bin?: string);
+    ensureImage(image: string, onPull?: () => void): Promise<void>;
+    /** Run a non-container docker subcommand to completion, capturing output. */
+    private simpleRun;
+    exec(command: string, policy: IsolationPolicy, opts: ExecOptions): Promise<ExecResult>;
+    private run;
+    /** Best-effort container teardown after a timeout kill. */
+    private forceRemove;
+}
+/**
+ * Build the `docker run` argv from a resolved policy. Pure and total — the
+ * single source of truth for the isolation boundary, asserted directly in
+ * tests. Order is stable for readability; docker is order-insensitive for flags.
+ */
+export declare function buildRunArgs(policy: IsolationPolicy, container: string, command: string): string[];

package/dist/sandbox/docker-runtime.js

@@ -0,0 +1,263 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { sandboxExec, sandboxImage } from "../errors/index.js";
+/**
+ * The shipped {@link SandboxRuntime}: shells out to the `docker` CLI (no SDK —
+ * matches the no-vendor-client ethos). {@link buildRunArgs} is a pure function
+ * so the entire isolation posture can be asserted from the argv without a live
+ * daemon; `exec` spawns docker, captures bias-capped output, enforces the
+ * wall-clock timeout by force-killing the container, and maps the result.
+ *
+ * The exit code from `docker run` is the command's own — EXCEPT `125`, which
+ * docker reserves for "the run itself failed" (bad flags, daemon error): that,
+ * and a spawn failure, are the only container-start failures, surfaced as a
+ * coded {@link sandboxExec} error. An ordinary non-zero command exit is a
+ * normal result (exit code is truth), never a thrown error and never a host run.
+ */
+export class DockerRuntime {
+    bin;
+    name = "docker";
+    constructor(bin = "docker") {
+        this.bin = bin;
+    }
+    async ensureImage(image, onPull) {
+        // Present locally already? `docker image inspect` exits 0 when it is.
+        const inspect = await this.simpleRun(["image", "inspect", image]);
+        if (inspect.code === 0)
+            return;
+        // Not present — pull it (surface once), and fail loud if the pull fails.
+        onPull?.();
+        const pull = await this.simpleRun(["pull", image]);
+        if (pull.code !== 0) {
+            throw sandboxImage(image, pull.stderr.trim() || pull.stdout.trim());
+        }
+    }
+    /** Run a non-container docker subcommand to completion, capturing output. */
+    simpleRun(args) {
+        return new Promise((resolve) => {
+            let child;
+            try {
+                child = spawn(this.bin, args);
+            }
+            catch (err) {
+                resolve({ code: null, stdout: "", stderr: err.message });
+                return;
+            }
+            let out = "";
+            let errText = "";
+            child.stdout?.on("data", (b) => (out += b.toString("utf8")));
+            child.stderr?.on("data", (b) => (errText += b.toString("utf8")));
+            child.on("error", (err) => resolve({ code: null, stdout: out, stderr: err.message }));
+            child.on("close", (code) => resolve({ code, stdout: out, stderr: errText }));
+        });
+    }
+    exec(command, policy, opts) {
+        const container = `cruxy-sbx-${randomUUID()}`;
+        const argv = buildRunArgs(policy, container, command);
+        return this.run(argv, container, opts);
+    }
+    run(argv, container, opts) {
+        const startedAt = Date.now();
+        return new Promise((resolve, reject) => {
+            const capture = new OutputCapture(opts.maxOutputBytes, opts.capture);
+            let child;
+            try {
+                // `detached` groups the docker client so a timeout kills the whole tree.
+                child = spawn(this.bin, argv, { detached: true });
+            }
+            catch (err) {
+                reject(sandboxExec(err));
+                return;
+            }
+            child.stdout?.on("data", (b) => capture.push(b));
+            child.stderr?.on("data", (b) => capture.push(b));
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                killTree(child.pid);
+                // Killing the client may orphan the container — force-remove it too.
+                this.forceRemove(container);
+                const { output, truncated } = capture.result();
+                resolve({
+                    exitCode: null,
+                    output,
+                    outputTruncated: truncated,
+                    durationMs: Date.now() - startedAt,
+                    timedOut: true,
+                });
+            }, opts.timeoutMs);
+            child.on("error", (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(sandboxExec(err));
+            });
+            child.on("close", (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                // 125 = `docker run` itself failed (not the inner command) → the
+                // container never really started. Fail loud, never fabricate a result.
+                if (code === 125) {
+                    const { output } = capture.result();
+                    reject(sandboxExec(output.trim() || "docker run exited 125"));
+                    return;
+                }
+                const { output, truncated } = capture.result();
+                resolve({
+                    exitCode: code,
+                    output,
+                    outputTruncated: truncated,
+                    durationMs: Date.now() - startedAt,
+                    timedOut: false,
+                });
+            });
+        });
+    }
+    /** Best-effort container teardown after a timeout kill. */
+    forceRemove(container) {
+        try {
+            const rm = spawn(this.bin, ["rm", "-f", container], {
+                stdio: "ignore",
+                detached: true,
+            });
+            rm.on("error", () => { });
+            rm.unref();
+        }
+        catch {
+            // Nothing more we can do; the container may already be gone.
+        }
+    }
+}
+/**
+ * Build the `docker run` argv from a resolved policy. Pure and total — the
+ * single source of truth for the isolation boundary, asserted directly in
+ * tests. Order is stable for readability; docker is order-insensitive for flags.
+ */
+export function buildRunArgs(policy, container, command) {
+    return [
+        "run",
+        "--rm", // auto-remove the container when it exits
+        "--name",
+        container, // so a timeout can force-remove it
+        ...networkArgs(policy.network),
+        "--user",
+        policy.user, // non-root
+        "--read-only", // root filesystem is read-only …
+        "--tmpfs",
+        `${policy.tmpfs}:rw,nosuid,nodev,size=64m`, // … except an in-memory tmp
+        "-v",
+        mountSpec(policy.workdir), // ONLY the workdir, read-write
+        ...policy.mounts.flatMap((m) => ["-v", mountSpec(m)]),
+        "-w",
+        policy.workdir.target,
+        "--memory",
+        policy.memory,
+        "--memory-swap",
+        policy.memory, // == memory disables swap (no swap-escape of the cap)
+        "--pids-limit",
+        String(policy.pids),
+        "--cpus",
+        String(policy.cpus),
+        "--security-opt",
+        "no-new-privileges", // no setuid privilege escalation
+        "--cap-drop",
+        "ALL", // drop every Linux capability
+        policy.image,
+        "sh",
+        "-c",
+        command,
+    ];
+}
+/**
+ * Egress flags. `none` denies all network (the default). Widening is a
+ * deliberate act: `full` uses the default bridge; `host-loopback` adds a
+ * host-gateway alias (best-effort — strict loopback-only firewalling is left
+ * for a later build). Anything but `none` can only come from explicit config.
+ */
+function networkArgs(network) {
+    switch (network) {
+        case "none":
+            return ["--network", "none"];
+        case "host-loopback":
+            return [
+                "--network",
+                "bridge",
+                "--add-host",
+                "host.docker.internal:host-gateway",
+            ];
+        case "full":
+            return ["--network", "bridge"];
+    }
+}
+function mountSpec(m) {
+    return `${m.source}:${m.target}:${m.readonly ? "ro" : "rw"}`;
+}
+/**
+ * Bias-capped output capture: `head` keeps the START and stops once the cap is
+ * hit (matches `run_command`); `tail` keeps the END, where failures live
+ * (matches `run_tests`). Bounded memory either way.
+ */
+class OutputCapture {
+    cap;
+    bias;
+    chunks = [];
+    bytes = 0;
+    truncated = false;
+    constructor(cap, bias) {
+        this.cap = cap;
+        this.bias = bias;
+    }
+    push(buf) {
+        if (this.bias === "head") {
+            if (this.truncated)
+                return;
+            const room = this.cap - this.bytes;
+            if (buf.length <= room) {
+                this.chunks.push(buf);
+                this.bytes += buf.length;
+            }
+            else {
+                if (room > 0) {
+                    this.chunks.push(buf.subarray(0, room));
+                    this.bytes += room;
+                }
+                this.truncated = true;
+            }
+            return;
+        }
+        // tail: append, dropping whole head chunks while the remainder still meets
+        // the cap; a final exact trim happens in result().
+        this.chunks.push(buf);
+        this.bytes += buf.length;
+        while (this.chunks.length > 1 &&
+            this.bytes - this.chunks[0].length >= this.cap) {
+            this.bytes -= this.chunks[0].length;
+            this.chunks.shift();
+            this.truncated = true;
+        }
+    }
+    result() {
+        let all = Buffer.concat(this.chunks);
+        if (this.bias === "tail" && all.length > this.cap) {
+            all = all.subarray(all.length - this.cap);
+            this.truncated = true;
+        }
+        return { output: all.toString("utf8"), truncated: this.truncated };
+    }
+}
+/** Kill the docker client's process group (POSIX; matches run_command). */
+function killTree(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        // Already exited, or no group — nothing to kill.
+    }
+}

package/dist/sandbox/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export { detectDocker, resetDetectionCache } from "./detect.js";
+export type { RuntimeProbe } from "./detect.js";
+export { DockerRuntime, buildRunArgs } from "./docker-runtime.js";
+export { buildPolicy } from "./policy.js";
+export { SandboxService } from "./service.js";
+export type { SandboxReporter, SandboxServiceDeps } from "./service.js";

package/dist/sandbox/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export { detectDocker, resetDetectionCache } from "./detect.js";
+export { DockerRuntime, buildRunArgs } from "./docker-runtime.js";
+export { buildPolicy } from "./policy.js";
+export { SandboxService } from "./service.js";

package/dist/sandbox/policy.d.ts

@@ -0,0 +1,17 @@
+import type { SandboxConfig } from "../config/index.js";
+import type { IsolationPolicy } from "./types.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 declare function buildPolicy(cfg: SandboxConfig, cwd: string): IsolationPolicy;

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