@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/posix-shell-fs.js

@@ -1,23 +1,3 @@
-/**
- * design/158 B6 —— POSIX shell-out 族的共享文件面基座。
- *
- * 服务对象 = {k8s, ssh, adb, local-docker} 四条「发一条 shell 命令 + 分类 stderr」的腿(lens3 C2 实测
- * 42–69% 同构)。**host(node:fs)与 e2b(SDK)是原生 API 腿,不并**(13–27% 是假共性,强行合并会造出
- * 一个假基座)。ssh 的 fileInfo/listDir 走 SFTP 原生,只接入本基座的 shell-out 子集。
- *
- * 五条裁决(B6-posix-shell-fs.md,test/posix-shell-fs.test.ts 逐条钉):
- *  R1 所有 path 实参前带 `--`(ssh 形):resolve() 先绝对化让风险只剩纵深,但**基座不依赖调用侧不变量**。
- *  R2 错误分类走 `classifyFsStderr`(k8s 形:分类 + 硬失败/命令缺失护栏 + 站点显式 fallback)。
- *  R3 listDir 用 `ls -1A`(adb 此前 `-1` 丢 dotfiles —— agent 场景 .env/.gitignore 是一等公民)。
- *  R4 createTempFile 后缀=尾-X 模板 + `mv`(纯 POSIX;GNU `--suffix` 在 BSD/macOS 远端直接失败;
- *     模板尾-X 约束的复发面见 adb 2026-07-25 修案)。
- *  R5 temp 位置参数化(workspace 腿 `-p <dir>`,ssh `-t`)—— 语义差异,不判正形。
- *
- * readLink 契约(逐字承各腿原注):必须返回**原始链接目标**(`readlink` 不带 `-f`),core 拿到后自己拼
- * 相对目标并走带跳数上限的循环;链接目标含换行是病态形,按 trim 处理,不假装支持。
- * statFileInfo 契约:**lstat 语义**(`stat` 不带 `-L`,不跟链)—— symlink 自身可被 fileInfo 判出,
- * core 的敏感路径/写门靠这个(exists→canonicalPath 失败→fileInfo 判 symlink→readLink)。
- */
 import path from "node:path";
 import { FileError, } from "@sema-agent/core";
 import { shellQuote, kindFromMode } from "./remote-shell.js";
