@sema-agent/server 7.137.0 → 7.139.0

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;
@@ -104,18 +107,22 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
      * (RPC 断、传输掉),不是「一个它看不见的命名空间」⇒ 读边界的执行期复核**拒**,而不是让词法判决站着。
      * 缺席是今天每个适配器的读法(整链沉默 ⇒ 词法判决成立、命令照跑),所以这一声明是**收紧**方向。
      * 严格读法 `=== true`(core `canonicalPathIsAuthoritative`);`isSuspendable` 一族同样严格,对本仓的
-     * 布尔字面量零影响(三键都写死字面 `true`/`false`,不存在「非布尔值被读成缺席」那一形 —— 那一形由
+     * 布尔字面量零影响(四键都写死字面 `true`/`false`,不存在「非布尔值被读成缺席」那一形 —— 那一形由
      * core 的 `config.execution_env_capability_invalid` 普查响亮播报,本仓的受众表已登记)。
      * 谁该声明由闭集门看着(`test/execution-lane-caps.test.ts` 的逐 lane 对账:新 lane 不表态 = 编译红)。
      */
+    /** `sharesProcessTable`(core 7.57.0,必填):命令跑在注册设备上(设备执行器),不在本进程所在的进程表。 */
+    /** 能力块(引擎 [ref],八键必填、各键只经引擎读器读):`hostLocalPaths` = 这条车道答出的路径是不是本进程所在机器上的文件;`externalContentTarget` = 产出是否来自部署信任边界之外;`io` = 文件与 shell 两面真到达目标;`keepsReadFloor` = 是否守住读拒表的字节地板(本车道不守 ⇒ 读拒表非空的 run 被告知,部署要求地板时准备期拒)。 */
     readonly capabilities: {
-        isolation: boolean;
-        suspendable: boolean;
-        canonicalPathAuthoritative: boolean;
+        isolation: false;
+        suspendable: false;
+        canonicalPathAuthoritative: true;
+        sharesProcessTable: false;
+        hostLocalPaths: false;
+        externalContentTarget: true;
+        io: true;
+        keepsReadFloor: false;
     };
-    readonly externalContentTarget = true;
-    /** [ref]:设备路径不在 worker 宿主文件系统上 —— host-path 回执消费方据此拒绝把它当宿主路径呈现。 */
-    readonly hostLocalPaths = false;
     cwd: string;
     /** 可选面(presence-typed,见文件头「铁律」段):构造期按设备声明装配,缺席就是缺席。 */
     readLink?: (path: string, abortSignal?: AbortSignal) => Promise<Result<string, FileError>>;
@@ -330,11 +337,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,8 @@
 import { posix } from "node:path";
 import { ExecutionError, FileError, RemoteExecutionError, } from "@sema-agent/core";
 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 +128,7 @@ export class RemoteDeviceExecutionEnv {
     homeDir;
     cdPath = "unknown";
     withheldEnv = [];
-    capabilities = { isolation: false, suspendable: false, canonicalPathAuthoritative: true };
-    externalContentTarget = true;
-    hostLocalPaths = false;
+    capabilities = { isolation: false, suspendable: false, canonicalPathAuthoritative: true, sharesProcessTable: false, hostLocalPaths: false, externalContentTarget: true, io: true, keepsReadFloor: false };
     cwd;
     readLink;
     writeFileExclusive;
@@ -227,7 +227,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 +303,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 +382,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 +799,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 +822,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

@@ -135,10 +135,17 @@ export declare class RemoteContainerExecutionEnv implements RemoteExecutionEnv,
     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,必填):命令跑在云沙箱里,不在本进程所在的进程表。 */
+    /** 能力块(引擎 [ref],八键必填、各键只经引擎读器读):`hostLocalPaths` = 这条车道答出的路径是不是本进程所在机器上的文件;`externalContentTarget` = 产出是否来自部署信任边界之外;`io` = 文件与 shell 两面真到达目标;`keepsReadFloor` = 是否守住读拒表的字节地板(本车道不守 ⇒ 读拒表非空的 run 被告知,部署要求地板时准备期拒)。 */
     readonly capabilities: {
-        isolation: boolean;
-        suspendable: boolean;
-        canonicalPathAuthoritative: boolean;
+        isolation: true;
+        suspendable: true;
+        canonicalPathAuthoritative: true;
+        sharesProcessTable: false;
+        hostLocalPaths: false;
+        externalContentTarget: false;
+        io: true;
+        keepsReadFloor: false;
     };
     workspaceHandle(): WorkspaceHandle;
     /**
@@ -252,7 +259,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>>;
@@ -338,6 +352,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;
 }

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

@@ -2,8 +2,9 @@ import path from "node:path";
 import { Sandbox, CommandExitError, FileType } from "e2b";
 import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { fileErrorFromExec } from "./remote-env-file-error.js";
-import { numEnvOr, runSymlinkChain, shellQuote } from "./remote-shell.js";
+import { appendFileStaged, 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";
 const PROVIDER = "e2b";
 const DEFAULT_MOUNT_PATH = "/home/user";
@@ -46,7 +47,7 @@ export class RemoteContainerExecutionEnv {
         this.homeDir = config.homeDir;
         this.sandboxApi = deps.sandboxApi ?? Sandbox;
     }
-    capabilities = { isolation: true, suspendable: true, canonicalPathAuthoritative: true };
+    capabilities = { isolation: true, suspendable: true, canonicalPathAuthoritative: true, sharesProcessTable: false, hostLocalPaths: false, externalContentTarget: false, io: true, keepsReadFloor: false };
     workspaceHandle() {
         if (!this.handle) {
             throw new RemoteExecutionError("connect_failed", "workspaceHandle() called before connect()");
@@ -251,6 +252,8 @@ export class RemoteContainerExecutionEnv {
                 stderr: { tail: new RollingTailBuffer(), total: 0, cursor: 0 },
             }
             : undefined;
+        let started;
+        const captured = () => ({ stdout: started?.stdout ?? "", stderr: started?.stderr ?? "" });
         let detached = false;
         const teePush = (s, d) => {
             const b = Buffer.from(d, "utf8");
@@ -299,10 +302,10 @@ export class RemoteContainerExecutionEnv {
             this.settleAbandonedStart(starting);
             const cut = e instanceof RemoteExecutionError && e.code === "timeout" && !options?.abortSignal?.aborted;
             if (!cut)
-                return { ok: false, error: this.execError(e, options?.abortSignal) };
-            const bc = boundCut(first);
-            return { ok: false, error: new ExecutionError(bc.code, bc.message, undefined, undefined, bc.noOutputSec) };
+                return { ok: false, error: this.execError(e, options?.abortSignal, captured()) };
+            return { ok: false, error: createCutError(boundCut(first), captured()) };
         }
+        started = handle;
         const onAbort = () => { if (!detached)
             void handle.kill().catch(() => { }); };
         if (options?.abortSignal) {
@@ -352,6 +355,7 @@ export class RemoteContainerExecutionEnv {
                 disarmed: () => detached,
                 ...(tee ? { wall: { totalMs: this.commandTimeoutMs(options?.timeout), leftMs: Math.max(0, this.commandTimeoutMs(options?.timeout) - (Date.now() - startedAt)) } } : {}),
                 liveness: bounds.liveness,
+                captured,
             });
             const winner = await (detachedP ? Promise.race([fg, detachedP]) : fg);
             if (winner === "detached") {
@@ -365,18 +369,18 @@ export class RemoteContainerExecutionEnv {
                 });
             }
             if (options?.abortSignal?.aborted && !detached) {
-                return { ok: false, error: new ExecutionError("aborted", "exec aborted (remote process killed)") };
+                return { ok: false, error: createCutError({ code: "aborted", message: "exec aborted (remote process killed)" }, captured()) };
             }
             return ok({ stdout: winner.stdout, stderr: winner.stderr, exitCode: winner.exitCode });
         }
         catch (e) {
             if (options?.abortSignal?.aborted && !detached) {
-                return { ok: false, error: this.execError(e, options.abortSignal) };
+                return { ok: false, error: this.execError(e, options.abortSignal, captured()) };
             }
             if (e instanceof CommandExitError) {
                 return ok({ stdout: e.stdout, stderr: e.stderr, exitCode: e.exitCode });
             }
-            return { ok: false, error: this.execError(e, options?.abortSignal) };
+            return { ok: false, error: this.execError(e, options?.abortSignal, captured()) };
         }
         finally {
             fgSettled = true;
@@ -659,37 +663,33 @@ export class RemoteContainerExecutionEnv {
             return { ok: false, error: this.fileError(e, this.resolve(p), abortSignal) };
         }
     }
+    stagedLane(sbx, content) {
+        const data = typeof content === "string" ? content : toArrayBuffer(content);
+        return {
+            upload: async (dest, signal) => {
+                try {
+                    await this.rpc("files.write", (s) => sbx.files.write(dest, data, { signal: s }), signal, this.cfg.dataTimeoutMs);
+                    return ok(undefined);
+                }
+                catch (e) {
+                    return { ok: false, error: this.fileError(e, dest, signal) };
+                }
+            },
+            run: (cmd, signal) => this.exec(cmd, { cwd: "/", ...(signal !== undefined ? { abortSignal: signal } : {}) }),
+        };
+    }
     async writeFile(p, content, abortSignal) {
         const sbx = await this.fsReady(p);
         if (!sbx.ok)
             return sbx;
-        try {
-            const data = typeof content === "string" ? content : toArrayBuffer(content);
-            await this.rpc("files.write", (signal) => sbx.value.files.write(this.resolve(p), data, { signal }), abortSignal, this.cfg.dataTimeoutMs);
-            return ok(undefined);
-        }
-        catch (e) {
-            return { ok: false, error: this.fileError(e, this.resolve(p), abortSignal) };
-        }
+        return writeFileStaged(this.stagedLane(sbx.value, content), this.resolve(p), abortSignal);
     }
     async appendFile(p, content, abortSignal) {
+        const sbx = await this.fsReady(p);
+        if (!sbx.ok)
+            return sbx;
         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);
+        return appendFileStaged(this.stagedLane(sbx.value, content), abs, abortSignal, (ctx) => rewriteAppend((signal) => this.readBinaryFile(abs, signal), (bytes, signal) => this.stagedLane(sbx.value, bytes).upload(abs, signal), content, ctx));
     }
     async fileInfo(p, abortSignal) {
         const sbx = await this.fsReady(p);
@@ -851,16 +851,15 @@ export class RemoteContainerExecutionEnv {
     async waitWithLiveness(handle, lastProgress, opts) {
         let timer;
         let wallTimer;
-        const liveness = opts?.liveness;
+        const liveness = opts.liveness;
         const idle = new Promise((_, reject) => {
             const arm = (bound) => {
                 timer = setTimeout(() => {
-                    if (opts?.disarmed?.())
+                    if (opts.disarmed?.())
                         return;
                     const idleFor = Date.now() - lastProgress();
                     if (idleFor >= bound.ms) {
-                        const cut = buildLivenessCut(bound);
-                        reject(new ExecutionError(cut.code, cut.message, undefined, undefined, cut.noOutputSec));
+                        reject(createCutError(buildLivenessCut(bound), opts.captured()));
                         void handle.kill().catch(() => { });
                         this.cfg.metrics?.inc("remote_env_exec_idle_timeout_total", { provider: PROVIDER });
                     }
@@ -871,18 +870,18 @@ export class RemoteContainerExecutionEnv {
             };
             if (liveness !== undefined)
                 arm(liveness);
-            if (opts?.wall !== undefined) {
+            if (opts.wall !== undefined) {
                 const wall = opts.wall;
                 wallTimer = setTimeout(() => {
                     if (opts.disarmed?.())
                         return;
-                    reject(new ExecutionError("timeout", wallCutMessage(wall.totalMs)));
+                    reject(createCutError({ code: "timeout", message: wallCutMessage(wall.totalMs) }, opts.captured()));
                     void handle.kill().catch(() => { });
                 }, wall.leftMs);
             }
         });
         try {
-            return await Promise.race([opts?.waitP ?? handle.wait(), idle]);
+            return await Promise.race([opts.waitP ?? handle.wait(), idle]);
         }
         finally {
             if (timer)
@@ -953,15 +952,15 @@ export class RemoteContainerExecutionEnv {
             return new FileError("is_directory", msg, p);
         return new FileError("unknown", msg, p);
     }
-    execError(e, abortSignal) {
+    execError(e, abortSignal, captured) {
         if (e instanceof ExecutionError)
             return e;
         const msg = errMsg(e);
         const name = e?.name;
         if (abortSignal?.aborted || name === "AbortError")
-            return new ExecutionError("aborted", msg);
+            return createCutError({ code: "aborted", message: msg }, captured);
         if (providerTimedOut(e))
-            return new ExecutionError("timeout", msg);
+            return createCutError({ code: "timeout", message: msg }, captured);
         return new ExecutionError("unknown", msg, e instanceof Error ? e : undefined);
     }
     remoteError(e, code = "unknown") {

package/dist/plugins/remote-env-file-error.d.ts

@@ -18,6 +18,8 @@
 import { FileError, type ExecutionError, type RemoteExecutionError } from "@sema-agent/core";
 /** exec 层的错误码 → 文件层的码。只映射**有对应语义**的那些,其余落 `unknown`(诚实降级)。 */
 export declare function fileErrorFromExec(e: ExecutionError | RemoteExecutionError, path?: string): FileError;
+/** POSIX 的一个名字段上限(NAME_MAX,字节;Linux / macOS / 常见文件系统同值)。也是远端写的私有暂存目录名的上限(`remote-shell.ts` `buildStagingPaths`)。 */
+export declare const NAME_MAX_BYTES = 255;
 /**
  * core 7.56.0 [ref]:`ENAMETOOLONG` 的**一只读法**(本文件的 stderr 分类器与 host 车道的 errno 映射同调)—— 路径有一段超过 NAME_MAX(按 UTF-8 字节量)⇒
  * `name_too_long`:没有目录装得下这个名字,引擎读站把它读作缺席(与 `not_found` 同读);段都短、只是整条超 PATH_MAX ⇒ `unknown`(那种文件可能存在,从下层目录够得着)。

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

@@ -3,7 +3,7 @@ export function fileErrorFromExec(e, path) {
     const code = e.code === "aborted" ? "aborted" : "unknown";
     return new FileError(code, e.message, path, e);
 }
-const NAME_MAX_BYTES = 255;
+export const NAME_MAX_BYTES = 255;
 export function nameTooLongCode(p) {
     return p !== undefined && p.split(/[\\/]/).some((part) => Buffer.byteLength(part, "utf8") > NAME_MAX_BYTES) ? "name_too_long" : "unknown";
 }

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

@@ -71,14 +71,21 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      * (RPC 断、传输掉),不是「一个它看不见的命名空间」⇒ 读边界的执行期复核**拒**,而不是让词法判决站着。
      * 缺席是今天每个适配器的读法(整链沉默 ⇒ 词法判决成立、命令照跑),所以这一声明是**收紧**方向。
      * 严格读法 `=== true`(core `canonicalPathIsAuthoritative`);`isSuspendable` 一族同样严格,对本仓的
-     * 布尔字面量零影响(三键都写死字面 `true`/`false`,不存在「非布尔值被读成缺席」那一形 —— 那一形由
+     * 布尔字面量零影响(四键都写死字面 `true`/`false`,不存在「非布尔值被读成缺席」那一形 —— 那一形由
      * core 的 `config.execution_env_capability_invalid` 普查响亮播报,本仓的受众表已登记)。
      * 谁该声明由闭集门看着(`test/execution-lane-caps.test.ts` 的逐 lane 对账:新 lane 不表态 = 编译红)。
      */
+    /** `sharesProcessTable`(core 7.57.0,必填):命令是本进程 spawn 的子进程(同一张进程表),引擎的模式杀守卫对它照 NodeExecutionEnv 一样问 `pgrep`。 */
+    /** 能力块(引擎 [ref],八键必填、各键只经引擎读器读):`hostLocalPaths` = 这条车道答出的路径是不是本进程所在机器上的文件;`externalContentTarget` = 产出是否来自部署信任边界之外;`io` = 文件与 shell 两面真到达目标;`keepsReadFloor` = 是否守住读拒表的字节地板(本车道不守 ⇒ 读拒表非空的 run 被告知,部署要求地板时准备期拒)。 */
     readonly capabilities: {
-        isolation: boolean;
-        suspendable: boolean;
-        canonicalPathAuthoritative: boolean;
+        isolation: false;
+        suspendable: false;
+        canonicalPathAuthoritative: true;
+        sharesProcessTable: true;
+        hostLocalPaths: true;
+        externalContentTarget: false;
+        io: true;
+        keepsReadFloor: false;
     };
     /** R7 自唤醒: structural delegation to the injected scheduler backend. `hasScheduler(env)` checks BOTH the method
      *  presence (always, since we implement the interface) AND `schedulerCapabilities.supported===true` — which is only
@@ -297,8 +304,9 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
         maxLines?: number;
         abortSignal?: AbortSignal;
     }): Promise<Result<string[], FileError>>;
-    /** core `NodeExecutionEnv` 的绑定读器 —— 首次 {@link openBound} 时建(构造无副作用,只记 cwd)。 */
-    private boundReader;
+    /** core `NodeExecutionEnv` 的一只实例 —— 本车道把**落盘那一步**委托给它的两只面({@link openBound} 的持有读、{@link writeFile} 的整文件替换);
+     *  首次用时建(构造无副作用,只记 cwd)。门(`fsReady`)、在飞登记(`withInflightFs`)与工作区相对解析留在本适配器。 */
+    private coreFs;
     /**
      * core 7.50.0 `FileSystem.openBound`:开着并**持有**一只对象(叶链接不跟,开后身份对拍),调用方判的与读的是同一只对象 ——
      * LSP 会话的读口与路径附件只经它读,不实现 ⇒ 两者在本车道一律拒。
@@ -308,8 +316,15 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      */
     openBound(p: string, abortSignal?: AbortSignal): Promise<Result<BoundFileObject, FileError>>;
     readBinaryFile(p: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
-    /** [ref]:整只方法体(**含** `fsReady` 那道门)走 `withInflightFs` —— 登记必须与调用方同一同步段,
-     *  否则 destroy 的快照可能刚好在 `await this.fsReady(...)` 的让出点上取完。见那处头注。 */
+    /**
+     * 整文件替换:**整旧或整新;`aborted` ⇒ 目标未碰**。
+     * 🔴 **不重写**:落盘那一步委托 core `NodeExecutionEnv.writeFile`(同目录暂存 + fsync + rename;父目录自建;单跳链接改写它指的
+     * 常规文件、链接链 / 非常规文件 / rename 不可用的文件系统回落就地写;已有文件的权限位带过去)—— 该原语的唯一属主在 core。
+     * 本适配器只给它与其余写面同一的入口纪律:[ref] 在飞登记(整只方法体**含** `fsReady` 那道门走 `withInflightFs` —— 登记必须与
+     * 调用方同一同步段,否则 destroy 的快照可能刚好在 `await this.fsReady(...)` 的让出点上取完;见那处头注)、销毁后拒、工作区相对解析。
+     * 修前这里是裸 `fs.writeFile(abs, data, { signal })`:open 即 O_TRUNC,中途取消 / 出错 ⇒ 目标 = 新内容的前缀,原件不可恢复。
+     * 已知语义变化(与 core / CC 同形):rename 断开硬链接 —— 另一条链接留旧内容。
+     */
     writeFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
     /** [ref](写面一律 `withInflightFs`,见那处头注)。本面是唯一能在 `destroyed` **之后**过门的写面
      *  (`lingeringBgWrite`):那一族登记在 destroy 的快照**之后**,所以 destroy 不会去等它们 —— 正确,