@celestea/tools 2.7.1

package/dist/sandbox/provider.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Provider policy — **which** sandbox a deployment gets, decided out loud.
+ *
+ * `bwrap` (probe-gated) → else `userspace`. The fallback is *explicit*:
+ * `CELESTEA_SANDBOX_FALLBACK=userspace` (default) degrades, while `=fail`
+ * refuses to run at all. That is the direct answer to the W268 lesson — the
+ * engine spent months on the weak userspace path because "bwrap unusable" was
+ * inferred from a broken probe and the degradation was never reported.
+ *
+ * Two consequences of "fail-closed" are deliberate:
+ * - an unrecognized `CELESTEA_SANDBOX_FALLBACK` value is an error, not a silent
+ *   return to the default (a typo must not decide the security posture);
+ * - the chosen provider always travels in `SandboxMeta` (`degraded`/`reason`
+ *   are available from `selectSandboxDetailed` for startup logs).
+ *
+ * Same env vocabulary as the engine contract (`contracts/tools.json`):
+ * `CELESTEA_SANDBOX_NET=1`, `CELESTEA_SANDBOX_SHARE_TMP=1`,
+ * `CELESTEA_SANDBOX_SECCOMP=1`, plus `CELESTEA_SANDBOX_MASK=<abs dirs>`.
+ */
+import type { Sandbox, SandboxConfig } from "@celestea/core";
+import { type BwrapOptions } from "./bwrap-argv.js";
+import { type HostProbe } from "./probe.js";
+/** Env var: `userspace` (default, degrade) | `fail` (refuse). */
+export declare const ENV_SANDBOX_FALLBACK = "CELESTEA_SANDBOX_FALLBACK";
+/** Env var: `1` keeps the host network namespace (contract knob). */
+export declare const ENV_SANDBOX_NET = "CELESTEA_SANDBOX_NET";
+/** Env var: `1` binds the host `/tmp` instead of a private tmpfs (contract knob). */
+export declare const ENV_SANDBOX_SHARE_TMP = "CELESTEA_SANDBOX_SHARE_TMP";
+/** Env var: `1` installs the TS cBPF whitelist (contract knob). */
+export declare const ENV_SANDBOX_SECCOMP = "CELESTEA_SANDBOX_SECCOMP";
+/** Env var: comma-separated absolute host dirs masked with an empty tmpfs. */
+export declare const ENV_SANDBOX_MASK = "CELESTEA_SANDBOX_MASK";
+export type SandboxFallbackMode = "userspace" | "fail";
+/**
+ * Session-grant view of the sandbox provider (W516). Structural: the tools
+ * package never imports the host's grants module.
+ */
+export interface SandboxGrantView {
+    /** `network`: keep the host network namespace even without the env knob. */
+    network?: boolean;
+    /** `unsandboxed`: accept the userspace provider although the mode is `fail`. */
+    unsandboxed?: boolean;
+    /** W9: the permission baseline's write capability (false = read-only). */
+    workspaceWritable?: boolean;
+    /** W9: extra absolute write roots to bind rw in the sandbox. */
+    writeRoots?: readonly string[];
+}
+export interface SelectOptions {
+    env?: NodeJS.ProcessEnv;
+    config?: SandboxConfig;
+    /** Inject a probe (tests); default: the memoized host probe. */
+    probe?: HostProbe;
+    /** Per-session grants (W516): widen only — see [bwrapOptionsFromEnv]. */
+    grants?: SandboxGrantView;
+}
+export interface SandboxSelection {
+    sandbox: Sandbox;
+    /** Provider that will actually execute commands. */
+    provider: string;
+    /** true when bwrap was unavailable and the userspace path was chosen. */
+    degraded: boolean;
+    /** Why bwrap was rejected (for the startup log); null when not degraded. */
+    reason: string | null;
+    mode: SandboxFallbackMode;
+    /**
+     * true when the userspace provider was chosen *because* the `unsandboxed`
+     * session grant overrode `CELESTEA_SANDBOX_FALLBACK=fail`. The host must
+     * record a `degraded_by_grant` audit line when it sees this (`§4.4`).
+     */
+    degradedByGrant: boolean;
+}
+/** The selected sandbox, ready to inject (`builtinTools`, plugin service). */
+export declare function selectSandbox(options?: SelectOptions): Sandbox;
+/** Selection plus the honest story of how it was made. */
+export declare function selectSandboxDetailed(options?: SelectOptions): SandboxSelection;
+/** Fallback policy; an unknown value is rejected (fail-closed, see module docs). */
+export declare function fallbackMode(env?: NodeJS.ProcessEnv): SandboxFallbackMode;
+/**
+ * bwrap knobs from the contract env vocabulary. W516: a session's `network`
+ * grant ORs into `shareNet` (and touches nothing else — `shareTmp`, `seccomp`,
+ * `maskDirs` and the rlimits stay exactly as the operator set them, §5.6).
+ */
+export declare function bwrapOptionsFromEnv(env?: NodeJS.ProcessEnv, grants?: SandboxGrantView): BwrapOptions;

