@sema-agent/server 7.43.0 → 7.44.0

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

@@ -1,42 +1,3 @@
-/**
- * `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)
- * or its own private registry — SWR was deprecated 2026-07-13 and the in-network Gitea registry container was
- * retired 2026-08 (no CN fallback is baked in). 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";
@@ -48,13 +9,8 @@ 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).
- *  ⚠️ 同判据三腿之一(另两条:`remote-env-host.ts` 同值 30min、`remote-env-ssh.ts` **5min**)——分歧成文
- *  与候裁说明写在 ssh 那处的 `commandTimeoutMs` 顶注(#176 二轮扫描 finding)。 */
 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) => ({
@@ -62,27 +18,18 @@ 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;
-    /** Provider name put on the WorkspaceHandle ("local-docker" | "remote-docker"). Observability only. */
     providerName;
-    /** 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 = {
@@ -96,7 +43,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"); // always-unique tail so a reused id never collides
+        const suffix = randomBytes(4).toString("hex");
         this.containerName = `sema-docker-${sanitizeId(id)}-${suffix}`;
         this.providerName = config.providerLabel?.trim() || PROVIDER;
     }
@@ -108,31 +55,27 @@ 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)"); // no managed snapshots
+            return unsupported("connect(snapshotId)");
         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()); // idempotent: already running
+            return ok(this.workspaceHandle());
         if (this.connecting)
-            return this.connecting; // concurrent first-use shares one container start
+            return this.connecting;
         this.connecting = this.doConnect(config);
         const r = await this.connecting;
         if (!r.ok)
-            this.connecting = undefined; // failed start → allow a later retry
+            this.connecting = undefined;
         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",
@@ -142,8 +85,6 @@ 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)] : []),
@@ -154,19 +95,17 @@ 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(() => { }); // a half-created container must not leak on a failed start
+            await this.forceRemove().catch(() => { });
             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") };
@@ -174,7 +113,6 @@ export class RemoteLocalDockerExecutionEnv {
         this.containerId = run.value.stdout.trim() || this.containerName;
         this.handle = { sandboxId: this.containerName, provider: this.providerName, 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);
     }
@@ -187,11 +125,6 @@ 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") };
@@ -200,39 +133,28 @@ 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: this.providerName, 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; // idempotent — safe double-call (Runner end + reaper)
+            return;
         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") };
@@ -248,10 +170,8 @@ 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)
@@ -279,7 +199,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()));
@@ -307,7 +227,7 @@ export class RemoteLocalDockerExecutionEnv {
                 try {
                     child.kill("SIGKILL");
                 }
-                catch { /* noop */ }
+                catch { }
             }
         };
         if (options?.signal) {
@@ -319,7 +239,7 @@ export class RemoteLocalDockerExecutionEnv {
                 try {
                     child.kill("SIGKILL");
                 }
-                catch { /* noop */ }
+                catch { }
                 signalReady();
             };
             if (options.signal.aborted)
@@ -337,7 +257,7 @@ export class RemoteLocalDockerExecutionEnv {
                         try {
                             child.kill("SIGKILL");
                         }
-                        catch { /* noop */ }
+                        catch { }
                         throw new RemoteExecutionError("unknown", `execStream output exceeded maxOutputBytes=${cap}`);
                     }
                 }
@@ -350,7 +270,6 @@ export class RemoteLocalDockerExecutionEnv {
                 if (finished)
                     break;
                 const waitMs = idleMs != null ? Math.max(1, idleMs - (Date.now() - lastChunk)) : 30_000;
-                // [4947] A-002.11 sibling: clear the losing timer — wake() firing first used to leave it armed.
                 let waitTimer;
                 try {
                     await new Promise((r) => { wake = r; waitTimer = setTimeout(r, waitMs); });
@@ -364,7 +283,7 @@ export class RemoteLocalDockerExecutionEnv {
                     try {
                         child.kill("SIGKILL");
                     }
-                    catch { /* noop */ }
+                    catch { }
                     throw new RemoteExecutionError("timeout", `execStream idle > ${idleMs}ms (command hang)`);
                 }
             }
@@ -378,7 +297,6 @@ export class RemoteLocalDockerExecutionEnv {
             teardown();
         }
     }
