@sema-agent/server 1.323.0 → 2.0.0

package/dist/plugins/remote-env-local-docker.d.ts

@@ -1,36 +1,76 @@
 import { spawn } from "node:child_process";
 import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
+/** Options accepted by `ExecutionEnv.exec` (core does not re-export the type; derive it from the seam). */
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
+/** Construction config for {@link RemoteLocalDockerExecutionEnv}. */
 export interface LocalDockerEnvConfig {
+    /**
+     * Base container image to run the task in. **REQUIRED — no default** (domestic-images iron rule: the registry
+     * is the operator's choice, never a hardcoded `docker.io` origin). e.g. the docker.io/claybobby pool or an
+     * in-network `node:20` mirror (SWR deprecated).
+     */
     image: string;
+    /** Workspace root INSIDE the container; relative paths resolve against it. Default {@link DEFAULT_MOUNT_PATH}. */
     mountPath?: string;
+    /** Path to the docker binary (or a docker-compatible CLI). Default "docker" (must be on PATH in the worker). */
     dockerPath?: string;
+    /**
+     * DOCKER_HOST override for the docker CLI (e.g. a non-default socket). Passed as `-H <value>` on EVERY docker
+     * invocation (not the process env) so it can't leak / drift. Absent = the daemon DOCKER_HOST points at.
+     */
     dockerHost?: string;
+    /** Container memory limit (docker `--memory`, e.g. "2g"). Absent = no limit. */
     memory?: string;
+    /** Container CPU limit (docker `--cpus`, e.g. 1.5). Absent = no limit. */
     cpus?: number;
+    /** Max processes in the container (docker `--pids-limit`) — a fork-bomb backstop on the shared host kernel.
+     *  Default 512 (generous for builds; raise for heavy parallelism). Set 0/negative to disable (not advised). */
     pidsLimit?: number;
+    /** Drop ALL Linux capabilities (docker `--cap-drop ALL`) — hardens this code sandbox, but BREAKS workloads
+     *  that need caps (some installs/builds). Default OFF (the container boundary + no-new-privileges + pids-limit
+     *  are always on). Turn ON for a genuinely-untrusted lane; operators re-add caps as needed. */
     dropAllCaps?: boolean;
+    /** Container network mode (docker `--network`). Absent = docker default (bridge, isolated net-ns). 🔴 `"host"`
+     *  SHARES the host network namespace — it removes the net-ns isolation dimension and exposes host-local
+     *  services (DBs/admin ports/metadata) to agent-run code. It is NOT a true isolation boundary; use only when
+     *  the lane is operator-trusted and needs host networking. */
     network?: "none" | "bridge" | "host";
+    /**
+     * Out-of-band env injected into EVERY command via `docker exec -e` (secrets etc.). The control plane resolves
+     * secret env-NAMEs from the worker's own `process.env` and passes resolved values here — they never enter the
+     * model prompt or the tool command string. Merged UNDER per-command `options.env` (per-call wins).
+     */
     env?: Record<string, string>;
+    /** Per-command wall-clock bound (ms) when the caller gives none. Default {@link DEFAULT_COMMAND_TIMEOUT_MS}. */
     commandTimeoutMs?: number;
+    /** Wall-clock bound (ms) for a docker control op (run/rm/inspect/cp). Default {@link DEFAULT_CONTROL_TIMEOUT_MS}. */
     controlTimeoutMs?: number;
+    /** Stable id mixed into the container NAME (e.g. the sessionId). A random suffix is always appended so two
+     *  envs sharing an id never collide. Default = a random id. */
     id?: string;
 }
+/** Inject `spawn` for tests (a fake docker CLI). Defaults to node's child_process spawn. */
 export interface LocalDockerEnvDeps {
     spawn?: typeof spawn;
 }
 export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv {
+    /** DUAL-MODE-DESIGN §5: a container is a real isolation boundary; v1 has no managed memory snapshot. */
     readonly capabilities: {
         isolation: boolean;
         suspendable: boolean;
     };
+    /** Working directory inside the container; relative paths resolve against it (ExecutionEnv contract). */
     cwd: string;
     private readonly cfg;
     private readonly spawnFn;
+    /** Stable container NAME (also our handle id). Created on connect; targeted by every docker exec/cp/rm. */
     private readonly containerName;
+    /** Set once the container is up + the workspace dir created. */
     private containerId?;
     private handle?;
+    /** Terminal once {@link destroy} ran — guards exec/fs from running against a removed container. */
     private destroyed;
+    /** In-flight connect, memoized so concurrent lazy first-use starts exactly one container (no double-run). */
     private connecting?;
     constructor(config: LocalDockerEnvConfig, deps?: LocalDockerEnvDeps);
     private resolve;
@@ -64,6 +104,11 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /**
+     * Liveness re-check (NOT a snapshot resume): if the container is still running → idempotent success; if it's
+     * gone (crashed / externally removed) → `connect_failed` (no managed snapshot to re-attach to). `sessionToken`
+     * is the container name (== our handle id); a mismatch with this env's container fails closed.
+     */
     reconnect(sessionToken: SessionToken): Promise<{
         ok: true;
         value: WorkspaceHandle;
@@ -71,6 +116,7 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /** `docker rm -f` the container (full teardown). Idempotent, best-effort, never throws (cleanup contract). */
     destroy(): Promise<void>;
     cleanup(): Promise<void>;
     private forceRemove;
@@ -112,17 +158,36 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
         suffix?: string;
         abortSignal?: AbortSignal;
     }): Promise<Result<string, FileError>>;
