kern-sandbox 0.2.39 → 0.2.43

package/README.md

@@ -1,17 +1,31 @@
-# kern-sandbox (Node.js / TypeScript)
+<div align="center">
 
-**Run LLM-generated code in a fast, real sandbox, one fresh box per call.**
+<img src="https://raw.githubusercontent.com/getkern/kern/main/assets/brand/kern-logo.png" width="220" alt="kern">
 
-Fast means milliseconds, and it is two numbers rather than one: the box is the cheap part, and an
-interpreter starting inside it costs more than the box does. Both depend on your machine, so they are
-measured under [Prewarming](https://github.com/getkern/kern/blob/main/bindings/node/README.md#prewarming-a-box-ready-before-the-call-arrives) with the machine and the method beside them, and the
-runtime's own are in [BENCHMARKS.md](https://github.com/getkern/kern/blob/main/BENCHMARKS.md).
+# Kern Sandbox
 
-`kern-sandbox` is the Node and TypeScript binding for **[kern](https://getkern.dev)**: a rootless,
-kernel-enforced sandbox out of one static binary, with no daemon, no VM and no cloud. An agent's
-tool-call, a model's generated snippet, a CI step: code that runs before anyone reads it gets its own
-box, and the box is thrown away after. A hundred calls are a hundred boxes and 1.4 s in total, with
-nothing left behind, and when state has to carry across them there is
+**Your model writes the code. This runs it where it can't touch your machine.**
+
+<sub>**Works with** Claude Code · Cursor · Claude Desktop · LM Studio · LangChain · pi</sub>
+
+[![npm](https://img.shields.io/npm/v/kern-sandbox?label=npm&color=0b7285)](https://www.npmjs.com/package/kern-sandbox)
+[![PyPI](https://img.shields.io/pypi/v/kern-sandbox?label=PyPI&color=0b7285)](https://pypi.org/project/kern-sandbox/)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/getkern/kern/blob/main/LICENSE)
+
+<sub>rootless · no daemon · no socket · no VM · no cloud · no account</sub>
+
+**[The runtime](https://github.com/getkern/kern)** ·
+**[MCP server](https://github.com/getkern/kern/blob/main/docs/MCP.md)** ·
+**[Security model](https://github.com/getkern/kern/blob/main/SECURITY.md)** ·
+**[Benchmarks](https://github.com/getkern/kern/blob/main/BENCHMARKS.md)**
+
+</div>
+
+An agent's tool-call, a generated snippet, a notebook cell, a CI step: it arrives, you run it, and
+nobody has read it first.
+
+`kern-sandbox` is the Node and TypeScript binding for **[kern](https://getkern.dev)**. Every call
+gets its own box, thrown away after; when state has to carry across calls there is
 [a session](#a-session-files-persist-processes-are-ephemeral) and a warm interpreter.
 
 Network off, memory and PID caps the kernel enforces **where your host delegates them**,
@@ -59,7 +73,9 @@ import { runCode, withSandbox, Sandbox } from "kern-sandbox";
 npm install kern-sandbox
 ```
 
-You also need the `kern` binary on `PATH` (or point `$KERN_BIN` at it). The quickest route is the
+On Linux x64 and arm64 that brings kern with it: the package carries kern's static release binary,
+the same file the install script serves, and the binding drives that copy. `$KERN_BIN` always wins
+over it. Anywhere else the binding drives a `kern` on `PATH`, and the quickest route to one is the
 released static binary, whose checksum the script verifies:
 
 ```sh
@@ -154,7 +170,7 @@ A non-zero exit from *your code* is **not** a fault (`fault` stays `null`): it i
 | `escape_blocked` | a syscall was blocked by the seccomp filter (SIGSYS) |
 | `oom` | the kernel's OOM killer took the box against its own memory cap. Read from a descriptor the code in the box cannot write, so it is an observation and not a guess from the exit code |
 | `killed` | SIGKILL with **no** OOM reported: an external kill (`kern stop`, a signal, the host out of memory), or a cap that did not bind here, which the message names |
-| `exec_failed` | the box started, the command did not exist inside it. `{language:"node"}` on an image with no `node` is the ordinary way there; the message names the binary AND the image |
+| `exec_failed` | the box started, the command did not exist inside it. `{language:"node"}` on an image YOU named that has no `node` is the ordinary way there; the message names the binary AND the image, and the remedy. On the DEFAULT image kern refuses before starting a box, because there it already knows the answer |
 | `startup_failed` | the box never ran, and kern said why in `stderr`. Two shapes: your `timeoutS` fired while kern was still BUILDING the box (run it again: if the second call is fast it was a cold image read, and if it is not, look for a bind source on a dead NFS export), or kern refused to build it at all (an image that cannot be pulled, a mount it will not make). The cold read is the FIRST call on a new machine and it is not small: 38 s for an arm64 image on a Raspberry Pi 5 here, against 0.1 s warm |
 
 ```js
@@ -183,7 +199,7 @@ Every relaxing option says so in its name or docs:
 - **env off argv**: workload env is written to a private `0600` file, never `--env K=V` on the command
   line, so a credential in `env` does not leak into `ps`.
 - **mounts refused**: the host's own sources (`/`, `/etc`, `/root`, `/boot`, `/proc`, `/sys`, `/dev`,
-  `$HOME`, the docker socket), any path with a **credential directory** in it (`.ssh`, `.aws`, `.gnupg`,
+  `$HOME`), any path with a **credential directory** in it (`.ssh`, `.aws`, `.gnupg`,
   `.kube`, `.docker`, `.azure`, `.oci`, `.terraform.d`, `.password-store`, `.netrc`, `.git-credentials`,
   `.pypirc`, `.npmrc`, `.databrickscfg`, `.boto`, `.s3cfg`, `.rclone.conf`, and under `.config`:
   `gcloud`, `gh`, `doctl`, `rclone`),
@@ -200,6 +216,12 @@ new Sandbox({
   image,           // default "python:3.12-slim"
   setup,           // one-time, network-on, e.g. "pip install pandas"
   workspace,       // host dir to persist; omit for a temp dir deleted on close()
+  workspaceMaxBytes, // default null; caps what the workspace ACCUMULATES across calls. Cooperative:
+                   // the call that exceeds it runs, the next is refused
+  persist,         // default false; true = ONE resident box per name, every call `kern exec`s into it
+                   // (2 ms against 6 ms). Needs name + workspace; survives close(), destroy() stops it
+  name,            // the stable identity two processes share a persist box by
+  persistTtlS,     // default 3600: the resident box ends by itself after this
   memoryMb,        // default 512
   cpus,            // default null (uncapped)
   pids,            // default 256
@@ -288,7 +310,7 @@ RUN python3 -m compileall -q -j 0 /usr/local/lib/python3.12
 
 Build it once and pass it: `run_code(..., image="my-python")`. The default stays the stock tag,
 because an SDK that silently required a custom image would be worse than one that costs 29 ms and
-says so. Measured on an Intel i7-14700KF, Linux 7.0.0, idle; [BENCHMARKS.md](https://github.com/getkern/kern/blob/main/BENCHMARKS.md) has the method.
+says so. Measured rootless on an idle machine; [BENCHMARKS.md](https://github.com/getkern/kern/blob/main/BENCHMARKS.md) has the method.
 
 ## Prewarming: a box ready before the call arrives
 
@@ -384,11 +406,11 @@ gives kern a delegated cgroup: on one that does not (a root shell with no user m
 runners) kern warns and the box runs UNCAPPED. `kern doctor` says which path a host takes, and
 `requireLimits: true` refuses to start rather than run a box whose caps are decoration.
 
-**`npm install kern-sandbox` does not install the sandbox.** The binding drives a `kern` binary it
-finds on `PATH` or in `$KERN_BIN`, and that is a SECOND thing to install and to keep current: a
-binary that is not kern is refused by name, but an OLDER kern runs fine and answers fewer questions,
-because the fault taxonomy reads bytes only newer builds write. If a verdict looks wrong, print
-`kern --version` before anything else.
+**The binary comes with the package only on Linux x64 and arm64.** Anywhere else, and whenever
+`$KERN_BIN` is set, the binding drives a `kern` it did not bring, and that is a SECOND thing to keep
+current: a binary that is not kern is refused by name, but an OLDER kern runs fine and answers fewer
+questions, because the fault taxonomy reads bytes only newer builds write. If a verdict looks wrong,
+print that kern's `--version` before anything else.
 
 ## License
 

package/index.d.ts

@@ -93,6 +93,20 @@ export interface SandboxOptions {
   setup?: string;
   /** Host dir to persist as the workspace. Omit -> a temp dir, created on open() and deleted on close(). */
   workspace?: string;
+  /** Cap on what the workspace ACCUMULATES across calls, in bytes. Cooperative, not a boundary: the
+   * call that exceeds it still runs, the next is refused. Default null (no cap). */
+  workspaceMaxBytes?: number | null;
+  /** A stable identity, used only with `persist`: two processes that name the same sandbox meet the
+   * same resident box. */
+  name?: string | null;
+  /** Keep ONE resident box and run every call in it with `kern exec`, 2 ms against 6 ms for a fresh
+   * box. Requires `name` and `workspace`. Survives close(); destroy() stops it. A resident box is not
+   * a fresh one: /tmp accumulates, the PID namespace is shared, and an OOM comes back `killed` rather
+   * than `oom`. A box built under another posture with the same name is refused. Default false. */
+  persist?: boolean;
+  /** How long the resident box lives, in seconds. It is kern's own `--timeout` on that box, so it ends
+   * by itself if the owning process dies. Default 3600. */
+  persistTtlS?: number;
   /** RAM cap in MiB (kern --memory). Default 512. Passed as an explicit --memory, so by kern's
    * "explicit flag wins over profile" rule the default OVERRIDES a `vcpu:` profile's own `memory=`;
    * pass `null` to let the profile's memory apply (uncapped if the profile carries none). */
@@ -152,7 +166,19 @@ export interface SandboxOptions {
   maxOutputBytes?: number;
   /** true (default) hard-enforces caps via a systemd scope (~6 ms start); false = best-effort (~3 ms). */
   enforceLimits?: boolean;
-  /** Mount setup= deps read-only for runCode (blocks cross-run dependency poisoning). Default false. */
+  /** Refuse to start unless the memory and pids caps are ACTUALLY enforced, read back from the cgroup,
+   * instead of running best-effort uncapped (kern --require-limits). Default false. */
+  requireLimits?: boolean;
+  /** "untrusted" is an opt-in hardening bundle: seccomp allowlist, cap-drop ALL and a read-only root.
+   * A bound `mounts` path stays writable. null (default) leaves kern's normal posture. */
+  securityProfile?: string | null;
+  /** Enter this pre-loaded AppArmor profile on the box's exec. kern fails the box CLOSED if it is not
+   * loaded on the host. null (default) applies none. */
+  apparmor?: string | null;
+  /** Capabilities dropped from every box (kern --cap-drop). Default ["ALL"]. NOT behaviour-free: a
+   * workload binding a port below 1024 inside the box needs NET_BIND_SERVICE. [] drops none. */
+  capDrop?: string[];
+  /** Mount setup= deps read-only for runCode (blocks cross-run dependency poisoning). Default true. */
   depsReadonly?: boolean;
   /** Compile this image's stdlib once and mount it read-only in every box (default true). */
   pycCache?: boolean;
@@ -202,6 +228,9 @@ export class Sandbox {
   open(): Promise<this>;
   /** Delete the workspace iff we created it. Idempotent. */
   close(): Promise<void>;
+  /** Stop the resident box of a `persist` sandbox: the only way it goes away before its TTL.
+   * Idempotent. */
+  destroy(): Promise<void>;
   /** Run a snippet on the workspace in a fresh, network-off box. File state persists; memory does not.
    * `timeoutS`/`onStdout`/`onStderr` override the session defaults for this call only. */
   runCode(code: string, opts?: { language?: Language } & PerCallOptions): Promise<ExecutionResult>;

package/index.js

@@ -3,10 +3,16 @@
  *
  *   const kern = require('kern-sandbox');
  *
- *   // one-shot (a throwaway session under the hood)
- *   const r = await kern.runCode("console.log(1 + 1)", { language: "node" });
+ *   // one-shot (a throwaway session under the hood). The CODE is Python, because the default image
+ *   // is python:3.12-slim: this example used to pass `language: "node"`, which that image cannot
+ *   // run, so the first thing a reader copied was the one call that fails.
+ *   const r = await kern.runCode("print(1 + 1)");
  *   console.log(r.stdout, r.success);
  *
+ *   // JavaScript needs an image that carries node; kern refuses it on the default one rather than
+ *   // starting a box to discover that.
+ *   const js = await kern.runCode("console.log(1 + 1)", { language: "node", image: "node:22-slim" });
+ *
  *   // a session: FILE state persists across steps; processes are ephemeral
  *   await kern.withSandbox({ setup: "pip install pandas" }, async (sbx) => {
  *     await sbx.writeFile("data.csv", csvBytes);
@@ -36,10 +42,130 @@ const crypto = require("crypto");
 const zlib = require("zlib");
 const { spawn, spawnSync } = require("child_process");
 
-const VERSION = "0.2.39";
+const VERSION = "0.2.43";
 
 const DEFAULT_IMAGE = "python:3.12-slim";
+// WHAT THE DEFAULT IMAGE CONTAINS, as a fact ABOUT THE IMAGE and not about its name. It drives the
+// node refusal below and sits here so that changing DEFAULT_IMAGE forces a decision about it in the
+// same edit: the batteries-included image this repo builds (`images/sandbox/Dockerfile`) ships node,
+// `python:3.12-slim` does not, and a refusal keyed on "is this the default image" would go on
+// refusing a path that had started working the day the default changed. Same spelling, same reason,
+// as `_DEFAULT_IMAGE_HAS_NODE` in the Python binding.
+const DEFAULT_IMAGE_HAS_NODE = false;
 const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box
+// What `kern exec` says when the box it was asked for is not running. Matched rather than inferred
+// from an exit code, because `exec` reports a MISSING BOX and a workload that exited non-zero through
+// the same status, and only the first of the two is something the binding can repair.
+const RESIDENT_GONE = "no running box named";
+// Prefix for a resident box's name, so one cannot be confused with a box the user started by hand.
+const RESIDENT_PREFIX = "kern-sbx-";
+// The label a resident box's posture fingerprint is stamped into.
+const CFG_LABEL = "kern.sbx.cfg";
+
+/**
+ * Bytes a directory tree occupies ON DISK, or 0 when it cannot be read.
+ *
+ * `blocks * 512` and NOT `size`, because the question is how much of the disk is gone and the two
+ * disagree in both directions: a sparse file reports a size it does not occupy, and a 1-byte file
+ * occupies a whole block.
+ *
+ * HARD LINKS ARE COUNTED ONCE, keyed by `(dev, ino)`: a box that hard-links one large file a thousand
+ * times occupies one file's worth of disk, and charging it a thousand times would refuse a session
+ * that is costing nothing.
+ *
+ * SYMLINKS ARE NOT FOLLOWED. The workspace is box-controlled, and a symlink to `/usr` would otherwise
+ * make untrusted input drive an unbounded walk - a denial of service dressed as a measurement.
+ * `lstatSync` keeps the walk inside the tree and charges the link its own (tiny) blocks.
+ *
+ * Iterative with an explicit stack, not recursion: a deep tree is something the box chooses, and a
+ * 2000-level one is enough to end a recursive walk in a stack overflow.
+ *
+ * Best effort, never throwing: a file deleted mid-walk is ordinary in a live workspace, and a
+ * measurement that can abort a call is worse than one that is slightly stale.
+ */
+function workspaceUsage(root) {
+  let total = 0;
+  const seen = new Set();
+  const stack = [root];
+  while (stack.length) {
+    const current = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      let st;
+      try {
+        st = fs.lstatSync(full);
+      } catch {
+        continue;
+      }
+      if (entry.isDirectory()) stack.push(full);
+      const key = `${st.dev}:${st.ino}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      total += (st.blocks || 0) * 512;
+    }
+  }
+  return total;
+}
+
+/**
+ * Run a command and capture it, WITHOUT blocking the event loop.
+ *
+ * `spawnSync` would be shorter and is what the first version of this used; this file already records
+ * why that is wrong here (see `pycBuild`): a synchronous spawn stops every other timer and socket in
+ * the host process for its whole duration, and these calls talk to `kern ps` and `kern box`.
+ */
+function runCapture(argv, timeoutMs, env) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      // `env` IS OPTIONAL AND DEFAULTS TO INHERITING, which is right for the read-only queries that
+      // use this helper (`kern ps`, `kern stop`). It exists because ONE caller must not inherit:
+      // creating a resident box has to honour the Sandbox's `enforceLimits` rather than whatever
+      // `KERN_NO_SCOPE` happened to be exported in the shell.
+      const opts = { stdio: ["ignore", "pipe", "pipe"] };
+      if (env !== undefined) opts.env = env;
+      child = spawn(argv[0], argv.slice(1), opts);
+    } catch (e) {
+      resolve({ code: -1, stdout: "", stderr: String(e && e.message) });
+      return;
+    }
+    let out = "";
+    let err = "";
+    let settled = false;
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ code, stdout: out, stderr: err });
+    };
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        /* already gone */
+      }
+      finish(-1);
+    }, timeoutMs);
+    child.stdout.on("data", (d) => {
+      out += d.toString();
+    });
+    child.stderr.on("data", (d) => {
+      err += d.toString();
+    });
+    child.on("error", (e) => {
+      err += String(e && e.message);
+      finish(-1);
+    });
+    child.on("close", (code) => finish(code === null ? -1 : code));
+  });
+}
+
 const DEPS_DIR = ".deps"; // pip --target dir inside the workspace (added to PYTHONPATH for python)
 
 /** Where the shared stdlib bytecode cache is mounted inside a box, READ-ONLY.
@@ -1340,9 +1466,34 @@ function verifyIsKern(bin) {
   VERIFIED_KERN.add(key);
 }
 
-/** Locate `kern`: $KERN_BIN if set, else the first `kern` on $PATH. The result is also IDENTIFIED as
- * kern (see `verifyIsKern`): being executable and being named `kern` are not the same as being kern. */
-function findKern() {
+/** The `kern` this package's npm tarball carries for this machine, or null.
+ *
+ * The published package carries kern's static release binary for Linux x64 and arm64 under
+ * `bin/linux-<arch>/kern`, the same file `install.sh` serves for the same tag, so `npm install
+ * kern-sandbox` is the whole install there and the binding drives the kern it was published with.
+ * Mirrors `_bundled_kern`, which finds the Linux wheel's copy.
+ *
+ * FOUND NEXT TO THIS FILE AND NOWHERE ELSE. A kern taken by position from some other directory can be
+ * a copy installed by hand months earlier; `root` is the package's own directory, so only a binary
+ * this package brought is taken. A source checkout has no `bin/` and falls through to PATH. A file
+ * that is there but cannot be executed (a `noexec` mount, an archive-backed install) falls through
+ * too, rather than failing a call that a `kern` on PATH could serve. `root` is a parameter for the
+ * tests only. */
+function bundledKern(root = __dirname) {
+  if (process.platform !== "linux") return null;
+  const cand = path.join(root, "bin", `linux-${process.arch}`, "kern");
+  try {
+    fs.accessSync(cand, fs.constants.X_OK);
+    return fs.statSync(cand).isFile() ? cand : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Locate `kern`: $KERN_BIN if set, else the kern this package carries (see `bundledKern`), else the
+ * first `kern` on $PATH. The result is also IDENTIFIED as kern (see `verifyIsKern`): being executable
+ * and being named `kern` are not the same as being kern. `root` is for the tests only. */
+function findKern(root = __dirname) {
   const env = process.env.KERN_BIN;
   if (env) {
     try {
@@ -1354,6 +1505,11 @@ function findKern() {
     verifyIsKern(env);
     return env;
   }
+  const bundled = bundledKern(root);
+  if (bundled) {
+    verifyIsKern(bundled);
+    return bundled;
+  }
   const exts = [""];
   const dirs = (process.env.PATH || "").split(path.delimiter).filter(Boolean);
   for (const d of dirs) {
@@ -1371,25 +1527,21 @@ function findKern() {
     }
   }
   // On macOS the generic "install it" is a dead end: there is no macOS build to install. kern needs
-  // a Linux kernel, so the answer is a VM, and the error says which one rather than leaving the
-  // reader hunting for a download that does not exist.
+  // a Linux kernel, so the answer is a VM, and inside one the same `npm install` brings kern.
   if (process.platform === "darwin")
     throw new SandboxError(
-      "the `kern` binary was not found on PATH, and this is macOS: kern is Linux-only " +
-        "(no namespaces, no cgroups on a Mac), so there is no macOS build to find. " +
-        "Run inside a Linux VM (colima, Lima, OrbStack, UTM) and install it there with:\n" +
-        "    curl -fsSL https://raw.githubusercontent.com/getkern/kern/main/install.sh | sh\n" +
-        "or set $KERN_BIN to a kern reachable from here.",
+      "kern was not found, and this is macOS: kern is Linux-only (no namespaces, no cgroups on a " +
+        "Mac), so there is no macOS build. Run your code inside a Linux VM (colima, Lima, OrbStack, " +
+        "UTM) and install this package there:\n" +
+        "    npm install kern-sandbox\n" +
+        "On Linux x64 and arm64 that brings kern with it. Or set $KERN_BIN to a kern reachable from here.",
     );
-  // THE COMMAND, NOT A LINK. `npm install kern-sandbox` does NOT bring the binary: this package is a
-  // wrapper around a process it does not ship, and the moment a user meets that fact is this error.
-  // It used to answer with a repository URL, which asks someone one paste away from working to go
-  // and read a page first. The same sentence the Python binding gives, deliberately: two wrappers
-  // around one runtime must not disagree about how to get it, and the installer line is the one the
-  // project's README leads with.
+  // THE COMMAND, NOT A LINK. Reached on Linux only when this copy carries no binary for the machine:
+  // an architecture the package has no kern for, or a source checkout. The installer is the same
+  // line the Python binding and the project's README give, so the three cannot drift apart.
   throw new SandboxError(
-    "the `kern` binary was not found on PATH. `npm install kern-sandbox` installs this wrapper, " +
-      "not the runtime it drives - install kern with:\n" +
+    `kern was not found: this copy of kern-sandbox carries no kern binary for linux-${process.arch} ` +
+      "(the npm package carries one for x64 and arm64) and there is none on PATH. Install kern with:\n" +
       "    curl -fsSL https://raw.githubusercontent.com/getkern/kern/main/install.sh | sh\n" +
       "or point $KERN_BIN at a kern you already have.",
   );
@@ -1960,6 +2112,11 @@ function tarParse(gz) {
 }
 
 class Sandbox {
+  // The box name the `--show-config` probe uses. A FIXED placeholder: kern refuses an empty name
+  // ("invalid box name: box name is empty", measured) and a per-call name would put itself in the
+  // output and make every fingerprint unique.
+  static FINGERPRINT_PROBE = "kern-fingerprint-probe";
+
   /**
    * @param {object} [opts]
    * @param {string} [opts.image]            OCI image the box runs from. Default a small Python image.
@@ -1967,6 +2124,20 @@ class Sandbox {
    * @param {string} [opts.workspace]        host dir to persist as the workspace. null -> a temp dir,
    *                                          created on open() and DELETED on close().
    * @param {number|null} [opts.memoryMb]    RAM cap (kern --memory). Default 512.
+   *   ⚠️ A `memory.high` ABOVE THE BOX TURNS AN OOM INTO A STALL, and kern reports it. The
+   *   cap is enforced (the box's own `memory.max` carries it and `memory.swap.max` is 0, so swap
+   *   cannot defeat it), and the kernel declares the OOM fast: one cell, a 400 MiB allocation under
+   *   a 128 MiB cap, was killed in 127 ms on a WSL2 kernel 6.18, 645 ms on a kernel 6.8 server and
+   *   0.06 s on a Jetson Orin (kernel 5.15-tegra). That Jetson first measured 317 s because its
+   *   `kern.slice` carried `MemoryHigh=80M` from an old `systemctl --user set-property`: above a
+   *   `memory.high` the kernel THROTTLES instead of killing, so every box under that slice stalled
+   *   past 80 MiB in total, whatever its own cap. Since `timeoutS` defaults to 30, under such a
+   *   limit the CELL deadline fires first: you get a `timeout` fault rather than an `oom` one, and
+   *   with `persist: true` the box dies LATER, so a subsequent call is the one that finds it gone and
+   *   recreates it. kern reports such a limit when it starts a box under one: a `kern: note:` line
+   *   in `result.stderr` naming the cgroup and the command that lifts it; `kern doctor` and
+   *   `kern inspect` show it too. kern does not change it. Same facts as the Python binding's
+   *   `memory_mb`.
    * @param {number|null} [opts.cpus]        CPU cap in cores; null = uncapped.
    * @param {number|null} [opts.pids]        task/fork-bomb ceiling. Default 256.
    * @param {number} [opts.timeoutS]         MANDATORY per-call wall-clock limit (binding-owned). Default 30.
@@ -1994,6 +2165,62 @@ class Sandbox {
           "should run (it runs once, with the network on)",
       );
     this.workspace = opts.workspace ?? null;
+    // Refuse to start a call once the workspace holds more than this many bytes. `null` is off and
+    // costs nothing: the walk only runs when a cap is set.
+    //
+    // ⛔ A COOPERATIVE CAP, NOT A BOUNDARY. The workspace is a host directory bind-mounted at
+    // /workspace, so the box writes to the real filesystem and nothing in the kernel holds it back.
+    // kern's other limits ARE boundaries, measured to the byte. This one cannot be from here: a
+    // kernel-enforced quota needs a disk-backed vdisk (mkfs.ext4, root) and this binding is rootless,
+    // while a size-capped tmpfs would be enforced and would NOT survive between calls, which is the
+    // one thing a workspace must do. So it bounds damage ACROSS calls, not within one: the call that
+    // exceeds it still runs, the next is refused. Said plainly, because a cap that sounds like a
+    // boundary and is not is worse than no cap at all.
+    this.workspaceMaxBytes = opts.workspaceMaxBytes ?? null;
+    // A STABLE IDENTITY, used only with `persist`. Two processes that name the same sandbox meet the
+    // same resident box.
+    this.name = opts.name ?? null;
+    // Keep ONE resident box alive and run every call inside it with `kern exec`, instead of starting
+    // a throwaway box per call. Survives `close()`: that is the point, and why `destroy()` exists.
+    //
+    // ⭐ MEASURED: `kern exec` into a resident box is 2 ms against 6 ms for a fresh box, and whatever
+    // a previous call left in the box is still there for the next - across PROCESSES, not just calls.
+    //
+    // ⛔ A resident box is NOT a fresh box. /tmp ACCUMULATES instead of starting empty; the network
+    // posture is whatever the box was CREATED with, which is why it is part of the fingerprint; the
+    // PID namespace is SHARED across calls. What does NOT leak, measured: a process a previous call
+    // left running - `kern exec` reaps its descendants when it returns, including one detached with
+    // setsid, which is why the resident box runs `--init`.
+    //
+    // ⛔ AND THE VERDICT IS COARSER. `oom` is read from the teardown bytes kern writes for the box IT
+    // started; `kern exec` does not carry them and the registry keeps only exitCode 137, which an
+    // external kill produces too. So an OOM comes back `killed` on this path where the one-shot path
+    // says `oom`. Not papered over: claiming `oom` from "137 and a cap was set" would be an inference
+    // presented as a measurement.
+    //
+    // 📌 WHAT ADOPTION KEYS ON, AND THE TWO THINGS IT DELIBERATELY DOES NOT. A box is adopted when
+    // its fingerprint matches: the argv, the `KERN_*` environment kern builds the box from, and what
+    // a `vcpu:`/`vgpio:`/`vdisk:` token resolves to in your kern.toml. That is the ISOLATION
+    // posture, which is what a caller is promised. Two things it does not key on, both decisions
+    // rather than gaps:
+    //
+    //   * THE BYTES BEHIND A FLOATING IMAGE TAG. `image: "python:3.12-slim"` is hashed as that
+    //     string, not as the digest it currently resolves to, so a box built before an ordinary
+    //     re-pull of the same tag is still adopted. Keying on the digest would refuse resumption
+    //     after every security update of the base image, and the isolation is identical either way.
+    //     ⭐ If resume must mean the same image bytes, PIN IT: `image: "python@sha256:..."` is a
+    //     valid reference, it goes into the argv and therefore into the fingerprint (verified:
+    //     three distinct hashes for a tag and two different digests).
+    //   * THE BODY OF AN APPARMOR PROFILE. `apparmor: "name"` hashes the NAME; replacing the policy
+    //     loaded under that name on the host changes enforcement without moving the fingerprint.
+    //     That is host administration, in the same class as replacing the kernel under a running
+    //     box, and not something this binding can observe portably.
+    this.persist = opts.persist ?? false;
+    // How long the resident box lives. It is kern's own `--timeout` on that box, so it ends by itself
+    // if the owning process dies: a resident sandbox cannot leak for longer than this.
+    this.persistTtlS = opts.persistTtlS ?? 3600;
+    this._resident = null;
+    this._residentCalls = 0;
     this.memoryMb = opts.memoryMb === undefined ? 512 : opts.memoryMb;
     this.cpus = opts.cpus ?? null;
     this.pids = opts.pids === undefined ? 256 : opts.pids;
@@ -2046,7 +2273,7 @@ class Sandbox {
      * there is nothing to wait for, which is what keeps the check on the call path free. */
     this._pycPending = "";
     // Capabilities dropped from every box this sandbox starts, as kern's own `--cap-drop` takes them.
-    // The default drops the lot: kern already drops 14 dangerous capabilities unconditionally, but the
+    // The default drops the lot: kern already drops 16 dangerous capabilities unconditionally, but the
     // rest were still held over the box's own user namespace, on the one code path whose purpose is
     // running code nobody has read. Defence in depth rather than the boundary itself, and measured to
     // cost nothing. It is NOT behaviour-free: a workload binding a port below 1024 INSIDE the box
@@ -2218,7 +2445,35 @@ class Sandbox {
       this._ownWs = false;
     }
     this._entered = true;
+    // THE RESIDENT BOX, adopted or created, BEFORE `setup` runs: a setup on a persistent sandbox has
+    // to install into the box every later call will use, not into a throwaway one.
+    if (this.persist) {
+      if (!this.name)
+        throw new SandboxError(
+          "persist needs a name: it is the identity two processes meet on. " +
+            'new Sandbox({ name: "my-agent", persist: true, workspace: "..." })',
+        );
+      if (this.workspace === null)
+        // A TEMPORARY WORKSPACE WOULD MAKE THIS HALF-PERSISTENT, and silently: the box would be
+        // adopted while its FILES started empty in a fresh directory every process, and the
+        // fingerprint (which contains the workspace path, because the mount is part of the posture)
+        // would never match twice, so no adoption could ever succeed.
+        throw new SandboxError(
+          "persist needs an explicit workspace: the resident box is adopted by posture, and a " +
+            "temporary workspace is a different path in every process, so nothing would ever be " +
+            "resumed. new Sandbox({ name, persist: true, workspace })",
+        );
+    }
     if (this.setup) await this._runSetup(this.setup);
+    // THE RESIDENT BOX IS CREATED AFTER THE SETUP, AND THAT ORDER IS THE FIX. It used to come first,
+    // so `_runSetup` was routed into it (network silently dropped), and `_baseArgv` mounts
+    // `<workspace>/.deps` READ-ONLY only `if` that directory exists - which it did not yet, so the
+    // resident box was created WITHOUT the mount and `kern exec` never re-applies mounts. The
+    // `depsReadonly` default is true and is documented as the defence against cross-run dependency
+    // poisoning: it was off for the whole life of every resident box. The setup does not need to run
+    // IN the resident box, because it installs into `<workspace>/.deps`, a HOST directory every
+    // later box mounts. Same reasoning, same measurements, as the Python binding.
+    if (this.persist) this._resident = await this._residentEnsure();
     // THE BYTECODE CACHE IS DECIDED HERE, once, and frozen: `_baseArgv` is what the prewarm pool
     // compares postures with, so a cache appearing mid-session would change the argv runCode builds and
     // every claim would miss. SKIPPED WHEN A SETUP LEFT DEPS: `PYTHONPYCACHEPREFIX` redirects every
@@ -2269,6 +2524,213 @@ class Sandbox {
 
   /** Close the session: tear down any prewarmed boxes, then delete the workspace iff we created it.
    * Idempotent. */
+  // ---- resident box (`persist: true`) ---------------------------------------------------------
+
+  _residentName() {
+    return `${RESIDENT_PREFIX}${this.name}`;
+  }
+
+  /**
+   * The posture a resident box BAKES IN, taken from the argv that would create it.
+   *
+   * ADOPTION IS THE DANGEROUS HALF OF THIS FEATURE: a caller who asks for memoryMb 256 and is handed
+   * a box someone else created with 512 has been told a limit is in force that is not. So the posture
+   * is hashed at creation, stamped into a label, and compared on adoption; a mismatch is refused with
+   * both values named rather than resolved by guessing.
+   *
+   * ⭐ TAKEN FROM `_baseArgv` AND NOT RE-LISTED. A hand-written list of the fields that matter is a
+   * second spelling of the posture, and the two drift the first time a flag is added: the new flag
+   * changes what the box IS without changing the fingerprint, so a box built before it gets adopted
+   * by a Sandbox that asks for it. The NAME is stripped before hashing - it is identity, not posture.
+   */
+  // ASYNC, because resolving a `vcpu:`/`vgpio:`/`vdisk:` token means asking kern. Only one
+  // production caller (`_residentEnsure`, already async) and the tests await it. `runCapture` and
+  // not `spawnSync`: this file's own rule, and a synchronous spawn here would stop every timer and
+  // socket in the host process.
+  async _residentFingerprint() {
+    return crypto
+      .createHash("sha256")
+      .update(await this._postureMaterial({ network: this.network, timeoutS: Math.trunc(this.persistTtlS) }))
+      .digest("hex")
+      .slice(0, 16);
+  }
+
+  // EVERYTHING THAT DETERMINES WHAT A BOX IS, as one string, spelled ONCE.
+  //
+  // 🚨 THIS EXISTS BECAUSE THE SAME HOLE WAS FOUND TWICE. First the resident fingerprint was found
+  // to omit the `KERN_*` environment, then to omit what a `vcpu:`/`vgpio:` token
+  // RESOLVES to. Both were fixed in the fingerprint - and the prewarm pool's key, which is the same
+  // question asked by a different mechanism, kept the second hole. Measured in the Python binding:
+  // with `profiles: ["vcpu:agent"]` and the definition changed from `cpus=1, memory="128M"` to
+  // `cpus=4, memory="4G"`, the pool key was the SAME both times while the fingerprint differed. A
+  // pool is adoption under another name: it hands a call a box that was built earlier.
+  async _postureMaterial({ network, timeoutS }) {
+    const argv = this._baseArgv("", { network, timeoutS, dry: true });
+    // AND THE CONTROLS THAT NEVER REACH argv ARE ADDED EXPLICITLY. Taking the posture from
+    // `_baseArgv` answers the drift problem for everything that IS a flag; `enforceLimits` is not a
+    // flag, it is `KERN_NO_SCOPE=1` in the spawn's ENVIRONMENT, so it changed whether the caps are
+    // kernel-enforced while leaving the argv byte for byte identical. Measured in the Python binding
+    // before the same fix: `enforceLimits` true and false produced ONE fingerprint, so an unenforced
+    // box could be adopted by a Sandbox that had asked for enforcement.
+    argv.push(`--enforce-limits=${this.enforceLimits ? 1 : 0}`);
+    // AND EVERY `KERN_*` IN THE ENVIRONMENT, because kern reads its OWN environment when it BUILDS
+    // the box: `KERN_SECCOMP` picks the seccomp filter, and `KERN_ALLOW_UNCAPPED`,
+    // `KERN_LANDLOCK_REQUIRED`, `KERN_DIRECT_CAPS` and `KERN_CONFIG` all change what the box is,
+    // with none of them in the argv. Measured in the Python binding: six different settings produced
+    // ONE fingerprint, so a box built under one filter could be adopted by a Sandbox asking for
+    // another - and the dangerous direction is adopting a WEAKER filter while believing in the
+    // stronger. The prewarm pool in this same file already folds these in, with its own measurement;
+    // the resident path did not follow it.
+    //
+    // ⛔ `KERN_BIN` is excluded: it selects which binary to run and that binary's resolved path is
+    // already argv[0] above, so hashing the variable too would refuse adoption between two processes
+    // that found the SAME binary by different means (one with the variable, one through PATH).
+    const kernEnv = Object.entries(process.env)
+      .filter(([k]) => k.startsWith("KERN_") && k !== "KERN_BIN")
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([k, v]) => `${k}=${v}`)
+      .join("\u0000");
+    let material = `${argv.join("\u0000")}\u0000\u0000${kernEnv}`;
+    // AND WHAT A `vcpu:`/`vgpio:`/`vdisk:` TOKEN RESOLVES TO. A profile is a positional token that
+    // `kern box` resolves against the user's kern.toml: the TOKEN is in the argv above, the
+    // DEFINITION is not. Measured in the Python binding: the same `vcpu:agent` with `cpus = 1,
+    // memory = "128M"` and then `cpus = 4, memory = "4G"` produced ONE fingerprint, so a box created
+    // under one definition is adopted under another and the caller is told its own limits are in
+    // force. `vgpio:` profiles are the only way to give a box a hardware device, so the collision
+    // spans a DEVICE GRANT and not just a number.
+    //
+    // ASKED OF kern, not re-derived: re-reading kern.toml here would be a second opinion about
+    // kern's own resolution (KERN_CONFIG > --config > XDG > ~/.config, plus `extends`) and two
+    // opinions drift. A MINIMAL argv - the image, the tokens, nothing else - because everything else
+    // about the posture is already in the material above. Measured: 2 ms, no pull, and it does not
+    // require the image to exist. The spawn is only paid when a profile is asked for.
+    //
+    // FAIL CLOSED: if the probe cannot answer this throws rather than falling back to the
+    // argv-only hash, which would reopen exactly this hole.
+    if (this._profileArgs.length > 0) {
+      const probe = [
+        this._kern, "box", Sandbox.FINGERPRINT_PROBE, "--image", this.image, "--show-config",
+        ...this._profileArgs, "--", "/bin/true",
+      ];
+      const shown = await runCapture(probe, 60000);
+      if (shown.code !== 0)
+        throw new SandboxError(
+          `the resource profiles ${JSON.stringify(this.profiles || [])} do not resolve, so the ` +
+            `resident sandbox posture cannot be compared: ` +
+            `${(shown.stderr || shown.stdout || "").trim().slice(0, 300)}`,
+        );
+      // ⛔ A kern TOO OLD TO DESCRIBE A GRANT IS REFUSED, not hashed around. Before the device and
+      // disk lines existed, `--show-config` printed what a `vcpu:` profile yields and nothing a
+      // `vgpio:`/`vdisk:` profile yields, so two device grants under one token gave one fingerprint.
+      // The fix lives in kern, so this binding is only protected when paired with a kern that has
+      // it. With a `vgpio:`/`vdisk:` token and no `devices:` line the posture cannot be known.
+      // `vcpu:` alone is not refused: memory and cpus have always been printed.
+      const grants = this._profileArgs.some((t) => ["vgpio", "vdisk"].includes(t.split(":")[0]));
+      if (grants && !shown.stdout.split("\n").some((l) => l.startsWith("devices:")))
+        throw new SandboxError(
+          `the kern at ${this._kern} cannot describe what a vgpio:/vdisk: profile grants ` +
+            `(its --show-config prints no \`devices:\` line), so a box built earlier cannot be ` +
+            `matched to this posture and is not reused. Upgrade kern to a version that prints the ` +
+            `granted devices`,
+        );
+      material += `\u0000\u0000${shown.stdout}`;
+    }
+    return material;
+  }
+
+  /** The running resident box for this name, or null. Never throws: a registry that cannot be read is
+   * the same answer as no box, and both lead to creating one. */
+  async _residentLookup() {
+    const r = await runCapture(
+      [this._kern, "ps", "--filter", `name=${this._residentName()}`, "--json"],
+      20000,
+    );
+    if (r.code !== 0 || !r.stdout.trim()) return null;
+    let data;
+    try {
+      data = JSON.parse(r.stdout);
+    } catch {
+      return null;
+    }
+    const rows = Array.isArray(data) ? data : [data];
+    for (const row of rows)
+      if (row && row.name === this._residentName())
+        return row.status === "running" ? row : null;
+    return null;
+  }
+
+  /**
+   * Adopt the resident box or create it, and return its name.
+   *
+   * THE RACE IS REAL AND IS HANDLED BY LOSING GRACEFULLY. Two processes naming the same sandbox can
+   * reach the create at the same moment; kern refuses a duplicate name, so the loser looks the box up
+   * again and adopts what the winner made, verified by the same fingerprint - so losing the race
+   * cannot smuggle in a different posture.
+   */
+  async _residentEnsure() {
+    const want = await this._residentFingerprint();
+    const found = await this._residentLookup();
+    if (found) {
+      const have = (found.labels || {})[CFG_LABEL];
+      if (have !== want)
+        throw new SandboxError(
+          `a resident sandbox named ${JSON.stringify(this.name)} is already running with a ` +
+            `DIFFERENT posture (its fingerprint is ${JSON.stringify(have)}, this Sandbox asks for ` +
+            `${JSON.stringify(want)}), so adopting it would report limits that are not the ones in ` +
+            `force. Use another name, or stop it: kern stop ${this._residentName()}`,
+        );
+      return this._residentName();
+    }
+    // THE SAME ARGV THE ONE-SHOT PATH USES, so the resident box carries identical mounts, caps, tmpfs
+    // and environment - plus `-d` to detach, `--init` so PID 1 REAPS, the fingerprint label, and a
+    // PID 1 that does nothing else. `--init` and not a bare `sleep`: `sleep` never calls wait(), so a
+    // process a call detached became a zombie and they accumulated until pids.max refused a fork.
+    const argv = [
+      ...this._baseArgv(this._residentName(), {
+        network: this.network,
+        timeoutS: Math.trunc(this.persistTtlS),
+      }),
+      "-d",
+      "--init",
+      "--label",
+      `${CFG_LABEL}=${want}`,
+      "--",
+      "sleep",
+      String(Math.trunc(this.persistTtlS)),
+    ];
+    // THE ENVIRONMENT IS BUILT, NOT INHERITED. Without this the box took whatever `KERN_NO_SCOPE`
+    // was in the ambient environment: `enforceLimits: false` never reached the box (only `_spawn`'s
+    // children got it, which on this path are `kern exec` calls and not the box's own cgroup
+    // placement), and a shell that merely had the variable exported created an unenforced box for a
+    // Sandbox that asked for enforcement - the dangerous direction.
+    const createEnv = { ...process.env };
+    if (this.enforceLimits) delete createEnv.KERN_NO_SCOPE;
+    else createEnv.KERN_NO_SCOPE = "1";
+    const made = await runCapture(argv, 180000, createEnv);
+    if (made.code !== 0) {
+      const again = await this._residentLookup();
+      if (again && (again.labels || {})[CFG_LABEL] === want) return this._residentName();
+      throw new SandboxError(
+        `could not start the resident sandbox ${JSON.stringify(this.name)}: ` +
+          `${(made.stderr || made.stdout || "").trim().slice(0, 400)}`,
+      );
+    }
+    return this._residentName();
+  }
+
+  /**
+   * Stop the resident box. The ONLY way a `persist` sandbox goes away before its TTL.
+   *
+   * Deliberately not `close()`: a sandbox that disappeared when the session ended would be the
+   * one-shot behaviour under another name, and nothing would be resumable. Idempotent and quiet:
+   * stopping a box that is already gone is the state the caller asked for.
+   */
+  async destroy() {
+    if (!this.name) return;
+    await runCapture([this._kern, "stop", this._residentName()], 60000);
+    this._resident = null;
+  }
+
   async close() {
     // Boxes first: they are live processes holding the workspace we are about to delete, and a box
     // still writing into a directory being removed is how a teardown turns into a stale mount.
@@ -2501,16 +2963,88 @@ class Sandbox {
     pycStartSweep(path.dirname(dest));
   }
 
-  _spawn(command, { network, timeoutS, isSetup = false, onStdout = UNSET, onStderr = UNSET }) {
+  /**
+   * One call, with ONE repair of a resident box that has died.
+   *
+   * THE BOX CAN BE GONE, AND IT IS NOT AN EXOTIC CASE. `memory.oom.group=1` means an OOM takes the
+   * WHOLE cgroup, so a cell that overruns its memory cap destroys the resident box rather than just
+   * its own process - MEASURED in the Python binding: the next call came back `startup_failed` and
+   * the sandbox was silently unusable from then on. The TTL expiring does the same on a longer clock.
+   *
+   * CHECKED BY TRYING, NOT BY ASKING: a `kern ps` before every call would spend a second process
+   * spawn on the hot path and buy nothing in the common case, which is the 2 ms this feature exists
+   * for. ONE retry and never a loop: a box that dies again immediately has a cause that is not
+   * transient, and retrying would hide it behind a hang.
+   */
+  async _spawn(command, opts) {
+    const r = await this._spawnOnce(command, opts);
+    if (
+      this._resident === null ||
+      (opts && opts.isSetup) ||
+      !String(r.stderr || "").includes(RESIDENT_GONE)
+    )
+      return r;
+    const lost = this._residentCalls;
+    this._resident = await this._residentEnsure();
+    this._residentCalls = 0;
+    // SAID OUT LOUD, because the repair is not free and the caller cannot see it. The box is new: its
+    // /tmp is empty again and anything a previous call installed into it is gone. Only the WORKSPACE
+    // survived, because that is a host directory. Repairing this silently would hand back a sandbox
+    // that looks continuous and is not - the caller would debug missing state instead of a dead box.
+    process.emitWarning(
+      `the resident sandbox ${JSON.stringify(this.name)} had died (an OOM takes the whole box, and ` +
+        `the TTL ends it) after serving ${lost} call(s); it was recreated and this call re-run. Its ` +
+        `in-box state is gone - /tmp is empty and anything installed into the box is not there. ` +
+        `Files under the workspace are unaffected.`,
+      "KernResidentRecreated",
+    );
+    return this._spawnOnce(command, opts);
+  }
+
+  _spawnOnce(command, { network, timeoutS, isSetup = false, onStdout = UNSET, onStderr = UNSET }) {
     this._pycAdoptIfReady(); // one property read once there is nothing left to wait for
     const cbOut = onStdout === UNSET ? this.onStdout : onStdout;
     const cbErr = onStderr === UNSET ? this.onStderr : onStderr;
     for (const part of command)
       if (typeof part !== "string" || part.includes("\0"))
         throw new SandboxError("command/code must be strings with no NUL byte");
+    // THE WORKSPACE CAP, CHECKED BEFORE THE WORK AND NOT AFTER IT. A call that has already run cannot
+    // be un-run, and its output is what the caller needs most when something went wrong, so refusing
+    // afterwards would destroy the evidence to enforce a limit the write had already passed. Costs
+    // nothing when unset, which is the default.
+    if (this.workspaceMaxBytes !== null && this._ws) {
+      const used = workspaceUsage(this._ws);
+      if (used > this.workspaceMaxBytes)
+        throw new SandboxError(
+          `workspace holds ${used} bytes, over the ${this.workspaceMaxBytes}-byte ` +
+            `workspaceMaxBytes, so this call was refused before running. The box writes to a host ` +
+            `directory (${this._ws}), so this is a cooperative cap and not a kernel boundary: it ` +
+            `bounds what accumulates ACROSS calls, and one call can still exceed it. Delete what the ` +
+            `session no longer needs, raise the cap, or give the Sandbox a workspace on a filesystem ` +
+            `you are willing to fill`,
+        );
+    }
     const before = this.trackFiles ? this._snapshot() : null; // skip the O(N) walk when not tracked
     const name = uniqueName();
-    const argv = [...this._baseArgv(name, { network, timeoutS, isSetup }), "--", ...command];
+    let argv;
+    // `&& !isSetup`: A SETUP NEVER RUNS IN THE RESIDENT BOX, even if one already exists. The setup
+    // box is defined by three properties - separate, network ON, dies at the end - and `kern exec`
+    // into a running box provides none of them: the resident box is created with a runCode posture,
+    // which is network-OFF, and exec cannot add a network to a box already running. Routing a setup
+    // there dropped `network: true` in SILENCE, so `setup: "pip install X"` failed with a DNS error.
+    // Same fix and same reason as the Python binding; `_enter` also creates the resident box after
+    // the setup now, so in the normal path there is nothing to route into.
+    if (this._resident !== null && !isSetup) {
+      // INTO THE RESIDENT BOX, which is the point of `persist`. `exec` and not `box`: measured, 2 ms
+      // against 6 ms, and the box's own state is still there. `-w` puts the call in the same working
+      // directory a fresh box starts in, so code writing a relative path lands in the workspace
+      // exactly as it does on the one-shot path. `timeoutS` is NOT passed to kern here: the resident
+      // box carries its own TTL, and the binding's deadline is enforced around this process.
+      this._residentCalls += 1;
+      argv = [this._kern, "exec", this._resident, "-w", WORKSPACE, "--", ...command];
+    } else {
+      argv = [...this._baseArgv(name, { network, timeoutS, isSetup }), "--", ...command];
+    }
     const childEnv = { ...process.env };
     if (!this.enforceLimits) childEnv.KERN_NO_SCOPE = "1";
     // Unforgeable "box started" channel: kern writes one byte to fd 3 iff its sandbox setup SUCCEEDED
@@ -2631,7 +3165,14 @@ class Sandbox {
               `interpreter line names something the image lacks.` +
               // The one case where the remedy is not "a different image": every image has a POSIX
               // shell, so a caller who asked for bash and does not need bash has a one-word fix.
-              (what === "bash" ? " This image has no bash; use language:'sh' if the script is POSIX." : "");
+              (what === "bash" ? " This image has no bash; use language:'sh' if the script is POSIX." : "") +
+              // NODE HAS NO IN-IMAGE FALLBACK, so the remedy is the image, and it is NAMED. Kept
+              // word-for-word in step with the Python binding: the two are one API with two
+              // spellings, and a message that differs between them is a product that differs.
+              (what === "node"
+                ? ` No image kern defaults to carries node; name one that does, e.g.` +
+                  ` new Sandbox({ image: "node:22-slim" }).`
+                : "");
           } else if (reason.includes("Permission denied")) {
             detail = "Permission denied: it is present in the box but not executable there.";
           } else {
@@ -3267,6 +3808,25 @@ class Sandbox {
         `unsupported language ${JSON.stringify(language)} (v1: 'python' | 'bash' | 'sh' | 'node')`,
       );
     const [runner, evalFlag, ext] = spec;
+    // REFUSED HERE, BECAUSE THE ANSWER IS ALREADY KNOWN, and this binding advertised it hardest:
+    // the example at the top of this file was `runCode("console.log(1 + 1)", { language: "node" })`,
+    // which cannot work as written because the default image has no node. MEASURED on
+    // python:3.12-slim: python, sh and bash 5.2 all run there, node does not. So a caller who leaves
+    // the image alone is told at the moment of the choice, with the remedy, rather than paying a box
+    // start to be told the same thing by an `exec_failed` fault.
+    //
+    // ⛔ ONLY for the default image. For an image the caller NAMED, kern does not know what is inside
+    // it, and refusing on a guess would be inventing a measurement; that case still reaches the box.
+    // Kept identical to the Python binding, which has the same check for the same reason: the two
+    // are one API with two spellings, and a divergence here is a divergence in the product.
+    if (language === "node" && this.image === DEFAULT_IMAGE && !DEFAULT_IMAGE_HAS_NODE) {
+      throw new SandboxError(
+        `language='node' needs an image that provides node, and this Sandbox is on the default ` +
+          `${JSON.stringify(DEFAULT_IMAGE)}, which does not (it provides python, sh and bash). ` +
+          `Name one that does, e.g. new Sandbox({ image: "node:22-slim" }), or run the code with ` +
+          `language='python'.`,
+      );
+    }
     const eff = this._effTimeout(timeoutS);
     if (language === "python")
       return this._runPythonCell(code, { timeoutS: eff, onStdout, onStderr });
@@ -3299,7 +3859,7 @@ class Sandbox {
     // adopted here is already in the key and the boxes warmed without it are retired as stale.
     this._pycAdoptIfReady();
     if (this._pool && !streaming && !code.includes("\0")) {
-      const warm = this._pool.claim({ network: this.network, deadlineS: eff });
+      const warm = await this._pool.claim({ network: this.network, deadlineS: eff });
       if (warm) {
         const before = this.trackFiles ? this._snapshot() : null;
         return warm.runCell(code, { deadlineS: eff, before });
@@ -4268,19 +4828,29 @@ class WarmPool {
    * filled would have been served a box built under the previous filter. Every `KERN_*` variable is
    * folded in, rather than the handful we can name today, because the failure mode is a variable nobody
    * thought to list. */
-  _key(network) {
-    const argv = this._sbx._baseArgv("", { network, timeoutS: 0, dry: true }).join("\0");
-    const env = Object.entries(process.env)
-      .filter(([k]) => k.startsWith("KERN_"))
-      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-      .map(([k, v]) => `${k}=${v}`)
-      .join("\0");
-    return `${argv}\0\0${env}`;
+  // ⭐ ONE SPELLING, SHARED WITH THE RESIDENT FINGERPRINT, and async for the same reason it is:
+  // resolving a profile token means asking kern. ⛔ Computed at CLAIM time and not cached, because
+  // the question is "does this warm box match what THIS call would create" and a cached answer would
+  // say yes to a box built before a `kern.toml` edit. Measured in the Python binding: 1.33 ms per
+  // claim WITH a profile, 0.039 ms without - the spawn is only paid when a profile is asked for.
+  async _key(network) {
+    return this._sbx._postureMaterial({ network, timeoutS: 0 });
   }
 
-  claim({ network, deadlineS }) {
+  async claim({ network, deadlineS }) {
     if (this._closed || this._size <= 0) return null;
-    const key = this._key(network);
+    // THE POOL STEPS ASIDE WHEN THE POSTURE CANNOT BE KNOWN; it does not fail the call. `_key`
+    // throws when a profile cannot be resolved or kern is too old to print a `vgpio:` grant. The
+    // resident path is right to throw on that; the pool is an optimisation, and the call it would
+    // have served can always start a fresh box from the live argv, which has the right posture by
+    // construction. Same decision, same reason, as the Python binding.
+    let key;
+    try {
+      key = await this._key(network);
+    } catch (e) {
+      if (e instanceof SandboxError) return null;
+      throw e;
+    }
     let picked = null;
     const keep = [];
     const stale = [];
@@ -4321,7 +4891,7 @@ class WarmPool {
     let box = null;
     let ok = false;
     try {
-      box = new WarmBox(this._sbx, this._key(network), deadlineS, (b) => this._sweep(b));
+      box = new WarmBox(this._sbx, await this._key(network), deadlineS, (b) => this._sweep(b));
       ok = (await box.start()) && (await box.waitReady());
     } catch {
       ok = false;
@@ -4400,6 +4970,16 @@ module.exports = {
   Result,
   SandboxError,
   MountRefused,
+  // The prewarm pool, exported for its tests only, and under an underscore for the same reason the
+  // bytecode cache's internals are below: a pool key is the same posture question the resident
+  // fingerprint asks, the two were allowed to drift once, and the test that stops them doing it
+  // again has to be able to ask the pool directly. The Python binding exposes it the same way.
+  _WarmPool: WarmPool,
+  // Where the binding finds kern, exported for its tests only: the order ($KERN_BIN, the package's
+  // own copy, PATH) decides which binary runs every box, and only a test that can hand these a
+  // package root can assert it without writing a `bin/` into this checkout.
+  _bundledKern: bundledKern,
+  _findKern: findKern,
   // The bytecode cache's internals, exported for its tests only: the mount flag and the atomic
   // publish are security properties, and a test that cannot reach them cannot assert them.
   _PYC_MOUNT: PYC_MOUNT,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kern-sandbox",
-  "version": "0.2.39",
+  "version": "0.2.43",
   "description": "Your model writes the code. This runs it where it can't touch your machine: a rootless Linux container, no daemon, no VM, no cloud, no account. A kernel boundary, not a microVM: for deliberately hostile code, use one.",
   "keywords": [
     "sandbox",
@@ -30,13 +30,15 @@
   "files": [
     "index.js",
     "index.d.ts",
-    "README.md"
+    "README.md",
+    "bin/"
   ],
   "engines": {
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "prepublishOnly": "node -e \"for (const a of ['x64', 'arm64']) if (!require('fs').existsSync('bin/linux-' + a + '/kern')) { console.error('kern-sandbox: bin/linux-' + a + '/kern is missing. Publish the tarball build-package.py writes, not this directory.'); process.exit(1) }\""
   },
   "os": [
     "linux"