@sema-agent/server 1.323.0 → 2.0.0

package/dist/plugins/pg-session-store.d.ts

@@ -1,2 +1,12 @@
+/**
+ * Compatibility re-export shim — the PG Session event-log center (L1).
+ *
+ * 🔴 SINGLE SOURCE OF TRUTH: the real PG twin (PgSessionStorage + PgSessionStore + PG_SESSION_SCHEMA +
+ * ensureSchema) lives in {@link ./pg-session-storage.ts}. This file previously carried a SECOND, byte-for-byte
+ * copy of that same code — a dual source of truth that would silently drift (a fix to one copy leaving the
+ * other stale, defeating the very twin/lock-step invariant the integration suite exists to protect). The
+ * duplicate has been collapsed: everything is now re-exported from the one storage module so there is exactly
+ * ONE PG implementation and the two integration suites both exercise it.
+ */
 export { PgSessionStorage, PgSessionStore, PG_SESSION_SCHEMA, ensureSchema, } from "./pg-session-storage.js";
 //# sourceMappingURL=pg-session-store.d.ts.map

package/dist/plugins/pg-session-store.js

@@ -1,2 +1,12 @@
+/**
+ * Compatibility re-export shim — the PG Session event-log center (L1).
+ *
+ * 🔴 SINGLE SOURCE OF TRUTH: the real PG twin (PgSessionStorage + PgSessionStore + PG_SESSION_SCHEMA +
+ * ensureSchema) lives in {@link ./pg-session-storage.ts}. This file previously carried a SECOND, byte-for-byte
+ * copy of that same code — a dual source of truth that would silently drift (a fix to one copy leaving the
+ * other stale, defeating the very twin/lock-step invariant the integration suite exists to protect). The
+ * duplicate has been collapsed: everything is now re-exported from the one storage module so there is exactly
+ * ONE PG implementation and the two integration suites both exercise it.
+ */
 export { PgSessionStorage, PgSessionStore, PG_SESSION_SCHEMA, ensureSchema, } from "./pg-session-storage.js";
 //# sourceMappingURL=pg-session-store.js.map

package/dist/plugins/pg-tool-result-store.d.ts

@@ -1,2 +1,9 @@
+/**
+ * PostgreSQL `ToolResultStore` — the implementation now lives in the single-file dual-dialect
+ * `tool-result-store-sql.ts` (design/158 A12 定型半场), the TiDB twin's sibling
+ * (src/plugins/tidb-tool-result-store.ts). This file is the historical import path: the class name, ctor
+ * shape, and the PG-only schema helpers (`PG_TOOL_RESULT_SCHEMA` / `ensureSchema`, consumed by pg-pool.ts's
+ * central schema apply) are re-exported unchanged, so every consumer and suite is untouched.
+ */
 export { PgToolResultStore, PG_TOOL_RESULT_SCHEMA, ensureSchema } from "./tool-result-store-sql.js";
 //# sourceMappingURL=pg-tool-result-store.d.ts.map

package/dist/plugins/pg-tool-result-store.js

@@ -1,2 +1,9 @@
+/**
+ * PostgreSQL `ToolResultStore` — the implementation now lives in the single-file dual-dialect
+ * `tool-result-store-sql.ts` (design/158 A12 定型半场), the TiDB twin's sibling
+ * (src/plugins/tidb-tool-result-store.ts). This file is the historical import path: the class name, ctor
+ * shape, and the PG-only schema helpers (`PG_TOOL_RESULT_SCHEMA` / `ensureSchema`, consumed by pg-pool.ts's
+ * central schema apply) are re-exported unchanged, so every consumer and suite is untouched.
+ */
 export { PgToolResultStore, PG_TOOL_RESULT_SCHEMA, ensureSchema } from "./tool-result-store-sql.js";
 //# sourceMappingURL=pg-tool-result-store.js.map