+    /** Prepend `-H <dockerHost>` to a docker argv when configured (per-invocation, not the process env). */
     private withHostFlag;
+    /** Build the `docker exec` argv for a command, applying cwd (`-w`) and per-command env (`-e K=V`).
+     *  argv elements are SEPARATE (no host-side shell join) — the command runs in the CONTAINER's `/bin/sh -c`. */
     private execArgv;
+    /** Like {@link execArgv} but for an internal FileSystem helper command (uses the workspace cwd + adapter env). */
     private execRaw;
+    /** Spawn the docker binary with argv; collect stdout/stderr (+ raw bytes when binary), bound by timeout/abort. */
     private docker;
+    /** Lazy connect for an exec path → ExecutionError on failure (fail closed, never throws). */
+    /** S1([1870]):容器内**用户命令**的 shell。缺省 /bin/sh;首次连接后探测一次 `command -v bash`,
+     *  有则切 bash(TB 实测 dash 三病:$'\t' 静默错字节/[[ ]] 127/进程替换)。镜像无 bash(alpine 裸底)
+     *  ⇒ 保 sh(修前字节形,诚实降级);探测自身失败同。容器**创建**引导命令(mkdir && tail)不走
+     *  本 shell——无 bash 语法且探测尚不可能。 */
     private containerShell;
     private containerShellProbed;
     private probeContainerShell;
     private ensureConnectedExec;
+    /** Lazy connect for a FileSystem path → FileError on failure (fail closed, never throws). */
     private fsReady;
+    /** Map an ExecutionError from a docker CONTROL op (run/inspect) onto a RemoteExecutionError code. */
     private dockerToRemoteError;
 }
+/**
+ * `ExecutionEnvFactory` for the TOC `local-docker` backend (DUAL-MODE-DESIGN §5). Wiring this onto a deployment
+ * makes its agent run each task in a per-task container on the worker's OWN docker daemon (isolation:true,
+ * suspendable:false). Returns the env UNCONNECTED (lazy — the container starts on first fs/exec use); the Runner
+ * owns the lifetime and calls `destroy()` (= `docker rm -f`) on task end. Folds the per-task `ctx.taskId`/
+ * `ctx.sessionId` into the container name so two concurrent tasks never share a container.
+ */
 export declare function localDockerExecutionEnvFactory(config: LocalDockerEnvConfig, deps?: LocalDockerEnvDeps): ExecutionEnvFactory;
 export {};
 //# sourceMappingURL=remote-env-local-docker.d.ts.map

package/dist/plugins/remote-env-local-docker.js

