@sema-agent/server 7.150.0 → 7.152.0

package/dist/plugins/org-delivery-quota-store.js

@@ -5,6 +5,8 @@ import { atomicWriteFile, ensureDir } from "@sema-agent/core";
 import { mysqlDriver, pgDriver, sqlDbNowMs } from "./sql-driver.js";
 import { retryOnDeadlock } from "./sql-errors.js";
 import { alignedWindow, retryAfterSecUntil } from "../observability/cost-quota.js";
+import { sealStoreClass } from "./store-boundary.js";
+import { storeBoundaryFault } from "../terminal.js";
 export const ORG_DELIVERY_SENDER_QUOTA_TABLE = "org_delivery_sender_quota";
 export const ORG_DELIVERY_RECIPIENT_QUOTA_TABLE = "org_delivery_recipient_quota";
 export const ORG_DELIVERY_PAIR_QUOTA_TABLE = "org_delivery_pair_quota";
@@ -169,7 +171,7 @@ export class SqlOrgDeliveryQuotaStore {
         }
         catch (err) {
             await conn.rollback().catch((rollbackErr) => {
-                throw new AggregateError([err, rollbackErr], `${table}: the quota transaction failed and its rollback failed too`);
+                throw new AggregateError([storeBoundaryFault(err, "sql-org-delivery-quota-store.inTx"), storeBoundaryFault(rollbackErr, "sql-org-delivery-quota-store.inTx")], `${table}: the quota transaction failed and its rollback failed too`);
             });
             throw err;
         }
@@ -221,6 +223,7 @@ export class SqlOrgDeliveryQuotaStore {
         return true;
     }
 }
+sealStoreClass(SqlOrgDeliveryQuotaStore, "sql-org-delivery-quota-store", { admitAttempt: "exit", take: "exit" });
 export class TiDBOrgDeliveryQuotaStore extends SqlOrgDeliveryQuotaStore {
     constructor(pool) {
         super(mysqlDriver(pool));

package/dist/plugins/outcome-ledger-sql.js

@@ -1,6 +1,7 @@
 import { randomUUID, createHash } from "node:crypto";
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { ensureIndexes } from "./ensure-index.js";
+import { sealStoreClass } from "./store-boundary.js";
 export function taskSignature(s) {
     if (s.tag)
         return `tag:${s.tag}`;
@@ -148,6 +149,7 @@ export class SqlOutcomeLedger {
         }));
     }
 }
