@celestea/tools 2.7.1

package/dist/sandbox/bwrap.js

@@ -0,0 +1,159 @@
+/**
+ * `BwrapSandbox` — the OS-isolated provider (P2c), behind the same `Sandbox`
+ * seam as the userspace one, so `run_shell` changes no line.
+ *
+ * Layer order (outermost → innermost), mirroring W274 §8.1:
+ *
+ *   node spawn(detached)                        → own process group (group kill)
+ *     prlimit | /bin/sh 'ulimit …; exec'        → RLIMIT_CPU/AS/NPROC/FSIZE/…
+ *       bwrap --unshare-all --die-with-parent   → user/mount/pid/net/ipc/uts ns,
+ *         --ro-bind / / --dev /dev --proc /proc    read-only root, private /dev
+ *         --tmpfs /tmp | --share-net | --seccomp FD
+ *           /bin/sh -c <command>
+ *
+ * Two properties are non-negotiable and tested:
+ * - **argv order** (`bwrap-argv.ts`) — the W274 device regression;
+ * - **`--die-with-parent`** — orphan reaping when the Node parent is SIGKILLed
+ *   (W274 §6.3: 3 orphans → 0), which the userspace path cannot do at all.
+ *
+ * If bwrap turns out unusable at call time the run is **refused** with a
+ * structured `SandboxError`; degrading to userspace is the *policy* layer's
+ * explicit decision (`provider.ts`), never this provider's silent fallback.
+ */
+import { mkdir } from "node:fs/promises";
+import { SandboxError } from "@celestea/core";
+import { wrapChild } from "./child.js";
+import { sandboxConfigFromEnv, sanitizedEnv } from "./config.js";
+import { BWRAP_PROVIDER, buildBwrapCommand, bwrapLabel, DEFAULT_BWRAP_OPTIONS, } from "./bwrap-argv.js";
+import { captureRun, preview, resolveTimeout, spawnPlan, validateSandboxConfig } from "./launch.js";
+import { limitsForCpu, limitsFromEnv, resolveCpuSec } from "./limits.js";
+import { probeHost } from "./probe.js";
+import { applyLimits, rlimitDiagnostics, rlimitVia } from "./rlimit.js";
+import { openSeccompBlob } from "./seccomp.js";
+import { resolveWorkdir } from "./workdir.js";
+export class BwrapSandbox {
+    config;
+    probe;
+    limits;
+    options;
+    /** W885: injected platform view; `undefined` = the host's own defaults. */
+    shell;
+    rlimits;
+    seccompDir;
+    constructor(config, options = {}) {
+        this.config = config;
+        this.probe = options.probe ?? probeHost();
+        this.limits = options.limits ?? limitsFromEnv(process.env, this.probe.uidThreads);
+        this.options = { ...DEFAULT_BWRAP_OPTIONS, ...(options.run ?? {}) };
+        this.rlimits = options.rlimits ?? true;
+        this.seccompDir = options.seccompDir;
+        this.shell = options.shell;
+    }
+    static fromEnv(env = process.env) {
+        return new BwrapSandbox(sandboxConfigFromEnv(env), { probe: probeHost({ env }) });
+    }
+    async run(request) {
+        validateSandboxConfig(this.config);
+        const timeoutMs = resolveTimeout(this.config, request.timeoutMs);
+        const limits = this.limitsFor(request.cpuSec);
+        const { child, meta } = await this.launch(request.command, request.workdir, false, limits, request.noAddressSpaceLimit === true);
+        return captureRun(this.config, child, timeoutMs, meta);
+    }
+    async spawn(request) {
+        validateSandboxConfig(this.config);
+        const limits = this.limitsFor(request.cpuSec);
+        const { child, meta } = await this.launch(request.command, request.workdir, true, limits, request.noAddressSpaceLimit === true);
+        return { child: wrapChild(child, { detached: true }), sandbox: meta };
+    }
+    /** W6: the base limits with this call's `cpu_sec` merged in (clamped). */
+    limitsFor(cpuSec) {
+        return limitsForCpu(this.limits, resolveCpuSec(this.limits.cpuSec, cpuSec, this.config.maxCpuSec));
+    }
+    /** Isolation actually in force, without running anything (logs / health). */
+    describe(options = {}) {
+        const diag = rlimitDiagnostics(this.probe, this.rlimits, options.noAddressSpaceLimit === true);
+        return runtimeMeta(this.options, this.limits, this.probe, diag.via, diag.address_space_limited);
+    }
+    async launch(command, requestedWorkdir, withStdin, limits, noAddressSpaceLimit) {
+        this.assertUsable();
+        const workdir = await resolveWorkdir(this.config, requestedWorkdir);
+        // W880: the program dir must exist before bwrap can bind it; run_code
+        // normally creates it first, but a run_shell-only sandbox must not fail.
+        await mkdir(this.config.programDir, { recursive: true }).catch(() => undefined);
+        const binary = this.probe.bwrapPath;
+        const blob = this.options.seccomp ? openSeccompBlob(this.seccompDir) : null;
+        try {
+            const limited = applyLimits(binary, buildBwrapCommand(workdir, { ...this.options, programDir: this.config.programDir }, command), limits, this.probe, { enabled: this.rlimits, noAddressSpaceLimit });
+            const child = await spawnPlan({
+                program: limited.program,
+                args: limited.args,
+                workdir,
+                env: sanitizedEnv(this.config),
+                extraFds: blob === null ? [] : [blob.fd],
+                withStdin,
+                label: `${bwrapLabel(this.options)} ${preview(command, 128)}`,
+            });
+            const diag = rlimitDiagnostics(this.probe, this.rlimits, noAddressSpaceLimit);
+            return { child, meta: resultMeta(runtimeMeta(this.options, limits, this.probe, limited.via, diag.address_space_limited)) };
+        }
+        finally {
+            blob?.dispose();
+        }
+    }
+    assertUsable() {
+        if (this.probe.bwrapUsable && this.probe.bwrapPath !== null)
+            return;
+        const reason = this.probe.bwrapRejectReason ?? "bwrap reported unusable by the host probe";
+        throw new SandboxError("config", `sandbox_unavailable: ${reason} (fix the host, pin a binary with CELESTEA_SANDBOX_BWRAP, or set CELESTEA_SANDBOX_FALLBACK=userspace to degrade explicitly)`, { provider: BWRAP_PROVIDER, reason, bwrap_path: this.probe.bwrapPath });
+    }
+}
+/**
+ * Which rlimit mechanism the probe leaves available.
+ *
+ * F4: the implementation moved to `rlimit.ts` (where the limit plan lives);
+ * this re-export keeps the public path `@celestea/tools` -> `bwrap.js` stable.
+ */
+export { rlimitVia } from "./rlimit.js";
+function runtimeMeta(options, limits, probe, via, addressSpaceLimited) {
+    return {
+        provider: BWRAP_PROVIDER,
+        net_isolated: !options.shareNet,
+        tmp_private: !options.shareTmp,
+        seccomp: options.seccomp,
+        readonly_root: true,
+        address_space_limited: addressSpaceLimited,
+        rlimit_via: via,
+        cpu_sec: limits.cpuSec,
+        nproc: limits.nproc,
+        uid_threads: probe.uidThreads,
+        bwrap_version: probe.bwrapVersion,
+    };
+}
+/**
+ * The model-visible projection: EXACTLY the `SandboxMeta` seam contract
+ * (`provider`, `net_isolated`, `tmp_private`, `seccomp`, optional `cpu_sec`).
+ *
+ * Why this exists: [runtimeMeta] also carries host diagnostics (`bwrap_version`,
+ * `rlimit_via`, `uid_threads`, `nproc`, `readonly_root`) that are identical on
+ * every single call and are NOT part of the contract. Shipping them inside every
+ * `run_shell` result floods the caller's context with constants (the userspace
+ * provider never did — see `USERSPACE_SANDBOX_META`). Diagnostics stay available
+ * on [BwrapSandbox.describe] for logs / health, never inside a tool result.
+ */
+function resultMeta(meta) {
+    return {
+        provider: meta.provider,
+        net_isolated: meta.net_isolated,
+        tmp_private: meta.tmp_private,
+        seccomp: meta.seccomp,
+        ...(meta.cpu_sec === undefined ? {} : { cpu_sec: meta.cpu_sec }),
+    };
+}
+/** Factory with explicit knobs (tests / embeddings). */
+export function bwrapSandboxWith(config, options = {}) {
+    return new BwrapSandbox(config, options);
+}
+/** Env-tuned default (`selectSandbox` builds this only when bwrap is usable). */
+export function bwrapSandbox(config = sandboxConfigFromEnv()) {
+    return new BwrapSandbox(config);
+}

