@celestea/tools 2.7.1

package/dist/run-code/sdk.js

@@ -0,0 +1,294 @@
+/**
+ * The engine-injected Python SDK preamble + runner (W255).
+ *
+ * Byte-for-byte port of `RUN_CODE_SDK` / `RUN_CODE_RUNNER` in
+ * `crates/tools/src/run_code.rs` (the raw strings are re-encoded here as
+ * escape-safe template literals; `run-code/sdk.test.ts` re-extracts the
+ * blocks and diffs them, so drift cannot hide).
+ *
+ * The program the broker actually runs is `SDK + user code + RUNNER`:
+ *   - the SDK exposes exactly one object `tools` (four synchronous bridges) and
+ *     the catchable `ToolCallError`; every bridge call is a one-line JSON
+ *     request on stdout, answered by the parent on stdin;
+ *   - the runner calls `main()` (awaiting it when it is a coroutine) and emits
+ *     `{"__final__": <json>}` — or `{"__error__": "<Type>: <msg>"}` after
+ *     printing the traceback, exiting 1.
+ */
+/** The runner appended after the user program. */
+export const RUN_CODE_RUNNER = `
+# ======================= harness entry point (injected) =======================
+def _plain(v):
+    """Unwrap dual-interface results before JSON serialization (dict/list deep)."""
+    if isinstance(v, _Value):
+        v = v._v
+    if isinstance(v, dict):
+        return {k: _plain(x) for k, x in v.items()}
+    if isinstance(v, (list, tuple)):
+        return [_plain(x) for x in v]
+    return v
+
+
+import asyncio as _asyncio
+
+
+def _celestea_run_main():
+    main = globals().get("main")
+    if main is None:
+        raise RuntimeError(
+            "run_code: no 'main' defined - write the program as an async "
+            "function body, or as a complete script defining async def main()"
+        )
+    result = main()
+    if _asyncio.iscoroutine(result):
+        result = _asyncio.run(result)
+    return result
+
+
+try:
+    _final_value = _celestea_run_main()
+    print(_json.dumps({"__final__": _plain(_final_value)}, ensure_ascii=False), flush=True)
+except BaseException as _exc:  # report ANY failure as __error__
+    _tb = _traceback.format_exc()
+    for _line in _tb.rstrip("\\n").split("\\n"):
+        print(_line, flush=True)
+    print(
+        _json.dumps({"__error__": f"{type(_exc).__name__}: {_exc}"}, ensure_ascii=False),
+        flush=True,
+    )
+    _sys.exit(1)
+`;
+// W774: the TypeScript SDK/runner live in their own module (see `sdk-ts.ts`) and
+// are re-exported here so a caller can reach both languages from one place.
+export { RUN_CODE_RUNNER_TS, RUN_CODE_SDK_TS } from "./sdk-ts.js";
+import { RUN_CODE_RUNNER_TS, RUN_CODE_SDK_TS } from "./sdk-ts.js";
+/** The SDK preamble (standard library only; zero pip). */
+export const RUN_CODE_SDK = `# =============================================================================
+# celestea run_code SDK (W255 P0) - engine-injected preamble. Standard library
+# only (zero pip). Runs under \`python3 -uB <file>\` inside the Celestea
+# execution sandbox; the parent engine (the "broker") reads our protocol lines
+# from stdout and writes replies to stdin.
+#
+# Protocol (one JSON object per line, no other framing):
+#   child -> parent   {"id": <int>, "tool": "<name>", "args": {...}}
+#   parent -> child   {"id": <int>, "ok": true, "value": <json>, "truncated": <bool>}
+#                     {"id": <int>, "ok": false, "error": "<message>"}
+#   child -> parent   {"__final__": <json>}      (normal end: main()'s return)
+#                     {"__error__": "<message>"} (uncaught exception)
+#
+# Contract:
+#   - Write the program as an \`async def main():\` FUNCTION BODY, or as a
+#     complete script that defines main. main()'s return value (lossless JSON)
+#     is the final result of the run.
+#   - \`tools.<name>(**args)\` (also \`tools.<name>({"path": ...})\`) is a
+#     SYNCHRONOUS bridge: every sub-call is dispatched by the parent through
+#     its normal tool pipeline (guards, schema checks, limits). A failure
+#     raises ToolCallError - catch it and continue.
+#   - Only print what the model needs (stdout logs are budgeted at 64KiB);
+#     intermediate tool results never enter the conversation automatically.
+#   - Sub-calls run SERIALLY in P0: Python-side concurrency (the Promise.all
+#     equivalent for independent read-only calls) is a documented follow-up.
+#   - Exposed tools: read_file / write_file / list_dir / run_shell. Any other
+#     name (including run_code itself) is rejected by the parent.
+#   - Do not read sys.stdin and do not add an \`if __name__ == "__main__"\`
+#     block: stdin is the protocol reply channel and this harness is the
+#     entry point.
+# =============================================================================
+import sys as _sys
+import json as _json
+import traceback as _traceback
+
+
+class ToolCallError(Exception):
+    """A bridged tool call failed (guard denial, unknown tool, dispatch
+    error, limit exceeded). Catchable: the program may recover and continue."""
+
+    def __init__(self, tool_name, message):
+        super().__init__(f"tool '{tool_name}' failed: {message}")
+        self.tool_name = tool_name
+
+
+_sub_call_id = 0
+
+
+def _bridge_call(tool, args):
+    global _sub_call_id
+    _sub_call_id += 1
+    request_id = _sub_call_id
+    try:
+        payload = _json.dumps(
+            {"id": request_id, "tool": tool, "args": args}, ensure_ascii=False
+        )
+    except (TypeError, ValueError) as exc:
+        raise ToolCallError(tool, f"arguments are not JSON-serializable: {exc}")
+    print(payload, flush=True)
+    line = _sys.stdin.readline()
+    if not line:
+        raise ToolCallError(tool, "the parent broker closed the reply channel (run aborted)")
+    try:
+        reply = _json.loads(line)
+    except ValueError as exc:
+        raise ToolCallError(tool, f"malformed reply from the parent broker: {exc}")
+    if reply.get("id") != request_id:
+        raise ToolCallError(
+            tool, f"reply id mismatch (expected {request_id}, got {reply.get('id')})"
+        )
+    if not reply.get("ok", False):
+        raise ToolCallError(tool, reply.get("error", "unknown error"))
+    return _Value(_attr(reply.get("value")))
+
+
+class _AttrDict(dict):
+    """dict whose keys are also attributes: s.stdout == s['stdout'].
+    Models write both styles; both must work, including AFTER \`await\`."""
+
+    def __getattr__(self, name):
+        try:
+            return self[name]
+        except KeyError:
+            raise AttributeError(name)
+
+
+def _attr(v):
+    """Recursively convert decoded JSON dicts/lists so every dict in a tool
+    result is an _AttrDict (attribute access everywhere, at any depth)."""
+    if isinstance(v, dict):
+        return _AttrDict({k: _attr(x) for k, x in v.items()})
+    if isinstance(v, list):
+        return [_attr(x) for x in v]
+    return v
+
+
+class _Value:
+    """Dual-interface tool result: usable directly (indexing/iteration/str)
+    AND awaitable. Models write both styles — \`await tools.list_dir(...)\`
+    and \`tools.list_dir(...)\` must behave identically."""
+
+    def __init__(self, v):
+        self._v = v
+
+    def __await__(self):
+        # Correct awaitable protocol: yield NOTHING and RETURN the value.
+        # (Yielding the value itself makes asyncio treat it as an awaitable
+        #  and dict/list results blow up with "Task got bad yield".)
+        if False:
+            yield
+        return self._v
+
+    def __iter__(self):
+        return iter(self._v)
+
+    def __getitem__(self, k):
+        return self._v[k]
+
+    def __len__(self):
+        return len(self._v)
+
+    def __bool__(self):
+        return bool(self._v)
+
+    def __str__(self):
+        return str(self._v)
+
+    def __repr__(self):
+        return repr(self._v)
+
+    def __eq__(self, other):
+        if isinstance(other, _Value):
+            other = other._v
+        return self._v == other
+
+    def get(self, *a, **k):
+        return self._v.get(*a, **k) if hasattr(self._v, "get") else None
+
+    def __getattr__(self, name):
+        # Method passthrough (splitlines, keys, ...) so the wrapper behaves
+        # exactly like the wrapped value in normal code paths.
+        return getattr(self._v, name)
+
+
+def _merge_args(positional, kwargs, tool):
+    if positional:
+        if len(positional) == 1 and isinstance(positional[0], dict):
+            merged = dict(positional[0])
+            merged.update(kwargs)
+            return merged
+        raise ToolCallError(tool, "expected a single dict argument and/or keyword arguments")
+    return dict(kwargs)
+
+
+class _Tools:
+    """The SDK tool surface: only these four tools are bridged to the parent
+    (read_file / write_file / list_dir / run_shell)."""
+
+    def read_file(self, *args, **kwargs):
+        return _bridge_call("read_file", _merge_args(args, kwargs, "read_file"))
+
+    def write_file(self, *args, **kwargs):
+        return _bridge_call("write_file", _merge_args(args, kwargs, "write_file"))
+
+    def list_dir(self, *args, **kwargs):
+        return _bridge_call("list_dir", _merge_args(args, kwargs, "list_dir"))
+
+    def run_shell(self, *args, **kwargs):
+        # Returns the full result dict: {"exit_code", "stdout", "stderr", ...}.
+        # Fields are readable both ways: s['stdout'] AND s.stdout, before or
+        # after \`await\` (results are _AttrDict at any depth).
+        return _bridge_call("run_shell", _merge_args(args, kwargs, "run_shell"))
+
+
+tools = _Tools()
+`;
+/** What `run_code` runs when the call omits `language`. */
+export const DEFAULT_RUN_CODE_LANGUAGE = "typescript";
+/**
+ * Assemble the program file for one language: SDK preamble + user code + runner.
+ *
+ * When the first non-blank line of the user code is indented it is treated as a
+ * **function body** and wrapped (`async def main():` / `async function main()`);
+ * otherwise it must be a complete script defining `main` itself (legacy
+ * `assemble_program`). The Python path is byte-for-byte what it always was; the
+ * TypeScript path lays the file out the same way and deliberately does NOT
+ * re-indent a wrapped body — JavaScript does not need it, and re-indenting would
+ * rewrite the contents of a template literal.
+ */
+export function assembleProgram(userCode, language) {
+    const body = firstNonblankLineIndented(userCode);
+    if (language === "python") {
+        const parts = [RUN_CODE_SDK, "\n\n# ========================== user program ==========================\n"];
+        parts.push(body ? wrapBody(userCode) : terminate(userCode));
+        parts.push(RUN_CODE_RUNNER);
+        return parts.join("");
+    }
+    const parts = [RUN_CODE_SDK_TS, "\n\n// ========================== user program ==========================\n"];
+    parts.push(body ? wrapBodyTs(userCode) : terminate(userCode));
+    parts.push(RUN_CODE_RUNNER_TS);
+    return parts.join("");
+}
+/** `async function main() {` + the user body verbatim + `}`. */
+function wrapBodyTs(userCode) {
+    return `async function main() {\n${terminate(userCode)}}\n`;
+}
+/** True when the first non-blank line starts with whitespace (body form). */
+export function firstNonblankLineIndented(code) {
+    const line = splitProgramLines(code).find((candidate) => candidate.trim() !== "");
+    return line !== undefined && (line.startsWith(" ") || line.startsWith("\t"));
+}
+/** `async def main():` + the user body, indented one level (blank lines kept). */
+function wrapBody(userCode) {
+    const out = ["async def main():\n"];
+    for (const line of splitProgramLines(userCode)) {
+        out.push(line.trim() === "" ? "\n" : `    ${line}\n`);
+    }
+    out.push("\n");
+    return out.join("");
+}
+function terminate(userCode) {
+    return userCode.endsWith("\n") ? userCode : `${userCode}\n`;
+}
+/** Split on `\n`, drop a trailing `\r`, no final empty line. */
+function splitProgramLines(code) {
+    const lines = code.split("\n");
+    if (lines.length > 0 && lines[lines.length - 1] === "")
+        lines.pop();
+    return lines.map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
+}

