@sema-agent/server 7.150.0 → 7.151.0

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";
@@ -194,6 +195,11 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     private tenure;
     /** 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} 开始 ⇒ 那一次收场。 */
@@ -214,6 +220,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 +484,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

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

@@ -1,11 +1,11 @@
 import { writeLogText } from "../observability/logger.js";
 import { spawn } from "node:child_process";
 import os from "node:os";
-import path from "node:path";
+import path, {} from "node:path";
 import { anchoredPath, anchorUnder, joinedPath } from "./exec-path-law.js";
 import fs from "node:fs/promises";
 import { randomBytes } from "node:crypto";
-import { openSync, closeSync, readSync, statSync, truncateSync, unlinkSync, mkdirSync, rmdirSync, mkdtempSync, existsSync, realpathSync, accessSync, constants as FS_CONST } from "node:fs";
+import { openSync, closeSync, readSync, statSync, truncateSync, unlinkSync, mkdirSync, rmdirSync, mkdtempSync, existsSync, accessSync, constants as FS_CONST } from "node:fs";
 import { StringDecoder } from "node:string_decoder";
 import { armPipeDestroyGrace, numEnvOr } from "./remote-shell.js";
 import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
@@ -13,7 +13,7 @@ import { buildCapturedOutput, createCutError } from "../exec-cut.js";
 import { hostBackgroundShellEnabled, hostExecSpoolEnabled } from "../config.js";
 import { IS_WIN32, resolveHostShell, hostShell, pinHostShell, spawnGroupOptions, killTreeHard, killTreeSoft, hardKillGroupNow, collapseWin32EnvKeys, adoptHostForegroundChild } from "./host-platform.js";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
-import { FileError, NodeExecutionEnv, inheritEnvPolicyProblem, ExecutionError, RemoteExecutionError, RollingTailBuffer, walkSymlinkChain, markTruncated, SchedulerError, BackgroundShellError, physicalPathOf as kernelRealPathOf, } from "@sema-agent/core";
+import { FileError, NodeExecutionEnv, inheritEnvPolicyProblem, ExecutionError, RemoteExecutionError, RollingTailBuffer, walkSymlinkChain, markTruncated, SchedulerError, BackgroundShellError, physicalPathOf, } from "@sema-agent/core";
 import { capabilitiesFor } from "../execution-lane-caps.js";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
 import { LaneHomeSeat, laneHomeRefusal } from "../lane-home-probe.js";
