@celestea/tools 2.7.1

package/dist/sandbox/fake-sandbox.js

@@ -0,0 +1,110 @@
+/**
+ * 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 { SandboxError, USERSPACE_SANDBOX_META } from "@celestea/core";
+import { buildSandboxConfig } from "./config.js";
+/** Scripted child: synthetic pipes, scripted exit, observable signals. */
+export class FakeChild {
+    pid;
+    stdin = new PassThrough();
+    stdout;
+    stderr;
+    written = [];
+    termAttempts = 0;
+    killAttempts = 0;
+    resolved = null;
+    resolveWait = null;
+    waited;
+    script;
+    constructor(pid, script) {
+        this.pid = pid;
+        this.script = script;
+        this.stdout = Readable.from(script.stdout ?? []);
+        this.stderr = Readable.from(script.stderr ?? []);
+        this.stdin.on("data", (chunk) => this.written.push(chunk.toString("utf8")));
+        this.waited = new Promise((resolve) => {
+            this.resolveWait = resolve;
+        });
+        const delayMs = script.exitAfterMs ?? 0;
+        if (Number.isFinite(delayMs)) {
+            const timer = setTimeout(() => this.settle({ code: script.exitCode ?? 0, signal: null }), delayMs);
+            timer.unref?.();
+        }
+    }
+    wait() {
+        return this.waited;
+    }
+    terminate() {
+        this.termAttempts += 1;
+        if (this.script.ignoresSigterm === true)
+            return;
+        this.settle({ code: null, signal: "SIGTERM" });
+    }
+    kill() {
+        this.killAttempts += 1;
+        this.settle({ code: null, signal: "SIGKILL" });
+    }
+    settle(exit) {
+        if (this.resolved !== null)
+            return;
+        this.resolved = exit;
+        this.resolveWait?.(exit);
+    }
+}
+export function createFakeSandbox(options = {}) {
+    const config = buildSandboxConfig(options.config ?? {});
+    const meta = options.meta ?? USERSPACE_SANDBOX_META;
+    const scripts = [...(options.scripts ?? [])];
+    const spawns = [];
+    const runs = [];
+    let nextPid = 5000;
+    const take = () => scripts.shift() ?? options.fallback ?? {};
+    const child = (script) => {
+        nextPid += 1;
+        return new FakeChild(nextPid, script);
+    };
+    return {
+        config,
+        spawns,
+        runs,
+        get lastChild() {
+            return spawns.at(-1)?.child ?? null;
+        },
+        async run(request) {
+            const script = take();
+            runs.push(request.command);
+            const timeoutMs = request.timeoutMs ?? config.timeoutMs;
+            const delayMs = script.exitAfterMs ?? 0;
+            if (!Number.isFinite(delayMs) || delayMs > timeoutMs) {
+                throw new SandboxError("timeout", `killed pid ? after ${timeoutMs}ms (stdout_captured_bytes=0 stderr_captured_bytes=0)`, {
+                    timeout_ms: timeoutMs,
+                });
+            }
+            const stdout = clip((script.stdout ?? []).join(""), config.maxOutputBytes);
+            const stderr = clip((script.stderr ?? []).join(""), config.maxOutputBytes);
+            return {
+                stdout: stdout.text,
+                stderr: stderr.text,
+                exit_code: script.exitCode ?? 0,
+                stdout_truncated: stdout.truncated,
+                stderr_truncated: stderr.truncated,
+                sandbox: meta,
+            };
+        },
+        async spawn(request) {
+            const created = child(take());
+            spawns.push({ command: request.command, workdir: request.workdir, child: created });
+            return { child: created, sandbox: meta };
+        },
+    };
+}
+function clip(text, cap) {
+    return text.length <= cap ? { text, truncated: false } : { text: text.slice(0, cap), truncated: true };
+}