package/dist/plugins/pg-workflow-journal-store.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Thin re-export shim (design/158 A12 collapse). The real implementation is the single-file dual-dialect
+ * {@link import("./workflow-journal-store-sql.js").SqlWorkflowJournalStore} — see that file for the durable
+ * {@link WorkflowJournalStore} contract, the schema, and the TiDB/PG dialect-delta ledger. This name (and ctor
+ * arity: `(pool: PgPool)`) survives unchanged so every consumer (store-backend.ts, the extreme/integration/
+ * resume-fork-probe suites) is untouched.
+ */
 export { PgWorkflowJournalStore } from "./workflow-journal-store-sql.js";
 //# sourceMappingURL=pg-workflow-journal-store.d.ts.map

package/dist/plugins/pg-workflow-journal-store.js

@@ -1,2 +1,9 @@
+/**
+ * Thin re-export shim (design/158 A12 collapse). The real implementation is the single-file dual-dialect
+ * {@link import("./workflow-journal-store-sql.js").SqlWorkflowJournalStore} — see that file for the durable
+ * {@link WorkflowJournalStore} contract, the schema, and the TiDB/PG dialect-delta ledger. This name (and ctor
+ * arity: `(pool: PgPool)`) survives unchanged so every consumer (store-backend.ts, the extreme/integration/
+ * resume-fork-probe suites) is untouched.
+ */
 export { PgWorkflowJournalStore } from "./workflow-journal-store-sql.js";
 //# sourceMappingURL=pg-workflow-journal-store.js.map

package/dist/plugins/pg-workflow-run-store.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Thin re-export shim (design/158 A12 扇出): the PG `WorkflowRunStore`/`WorkflowCompletionInbox`/
+ * `WorkflowNotifyJournalStore` twins now live collapsed with their TiDB dialect siblings in the
+ * single-file dual-dialect `workflow-run-store-sql.ts` (design doc + dialect-delta ledger there).
+ * Class names and ctor arity stay EXACTLY as they were — every consumer (store-backend.ts, the
+ * DB-integration suite) imports from THIS path unchanged.
+ */
 export { PgWorkflowRunStore, PgWorkflowCompletionInbox, PgWorkflowNotifyJournalStore } from "./workflow-run-store-sql.js";
 //# sourceMappingURL=pg-workflow-run-store.d.ts.map

package/dist/plugins/pg-workflow-run-store.js

@@ -1,2 +1,9 @@
+/**
+ * Thin re-export shim (design/158 A12 扇出): the PG `WorkflowRunStore`/`WorkflowCompletionInbox`/
+ * `WorkflowNotifyJournalStore` twins now live collapsed with their TiDB dialect siblings in the
+ * single-file dual-dialect `workflow-run-store-sql.ts` (design doc + dialect-delta ledger there).
+ * Class names and ctor arity stay EXACTLY as they were — every consumer (store-backend.ts, the
+ * DB-integration suite) imports from THIS path unchanged.
+ */
 export { PgWorkflowRunStore, PgWorkflowCompletionInbox, PgWorkflowNotifyJournalStore } from "./workflow-run-store-sql.js";
 //# sourceMappingURL=pg-workflow-run-store.js.map

package/dist/plugins/posix-shell-fs.d.ts

