@sema-agent/server 7.149.0 → 7.151.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,9 +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;
@@ -88,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",
@@ -109,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 };
 }
@@ -136,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;
@@ -149,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();
@@ -174,7 +188,7 @@ export class RemoteDeviceExecutionEnv {
             "performing a NON-atomic write here is exactly the silent downgrade guarded writes exist to prevent (#157). Refusing; the per-task factory mints a correctly-shaped env on the next task.", absPath);
     }
     resolve(p) {
-        return isDeviceAbsolutePath(p) ? posix.normalize(p) : posix.normalize(posix.join(this.cwd, p));
+        return anchoredPath(DEVICE_PATH_FAMILY, this.cwd, p);
     }
     instructionCwd(requested) {
         return requested === undefined ? this.cwd : this.resolve(requested);
@@ -183,7 +197,7 @@ export class RemoteDeviceExecutionEnv {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
-        return ok(posix.join(...parts));
+        return ok(joinedPath(DEVICE_PATH_FAMILY, parts));
     }
     workspaceHandle() {
         return {
@@ -195,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;
@@ -557,7 +566,7 @@ export class RemoteDeviceExecutionEnv {
                 return this.wrongOutcome("stat", o.kind, abs);
             if (!o.info)
                 return { ok: false, error: new FileError("unknown", "device returned a stat outcome without info — protocol violation", abs) };
-            return ok(toFileInfo(o.info));
+            return ok(toFileInfo(o.info, abs));
         });
     }
     async doReadLink(p, abortSignal) {
@@ -576,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)
@@ -642,7 +741,7 @@ export class RemoteDeviceExecutionEnv {
                 return this.wrongOutcome("stat", o.kind, abs);
             if (!o.entries)
                 return { ok: false, error: new FileError("unknown", "device returned a stat outcome without entries — protocol violation", abs) };
-            return ok(o.entries.map(toFileInfo));
+            return ok(o.entries.map((w) => toFileInfo(w, anchorUnder(DEVICE_PATH_FAMILY, abs, posix.basename(w.path)))));
         });
     }
     async writeFile(p, content, abortSignal) {
@@ -738,8 +837,9 @@ function mergedEnv(taskEnv, commandEnv) {
 function markTruncated(text, truncated) {
     return truncated === true ? `${text}\n[output truncated by the device executor]` : text;
 }
-function toFileInfo(w) {
-    return { name: posix.basename(w.path), path: w.path, kind: w.kind === "dir" ? "directory" : w.kind === "symlink" ? "symlink" : "file", size: w.size, mtimeMs: w.mtimeMs };
+const DEVICE_PATH_FAMILY = { sep: posix.sep, isAbsolute: isDeviceAbsolutePath };
+function toFileInfo(w, at) {
+    return { name: posix.basename(at), path: at, kind: w.kind === "dir" ? "directory" : w.kind === "symlink" ? "symlink" : "file", size: w.size, mtimeMs: w.mtimeMs };
 }
 function toWireExpectation(e) {
     return {

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";
@@ -45,7 +45,7 @@ export interface RemoteContainerEnvConfig extends RemoteEnvObservers, LaneHomeCo
     template?: string;
     /** Sandbox lifetime in ms (E2B billing window). Default {@link DEFAULT_TIMEOUT_MS}. */
     timeoutMs?: number;
-    /** Workspace root inside the VM; remote paths normalize against it. Default {@link DEFAULT_MOUNT_PATH}. */
+    /** Workspace root inside the VM; a relative path is anchored at it (`exec-path-law.ts`: anchored, never folded). Default {@link DEFAULT_MOUNT_PATH}. */
     mountPath?: string;
     /** Outbound network for the sandbox (clay: service needs external-network capability). Default `true`. */
     allowInternetAccess?: boolean;
@@ -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?: {
@@ -365,6 +374,8 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     private ensureConnected;
     private fsReady;
     private tempResult;
+    /** 提供方的条目 → `FileInfo`。`path` 取本环境的拼法(`at`:被问的那只路径 / 列目录时锚在它之下的条目),不取提供方回报的那一份
+     *  —— 提供方可能已把 `..` 折掉,而执行缝路径律(`exec-path-law.ts`)要求条目名在交来的路径之下、能原样再交回来。 */
     private toFileInfo;
     private fileError;
     /** A thrown provider error → this exec's error. The two cuts (aborted, the provider's own command deadline) are a command that RAN: they carry what it had

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

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { anchoredPath, anchorUnder, joinedPath } from "./exec-path-law.js";
 import { Sandbox, CommandExitError, FileType } from "e2b";
 import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { capabilitiesFor } from "../execution-lane-caps.js";
@@ -6,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";
@@ -36,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;
@@ -155,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 {
@@ -199,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;
@@ -255,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;
@@ -268,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) {
@@ -279,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());
         }
@@ -328,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;
@@ -382,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);
@@ -862,7 +860,7 @@ export class RemoteContainerExecutionEnv {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
-        return ok(path.posix.join(...parts));
+        return ok(joinedPath(path.posix, parts));
     }
     async readTextFile(p, abortSignal) {
         const sbx = await this.fsReady(p);
@@ -934,8 +932,9 @@ export class RemoteContainerExecutionEnv {
         if (!sbx.ok)
             return sbx;
         try {
-            const info = await this.rpc("files.getInfo", (signal) => sbx.value.files.getInfo(this.resolve(p), { signal }), abortSignal);
-            return ok(this.toFileInfo(info));
+            const abs = this.resolve(p);
+            const info = await this.rpc("files.getInfo", (signal) => sbx.value.files.getInfo(abs, { signal }), abortSignal);
+            return ok(this.toFileInfo(info, abs));
         }
         catch (e) {
             return { ok: false, error: this.fileError(e, this.resolve(p), abortSignal) };
@@ -946,8 +945,9 @@ export class RemoteContainerExecutionEnv {
         if (!sbx.ok)
             return sbx;
         try {
-            const entries = await this.rpc("files.list", (signal) => sbx.value.files.list(this.resolve(p), { signal }), abortSignal);
-            return ok(entries.map((e) => this.toFileInfo(e)));
+            const abs = this.resolve(p);
+            const entries = await this.rpc("files.list", (signal) => sbx.value.files.list(abs, { signal }), abortSignal);
+            return ok(entries.map((e) => this.toFileInfo(e, anchorUnder(path.posix, abs, e.name))));
         }
         catch (e) {
             return { ok: false, error: this.fileError(e, this.resolve(p), abortSignal) };
@@ -965,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 });
@@ -1044,7 +1057,7 @@ export class RemoteContainerExecutionEnv {
         return this.tempResult(r, "mktemp");
     }
     resolve(p) {
-        return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
+        return anchoredPath(path.posix, this.cwd, p);
     }
     async rpc(label, op, userSignal, timeoutMs = this.cfg.rpcTimeoutMs) {
         const deadline = new AbortController();
@@ -1163,11 +1176,11 @@ export class RemoteContainerExecutionEnv {
             return { ok: false, error: new FileError("unknown", r.value.stderr.trim() || `${op} failed`) };
         return ok(r.value.stdout.trim());
     }
-    toFileInfo(e) {
+    toFileInfo(e, at) {
         const kind = e.symlinkTarget ? "symlink" : e.type === FileType.DIR ? "directory" : "file";
         return {
             name: e.name,
-            path: e.path,
+            path: at,
             kind,
             size: e.size ?? 0,
             mtimeMs: e.modifiedTime ? e.modifiedTime.getTime() : 0,

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";