@sema-agent/server 7.150.0 → 7.152.0

package/dist/plugins/remote-env-connect-seat.js

@@ -0,0 +1,72 @@
+import { RemoteExecutionError, isRetryableRemoteErrorCode } from "@sema-agent/core";
+export const CONNECT_REFUSAL_CODE = {
+    home_unconfirmed: "env.home_unconfirmed",
+    snapshot_bucket_missing: "env.snapshot_bucket_missing",
+    occupant_missing: "env.occupant_missing",
+    pod_admission_refused: "env.sandbox_refused",
+    credential_broker_refused: "env.sandbox_refused",
+    archive_unrecoverable: "env.sandbox_refused",
+    workspace_fill_refused: "env.sandbox_refused",
+    host_key_rejected: "env.host_key_rejected",
+    pod_quota_exceeded: "connect_failed",
+    occupant_unreadable: "connect_failed",
+    target_settling: "connect_failed",
+};
+const ENGINE_FIELD_STILL_CLOSED = true;
+void ENGINE_FIELD_STILL_CLOSED;
+function mintRefusalError(code, message, cause) {
+    return new RemoteExecutionError(code, message, cause);
+}
+function standsFor(code) {
+    return !isRetryableRemoteErrorCode(code);
+}
+export function connectRefusal(fact, message, cause) {
+    const code = CONNECT_REFUSAL_CODE[fact];
+    const error = mintRefusalError(code, message, cause);
+    return standsFor(code) ? { ok: false, error, standing: true } : { ok: false, error, standing: false };
+}
+export function withdrawOnAbort(walk, signal) {
+    if (signal === undefined)
+        return walk;
+    if (signal.aborted)
+        return Promise.resolve({ ok: false, error: new RemoteExecutionError("aborted", "connect aborted") });
+    return new Promise((resolve, reject) => {
+        const onAbort = () => resolve({ ok: false, error: new RemoteExecutionError("aborted", "connect aborted while waiting") });
+        signal.addEventListener("abort", onAbort, { once: true });
+        walk.then((r) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(r);
+        }, (e) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(e);
+        });
+    });
+}
+export function createConnectSeat(lane) {
+    let held;
+    return {
+        get held() {
+            return held;
+        },
+        answer(refusal) {
+            if (refusal.standing && held === undefined)
+                held = refusal;
+            return refusal;
+        },
+        connect(config) {
+            if (held !== undefined)
+                return Promise.resolve(held);
+            const signal = config?.abortSignal;
+            const walking = lane.inFlight();
+            if (walking !== undefined)
+                return withdrawOnAbort(walking, signal);
+            const handle = lane.live();
+            if (handle !== undefined)
+                return Promise.resolve({ ok: true, value: handle });
+            if (signal?.aborted)
+                return Promise.resolve({ ok: false, error: new RemoteExecutionError("aborted", "connect aborted") });
+            return lane.establish(config);
+        },
+    };
+}
+//# sourceMappingURL=remote-env-connect-seat.js.map

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

@@ -1,4 +1,4 @@
-import { ExecutionError, FileError, RemoteExecutionError, type ExecutionEnv, type ExecutionEnvFactory, type ExecStreamOptions, type FileInfo, type OutputChunk, type RemoteConnectConfig, type RemoteExecutionEnv, type Result, type SessionToken, type SnapshotId, type VmLifecycleOptions, type WorkspaceHandle, type WriteExpectation, type WriteReceipt } from "@sema-agent/core";
+import { ExecutionError, FileError, RemoteExecutionError, type ExecutionEnv, type ExecutionEnvFactory, type ExecStreamOptions, type FileInfo, type OutputChunk, type RemoteConnectConfig, type RemoteExecutionEnv, type Result, type SessionToken, type SnapshotId, type VmLifecycleOptions, type WorkspaceHandle, type WriteExpectation, type WriteReceipt, type BoundFileObject } from "@sema-agent/core";
 import { type DeviceOwner, type DeviceRejectCode, type DeviceRow, type DeviceStore } from "../device-store.js";
 import type { DeviceEnrollment } from "../device-enrollment.js";
 import { type ExecutionPlacementSeat } from "../execution-placement.js";
@@ -48,6 +48,13 @@ type RejectCode = DeviceRejectCode;
  */
 export declare const DEVICE_REJECT_TO_EXEC_ERROR: Readonly<Record<RejectCode, ExecutionError["code"]>>;
 export declare const DEVICE_REJECT_TO_FILE_ERROR: Readonly<Record<RejectCode, FileError["code"]>>;