package/dist/sandbox/provider.js

@@ -0,0 +1,126 @@
+/**
+ * Provider policy — **which** sandbox a deployment gets, decided out loud.
+ *
+ * `bwrap` (probe-gated) → else `userspace`. The fallback is *explicit*:
+ * `CELESTEA_SANDBOX_FALLBACK=userspace` (default) degrades, while `=fail`
+ * refuses to run at all. That is the direct answer to the W268 lesson — the
+ * engine spent months on the weak userspace path because "bwrap unusable" was
+ * inferred from a broken probe and the degradation was never reported.
+ *
+ * Two consequences of "fail-closed" are deliberate:
+ * - an unrecognized `CELESTEA_SANDBOX_FALLBACK` value is an error, not a silent
+ *   return to the default (a typo must not decide the security posture);
+ * - the chosen provider always travels in `SandboxMeta` (`degraded`/`reason`
+ *   are available from `selectSandboxDetailed` for startup logs).
+ *
+ * Same env vocabulary as the engine contract (`contracts/tools.json`):
+ * `CELESTEA_SANDBOX_NET=1`, `CELESTEA_SANDBOX_SHARE_TMP=1`,
+ * `CELESTEA_SANDBOX_SECCOMP=1`, plus `CELESTEA_SANDBOX_MASK=<abs dirs>`.
+ */
+import { isAbsolute } from "node:path";
+import { SandboxError } from "@celestea/core";
+import { BWRAP_PROVIDER, DEFAULT_BWRAP_OPTIONS } from "./bwrap-argv.js";
+import { BwrapSandbox } from "./bwrap.js";
+import { sandboxConfigFromEnv } from "./config.js";
+import { envFlag, envString } from "../env.js";
+import { limitsFromEnv, rlimitsEnabled } from "./limits.js";
+import { probeHost } from "./probe.js";
+import { UserspaceSandbox } from "./userspace.js";
+/** Env var: `userspace` (default, degrade) | `fail` (refuse). */
+export const ENV_SANDBOX_FALLBACK = "CELESTEA_SANDBOX_FALLBACK";
+/** Env var: `1` keeps the host network namespace (contract knob). */
+export const ENV_SANDBOX_NET = "CELESTEA_SANDBOX_NET";
+/** Env var: `1` binds the host `/tmp` instead of a private tmpfs (contract knob). */
+export const ENV_SANDBOX_SHARE_TMP = "CELESTEA_SANDBOX_SHARE_TMP";
+/** Env var: `1` installs the TS cBPF whitelist (contract knob). */
+export const ENV_SANDBOX_SECCOMP = "CELESTEA_SANDBOX_SECCOMP";
+/** Env var: comma-separated absolute host dirs masked with an empty tmpfs. */
+export const ENV_SANDBOX_MASK = "CELESTEA_SANDBOX_MASK";
+/** The selected sandbox, ready to inject (`builtinTools`, plugin service). */
+export function selectSandbox(options = {}) {
+    return selectSandboxDetailed(options).sandbox;
+}
+/** Selection plus the honest story of how it was made. */
+export function selectSandboxDetailed(options = {}) {
+    const env = options.env ?? process.env;
+    const mode = fallbackMode(env);
+    const grants = options.grants ?? {};
+    const probe = options.probe ?? probeHost({ env });
+    const config = options.config ?? sandboxConfigFromEnv(env);
+    if (probe.bwrapUsable && probe.bwrapPath !== null) {
+        const sandbox = new BwrapSandbox(config, {
+            probe,
+            limits: limitsFromEnv(env, probe.uidThreads),
+            // W516 §4.3.5: `unsandboxed` is IGNORED when bwrap works — isolation is
+            // already in effect and grants only ever add an escape when a policy
+            // refuses, never "less isolation than the host already provides".
+            run: bwrapOptionsFromEnv(env, grants),
+            rlimits: rlimitsEnabled(env),
+        });
+        return { sandbox, provider: BWRAP_PROVIDER, degraded: false, reason: null, mode, degradedByGrant: false };
+    }
+    const reason = probe.bwrapRejectReason ?? "bwrap reported unusable by the host probe";
+    if (mode === "fail") {
+        // §4.3.5: the ONE case `unsandboxed` is for — the policy would refuse, and
+        // the user explicitly asked (by clicking) for this session to run anyway.
+        if (grants.unsandboxed === true) {
+            return {
+                sandbox: new UserspaceSandbox(config, { probe, limits: limitsFromEnv(env, probe.uidThreads), rlimits: rlimitsEnabled(env) }),
+                provider: "userspace",
+                degraded: true,
+                reason: `${reason} — degraded by the 'unsandboxed' session grant`,
+                mode,
+                degradedByGrant: true,
+            };
+        }
+        throw new SandboxError("config", `sandbox_unavailable: ${reason} and ${ENV_SANDBOX_FALLBACK}=fail refuses to degrade to the userspace sandbox`, { provider: BWRAP_PROVIDER, reason, mode });
+    }
+    return {
+        sandbox: new UserspaceSandbox(config, { probe, limits: limitsFromEnv(env, probe.uidThreads), rlimits: rlimitsEnabled(env) }),
+        provider: "userspace",
+        degraded: true,
+        reason,
+        mode,
+        degradedByGrant: false,
+    };
+}
+/** Fallback policy; an unknown value is rejected (fail-closed, see module docs). */
+export function fallbackMode(env = process.env) {
+    const raw = envString(env, ENV_SANDBOX_FALLBACK)?.toLowerCase();
+    if (raw === undefined || raw === "userspace")
+        return "userspace";
+    if (raw === "fail")
+        return "fail";
+    throw new SandboxError("config", `invalid ${ENV_SANDBOX_FALLBACK}='${raw}' (expected 'userspace' or 'fail')`, {
+        value: raw,
+    });
+}
+/**
+ * bwrap knobs from the contract env vocabulary. W516: a session's `network`
+ * grant ORs into `shareNet` (and touches nothing else — `shareTmp`, `seccomp`,
+ * `maskDirs` and the rlimits stay exactly as the operator set them, §5.6).
+ */
+export function bwrapOptionsFromEnv(env = process.env, grants = {}) {
+    return {
+        shareNet: envFlag(env[ENV_SANDBOX_NET], DEFAULT_BWRAP_OPTIONS.shareNet) || grants.network === true,
+        shareTmp: envFlag(env[ENV_SANDBOX_SHARE_TMP], DEFAULT_BWRAP_OPTIONS.shareTmp),
+        seccomp: envFlag(env[ENV_SANDBOX_SECCOMP], DEFAULT_BWRAP_OPTIONS.seccomp),
+        maskDirs: parseMaskDirs(envString(env, ENV_SANDBOX_MASK)),
+        workspaceWritable: grants.workspaceWritable !== false,
+        writeRoots: [...(grants.writeRoots ?? [])],
+    };
+}
+function parseMaskDirs(raw) {
+    if (raw === undefined)
+        return [];
+    const dirs = raw
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry !== "");
+    for (const dir of dirs) {
+        if (!isAbsolute(dir) || dir === "/") {
+            throw new SandboxError("config", `invalid ${ENV_SANDBOX_MASK} entry '${dir}' (absolute, non-root paths only)`);
+        }
+    }
+    return dirs;
+}