package/dist/sandbox/child.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `SandboxChild` over a `node:child_process` child.
+ *
+ * The wrapper gives every sandbox provider the same handle shape (pid + three
+ * streams + wait/terminate/kill), so the process registry never touches
+ * provider internals. Signals target the whole **process group** when the child
+ * was spawned detached — a shell that forked grandchildren must die with its
+ * tree, not leave orphans behind.
+ */
+import { type ChildProcess } from "node:child_process";
+import type { SandboxChild } from "@celestea/core";
+export interface WrapOptions {
+    /** Child was spawned with `detached: true` (it leads its own process group). */
+    detached: boolean;
+}
+export declare function wrapChild(child: ChildProcess, options: WrapOptions): SandboxChild;
+/** Best-effort signal of the child's whole process group (falls back to child). */
+export declare function signalTree(child: ChildProcess, options: WrapOptions, signal: NodeJS.Signals): void;
+/**
+ * W885 — Windows process-tree recycling, BEST EFFORT.
+ *
+ * Windows has no POSIX process group and Node's `child.kill()` signals only the
+ * DIRECT child (W883 B10), so a `cmd.exe` that forked grandchildren would leak
+ * them. `taskkill /T` walks the parent-child chain and is the only tool the OS
+ * ships for this, but it is NOT an atomic boundary — standard Windows: a child
+ * can re-parent or die between the walk and the kill (TOCTOU) — which is why the
+ * real fix is a **Job Object** and is deferred to W885 slice 2 (Job Objects +
+ * resource limits + the Windows sandbox provider).
+ *
+ * Slice-2 TODO: create the child inside a Job Object with
+ * `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` so the tree dies atomically with the
+ * parent, instead of racing `taskkill`. The behaviour here is therefore
+ * "best-effort", never a guarantee.
+ *
+ * NOT verifiable on this host (Linux): the branch selection is unit-tested
+ * (`child.test.ts` injects `platform`), the actual kill is not.
+ */
+export declare function taskkillTree(pid: number, platform?: string): boolean;