-    // ─────────────────────────────── FileSystem ───────────────────────────────
     async absolutePath(p) {
         return ok(this.resolve(p));
     }
@@ -390,13 +308,12 @@ 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()); // binary:true always sets stdoutBytes (empty file → empty); ?? satisfies the now-optional type
+        return ok(r.value.stdoutBytes ?? new Uint8Array());
     }
     async readTextFile(p, abortSignal) {
         const r = await this.readBinaryFile(p, abortSignal);
@@ -418,7 +335,6 @@ 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 });
@@ -427,8 +343,6 @@ 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")}`);
@@ -464,14 +378,9 @@ 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") };
@@ -513,63 +422,43 @@ 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 ?? {}) }; // adapter secrets base; per-command wins
+        const mergedEnv = { ...(this.cfg.env ?? {}), ...(env ?? {}) };
         for (const [k, v] of Object.entries(mergedEnv))
-            args.push("-e", `${k}=${v}`); // separate argv → no injection
-        args.push(this.containerName, this.containerShell, "-c", command); // S1:探测后 bash 优先,无则 sh
+            args.push("-e", `${k}=${v}`);
+        args.push(this.containerName, this.containerShell, "-c", command);
         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 { /* noop */ }
+                catch { }
                 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 = []; // binary path only: full bytes for stdoutBytes
-            const outTail = binary ? undefined : new RollingTailBuffer(); // text path only: bounded stdout
+            const outBufs = [];
+            const outTail = binary ? undefined : new RollingTailBuffer();
             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);
             };
@@ -590,33 +479,26 @@ export class RemoteLocalDockerExecutionEnv {
             child.stdout?.on("data", (d) => { if (binary)
                 outBufs.push(d);
             else
-                outTail.push(d); opts?.onStdout?.(d.toString()); }); // streaming callback gets the full chunk; only the buffered return is bounded
+                outTail.push(d); opts?.onStdout?.(d.toString()); });
             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); // `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.
+                    clearTimeout(forceSettleTimer);
                 const exitCode = code ?? (signal ? 128 + (signalNumber(signal) ?? 9) : 1);
                 const err = errBuf.result();
                 const stderr = markTruncated(err.text, err.droppedBytes);
                 if (binary) {
-                    const outBytes = Buffer.concat(outBufs); // byte-exact: readBinaryFile decodes stdoutBytes; never truncate.
+                    const outBytes = Buffer.concat(outBufs);
                     finish(ok({ stdout: outBytes.toString("utf8"), stderr, exitCode, stdoutBytes: new Uint8Array(outBytes) }));
                 }
                 else {
-                    const out = outTail.result(); // text path: no stdoutBytes (readBinaryFile is the only reader, and it uses binary:true)
+                    const out = outTail.result();
                     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() {
@@ -624,23 +506,18 @@ export class RemoteLocalDockerExecutionEnv {
             return;
         this.containerShellProbed = true;
         try {
-            // 🔴 NO withHostFlag here — `docker()` already prepends it. A second `-H` is not a harmless repeat: the
-            // docker CLI rejects the whole command (`invalid argument … specify only one -H`), so on every
-            // REMOTE-daemon container (`dockerHost` set — always, on the `remote-docker` arm) the probe used to fail
-            // and silently degrade the user shell to /bin/sh for a reason unrelated to the image.
             const r = await this.docker(["exec", this.containerName, "/bin/sh", "-c", "command -v bash"], { timeoutMs: this.cfg.controlTimeoutMs });
             if (r.ok && r.value.exitCode === 0 && r.value.stdout.trim().length > 0)
                 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(); // S1:已连的腿也补探测(幂等一次)
+            await this.probeContainerShell();
             return ok(undefined);
         }
         const c = await this.connect();
@@ -649,7 +526,6 @@ 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)) };
@@ -660,7 +536,6 @@ 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);
@@ -669,20 +544,12 @@ 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);
 }
-/**
- * `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);
 }