package/dist/sandbox/rlimit.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The rlimit layer: `prlimit` when present, `/bin/sh` builtins when not.
+ *
+ * Limits are applied **outside** the namespace layer (on the bwrap process
+ * itself) and inherited by everything it forks, so a sandboxed tree cannot raise
+ * them back. Both mechanisms are equivalent (W274 §3.1/§3.3); the binary is
+ * preferred only because `prlimit --core=0` expresses "no core files" without
+ * shell quoting.
+ *
+ * Note `RLIMIT_NPROC` semantics: it counts threads of the whole real UID on the
+ * host (`limits.ts` derives the value accordingly) — a too-small value does not
+ * merely throttle the sandbox, it makes `clone()` fail for the sandbox launcher.
+ *
+ * F4: `RLIMIT_AS` is the ONE limit a modern Chromium cannot live under (it
+ * reserves an enormous virtual address space). [RlimitApplyOptions] therefore
+ * carries a per-call `noAddressSpaceLimit` that omits ONLY `--as=` /
+ * `ulimit -v`; every other limit stays. [rlimitDiagnostics] makes that exemption
+ * observable on the provider's `describe()` path without touching SandboxMeta.
+ */
+import type { SandboxLimits } from "./limits.js";
+import type { HostProbe } from "./probe.js";
+/** How the limits were enforced — reported, never guessed. */
+export type RlimitVia = "prlimit" | "shell-ulimit" | "none";
+export interface RlimitPlan {
+    program: string;
+    args: string[];
+    via: RlimitVia;
+}
+/** Which rlimit mechanism the probe leaves available. */
+export declare function rlimitVia(probe: HostProbe): RlimitVia;
+/** Per-call knobs for [applyLimits]. */
+export interface RlimitApplyOptions {
+    /** false disables EVERY rlimit (the operator escape hatch). Default true. */
+    enabled?: boolean;
+    /** true omits RLIMIT_AS only; every other limit stays. Default false. */
+    noAddressSpaceLimit?: boolean;
+}
+/** Diagnostic knobs for a provider's describe() path. */
+export interface RlimitDescribeOptions {
+    /** The answer for a call that WOULD pass noAddressSpaceLimit. Default false. */
+    noAddressSpaceLimit?: boolean;
+}
+/** Whether (and how) limits are in force — diagnostics, never SandboxMeta. */
+export interface RlimitDiagnostics {
+    via: RlimitVia;
+    rlimits_enabled: boolean;
+    address_space_limited: boolean;
+}
+/** Pure diagnostic projection (F4: makes an address-space exemption observable). */
+export declare function rlimitDiagnostics(probe: HostProbe, enabled: boolean, noAddressSpaceLimit: boolean): RlimitDiagnostics;
+/**
+ * Wrap `program args` with the strongest available rlimit mechanism.
+ *
+ * The 5th parameter accepts the legacy boolean ("enable every limit") OR
+ * [RlimitApplyOptions]. `false` / `{ enabled: false }` returns the command
+ * untouched; `{ noAddressSpaceLimit: true }` omits ONLY `RLIMIT_AS`.
+ */
+export declare function applyLimits(program: string, args: readonly string[], limits: SandboxLimits, probe: HostProbe, options?: boolean | RlimitApplyOptions): RlimitPlan;
+/** dash/bash `ulimit` form of the same six limits (RLIMIT_AS optional). */
+export declare function ulimitScript(limits: SandboxLimits, noAddressSpaceLimit?: boolean): string;

