@sema-agent/server 1.323.0 → 2.0.0

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

@@ -1,3 +1,36 @@
+/**
+ * `RemoteHostExecutionEnv` — the **TOC `host` exec adapter** (DUAL-MODE-DESIGN §5). Runs
+ * commands DIRECTLY on THIS machine, in NO container — the TOC ("take-over-this-computer") default, exactly
+ * like a local coding agent operating on the user's own box. **Isolation = none.**
+ *
+ * It is a PEER adapter to the E2B / SSH / k8s ones (not chained): all four implement the SAME core seam
+ * `RemoteExecutionEnv` (core src/core/remote-env.ts, design/48 §5) so the agent's "hand" plugs into any of
+ * them via the deployment-level `ExecutionEnvFactory`. The discriminator that selects between them is the
+ * `remoteExec.provider` superset — this adapter is `provider:"host"` (DUAL-MODE-DESIGN §5).
+ *
+ * 🔴 **`host` targets the operator's OWN machine, not a disposable sandbox** (DUAL-MODE-DESIGN §5):
+ *  - `capabilities = { isolation: false, suspendable: false }` — there is NO container boundary and NO
+ *    snapshot. Side effects are PERMANENT and visible to the whole machine. The orchestrator/leader MUST
+ *    tighten autonomy + the design/37 policy gate + HITL on a non-isolated env (design/53 zero-trust) —
+ *    identical posture to the SSH adapter, which also runs on a real (un-isolated) system.
+ *  - **NO network restriction** — this is the user's own machine; the agent has the same network the user
+ *    does (that is the whole point of the TOC mode).
+ *  - `suspendVM`/`resumeVM`/`postResumeInit` → typed `"unsupported"` (a live host process tree isn't
+ *    snapshotable — durable suspend N/A). `reconnect` is a no-op success (the "connection" is the local
+ *    process; nothing to re-establish).
+ *  - `destroy()` / `cleanup()` **`rm -rf` the per-task working directory** (the workspace this adapter
+ *    created), NOT the machine. Anything the agent created OUTSIDE the workspace persists (that is the
+ *    operator's/gate's concern — there is no isolation to undo).
+ *
+ * **never-throw invariant:** every base `ExecutionEnv` FileSystem/Shell method encodes failure in its
+ * returned `Result` (never throws). `execStream`'s iterator MAY throw `RemoteExecutionError` mid-stream
+ * before an `exit` chunk (the seam contract, OutputChunk). A non-zero command exit is a NORMAL value
+ * (`{ ok:true, exitCode }`), never an error.
+ *
+ * Platforms: macOS + Linux (POSIX shell). Forward-compatible with the `remoteExec` superset: this file also
+ * scaffolds the `local-docker` / `remote-docker` providers' factory entry points (typed stubs that throw a
+ * clear "not yet implemented" — explicit fast-follow per DUAL-MODE-DESIGN §5; NOT faked green).
+ */
 import { spawn } from "node:child_process";
 import os from "node:os";
 import path from "node:path";
@@ -6,24 +39,37 @@ import { randomBytes } from "node:crypto";
 import { openSync, closeSync, readSync, statSync, truncateSync, unlinkSync, mkdirSync, rmdirSync, mkdtempSync, existsSync, realpathSync } from "node:fs";
 import { StringDecoder } from "node:string_decoder";
 import { armPipeDestroyGrace, numEnvOr } from "./remote-shell.js";