package/dist/sandbox/child.js

@@ -0,0 +1,98 @@
+/**
+ * `SandboxChild` over a `node:child_process` child.
+ *
+ * The wrapper gives every sandbox provider the same handle shape (pid + three
+ * streams + wait/terminate/kill), so the process registry never touches
+ * provider internals. Signals target the whole **process group** when the child
+ * was spawned detached — a shell that forked grandchildren must die with its
+ * tree, not leave orphans behind.
+ */
+import { execFileSync } from "node:child_process";
+import { isWindows } from "../platform/paths.js";
+export function wrapChild(child, options) {
+    let settled = null;
+    let resolveWait = null;
+    const waitPromise = new Promise((resolve) => {
+        resolveWait = resolve;
+    });
+    const settle = (exit) => {
+        if (settled !== null)
+            return;
+        settled = exit;
+        resolveWait?.(exit);
+    };
+    // `close` (not `exit`) fires once the stdio pipes are drained, so a reader
+    // that starts after `wait()` never loses buffered output.
+    child.once("close", (code, signal) => settle({ code, signal }));
+    child.once("error", (error) => settle({ code: null, signal: error.name }));
+    return {
+        pid: child.pid ?? null,
+        stdin: child.stdin,
+        stdout: child.stdout,
+        stderr: child.stderr,
+        wait: () => waitPromise,
+        terminate: () => signalTree(child, options, "SIGTERM"),
+        kill: () => signalTree(child, options, "SIGKILL"),
+    };
+}
+/** Best-effort signal of the child's whole process group (falls back to child). */
+export function signalTree(child, options, signal) {
+    const pid = child.pid;
+    if (pid !== undefined && options.detached && signalProcessGroup(pid, signal))
+        return;
+    signalChild(child, signal);
+}
+function signalProcessGroup(pid, signal) {
+    if (isWindows())
+        return taskkillTree(pid);
+    try {
+        // Negative pid targets the whole group: the child leads it (detached).
+        process.kill(-pid, signal);
+        return true;
+    }
+    catch {
+        return false; // group already gone, or not ours to signal
+    }
+}
+/**
+ * W885 — Windows process-tree recycling, BEST EFFORT.
+ *
+ * Windows has no POSIX process group and Node's `child.kill()` signals only the
+ * DIRECT child (W883 B10), so a `cmd.exe` that forked grandchildren would leak
+ * them. `taskkill /T` walks the parent-child chain and is the only tool the OS
+ * ships for this, but it is NOT an atomic boundary — standard Windows: a child
+ * can re-parent or die between the walk and the kill (TOCTOU) — which is why the
+ * real fix is a **Job Object** and is deferred to W885 slice 2 (Job Objects +
+ * resource limits + the Windows sandbox provider).
+ *
+ * Slice-2 TODO: create the child inside a Job Object with
+ * `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` so the tree dies atomically with the
+ * parent, instead of racing `taskkill`. The behaviour here is therefore
+ * "best-effort", never a guarantee.
+ *
+ * NOT verifiable on this host (Linux): the branch selection is unit-tested
+ * (`child.test.ts` injects `platform`), the actual kill is not.
+ */
+export function taskkillTree(pid, platform = process.platform) {
+    if (!isWindows(platform))
+        return false;
+    try {
+        execFileSync("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore", timeout: WINDOWS_TASKKILL_TIMEOUT_MS });
+        return true;
+    }
+    catch {
+        // taskkill missing, the pid already gone, or access denied: the caller
+        // falls back to `child.kill()`, which still stops the direct child.
+        return false;
+    }
+}
+/** taskkill is a local, bounded operation; never let it stall a timeout path. */
+const WINDOWS_TASKKILL_TIMEOUT_MS = 5_000;
+function signalChild(child, signal) {
+    try {
+        return child.kill(signal);
+    }
+    catch {
+        return false; // already reaped
+    }
+}

