@molecule/api-code-sandbox-e2b 1.1.0 → 1.2.0

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-08-15T18:25:48.482Z
+Generated: 2026-08-16T01:25:40.978Z
 -->
 
 # @molecule/api-code-sandbox-e2b
@@ -65,6 +65,40 @@ npm install @molecule/api-code-sandbox-e2b @bufbuild/protobuf @molecule/api-bond
 
 ### Interfaces
 
+#### `E2BCommandHandleLike`
+
+Handle to a command started with `background: true` (the SDK's `CommandHandle`).
+
+The handle is what makes a backgrounded start HONEST: it carries the pid, and
+`wait()` resolves with the real exit code once the started process exits —
+even when it left a detached child behind. A launcher therefore learns whether
+its command was accepted instead of being handed a fabricated success.
+
+```typescript
+interface E2BCommandHandleLike {
+  /** The started process's pid inside the sandbox. */
+  pid: number
+  /** Output accumulated so far — readable before {@link E2BCommandHandleLike.wait} settles. */
+  stdout?: string
+  /** Error output accumulated so far. */
+  stderr?: string
+  /** Set once the process's exit is known; absent while it is still streaming. */
+  exitCode?: number
+  /**
+   * Resolve when the started process exits. Rejects with the SDK's
+   * `CommandExitError` (carrying `.result`) on a non-zero exit, and with a
+   * timeout error when `timeoutMs` elapses first.
+   */
+  wait(): Promise<E2BCommandResultLike>
+  /** Write to the process's stdin (requires `stdin: true` at start). */
+  sendStdin(data: string | Uint8Array): Promise<void>
+  /** Kill the process. */
+  kill(): Promise<boolean>
+  /** Stop streaming without killing the process. */
+  disconnect?(): Promise<void>
+}
+```
+
 #### `E2BCommandResultLike`
 
 Result of an E2B command run (subset of the SDK's `CommandResult`).
@@ -77,22 +111,36 @@ interface E2BCommandResultLike {
 }
 ```
 
+#### `E2BCommandRunOpts`
+
+Options accepted by the SDK's `commands.run`.
+
+```typescript
+interface E2BCommandRunOpts {
+  cwd?: string
+  timeoutMs?: number
+  envs?: Record<string, string>
+  /** Keep stdin open so {@link E2BCommandHandleLike.sendStdin} works. */
+  stdin?: boolean
+  onStdout?: (data: string) => void
+  onStderr?: (data: string) => void
+}
+```
+
 #### `E2BCommandsLike`
 
 Subset of the SDK's `Commands` the bond uses.
 
 ```typescript
 interface E2BCommandsLike {
-  run(
-    cmd: string,
-    opts?: {
-      cwd?: string
-      timeoutMs?: number
-      envs?: Record<string, string>
-      /** Fire-and-forget: returns immediately without waiting for exit. */
-      background?: boolean
-    },
-  ): Promise<E2BCommandResultLike>
+  /**
+   * Start a command and return a handle immediately. The bond always uses this
+   * form: waiting inline blocks until the whole process GROUP ends, which never
+   * happens for a launch that leaves a dev server running.
+   */
+  run(cmd: string, opts: E2BCommandRunOpts & { background: true }): Promise<E2BCommandHandleLike>
+  /** Run a command to completion (the SDK's default). */
+  run(cmd: string, opts?: E2BCommandRunOpts & { background?: false }): Promise<E2BCommandResultLike>
 }
 ```
 
@@ -159,6 +207,31 @@ interface E2BFilesystemLike {
 }
 ```
 
+#### `E2BPtyLike`
+
+Subset of the SDK's `Pty` module the bond uses.
+
+A PTY is a different mechanism from a command, not a flag on one: it has its
+own create/input/resize/kill endpoints, and only it gives the sandbox side a
+controlling terminal (job control, so Ctrl-C becomes SIGINT; a negotiated
+width, so tools format to the real panel size).
+
+```typescript
+interface E2BPtyLike {
+  create(opts: {
+    cols: number
+    rows: number
+    onData: (data: Uint8Array) => void
+    cwd?: string
+    envs?: Record<string, string>
+    timeoutMs?: number
+  }): Promise<E2BCommandHandleLike>
+  sendInput(pid: number, data: Uint8Array): Promise<void>
+  resize(pid: number, size: { cols: number; rows: number }): Promise<void>
+  kill(pid: number): Promise<boolean>
+}
+```
+
 #### `E2BSandboxClientLike`
 
 Subset of the SDK's `Sandbox` static surface the bond uses.
@@ -169,11 +242,27 @@ interface E2BSandboxClientLike {
   connect(sandboxId: string, opts?: Record<string, unknown>): Promise<E2BSandboxLike>
   list(
     opts?: Record<string, unknown>,
-  ): Promise<
-    | Array<{ sandboxId: string; state?: string }>
-    | { sandboxes?: Array<{ sandboxId: string; state?: string }> }
-  >
+  ): Promise<E2BSandboxListItem[] | { sandboxes?: E2BSandboxListItem[] }>
   kill?(sandboxId: string, opts?: Record<string, unknown>): Promise<boolean>
+  /**
+   * Create a team volume. Optional: the volume API is a private beta on E2B, so a
+   * client built against an account without it does not expose these at all.
+   */
+  createVolume?(name: string): Promise<E2BVolumeLike>
+  /** Enumerate team volumes. */
+  listVolumes?(): Promise<E2BVolumeLike[]>
+  /** Destroy a volume by its provider-native id. */
+  destroyVolume?(volumeId: string): Promise<boolean>
+  /**
+   * Capture a sandbox's filesystem + memory as a named snapshot. Re-using a name
+   * assigns a new build to the SAME snapshot rather than creating a second one,
+   * which is what makes a per-project restore point a fixed-size resource.
+   */
+  createSnapshot?(sandboxId: string, name: string): Promise<E2BSnapshotLike>
+  /** Enumerate snapshots, optionally filtered to one exact name. */
+  listSnapshots?(opts?: { name?: string; limit?: number }): Promise<E2BSnapshotLike[]>
+  /** Delete a snapshot. Resolves `false` when there was nothing to delete. */
+  deleteSnapshot?(snapshotId: string): Promise<boolean>
   /**
    * Read a sandbox's record WITHOUT connecting to it — the only lookup that does
    * not resume a paused sandbox. Throws `SandboxNotFoundError` on a 404.
@@ -222,17 +311,71 @@ Subset of the SDK's `Sandbox` instance the bond uses.
 interface E2BSandboxLike {
   sandboxId: string
   commands: E2BCommandsLike
+  /** Present on SDK builds that support pseudo-terminals; absent means no PTY. */
+  pty?: E2BPtyLike
   files: E2BFilesystemLike
   getHost(port: number): string
   setTimeout(ms: number): Promise<void>
   kill(): Promise<void>
-  pause?(): Promise<string>
-  betaPause?(): Promise<string>
+  /**
+   * Suspend the sandbox (FS + memory snapshot). Resolves `false` when the API
+   * answered 409 because it was ALREADY paused — which is a success, not a
+   * failure, and the reason this is not typed as `void`.
+   */
+  pause?(): Promise<boolean>
+  /** Deprecated alias of {@link E2BSandboxLike.pause}; same endpoint. */
+  betaPause?(): Promise<boolean>
   isRunning(): Promise<boolean>
   updateNetwork?(opts: { allowOut?: string[]; denyOut?: string[] }): Promise<void>
 }
 ```
 
+#### `E2BSandboxListItem`
+
+One row of a sandbox listing.
+
+`name` is the template the sandbox booted from (the SDK's `alias`) and
+`volumeMounts` is what it has attached. Both are here for the same reason: they
+are the only way to observe whether a volume or a snapshot is still IN USE, and
+deleting one that is destroys a running sandbox.
+
+```typescript
+interface E2BSandboxListItem {
+  sandboxId: string
+  state?: string
+  /** Template/snapshot name the sandbox booted from, when the API reports one. */
+  name?: string
+  /** Volumes attached to this sandbox. */
+  volumeMounts?: Array<{ name: string; path: string }>
+}
+```
+
+#### `E2BSnapshotLike`
+
+A snapshot as E2B reports it.
+
+`snapshotId` is the namespaced, tag-qualified reference
+(`<team-slug>/<name>:<tag>`) — opaque, and the thing `Sandbox.create()` boots
+from. The bond's OWN identifier is the bare name the caller supplied.
+
+```typescript
+interface E2BSnapshotLike {
+  snapshotId: string
+  names?: string[]
+}
+```
+
+#### `E2BVolumeLike`
+
+A team volume as E2B reports it.
+
+```typescript
+interface E2BVolumeLike {
+  name: string
+  volumeId: string
+}
+```
+
 ### Classes
 
 #### `E2BSandboxProvider`
@@ -319,11 +462,13 @@ Peer dependencies:
 - `@molecule/api-i18n`
 - `e2b`
 
-**`verifyEgress` is intentionally not implemented yet.** The control plane
-treats an absent `verifyEgress` as an `inconclusive` verdict and refuses to
-boot sandboxes in production — the correct safe default until egress
-observation is proven against E2B's `updateNetwork` policy (Rule 18: never
-trade cost for security). Do not stub it with a fabricated `filtered`.
+**`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).
 
 **E2B pauses, it does not stop.** `sleep()`/`stop()` both map to E2B pause
 (FS + memory snapshot); `wake()`/`start()` reconnect by id. `hibernate()`/