package/dist/sandbox/async.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Small async helpers shared by the sandbox and the process registry: a
+ * timeout race (without leaking timers) and a bounded poll.
+ */
+/** Sentinel returned by [withTimeout] when the deadline won the race. */
+export declare const TIMED_OUT: unique symbol;
+export type TimeoutResult<T> = T | typeof TIMED_OUT;
+/** Race a promise against a deadline; the timer is always cleared. */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<TimeoutResult<T>>;
+export declare function delay(ms: number): Promise<void>;

package/dist/sandbox/async.js

@@ -0,0 +1,26 @@
+/**
+ * Small async helpers shared by the sandbox and the process registry: a
+ * timeout race (without leaking timers) and a bounded poll.
+ */
+/** Sentinel returned by [withTimeout] when the deadline won the race. */
+export const TIMED_OUT = Symbol("timed-out");
+/** Race a promise against a deadline; the timer is always cleared. */
+export async function withTimeout(promise, timeoutMs) {
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(TIMED_OUT), timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, deadline]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+export function delay(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}

package/dist/sandbox/bwrap-argv.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The bubblewrap argv builder — **the whole point of P2c is in this order**.
+ *
+ * W274 §2 diagnosed the engine's "bubblewrap is unusable" verdict as a pure
+ * argument-order bug: bwrap stacks mounts in argv order, so
+ * `--dev /dev --ro-bind / /` builds a private devtmpfs and then buries it under
+ * a read-only bind of the *host* root — `/dev/zero` becomes `EACCES` and the
+ * startup probe wrongly reports "no bwrap" (production then silently ran on the
+ * userspace path for months).
+ *
+ *   --unshare-all → --ro-bind / / → --dev /dev → --proc /proc
+ *
+ * is the only shape that passes the device smoke test, so it is asserted by a
+ * regression test (`bwrap.test.ts`) rather than trusted to reviewers.
+ */
+import type { SandboxMeta } from "@celestea/core";
+import { type ShellResolveInput } from "../platform/exec.js";
+/** Provider name reported in every `SandboxMeta` from this layer. */
+export declare const BWRAP_PROVIDER = "bwrap";
+/** Child fd of the seccomp blob: the first fd after stdin/stdout/stderr. */
+export declare const SECCOMP_FD = 3;
+export interface BwrapOptions {
+    /** true → `--share-net` (host network kept). Default: isolated. */
+    readonly shareNet: boolean;
+    /** true → host `/tmp` bind-mounted. Default: private tmpfs. */
+    readonly shareTmp: boolean;
+    /** true → install the TS-built cBPF whitelist via `--seccomp`. */
+    readonly seccomp: boolean;
+    /** Absolute host directories masked with an empty tmpfs (opt-in). */
+    readonly maskDirs: readonly string[];
+    /** W9: bind the workspace rw (default true; false = a read-only permission). */
+    readonly workspaceWritable?: boolean;
+    /** W9: extra absolute dirs to bind rw (permission tool roots / write_roots). */
+    readonly writeRoots?: readonly string[];
+    /**
+     * W880: the `run_code` program directory. It now lives under CELESTEA_HOME
+     * (outside the workspace), so it must be bound into the namespace — AFTER the
+     * private `/tmp` tmpfs, or a CELESTEA_HOME under `/tmp` would stay hidden.
+     */
+    readonly programDir?: string;
+}
+/** Contract default: network isolated, `/tmp` private, no seccomp, no masks. */
+export declare const DEFAULT_BWRAP_OPTIONS: BwrapOptions;
+/**
+ * Mount/namespace flags, in the one order that works. `workdir === null` is the
+ * probe shape (no bind, no chdir) so the smoke test exercises exactly the mount
+ * sequence production uses.
+ */
+export declare function buildBwrapArgv(workdir: string | null, options: BwrapOptions): string[];
+/**
+ * The full `bwrap … -- <shell> <args…> <command>` argv (workdir bind included).
+ *
+ * W885: the shell is RESOLVED, not the hardcoded `/bin/sh` — bwrap only exists
+ * on Linux today, so the POSIX answer is unchanged (this slice changes no Linux
+ * byte), but the gitbash/pwsh/cmd ladder is what a future Windows provider would
+ * consult. A host with no usable shell fails closed through [resolveShell].
+ */
+export declare function buildBwrapCommand(workdir: string, options: BwrapOptions, command: string, input?: ShellResolveInput): string[];
+/** The isolation actually in force — reported, never inferred by the caller. */
+export declare function bwrapMeta(options: BwrapOptions): SandboxMeta;
+/** Human-readable label for spawn failures (never contains the command body). */
+export declare function bwrapLabel(options: BwrapOptions): string;