package/dist/sandbox/config.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Sandbox configuration and spawn plumbing for the userspace implementation
+ * (`crates/tools/src/sandbox.rs`, v1 userspace path).
+ *
+ * Everything an operator can tune is an env knob, read once per sandbox
+ * construction; the child environment is an **allowlist** (never the whole host
+ * environment, and deliberately never `HOME`: `~/.ssh`, `~/.aws`, `~/.gnupg`
+ * must not ride along).
+ */
+import { type SandboxConfig } from "@celestea/core";
+import { type ShellResolveInput } from "../platform/exec.js";
+/** Env var: default kill deadline in milliseconds. */
+export declare const ENV_SHELL_TIMEOUT_MS = "CELAESTEA_RUN_SHELL_TIMEOUT_MS";
+/** Env var: upper bound accepted for a per-call `timeout_ms`. */
+export declare const ENV_SHELL_MAX_TIMEOUT_MS = "CELESTEA_SHELL_MAX_TIMEOUT_MS";
+/** W6: env var for the upper bound accepted for a per-call `cpu_sec`. */
+export declare const ENV_SHELL_MAX_CPU_SEC = "CELESTEA_SHELL_MAX_CPU_SEC";
+/** Env var: per-stream output cap in bytes. */
+export declare const ENV_SHELL_MAX_OUTPUT_BYTES = "CELAESTEA_RUN_SHELL_MAX_OUTPUT_BYTES";
+/** Env var: fixed default workdir. */
+export declare const ENV_SHELL_WORKDIR = "CELAESTEA_RUN_SHELL_WORKDIR";
+/** Env var: canonical root every resolved workdir must stay inside. */
+export declare const ENV_SHELL_ROOT = "CELAESTEA_RUN_SHELL_ROOT";
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare const DEFAULT_MAX_TIMEOUT_MS = 300000;
+/** W6: `cpu_sec` above this is CLAMPED to it (not rejected). */
+export declare const DEFAULT_MAX_CPU_SEC = 600;
+export declare const DEFAULT_MAX_OUTPUT_BYTES: number;
+/** Host env vars passed through to the child (whitelist, not blacklist). */
+export declare const ENV_ALLOWLIST: readonly string[];
+/**
+ * W768: the per-SESSION filesystem scope. One value, resolved by the HOST from
+ * the session's own workspace record — never from a process-wide env knob —
+ * because a process serves several sessions and `process.cwd()` cannot describe
+ * more than one of them.
+ *
+ * `workspace` is both the default cwd of every spawned command and the root a
+ * workdir must stay inside, so "where am I" and "what may I touch" cannot
+ * disagree.
+ */
+export interface SessionFsScope {
+    /** Absolute, canonical workspace root of the session being composed. */
+    workspace: string;
+}
+export interface SandboxConfigOverrides {
+    timeoutMs?: number;
+    maxTimeoutMs?: number;
+    maxCpuSec?: number;
+    maxOutputBytes?: number;
+    workdir?: string;
+    root?: string;
+    /** W880: override the run_code program directory (tests / embeddings). */
+    programDir?: string;
+    extraEnv?: ReadonlyArray<readonly [string, string]>;
+}
+/**
+ * Configuration from `CELAESTEA_RUN_SHELL_*` / `CELESTEA_SHELL_MAX_TIMEOUT_MS`.
+ *
+ * W768: `overrides` is how a session's OWN workspace replaces the process-wide
+ * default. `workdir`/`root` are the only two knobs a session may set — the
+ * limits stay operator policy — and with no override the env reading is byte for
+ * byte what it always was (the fallback path for detached/legacy sessions).
+ */
+export declare function sandboxConfigFromEnv(env?: NodeJS.ProcessEnv, overrides?: SandboxConfigOverrides): SandboxConfig;
+/**
+ * W768: the sandbox config of ONE session — the session's workspace as cwd and
+ * root, the operator's limits unchanged. `null` scope = the env posture.
+ */
+export declare function sessionSandboxConfig(scope: SessionFsScope | null, env?: NodeJS.ProcessEnv): SandboxConfig;
+/** Materialize a config, filling defaults (tests pin explicit knobs). */
+export declare function buildSandboxConfig(overrides?: SandboxConfigOverrides): SandboxConfig;
+/**
+ * `{program, args}` of the platform shell carrying exactly one command.
+ *
+ * W885: the decision moved into the injectable `resolveShell` ladder —
+ * POSIX answers the literal `/bin/sh -c <command>` (byte-identical to the
+ * pre-W885 code, asserted by `platform-exec.test.ts`), Windows walks
+ * gitbash > pwsh > cmd. A host with no usable shell now fails closed with a
+ * structured [ShellNotFoundError] instead of guessing `cmd.exe`; the
+ * `input` seam is what lets the win32 ladder be unit-tested on Linux.
+ */
+export declare function shellInvocation(command: string, input?: ShellResolveInput): {
+    program: string;
+    args: string[];
+};
+/** Allowlisted host env plus explicit operator additions (never `HOME`). */
+export declare function sanitizedEnv(config: SandboxConfig, env?: NodeJS.ProcessEnv): Record<string, string>;
+/** Walk up from `start` looking for a git marker (dir `.git` or a worktree file). */
+export declare function gitToplevelOr(start: string): string;