package/dist/sandbox/launch.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Provider-neutral process plumbing: spawn → capture → deadline → reap.
+ *
+ * Every sandbox provider (`userspace`, `bwrap`) differs only in *what* it
+ * execs; the hard parts are identical and live here so the two paths cannot
+ * drift:
+ * - the child leads its own **process group** (`detached`), so a timeout
+ *   SIGKILLs the whole tree, not just the leader;
+ * - each stream is drained to EOF while buffering at most `maxOutputBytes`
+ *   (a chatty child can never deadlock on a full pipe);
+ * - a timeout surfaces as a structured `SandboxError` carrying the captured
+ *   byte counts and output previews.
+ */
+import type { ChildProcess } from "node:child_process";
+import type { Readable } from "node:stream";
+import type { SandboxConfig, SandboxMeta, SandboxRunResult } from "@celestea/core";
+/** Grace allowed for a SIGKILLed child to be reaped before we stop waiting. */
+export declare const REAP_GRACE_MS = 5000;
+export interface SpawnPlan {
+    program: string;
+    args: readonly string[];
+    workdir: string;
+    env: Record<string, string>;
+    /** Extra fds passed to the child after stdio (index 3, 4, …). */
+    extraFds?: readonly number[];
+    /** stdin is piped for background children (`process_control` writes lines). */
+    withStdin: boolean;
+    /** Human-readable command for spawn-failure messages. */
+    label: string;
+}
+export declare function validateSandboxConfig(config: SandboxConfig): void;
+export declare function resolveTimeout(config: SandboxConfig, override: number | undefined): number;
+/** Spawn the plan; rejects with a structured `spawn` error, never a bare throw. */
+export declare function spawnPlan(plan: SpawnPlan): Promise<ChildProcess>;
+/** Enforce the deadline, cap both streams, and report the effective meta. */
+export declare function captureRun(config: SandboxConfig, child: ChildProcess, timeoutMs: number, meta: SandboxMeta): Promise<SandboxRunResult>;
+export interface CappedText {
+    text: string;
+    bytes: number;
+    truncated: boolean;
+}
+/**
+ * Drain a stream to EOF while buffering at most `cap` bytes. Bytes past the cap
+ * are read and discarded (never buffered) so a chatty child can still finish
+ * and its exit code stays observable.
+ */
+export declare function readCapped(stream: Readable | null, cap: number): Promise<CappedText>;
+/** Single-line, truncated preview for error messages (legacy `preview`). */
+export declare function preview(text: string, max: number): string;
+/** Signal the whole process group of a detached child (best effort). */
+export declare function killDetached(child: ChildProcess, signal: NodeJS.Signals): void;

package/dist/sandbox/launch.js

