@molecule/api-code-sandbox-e2b 1.2.6 → 1.2.8

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-04T09:45:27.540Z
+Generated: 2026-10-05T07:29:02.107Z
 -->
 
 # @molecule/api-code-sandbox-e2b
@@ -25,9 +25,8 @@ the official `e2b` SDK.
 The design that makes it fast: a single golden SUPERSET template carries the
 entire `@molecule` fleet node_modules + postgres + warmed Vite deps, so a boot
 only copies the ONE selected app's source in and starts the dev servers — no
-per-boot `npm install`. The 133 flagship template sources are NOT baked into
-the image; they are copied from the control plane at boot, so templates and
-`mlcl` stay private.
+per-boot `npm install`. The app template sources are not baked into the
+image; they are copied in at boot.
 
 ## Quick Start
 
@@ -181,7 +180,7 @@ interface E2BConfig {
    * time; everything else is denied (`denyOut: [ALL_TRAFFIC]`). Wildcards like
    * `*.npmjs.org` are supported. Empty/omitted means the bond does NOT
    * constrain egress — prod must supply this or `verifyEgress` observes `open`
-   * and the control plane refuses to boot (Rule 18).
+   * and the control plane refuses to boot.
    *
    * Verified against a live E2B sandbox: with `denyOut: [ALL_TRAFFIC]`, a
    * non-allowlisted host AND a raw destination IP are both blocked — a stronger
@@ -401,8 +400,7 @@ Only the required surface (`create`/`get`/`list`/`destroy`) plus the boot-path
 optionals are wired here; `verifyEgress` and `commitTemplate`/`getTemplate`
 land in follow-up steps. Leaving `verifyEgress` UNimplemented is deliberate:
 the control plane treats "unsupported" as `inconclusive` and refuses to boot
-in prod, which is the correct safe default until egress observation is proven
-(Rule 18 — never trade cost for security).
+in prod, which is the correct safe default until egress observation is proven.
 
 ### Functions
 
@@ -414,8 +412,7 @@ Turn the probe's curl codes into a verdict.
   egress was OBSERVED;
 - `inconclusive` whenever the allow-listed control host did not answer — a
   probe sandbox with no network at all blocks everything, which says nothing
-  about the policy (2026-10-04: `host=000, rawIP=000, allowed=000` was read
-  as open and production refused to boot);
+  about the policy;
 - `filtered` only when the control host answered AND both denied probes were
   blocked (`000` / empty).
 
@@ -498,13 +495,19 @@ Peer dependencies:
 - `@molecule/api-i18n`
 - `e2b`
 
-**`verifyEgress` OBSERVES, it never attests.** It boots a throwaway sandbox,
-applies `{ allowOut: [npm], denyOut: [ALL_TRAFFIC] }`, and curls an
-allow-listed host, a non-allow-listed host AND a raw IP from inside it;
-`filtered` requires the last two to be blocked while the first answers. Any
-failure to run that probe is `inconclusive` — never `filtered`, because "I
-could not look" must not reach a control plane as "I looked, and it is safe"
-(Rule 18: never trade cost for security).
+- `importFiles` spools an incoming archive into the sandbox in 8 MB pieces
+  whatever the size of the chunks it is given; `exportFiles` reads the whole
+  archive into memory once, so bound what you export.
+- `importFiles` trusts the stream's length: an archive cut exactly between two
+  tar members extracts cleanly (tar exits 0) and is reported complete. Give it
+  a stream that errors on truncation (an authenticated encrypted stream does)
+  or check a length or hash yourself.
+  **`verifyEgress` OBSERVES, it never attests.** It boots a throwaway sandbox,
+  applies `{ allowOut: [npm], denyOut: [ALL_TRAFFIC] }`, and curls an
+  allow-listed host, a non-allow-listed host AND a raw IP from inside it;
+  `filtered` requires the last two to be blocked while the first answers. Any
+  failure to run that probe is `inconclusive` — never `filtered`, because "I
+  could not look" must not reach a control plane as "I looked, and it is safe".
 
 **A probe that sees NO network is `inconclusive`, not `open`.** When the
 allow-listed control host does not answer either, the probe sandbox itself has
@@ -585,8 +588,7 @@ can never be given a project's volume afterwards — a project that needs one
 must be booted fresh with it.
 
 **Volumes are a private beta on E2B.** An account without them answers
-`403 use of volumes is not enabled` (measured on the production account,
-2026-08-16); ask E2B support to enable them. Every volume method throws in
+`403 use of volumes is not enabled`; ask E2B support to enable them. Every volume method throws in
 that state rather than no-op-ing, because a control plane that believes it has
 durable storage and does not is the failure this bond exists to prevent.
 

package/dist/index.d.ts

@@ -12,9 +12,8 @@
  * The design that makes it fast: a single golden SUPERSET template carries the
  * entire `@molecule` fleet node_modules + postgres + warmed Vite deps, so a boot
  * only copies the ONE selected app's source in and starts the dev servers — no
- * per-boot `npm install`. The 133 flagship template sources are NOT baked into
- * the image; they are copied from the control plane at boot, so templates and
- * `mlcl` stay private.
+ * per-boot `npm install`. The app template sources are not baked into the
+ * image; they are copied in at boot.
  *
  * @example
  * ```typescript
@@ -39,13 +38,19 @@
  * ```
  *
  * @remarks
+ * - `importFiles` spools an incoming archive into the sandbox in 8 MB pieces
+ *   whatever the size of the chunks it is given; `exportFiles` reads the whole
+ *   archive into memory once, so bound what you export.
+ * - `importFiles` trusts the stream's length: an archive cut exactly between two
+ *   tar members extracts cleanly (tar exits 0) and is reported complete. Give it
+ *   a stream that errors on truncation (an authenticated encrypted stream does)
+ *   or check a length or hash yourself.
  * **`verifyEgress` OBSERVES, it never attests.** It boots a throwaway sandbox,
  * applies `{ allowOut: [npm], denyOut: [ALL_TRAFFIC] }`, and curls an
  * allow-listed host, a non-allow-listed host AND a raw IP from inside it;
  * `filtered` requires the last two to be blocked while the first answers. Any
  * failure to run that probe is `inconclusive` — never `filtered`, because "I
- * could not look" must not reach a control plane as "I looked, and it is safe"
- * (Rule 18: never trade cost for security).
+ * could not look" must not reach a control plane as "I looked, and it is safe".
  *
  * **A probe that sees NO network is `inconclusive`, not `open`.** When the
  * allow-listed control host does not answer either, the probe sandbox itself has
@@ -126,8 +131,7 @@
  * must be booted fresh with it.
  *
  * **Volumes are a private beta on E2B.** An account without them answers
- * `403 use of volumes is not enabled` (measured on the production account,
- * 2026-08-16); ask E2B support to enable them. Every volume method throws in
+ * `403 use of volumes is not enabled`; ask E2B support to enable them. Every volume method throws in
  * that state rather than no-op-ing, because a control plane that believes it has
  * durable storage and does not is the failure this bond exists to prevent.
  *

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6JG;AAEH,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiKG;AAEH,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -12,9 +12,8 @@
  * The design that makes it fast: a single golden SUPERSET template carries the
  * entire `@molecule` fleet node_modules + postgres + warmed Vite deps, so a boot
  * only copies the ONE selected app's source in and starts the dev servers — no
- * per-boot `npm install`. The 133 flagship template sources are NOT baked into
- * the image; they are copied from the control plane at boot, so templates and
- * `mlcl` stay private.
+ * per-boot `npm install`. The app template sources are not baked into the
+ * image; they are copied in at boot.
  *
  * @example
  * ```typescript
@@ -39,13 +38,19 @@
  * ```
  *
  * @remarks
+ * - `importFiles` spools an incoming archive into the sandbox in 8 MB pieces
+ *   whatever the size of the chunks it is given; `exportFiles` reads the whole
+ *   archive into memory once, so bound what you export.
+ * - `importFiles` trusts the stream's length: an archive cut exactly between two
+ *   tar members extracts cleanly (tar exits 0) and is reported complete. Give it
+ *   a stream that errors on truncation (an authenticated encrypted stream does)
+ *   or check a length or hash yourself.
  * **`verifyEgress` OBSERVES, it never attests.** It boots a throwaway sandbox,
  * applies `{ allowOut: [npm], denyOut: [ALL_TRAFFIC] }`, and curls an
  * allow-listed host, a non-allow-listed host AND a raw IP from inside it;
  * `filtered` requires the last two to be blocked while the first answers. Any
  * failure to run that probe is `inconclusive` — never `filtered`, because "I
- * could not look" must not reach a control plane as "I looked, and it is safe"
- * (Rule 18: never trade cost for security).
+ * could not look" must not reach a control plane as "I looked, and it is safe".
  *
  * **A probe that sees NO network is `inconclusive`, not `open`.** When the
  * allow-listed control host does not answer either, the probe sandbox itself has
@@ -126,8 +131,7 @@
  * must be booted fresh with it.
  *
  * **Volumes are a private beta on E2B.** An account without them answers
- * `403 use of volumes is not enabled` (measured on the production account,
- * 2026-08-16); ask E2B support to enable them. Every volume method throws in
+ * `403 use of volumes is not enabled`; ask E2B support to enable them. Every volume method throws in
  * that state rather than no-op-ing, because a control plane that believes it has
  * durable storage and does not is the failure this bond exists to prevent.
  *

package/dist/provider.d.ts

@@ -17,8 +17,7 @@ import type { E2BConfig, E2BSandboxClientLike } from './types.js';
  * optionals are wired here; `verifyEgress` and `commitTemplate`/`getTemplate`
  * land in follow-up steps. Leaving `verifyEgress` UNimplemented is deliberate:
  * the control plane treats "unsupported" as `inconclusive` and refuses to boot
- * in prod, which is the correct safe default until egress observation is proven
- * (Rule 18 — never trade cost for security).
+ * in prod, which is the correct safe default until egress observation is proven.
  */
 export declare class E2BSandboxProvider implements SandboxProvider {
     readonly name = "e2b";
@@ -284,8 +283,7 @@ export interface EgressProbeCodes {
  *   egress was OBSERVED;
  * - `inconclusive` whenever the allow-listed control host did not answer — a
  *   probe sandbox with no network at all blocks everything, which says nothing
- *   about the policy (2026-10-04: `host=000, rawIP=000, allowed=000` was read
- *   as open and production refused to boot);
+ *   about the policy;
  * - `filtered` only when the control host answered AND both denied probes were
  *   blocked (`000` / empty).
  *

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,qBAAqB,EAErB,aAAa,EAKb,oBAAoB,EACpB,kBAAkB,EAClB,OAAO,EACP,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,eAAe,EAGf,UAAU,EACX,MAAM,4BAA4B,CAAA;AAEnC,OAAO,KAAK,EAGV,SAAS,EACT,oBAAoB,EAMrB,MAAM,YAAY,CAAA;AA+yBnB;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,YAAW,eAAe;IACxD,QAAQ,CAAC,IAAI,SAAQ;IAErB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0D;IACjF,OAAO,CAAC,aAAa,CAA6C;IAClE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAsB;IAEtD;;;;;OAKG;gBACS,MAAM,GAAE,SAAc,EAAE,cAAc,CAAC,EAAE,oBAAoB;IAYzE;;;;OAIG;YACW,MAAM;IASpB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrD;;;;;;;;;;;;;;OAcG;YACW,aAAa;IAkD3B;;;;;OAKG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAoB9C;;;;;;;;;;;;;;;OAeG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAkC7D;;;;;OAKG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAgB/C;;;;OAIG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC;;;;;;;;;OASG;YACW,aAAa;IAM3B;;;;;OAKG;YACW,UAAU;IASxB;;;;;;;;;;;;;;OAcG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/C;;;;OAIG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU/C;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIlD;;;;;;;;;;OAUG;IACG,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAmBtE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IA6B9E;;;;;;;;;OASG;IACG,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAoBtE;;;;;;;;;OASG;IACG,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAmB/E;;;;;;;;;;OAUG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAevD;;;;;;;;;;;OAWG;IACG,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC;IAwB5C;;;;;OAKG;YACW,YAAY;IAa1B;;;;;OAKG;YACW,WAAW;CA6B1B;AAED,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAA;IACf,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAA;IAClB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,GAAG,aAAa,CA8B1E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,GAAE,SAAc,EACtB,cAAc,CAAC,EAAE,oBAAoB,GACpC,kBAAkB,CAEpB;AAED,kEAAkE;AAClE,eAAO,MAAM,QAAQ,EAAE,eAAkC,CAAA"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,qBAAqB,EAErB,aAAa,EAKb,oBAAoB,EACpB,kBAAkB,EAClB,OAAO,EACP,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,eAAe,EAGf,UAAU,EACX,MAAM,4BAA4B,CAAA;AAEnC,OAAO,KAAK,EAGV,SAAS,EACT,oBAAoB,EAMrB,MAAM,YAAY,CAAA;AAu2BnB;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,YAAW,eAAe;IACxD,QAAQ,CAAC,IAAI,SAAQ;IAErB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0D;IACjF,OAAO,CAAC,aAAa,CAA6C;IAClE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAsB;IAEtD;;;;;OAKG;gBACS,MAAM,GAAE,SAAc,EAAE,cAAc,CAAC,EAAE,oBAAoB;IAYzE;;;;OAIG;YACW,MAAM;IASpB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrD;;;;;;;;;;;;;;OAcG;YACW,aAAa;IAkD3B;;;;;OAKG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAoB9C;;;;;;;;;;;;;;;OAeG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAkC7D;;;;;OAKG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAgB/C;;;;OAIG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC;;;;;;;;;OASG;YACW,aAAa;IAM3B;;;;;OAKG;YACW,UAAU;IASxB;;;;;;;;;;;;;;OAcG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/C;;;;OAIG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU/C;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIlD;;;;;;;;;;OAUG;IACG,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAmBtE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IA6B9E;;;;;;;;;OASG;IACG,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAoBtE;;;;;;;;;OASG;IACG,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAmB/E;;;;;;;;;;OAUG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAevD;;;;;;;;;;;OAWG;IACG,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC;IAwB5C;;;;;OAKG;YACW,YAAY;IAa1B;;;;;OAKG;YACW,WAAW;CA6B1B;AAED,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAA;IACf,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAA;IAClB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,GAAG,aAAa,CA8B1E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,GAAE,SAAc,EACtB,cAAc,CAAC,EAAE,oBAAoB,GACpC,kBAAkB,CAEpB;AAED,kEAAkE;AAClE,eAAO,MAAM,QAAQ,EAAE,eAAkC,CAAA"}

package/dist/provider.js

@@ -26,6 +26,23 @@ const DEFAULT_SPAWN_TIMEOUT_MS = 60 * 60 * 1000;
  * this instead of the caller's whole timeout.
  */
 const SETTLE_PROBE_MS = 1_500;
+/**
+ * How long to wait for the handle to REPORT the exit code after the started pid
+ * is confirmed gone. envd closes the output stream right behind a real exit, so
+ * a finished command's `end` event — the only thing that carries its exit code —
+ * lands within this window; only a stream held by a stranded descendant
+ * outlives it.
+ */
+const EXIT_REPORT_GRACE_MS = 2_000;
+/**
+ * The exit code reported when a command's outcome cannot be observed at all:
+ * the started pid is gone but the stream it was reading is still held, so the
+ * SDK never delivers the `end` event that carries the real code. 128+SIGKILL
+ * (137), the conventional status of a killed process — because "unknown" must
+ * read as failure, never as the fabricated `0` that once reported a killed
+ * build (partial `dist/` and all) as a successful one.
+ */
+const EXIT_CODE_UNKNOWN = 137;
 /** Default lifetime for a PTY session; same reasoning as {@link DEFAULT_SPAWN_TIMEOUT_MS}. */
 const DEFAULT_PTY_TIMEOUT_MS = 60 * 60 * 1000;
 /**
@@ -309,6 +326,14 @@ class E2BSandbox {
      * running and the caller's own timeout is the right bound. Never a guess from
      * the shape of the command.
      *
+     * But "over" is not "succeeded": the SDK delivers the exit code on the
+     * stream's `end` event, and the descendant holding the stream keeps that
+     * event from ever arriving. A gone pid therefore gets a bounded grace window
+     * for the handle to report the real code, and a handle that never does is
+     * reported as {@link EXIT_CODE_UNKNOWN} — failure — because an outcome that
+     * cannot be observed (a build OOM-killed mid-run) must never be fabricated
+     * into success.
+     *
      * @param handle - The started command.
      * @returns The command's result.
      */
@@ -328,11 +353,29 @@ class E2BSandbox {
         const alive = await this.isProcessAlive(handle.pid);
         if (alive)
             return finished;
-        // The process is gone; whatever still holds the stream is not it.
+        // The process is gone; whatever still holds the stream is not it. The real
+        // exit code rides the stream's `end` event, so give the handle a bounded
+        // window to deliver it — when the process truly finished, envd closes the
+        // stream right behind it and the result lands here.
+        const reported = await Promise.race([
+            finished,
+            new Promise((resolve) => setTimeout(() => resolve(null), EXIT_REPORT_GRACE_MS)),
+        ]);
+        if (reported)
+            return reported;
+        if (typeof handle.exitCode === 'number') {
+            return { stdout: handle.stdout ?? '', stderr: handle.stderr ?? '', exitCode: handle.exitCode };
+        }
+        // Still nothing: the exit code is UNKNOWN. Reporting `0` here used to
+        // fabricate success for exactly this shape — a killed build whose stranded
+        // daemon held the stream shipped its partial `dist/` as a finished site —
+        // so fail closed instead, with a line that says why the code is missing.
+        const unknownNote = `e2b: exit code unknown — the started process (pid ${handle.pid}) is gone but its ` +
+            'output stream is still held, so its real outcome cannot be observed; reporting failure';
         return {
             stdout: handle.stdout ?? '',
-            stderr: handle.stderr ?? '',
-            exitCode: handle.exitCode ?? 0,
+            stderr: handle.stderr ? `${handle.stderr}\n${unknownNote}` : unknownNote,
+            exitCode: EXIT_CODE_UNKNOWN,
         };
     }
     /**
@@ -646,7 +689,8 @@ class E2BSandbox {
      * Extract a POSIX tar stream into the sandbox at `path`.
      *
      * The transfer primitive the scaffold path uses to copy a project tree in.
-     * Buffers the stream, writes it as one blob, and `tar x`-tracts it.
+     * Spools the stream into the sandbox in 8 MB pieces, so the archive is never
+     * held whole in memory, then extracts it with `tar x`.
      * `--no-same-owner --no-same-permissions` enforces the contract that a
      * caller/tenant-authored archive's ownership + setuid/setgid bits are NOT
      * restored (they arrive owned by the sandbox user, no privilege bits).
@@ -679,10 +723,18 @@ class E2BSandbox {
         };
         try {
             for await (const chunk of archive) {
-                pending.push(chunk);
-                pendingBytes += chunk.length;
-                if (pendingBytes >= IMPORT_PIECE_BYTES)
-                    await flush();
+                // Sliced into the piece: a single chunk larger than a piece (a whole
+                // archive yielded at once) must not become one huge write (R93-B9).
+                let offset = 0;
+                while (offset < chunk.length) {
+                    const room = IMPORT_PIECE_BYTES - pendingBytes;
+                    const slice = chunk.subarray(offset, offset + room);
+                    pending.push(slice);
+                    pendingBytes += slice.length;
+                    offset += slice.length;
+                    if (pendingBytes >= IMPORT_PIECE_BYTES)
+                        await flush();
+                }
             }
             await flush();
             if (pieces === 0)
@@ -710,9 +762,6 @@ class E2BSandbox {
      * <name>`), so `exportFiles('/workspace/my-app')` yields `my-app/…` — the
      * shape Docker's archive endpoint produces and the shape every consumer
      * (`importFiles(<parent>)`, host-side unpackers with `strip: 1`) expects.
-     * The previous `tar -C <path> .` rooting yielded `./…`, which
-     * `importFiles('/')` extracted at the filesystem root instead of the
-     * directory it was taken from.
      *
      * @param path - Absolute path inside the sandbox to archive (not `/`).
      * @returns A POSIX tar byte stream of that path's contents.
@@ -725,15 +774,22 @@ class E2BSandbox {
         if (!trimmed.startsWith('/') || !name) {
             throw new Error(`exportFiles: path must be an absolute directory below "/" (got "${path}")`);
         }
-        const tarPath = `/tmp/mol-export-${Date.now().toString(36)}.tar`;
-        const r = await this.sbx.commands.run(`tar cf ${tarPath} -C ${shellQuote(parent)} ${shellQuote(name)}`, { timeoutMs: 300_000 });
-        if (r.exitCode !== 0) {
-            throw new Error(`exportFiles: tar create failed (${r.exitCode}): ${r.stderr.slice(0, 300)}`);
+        // A unique name (two exports in one millisecond collided on Date.now()
+        // alone), removed whether the tar or the read succeeds or not (R93-B8).
+        const tarPath = `/tmp/mol-export-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}.tar`;
+        let bytes;
+        try {
+            const r = await this.sbx.commands.run(`tar cf ${tarPath} -C ${shellQuote(parent)} ${shellQuote(name)}`, { timeoutMs: 300_000 });
+            if (r.exitCode !== 0) {
+                throw new Error(`exportFiles: tar create failed (${r.exitCode}): ${r.stderr.slice(0, 300)}`);
+            }
+            bytes = await this.sbx.files.read(tarPath, { format: 'bytes' });
+        }
+        finally {
+            await this.sbx.commands.run(`rm -f ${tarPath}`, { timeoutMs: 20_000 }).catch((_error) => {
+                // intentional noop — leftover /tmp tar is harmless; the sandbox is ephemeral.
+            });
         }
-        const bytes = await this.sbx.files.read(tarPath, { format: 'bytes' });
-        await this.sbx.commands.run(`rm -f ${tarPath}`, { timeoutMs: 20_000 }).catch((_error) => {
-            // intentional noop — leftover /tmp tar is harmless; the sandbox is ephemeral.
-        });
         return (async function* () {
             yield bytes;
         })();
@@ -765,8 +821,7 @@ class E2BSandbox {
  * optionals are wired here; `verifyEgress` and `commitTemplate`/`getTemplate`
  * land in follow-up steps. Leaving `verifyEgress` UNimplemented is deliberate:
  * the control plane treats "unsupported" as `inconclusive` and refuses to boot
- * in prod, which is the correct safe default until egress observation is proven
- * (Rule 18 — never trade cost for security).
+ * in prod, which is the correct safe default until egress observation is proven.
  */
 export class E2BSandboxProvider {
     name = 'e2b';
@@ -1344,8 +1399,7 @@ export class E2BSandboxProvider {
  *   egress was OBSERVED;
  * - `inconclusive` whenever the allow-listed control host did not answer — a
  *   probe sandbox with no network at all blocks everything, which says nothing
- *   about the policy (2026-10-04: `host=000, rawIP=000, allowed=000` was read
- *   as open and production refused to boot);
+ *   about the policy;
  * - `filtered` only when the control host answered AND both denied probes were
  *   blocked (`000` / empty).
  *

package/dist/types.d.ts

@@ -42,7 +42,7 @@ export interface E2BConfig {
      * time; everything else is denied (`denyOut: [ALL_TRAFFIC]`). Wildcards like
      * `*.npmjs.org` are supported. Empty/omitted means the bond does NOT
      * constrain egress — prod must supply this or `verifyEgress` observes `open`
-     * and the control plane refuses to boot (Rule 18).
+     * and the control plane refuses to boot.
      *
      * Verified against a live E2B sandbox: with `denyOut: [ALL_TRAFFIC]`, a
      * non-allowlisted host AND a raw destination IP are both blocked — a stronger

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-code-sandbox-e2b",
-  "version": "1.2.6",
+  "version": "1.2.8",
   "description": "E2B (e2b.dev) code sandbox provider — Firecracker microVMs with golden templates, fork, and pause/resume",
   "type": "module",
   "main": "dist/index.js",