package/dist/sandbox/config.js

@@ -0,0 +1,149 @@
+/**
+ * Sandbox configuration and spawn plumbing for the userspace implementation
+ * (`crates/tools/src/sandbox.rs`, v1 userspace path).
+ *
+ * Everything an operator can tune is an env knob, read once per sandbox
+ * construction; the child environment is an **allowlist** (never the whole host
+ * environment, and deliberately never `HOME`: `~/.ssh`, `~/.aws`, `~/.gnupg`
+ * must not ride along).
+ */
+import { realpathSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CELESTEA_RUN_CODE_DIR, workspaceSubdir } from "@celestea/core";
+import { envInt, envString } from "../env.js";
+import { resolveShell } from "../platform/exec.js";
+/** Env var: default kill deadline in milliseconds. */
+export const ENV_SHELL_TIMEOUT_MS = "CELAESTEA_RUN_SHELL_TIMEOUT_MS";
+/** Env var: upper bound accepted for a per-call `timeout_ms`. */
+export const ENV_SHELL_MAX_TIMEOUT_MS = "CELESTEA_SHELL_MAX_TIMEOUT_MS";
+/** W6: env var for the upper bound accepted for a per-call `cpu_sec`. */
+export const ENV_SHELL_MAX_CPU_SEC = "CELESTEA_SHELL_MAX_CPU_SEC";
+/** Env var: per-stream output cap in bytes. */
+export const ENV_SHELL_MAX_OUTPUT_BYTES = "CELAESTEA_RUN_SHELL_MAX_OUTPUT_BYTES";
+/** Env var: fixed default workdir. */
+export const ENV_SHELL_WORKDIR = "CELAESTEA_RUN_SHELL_WORKDIR";
+/** Env var: canonical root every resolved workdir must stay inside. */
+export const ENV_SHELL_ROOT = "CELAESTEA_RUN_SHELL_ROOT";
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const DEFAULT_MAX_TIMEOUT_MS = 300_000;
+/** W6: `cpu_sec` above this is CLAMPED to it (not rejected). */
+export const DEFAULT_MAX_CPU_SEC = 600;
+export const DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024;
+/** Host env vars passed through to the child (whitelist, not blacklist). */
+export const ENV_ALLOWLIST = [
+    "PATH",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TZ",
+    "TERM",
+    "USER",
+    "LOGNAME",
+    "SHELL",
+    "TMPDIR",
+    "PWD",
+];
+/**
+ * Configuration from `CELAESTEA_RUN_SHELL_*` / `CELESTEA_SHELL_MAX_TIMEOUT_MS`.
+ *
+ * W768: `overrides` is how a session's OWN workspace replaces the process-wide
+ * default. `workdir`/`root` are the only two knobs a session may set — the
+ * limits stay operator policy — and with no override the env reading is byte for
+ * byte what it always was (the fallback path for detached/legacy sessions).
+ */
+export function sandboxConfigFromEnv(env = process.env, overrides = {}) {
+    const workdir = resolveOrCwd(overrides.workdir ?? envString(env, ENV_SHELL_WORKDIR) ?? process.cwd());
+    return buildSandboxConfig({
+        timeoutMs: positive(envInt(env, ENV_SHELL_TIMEOUT_MS), DEFAULT_TIMEOUT_MS),
+        maxTimeoutMs: positive(envInt(env, ENV_SHELL_MAX_TIMEOUT_MS), DEFAULT_MAX_TIMEOUT_MS),
+        maxCpuSec: positive(envInt(env, ENV_SHELL_MAX_CPU_SEC), DEFAULT_MAX_CPU_SEC),
+        maxOutputBytes: positive(envInt(env, ENV_SHELL_MAX_OUTPUT_BYTES), DEFAULT_MAX_OUTPUT_BYTES),
+        workdir,
+        root: resolveOrCwd(overrides.root ?? envString(env, ENV_SHELL_ROOT) ?? gitToplevelOr(workdir)),
+        // W880: run_code programs live under CELESTEA_HOME, never in the workspace.
+        programDir: overrides.programDir ?? workspaceSubdir(workdir, CELESTEA_RUN_CODE_DIR, { env }),
+    });
+}
+/**
+ * W768: the sandbox config of ONE session — the session's workspace as cwd and
+ * root, the operator's limits unchanged. `null` scope = the env posture.
+ */
+export function sessionSandboxConfig(scope, env = process.env) {
+    if (scope === null)
+        return sandboxConfigFromEnv(env);
+    return sandboxConfigFromEnv(env, { workdir: scope.workspace, root: scope.workspace });
+}
+/** Materialize a config, filling defaults (tests pin explicit knobs). */
+export function buildSandboxConfig(overrides = {}) {
+    const workdir = resolveOrCwd(overrides.workdir ?? process.cwd());
+    return {
+        timeoutMs: overrides.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        maxTimeoutMs: overrides.maxTimeoutMs ?? DEFAULT_MAX_TIMEOUT_MS,
+        maxCpuSec: overrides.maxCpuSec ?? DEFAULT_MAX_CPU_SEC,
+        maxOutputBytes: overrides.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES,
+        workdir,
+        root: resolveOrCwd(overrides.root ?? gitToplevelOr(workdir)),
+        // Explicit construction (tests / embeddings) keeps the historical in-workspace
+        // default; the ENV posture above is the one that uses CELESTEA_HOME.
+        programDir: overrides.programDir ?? join(workdir, ".celestea", "run-code"),
+        extraEnv: overrides.extraEnv ?? [],
+    };
+}
+/**
+ * `{program, args}` of the platform shell carrying exactly one command.
+ *
+ * W885: the decision moved into the injectable `resolveShell` ladder —
+ * POSIX answers the literal `/bin/sh -c <command>` (byte-identical to the
+ * pre-W885 code, asserted by `platform-exec.test.ts`), Windows walks
+ * gitbash > pwsh > cmd. A host with no usable shell now fails closed with a
+ * structured [ShellNotFoundError] instead of guessing `cmd.exe`; the
+ * `input` seam is what lets the win32 ladder be unit-tested on Linux.
+ */
+export function shellInvocation(command, input = {}) {
+    const shell = resolveShell(command, input);
+    return { program: shell.path, args: [...shell.argv] };
+}
+/** Allowlisted host env plus explicit operator additions (never `HOME`). */
+export function sanitizedEnv(config, env = process.env) {
+    const out = {};
+    for (const name of ENV_ALLOWLIST) {
+        const value = env[name];
+        if (typeof value === "string" && value !== "")
+            out[name] = value;
+    }
+    for (const [name, value] of config.extraEnv)
+        out[name] = value;
+    return out;
+}
+/** Walk up from `start` looking for a git marker (dir `.git` or a worktree file). */
+export function gitToplevelOr(start) {
+    const pinned = resolveOrCwd(start);
+    let current = pinned;
+    for (;;) {
+        if (statOrNull(join(current, ".git")) !== null)
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return pinned; // filesystem root: fully pinned
+        current = parent;
+    }
+}
+function resolveOrCwd(target) {
+    try {
+        return realpathSync(target);
+    }
+    catch {
+        return target;
+    }
+}
+function statOrNull(target) {
+    try {
+        return statSync(target);
+    }
+    catch {
+        return null;
+    }
+}
+function positive(value, fallback) {
+    return value !== undefined && value > 0 ? value : fallback;
+}