@@ -0,0 +1,134 @@
+/**
+ * Provider-neutral process plumbing: spawn → capture → deadline → reap.
+ *
+ * Every sandbox provider (`userspace`, `bwrap`) differs only in *what* it
+ * execs; the hard parts are identical and live here so the two paths cannot
+ * drift:
+ * - the child leads its own **process group** (`detached`), so a timeout
+ *   SIGKILLs the whole tree, not just the leader;
+ * - each stream is drained to EOF while buffering at most `maxOutputBytes`
+ *   (a chatty child can never deadlock on a full pipe);
+ * - a timeout surfaces as a structured `SandboxError` carrying the captured
+ *   byte counts and output previews.
+ */
+import { spawn } from "node:child_process";
+import { SandboxError } from "@celestea/core";
+import { TIMED_OUT, withTimeout } from "./async.js";
+import { signalTree, wrapChild } from "./child.js";
+/** Grace allowed for a SIGKILLed child to be reaped before we stop waiting. */
+export const REAP_GRACE_MS = 5_000;
+export function validateSandboxConfig(config) {
+    if (config.maxOutputBytes <= 0)
+        throw new SandboxError("config", "maxOutputBytes must be > 0");
+    if (config.timeoutMs <= 0)
+        throw new SandboxError("config", "timeoutMs must be > 0");
+    if (config.maxTimeoutMs <= 0)
+        throw new SandboxError("config", "maxTimeoutMs must be > 0");
+}
+export function resolveTimeout(config, override) {
+    if (override === undefined)
+        return config.timeoutMs;
+    if (override < 1)
+        throw new SandboxError("arg", `timeoutMs must be >= 1, got ${override}`);
+    if (override > config.maxTimeoutMs) {
+        throw new SandboxError("arg", `timeoutMs=${override} exceeds the sandbox maximum ${config.maxTimeoutMs}ms`);
+    }
+    return override;
+}
+/** Spawn the plan; rejects with a structured `spawn` error, never a bare throw. */
+export function spawnPlan(plan) {
+    const stdio = [
+        plan.withStdin ? "pipe" : "ignore",
+        "pipe",
+        "pipe",
+        ...(plan.extraFds ?? []),
+    ];
+    return new Promise((resolve, reject) => {
+        const child = spawn(plan.program, [...plan.args], {
+            cwd: plan.workdir,
+            env: plan.env,
+            stdio,
+            detached: true,
+        });
+        child.once("spawn", () => resolve(child));
+        child.once("error", (error) => {
+            reject(new SandboxError("spawn", `failed to start '${preview(plan.label, 256)}': ${error.message}`));
+        });
+    });
+}
+/** Enforce the deadline, cap both streams, and report the effective meta. */
+export async function captureRun(config, child, timeoutMs, meta) {
+    const sandboxed = wrapChild(child, { detached: true });
+    const outPromise = readCapped(child.stdout, config.maxOutputBytes);
+    const errPromise = readCapped(child.stderr, config.maxOutputBytes);
+    const exit = await withTimeout(sandboxed.wait(), timeoutMs);
+    if (exit === TIMED_OUT)
+        throw await timeoutFailure(sandboxed, outPromise, errPromise, timeoutMs);
+    const [stdout, stderr] = await Promise.all([outPromise, errPromise]);
+    return {
+        stdout: stdout.text,
+        stderr: stderr.text,
+        exit_code: exit.code,
+        signal: exit.signal,
+        stdout_truncated: stdout.truncated,
+        stderr_truncated: stderr.truncated,
+        sandbox: meta,
+    };
+}
+async function timeoutFailure(sandboxed, outPromise, errPromise, timeoutMs) {
+    sandboxed.kill();
+    await withTimeout(sandboxed.wait(), REAP_GRACE_MS);
+    const stdout = await outPromise;
+    const stderr = await errPromise;
+    const detail = {
+        pid: sandboxed.pid,
+        timeout_ms: timeoutMs,
+        stdout_captured: stdout.bytes,
+        stderr_captured: stderr.bytes,
+    };
+    return new SandboxError("timeout", `killed pid ${sandboxed.pid ?? "?"} after ${timeoutMs}ms (stdout_captured_bytes=${stdout.bytes} stderr_captured_bytes=${stderr.bytes} stdout_preview="${preview(stdout.text, 512)}" stderr_preview="${preview(stderr.text, 512)}")`, detail);
+}
+/**
+ * Drain a stream to EOF while buffering at most `cap` bytes. Bytes past the cap
+ * are read and discarded (never buffered) so a chatty child can still finish
+ * and its exit code stays observable.
+ */
+export async function readCapped(stream, cap) {
+    if (stream === null)
+        return { text: "", bytes: 0, truncated: false };
+    const chunks = [];
+    let size = 0;
+    let truncated = false;
+    try {
+        for await (const chunk of stream) {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+            const room = cap - size;
+            // B3 / W812 P2-1: exactly `cap` bytes is COMPLETE, not truncated; only a
+            // byte beyond the remaining capacity (or an already-full buffer) is.
+            if (buffer.length <= room) {
+                chunks.push(buffer);
+                size += buffer.length;
+                continue;
+            }
+            if (room > 0)
+                chunks.push(buffer.subarray(0, room));
+            size = cap;
+            truncated = true;
+        }
+    }
+    catch {
+        // A killed child tears its pipes down mid-read; the bytes captured so far
+        // are still the honest answer (the legacy path drains to EOF the same way).
+        return { text: Buffer.concat(chunks).toString("utf8"), bytes: size, truncated };
+    }
+    return { text: Buffer.concat(chunks).toString("utf8"), bytes: size, truncated };
+}
+/** Single-line, truncated preview for error messages (legacy `preview`). */
+export function preview(text, max) {
+    const folded = text.replace(/\r?\n/g, "\\n");
+    return folded.length > max ? `${folded.slice(0, max)}…` : folded;
+}
+/** Signal the whole process group of a detached child (best effort). */
+export function killDetached(child, signal) {
+    signalTree(child, { detached: true }, signal);
+}