@@ -21,7 +21,9 @@ import { composeHostSubprocessEnv, hostSubprocessEnv, withheldFromHostSubprocess
 import { nameTooLongCode } from "./remote-env-file-error.js";
 import { trackEphemeralHostWorkspace, untrackEphemeralHostWorkspace } from "./host-workspace-registry.js";
 import { createWorkspaceCustody } from "./workspace-custody.js";
+import { canonicalPathOf, pathIsWithin } from "../memory-scope.js";
 import { OWNER_ONLY_FILE_MODE } from "./owner-only-file-mode.js";
+import { createConnectSeat, withdrawOnAbort } from "./remote-env-connect-seat.js";
 const PROVIDER = "host";
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
 const inflightFsDrainWaitMs = () => numEnvOr("HOST_FS_DRAIN_WAIT_MS", 10_000, 1);
@@ -131,18 +133,23 @@ export class RemoteHostExecutionEnv {
     }
     tenure;
     preparing;
+    seat = createConnectSeat({
+        live: () => (this.prepared && !this.destroyed ? this.handle : undefined),
+        inFlight: () => (this.prepared ? undefined : this.preparing?.then(() => this.preparedAnswer(), (e) => this.prepareFailed(e))),
+        establish: (config) => withdrawOnAbort(this.ensurePrepared().then(() => this.preparedAnswer(), (e) => this.prepareFailed(e)), config?.abortSignal),
+    });
     handle;
     constructor(config = {}) {
         if (config.workspaceDir) {
-            this.workspaceDir = path.resolve(config.workspaceDir);
+            this.workspaceDir = hostSeatPath(config.workspaceDir);
             const shared = config.custody?.sharedRoot;
-            this.tenure = shared !== undefined ? { kind: "held", root: path.resolve(shared) } : BORROWED;
+            this.tenure = shared !== undefined ? { kind: "held", root: hostSeatPath(shared) } : BORROWED;
         }
         else {
-            const base = config.workspaceBase ?? os.tmpdir();
+            const base = hostSeatPath(config.workspaceBase ?? os.tmpdir());
             const id = config.id ?? randomBytes(6).toString("hex");
             const suffix = randomBytes(4).toString("hex");
-            this.workspaceDir = path.resolve(base, `sema-host-${sanitizeId(id)}-${suffix}`);
+            this.workspaceDir = anchorUnder(path, base, `sema-host-${sanitizeId(id)}-${suffix}`);
             this.tenure = { kind: "held", root: this.workspaceDir };
         }
         const inheritEnvProblem = inheritEnvPolicyProblem(config.inheritEnv);
@@ -185,18 +192,14 @@ export class RemoteHostExecutionEnv {
             return unsupported("connect(snapshotId)");
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
-        if (config?.abortSignal?.aborted)
-            return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted") };
-        try {
-            await this.ensurePrepared();
-        }
-        catch (e) {
-            return { ok: false, error: new RemoteExecutionError("connect_failed", `failed to create host workspace ${this.workspaceDir}: ${errMsg(e)}`, asError(e)) };
-        }
-        if (config?.secrets?.length) {
-        }
+        return this.seat.connect(config);
+    }
+    preparedAnswer() {
         return ok(this.handle);
     }
+    prepareFailed(e) {
+        return { ok: false, error: new RemoteExecutionError("connect_failed", `failed to create host workspace ${this.workspaceDir}: ${errMsg(e)}`, asError(e)) };
+    }
     async suspendVM(_options) {
         return unsupported("suspendVM");
     }
@@ -1327,7 +1330,7 @@ export class RemoteHostExecutionEnv {
             return false;
         const real = (x) => {
             try {
-                return kernelRealPathOf(x);
+                return physicalPathOf(x);
             }
             catch {
                 return undefined;
@@ -1408,6 +1411,13 @@ export class RemoteHostExecutionEnv {
         return new FileError("unknown", msg, p);
     }
 }
+export function hostSeatPath(p, pathApi = path) {
+    if (pathApi.sep === "\\" && /^[A-Za-z]:(?![\\/])/.test(p)) {
+        const driveCwd = pathApi.resolve(p.slice(0, 2));
+        return p.length === 2 ? driveCwd : anchorUnder(pathApi, driveCwd, p.slice(2));
+    }
+    return anchoredPath(pathApi, process.cwd(), p);
+}
 function sanitizeId(id) {
     return id.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 64) || "task";
 }
@@ -1430,36 +1440,18 @@ function signalNumber(signal) {
 export function hostExecutionEnvFactory(config = {}, legOf = () => ({})) {
     const custody = createWorkspaceCustody();
     const heldElsewhere = (self, root) => custody.holder((m) => m !== self && m.heldWorkspace === root) !== undefined;
+    const rootHolding = (dir) => custody.holder((m) => m.heldWorkspace !== undefined && pathIsWithin(m.heldWorkspace, dir, canonicalPathOf))?.heldWorkspace;
     return (ctx) => {
         const { minted, ...leg } = legOf(ctx);
         const identity = ctx.taskId ?? ctx.sessionId;
         return custody.envOf(identity, () => {
             const dir = leg.workspaceDir ?? config.workspaceDir;
-            const sharedRoot = dir === undefined ? undefined : custody.holder((m) => m.heldWorkspace !== undefined && dirWithin(dir, m.heldWorkspace))?.heldWorkspace;
+            const sharedRoot = dir === undefined ? undefined : rootHolding(hostSeatPath(dir));
             const env = new RemoteHostExecutionEnv({ ...config, ...leg, id: config.id ?? identity, custody: { heldElsewhere, ...(sharedRoot !== undefined ? { sharedRoot } : {}) } });
             minted?.(env);
             return env;
         });
     };
 }
-function dirWithin(dir, root) {
-    const inside = (d, r) => {
-        const rel = path.relative(r, d);
-        return rel === "" || (rel.split(path.sep)[0] !== ".." && !path.isAbsolute(rel));
-    };
-    return inside(path.resolve(dir), path.resolve(root)) || inside(physicalPathOf(dir), physicalPathOf(root));
-}
-function physicalPathOf(p) {
-    let head = path.resolve(p);
-    const tail = [];
-    while (!existsSync(head)) {
-        const up = path.dirname(head);
-        if (up === head)
-            return path.resolve(p);
-        tail.unshift(path.basename(head));
-        head = up;
-    }
-    return path.join(realpathSync(head), ...tail);
-}
 export { localDockerExecutionEnvFactory, RemoteLocalDockerExecutionEnv } from "./remote-env-local-docker.js";
 //# sourceMappingURL=remote-env-host.js.map