@@ -53,7 +33,6 @@ export function createPosixShellFs(deps) {
         },
         async statFileInfo(p, abortSignal) {
             const abs = resolve(p);
-            // %s size / %Y mtime(epoch s)/ %f raw hex mode —— GNU、busybox、toybox 三家一致;无 `-L` = lstat。
             const r = await run(`stat -c '%s %Y %f' -- ${shellQuote(abs)}`, abortSignal);
             if (!r.ok)
                 return { ok: false, error: fileErrorFromExec(r.error, abs) };
@@ -79,7 +58,6 @@ export function createPosixShellFs(deps) {
             const out = [];
             for (const name of names) {
                 const info = await fs.statFileInfo(path.posix.join(abs, name), abortSignal);
-                // 竞态容忍(承各腿原形):条目在 ls 与 stat 之间消失/不可读时降级为占位行,不让整个列表失败。
                 if (info.ok)
                     out.push(info.value);
                 else
@@ -89,11 +67,6 @@ export function createPosixShellFs(deps) {
         },
         async exists(p, abortSignal) {
             const abs = resolve(p);
-            // R6(k8s 形=正形,原注全额承接):`[ -e ]` 经 stdout 答 yes/no —— 不依赖 stderr(鲁棒于 fast-exit
-            // 下 stderr 被截断的竞态),单往返。`|| [ -L ]` 是 2026-07-25 补的跨腿分叉:`[ -e ]` **跟随**符号链接,
-            // 悬空链接(`latest -> ./build-123` 未构建)会答 false,而 core 的 canonicalizeTarget 第一步就是
-            // exists —— 答 false ⇒ 走「目标不存在」分支,敏感路径门拿到的键是无害的链接名而非真目标(core 注释
-            // 点名要 fail-closed 防的绕过形)。`[ -e ] || [ -L ]` = lstat 语义,与 host 腿对齐。
             const r = await run(`{ [ -e ${shellQuote(abs)} ] || [ -L ${shellQuote(abs)} ]; } && printf yes || printf no`, abortSignal);
             if (!r.ok)
                 return { ok: false, error: fileErrorFromExec(r.error, abs) };
@@ -106,7 +79,6 @@ export function createPosixShellFs(deps) {
         },
         async createDir(p, options) {
             const abs = resolve(p);
-            // sftp/一次性 mkdir 都非递归 ⇒ 恒 `-p`(对已存在目录也幂等)——承 ssh/adb/k8s 原形。
             const r = await run(`mkdir -p -- ${shellQuote(abs)}`, options?.abortSignal);
             if (!r.ok)
                 return { ok: false, error: fileErrorFromExec(r.error, abs) };
@@ -122,7 +94,7 @@ export function createPosixShellFs(deps) {
                 return { ok: false, error: fileErrorFromExec(r.error, abs) };
             if (r.value.exitCode !== 0) {
                 if (options?.force && /no such file/i.test(r.value.stderr))
-                    return ok(undefined); // force = 幂等删除
+                    return ok(undefined);
                 return { ok: false, error: classifyFsStderr(r.value.stderr, abs, "unknown") };
             }
             return ok(undefined);
@@ -138,8 +110,6 @@ export function createPosixShellFs(deps) {
             const sfx = options?.suffix ?? "";
             const dir = deps.tempDir();
             const where = dir === null ? "-t" : `-p ${shellQuote(dir)}`;
-            // R4:`mktemp` 要求 X 在**末尾**,后缀不能折进模板(折进去产出的是一个带字面 XXXXXX 的文件名,
-            // 第二次调用同名撞车)。正解=合法尾-X 模板建(基名唯一),后缀 `mv` 上去 —— 目标名因基名唯一而唯一。
             const cmd = sfx
                 ? `f=$(mktemp ${where} ${shellQuote(`${prefix}XXXXXX`)}) && mv -- "$f" "$f"${shellQuote(sfx)} && printf '%s' "$f"${shellQuote(sfx)}`
                 : `mktemp ${where} ${shellQuote(`${prefix}XXXXXX`)}`;

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

@@ -1,29 +1,3 @@
-/**
- * `RemoteAdbExecutionEnv` — the ADB implementation of core's `RemoteExecutionEnv` seam (design/61). A PEER
- * adapter to SSH/E2B (NOT chained). Use case: an AI driving on-device APP testing over `adb` (a real phone /
- * emulator).
- *
- * 🔴 **An ADB target is a REAL device, not a disposable sandbox** (design/61 §5) — same posture as SSH:
- *  - `capabilities = { isolation: false, suspendable: false }` — actions are PERMANENT; the leader tightens
- *    autonomy + the design/37 gate + HITL run on a non-isolated env (design/53).
- *  - `destroy()` / `cleanup()` **`adb disconnect`** the (TCP) device — they do NOT wipe/reset the phone.
- *  - `suspendVM`/`resumeVM`/`postResumeInit` → typed `"unsupported"` (a physical device isn't snapshotable).
- *    `reconnect` re-runs `adb connect`.
- *
- * 🔴 **First-attach is flaky → retry** (design/61 §2A): a fresh `adb connect` / a device that is still
- * `unauthorized` (USB-debug prompt) or `offline` surfaces `auth_transient`, which `connect` retries via
- * `withRetry` (idempotent establishment only). A genuinely rejected device → `auth_failed` (permanent).
- *
- * 🔴 **Credentials / device identity** are control-plane config (the device `serial` / `host:port`), injected
- * to the ADAPTER — never the workspace (design/61 §5 #2).
- *
- * **APP install** is NOT a seam method: the agent pushes the APK with `writeFile` then runs `pm install` (or
- * `adb install` is reachable via the device's own shell) through `exec` — the ExecutionEnv stays generic.
- *
- * ⚠️ **Device-untested:** built mirroring the SSH adapter (which IS proven against a real host); no physical
- * device/emulator was available to integration-test the `adb` paths. The contracts are locked by unit tests;
- * the live `adb` round-trip needs a device run before production use.
- */
 import path from "node:path";
 import os from "node:os";
 import fs from "node:fs/promises";
@@ -40,8 +14,6 @@ const unsupported = (op) => ({
     error: new RemoteExecutionError("unsupported", `${op} is not supported on an ADB device (real hardware — not snapshotable; capabilities.suspendable=false)`),
 });
 const isTcp = (serial) => /:\d+$/.test(serial);
-/** [R78]#1: adb stderr markers that mean the DEVICE TRANSPORT died mid-op (not a normal command failure) —
- *  typed retryable (reconnect + retry per idempotency), never a fake command result. Exported for tests. */
 export function isAdbTransportLost(stderr) {
     return /device offline|device '.*' not found|no devices\/emulators found|connection reset|protocol fault|device disconnected/i.test(stderr);
 }
@@ -49,12 +21,6 @@ export class RemoteAdbExecutionEnv {
     capabilities = { isolation: false, suspendable: false };
     cwd;
     connected = false;
-    /** 🔴 拆除是**终态**(2026-07-25 补齐:此前本适配器是同族里唯一没有这个概念的一条腿)。
-     *  没有它的后果实测:`destroy()` 只清 `connected`,于是任何残留引用**一次 `connect()` 就把 env 整个复活**,
-     *  `exec` 又能在真设备上跑;而 `reconnect(sessionToken)` 就在同一个接缝上摆着。读面更松 —— 它连
-     *  `connected` 都不查,所以 destroy 之后 `readTextFile` 照样从真设备把文件读出来。
-     *  同姿态的 ssh 腿早有先例(`remote-env-ssh.ts`「destroy 后一律不复活,显式 connect/reconnect 同禁」),
-     *  五条兄弟腿全部 fail-closed,只有 adb 例外 —— 补齐它。 */
     destroyed = false;
     cfg;
     spawnFn;
@@ -78,14 +44,11 @@ export class RemoteAdbExecutionEnv {
     workspaceHandle() {
         return { sandboxId: this.cfg.serial, provider: PROVIDER, mountPath: this.cwd };
     }
-    // ─────────────────────────────── lifecycle ───────────────────────────────
     async connect(config) {
-        // 拆除后一律不复活(显式 connect / reconnect 同禁)—— 与 ssh 腿逐字同口径:被拆除的 env 是 teardown
-        // 的产物,重连它等于把已释放的真实设备重新挂上,而那时已经没有谁负责再断开它。要新连接就建新 env。
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "ADB env destroyed — create a fresh env instead of reviving") };
         const policy = {
-            retryableCodes: ["auth_transient", "connect_failed", "timeout"], // first-attach flakiness; NOT auth_failed
+            retryableCodes: ["auth_transient", "connect_failed", "timeout"],
             maxAttempts: this.cfg.retry.maxAttempts,
             backoffMs: (failed) => this.cfg.retry.backoffMs * failed,
         };
@@ -105,7 +68,6 @@ export class RemoteAdbExecutionEnv {
             if (/cannot connect|connection refused|no route/.test(out))
                 return { ok: false, error: new RemoteExecutionError("connect_failed", c.value.stdout.trim()) };
         }
-        // Confirm the device is actually usable (not unauthorized/offline) before declaring connected.
         const st = await this.adb(["-s", this.cfg.serial, "get-state"], { signal, timeoutMs: this.cfg.commandTimeoutMs });
         if (!st.ok)
             return { ok: false, error: new RemoteExecutionError("connect_failed", `adb get-state failed: ${st.error.message}`, st.error) };
@@ -135,23 +97,19 @@ export class RemoteAdbExecutionEnv {
         this.connected = false;
         return this.connect();
     }
-    /** `adb disconnect` the TCP device (USB: just drop our flag). Does NOT reset the phone — idempotent, never throws. */
     async destroy() {
         if (isTcp(this.cfg.serial))
             await this.adb(["disconnect", this.cfg.serial], { timeoutMs: 10_000 }).catch(() => { });
         this.connected = false;
-        this.destroyed = true; // 终态(见字段旁注):此后 connect/reconnect 与整个文件面一律 fail-closed
+        this.destroyed = true;
     }
     async cleanup() {
         return this.destroy();
     }
-    // ─────────────────────────────── exec ───────────────────────────────
     async exec(command, options) {
         if (!this.connected)
             return { ok: false, error: new ExecutionError("shell_unavailable", "ADB device not connected — call connect() first") };
         const wrapped = this.withCwdEnv(command, options?.cwd, options?.env);
-        // exec-out (shell protocol v2, NO pty): clean separated stdout/stderr + a real exit code. `adb shell` allocates
-        // a pty that merges stderr into stdout and does CRLF translation — wrong for capture/streaming (council §9.2).
         const r = await this.adb(["-s", this.cfg.serial, "exec-out", wrapped], {
             signal: options?.abortSignal,
             timeoutMs: options?.timeout != null ? options.timeout * 1000 : this.cfg.commandTimeoutMs,
@@ -160,10 +118,8 @@ export class RemoteAdbExecutionEnv {
         });
         if (!r.ok)
             return { ok: false, error: r.error };
-        // A device-transport drop mid-op is NOT a command result — typed "transport_lost" since core 1.89
-        // (outcome UNKNOWN — reconnect, then retry only per the op's idempotency).
         if (r.value.exitCode !== 0 && isAdbTransportLost(r.value.stderr)) {
-            this.connected = false; // dead transport — the next exec fails closed; reconnect() re-establishes
+            this.connected = false;
             return { ok: false, error: new ExecutionError("transport_lost", `adb transport lost mid-command: ${r.value.stderr.trim().slice(0, 200)} — reconnect + retry per idempotency`) };
         }
         return ok(r.value);
@@ -172,7 +128,7 @@ export class RemoteAdbExecutionEnv {
         if (!this.connected)
             throw new RemoteExecutionError("connect_failed", "ADB device not connected — call connect() first");
         const wrapped = this.withCwdEnv(command, options?.cwd, options?.env);
-        const child = this.spawnFn(this.cfg.adbPath, ["-s", this.cfg.serial, "exec-out", wrapped], { stdio: ["ignore", "pipe", "pipe"] }); // exec-out (no pty) — see exec()
+        const child = this.spawnFn(this.cfg.adbPath, ["-s", this.cfg.serial, "exec-out", wrapped], { stdio: ["ignore", "pipe", "pipe"] });
         const queue = [];
         let finished = false;
         let failure;
@@ -188,8 +144,6 @@ export class RemoteAdbExecutionEnv {
         let paused = false;
         let onAbort;
         const teardown = () => {
-            // every exit path (normal end, timeout/failure throw, consumer early-break via .return()): drop the abort
-            // listener (council #5) + kill the child if still running.
             if (onAbort) {
                 options?.signal?.removeEventListener("abort", onAbort);
                 onAbort = undefined;
@@ -199,7 +153,6 @@ export class RemoteAdbExecutionEnv {
                     child.kill("SIGKILL");
                 }
                 catch {
-                    /* noop */
                 }
             }
         };
@@ -219,12 +172,12 @@ export class RemoteAdbExecutionEnv {
             lastChunk = Date.now();
             queue.push(chunk);
             if (queue.length >= 512 && !paused) {
-                paused = true; // backpressure: bound queue growth on a fast producer / slow consumer (council design #1)
+                paused = true;
                 child.stdout.pause();
             }
             signalReady();
         };
-        let stderrTail = ""; // [R78]#1: watch for device-transport-drop markers (bounded tail, not the whole stream)
+        let stderrTail = "";
         child.stdout.on("data", (d) => enqueue({ type: "stdout", data: d.toString() }));
         child.stderr.on("data", (d) => {
             stderrTail = (stderrTail + d.toString()).slice(-512);
@@ -237,12 +190,9 @@ export class RemoteAdbExecutionEnv {
         });
         child.on("close", (code, signal) => {
             if ((code ?? 0) !== 0 && isAdbTransportLost(stderrTail) && !failure) {
-                // device transport died mid-stream — typed retryable, not a fake exit ([R78]#1)
                 this.connected = false;
                 failure = new RemoteExecutionError("transport_lost", `adb transport lost mid-stream: ${stderrTail.trim().slice(0, 200)}`);
             }
-            // code==null WITH a signal = the adb child was killed by an external signal (SIGKILL/OOM) — conventional
-            // 128+signo, NOT a fake success 0 ([R78]#2; the second `close` argument was dropped before this fix).
             exitCode = code ?? (signal ? 128 + (signalNumber(signal) ?? 9) : 0);
             finished = true;
             signalReady();
@@ -260,7 +210,6 @@ export class RemoteAdbExecutionEnv {
                 if (finished)
                     break;
                 const waitMs = idleMs ? 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) => {
@@ -284,15 +233,12 @@ export class RemoteAdbExecutionEnv {
             teardown();
         }
     }
-    // ─────────────────────────────── FileSystem (adb shell + push/exec-out) ───────────────────────────────
     async absolutePath(p) {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
         return ok(path.posix.join(...parts));
     }
-    /** 文件面的终态门 —— 读面此前**连 `connected` 都不查**,所以 destroy 之后还能从真设备读出文件内容。
-     *  与 host/local-docker/k8s/e2b 的姿态对齐(它们的文件面都在 destroy 后 fail-closed)。 */
     fsGate(p) {
         if (this.destroyed)
             return { ok: false, error: new FileError("unknown", "execution env already destroyed", this.resolve(p)) };
@@ -303,7 +249,6 @@ export class RemoteAdbExecutionEnv {
         if (gated)
             return gated;
         const abs = this.resolve(p);
-        // exec-out streams the file's raw bytes (binary-safe); stderr carries cat's error if any.
         const r = await this.adb(["-s", this.cfg.serial, "exec-out", `cat ${shellQuote(abs)}`], { signal: abortSignal, timeoutMs: this.cfg.dataTimeoutMs, binary: true });
         if (!r.ok)
             return { ok: false, error: fileErrorFromExec(r.error, abs) };
@@ -317,8 +262,6 @@ export class RemoteAdbExecutionEnv {
                 return { ok: false, error: new FileError("is_directory", errOut, abs) };
             return { ok: false, error: new FileError("unknown", errOut, abs) };
         }
-        // exec-out gives no exit code on the wire, but the adb transport itself can fail non-zero with empty stderr
-        // (device dropped mid-read) — don't mistake that for a legit empty file (council #6).
         if (r.value.exitCode !== 0)
             return { ok: false, error: new FileError("unknown", `adb exec-out cat exited ${r.value.exitCode}`, abs) };
         return ok(r.value.stdoutBytes ?? new Uint8Array(0));
@@ -343,16 +286,11 @@ export class RemoteAdbExecutionEnv {
         const dir = path.posix.dirname(abs);
         if (dir && dir !== "." && dir !== "/") {
             const mk = await this.exec(`mkdir -p ${shellQuote(dir)}`, { abortSignal });
-            // 🔴 `!mk.ok` 也必须 fail-closed(2026-07-25 补):原来只看 `exitCode !== 0`,于是 **exec 本身失败**
-            // (设备/连接在这一拍掉线 ⇒ `transport_lost` / `shell_unavailable`)被整条吞掉,后面照样推载荷,
-            // 而整个 `writeFile` 返回 **ok:true** —— 调用方看到的成功与真实故障点完全脱节。同族的
-            // local-docker / k8s 用的正是 `if (!mk.ok) return`,这两条腿是漏的。
             if (!mk.ok)
                 return { ok: false, error: fileErrorFromExec(mk.error, dir) };
             if (mk.value.exitCode !== 0)
                 return { ok: false, error: new FileError("unknown", mk.value.stderr.trim() || `mkdir -p failed for ${dir}`, dir) };
         }
-        // Stage to a local temp then `adb push` (binary-safe; avoids shell-escaping the payload).
         let local;
         try {
             local = path.join(os.tmpdir(), `adb-push-${Date.now()}-${Math.random().toString(36).slice(2)}`);
@@ -391,9 +329,6 @@ export class RemoteAdbExecutionEnv {
         merged.set(add, base.length);
         return this.writeFile(abs, merged, abortSignal);
     }
-    // ── design/158 B6:以下 POSIX shell-out 文件面全部委托共享基座(posix-shell-fs.ts)──────────────
-    // 五裁决(`--`/classifyFsStderr/ls -1A/mv 后缀形/temp 位置参数化)与 readLink・lstat 契约见基座头注;
-    // 委托钉在 test/posix-shell-fs.test.ts(腿内不再自拼 readlink/realpath 命令串)。
     posixFsInst;
     get posixFs() {
         return (this.posixFsInst ??= createPosixShellFs({
@@ -429,42 +364,27 @@ export class RemoteAdbExecutionEnv {
     async createTempFile(options) {
         return this.posixFs.createTempFile(options);
     }
-    // ─────────────────────────────── helpers ───────────────────────────────
-    /** Spawn the adb binary with the given args; collect stdout/stderr (+ raw bytes when binary), bound by timeout/abort. */
     adb(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.adbPath, 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 (`exec-out cat`, opts.binary=true,
-            // which MUST keep EVERY byte or binary/large reads silently corrupt). So we branch on opts.binary:
-            //  - 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)).
-            // 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 errBuf = new RollingTailBuffer(); // Buffer[]+concat replaced by rolling-tail — same O(n) push, bounded total
+            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);
             };
@@ -487,7 +407,7 @@ export class RemoteAdbExecutionEnv {
                     outBufs.push(d);
                 else
                     outTail.push(d);
-                opts?.onStdout?.(d.toString()); // streaming callback still gets the full chunk; only the buffered return is bounded
+                opts?.onStdout?.(d.toString());
             });
             child.stderr.on("data", (d) => {
                 errBuf.push(d);
@@ -496,15 +416,11 @@ export class RemoteAdbExecutionEnv {
             child.on("error", (e) => finish({ ok: false, error: new ExecutionError("spawn_error", `adb spawn failed (is '${this.cfg.adbPath}' installed?): ${e.message}`, e) }));
             child.on("close", (code, signal) => {
                 if (forceSettleTimer)
-                    clearTimeout(forceSettleTimer); // `close` fired → pipes closed naturally; clear D5 grace
+                    clearTimeout(forceSettleTimer);
                 const err = errBuf.result();
                 const stderr = markTruncated(err.text, err.droppedBytes);
-                // code==null WITH a signal = the adb child was killed by an external signal (SIGKILL/OOM) —
-                // conventional 128+signo, NOT a fake success 0 ([R78]#2; the second `close` argument was dropped
-                // before this fix).
                 const exitCode = code ?? (signal ? 128 + (signalNumber(signal) ?? 9) : 0);
                 if (binary) {
-                    // byte-exact: readBinaryFile decodes stdoutBytes; never truncate.
                     const stdoutBytes = Buffer.concat(outBufs);
                     finish(ok({ stdout: stdoutBytes.toString("utf8"), stderr, exitCode, stdoutBytes: new Uint8Array(stdoutBytes) }));
                 }
@@ -527,11 +443,6 @@ export class RemoteAdbExecutionEnv {
         return parts.join(" ");
     }
 }
-/**
- * `ExecutionEnvFactory` for the ADB backend — one fresh (unconnected) env per task against the same device
- * (lazy: `adb connect` on first use). Config (serial) is control-plane-supplied; the Runner owns the lifetime
- * and calls `destroy()` (= `adb disconnect`, never a device wipe) on task end.
- */
 export function adbExecutionEnvFactory(config) {
     return (_ctx) => new RemoteAdbExecutionEnv(config);
 }