package/dist/sandbox/limits.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Resource limits for the OS-isolated provider — and the `RLIMIT_NPROC` trap.
+ *
+ * `RLIMIT_NPROC` is **not** a per-sandbox process count: the kernel counts every
+ * thread owned by the *real UID across the whole host*. W274 §3.2 measured this
+ * the hard way: with 347 threads owned by uid 1003 on this machine, `--nproc`
+ * below that number makes bwrap fail to even `clone()` its pid-1
+ * (`Resource temporarily unavailable`), while the legacy default of 512 left only
+ * ~165 threads of slack before production commands start failing.
+ *
+ * So the cap is **derived at probe time**: `threads(uid) + headroom`, with a
+ * floor that also covers hosts where counting is impossible (non-Linux, no
+ * `/proc`). It stays a fork-bomb brake, it just stops being a time bomb.
+ */
+/** Env var: explicit `RLIMIT_NPROC` override (skips derivation). */
+export declare const ENV_SANDBOX_NPROC = "CELESTEA_SANDBOX_NPROC";
+/** Env var: slack added to the measured UID thread count (default 512). */
+export declare const ENV_SANDBOX_NPROC_HEADROOM = "CELESTEA_SANDBOX_NPROC_HEADROOM";
+/** Env var: `0` disables every rlimit (operator escape hatch). */
+export declare const ENV_SANDBOX_RLIMITS = "CELESTEA_SANDBOX_RLIMITS";
+/** Default slack above the measured thread count. */
+export declare const NPROC_HEADROOM = 512;
+/** Floor used when the thread count cannot be measured (and a sane minimum). */
+export declare const NPROC_FLOOR = 1024;
+/** The six limits the OS layer enforces (mirrors the legacy `V2Limits::default()`). */
+export interface SandboxLimits {
+    cpuSec: number;
+    memMb: number;
+    nproc: number;
+    fsizeBytes: number;
+    nofile: number;
+    core: boolean;
+}
+/** Legacy defaults, except `nproc` which is always derived (see module docs). */
+export declare const DEFAULT_LIMITS: Omit<SandboxLimits, "nproc">;
+/**
+ * Count every thread owned by `uid` on this host by summing
+ * `/proc/<pid>/task/*` for the pids that uid owns. Returns `null` when the
+ * answer cannot be established (non-Linux, no `/proc`, nothing readable).
+ */
+export declare function countUidThreads(uid?: number | null, procRoot?: string): number | null;
+/** `threads + headroom`, never below `floor` (see the module docs). */
+export declare function deriveNproc(threads: number | null, headroom?: number, floor?: number): number;
+/** Limits for one provider instance: measured `nproc` plus env overrides. */
+export declare function limitsFromEnv(env?: NodeJS.ProcessEnv, threads?: number | null): SandboxLimits;
+/** rlimits are on unless the operator explicitly turns them off. */
+export declare function rlimitsEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** W6: the resolved per-call CPU limit plus whether it was clamped. */
+export interface CpuResolution {
+    cpuSec: number;
+    clamped: boolean;
+    /** The raw request (null = the caller passed nothing). */
+    requested: number | null;
+}
+/**
+ * Resolve the effective `RLIMIT_CPU` for ONE call.
+ * - absent `requested` keeps `base` (the default, `DEFAULT_LIMITS.cpuSec` = 20);
+ * - above `max` is CLAMPED to `max` (`clamped: true`, documented, not an error);
+ * - a non-integer/below-1 value keeps `base` (the arg schema rejects it first).
+ */
+export declare function resolveCpuSec(base: number, requested: number | undefined, max: number): CpuResolution;
+/** The base limits with the resolved CPU limit merged in (identity when equal). */
+export declare function limitsForCpu(base: SandboxLimits, resolution: CpuResolution): SandboxLimits;

package/dist/sandbox/limits.js