package/dist/sandbox/fake-sandbox.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Fake `Sandbox` — a scripted, in-memory implementation of the seam.
+ *
+ * Purpose: prove the seam is genuinely replaceable (ARCHITECTURE.md §7.4) and
+ * let the tool pipeline and the process registry be tested without spawning any
+ * real process: stdout/stderr are synthetic streams, exits are scripted, and
+ * `terminate()` can be made deliberately ignorable so the SIGKILL escalation
+ * path is observable. It is a test double, not a production provider.
+ */
+import { PassThrough, Readable } from "node:stream";
+import type { Sandbox, SandboxChild, SandboxExit, SandboxMeta } from "@celestea/core";
+import { type SandboxConfigOverrides } from "./config.js";
+export interface FakeScript {
+    stdout?: readonly string[];
+    stderr?: readonly string[];
+    exitCode?: number | null;
+    /** ms before the child exits on its own; `Infinity` = never exits. */
+    exitAfterMs?: number;
+    /** true = `terminate()` is ignored (exercises the SIGKILL escalation). */
+    ignoresSigterm?: boolean;
+}
+export interface FakeSandboxOptions {
+    scripts?: readonly FakeScript[];
+    fallback?: FakeScript;
+    config?: SandboxConfigOverrides;
+    meta?: SandboxMeta;
+}
+export interface FakeSpawnRecord {
+    command: string;
+    workdir: string | undefined;
+    child: FakeChild;
+}
+/** Scripted child: synthetic pipes, scripted exit, observable signals. */
+export declare class FakeChild implements SandboxChild {
+    readonly pid: number;
+    readonly stdin: PassThrough;
+    readonly stdout: Readable;
+    readonly stderr: Readable;
+    readonly written: string[];
+    termAttempts: number;
+    killAttempts: number;
+    private resolved;
+    private resolveWait;
+    private readonly waited;
+    private readonly script;
+    constructor(pid: number, script: FakeScript);
+    wait(): Promise<SandboxExit>;
+    terminate(): void;
+    kill(): void;
+    private settle;
+}
+export interface FakeSandbox extends Sandbox {
+    readonly spawns: FakeSpawnRecord[];
+    readonly runs: string[];
+    readonly lastChild: FakeChild | null;
+}
+export declare function createFakeSandbox(options?: FakeSandboxOptions): FakeSandbox;