@@ -346,6 +491,71 @@ a project's files, answering a transient 5xx with `null` destroys the user's
 code. "I could not look" must never be delivered as "I looked, and it is not
 there". The same rule governs `describe()`.
 
+**`hibernate()`/`stop()`/`sleep()` pause or THROW.** They never resolve a
+success-shaped outcome for a sandbox that is still running: a caller's next act
+is to record the sandbox as stopped, and a control plane that believes a running
+sandbox is asleep bills for it and — with the kill timeout — watches it die at
+its deadline instead of hibernating. Note the converse trap: a pause is undone by
+the very next `get()`, since obtaining a handle connects. Anything that polls a
+stopped sandbox (status, logs, files) must go through `describe()`.
+
+**`exec()` starts the command and waits on its HANDLE, never inline.** E2B's
+inline `commands.run` waits for the whole process GROUP, so any command that
+leaves a detached child behind — `nohup … >log 2>&1 &`, i.e. every dev-server
+launch — blocks until the request deadline and then throws while the child is
+running perfectly. Starting in the background and awaiting the handle returns
+the STARTED process's real exit code in milliseconds, so a launcher learns
+whether its command was accepted. Do not reintroduce the old shortcut of
+sniffing the command string for a trailing `&`: it classified shell text
+instead of observing the process, and got both halves wrong — a launch shaped
+`… & fi` did not match and hung, while a user's `npm run build &` was answered
+with a fabricated empty success.
+
+**`spawn()` is what an editor and a terminal need, and `exec()` cannot give.**
+It returns a live process: streaming stdout/stderr, writable stdin, `kill()`.
+Pass `pty: { cols, rows }` for a real controlling terminal — then Ctrl-C
+(`0x03`) becomes SIGINT for the foreground job and `handle.resize({cols,rows})`
+renegotiates the width. Omit it for a language server, whose framed JSON-RPC a
+PTY would corrupt with echo and CR translation. A PTY request is REJECTED
+rather than downgraded when the SDK build has no `pty` module, because a
+terminal that silently got pipes is a terminal whose Ctrl-C does nothing.
+
+**Two ways to make a project outlive its sandbox, and they are not the same
+strength.** A **volume** (`SandboxConfig.volumeName` + `volumeMountPath`) is
+continuous: every write already lives outside the microVM, so losing the
+sandbox loses nothing. A **snapshot** (`commitTemplate`, restored by
+`create({ templateId })`) is point-in-time: a persistent image that survives
+the sandbox, at the cost of everything written since the capture. Prefer the
+volume; take snapshots when the account has no volumes, or as restore points
+alongside one.
+
+**A volume needs a mount path, and `create()` refuses without one.** E2B
+mounts shadow whatever the image had at that path, and this bond's superset
+template keeps a multi-GB `/workspace/node_modules` there — so the obvious
+default (the workspace root) is the one value that boots a project unable to
+resolve a single import. Mount the app directory instead
+(`/workspace/<appDir>`): the durable source lands on the volume and the
+regenerable tooling stays on the faster image-backed rootfs.
+
+**A volume can only be attached when the sandbox is created.** There is no
+attach-to-a-running-sandbox call, so a sandbox claimed from a pre-warmed pool
+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
+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.
+
+**Snapshots ARE available and they do survive a kill** — verified live: a
+sandbox was killed and a new one created from its snapshot came up with the
+same files, in ~2.3 s. Capturing takes well under a second, leaves the sandbox
+running, and re-using a name replaces that snapshot rather than adding one, so
+a per-project restore point is a fixed-size resource. It BRIEFLY pauses the
+sandbox and drops open connections (PTYs, command streams, websockets), so
+capture when a project goes quiet — never underneath a live terminal.
+
 **Sandboxes are created to PAUSE at their timeout, not to be killed.** E2B's
 default is `onTimeout: 'kill'`, so a sandbox nothing touched for its lifetime
 would be destroyed with its files. This bond creates every sandbox with