package/dist/sandbox/bwrap-argv.js

@@ -0,0 +1,113 @@
+/**
+ * The bubblewrap argv builder — **the whole point of P2c is in this order**.
+ *
+ * W274 §2 diagnosed the engine's "bubblewrap is unusable" verdict as a pure
+ * argument-order bug: bwrap stacks mounts in argv order, so
+ * `--dev /dev --ro-bind / /` builds a private devtmpfs and then buries it under
+ * a read-only bind of the *host* root — `/dev/zero` becomes `EACCES` and the
+ * startup probe wrongly reports "no bwrap" (production then silently ran on the
+ * userspace path for months).
+ *
+ *   --unshare-all → --ro-bind / / → --dev /dev → --proc /proc
+ *
+ * is the only shape that passes the device smoke test, so it is asserted by a
+ * regression test (`bwrap.test.ts`) rather than trusted to reviewers.
+ */
+import { resolveShell } from "../platform/exec.js";
+/** Provider name reported in every `SandboxMeta` from this layer. */
+export const BWRAP_PROVIDER = "bwrap";
+/** Child fd of the seccomp blob: the first fd after stdin/stdout/stderr. */
+export const SECCOMP_FD = 3;
+/** Contract default: network isolated, `/tmp` private, no seccomp, no masks. */
+export const DEFAULT_BWRAP_OPTIONS = {
+    shareNet: false,
+    shareTmp: false,
+    seccomp: false,
+    maskDirs: [],
+    workspaceWritable: true,
+    writeRoots: [],
+};
+// W885: no module-level SHELL constant — `resolveShell` owns the choice (the
+// POSIX answer stays the literal `/bin/sh`, so the argv bytes do not move).
+/**
+ * Mount/namespace flags, in the one order that works. `workdir === null` is the
+ * probe shape (no bind, no chdir) so the smoke test exercises exactly the mount
+ * sequence production uses.
+ */
+export function buildBwrapArgv(workdir, options) {
+    const argv = ["--unshare-all", "--die-with-parent"];
+    // W9: writable mounts. The workspace is bound rw only while the permission
+    // allows it (read-only omits it, leaving the `--ro-bind / /` view); the
+    // permission's extra roots (deployment tool roots / write_roots) are bound too.
+    const rwRoots = [];
+    if (workdir !== null && options.workspaceWritable !== false)
+        rwRoots.push(workdir);
+    for (const root of options.writeRoots ?? [])
+        if (!rwRoots.includes(root))
+            rwRoots.push(root);
+    /**
+     * W864: a write root of `/` (a full-access permission's `allPaths`) makes the
+     * WHOLE host root writable, and it replaces `--ro-bind / /` instead of being
+     * stacked after `--dev`/`--proc`: bwrap applies mounts in argv order, so a
+     * trailing `--bind / /` would bury the private devtmpfs/procfs under the
+     * host's — the W274 regression in reverse. Emitting it first keeps
+     * devtmpfs/procfs on top and still yields exactly one `--bind / /`.
+     */
+    const wholeRootWritable = rwRoots.includes("/");
+    // ORDER IS SECURITY SEMANTICS — do not reorder (W274 §2):
+    // the host root goes on first, the private devtmpfs/procfs on top of it.
+    argv.push(wholeRootWritable ? "--bind" : "--ro-bind", "/", "/");
+    argv.push("--dev", "/dev");
+    argv.push("--proc", "/proc");
+    if (options.shareNet)
+        argv.push("--share-net");
+    if (options.shareTmp)
+        argv.push("--bind", "/tmp", "/tmp");
+    else
+        argv.push("--tmpfs", "/tmp");
+    for (const dir of options.maskDirs)
+        argv.push("--tmpfs", dir);
+    for (const root of rwRoots)
+        if (root !== "/")
+            argv.push("--bind", root, root);
+    // W880: re-expose the run_code program dir on top of the tmpfs/mask layers.
+    const programDir = options.programDir;
+    if (programDir !== undefined && programDir !== "" && !rwRoots.includes(programDir)) {
+        argv.push("--bind", programDir, programDir);
+    }
+    if (workdir !== null)
+        argv.push("--chdir", workdir);
+    if (options.seccomp)
+        argv.push("--seccomp", String(SECCOMP_FD));
+    return argv;
+}
+/**
+ * The full `bwrap … -- <shell> <args…> <command>` argv (workdir bind included).
+ *
+ * W885: the shell is RESOLVED, not the hardcoded `/bin/sh` — bwrap only exists
+ * on Linux today, so the POSIX answer is unchanged (this slice changes no Linux
+ * byte), but the gitbash/pwsh/cmd ladder is what a future Windows provider would
+ * consult. A host with no usable shell fails closed through [resolveShell].
+ */
+export function buildBwrapCommand(workdir, options, command, input = {}) {
+    const shell = resolveShell(command, input);
+    return [...buildBwrapArgv(workdir, options), "--", shell.path, ...shell.argv];
+}
+/** The isolation actually in force — reported, never inferred by the caller. */
+export function bwrapMeta(options) {
+    return {
+        provider: BWRAP_PROVIDER,
+        net_isolated: !options.shareNet,
+        tmp_private: !options.shareTmp,
+        seccomp: options.seccomp,
+    };
+}
+/** Human-readable label for spawn failures (never contains the command body). */
+export function bwrapLabel(options) {
+    const bits = [options.shareNet ? "share-net" : "net-isolated", options.shareTmp ? "host-tmp" : "private-tmp"];
+    if (options.seccomp)
+        bits.push("seccomp");
+    if (options.maskDirs.length > 0)
+        bits.push(`masked=${options.maskDirs.length}`);
+    return `bwrap[${bits.join(",")}]`;
+}

