@sema-agent/server 7.138.0 → 7.140.0

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

@@ -1,9 +1,12 @@
 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 { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
 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";
@@ -18,7 +21,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;
@@ -28,6 +33,8 @@ export class RemoteContainerExecutionEnv {
     keepAlive;
     handle;
     destroyed = false;
+    homeSeat;
+    homeRefusal;
     connecting;
     activeCommands = 0;
     paused = false;
@@ -43,10 +50,10 @@ 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;
     }
-    capabilities = { isolation: true, suspendable: true, canonicalPathAuthoritative: true, sharesProcessTable: false };
+    capabilities = capabilitiesFor({ remoteExec: { provider: "e2b" } });
     workspaceHandle() {
         if (!this.handle) {
             throw new RemoteExecutionError("connect_failed", "workspaceHandle() called before connect()");
@@ -68,6 +75,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)
@@ -94,6 +103,12 @@ 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") };
+            }
             this.sbx = sbx;
             this.paused = false;
             this.startKeepAlive();
@@ -146,6 +161,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)
@@ -163,6 +180,16 @@ export class RemoteContainerExecutionEnv {
                 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();
@@ -195,6 +222,27 @@ 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 r = await this.rpc("sandbox.home", (s) => sbx.commands.run(LANE_HOME_PROBE_COMMAND, { 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));
@@ -251,6 +299,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 +349,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 +402,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 +416,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 +710,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 +898,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 +917,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)
@@ -906,7 +952,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) {
@@ -953,15 +999,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

@@ -15,9 +15,11 @@
  * 那条教训:宣布"类修完成"而三个实现只落了一个)。收成一处之后,判据只有一条 ——
  * **文件面的 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`)。 */
+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

@@ -1,9 +1,15 @@
-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);
 }
-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

@@ -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,24 +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`。 */
-    readonly capabilities: {
-        isolation: boolean;
-        suspendable: boolean;
-        canonicalPathAuthoritative: boolean;
-        sharesProcessTable: boolean;
-    };
+    /** 能力块的唯一作者 = `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). */
@@ -93,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
@@ -299,8 +280,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 会话的读口与路径附件只经它读,不实现 ⇒ 两者在本车道一律拒。
@@ -310,8 +292,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 不会去等它们 —— 正确,
@@ -441,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;
 }
 /**