package/dist/index.d.ts

@@ -39,11 +39,13 @@
  * ```
  *
  * @remarks
- * **`verifyEgress` is intentionally not implemented yet.** The control plane
- * treats an absent `verifyEgress` as an `inconclusive` verdict and refuses to
- * boot sandboxes in production — the correct safe default until egress
- * observation is proven against E2B's `updateNetwork` policy (Rule 18: never
- * trade cost for security). Do not stub it with a fabricated `filtered`.
+ * **`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).
  *
  * **E2B pauses, it does not stop.** `sleep()`/`stop()` both map to E2B pause
  * (FS + memory snapshot); `wake()`/`start()` reconnect by id. `hibernate()`/
@@ -66,6 +68,71 @@
  * code. "I could not look" must never be delivered as "I looked, and it is not
  * there". The same rule governs `describe()`.
  *
+ * **`hibernate()`/`stop()`/`sleep()` pause or THROW.** They never resolve a
+ * success-shaped outcome for a sandbox that is still running: a caller's next act
+ * is to record the sandbox as stopped, and a control plane that believes a running
+ * sandbox is asleep bills for it and — with the kill timeout — watches it die at
+ * its deadline instead of hibernating. Note the converse trap: a pause is undone by
+ * the very next `get()`, since obtaining a handle connects. Anything that polls a
+ * stopped sandbox (status, logs, files) must go through `describe()`.
+ *
+ * **`exec()` starts the command and waits on its HANDLE, never inline.** E2B's
+ * inline `commands.run` waits for the whole process GROUP, so any command that
+ * leaves a detached child behind — `nohup … >log 2>&1 &`, i.e. every dev-server
+ * launch — blocks until the request deadline and then throws while the child is
+ * running perfectly. Starting in the background and awaiting the handle returns
+ * the STARTED process's real exit code in milliseconds, so a launcher learns
+ * whether its command was accepted. Do not reintroduce the old shortcut of
+ * sniffing the command string for a trailing `&`: it classified shell text
+ * instead of observing the process, and got both halves wrong — a launch shaped
+ * `… & fi` did not match and hung, while a user's `npm run build &` was answered
+ * with a fabricated empty success.
+ *
+ * **`spawn()` is what an editor and a terminal need, and `exec()` cannot give.**
+ * It returns a live process: streaming stdout/stderr, writable stdin, `kill()`.
+ * Pass `pty: { cols, rows }` for a real controlling terminal — then Ctrl-C
+ * (`0x03`) becomes SIGINT for the foreground job and `handle.resize({cols,rows})`
+ * renegotiates the width. Omit it for a language server, whose framed JSON-RPC a
+ * PTY would corrupt with echo and CR translation. A PTY request is REJECTED
+ * rather than downgraded when the SDK build has no `pty` module, because a
+ * terminal that silently got pipes is a terminal whose Ctrl-C does nothing.
+ *
+ * **Two ways to make a project outlive its sandbox, and they are not the same
+ * strength.** A **volume** (`SandboxConfig.volumeName` + `volumeMountPath`) is
+ * continuous: every write already lives outside the microVM, so losing the
+ * sandbox loses nothing. A **snapshot** (`commitTemplate`, restored by
+ * `create({ templateId })`) is point-in-time: a persistent image that survives
+ * the sandbox, at the cost of everything written since the capture. Prefer the
+ * volume; take snapshots when the account has no volumes, or as restore points
+ * alongside one.
+ *
+ * **A volume needs a mount path, and `create()` refuses without one.** E2B
+ * mounts shadow whatever the image had at that path, and this bond's superset
+ * template keeps a multi-GB `/workspace/node_modules` there — so the obvious
+ * default (the workspace root) is the one value that boots a project unable to
+ * resolve a single import. Mount the app directory instead
+ * (`/workspace/<appDir>`): the durable source lands on the volume and the
+ * regenerable tooling stays on the faster image-backed rootfs.
+ *
+ * **A volume can only be attached when the sandbox is created.** There is no
+ * attach-to-a-running-sandbox call, so a sandbox claimed from a pre-warmed pool
+ * 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
+ * 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.
+ *
+ * **Snapshots ARE available and they do survive a kill** — verified live: a
+ * sandbox was killed and a new one created from its snapshot came up with the
+ * same files, in ~2.3 s. Capturing takes well under a second, leaves the sandbox
+ * running, and re-using a name replaces that snapshot rather than adding one, so
+ * a per-project restore point is a fixed-size resource. It BRIEFLY pauses the
+ * sandbox and drops open connections (PTYs, command streams, websockets), so
+ * capture when a project goes quiet — never underneath a live terminal.
+ *
  * **Sandboxes are created to PAUSE at their timeout, not to be killed.** E2B's
  * default is `onTimeout: 'kill'`, so a sandbox nothing touched for its lifetime
  * would be destroyed with its files. This bond creates every sandbox with

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -39,11 +39,13 @@
  * ```
  *
  * @remarks
- * **`verifyEgress` is intentionally not implemented yet.** The control plane
- * treats an absent `verifyEgress` as an `inconclusive` verdict and refuses to
- * boot sandboxes in production — the correct safe default until egress
- * observation is proven against E2B's `updateNetwork` policy (Rule 18: never
- * trade cost for security). Do not stub it with a fabricated `filtered`.
+ * **`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).
  *
  * **E2B pauses, it does not stop.** `sleep()`/`stop()` both map to E2B pause
  * (FS + memory snapshot); `wake()`/`start()` reconnect by id. `hibernate()`/