package/dist/sandbox/rlimit.js

@@ -0,0 +1,76 @@
+/**
+ * The rlimit layer: `prlimit` when present, `/bin/sh` builtins when not.
+ *
+ * Limits are applied **outside** the namespace layer (on the bwrap process
+ * itself) and inherited by everything it forks, so a sandboxed tree cannot raise
+ * them back. Both mechanisms are equivalent (W274 §3.1/§3.3); the binary is
+ * preferred only because `prlimit --core=0` expresses "no core files" without
+ * shell quoting.
+ *
+ * Note `RLIMIT_NPROC` semantics: it counts threads of the whole real UID on the
+ * host (`limits.ts` derives the value accordingly) — a too-small value does not
+ * merely throttle the sandbox, it makes `clone()` fail for the sandbox launcher.
+ *
+ * F4: `RLIMIT_AS` is the ONE limit a modern Chromium cannot live under (it
+ * reserves an enormous virtual address space). [RlimitApplyOptions] therefore
+ * carries a per-call `noAddressSpaceLimit` that omits ONLY `--as=` /
+ * `ulimit -v`; every other limit stays. [rlimitDiagnostics] makes that exemption
+ * observable on the provider's `describe()` path without touching SandboxMeta.
+ */
+import { SandboxError } from "@celestea/core";
+/** Which rlimit mechanism the probe leaves available. */
+export function rlimitVia(probe) {
+    if (probe.prlimitPath !== null)
+        return "prlimit";
+    return probe.shellUlimitWorks ? "shell-ulimit" : "none";
+}
+/** Pure diagnostic projection (F4: makes an address-space exemption observable). */
+export function rlimitDiagnostics(probe, enabled, noAddressSpaceLimit) {
+    return {
+        via: enabled ? rlimitVia(probe) : "none",
+        rlimits_enabled: enabled,
+        address_space_limited: enabled && !noAddressSpaceLimit,
+    };
+}
+/**
+ * Wrap `program args` with the strongest available rlimit mechanism.
+ *
+ * The 5th parameter accepts the legacy boolean ("enable every limit") OR
+ * [RlimitApplyOptions]. `false` / `{ enabled: false }` returns the command
+ * untouched; `{ noAddressSpaceLimit: true }` omits ONLY `RLIMIT_AS`.
+ */
+export function applyLimits(program, args, limits, probe, options = true) {
+    const { enabled, noAddressSpaceLimit } = normalizeApplyOptions(options);
+    if (!enabled)
+        return { program, args: [...args], via: "none" };
+    if (probe.prlimitPath !== null) {
+        return { program: probe.prlimitPath, args: [...prlimitArgs(limits, noAddressSpaceLimit), "--", program, ...args], via: "prlimit" };
+    }
+    if (probe.shellUlimitWorks) {
+        const script = ulimitScript(limits, noAddressSpaceLimit) + '; exec "$0" "$@"';
+        return { program: "/bin/sh", args: ["-c", script, program, ...args], via: "shell-ulimit" };
+    }
+    throw new SandboxError("config", "rlimits requested but neither the prlimit binary nor a shell with usable ulimit builtins is available", { prlimit: false, shellUlimit: false, nproc: limits.nproc });
+}
+function normalizeApplyOptions(options) {
+    if (typeof options === "boolean")
+        return { enabled: options, noAddressSpaceLimit: false };
+    return { enabled: options.enabled ?? true, noAddressSpaceLimit: options.noAddressSpaceLimit === true };
+}
+function prlimitArgs(limits, noAddressSpaceLimit = false) {
+    const args = ["--cpu=" + limits.cpuSec];
+    if (!noAddressSpaceLimit)
+        args.push("--as=" + limits.memMb * 1024 * 1024);
+    args.push("--nproc=" + limits.nproc, "--fsize=" + limits.fsizeBytes, "--nofile=" + limits.nofile, "--core=" + (limits.core ? 0 : "unlimited"));
+    return args;
+}
+/** dash/bash `ulimit` form of the same six limits (RLIMIT_AS optional). */
+// B3 / W812 P2-3: POSIX/dash ulimit -f counts 512-byte blocks while prlimit's
+// --fsize is bytes; dividing by 1024 halved the effective limit.
+export function ulimitScript(limits, noAddressSpaceLimit = false) {
+    const lines = ["ulimit -t " + limits.cpuSec];
+    if (!noAddressSpaceLimit)
+        lines.push("ulimit -v " + limits.memMb * 1024);
+    lines.push("ulimit -u " + limits.nproc, "ulimit -f " + Math.ceil(limits.fsizeBytes / 512), "ulimit -n " + limits.nofile, "ulimit -c " + (limits.core ? 0 : "unlimited"));
+    return lines.join("; ");
+}