@@ -5,8 +5,11 @@ export interface ShellRunResult {
     exitCode: number;
 }
 export interface PosixShellFsDeps {
+    /** 腿的传输:k8s/ssh/adb=`this.exec`,local-docker=`docker(execRaw(cmd))` 包一层。 */
     run: (cmd: string, abortSignal?: AbortSignal) => Promise<Result<ShellRunResult, ExecutionError | RemoteExecutionError>>;
+    /** 腿的路径绝对化(各腿 cwd 语义不同,留在腿上)。 */
     resolve: (p: string) => string;
+    /** R5:临时件落点。返回目录 ⇒ `mktemp -p <dir>`(workspace 腿);null ⇒ `mktemp -t`(ssh,系统 temp)。 */
     tempDir: () => string | null;
 }
 export interface PosixShellFs {

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

@@ -1,3 +1,23 @@
+/**
+ * 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";
@@ -33,6 +53,7 @@ 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) };
@@ -58,6 +79,7 @@ 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
@@ -67,6 +89,11 @@ 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) };
@@ -79,6 +106,7 @@ 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) };
@@ -94,7 +122,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);
+                    return ok(undefined); // force = 幂等删除
                 return { ok: false, error: classifyFsStderr(r.value.stderr, abs, "unknown") };
             }
             return ok(undefined);
@@ -110,6 +138,8 @@ 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.d.ts

@@ -2,8 +2,11 @@ import { spawn } from "node:child_process";
 import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 export interface AdbEnvConfig {
+    /** Device serial or `host:port` (TCP). `host:port` triggers `adb connect` on connect()/reconnect(). */
     serial: string;
+    /** Path to the adb binary. Default "adb" (must be on PATH in the runner image). */
     adbPath?: string;
+    /** On-device workspace root; relative paths resolve against it. Default "/data/local/tmp". */
     mountPath?: string;
     commandTimeoutMs?: number;
     dataTimeoutMs?: number;
@@ -19,10 +22,17 @@ type ConnectResult = {
     ok: false;
     error: RemoteExecutionError;
 };
+/**
+ * Test seam (design/61 §9.3 fault-injection): inject `spawn` and/or a `connectOnce` that replays an error
+ * sequence, so the retry policy + first-attach behaviour is deterministically testable without a real device
+ * (the E2B-adapter bug that only surfaced in dogfood is the lesson this guards against).
+ */
 export interface AdbEnvDeps {
     spawn?: typeof spawn;
     connectOnce?: (signal?: AbortSignal) => Promise<ConnectResult>;
 }
+/** [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 declare function isAdbTransportLost(stderr: string): boolean;
 export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     readonly capabilities: {
@@ -31,6 +41,12 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     };
     cwd: string;
     private connected;
+    /** 🔴 拆除是**终态**(2026-07-25 补齐:此前本适配器是同族里唯一没有这个概念的一条腿)。
+     *  没有它的后果实测:`destroy()` 只清 `connected`,于是任何残留引用**一次 `connect()` 就把 env 整个复活**,
+     *  `exec` 又能在真设备上跑;而 `reconnect(sessionToken)` 就在同一个接缝上摆着。读面更松 —— 它连
+     *  `connected` 都不查,所以 destroy 之后 `readTextFile` 照样从真设备把文件读出来。
+     *  同姿态的 ssh 腿早有先例(`remote-env-ssh.ts`「destroy 后一律不复活,显式 connect/reconnect 同禁」),
+     *  五条兄弟腿全部 fail-closed,只有 adb 例外 —— 补齐它。 */
     private destroyed;
     private readonly cfg;
     private readonly spawnFn;
@@ -74,6 +90,7 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /** `adb disconnect` the TCP device (USB: just drop our flag). Does NOT reset the phone — idempotent, never throws. */
     destroy(): Promise<void>;
     cleanup(): Promise<void>;
     exec(command: string, options?: ExecOpts): Promise<Result<{
@@ -84,6 +101,8 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     execStream(command: string, options?: ExecStreamOptions): AsyncIterable<OutputChunk>;
     absolutePath(p: string): Promise<Result<string, FileError>>;
     joinPath(parts: string[]): Promise<Result<string, FileError>>;
+    /** 文件面的终态门 —— 读面此前**连 `connected` 都不查**,所以 destroy 之后还能从真设备读出文件内容。
+     *  与 host/local-docker/k8s/e2b 的姿态对齐(它们的文件面都在 destroy 后 fail-closed)。 */
     private fsGate;
     readBinaryFile(p: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
     readTextFile(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
@@ -115,9 +134,15 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
         suffix?: string;
         abortSignal?: AbortSignal;
     }): Promise<Result<string, FileError>>;
+    /** Spawn the adb binary with the given args; collect stdout/stderr (+ raw bytes when binary), bound by timeout/abort. */
     private adb;
     private withCwdEnv;
 }
+/**
+ * `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 declare function adbExecutionEnvFactory(config: AdbEnvConfig): ExecutionEnvFactory;
 export {};
 //# sourceMappingURL=remote-env-adb.d.ts.map

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

@@ -1,3 +1,29 @@
+/**
+ * `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";
@@ -13,6 +39,8 @@ 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);
 }
@@ -20,6 +48,12 @@ 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;
@@ -43,11 +77,14 @@ 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"],
+            retryableCodes: ["auth_transient", "connect_failed", "timeout"], // first-attach flakiness; NOT auth_failed
             maxAttempts: this.cfg.retry.maxAttempts,
             backoffMs: (failed) => this.cfg.retry.backoffMs * failed,
         };
@@ -67,6 +104,7 @@ 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) };
@@ -96,19 +134,23 @@ 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;
+        this.destroyed = true; // 终态(见字段旁注):此后 connect/reconnect 与整个文件面一律 fail-closed
     }
     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,
@@ -117,8 +159,10 @@ 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;
+            this.connected = false; // dead transport — the next exec fails closed; reconnect() re-establishes
             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);
@@ -127,7 +171,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"] });
+        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 queue = [];
         let finished = false;
         let failure;
@@ -143,6 +187,8 @@ 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;
@@ -152,6 +198,7 @@ export class RemoteAdbExecutionEnv {
                     child.kill("SIGKILL");
                 }
                 catch {
+                    /* noop */
                 }
             }
         };
