@descryy/runtime-controller 0.0.0

package/dist/readiness.js

@@ -0,0 +1,179 @@
+/**
+ * Readiness (plan §6): "Readiness must not equal 'process exists.'" —
+ * supported strategies are HTTP health check, TCP/port check, a known log
+ * pattern, a real subprocess command, or a caller-supplied hook (which
+ * covers the plan's "framework readiness hook" and "user-defined readiness"
+ * — two names for the same shape, a caller-provided async predicate,
+ * consolidated into one mechanism rather than two near-identical ones).
+ *
+ * **`command` is not `custom-hook` (RT-193).** An earlier version of this
+ * comment folded the plan's "command check" into `custom-hook` too, on the
+ * reasoning that both are "a caller-provided check." That collapsed a real
+ * distinction: `custom-hook` runs a caller's own in-process predicate,
+ * while `command` runs an actual subprocess and reads its actual exit
+ * code — the same "declared, not inferred" shape `ServiceConfiguration`'s
+ * own `command` field already uses, one layer over. A caller with a real
+ * CLI health check (`pg_isready`, a framework's own readiness script) had
+ * no way to express that without either wrapping it in a hand-written
+ * `custom-hook` predicate that shells out itself, or reimplementing the
+ * subprocess plumbing per caller — `command` is that plumbing, built once.
+ *
+ * The plan requires recording which mechanism succeeded — `ReadinessResult`
+ * makes that a field, not something inferred after the fact.
+ *
+ * **What `ready: true` does and does not claim (RT-024).** All four
+ * mechanisms answer one question — is something listening / responding
+ * where expected — and none answer whether it is the process *this*
+ * `spawnProcess` call produced. A stale listener from an unrelated, already-
+ * dead run satisfies `http`/`tcp-port` identically to a correct one; nothing
+ * here can tell them apart. `log-pattern` only carries the stronger,
+ * this-run-specific guarantee when its `read` is wired to *this* execution's
+ * own `ManagedProcess.readOutput()` — the type does not enforce that wiring,
+ * it is a caller discipline. `custom-hook` inherits whatever the caller's
+ * predicate actually checks.
+ *
+ * Callers that bind a fixed, guessable host:port are exposed to this gap;
+ * an ephemeral port closes it by construction (nothing else can already be
+ * bound there) rather than by detection, and is the default recommendation
+ * over a startup-nonce scheme, which only earns its extra machinery when a
+ * fixed port is genuinely unavoidable (a contract with an external tool).
+ * See `descry-runtime`'s `DECISIONS.md` RT-024 for how this was found —
+ * a real 30-second collector timeout that looked like a Playwright/DOM bug
+ * and was actually a correct wait against an orphaned process from a
+ * different, already-dead session.
+ *
+ * **A single probe attempt cannot outlive `timeoutMs` (RT-030).** `http`
+ * and `tcp-port` each bind their I/O to the *remaining* time until
+ * `deadline`, not a fresh per-attempt budget — a target that accepts a
+ * connection and never responds no longer lets one probe attempt run past
+ * the caller's own deadline. Measured, not theoretical: an unbound `fetch`
+ * here let `awaitReadiness` run past its own `timeoutMs` (>8s observed
+ * against a 3s budget). `command` honors the same discipline, the same
+ * way: `execFile`'s own `timeout` option is set to the remaining time until
+ * `deadline`, so a command that hangs instead of exiting is killed rather
+ * than left to run past the caller's own budget — it owns a real OS
+ * resource (a child process) exactly like the http/tcp-port sockets do, so
+ * it gets the same treatment. `custom-hook` is not wrapped the same way — a
+ * caller-supplied predicate owns its own timeout behavior, same as every
+ * other `Collector`-shaped callback contract in this repo (`collector.ts`'s
+ * own docs put "must resolve, not hang" on the implementer); imposing a
+ * surprise external cancellation on arbitrary caller code would be a
+ * different, larger decision than fixing the mechanisms that own a real OS
+ * resource this module can actually clean up.
+ */
+import { createConnection } from "node:net";
+import { execFile } from "node:child_process";
+export const READINESS_MECHANISMS = ["http", "tcp-port", "log-pattern", "command", "custom-hook"];
+const DEFAULT_POLL_INTERVAL_MS = 200;
+export async function awaitReadiness(checks, options) {
+    const startedAt = Date.now();
+    const deadline = startedAt + options.timeoutMs;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    if (checks.length === 0) {
+        return { ready: false, mechanism: null, elapsedMs: 0, reason: "no readiness checks configured" };
+    }
+    do {
+        for (const check of checks) {
+            if (await probe(check, deadline)) {
+                return { ready: true, mechanism: check.kind, elapsedMs: Date.now() - startedAt, reason: null };
+            }
+        }
+        await sleep(pollIntervalMs);
+    } while (Date.now() < deadline);
+    // Names what was actually probed, not just that nothing answered.
+    //
+    // This is the only cheap thing available against the ephemeral-port race
+    // in `allocateEphemeralPort` (bind 0, read, close, spawn): if another
+    // process takes the port in the window between release and the child's
+    // own bind, the child never comes up and the *only* symptom is this
+    // result. "No readiness mechanism succeeded" sends the reader to look at
+    // the application; "nothing answered http://127.0.0.1:41237/health"
+    // sends them to look at the port, which is where the problem is. The race
+    // itself cannot be closed without binding the real service directly to
+    // the probe socket, which the child-process model does not support — so
+    // making its one symptom legible is the honest remainder.
+    return {
+        ready: false,
+        mechanism: null,
+        elapsedMs: Date.now() - startedAt,
+        // "timeout" stays in the wording deliberately: the first draft of this
+        // message replaced it with "within 1500ms", which reads fine and drops
+        // the one word a caller can match on. §41's hung-process test does
+        // exactly that, and caught it.
+        reason: `no readiness mechanism succeeded within the ${options.timeoutMs}ms timeout — probed ${checks.map(describeCheck).join(", ")}`,
+    };
+}
+function describeCheck(check) {
+    switch (check.kind) {
+        case "http":
+            return check.url;
+        case "tcp-port":
+            return `tcp ${check.host}:${check.port}`;
+        case "log-pattern":
+            return `log pattern ${String(check.pattern)}`;
+        case "command":
+            return `command ${[check.command, ...(check.args ?? [])].join(" ")}`;
+        case "custom-hook":
+            return "custom hook";
+    }
+}
+async function probe(check, deadline) {
+    switch (check.kind) {
+        case "http":
+            return probeHttp(check, deadline);
+        case "tcp-port":
+            return probeTcpPort(check, deadline);
+        case "log-pattern":
+            return check.pattern.test(check.read());
+        case "command":
+            return probeCommand(check, deadline);
+        case "custom-hook":
+            return check.check();
+    }
+}
+async function probeHttp(check, deadline) {
+    try {
+        const response = await fetch(check.url, { signal: AbortSignal.timeout(Math.max(0, deadline - Date.now())) });
+        return response.status === (check.expectedStatus ?? 200);
+    }
+    catch {
+        return false;
+    }
+}
+function probeTcpPort(check, deadline) {
+    return new Promise((resolve) => {
+        const socket = createConnection({ host: check.host, port: check.port });
+        socket.setTimeout(Math.max(0, deadline - Date.now()));
+        const finish = (ok) => {
+            socket.destroy();
+            resolve(ok);
+        };
+        socket.once("connect", () => finish(true));
+        socket.once("error", () => finish(false));
+        socket.once("timeout", () => finish(false));
+    });
+}
+/**
+ * Ready when `check.command` exits 0 within the remaining time until
+ * `deadline` (RT-030 — see this module's own header). A non-zero exit, a
+ * spawn failure (e.g. command not found), and a timeout kill are all "not
+ * ready yet" here — `awaitReadiness`'s polling loop retries on the next
+ * `pollIntervalMs` tick regardless of which one happened, the same as every
+ * other mechanism's `false`.
+ */
+function probeCommand(check, deadline) {
+    return new Promise((resolve) => {
+        const remainingMs = Math.max(0, deadline - Date.now());
+        if (remainingMs === 0) {
+            resolve(false);
+            return;
+        }
+        execFile(check.command, check.args ?? [], { cwd: check.cwd, timeout: remainingMs }, (error) => {
+            resolve(error === null);
+        });
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=readiness.js.map

package/dist/readiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.js","sourceRoot":"","sources":["../src/readiness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,aAAa,CAAU,CAAC;AAqE3G,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAErC,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAiC,EACjC,OAA8B;IAE9B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAC/C,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,wBAAwB,CAAC;IAE1E,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,gCAAgC,EAAE,CAAC;IACnG,CAAC;IAED,GAAG,CAAC;QACF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,MAAM,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAC;gBACjC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;YACjG,CAAC;QACH,CAAC;QACD,MAAM,KAAK,CAAC,cAAc,CAAC,CAAC;IAC9B,CAAC,QAAQ,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE;IAEhC,kEAAkE;IAClE,EAAE;IACF,yEAAyE;IACzE,sEAAsE;IACtE,uEAAuE;IACvE,oEAAoE;IACpE,yEAAyE;IACzE,oEAAoE;IACpE,0EAA0E;IAC1E,uEAAuE;IACvE,wEAAwE;IACxE,0DAA0D;IAC1D,OAAO;QACL,KAAK,EAAE,KAAK;QACZ,SAAS,EAAE,IAAI;QACf,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;QACjC,uEAAuE;QACvE,uEAAuE;QACvE,mEAAmE;QACnE,+BAA+B;QAC/B,MAAM,EAAE,+CAA+C,OAAO,CAAC,SAAS,uBAAuB,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;KACtI,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,KAAqB;IAC1C,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,MAAM;YACT,OAAO,KAAK,CAAC,GAAG,CAAC;QACnB,KAAK,UAAU;YACb,OAAO,OAAO,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QAC3C,KAAK,aAAa;YAChB,OAAO,eAAe,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QAChD,KAAK,SAAS;YACZ,OAAO,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACvE,KAAK,aAAa;YAChB,OAAO,aAAa,CAAC;IACzB,CAAC;AACH,CAAC;AAED,KAAK,UAAU,KAAK,CAAC,KAAqB,EAAE,QAAgB;IAC1D,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,MAAM;YACT,OAAO,SAAS,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACpC,KAAK,UAAU;YACb,OAAO,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACvC,KAAK,aAAa;YAChB,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QAC1C,KAAK,SAAS;YACZ,OAAO,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACvC,KAAK,aAAa;YAChB,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;AACH,CAAC;AAED,KAAK,UAAU,SAAS,CAAC,KAAyB,EAAE,QAAgB;IAClE,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QAC7G,OAAO,QAAQ,CAAC,MAAM,KAAK,CAAC,KAAK,CAAC,cAAc,IAAI,GAAG,CAAC,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,KAA4B,EAAE,QAAgB;IAClE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,gBAAgB,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QACxE,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACtD,MAAM,MAAM,GAAG,CAAC,EAAW,EAAQ,EAAE;YACnC,MAAM,CAAC,OAAO,EAAE,CAAC;YACjB,OAAO,CAAC,EAAE,CAAC,CAAC;QACd,CAAC,CAAC;QACF,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3C,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1C,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,YAAY,CAAC,KAA4B,EAAE,QAAgB;IAClE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACvD,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;YACtB,OAAO,CAAC,KAAK,CAAC,CAAC;YACf,OAAO;QACT,CAAC;QACD,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE;YAC5F,OAAO,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC;QAC1B,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/sandbox.d.ts

@@ -0,0 +1,139 @@
+/**
+ * §21's execution boundary, real isolation half (the sandbox-isolation
+ * lane, superseding the "sandbox platform is a separate architectural
+ * decision, not built here" deferral). RT-070 and RT-193 gave this runtime
+ * a *named* boundary (trusted-local, resource limits, privilege reporting)
+ * but not an *isolating* one -- nothing stopped a spawned process from
+ * reading any file the invoking user could read, or reaching any host the
+ * invoking user's network could reach. This module closes that gap for
+ * real, on Linux, for processes this runtime SPAWNS.
+ *
+ * **The architectural constraint this module does not try to solve
+ * around:** isolation can only wrap a process Descry itself launches.
+ * Attach-mode (`attach-to-running-process.ts`, `attach-to-running-node-
+ * process.ts`, `attach-to-running-jvm-process.ts`) reaches a process that
+ * was already running, unconfined, before Descry touched it -- there is no
+ * honest way to retroactively contain it (ptrace-based interception was
+ * investigated and rejected elsewhere in this repo as "not honestly
+ * generalizable"). Spawn-mode gets real isolation via this module.
+ * Attach-mode stays permanently and explicitly unsandboxed --
+ * `SANDBOX_BOUNDARY_DISCLOSURE` in `execution-safety.ts` says so in-product,
+ * and this module does not (and structurally cannot) change that.
+ *
+ * **Mechanism: bubblewrap (bwrap), not raw `unshare`/`clone`.** bwrap is
+ * the unprivileged sandboxing helper behind Flatpak and used by many
+ * developer tools directly -- a small (tens of KB), auditable, actively
+ * maintained binary, not a bespoke native module this repo would need to
+ * build and ship per-platform. It runs setuid-free on any kernel with
+ * unprivileged user namespaces enabled (checked below, not assumed) and
+ * gives one process a new mount namespace (real filesystem visibility
+ * control) and network namespace (real network denial) in one exec,
+ * composing cleanly with `applyResourceLimits`'s `prlimit` wrap and with
+ * this package's existing process-group kill mechanism (`detached: true` +
+ * `process.kill(-pid, …)`) -- verified directly: bwrap does not create a
+ * new process group unless asked to, so the group-kill in
+ * `process-manager.ts` reaches it and everything it started, unchanged.
+ * The one dependency this buys: `bwrap` must be on `PATH`. Reported as a
+ * capability, exactly like `prlimit` -- refused, never silently
+ * unconstrained, when requested and absent.
+ *
+ * **What this module does NOT attempt, and where that gap actually closes:**
+ * a *native* macOS or Windows sandbox for this mechanism (`sandbox-exec`/
+ * Seatbelt -- deprecated public API; the Endpoint Security Framework --
+ * needs a special Apple entitlement this project does not have; Windows Job
+ * Objects + restricted tokens/AppContainer + WFP network enforcement -- a
+ * second and third bespoke native sandbox to build and maintain). That is
+ * not "researched but not built here, someday" -- it is an explicit
+ * architecture decision NOT to build native sandboxes for those two
+ * platforms at all. `../container-sandbox.ts` closes the gap instead, by
+ * routing macOS and Windows through a real Docker container that reuses
+ * THIS module's own proven Linux mechanism underneath (Docker Desktop's
+ * Linux VM on macOS, WSL2/Docker Desktop's Windows backend on Windows) --
+ * see that module's own doc comment for exactly what is real-tested there
+ * versus unverified on real macOS/Windows hardware. `filesystemIsolationCapability`/
+ * `networkIsolationCapability` below still report `unavailable` with a
+ * reason on non-Linux platforms -- this module never silently claims to
+ * cover them; `container-sandbox.ts` is the module a non-Linux caller
+ * actually wants.
+ */
+import type { CapabilityStatus, FilesystemPolicy, NetworkPolicy } from "@descryy/runtime-contracts";
+/**
+ * Real capability check, matching `resourceLimitCapability`'s own shape and
+ * precedent exactly: existence on `PATH` first (fast, matches
+ * `prlimit --version`'s pattern), then the one Linux-specific precondition
+ * that existence alone doesn't prove -- unprivileged user namespaces
+ * actually being usable, not just bwrap being installed.
+ */
+export declare function filesystemIsolationCapability(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): CapabilityStatus;
+/**
+ * The same underlying mechanism as `filesystemIsolationCapability` --
+ * bwrap building one namespace set covers both a restricted mount view and
+ * a network namespace in the same exec -- so this delegates rather than
+ * duplicating the check. Kept as its own named function because the two
+ * policies are declared, refused, and reasoned about independently
+ * (`NetworkPolicy` only supports one shape; see `unsupportedNetworkPolicyReason`),
+ * even though today they share one mechanism underneath.
+ */
+export declare function networkIsolationCapability(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): CapabilityStatus;
+/**
+ * `NetworkPolicy`'s general shape (arbitrary allow/deny host lists) is not
+ * what this iteration's mechanism enforces -- only full denial. Returns the
+ * reason a given policy cannot be applied, or `null` if it is the one
+ * shape that can. Checked independently of `networkIsolationCapability`:
+ * a policy can be shape-unsupported on a platform where the mechanism
+ * itself is otherwise available, and the two refusals are different
+ * claims ("nothing here can enforce any network policy" vs. "this specific
+ * policy asks for something the real mechanism doesn't do yet").
+ */
+export declare function unsupportedNetworkPolicyReason(policy: NetworkPolicy): string | null;
+/**
+ * Resolves the real, symlink-followed directory containing the executable
+ * `command` would run as -- the one piece of host filesystem a sandboxed
+ * process needs beyond the standard OS directories and whatever the caller
+ * declared, and the one this function computes generically rather than by
+ * naming a language: an interpreter installed outside `/usr` (nvm, rbenv,
+ * pyenv, sdkman -- all common, all under a user's home directory) would
+ * otherwise be invisible inside the sandbox no matter which language it
+ * is, which is exactly the kind of per-language special case §IR-boundary
+ * rules out. Returns `null` when `command` cannot be resolved (already
+ * absolute-looking and missing, or not found on `PATH`) -- the caller
+ * proceeds without an extra bind in that case; the exec itself will fail
+ * inside the sandbox the same honest way it would outside one.
+ */
+export declare function resolveExecutableDirectory(command: string, cwd: string, env: NodeJS.ProcessEnv): string | null;
+export interface SandboxOptions {
+    /** The original, un-resource-limit-wrapped command (e.g. `"node"`) -- used only to resolve which extra directory the interpreter itself needs bound in. */
+    readonly interpreterCommand: string;
+    /** The command to actually exec inside the sandbox -- already passed through `applyResourceLimits`, so this may be `"prlimit"` with the real command in `args`. */
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly filesystemPolicy?: FilesystemPolicy;
+    readonly networkPolicy?: NetworkPolicy;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+}
+/**
+ * Wraps `command`/`args` with `bwrap` so the OS enforces `filesystemPolicy`
+ * and/or `networkPolicy`. Neither declared returns `command`/`args`
+ * unchanged -- every execution before this lane keeps behaving exactly as
+ * before unless it opts in, the same non-regression contract
+ * `applyResourceLimits` already established for resource limits.
+ *
+ * **Throws rather than silently spawning unconstrained** -- same
+ * `tokenizeCommand`/`applyResourceLimits` precedent -- when a policy is
+ * requested and the real mechanism cannot back it, whether because the
+ * platform has no mechanism at all or because the declared shape is one
+ * this mechanism doesn't implement (`unsupportedNetworkPolicyReason`).
+ *
+ * Composes with `applyResourceLimits`: this function wraps *outside* it
+ * (`bwrap … -- prlimit … -- realCommand`), because the mount namespace must
+ * exist before `prlimit` or the real command run inside it, and `prlimit`
+ * itself (in `/usr/bin`) is reachable through the same base OS binding
+ * every sandboxed process gets.
+ */
+export declare function applySandbox(options: SandboxOptions): {
+    readonly command: string;
+    readonly args: readonly string[];
+};
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AA+BpG;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,gBAAgB,CAoBlJ;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,gBAAgB,CAE/I;AAED;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAOnF;AAOD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,GAAG,IAAI,CAwB9G;AAED,MAAM,WAAW,cAAc;IAC7B,2JAA2J;IAC3J,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,mKAAmK;IACnK,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAmFpH"}

package/dist/sandbox.js

@@ -0,0 +1,271 @@
+/**
+ * §21's execution boundary, real isolation half (the sandbox-isolation
+ * lane, superseding the "sandbox platform is a separate architectural
+ * decision, not built here" deferral). RT-070 and RT-193 gave this runtime
+ * a *named* boundary (trusted-local, resource limits, privilege reporting)
+ * but not an *isolating* one -- nothing stopped a spawned process from
+ * reading any file the invoking user could read, or reaching any host the
+ * invoking user's network could reach. This module closes that gap for
+ * real, on Linux, for processes this runtime SPAWNS.
+ *
+ * **The architectural constraint this module does not try to solve
+ * around:** isolation can only wrap a process Descry itself launches.
+ * Attach-mode (`attach-to-running-process.ts`, `attach-to-running-node-
+ * process.ts`, `attach-to-running-jvm-process.ts`) reaches a process that
+ * was already running, unconfined, before Descry touched it -- there is no
+ * honest way to retroactively contain it (ptrace-based interception was
+ * investigated and rejected elsewhere in this repo as "not honestly
+ * generalizable"). Spawn-mode gets real isolation via this module.
+ * Attach-mode stays permanently and explicitly unsandboxed --
+ * `SANDBOX_BOUNDARY_DISCLOSURE` in `execution-safety.ts` says so in-product,
+ * and this module does not (and structurally cannot) change that.
+ *
+ * **Mechanism: bubblewrap (bwrap), not raw `unshare`/`clone`.** bwrap is
+ * the unprivileged sandboxing helper behind Flatpak and used by many
+ * developer tools directly -- a small (tens of KB), auditable, actively
+ * maintained binary, not a bespoke native module this repo would need to
+ * build and ship per-platform. It runs setuid-free on any kernel with
+ * unprivileged user namespaces enabled (checked below, not assumed) and
+ * gives one process a new mount namespace (real filesystem visibility
+ * control) and network namespace (real network denial) in one exec,
+ * composing cleanly with `applyResourceLimits`'s `prlimit` wrap and with
+ * this package's existing process-group kill mechanism (`detached: true` +
+ * `process.kill(-pid, …)`) -- verified directly: bwrap does not create a
+ * new process group unless asked to, so the group-kill in
+ * `process-manager.ts` reaches it and everything it started, unchanged.
+ * The one dependency this buys: `bwrap` must be on `PATH`. Reported as a
+ * capability, exactly like `prlimit` -- refused, never silently
+ * unconstrained, when requested and absent.
+ *
+ * **What this module does NOT attempt, and where that gap actually closes:**
+ * a *native* macOS or Windows sandbox for this mechanism (`sandbox-exec`/
+ * Seatbelt -- deprecated public API; the Endpoint Security Framework --
+ * needs a special Apple entitlement this project does not have; Windows Job
+ * Objects + restricted tokens/AppContainer + WFP network enforcement -- a
+ * second and third bespoke native sandbox to build and maintain). That is
+ * not "researched but not built here, someday" -- it is an explicit
+ * architecture decision NOT to build native sandboxes for those two
+ * platforms at all. `../container-sandbox.ts` closes the gap instead, by
+ * routing macOS and Windows through a real Docker container that reuses
+ * THIS module's own proven Linux mechanism underneath (Docker Desktop's
+ * Linux VM on macOS, WSL2/Docker Desktop's Windows backend on Windows) --
+ * see that module's own doc comment for exactly what is real-tested there
+ * versus unverified on real macOS/Windows hardware. `filesystemIsolationCapability`/
+ * `networkIsolationCapability` below still report `unavailable` with a
+ * reason on non-Linux platforms -- this module never silently claims to
+ * cover them; `container-sandbox.ts` is the module a non-Linux caller
+ * actually wants.
+ */
+import { execFileSync } from "node:child_process";
+import { accessSync, constants as fsConstants, readFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, relative } from "node:path";
+/**
+ * Whether unprivileged user namespaces -- the kernel feature bwrap needs to
+ * build a mount/network namespace without running setuid-root -- are
+ * actually enabled on this host, not merely assumed from "the kernel
+ * supports namespaces in general." Two independent sysctls can each
+ * disable it; neither file existing at all is itself evidence of a
+ * restriction (most non-Debian-derived distros never gate this at all).
+ */
+function unprivilegedUserNamespaceStatus() {
+    try {
+        const clone = readFileSync("/proc/sys/kernel/unprivileged_userns_clone", "utf8").trim();
+        if (clone === "0") {
+            return { ok: false, reason: "kernel.unprivileged_userns_clone=0 -- unprivileged user namespaces are disabled on this host" };
+        }
+    }
+    catch {
+        // Sysctl doesn't exist on this kernel -- not evidence of a restriction,
+        // only Debian/Ubuntu-derived kernels gate it through this specific file.
+    }
+    try {
+        const max = readFileSync("/proc/sys/user/max_user_namespaces", "utf8").trim();
+        if (max === "0") {
+            return { ok: false, reason: "user.max_user_namespaces=0 -- unprivileged user namespaces are disabled on this host" };
+        }
+    }
+    catch {
+        // Same reasoning.
+    }
+    return { ok: true, reason: null };
+}
+/**
+ * Real capability check, matching `resourceLimitCapability`'s own shape and
+ * precedent exactly: existence on `PATH` first (fast, matches
+ * `prlimit --version`'s pattern), then the one Linux-specific precondition
+ * that existence alone doesn't prove -- unprivileged user namespaces
+ * actually being usable, not just bwrap being installed.
+ */
+export function filesystemIsolationCapability(env = process.env, platform = process.platform) {
+    if (platform !== "linux") {
+        return {
+            availability: "unavailable",
+            reason: `no filesystem isolation mechanism is wired up on "${platform}" for bwrap -- by design, not by omission (native sandbox-exec/Seatbelt and Job Objects/AppContainer were researched and rejected); see container-sandbox.ts, which routes "${platform}" through a real Docker container instead`,
+        };
+    }
+    try {
+        execFileSync("bwrap", ["--version"], { env, stdio: "ignore" });
+    }
+    catch {
+        return {
+            availability: "unavailable",
+            reason: "bubblewrap (bwrap) is not on PATH -- filesystem isolation cannot be enforced without it",
+        };
+    }
+    const userns = unprivilegedUserNamespaceStatus();
+    if (!userns.ok) {
+        return { availability: "unavailable", reason: `bubblewrap is installed but unprivileged user namespaces are unavailable: ${userns.reason}` };
+    }
+    return { availability: "available", reason: null };
+}
+/**
+ * The same underlying mechanism as `filesystemIsolationCapability` --
+ * bwrap building one namespace set covers both a restricted mount view and
+ * a network namespace in the same exec -- so this delegates rather than
+ * duplicating the check. Kept as its own named function because the two
+ * policies are declared, refused, and reasoned about independently
+ * (`NetworkPolicy` only supports one shape; see `unsupportedNetworkPolicyReason`),
+ * even though today they share one mechanism underneath.
+ */
+export function networkIsolationCapability(env = process.env, platform = process.platform) {
+    return filesystemIsolationCapability(env, platform);
+}
+/**
+ * `NetworkPolicy`'s general shape (arbitrary allow/deny host lists) is not
+ * what this iteration's mechanism enforces -- only full denial. Returns the
+ * reason a given policy cannot be applied, or `null` if it is the one
+ * shape that can. Checked independently of `networkIsolationCapability`:
+ * a policy can be shape-unsupported on a platform where the mechanism
+ * itself is otherwise available, and the two refusals are different
+ * claims ("nothing here can enforce any network policy" vs. "this specific
+ * policy asks for something the real mechanism doesn't do yet").
+ */
+export function unsupportedNetworkPolicyReason(policy) {
+    if (policy.mode === "allow" && policy.hosts.length === 0)
+        return null;
+    return ('only full network denial ({ mode: "allow", hosts: [] }) is enforced -- selective allow- or deny-listing of ' +
+        "specific hosts needs DNS interception and IP filtering inside the sandbox's network namespace (a veth pair, " +
+        "NAT, iptables/nftables rules), not built in this iteration");
+}
+function isWithin(root, target) {
+    const rel = relative(root, target);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+/**
+ * Resolves the real, symlink-followed directory containing the executable
+ * `command` would run as -- the one piece of host filesystem a sandboxed
+ * process needs beyond the standard OS directories and whatever the caller
+ * declared, and the one this function computes generically rather than by
+ * naming a language: an interpreter installed outside `/usr` (nvm, rbenv,
+ * pyenv, sdkman -- all common, all under a user's home directory) would
+ * otherwise be invisible inside the sandbox no matter which language it
+ * is, which is exactly the kind of per-language special case §IR-boundary
+ * rules out. Returns `null` when `command` cannot be resolved (already
+ * absolute-looking and missing, or not found on `PATH`) -- the caller
+ * proceeds without an extra bind in that case; the exec itself will fail
+ * inside the sandbox the same honest way it would outside one.
+ */
+export function resolveExecutableDirectory(command, cwd, env) {
+    let candidate = null;
+    if (command.includes("/")) {
+        candidate = isAbsolute(command) ? command : join(cwd, command);
+    }
+    else {
+        const pathVar = env.PATH ?? "";
+        for (const dir of pathVar.split(":")) {
+            if (dir === "")
+                continue;
+            const full = join(dir, command);
+            try {
+                accessSync(full, fsConstants.X_OK);
+                candidate = full;
+                break;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    if (candidate === null)
+        return null;
+    try {
+        return dirname(realpathSync(candidate));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Wraps `command`/`args` with `bwrap` so the OS enforces `filesystemPolicy`
+ * and/or `networkPolicy`. Neither declared returns `command`/`args`
+ * unchanged -- every execution before this lane keeps behaving exactly as
+ * before unless it opts in, the same non-regression contract
+ * `applyResourceLimits` already established for resource limits.
+ *
+ * **Throws rather than silently spawning unconstrained** -- same
+ * `tokenizeCommand`/`applyResourceLimits` precedent -- when a policy is
+ * requested and the real mechanism cannot back it, whether because the
+ * platform has no mechanism at all or because the declared shape is one
+ * this mechanism doesn't implement (`unsupportedNetworkPolicyReason`).
+ *
+ * Composes with `applyResourceLimits`: this function wraps *outside* it
+ * (`bwrap … -- prlimit … -- realCommand`), because the mount namespace must
+ * exist before `prlimit` or the real command run inside it, and `prlimit`
+ * itself (in `/usr/bin`) is reachable through the same base OS binding
+ * every sandboxed process gets.
+ */
+export function applySandbox(options) {
+    const { filesystemPolicy, networkPolicy } = options;
+    if (filesystemPolicy === undefined && networkPolicy === undefined) {
+        return { command: options.command, args: options.args };
+    }
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    if (networkPolicy !== undefined) {
+        const shapeReason = unsupportedNetworkPolicyReason(networkPolicy);
+        if (shapeReason !== null) {
+            throw new Error(`networkPolicy was configured but cannot be enforced: ${shapeReason}`);
+        }
+        const capability = networkIsolationCapability(env, platform);
+        if (capability.availability !== "available") {
+            throw new Error(`networkPolicy was configured but cannot be enforced on this platform: ${capability.reason}`);
+        }
+    }
+    if (filesystemPolicy !== undefined) {
+        const capability = filesystemIsolationCapability(env, platform);
+        if (capability.availability !== "available") {
+            throw new Error(`filesystemPolicy was configured but cannot be enforced on this platform: ${capability.reason}`);
+        }
+    }
+    const bwrapArgs = [];
+    if (filesystemPolicy !== undefined) {
+        bwrapArgs.push("--ro-bind", "/usr", "/usr", "--symlink", "/usr/bin", "/bin", "--symlink", "/usr/lib", "/lib", "--symlink", "/usr/lib64", "/lib64", "--proc", "/proc", "--dev", "/dev", "--tmpfs", "/tmp", "--bind", options.cwd, options.cwd);
+        const boundRoots = ["/usr", options.cwd, ...filesystemPolicy.allowedRoots];
+        for (const root of filesystemPolicy.allowedRoots) {
+            bwrapArgs.push("--bind", root, root);
+        }
+        const interpreterDir = resolveExecutableDirectory(options.interpreterCommand, options.cwd, env);
+        if (interpreterDir !== null && !boundRoots.some((root) => isWithin(root, interpreterDir))) {
+            bwrapArgs.push("--ro-bind", interpreterDir, interpreterDir);
+        }
+    }
+    else {
+        // No filesystem restriction declared -- mirror the host root exactly,
+        // matching FilesystemPolicy's own "absent means unconstrained" default.
+        // A mount namespace is still created here (bwrap always builds one, and
+        // --unshare-net below needs it), so /proc, /dev and /tmp are remounted
+        // explicitly rather than inherited: a plain `--bind / /` is not
+        // recursive and would otherwise leave them looking empty inside.
+        bwrapArgs.push("--bind", "/", "/", "--dev", "/dev", "--proc", "/proc", "--bind", "/tmp", "/tmp");
+    }
+    bwrapArgs.push("--chdir", options.cwd);
+    if (networkPolicy !== undefined) {
+        bwrapArgs.push("--unshare-net");
+    }
+    // Kills the sandboxed tree with the sandbox itself if bwrap's own parent
+    // (this Node process) dies unexpectedly -- a second, independent backstop
+    // alongside process-manager.ts's own group-kill, not a replacement for it.
+    bwrapArgs.push("--die-with-parent", "--", options.command, ...options.args);
+    return { command: "bwrap", args: bwrapArgs };
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@descryy/runtime-controller",
+  "version": "0.0.0",
+  "type": "module",
+  "description": "Runtime controller: process manager, readiness, timeout/cancellation, execution IDs, cleanup. Deliverable 2 of the runtime phase — depends on @descryy/runtime-contracts, builds no collectors.",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "@descryy/runtime-contracts": "0.0.0"
+  }
+}