@sema-agent/server 1.323.0 → 2.0.1

package/dist/plugins/remote-env-e2b.js

@@ -1,3 +1,24 @@
+/**
+ * `RemoteContainerExecutionEnv` — the E2B implementation of core's `RemoteExecutionEnv` seam
+ * (core src/core/remote-env.ts, design/48 §5). The service control plane owns this backend; core
+ * owns the seam shape (exactly like `CheckpointStore` / `SqlExecutor`).
+ *
+ * **Scope = design/48 §0.5 v1 minimal slice**: single worker, E2B managed, **Tier 2 only** (every
+ * op runs in a per-task E2B Firecracker VM — no tiering/classification), and the ~4 live seam methods
+ * `connect` / `execStream` / `workspaceHandle` / `destroy` + the base `ExecutionEnv` (FileSystem + Shell).
+ *
+ * **v1.5 (design/49, core 1.69):** `suspendVM` (E2B `pause()`) / `resumeVM` (`Sandbox.connect(id)` auto-resume)
+ * / `postResumeInit` (reachability + at-rest-encryption red line) are IMPLEMENTED — core orchestrates them when
+ * a task with this remote env hits a durable-approval `ask` (workspaceHandle → Checkpoint.state). `reconnect`
+ * (cross-replica re-attach to a still-running VM) stays deferred to **v2** (v1.5 always snapshots → resumeVM).
+ *
+ * **Provider seam discipline (self-host endgame):** every E2B SDK call is confined to this one class. A
+ * future OSS-self-hosted E2B (clay's "最终自部署" constraint) swaps the backend without touching consumers.
+ *
+ * **never-throw invariant:** the base `ExecutionEnv` contract requires every FileSystem/Shell method to
+ * encode failure in the returned `Result` (never throw). The one exception is `execStream`, whose async
+ * iterator MAY throw `RemoteExecutionError` mid-stream before an `exit` chunk (seam contract, OutputChunk).
+ */
 import path from "node:path";
 import { Sandbox, CommandExitError, FileType } from "e2b";
 import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
@@ -5,32 +26,91 @@ import { fileErrorFromExec } from "./remote-env-file-error.js";
 import { numEnvOr } from "./remote-shell.js";
 import { BackgroundShellManager } from "./background-shell-support.js";
 const PROVIDER = "e2b";
+/** E2B default sandbox user home — the workspace root unless overridden. */
 const DEFAULT_MOUNT_PATH = "/home/user";
+/** Default sandbox lifetime if the caller does not set one (E2B bills for this window). */
 const DEFAULT_TIMEOUT_MS = 5 * 60_000;
+/**
+ * 🔴 BL-31 — the E2B sandbox lifetime (`Sandbox.create({ timeoutMs })`) is bounded by E2B's per-sandbox MAX
+ * (≈1h on the fleet plan). A caller that passes a long deadline as the sandbox lifetime — the static-lane leader
+ * forwards `leaderTimeoutMs` (default 24h, the leader's OVERALL deadline) straight through — makes `create()`
+ * reject and `connect()` fail (found live: canary leader judare, 2026-06-17). Clamp the requested lifetime to
+ * this max (env-tunable `E2B_SANDBOX_MAX_MS`, default 1h) — the sandbox lifetime is decoupled from the leader's
+ * overall deadline. A run longer than the clamp needs a sandbox keep-alive/extend (`setTimeout`, follow-up);
+ * today an unclamped 24h simply never connects, so a clamp is strictly safer.
+ */
 const E2B_SANDBOX_MAX_MS = numEnvOr("E2B_SANDBOX_MAX_MS", 3_600_000, 60_000);
+/**
+ * 🔴 Class-fix for the E2B-hang bug (core timeout/liveness contract). Three SEMANTICALLY DISTINCT
+ * timeouts that were previously conflated into the one sandbox-lifetime value:
+ *  - {@link DEFAULT_RPC_TIMEOUT_MS}  — wall-clock bound for a CONTROL-PLANE RPC (create/resume/pause/kill/isRunning/
+ *    files.*). These are "should-be-fast" ops; a provider hang here used to wait the whole lifetime (~30 min).
+ *  - {@link DEFAULT_LIVENESS_MS}     — idle/liveness bound for a COMMAND (exec/execStream): max time with NO output
+ *    AND not yet complete = suspected hang. The precise hang-killer: only kills "zero-progress",
+ *    never a slow-but-streaming `npm ci`. MUST also cover the command-CREATION RPC (hang happens before chunk #1).
+ *  - per-command wall-clock = the caller's explicit `timeout` (slow-but-progressing cap), which MUST NOT fall back
+ *    to the sandbox lifetime. Unset → liveness is the safety net, not the lifetime.
+ */
 const DEFAULT_RPC_TIMEOUT_MS = 60_000;
 const DEFAULT_LIVENESS_MS = 120_000;
+/**
+ * Wall-clock for DATA-TRANSFER / provisioning RPCs (large `files.read`/`files.write`, `suspendVM`/`resumeVM`
+ * snapshot, sandbox `create`/`connect`). 🔴 These legitimately run MINUTES — a short fixed
+ * wall-clock would kill the durable-checkpoint path (suspending a large workspace). E2B's file/lifecycle SDK
+ * exposes NO progress/heartbeat to drive a true idle-bound, so this is a GENEROUS wall-clock; the moment the SDK
+ * surfaces progress, these should move to a real liveness bound. OP-CLASS sized: cheap control RPCs
+ * (isRunning/kill/metadata) keep the short {@link DEFAULT_RPC_TIMEOUT_MS}; this only widens the transfer class.
+ */
 const DEFAULT_DATA_TIMEOUT_MS = 5 * 60_000;
+/**
+ * design/103 background-shell bounds for E2B (TOB). A background process cannot outlive its sandbox, so the BG
+ * timeout ceiling is well under the per-sandbox max ({@link E2B_SANDBOX_MAX_MS}). `maxConcurrent` mirrors the TOC
+ * default (8) — anti fork-bomb, not a workload limit.
+ */
 const E2B_BG_MAX_CONCURRENT = numEnvOr("E2B_BG_MAX_CONCURRENT", 8, 1);
 const E2B_BG_DEFAULT_TIMEOUT_SEC = numEnvOr("E2B_BG_DEFAULT_TIMEOUT_SEC", 300, 1);
 const E2B_BG_MAX_TIMEOUT_SEC = numEnvOr("E2B_BG_MAX_TIMEOUT_SEC", 1800, E2B_BG_DEFAULT_TIMEOUT_SEC);
+/** Pad (sec) added to the E2B command `timeoutMs` backstop so the control-plane hard wall flips status to `killed` FIRST. */
 const E2B_BG_PROVIDER_BACKSTOP_PAD_SEC = 30;
 const ok = (value) => ({ ok: true, value });