+/**
+ * 生命周期面(connect/reconnect)的 typed 拒 → `RemoteExecutionErrorCode`。
+ *
+ * `connect_failed` = 本次到不了(**可重试**,core `RETRYABLE_REMOTE_ERROR_CODES` 含它);
+ * `auth_failed` = 永久拒(NEVER retry —— 换绑/吊销/不是你的设备,重试一万次也是同一答)。
+ */
+export declare const DEVICE_REJECT_TO_REMOTE_ERROR: Readonly<Record<RejectCode, RemoteExecutionError["code"]>>;
 export interface DeviceEnvLogger {
     warn(msg: string, fields?: Record<string, unknown>): void;
     info?(msg: string, fields?: Record<string, unknown>): void;
@@ -102,9 +109,15 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
     readLink?: (path: string, abortSignal?: AbortSignal) => Promise<Result<string, FileError>>;
     writeFileExclusive?: (path: string, content: string | Uint8Array, abortSignal?: AbortSignal) => Promise<Result<void, FileError>>;
     writeFileGuarded?: (path: string, content: string | Uint8Array, expect: WriteExpectation, abortSignal?: AbortSignal) => Promise<Result<WriteReceipt, FileError>>;
+    openBound?: (path: string, abortSignal?: AbortSignal) => Promise<Result<BoundFileObject, FileError>>;
     private connected;
     /** 在飞的那一次准入(单飞记忆)——见 {@link admitShared}。settle 即清,**不缓存败诺**。 */
     private connectPromise?;
+    /**
+     * 建连座(`remote-env-connect-seat.ts`):`connect` 的唯一次序 —— 准入在飞 ⇒ 等那一次(调用方的取消只退它自己的等待)· 已连 ⇒ 当下的把手、不再准入 · 否则准入一次。
+     * 本车道不记拒:准入每次都是对绑定 / 吊销 / 在线的一次新读(拒码按生命周期表拼:{@link DEVICE_REJECT_TO_REMOTE_ERROR})。
+     */
+    private readonly seat;
     /** 拆除是**终态**(六条兄弟腿同纪律:destroy 之后 connect/exec/读面一律 fail-closed,不复活)。 */
     private destroyed;
     constructor(cfg: DeviceEnvConfig);
@@ -170,10 +183,8 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
     /**
      * 懒连接:**首次调用任一面**(exec / execStream / 文件面)时自动走一次准入。
      *
-     * 🔴 为什么这条必须在 adapter 里(而不是「谁用谁先 connect」):task/run 车道**没有任何人**会替
-     * adapter 调 `connect()` —— 工厂铸出 env 就直接用它的 exec/文件面(本仓亲核:`src/` 里对执行环境的
-     * `.connect()` 只有 bench 与生命周期面自己)。所以一条「设了未连闸、又不自连」的腿,它的每一次工具
-     * 调用都被自家的闸挡回,而设备侧一条指令帧都收不到。e2b(首用建 VM)/ k8s(`connectPromise ??=`)/
+     * 🔴 为什么这条必须在 adapter 里(而不是「谁用谁先 connect」):面可能在任何人连它之前就被调到(工厂交出之前的附件物化层、
+     * 委派子代的放置检查)。所以一条「设了未连闸、又不自连」的腿,它的每一次工具调用都被自家的闸挡回,而设备侧一条指令帧都收不到。e2b(首用建 VM)/ k8s(`connectPromise ??=`)/
      * ssh(single-flight join)/ local-docker 四腿早就是懒连接;本腿从此同形,`connect()` 的语义
      * (准入 + 取活连接 + 保护面对拍)一个字不动,只是触发时机与兄弟一致。
      *
@@ -262,6 +273,12 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     private doReadLink;
+    private doOpenBound;
+    /**
+     * 逐答重绑的答者:每一答一条 `openBound` 指令,结局 kind **按 op 精确对拍**(`open` / `size` / `list` ⇒ `stat`,`readBytes` ⇒ `read`;答错 = 协议违约,不猜)。
+     * 开答之后的三答带开答时的 `identity` + `kind`,执行器在本机核对这一次打开的对象与它们都相等;每一答前照文件面同一道门(已拆 ⇒ 拒;首用准入)。
+     */
+    private boundAnswers;
     readBinaryFile(p: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
     readTextFile(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     readTextLines(p: string, options?: {

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

@@ -1,10 +1,12 @@
 import { posix } from "node:path";
 import { anchoredPath, anchorUnder, joinedPath } from "./exec-path-law.js";
 import { ExecutionError, FileError, RemoteExecutionError, } from "@sema-agent/core";
+import { openRebinding } from "./remote-shell.js";
 import { capabilitiesFor } from "../execution-lane-caps.js";
 import { DEVICE_ERROR_CODES, isDeviceAbsolutePath, } from "../device-store.js";
 import { boundDeviceOf } from "../execution-placement.js";
 import { createCutError, createExecFailure } from "../exec-cut.js";
+import { createConnectSeat, withdrawOnAbort } from "./remote-env-connect-seat.js";
 export const DEVICE_PROVIDER = "device";
 const ok = (value) => ({ ok: true, value });
 const STREAM_PENDING_MAX_BYTES = 2 * 1024 * 1024;
@@ -89,12 +91,12 @@ export const DEVICE_REJECT_TO_FILE_ERROR = {
     "limit.rate_exceeded": "target_unavailable",
     "draining": "target_unavailable",
 };
-const DEVICE_REJECT_TO_REMOTE_ERROR = {
+export const DEVICE_REJECT_TO_REMOTE_ERROR = {
     "device.not_bound": "connect_failed",
     "device.offline": "connect_failed",
     "device.busy": "connect_failed",
     "device.attached_elsewhere": "connect_failed",
-    "device.claim_conflict": "auth_failed",
+    "device.claim_conflict": "connect_failed",
     "device.provider_mismatch": "auth_failed",
     "device.identity_mismatch": "auth_failed",
     "device.revoked": "auth_failed",
@@ -110,6 +112,9 @@ function rejectText(reject) {
 }
 const ENV_TERMINAL = { kind: "env_terminal" };
 const ENV_TERMINAL_MESSAGE = "execution env already destroyed";
+function connectAnswerOf(admitted) {
+    return admitted.ok ? { ok: true, value: admitted.value } : { ok: false, error: new RemoteExecutionError(admitted.failure.remote, admitted.failure.message) };
+}
 function failureFor(code, message) {
     return { remote: DEVICE_REJECT_TO_REMOTE_ERROR[code], exec: DEVICE_REJECT_TO_EXEC_ERROR[code], file: DEVICE_REJECT_TO_FILE_ERROR[code], message };
 }
@@ -137,8 +142,14 @@ export class RemoteDeviceExecutionEnv {
     readLink;
     writeFileExclusive;
     writeFileGuarded;
+    openBound;
     connected = false;
     connectPromise;
+    seat = createConnectSeat({
+        live: () => (this.connected && !this.destroyed ? this.workspaceHandle() : undefined),
+        inFlight: () => this.connectPromise?.then(connectAnswerOf),
+        establish: (config) => withdrawOnAbort(this.admitShared().then(connectAnswerOf), config?.abortSignal),
+    });
     destroyed = false;
     constructor(cfg) {
         this.cfg = cfg;
@@ -150,6 +161,8 @@ export class RemoteDeviceExecutionEnv {
             this.writeFileExclusive = (p, c, s) => this.doWrite("writeFileExclusive", p, c, undefined, s);
         if (cfg.supports?.has("writeFileGuarded") === true)
             this.writeFileGuarded = (p, c, e, s) => this.doGuardedWrite(p, c, e, s);
+        if (cfg.supports?.has("openBound") === true)
+            this.openBound = (p, s) => this.doOpenBound(p, s);
     }
     guardFaceSnapshot() {
         const out = new Set();
@@ -196,12 +209,7 @@ export class RemoteDeviceExecutionEnv {
         };
     }
     async connect(config) {
-        if (config?.abortSignal?.aborted === true)
-            return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted") };
-        const admitted = await this.admitShared();
-        if (admitted.ok)
-            return ok(admitted.value);
-        return { ok: false, error: new RemoteExecutionError(admitted.failure.remote, admitted.failure.message) };
+        return this.seat.connect(config);
     }
     async admitShared() {
         const inflight = this.connectPromise;
@@ -577,6 +585,96 @@ export class RemoteDeviceExecutionEnv {
             return ok(o.linkTarget);
         });
     }
+    async doOpenBound(p, abortSignal) {
+        const gated = await this.fsGate(p);
+        if (gated)
+            return gated;
+        const abs = this.resolve(p);
+        return openRebinding(abs, this.boundAnswers(abs), abortSignal);
+    }
+    boundAnswers(abs) {
+        const send = async (args, signal, onChunk) => {
+            const gated = await this.fsGate(abs);
+            if (gated)
+                return gated;
+            return this.dispatch("openBound", { path: abs, ...args }, { timeoutMs: this.cfg.execTimeoutMs, ...(signal === undefined ? {} : { signal }), ...(onChunk === undefined ? {} : { onChunk }) });
+        };
+        const violation = (what) => ({ ok: false, error: new FileError("unknown", `device returned an openBound outcome ${what} — protocol violation`, abs) });
+        return {
+            open: async (signal) => {
+                const res = await send({ op: "open" }, signal);
+                if ("ok" in res)
+                    return res;
+                return this.fileOutcome(res, abs, (o) => {
+                    if (o.kind !== "stat")
+                        return this.wrongOutcome("stat", o.kind, abs);
+                    if (typeof o.identity !== "string" || o.identity === "" || o.info === undefined)
+                        return violation("without identity and info for the open answer");
+                    if (o.info.kind !== "file" && o.info.kind !== "dir")
+                        return violation(`naming a ${o.info.kind} (an executor refuses anything but a regular file or a directory with invalid)`);
+                    return ok({ identity: o.identity, kind: o.info.kind === "dir" ? "directory" : "file" });
+                });
+            },
+            size: async (bound) => {
+                const res = await send({ op: "size", identity: bound.identity, kind: bound.kind }, undefined);
+                if ("ok" in res)
+                    return res;
+                return this.fileOutcome(res, abs, (o) => {
+                    if (o.kind !== "stat")
+                        return this.wrongOutcome("stat", o.kind, abs);
+                    if (o.info === undefined)
+                        return violation("without info for the size answer");
+                    return ok(o.info.size);
+                });
+            },
+            readBytes: async (bound, max, signal) => {
+                const parts = [];
+                let got = 0;
+                let stray;
+                const res = await send({ op: "readBytes", identity: bound.identity, kind: bound.kind, max }, signal, (c) => {
+                    if (c.kind !== "data") {
+                        stray ??= c.kind;
+                        return;
+                    }
+                    if (c.data === undefined || c.data.length === 0)
+                        return;
+                    got += c.data.length;
+                    if (got <= max)
+                        parts.push(c.data);
+                });
+                if ("ok" in res)
+                    return res;
+                return this.fileOutcome(res, abs, (o) => {
+                    if (o.kind !== "read")
+                        return this.wrongOutcome("read", o.kind, abs);
+                    if (stray !== undefined)
+                        return violation(`carrying a ${stray} chunk for a readBytes answer (only data chunks belong to it)`);
+                    if (got > max)
+                        return { ok: false, error: new FileError("invalid", `The held file is over the ${max}-byte read cap (${got} bytes or more arrived); it was not read`, abs) };
+                    return ok(new Uint8Array(Buffer.concat(parts)));
+                });
+            },
+            list: async (bound, signal) => {
+                const res = await send({ op: "list", identity: bound.identity, kind: bound.kind }, signal);
+                if ("ok" in res)
+                    return res;
+                return this.fileOutcome(res, abs, (o) => {
+                    if (o.kind !== "stat")
+                        return this.wrongOutcome("stat", o.kind, abs);
+                    if (o.entries === undefined)
+                        return violation("without entries for the list answer");
+                    const entries = [];
+                    for (const w of o.entries) {
+                        const kind = w.kind === "dir" ? "directory" : w.kind === "symlink" ? "symlink" : w.kind === "file" ? "file" : undefined;
+                        if (kind === undefined)
+                            continue;
+                        entries.push({ name: posix.basename(w.path), kind, size: w.size, mtimeMs: w.mtimeMs });
+                    }
+                    return ok(entries);
+                });
+            },
+        };
+    }
     async readBinaryFile(p, abortSignal) {
         const gated = await this.fsGate(p);
         if (gated)

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

@@ -20,7 +20,7 @@
  * iterator MAY throw `RemoteExecutionError` mid-stream before an `exit` chunk (seam contract, OutputChunk).
  */
 import { Sandbox, type SandboxOpts, type SandboxConnectOpts } from "e2b";
-import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type ExecResult, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type ExecutionEnvFactory, type VmLifecycleOptions, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll, type ExecutionEnvCapabilities } from "@sema-agent/core";
+import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type ExecResult, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type BoundFileObject, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type ExecutionEnvFactory, type VmLifecycleOptions, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll, type ExecutionEnvCapabilities } from "@sema-agent/core";
 import { type SandboxReadFloorKnob } from "../execution-lane-caps.js";
 import { type SandboxReadFloor } from "./sandbox-read-floor.js";
 import { type LaneHomeConfig } from "../lane-home-probe.js";
@@ -127,9 +127,12 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     private destroyed;
     /** 家目录的座(主张在场 ⇒ 每只沙箱对证 · 否则建沙箱那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。 */
     private readonly homeSeat;
-    /** 这只环境的拒 —— 记一次、此后每次连接 / 恢复原样回它(同一模板同一个答案:不再建沙箱、不再问)。两个写者:家目录(沙箱答了而与主张不一致,或答的不是绝对路径)
-     *  与恢复点的填充(换一台沙箱也是同一个答的拒:种子不是项目包、摘要不符、镜像没有 `tar`、镜像预置撞名 —— `FillOutcome.standing`)。 */
-    private connectRefusal?;
+    /**
+     * 建连座(`remote-env-connect-seat.ts`):`connect` 的唯一次序(记住的拒 ⇒ 原样再答 · 一走在飞 ⇒ 等它 · 已连 ⇒ 当下的把手 · 否则建一只沙箱),并持有这只环境记住的拒 ——
+     * 记一次、此后每次连接 / 恢复原样回它(同一模板同一个答案:不再建沙箱、不再问)。两件立定的事实写它:家目录(沙箱答了而与主张不一致,或答的不是绝对路径;`env.home_unconfirmed`)
+     * 与恢复点的填充(换一台沙箱也是同一个答的拒:种子不是项目包、摘要不符、镜像没有 `tar`、镜像预置撞名 —— `FillOutcome.standing`;`env.sandbox_refused`)。
+     */
+    private readonly seat;
     /** In-flight connect/resume, memoized so concurrent lazy first-use OR resume provisions exactly one VM (no double-bill). `target` = the snapshot a resume
      *  restores (`undefined` = a fresh sandbox): {@link resumeVM} shares only a resume of the SAME snapshot — a connect for anything else is not the
      *  workspace it is asked to restore (it waits that one out, then releases the sandbox it left). */
@@ -223,8 +226,9 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     }>;
     /**
      * 家目录:座要问({@link LaneHomeSeat.asks}:主张在场 ⇒ 对证;没主张 ⇒ 量到绝对路径为止)⇒ 在这只沙箱里问一次 `$HOME`(前台 `commands.run`,与命令同一个
-     * 模板缺省用户、同一份沙箱 env),读数交座。返回这只沙箱的拒(`connect_failed`,拒句 = 同一只判官的句子),或 `undefined`(照用)。
-     * 沙箱答了的拒记在环境上(同一模板同一个答案);没答上(非零退出 / RPC 失败 / 输出里没有标记行)⇒ 这一次不开、不记,下一次重问;调用方中止 ⇒ `aborted`、不交座。
+     * 模板缺省用户、同一份沙箱 env),读数交座。返回这只沙箱的拒(拒句 = 同一只判官的句子),或 `undefined`(照用)。
+     * 沙箱答了的拒是立定的拒(`env.home_unconfirmed`,建连座记住它:同一模板同一个答案);没答上(非零退出 / RPC 失败 / 输出里没有标记行)⇒ 这一次不开、不记(`connect_failed`),
+     * 下一次重问;调用方中止 ⇒ `aborted`、不交座。
      * 上界 = 控制面 RPC 的墙钟(`rpcTimeoutMs`:问一个环境变量,不是跑用户命令)。
      */
     private homeVerdict;
@@ -295,6 +299,11 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
      *  🔴 exit≠0 归 `unknown` 而不是 `not_found`(与本腿 `readLink` 那一格刻意分家,同 `posix-shell-fs` 的理由):
      *  「叶不是软链」与「叶不存在」在这条命令上都是 exit 0 + 空 stdout,所以 exit≠0 一定不是「文件不在」。 */
     canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
+    /** 绑定读(逐答重绑,Linux 读法)。本腿不并进 `posix-shell-fs` 基座(原生 SDK 腿),但脚本、读法与工厂与四条 shell 腿**是同一只**
+     *  (`remote-shell.ts` `openBoundOverShell`),这里只多一条传输:{@link execInternal}(适配器自己的固定命令那一起动,与链脚本同一形)、数据界。
+     *  🔴 字节只经 stdout 的 base64 回来 —— `files.read` 按路径读,不能用;也不「拷进暂存件再按路径读」(同身份进程可换暂存件或它的祖先目录)。 */
+    openBound(p: string, abortSignal?: AbortSignal): Promise<Result<BoundFileObject, FileError>>;
+    private get boundLane();
     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-e2b.js

@@ -7,7 +7,8 @@ import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
 import { ADAPTER_START, BOOTSTRAP_START, createSandboxReadFloor, e2bFloorCommand, engineStart, } from "./sandbox-read-floor.js";
 import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
 import { fileErrorFromExec } from "./remote-env-file-error.js";
-import { appendFileStaged, readyUpload, rewriteAppend, numEnvOr, runSymlinkChain, shellQuote, writeFileStaged } from "./remote-shell.js";
+import { connectRefusal, createConnectSeat } from "./remote-env-connect-seat.js";
+import { appendFileStaged, openBoundOverShell, readyUpload, rewriteAppend, numEnvOr, runSymlinkChain, shellQuote, writeFileStaged } from "./remote-shell.js";
 import { buildLivenessCut, commandBoundsOf, firstBoundOf, laneLivenessOf, LIVENESS_MS_DEFAULT } from "../exec-bounds.js";
 import { createCutError } from "../exec-cut.js";
 import { BackgroundShellManager } from "./background-shell-support.js";
@@ -37,7 +38,22 @@ export class RemoteContainerExecutionEnv {
     handle;
     destroyed = false;
     homeSeat;
-    connectRefusal;
+    seat = createConnectSeat({
+        live: () => (this.sbx !== undefined && !this.paused ? this.workspaceHandle() : undefined),
+        inFlight: () => this.connecting?.promise,
+        establish: (config) => {
+            if (this.paused)
+                return Promise.resolve({ ok: false, error: new RemoteExecutionError("connect_failed", "execution env is suspended (paused) — resumeVM(snapshotId) before use") });
+            const mine = { target: undefined, promise: this.doConnect(config) };
+            this.connecting = mine;
+            const settled = () => {
+                if (this.connecting === mine)
+                    this.connecting = undefined;
+            };
+            void mine.promise.then(settled, settled);
+            return mine.promise;
+        },
+    });
     connecting;
     activeCommands = 0;
     paused = false;
@@ -156,20 +172,7 @@ export class RemoteContainerExecutionEnv {
         }
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
-        if (this.connectRefusal)
-            return { ok: false, error: this.connectRefusal };
-        if (this.paused)
-            return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env is suspended (paused) — resumeVM(snapshotId) before use") };
-        if (this.sbx)
-            return ok(this.workspaceHandle());
-        if (this.connecting)
-            return this.connecting.promise;
-        const mine = { target: undefined, promise: this.doConnect(config) };
-        this.connecting = mine;
-        const r = await mine.promise;
-        if (!r.ok && this.connecting === mine)
-            this.connecting = undefined;
-        return r;
+        return this.seat.connect(config);
     }
     async doConnect(config) {
         try {
@@ -200,9 +203,7 @@ export class RemoteContainerExecutionEnv {
             if (!filled.ok || this.destroyed) {
                 await sbx.kill().catch(() => { });
                 this.cfg.metrics?.inc("remote_env_connect_total", { provider: PROVIDER, result: "error" });
-                if (!filled.ok && filled.standing)
-                    this.connectRefusal = filled.error;
-                return { ok: false, error: filled.ok ? new RemoteExecutionError("connect_failed", "execution env destroyed during connect") : filled.error };
+                return filled.ok ? { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") } : this.seat.answer(filled);
             }
             this.sbx = sbx;
             this.paused = false;
@@ -256,8 +257,9 @@ export class RemoteContainerExecutionEnv {
     resumeVM(snapshotId, options) {
         if (this.destroyed)
             return Promise.resolve({ ok: false, error: new RemoteExecutionError("connect_failed", "env already destroyed") });
-        if (this.connectRefusal)
-            return Promise.resolve({ ok: false, error: this.connectRefusal });
+        const held = this.seat.held;
+        if (held)
+            return Promise.resolve(held);
         if (this.sbx && !this.paused && this.sbx.sandboxId === snapshotId)
             return Promise.resolve(ok(this.workspaceHandle()));
         const inFlight = this.connecting;
@@ -269,10 +271,7 @@ export class RemoteContainerExecutionEnv {
             if (this.connecting === mine)
                 this.connecting = undefined;
         };
-        mine.promise.then((r) => {
-            if (!r.ok)
-                forget();
-        }, forget);
+        mine.promise.then(forget, forget);
         return mine.promise;
     }
     async resumeWalk(inFlight, snapshotId, options) {
@@ -280,6 +279,9 @@ export class RemoteContainerExecutionEnv {
             await inFlight.promise;
             if (this.destroyed)
                 return { ok: false, error: new RemoteExecutionError("connect_failed", "env already destroyed") };
+            const held = this.seat.held;
+            if (held)
+                return held;
             if (this.sbx && !this.paused && this.sbx.sandboxId === snapshotId)
                 return ok(this.workspaceHandle());
         }
@@ -329,9 +331,7 @@ export class RemoteContainerExecutionEnv {
             if (!filled.ok) {
                 await this.rpc("sandbox.pause", (signal) => sbx.pause({ signal }), undefined, this.cfg.dataTimeoutMs).catch((e) => this.cfg.logger?.warn?.("remote_env_fill_refused_repause_failed", { sandboxId: sbx.sandboxId, error: errMsg(e) }));
                 this.cfg.metrics?.inc("remote_env_resume_total", { provider: PROVIDER, result: "error" });
-                if (filled.standing)
-                    this.connectRefusal = filled.error;
-                return { ok: false, error: filled.error };
+                return this.seat.answer(filled);
             }
             this.sbx = sbx;
             this.paused = false;
@@ -383,10 +383,7 @@ export class RemoteContainerExecutionEnv {
         const verdict = this.homeSeat.settle(probe);
         if (verdict === undefined)
             return undefined;
-        const error = new RemoteExecutionError("connect_failed", verdict.refusal);
-        if (verdict.answered)
-            this.connectRefusal = error;
-        return error;
+        return verdict.answered ? this.seat.answer(connectRefusal("home_unconfirmed", verdict.refusal)).error : new RemoteExecutionError("connect_failed", verdict.refusal);
     }
     fillAt(sbx, root, origin) {
         return this.cfg.workspaceFill === undefined ? Promise.resolve({ ok: true }) : this.cfg.workspaceFill.fill(this.fillChannel(sbx), root, origin);
@@ -968,6 +965,19 @@ export class RemoteContainerExecutionEnv {
     async canonicalChain(p, abortSignal) {
         return runSymlinkChain(this.resolve(p), (cmd) => this.execInternal(cmd, { abortSignal }));
     }
+    async openBound(p, abortSignal) {
+        return openBoundOverShell(this.resolve(p), this.boundLane, abortSignal);
+    }
+    get boundLane() {
+        return {
+            run: async (cmd, _cap, abortSignal) => {
+                const r = await this.execInternal(cmd, { cwd: "/", timeout: this.cfg.dataTimeoutMs / 1000, ...(abortSignal !== undefined ? { abortSignal } : {}) });
+                return r.ok ? { ok: true, value: { stdout: Buffer.from(r.value.stdout, "utf8"), stderr: r.value.stderr, exitCode: r.value.exitCode } } : r;
+            },
+            payload: "base64",
+            boundSec: this.cfg.dataTimeoutMs / 1000,
+        };
+    }
     async canonicalPath(p, abortSignal) {
         const abs = this.resolve(p);
         const r = await this.execInternal(`realpath -- ${shellQuote(abs)}`, { abortSignal });

package/dist/plugins/remote-env-file-error.js

@@ -1,9 +1,13 @@
 import { FileError, RemoteExecutionError } from "@sema-agent/core";
+import { isExecutionEnvRefusalCode } from "../execution-env-refusal.js";
+function sayEnvNotOpened(code) {
+    return code === "connect_failed" || isExecutionEnvRefusalCode(code);
+}
 function neverOpened(e) {
-    if (e.code === "connect_failed")
+    if (sayEnvNotOpened(e.code))
         return true;
     const cause = e.cause;
-    return cause instanceof RemoteExecutionError && cause.code === "connect_failed";
+    return cause instanceof RemoteExecutionError && sayEnvNotOpened(cause.code);
 }
 export function fileErrorFromExec(e, path) {
     const code = e.code === "aborted" ? "aborted" : neverOpened(e) ? "target_unavailable" : "unknown";

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

@@ -1,3 +1,4 @@
+import { type PlatformPath } from "node:path";
 import { FileError, type InheritEnvPolicy, ExecutionError, RemoteExecutionError, SchedulerError, type SchedulerCapability, type ScheduledIntent, type SchedulerContext, type ScheduledTaskId, type ScheduledTaskSummary, type ExecutionEnv, type ExecResult, 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, type ExecutionEnvFactoryContext, BackgroundShellError, type BackgroundShellCapability, type BackgroundShellId, type BackgroundHardKillOutcome, type BackgroundPoll, type BackgroundSpawnOptions, type SecretEnvFinding } from "@sema-agent/core";
 import { type LaneHomeConfig } from "../lane-home-probe.js";
 import { type CustodyMember } from "./workspace-custody.js";
@@ -45,7 +46,8 @@ export interface HostEnvConfig extends LaneHomeConfig {
      * user's OWN directory (e.g. the cwd `run-local` was invoked in), not an adapter-created ephemeral sandbox,
      * so the agent's file edits PERSIST and are user-visible (like a local coding agent working in your repo).
      * Takes precedence over `workspaceBase`/`id` (those are ignored). Default unset = ephemeral random + cleanup.
-     * 唯一的例外由托管表说:它落在一只本服务铸的临时根里({@link custody} 的 `sharedRoot`)⇒ 本环境共持那只根,不是调用方自有目录。
+     * 唯一的例外由托管表说:它落在一只本服务铸的临时根里 ⇒ 本环境(也)持有那只根 —— 铸时就判得出的({@link custody} 的 `sharedRoot`)从铸起共持;
+     * 铸时判不出、在那只根的最后一只持有者放手那一拍读得出地落在里面的,当场接过删除({@link RemoteHostExecutionEnv.assumeRoot})。
      */
     workspaceDir?: string;
     /**
@@ -71,10 +73,16 @@ export interface HostEnvConfig extends LaneHomeConfig {
 }
 /** 工作区托管表交给它铸的环境的那一面(`workspace-custody.ts`;host 车道的读法)。 */
 export interface HostWorkspaceCustodySeat {
-    /** `workspaceDir` 落在这只本服务铸的临时根里(委派子代按父的工作目录落根)⇒ 本环境与它的铸者共持这只根:建成后登记、收场时放手、最后放手的持有者删它。 */
+    /**
+     * 铸时那一判:`workspaceDir` 落在这只本服务铸的临时根里(委派子代按父的工作目录落根)⇒ 本环境从铸起与它的持有者共持这只根。
+     * 这是删除责任的**提前交接**,不是删除的闸 —— 删不删只由 {@link passOn} 在放手那一拍答。
+     */
     readonly sharedRoot?: string;
-    /** 表里除 `self` 之外还有没有成员持有 `root` —— 收场放手时问;有 ⇒ 删交给最后放手的那一只。 */
-    heldElsewhere(self: RemoteHostExecutionEnv, root: string): boolean;
+    /**
+     * 删前那一判(本环境放手 `root` 的同一同步段里问;同步、永不抛):「此刻还有谁在 `root` 里」—— 另有持有者 / 有还没离场的环境读得出地落在里面(它当场接过)/
+     * 有读不出的(留给退出兜底)⇒ `true`,不删;读得出地没人 ⇒ `false`,本环境在同一同步段里把它移出原路径再删。
+     */
+    passOn(self: RemoteHostExecutionEnv, root: string): boolean;
 }
 export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, SchedulerCapability, BackgroundShellCapability, CustodyMember<never> {
     /** 能力块的唯一作者 = `capabilitiesFor`(`execution-lane-caps.ts`;逐键表态与理由在那里,本类零能力字面量)。 */
@@ -190,10 +198,17 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      */
     private drainInflightFs;
     private ensureSpoolRoot;
-    /** 本环境对它工作区的租期({@link HostWorkspaceTenure}):借用的永不删;持有的收场放手、最后放手的持有者删。唯一写处 = 构造与 {@link removeOwnedTrees}。 */
+    /** 本环境对它工作区的租期({@link HostWorkspaceTenure}):借用的永不删;持有的收场放手、放手那一拍判得没人才删。唯一写处 = 构造、{@link assumeRoot} 与 {@link removeOwnedTrees}。 */
     private tenure;
+    /** 离场({@link left}):唯一写处 = {@link removeOwnedTrees} 的放手段。 */
+    private hasLeft;
     /** Memoized lazy `mkdir -p` so concurrent first-use prepares the workspace exactly once. */
     private preparing?;
+    /**
+     * 建连座(`remote-env-connect-seat.ts`):`connect` 的唯一次序 —— 建工作目录在飞 ⇒ 等那一次(调用方的取消只退它自己的等待)· 已建好 ⇒ 当下的把手 · 否则建一次。
+     * 本车道不记拒:主张证不了的家目录在构造时就拒了(环境不铸),建目录的失败是那一次的(下一次重来)。
+     */
+    private readonly seat;
     private readonly handle;
     constructor(config?: HostEnvConfig);
     /** 收场的进度(托管表读):活着 ⇒ 缺席;{@link destroy} 开始 ⇒ 那一次收场。 */
@@ -202,10 +217,20 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     get released(): boolean;
     /** 本车道收场不欠同一身份下一只环境任何账(删不掉的根留在退出兜底簿上,不交接)。 */
     readonly leftover: undefined;
-    /** 收场落定且已放手 ⇒ 出托管表(超时臂里放手挂在在飞写之后:落定了还持有 ⇒ 仍是持有者)。 */
+    /**
+     * 离场:本环境自己的收场放手那一段({@link removeOwnedTrees},在飞写落地之后)跑过。删前那一判只问还没离场的环境「你在不在这只根里」——
+     * 收场开始了而写还没落地的仍在场(它的写还会落进去);离场之后它不再动工作区(残余镜像写只许落在借用目录 / spool 根上)。
+     */
+    get left(): boolean;
+    /** 收场落定且已离场 ⇒ 出托管表(超时臂里放手挂在在飞写之后:落定了还没离场 ⇒ 仍在表里,借用的与持有的同一句)。 */
     get settled(): boolean;
-    /** 本环境此刻持有的、本服务铸的临时根(托管表的持有读法读它);借用 / 已放手 ⇒ 缺席。 */
-    get heldWorkspace(): string | undefined;
+    /** 本环境此刻持有的、本服务铸的临时根(托管表的持有读法读它;正常流至多一只);借用 / 已放手 ⇒ 空。 */
+    get heldRoots(): readonly string[];
+    /**
+     * 删前那一判把 `root` 的删除交给本环境。唯一调用方 = 工厂的 {@link passOnRoot}(与放手者的判在同一同步段;前提:本环境还没离场、工作目录读得出地落在 `root` 里):
+     * 持有集合加上它(借用的从此持有;已持有别的根的两只都持有),离场时按同一句律逐根再判。`root` 在盘或读不出 ⇒ 当场登记退出兜底簿(本环境的 prepare 可能早已跑过、不会再登记)。
+     */
+    assumeRoot(root: string): void;
     workspaceHandle(): WorkspaceHandle;
     connect(config?: RemoteConnectConfig): Promise<{
         ok: true;
@@ -214,6 +239,10 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /** 工作目录已建好时 `connect` 的那一答。 */
+    private preparedAnswer;
+    /** 建工作目录失败时 `connect` 的那一答(那一次的失败:下一次重来)。 */
+    private prepareFailed;
     suspendVM(_options?: VmLifecycleOptions): Promise<{
         ok: true;
         value: SnapshotId;
@@ -474,6 +503,13 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     private childHome;
     private fileError;
 }
+/**
+ * host 环境配置座的拼法(构造期的 `workspaceDir` / `workspaceBase` / 托管 `sharedRoot`,与工厂托管判读的腿目录同一只):与执行缝同一只读者
+ * (`exec-path-law.ts` 的 `anchoredPath`)—— 绝对的原样,相对的锚在本进程工作目录上,不折 `..`、不解链接。win32 的盘相对拼写(`C:work`)相对的是
+ * **那只盘**上的工作目录:锚在本进程在那只盘上的工作目录(`resolve("C:")`)下、余下原样接上(不这样读,它会被当成一段名字接在工作目录后面:`<cwd>\C:work`)。
+ * `pathApi` 只为让 POSIX 上的钉量 win32 形;生产读本机的 `path`。
+ */
+export declare function hostSeatPath(p: string, pathApi?: PlatformPath): string;
 /**
  * `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
@@ -490,8 +526,8 @@ export interface HostLegConfig extends Pick<HostEnvConfig, "workspaceDir" | "env
 /**
  * host 车道的工厂。**一只身份一只工作区**:经工作区托管表(`workspace-custody.ts`,与 local-docker 车道同一只)铸环境 ——
  * 同一身份(`ctx.taskId ?? ctx.sessionId`)还有一只没收场的环境 ⇒ 交回它(停驻腿的环境 = 续跑腿的环境:引擎 park-only 契约要的「重连到同一工作区」);
- * 正在收场 ⇒ 等它落定再铸。铸的时候问同一张表「腿的目录落在哪只本服务铸的临时根里」:落在里面(委派子代按父的工作目录落根)⇒ 与铸者共持那只根,
- * 父收场时子代还持有它就不删,最后放手的持有者删。`legOf` 先于交回 / 铸判(它可以拒)。
+ * 正在收场 ⇒ 等它落定再铸。本服务铸的临时根只在它的最后一只持有者放手那一拍、按表里还没离场的环境此刻的工作目录判得没人之后才删({@link passOnRoot});
+ * 铸时那一判({@link heldRootContaining})只把落在持有根里的新腿当场记成共持者。`legOf` 先于交回 / 铸判(它可以拒)。
  * 起服铸**一只**工厂(每次调用另铸一只工厂 = 没有表)。
  */
 export declare function hostExecutionEnvFactory(config?: HostEnvConfig, legOf?: (ctx: ExecutionEnvFactoryContext) => HostLegConfig): ExecutionEnvFactory;