@@ -0,0 +1,113 @@
+/**
+ * Resource limits for the OS-isolated provider — and the `RLIMIT_NPROC` trap.
+ *
+ * `RLIMIT_NPROC` is **not** a per-sandbox process count: the kernel counts every
+ * thread owned by the *real UID across the whole host*. W274 §3.2 measured this
+ * the hard way: with 347 threads owned by uid 1003 on this machine, `--nproc`
+ * below that number makes bwrap fail to even `clone()` its pid-1
+ * (`Resource temporarily unavailable`), while the legacy default of 512 left only
+ * ~165 threads of slack before production commands start failing.
+ *
+ * So the cap is **derived at probe time**: `threads(uid) + headroom`, with a
+ * floor that also covers hosts where counting is impossible (non-Linux, no
+ * `/proc`). It stays a fork-bomb brake, it just stops being a time bomb.
+ */
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { envFlag, envInt } from "../env.js";
+/** Env var: explicit `RLIMIT_NPROC` override (skips derivation). */
+export const ENV_SANDBOX_NPROC = "CELESTEA_SANDBOX_NPROC";
+/** Env var: slack added to the measured UID thread count (default 512). */
+export const ENV_SANDBOX_NPROC_HEADROOM = "CELESTEA_SANDBOX_NPROC_HEADROOM";
+/** Env var: `0` disables every rlimit (operator escape hatch). */
+export const ENV_SANDBOX_RLIMITS = "CELESTEA_SANDBOX_RLIMITS";
+/** Default slack above the measured thread count. */
+export const NPROC_HEADROOM = 512;
+/** Floor used when the thread count cannot be measured (and a sane minimum). */
+export const NPROC_FLOOR = 1024;
+/** Legacy defaults, except `nproc` which is always derived (see module docs). */
+export const DEFAULT_LIMITS = {
+    cpuSec: 20,
+    memMb: 2048,
+    fsizeBytes: 256 * 1024 * 1024,
+    nofile: 256,
+    core: true,
+};
+/**
+ * Count every thread owned by `uid` on this host by summing
+ * `/proc/<pid>/task/*` for the pids that uid owns. Returns `null` when the
+ * answer cannot be established (non-Linux, no `/proc`, nothing readable).
+ */
+export function countUidThreads(uid = currentUid(), procRoot = "/proc") {
+    if (uid === null || process.platform !== "linux")
+        return null;
+    const entries = readDir(procRoot);
+    let total = 0;
+    for (const entry of entries) {
+        if (isPid(entry))
+            total += threadsOf(join(procRoot, entry), uid);
+    }
+    return total > 0 ? total : null;
+}
+function currentUid() {
+    return typeof process.getuid === "function" ? process.getuid() : null;
+}
+function readDir(target) {
+    try {
+        return readdirSync(target);
+    }
+    catch {
+        return [];
+    }
+}
+function isPid(entry) {
+    const value = Number(entry);
+    return Number.isInteger(value) && value > 0 && entry === String(value);
+}
+function threadsOf(pidDir, uid) {
+    try {
+        if (statSync(pidDir).uid !== uid)
+            return 0;
+        return readdirSync(join(pidDir, "task")).length;
+    }
+    catch {
+        return 0; // the process vanished mid-scan (or is not ours to inspect)
+    }
+}
+/** `threads + headroom`, never below `floor` (see the module docs). */
+export function deriveNproc(threads, headroom = NPROC_HEADROOM, floor = NPROC_FLOOR) {
+    return Math.max(floor, (threads ?? 0) + headroom);
+}
+/** Limits for one provider instance: measured `nproc` plus env overrides. */
+export function limitsFromEnv(env = process.env, threads = countUidThreads()) {
+    const explicit = envInt(env, ENV_SANDBOX_NPROC);
+    const headroom = envInt(env, ENV_SANDBOX_NPROC_HEADROOM);
+    return {
+        ...DEFAULT_LIMITS,
+        nproc: explicit !== undefined && explicit > 0 ? explicit : deriveNproc(threads, headroom ?? NPROC_HEADROOM),
+    };
+}
+/** rlimits are on unless the operator explicitly turns them off. */
+export function rlimitsEnabled(env = process.env) {
+    return envFlag(env[ENV_SANDBOX_RLIMITS], true);
+}
+/**
+ * Resolve the effective `RLIMIT_CPU` for ONE call.
+ * - absent `requested` keeps `base` (the default, `DEFAULT_LIMITS.cpuSec` = 20);
+ * - above `max` is CLAMPED to `max` (`clamped: true`, documented, not an error);
+ * - a non-integer/below-1 value keeps `base` (the arg schema rejects it first).
+ */
+export function resolveCpuSec(base, requested, max) {
+    if (requested === undefined)
+        return { cpuSec: base, clamped: false, requested: null };
+    const raw = Math.trunc(requested);
+    if (!Number.isFinite(raw) || raw < 1)
+        return { cpuSec: base, clamped: false, requested };
+    if (raw > max)
+        return { cpuSec: max, clamped: true, requested: raw };
+    return { cpuSec: raw, clamped: false, requested: raw };
+}
+/** The base limits with the resolved CPU limit merged in (identity when equal). */
+export function limitsForCpu(base, resolution) {
+    return resolution.cpuSec === base.cpuSec ? base : { ...base, cpuSec: resolution.cpuSec };
+}

