kern-sandbox 0.1.15 → 0.1.17

package/README.md

@@ -99,7 +99,10 @@ A non-zero exit from *your code* is **not** a fault (`fault` stays `null`): it i
 | `timeout` | the call exceeded `timeoutS`; the binding killed the box |
 | `escape_blocked` | a syscall was blocked by the seccomp filter (SIGSYS) |
 | `killed` | the box was SIGKILLed, most often the cgroup OOM-killer |
-| `startup_failed` | kern could not start the box (bad image, pull error, ...) |
+
+A box that fails to **start** (kern exits 125: a mount refused at runtime, an unmappable `--user`, a
+seccomp/AppArmor/cgroup setup error, or a pull/image error) is **thrown** as a `SandboxError`, not
+returned as a fault, because the code never ran.
 
 ```js
 const r = await kern.runCode("while True: pass", { timeoutS: 5 });

package/index.js

@@ -36,7 +36,7 @@ const crypto = require("crypto");
 const zlib = require("zlib");
 const { spawn, spawnSync } = require("child_process");
 
-const VERSION = "0.1.15";
+const VERSION = "0.1.17";
 
 const DEFAULT_IMAGE = "python:3.12-slim";
 const WORKSPACE = "/workspace"; // where the persistent workspace is mounted inside every box
@@ -387,8 +387,11 @@ const REFUSED_MOUNT_SOURCES = new Set([
   "/run/docker.sock",
 ]);
 
-/** A PROGRAMMER/config error, THROWN: bad argument, illegal mount, or `kern` not installed. Runtime
- * sandbox events (timeout, blocked escape, OOM-kill) are NOT thrown - they are data in result.fault. */
+/** A PROGRAMMER/config error, THROWN: bad argument, illegal mount, `kern` not installed, or the box
+ * FAILED TO START (kern exits 125 - a mount refused at runtime, an unmappable `--user`, a seccomp or
+ * AppArmor setup error). A box that never started ran no user code, so it rejects rather than resolve a
+ * hollow result. Runtime sandbox events where the code DID run (timeout, blocked escape, OOM-kill) are
+ * NOT thrown - they are data on `result.fault`. */
 class SandboxError extends Error {
   constructor(message) {
     super(message);
@@ -1057,6 +1060,15 @@ class Sandbox {
         const stderr = err.buffer().toString("utf8");
         const rc = toRc(code, signal);
         const fault = this._classify(rc, signal, stderr, timedOut, timeoutS);
+        // A box that FAILED TO START ran no user code, so REJECT rather than resolve a hollow
+        // ExecutionResult (empty stdout). Gated on `rc === 125` (kern's box-not-started code) AND the
+        // startup_failed classification (which requires kern's own stderr marker): the confident pair
+        // that tells a genuine box-not-started apart from a workload that itself exited 125 (no marker ->
+        // fault null -> a normal result). An older kern (127) is returned as a data fault, not thrown.
+        // Runtime events where the code DID run (timeout, OOM, escape) stay as data on `.fault`.
+        if (rc === 125 && fault && fault.type === "startup_failed") {
+          return reject(new SandboxError(fault.message || "the box failed to start"));
+        }
         const files = before ? this._diff(before) : [];
         resolve(
           new ExecutionResult({
@@ -1129,6 +1141,11 @@ class Sandbox {
       return sandboxFault("killed", "the box was killed (SIGKILL) - likely out of memory (exit 137)");
     if (rc === EXIT_SIGTERM || signal === "SIGTERM")
       return sandboxFault("timeout", "the box exceeded its time limit (reaped by kern's timeout backstop)");
+    // Box-not-started: a non-zero exit whose stderr carries kern's OWN setup markers (printed by the
+    // PARENT before the box runs). kern's box-not-started paths BOTH exit 125 AND print a `kern:` marker,
+    // so `rc === 125 && marker` is the reliable signal - the marker is REQUIRED so a workload that merely
+    // exits 125 ITSELF (the code ran and chose 125) is NOT mislabeled. `finish` REJECTS only on rc===125;
+    // a non-125 startup_failed (an older kern's 127, or a forged marker) is returned as DATA, not thrown.
     if (rc !== 0 && looksLikeStartupFailure(stderr))
       return sandboxFault("startup_failed", stderr.trim().slice(0, 500));
     // Any other non-zero exit (incl. 139 SIGSEGV) is the USER's code failing - a normal Result.
@@ -1752,6 +1769,9 @@ class Kernel {
 
   _teardownResult(type, message, started) {
     this._kill();
+    // Same rule as the one-shot path: a box that never STARTED (the kernel failed to boot) throws, it
+    // does not return a hollow result. timeout/killed stay as data on the returned result.
+    if (type === "startup_failed") throw new SandboxError(message || "the box failed to start");
     return new ExecutionResult({
       stdout: "",
       stderr: "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kern-sandbox",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "kern is a fast, rootless sandbox and virtual resource runtime for any workload, including untrusted and AI-generated code; kern-sandbox is its Node/TypeScript binding. Run untrusted or agent-generated code (Python/JS/Bash) in a real, kernel-enforced box in single-digit milliseconds, with no cloud, no account and no VM.",
   "keywords": [
     "sandbox",