@@ -1,3 +1,41 @@
+/**
+ * `RemoteLocalDockerExecutionEnv` — the TOC **local-docker** exec adapter (DUAL-MODE-DESIGN §5, the
+ * fast-follow promoted from the host file's typed stub). Runs the agent's bash/file tools inside a long-lived
+ * container ON THIS MACHINE's docker daemon, so a single-machine ("take-over-this-computer") deployment gets a
+ * REAL OS-level isolation boundary — the in-between lane between the un-isolated `host` adapter (no container)
+ * and the fleet `e2b`/`k8s` sandboxes (remote microVMs/pods).
+ *
+ * It is a PEER adapter to host / e2b / k8s / ssh / adb (NOT chained): all implement the SAME core seam
+ * `RemoteExecutionEnv` (core src/core/remote-env.ts, design/48 §5), selected by `remoteExec.provider` —
+ * this one is `provider:"local-docker"`.
+ *
+ * 🔴 **Isolation, NOT a snapshot sandbox** (DUAL-MODE-DESIGN §5 / design/61 §9):
+ *  - `capabilities = { isolation: true, suspendable: false }`. The container is a true isolation boundary
+ *    (separate filesystem/PID/mount namespaces), so the agent's writes/exec are confined to it and parallel
+ *    fan-out tasks don't collide. But v1 is **NOT suspendable** — `suspendVM`/`resumeVM`/`postResumeInit`
+ *    return typed `"unsupported"`. (`docker pause`/`docker commit` could give a coarse suspend later; we do
+ *    NOT fake it here — durable suspend is honestly N/A until that lands.)
+ *  - `destroy()` / `cleanup()` **`docker rm -f` the container** — a full teardown (the container IS the
+ *    per-task sandbox, unlike host which only `rm -rf`s a dir). Idempotent, best-effort, never throws.
+ *  - `reconnect()` is supported as a liveness re-check: if the container is still running it is an idempotent
+ *    success; if it's gone (crashed / externally `rm`'d) it FAILS (`connect_failed`) — there is no managed
+ *    snapshot to resume from, so a dead container cannot be re-attached.
+ *
+ * 🔴 **Domestic-images iron rule (clay):** the base `image` comes ENTIRELY from config (no hardcoded
+ * `docker.io/...` default). A deployment points it at the sandbox-image-pool (docker.io/claybobby public pool;
+ * CN fallback = in-network Gitea registry — SWR deprecated 2026-07-13). This adapter never invents a registry.
+ *
+ * 🔴 **argv anti-injection (council, host/ssh §4):** every `docker` invocation is a `spawn(binary, argv[])`
+ * with NO host-side shell (`shell:false` default) — the container id, image, paths, and env values are
+ * SEPARATE argv elements, never string-concatenated into a `sh -c` on the host. The agent's COMMAND itself is
+ * still a shell command (it runs the container's `/bin/sh -c <command>`, exactly like the host/ssh adapters
+ * run the operator's command in a shell) — that is the agent's intended surface, bounded by the container.
+ *
+ * **never-throw invariant:** every base `ExecutionEnv` FileSystem/Shell method encodes failure in its returned
+ * `Result` (never throws) — docker missing from PATH, a command timeout, a container that won't start, all
+ * become `Result.error`. `execStream`'s iterator MAY throw `RemoteExecutionError` mid-stream before an `exit`
+ * chunk (the seam contract). A non-zero command exit is a NORMAL value (`{ ok:true, exitCode }`), never an error.
+ */
 import path from "node:path";
 import os from "node:os";
 import fs from "node:fs/promises";
@@ -8,8 +46,11 @@ import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, mar
 import { fileErrorFromExec, classifyFsStderr } from "./remote-env-file-error.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
 const PROVIDER = "local-docker";
+/** Default workspace root INSIDE the container (the agent's tools resolve relative paths against it). */
 const DEFAULT_MOUNT_PATH = "/workspace";