package/dist/sandbox/bwrap.d.ts

@@ -0,0 +1,94 @@
+/**
+ * `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 type { Sandbox, SandboxConfig, SandboxRunRequest, SandboxRunResult, SandboxShellLookup, SandboxSpawnRequest, SandboxSpawned } from "@celestea/core";
+import { type BwrapOptions } from "./bwrap-argv.js";
+import { type SandboxLimits } from "./limits.js";
+import { type HostProbe } from "./probe.js";
+import { type RlimitDescribeOptions, type RlimitVia } from "./rlimit.js";
+/** `SandboxMeta` plus the observability the 4-field contract cannot carry. */
+export interface BwrapMeta {
+    provider: string;
+    net_isolated: boolean;
+    tmp_private: boolean;
+    seccomp: boolean;
+    /** true: the child saw a read-only host root. */
+    readonly_root: boolean;
+    /**
+     * F4: true when RLIMIT_AS is in force. false = this view describes a call
+     * that would be exempt (or every rlimit is off). Diagnostics only — the
+     * model-visible SandboxMeta deliberately does NOT carry it.
+     */
+    address_space_limited: boolean;
+    /** W6: effective `RLIMIT_CPU` for this run (seconds). */
+    cpu_sec: number;
+    /** Which mechanism enforced the rlimits. */
+    rlimit_via: RlimitVia;
+    /** Effective `RLIMIT_NPROC` (derived from the UID thread count). */
+    nproc: number;
+    /** Threads owned by this uid host-wide when the probe ran (null = unknown). */
+    uid_threads: number | null;
+    /** `bwrap --version` output, for post-mortems. */
+    bwrap_version: string | null;
+}
+export interface BwrapSandboxOptions {
+    probe?: HostProbe;
+    limits?: SandboxLimits;
+    run?: Partial<BwrapOptions>;
+    /** false disables every rlimit (operator escape hatch). */
+    rlimits?: boolean;
+    /** Directory for the generated seccomp blob (tests pin it). */
+    seccompDir?: string;
+    /** W885: the platform/shell view commands run under (defaults to the host). */
+    shell?: SandboxShellLookup;
+}
+export declare class BwrapSandbox implements Sandbox {
+    readonly config: SandboxConfig;
+    readonly probe: HostProbe;
+    readonly limits: SandboxLimits;
+    readonly options: BwrapOptions;
+    /** W885: injected platform view; `undefined` = the host's own defaults. */
+    readonly shell: SandboxShellLookup | undefined;
+    private readonly rlimits;
+    private readonly seccompDir;
+    constructor(config: SandboxConfig, options?: BwrapSandboxOptions);
+    static fromEnv(env?: NodeJS.ProcessEnv): BwrapSandbox;
+    run(request: SandboxRunRequest): Promise<SandboxRunResult>;
+    spawn(request: SandboxSpawnRequest): Promise<SandboxSpawned>;
+    /** W6: the base limits with this call's `cpu_sec` merged in (clamped). */
+    private limitsFor;
+    /** Isolation actually in force, without running anything (logs / health). */
+    describe(options?: RlimitDescribeOptions): BwrapMeta;
+    private launch;
+    private assertUsable;
+}
+/**
+ * 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";
+/** Factory with explicit knobs (tests / embeddings). */
+export declare function bwrapSandboxWith(config: SandboxConfig, options?: BwrapSandboxOptions): BwrapSandbox;
+/** Env-tuned default (`selectSandbox` builds this only when bwrap is usable). */
+export declare function bwrapSandbox(config?: SandboxConfig): BwrapSandbox;