@sema-agent/server 7.138.0 → 7.140.0

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

@@ -4,10 +4,12 @@ import fs from "node:fs/promises";
 import { spawn } from "node:child_process";
 import { hostSubprocessEnv } from "../server-secret-env.js";
 import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
-import { buildCwdEnvCommand, createCwdGuardedCall, shellQuote, armPipeDestroyGrace } from "./remote-shell.js";
+import { appendFileStaged, rewriteAppend, buildCwdEnvCommand, createCwdGuardedCall, shellQuote, armPipeDestroyGrace, writeFileStaged } from "./remote-shell.js";
 import { signalNumber } from "./host-platform.js";
 import { buildLivenessCut, commandBoundsOf } from "../exec-bounds.js";
+import { buildCapturedOutput, createCutError } from "../exec-cut.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
+import { capabilitiesFor } from "../execution-lane-caps.js";
 import { classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
 const PROVIDER = "adb";
@@ -20,14 +22,14 @@ function lazyConnectExecError(e) {
     return e.code === "aborted" ? new ExecutionError("aborted", e.message, e) : new ExecutionError("shell_unavailable", `ADB lazy-connect failed: ${e.message}`, e);
 }
 function lazyConnectFileError(e, absPath) {
-    return e.code === "aborted" ? new FileError("aborted", e.message, absPath, e) : new FileError("unknown", `ADB lazy-connect failed: ${e.message}`, absPath, e);
+    return fileErrorFromExec(e, absPath);
 }
 const isTcp = (serial) => /:\d+$/.test(serial);
 export function isAdbTransportLost(stderr) {
     return /device offline|device '.*' not found|no devices\/emulators found|connection reset|protocol fault|device disconnected/i.test(stderr);
 }
 export class RemoteAdbExecutionEnv {
-    capabilities = { isolation: false, suspendable: false, canonicalPathAuthoritative: true, sharesProcessTable: false };
+    capabilities = capabilitiesFor({ remoteExec: { provider: "adb" } });
     cwd;
     connected = false;
     destroyed = false;
@@ -36,6 +38,7 @@ export class RemoteAdbExecutionEnv {
         return this.homeSeat.home;
     }
     homeSeat;
+    homeRefusal;
     cdPath = "unknown";
     withheldEnv = [];
     cfg;
@@ -51,7 +54,7 @@ export class RemoteAdbExecutionEnv {
             retry: { maxAttempts: config.retry?.maxAttempts ?? 3, backoffMs: config.retry?.backoffMs ?? 800 },
         };
         this.cwd = this.cfg.mountPath;
-        this.homeSeat = new LaneHomeSeat({ lane: PROVIDER, declared: config.homeDir, verifiesDeclared: false, onAbsent: config.onHomeAbsent });
+        this.homeSeat = new LaneHomeSeat(PROVIDER, config);
         this.spawnFn = deps?.spawn ?? spawn;
         this.injectedConnectOnce = deps?.connectOnce;
     }
@@ -64,13 +67,22 @@ export class RemoteAdbExecutionEnv {
     async connect(config) {
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "ADB env destroyed — create a fresh env instead of reviving") };
+        if (this.homeRefusal)
+            return { ok: false, error: this.homeRefusal };
         const policy = {
             retryableCodes: ["auth_transient", "connect_failed", "timeout"],
             maxAttempts: this.cfg.retry.maxAttempts,
             backoffMs: (failed) => this.cfg.retry.backoffMs * failed,
         };
         const once = this.injectedConnectOnce ?? ((s) => this.connectOnce(s));
-        return withRetry((_attempt) => once(config?.abortSignal), policy, { signal: config?.abortSignal });
+        const refused = new AbortController();
+        const halt = config?.abortSignal ? AbortSignal.any([config.abortSignal, refused.signal]) : refused.signal;
+        return withRetry(async () => {
+            const r = await once(config?.abortSignal);
+            if (!r.ok && this.homeRefusal)
+                refused.abort();
+            return r;
+        }, policy, { signal: halt });
     }
     async ensureConnected() {
         if (this.destroyed)
@@ -126,7 +138,13 @@ export class RemoteAdbExecutionEnv {
                 const home = await this.adb(this.deviceShellArgs(LANE_HOME_PROBE_COMMAND), { signal, timeoutMs: this.cfg.commandTimeoutMs });
                 if (!home.ok && home.error.code === "aborted")
                     return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted while reading the device's home") };
-                this.homeSeat.settle(home.ok && home.value.exitCode === 0 ? { ok: true, stdout: home.value.stdout } : { ok: false, reason: home.ok ? `exit ${home.value.exitCode}` : home.error.message });
+                const verdict = this.homeSeat.settle(home.ok && home.value.exitCode === 0 ? { ok: true, stdout: home.value.stdout } : { ok: false, reason: home.ok ? `exit ${home.value.exitCode}` : home.error.message });
+                if (verdict !== undefined) {
+                    const error = new RemoteExecutionError("connect_failed", verdict.refusal);
+                    if (verdict.answered)
+                        this.homeRefusal = error;
+                    return { ok: false, error };
+                }
             }
             this.connected = true;
             return ok(this.workspaceHandle());
@@ -341,57 +359,46 @@ export class RemoteAdbExecutionEnv {
             lines = lines.slice(0, options.maxLines);
         return ok(lines);
     }
+    stagedLane(content) {
+        return { upload: (dest, signal) => this.push(content, dest, signal), run: (cmd, signal) => this.fsExec(cmd, signal) };
+    }
     async writeFile(p, content, abortSignal) {
+        const gated = await this.fsGate(p);
+        if (gated)
+            return gated;
+        return writeFileStaged(this.stagedLane(content), this.resolve(p), abortSignal);
+    }
+    async appendFile(p, content, abortSignal) {
         const gated = await this.fsGate(p);
         if (gated)
             return gated;
         const abs = this.resolve(p);
-        const dir = path.posix.dirname(abs);
-        if (dir && dir !== "." && dir !== "/") {
-            const mk = await this.fsExec(`mkdir -p ${shellQuote(dir)}`, abortSignal);
-            if (!mk.ok)
-                return { ok: false, error: fileErrorFromExec(mk.error, dir) };
-            if (mk.value.exitCode !== 0)
-                return { ok: false, error: new FileError("unknown", mk.value.stderr.trim() || `mkdir -p failed for ${dir}`, dir) };
-        }
-        let local;
+        return appendFileStaged(this.stagedLane(content), abs, abortSignal, (ctx) => rewriteAppend((signal) => this.readBinaryFile(abs, signal), (bytes, signal) => this.push(bytes, abs, signal), content, ctx));
+    }
+    async push(content, dest, abortSignal) {
+        let localDir;
         try {
-            local = path.join(os.tmpdir(), `adb-push-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+            localDir = await fs.mkdtemp(path.join(os.tmpdir(), "sema-adb-push-"));
+            const local = path.join(localDir, "data");
             await fs.writeFile(local, typeof content === "string" ? Buffer.from(content, "utf8") : Buffer.from(content));
-            const r = await this.adb(["-s", this.cfg.serial, "push", local, abs], { signal: abortSignal, timeoutMs: this.cfg.dataTimeoutMs });
+            const r = await this.adb(["-s", this.cfg.serial, "push", local, dest], { signal: abortSignal, timeoutMs: this.cfg.dataTimeoutMs });
             if (!r.ok)
-                return { ok: false, error: fileErrorFromExec(r.error, abs) };
+                return { ok: false, error: fileErrorFromExec(r.error, dest) };
             const out = `${r.value.stdout} ${r.value.stderr}`;
             if (/permission denied/i.test(out))
-                return { ok: false, error: new FileError("permission_denied", out.trim(), abs) };
+                return { ok: false, error: new FileError("permission_denied", out.trim(), dest) };
             if (r.value.exitCode !== 0)
-                return { ok: false, error: new FileError("unknown", r.value.stderr.trim() || `adb push failed for ${abs}`, abs) };
+                return { ok: false, error: new FileError("unknown", r.value.stderr.trim() || `adb push failed for ${dest}`, dest) };
             return ok(undefined);
         }
         catch (e) {
-            return { ok: false, error: new FileError("unknown", e instanceof Error ? e.message : String(e), abs) };
+            return { ok: false, error: new FileError("unknown", e instanceof Error ? e.message : String(e), dest) };
         }
         finally {
-            if (local)
-                await fs.rm(local, { force: true }).catch(() => { });
+            if (localDir)
+                await fs.rm(localDir, { recursive: true, force: true }).catch(() => { });
         }
     }
-    async appendFile(p, content, abortSignal) {
-        const abs = this.resolve(p);
-        const existing = await this.readBinaryFile(abs, abortSignal);
-        let base;
-        if (existing.ok)
-            base = existing.value;
-        else if (existing.error.code === "not_found")
-            base = new Uint8Array(0);
-        else
-            return existing;
-        const add = typeof content === "string" ? new TextEncoder().encode(content) : content;
-        const merged = new Uint8Array(base.length + add.length);
-        merged.set(base, 0);
-        merged.set(add, base.length);
-        return this.writeFile(abs, merged, abortSignal);
-    }
     posixFsInst;
     get posixFs() {
         return (this.posixFsInst ??= createPosixShellFs({
@@ -451,23 +458,44 @@ export class RemoteAdbExecutionEnv {
             const outBufs = [];
             const outTail = binary ? undefined : new RollingTailBuffer();
             const errBuf = new RollingTailBuffer();
-            const finish = (r) => {
+            const recordStderr = (bytes) => {
+                if (bytes.length > 0)
+                    errBuf.push(bytes);
+            };
+            const emitStderr = (bytes) => {
+                if (bytes.length > 0)
+                    opts?.onStderr?.(bytes.toString());
+            };
+            const takeStderr = (bytes) => {
+                recordStderr(bytes);
+                emitStderr(bytes);
+            };
+            const heldStderr = () => opts?.stderrFilter?.endStderr();
+            const captured = () => {
+                const held = heldStderr();
+                if (held)
+                    recordStderr(held);
+                return buildCapturedOutput(outTail, errBuf);
+            };
+            const finish = (outcome) => {
                 if (settled)
-                    return;
+                    return false;
                 settled = true;
+                const r = outcome();
                 clearTimeout(timer);
                 opts?.signal?.removeEventListener("abort", onAbort);
                 resolve(r);
+                return true;
             };
             const timeoutMs = opts?.timeoutMs ?? this.cfg.commandTimeoutMs;
-            const timer = setTimeout(() => {
-                killGrace();
-                finish({ ok: false, error: new ExecutionError("timeout", `adb ${args[0]} exceeded ${timeoutMs}ms`) });
-            }, timeoutMs);
-            const onAbort = () => {
-                killGrace();
-                finish({ ok: false, error: new ExecutionError("aborted", "adb command aborted") });
+            const cut = (c) => {
+                finish(() => {
+                    killGrace();
+                    return { ok: false, error: createCutError(c, captured()) };
+                });
             };
+            const timer = setTimeout(() => cut({ code: "timeout", message: `adb ${args[0]} exceeded ${timeoutMs}ms` }), timeoutMs);
+            const onAbort = () => cut({ code: "aborted", message: "adb command aborted" });
             if (opts?.signal) {
                 if (opts.signal.aborted)
                     return onAbort();
@@ -480,30 +508,27 @@ export class RemoteAdbExecutionEnv {
                     outTail.push(d);
                 opts?.onStdout?.(d.toString());
             });
-            const takeStderr = (bytes) => {
-                if (bytes.length === 0)
-                    return;
-                errBuf.push(bytes);
-                opts?.onStderr?.(bytes.toString());
-            };
             child.stderr.on("data", (d) => takeStderr(opts?.stderrFilter ? opts.stderrFilter.filterStderr(d) : d));
-            child.on("error", (e) => finish({ ok: false, error: new ExecutionError("spawn_error", `adb spawn failed (is '${this.cfg.adbPath}' installed?): ${e.message}`, e) }));
+            child.on("error", (e) => finish(() => ({ ok: false, error: new ExecutionError("spawn_error", `adb spawn failed (is '${this.cfg.adbPath}' installed?): ${e.message}`, e) })));
             child.on("close", (code, signal) => {
                 if (forceSettleTimer)
                     clearTimeout(forceSettleTimer);
-                if (opts?.stderrFilter)
-                    takeStderr(opts.stderrFilter.endStderr());
-                const err = errBuf.result();
-                const stderr = markTruncated(err.text, err.droppedBytes);
                 const exitCode = code ?? (signal ? 128 + (signalNumber(signal) ?? 9) : 0);
-                if (binary) {
-                    const stdoutBytes = Buffer.concat(outBufs);
-                    finish(ok({ stdout: stdoutBytes.toString("utf8"), stderr, exitCode, stdoutBytes: new Uint8Array(stdoutBytes) }));
-                }
-                else {
+                const held = heldStderr();
+                const won = finish(() => {
+                    if (held)
+                        recordStderr(held);
+                    const err = errBuf.result();
+                    const stderr = markTruncated(err.text, err.droppedBytes);
+                    if (binary) {
+                        const stdoutBytes = Buffer.concat(outBufs);
+                        return ok({ stdout: stdoutBytes.toString("utf8"), stderr, exitCode, stdoutBytes: new Uint8Array(stdoutBytes) });
+                    }
                     const out = outTail.result();
-                    finish(ok({ stdout: markTruncated(out.text, out.droppedBytes), stderr, exitCode }));
-                }
+                    return ok({ stdout: markTruncated(out.text, out.droppedBytes), stderr, exitCode });
+                });
+                if (won && held)
+                    emitStderr(held);
             });
         });
     }

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

@@ -1,6 +1,7 @@
 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 { 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";
 import type { DeviceWsHub } from "../device-ws-hub.js";
 import type { DeviceInstructionKind, DeviceOutcomeErrorCode } from "../device-ws-protocol.js";
 /** `WorkspaceHandle.provider` 与 `REMOTE_EXEC` 词表的那一个词,单点。 */
@@ -57,6 +58,8 @@ export interface DeviceEnvFactoryDeps {
     homeDir?: string;
     hub: DeviceWsHub;
     store: DeviceStore;
+    /** 会话店的执行席(绑定的唯一载体与唯一读;装配点交会话店的 `executionPlacement`,与准入链同一只)。工厂只调它的 `read(root)`。 */
+    seat: Pick<ExecutionPlacementSeat, "read">;
     enrollment: DeviceEnrollment;
     /** 指令级默认超时(ms;`DEVICE_EXEC_TIMEOUT_MS`,§4.7)。core 的 per-command `timeout` 可收紧它。 */
     execTimeoutMs?: number;
@@ -92,32 +95,8 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
     /** core 7.56.0 [ref]:shell 子进程继承的环境里收不到的条目 —— 本车道 shell 的环境在设备上**构建**(本进程的 env 从不注入,只有引擎逐次交的 `env`
      *  这条显式授予),没有一条是从本进程继承的 ⇒ `[]`(core 契约:「`[]` when its shell environment is built rather than inherited」)。 */
     readonly withheldEnv: readonly [];
-    /**
-     * 🔴 `suspendable: false` 在 core 契约里**同时断言**「工作区在目标上外部持久」(remote-env.ts 的
-     * load-bearing 不变量)—— 设备工作区 = 员工机磁盘,真持久 ✅,park-only 降级腿因此合法可用。
-     * 谁要把 executor 的工作区改成临时目录,先来改这一行:那一刻这个 `false` 就变成谎话,park 赎回会
-     * 落到一个空工作区上而链路上没有任何一层会报错。
-     */
-    /**
-     * 🔴 **[ref] / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
-     * 就是**命令真正跑的那块文件系统**的权威答案(设备 WS 协议的**必答** `canonicalPath` op)。声明它 = 告诉引擎:整链答不出来是**解析器出了事**
-     * (RPC 断、传输掉),不是「一个它看不见的命名空间」⇒ 读边界的执行期复核**拒**,而不是让词法判决站着。
-     * 缺席是今天每个适配器的读法(整链沉默 ⇒ 词法判决成立、命令照跑),所以这一声明是**收紧**方向。
-     * 严格读法 `=== true`(core `canonicalPathIsAuthoritative`);`isSuspendable` 一族同样严格,对本仓的
-     * 布尔字面量零影响(四键都写死字面 `true`/`false`,不存在「非布尔值被读成缺席」那一形 —— 那一形由
-     * core 的 `config.execution_env_capability_invalid` 普查响亮播报,本仓的受众表已登记)。
-     * 谁该声明由闭集门看着(`test/execution-lane-caps.test.ts` 的逐 lane 对账:新 lane 不表态 = 编译红)。
-     */
-    /** `sharesProcessTable`(core 7.57.0,必填):命令跑在注册设备上(设备执行器),不在本进程所在的进程表。 */
-    readonly capabilities: {
-        isolation: boolean;
-        suspendable: boolean;
-        canonicalPathAuthoritative: boolean;
-        sharesProcessTable: boolean;
-    };
-    readonly externalContentTarget = true;
-    /** [ref]:设备路径不在 worker 宿主文件系统上 —— host-path 回执消费方据此拒绝把它当宿主路径呈现。 */
-    readonly hostLocalPaths = false;
+    /** 能力块的唯一作者 = `capabilitiesFor`(`execution-lane-caps.ts`;逐键表态与理由在那里,本类零能力字面量)。 */
+    readonly capabilities: import("@sema-agent/core").ExecutionEnvCapabilities;
     cwd: string;
     /** 可选面(presence-typed,见文件头「铁律」段):构造期按设备声明装配,缺席就是缺席。 */
     readLink?: (path: string, abortSignal?: AbortSignal) => Promise<Result<string, FileError>>;
@@ -332,11 +311,24 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
  * `DEVICE_ERROR_CODES` 闭集(装配 / 数据错误取 {@link DEVICE_FACTORY_CONFIG_CODES}:placement 根为空 · 有效工作目录非绝对路径),句子里的 `[码]` 与 `.code` 同值。修前抛裸 `Error`,码只在句子里
  * (有效工作目录那一只直到 7.135.0 仍是裸 `Error`;钉:本工厂与 {@link effectiveDeviceCwd} 的函数体里没有 `new Error(`)。
  *
- * 🔴 **续跑腿的投递围栏**(core 7.54.0 [ref] r3 / [ref],`ExecutionEnvFactoryContext.resumeWorkspace`):行记下了设备(`resumeWorkspace.deviceId`)⇒
- * 本工厂**只**在那台设备上铸 —— placement 根此刻绑的不是它(换绑过)⇒ 抛 typed `device.identity_mismatch`(换绑后赎回的同一个词,零新码),
- * 句子点名两台设备;不连另一台、不改道(新设备没有那个工作区)。读当前绑定只为判出这一拒与取属主,铸的设备恒是行记下的那一台。
- * 「绑的就是它但现在不在线」与新跑同形:构造成功、`connect()` 回 typed `device.offline`(从不连别的设备)。
- * 行没记设备(非设备车道 / 早于该字段的行)⇒ 不声明要兑现的设备,按普通路由走。句柄(`workspaceHandle()`)恒报连接真到达的设备,不抄 `resumeWorkspace`。
+ * 🔴 **工厂认设备不认住客**(读口一只 = 会话店执行席 `seat.read(root)`,与解析器 / 换绑门 / 执行放置读面 / 准入链同一只读):按 placement 根读**当前**格,
+ * 与这条腿带来的设备句柄 `honor` 比,不同即 typed 拒。判序(一次行读):
+ *   root  = ctx.placementRootSessionId                       // 空 ⇒ config.placement_root_invalid
+ *   honor = ctx.resumeWorkspace?.deviceId
+ *   cell  = seat.read(root).cell                             // 行不在 / 格缺 / mirror / writer(device, ∅) ⇒ device.not_bound(唯一读法 `boundDeviceOf`)
+ *   honor ≠ undefined ∧ 格上设备 ≠ honor                    ⇒ device.identity_mismatch(句点名两台,零连接)
+ *   readDeviceForAdmission(格上设备, 格上属主)
+ * 工厂**不**读 `task_run`、不读子代分区行、不按 `ctx.taskId`、不比化身、不比属主(住客谓词只用于写与 judged 复核,不是工厂的读者)。
+ * 续跑腿(core 7.54.0 [ref] r3 / [ref],`ExecutionEnvFactoryContext.resumeWorkspace`):行记下了设备 ⇒ 本工厂**只**在那台设备上铸 —— 根此刻绑的不是它(换绑过)
+ * ⇒ `device.identity_mismatch`(换绑后赎回的同一个词,零新码);不连另一台、不改道(新设备没有那个工作区)。「绑的就是它但现在不在线」与新跑同形:
+ * 构造成功、`connect()` 回 typed `device.offline`(从不连别的设备)。行没记设备(早于该字段的行)⇒ 引擎已命名的「行未记设备 ⇒ 普通路由」臂,按根读当前格。
+ * 句柄(`workspaceHandle()`)恒报连接真到达的设备,不抄 `resumeWorkspace`。
+ *
+ * 🔴 **过渡期(条件句)**:新派后代腿的放置句柄(引擎在 `ExecutionEnvFactoryContext` 上的放置工作区字段,`honor` 的第二来源)**只在本仓所基的引擎版本带它时**
+ * 进判序;本仓今天所基的引擎上下文没有这个字段 ⇒ `honor` 只取续跑腿的 `resumeWorkspace`,新派后代腿按根读当前格。本仓**不**注入任何替代见证、不造任何行
+ * (修在源头)。敞口(在那个字段到货之前成立):活过父 turn 的后台子代,在根换绑之后新派的腿会落到根当前设备 —— 换绑半边由换绑门的子代活性判关闭(归换绑门那一车),
+ * 删除半边另有票。字段到货后的形:`honor = ctx.resumeWorkspace?.deviceId ?? <放置句柄>.deviceId`,放置句柄的 provider 不是本车道 ⇒ 装配拒(`config.placement_root_invalid` 同级)。
+ * 本仓任何文本不得宣称工厂「一律按住客定址」。
  */
 export declare function deviceExecutionEnvFactory(deps: DeviceEnvFactoryDeps): ExecutionEnvFactory;
 /**

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

@@ -1,6 +1,9 @@
 import { posix } from "node:path";
 import { ExecutionError, FileError, RemoteExecutionError, } from "@sema-agent/core";
+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";
 export const DEVICE_PROVIDER = "device";
 const ok = (value) => ({ ok: true, value });
 const STREAM_PENDING_MAX_BYTES = 2 * 1024 * 1024;
@@ -126,9 +129,7 @@ export class RemoteDeviceExecutionEnv {
     homeDir;
     cdPath = "unknown";
     withheldEnv = [];
-    capabilities = { isolation: false, suspendable: false, canonicalPathAuthoritative: true, sharesProcessTable: false };
-    externalContentTarget = true;
-    hostLocalPaths = false;
+    capabilities = capabilitiesFor({ remoteExec: { provider: "device" } });
     cwd;
     readLink;
     writeFileExclusive;
@@ -227,7 +228,8 @@ export class RemoteDeviceExecutionEnv {
         }
         let admitted;
         try {
-            admitted = await this.cfg.enrollment.admitSession({ rootSessionId: this.cfg.rootSessionId, requester: this.cfg.owner });
+            const placement = await this.cfg.enrollment.readPlacement(this.cfg.rootSessionId);
+            admitted = await this.cfg.enrollment.admitSession({ rootSessionId: this.cfg.rootSessionId, placement, requester: this.cfg.owner });
         }
         catch (err) {
             return {
@@ -302,7 +304,7 @@ export class RemoteDeviceExecutionEnv {
             return { ok: false, error: new ExecutionError("shell_unavailable", "execution env already destroyed") };
         const failure = await this.ensureConnected();
         if (failure)
-            return { ok: false, error: new ExecutionError(failure.exec, failure.message) };
+            return { ok: false, error: createExecFailure(failure.exec, failure.message) };
         return undefined;
     }
     async fsGate(p) {
@@ -381,15 +383,14 @@ export class RemoteDeviceExecutionEnv {
             case "env_terminal":
                 return { ok: false, error: new ExecutionError("shell_unavailable", ENV_TERMINAL_MESSAGE) };
             case "rejected":
-                return { ok: false, error: new ExecutionError(DEVICE_REJECT_TO_EXEC_ERROR[res.reject.code], rejectText(res.reject)) };
+                return { ok: false, error: createExecFailure(DEVICE_REJECT_TO_EXEC_ERROR[res.reject.code], rejectText(res.reject)) };
             case "never_started":
             case "settled": {
                 const o = res.outcome;
-                if (!o.ok) {
-                    return { ok: false, error: new ExecutionError(DEVICE_OUTCOME_TO_EXEC_ERROR[o.errorCode], o.message, undefined, { stdout, stderr }) };
-                }
+                if (!o.ok)
+                    return { ok: false, error: createExecFailure(DEVICE_OUTCOME_TO_EXEC_ERROR[o.errorCode], o.message, res.kind === "settled" ? { stdout, stderr } : undefined) };
                 if (o.kind === "cancelled") {
-                    return { ok: false, error: new ExecutionError("aborted", `the device reported the command as ${o.state} after a cancel`, undefined, { stdout, stderr }) };
+                    return { ok: false, error: createCutError({ code: "aborted", message: `the device reported the command as ${o.state} after a cancel` }, { stdout, stderr }) };
                 }
                 if (o.kind !== "exec")
                     return { ok: false, error: new ExecutionError("unknown", `device returned a "${o.kind}" outcome for an exec — protocol violation`) };
@@ -799,17 +800,18 @@ export function deviceExecutionEnvFactory(deps) {
             throw deviceFactoryRefusal(DEVICE_FACTORY_CONFIG_CODES.PLACEMENT_ROOT_INVALID, `device lane: ExecutionEnvFactoryContext.placementRootSessionId is empty [${DEVICE_FACTORY_CONFIG_CODES.PLACEMENT_ROOT_INVALID}] — ` +
                 "the device placement is keyed on the run tree's placement root; defaulting to the child sessionId would read as a NEW placement (v2 §4.3.2 / core design/380 O1①)");
         }
-        const binding = await deps.store.getSessionBinding(rootSessionId);
+        const placement = await deps.seat.read(rootSessionId);
+        const binding = placement === undefined ? undefined : boundDeviceOf(placement.cell);
         if (!binding) {
             throw deviceFactoryRefusal(DEVICE_ERROR_CODES.NOT_BOUND, `device lane: no device binding for placement root ${rootSessionId} [${DEVICE_ERROR_CODES.NOT_BOUND}] — ` +
                 "the submit-time admission chain must bind the root session to a device before a run reaches the factory (v2 §4.3.2)");
         }
-        const recordedDevice = ctx.resumeWorkspace?.deviceId;
-        if (recordedDevice !== undefined && recordedDevice !== binding.deviceId) {
-            throw deviceFactoryRefusal(DEVICE_ERROR_CODES.IDENTITY_MISMATCH, `device lane: this resume rebuilds the workspace on device ${recordedDevice}, but placement root ${rootSessionId} is now bound to ${binding.deviceId} [${DEVICE_ERROR_CODES.IDENTITY_MISMATCH}] — ` +
+        const honor = ctx.resumeWorkspace?.deviceId;
+        if (honor !== undefined && honor !== binding.id) {
+            throw deviceFactoryRefusal(DEVICE_ERROR_CODES.IDENTITY_MISMATCH, `device lane: this resume rebuilds the workspace on device ${honor}, but placement root ${rootSessionId} is now bound to ${binding.id} [${DEVICE_ERROR_CODES.IDENTITY_MISMATCH}] — ` +
                 "a parked call does not follow a rebind (the new device has no copy of that workspace); finish or cancel the parked task, then start it again on the device now bound");
         }
-        const view = await deps.store.readDeviceForAdmission(binding.deviceId, binding.owner);
+        const view = await deps.store.readDeviceForAdmission(binding.id, binding.owner);
         if (!view) {
             throw deviceFactoryRefusal(DEVICE_ERROR_CODES.NOT_FOUND, `device lane: the bound device is gone or not owned by the binding's principal [${DEVICE_ERROR_CODES.NOT_FOUND}]`);
         }
@@ -821,13 +823,13 @@ export function deviceExecutionEnvFactory(deps) {
             hub: deps.hub,
             enrollment: deps.enrollment,
             rootSessionId,
-            deviceId: binding.deviceId,
+            deviceId: binding.id,
             owner: binding.owner,
             cwd: effectiveDeviceCwd(deps.perSessionCwd?.get(ctx.sessionId), ctx.parentCwd, view.row),
             ...(deps.homeDir === undefined ? {} : { homeDir: deps.homeDir }),
             ...(deps.perSessionShellEnv?.get(ctx.sessionId) === undefined ? {} : { shellEnv: deps.perSessionShellEnv.get(ctx.sessionId) }),
             execTimeoutMs,
-            supports: deps.hub.declaredSupports(binding.deviceId),
+            supports: deps.hub.declaredSupports(binding.id),
             ...(deps.logger === undefined ? {} : { logger: deps.logger }),
         });
     };

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

@@ -21,6 +21,7 @@
  */
 import { Sandbox, type SandboxOpts, type SandboxConnectOpts } from "e2b";
 import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type ExecutionEnvFactory, type VmLifecycleOptions, type BackgroundShellCapability, type BackgroundShellId, type BackgroundShellError, type BackgroundSpawnOptions, type BackgroundPoll } from "@sema-agent/core";
+import { type LaneHomeConfig } from "../lane-home-probe.js";
 /** Options accepted by `ExecutionEnv.exec` (core does not re-export the type; derive it from the seam). */
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 /** Minimal optional observability hooks (kept structural so the adapter stays standalone-testable). */
@@ -34,22 +35,13 @@ export interface RemoteEnvObservers {
     };
 }
 /** Construction config for {@link RemoteContainerExecutionEnv}. Secrets/resolved values are control-plane supplied. */