+sealStoreClass(SqlOutcomeLedger, "sql-outcome-ledger", { record: "exit", recordCore: "exit", summary: "exit" });
 export class TiDBOutcomeLedger extends SqlOutcomeLedger {
     constructor(pool) {
         super(mysqlDriver(pool));

package/dist/plugins/permission-rule-store-sql.js

@@ -7,6 +7,7 @@ import { probedMissingColumnRefusal } from "./schema-drift-sentence.js";
 import { canonicalJsonStringify } from "@sema-agent/core";
 import { ensureIndexes } from "./ensure-index.js";
 import { createZodColumnReader, decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, StoreCorruptError } from "./sql-json-column.js";
+import { sealStoreClass, sealStoreObject } from "./store-boundary.js";
 export function writerOfSqlRuleStore(store) {
     const w = Reflect.get(store, PERMISSION_RULE_WRITER);
     if (w === null || typeof w !== "object")
@@ -494,7 +495,7 @@ class SqlDurableRulePartition {
     get [PERMISSION_RULE_WRITER]() {
         return this.writer;
     }
-    writer = {
+    writer = sealStoreObject({
         nextDot: async () => {
             await this.ensureBucket();
             for (let attempt = 0; attempt < NEXT_DOT_MAX_ATTEMPTS; attempt++) {
@@ -561,8 +562,9 @@ class SqlDurableRulePartition {
             }
             return { rev: opts.expectedRev + 1 };
         },
-    };
+    }, "sql-durable-rule-partition-writer", { nextDot: "exit", readRaw: "exit", apply: "exit" });
 }
+sealStoreClass(SqlDurableRulePartition, "sql-durable-rule-partition", { list: "exit", quarantined: "exit" });
 export class SqlDurableRulePartitionProvider {
     db;
     now;
@@ -583,6 +585,7 @@ export class SqlDurableRulePartitionProvider {
         return new SqlDurableRulePartition(this.db, { kind: "local-owner" }, this.now);
     }
 }
+sealStoreClass(SqlDurableRulePartitionProvider, "sql-durable-rule-partition-provider", { forPrincipal: "exit", forLocalOwner: "exit" });
 export function recordOwnerOf(record) {
     return readRuleOwner(record.owner ?? { kind: "principal", principal: record.principal });
 }
@@ -734,6 +737,7 @@ export class SqlRuleApprovalRecordStore {
         return affected === 1;
     }
 }
+sealStoreClass(SqlRuleApprovalRecordStore, "sql-rule-approval-record-store", { get: "exit", create: "exit", discardPendingRecord: "exit", cas: "exit" });
 export const RULE_IMPORT_TICKET_GC_GRACE_MS = 10 * 60_000;
 export function buildRulePayloadHash(candidates) {
     return createHash("sha256").update(canonicalJsonStringify(candidates), "utf8").digest("hex");
@@ -853,11 +857,14 @@ export class SqlRuleImportTicketStore {
         };
     }
 }
+sealStoreClass(SqlRuleImportTicketStore, "sql-rule-import-ticket-store", {
+    mint: "exit", consume: "exit", release: "exit", settle: "exit", peek: "exit", reclaim: "exit",
+});
 export const RULE_PENDING_APPROVAL_RETENTION_MS = 24 * 60 * 60_000;
 export const RULE_REAP_BATCH = 500;
 export function createSqlPermissionRuleStores(db, now) {
     const q = (mysql, pg) => (db.dialect === "mysql" ? mysql : pg);
-    return {
+    return sealStoreObject({
         durable: new SqlDurableRulePartitionProvider(db, now),
         approvals: new SqlRuleApprovalRecordStore(db, now),
         tickets: new SqlRuleImportTicketStore(db),
@@ -873,6 +880,6 @@ export function createSqlPermissionRuleStores(db, now) {
                 throw new Error(`${PERMISSION_RULE_TABLE} bucket count came back unreadable (${String(rows[0]?.["n"])})`);
             return n;
         },
-    };
+    }, "sql-permission-rule-stores", { reapExpired: "exit", countBuckets: "exit" });
 }
 //# sourceMappingURL=permission-rule-store-sql.js.map

package/dist/plugins/pg-cost-quota.js

@@ -1,6 +1,7 @@
 import { decideQuota } from "../observability/cost-quota.js";
 import { PgWriteBehindCounter } from "./write-behind-counter.js";
 import { ensureIndexes } from "./ensure-index.js";
+import { sealStoreClass } from "./store-boundary.js";
 const COST_QUOTA_TABLE = { table: "cost_quota", keyCol: "scope_key", valCol: "micro_usd" };
 export class PgCostQuota {
     counter;
@@ -52,6 +53,9 @@ export class PgCostQuota {
         this.counter.stop();
     }
 }
+sealStoreClass(PgCostQuota, "pg-cost-quota", {
+    setLimits: "exit", check: "exit", add: "exit", flush: "exit", refresh: "exit", reap: "exit", startRefresh: "exit", stop: "exit",
+});
 export const PG_COST_QUOTA_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS cost_quota (
      scope_key     VARCHAR(190) COLLATE "C" NOT NULL,

package/dist/plugins/pg-pool.js

@@ -1,10 +1,11 @@
 import { createLogger } from "../observability/logger.js";
 import pg from "pg";
 import { recordFailOpen } from "../observability/fail-open.js";
+import { markErrorOrigin } from "./error-origin.js";
 import { acquireAdvisoryLock, releaseAdvisoryLock } from "./ensure-schema-lock-policy.js";
 import { RUN_IDENTITY_COLUMNS } from "../identity-source.js";
 import { ensureSchema as ensureSessionSchema } from "../stores-sql/pg-session-storage.js";
-import { sessionExtDdl } from "./session-ext-table.js";
+import { SESSION_EXT_INDEXES, sessionExtDdl } from "./session-ext-table.js";
 import { CHECKPOINT_HOST_SESSION_COLUMN } from "./checkpoint-index-columns.js";
 import { ensureSchema as ensureToolResultSchema } from "../stores-sql/tool-result-store-sql.js";
 import { ensureSchema as ensureCostQuotaSchema } from "./pg-cost-quota.js";
@@ -29,6 +30,7 @@ import { PRINCIPAL_MAX_BYTES } from "../principal-shape.js";
 import { SKILL_EXEMPTION_CUTOFF_ID, markIfAbsentSql, migrationMarkerDdl } from "./one-time-migration-marker.js";
 import { replicaRegistrationDdl } from "./replica-registration.js";
 import { servingRequirementDdl } from "./serving-requirement.js";
+import { sessionBlobNamespaceClaimDdl } from "./session-blob-claim-token.js";
 export const PG_SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS task_run (
      task_id     VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -95,9 +97,7 @@ export const PG_SCHEMA_STATEMENTS = [
      session_id   VARCHAR(190) COLLATE "C" NOT NULL,
      version      INT          NOT NULL DEFAULT 1,
      status       VARCHAR(16) COLLATE "C"  NOT NULL DEFAULT 'pending',
-     tool_name    VARCHAR(190) COLLATE "C",
      tool_call_id VARCHAR(190) COLLATE "C",
-     tool_input   JSONB,
      checkpoint   JSONB        NOT NULL,
      outcome      JSONB,
      deadline     BIGINT,
@@ -116,13 +116,6 @@ export const PG_SCHEMA_STATEMENTS = [
      -- (tidb-pool.ts 同两列的行内注)。PG text 无长度上限,预算由 core 侧统一执法。
      pending_steer_queue TEXT COLLATE "C",
      pending_steer_rev BIGINT NOT NULL DEFAULT 0,
-     risk_descriptor TEXT COLLATE "C",
-     -- rule_suggestions:语义、铸行侧的窄读/脱敏/截断纪律、以及「NULL = 无供给 ⇒ 读口省键」的完整由来见
-     -- MySQL 孪生(tidb-pool.ts 同名列的行内注)。
-     rule_suggestions TEXT COLLATE "C",
-     -- has_bidi_controls(S-30① / #356②):bidi 在场位,语义与「1 或 NULL、恒不写 0」见 MySQL 孪生同名列的
-     -- 行内注。clay 批 TINYINT(1) 归一先例:PG 侧统一 SMALLINT。
-     has_bidi_controls SMALLINT,
      -- execution_outcome / execution_at_ms(S-160;core 7.7.0 #602):语义、两轴的分工、CAS 与冲突的
      -- 「记录物理不可变」由来见 MySQL 孪生(tidb-pool.ts 同两列的行内注)。载荷是 core 的 GateOutcome
      -- JSON ⇒ 与同表 outcome 列同取 JSONB(协议信封无损,IS NULL 谓词两方言同义)。
@@ -130,6 +123,8 @@ export const PG_SCHEMA_STATEMENTS = [
      execution_at_ms   BIGINT,
      -- host_session_id:这张卡归在哪只会话上(MySQL 孪生同名同义;语义、写口与 M49 回填见 tidb-pool.ts 同名列的行内注)。
      ${CHECKPOINT_HOST_SESSION_COLUMN.pg},
+     -- card_scope_root:「不再询问」规则的 project root 铸卡快照(MySQL 孪生同名同义;语义见 tidb-pool.ts 同名列的行内注)。
+     card_scope_root   VARCHAR(4096) COLLATE "C",
      PRIMARY KEY (token)
    )`,
     `CREATE TABLE IF NOT EXISTS checkpoint_ctx (
@@ -303,6 +298,13 @@ export const PG_SCHEMA_STATEMENTS = [
      -- bytes NULLABLE = the same two-backend (SQL inline / MinIO index-only) contract as snapshot_blob above.
      bytes      BYTEA          NULL,
      created_at TIMESTAMPTZ(3) NOT NULL
+   )`,
+    `CREATE TABLE IF NOT EXISTS file_history_blob_grant (
+     scope         VARCHAR(64) COLLATE "C"  NOT NULL,
+     landing_owner VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
+     blob_hash     CHAR(64) COLLATE "C"     NOT NULL,
+     granted_at    TIMESTAMPTZ(3)           NOT NULL,
+     PRIMARY KEY (scope, landing_owner, blob_hash)
    )`,
     `CREATE TABLE IF NOT EXISTS workflow_journal (
      run_id        VARCHAR(191) COLLATE "C" NOT NULL,
@@ -425,6 +427,7 @@ export const PG_SCHEMA_STATEMENTS = [
     migrationMarkerDdl("pg"),
     replicaRegistrationDdl("pg"),
     servingRequirementDdl("pg"),
+    sessionBlobNamespaceClaimDdl("pg"),
 ];
 export function pgPoolOptions(pgCfg, dbQueryTimeoutMs) {
     return {
@@ -480,8 +483,29 @@ export function createPgPool(opts, onIdleClientError) {
             checkoutGuards.delete(client);
         }
     });
+    markPgDriverOrigins(pool);
     return pool;
 }
+function markPgDriverOrigins(pool) {
+    const query = pool.query.bind(pool);
+    const connect = pool.connect.bind(pool);
+    shadowMethod(pool, "query", (...args) => markRejection(query(...args)));
+    shadowMethod(pool, "connect", (...args) => (args.length > 0 ? connect(...args) : markRejection(connect())));
+    pool.on("connect", (client) => {
+        const clientQuery = client.query.bind(client);
+        shadowMethod(client, "query", (...args) => markRejection(clientQuery(...args)));
+    });
+}
+function shadowMethod(target, key, fn) {
+    Object.defineProperty(target, key, { value: fn, writable: true, configurable: true, enumerable: false });
+}
+function markRejection(out) {
+    if (out === null || (typeof out !== "object" && typeof out !== "function") || typeof out.then !== "function")
+        return out;
+    return out.then(undefined, (err) => {
+        throw markErrorOrigin(err, "driver");
+    });
+}
 export const ENSURE_SCHEMA_LOCK_KEY = 4906;
 const ENSURE_SCHEMA_LOCK_ID = { dialect: "pg", keys: [ENSURE_SCHEMA_LOCK_KEY] };
 export async function acquirePgEnsureSchemaLock(client, tag) {
@@ -501,6 +525,7 @@ export async function ensurePgSchema(pool) {
         await client.query(markIfAbsentSql("pg"), [SKILL_EXEMPTION_CUTOFF_ID, Date.now()]);
         await ensureSessionSchema(client);
         await client.query(sessionExtDdl("pg"));
+        await ensureIndexes((text, params) => client.query(text, params), "pg", SESSION_EXT_INDEXES);
         await ensureToolResultSchema(client);
         await ensureCostQuotaSchema(client);
         await ensureRateLimitSchema(client);

package/dist/plugins/pg-rate-limiter.js

@@ -1,5 +1,6 @@
 import { PgWriteBehindCounter } from "./write-behind-counter.js";
 import { ensureIndexes } from "./ensure-index.js";
+import { sealStoreClass } from "./store-boundary.js";
 const RATE_LIMIT_TABLE = { table: "rate_limit", keyCol: "limit_key", valCol: "hits" };
 export class PgRateLimiter {
     counter;
@@ -50,6 +51,7 @@ export class PgRateLimiter {
         this.counter.stop();
     }
 }
+sealStoreClass(PgRateLimiter, "pg-rate-limiter", { setLimits: "exit", check: "exit", sweep: "exit", flush: "exit", refresh: "exit", startRefresh: "exit", stop: "exit" });
 export const PG_RATE_LIMITER_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS rate_limit (
      limit_key     VARCHAR(190) COLLATE "C"   NOT NULL,

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

@@ -1,4 +1,5 @@
-import { FileError, type ExecutionError, type RemoteExecutionError, type FileInfo, type Result, type SymlinkChain } from "@sema-agent/core";
+import { FileError, type ExecutionError, type RemoteExecutionError, type BoundFileObject, type FileInfo, type Result, type SymlinkChain } from "@sema-agent/core";
+import { type BoundReadLane } from "./remote-shell.js";
 export interface ShellRunResult {
     stdout: string;
     stderr: string;
@@ -11,6 +12,9 @@ export interface PosixShellFsDeps {
     resolve: (p: string) => string;
     /** R5:临时件落点。返回目录 ⇒ `mktemp -p <dir>`(workspace 腿);null ⇒ `mktemp -t`(ssh,系统 temp)。 */
     tempDir: () => string | null;
+    /** 绑定读的传输:该腿**不丢字节**的那一条(k8s `execData` · local-docker 二进制 `docker exec` · adb `shell -T` 二进制 · ssh 按本答上界封顶的收集器),
+     *  起动形与该腿 `readBinaryFile` 同一形(适配器自己的固定命令)。 */
+    boundLane: BoundReadLane;
 }
 export interface PosixShellFs {
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
@@ -34,6 +38,7 @@ export interface PosixShellFs {
         suffix?: string;
         abortSignal?: AbortSignal;
     }): Promise<Result<string, FileError>>;
+    openBound(p: string, abortSignal?: AbortSignal): Promise<Result<BoundFileObject, FileError>>;
 }
 export declare function createPosixShellFs(deps: PosixShellFsDeps): PosixShellFs;
 //# sourceMappingURL=posix-shell-fs.d.ts.map

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

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { anchorUnder } from "./exec-path-law.js";
 import { FileError, } from "@sema-agent/core";
-import { runSymlinkChain, shellQuote, kindFromMode } from "./remote-shell.js";
+import { openBoundOverShell, runSymlinkChain, shellQuote, kindFromMode } from "./remote-shell.js";
 import { classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
 const ok = (value) => ({ ok: true, value });
 export function createPosixShellFs(deps) {
@@ -121,6 +121,9 @@ export function createPosixShellFs(deps) {
             const r = await run(cmd, options?.abortSignal);
             return tempResult(r);
         },
+        async openBound(p, abortSignal) {
+            return openBoundOverShell(resolve(p), deps.boundLane, abortSignal);
+        },
     };
     return fs;
 }

package/dist/plugins/remote-env-adb.d.ts

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { type LaneHomeConfig } from "../lane-home-probe.js";
-import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
+import { type ConnectResult } from "./remote-env-connect-seat.js";
+import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type BoundFileObject, 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 extends LaneHomeConfig {
     /** Device serial or `host:port` (TCP). `host:port` triggers `adb connect` on connect()/reconnect(). */
@@ -22,13 +23,6 @@ export interface AdbEnvConfig extends LaneHomeConfig {
 export interface AdbEnvLogger {
     warn(event: string, fields?: Record<string, unknown>): void;
 }
-type ConnectResult = {
-    ok: true;
-    value: WorkspaceHandle;
-} | {
-    ok: false;
-    error: RemoteExecutionError;
-};
 /**
  * Test seam ([ref] §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
@@ -69,15 +63,19 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
      *  同姿态的 ssh 腿早有先例(`remote-env-ssh.ts`「destroy 后一律不复活,显式 connect/reconnect 同禁」),
      *  五条兄弟腿全部 fail-closed,只有 adb 例外 —— 补齐它。 */
     private destroyed;
-    /** 在飞的那一次懒连接(单飞记忆)——见 {@link ensureConnected}。settle 即清,**不缓存败诺**。 */
+    /** 在飞的那一次连接(单飞记忆:显式 connect、首用的懒连接、reconnect 共用)。落定即清(按身份),**不缓存败诺**。 */
     private connectPromise?;
     /** core `ExecutionEnv.homeDir`([ref]):设备 shell 里执行用户的 home —— 声明在场 ⇒ 声明(首连时与设备 shell 的 `$HOME` 对证过),否则首连时 `adb shell` 实测的 `$HOME`(Android 常为 `/` 或 `/data/local/tmp` 一类,读到什么填什么,绝对即可),见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
     get homeDir(): string | undefined;
     /** 家目录的座(声明在场 ⇒ 首连时对证 · 否则首连时实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。设备 shell 答得出 `$HOME`,命令里的 `~` / `$HOME` 展开的就是它 ——
      *  声明与它不一致时规则守的是声明那个目录,所以与其余读得出家目录的车道同一只判官、同一句拒。 */
     private readonly homeSeat;
-    /** 家目录:设备答了而与声明不一致(或答的不是绝对路径)⇒ 这只环境的拒,记一次、此后每次连接原样回它(同一台设备同一个答案:不重试、不再问)。 */
-    private homeRefusal?;
+    /**
+     * 建连座(`remote-env-connect-seat.ts`):`connect` 的唯一次序(记住的拒 ⇒ 原样再答 · 一次连接在飞 ⇒ 等它 · 已连 ⇒ 当下的把手、不再握手 · 否则握手一次),
+     * 并持有这只环境记住的拒 —— 家目录:设备答了而与声明不一致(或答的不是绝对路径)⇒ 立定的拒(`env.home_unconfirmed`),记一次、此后每次连接原样回它
+     * (同一台设备同一个答案:不重试、不再问)。
+     */
+    private readonly seat;
     /** core 7.49.0 [ref]:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 Android 设备的 shell 里(设备自己的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
@@ -98,13 +96,14 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /** 握手一次(含重试策略):建连座在没有记住的拒、没有在飞、没连上时起它。 */
+    private handshake;
     /**
      * 懒连接:**首次调用任一面**(exec / execStream / 文件面)时自动 `connect()`(含重试策略),在飞的
-     * 那一次由全部调用者共用,失败**不缓存**(下一次调用重新试),`destroyed` 是终态不复活。
+     * 那一次由全部调用者共用(建连座),失败**不缓存**(下一次调用重新试;记住的拒例外,原样再答),`destroyed` 是终态不复活。
      *
-     * 🔴 为什么这条必须在 adapter 里:core 的 task/run 车道**没有任何人**替 adapter 调 `connect()` ——
-     * 工厂铸出 env 就直接用它的 exec/文件面(本仓亲核:`src/` 里对执行环境的 `.connect()` 只有 bench 与
-     * 生命周期面自己)。所以一条「设了未连闸、又不自连」的腿,它的每一次工具调用都被自家的闸挡回;
+     * 🔴 为什么这条必须在 adapter 里:面可能在任何人连它之前就被调到(工厂交出之前的附件物化层、委派子代的放置检查;
+     * 引擎在本腿的建立座上显式 `connect()`,那常常不是第一次 —— 建连座让它幂等)。所以一条「设了未连闸、又不自连」的腿,它的每一次工具调用都被自家的闸挡回;
      * 那不是 adb 特有语义,而是与 ssh([ref] 同一实红点)/ k8s / e2b / local-docker / device 不均匀。
      * 未连时的错误文案因此从「call connect() first」(这条车道上没人能照做)换成**真试过之后**的拒因。
      */
@@ -194,6 +193,9 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
     private push;
     private posixFsInst?;
     private get posixFs();
+    /** 绑定读一答的往返:与 {@link readBinaryFile} 同一道门(已拆 ⇒ 拒;首用建连)、同一只起动(`shell -T -- <命令>`)、同一只二进制收集器与数据界;
+     *  设备传输半途断 ⇒ `transport_lost`(与 {@link execCall} 同判)。 */
+    private boundExec;
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
@@ -201,6 +203,8 @@ export declare class RemoteAdbExecutionEnv implements RemoteExecutionEnv {
      *  循环(上限 64、只锚不折、遇环即止),脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份。
      *  缺席读法用不上(本腿在场);`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。 */
     canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
+    /** 绑定读(逐答重绑,Linux 读法 —— Android 是 Linux 内核;脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份)。 */
+    openBound(p: string, abortSignal?: AbortSignal): Promise<Result<BoundFileObject, FileError>>;
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     createDir(p: string, options?: {

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

@@ -5,6 +5,7 @@ import fs from "node:fs/promises";
 import { spawn } from "node:child_process";
 import { hostSubprocessEnv } from "../server-secret-env.js";
 import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
+import { connectRefusal, createConnectSeat } from "./remote-env-connect-seat.js";
 import { appendFileStaged, rewriteAppend, buildCwdEnvCommand, createCwdGuardedCall, shellQuote, armPipeDestroyGrace, writeFileStaged } from "./remote-shell.js";
 import { OWNER_ONLY_FILE_MODE } from "./owner-only-file-mode.js";
 import { signalNumber } from "./host-platform.js";
@@ -17,6 +18,7 @@ import { createPosixShellFs } from "./posix-shell-fs.js";
 import { createLogger } from "../observability/logger.js";
 import { seatText } from "../trace/exit-seat.js";
 const PROVIDER = "adb";
+const ADB_SETTLING_STATES = new Set(["bootloader", "recovery", "sideload", "rescue", "connecting", "authorizing"]);
 const DEVICE_PUSHED_FILE_MODE = "0644";
 const ok = (value) => ({ ok: true, value });
 const unsupported = (op) => ({
@@ -43,7 +45,18 @@ export class RemoteAdbExecutionEnv {
         return this.homeSeat.home;
     }
     homeSeat;
-    homeRefusal;
+    seat = createConnectSeat({
+        live: () => (this.connected && !this.destroyed ? this.workspaceHandle() : undefined),
+        inFlight: () => this.connectPromise,
+        establish: (config) => {
+            const walk = this.handshake(config).finally(() => {
+                if (this.connectPromise === walk)
+                    this.connectPromise = undefined;
+            });
+            this.connectPromise = walk;
+            return walk;
+        },
+    });
     cdPath = "unknown";
     withheldEnv = [];
     cfg;
@@ -74,8 +87,9 @@ export class RemoteAdbExecutionEnv {
     async connect(config) {
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "ADB env destroyed — create a fresh env instead of reviving") };
-        if (this.homeRefusal)
-            return { ok: false, error: this.homeRefusal };
+        return this.seat.connect(config);
+    }
+    handshake(config) {
         const policy = {
             retryableCodes: ["auth_transient", "connect_failed", "timeout"],
             maxAttempts: this.cfg.retry.maxAttempts,
@@ -86,7 +100,7 @@ export class RemoteAdbExecutionEnv {
         const halt = config?.abortSignal ? AbortSignal.any([config.abortSignal, refused.signal]) : refused.signal;
         return withRetry(async () => {
             const r = await once(config?.abortSignal);
-            if (!r.ok && this.homeRefusal)
+            if (!r.ok && this.seat.held)
                 refused.abort();
             return r;
         }, policy, { signal: halt });
@@ -96,19 +110,13 @@ export class RemoteAdbExecutionEnv {
             return { ok: false, error: new RemoteExecutionError("connect_failed", "ADB env destroyed — no lazy reconnect after teardown") };
         if (this.connected)
             return { ok: true };
-        const started = this.connectPromise ?? this.connect();
-        this.connectPromise = started;
         try {
-            const r = await started;
+            const r = await this.connect();
             return r.ok ? { ok: true } : { ok: false, error: r.error };
         }
         catch (err) {
             return { ok: false, error: new RemoteExecutionError("connect_failed", `adb lazy-connect threw: ${err instanceof Error ? err.message : String(err)}`) };
         }
-        finally {
-            if (this.connectPromise === started)
-                this.connectPromise = undefined;
-        }
     }
     async connectOnce(signal) {
         if (signal?.aborted)
@@ -147,10 +155,7 @@ export class RemoteAdbExecutionEnv {
                     return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted while reading the device's home") };
                 const verdict = this.homeSeat.settle(home.ok && home.value.exitCode === 0 ? { ok: true, stdout: home.value.stdout } : { ok: false, reason: home.ok ? `exit ${home.value.exitCode}` : home.error.message });
                 if (verdict !== undefined) {
-                    const error = new RemoteExecutionError("connect_failed", verdict.refusal);
-                    if (verdict.answered)
-                        this.homeRefusal = error;
-                    return { ok: false, error };
+                    return verdict.answered ? this.seat.answer(connectRefusal("home_unconfirmed", verdict.refusal)) : { ok: false, error: new RemoteExecutionError("connect_failed", verdict.refusal) };
                 }
             }
             this.connected = true;
@@ -161,6 +166,8 @@ export class RemoteAdbExecutionEnv {
         }
         if (/device.*not found|no devices/.test(err))
             return { ok: false, error: new RemoteExecutionError("connect_failed", `device ${this.cfg.serial} not found`) };
+        if (ADB_SETTLING_STATES.has(state))
+            return connectRefusal("target_settling", `device ${this.cfg.serial} is not usable yet (state=${state}) — it answers from a state it passes through on its way back to \`device\` (rebooting, an update applying, the transport handshake still running)`);
         return { ok: false, error: new RemoteExecutionError("auth_failed", `device ${this.cfg.serial} unusable (state=${state || "?"})`) };
     }
     async suspendVM(_options) {
@@ -434,8 +441,24 @@ export class RemoteAdbExecutionEnv {
             run: (cmd, abortSignal) => this.fsExec(cmd, abortSignal),
             resolve: (p) => this.resolve(p),
             tempDir: () => this.cwd,
+            boundLane: { run: (cmd, _cap, abortSignal) => this.boundExec(cmd, abortSignal), payload: "raw", boundSec: this.cfg.dataTimeoutMs / 1000 },
         }));
     }
+    async boundExec(cmd, abortSignal) {
+        if (this.destroyed)
+            return { ok: false, error: new ExecutionError("shell_unavailable", "execution env already destroyed") };
+        const ready = await this.ensureConnected();
+        if (!ready.ok)
+            return { ok: false, error: lazyConnectExecError(ready.error) };
+        const r = await this.adb(this.deviceShellArgs(cmd), { signal: abortSignal, timeoutMs: this.cfg.dataTimeoutMs, binary: true });
+        if (!r.ok)
+            return r;
+        if (r.value.exitCode !== 0 && isAdbTransportLost(r.value.stderr)) {
+            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({ stdout: r.value.stdoutBytes ?? new Uint8Array(0), stderr: r.value.stderr, exitCode: r.value.exitCode });
+    }
     async fileInfo(p, abortSignal) {
         return this.posixFs.statFileInfo(p, abortSignal);
     }
@@ -448,6 +471,9 @@ export class RemoteAdbExecutionEnv {
     async canonicalChain(p, abortSignal) {
         return this.posixFs.canonicalChain(p, abortSignal);
     }
+    async openBound(p, abortSignal) {
+        return this.posixFs.openBound(p, abortSignal);
+    }
     async canonicalPath(p, abortSignal) {
         return this.posixFs.canonicalPath(p, abortSignal);
     }

package/dist/plugins/remote-env-connect-seat.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 远端执行环境的**建连座** —— 每只远端适配器的 `connect` 只走这一只座:幂等的次序、记住的拒、拒码的拼法,都只写在这里。
+ *
+ * ## 律(两条)
+ * ① **`connect` 幂等**(引擎会在本腿的建立座上显式调它,而那常常不是第一次建立:委派子代在放置检查期已懒连过、工厂交出环境之前往里写过附件、
+ *    停驻腿交回的是同一只活环境)。答案的次序只有一种,写在 {@link createConnectSeat}:
+ *    这只环境**记住了拒** ⇒ 原样再答(不再建 pod / 沙箱 / 连接、不再读、不再等)· 有一走**正在建立**它(一次 connect、首用的懒连、一次恢复)⇒ 等**那一走**的答,
+ *    等它的调用方的取消只退**它自己**的等待(那一走照常服务其余等待者)· **已连上** ⇒ 当下的把手、什么都不建 · 都不是 ⇒ 起一走(适配器把它记成自己的在飞那一走;
+ *    起它的调用方的取消信号交给那一走,由那一走自己收场 —— 落定之前不交回,落定之后它就不再在飞)。
+ *    车道只答三件事实(记住的拒归座,在飞那一走与已连的把手归车道),不各写一份次序。
+ * ② **记住的拒 = 立定的拒 = 码在引擎可重试表之外**,三者是一个事实:拒因按事实词拼码只走 {@link connectRefusal}(拒因表 {@link CONNECT_REFUSAL_CODE},
+ *    闭集:表外的词编译红);立定与否不另写,读引擎那一张可重试表(`isRetryableRemoteErrorCode`)—— 码在表外 ⇒ 立定 ⇒ 座记住它;码在表内 ⇒ 会自愈 ⇒
+ *    座不记、下一次建连重来。座只收表拼出来的立定拒({@link StandingRefusal} 带品牌,别处铸不出),所以「记住了一只可重试码的拒」写不出来。
+ *    表外的码不是 `unknown` / `aborted`(那两词是引擎读作「不说环境本身」的两类,拒因表一个都不拼)。
+ *
+ * 车道每次尝试各自的答(`connect_failed` / `timeout` / 私钥被拒的 `auth_failed` / 不支持的 `unsupported` …)不经本表、不被记住 —— 那是一次尝试的读数,不是这只环境的立定事实。
+ */
+import { RemoteExecutionError, type RemoteConnectConfig, type WorkspaceHandle } from "@sema-agent/core";
+/** 一次建连的答(core `RemoteExecutionEnv.connect` 的返回形)。 */
+export type ConnectResult = {
+    ok: true;
+    value: WorkspaceHandle;
+} | {
+    ok: false;
+    error: RemoteExecutionError;
+};
+/**
+ * **拒因表**:远端车道在建连时答的、需要判「立定还是会自愈」的拒,按事实词 → 码。立定的事实拼引擎可重试表之外的码(本仓 `env.*` 族,
+ * 或引擎既有的永久词);会自愈的事实拼可重试表之内的码。
+ *
+ * 立定(此后每一次建连都是同一个答;座记住它):
+ *  · `home_unconfirmed` —— 环境**答了**自己的 `$HOME`,与主张不一致 / 不是绝对路径(k8s / e2b / local-docker / adb / ssh;host 在构造时以同一码拒);
+ *  · `snapshot_bucket_missing` —— k8s:对象存储对 `latest` 或归档的读答 `404 NoSuchBucket`;
+ *  · `occupant_missing` —— k8s:会话行在、却不带住客令牌(`session.incarnation_missing`,存储数据缺陷);
+ *  · `pod_admission_refused` —— k8s:集群建出 pod 后在它跑起来之前就判它 `Failed` / `Succeeded`(kubelet 准入拒:`SysctlForbidden`、节点亲和不中、节点放不下 …);
+ *  · `credential_broker_refused` —— k8s:成员凭据中继在这只 pod 上建不起来(中继表被拒、部署补丁够得着中继);
+ *  · `archive_unrecoverable` —— k8s 空间车道:`latest` 指的归档在桶里、却在有界重试之后仍取不回;
+ *  · `workspace_fill_refused` —— 隔离车道:恢复点的填充(会话附件 / 项目包种子)放不进、换一台机器也是同一个答(`workspace-fill.ts` 的 `standing`);
+ *  · `host_key_rejected` —— ssh:目标机出示的主机密钥过不了部署钉的判(指纹不符、条目换了钥、被吊销、没有条目;钉的文件读不出那一形不在此列)。
+ * 会自愈(座不记;下一次建连重来):
+ *  · `pod_quota_exceeded` —— k8s:建 pod 撞命名空间的 ResourceQuota(403 `exceeded quota`):别的 pod 结束就有额度;
+ *  · `occupant_unreadable` —— k8s:读会话住客超时或店报错(重跑这条 run 会再读);
+ *  · `target_settling` —— adb:设备答的是它在走向可用途中会经过的态(重启进 / 出引导、恢复、刷机模式,传输握手还在进行)。
+ */
+export declare const CONNECT_REFUSAL_CODE: {
+    readonly home_unconfirmed: "env.home_unconfirmed";
+    readonly snapshot_bucket_missing: "env.snapshot_bucket_missing";
+    readonly occupant_missing: "env.occupant_missing";
+    readonly pod_admission_refused: "env.sandbox_refused";
+    readonly credential_broker_refused: "env.sandbox_refused";
+    readonly archive_unrecoverable: "env.sandbox_refused";
+    readonly workspace_fill_refused: "env.sandbox_refused";
+    readonly host_key_rejected: "env.host_key_rejected";
+    readonly pod_quota_exceeded: "connect_failed";
+    readonly occupant_unreadable: "connect_failed";
+    readonly target_settling: "connect_failed";
+};
+export type ConnectRefusalFact = keyof typeof CONNECT_REFUSAL_CODE;
+/** 拒因表拼得出的码。 */
+export type ConnectRefusalCode = (typeof CONNECT_REFUSAL_CODE)[ConnectRefusalFact];
+declare const STANDING: unique symbol;
+/** 立定的拒:只由 {@link connectRefusal} 铸(品牌位),座只记它。 */
+export type StandingRefusal = {
+    readonly ok: false;
+    readonly error: RemoteExecutionError;
+    readonly standing: true;
+    readonly [STANDING]: true;
+};
+/** 会自愈的拒:这一次不开,下一次建连重来。 */
+export type PassingRefusal = {
+    readonly ok: false;
+    readonly error: RemoteExecutionError;
+    readonly standing: false;
+};
+/** 一次建连的拒,带它是不是立定的。 */
+export type ConnectRefusal = StandingRefusal | PassingRefusal;
+/** 按事实词拼一次建连的拒(码从拒因表来,立定与否从引擎的可重试表来)。句子 = 车道的拒句原文。 */
+export declare function connectRefusal(fact: ConnectRefusalFact, message: string, cause?: Error): ConnectRefusal;
+/** 建连座向车道要的三件事实(记住的拒由座自己持有)。 */
+export interface ConnectLane {
+    /** 已连上(且没有一走在飞)⇒ 当下的把手;否则 `undefined`。 */
+    live(): WorkspaceHandle | undefined;
+    /** 正在建立这只环境的那一走(一次 connect、首用的懒连、一次恢复);没有 ⇒ `undefined`。 */
+    inFlight(): Promise<ConnectResult> | undefined;
+    /**
+     * 起一走:车道把它记成自己的在飞那一走({@link inFlight} 随即答它),落定时按身份清。`config.abortSignal` 是起它的调用方的:那一走被它取消时答 `aborted`
+     * 并收掉自己建到一半的东西;共享尝试不带调用方信号的车道(ssh)经 {@link withdrawOnAbort} 只退这一位调用方的等待。
+     */
+    establish(config?: RemoteConnectConfig): Promise<ConnectResult>;
+}
+/** 一只环境的建连座(活对象:持有记住的拒)。 */
+export interface ConnectSeat {
+    /** 这只环境记住的拒(立定;直到销毁)。 */
+    readonly held: StandingRefusal | undefined;
+    /** 交出一次拒:立定的记住(先到者为准),会自愈的不记;原样交回(调用方以它作答)。 */
+    answer(refusal: ConnectRefusal): ConnectRefusal;
+    /** `connect` 的唯一入口(次序见文件头 ①)。 */
+    connect(config?: RemoteConnectConfig): Promise<ConnectResult>;
+}
+/** 调用方的取消只退它自己的等待:共享的那一走不动。已取消 ⇒ 当场答 `aborted`。 */
+export declare function withdrawOnAbort(walk: Promise<ConnectResult>, signal: AbortSignal | undefined): Promise<ConnectResult>;
+/** 铸一只建连座(每只远端环境一只)。 */
+export declare function createConnectSeat(lane: ConnectLane): ConnectSeat;
+export {};
+//# sourceMappingURL=remote-env-connect-seat.d.ts.map