+/** Per-command wall-clock when the caller passes none (a single exec bound, NOT the container lifetime). */
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
+/** Wall-clock for a control-plane docker op (run/rm/inspect/cp) — should be fast; a hang surfaces typed. */
 const DEFAULT_CONTROL_TIMEOUT_MS = 60_000;
 const ok = (value) => ({ ok: true, value });
 const unsupported = (op) => ({
@@ -17,17 +58,25 @@ const unsupported = (op) => ({
     error: new RemoteExecutionError("unsupported", `${op} is not supported on a local-docker target (v1: a container is an isolation boundary but not a managed memory snapshot; capabilities.suspendable=false)`),
 });
 export class RemoteLocalDockerExecutionEnv {
+    /** DUAL-MODE-DESIGN §5: a container is a real isolation boundary; v1 has no managed memory snapshot. */
     capabilities = { isolation: true, suspendable: false };
+    /** Working directory inside the container; relative paths resolve against it (ExecutionEnv contract). */
     cwd;
     cfg;
     spawnFn;
+    /** Stable container NAME (also our handle id). Created on connect; targeted by every docker exec/cp/rm. */
     containerName;
+    /** Set once the container is up + the workspace dir created. */
     containerId;
     handle;
+    /** Terminal once {@link destroy} ran — guards exec/fs from running against a removed container. */
     destroyed = false;
+    /** In-flight connect, memoized so concurrent lazy first-use starts exactly one container (no double-run). */
     connecting;
     constructor(config, deps = {}) {
         if (!config.image || !config.image.trim()) {
+            // image is required (no docker.io default) — but the constructor must not throw (never-throw posture):
+            // record the empty image and let connect() fail closed with a typed error.
             config = { ...config, image: config.image ?? "" };
         }
         this.cfg = {
@@ -41,7 +90,7 @@ export class RemoteLocalDockerExecutionEnv {
         this.cwd = this.cfg.mountPath;
         this.spawnFn = deps.spawn ?? spawn;
         const id = config.id ?? randomBytes(6).toString("hex");
-        const suffix = randomBytes(4).toString("hex");
+        const suffix = randomBytes(4).toString("hex"); // always-unique tail so a reused id never collides
         this.containerName = `sema-docker-${sanitizeId(id)}-${suffix}`;
     }
     resolve(p) {
@@ -52,27 +101,31 @@ export class RemoteLocalDockerExecutionEnv {
             throw new RemoteExecutionError("connect_failed", "workspaceHandle() called before connect()");
         return this.handle;
     }
+    // ─────────────────────────────── lifecycle ───────────────────────────────
     async connect(config) {
         if (config?.snapshotId)
-            return unsupported("connect(snapshotId)");
+            return unsupported("connect(snapshotId)"); // no managed snapshots
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
         if (config?.abortSignal?.aborted)
             return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted") };
         if (this.containerId)
-            return ok(this.workspaceHandle());
+            return ok(this.workspaceHandle()); // idempotent: already running
         if (this.connecting)
-            return this.connecting;
+            return this.connecting; // concurrent first-use shares one container start
         this.connecting = this.doConnect(config);
         const r = await this.connecting;
         if (!r.ok)
-            this.connecting = undefined;
+            this.connecting = undefined; // failed start → allow a later retry
         return r;
     }
     async doConnect(config) {
         if (!this.cfg.image.trim()) {
             return { ok: false, error: new RemoteExecutionError("connect_failed", "local-docker: no base image configured (the image is required — no docker.io default)") };
         }
+        // Start a long-lived detached container that idles forever (the agent's commands are `docker exec`'d into
+        // it). `tail -f /dev/null` is the most portable idle keep-alive (no `sleep infinity` dependency on some
+        // busybox/alpine images). --init reaps zombie exec children. The workspace dir is created via the same run.
         const pidsLimit = this.cfg.pidsLimit ?? 512;
         const runArgs = [
             "run",
@@ -82,6 +135,8 @@ export class RemoteLocalDockerExecutionEnv {
             this.containerName,
             "-w",
             this.cfg.mountPath,
+            // Always-safe sandbox hardening (no build breakage): block setuid privilege escalation + cap the process
+            // count so generated code can't fork-bomb the shared host kernel. cap-drop is opt-in (it DOES break some builds).
             "--security-opt",
             "no-new-privileges",
             ...(pidsLimit > 0 ? ["--pids-limit", String(pidsLimit)] : []),
@@ -92,17 +147,19 @@ export class RemoteLocalDockerExecutionEnv {
             this.cfg.image,
             "/bin/sh",
             "-c",
+            // Create the workspace then idle. mkdir -p is harmless if the image already has it.
             `mkdir -p ${shellQuote(this.cfg.mountPath)} && exec tail -f /dev/null`,
         ];
         const run = await this.docker(runArgs, { signal: config?.abortSignal, timeoutMs: this.cfg.controlTimeoutMs });
         if (!run.ok) {
-            await this.forceRemove().catch(() => { });
+            await this.forceRemove().catch(() => { }); // a half-created container must not leak on a failed start
             return { ok: false, error: this.dockerToRemoteError(run.error, "connect_failed") };
         }
         if (run.value.exitCode !== 0) {
             await this.forceRemove().catch(() => { });
             return { ok: false, error: new RemoteExecutionError("connect_failed", `docker run failed: ${run.value.stderr.trim() || `exit ${run.value.exitCode}`}`) };
         }
+        // Race with destroy() (the awaits above yield): a destroy that landed must win — remove + bail (no orphan).
         if (this.destroyed) {
             await this.forceRemove().catch(() => { });
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
@@ -110,6 +167,7 @@ export class RemoteLocalDockerExecutionEnv {
         this.containerId = run.value.stdout.trim() || this.containerName;
         this.handle = { sandboxId: this.containerName, provider: PROVIDER, mountPath: this.cfg.mountPath, sessionToken: this.containerName };
         if (config?.secrets?.length) {
+            // Secrets are injected per-command via cfg.env (resolved by the control plane), not at connect — record only.
         }
         return ok(this.handle);
     }
@@ -122,6 +180,11 @@ export class RemoteLocalDockerExecutionEnv {
     async postResumeInit() {
         return unsupported("postResumeInit");
     }
+    /**
+     * Liveness re-check (NOT a snapshot resume): if the container is still running → idempotent success; if it's
+     * gone (crashed / externally removed) → `connect_failed` (no managed snapshot to re-attach to). `sessionToken`
+     * is the container name (== our handle id); a mismatch with this env's container fails closed.
+     */
     async reconnect(sessionToken) {
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
@@ -130,28 +193,39 @@ export class RemoteLocalDockerExecutionEnv {
         }
         const insp = await this.docker(["inspect", "-f", "{{.State.Running}}", this.containerName], { timeoutMs: this.cfg.controlTimeoutMs });
         if (insp.ok && insp.value.exitCode === 0 && insp.value.stdout.trim() === "true") {
+            // 🔴 mark CONNECTED to the live container: else ensureConnectedExec/fsReady (gate on containerId) would
+            // re-run `docker run --name <same>` → name conflict → the failure path rm -f's the very container we just
+            // re-attached to (destroying the running workspace). The name IS our exec/handle target.
             this.containerId = this.containerName;
             this.handle ??= { sandboxId: this.containerName, provider: PROVIDER, mountPath: this.cfg.mountPath, sessionToken: this.containerName };
             return ok(this.handle);
         }
         return { ok: false, error: new RemoteExecutionError("connect_failed", `container '${this.containerName}' is not running (gone or stopped) — no managed snapshot to resume`) };
     }
+    /** `docker rm -f` the container (full teardown). Idempotent, best-effort, never throws (cleanup contract). */
     async destroy() {
         if (this.destroyed)
-            return;
+            return; // idempotent — safe double-call (Runner end + reaper)
         this.destroyed = true;
+        // 🔴 AWAIT any racing `docker run` before reaping: a destroy that lands mid-connect must not resolve before
+        // the container exists, else forceRemove (by name) no-ops now and the just-created container LEAKS forever
+        // (docker has no self-timeout). Mirrors the host adapter's await-prepare-then-rm.
         const inflight = this.connecting;
         this.connecting = undefined;
         this.containerId = undefined;
         await inflight?.catch(() => { });
+        // Remove by NAME (covers a container that started but whose id we never recorded) — `rm -f` no-ops a
+        // never-created name; best-effort, never throws.
         await this.forceRemove().catch(() => { });
     }
     async cleanup() {
         return this.destroy();
     }
     async forceRemove() {
+        // best-effort, short bound; swallow everything (teardown must never throw).
         await this.docker(["rm", "-f", this.containerName], { timeoutMs: this.cfg.controlTimeoutMs }).catch(() => { });
     }
+    // ─────────────────────────────── Shell: buffered exec ───────────────────────────────
     async exec(command, options) {
         if (options?.abortSignal?.aborted)
             return { ok: false, error: new ExecutionError("aborted", "exec aborted before start") };
@@ -167,8 +241,10 @@ export class RemoteLocalDockerExecutionEnv {
         });
         if (!r.ok)
             return { ok: false, error: r.error };
+        // A non-zero exit is a NORMAL value (ExecutionEnv contract) — `docker exec` propagates the inner exit code.
         return ok({ stdout: r.value.stdout, stderr: r.value.stderr, exitCode: r.value.exitCode });
     }
+    // ─────────────────────────────── streaming exec ───────────────────────────────
     async *execStream(command, options) {
         const ready = await this.ensureConnectedExec();
         if (!ready.ok)
@@ -196,7 +272,7 @@ export class RemoteLocalDockerExecutionEnv {
             if (queue.length >= 512 && !paused) {
                 paused = true;
                 child.stdout?.pause();
-            }
+            } // backpressure
             signalReady();
         };
         child.stdout?.on("data", (d) => enqueue("stdout", d.toString()));
@@ -224,7 +300,7 @@ export class RemoteLocalDockerExecutionEnv {
                 try {
                     child.kill("SIGKILL");
                 }
-                catch { }
+                catch { /* noop */ }
             }
         };
         if (options?.signal) {
@@ -236,7 +312,7 @@ export class RemoteLocalDockerExecutionEnv {
                 try {
                     child.kill("SIGKILL");
                 }
-                catch { }
+                catch { /* noop */ }
                 signalReady();
             };
             if (options.signal.aborted)
@@ -254,7 +330,7 @@ export class RemoteLocalDockerExecutionEnv {
                         try {
                             child.kill("SIGKILL");
                         }
-                        catch { }
+                        catch { /* noop */ }
                         throw new RemoteExecutionError("unknown", `execStream output exceeded maxOutputBytes=${cap}`);
                     }
                 }
@@ -273,7 +349,7 @@ export class RemoteLocalDockerExecutionEnv {
                     try {
                         child.kill("SIGKILL");
                     }
-                    catch { }
+                    catch { /* noop */ }
                     throw new RemoteExecutionError("timeout", `execStream idle > ${idleMs}ms (command hang)`);
                 }
             }
@@ -287,6 +363,7 @@ export class RemoteLocalDockerExecutionEnv {
             teardown();
         }
     }
+    // ─────────────────────────────── FileSystem ───────────────────────────────
     async absolutePath(p) {
         return ok(this.resolve(p));
     }
@@ -298,12 +375,13 @@ export class RemoteLocalDockerExecutionEnv {
         if (!ready.ok)
             return ready;
         const abs = this.resolve(p);
+        // `docker exec ... cat <file>` streams raw bytes on stdout (binary-safe); stderr carries cat's error.
         const r = await this.docker(this.execRaw(`cat ${shellQuote(abs)}`), { signal: abortSignal, timeoutMs: this.cfg.commandTimeoutMs, binary: true });
         if (!r.ok)
             return { ok: false, error: fileErrorFromExec(r.error, abs) };
         if (r.value.exitCode !== 0)
             return { ok: false, error: classifyFsStderr(r.value.stderr, abs) };
-        return ok(r.value.stdoutBytes ?? new Uint8Array());
+        return ok(r.value.stdoutBytes ?? new Uint8Array()); // binary:true always sets stdoutBytes (empty file → empty); ?? satisfies the now-optional type
     }
     async readTextFile(p, abortSignal) {
         const r = await this.readBinaryFile(p, abortSignal);
@@ -325,6 +403,7 @@ export class RemoteLocalDockerExecutionEnv {
         if (!ready.ok)
             return ready;
         const abs = this.resolve(p);
+        // Create parent dirs inside the container (parity with the host/e2b adapters' auto-create).
         const dir = path.posix.dirname(abs);
         if (dir && dir !== "." && dir !== "/") {
             const mk = await this.docker(this.execRaw(`mkdir -p ${shellQuote(dir)}`), { signal: abortSignal, timeoutMs: this.cfg.commandTimeoutMs });
@@ -333,6 +412,8 @@ export class RemoteLocalDockerExecutionEnv {
             if (mk.value.exitCode !== 0)
                 return { ok: false, error: classifyFsStderr(mk.value.stderr, dir) };
         }
+        // Stage to a host temp file then `docker cp` (binary-safe; avoids shell-escaping the payload — same
+        // discipline as the ADB adapter's `adb push`). `docker cp <src> <name>:<abs>` writes into the container.
         let local;
         try {
             local = path.join(os.tmpdir(), `docker-cp-${Date.now()}-${randomBytes(6).toString("hex")}`);
@@ -368,9 +449,14 @@ export class RemoteLocalDockerExecutionEnv {
         merged.set(add, base.length);
         return this.writeFile(abs, merged, abortSignal);
     }
+    // ── design/158 B6:POSIX shell-out 文件面全部委托共享基座(posix-shell-fs.ts)─────────────────────
+    // 六裁决与 readLink・lstat 契约见基座头注。本腿此前的 fsErrorFromStderr 无 not_found 缺省(缺文件报
+    // unknown),且 `|not found` 宽包含会把「命令缺失」误判成「文件不存在」—— 两处都被基座正形纠正。
     posixFsInst;
     get posixFs() {
         return (this.posixFsInst ??= createPosixShellFs({
+            // 承 fsReady 契约(其余三腿走公有 exec、守卫天然在;本腿直用私有 docker,必须自带):
+            // destroyed 守卫 + 懒连接,fail closed 不抛 —— 消息保留 "destroyed" 字样(测试钉的就是它)。
             run: async (cmd, abortSignal) => {
                 if (this.destroyed)
                     return { ok: false, error: new ExecutionError("shell_unavailable", "execution env already destroyed") };
@@ -412,43 +498,63 @@ export class RemoteLocalDockerExecutionEnv {
     async createTempFile(options) {
         return this.posixFs.createTempFile(options);
     }
+    // ─────────────────────────────── internals ───────────────────────────────
+    /** Prepend `-H <dockerHost>` to a docker argv when configured (per-invocation, not the process env). */
     withHostFlag(args) {
         return this.cfg.dockerHost ? ["-H", this.cfg.dockerHost, ...args] : args;
     }
+    /** Build the `docker exec` argv for a command, applying cwd (`-w`) and per-command env (`-e K=V`).
+     *  argv elements are SEPARATE (no host-side shell join) — the command runs in the CONTAINER's `/bin/sh -c`. */
     execArgv(command, cwd, env) {
         const args = ["exec"];
         const dir = cwd != null ? this.resolve(cwd) : this.cwd;
         args.push("-w", dir);
-        const mergedEnv = { ...(this.cfg.env ?? {}), ...(env ?? {}) };
+        const mergedEnv = { ...(this.cfg.env ?? {}), ...(env ?? {}) }; // adapter secrets base; per-command wins
         for (const [k, v] of Object.entries(mergedEnv))
-            args.push("-e", `${k}=${v}`);
-        args.push(this.containerName, this.containerShell, "-c", command);
+            args.push("-e", `${k}=${v}`); // separate argv → no injection
+        args.push(this.containerName, this.containerShell, "-c", command); // S1:探测后 bash 优先,无则 sh
         return args;
     }
+    /** Like {@link execArgv} but for an internal FileSystem helper command (uses the workspace cwd + adapter env). */
     execRaw(command) {
         return this.execArgv(command);
     }
+    /** Spawn the docker binary with argv; collect stdout/stderr (+ raw bytes when binary), bound by timeout/abort. */
     docker(args, opts) {
         return new Promise((resolve) => {
             let settled = false;
+            // D5 pipe-destroy grace: armed by killGrace() on abort/timeout; destroys stdout/stderr pipes if `close`
+            // never fires (a re-parented grandchild holding the FD). Cleared in finish() — the real `close` routes
+            // through finish() — so the timer never leaks. Does NOT change the synchronous settle below.
             let forceSettleTimer;
             const child = this.spawnFn(this.cfg.dockerPath, this.withHostFlag(args), { stdio: ["ignore", "pipe", "pipe"] });
+            // SIGKILL the child then arm the D5 pipe-destroy grace (only on the abort/timeout paths — a normal `close`
+            // never calls this). Idempotent: only one timer is ever armed.
             const killGrace = () => {
                 try {
                     child.kill("SIGKILL");
                 }
-                catch { }
+                catch { /* noop */ }
                 forceSettleTimer ??= armPipeDestroyGrace(child);
             };
+            // 🔴 binary caveat (D2): this helper is SHARED by the model-facing TEXT exec (must be bounded — a
+            // `yes`/`cat big` could OOM the durable worker) and by readBinaryFile (`docker exec ... cat`, opts.binary=true,
+            // which reads stdoutBytes and MUST keep EVERY byte or binary/large reads silently corrupt). So we branch:
+            //  - binary=true  → full Buffer[] + concat (byte-exact stdoutBytes; readBinaryFile path).
+            //  - binary=false → bounded rolling-TAIL for stdout (keep last 8MB + dropped-byte marker, O(maxBytes));
+            //    no text caller reads stdoutBytes, so it is derived from the bounded text (DockerRun.stdoutBytes is non-optional).
+            // stderr is ALWAYS bounded — it never carries the binary payload (just cat's error text).
             const binary = !!opts?.binary;
-            const outBufs = [];
-            const outTail = binary ? undefined : new RollingTailBuffer();
+            const outBufs = []; // binary path only: full bytes for stdoutBytes
+            const outTail = binary ? undefined : new RollingTailBuffer(); // text path only: bounded stdout
             const errBuf = new RollingTailBuffer();
             const finish = (r) => {
                 if (settled)
                     return;
                 settled = true;
                 clearTimeout(timer);
+                // D5 grace cleared in the `close` handler (pipes closed naturally), NOT here — abort/timeout reaches
+                // finish() BEFORE `close`, so clearing here would cancel the grace before it can free a leaked FD.
                 opts?.signal?.removeEventListener("abort", onAbort);
                 resolve(r);
             };
@@ -469,26 +575,33 @@ export class RemoteLocalDockerExecutionEnv {
             child.stdout?.on("data", (d) => { if (binary)
                 outBufs.push(d);
             else
-                outTail.push(d); opts?.onStdout?.(d.toString()); });
+                outTail.push(d); opts?.onStdout?.(d.toString()); }); // streaming callback gets the full chunk; only the buffered return is bounded
             child.stderr?.on("data", (d) => { errBuf.push(d); opts?.onStderr?.(d.toString()); });
             child.on("error", (e) => finish({ ok: false, error: new ExecutionError("spawn_error", `docker spawn failed (is '${this.cfg.dockerPath}' installed?): ${e.message}`, e) }));
             child.on("close", (code, signal) => {
                 if (forceSettleTimer)
-                    clearTimeout(forceSettleTimer);
+                    clearTimeout(forceSettleTimer); // `close` fired → pipes closed naturally; clear D5 grace
+                // A signal-killed process (external SIGKILL/OOM) has code===null → derive the conventional 128+signo
+                // (parity with execStream + the host adapter); NEVER report a killed command as a success exitCode 0.
                 const exitCode = code ?? (signal ? 128 + (signalNumber(signal) ?? 0) : 1);
                 const err = errBuf.result();
                 const stderr = markTruncated(err.text, err.droppedBytes);
                 if (binary) {
-                    const outBytes = Buffer.concat(outBufs);
+                    const outBytes = Buffer.concat(outBufs); // byte-exact: readBinaryFile decodes stdoutBytes; never truncate.
                     finish(ok({ stdout: outBytes.toString("utf8"), stderr, exitCode, stdoutBytes: new Uint8Array(outBytes) }));
                 }
                 else {
-                    const out = outTail.result();
+                    const out = outTail.result(); // text path: no stdoutBytes (readBinaryFile is the only reader, and it uses binary:true)
                     finish(ok({ stdout: markTruncated(out.text, out.droppedBytes), stderr, exitCode }));
                 }
             });
         });
     }
+    /** Lazy connect for an exec path → ExecutionError on failure (fail closed, never throws). */
+    /** S1([1870]):容器内**用户命令**的 shell。缺省 /bin/sh;首次连接后探测一次 `command -v bash`,
+     *  有则切 bash(TB 实测 dash 三病:$'\t' 静默错字节/[[ ]] 127/进程替换)。镜像无 bash(alpine 裸底)
+     *  ⇒ 保 sh(修前字节形,诚实降级);探测自身失败同。容器**创建**引导命令(mkdir && tail)不走
+     *  本 shell——无 bash 语法且探测尚不可能。 */
     containerShell = "/bin/sh";
     containerShellProbed = false;
     async probeContainerShell() {
@@ -501,13 +614,14 @@ export class RemoteLocalDockerExecutionEnv {
                 this.containerShell = "bash";
         }
         catch {
+            /* 保 sh —— 探测绝不 fault 连接路径 */
         }
     }
     async ensureConnectedExec() {
         if (this.destroyed)
             return { ok: false, error: new ExecutionError("shell_unavailable", "execution env already destroyed") };
         if (this.containerId) {
-            await this.probeContainerShell();
+            await this.probeContainerShell(); // S1:已连的腿也补探测(幂等一次)
             return ok(undefined);
         }
         const c = await this.connect();
@@ -516,6 +630,7 @@ export class RemoteLocalDockerExecutionEnv {
         await this.probeContainerShell();
         return ok(undefined);
     }
+    /** Lazy connect for a FileSystem path → FileError on failure (fail closed, never throws). */
     async fsReady(p) {
         if (this.destroyed)
             return { ok: false, error: new FileError("unknown", "execution env already destroyed", this.resolve(p)) };
@@ -526,6 +641,7 @@ export class RemoteLocalDockerExecutionEnv {
             return { ok: false, error: new FileError("unknown", `local-docker connect failed: ${c.error.message}`, this.resolve(p), c.error) };
         return ok(undefined);
     }
+    /** Map an ExecutionError from a docker CONTROL op (run/inspect) onto a RemoteExecutionError code. */
     dockerToRemoteError(e, fallback) {
         if (e.code === "timeout")
             return new RemoteExecutionError("timeout", e.message, e);
@@ -534,16 +650,25 @@ export class RemoteLocalDockerExecutionEnv {
         return new RemoteExecutionError(fallback, e.message, e);
     }
 }
+/** Strip anything but [A-Za-z0-9._-] from an id so it is safe in a docker container name. */
 function sanitizeId(id) {
     return id.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 48) || "task";
 }
 function errMsg(e) {
     return e instanceof Error ? e.message : String(e);
 }
+/** Conventional exit code for a process killed by a signal (128 + signal number); falls back to undefined. */
 function signalNumber(signal) {
     const table = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15, SIGSEGV: 11 };
     return table[signal];
 }
+/**
+ * `ExecutionEnvFactory` for the TOC `local-docker` backend (DUAL-MODE-DESIGN §5). Wiring this onto a deployment
+ * makes its agent run each task in a per-task container on the worker's OWN docker daemon (isolation:true,
+ * suspendable:false). Returns the env UNCONNECTED (lazy — the container starts on first fs/exec use); the Runner
+ * owns the lifetime and calls `destroy()` (= `docker rm -f`) on task end. Folds the per-task `ctx.taskId`/
+ * `ctx.sessionId` into the container name so two concurrent tasks never share a container.
+ */
 export function localDockerExecutionEnvFactory(config, deps = {}) {
     return (ctx) => new RemoteLocalDockerExecutionEnv({ ...config, id: config.id ?? ctx.taskId ?? ctx.sessionId }, deps);
 }