-export interface RemoteContainerEnvConfig extends RemoteEnvObservers {
+export interface RemoteContainerEnvConfig extends RemoteEnvObservers, LaneHomeConfig {
     /** E2B API key. Resolved by the trusted control plane from env — never baked into an image or committed. */
     apiKey: string;
     /** E2B template id (image). Defaults to the E2B base template. */
     template?: string;
     /** Sandbox lifetime in ms (E2B billing window). Default {@link DEFAULT_TIMEOUT_MS}. */
     timeoutMs?: number;
-    /**
-     * [ref]④ / core [ref] —— 本执行环境的 **home 目录**(`ExecutionEnv.homeDir` 座,绝对路径,本环境自己的
-     * 命名空间里)。`~/…` 形权限规则(`Edit(~/.ssh/**)`)对**跑在本 env 里的调用**就以它为基。
-     * 缺席 ⇒ 本 env 声明「我没有 home」,core 对 `~/` 规则判 `unreadable`(fail-closed 的 ask),
-     * 绝不回落引擎进程自己的 home(那在远端腿上是另一个用户的另一个目录 —— 静默守错目录正是 [ref] 的病)。
-     * 值由 `boot/execution-env.ts` 从**唯一属主** `execution-lane-caps.ts` 的 `executionLaneHomeDir` 递进来;
-     * adapter 不自算(两处各算一份 = 422 门与引擎对同一条规则给相反答案)。
-     */
-    homeDir?: string;
     /** Workspace root inside the VM; remote paths normalize against it. Default {@link DEFAULT_MOUNT_PATH}. */
     mountPath?: string;
     /** Outbound network for the sandbox (clay: service needs external-network capability). Default `true`. */
@@ -99,8 +91,9 @@ export interface RemoteContainerEnvDeps {
 export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv, BackgroundShellCapability {
     /** Current working directory for relative paths (FileSystem contract; mutable, core may reassign). */
     cwd: string;
-    /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
-    readonly homeDir?: string | undefined;
+    /** core `ExecutionEnv.homeDir`([ref]):沙箱里执行用户的 home —— 主张在场 ⇒ 主张(每只沙箱建起来 / 恢复时与沙箱里的 `$HOME` 对证过),
+     *  否则建沙箱那一拍实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没主张时沙箱建起来之前缺席)。 */
+    get homeDir(): string | undefined;
     /** core 7.49.0 [ref]:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在 e2b 沙箱里(模板镜像的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
@@ -123,6 +116,10 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
      *  and the post-await re-check in BOTH async-provision paths ({@link doConnect} and {@link doResumeVM}) against
      *  a destroy that races an in-flight provision/restore. */
     private destroyed;
+    /** 家目录的座(主张在场 ⇒ 每只沙箱对证 · 否则建沙箱那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。 */
+    private readonly homeSeat;
+    /** 家目录:沙箱答了而与主张不一致(或答的不是绝对路径)⇒ 这只环境的拒,记一次、此后每次连接 / 恢复原样回它(同一模板同一个答案:不再建沙箱、不再问)。 */
+    private homeRefusal?;
     /** In-flight connect/resume, memoized so concurrent lazy first-use OR resume provisions exactly one VM (no double-bill). */
     private connecting?;
     /** Count of exec/execStream calls in flight — `suspendVM` refuses while > 0 (council #4: never snapshot a running command). */
@@ -133,15 +130,8 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
      *  SAME env instance skips the reconnect and every later fs/exec runs against the dead VM. */
     private paused;
     constructor(config: RemoteContainerEnvConfig, deps?: RemoteContainerEnvDeps);
-    /** [ref] §9: E2B is a FULL RemoteExecutionEnv — an isolated, snapshot-suspendable microVM. (SSH/ADB
-     *  adapters declare {isolation:false, suspendable:false} — real machines/devices, not snapshotable.) */
-    /** `sharesProcessTable`(core 7.57.0,必填):命令跑在云沙箱里,不在本进程所在的进程表。 */
-    readonly capabilities: {
-        isolation: boolean;
-        suspendable: boolean;
-        canonicalPathAuthoritative: boolean;
-        sharesProcessTable: boolean;
-    };
+    /** 能力块的唯一作者 = `capabilitiesFor`(`execution-lane-caps.ts`;逐键表态与理由在那里,本类零能力字面量)。 */
+    readonly capabilities: import("@sema-agent/core").ExecutionEnvCapabilities;
     workspaceHandle(): WorkspaceHandle;
     /**
      * Public host for a port inside the sandbox (E2B reverse proxy → `<port>-<id>.e2b.app`). The LSP sidecar
@@ -212,6 +202,13 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /**
+     * 家目录:座要问({@link LaneHomeSeat.asks}:主张在场 ⇒ 对证;没主张 ⇒ 量到绝对路径为止)⇒ 在这只沙箱里问一次 `$HOME`(前台 `commands.run`,与命令同一个
+     * 模板缺省用户、同一份沙箱 env),读数交座。返回这只沙箱的拒(`connect_failed`,拒句 = 同一只判官的句子),或 `undefined`(照用)。
+     * 沙箱答了的拒记在环境上(同一模板同一个答案);没答上(非零退出 / RPC 失败 / 输出里没有标记行)⇒ 这一次不开、不记,下一次重问;调用方中止 ⇒ `aborted`、不交座。
+     * 上界 = 控制面 RPC 的墙钟(`rpcTimeoutMs`:问一个环境变量,不是跑用户命令)。
+     */
+    private homeVerdict;
     /** BL-31 — (re)start the periodic sandbox-lifetime extension. `setTimeout(timeoutMs)` resets the auto-kill window
      *  from now; we re-arm at ~80% of the (clamped, ≤1h) window so a long-held sandbox never expires mid-run. A no-op
      *  when paused/destroyed; `unref`'d so it never keeps the process alive; cleared on destroy. */
@@ -254,7 +251,14 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
         abortSignal?: AbortSignal;
     }): Promise<Result<string[], FileError>>;
     readBinaryFile(p: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
+    /** 暂存写的两只面(规则与提交脚本的唯一属主 = `remote-shell.ts` `writeFileStaged` / `appendFileStaged`;本腿是原生 SDK 腿,与四条
+     *  shell 腿共用的是这只编排,不是 `posix-shell-fs` 基座;父目录与私有暂存目录由编排的准备那一步建):上传 = `files.write` 整份写到私有目录里的
+     *  暂存件;提交 = 一次 `exec`。两者同一身份(`files.write` 与 `commands.run` 都不带 `user`,沙箱侧取同一个缺省用户)。 */
+    private stagedLane;
+    /** 整旧或整新(暂存 → 一次 `mv -f`)。修前 `files.write` 直落目标:上传中途断 / 取消时目标剩什么取决于沙箱侧的落地实现,本适配器不依赖它。 */
     writeFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** 追加(暂存要加的字节 → 一次 `cat >>`;inode 不换、已有字节不重写)。修前 = 读旧 + 拼 + 整份 `files.write`(O(文件);中途断 ⇒
+     *  半份)。目录不收新名字 / 私有目录收不成私有时的退路 = 旧形(`rewriteAppend`:读旧 + 拼 + 整份 `files.write` 到目标;只有写那一步经 `ctx.inPlace`)。 */
     appendFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
@@ -340,6 +344,8 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     private tempResult;
     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
+     *  written (`captured`, `createCutError`); an unclassified fault does not (its outcome is unknown, the engine reads no partial output from it). */
     private execError;
     private remoteError;
 }