+// design/158 B4 (lens4 N8): the two host-lane kill switches were the negative names `HOST_BG_DISABLED` /
+// `HOST_EXEC_SPOOL_DISABLED`, parsed inline. Their canonical names are now positive (`HOST_BG_ENABLED` /
+// `HOST_EXEC_SPOOL_ENABLED`, default ON) and resolved by the shared config helpers, which keep the retired
+// names working for one deprecation window and register both in the boot polarity table.
 import { hostBackgroundShellEnabled, hostExecSpoolEnabled } from "../config.js";
 import { resolveHostShell, hostShell, spawnGroupOptions, killTreeHard, killTreeSoft, collapseWin32EnvKeys } from "./host-platform.js";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
 import { FileError, ExecutionError, RemoteExecutionError, scrubSecretEnv, RollingTailBuffer, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
 const PROVIDER = "host";
+/** Default per-command wall-clock when the caller passes none (NOT a hang detector — host commands rarely hang). */
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
+// ─── design/103 host-lane background shell: TOC's run_in_background / BashOutput / KillShell ───
+// host driver = design/103 §5.2 path ①: a `detached` child (its OWN process group via `detached:true` → pgid ===
+// child.pid) writes stdout/stderr DIRECTLY to two local files; poll re-reads each by byte cursor; kill/dispose reap
+// the whole group with `process.kill(-pid)`. The BackgroundShellManager owns every red-line (opaque id / owned-id
+// isolation / maxConcurrent / timeout hard wall / dispose); this driver only writes the 4 transport primitives.
 const HOST_BG_MAX_CONCURRENT = numEnvOr("HOST_BG_MAX_CONCURRENT", 8, 1);
 const HOST_BG_DEFAULT_TIMEOUT_SEC = numEnvOr("HOST_BG_DEFAULT_TIMEOUT_SEC", 300, 1);
 const HOST_BG_MAX_TIMEOUT_SEC = numEnvOr("HOST_BG_MAX_TIMEOUT_SEC", 1800, HOST_BG_DEFAULT_TIMEOUT_SEC);
-const HOST_BG_READ_CAP = numEnvOr("HOST_BG_READ_CAP", 1024 * 1024, 64 * 1024);
-const HOST_BG_FILE_CAP = numEnvOr("HOST_BG_FILE_CAP", 64 * 1024 * 1024, HOST_BG_READ_CAP);
-const HOST_BG_KILL_GRACE_MS = numEnvOr("HOST_BG_KILL_GRACE_MS", 1000, 0);
+const HOST_BG_READ_CAP = numEnvOr("HOST_BG_READ_CAP", 1024 * 1024, 64 * 1024); // per-poll incremental read ceiling
+const HOST_BG_FILE_CAP = numEnvOr("HOST_BG_FILE_CAP", 64 * 1024 * 1024, HOST_BG_READ_CAP); // disk guard: reap a runaway
+const HOST_BG_KILL_GRACE_MS = numEnvOr("HOST_BG_KILL_GRACE_MS", 1000, 0); // SIGTERM → grace → SIGKILL (no host isolation)
+/** Per-stream memory-mode drain cap: an un-polled adopted child cannot grow the worker heap without bound (the
+ *  host lane has no VM to contain it). Drop-oldest beyond this, counting dropped bytes → surfaced as `truncated`. */
 const HOST_BG_MEM_CAP = numEnvOr("HOST_BG_MEM_CAP", 8 * 1024 * 1024, 64 * 1024);
 const ok = (value) => ({ ok: true, value });
 const unsupported = (op) => ({
     ok: false,
     error: new RemoteExecutionError("unsupported", `${op} is not supported on a host target (the operator's own machine — no container boundary, not snapshotable; capabilities.suspendable=false)`),
 });
+// The cap shape an env without a backend advertises — `supported:false` makes `hasScheduler` false (INERT, no tools).
 const UNSUPPORTED_SCHEDULER_CAPS = {
     supported: false,
     maxScheduledPerScope: 0,
@@ -32,7 +78,11 @@ const UNSUPPORTED_SCHEDULER_CAPS = {
     maxScheduledHorizonSec: 0,
 };
 export class RemoteHostExecutionEnv {
+    /** design/61 §9 / DUAL-MODE-DESIGN §5: a `host` env is the operator's real machine — no isolation, no snapshot. */
     capabilities = { isolation: false, suspendable: false };
+    /** R7 自唤醒: structural delegation to the injected scheduler backend. `hasScheduler(env)` checks BOTH the method
+     *  presence (always, since we implement the interface) AND `schedulerCapabilities.supported===true` — which is only
+     *  true when a backend was injected, so a host env without one stays INERT (the four scheduler tools don't mount). */
     get schedulerCapabilities() {
         return this.cfg.scheduler?.schedulerCapabilities ?? UNSUPPORTED_SCHEDULER_CAPS;
     }
@@ -51,30 +101,45 @@ export class RemoteHostExecutionEnv {
             ? this.cfg.scheduler.list(ctx)
             : Promise.resolve({ ok: false, error: new SchedulerError("unsupported", "scheduler not enabled on this worker") });
     }
+    /** Working directory; relative paths resolve against it (ExecutionEnv contract). Starts at the workspace root. */
     cwd;
     workspaceDir;
     cfg;
+    /** Workspace created on disk (lazily, on first use). */
     prepared = false;
+    /** Terminal once {@link destroy} ran — guards fs/exec from running against a removed workspace. */
     destroyed = false;
+    /** [1116] 五轮复审:fg/bg spool 根=tmpdir 私有目录(core bgSpoolDir 同形)。workspace 是命令可写区,
+     *  `git clean -fdx` 类清理会 unlink 活跃 spool(子进程经继承 fd 对 unlinked inode 继续写,而父进程
+     *  按路径 statSync/read 静默断=输出丢失+轮转帽失效);顺带不再弄脏 user-owned workspace(TOC/CC
+     *  persistent 形)。懒建;destroy 整树清。 */
     spoolRootDir;
+    /** 🔴 在飞的 fg spool 目录登记表(2026-07-25)。`destroy()` 原来只看 `bgManager.hasShells()` 就 `rm -rf`
+     *  spool 根 —— 而**前台** exec 的 spool 也在同一个根下,子进程通过继承的 fd 继续往已 unlink 的 inode 写,
+     *  父进程按**路径** stat/read 于是什么都看不到 ⇒ 命令照跑、副作用照落盘,但 stdout 被静默截断,还返回
+     *  `exitCode 0`。对模型而言那与「成功且无输出」**不可区分**。(与 core RB-73 同形:写已释放的 inode。)
+     *  判据与 `hasShells()` 并列:**只要还有人在读写这个根下的文件,就不删它**。 */
     liveFgSpools = new Set();
     ensureSpoolRoot() {
         if (!this.spoolRootDir)
             this.spoolRootDir = mkdtempSync(path.join(os.tmpdir(), "sema-host-spool-"));
         return this.spoolRootDir;
     }
+    /** True when `workspaceDir` was given (user-owned persistent dir) → destroy() must NOT delete it. */
     persistent;
+    /** Memoized lazy `mkdir -p` so concurrent first-use prepares the workspace exactly once. */
     preparing;
     handle;
     constructor(config = {}) {
         if (config.workspaceDir) {
+            // TOC/CC mode: the user's OWN dir, verbatim — no random subdir, never deleted (see destroy()).
             this.workspaceDir = path.resolve(config.workspaceDir);
             this.persistent = true;
         }
         else {
             const base = config.workspaceBase ?? os.tmpdir();
             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.workspaceDir = path.resolve(base, `sema-host-${sanitizeId(id)}-${suffix}`);
             this.persistent = false;
         }
@@ -85,12 +150,13 @@ export class RemoteHostExecutionEnv {
         this.cwd = this.workspaceDir;
         this.handle = { sandboxId: this.workspaceDir, provider: PROVIDER, mountPath: this.workspaceDir };
     }
+    // ─────────────────────────────── lifecycle ───────────────────────────────
     workspaceHandle() {
         return this.handle;
     }
     async connect(config) {
         if (config?.snapshotId)
-            return unsupported("connect(snapshotId)");
+            return unsupported("connect(snapshotId)"); // host has no snapshots
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
         if (config?.abortSignal?.aborted)
@@ -102,6 +168,7 @@ export class RemoteHostExecutionEnv {
             return { ok: false, error: new RemoteExecutionError("connect_failed", `failed to create host workspace ${this.workspaceDir}: ${errMsg(e)}`, asError(e)) };
         }
         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);
     }
@@ -114,46 +181,72 @@ export class RemoteHostExecutionEnv {
     async postResumeInit() {
         return unsupported("postResumeInit");
     }
+    /** The "connection" is the local process; there is nothing to re-establish. Idempotent success (unless destroyed). */
     async reconnect(_sessionToken) {
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
         return ok(this.handle);
     }
+    /** `rm -rf` the per-task workspace (NOT the machine). Idempotent, best-effort, never throws (cleanup contract).
+     *
+     *  core 1.258.2 destroy 契约注(remote-env.d.ts):非隔离 env(host lane,capabilities.isolation
+     *  缺席)的 destroy = 工作区/对象级清理,**不得收割仍在跑的后台进程**——收割全权归 `disposeBackgroundShells`
+     *  (它带 timeout/session keep-alive except 名单)。此前这里的无-except 全灭把
+     *  core 留活过的驻留 watcher 又杀了一遍(run 尾 dispose→destroy 顺序,destroy 是第二刀)。隔离 env(容器/VM)
+     *  整体拆机自然带走进程,与本契约不冲突(k8s/e2b 各自 destroy 不走这条路径)。 */
     async destroy() {
         if (this.destroyed)
-            return;
+            return; // idempotent — safe double-call (Runner end + reaper)
         this.destroyed = true;
+        // Await any in-flight prepare so a destroy-vs-first-use race can't leak the workspace dir:
+        // an attached .then may still flip prepared=true after we null the memo. Then rm unconditionally
+        // (force:true no-ops a never-created path), eliminating the prepared-flag race entirely.
         const p = this.preparing;
         this.preparing = undefined;
         try {
             await p?.catch(() => { });
         }
         finally {
+            // spool 根(tmpdir 私有)与 workspace 归属无关——persistent 形也要清(五轮复审迁址后属本 env 自有)。
+            // 六轮复审:但驻留 shell(core 1.258.2「destroy 不得收割后台进程」契约,keep-alive except 名单)与
+            // terminal 残余(dispose 前仍可轮询)还在读写这些文件——有任何 shell 在册即跳过整树删,逐 shell 清理
+            // 归 dispose 面(state.dir 单删);空根目录留给 OS tmp 周期清,量级=一个空目录。
+            // 判据两条并列(见 liveFgSpools 旁注):后台 shell **或**在飞的前台 exec,任一还在就不删这个根 ——
+            // 删了等于把它们正在写的文件从脚下抽走,而写者拿的是 fd、察觉不到,只有读者看到"空输出"。
             if (this.spoolRootDir && !this.bgManager.hasShells() && this.liveFgSpools.size === 0) {
                 try {
                     await fs.rm(this.spoolRootDir, { recursive: true, force: true });
                 }
-                catch { }
+                catch { /* best-effort */ }
                 this.spoolRootDir = undefined;
             }
             if (this.persistent)
-                return;
+                return; // user-owned persistent dir (TOC/CC) — NEVER rm -rf it
             try {
                 await fs.rm(this.workspaceDir, { recursive: true, force: true });
             }
             catch {
+                /* best-effort: never throw on teardown */
             }
         }
     }
     async cleanup() {
         return this.destroy();
     }
+    // ─────────────────────────────── design/103 background shell (host lane) ───────────────────────────────
+    // Host lane = single-user TOC (the user's own box) → background shell is ON (run_in_background/BashOutput/KillShell
+    // auto-mount via core's `hasBackgroundShell`). `HOST_BG_ENABLED=false` turns it INERT (defence for a mis-configured
+    // multi-tenant host lane). caps tuned via HOST_BG_* env. The manager owns the red-lines; the driver below is local.
+    // A getter (NOT a field initializer) so it reads `this.cfg` which is set in the constructor — a field initializer
+    // runs before the constructor body and would see cfg undefined (the kata adapter hit the same ordering trap).
     get backgroundCapabilities() {
         return {
             supported: (this.cfg.backgroundShell ?? true) && hostBackgroundShellEnabled(),
             maxConcurrent: HOST_BG_MAX_CONCURRENT,
             defaultBgTimeoutSec: HOST_BG_DEFAULT_TIMEOUT_SEC,
             maxBgTimeoutSec: HOST_BG_MAX_TIMEOUT_SEC,
+            // core 1.207 design/116 detach (clay 排, 1.81): a running foreground exec can be ADOPTED as a background
+            // shell (mid-flight ctrl+b). Core's Bash tool gates the whole detach chain on this flag === true.
             supportsDetach: (this.cfg.backgroundShell ?? true) && hostBackgroundShellEnabled(),
         };
     }
@@ -165,21 +258,25 @@ export class RemoteHostExecutionEnv {
         const self = this;
         return {
             async launch(command, options, ctx) {
-                const ready = await self.shellReady();
+                const ready = await self.shellReady(); // lazily prepares the workspace dir
                 if (!ready.ok)
                     throw new BackgroundShellError("spawn_failed", ready.error.message);
                 const dir = path.join(self.ensureSpoolRoot(), "bg-" + randomBytes(8).toString("hex"));
                 await fs.mkdir(dir, { recursive: true });
                 const outPath = path.join(dir, "out");
                 const errPath = path.join(dir, "err");
+                // Open the child's stdout/stderr targets; the parent closes its OWN fd copies right after spawn so file
+                // size/EOF reflect only the child's writes (the child keeps its inherited fds).
                 const outFh = await fs.open(outPath, "w");
                 const errFh = await fs.open(errPath, "w");
                 let child;
                 try {
-                    const sh = hostShell();
+                    const sh = hostShell(); // Windows S1/S3: behind shellReady() above → resolved
                     child = spawn(sh.shell, [...sh.args, command], {
                         cwd: self.resolve(options?.cwd ?? self.cwd),
-                        env: self.mergeEnv(options?.env),
+                        env: self.mergeEnv(options?.env), // 🔴 SAME secret-scrub as exec (design/103 §3.1) — host process.env minus secret-pattern keys
+                        // POSIX: detached:true → child = process-group leader (pgid === pid), kill(-pid) reaps the whole
+                        // group. win32: no POSIX group either way — windowsHide, kill side = taskkill tree (design D3).
                         ...spawnGroupOptions(),
                         stdio: ["ignore", outFh.fd, errFh.fd],
                     });
@@ -191,10 +288,18 @@ export class RemoteHostExecutionEnv {
                     throw new BackgroundShellError("spawn_failed", e instanceof Error ? e.message : String(e), e);
                 }
                 const pid = child.pid;
+                // 🔴 register close/error listeners SYNCHRONOUSLY (before any await) — a fast child must not exit before we
+                // listen, else onTerminal never fires and the shell would lie "running" until the timeout wall.
                 if (pid != null) {
+                    // core-baseline terminal semantics (Fable-5 review #1): ANY self-ended process is "exited" with its exit
+                    // code (signal death synthesizes the conventional 128+signo, like core's NodeExecutionEnv + the k8s/E2B
+                    // lanes) — a non-zero exit is a NORMAL result, NOT "failed". "failed" is reserved for spawn-level errors.
+                    // The old non-zero→failed classification hid the exit code from the model (BashOutput only prints
+                    // `exited(code N)`), and split the three lanes' semantics. Classify on `close` (not `exit`), also per
+                    // core baseline — stdio settled before the status flips (with fd-passed spool files close ≈ exit anyway).
                     child.on("close", (code, signal) => ctx.onTerminal(false, code ?? (signal ? 128 + (signalNumber(signal) ?? 9) : 0)));
-                    child.on("error", () => ctx.onTerminal(true));
-                    child.unref();
+                    child.on("error", () => ctx.onTerminal(true)); // post-pid spawn error (rare)
+                    child.unref(); // a detached background job must not keep the worker's event loop alive
                 }
                 await outFh.close().catch(() => { });
                 await errFh.close().catch(() => { });
@@ -205,6 +310,8 @@ export class RemoteHostExecutionEnv {
                 return { pid, dir, outPath, errPath, stdoutCursor: 0, stderrCursor: 0 };
             },
             async read(state) {
+                // ADOPT (memory) mode: drain the in-memory buffers (no files). Each read returns the queued chunks +
+                // resets the queue; totalBytes/droppedBytes are cursor metadata (design/103 §3.4).
                 if (state.mem) {
                     const o = drainMemStream(state.mem.out);
                     const e = drainMemStream(state.mem.err);
@@ -215,6 +322,9 @@ export class RemoteHostExecutionEnv {
                         bytesDroppedBeforeCursor: o.dropped + e.dropped,
                     };
                 }
+                // Returns the advanced cursor AND the TRUE on-disk size — the per-poll READ is capped at HOST_BG_READ_CAP,
+                // but the disk guard must see the real file size (a slow poller advances the cursor ≤1 MiB/poll while the
+                // file on the operator's real disk could already be GBs — review MED).
                 const readForward = async (p, cursor, dec) => {
                     let fh;
                     try {
@@ -222,93 +332,134 @@ export class RemoteHostExecutionEnv {
                     }
                     catch {
                         return { chunk: "", cursor, size: cursor };
-                    }
+                    } // file gone (disposed) → no new bytes
                     try {
                         const { size } = await fh.stat();
                         if (size <= cursor)
-                            return { chunk: "", cursor: size, size };
+                            return { chunk: "", cursor: size, size }; // no growth (or shrank) → cursor tracks size
                         const n = Math.min(size - cursor, HOST_BG_READ_CAP);
                         const buf = Buffer.alloc(n);
                         await fh.read(buf, 0, n, cursor);
+                        // per-shell StringDecoder([1116] 批):跨段码点保状态——逐段 toString 会在段界劈出 U+FFFD。
                         return { chunk: dec.write(buf), cursor: cursor + n, size };
                     }
                     finally {
                         await fh.close().catch(() => { });
                     }
                 };
+                // File mode (launch + [1116] spool adoption): the memory-mode early-return above handled `state.mem`.
                 state.decOut ??= new StringDecoder("utf8");
                 state.decErr ??= new StringDecoder("utf8");
                 const o = await readForward(state.outPath, state.stdoutCursor, state.decOut);
                 const e = await readForward(state.errPath, state.stderrCursor, state.decErr);
                 state.stdoutCursor = o.cursor;
                 state.stderrCursor = e.cursor;
+                // Disk guard: reap a runaway by its TRUE on-disk size (the host lane has no VM isolation to contain a
+                // runaway output file; the BG-timeout also bounds wall-clock).
                 let terminal;
                 if (o.size > HOST_BG_FILE_CAP || e.size > HOST_BG_FILE_CAP) {
                     try {
                         killTreeHard(state.pid);
                     }
-                    catch { }
+                    catch { /* already dead */ } // disk-guard熔断 (the 5th kill site) — POSIX kill(-pid) byte-identical; win32 taskkill /F /T
                     terminal = { failed: true };
                 }
+                // F2/F3([1116] 批,二轮复审):spool adoption 携带的 fg 期文件移除字节。preSpoolBase 每拍并入
+                // bytesFromStart(单调不倒退);pendingDropped 只首拍并入 bytesDroppedBeforeCursor 后清零(launch
+                // 形两者恒 undefined→0:本地文件不 head-evict,全量保留到 dispose)。
                 const preBase = state.preSpoolBase ?? 0;
                 const pending = state.pendingDropped ?? 0;
                 state.pendingDropped = 0;
                 return {
                     stdout: o.chunk,
                     stderr: e.chunk,
-                    bytesFromStart: o.size + e.size + preBase,
+                    bytesFromStart: o.size + e.size + preBase, // TRUE total from start(含 fg 已移除段;preBase 每拍恒在)
                     bytesDroppedBeforeCursor: pending,
                     ...(terminal ? { terminal } : {}),
                 };
             },
             async kill(state) {
+                // host lane has NO container isolation — a SIGTERM-trapping group must still die at the hard wall. Send
+                // SIGTERM, then escalate to SIGKILL after a short grace (mirrors kata's `kill -TERM; sleep 1; kill -KILL`).
+                // This is the path for BOTH KillShell and the manager's BG-timeout wall, so the §3.6 "到点自杀" really kills.
+                // POSIX byte-identical: killTreeSoft = kill(-pid, SIGTERM) incl. the throw-on-dead-group → return (no
+                // escalation needed). win32 (design D2): soft = taskkill /T — a no-op for console trees ("can only be
+                // terminated forcefully"), and it never throws, so the escalation timer ALWAYS arms there: the ladder
+                // degrades to delay→hard-kill, which is exactly the accepted win32 semantics.
                 try {
                     killTreeSoft(state.pid);
                 }
                 catch {
                     return;
-                }
+                } // idempotent: already-dead group → no escalation needed
                 setTimeout(() => { try {
                     killTreeHard(state.pid);
                 }
-                catch { } }, HOST_BG_KILL_GRACE_MS).unref?.();
+                catch { /* exited within grace */ } }, HOST_BG_KILL_GRACE_MS).unref?.();
             },
             async disposeOne(state) {
-                state.detachCleanup?.();
+                state.detachCleanup?.(); // adopt path: detach the extra pipe listeners (memory mode → no fds/dir)
                 try {
                     killTreeHard(state.pid);
                 }
-                catch { }
+                catch { /* already dead */ }
                 if (state.dir)
-                    await fs.rm(state.dir, { recursive: true, force: true }).catch(() => { });
+                    await fs.rm(state.dir, { recursive: true, force: true }).catch(() => { }); // file (launch) mode only
             },
         };
     }
     spawnBackground(command, options) {
         return this.bgManager.spawn(command, options);
     }
+    /**
+     * design/116 detach (core 1.207, clay 排 1.81): ADOPT a still-running FOREGROUND exec child as a background
+     * shell — the mid-flight ctrl+b path. The exec child writes to pipes (not files, unlike a `launch`-spawned
+     * bg shell), so adoption splices those live pipes into fresh bg spool files: pre-fill them with the output
+     * captured so far (the detach TEE, fed from the exec's FIRST chunk → TaskOutput's first read has the full
+     * history), then append every subsequent chunk. From then on the shell is indistinguishable from a spawned one
+     * (poll by cursor, kill by pgid, the BG-timeout wall applies). Returns the opaque shellId, or `undefined` when
+     * the live-shell limit is hit (detach refused → the exec keeps running in the foreground; NEVER a dropped process).
+     *
+     * `memOut`/`memErr` are the exec's tee-from-start buffers (Fable-5 review #3, mirrors the E2B tee): they were fed
+     * every chunk since process start THROUGH THE SAME per-stream StringDecoder that keeps feeding post-detach, so a
+     * multibyte codepoint straddling the detach instant decodes correctly (the old seed-from-fg-tail handoff decoded
+     * the two halves in separate passes → U+FFFD at the seam).
+     */
     adoptRunningExec(child, memOut, memErr) {
         const pid = child.pid;
         if (pid == null)
-            return undefined;
+            return undefined; // no pid → nothing to adopt (exec keeps running / will settle normally)
+        // 🔴 FULLY SYNCHRONOUS (double-review, 3 findings): memory buffers, no files/fds. The tee handover + the
+        // live-pipe listener attach happen in ONE tick so no output is lost to an async window, and the exec-settle
+        // can't race the adoption (mirrors core's `adoptRunningChild`).
+        // 🔴 builder contract (Fable-5 review #5): everything below is NON-THROWING (listener attach + plain object
+        // construction). adoptSync's catch returns undefined WITHOUT undoing side effects — any future logic that can
+        // throw must go BEFORE the first side effect (listener/on) or clean up after itself.
         const adopted = this.bgManager.adoptSync((ctx) => {
             const mem = { out: memOut, err: memErr };
+            // Bound un-drained memory (no VM on the host lane to contain a runaway): drop OLDEST, count as truncated.
             const onOut = (d) => feedMemStream(mem.out, d, HOST_BG_MEM_CAP);
             const onErr = (d) => feedMemStream(mem.err, d, HOST_BG_MEM_CAP);
             child.stdout?.on("data", onOut);
             child.stderr?.on("data", onErr);
+            // core-baseline terminal semantics (Fable-5 review #1, same as the launch path): self-ended → "exited" with
+            // the exit code (signal death = 128+signo), NEVER "failed" — matches core's adoptRunningChild verbatim.
+            // Classify on `close` (not `exit`), also per core baseline: in pipe (adopt) mode the final data events can
+            // trail `exit` — flipping the status early lets a poll in that window read "exited" with the tail undrained.
             const onClose = (code, signal) => ctx.onTerminal(false, code ?? (signal ? 128 + (signalNumber(signal) ?? 9) : 0));
             const onErrEvt = () => ctx.onTerminal(true);
             child.on("close", onClose);
             child.on("error", onErrEvt);
+            // Race guard: the child may have exited between the detach request and adoption — a close that fired before
+            // the listener attached won't re-fire, so classify terminal now (mirrors core's adoptRunningChild).
             if (child.exitCode !== null || child.signalCode !== null)
                 ctx.onTerminal(false, child.exitCode ?? (child.signalCode ? 128 + (signalNumber(child.signalCode) ?? 9) : 0));
-            child.unref?.();
+            child.unref?.(); // a detached background job must not keep the worker's event loop alive
             const detachCleanup = () => {
                 child.stdout?.off("data", onOut);
                 child.stderr?.off("data", onErr);
                 child.off("close", onClose);
-                child.off("error", onErrEvt);
+                child.off("error", onErrEvt); // no fds to close — memory mode
             };
             return { pid, stdoutCursor: 0, stderrCursor: 0, mem, detachCleanup };
         });
@@ -321,8 +472,18 @@ export class RemoteHostExecutionEnv {
         return this.bgManager.kill(shellId);
     }
     disposeBackgroundShells(opts) {
+        // 签名带 opts——core runtask 尾调 `{except: keepAlive}`(timeout/session 驻留 Monitor
+        // 留活名单),此前无参签名把它静默丢弃=kill-all。透传给 manager(无参=既有全灭)。
         return this._bgManager ? this._bgManager.dispose(opts) : Promise.resolve();
     }
+    // ─────────────────────────────── Shell: buffered exec ───────────────────────────────
+    //
+    // [1116] fg spool 化(core 1.318 修的平行盲区,当班移植):管道 stdio + 等 `close` settle 的旧形,
+    // 在孙进程(`nohup server &`)持有管道写端时 close 恒不发——exec 挂满 timeout → 组杀连坐孙进程。
+    // spool 形:子进程 stdout/stderr 直写文件 fd(进程间零管道),`close` 仍是主 settle 路,但 `exit`
+    // +500ms drain 兜底(close 不来也 settle);正常终态不进任何杀伤集(timeout/abort 才杀树)。
+    // detach adoption 走 FILE 形 handover(spool 路径+游标直接进 HostBgState——launch 同形,poll 共码,
+    // 单一字节流天然无 decoder 接缝)。win32 / spool 打开失败 → 回退管道旧形(core 同姿势)。
     async exec(command, options) {
         if (options?.abortSignal?.aborted)
             return { ok: false, error: new ExecutionError("aborted", "exec aborted before start") };
@@ -331,7 +492,11 @@ export class RemoteHostExecutionEnv {
             return ready;
         const cwd = this.resolve(options?.cwd ?? this.cwd);
         const timeoutMs = options?.timeout != null ? options.timeout * 1000 : this.cfg.commandTimeoutMs;
+        // core 1.207 design/116 detach: the Bash tool threads a `detachSignal` when the model/operator mid-flight
+        // ctrl+b's a running command. `ExecOpts` doesn't type it yet (core-side seam) — read it structurally.
         const detachSignal = options?.detachSignal;
+        // [1116] spool 形优先(POSIX;HOST_EXEC_SPOOL_ENABLED=false 逃生舱)。打开失败=回退管道旧形,永不因
+        // spool 基建挡 exec。
         if (process.platform !== "win32" && hostExecSpoolEnabled()) {
             const spool = this.openFgSpool();
             if (spool)
@@ -339,19 +504,37 @@ export class RemoteHostExecutionEnv {
         }
         return this.execViaPipes(command, options, cwd, timeoutMs, detachSignal);
     }
+    /** 管道旧形(win32 / spool 打开失败的回退;行为=1.225 及以前的 exec 原样)。 */
     execViaPipes(command, options, cwd, timeoutMs, detachSignal) {
         return new Promise((resolve) => {
+            // D2: bounded rolling-TAIL (core's RollingTailBuffer) — a model-driven `yes`/`cat big.bin` can't OOM the
+            // durable worker; keep only the last 8MB (tail = errors+exit, what the model needs) + a dropped-byte marker. O(maxBytes).
             const outBuf = new RollingTailBuffer();
             const errBuf = new RollingTailBuffer();
+            // design/116 detach TEE (mirrors the E2B tee-from-start): when the exec is detach-capable,
+            // tee every chunk from process START into the pair of drain buffers a later adoption hands over as-is. The
+            // per-stream StringDecoder inside BgMemStream then spans the whole stream — fg segment AND post-detach segment
+            // decode through ONE stateful decoder, so a multibyte codepoint straddling the detach instant survives (the
+            // old fg-tail→seed handoff decoded the halves separately → U+FFFD at the seam). Cost: one extra bounded
+            // (drop-oldest, HOST_BG_MEM_CAP) buffer pair for the exec's lifetime, only when a detachSignal is present.
             const tee = detachSignal ? { out: seedMemStream(""), err: seedMemStream("") } : undefined;
             let settled = false;
+            // D5 pipe-destroy grace: armed inside kill() (abort/timeout); destroys the stdout/stderr pipes if `close`
+            // never fires (a re-parented grandchild holding the FD). Cleared in finish() — including the real `close`
+            // path, which routes through finish() — so the timer never leaks. Does NOT change promise settle (the
+            // abort/timeout handlers already finish() synchronously below).
             let forceSettleTimer;
+            // Windows S1/S3 (design D1/D3): shell + group options are platform-resolved (POSIX byte-identical:
+            // /bin/sh + detached:true so kill(-pid) reaps the whole group; win32: Git Bash + windowsHide, kill
+            // side uses the taskkill tree instead of a group).
             const sh = hostShell();
             const child = spawn(sh.shell, [...sh.args, command], {
                 cwd,
                 env: this.mergeEnv(options?.env),
                 ...spawnGroupOptions(),
             });
+            // core 1.321 cut-kill registry(三轮复审存量缺口):把杀柄交给上层(Bash 工具 cut 时强制终杀);
+            // 柄内 still-running 守卫(exitCode/signalCode)防对已亡组的 pgid 复用误杀(core 参考实现同语义)。
             if (options?.onSpawn && child.pid != null) {
                 const spawnedPid = child.pid;
                 try {
@@ -365,18 +548,23 @@ export class RemoteHostExecutionEnv {
                                 try {
                                     child.kill("SIGKILL");
                                 }
-                                catch { }
+                                catch { /* noop */ }
                             }
                         } });
                 }
-                catch { }
+                catch { /* registry 回调失败不挡 exec(core 同姿势吞) */ }
             }
             const finish = (r) => {
                 if (settled)
                     return;
                 settled = true;
                 clearTimeout(timer);
+                // NOTE: the D5 grace timer is cleared in the `close` handler (pipes closed naturally), NOT here — an
+                // abort/timeout settle reaches finish() BEFORE `close`, so clearing here would cancel the grace before
+                // it can free a leaked FD (the exact case it exists for). On abort/timeout it fires after the grace.
                 options?.abortSignal?.removeEventListener("abort", onAbort);
+                // A foreground settle must also release the never-fired detach listener — the hub's signal
+                // can outlive this exec (bounded 256-entry hub), and the listener closes over the child + tee buffers.
                 removeDetachListener?.();
                 resolve(r);
             };
@@ -384,14 +572,17 @@ export class RemoteHostExecutionEnv {
             const kill = () => {
                 try {
                     if (child.pid != null)
-                        killTreeHard(child.pid);
+                        killTreeHard(child.pid); // POSIX: kill(-pid) whole group (byte-identical); win32: taskkill /F /T
                 }
                 catch {
                     try {
                         child.kill("SIGKILL");
                     }
-                    catch { }
+                    catch { /* noop */ }
                 }
+                // D5: if the kill leaves a re-parented grandchild holding the pipes, `close` may never come — free the
+                // stdout/stderr FDs after a short grace. Idempotent (armPipeDestroyGrace is a no-op if already settled →
+                // we only ever arm one; reassigning is harmless since kill is called once per abort/timeout).
                 forceSettleTimer ??= armPipeDestroyGrace(child);
             };
             const timer = setTimeout(() => {
@@ -404,38 +595,56 @@ export class RemoteHostExecutionEnv {
             };
             if (options?.abortSignal)
                 options.abortSignal.addEventListener("abort", onAbort, { once: true });
+            // core 1.207 design/116 detach (clay 排, 1.81): mid-flight ctrl+b — ADOPT the running child as a background
+            // shell instead of killing it. On adoption the exec settles EARLY with `detached:{shellId}` (+ the output
+            // captured so far); ownership (output capture → the bg files, close handling, the BG-timeout wall, kill)
+            // moves to the bgManager entry. Fired after `settled` = too late (no-op). Refused over the live-shell limit
+            // (or on a pid-less/failed adopt) → the exec keeps running in the foreground, settling normally on close.
             const onDetach = () => {
                 if (settled)
                     return;
                 const out = outBuf.result();
                 const err = errBuf.result();
+                // 🔴 SYNCHRONOUS adopt (double-review): no `await` between the tee handover and the pipe-listener attach,
+                // so no data chunk is lost and no exec close/timeout can settle mid-adoption. The exec's ORIGINAL stdout/
+                // stderr listeners are removed FIRST so post-detach output flows only to the adopted memory buffers (no
+                // double-count into the now-orphaned outBuf) and `close` won't re-drive them. The adopted spool is the
+                // tee-from-start pair (already holds every chunk since process start through ONE stateful decoder — review
+                // #3); the truncation marker rides on the exec's OWN result string only (review LOW).
                 child.stdout?.off("data", onExecOut);
                 child.stderr?.off("data", onExecErr);
                 const shellId = this.adoptRunningExec(child, tee.out, tee.err);
                 const seedOut = markTruncated(out.text, out.droppedBytes);
                 const seedErr = markTruncated(err.text, err.droppedBytes);
                 if (shellId === undefined) {
+                    // Refused (limit) or no pid → re-attach the exec listeners; the command keeps running in the foreground
+                    // and settles normally on close (NEVER a dropped process).
                     child.stdout?.on("data", onExecOut);
                     child.stderr?.on("data", onExecErr);
                     return;
                 }
-                clearTimeout(timer);
+                clearTimeout(timer); // the adopted process is the bgManager's now (its own BG-timeout wall applies)
                 if (forceSettleTimer)
                     clearTimeout(forceSettleTimer);
                 options?.abortSignal?.removeEventListener("abort", onAbort);
                 settled = true;
+                // cut-kill registry 注销(所有权已移交 bgManager——cut 不该再杀后台 shell;core 参考实现同位)。
                 try {
                     options?.onDetachAdopted?.();
                 }
-                catch { }
+                catch { /* noop */ }
                 resolve(ok({ stdout: seedOut, stderr: seedErr, exitCode: 0, detached: { shellId } }));
             };
+            // Named (not inline) so onDetach can `off` them when it hands the pipes to the adopted background shell.
             const onExecOut = (d) => { outBuf.push(d); if (tee)
                 feedMemStream(tee.out, d, HOST_BG_MEM_CAP); options?.onStdout?.(d.toString()); };
             const onExecErr = (d) => { errBuf.push(d); if (tee)
                 feedMemStream(tee.err, d, HOST_BG_MEM_CAP); options?.onStderr?.(d.toString()); };
             child.stdout?.on("data", onExecOut);
             child.stderr?.on("data", onExecErr);
+            // 🔴 AFTER the exec listeners exist (TDZ): core's ToolDetachHub uses create-then-abort, so a detach that
+            // landed BEFORE this exec started arrives as an ALREADY-aborted signal → onDetach runs synchronously right
+            // here and must be able to `off`/re-`on` onExecOut/onExecErr. Same tick either way — no event can interleave.
             if (detachSignal) {
                 if (detachSignal.aborted)
                     onDetach();
@@ -445,11 +654,16 @@ export class RemoteHostExecutionEnv {
                 }
             }
             child.on("error", (e) => {
+                // Failure to even spawn the shell (ENOENT etc.) — never the command's own non-zero exit.
                 finish({ ok: false, error: new ExecutionError("spawn_error", `host spawn failed: ${e.message}`, e) });
             });
             child.on("close", (code, signal) => {
+                // `close` fired ⇒ the pipes closed naturally → clear the D5 grace (it only needs to force-destroy FDs when
+                // `close` NEVER comes after a kill — the re-parented-grandchild leak). Clearing here, not in finish().
                 if (forceSettleTimer)
                     clearTimeout(forceSettleTimer);
+                // A non-zero exit is a NORMAL value, not an error (ExecutionEnv contract). A kill-by-signal that
+                // wasn't a timeout/abort still resolves with the conventional 128+signo exit code.
                 const exitCode = code ?? (signal ? 128 + (signalNumber(signal) ?? 0) : 1);
                 const out = outBuf.result();
                 const err = errBuf.result();
@@ -457,6 +671,8 @@ export class RemoteHostExecutionEnv {
             });
         });
     }
+    /** [1116] fg spool pair:tmpdir 私有根下专属子目录(五轮复审迁址,workspace=命令可写区不可放)+ "ax"
+     *  独占建(core openSpoolPair 同形)。失败=undefined(调用方回退管道形)。 */
     openFgSpool() {
         try {
             const dir = path.join(this.ensureSpoolRoot(), "fg-" + randomBytes(8).toString("hex"));
@@ -472,16 +688,17 @@ export class RemoteHostExecutionEnv {
                 try {
                     closeSync(fdOut);
                 }
-                catch { }
+                catch { /* noop */ }
                 throw e;
             }
-            this.liveFgSpools.add(dir);
+            this.liveFgSpools.add(dir); // 见 liveFgSpools 旁注:登记后 destroy() 才不会把它脚下的根删掉
             return { dir, outPath, errPath, fds: [fdOut, fdErr] };
         }
         catch {
             return undefined;
         }
     }
+    /** [1116] spool 形 fg exec(core node-execution-env 1.318-1.321 机制移植;坑图=core CHANGELOG 同段)。 */
     execViaSpool(command, options, cwd, timeoutMs, detachSignal, spool) {
         const EXIT_SETTLE_DRAIN_MS = 500;
         const PUMP_MS = 200;
@@ -492,10 +709,14 @@ export class RemoteHostExecutionEnv {
             const outBuf = new RollingTailBuffer();
             const errBuf = new RollingTailBuffer();
             let settled = false;
-            let handedOver = false;
+            let handedOver = false; // detach adoption 拿走了 spool 文件(bg poll 续读)——settle 清理不删文件
             let pump;
             let drainTimer;
             const cursor = { out: 0, err: 0 };
+            // F2(二轮复审):从命名 spool **文件**移除的累计字节(仅轮转/硬帽 truncate;skipAhead 不算,
+            // 字节还在文件里)——与
+            // RollingTailBuffer.droppedBytes 独立(后者只反映内存尾窗的 head-evict,轮转 truncate 后尾窗仍满
+            // =0 dropped,整代对文件消失却不计)。handover 从 0 读现存文件,这个数就是 bg 看不到的历史。
             const spoolRemoved = { out: 0, err: 0 };
             const lanes = [
                 { path: spool.outPath, key: "out", buf: outBuf, cb: options?.onStdout },
@@ -531,25 +752,33 @@ export class RemoteHostExecutionEnv {
                         return;
                     const skipped = behind - keep;
                     lane.buf.recordSkippedBytes(skipped);
+                    // 注意:skip 只推游标,字节仍留在命名文件里(handover 从 0 读**看得到**)——不计 spoolRemoved;
+                    // 它们随后被 truncate 抹掉时按 cursor 整段计入(三轮复审:此处预计会双计)。
                     cursor[lane.key] += skipped;
                 }
-                catch { }
+                catch { /* noop */ }
             };
             const reclaim = (lane) => {
+                // 轮转回收(core 坑图「配额绕过」形):游标推进到 ROTATE 以上且文件读平 → truncate 归零;文件冲破
+                // 硬帽(泵落后)→ 记 skipped 后强制归零(磁盘上限=诚实丢最旧)。
                 if (cursor[lane.key] < ROTATE_BYTES)
                     return;
                 try {
                     const size = statSync(lane.path).size;
                     if (size === cursor[lane.key] || size >= HARD_CAP_BYTES) {
+                        // F2 竞窗补账(三轮复审收紧):truncate 前复采 size2(stat→truncate 间 "ax" append 形可能又写)
+                        // → 记账全部挪到 truncateSync **成功之后**(throw=文件一字未动=不记 spoolRemoved,下拍重试);
+                        // 实际截除=size2 整段(cursor 已 pump 部分 + 未 pump 部分)。size2 采样与 truncate 之间的极窄
+                        // append 窗仍在(活跃写者下 truncate 语义固有;量级=两条相邻 syscall 间),接受为残余误差。
                         const size2 = statSync(lane.path).size;
                         truncateSync(lane.path, 0);
                         if (size2 > cursor[lane.key])
-                            lane.buf.recordSkippedBytes(size2 - cursor[lane.key]);
-                        spoolRemoved[lane.key] += size2;
+                            lane.buf.recordSkippedBytes(size2 - cursor[lane.key]); // 未 pump 段对内存尾窗=跳过
+                        spoolRemoved[lane.key] += size2; // 硬帽/轮转同式:文件真正归零的字节数
                         cursor[lane.key] = 0;
                     }
                 }
-                catch { }
+                catch { /* noop */ }
             };
             const feed = (lane, inc) => {
                 lane.buf.push(inc);
@@ -557,7 +786,7 @@ export class RemoteHostExecutionEnv {
                     try {
                         lane.cb?.(inc.toString("utf8"));
                     }
-                    catch { }
+                    catch { /* callback 失败不挡 settle(host 旧形同容忍) */ }
                 }
             };
             const pumpOnce = () => {
@@ -570,6 +799,7 @@ export class RemoteHostExecutionEnv {
                 }
             };
             const drainFinal = () => {
+                // finalization 真尾部(core 坑图:快突发不再拿头丢尾)——先跳到只剩 FINAL_TAIL 窗,再最多 4 轮读平。
                 for (const lane of lanes) {
                     skipAhead(lane, FINAL_TAIL_BYTES);
                     for (let i = 0; i < 4; i++) {
@@ -589,21 +819,23 @@ export class RemoteHostExecutionEnv {
                     clearTimeout(drainTimer);
                     drainTimer = undefined;
                 }
-                this.liveFgSpools.delete(spool.dir);
+                this.liveFgSpools.delete(spool.dir); // 注销:本 exec 已 settle,它不再需要这个根活着
                 if (!handedOver) {
+                    // RB-26 同型记档(core 官方裁决,发版复审 F3 对拆):幸存孙进程持继承 fd 对 unlinked inode 的
+                    // 后续写=脱离进程自身的增长,接受不管(命名文件形=CC 同暴露且路径可见更差;进程退出即回收)。
                     for (const lane of lanes) {
                         try {
                             unlinkSync(lane.path);
                         }
-                        catch { }
+                        catch { /* noop */ }
                     }
                     try {
                         rmdirSync(spool.dir);
                     }
-                    catch { }
+                    catch { /* noop */ }
                 }
             };
-            let removeDetachListener;
+            let removeDetachListener; // F5(二轮复审):先声明——onAbort→finish 会读它,TDZ 会抛 ReferenceError
             const finish = (r) => {
                 if (settled)
                     return;
@@ -619,7 +851,7 @@ export class RemoteHostExecutionEnv {
                     try {
                         closeSync(fd);
                     }
-                    catch { }
+                    catch { /* noop */ }
                 }
             };
             const sh = hostShell();
@@ -629,15 +861,18 @@ export class RemoteHostExecutionEnv {
                     cwd,
                     env: this.mergeEnv(options?.env),
                     ...spawnGroupOptions(),
-                    stdio: ["ignore", spool.fds[0], spool.fds[1]],
+                    stdio: ["ignore", spool.fds[0], spool.fds[1]], // 子进程直写文件——进程间零管道([1116] 病理根除点)
                 });
             }
             catch (e) {
+                // 同步 spawn throw(如 cwd=文件的 ENOTDIR)——与管道旧形字节级对齐:executor 内 re-throw=Promise
+                // reject(消费方契约:core pruneWorktrees 等 await 抛才算失败;吞成 Result err 会让 reap 静默)。
                 closeSpoolFds();
                 cleanupSpool();
                 throw e;
             }
-            closeSpoolFds();
+            closeSpoolFds(); // 父进程的 fd 副本立即关(文件 size/EOF 只反映子进程写;launch FILE 形同姿势)
+            // core 1.321 cut-kill registry(三轮复审存量缺口):同 pipe 径——杀柄带 still-running 守卫。
             if (options?.onSpawn && child.pid != null) {
                 const spawnedPid = child.pid;
                 try {
@@ -651,12 +886,16 @@ export class RemoteHostExecutionEnv {
                                 try {
                                     child.kill("SIGKILL");
                                 }
-                                catch { }
+                                catch { /* noop */ }
                             }
                         } });
                 }
-                catch { }
+                catch { /* registry 回调失败不挡 exec */ }
             }
+            // 七轮复审:'error' 监听必须在任何可提前 return 的路径(下方 F5 already-aborted 查)之前装——异步
+            // spawn 失败(如 cwd 不存在)以 ChildProcess 'error' 事件发出,无监听=uncaught 直接打死 worker 进程
+            // (plain-node 最小形实证 crash;vitest/tsx 宿主会吸收,故该面无法用测试钉住,靠此排序保证)。
+            // settle 后到达的 'error' 经 finish 的 settled 门自然吞掉。
             child.on("error", (e) => {
                 finish({ ok: false, error: new ExecutionError("spawn_error", `host spawn failed: ${e.message}`) });
             });
@@ -666,10 +905,14 @@ export class RemoteHostExecutionEnv {
                 const e = errBuf.result();
                 return { stdout: markTruncated(o.text, o.droppedBytes), stderr: markTruncated(e.text, e.droppedBytes) };
             };
+            // F4(发版复审):exit 一到即 latch——命令已 completed,此后 timeout/abort 绝不再杀(否则 close
+            // 延迟/缺席的 500ms drain 窗内,一个 timeout 会把幸存进程组连坐——恰是本修要消的杀伤面),detach
+            // 也不再领养(completed 命令不是后台工作)。只剩 drain timer 与 close 竞争 settle。
             let exited = false;
             const timer = setTimeout(() => {
                 if (exited)
-                    return;
+                    return; // F4:completed 命令不进杀伤集(drain settle 即将给出正常结果)
+                // timeout 仍杀树(RUNNING 命令超时=合法杀伤面;[1116] 修的是 completed 命令被 close 不来拖进杀伤集)
                 try {
                     if (child.pid != null)
                         killTreeHard(child.pid);
@@ -678,14 +921,14 @@ export class RemoteHostExecutionEnv {
                     try {
                         child.kill("SIGKILL");
                     }
-                    catch { }
+                    catch { /* noop */ }
                 }
                 const p = partial();
                 finish({ ok: false, error: new ExecutionError("timeout", `host exec exceeded ${timeoutMs}ms; partial stdout: ${p.stdout.slice(-2048)}`) });
             }, timeoutMs);
             const onAbort = () => {
                 if (exited)
-                    return;
+                    return; // F4 同上:已 completed 的 abort=让 drain settle 正常返回,不杀幸存组
                 try {
                     if (child.pid != null)
                         killTreeHard(child.pid);
@@ -694,31 +937,43 @@ export class RemoteHostExecutionEnv {
                     try {
                         child.kill("SIGKILL");
                     }
-                    catch { }
+                    catch { /* noop */ }
                 }
                 finish({ ok: false, error: new ExecutionError("aborted", "host exec aborted") });
             };
+            // F5(发版复审):AbortSignal 不重放 shellReady/workspace 建目录期间已发生的 abort——注册前必查。
             if (options?.abortSignal?.aborted) {
                 onAbort();
                 return;
             }
             if (options?.abortSignal)
                 options.abortSignal.addEventListener("abort", onAbort, { once: true });
+            // F1(发版复审):泵先装再挂 detach——already-aborted 的 detachSignal 会同步跑 onDetach→finish,
+            // 若泵在其后才装,cleanupSpool 清不到=幽灵泵继续 truncate 已移交的文件+常驻泄漏。
             pump = setInterval(pumpOnce, PUMP_MS);
             pump.unref?.();
             const onDetach = () => {
                 if (settled || exited)
-                    return;
-                pumpOnce();
+                    return; // F4:completed 命令不领养(它不是后台工作;drain settle 在途)
+                pumpOnce(); // fg 段读平(exec 结果里的 seed 完整)
+                // handover 游标=0(消费方契约,旧 mem 形同语义):core 的 Bash 工具在 detach 时只给模型
+                // 「moved to background」marker、丢弃 exec 结果的 stdout——完整历史必须活在 bg spool 里由
+                // BashOutput 给。spool FILE 形从 0 重读同一文件=fg+post 单一字节流零接缝零 U+FFFD(mem-tee
+                // 为此专门修过的病结构性不存在);已被轮转 truncate 的头部(>8MB)在 exec 结果里已 markTruncated。
+                // F2(发版复审):fg 期发生过轮转/skip 的丢失字节随 handover 记账(bg 首拍 poll 并入
+                // bytesDroppedBeforeCursor → BashOutput 的 truncated 面诚实),从 0 读只覆盖现存代。
+                // F2(二轮复审):handover 丢失=从命名 spool 文件真正移除的字节(spoolRemoved),不是 RollingTail
+                // 尾窗的 head-evict 计数——后者在轮转 truncate 后仍报 0(尾窗满),会漏计整代。
                 const fgDropped = spoolRemoved.out + spoolRemoved.err;
                 const shellId = this.adoptRunningExecSpool(child, spool, { out: 0, err: 0 }, fgDropped);
                 if (shellId === undefined)
-                    return;
-                handedOver = true;
+                    return; // 拒收(limit/无 pid)→ 继续 fg,泵照跑,close 正常 settle
+                handedOver = true; // spool 文件归 bg(dispose 面按 FILE 形清理)
+                // cut-kill registry 注销(所有权已移交 bgManager;pipe 径同位)。
                 try {
                     options?.onDetachAdopted?.();
                 }
-                catch { }
+                catch { /* noop */ }
                 const o = outBuf.result();
                 const e = errBuf.result();
                 finish(ok({ stdout: markTruncated(o.text, o.droppedBytes), stderr: markTruncated(e.text, e.droppedBytes), exitCode: 0, detached: { shellId } }));
@@ -740,6 +995,7 @@ export class RemoteHostExecutionEnv {
                 const exitCode = code ?? (signal ? 128 + (signalNumber(signal) ?? 0) : 1);
                 finish(ok({ stdout: markTruncated(o.text, o.droppedBytes), stderr: markTruncated(e.text, e.droppedBytes), exitCode }));
             };
+            // ('error' 监听已在 spawn 后立即装——七轮复审:F5 提前 return 前必须有监听,防 uncaught)
             child.on("close", (code, signal) => {
                 if (drainTimer) {
                     clearTimeout(drainTimer);
@@ -748,12 +1004,18 @@ export class RemoteHostExecutionEnv {
                 settleFromTermination(code, signal);
             });
             child.on("exit", (code, signal) => {
+                // F4(二轮复审):exit **立即** latch——命令已 completed,此后 timeout/abort/detach 全 no-op(否则
+                // close 延迟/缺席时,drain 窗内的 timeout 会 killTree 连坐幸存孙进程;一轮修漏了这行赋值)。
                 exited = true;
+                // [1116] 病理根除点:exit=子 shell 已终——孙进程(nohup 服务)可以继续持有 spool 文件 fd(写文件
+                // 不牵连本 exec 的 settle),500ms drain 后兜底 settle;close 先来则上面清掉本 timer 直接 settle。
                 drainTimer = setTimeout(() => settleFromTermination(code, signal), EXIT_SETTLE_DRAIN_MS);
                 drainTimer.unref?.();
             });
         });
     }
+    /** [1116] spool 形 detach adoption:spool 路径+fg 游标直接进 HostBgState 的 FILE 面(launch 同形,poll
+     *  共码);同一文件单一字节流=天然无 decoder 接缝(mem-tee 版为此专门修过的病在此结构性不存在)。 */
     adoptRunningExecSpool(child, spool, cursors, fgRemovedBytes = 0) {
         const pid = child.pid;
         if (pid == null)
@@ -774,12 +1036,16 @@ export class RemoteHostExecutionEnv {
         });
         return adopted?.shellId;
     }
+    // ─────────────────────────────── streaming exec ───────────────────────────────
     async *execStream(command, options) {
         const ready = await this.shellReady();
         if (!ready.ok)
             throw new RemoteExecutionError("connect_failed", ready.error.message, ready.error);
         const cwd = this.resolve(options?.cwd ?? this.cwd);
         const timeoutMs = options?.timeout != null ? options.timeout * 1000 : undefined;
+        // Liveness is opt-in here (unlike e2b's default-on idle cap). Deliberate divergence:
+        // host runs on the operator's own machine — no provider-unreachability hang class — and a missing
+        // readTimeoutMs means the caller's own AbortSignal is the abort path. So no default wall-clock cap.
         const idleMs = options?.readTimeoutMs;
         const cap = options?.maxOutputBytes;
         const queue = [];
@@ -790,7 +1056,7 @@ export class RemoteHostExecutionEnv {
         let lastChunk = Date.now();
         let wake;
         const signalReady = () => { const w = wake; wake = undefined; w?.(); };
-        const sh = hostShell();
+        const sh = hostShell(); // Windows S1/S3: platform-resolved shell + group options (POSIX byte-identical)
         const child = spawn(sh.shell, [...sh.args, command], { cwd, env: this.mergeEnv(options?.env), ...spawnGroupOptions() });
         let pipeDestroyTimer;
         const kill = () => {
@@ -802,8 +1068,12 @@ export class RemoteHostExecutionEnv {
                 try {
                     child.kill("SIGKILL");
                 }
-                catch { }
+                catch { /* noop */ }
             }
+            // S2b: same D5 pipe-destroy grace the buffered exec has — a kill-escaping process (POSIX
+            // re-parented grandchild; win32 taskkill out-of-tree escapee) holding our pipes means `close` never
+            // fires and the stream hangs on its own idle/abort path forever. Force-free the FDs after the grace so
+            // the generator's close-driven finish always arrives. Idempotent (one timer; cleared on close).
             pipeDestroyTimer ??= armPipeDestroyGrace(child);
         };
         const enqueue = (type, data) => {
@@ -825,7 +1095,7 @@ export class RemoteHostExecutionEnv {
         });
         child.on("close", (code, signal) => {
             if (pipeDestroyTimer)
-                clearTimeout(pipeDestroyTimer);
+                clearTimeout(pipeDestroyTimer); // pipes closed naturally → the S2b grace is moot
             if (finished)
                 return;
             exitCode = code ?? (signal ? 128 + (signalNumber(signal) ?? 0) : 1);
@@ -846,6 +1116,7 @@ export class RemoteHostExecutionEnv {
             else
                 options.signal.addEventListener("abort", onAbort, { once: true });
         }
+        // Optional total wall-clock cap (host: only when the caller asks).
         const wallTimer = timeoutMs != null
             ? setTimeout(() => {
                 if (finished)
@@ -872,6 +1143,7 @@ export class RemoteHostExecutionEnv {
                     throw failure;
                 if (finished)
                     break;
+                // idle/liveness bound: no chunk within readTimeoutMs → typed timeout (a hung command).
                 const waitMs = idleMs != null ? Math.max(1, idleMs - (Date.now() - lastChunk)) : 30_000;
                 await new Promise((r) => { wake = r; setTimeout(r, waitMs); });
                 if (idleMs != null && !finished && Date.now() - lastChunk >= idleMs) {
@@ -890,12 +1162,13 @@ export class RemoteHostExecutionEnv {
             if (!finished) {
                 finished = true;
                 kill();
-            }
+            } // consumer abandoned early → don't leak the child
             if (wallTimer)
                 clearTimeout(wallTimer);
             options?.signal?.removeEventListener("abort", onAbort);
         }
     }
+    // ─────────────────────────────── FileSystem ───────────────────────────────
     async absolutePath(p) {
         return ok(this.resolve(p));
     }
@@ -944,6 +1217,7 @@ export class RemoteHostExecutionEnv {
             return ready;
         const abs = this.resolve(p);
         try {
+            // Create parent dirs automatically (parity with the E2B adapter).
             await fs.mkdir(path.dirname(abs), { recursive: true });
             const data = typeof content === "string" ? content : Buffer.from(content);
             await fs.writeFile(abs, data, { signal: abortSignal });
@@ -954,6 +1228,9 @@ export class RemoteHostExecutionEnv {
         }
     }
     async appendFile(p, content, abortSignal) {
+        // `lingeringBgWrite`:destroy 之后**仍在册**的后台 shell 还要把输出镜像到文件 —— 见 fsReady 旁注。
+        // 只有 append 开这个口:core 的后台输出镜像唯一走 `env.appendFile(handle.outputFile, …)`,别的文件动作
+        // 在 destroy 之后没有正当理由(读面留给下一轮的新 env)。
         const ready = await this.fsReady(p, { lingeringBgWrite: true });
         if (!ready.ok)
             return ready;
@@ -976,7 +1253,7 @@ export class RemoteHostExecutionEnv {
             return ready;
         const abs = this.resolve(p);
         try {
-            const st = await fs.lstat(abs);
+            const st = await fs.lstat(abs); // no follow (FileInfo contract)
             return ok({
                 name: path.basename(abs),
                 path: abs,
@@ -1007,6 +1284,7 @@ export class RemoteHostExecutionEnv {
                     mtimeMs = st.mtimeMs;
                 }
                 catch {
+                    /* a child that vanished between readdir and lstat → keep kind from Dirent, size/mtime 0 */
                 }
                 out.push({ name: e.name, path: child, kind: kindFromDirent(e), size, mtimeMs });
             }
@@ -1017,6 +1295,10 @@ export class RemoteHostExecutionEnv {
         }
     }
     async canonicalPath(p, abortSignal) {
+        // 🔴 只读面也过 fsReady(2026-07-25 统一):`exists`/`canonicalPath`/`readLink` 此前**不查** destroyed,
+        // 于是拆除之后「exists 答 true、紧接着 readTextFile 答 already destroyed」这一对自相矛盾 —— 调用方按
+        // exists 的结果去读就撞一个措辞完全不同的错。同批把 adb 腿的读面也补上了门(它此前连 connected 都不查),
+        // 这里是同一件事:**同族一致性**。只读探测本身无害,但"有害/无害"不该是各方法自行其是的判断。
         const ready = await this.fsReady(p);
         if (!ready.ok)
             return ready;
@@ -1029,6 +1311,10 @@ export class RemoteHostExecutionEnv {
         }
     }
     async readLink(p, abortSignal) {
+        // 🔴 只读面也过 fsReady(2026-07-25 统一):`exists`/`canonicalPath`/`readLink` 此前**不查** destroyed,
+        // 于是拆除之后「exists 答 true、紧接着 readTextFile 答 already destroyed」这一对自相矛盾 —— 调用方按
+        // exists 的结果去读就撞一个措辞完全不同的错。同批把 adb 腿的读面也补上了门(它此前连 connected 都不查),
+        // 这里是同一件事:**同族一致性**。只读探测本身无害,但"有害/无害"不该是各方法自行其是的判断。
         const ready = await this.fsReady(p);
         if (!ready.ok)
             return ready;
@@ -1041,6 +1327,10 @@ export class RemoteHostExecutionEnv {
         }
     }
     async exists(p, abortSignal) {
+        // 🔴 只读面也过 fsReady(2026-07-25 统一):`exists`/`canonicalPath`/`readLink` 此前**不查** destroyed,
+        // 于是拆除之后「exists 答 true、紧接着 readTextFile 答 already destroyed」这一对自相矛盾 —— 调用方按
+        // exists 的结果去读就撞一个措辞完全不同的错。同批把 adb 腿的读面也补上了门(它此前连 connected 都不查),
+        // 这里是同一件事:**同族一致性**。只读探测本身无害,但"有害/无害"不该是各方法自行其是的判断。
         const ready = await this.fsReady(p);
         if (!ready.ok)
             return ready;
@@ -1052,7 +1342,7 @@ export class RemoteHostExecutionEnv {
         catch (e) {
             const fe = this.fileError(e, abs, 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 };
         }
     }
@@ -1070,12 +1360,13 @@ export class RemoteHostExecutionEnv {
         }
     }
     async remove(p, options) {
-        const ready = await this.fsReady(p);
+        const ready = await this.fsReady(p); // mutation: fail closed after destroy() — parity with writeFile/createDir + e2b/ssh
         if (!ready.ok)
             return ready;
         const abs = this.resolve(p);
         try {
             if (!options?.force) {
+                // Surface a missing path as not_found (fs.rm with force:false already throws ENOENT, but be explicit).
                 await fs.lstat(abs);
             }
             await fs.rm(abs, { recursive: options?.recursive ?? false, force: options?.force ?? false });
@@ -1088,6 +1379,18 @@ export class RemoteHostExecutionEnv {
             return { ok: false, error: fe };
         }
     }
+    /** 🔴 临时文件/目录**不放进 workspace**(2026-07-25 修)。
+     *  原来两者都建在 `this.workspaceDir` 下,而 **TOC/CC 形的 workspaceDir 就是用户自己的目录**,且 `destroy()`
+     *  明文永不删它 ⇒ core 给**每个**后台 bash 都调一次 `createTempFile({prefix:"bash-task-", suffix:".output"})`
+     *  ⇒ 用户仓库根目录按后台任务数累积 `bash-task-<hex>.output`(内容=命令输出)+ 每次 `createTempDir` 一个
+     *  `tmp-XXXXXX/`,**永久**留在他们的 git 树里。两条独立判据说明这是偏差不是设计:①core 自己的 TOC 参照实现
+     *  `NodeExecutionEnv.createTempFile` 放的是 `os.tmpdir()`;②**本适配器早就为了同一个理由把 spool 根搬去了
+     *  tmpdir**([1116] 五轮复审明写"不再弄脏 user-owned workspace"),只是 createTempFile/Dir 没跟上。
+     *  改用本 env 自己的 tmp 根(`ensureSpoolRoot()`,已在 `os.tmpdir()` 下):
+     *   · 用户目录不再被写入;
+     *   · 镜像写仍然可用 —— `isLingeringMirrorTarget` 同批放行这个根(见那里的旁注);
+     *   · ephemeral 形反而更好:`destroy()` 在**有后台 shell 在册**时不删这个根,而 workspace 是会被 rm 的。
+     *  ⚠️ 这是 **host-only**:k8s/local-docker 的临时文件必须落在**容器内**可见的 cwd,ssh/e2b 本来就用远端系统 tmp。 */
     async createTempDir(prefix = "tmp-", abortSignal) {
         const ready = await this.fsReady(".");
         if (!ready.ok)
@@ -1107,23 +1410,29 @@ export class RemoteHostExecutionEnv {
         const suffix = options?.suffix ?? "";
         try {
             const name = `${prefix}${randomBytes(8).toString("hex")}${suffix}`;
-            const abs = path.join(this.ensureSpoolRoot(), name);
+            const abs = path.join(this.ensureSpoolRoot(), name); // 见 createTempDir 上方旁注:不放进用户的 workspace
             if (options?.abortSignal?.aborted)
                 throw Object.assign(new Error("aborted"), { name: "AbortError" });
-            await fs.writeFile(abs, "", { flag: "wx" });
+            await fs.writeFile(abs, "", { flag: "wx" }); // wx = fail if exists (random → won't)
             return ok(abs);
         }
         catch (e) {
             return { ok: false, error: this.fileError(e, this.workspaceDir, options?.abortSignal) };
         }
     }
+    // ─────────────────────────────── internals ───────────────────────────────
+    /** Resolve a (possibly relative) path against {@link cwd} like the other adapters. Host paths are platform-native. */
     resolve(p) {
         return path.isAbsolute(p) ? path.normalize(p) : path.normalize(path.resolve(this.cwd, p));
     }
+    /** Lazily create the per-task workspace exactly once (memoized; concurrent first-use shares it). */
     ensurePrepared() {
         if (this.prepared)
             return Promise.resolve();
         if (!this.preparing) {
+            // Reset the memo on rejection so a later call can re-attempt after a transient mkdir
+            // failure (ENOSPC / racy EACCES / rm race) — mirrors e2b's reset-on-failed-provision.
+            // Re-throw (don't swallow) so shellReady/fsReady/connect still surface the original error.
             this.preparing = fs
                 .mkdir(this.workspaceDir, { recursive: true })
                 .then(() => {
@@ -1140,6 +1449,11 @@ export class RemoteHostExecutionEnv {
         if (this.destroyed)
             return { ok: false, error: new ExecutionError("shell_unavailable", "execution env already destroyed") };
         try {
+            // Windows S1 (design D1): resolve the host shell ONCE (POSIX = /bin/sh, sync constant; win32 = Git Bash
+            // via core getShellConfig, fail-loud when absent). Every spawn site is behind this gate, so the sync
+            // `hostShell()` reads below are always post-resolution. A missing Git Bash surfaces as its own
+            // shell_unavailable error with the install hint — never a silent cmd fallback, never mislabeled as a
+            // workspace failure.
             try {
                 await resolveHostShell();
             }
@@ -1153,10 +1467,48 @@ export class RemoteHostExecutionEnv {
             return { ok: false, error: new ExecutionError("shell_unavailable", `failed to create host workspace: ${errMsg(e)}`, asError(e)) };
         }
     }
+    /**
+     * @param opts.lingeringBgWrite 只由 {@link appendFile} 传 true —— 允许「destroy 之后、仍在册的后台 shell
+     *   的输出镜像写」。
+     *
+     * 🔴 为什么需要这个口(2026-07-25,cli dogfood 报的现象追出来的真因):`destroy()` 无条件置
+     * `destroyed = true`,于是文件面**全拒**;而 `pollBackground` 直通 bgManager、**没有** destroyed 门。
+     * 这与本适配器自己遵守的 core 契约(1.258.2「destroy 不得收割后台进程」,上方 destroy() 里也为
+     * 「dispose 前仍可轮询」的残余刻意保留了 spool 根)直接打架:我们**刻意**让后台 shell 跨 destroy 存活并
+     * 继续被轮询,却拒掉它们要写的那个文件 ⇒ core 的 `appendFile` 一失败即置 `spool.mirrorFailed`,用户在一个
+     * 其实成功的后台任务上看到「[!] The output file is INCOMPLETE」。已用真子进程执行验证过这个不对称。
+     *
+     * 放行判据刻意收紧到三条同时成立,少一条都拒:
+     *  ① `persistent` —— 只有 TOC/CC 形(构造时给了 `workspaceDir` = 用户自己的目录)。那一形 destroy() 明文
+     *     「NEVER rm -rf it」,什么都没删,文件确实还在,core 还告诉用户「Read it any time」⇒ 报 INCOMPLETE 是谎。
+     *     **ephemeral 形不放行**:它的 destroy() 真的 rm -rf 了 workspace,而 `createTempFile` 恰把 outputFile
+     *     建在 workspace 里 ⇒ 镜像目标已被删,拒写是**诚实**的;放行反而会让 appendFile 的 mkdir -p 把一个已拆除
+     *     的工作目录**复活**成孤儿目录。
+     *  ② 还有后台 shell **在册** —— 判据与 destroy() 里"跳过删 spool 根"用的是同一个 `hasShells()`,即
+     *     「还有人在读写这些文件」这一个事实,不是两套规则。没有 shell 在册时 `destroyed` 照旧是硬护栏。
+     *  ③ 只对 append 一个动作开 —— 不是把整个文件面在 destroy 之后重新开门。
+     * 用 `this._bgManager?.` 而不是惰性 getter:拆除路径上不该顺手 **新建** 一个 manager。
+     */
+    /** destroy 后「残余镜像写」的**路径**判据 —— 与方法判据(`lingeringBgWrite`)并列,两者都满足才放行。
+     *
+     *  🔴 为什么需要它(深挖第一轮打在我自己头上的一条,2026-07-25):我原先的放行只看方法标志,于是 destroy 之后
+     *  `appendFile` 能**新建**文件、`mkdir -p` 建整棵树、甚至写 workspace **之外**的绝对路径 —— 而我在 fsReady
+     *  头注里写的是「别的文件动作在 destroy 之后没有正当理由」。探针实测把这个不一致钉了出来:说是"窄",在路径
+     *  维度上一点都不窄。
+     *
+     *  收紧到恰好贴合唯一的正当调用方(core 的后台输出镜像):
+     *   ① 目标必须在 **workspace 之内**(`createTempFile` 就把 outputFile 建在这儿)—— 挡住"写到工作区外面";
+     *   ② 目标**必须已经存在** —— 镜像写的文件是 destroy **之前**建好的,所以"新建"从来不是这条路的需求;
+     *      这一条同时挡掉 `mkdir -p` 建新目录树的副作用。
+     *  同步 `existsSync` 而不是 await:这是拆除路径上的判据,不该再引入一次异步让出。 */
     isLingeringMirrorTarget(p) {
         const abs = this.resolve(p);
         if (!existsSync(abs))
-            return false;
+            return false; // 必须是既存文件(镜像目标在 destroy 前就已建好)
+        // 🔴 必须在**同一路径空间**里比 containment:core 传进来的是 `canonicalPath()` 的产物(realpath),
+        // 而 `workspaceDir` 是构造时给的原样串 —— macOS 上 `/var/...` 与 `/private/var/...` 是同一目录的两种写法,
+        // 直接 `path.relative` 会把合法目标判成"在 workspace 之外"。(这条是我自己的行为面测试当场按住的:
+        // 收紧判据的第一版让 `host-env-bg-mirror-after-destroy` 立刻红。)两侧都过 realpath 再比。
         const real = (x) => { try {
             return realpathSync(x);
         }
@@ -1167,13 +1519,23 @@ export class RemoteHostExecutionEnv {
             const rel = path.relative(real(root), real(abs));
             return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
         };
+        // workspace **或**本 env 自己的 tmp 根:后者是 `createTempFile` 现在的落点(同批把临时文件搬出用户目录,
+        // 见 createTempDir 上方旁注)。两个根都是"本 env 自有"的面,放行它们不会让残余写触及无关路径。
+        // 用 `this.spoolRootDir` 而不是 `ensureSpoolRoot()`:拆除路径上不该顺手**新建**一个 tmp 根。
         return inside(this.workspaceDir) || (this.spoolRootDir !== undefined && inside(this.spoolRootDir));
     }
     async fsReady(p, opts) {
         if (this.destroyed) {
+            // 🔴 判据从三条收成两条 +路径判据(2026-07-25 同批):原先还要求 `this.persistent`,理由是
+            // 「ephemeral 形的 workspace 会被 rm,放行会让 mkdir -p **复活**一个已拆除的目录」。同批把临时文件搬到本 env
+            // 的 tmp 根之后,那个理由**已被 `isLingeringMirrorTarget` 里的 `existsSync` 覆盖**:workspace 被删 ⇒ 目标不
+            // 存在 ⇒ 自然拒;而"必须是既存文件"也让 mkdir -p 无从复活任何东西。继续要求 `persistent` 只会挡住
+            // ephemeral 形**本该成功**的镜像写(目标在 tmp 根、destroy 在有 shell 在册时不删它)。
             const lingering = opts?.lingeringBgWrite === true && this._bgManager?.hasShells() === true && this.isLingeringMirrorTarget(p);
             if (!lingering)
                 return { ok: false, error: new FileError("unknown", "execution env already destroyed", this.resolve(p)) };
+            // 放行:不再走 ensurePrepared() —— destroy 已清空 preparing memo,而 persistent 形的目录本来就是用户的、
+            // 必然存在(后台 shell 正在里面跑),且 appendFile 自己还会 mkdir -p 父目录。
             return ok(undefined);
         }
         try {
@@ -1184,6 +1546,10 @@ export class RemoteHostExecutionEnv {
             return { ok: false, error: new FileError("unknown", `failed to create host workspace: ${errMsg(e)}`, this.resolve(p), asError(e)) };
         }
     }
+    /** Base env (process.env when inheriting) merged with the adapter's secret env, then per-command overrides win. */
+    /** D1 secure default = `"scrub"`: inherit `process.env` minus secret-pattern keys (core's `scrubSecretEnv`, single
+     *  source of truth). `"all"` = full inherit (opt-out); a `string[]` = strict allowlist. Legacy `inheritProcessEnv`
+     *  maps `true`→`"all"` / `false`→`[]`. */
     inheritMode() {
         if (this.cfg.inheritEnv !== undefined)
             return this.cfg.inheritEnv;
@@ -1205,11 +1571,16 @@ export class RemoteHostExecutionEnv {
                     base[k] = process.env[k];
         }
         else
-            base = scrubSecretEnv(process.env);
+            base = scrubSecretEnv(process.env); // "scrub" — core's first-party D1 secret-env filter
         if (this.cfg.env)
-            Object.assign(base, this.cfg.env);
+            Object.assign(base, this.cfg.env); // caller-supplied (control-plane secrets) verbatim
         if (perCommand)
-            Object.assign(base, perCommand);
+            Object.assign(base, perCommand); // per-call wins
+        // Windows S2b (design D1): win32 env keys are case-insensitive — a case-sensitive merge that
+        // produced BOTH `Path` (inherited) and `PATH` (override) reaches CreateProcess as one-undefined-which.
+        // Pin SHELL to the resolved Git Bash (subshell scripts read $SHELL) BEFORE the collapse (so an inherited
+        // case-variant `Shell` folds into one entry), then collapse case-duplicates (later = higher-precedence
+        // value, first-seen = native casing). POSIX: both are identity/no-ops — byte-identical.
         if (process.platform === "win32")
             base.SHELL = hostShell().shell;
         return collapseWin32EnvKeys(base);
@@ -1235,6 +1606,7 @@ export class RemoteHostExecutionEnv {
         return new FileError("unknown", msg, p);
     }
 }
+/** Strip anything but [A-Za-z0-9._-] from an id so it is safe in a directory name. */
 function sanitizeId(id) {
     return id.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 64) || "task";
 }
@@ -1251,16 +1623,42 @@ function errMsg(e) {
 function asError(e) {
     return e instanceof Error ? e : undefined;
 }
+/** Conventional exit code for a process killed by a signal (128 + signal number); falls back to undefined.
+ *  Uses Node's authoritative platform table (`os.constants.signals`) — a hand-written table missed SIGABRT/SIGPIPE
+ *  (`kill -ABRT` reported 137 instead of 134, impersonating SIGKILL). Callers keep the `?? 9`
+ *  fallback for a name the platform doesn't define, matching core's `SIGNUM[signal] ?? 9`. */
 function signalNumber(signal) {
     return os.constants.signals[signal];
 }
+/**
+ * `ExecutionEnvFactory` for the TOC `host` backend (DUAL-MODE-DESIGN §5). Wiring this onto a deployment makes
+ * its agent run DIRECTLY on the worker's machine (no container) — the local-coding-agent default. One fresh
+ * env per task; the Runner owns the lifetime and calls `destroy()` (= `rm -rf` the workspace) on task end.
+ *
+ * Mirrors `e2bExecutionEnvFactory`: returns the env **unconnected** (lazy) and folds the per-task
+ * `ctx.sessionId` into the workspace dir id so two concurrent tasks never share a working directory.
+ */
 export function hostExecutionEnvFactory(config = {}) {
     return (ctx) => new RemoteHostExecutionEnv({
         ...config,
         id: config.id ?? ctx.taskId ?? ctx.sessionId,
     });
 }
+// ─────────────────────────────── remoteExec superset: docker providers ───────────────────────────────
+//
+// DUAL-MODE-DESIGN §5 defines a `remoteExec.provider` superset. `host` (above) is implemented; `local-docker`
+// is NOW IMPLEMENTED (the isolation lane) — it lives in its own module (remote-env-local-docker.ts) and is
+// re-exported here so the discriminator entry point + the historical import site stay stable. `remote-docker`
+// (a REMOTE docker daemon over TLS/SSH) is still an explicit fast-follow stub — it throws a clear "not yet
+// implemented" so selecting it fails loud at wiring time instead of silently degrading isolation. NOT faked green.
+// `local-docker` (the isolation lane): real implementation moved to remote-env-local-docker.ts. Re-export the
+// factory + config from here so existing wiring (`import { localDockerExecutionEnvFactory } from "./remote-env-host"`)
+// keeps working and the provider discriminator has one canonical entry point.
 export { localDockerExecutionEnvFactory, RemoteLocalDockerExecutionEnv } from "./remote-env-local-docker.js";
+/**
+ * `remote-docker` factory entry point — wired but an explicit TODO (DUAL-MODE-DESIGN §5 fast-follow). Throws
+ * at factory-BUILD time so selecting it before it exists fails loud rather than degrading isolation silently.
+ */
 export function remoteDockerExecutionEnvFactory(_config) {
     throw new RemoteExecutionError("unsupported", "remoteExec provider 'remote-docker' is not yet implemented (DUAL-MODE-DESIGN §5 fast-follow) — use 'host', 'local-docker', or 'e2b' until it ships");
 }