package/dist/sandbox/seccomp.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Pure-TS cBPF seccomp whitelist (W274 §3.6), handed to `bwrap --seccomp FD`.
+ *
+ * Classic BPF needs no native addon and no helper process: 8 bytes per
+ * instruction (`u16 code | u8 jt | u8 jf | u32 k`, little-endian) written to a
+ * regular file whose fd is passed as fd 3. The instruction stream is a
+ * field-for-field port of the engine's `seccomp_v2` builder, so the two sandboxes
+ * deny the same syscalls.
+ *
+ * Semantics: x86_64 only; unknown arch → `EPERM`; x32-flagged numbers → `EPERM`;
+ * everything outside the whitelist → `EPERM`, except `clone3` → `ENOSYS` (so
+ * glibc falls back to `clone` instead of failing outright).
+ *
+ * Node needs four read-only metadata queries on top of the engine table
+ * (`51 getsockname` + `55 getsockopt` let libuv's `uv_guess_handle()` classify
+ * socket-backed stdio; `143 sched_getparam` + `145 sched_getscheduler` back
+ * `pthread_getschedparam`, which V8's absl mutex calls at startup). Without them
+ * Node does not fail loudly: `uv_guess_handle()` returns an unknown handle, the
+ * `process.stdout`/`stderr` objects get no libuv handle, and every write is
+ * dropped silently (W775).
+ *
+ * `53 socketpair` is the one addition that is not a metadata query: CPython's
+ * asyncio event loop builds its self-pipe with it. It stays a purely local IPC
+ * primitive — `socket(41)`, `connect(42)`, `bind(49)` and friends are still
+ * denied and the net namespace is unshared, so it grants no reach outside the
+ * sandbox (same family as the already-allowed `pipe2`/`eventfd2`).
+ */
+export interface BpfInstruction {
+    code: number;
+    jt: number;
+    jf: number;
+    k: number;
+}
+/** The full filter: 4 header/jump slots + 2 per allowed syscall + 3 tail slots. */
+export declare function buildSeccompFilter(): BpfInstruction[];
+/** Serialize to the blob `bwrap --seccomp FD` expects. */
+export declare function toBlobBytes(program?: BpfInstruction[]): Buffer;
+export declare function instructionCount(program?: BpfInstruction[]): number;
+export interface SeccompBlobHandle {
+    /** Open read-only fd, passed to the child as fd 3 (`--seccomp 3`). */
+    readonly fd: number;
+    dispose(): void;
+}
+/**
+ * Materialize the filter in a private temp file and open it. The caller must
+ * call `dispose()` after spawn (the child holds its own dup of the fd).
+ */
+export declare function openSeccompBlob(dir?: string): SeccompBlobHandle;

package/dist/sandbox/seccomp.js

@@ -0,0 +1,115 @@
+/**
+ * Pure-TS cBPF seccomp whitelist (W274 §3.6), handed to `bwrap --seccomp FD`.
+ *
+ * Classic BPF needs no native addon and no helper process: 8 bytes per
+ * instruction (`u16 code | u8 jt | u8 jf | u32 k`, little-endian) written to a
+ * regular file whose fd is passed as fd 3. The instruction stream is a
+ * field-for-field port of the engine's `seccomp_v2` builder, so the two sandboxes
+ * deny the same syscalls.
+ *
+ * Semantics: x86_64 only; unknown arch → `EPERM`; x32-flagged numbers → `EPERM`;
+ * everything outside the whitelist → `EPERM`, except `clone3` → `ENOSYS` (so
+ * glibc falls back to `clone` instead of failing outright).
+ *
+ * Node needs four read-only metadata queries on top of the engine table
+ * (`51 getsockname` + `55 getsockopt` let libuv's `uv_guess_handle()` classify
+ * socket-backed stdio; `143 sched_getparam` + `145 sched_getscheduler` back
+ * `pthread_getschedparam`, which V8's absl mutex calls at startup). Without them
+ * Node does not fail loudly: `uv_guess_handle()` returns an unknown handle, the
+ * `process.stdout`/`stderr` objects get no libuv handle, and every write is
+ * dropped silently (W775).
+ *
+ * `53 socketpair` is the one addition that is not a metadata query: CPython's
+ * asyncio event loop builds its self-pipe with it. It stays a purely local IPC
+ * primitive — `socket(41)`, `connect(42)`, `bind(49)` and friends are still
+ * denied and the net namespace is unshared, so it grants no reach outside the
+ * sandbox (same family as the already-allowed `pipe2`/`eventfd2`).
+ */
+import { closeSync, openSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const BPF_LD = 0x00;
+const BPF_W = 0x00;
+const BPF_ABS = 0x20;
+const BPF_JMP = 0x05;
+const BPF_JEQ = 0x10;
+const BPF_JGE = 0x30;
+const BPF_RET = 0x06;
+const BPF_K = 0x00;
+const AUDIT_ARCH_X86_64 = 0xc000_003e;
+const X32_BIT = 0x4000_0000;
+const RET_ALLOW = 0x7fff_0000;
+const RET_EPERM = 0x0005_0001;
+const RET_ENOSYS = 0x0005_0026;
+const SYSCALL_CLONE3 = 435;
+/** x86_64 syscall numbers the sandbox allows (engine `ALLOW` table). */
+const ALLOWED_SYSCALLS = [
+    0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28,
+    32, 33, 35, 38, 39, 40, 42, 51, 53, 55, 56, 57, 58, 59, 60, 61, 62, 63, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83,
+    84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 102, 104, 107, 108, 109, 110, 111, 112,
+    118, 120, 121, 131, 137, 138, 143, 145, 157, 158, 160, 186, 202, 203, 204, 217, 218, 219, 228, 229, 230, 231, 232, 233,
+    234, 235, 247, 253, 254, 255, 257, 258, 260, 261, 262, 263, 264, 265, 266, 267, 268, 269, 270, 271, 273, 274,
+    276, 280, 281, 282, 283, 284, 285, 286, 287, 288, 289, 290, 291, 292, 293, 294, 295, 296, 302, 306, 315, 318,
+    322, 324, 326, 327, 328, 332, 334, 437, 439, 452,
+];
+const stmt = (code, k) => ({ code, jt: 0, jf: 0, k });
+const jump = (code, jt, jf, k) => ({ code, jt, jf, k });
+/** The full filter: 4 header/jump slots + 2 per allowed syscall + 3 tail slots. */
+export function buildSeccompFilter() {
+    const program = [
+        stmt(BPF_LD | BPF_W | BPF_ABS, 4),
+        jump(BPF_JMP | BPF_JEQ | BPF_K, 0, 2, AUDIT_ARCH_X86_64),
+        stmt(BPF_LD | BPF_W | BPF_ABS, 0),
+        jump(BPF_JMP | BPF_JGE | BPF_K, 0, 1, X32_BIT),
+        stmt(BPF_RET | BPF_K, RET_EPERM),
+    ];
+    for (const nr of ALLOWED_SYSCALLS) {
+        program.push(jump(BPF_JMP | BPF_JEQ | BPF_K, 0, 1, nr), stmt(BPF_RET | BPF_K, RET_ALLOW));
+    }
+    program.push(jump(BPF_JMP | BPF_JEQ | BPF_K, 0, 1, SYSCALL_CLONE3), stmt(BPF_RET | BPF_K, RET_ENOSYS));
+    program.push(stmt(BPF_RET | BPF_K, RET_EPERM));
+    return program;
+}
+/** Serialize to the blob `bwrap --seccomp FD` expects. */
+export function toBlobBytes(program = buildSeccompFilter()) {
+    const out = Buffer.alloc(program.length * 8);
+    program.forEach((ins, i) => {
+        const at = i * 8;
+        out.writeUInt16LE(ins.code, at);
+        out.writeUInt8(ins.jt, at + 2);
+        out.writeUInt8(ins.jf, at + 3);
+        out.writeUInt32LE(ins.k >>> 0, at + 4);
+    });
+    return out;
+}
+export function instructionCount(program = buildSeccompFilter()) {
+    return program.length;
+}
+let counter = 0;
+/**
+ * Materialize the filter in a private temp file and open it. The caller must
+ * call `dispose()` after spawn (the child holds its own dup of the fd).
+ */
+export function openSeccompBlob(dir = tmpdir()) {
+    counter += 1;
+    const path = join(dir, `celestea-seccomp-${process.pid}-${Date.now()}-${counter}.bpf`);
+    writeFileSync(path, toBlobBytes(), { mode: 0o600 });
+    const fd = openSync(path, "r");
+    return {
+        fd,
+        dispose: () => {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* already closed */
+            }
+            try {
+                unlinkSync(path);
+            }
+            catch {
+                /* already gone */
+            }
+        },
+    };
+}

package/dist/sandbox/userspace.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `UserspaceSandbox` — the P2b implementation of the `Sandbox` seam, kept as the
+ * explicit **fallback** (and as the "no OS isolation at all" reference the
+ * tests compare against).
+ *
+ * It is honest about what it is: no namespaces, no seccomp, no private /tmp, and
+ * — W274 §6.2/§6.3 — a `setsid()`ing grandchild or a SIGKILLed Node parent leaks
+ * processes that the bwrap path reaps. What it does enforce, and what the tool
+ * contract depends on:
+ * - a fixed workdir that must resolve inside the configured root;
+ * - an allowlisted child environment (never the host environment, never HOME);
+ * - a kill deadline that SIGKILLs the whole process group;
+ * - per-stream output caps, with the truncation flag reported;
+ * - structured failures (`run_shell-sandbox: code=timeout|workdir|arg|config|spawn`).
+ *
+ * Which provider a deployment actually gets is decided in `provider.ts`; the
+ * OS-isolated one is `bwrap.ts`.
+ */
+import type { Sandbox, SandboxConfig, SandboxMeta, SandboxRunRequest, SandboxRunResult, SandboxShellLookup, SandboxSpawnRequest, SandboxSpawned } from "@celestea/core";
+import { type SandboxConfigOverrides } from "./config.js";
+import { type SandboxLimits } from "./limits.js";
+import { type HostProbe } from "./probe.js";
+import { type RlimitDescribeOptions, type RlimitVia } from "./rlimit.js";
+/** W6: the same rlimit layer the bwrap path uses (best-effort here). */
+export interface UserspaceSandboxOptions {
+    probe?: HostProbe;
+    limits?: SandboxLimits;
+    /** false disables every rlimit (operator escape hatch). */
+    rlimits?: boolean;
+    /** W885: the platform/shell view commands run under (defaults to the host). */
+    shell?: SandboxShellLookup;
+}
+/** The effective mode every result reports (never inferred by the caller). */
+export declare const USERSPACE_META: SandboxMeta;
+/**
+ * F4: the DIAGNOSTIC view (logs / health), never the model-visible contract.
+ * `address_space_limited` is how an AS exemption stays observable without
+ * adding a field to `SandboxMeta`.
+ */
+export interface UserspaceMeta extends SandboxMeta {
+    cpu_sec: number;
+    rlimit_via: RlimitVia;
+    address_space_limited: boolean;
+}
+export declare class UserspaceSandbox implements Sandbox {
+    readonly config: SandboxConfig;
+    readonly probe: HostProbe;
+    readonly limits: SandboxLimits;
+    /** W885: injected platform view; `undefined` = the host's own defaults. */
+    readonly shell: SandboxShellLookup | undefined;
+    private readonly rlimits;
+    constructor(config?: SandboxConfig, options?: UserspaceSandboxOptions);
+    static fromEnv(env?: NodeJS.ProcessEnv): UserspaceSandbox;
+    run(request: SandboxRunRequest): Promise<SandboxRunResult>;
+    spawn(request: SandboxSpawnRequest): Promise<SandboxSpawned>;
+    /** W6: the base limits with the per-call `cpu_sec` merged in (clamped). */
+    private limitsFor;
+    /** F4: diagnostic view of what would be enforced (never SandboxMeta). */
+    describe(options?: RlimitDescribeOptions): UserspaceMeta;
+    private launch;
+}
+/** Factory used by the policy layer as the explicit fallback. */
+export declare function userspaceSandbox(config?: SandboxConfig): UserspaceSandbox;
+/** Factory with explicit knobs (tests / embeddings). */
+export declare function userspaceSandboxWith(overrides: SandboxConfigOverrides): UserspaceSandbox;