@@ -171,12 +218,12 @@ export class RemoteAdbExecutionEnv {
             lastChunk = Date.now();
             queue.push(chunk);
             if (queue.length >= 512 && !paused) {
-                paused = true;
+                paused = true; // backpressure: bound queue growth on a fast producer / slow consumer (council design #1)
                 child.stdout.pause();
             }
             signalReady();
         };
-        let stderrTail = "";
+        let stderrTail = ""; // [R78]#1: watch for device-transport-drop markers (bounded tail, not the whole stream)
         child.stdout.on("data", (d) => enqueue({ type: "stdout", data: d.toString() }));
         child.stderr.on("data", (d) => {
             stderrTail = (stderrTail + d.toString()).slice(-512);
@@ -189,6 +236,7 @@ export class RemoteAdbExecutionEnv {
         });
         child.on("close", (code) => {
             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)}`);
             }
@@ -225,12 +273,15 @@ 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)) };
@@ -241,6 +292,7 @@ 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) };
@@ -254,6 +306,8 @@ 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));
@@ -278,11 +332,16 @@ 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)}`);
@@ -321,6 +380,9 @@ 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({
@@ -356,27 +418,42 @@ 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 { }
+                catch { /* noop */ }
                 forceSettleTimer ??= armPipeDestroyGrace(child);
             };
+            // 🔴 binary caveat (D2): this helper is SHARED by the model-facing TEXT exec (must be bounded — a
+            // `yes`/`cat big` could OOM the durable worker) and by readBinaryFile (`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 = [];
-            const outTail = binary ? undefined : new RollingTailBuffer();
-            const errBuf = new RollingTailBuffer();
+            const outBufs = []; // binary path only: full bytes for stdoutBytes
+            const outTail = binary ? undefined : new RollingTailBuffer(); // text path only: bounded stdout
+            const errBuf = new RollingTailBuffer(); // Buffer[]+concat replaced by rolling-tail — same O(n) push, bounded total
             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);
             };
@@ -399,7 +476,7 @@ export class RemoteAdbExecutionEnv {
                     outBufs.push(d);
                 else
                     outTail.push(d);
-                opts?.onStdout?.(d.toString());
+                opts?.onStdout?.(d.toString()); // streaming callback still gets the full chunk; only the buffered return is bounded
             });
             child.stderr.on("data", (d) => {
                 errBuf.push(d);
@@ -408,10 +485,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) => {
                 if (forceSettleTimer)
-                    clearTimeout(forceSettleTimer);
+                    clearTimeout(forceSettleTimer); // `close` fired → pipes closed naturally; clear D5 grace
                 const err = errBuf.result();
                 const stderr = markTruncated(err.text, err.droppedBytes);
                 if (binary) {
+                    // byte-exact: readBinaryFile decodes stdoutBytes; never truncate.
                     const stdoutBytes = Buffer.concat(outBufs);
                     finish(ok({ stdout: stdoutBytes.toString("utf8"), stderr, exitCode: code ?? 0, stdoutBytes: new Uint8Array(stdoutBytes) }));
                 }
@@ -434,6 +512,11 @@ 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);
 }