@sema-agent/server 7.139.0 → 7.141.0

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

@@ -1,6 +1,9 @@
 import path from "node:path";
 import { Sandbox, CommandExitError, FileType } from "e2b";
 import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
+import { capabilitiesFor } from "../execution-lane-caps.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, rewriteAppend, numEnvOr, runSymlinkChain, shellQuote, writeFileStaged } from "./remote-shell.js";
 import { buildLivenessCut, commandBoundsOf, firstBoundOf, laneLivenessOf, LIVENESS_MS_DEFAULT } from "../exec-bounds.js";
@@ -19,7 +22,9 @@ const E2B_BG_PROVIDER_BACKSTOP_PAD_SEC = 30;
 const ok = (value) => ({ ok: true, value });
 export class RemoteContainerExecutionEnv {
     cwd;
-    homeDir;
+    get homeDir() {
+        return this.homeSeat.home;
+    }
     cdPath = "unknown";
     withheldEnv = [];
     cfg;
@@ -29,6 +34,8 @@ export class RemoteContainerExecutionEnv {
     keepAlive;
     handle;
     destroyed = false;
+    homeSeat;
+    homeRefusal;
     connecting;
     activeCommands = 0;
     paused = false;
@@ -44,10 +51,92 @@ export class RemoteContainerExecutionEnv {
         };
         this.laneLiveness = laneLivenessOf(this.cfg.livenessMs, "E2B_LIVENESS_MS");
         this.cwd = this.cfg.mountPath;
-        this.homeDir = config.homeDir;
+        this.homeSeat = new LaneHomeSeat(PROVIDER, config);
         this.sandboxApi = deps.sandboxApi ?? Sandbox;
+        this.floor = deps.readFloor ?? createSandboxReadFloor({ lane: PROVIDER, knob: config.sandboxReadFloor, ...(config.logger !== undefined ? { logger: config.logger } : {}) });
+        this.capabilities = capabilitiesFor({ remoteExec: { provider: PROVIDER }, sandboxReadFloor: config.sandboxReadFloor });
+    }
+    capabilities;
+    floor;
+    startIn(start, command, envs) {
+        const launch = this.floor.wrap(start);
+        return launch.ok ? ok(e2bFloorCommand(launch.value, command, envs)) : launch;
+    }
+    runIn(sbx, s, opts = {}) {
+        const { background, ...rest } = opts;
+        const o = { ...rest, ...(s.user !== undefined ? { user: s.user } : {}), ...(s.envs !== undefined ? { envs: s.envs } : {}) };
+        return background ? sbx.commands.run(s.cmd, { ...o, background: true }) : sbx.commands.run(s.cmd, o);
+    }
+    floorTransport(sbx) {
+        const bootstrap = async (command) => {
+            const s = this.startIn(BOOTSTRAP_START, command, undefined);
+            if (!s.ok)
+                return { ok: false, error: s.error.message };
+            try {
+                const r = await this.rpc("floor.bootstrap", (signal) => this.runIn(sbx, s.value, { signal, timeoutMs: this.cfg.rpcTimeoutMs }));
+                return { ok: true, exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr };
+            }
+            catch (e) {
+                if (e instanceof CommandExitError)
+                    return { ok: true, exitCode: e.exitCode, stdout: e.stdout, stderr: e.stderr };
+                return { ok: false, error: errMsg(e) };
+            }
+        };
+        return {
+            bootstrap,
+            place: async (dest, bytes) => {
+                const dir = path.posix.dirname(dest);
+                const tmp = `${dest}.${Math.random().toString(16).slice(2, 10)}`;
+                const mk = await bootstrap(`umask 022 && mkdir -p ${shellQuote(dir)}`);
+                if (!mk.ok || mk.exitCode !== 0)
+                    return { ok: false, error: mk.ok ? mk.stderr.trim() || `exit ${mk.exitCode}` : mk.error };
+                try {
+                    const ab = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+                    await this.rpc("files.write", (signal) => sbx.files.write(tmp, ab, { user: "root", signal }), undefined, this.cfg.dataTimeoutMs);
+                }
+                catch (e) {
+                    return { ok: false, error: errMsg(e) };
+                }
+                const mv = await bootstrap(`chmod 0755 ${shellQuote(tmp)} && mv -f ${shellQuote(tmp)} ${shellQuote(dest)}`);
+                return mv.ok && mv.exitCode === 0 ? { ok: true } : { ok: false, error: mv.ok ? mv.stderr.trim() || `exit ${mv.exitCode}` : mv.error };
+            },
+            openRelay: (identity, command, events) => {
+                let handle;
+                let closed = false;
+                const pending = [];
+                const user = (() => {
+                    switch (identity) {
+                        case "root":
+                            return { user: "root" };
+                        case "exec-user":
+                            return {};
+                    }
+                })();
+                sbx.commands
+                    .run(command, { background: true, stdin: true, timeoutMs: 0, ...user, onStdout: (d) => events.data(d) })
+                    .then((h) => {
+                    handle = h;
+                    if (closed)
+                        return void h.kill().catch(() => { });
+                    for (const line of pending.splice(0))
+                        void h.sendStdin(line).catch(() => { });
+                    h.wait().then(() => events.closed("relay exited"), (e) => events.closed(`relay exited: ${errMsg(e)}`));
+                }, (e) => events.closed(`relay start failed: ${errMsg(e)}`));
+                return {
+                    send: (line) => {
+                        if (handle !== undefined)
+                            void handle.sendStdin(line).catch(() => { });
+                        else
+                            pending.push(line);
+                    },
+                    close: () => {
+                        closed = true;
+                        void handle?.kill().catch(() => { });
+                    },
+                };
+            },
+        };
     }
-    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()");
@@ -60,8 +149,12 @@ export class RemoteContainerExecutionEnv {
     }
     async startBackground(command) {
         const conn = await this.ensureConnected();
-        if (conn.ok)
-            await conn.value.commands.run(command, { background: true });
+        if (!conn.ok)
+            return;
+        const s = this.startIn(engineStart(undefined), command, undefined);
+        if (!s.ok)
+            return void this.cfg.logger?.warn?.("remote_env_background_refused", { error: s.error.message });
+        await this.runIn(conn.value, s.value, { background: true });
     }
     async connect(config) {
         if (config?.snapshotId) {
@@ -69,6 +162,8 @@ export class RemoteContainerExecutionEnv {
         }
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
+        if (this.homeRefusal)
+            return { ok: false, error: this.homeRefusal };
         if (this.paused)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env is suspended (paused) — resumeVM(snapshotId) before use") };
         if (this.sbx)
@@ -95,6 +190,17 @@ export class RemoteContainerExecutionEnv {
                 await sbx.kill().catch(() => { });
                 return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
             }
+            const home = await this.homeVerdict(sbx, config?.abortSignal);
+            if (home !== undefined || this.destroyed) {
+                await sbx.kill().catch(() => { });
+                this.cfg.metrics?.inc("remote_env_connect_total", { provider: PROVIDER, result: "error" });
+                return { ok: false, error: home ?? new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
+            }
+            await this.floor.attach(this.floorTransport(sbx), { origin: "created", workspaceRoot: this.cfg.mountPath });
+            if (this.destroyed) {
+                await sbx.kill().catch(() => { });
+                return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
+            }
             this.sbx = sbx;
             this.paused = false;
             this.startKeepAlive();
@@ -147,6 +253,8 @@ export class RemoteContainerExecutionEnv {
     async resumeVM(snapshotId, options) {
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "env already destroyed") };
+        if (this.homeRefusal)
+            return { ok: false, error: this.homeRefusal };
         if (this.sbx && !this.paused && this.sbx.sandboxId === snapshotId)
             return ok(this.workspaceHandle());
         if (this.connecting)
@@ -164,11 +272,26 @@ export class RemoteContainerExecutionEnv {
                 await sbx.kill().catch(() => { });
                 return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during resume") };
             }
+            const restoredRoot = options?.priorHandle?.mountPath ?? this.cfg.mountPath;
+            await this.floor.attach(this.floorTransport(sbx), { origin: "resumed", workspaceRoot: restoredRoot });
+            if (this.destroyed) {
+                await sbx.kill().catch(() => { });
+                return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during resume") };
+            }
+            const home = await this.homeVerdict(sbx, options?.abortSignal);
+            if (this.destroyed) {
+                await sbx.kill().catch(() => { });
+                return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during resume") };
+            }
+            if (home !== undefined) {
+                await this.rpc("sandbox.pause", (signal) => sbx.pause({ signal }), undefined, this.cfg.dataTimeoutMs).catch((e) => this.cfg.logger?.warn?.("remote_env_home_refused_repause_failed", { sandboxId: sbx.sandboxId, error: errMsg(e) }));
+                this.cfg.metrics?.inc("remote_env_resume_total", { provider: PROVIDER, result: "error" });
+                return { ok: false, error: home };
+            }
             this.sbx = sbx;
             this.paused = false;
             this.startKeepAlive();
             this.cfg.logger?.info?.("remote_env_resume", { requested: snapshotId, connected: sbx.sandboxId });
-            const restoredRoot = options?.priorHandle?.mountPath ?? this.cfg.mountPath;
             this.cwd = restoredRoot;
             this.handle = { sandboxId: sbx.sandboxId, provider: PROVIDER, mountPath: restoredRoot, snapshotId, sessionToken: sbx.sandboxId };
             this.cfg.metrics?.inc("remote_env_resume_total", { provider: PROVIDER, result: "ok" });
@@ -196,6 +319,30 @@ export class RemoteContainerExecutionEnv {
             return { ok: false, error: this.remoteError(e, "post_resume_failed") };
         }
     }
+    async homeVerdict(sbx, signal) {
+        if (!this.homeSeat.asks)
+            return undefined;
+        let probe;
+        try {
+            const start = this.startIn(ADAPTER_START, LANE_HOME_PROBE_COMMAND, undefined);
+            if (!start.ok)
+                throw start.error;
+            const r = await this.rpc("sandbox.home", (s) => this.runIn(sbx, start.value, { signal: s }), signal);
+            probe = r.exitCode === 0 ? { ok: true, stdout: r.stdout } : { ok: false, reason: `exit ${r.exitCode}` };
+        }
+        catch (e) {
+            probe = { ok: false, reason: e instanceof CommandExitError ? `exit ${e.exitCode}` : errMsg(e) };
+        }
+        if (signal?.aborted)
+            return new RemoteExecutionError("aborted", "connect aborted while reading the sandbox's home");
+        const verdict = this.homeSeat.settle(probe);
+        if (verdict === undefined)
+            return undefined;
+        const error = new RemoteExecutionError("connect_failed", verdict.refusal);
+        if (verdict.answered)
+            this.homeRefusal = error;
+        return error;
+    }
     startKeepAlive() {
         this.stopKeepAlive();
         const everyMs = Math.max(30_000, Math.floor(this.cfg.timeoutMs * 0.8));
@@ -218,6 +365,7 @@ export class RemoteContainerExecutionEnv {
         this.destroyed = true;
         this.connecting = undefined;
         this.stopKeepAlive();
+        this.floor.dispose();
         await this.disposeBackgroundShells();
         const sbx = this.sbx;
         this.sbx = undefined;
@@ -238,12 +386,21 @@ export class RemoteContainerExecutionEnv {
         await this.destroy();
     }
     async exec(command, options) {
+        return this.execAs(engineStart(options?.readFloor), command, options);
+    }
+    execInternal(command, options) {
+        return this.execAs(ADAPTER_START, command, options);
+    }
+    async execAs(start, command, options) {
         if (options?.abortSignal?.aborted)
             return { ok: false, error: new ExecutionError("aborted", "exec aborted before start") };
         const conn = await this.ensureConnected();
         if (!conn.ok)
             return { ok: false, error: new ExecutionError("shell_unavailable", `remote connect failed: ${conn.error.message}`, conn.error) };
         const sbx = conn.value;
+        const launch = this.startIn(start, command, options?.env);
+        if (!launch.ok)
+            return launch;
         this.activeCommands++;
         const detachSignal = options?.detachSignal;
         const tee = detachSignal
@@ -268,10 +425,9 @@ export class RemoteContainerExecutionEnv {
         let starting;
         let startCut = false;
         try {
-            handle = await this.rpc("commands.run", () => (starting = sbx.commands.run(command, {
+            handle = await this.rpc("commands.run", () => (starting = this.runIn(sbx, launch.value, {
                 background: true,
                 cwd: this.resolve(options?.cwd ?? this.cwd),
-                ...(options?.env ? { envs: options.env } : {}),
                 timeoutMs: tee
                     ? Math.max(this.commandTimeoutMs(options?.timeout), (E2B_BG_MAX_TIMEOUT_SEC + E2B_BG_PROVIDER_BACKSTOP_PAD_SEC) * 1000)
                     : this.commandTimeoutMs(options?.timeout),
@@ -395,6 +551,9 @@ export class RemoteContainerExecutionEnv {
         if (!conn.ok)
             throw conn.error;
         const sbx = conn.value;
+        const launch = this.startIn(engineStart(undefined), command, options?.env);
+        if (!launch.ok)
+            throw new RemoteExecutionError("unsupported", launch.error.message, launch.error);
         const queue = [];
         let finished = false;
         let failure;
@@ -421,10 +580,9 @@ export class RemoteContainerExecutionEnv {
         let handle;
         let starting;
         try {
-            handle = await this.rpc("commands.run", () => (starting = sbx.commands.run(command, {
+            handle = await this.rpc("commands.run", () => (starting = this.runIn(sbx, launch.value, {
                 background: true,
                 cwd: this.resolve(options?.cwd ?? this.cwd),
-                ...(options?.env ? { envs: options.env } : {}),
                 timeoutMs: this.commandTimeoutMs(options?.timeout),
                 onStdout: (d) => push("stdout", d),
                 onStderr: (d) => push("stderr", d),
@@ -552,12 +710,14 @@ export class RemoteContainerExecutionEnv {
                 if (!conn.ok)
                     throw new Error(`remote connect failed: ${conn.error.message}`);
                 const sbx = conn.value;
+                const launch = self.startIn(engineStart(options?.readFloor), command, options?.env);
+                if (!launch.ok)
+                    throw launch.error;
                 const stdout = { tail: new RollingTailBuffer(), total: 0, cursor: 0 };
                 const stderr = { tail: new RollingTailBuffer(), total: 0, cursor: 0 };
-                const handle = await self.rpc("commands.run.bg", () => sbx.commands.run(command, {
+                const handle = await self.rpc("commands.run.bg", () => self.runIn(sbx, launch.value, {
                     background: true,
                     cwd: self.resolve(options?.cwd ?? self.cwd),
-                    ...(options?.env ? { envs: options.env } : {}),
                     timeoutMs: (ctx.bgTimeoutSec + E2B_BG_PROVIDER_BACKSTOP_PAD_SEC) * 1000,
                     onStdout: (d) => {
                         const b = Buffer.from(d, "utf8");
@@ -675,7 +835,7 @@ export class RemoteContainerExecutionEnv {
                     return { ok: false, error: this.fileError(e, dest, signal) };
                 }
             },
-            run: (cmd, signal) => this.exec(cmd, { cwd: "/", ...(signal !== undefined ? { abortSignal: signal } : {}) }),
+            run: (cmd, signal) => this.execInternal(cmd, { cwd: "/", ...(signal !== undefined ? { abortSignal: signal } : {}) }),
         };
     }
     async writeFile(p, content, abortSignal) {
@@ -717,7 +877,7 @@ export class RemoteContainerExecutionEnv {
     }
     async readLink(p, abortSignal) {
         const abs = this.resolve(p);
-        const r = await this.exec(`readlink -- ${shellQuote(abs)}`, { abortSignal });
+        const r = await this.execInternal(`readlink -- ${shellQuote(abs)}`, { abortSignal });
         if (!r.ok)
             return { ok: false, error: fileErrorFromExec(r.error, abs) };
         if (r.value.exitCode !== 0)
@@ -725,11 +885,11 @@ export class RemoteContainerExecutionEnv {
         return ok(r.value.stdout.trim());
     }
     async canonicalChain(p, abortSignal) {
-        return runSymlinkChain(this.resolve(p), (cmd) => this.exec(cmd, { abortSignal }));
+        return runSymlinkChain(this.resolve(p), (cmd) => this.execInternal(cmd, { abortSignal }));
     }
     async canonicalPath(p, abortSignal) {
         const abs = this.resolve(p);
-        const r = await this.exec(`realpath -- ${shellQuote(abs)}`, { abortSignal });
+        const r = await this.execInternal(`realpath -- ${shellQuote(abs)}`, { abortSignal });
         if (!r.ok)
             return { ok: false, error: fileErrorFromExec(r.error, abs) };
         if (r.value.exitCode !== 0) {
@@ -776,7 +936,7 @@ export class RemoteContainerExecutionEnv {
         const abs = this.resolve(p);
         if (options?.recursive) {
             const flags = options.force ? "-rf" : "-r";
-            const r = await this.exec(`rm ${flags} -- ${shellQuote(abs)}`, { abortSignal: options.abortSignal });
+            const r = await this.execInternal(`rm ${flags} -- ${shellQuote(abs)}`, { abortSignal: options.abortSignal });
             if (!r.ok)
                 return { ok: false, error: fileErrorFromExec(r.error, abs) };
             if (r.value.exitCode !== 0)
@@ -795,14 +955,14 @@ export class RemoteContainerExecutionEnv {
         }
     }
     async createTempDir(prefix = "tmp-", abortSignal) {
-        const r = await this.exec(`mktemp -d -t ${shellQuote(`${prefix}XXXXXX`)}`, { abortSignal });
+        const r = await this.execInternal(`mktemp -d -t ${shellQuote(`${prefix}XXXXXX`)}`, { abortSignal });
         return this.tempResult(r, "mktemp -d");
     }
     async createTempFile(options) {
         const prefix = options?.prefix ?? "";
         const suffix = options?.suffix ?? "";
         const suffixArg = suffix ? `--suffix=${shellQuote(suffix)} -t` : "-t";
-        const r = await this.exec(`mktemp ${suffixArg} ${shellQuote(`${prefix}XXXXXX`)}`, { abortSignal: options?.abortSignal });
+        const r = await this.execInternal(`mktemp ${suffixArg} ${shellQuote(`${prefix}XXXXXX`)}`, { abortSignal: options?.abortSignal });
         return this.tempResult(r, "mktemp");
     }
     resolve(p) {
@@ -905,7 +1065,7 @@ export class RemoteContainerExecutionEnv {
     async fsReady(p) {
         const conn = await this.ensureConnected();
         if (!conn.ok)
-            return { ok: false, error: new FileError("unknown", `remote connect failed: ${conn.error.message}`, this.resolve(p), conn.error) };
+            return { ok: false, error: fileErrorFromExec(conn.error, this.resolve(p)) };
         return ok(conn.value);
     }
     tempResult(r, op) {

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

@@ -15,7 +15,7 @@
  * 那条教训:宣布"类修完成"而三个实现只落了一个)。收成一处之后,判据只有一条 ——
  * **文件面的 exec 包装必须走这里**,而这条能被机器检查(见 `test/env-adapter-file-error-parity.test.ts`)。
  */
-import { FileError, type ExecutionError, type RemoteExecutionError } from "@sema-agent/core";
+import { FileError, RemoteExecutionError, type ExecutionError } 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`)。 */

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

@@ -1,6 +1,12 @@
-import { FileError } from "@sema-agent/core";
+import { FileError, RemoteExecutionError } from "@sema-agent/core";
+function neverOpened(e) {
+    if (e.code === "connect_failed")
+        return true;
+    const cause = e.cause;
+    return cause instanceof RemoteExecutionError && cause.code === "connect_failed";
+}
 export function fileErrorFromExec(e, path) {
-    const code = e.code === "aborted" ? "aborted" : "unknown";
+    const code = e.code === "aborted" ? "aborted" : neverOpened(e) ? "target_unavailable" : "unknown";
     return new FileError(code, e.message, path, e);
 }
 export const NAME_MAX_BYTES = 255;

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

@@ -1,4 +1,5 @@
 import { FileError, type InheritEnvPolicy, ExecutionError, RemoteExecutionError, SchedulerError, type SchedulerCapability, type ScheduledIntent, type SchedulerContext, type ScheduledTaskId, type ScheduledTaskSummary, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type BoundFileObject, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, BackgroundShellError, type BackgroundShellCapability, type BackgroundShellId, type BackgroundHardKillOutcome, type BackgroundPoll, type BackgroundSpawnOptions, type SecretEnvFinding } from "@sema-agent/core";
+import { type LaneHomeConfig } from "../lane-home-probe.js";
 /** Options accepted by `ExecutionEnv.exec` (core does not re-export the type; derive it from the seam). */
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 /** SIGTERM → grace → SIGKILL (no host isolation). 🔴 宽限的**唯一属主**:本 driver 的 `kill` 梯子用它排升级定时器;会话级收敛
@@ -6,7 +7,7 @@ type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
  *  这把梯子的用户面宽限取消),不另抄数。启动期读一次;`0` 被 `numEnvOr` 读作缺席(回落 1000),要几乎不等写 `1`。 */
 export declare const HOST_BG_KILL_GRACE_MS: number;
 /** Construction config for {@link RemoteHostExecutionEnv}. */
-export interface HostEnvConfig {
+export interface HostEnvConfig extends LaneHomeConfig {
     /**
      * Base directory under which this adapter creates its per-task working directory. Default {@link os.tmpdir}.
      * The actual workspace is `<workspaceBase>/sema-host-<id>` and is `rm -rf`'d on {@link destroy}.
@@ -24,15 +25,6 @@ export interface HostEnvConfig {
      * own `process.env` is the default base (a local coding agent inherits the user's environment).
      */
     env?: Record<string, string>;
-    /**
-     * [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;
     /** Per-command wall-clock bound (ms) when the caller gives none. Default {@link DEFAULT_COMMAND_TIMEOUT_MS}. */
     commandTimeoutMs?: number;
     /** Shell-child env policy — core's `InheritEnvPolicy`, read by core's `inheritedHostEnv` (the three words are judged
@@ -64,29 +56,8 @@ export interface HostEnvConfig {
     backgroundShell?: boolean;
 }
 export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, SchedulerCapability, BackgroundShellCapability {
-    /** [ref] §9 / DUAL-MODE-DESIGN §5: a `host` env is the operator's real machine — no isolation, no snapshot. */
-    /**
-     * 🔴 **[ref] / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
-     * 就是**命令真正跑的那块文件系统**的权威答案(worker 本机的 `fs.realpath`)。声明它 = 告诉引擎:整链答不出来是**解析器出了事**
-     * (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,必填):命令是本进程 spawn 的子进程(同一张进程表),引擎的模式杀守卫对它照 NodeExecutionEnv 一样问 `pgrep`。 */
-    /** 能力块(引擎 [ref],八键必填、各键只经引擎读器读):`hostLocalPaths` = 这条车道答出的路径是不是本进程所在机器上的文件;`externalContentTarget` = 产出是否来自部署信任边界之外;`io` = 文件与 shell 两面真到达目标;`keepsReadFloor` = 是否守住读拒表的字节地板(本车道不守 ⇒ 读拒表非空的 run 被告知,部署要求地板时准备期拒)。 */
-    readonly capabilities: {
-        isolation: false;
-        suspendable: false;
-        canonicalPathAuthoritative: true;
-        sharesProcessTable: true;
-        hostLocalPaths: true;
-        externalContentTarget: false;
-        io: true;
-        keepsReadFloor: false;
-    };
+    /** 能力块的唯一作者 = `capabilitiesFor`(`execution-lane-caps.ts`;逐键表态与理由在那里,本类零能力字面量)。 */
+    readonly capabilities: import("@sema-agent/core").ExecutionEnvCapabilities;
     /** 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
      *  true when a backend was injected, so a host env without one stays INERT (the four scheduler tools don't mount). */
@@ -98,8 +69,13 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     list(ctx: SchedulerContext): Promise<Result<ScheduledTaskSummary[], SchedulerError>>;
     /** Working directory; relative paths resolve against it (ExecutionEnv contract). Starts at the workspace root. */
     cwd: string;
-    /** core `ExecutionEnv.homeDir`([ref]):本沙箱/目标机上执行用户的 home。见配置同名字段。 */
-    readonly homeDir?: string | undefined;
+    /** core `ExecutionEnv.homeDir`([ref]):本机执行用户的 home —— 主张在场 ⇒ 主张(构造时与子进程拿到的 `HOME` 对证过),否则构造时读到的那个 `HOME`,见 {@link LaneHomeSeat}。 */
+    get homeDir(): string | undefined;
+    /** 家目录的座(主张在场 ⇒ 构造时对证 · 否则构造时实测)。读数 = {@link childHome}:本类自己组合给子进程的那份 env,不 spawn。 */
+    private readonly homeSeat;
+    /** 家目录:主张与子进程拿到的 `HOME` 对不上 ⇒ 这只环境的拒句;`shellReady` / `fsReady` / `connect` 三道门原样回它,一条命令、一次文件动作都不做。
+     *  读数是本类自己组合的 env(纯函数,同一份输入同一个答案)⇒ 构造时判一次、记一辈子。 */
+    private readonly homeRefusal;
     /**
      * core 7.49.0 [ref]:shell 子进程**真拿到的** `CDPATH` 条目(`[]` = 没有)—— 删除守卫按它解裸 `cd <dir>`。本车道的命令就是本机子进程,
      * env 是本类自己组合的(继承姿态 + `cfg.env`),所以说得出:读同一只组合({@link childEnv} 的**读面**,不披露、不钉 shell),切法与 core
@@ -454,6 +430,14 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      * 引擎对点到自有凭据名的白名单在这里**抛**(spawn 时的拒;构造器已先问过同一只判)—— 子进程不起,拒句带名。
      */
     private childEnv;
+    /**
+     * 家目录的读数:本类组合给子进程的那份 env 里的 `HOME`(组合层,不 spawn、不记剥除 —— 与 {@link cdPath} 同一只读面)。env 里没有 `HOME` ⇒ 读
+     * 账户的家目录(`os.userInfo().homedir`):那正是子进程的 shell 对缺席 `HOME` 的 `~` 展开(POSIX 取账户 passwd 行;win32 是账户的配置目录)。
+     * 不读 `os.homedir()`:它先读**服务进程自己的** `HOME` —— 子进程没继承到的那个值(对抗轮 r1 [high] 实测:服务 `HOME` 指别处 + `inheritEnv: []` 时两者分叉)。
+     * 账户查不到(无 passwd 行)⇒ 读不出(有主张 ⇒ 不开;没主张 ⇒ 座缺席 + warn)。
+     * 残余(引擎 `NodeExecutionEnv.homeDir` 注同一句):POSIX 上 `HOME` 缺席时 shell 里的 `$HOME` 字面量展开为空,与 `~` 不是一个值 —— 本读数按 `~` 记。
+     */
+    private childHome;
     private fileError;
 }
 /**

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

@@ -12,6 +12,8 @@ import { hostBackgroundShellEnabled, hostExecSpoolEnabled } from "../config.js";
 import { IS_WIN32, resolveHostShell, hostShell, pinHostShell, spawnGroupOptions, killTreeHard, killTreeSoft, hardKillGroupNow, collapseWin32EnvKeys, adoptHostForegroundChild } from "./host-platform.js";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
 import { FileError, NodeExecutionEnv, inheritEnvPolicyProblem, ExecutionError, RemoteExecutionError, RollingTailBuffer, walkSymlinkChain, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
+import { capabilitiesFor } from "../execution-lane-caps.js";
+import { LaneHomeSeat } from "../lane-home-probe.js";
 import { composeHostSubprocessEnv, hostSubprocessEnv, withheldFromHostSubprocess } from "../server-secret-env.js";
 import { nameTooLongCode } from "./remote-env-file-error.js";
 import { trackEphemeralHostWorkspace, untrackEphemeralHostWorkspace } from "./host-workspace-registry.js";
@@ -38,7 +40,7 @@ const UNSUPPORTED_SCHEDULER_CAPS = {
     maxScheduledHorizonSec: 0,
 };
 export class RemoteHostExecutionEnv {
-    capabilities = { isolation: false, suspendable: false, canonicalPathAuthoritative: true, sharesProcessTable: true, hostLocalPaths: true, externalContentTarget: false, io: true, keepsReadFloor: false };
+    capabilities = capabilitiesFor({ remoteExec: { provider: "host" } });
     get schedulerCapabilities() {
         return this.cfg.scheduler?.schedulerCapabilities ?? UNSUPPORTED_SCHEDULER_CAPS;
     }
@@ -58,7 +60,11 @@ export class RemoteHostExecutionEnv {
             : Promise.resolve({ ok: false, error: new SchedulerError("unsupported", "scheduler not enabled on this worker") });
     }
     cwd;
-    homeDir;
+    get homeDir() {
+        return this.homeSeat.home;
+    }
+    homeSeat;
+    homeRefusal;
     get cdPath() {
         const value = this.childEnv(undefined, undefined).CDPATH;
         return value === undefined || value === "" ? [] : value.split(":");
@@ -140,8 +146,9 @@ export class RemoteHostExecutionEnv {
         if (Array.isArray(config.inheritEnv))
             this.cfg.inheritEnv = [...config.inheritEnv];
         this.cwd = this.workspaceDir;
-        this.homeDir = config.homeDir;
         this.handle = { sandboxId: this.workspaceDir, provider: PROVIDER, mountPath: this.workspaceDir };
+        this.homeSeat = new LaneHomeSeat(PROVIDER, config, IS_WIN32 ? "win32" : "posix");
+        this.homeRefusal = this.homeSeat.settle(this.childHome())?.refusal;
     }
     workspaceHandle() {
         return this.handle;
@@ -151,6 +158,8 @@ export class RemoteHostExecutionEnv {
             return unsupported("connect(snapshotId)");
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
+        if (this.homeRefusal !== undefined)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", this.homeRefusal) };
         if (config?.abortSignal?.aborted)
             return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted") };
         try {
@@ -1253,6 +1262,8 @@ export class RemoteHostExecutionEnv {
     async shellReady() {
         if (this.destroyed)
             return { ok: false, error: new ExecutionError("shell_unavailable", "execution env already destroyed") };
+        if (this.homeRefusal !== undefined)
+            return { ok: false, error: new ExecutionError("shell_unavailable", this.homeRefusal) };
         try {
             try {
                 await resolveHostShell();
@@ -1284,6 +1295,8 @@ export class RemoteHostExecutionEnv {
         return (this.spoolRootDir !== undefined && inside(this.spoolRootDir)) || (this.persistent && inside(this.workspaceDir));
     }
     async fsReady(p, opts) {
+        if (this.homeRefusal !== undefined)
+            return { ok: false, error: new FileError("target_unavailable", this.homeRefusal, this.resolve(p)) };
         if (this.destroyed) {
             const lingering = opts?.lingeringBgWrite === true && this._bgManager?.hasShells() === true && this.isLingeringMirrorTarget(p);
             if (!lingering)
@@ -1313,6 +1326,16 @@ export class RemoteHostExecutionEnv {
             pinHostShell(base, spawnShell);
         return collapseWin32EnvKeys(base);
     }
+    childHome() {
+        try {
+            const env = this.childEnv(undefined, undefined);
+            const home = Object.entries(env).find(([k]) => (IS_WIN32 ? k.toUpperCase() : k) === "HOME")?.[1];
+            return { ok: true, value: home ?? os.userInfo().homedir };
+        }
+        catch (e) {
+            return { ok: false, reason: errMsg(e) };
+        }
+    }
     fileError(e, p, abortSignal) {
         if (e instanceof FileError)
             return e;