@smthrs/platform-node 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/ProcessSandbox.js

@@ -0,0 +1,1014 @@
+/**
+ * The one operating-system sandbox every confined process goes through.
+ *
+ * A caller resolves what a run may touch, a {@link Request}: the network
+ * posture, the read and write sets, and optionally which mechanism it wants.
+ * This module turns the request into an argv the host enforces, or into an
+ * {@link Unenforceable} refusal naming what the host lacks. Two callers share
+ * it: the build graph confines every target's tool run under its declared
+ * inputs and outputs (`@smthrs/targets/ExecSandbox`), and the Node
+ * `ProcessConfinement` confines every approved agent command under the
+ * grants in force.
+ *
+ * Three mechanisms, one contract:
+ *
+ * - Linux: bubblewrap. An empty root contains only enumerated system/runtime
+ *   paths and declared reads and writes. The workspace and root are remounted
+ *   read-only after mounting grants. A private tmp supplies HOME. The network
+ *   namespace is unshared unless explicitly opened; loopback-only is refused.
+ * - macOS: seatbelt (`sandbox-exec`). Host reads are denied except enumerated
+ *   system/runtime paths, declared inputs, external reads, writes and private
+ *   tmp. Host credential locations are re-closed under broad grants. Writes
+ *   and network access are denied except what the request opens.
+ * - Docker: `docker run` with a read-only root, declared reads mounted
+ *   read-only at their host paths, declared writes read-write, `--network
+ *   none` unless the request opens it. The image supplies the toolchain. It is
+ *   the path on Windows and on any host without the native mechanism.
+ *
+ * Every declared confinement is enforced or the caller fails closed. Nothing
+ * here logs "unenforced" and carries on; the one caller that may run
+ * unconfined when no mechanism exists, `ProcessConfinement`, says so in its
+ * own options and never on this module's behalf.
+ *
+ * @since 1.0.0-rc.1
+ */
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import * as NodeFs from "node:fs";
+import * as NodeOs from "node:os";
+import * as NodePath from "node:path";
+/**
+ * Checks for an {@link Unenforceable} refusal.
+ *
+ * @category guards
+ * @since 1.0.0-rc.1
+ */
+export const isUnenforceable = (value) => typeof value === "object" && value !== null &&
+    value._tag === "@smthrs/platform-node/SandboxUnenforceable";
+/**
+ * Builds an {@link Unenforceable} refusal.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.1
+ */
+export const unenforceable = (platform, mechanism, missing, detail) => ({
+    _tag: "@smthrs/platform-node/SandboxUnenforceable",
+    platform,
+    mechanism,
+    missing,
+    message: `sandbox: the declared confinement cannot be enforced on this ${platform} host: ${detail}.`
+});
+const pathSeparator = (platform) => platform === "win32" ? ";" : ":";
+/** Ambient host environment for runtime lookup and cache locations. */
+const ambientEnvironment = () => process.env;
+/**
+ * The real host: platform, `PATH` lookup, and filesystem probes.
+ *
+ * @category resolution
+ * @since 0.1.0
+ */
+export const host = (env = ambientEnvironment()) => {
+    const platform = process.platform;
+    let developerDirectory = env["DEVELOPER_DIR"];
+    if (platform === "darwin" && developerDirectory === undefined) {
+        try {
+            developerDirectory = execFileSync("/usr/bin/xcode-select", ["-p"], { encoding: "utf8", timeout: 2_000 }).trim();
+        }
+        catch {
+            // A host without Xcode needs no developer-tree grant.
+        }
+    }
+    const entries = (env["PATH"] ?? "").split(pathSeparator(platform)).filter((entry) => entry !== "");
+    const extensions = platform === "win32" ? (env["PATHEXT"] ?? ".EXE;.CMD;.BAT").split(";") : [""];
+    return {
+        platform,
+        developerDirectory,
+        home: NodeOs.homedir(),
+        executable: (name) => {
+            if (NodePath.isAbsolute(name))
+                return isExecutable(name) ? name : undefined;
+            for (const entry of entries) {
+                for (const extension of extensions) {
+                    const candidate = NodePath.join(entry, name + extension);
+                    if (isExecutable(candidate))
+                        return candidate;
+                }
+            }
+            return undefined;
+        },
+        exists: (path) => NodeFs.existsSync(path),
+        isSymbolicLink,
+        isDirectory: (path) => {
+            try {
+                return NodeFs.statSync(path).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        },
+        entries: (directory) => {
+            try {
+                return NodeFs.readdirSync(directory);
+            }
+            catch {
+                return undefined;
+            }
+        },
+        realpath: (path) => {
+            try {
+                return NodeFs.realpathSync(path);
+            }
+            catch {
+                return undefined;
+            }
+        },
+        uid: typeof process.getuid === "function" ? process.getuid() : undefined,
+        gid: typeof process.getgid === "function" ? process.getgid() : undefined
+    };
+};
+const isExecutable = (path) => {
+    try {
+        NodeFs.accessSync(path, NodeFs.constants.X_OK);
+        return NodeFs.statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Selects the mechanism a request runs under on a host.
+ *
+ * A docker selection is honored when `docker` is on `PATH` and refused
+ * otherwise; a bubblewrap selection is refused off Linux. With no selection
+ * the platform decides: bubblewrap on Linux, seatbelt on macOS, and a refusal
+ * elsewhere, because Windows has no user-level process sandbox and Docker
+ * needs an image only the caller can name.
+ *
+ * @category resolution
+ * @since 1.0.0-rc.1
+ */
+export const select = (request, hostFacts) => {
+    const declared = request.mechanism;
+    const platform = hostFacts.platform;
+    if (declared !== undefined && declared._tag === "docker") {
+        const executable = hostFacts.executable("docker");
+        if (executable === undefined) {
+            return unenforceable(platform, "docker", "docker", "a docker mechanism is selected but docker is not on PATH");
+        }
+        return { _tag: "docker", executable, image: declared.image };
+    }
+    if (declared !== undefined && platform !== "linux") {
+        return unenforceable(platform, "bubblewrap", "linux", "bubblewrap is selected but runs only on Linux; on macOS the seatbelt mechanism is selected when no mechanism is named");
+    }
+    if (platform === "linux") {
+        const executable = hostFacts.executable("bwrap");
+        if (executable === undefined) {
+            return unenforceable(platform, "bubblewrap", "bwrap", "bwrap is not on PATH (install the bubblewrap package)");
+        }
+        if (request.network === "loopback") {
+            return unenforceable(platform, "bubblewrap", "network: true", "bubblewrap cannot expose only the host loopback interface: sharing that interface also grants full host networking; " +
+                "open the whole network to opt into that access");
+        }
+        return { _tag: "bubblewrap", executable };
+    }
+    if (platform === "darwin") {
+        const executable = hostFacts.executable("/usr/bin/sandbox-exec");
+        if (executable === undefined) {
+            return unenforceable(platform, "seatbelt", "/usr/bin/sandbox-exec", "/usr/bin/sandbox-exec is missing");
+        }
+        return { _tag: "seatbelt", executable };
+    }
+    return unenforceable(platform, "docker", "docker image", `${platform} has no process sandbox of its own; select a docker mechanism with an image`);
+};
+const toPosix = (path) => path.split(NodePath.sep).join("/");
+/**
+ * The path with the symlinks of its existing ancestors resolved. A path that
+ * does not exist yet keeps its unresolved tail below the deepest ancestor
+ * that does; a path with no existing ancestor is returned as given.
+ */
+const realized = (path) => {
+    let head = path;
+    const tail = [];
+    while (head !== NodePath.dirname(head)) {
+        try {
+            const real = NodeFs.realpathSync(head);
+            return tail.length === 0 ? real : NodePath.join(real, ...tail);
+        }
+        catch {
+            tail.unshift(NodePath.basename(head));
+            head = NodePath.dirname(head);
+        }
+    }
+    return path;
+};
+const insideRoot = (root, candidate) => {
+    const relative = NodePath.relative(root, candidate);
+    return relative === "" ||
+        (relative !== ".." && !relative.startsWith(`..${NodePath.sep}`) && !NodePath.isAbsolute(relative));
+};
+/** Unlike exists/stat, lstat sees dangling links and does not follow them. */
+const isSymbolicLink = (path) => {
+    try {
+        return NodeFs.lstatSync(path).isSymbolicLink();
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return false;
+        throw cause;
+    }
+};
+/** Check each component, including existing ancestors of a missing output. */
+const safeWrite = (root, path, hostFacts) => {
+    if (!insideRoot(root, path))
+        return false;
+    try {
+        const realpath = hostFacts.realpath ?? NodeFs.realpathSync;
+        const link = hostFacts.isSymbolicLink ?? isSymbolicLink;
+        if (realpath(root) !== root)
+            return false;
+        let current = root;
+        for (const component of NodePath.relative(root, path).split(NodePath.sep).filter(Boolean)) {
+            current = NodePath.join(current, component);
+            if (link(current))
+                return false;
+            if (hostFacts.exists(current) && realpath(current) !== current)
+                return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const unsafeWrite = (platform, mechanism, path) => unenforceable(platform, mechanism, "canonical workspace write path", `write path ${path} has a symbolic link, an unresolved ancestor, or leaves the canonical workspace`);
+/**
+ * Rechecks write grants before directory creation and before rendering. Throws
+ * an {@link Unenforceable} refusal if a path changed since planning. Callers
+ * must keep the workspace stable until the operating system consumes mounts.
+ *
+ * @category resolution
+ * @since 0.1.0
+ */
+export const validateWrites = (confinement, hostFacts = host()) => {
+    for (const write of confinement.writes) {
+        if (!safeWrite(confinement.workspaceRoot, write, hostFacts)) {
+            throw unsafeWrite(hostFacts.platform, confinement.mechanism._tag, write);
+        }
+    }
+};
+/**
+ * Folds a declared file set into directories plus the entries to re-close.
+ *
+ * The seatbelt compiler caps one rule's data at 64 KiB, so a workspace with a
+ * few thousand declared sources cannot be granted file by file. Deepest
+ * first, a directory in which at least as many entries are covered as not is
+ * granted whole, and its uncovered entries are listed for a deny rule that
+ * follows the grant. The result admits exactly the declared set plus the
+ * granted directories' future entries. A directory whose uncovered entry
+ * still holds a covered path deeper down is never folded over that entry,
+ * the workspace root is never folded, and a host that cannot list a
+ * directory leaves its files as they were. Covered means a declared read, a
+ * declared write, or the private tmp.
+ */
+const fold = (root, declared, alsoCovered, hostFacts) => {
+    const entries = hostFacts.entries;
+    if (entries === undefined)
+        return { reads: declared, denies: [] };
+    const covered = new Set([...declared, ...alsoCovered]);
+    const candidates = new Set();
+    for (const path of declared) {
+        let current = NodePath.dirname(path);
+        while (insideRoot(root, current) && current !== root && !candidates.has(current)) {
+            candidates.add(current);
+            current = NodePath.dirname(current);
+        }
+    }
+    // An undeclared directory on the way down to a covered write or read-only
+    // path is not a candidate, so nothing else would stop its parent being
+    // folded over it. The deny that follows the grant names the directory, and
+    // because later rules win in SBPL it closes reads on the very subtree the
+    // plan grants a write to.
+    const holdsCovered = new Set();
+    for (const path of alsoCovered) {
+        let current = NodePath.dirname(path);
+        while (insideRoot(root, current) && current !== root && !holdsCovered.has(current)) {
+            holdsCovered.add(current);
+            current = NodePath.dirname(current);
+        }
+    }
+    const deepestFirst = [...candidates].sort((left, right) => right.length - left.length || (left < right ? -1 : 1));
+    const promoted = [];
+    const denies = [];
+    for (const directory of deepestFirst) {
+        if (covered.has(directory))
+            continue;
+        const children = entries(directory);
+        if (children === undefined || children.length === 0)
+            continue;
+        const uncovered = [];
+        let coveredCount = 0;
+        let partial = false;
+        for (const child of children) {
+            const path = NodePath.join(directory, child);
+            if (covered.has(path))
+                coveredCount += 1;
+            else if (candidates.has(path) || holdsCovered.has(path))
+                partial = true;
+            else
+                uncovered.push(path);
+        }
+        if (partial || coveredCount === 0 || coveredCount < uncovered.length)
+            continue;
+        covered.add(directory);
+        promoted.push(directory);
+        denies.push(...uncovered);
+    }
+    return { reads: [...declared, ...promoted], denies };
+};
+/**
+ * Orders paths so that every subtree is contiguous and its root comes first.
+ *
+ * Comparing on the path plus its separator is what makes that hold: `a/b` and
+ * `a/b/c` sort around `a/b.ts`, because `.` precedes `/`, and a plain
+ * comparison would then put a sibling between an ancestor and its child.
+ */
+const bySubtree = (left, right) => {
+    const leftKey = left + NodePath.sep;
+    const rightKey = right + NodePath.sep;
+    return leftKey < rightKey ? -1 : 1;
+};
+/**
+ * Drops a path covered by another entry of the same set, keeping the set ordered.
+ *
+ * One sweep in subtree order carries the shallowest kept ancestor forward,
+ * because searching the kept set per path is quadratic in the sibling files a
+ * bubblewrap or Docker plan declares one by one.
+ */
+const collapse = (paths) => {
+    const unique = [...new Set(paths)];
+    const kept = new Set();
+    let ancestor;
+    for (const path of [...unique].sort(bySubtree)) {
+        if (ancestor !== undefined && path.startsWith(ancestor + NodePath.sep))
+            continue;
+        kept.add(path);
+        ancestor = path;
+    }
+    return unique.filter((path) => kept.has(path)).sort((left, right) => left.length - right.length || (left < right ? -1 : 1));
+};
+/**
+ * Resolves a request against a workspace into a {@link Plan}, or refuses.
+ *
+ * Every relative path is anchored at the canonical workspace root; one that
+ * escapes the workspace is dropped, because the sandbox never grants anything
+ * outside the tree the key covers. Reads that do not exist are dropped too:
+ * bubblewrap cannot bind a missing path, and a declared input that vanished is
+ * the executor's measurement failure, not this module's. A write containing
+ * any symbolic link below the canonical root is refused, including a missing
+ * output below a linked ancestor.
+ *
+ * @category resolution
+ * @since 0.1.0
+ */
+export const plan = (request, location, hostFacts) => {
+    const selected = select(request, hostFacts);
+    if (isUnenforceable(selected))
+        return selected;
+    let root;
+    try {
+        const canonical = (hostFacts.realpath ?? NodeFs.realpathSync)(location.workspaceRoot);
+        if (canonical === undefined)
+            return unsafeWrite(hostFacts.platform, selected._tag, location.workspaceRoot);
+        root = canonical;
+    }
+    catch {
+        return unsafeWrite(hostFacts.platform, selected._tag, location.workspaceRoot);
+    }
+    const anchor = (relative) => {
+        const absolute = NodePath.resolve(root, ...relative.split("/"));
+        return insideRoot(root, absolute) ? absolute : undefined;
+    };
+    const declared = [];
+    // A declared link grants its target as well: native read allowlists and
+    // Docker's image filesystem otherwise hide bytes outside the workspace.
+    const externalReads = [];
+    for (const relative of request.reads) {
+        const absolute = anchor(relative);
+        if (absolute === undefined || !hostFacts.exists(absolute))
+            continue;
+        declared.push(absolute);
+        const real = hostFacts.realpath?.(absolute);
+        if (real !== undefined && real !== absolute && !insideRoot(root, real))
+            externalReads.push(real);
+    }
+    for (const path of request.externalReads ?? []) {
+        if (!NodePath.isAbsolute(path) || insideRoot(root, path) || !hostFacts.exists(path))
+            continue;
+        externalReads.push(hostFacts.realpath?.(path) ?? path);
+    }
+    // A write names a directory the tool may fill, and is bound as declared
+    // whether or not it exists yet: a name is never read as a file, because a
+    // dot in `.cargo-home` or `dist.new` would otherwise widen the bind to the
+    // parent, and a parent that is the workspace root opens every file in it.
+    // A path that is already a file on the host is the one exception, since a
+    // file cannot be bound as a writable directory.
+    const writes = [];
+    const add = (absolute) => {
+        if (!safeWrite(root, absolute, hostFacts))
+            return unsafeWrite(hostFacts.platform, selected._tag, absolute);
+        writes.push(absolute);
+        return undefined;
+    };
+    for (const relative of request.writes) {
+        const absolute = anchor(relative);
+        if (absolute === undefined)
+            continue;
+        if (!safeWrite(root, absolute, hostFacts))
+            return unsafeWrite(hostFacts.platform, selected._tag, absolute);
+        const refusal = add(hostFacts.exists(absolute) && !hostFacts.isDirectory(absolute) ? NodePath.dirname(absolute) : absolute);
+        if (refusal !== undefined)
+            return refusal;
+    }
+    // A declared output file opens its parent: a file cannot be bound before it
+    // exists, and a tool that writes by rename needs the directory anyway.
+    for (const relative of request.writeFiles ?? []) {
+        const absolute = anchor(relative);
+        if (absolute === undefined)
+            continue;
+        if (!safeWrite(root, absolute, hostFacts))
+            return unsafeWrite(hostFacts.platform, selected._tag, absolute);
+        const refusal = add(hostFacts.exists(absolute) && hostFacts.isDirectory(absolute) ? absolute : NodePath.dirname(absolute));
+        if (refusal !== undefined)
+            return refusal;
+    }
+    const readOnly = [];
+    for (const relative of request.readOnly ?? []) {
+        const absolute = anchor(relative);
+        if (absolute !== undefined)
+            readOnly.push(absolute);
+    }
+    const folded = selected._tag === "seatbelt"
+        ? fold(root, declared, [...writes, ...readOnly, location.tmp], hostFacts)
+        : { reads: declared, denies: [] };
+    return {
+        mechanism: selected,
+        network: request.network,
+        unixSockets: request.unixSockets,
+        strict: request.strict,
+        workspaceRoot: root,
+        cwd: location.cwd,
+        reads: collapse(folded.reads),
+        readDenies: collapse(folded.denies),
+        writes: collapse(writes),
+        readOnly: collapse(readOnly),
+        externalReads: collapse(externalReads),
+        tmp: location.tmp,
+        uid: hostFacts.uid,
+        gid: hostFacts.gid
+    };
+};
+/**
+ * Where corepack keeps the package-manager binaries it manages, resolved the
+ * way corepack itself resolves it from a host environment.
+ *
+ * A `pnpm`, `yarn`, or `npm` on `PATH` is often corepack's shim, and the
+ * program it execs lives in this directory, not on `PATH`. Redirecting `HOME`
+ * and `XDG_CACHE_HOME` to the private tmp moves that directory out from under
+ * the shim, which then tries to re-download the package manager from the
+ * registry — and a confined run has no network, so every rule that drives the
+ * package manager fails with a connect error that names the registry rather
+ * than the missing cache.
+ */
+const corepackHome = (env, home) => {
+    const declared = env["COREPACK_HOME"];
+    if (declared !== undefined && declared !== "")
+        return declared;
+    const base = env["XDG_CACHE_HOME"] ?? env["LOCALAPPDATA"] ??
+        NodePath.join(home, process.platform === "win32" ? "AppData/Local" : ".cache");
+    return NodePath.join(base, "node", "corepack");
+};
+/**
+ * Environment the confined process receives on top of the tool environment:
+ * a private temporary directory and home, so nothing a tool caches lands in
+ * the real home or the shared temp directory.
+ *
+ * `COREPACK_HOME` is the one host cache kept: it holds the package-manager
+ * program a corepack shim execs, the run may only read it (the mechanisms
+ * deny writes outside the workspace), and without it a confined `pnpm` is a
+ * shim with nothing to run. A non-default cache location requires an explicit
+ * `externalReads` grant; preserving the variable does not grant access.
+ *
+ * @category rendering
+ * @since 0.1.0
+ */
+export const environment = (confinement, hostEnv = ambientEnvironment(), hostHome = NodeOs.homedir()) => {
+    const tmp = confinement.mechanism._tag === "seatbelt" ? confinement.tmp : "/tmp";
+    const home = NodePath.posix.join(toPosix(tmp), "home");
+    return {
+        COREPACK_HOME: corepackHome(hostEnv, hostHome),
+        HOME: home,
+        TMPDIR: tmp,
+        TMP: tmp,
+        TEMP: tmp,
+        XDG_CACHE_HOME: NodePath.posix.join(toPosix(tmp), "cache"),
+        XDG_CONFIG_HOME: NodePath.posix.join(toPosix(tmp), "config"),
+        XDG_DATA_HOME: NodePath.posix.join(toPosix(tmp), "data"),
+        XDG_STATE_HOME: NodePath.posix.join(toPosix(tmp), "state")
+    };
+};
+/** The fixed runtime surface, never the host root, home, PATH, or arbitrary env paths. */
+const runtimeReads = (hostFacts) => {
+    const paths = [
+        "/usr",
+        "/bin",
+        "/sbin",
+        "/lib",
+        "/lib64",
+        "/nix/store",
+        "/opt/homebrew",
+        // A Smithers machine's toolchain layer: the repository's Node, pnpm, Go,
+        // Rust and Python, which the machine's environment puts first on PATH
+        // (packages/backend/microsandbox layers.go toolchainRoot). Never all of
+        // /opt/smithers, which holds the machine's environment and helpers.
+        "/opt/smithers/toolchain",
+        "/opt/smithers/rust",
+        "/System/Library",
+        "/System/Volumes/Preboot/Cryptexes/OS",
+        "/private/var/db/dyld",
+        // macOS shell and developer-tool dispatch read these system selectors.
+        "/var/select/sh",
+        "/private/var/select/sh",
+        "/var/select/developer_dir",
+        "/private/var/select/developer_dir",
+        "/Library/Apple",
+        "/Library/Developer",
+        "/Applications/Xcode.app/Contents/Developer",
+        "/Applications/Xcode.app/Contents/Info.plist",
+        "/Applications/Xcode.app/Contents/Frameworks",
+        "/Applications/Xcode.app/Contents/SharedFrameworks",
+        "/Applications/Xcode.app/Contents/PlugIns",
+        "/etc/ld.so.cache",
+        "/etc/ld.so.conf",
+        "/etc/ld.so.conf.d",
+        "/etc/localtime",
+        "/etc/ssl",
+        "/etc/hosts",
+        "/etc/resolv.conf",
+        "/etc/nsswitch.conf"
+    ];
+    const developerDirectory = hostFacts.developerDirectory;
+    if (hostFacts.platform === "darwin" && developerDirectory !== undefined &&
+        /^\/Applications\/Xcode[^/]*\.app\/Contents\/Developer$/.test(developerDirectory)) {
+        paths.push(developerDirectory);
+    }
+    if (hostFacts.home !== undefined)
+        paths.push(NodePath.join(hostFacts.home, ".cache/node/corepack"));
+    for (const name of ["node", "bun"]) {
+        const executable = hostFacts.executable(name);
+        if (executable !== undefined) {
+            paths.push(executable);
+            const real = hostFacts.realpath?.(executable) ?? executable;
+            paths.push(real);
+            // Node distributions keep npm/corepack here; never grant the install
+            // prefix itself, which can be the real home for a custom installation.
+            paths.push(NodePath.resolve(NodePath.dirname(real), "../lib/node_modules"));
+        }
+    }
+    const present = paths.filter((path) => hostFacts.exists(path));
+    return collapse(present.flatMap((path) => [path, hostFacts.realpath?.(path) ?? path]));
+};
+/** Credentials remain closed even when a workspace or runtime grant contains the home. */
+const credentialPaths = (hostFacts) => {
+    const home = hostFacts.home;
+    if (home === undefined)
+        return [];
+    return collapse([
+        ".aws",
+        ".ssh",
+        ".gnupg",
+        ".azure",
+        ".kube",
+        ".docker",
+        ".config/gcloud",
+        ".config/gh",
+        ".npmrc",
+        ".netrc",
+        ".git-credentials"
+    ].flatMap((relative) => {
+        const path = NodePath.join(home, relative);
+        return [path, hostFacts.realpath?.(path) ?? path];
+    }));
+};
+/**
+ * The program a confined run execs, made reachable inside its empty root.
+ *
+ * @internal
+ *
+ * Bubblewrap resolves a bare program name with `execvp` against `PATH` inside
+ * the new root, and that root holds only the runtime paths and the declared
+ * sets. A package manager installed outside them — pnpm under the
+ * `pnpm/action-setup` prefix on a CI runner, a `.bin` link into a
+ * `node_modules` tree — is on the host `PATH` and absent from the sandbox, so
+ * the run died with `bwrap: execvp pnpm` before the tool started (#3140).
+ *
+ * A bare name is resolved on the tool's `PATH` (the host's when none is
+ * given). A program already inside a granted path is left exactly as spelled,
+ * so a multi-call binary keeps the name it dispatches on, and so is one inside
+ * the workspace, whose reads only the declaration may open. Otherwise the run
+ * execs the program's real file, and the nearest package directory holding it
+ * (its `package.json`, at most three levels up, never the home or the root)
+ * is bound read-only, because a script like `pnpm.cjs` loads its siblings.
+ * With no package directory only the real file is bound. A name that resolves
+ * nowhere is left for `execvp` to report.
+ */
+export const launcher = (program, searchPath, granted, workspaceRoot, hostFacts) => {
+    const unchanged = { program, reads: [] };
+    if (program.includes("/") && !NodePath.isAbsolute(program))
+        return unchanged;
+    const found = NodePath.isAbsolute(program)
+        ? hostFacts.executable(program)
+        : searchPath === undefined
+            ? hostFacts.executable(program)
+            : searchPath.split(":").filter((entry) => NodePath.isAbsolute(entry))
+                .map((entry) => hostFacts.executable(NodePath.join(entry, program)))
+                .find((candidate) => candidate !== undefined);
+    if (found === undefined || granted.some((parent) => insideRoot(parent, found)))
+        return unchanged;
+    const real = hostFacts.realpath?.(found) ?? found;
+    if (insideRoot(workspaceRoot, found) || insideRoot(workspaceRoot, real))
+        return unchanged;
+    if (granted.some((parent) => insideRoot(parent, real)))
+        return { program: real, reads: [] };
+    let directory = NodePath.dirname(real);
+    for (let level = 0; level < 3; level++) {
+        if (directory === NodePath.dirname(directory) || directory === hostFacts.home)
+            break;
+        if (hostFacts.exists(NodePath.join(directory, "package.json")))
+            return { program: real, reads: [directory] };
+        directory = NodePath.dirname(directory);
+    }
+    return { program: real, reads: [real] };
+};
+/**
+ * The bubblewrap argv for a plan.
+ *
+ * Order matters: bubblewrap applies operations in argument order, so the
+ * empty root goes first, runtime paths are bound, the workspace tmpfs shadows
+ * any broad runtime grant, declared paths are bound on top, and re-closed
+ * subtrees are bound read-only over their writable parents. The tmpfs is
+ * remounted read-only last so an undeclared write
+ * under the workspace fails with `EROFS` instead of vanishing into the tmpfs.
+ *
+ * @category rendering
+ * @since 0.1.0
+ */
+export const bubblewrap = (confinement, argv, hostFacts = host(), searchPath) => {
+    if (confinement.mechanism._tag !== "bubblewrap")
+        throw new Error("bubblewrap argv needs a bubblewrap plan");
+    validateWrites(confinement, hostFacts);
+    const home = "/tmp/home";
+    const out = [
+        confinement.mechanism.executable,
+        "--tmpfs",
+        "/"
+    ];
+    const runtime = runtimeReads(hostFacts);
+    for (const read of runtime)
+        out.push("--ro-bind", read, read);
+    out.push("--dev", "/dev", "--proc", "/proc", "--tmpfs", "/tmp", "--dir", home, "--dir", "/tmp/cache", "--tmpfs", confinement.workspaceRoot, "--dir", confinement.cwd);
+    // The target of a link that leaves the workspace is bound first, so the
+    // link a declared read then binds resolves to the same bytes the host sees
+    // even when `/tmp` above the target has just become a private tmpfs.
+    for (const real of confinement.externalReads)
+        out.push("--ro-bind", real, real);
+    const [program, ...args] = argv;
+    const launch = program === undefined ? undefined : launcher(program, searchPath, [...runtime, ...confinement.reads, ...confinement.writes, ...confinement.externalReads], confinement.workspaceRoot, hostFacts);
+    for (const read of launch?.reads ?? [])
+        out.push("--ro-bind", read, read);
+    for (const read of confinement.reads)
+        out.push("--ro-bind", read, read);
+    for (const write of confinement.writes)
+        out.push("--bind", write, write);
+    for (const closed of confinement.readOnly) {
+        if (confinement.writes.some((write) => closed === write || closed.startsWith(write + NodePath.sep))) {
+            out.push("--ro-bind-try", closed, closed);
+        }
+    }
+    const granted = [
+        ...runtime,
+        ...(launch?.reads ?? []),
+        ...confinement.reads,
+        ...confinement.writes,
+        ...confinement.externalReads
+    ];
+    for (const path of credentialPaths(hostFacts)) {
+        if (!hostFacts.exists(path) || !granted.some((parent) => insideRoot(parent, path)))
+            continue;
+        // An explicit external read can name a credential or a file inside it.
+        // Mask first, then restore only those explicit paths below the mask.
+        if (confinement.externalReads.some((parent) => insideRoot(parent, path)))
+            continue;
+        const directory = hostFacts.isDirectory(path);
+        if (directory)
+            out.push("--tmpfs", path);
+        else
+            out.push("--ro-bind", "/dev/null", path);
+        for (const read of confinement.externalReads) {
+            if (insideRoot(path, read))
+                out.push("--ro-bind", read, read);
+        }
+        if (directory)
+            out.push("--remount-ro", path);
+    }
+    // `--remount-ro` acts on the mount at that exact path. When the root itself
+    // is a declared write (a declared output file at the top level opens its
+    // parent), that mount is the writable bind, and remounting it would deny
+    // every write the declaration admitted; the tmpfs it replaced needs no
+    // re-closing.
+    if (!confinement.writes.includes(confinement.workspaceRoot))
+        out.push("--remount-ro", confinement.workspaceRoot);
+    out.push("--remount-ro", "/");
+    out.push("--chdir", confinement.cwd, "--unshare-all", "--new-session", "--die-with-parent");
+    // Bubblewrap cannot expose only the host loopback interface. Planning
+    // refuses that posture on Linux, so only an explicit full-network opening
+    // reaches `--share-net` here.
+    if (confinement.network === "loopback") {
+        throw new Error("bubblewrap cannot render loopback-only networking");
+    }
+    if (confinement.network === "open")
+        out.push("--share-net");
+    out.push("--", ...(launch === undefined ? argv : [launch.program, ...args]));
+    return out;
+};
+/** Escapes one string for a seatbelt profile literal. */
+const sbpl = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"")}"`;
+/** Every directory from the workspace root down to the parent of each path. */
+const ancestors = (root, paths) => {
+    const found = new Set([root]);
+    for (const path of paths) {
+        let current = NodePath.dirname(path);
+        while (current.length >= root.length && current !== NodePath.dirname(current)) {
+            found.add(current);
+            if (current === root)
+                break;
+            current = NodePath.dirname(current);
+        }
+    }
+    return [...found].sort();
+};
+/**
+ * The seatbelt profile for a plan.
+ *
+ * File reads start closed, then enumerated runtime paths and declared sets
+ * are opened. The workspace is re-closed before its grants so a workspace
+ * under a runtime root does not inherit the broad runtime grant. Credentials
+ * are re-closed before explicit external reads, which can opt into them.
+ *
+ * @category rendering
+ * @since 0.1.0
+ */
+export const seatbelt = (confinement, hostFacts = host()) => {
+    if (confinement.mechanism._tag !== "seatbelt")
+        throw new Error("a seatbelt profile needs a seatbelt plan");
+    validateWrites(confinement, hostFacts);
+    const lines = ["(version 1)", confinement.strict === true ? "(deny default)" : "(allow default)"];
+    if (confinement.strict === true) {
+        // No Mach lookup, Apple Events or LaunchServices grants: work must stay
+        // in descendants inheriting this sandbox, never delegated to a host daemon.
+        lines.push("(allow process-exec)", "(allow process-fork)", "(allow signal (target same-sandbox))", "(allow process-info* (target same-sandbox))", "(allow sysctl-read (sysctl-name-prefix \"hw.\") (sysctl-name-prefix \"machdep.cpu.\") (sysctl-name \"kern.argmax\") (sysctl-name \"kern.hostname\") (sysctl-name \"kern.maxfilesperproc\") (sysctl-name \"kern.maxproc\") (sysctl-name \"kern.osproductversion\") (sysctl-name \"kern.osrelease\") (sysctl-name \"kern.ostype\") (sysctl-name \"kern.osversion\") (sysctl-name \"kern.secure_kernel\") (sysctl-name \"kern.usrstack64\") (sysctl-name \"kern.version\") (sysctl-name \"sysctl.proc_cputype\") (sysctl-name \"vm.loadavg\"))", "(allow mach-host*)");
+        if (confinement.network === "open")
+            lines.push("(allow network*)");
+    }
+    if (confinement.network !== "open") {
+        lines.push("(deny network*)");
+        if (confinement.unixSockets !== false)
+            lines.push("(allow network* (local unix-socket))");
+        if (confinement.network === "loopback") {
+            lines.push("(allow network-bind (local ip \"localhost:*\"))", "(allow network-inbound (local ip \"localhost:*\"))", "(allow network-outbound (remote ip \"localhost:*\"))");
+        }
+    }
+    if (confinement.network === "open" && confinement.unixSockets === false) {
+        lines.push("(deny network* (local unix-socket))");
+        if (confinement.strict === true) {
+            // Darwin resolves DNS through this trusted endpoint. Full IP authority
+            // permits DNS only; other host daemons remain closed, including Mach IPC.
+            lines.push("(allow network-outbound (literal \"/private/var/run/mDNSResponder\"))");
+        }
+    }
+    const writable = [...confinement.writes, confinement.tmp];
+    lines.push("(deny file-write*)", `(allow file-write* ${confinement.strict === true ? "(literal \"/dev/null\")" : "(subpath \"/dev\")"} ${writable.map((path) => `(subpath ${sbpl(path)})`).join(" ")})`);
+    if (confinement.readOnly.length > 0) {
+        lines.push(`(deny file-write* ${confinement.readOnly.map((path) => `(subpath ${sbpl(path)})`).join(" ")})`);
+    }
+    lines.push("(deny file-read*)", confinement.strict === true
+        ? "(allow file-read* (literal \"/\") (literal \"/dev/null\") (literal \"/dev/zero\") (literal \"/dev/random\") (literal \"/dev/urandom\"))"
+        : "(allow file-read* (literal \"/\") (subpath \"/dev\"))", 
+    // macOS's system aliases need readlink access before a shell can execute
+    // an admitted file through them. Literal grants expose the links only;
+    // their target directories still cannot be listed or read wholesale.
+    "(allow file-read* (literal \"/tmp\") (literal \"/var\") (literal \"/etc\"))");
+    const runtime = runtimeReads(hostFacts);
+    if (runtime.length > 0)
+        lines.push(`(allow file-read* ${runtime.map((path) => `(subpath ${sbpl(path)})`).join(" ")})`);
+    const readable = [...confinement.reads, ...confinement.writes, confinement.tmp];
+    // Node realpath walks every ancestor, including parents outside the
+    // workspace. Grant only their metadata, without listing or reading bytes.
+    const traversable = ancestors("/", [...runtime, ...readable, ...confinement.externalReads])
+        .filter((path) => !insideRoot(confinement.workspaceRoot, path));
+    lines.push(`(allow file-read-metadata ${traversable.map((path) => `(literal ${sbpl(path)})`).join(" ")})`);
+    const listable = ancestors(confinement.workspaceRoot, readable.filter((path) => insideRoot(confinement.workspaceRoot, path)));
+    lines.push(`(deny file-read* (subpath ${sbpl(confinement.workspaceRoot)}))`);
+    if (confinement.strict === true) {
+        const metadata = [
+            ...new Set([
+                ...listable,
+                ...ancestors(confinement.workspaceRoot, [confinement.cwd]),
+                confinement.cwd
+            ])
+        ].sort();
+        lines.push(`(allow file-read-metadata ${metadata.map((path) => `(literal ${sbpl(path)})`).join(" ")})`);
+    }
+    else {
+        lines.push(`(allow file-read-metadata (subpath ${sbpl(confinement.workspaceRoot)}))`);
+    }
+    lines.push(`(allow file-read* ${[
+        ...(confinement.strict === true ? [] : listable.map((path) => `(literal ${sbpl(path)})`)),
+        ...readable.map((path) => `(subpath ${sbpl(path)})`)
+    ].join(" ")})`);
+    if (confinement.readDenies.length > 0) {
+        lines.push(`(deny file-read* ${confinement.readDenies.map((path) => `(subpath ${sbpl(path)})`).join(" ")})`);
+    }
+    const credentials = credentialPaths(hostFacts);
+    if (credentials.length > 0) {
+        lines.push(`(deny file-read* ${credentials.map((path) => `(subpath ${sbpl(path)})`).join(" ")})`);
+        if (confinement.strict === true) {
+            lines.push(`(deny file-write* ${credentials.map((path) => `(subpath ${sbpl(path)})`).join(" ")})`);
+        }
+    }
+    if (confinement.externalReads.length > 0) {
+        lines.push(`(allow file-read* ${confinement.externalReads.map((path) => `(subpath ${sbpl(path)})`).join(" ")})`);
+    }
+    return lines.join("");
+};
+/**
+ * One `key=value` field of a `docker run --mount` value. Docker parses the
+ * value as one CSV record, so a field containing a comma, a quote, or a line
+ * break is wrapped in quotes with inner quotes doubled; any other field keeps
+ * its plain spelling.
+ */
+const mountField = (key, value) => {
+    const field = `${key}=${value}`;
+    return /[",\r\n]/.test(field) ? `"${field.replaceAll("\"", "\"\"")}"` : field;
+};
+const bindMount = (path, readonly) => ["type=bind", mountField("src", path), mountField("dst", toPosix(path)), ...(readonly ? ["readonly"] : [])].join(",");
+/**
+ * The `docker run` argv for a plan. Paths keep their host spelling inside the
+ * container so an argv that names workspace paths works unchanged; the image
+ * supplies everything outside the workspace.
+ *
+ * @category rendering
+ * @since 0.1.0
+ */
+export const docker = (confinement, argv, env, hostFacts = host(), containerName = `smithers-${randomUUID()}`) => {
+    if (confinement.mechanism._tag !== "docker")
+        throw new Error("docker argv needs a docker plan");
+    validateWrites(confinement, hostFacts);
+    const out = [
+        confinement.mechanism.executable,
+        "run",
+        "--rm",
+        "--init",
+        "--name",
+        containerName,
+        "--read-only",
+        "--tmpfs",
+        "/tmp:rw,exec",
+        "--network",
+        confinement.network === "open" ? "bridge" : "none",
+        "--workdir",
+        toPosix(confinement.cwd)
+    ];
+    if (confinement.uid !== undefined && confinement.gid !== undefined) {
+        out.push("--user", `${confinement.uid}:${confinement.gid}`);
+    }
+    for (const real of confinement.externalReads)
+        out.push("--mount", bindMount(real, true));
+    for (const read of confinement.reads)
+        out.push("--mount", bindMount(read, true));
+    for (const write of confinement.writes)
+        out.push("--mount", bindMount(write, false));
+    for (const closed of confinement.readOnly) {
+        if (confinement.writes.some((write) => closed === write || closed.startsWith(write + NodePath.sep))) {
+            out.push("--mount", bindMount(closed, true));
+        }
+    }
+    for (const [name, value] of Object.entries(env).sort(([left], [right]) => (left < right ? -1 : 1))) {
+        if (name === "PATH" || name === "HOME")
+            continue;
+        out.push("--env", `${name}=${value}`);
+    }
+    out.push("--env", "HOME=/tmp/home", confinement.mechanism.image, ...argv);
+    return out;
+};
+/**
+ * Wraps a tool argv in the plan's mechanism and reports the environment the
+ * wrapper needs the child to carry. Docker runs also return the unique
+ * container name the caller must forcibly remove when the client scope closes.
+ *
+ * @category rendering
+ * @since 0.1.0
+ */
+export const wrap = (confinement, argv, env, hostFacts = host()) => {
+    const extra = environment(confinement);
+    switch (confinement.mechanism._tag) {
+        case "bubblewrap":
+            return { argv: bubblewrap(confinement, argv, hostFacts, env["PATH"]), env: extra };
+        case "seatbelt": {
+            const profile = seatbelt(confinement, hostFacts);
+            return { argv: [confinement.mechanism.executable, "-p", profile, ...argv], env: extra };
+        }
+        case "docker": {
+            const containerName = `smithers-${randomUUID()}`;
+            return { argv: docker(confinement, argv, { ...env, ...extra }, hostFacts, containerName), env: {}, containerName };
+        }
+    }
+};
+/**
+ * Each pattern names the path a tool complained about and whether the text
+ * proves the denied operation was a write. A confined process never sees an
+ * undeclared path: seatbelt answers EPERM, bubblewrap answers ENOENT because
+ * the path was never mounted, and dash spells that "Directory nonexistent".
+ */
+const denialPatterns = [
+    { pattern: /\b(?:EACCES|EPERM|ENOENT)\b[^'"\n]*['"]([^'"\n]+)['"]/g, write: false },
+    { pattern: /\bEROFS\b[^'"\n]*['"]([^'"\n]+)['"]/g, write: true },
+    {
+        pattern: /(?:^|[\s:])((?:\/|\.{0,2}\/?)[^\s:'"]+): (?:Operation not permitted|Permission denied|No such file or directory|Directory nonexistent|Not a directory)/gm,
+        write: false
+    },
+    { pattern: /(?:^|[\s:])((?:\/|\.{0,2}\/?)[^\s:'"]+): Read-only file system/gm, write: true },
+    {
+        pattern: /(?:Operation not permitted|Permission denied|No such file or directory|Directory nonexistent)[^\n]*?[:\s]['"]?((?:\/|[A-Za-z]:\\)[^'"\s:]+)/g,
+        write: false
+    },
+    { pattern: /Read-only file system[^\n]*?[:\s]['"]?((?:\/|[A-Za-z]:\\)[^'"\s:]+)/g, write: true },
+    {
+        pattern: /cannot (?:create|write|touch|mkdir|remove) (?:directory )?['"]?((?:\/|[A-Za-z]:\\|\.{0,2}\/?)[^'":\s]+)/g,
+        write: true
+    },
+    { pattern: /cannot (?:open|access|stat|read) ['"]?((?:\/|[A-Za-z]:\\|\.{0,2}\/?)[^'":\s]+)/g, write: false }
+];
+/**
+ * Names, from a failed tool's own output, the paths it touched outside the
+ * declared set. The sandbox denies at the kernel, so the only witness is the
+ * tool's error text; this reads it back and says which side of the boundary
+ * each path fell on.
+ *
+ * @category diagnostics
+ * @since 0.1.0
+ */
+export const diagnose = (confinement, text) => {
+    // Path → whether the text proved the denied operation was a write.
+    const named = new Map();
+    for (const { pattern, write } of denialPatterns) {
+        for (const match of text.matchAll(pattern)) {
+            const raw = match[1];
+            const absolute = NodePath.isAbsolute(raw) ? raw : NodePath.resolve(confinement.cwd, raw);
+            if (insideRoot(confinement.workspaceRoot, absolute))
+                named.set(absolute, (named.get(absolute) ?? false) || write);
+            if (named.size >= 5)
+                break;
+        }
+        if (named.size >= 5)
+            break;
+    }
+    if (named.size === 0)
+        return undefined;
+    const covered = (path, set) => set.some((entry) => entry === path || path.startsWith(entry + NodePath.sep));
+    const lines = [...named.entries()].sort(([left], [right]) => (left < right ? -1 : 1)).map(([path, write]) => {
+        const relative = toPosix(NodePath.relative(confinement.workspaceRoot, path));
+        // A path that lexically sits in the workspace can still leave it through
+        // a symlink in an existing ancestor; the declaration covers the tree, not
+        // wherever a link points.
+        const real = realized(path);
+        const escapes = !insideRoot(confinement.workspaceRoot, real);
+        const readable = !escapes && (covered(path, confinement.reads) || covered(path, confinement.writes));
+        const writable = !escapes && covered(path, confinement.writes) && !covered(path, confinement.readOnly);
+        if (escapes) {
+            return `sandbox: ${relative} resolves to ${real}, outside the declared ${write ? "write" : "read"} set`;
+        }
+        if (write) {
+            return writable
+                ? `sandbox: ${relative} was denied inside the declared set`
+                : `sandbox: ${relative} is outside the declared write set`;
+        }
+        if (!readable)
+            return `sandbox: ${relative} is outside the declared read set`;
+        if (!writable)
+            return `sandbox: ${relative} is outside the declared write set`;
+        return `sandbox: ${relative} was denied inside the declared set`;
+    });
+    return `${lines.join("\n")}\nsandbox: ${confinement.mechanism._tag}, network ${confinement.network}, ` +
+        `${confinement.reads.length} read path(s), ${confinement.writes.length} write path(s)`;
+};
+//# sourceMappingURL=ProcessSandbox.js.map