package/dist/sandbox/probe.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Host self-check (`probeHost`): what isolation can this machine actually give?
+ *
+ * The probe is deliberately *evidence-based*: bwrap is only "usable" after it
+ * has run the real mount sequence and read `/dev/zero` inside it (W274 §8.2).
+ * A binary that exists but cannot create a namespace (AppArmor tightening, a
+ * missing `bwrap-userns-restrict` exception, a deleted device node) must be
+ * reported as unusable — never assumed working, never assumed broken.
+ *
+ * The result is memoized per process (the probe costs two short `execFileSync`s)
+ * and is injectable, so policy tests never touch the host.
+ */
+/** Env var: explicit `bwrap` path (skips the PATH search). */
+export declare const ENV_SANDBOX_BWRAP = "CELESTEA_SANDBOX_BWRAP";
+export interface HostProbe {
+    readonly platform: NodeJS.Platform;
+    readonly bwrapPath: string | null;
+    readonly bwrapVersion: string | null;
+    /** true only after the ordered device smoke returned `ok`. */
+    readonly bwrapUsable: boolean;
+    /** Why the probe rejected bwrap (startup-log / degraded-reason material). */
+    readonly bwrapRejectReason: string | null;
+    readonly prlimitPath: string | null;
+    readonly shellUlimitWorks: boolean;
+    /** Threads owned by this uid host-wide → drives the `RLIMIT_NPROC` cap. */
+    readonly uidThreads: number | null;
+}
+export interface ProbeOptions {
+    env?: NodeJS.ProcessEnv;
+    /** Ignore (and replace) the memoized probe. */
+    refresh?: boolean;
+    /** Inject a uid thread count (tests); default: measure the host. */
+    uidThreads?: number | null;
+}
+/** Drop the memoized probe (tests, or after a host-level change). */
+export declare function resetProbeCache(): void;
+export declare function probeHost(options?: ProbeOptions): HostProbe;
+/**
+ * PATH lookup that honours an explicitly passed env (no global mutation).
+ *
+ * W885: split per PLATFORM delimiter and, on Windows, with `PATHEXT`
+ * suffixes — a Windows `PATH` is `;`-separated and its entries carry drive
+ * letters, so the old `split(":")` produced meaningless results there
+ * (W883 B13). `platform` is injectable so the win32 rule is testable on Linux.
+ */
+export declare function whichSync(bin: string, env?: NodeJS.ProcessEnv, platform?: string): string | null;

package/dist/sandbox/probe.js