@@ -66,6 +68,71 @@
  * code. "I could not look" must never be delivered as "I looked, and it is not
  * there". The same rule governs `describe()`.
  *
+ * **`hibernate()`/`stop()`/`sleep()` pause or THROW.** They never resolve a
+ * success-shaped outcome for a sandbox that is still running: a caller's next act
+ * is to record the sandbox as stopped, and a control plane that believes a running
+ * sandbox is asleep bills for it and — with the kill timeout — watches it die at
+ * its deadline instead of hibernating. Note the converse trap: a pause is undone by
+ * the very next `get()`, since obtaining a handle connects. Anything that polls a
+ * stopped sandbox (status, logs, files) must go through `describe()`.
+ *
+ * **`exec()` starts the command and waits on its HANDLE, never inline.** E2B's
+ * inline `commands.run` waits for the whole process GROUP, so any command that
+ * leaves a detached child behind — `nohup … >log 2>&1 &`, i.e. every dev-server
+ * launch — blocks until the request deadline and then throws while the child is
+ * running perfectly. Starting in the background and awaiting the handle returns
+ * the STARTED process's real exit code in milliseconds, so a launcher learns
+ * whether its command was accepted. Do not reintroduce the old shortcut of
+ * sniffing the command string for a trailing `&`: it classified shell text
+ * instead of observing the process, and got both halves wrong — a launch shaped
+ * `… & fi` did not match and hung, while a user's `npm run build &` was answered
+ * with a fabricated empty success.
+ *
+ * **`spawn()` is what an editor and a terminal need, and `exec()` cannot give.**
+ * It returns a live process: streaming stdout/stderr, writable stdin, `kill()`.
+ * Pass `pty: { cols, rows }` for a real controlling terminal — then Ctrl-C
+ * (`0x03`) becomes SIGINT for the foreground job and `handle.resize({cols,rows})`
+ * renegotiates the width. Omit it for a language server, whose framed JSON-RPC a
+ * PTY would corrupt with echo and CR translation. A PTY request is REJECTED
+ * rather than downgraded when the SDK build has no `pty` module, because a
+ * terminal that silently got pipes is a terminal whose Ctrl-C does nothing.
+ *
+ * **Two ways to make a project outlive its sandbox, and they are not the same
+ * strength.** A **volume** (`SandboxConfig.volumeName` + `volumeMountPath`) is
+ * continuous: every write already lives outside the microVM, so losing the
+ * sandbox loses nothing. A **snapshot** (`commitTemplate`, restored by
+ * `create({ templateId })`) is point-in-time: a persistent image that survives
+ * the sandbox, at the cost of everything written since the capture. Prefer the
+ * volume; take snapshots when the account has no volumes, or as restore points
+ * alongside one.
+ *
+ * **A volume needs a mount path, and `create()` refuses without one.** E2B
+ * mounts shadow whatever the image had at that path, and this bond's superset
+ * template keeps a multi-GB `/workspace/node_modules` there — so the obvious
+ * default (the workspace root) is the one value that boots a project unable to
+ * resolve a single import. Mount the app directory instead
+ * (`/workspace/<appDir>`): the durable source lands on the volume and the
+ * regenerable tooling stays on the faster image-backed rootfs.
+ *
+ * **A volume can only be attached when the sandbox is created.** There is no
+ * attach-to-a-running-sandbox call, so a sandbox claimed from a pre-warmed pool
+ * 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
+ * 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.
+ *
+ * **Snapshots ARE available and they do survive a kill** — verified live: a
+ * sandbox was killed and a new one created from its snapshot came up with the
+ * same files, in ~2.3 s. Capturing takes well under a second, leaves the sandbox
+ * running, and re-using a name replaces that snapshot rather than adding one, so
+ * a per-project restore point is a fixed-size resource. It BRIEFLY pauses the
+ * sandbox and drops open connections (PTYs, command streams, websockets), so
+ * capture when a project goes quiet — never underneath a live terminal.
+ *
  * **Sandboxes are created to PAUSE at their timeout, not to be killed.** E2B's
  * default is `onTimeout: 'kill'`, so a sandbox nothing touched for its lifetime
  * would be destroyed with its files. This bond creates every sandbox with