+/**
+ * E2B-backed remote `ExecutionEnv`. **Lazy by default (v1b):** the VM is provisioned on the
+ * FIRST FileSystem/Shell/execStream call (auto `connect()`), so a task that never touches the hand pays zero
+ * cost. `connect()` may still be called explicitly (idempotent + concurrency-memoized) if the control plane
+ * wants to provision eagerly. `destroy()` on task end (the Runner calls it via `hasDestroy`); a never-used env's
+ * destroy is a no-op (nothing to kill, no bill). One container per task (design/48 §5 §7 Q7).
+ */
 export class RemoteContainerExecutionEnv {
+    /** Current working directory for relative paths (FileSystem contract; mutable, core may reassign). */
     cwd;
     cfg;
     sandboxApi;
     sbx;
+    /** 🔴 BL-31 keep-alive — the E2B sandbox lifetime is hard-capped (≈1h, {@link E2B_SANDBOX_MAX_MS}), but a long
+     *  leader/repair run legitimately exceeds it. This interval RE-extends the sandbox (`setTimeout(timeoutMs)` resets
+     *  the auto-kill window from now) while the env is held, so the sandbox tracks ACTUAL usage rather than dying
+     *  mid-run at the cap (otherwise: a silent dead sandbox at hour 1). Cleared on destroy;
+     *  a no-op while paused/destroyed. `unref`'d so it never holds the process open. */
     keepAlive;
     handle;
+    /** Terminal once set by {@link destroy} — never reset to false (no resurrection). Guards connect/ensureConnected
+     *  and the post-await re-check in BOTH async-provision paths ({@link doConnect} and {@link doResumeVM}) against
+     *  a destroy that races an in-flight provision/restore. */
     destroyed = false;
+    /** In-flight connect/resume, memoized so concurrent lazy first-use OR resume provisions exactly one VM (no double-bill). */
     connecting;
+    /** Count of exec/execStream calls in flight — `suspendVM` refuses while > 0 (council #4: never snapshot a running command). */
     activeCommands = 0;
+    /** True between a `suspendVM` (VM paused, external connection dead) and the next `resumeVM` reconnect. While
+     *  paused, `this.sbx` still points at the (now-dead) handle, so `resumeVM`'s idempotency guard must NOT treat
+     *  it as live — it has to fall through and actually `Sandbox.connect()`. Without this, a suspend→resume on the
+     *  SAME env instance skips the reconnect and every later fs/exec runs against the dead VM. */
     paused = false;
     constructor(config, deps = {}) {
         this.cfg = {
             ...config,
             mountPath: config.mountPath ?? DEFAULT_MOUNT_PATH,
+            // BL-31: clamp the sandbox lifetime to E2B's per-sandbox max (a 24h leaderTimeoutMs blows the cap → connect fails).
             timeoutMs: Math.min(config.timeoutMs ?? DEFAULT_TIMEOUT_MS, E2B_SANDBOX_MAX_MS),
             allowInternetAccess: config.allowInternetAccess ?? true,
             rpcTimeoutMs: config.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS,
@@ -40,17 +120,30 @@ export class RemoteContainerExecutionEnv {
         this.cwd = this.cfg.mountPath;
         this.sandboxApi = deps.sandboxApi ?? Sandbox;
     }
+    /** design/61 §9: E2B is a FULL RemoteExecutionEnv — an isolated, snapshot-suspendable microVM. (SSH/ADB
+     *  adapters declare {isolation:false, suspendable:false} — real machines/devices, not snapshotable.) */
     capabilities = { isolation: true, suspendable: true };
+    // ─────────────────────────────── RemoteExecutionEnv: lifecycle ───────────────────────────────
     workspaceHandle() {
         if (!this.handle) {
             throw new RemoteExecutionError("connect_failed", "workspaceHandle() called before connect()");
         }
         return this.handle;
     }
+    /**
+     * Public host for a port inside the sandbox (E2B reverse proxy → `<port>-<id>.e2b.app`). The LSP sidecar
+     * (design/64 §13.1) uses this to reach the in-sandbox language-server WS bridge over `wss://`. Lazily
+     * provisions the VM (like exec/fs); `undefined` if it can't connect → the LSP manager degrades.
+     */
     async getHost(port) {
         const conn = await this.ensureConnected();
         return conn.ok ? conn.value.getHost(port) : undefined;
     }
+    /**
+     * Launch a long-running process as a TRUE E2B background command (resolves once launched, E2B keeps it alive)
+     * — for the LSP bridge (design/64 §13.1). NOT the same as `exec` with a shell `&`: E2B reaps a foreground
+     * command's process group on completion, which would kill an in-shell `&`/nohup child. Fire-and-forget.
+     */
     async startBackground(command) {
         const conn = await this.ensureConnected();
         if (conn.ok)
@@ -58,46 +151,57 @@ export class RemoteContainerExecutionEnv {
     }
     async connect(config) {
         if (config?.snapshotId) {
+            // resume-from-snapshot lands via resumeVM (v1.5); connect() just delegates.
             return this.resumeVM(config.snapshotId, config.abortSignal ? { abortSignal: config.abortSignal } : undefined);
         }
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
+        // A paused (suspended) env still HOLDS this.sbx but the external connection is dead — returning it as live
+        // would let a late fs/exec hit the dead VM with a confusing low-level error. Fail clearly until resumeVM.
         if (this.paused)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env is suspended (paused) — resumeVM(snapshotId) before use") };
         if (this.sbx)
-            return ok(this.workspaceHandle());
+            return ok(this.workspaceHandle()); // idempotent: already connected
         if (this.connecting)
-            return this.connecting;
+            return this.connecting; // concurrent first-use shares one provision (lazy path)
         this.connecting = this.doConnect(config);
         const r = await this.connecting;
         if (!r.ok)
-            this.connecting = undefined;
+            this.connecting = undefined; // failed connect → allow a later retry
         return r;
     }
     async doConnect(config) {
         try {
+            // ⚠️ This `await` yields — destroy() can run during it. A destroy that lands here sees sbx===undefined
+            // and returns without killing; if we then blindly assigned + reset `destroyed`, we'd RESURRECT a
+            // destroyed env and orphan a live billable VM (the Runner never calls destroy() twice). So after the
+            // await we re-check `destroyed` and kill-then-bail. Note: destroy is terminal — we never reset it to false.
             const sbx = await this.rpc("sandbox.create", () => this.sandboxApi.create({
                 ...(this.cfg.template ? { template: this.cfg.template } : {}),
                 apiKey: this.cfg.apiKey,
                 timeoutMs: this.cfg.timeoutMs,
                 allowInternetAccess: this.cfg.allowInternetAccess,
                 ...(this.cfg.metadata ? { metadata: this.cfg.metadata } : {}),
+                // Out-of-band secret/config env (never logged) — sandbox-wide so every command + the LSP/bg process
+                // sees it without the value ever touching the model prompt or the tool command string.
                 ...(this.cfg.sandboxEnv && Object.keys(this.cfg.sandboxEnv).length > 0 ? { envs: this.cfg.sandboxEnv } : {}),
             }), config?.abortSignal, this.cfg.dataTimeoutMs);
             if (this.destroyed) {
-                await sbx.kill().catch(() => { });
+                await sbx.kill().catch(() => { }); // raced with destroy() → kill the just-provisioned VM (no leak)
                 return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
             }
             this.sbx = sbx;
             this.paused = false;
-            this.startKeepAlive();
+            this.startKeepAlive(); // BL-31 — keep the sandbox alive past its ≤1h lifetime cap while the env is held.
             this.cfg.logger?.info?.("remote_env_connect", { sandboxId: sbx.sandboxId });
             this.handle = {
                 sandboxId: sbx.sandboxId,
                 provider: PROVIDER,
                 mountPath: this.cfg.mountPath,
-                sessionToken: sbx.sandboxId,
+                sessionToken: sbx.sandboxId, // a still-running E2B VM is re-attachable by its id (Sandbox.connect)
             };
+            // design/48 §5 gap 7: secrets are injected at connect time. v1 defers secret *resolution* to the
+            // control plane (SecretRef carries only name+locator, no value) — recorded, wired in v1b/v1.5.
             if (config?.secrets?.length) {
                 this.cfg.logger?.warn?.("remote-env: connect secrets are not injected in v1 (control-plane resolution deferred)", {
                     count: config.secrets.length,
@@ -111,6 +215,12 @@ export class RemoteContainerExecutionEnv {
             return { ok: false, error: this.remoteError(e, "connect_failed") };
         }
     }
+    /**
+     * v1.5 (design/49): snapshot the workspace via E2B `pause()` (stores fs+memory+process; the snapshot id IS
+     * the sandbox id — a paused E2B sandbox is resumed by its id). Atomic contract (council): on failure the VM
+     * is left UNTOUCHED (still running) so core can fall back to onAsk. Refuses if a command is in flight
+     * (council #4) — never silently snapshot a running command. `abortSignal` bounds a hung pause (council BUG#2).
+     */
     async suspendVM(options) {
         const sbx = this.sbx;
         if (!sbx)
@@ -122,12 +232,18 @@ export class RemoteContainerExecutionEnv {
         }
         try {
             await this.rpc("sandbox.pause", (signal) => sbx.pause({ signal }), options?.abortSignal, this.cfg.dataTimeoutMs);
+            // Same race as doConnect/doResumeVM: this `await` yielded, so destroy() may have landed. If destroy()
+            // killed a still-pausing sandbox its kill can be rejected, leaving a paused-but-unreferenced snapshot
+            // (billed storage until E2B's TTL); and we must NOT report a snapshotId for it — core would persist it
+            // and every later resume would fail. Best-effort kill (symmetric with doConnect/doResumeVM) + bail.
             if (this.destroyed) {
+                // best-effort: if BOTH this and destroy()'s kill fail, a paused snapshot is orphaned (billed storage)
+                // until E2B's TTL — log it (destroy() logs its own kill failures too) so that is observable.
                 await sbx.kill().catch((e) => this.cfg.logger?.warn?.("remote-env: suspend-recheck kill failed (snapshot may orphan)", { error: errMsg(e) }));
                 return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during suspend") };
             }
-            this.paused = true;
-            this.connecting = undefined;
+            this.paused = true; // VM paused → external connection is dead; force resumeVM to actually reconnect
+            this.connecting = undefined; // drop the now-resolved prior provision promise so resumeVM doesn't return it instead of reconnecting
             this.cfg.metrics?.inc("remote_env_suspend_total", { provider: PROVIDER, result: "ok" });
             this.cfg.logger?.info?.("remote_env_suspend", { snapshotId: sbx.sandboxId });
             return ok(sbx.sandboxId);
@@ -137,30 +253,48 @@ export class RemoteContainerExecutionEnv {
             return { ok: false, error: this.remoteError(e, options?.abortSignal?.aborted ? "aborted" : "unknown") };
         }
     }
+    /**
+     * v1.5: restore from a snapshot via E2B `Sandbox.connect(snapshotId)` (auto-resumes a paused sandbox).
+     * Idempotent: a no-op if already on that sandbox. Concurrent resume/connect for the same snapshot share ONE
+     * provision (memoized via `connecting`, like {@link connect}) so a racing call never double-creates a billable
+     * VM (council #3). `abortSignal` bounds a hung restore.
+     */
     async resumeVM(snapshotId, options) {
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "env already destroyed") };
         if (this.sbx && !this.paused && this.sbx.sandboxId === snapshotId)
-            return ok(this.workspaceHandle());
+            return ok(this.workspaceHandle()); // already resumed + live (idempotent); a paused sbx must reconnect
         if (this.connecting)
-            return this.connecting;
+            return this.connecting; // concurrent resume/connect shares one provision (council #3)
         this.connecting = this.doResumeVM(snapshotId, options);
         const r = await this.connecting;
         if (!r.ok)
-            this.connecting = undefined;
+            this.connecting = undefined; // failed resume → allow a later retry
         return r;
     }
     async doResumeVM(snapshotId, options) {
         try {
+            // Carry the SAME apiKey + lifetime as doConnect. `SandboxConnectOpts.timeoutMs` defaults to 5 minutes;
+            // omitting it would reset a resumed VM's lifetime to 5min regardless of cfg.timeoutMs, so a long task
+            // resumed after a durable-approval ask would be reaped by E2B mid-run (snapshot already consumed). The
+            // apiKey is explicit too (don't depend on the SDK's E2B_API_KEY env fallback once keys move to the
+            // control plane). Wrapped in `rpc` so the connect also gets the data-transfer timeout/abort.
             const sbx = await this.rpc("sandbox.connect", (signal) => this.sandboxApi.connect(snapshotId, { apiKey: this.cfg.apiKey, timeoutMs: this.cfg.timeoutMs, signal }), options?.abortSignal, this.cfg.dataTimeoutMs);
+            // Same race as doConnect: this `await` yields → destroy() can land during it. Re-check + kill-then-bail
+            // so we never assign a live VM to a destroyed env (which would orphan a billable sandbox — destroy() is
+            // terminal and won't be called again). (council #1)
             if (this.destroyed) {
                 await sbx.kill().catch(() => { });
                 return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during resume") };
             }
             this.sbx = sbx;
             this.paused = false;
-            this.startKeepAlive();
+            this.startKeepAlive(); // BL-31 — re-arm the keep-alive on a resumed sandbox too.
             this.cfg.logger?.info?.("remote_env_resume", { requested: snapshotId, connected: sbx.sandboxId });
+            // [1467]①(core 1.360 VmLifecycleOptions.priorHandle):恢复根=checkpoint 的 mountPath——E2B resume
+            // 恢复的是整个 VM 文件系统,旧根里的产物原位在;当前配置值只该管新建沙箱。exec/fs/mktemp 三腿同源
+            // 消费 this.cwd,一并重基;handle 回报的就是真生效根(诚实契约:绝不回显未兑现值)。缺 priorHandle
+            // (旧 core/旧 checkpoint)= 落当前配置值——此窗内改 E2B_MOUNT_PATH 仍需先 drain 挂起任务。
             const restoredRoot = options?.priorHandle?.mountPath ?? this.cfg.mountPath;
             this.cwd = restoredRoot;
             this.handle = { sandboxId: sbx.sandboxId, provider: PROVIDER, mountPath: restoredRoot, snapshotId, sessionToken: sbx.sandboxId };
@@ -172,9 +306,17 @@ export class RemoteContainerExecutionEnv {
             return { ok: false, error: this.remoteError(e, options?.abortSignal?.aborted ? "aborted" : "connect_failed") };
         }
     }
+    /** Cross-replica re-attach to a still-running VM = v2 (design/49 council #15: v1.5 always snapshots→resumeVM). */
     async reconnect(_sessionToken) {
         return { ok: false, error: new RemoteExecutionError("unknown", "reconnect is deferred to v2 (v1.5 always snapshots → use resumeVM)") };
     }
+    /**
+     * v1.5: re-establish consistency after resumeVM. The resumed VM is restored to its paused state (fs+memory+
+     * process); this verifies it is reachable. Per-command secrets are re-applied automatically (this adapter
+     * injects envs per command, not persistently). The VM-internal agent rebuilds its own external connections
+     * (git/API don't survive pause). 🔴 At-rest snapshot encryption is the provider's here (E2B managed) — a
+     * self-hosted E2B (v2) MUST guarantee it before any secret injection (remote-env.ts §5 red line).
+     */
     async postResumeInit() {
         const sbx = this.sbx;
         if (!sbx)
@@ -189,12 +331,15 @@ export class RemoteContainerExecutionEnv {
             return { ok: false, error: this.remoteError(e, "post_resume_failed") };
         }
     }
+    /** BL-31 — (re)start the periodic sandbox-lifetime extension. `setTimeout(timeoutMs)` resets the auto-kill window
+     *  from now; we re-arm at ~80% of the (clamped, ≤1h) window so a long-held sandbox never expires mid-run. A no-op
+     *  when paused/destroyed; `unref`'d so it never keeps the process alive; cleared on destroy. */
     startKeepAlive() {
         this.stopKeepAlive();
         const everyMs = Math.max(30_000, Math.floor(this.cfg.timeoutMs * 0.8));
         this.keepAlive = setInterval(() => {
             if (this.destroyed || this.paused || !this.sbx)
-                return;
+                return; // paused/dead → the resume path re-arms it
             void this.sbx.setTimeout(this.cfg.timeoutMs).catch((e) => this.cfg.logger?.warn?.("remote_env_keepalive_failed", { error: errMsg(e) }));
         }, everyMs);
         this.keepAlive.unref?.();
@@ -207,37 +352,47 @@ export class RemoteContainerExecutionEnv {
     }
     async destroy() {
         if (this.destroyed)
-            return;
+            return; // idempotent — safe double-call (Runner end + reaper)
         this.destroyed = true;
         this.connecting = undefined;
-        this.stopKeepAlive();
-        await this.disposeBackgroundShells();
+        this.stopKeepAlive(); // BL-31 — stop extending the sandbox lifetime; it's being killed below.
+        await this.disposeBackgroundShells(); // design/103 §3.7 backstop — clears BG timers (the VM kill below reaps the jobs)
         const sbx = this.sbx;
         this.sbx = undefined;
         if (!sbx)
-            return;
+            return; // never connected (lazy task that didn't touch the hand) → nothing to kill, zero bill
         const startedAt = Date.now();
         try {
             await this.rpc("sandbox.kill", () => sbx.kill());
             this.cfg.metrics?.inc("remote_env_destroy_total", { provider: PROVIDER, result: "ok" });
+            // Symmetric with remote_env_connect: a clean teardown line carrying the same sandboxId
+            // gives the cleanup leg a log-only proof — no need to cross-check the provider's running-sandbox API.
             this.cfg.logger?.info?.("remote_env_destroy", { sandboxId: sbx.sandboxId, ms: Date.now() - startedAt });
         }
         catch (e) {
+            // best-effort, must never throw (cleanup contract)
             this.cfg.metrics?.inc("remote_env_destroy_total", { provider: PROVIDER, result: "error" });
             this.cfg.logger?.warn?.("remote_env_destroy_failed", { sandboxId: sbx.sandboxId, ms: Date.now() - startedAt, error: errMsg(e) });
         }
     }
+    // FileSystem + Shell both declare cleanup(); both map to destroy() (release all VM resources).
     async cleanup() {
         await this.destroy();
     }
+    // ─────────────────────────────── Shell: buffered exec ───────────────────────────────
     async exec(command, options) {
+        // Already cancelled → don't lazily provision a billable VM just to immediately abort it.
         if (options?.abortSignal?.aborted)
             return { ok: false, error: new ExecutionError("aborted", "exec aborted before start") };
-        const conn = await this.ensureConnected();
+        const conn = await this.ensureConnected(); // lazy: first use provisions the VM
         if (!conn.ok)
             return { ok: false, error: new ExecutionError("shell_unavailable", `remote connect failed: ${conn.error.message}`, conn.error) };
         const sbx = conn.value;
-        this.activeCommands++;
+        this.activeCommands++; // in-flight: suspendVM refuses while > 0 (council #4)
+        // design/116 detach (core 1.207, 1.82): the Bash tool threads a `detachSignal` when the operator can mid-flight
+        // ctrl+b. `ExecOpts` doesn't type it yet (core-side seam) — read it structurally. When present, tee all output
+        // into a rolling-tail pair shaped EXACTLY like the bg driver's per-shell state (E2bBgStream) — adoption is then
+        // a zero-copy handover of {handle, stdout, stderr} into the SAME state the launch path builds.
         const detachSignal = options?.detachSignal;
         const tee = detachSignal
             ? {
@@ -251,13 +406,23 @@ export class RemoteContainerExecutionEnv {
             s.tail.push(b);
             s.total += b.length;
         };
-        let lastProgress = Date.now();
+        // Run in the background and keep the handle so an abort can actually KILL the remote process. A plain
+        // `commands.run` only aborts the local request — the VM process keeps running (and billing) until the
+        // sandbox times out. The handle still buffers stdout/stderr; wait() returns the full CommandResult.
+        let lastProgress = Date.now(); // bumped by stdout/stderr → drives the wait()-phase liveness (waitWithLiveness)
         let handle;
         try {
+            // 🔴 Bound the command-CREATION RPC with the liveness timer — a provider hang here (before the
+            // command even starts) used to wait the whole sandbox lifetime. The wait() phase below is then
+            // bounded by waitWithLiveness (idle-bound), so BOTH phases of a hang are covered.
             handle = await this.rpc("commands.run", () => sbx.commands.run(command, {
                 background: true,
                 cwd: this.resolve(options?.cwd ?? this.cwd),
                 ...(options?.env ? { envs: options.env } : {}),
+                // Detach-capable exec: the provider command timeout is fixed at creation, so it must not undercut a
+                // LATER adoption's BG wall — lift it to the BG ceiling (+backstop pad, same discipline as the bg
+                // launch) and enforce the FOREGROUND wall with the control-plane `wallMs` in waitWithLiveness below
+                // (disarmed on adoption). Without a detachSignal the provider timeout stays the wall, as before.
                 timeoutMs: tee
                     ? Math.max(this.commandTimeoutMs(options?.timeout), (E2B_BG_MAX_TIMEOUT_SEC + E2B_BG_PROVIDER_BACKSTOP_PAD_SEC) * 1000)
                     : this.commandTimeoutMs(options?.timeout),
@@ -283,6 +448,8 @@ export class RemoteContainerExecutionEnv {
             this.activeCommands--;
             return { ok: false, error: this.execError(e, options?.abortSignal) };
         }
+        // Post-adoption the abort belongs to the (already-settled) foreground tool call — it must NOT kill the
+        // adopted background job (core aborts the per-call signal right after the early tool result).
         const onAbort = () => { if (!detached)
             void handle.kill().catch(() => { }); };
         if (options?.abortSignal) {
@@ -291,8 +458,10 @@ export class RemoteContainerExecutionEnv {
             else
                 options.abortSignal.addEventListener("abort", onAbort, { once: true });
         }
+        // 🔴 Consume `handle.wait()` exactly ONCE (the SDK processes the command's event stream in it): the foreground
+        // race and the post-adoption terminal notification both hang off this single promise.
         const waitP = handle.wait();
-        let fgResolved = false;
+        let fgResolved = false; // microtask-latch: a detach landing after the command finished must NOT adopt (double-represent)
         const markResolved = () => { fgResolved = true; };
         waitP.then(markResolved, markResolved);
         let fgSettled = false;
@@ -301,8 +470,19 @@ export class RemoteContainerExecutionEnv {
         const detachedP = detachSignal && tee
             ? new Promise((res) => {
                 onDetach = () => {
+                    // 🔴 review MED: E2B's onAbort only fires an async `handle.kill()` (no synchronous settle flag), unlike
+                    // host/k8s whose abort synchronously settles (finish→settled) and whose onDetach guards on it. Without
+                    // `abortSignal?.aborted` here, an abort in flight (kill RPC not yet completed, so `fgResolved` unset)
+                    // followed by a detach would ADOPT a process that is already being killed — the aborted call would return
+                    // detached success and hand the operator a corpse shellId. Align E2B with the settled-blocks-detach rule.
                     if (detached || fgSettled || fgResolved || options?.abortSignal?.aborted)
                         return;
+                    // SYNC adopt (manager contract): the tee buffers already hold every byte from process start (the
+                    // onStdout/onStderr closures keep feeding them — no listener re-registration exists on an E2B
+                    // CommandHandle, which is exactly why the tee is created up-front). Terminal rides the shared waitP.
+                    // 🔴 builder contract (Fable-5 review #5): everything inside is NON-THROWING (.then/.catch on an
+                    // existing promise + object construction). adoptSync's catch does NOT undo side effects — future
+                    // logic that can throw must go before the first side effect.
                     const adopted = this.bgManager.adoptSync((ctx) => {
                         waitP
                             .then((r) => ctx.onTerminal(false, r.exitCode))
@@ -315,11 +495,13 @@ export class RemoteContainerExecutionEnv {
                         return { handle, stdout: tee.stdout, stderr: tee.stderr };
                     });
                     if (!adopted)
-                        return;
+                        return; // refused (limit) → the exec keeps running in the foreground
                     adoptedShellId = adopted.shellId;
-                    detached = true;
+                    detached = true; // stops caller-forwarding + disarms the fg liveness/wall kills
                     res("detached");
                 };
+                // core's ToolDetachHub is create-then-abort: a detach that landed BEFORE this exec started arrives as an
+                // ALREADY-aborted signal → adopt immediately (everything onDetach touches is initialized above).
                 if (detachSignal.aborted)
                     onDetach();
                 else
@@ -330,6 +512,7 @@ export class RemoteContainerExecutionEnv {
             const fg = this.waitWithLiveness(handle, () => lastProgress, {
                 waitP,
                 disarmed: () => detached,
+                // Foreground wall, control-plane enforced on the detach-capable path (provider timeout was lifted above).
                 ...(tee ? { wallMs: this.commandTimeoutMs(options?.timeout) } : {}),
             });
             const winner = await (detachedP ? Promise.race([fg, detachedP]) : fg);
@@ -343,6 +526,11 @@ export class RemoteContainerExecutionEnv {
                     detached: { shellId: adoptedShellId },
                 });
             }
+            // 夜测 N2(2026-07-09,MED):an aborted exec's Result shape was NON-DETERMINISTIC — the abort path only
+            // fires an async handle.kill(), after which wait() may settle as a plain result OR a CommandExitError
+            // (non-zero exit from the kill), both previously returned ok:true; only an rpc-layer failure surfaced
+            // "aborted". Normalize: an aborted, non-detached exec ALWAYS returns {ok:false, error:"aborted"} (the
+            // remote process IS terminated either way — this only stabilizes the caller's Result contract).
             if (options?.abortSignal?.aborted && !detached) {
                 return { ok: false, error: new ExecutionError("aborted", "exec aborted (remote process killed)") };
             }
@@ -350,8 +538,9 @@ export class RemoteContainerExecutionEnv {
         }
         catch (e) {
             if (options?.abortSignal?.aborted && !detached) {
-                return { ok: false, error: this.execError(e, options.abortSignal) };
+                return { ok: false, error: this.execError(e, options.abortSignal) }; // N2: classified "aborted" (see above)
             }
+            // E2B throws CommandExitError on non-zero exit, but ExecutionEnv treats exitCode as a normal value.
             if (e instanceof CommandExitError) {
                 return ok({ stdout: e.stdout, stderr: e.stderr, exitCode: e.exitCode });
             }
@@ -365,11 +554,13 @@ export class RemoteContainerExecutionEnv {
             options?.abortSignal?.removeEventListener("abort", onAbort);
         }
     }
+    // ─────────────────────────────── RemoteExecutionEnv: streaming exec ───────────────────────────────
     async *execStream(command, options) {
-        const conn = await this.ensureConnected();
+        const conn = await this.ensureConnected(); // lazy: first use provisions the VM
         if (!conn.ok)
             throw conn.error;
         const sbx = conn.value;
+        // Producer/consumer queue: E2B delivers output via onStdout/onStderr callbacks; we pull as an iterator.
         const queue = [];
         let finished = false;
         let failure;
@@ -384,11 +575,15 @@ export class RemoteContainerExecutionEnv {
         const cap = options?.maxOutputBytes;
         const push = (type, data) => {
             if (finished)
-                return;
+                return; // terminal-latch: once finished, drop any late E2B callback (never enqueue into a dead stream)
             bytes += Buffer.byteLength(data, "utf8");
             queue.push({ type, data });
             signalReady();
         };
+        // Increment BEFORE awaiting commands.run (mirrors exec): `commands.run` is a round-trip that may start the
+        // command on the VM before it resolves, so suspendVM must already see activeCommands > 0 to refuse — else a
+        // suspend racing the launch could snapshot a running command (council #4 invariant). Decrement on launch
+        // failure here; the normal path decrements in the outer finally.
         this.activeCommands++;
         let handle;
         try {
@@ -402,9 +597,14 @@ export class RemoteContainerExecutionEnv {
             }), options?.signal, this.cfg.livenessMs);
         }
         catch (e) {
+            // failed before any exit chunk → throw (streaming analogue of never-throw Result)
             this.activeCommands--;
             throw this.remoteError(e, "connect_failed");
         }
+        // Completion: E2B throws CommandExitError on non-zero exit — that is a NORMAL finish, not a stream failure.
+        // `finished` is a first-writer-wins latch: whichever of {wait-resolve, wait-reject, abort} fires first sets
+        // the terminal state; the rest no-op. Without it, an abort (or a late wait settlement) firing AFTER a clean
+        // completion — but before the consumer pulls the final chunk — would clobber a successful exit into a throw.
         handle
             .wait()
             .then((r) => {
@@ -440,13 +640,18 @@ export class RemoteContainerExecutionEnv {
             else
                 options.signal.addEventListener("abort", onAbort, { once: true });
         }
+        // Drain via a read-index, not Array.shift() — shift() is O(n) per call → O(n²) on large output (a
+        // `npm ci`/build streaming millions of lines). Compacts once fully caught up. Throws (after killing the
+        // command) on maxOutputBytes. Single helper so the main loop and the post-completion flush stay in lockstep.
         let head = 0;
         const drainQueued = function* () {
             while (head < queue.length) {
                 const chunk = queue[head++];
                 yield chunk;
+                // Soft cap: checked AFTER yield, so the chunk that crosses `cap` is still delivered (bounded by one
+                // E2B chunk). It's flood-protection (stop a `find /` drowning the control plane), not a byte-exact limit.
                 if (cap != null && bytes > cap) {
-                    finished = true;
+                    finished = true; // latch before kill (symmetry with onAbort): blocks late callbacks + the finally's re-kill
                     void handle.kill().catch(() => { });
                     throw new RemoteExecutionError("unknown", `execStream output exceeded maxOutputBytes=${cap}`);
                 }
@@ -459,9 +664,15 @@ export class RemoteContainerExecutionEnv {
                 yield* drainQueued();
                 if (finished)
                     break;
+                // Idle read-timeout (design/48 §5, E2B #1128): a streaming call has no read timeout, so an
+                // unreachable sandbox would hang forever. Bound the wait for the NEXT chunk and kill on expiry.
                 const next = new Promise((resolve) => {
                     wake = resolve;
                 });
+                // 🔴 Liveness is DEFAULT-ON: a missing readTimeoutMs MUST NOT mean "wait forever / until the env
+                // dies" — fall back to cfg.livenessMs. (The command-CREATION RPC is bounded separately by rpc() above, so
+                // the two together cover both phases of a provider hang.) Only kills a ZERO-PROGRESS command — a slow but
+                // streaming `npm ci` keeps resetting the timer via push()→signalReady().
                 const idleMs = options?.readTimeoutMs ?? this.cfg.livenessMs;
                 let timer;
                 const idle = new Promise((_, reject) => {
@@ -471,7 +682,7 @@ export class RemoteContainerExecutionEnv {
                     await Promise.race([next, idle]);
                 }
                 catch (e) {
-                    finished = true;
+                    finished = true; // latch before kill (symmetry with onAbort): blocks late callbacks + the finally's re-kill
                     void handle.kill().catch(() => { });
                     this.cfg.metrics?.inc("remote_env_exec_stream_read_timeout_total", { provider: PROVIDER });
                     throw e instanceof RemoteExecutionError ? e : this.remoteError(e);
@@ -481,12 +692,16 @@ export class RemoteContainerExecutionEnv {
                         clearTimeout(timer);
                 }
             }
-            yield* drainQueued();
+            yield* drainQueued(); // flush any chunks delivered alongside completion (same cap/kill semantics)
             if (failure)
                 throw failure;
             yield { type: "exit", exitCode };
         }
         finally {
+            // If the consumer abandons the iterator early (`break`/upstream cancel without an abort signal), the
+            // generator runs only this finally — the remote command would otherwise keep running (and billing) for
+            // its whole timeout, AND activeCommands would drop to 0 with a live command, letting suspendVM snapshot a
+            // running command. Kill on any non-finished exit so the council #4 invariant holds on every path.
             if (!finished) {
                 finished = true;
                 void handle.kill().catch(() => { });
@@ -495,11 +710,34 @@ export class RemoteContainerExecutionEnv {
             options?.signal?.removeEventListener("abort", onAbort);
         }
     }
+    // ─────────────────────────── design/103 background shell (TOB, path ②) ───────────────────────────
+    //
+    // E2B takes path ② (design/103 §5.2): a resident control-plane reader. `commands.run({background:true})` returns
+    // a `CommandHandle` immediately whose `onStdout`/`onStderr` callbacks keep firing as output arrives; we tee them
+    // into a per-shell rolling-tail buffer and serve `pollBackground` from that buffer's cursor. Consequence (design
+    // §5.2): the buffer is REPLICA-AFFINE — it lives in this env instance's heap and does NOT survive a reconnect to
+    // another replica. That is fine: background shells never cross a durable suspend (the Runner disposes them before
+    // `suspendVM`, design/103 §3.7), and a reconnected replica's empty registry yields `not_found` (VM destroy reaps
+    // the orphaned in-sandbox job). Background jobs deliberately do NOT touch `activeCommands` — they are long-lived
+    // and would otherwise wedge `suspendVM` forever; the dispose-before-suspend ordering (core saga) is what keeps a
+    // running background job from being snapshotted.
+    //
+    // 🔴 KILL SCOPE (honest, live-verified limitation): `handle.kill()` reliably SIGKILLs the MAIN process the model
+    // started — which is the model's KillShell intent (the dev server stops, its port frees). It does NOT group-kill
+    // the subtree, and E2B offers no SAFE way to: the per-command process group is SHARED with envd (killing it kills
+    // the sandbox), a ppid tree-walk doesn't reach E2B's reparented/disowned descendants, and `/proc/<pid>/environ`
+    // is ptrace-hardened (an env-marker scan reads nothing). All probed live. So detached grandchildren are reaped by
+    // the sandbox VM teardown (`destroy()`/`sbx.kill()`), which ALWAYS runs at task end — the reliable reaper (mirrors
+    // TOC's crash-honesty: we don't fake a group-kill the provider can't safely do). Practical impact is bounded:
+    // KillShell stops the server; on dispose-before-suspend the main processes die and any survivor is frozen (paused
+    // VM = no CPU) then reaped at the eventual destroy. Relayed to core for the design ledger.
     backgroundCapabilities = {
         supported: true,
         maxConcurrent: E2B_BG_MAX_CONCURRENT,
         defaultBgTimeoutSec: E2B_BG_DEFAULT_TIMEOUT_SEC,
         maxBgTimeoutSec: E2B_BG_MAX_TIMEOUT_SEC,
+        // core 1.207 design/116 detach (1.82): a running foreground exec can be ADOPTED as a background shell
+        // (mid-flight ctrl+b) — the exec's CommandHandle + tee buffers hand over into the launch-shaped state.
         supportsDetach: true,
     };
     _bgManager;
@@ -510,16 +748,21 @@ export class RemoteContainerExecutionEnv {
         const self = this;
         return {
             async launch(command, options, ctx) {
-                const conn = await self.ensureConnected();
+                const conn = await self.ensureConnected(); // lazy: first use provisions the VM
                 if (!conn.ok)
-                    throw new Error(`remote connect failed: ${conn.error.message}`);
+                    throw new Error(`remote connect failed: ${conn.error.message}`); // → manager wraps as spawn_failed
                 const sbx = conn.value;
                 const stdout = { tail: new RollingTailBuffer(), total: 0, cursor: 0 };
                 const stderr = { tail: new RollingTailBuffer(), total: 0, cursor: 0 };
+                // 🔴 secret-scrub red line (design/103 §3.1): env is passed EXACTLY as `exec`/`execStream` do
+                // (`{ envs: options.env }`) — the host process.env is never inherited; the sandbox base env is the
+                // operator-trusted `sandboxEnv` set at create. A background child therefore sees the SAME scrubbed env.
                 const handle = await self.rpc("commands.run.bg", () => sbx.commands.run(command, {
                     background: true,
                     cwd: self.resolve(options?.cwd ?? self.cwd),
                     ...(options?.env ? { envs: options.env } : {}),
+                    // Provider-level backstop ONLY: padded past the control-plane hard wall so the manager's timer flips
+                    // status to `killed` first; this reaps the in-sandbox job if the control plane dies (design/103 §3.6).
                     timeoutMs: (ctx.bgTimeoutSec + E2B_BG_PROVIDER_BACKSTOP_PAD_SEC) * 1000,
                     onStdout: (d) => {
                         const b = Buffer.from(d, "utf8");
@@ -532,6 +775,8 @@ export class RemoteContainerExecutionEnv {
                         stderr.total += b.length;
                     },
                 }), undefined, self.cfg.livenessMs);
+                // Push-model terminal (design/103): wait() resolves on clean exit, rejects with CommandExitError on non-zero
+                // (a NORMAL finish → exited), or any other error → failed. `.catch` is mandatory (no unhandled rejection).
                 handle
                     .wait()
                     .then((r) => ctx.onTerminal(false, r.exitCode))
@@ -545,10 +790,18 @@ export class RemoteContainerExecutionEnv {
             },
             async read(state) {
                 const slice = (s) => {
+                    // Cursor over ABSOLUTE byte offsets; the tail retains [droppedBytes, total). Return [cursor, total).
                     const { text, droppedBytes } = s.tail.result();
                     const droppedBeforeCursor = Math.max(0, droppedBytes - s.cursor);
                     const startByte = Math.max(s.cursor, droppedBytes);
                     const startInTail = startByte - droppedBytes;
+                    // 🔴 re-encode delta (Fable-5 review #2): `startInTail` is an ORIGINAL-byte offset, but `text` is a
+                    // decode→re-encode round trip. The tail's content is always valid UTF-8 (fed from SDK strings) EXCEPT
+                    // its very head when an evict partially cut a multibyte codepoint — each stranded byte decodes to one
+                    // U+FFFD (3 bytes re-encoded), so the re-encoded buffer is `delta` bytes longer than the original tail
+                    // and the difference sits entirely BEFORE any valid cursor position (the cursor always lands on an SDK
+                    // string boundary, past the stranded head). Shift the slice start by delta; without it the increment
+                    // re-served up to 2 already-returned bytes per stranded byte (byte-drifted output).
                     const reencoded = Buffer.from(text, "utf8");
                     const delta = reencoded.length - (s.total - droppedBytes);
                     const inc = startInTail <= 0 ? text : reencoded.subarray(startInTail + delta).toString("utf8");
@@ -565,10 +818,10 @@ export class RemoteContainerExecutionEnv {
                 };
             },
             async kill(state) {
-                await state.handle.kill().catch(() => { });
+                await state.handle.kill().catch(() => { }); // idempotent: no-op if already settled
             },
             async disposeOne(state) {
-                await state.handle.kill().catch(() => { });
+                await state.handle.kill().catch(() => { }); // best-effort; the VM destroy reaps anything that survives
             },
         };
     }
@@ -582,8 +835,11 @@ export class RemoteContainerExecutionEnv {
         return this.bgManager.kill(shellId);
     }
     disposeBackgroundShells(opts) {
+        // 签名统一带 opts(core 尾调 {except: keepAlive})。隔离 env 的留活是名义的——沙箱拆机进程必然随之
+        // 消亡(destroy 整体带走),core 的 envDying settle 会先给准确 killed 回执;透传保证签名不静默丢参。
         return this._bgManager ? this._bgManager.dispose(opts) : Promise.resolve();
     }
+    // ─────────────────────────────── FileSystem ───────────────────────────────
     async absolutePath(p) {
         return ok(this.resolve(p));
     }
@@ -608,7 +864,7 @@ export class RemoteContainerExecutionEnv {
             return r;
         let lines = r.value.split(/\r?\n/);
         if (lines.length > 0 && lines[lines.length - 1] === "")
-            lines.pop();
+            lines.pop(); // drop trailing newline's empty tail
         if (options?.maxLines != null)
             lines = lines.slice(0, options.maxLines);
         return ok(lines);
@@ -630,6 +886,7 @@ export class RemoteContainerExecutionEnv {
         if (!sbx.ok)
             return sbx;
         try {
+            // E2B write creates parent directories automatically. Uint8Array → its backing ArrayBuffer slice.
             const data = typeof content === "string" ? content : toArrayBuffer(content);
             await this.rpc("files.write", (signal) => sbx.value.files.write(this.resolve(p), data, { signal }), abortSignal, this.cfg.dataTimeoutMs);
             return ok(undefined);
@@ -639,6 +896,7 @@ export class RemoteContainerExecutionEnv {
         }
     }
     async appendFile(p, content, abortSignal) {
+        // E2B has no native append; read-modify-write (v1 single-worker → no concurrent-append race).
         const abs = this.resolve(p);
         const existing = await this.readBinaryFile(abs, abortSignal);
         let base;
@@ -681,6 +939,9 @@ export class RemoteContainerExecutionEnv {
             return { ok: false, error: this.fileError(e, this.resolve(p), abortSignal) };
         }
     }
+    /** 见其余 shell 腿上同名方法的旁注(2026-07-25 六腿补齐):core 的敏感路径门在 `canonicalPath` 失败时退到它;
+     *  缺它 ⇒ 合法的悬空链接让整个工具调用失败。必须返回**原始链接目标**(`readlink` 不带 `-f`)。
+     *  本腿的文件面也走 `exec`(与 canonicalPath 同通道),所以实现方式与 shell 腿一致。 */
     async readLink(p, abortSignal) {
         const abs = this.resolve(p);
         const r = await this.exec(`readlink -- ${shellQuote(abs)}`, { abortSignal });
@@ -696,6 +957,7 @@ export class RemoteContainerExecutionEnv {
         if (!r.ok)
             return { ok: false, error: fileErrorFromExec(r.error, abs) };
         if (r.value.exitCode !== 0) {
+            // realpath can fail for more than missing paths — classify like fileError() instead of collapsing to not_found.
             const msg = r.value.stderr.trim();
             if (/permission denied|access denied/i.test(msg))
                 return { ok: false, error: new FileError("permission_denied", msg, abs) };
@@ -716,7 +978,7 @@ export class RemoteContainerExecutionEnv {
         catch (e) {
             const fe = this.fileError(e, this.resolve(p), abortSignal);
             if (fe.code === "not_found")
-                return ok(false);
+                return ok(false); // missing path is `false`, not an error (contract)
             return { ok: false, error: fe };
         }
     }
@@ -725,6 +987,7 @@ export class RemoteContainerExecutionEnv {
         if (!sbx.ok)
             return sbx;
         try {
+            // E2B makeDir creates necessary parent directories; returns false if it already exists (treated as ok).
             await this.rpc("files.makeDir", (signal) => sbx.value.files.makeDir(this.resolve(p), { signal }), options?.abortSignal);
             return ok(undefined);
         }
@@ -738,6 +1001,7 @@ export class RemoteContainerExecutionEnv {
             return sbx;
         const abs = this.resolve(p);
         if (options?.recursive) {
+            // E2B files.remove does not guarantee recursive directory removal → shell rm -rf.
             const flags = options.force ? "-rf" : "-r";
             const r = await this.exec(`rm ${flags} -- ${shellQuote(abs)}`, { abortSignal: options.abortSignal });
             if (!r.ok)
@@ -768,9 +1032,17 @@ export class RemoteContainerExecutionEnv {
         const r = await this.exec(`mktemp ${suffixArg} ${shellQuote(`${prefix}XXXXXX`)}`, { abortSignal: options?.abortSignal });
         return this.tempResult(r, "mktemp");
     }
+    // ─────────────────────────────── internals ───────────────────────────────
     resolve(p) {
         return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
     }
+    /**
+     * 🔴 (hang class-fix) Bound a CONTROL-PLANE provider RPC (create/resume/pause/kill/isRunning/files.*) with a
+     * client-side wall-clock deadline + the caller's AbortSignal. Without this, an E2B RPC that hangs (the original
+     * bug: ESTABLISHED socket, no response) pins the worker for the whole sandbox lifetime. On deadline we abort the
+     * op and throw a typed, retryable {@link RemoteExecutionError} code `"timeout"` (caller retries per idempotency —
+     * the adapter NEVER blind-retries). A caller AbortSignal still aborts independently (op surfaces it / "aborted").
+     */
     async rpc(label, op, userSignal, timeoutMs = this.cfg.rpcTimeoutMs) {
         const deadline = new AbortController();
         const timer = setTimeout(() => deadline.abort(), timeoutMs);
@@ -781,24 +1053,55 @@ export class RemoteContainerExecutionEnv {
             reject(new RemoteExecutionError("timeout", `remote ${label} exceeded ${timeoutMs}ms (provider RPC hang)`));
         }, { once: true }));
         try {
+            // RACE the op against the deadline: even if the provider SDK ignores `signal` (e.g. create/isRunning/kill),
+            // the worker is freed on timeout (the op may leak in the background until the SDK's own timeout — but it no
+            // longer PINS us for the sandbox lifetime, the original hang bug). Passing `signal` lets SDK methods that DO
+            // honor it (files.*, pause, connect) actually cancel the request. A caller `userSignal` abort propagates via
+            // `signal` → the op rejects with its own abort error (NOT surfaced as "timeout"; deadline never fired).
             return await Promise.race([op(signal), onDeadline]);
         }
         finally {
             clearTimeout(timer);
-            combined?.dispose();
+            combined?.dispose(); // council BUG-2: release the fallback anySignal listeners (no-op for AbortSignal.any)
         }
     }
+    /**
+     * Per-command wall-clock for the E2B SDK (seconds→ms). 🔴 This is a PHYSICAL CAP, NOT the hang
+     * detector. The old code returned `this.cfg.timeoutMs` (the sandbox lifetime) when no `timeout` was given AND
+     * had no liveness check → a hung command waited the WHOLE lifetime (~30 min, the original hang bug). The fix is
+     * NOT to shorten this cap (that would spuriously kill a long-but-progressing `npm ci`) — it's to add a LIVENESS
+     * bound ({@link cfg.livenessMs}) in exec/execStream that catches a *zero-progress* command in ~livenessMs,
+     * independent of this cap. So: explicit caller `timeout` wins; else the lifetime is the cap (a command can't
+     * outlive its VM) but hang detection no longer depends on it.
+     */
     commandTimeoutMs(timeoutSec) {
         return timeoutSec != null ? timeoutSec * 1000 : this.cfg.timeoutMs;
     }
-    async waitWithLiveness(handle, lastProgress, opts) {
+    /**
+     * 🔴 Liveness for the buffered exec WAIT phase. `handle.wait()` is a long-poll with no read timeout —
+     * a command that hangs DURING execution (not creation) would otherwise wait the E2B command timeout (= the
+     * lifetime when none is set, the original hang bug). Races wait() against an idle check: if no stdout/stderr for
+     * `livenessMs`, the command is hung → kill + typed retryable "timeout". `lastProgress()` is bumped by the
+     * stdout/stderr callbacks, so a slow-but-PROGRESSING command (long `npm ci`) is never killed. (execStream has
+     * its own chunk-driven idle timer; this is the buffered-exec analogue.)
+     */
+    async waitWithLiveness(handle, lastProgress, 
+    // design/116 detach: `waitP` shares the ONE `handle.wait()` consumption with exec's adoption path; `disarmed`
+    // (⇒ the command was adopted as a background shell) makes the liveness/wall timers dead switches — the fg leg
+    // must NEVER kill a process the bgManager now owns; `wallMs` is the control-plane foreground wall for the
+    // detach-capable path (whose provider timeout was lifted to the BG ceiling).
+    opts) {
         let timer;
         let wallTimer;
+        // council DESIGN-1: a fixed 5s polling setInterval can fire AT the deadline and kill a command that just
+        // finished (race vs handle.wait settling, discarding its exitCode). Instead arm a setTimeout for EXACTLY the
+        // remaining idle window; when it fires, re-check lastProgress() — if output advanced it, re-arm for the new
+        // remainder (so a slow-but-progressing command is never killed), else it is genuinely idle → kill + timeout.
         const idle = new Promise((_, reject) => {
             const arm = () => {
                 timer = setTimeout(() => {
                     if (opts?.disarmed?.())
-                        return;
+                        return; // adopted: the BG wall owns the process now — never kill from the fg leg
                     const idleFor = Date.now() - lastProgress();
                     if (idleFor >= this.cfg.livenessMs) {
                         void handle.kill().catch(() => { });
@@ -806,7 +1109,7 @@ export class RemoteContainerExecutionEnv {
                         reject(new RemoteExecutionError("timeout", `exec idle > ${this.cfg.livenessMs}ms (provider hang / unreachable sandbox)`));
                     }
                     else {
-                        arm();
+                        arm(); // progress advanced lastProgress since arming → re-arm for the now-remaining window
                     }
                 }, Math.max(this.cfg.livenessMs - (Date.now() - lastProgress()), 0));
             };
@@ -821,6 +1124,8 @@ export class RemoteContainerExecutionEnv {
             }
         });
         try {
+            // handle.wait() settling (resolve OR CommandExitError reject) wins the race over a still-pending timer, so a
+            // command that completes is never killed; finally clears the timer on every exit path.
             return await Promise.race([opts?.waitP ?? handle.wait(), idle]);
         }
         finally {
@@ -830,7 +1135,10 @@ export class RemoteContainerExecutionEnv {
                 clearTimeout(wallTimer);
         }
     }
+    /** Lazily provision the VM on first use: a task that never touches the hand pays zero cost.
+     *  Concurrent first-calls share one provision via the memoized {@link connect}. */
     async ensureConnected() {
+        // A paused (suspended) env's this.sbx is a dead handle — fail clearly rather than running fs/exec against it.
         if (this.paused)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env is suspended (paused) — resume before fs/exec") };
         if (this.sbx)
@@ -872,10 +1180,16 @@ export class RemoteContainerExecutionEnv {
         const name = e?.name;
         if (abortSignal?.aborted || name === "AbortError")
             return new FileError("aborted", msg, p);
+        // A remote-fs RPC liveness timeout arrives as RemoteExecutionError("timeout"); surface it on the FileSystem
+        // seam as the symmetric FileError("timeout") (core 1.77.0 added "timeout" to FileErrorCode too — [R71]) so the
+        // retryable-hang signal travels as a typed code, not just a message. + a metric so a file-RPC hang stays
+        // observable. Minor: file RPCs rarely hang and only past dataTimeoutMs (5m).
         if (e instanceof RemoteExecutionError && e.code === "timeout") {
             this.cfg.metrics?.inc("remote_env_file_timeout_total", { provider: PROVIDER });
             return new FileError("timeout", msg, p, e);
         }
+        // The sandbox itself vanishing (reaped/timed-out) is an INFRASTRUCTURE failure, not a confirmed-absent
+        // file — never collapse it to not_found, or exists()/stat() would report a dead VM as "file is absent".
         if (name === "SandboxNotFoundError" || /sandbox .*not found|sandbox .*not running|sandbox was not found/i.test(msg)) {
             return new FileError("unknown", msg, p);
         }
@@ -909,15 +1223,30 @@ export class RemoteContainerExecutionEnv {
         return new RemoteExecutionError(code, errMsg(e), e instanceof Error ? e : undefined);
     }
 }
+/**
+ * Build the deployment-level `RunnerDeps.executionEnvFactory` (design/48 v1b). Wiring this onto a
+ * deployment makes it a "code-agent worker": every task's hand runs in a per-task E2B VM. Deployments that do
+ * NOT set this (e.g. OA / review) keep the in-process stub env — routing is **deployment-level** (the factory
+ * ctx carries only sessionId/taskId, never a service scenario; that stays out of the generic core seam).
+ *
+ * The factory returns the env **unconnected** (lazy): the VM is provisioned on first FS/Shell/execStream use,
+ * so a task that never touches the hand (e.g. a leader that only plans) pays zero VM cost. The Runner owns the
+ * lifetime and calls `destroy()` on task end (via `hasDestroy`); a never-used env's destroy is a no-op.
+ */
 export function e2bExecutionEnvFactory(config, deps) {
     return (ctx) => new RemoteContainerExecutionEnv({
         ...config,
         metadata: { ...config.metadata, sessionId: ctx.sessionId, ...(ctx.taskId ? { taskId: ctx.taskId } : {}) },
     }, deps);
 }
+// ─────────────────────────────── module helpers ───────────────────────────────
 function errMsg(e) {
     return e instanceof Error ? e.message : String(e);
 }
+/** E2B FilesystemRequestOpts `{ signal }` spread helper (omit the key entirely when no signal). */
+/** Combine signals into one that aborts when ANY input does (used by {@link RemoteContainerExecutionEnv.rpc} to
+ *  race the caller's abort with the client-side deadline). Uses the platform `AbortSignal.any` when present
+ *  (Node ≥20 / Bun), else a small fallback. */
 function anySignal(signals) {
     const ctor = AbortSignal;
     if (typeof ctor.any === "function")
@@ -931,13 +1260,15 @@ function anySignal(signals) {
             break;
         }
         s.addEventListener("abort", onAbort, { once: true });
-        cleanups.push(() => s.removeEventListener("abort", onAbort));
+        cleanups.push(() => s.removeEventListener("abort", onAbort)); // council BUG-2: dispose() removes these on long-lived signals
     }
     return { signal: ctrl.signal, dispose: () => cleanups.forEach((c) => c()) };
 }
+/** POSIX single-quote a string for safe shell interpolation. */
 function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
+/** Copy a Uint8Array's exact bytes into a standalone ArrayBuffer (E2B write accepts ArrayBuffer). */
 function toArrayBuffer(u) {
     return u.buffer.slice(u.byteOffset, u.byteOffset + u.byteLength);
 }