@@ -0,0 +1,102 @@
+/**
+ * Host self-check (`probeHost`): what isolation can this machine actually give?
+ *
+ * The probe is deliberately *evidence-based*: bwrap is only "usable" after it
+ * has run the real mount sequence and read `/dev/zero` inside it (W274 §8.2).
+ * A binary that exists but cannot create a namespace (AppArmor tightening, a
+ * missing `bwrap-userns-restrict` exception, a deleted device node) must be
+ * reported as unusable — never assumed working, never assumed broken.
+ *
+ * The result is memoized per process (the probe costs two short `execFileSync`s)
+ * and is injectable, so policy tests never touch the host.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { whichInPath } from "../platform/exec.js";
+import { buildBwrapArgv, DEFAULT_BWRAP_OPTIONS } from "./bwrap-argv.js";
+import { countUidThreads } from "./limits.js";
+/** Env var: explicit `bwrap` path (skips the PATH search). */
+export const ENV_SANDBOX_BWRAP = "CELESTEA_SANDBOX_BWRAP";
+/** One-shot device smoke: read a device node that only exists if order is right. */
+const DEVICE_SMOKE = "exec 3</dev/zero 2>/dev/null && exec 4</dev/null && printf ok";
+/** One-shot ulimit probe: the zero-dependency rlimit fallback. */
+const ULIMIT_SMOKE = "ulimit -v 65536 2>/dev/null && ulimit -t 1 && printf ok";
+let cached = null;
+let cachedKey = null;
+/** Drop the memoized probe (tests, or after a host-level change). */
+export function resetProbeCache() {
+    cached = null;
+    cachedKey = null;
+}
+/** Cache key: the probe answer depends on these two env values and nothing else. */
+function cacheKey(env) {
+    return `${env[ENV_SANDBOX_BWRAP] ?? ""}\u0000${env["PATH"] ?? ""}`;
+}
+export function probeHost(options = {}) {
+    const env = options.env ?? process.env;
+    const key = cacheKey(env);
+    if (cached !== null && cachedKey === key && options.refresh !== true)
+        return cached;
+    cachedKey = key;
+    const bwrap = probeBwrap(env);
+    cached = {
+        platform: process.platform,
+        ...bwrap,
+        prlimitPath: whichSync("prlimit", env),
+        shellUlimitWorks: runOk("/bin/sh", ["-c", ULIMIT_SMOKE]).includes("ok"),
+        uidThreads: options.uidThreads === undefined ? countUidThreads() : options.uidThreads,
+    };
+    return cached;
+}
+function probeBwrap(env) {
+    const path = resolveBwrapPath(env);
+    if (path === null)
+        return reject("bwrap not found on PATH (set CELESTEA_SANDBOX_BWRAP to pin one)");
+    const version = run(path, ["--version"]);
+    if (!version.ok)
+        return reject(`${path} --version failed: ${version.out}`, path);
+    if (process.platform !== "linux")
+        return reject(`${path} reported ${version.out}, but this is not Linux`, path);
+    const smoke = run(path, [...buildBwrapArgv(null, DEFAULT_BWRAP_OPTIONS), "--", "/bin/sh", "-c", DEVICE_SMOKE]);
+    if (!smoke.out.includes("ok")) {
+        return reject(`device smoke failed (argv order regression?): ${smoke.out || "(no output)"}`, path);
+    }
+    return { bwrapPath: path, bwrapVersion: version.out, bwrapUsable: true, bwrapRejectReason: null };
+}
+function reject(reason, path = null) {
+    return { bwrapPath: path, bwrapVersion: null, bwrapUsable: false, bwrapRejectReason: reason };
+}
+function resolveBwrapPath(env) {
+    const pinned = env[ENV_SANDBOX_BWRAP];
+    if (pinned !== undefined && pinned.trim() !== "") {
+        const candidate = pinned.trim();
+        return existsSync(candidate) ? candidate : null;
+    }
+    return whichSync("bwrap", env);
+}
+/**
+ * PATH lookup that honours an explicitly passed env (no global mutation).
+ *
+ * W885: split per PLATFORM delimiter and, on Windows, with `PATHEXT`
+ * suffixes — a Windows `PATH` is `;`-separated and its entries carry drive
+ * letters, so the old `split(":")` produced meaningless results there
+ * (W883 B13). `platform` is injectable so the win32 rule is testable on Linux.
+ */
+export function whichSync(bin, env = process.env, platform = process.platform) {
+    return whichInPath(bin, platform, env);
+}
+/** Run a short probe command; never throws, folds stdout+stderr into `out`. */
+function run(file, args) {
+    try {
+        const out = execFileSync(file, [...args], { stdio: ["ignore", "pipe", "pipe"], timeout: 10_000 }).toString();
+        return { ok: true, out };
+    }
+    catch (error) {
+        const detail = error;
+        const out = `${detail.stdout?.toString() ?? ""}${detail.stderr?.toString() ?? ""}${detail.message ?? ""}`;
+        return { ok: false, out };
+    }
+}
+function runOk(file, args) {
+    return run(file, args).out;
+}