@sema-agent/server 7.138.0 → 7.140.0

package/dist/plugins/remote-env-local-docker.d.ts

@@ -23,7 +23,7 @@ export interface LocalDockerEnvConfig extends LaneHomeConfig {
      * lane stays `local-docker` (`REMOTE_EXEC=local-docker` + `DOCKER_HOST`; the settings-schema lane table lists
      * `DOCKER_HOST` as this lane's optional coordinate, and there is no separate `remote-docker` lane since 7.0.0).
      * Nothing about the class is host-local: the workspace is `mkdir`'d INSIDE the container (never a bind-mount of a
-     * host path) and bytes move by `docker cp` / `docker exec cat`, which stream over the daemon API.
+     * host path) and bytes move by `docker exec -i … cat >` / `docker exec cat`, which stream over the daemon API.
      */
     dockerHost?: string;
     /** Container memory limit (docker `--memory`, e.g. "2g"). Absent = no limit. */
@@ -61,17 +61,11 @@ export interface LocalDockerEnvDeps {
     spawn?: typeof spawn;
 }
 export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv {
-    /** DUAL-MODE-DESIGN §5: a container is a real isolation boundary; v1 has no managed memory snapshot. */
-    /** `sharesProcessTable`(core 7.57.0,必填):命令跑在本机容器自己的 PID 命名空间里(不传 `--pid=host`),不在本进程所在的进程表。 */
-    readonly capabilities: {
-        isolation: boolean;
-        suspendable: boolean;
-        canonicalPathAuthoritative: boolean;
-        sharesProcessTable: boolean;
-    };
+    /** 能力块的唯一作者 = `capabilitiesFor`(`execution-lane-caps.ts`;逐键表态与理由在那里,本类零能力字面量)。 */
+    readonly capabilities: import("@sema-agent/core").ExecutionEnvCapabilities;
     /** Working directory inside the container; relative paths resolve against it (ExecutionEnv contract). */
     cwd: string;
-    /** core `ExecutionEnv.homeDir`([ref]):本容器里执行用户的 home —— 声明胜,否则开容器那一拍实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
+    /** core `ExecutionEnv.homeDir`([ref]):本容器里执行用户的 home —— 声明在场 ⇒ 声明(开环境那一拍与 `$HOME` 对证过),否则开容器那一拍实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
     get homeDir(): string | undefined;
     /** core 7.49.0 [ref]:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在容器里(镜像的 env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
@@ -92,7 +86,7 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     private connecting?;
     /** 家目录:环境答了而与声明不一致 ⇒ 这只环境的拒,记一次、此后每次连接原样回它(同一镜像同一答案:不再起容器、不再问)。 */
     private homeRefusal?;
-    /** 家目录的座(声明胜 · 否则开容器那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。本车道对声明对证。 */
+    /** 家目录的座(声明在场 ⇒ 开环境那一拍对证 · 否则开容器那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。与其余读得出家目录的车道同一只判官、同一句拒。 */
     private readonly homeSeat;
     constructor(config: LocalDockerEnvConfig, deps?: LocalDockerEnvDeps);
     private resolve;
@@ -163,10 +157,27 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
         maxLines?: number;
         abortSignal?: AbortSignal;
     }): Promise<Result<string[], FileError>>;
+    /** 暂存写的两只面(规则与提交脚本的唯一属主 = `remote-shell.ts` `writeFileStaged` / `appendFileStaged`;父目录与私有暂存目录由编排的准备那一步建):
+     *  上传 = 容器内 `cat` 从 stdin 收整份字节落到私有目录里的暂存件({@link pipeIn});提交 = 容器内一次 shell 往返。两者同一身份 ——
+     *  同一只 argv 构造({@link execArgv}),都是镜像的用户。不用 `docker cp`:它由守护进程以 root 落盘,镜像用户 ≠ root 时暂存件属 root、
+     *  提交方拿不走也清不掉,「目录不收新名字」也探不出来(root 哪里都写得进)。 */
+    private stagedLane;
+    /** 整旧或整新(暂存 → 一次 `mv -f`)。修前 `docker cp` 直落目标(以守护进程的 root 身份):传输中途断 / 取消时目标剩什么取决于守护进程的解包实现,本适配器不依赖它。 */
     writeFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** 追加(暂存要加的字节 → 一次 `cat >>`;inode 不换、已有字节不重写)。修前 = 读旧 + 拼 + 整份 cp(O(文件);中途断 ⇒ 目标没了或半份)。
+     *  目录不收新名字 / 私有目录收不成私有时的退路 = 容器内 `cat >>` 从 stdin 直接追加到目标(同一身份)。 */
     appendFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /**
+     * 把整份内容经 stdin 交给容器里的 `cat`,落到 `dest`(`>` 建或覆盖;`>>` 追加)。走与提交 / 文件面探针同一只往返({@link fsExec},argv 只多一个 `-i`)
+     * ⇒ 同一身份、同一工作目录、同一道守卫;二进制安全(载荷不经 shell 转义,也不在宿主落临时件)。stdin 没写完而进程退 0 ⇒ 按失败答(载荷未必整份到了)。
+     */
+    private pipeIn;
     private posixFsInst?;
     private get posixFs();
+    /** 文件面的一次容器内 shell 往返(基座、暂存写的准备 / 上传 / 提交 / 清理共用)。承 fsReady 契约(其余三腿走公有 exec、守卫天然在;本腿直用私有
+     *  docker,必须自带):destroyed 守卫 + 懒连接,fail closed 不抛 —— 消息保留 "destroyed" 字样(测试钉的就是它)。`input` 在场 ⇒ 同一只 argv 多一个
+     *  `-i`、载荷走 stdin({@link pipeIn});身份与工作目录与不带载荷的往返逐字相同。 */
+    private fsExec;
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
     readLink(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
@@ -200,7 +211,8 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
     /** Prepend `-H <dockerHost>` to a docker argv when configured (per-invocation, not the process env). */
     private withHostFlag;
     /** Build the `docker exec` argv for a command, applying cwd (`-w`) and per-command env (`-e K=V`).
-     *  argv elements are SEPARATE (no host-side shell join) — the command runs in the CONTAINER's `/bin/sh -c`. */
+     *  argv elements are SEPARATE (no host-side shell join) — the command runs in the CONTAINER's `/bin/sh -c`.
+     *  `stdin` ⇒ `-i` (the payload of {@link pipeIn}); nothing else differs, so a piped upload runs as the same user as every other exec. */
     private execArgv;
     /** Like {@link execArgv} but for an internal FileSystem helper command (uses the workspace cwd + adapter env). */
     private execRaw;

package/dist/plugins/remote-env-local-docker.js

@@ -1,14 +1,14 @@
 import path from "node:path";
-import os from "node:os";
-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 { randomBytes } from "node:crypto";
-import { shellQuote, armPipeDestroyGrace } from "./remote-shell.js";
+import { shellQuote, armPipeDestroyGrace, appendFileStaged, 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, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
+import { capabilitiesFor } from "../execution-lane-caps.js";
 import { fileErrorFromExec, classifyFsStderr } from "./remote-env-file-error.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
 const PROVIDER = "local-docker";
@@ -21,7 +21,7 @@ const unsupported = (op) => ({
     error: new RemoteExecutionError("unsupported", `${op} is not supported on a local-docker target (v1: a container is an isolation boundary but not a managed memory snapshot; capabilities.suspendable=false)`),
 });
 export class RemoteLocalDockerExecutionEnv {
-    capabilities = { isolation: true, suspendable: false, canonicalPathAuthoritative: true, sharesProcessTable: false };
+    capabilities = capabilitiesFor({ remoteExec: { provider: "local-docker" } });
     cwd;
     get homeDir() {
         return this.homeSeat.home;
@@ -50,7 +50,7 @@ export class RemoteLocalDockerExecutionEnv {
             controlTimeoutMs: config.controlTimeoutMs ?? DEFAULT_CONTROL_TIMEOUT_MS,
         };
         this.cwd = this.cfg.mountPath;
-        this.homeSeat = new LaneHomeSeat({ lane: PROVIDER, declared: config.homeDir, verifiesDeclared: true, onAbsent: config.onHomeAbsent });
+        this.homeSeat = new LaneHomeSeat(PROVIDER, config);
         this.spawnFn = deps.spawn ?? spawn;
         const id = config.id ?? randomBytes(6).toString("hex");
         const suffix = randomBytes(4).toString("hex");
@@ -383,71 +383,48 @@ export class RemoteLocalDockerExecutionEnv {
             lines = lines.slice(0, options.maxLines);
         return ok(lines);
     }
+    stagedLane(content) {
+        return { upload: (dest, signal) => this.pipeIn(content, dest, signal), run: (cmd, signal) => this.fsExec(cmd, signal) };
+    }
     async writeFile(p, content, abortSignal) {
         const ready = await this.fsReady(p);
         if (!ready.ok)
             return ready;
-        const abs = this.resolve(p);
-        const dir = path.posix.dirname(abs);
-        if (dir && dir !== "." && dir !== "/") {
-            const mk = await this.docker(this.execRaw(`mkdir -p ${shellQuote(dir)}`), { signal: abortSignal, timeoutMs: this.cfg.commandTimeoutMs });
-            if (!mk.ok)
-                return { ok: false, error: fileErrorFromExec(mk.error, dir) };
-            if (mk.value.exitCode !== 0)
-                return { ok: false, error: classifyFsStderr(mk.value.stderr, dir) };
-        }
-        let local;
-        try {
-            local = path.join(os.tmpdir(), `docker-cp-${Date.now()}-${randomBytes(6).toString("hex")}`);
-            await fs.writeFile(local, typeof content === "string" ? Buffer.from(content, "utf8") : Buffer.from(content));
-            const cp = await this.docker(["cp", local, `${this.containerName}:${abs}`], { signal: abortSignal, timeoutMs: this.cfg.commandTimeoutMs });
-            if (!cp.ok)
-                return { ok: false, error: fileErrorFromExec(cp.error, abs) };
-            if (cp.value.exitCode !== 0)
-                return { ok: false, error: classifyFsStderr(cp.value.stderr, abs) };
-            return ok(undefined);
-        }
-        catch (e) {
-            return { ok: false, error: new FileError("unknown", errMsg(e), abs) };
-        }
-        finally {
-            if (local)
-                await fs.rm(local, { force: true }).catch(() => { });
-        }
+        return writeFileStaged(this.stagedLane(content), this.resolve(p), abortSignal);
     }
     async appendFile(p, content, abortSignal) {
+        const ready = await this.fsReady(p);
+        if (!ready.ok)
+            return ready;
         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(content), abs, abortSignal, (ctx) => ctx.inPlace((signal) => this.pipeIn(content, abs, signal, ">>")));
+    }
+    async pipeIn(content, dest, abortSignal, redirect = ">") {
+        const r = await this.fsExec(`cat ${redirect} ${shellQuote(dest)}`, abortSignal, typeof content === "string" ? Buffer.from(content, "utf8") : content);
+        if (!r.ok)
+            return { ok: false, error: fileErrorFromExec(r.error, dest) };
+        if (r.value.exitCode !== 0)
+            return { ok: false, error: classifyFsStderr(r.value.stderr, dest) };
+        return ok(undefined);
     }
     posixFsInst;
     get posixFs() {
         return (this.posixFsInst ??= createPosixShellFs({
-            run: async (cmd, abortSignal) => {
-                if (this.destroyed)
-                    return { ok: false, error: new ExecutionError("shell_unavailable", "execution env already destroyed") };
-                if (!this.containerId) {
-                    const c = await this.connect();
-                    if (!c.ok)
-                        return { ok: false, error: new ExecutionError("shell_unavailable", `local-docker connect failed: ${c.error.message}`) };
-                }
-                return this.docker(this.execRaw(cmd), { signal: abortSignal, timeoutMs: this.cfg.commandTimeoutMs });
-            },
+            run: (cmd, abortSignal) => this.fsExec(cmd, abortSignal),
             resolve: (p) => this.resolve(p),
             tempDir: () => this.cwd,
         }));
     }
+    async fsExec(cmd, abortSignal, input) {
+        if (this.destroyed)
+            return { ok: false, error: new ExecutionError("shell_unavailable", "execution env already destroyed") };
+        if (!this.containerId) {
+            const c = await this.connect();
+            if (!c.ok)
+                return { ok: false, error: new ExecutionError("shell_unavailable", `local-docker connect failed: ${c.error.message}`, c.error) };
+        }
+        return this.docker(this.execArgv(cmd, undefined, undefined, input !== undefined), { signal: abortSignal, timeoutMs: this.cfg.commandTimeoutMs, ...(input !== undefined ? { input } : {}) });
+    }
     async fileInfo(p, abortSignal) {
         return this.posixFs.statFileInfo(p, abortSignal);
     }
@@ -484,8 +461,8 @@ export class RemoteLocalDockerExecutionEnv {
     withHostFlag(args) {
         return this.cfg.dockerHost ? ["-H", this.cfg.dockerHost, ...args] : args;
     }
-    execArgv(command, cwd, env) {
-        const args = ["exec"];
+    execArgv(command, cwd, env, stdin = false) {
+        const args = stdin ? ["exec", "-i"] : ["exec"];
         const dir = cwd != null ? this.resolve(cwd) : this.cwd;
         args.push("-w", dir);
         const mergedEnv = { ...(this.cfg.env ?? {}), ...(env ?? {}) };
@@ -501,7 +478,7 @@ export class RemoteLocalDockerExecutionEnv {
         return new Promise((resolve) => {
             let settled = false;
             let forceSettleTimer;
-            const child = this.spawnFn(this.cfg.dockerPath, this.withHostFlag(args), { stdio: ["ignore", "pipe", "pipe"], env: this.cliEnv() });
+            const child = this.spawnFn(this.cfg.dockerPath, this.withHostFlag(args), { stdio: [opts?.input !== undefined ? "pipe" : "ignore", "pipe", "pipe"], env: this.cliEnv() });
             const killGrace = () => {
                 try {
                     child.kill("SIGKILL");
@@ -524,11 +501,11 @@ export class RemoteLocalDockerExecutionEnv {
             const timeoutMs = opts?.timeoutMs ?? this.cfg.controlTimeoutMs;
             const timer = setTimeout(() => {
                 killGrace();
-                finish({ ok: false, error: new ExecutionError("timeout", `docker ${args[0]} exceeded ${timeoutMs}ms`) });
+                finish({ ok: false, error: createCutError({ code: "timeout", message: `docker ${args[0]} exceeded ${timeoutMs}ms` }, buildCapturedOutput(outTail, errBuf)) });
             }, timeoutMs);
             const onAbort = () => {
                 killGrace();
-                finish({ ok: false, error: new ExecutionError("aborted", "docker command aborted") });
+                finish({ ok: false, error: createCutError({ code: "aborted", message: "docker command aborted" }, buildCapturedOutput(outTail, errBuf)) });
             };
             if (opts?.signal) {
                 if (opts.signal.aborted)
@@ -541,10 +518,21 @@ export class RemoteLocalDockerExecutionEnv {
                 outTail.push(d); opts?.onStdout?.(d.toString()); });
             child.stderr?.on("data", (d) => { errBuf.push(d); opts?.onStderr?.(d.toString()); });
             child.on("error", (e) => finish({ ok: false, error: new ExecutionError("spawn_error", `docker spawn failed (is '${this.cfg.dockerPath}' installed?): ${e.message}`, e) }));
+            let stdinFailure;
+            if (opts?.input !== undefined) {
+                if (!child.stdin) {
+                    killGrace();
+                    return finish({ ok: false, error: new ExecutionError("spawn_error", `docker ${args[0]}: no stdin pipe for the payload`) });
+                }
+                child.stdin.on("error", (e) => { stdinFailure = e.message; });
+                child.stdin.end(Buffer.from(opts.input.buffer, opts.input.byteOffset, opts.input.byteLength));
+            }
             child.on("close", (code, signal) => {
                 if (forceSettleTimer)
                     clearTimeout(forceSettleTimer);
                 const exitCode = code ?? (signal ? 128 + (signalNumber(signal) ?? 9) : 1);
+                if (exitCode === 0 && stdinFailure !== undefined)
+                    return finish({ ok: false, error: new ExecutionError("unknown", `docker ${args[0]}: the payload could not be written to stdin (${stdinFailure})`) });
                 const err = errBuf.result();
                 const stderr = markTruncated(err.text, err.droppedBytes);
                 if (binary) {
@@ -610,7 +598,7 @@ export class RemoteLocalDockerExecutionEnv {
             return ok(undefined);
         const c = await this.connect();
         if (!c.ok)
-            return { ok: false, error: new FileError("unknown", `local-docker connect failed: ${c.error.message}`, this.resolve(p), c.error) };
+            return { ok: false, error: fileErrorFromExec(c.error, this.resolve(p)) };
         return ok(undefined);
     }
     dockerToRemoteError(e, fallback) {

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

@@ -53,23 +53,8 @@ export interface SshEnvDeps {
     connectOnce?: (signal?: AbortSignal) => Promise<ConnectResult>;
 }
 export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
-    /**
-     * 🔴 **[ref] / core 7.20.0([ref])`canonicalPathAuthoritative: true`** —— 本适配器的 `canonicalPath`
-     * 就是**命令真正跑的那块文件系统**的权威答案(`posix-shell-fs` 的 `canonicalPath` 原语,在真机上解到落点)。声明它 = 告诉引擎:整链答不出来是**解析器出了事**
-     * (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,必填):命令跑在 SSH 目标机上;目标恰是本机(或本进程所在容器的宿主)时命令与本进程同表,这一形今天没有配置面可声明 `true`。 */
-    readonly capabilities: {
-        isolation: boolean;
-        suspendable: boolean;
-        canonicalPathAuthoritative: boolean;
-        sharesProcessTable: boolean;
-    };
+    /** 能力块的唯一作者 = `capabilitiesFor`(`execution-lane-caps.ts`;逐键表态与理由在那里,本类零能力字面量)。 */
+    readonly capabilities: import("@sema-agent/core").ExecutionEnvCapabilities;
     /** Working directory; relative paths resolve against it (ExecutionEnv contract). Starts at mountPath. */
     cwd: string;
     private conn?;
@@ -86,9 +71,9 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
      *  =重连风暴);②共享尝试**不携带任何 caller 信号**(首创者的 pre-abort 不得毒化 joiner;单 caller
      *  取消只退它自己的等待,底层握手余命 ≤ readyTimeout 有界,彻底取消归 destroy 代际闸)。 */
     private inFlight?;
-    /** core `ExecutionEnv.homeDir`([ref]):目标机上登录用户的 home —— 声明胜,否则连上之后实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
+    /** core `ExecutionEnv.homeDir`([ref]):目标机上登录用户的 home —— 声明在场 ⇒ 声明(开环境那一拍与 `$HOME` 对证过),否则连上之后实测的 `$HOME`,见 {@link LaneHomeSeat}。读时才取(没声明时连上之前缺席)。 */
     get homeDir(): string | undefined;
-    /** 家目录的座(声明胜 · 否则连上之后实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。本车道对声明对证。 */
+    /** 家目录的座(声明在场 ⇒ 开环境那一拍对证 · 否则连上之后实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。与其余读得出家目录的车道同一只判官、同一句拒。 */
     private readonly homeSeat;
     /** 家目录声明 × 实测的判定,按连接记(同一条连接只问一次;重连换了连接再问 —— 登录用户不变时答案相同,代价一次往返;没声明且已量到绝对路径之后不再问)。 */
     private homeChecked?;
@@ -186,7 +171,14 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
         abortSignal?: AbortSignal;
     }): Promise<Result<string[], FileError>>;
     readBinaryFile(p: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
+    /** 暂存写的两只面(规则与提交脚本的唯一属主 = `remote-shell.ts` `writeFileStaged` / `appendFileStaged`;父目录与私有暂存目录由编排的准备那一步建):
+     *  上传 = sftp 整份写到私有目录里的暂存件;提交 = 文件面探针 exec。两者同一身份(sftp 子系统与 exec 都是这条连接的登录用户)。
+     *  sftp 写不收取消信号 ⇒ 取消在传输结束之后、提交之前生效(目标未碰)。 */
+    private stagedLane;
+    /** 整旧或整新(暂存 → 一次 `mv -f`)。修前 `sftp.writeFile(abs)` 就地 O_TRUNC:传输中途断 ⇒ 目标 = 半份新件。 */
     writeFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** 追加(暂存要加的字节 → 一次 `cat >>`;inode 不换、已有字节不重写)。修前 = 读旧 + 拼 + 整份就地重写(O(文件);中途断 ⇒ 半份)。
+     *  目录不收新名字 / 私有目录收不成私有时的退路 = sftp 直接追加到目标。 */
     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>>;

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

@@ -1,11 +1,13 @@
 import path from "node:path";
 import { Client } from "ssh2";
 import { createSshHostKeyVerifier } from "../ssh-host-key.js";
-import { buildCwdEnvCommand, createCwdGuardedCall, shellQuote, kindFromMode } from "./remote-shell.js";
+import { appendFileStaged, buildCwdEnvCommand, createCwdGuardedCall, kindFromMode, 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 { createPosixShellFs } from "./posix-shell-fs.js";
 import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
+import { capabilitiesFor } from "../execution-lane-caps.js";
 import { fileErrorFromExec } from "./remote-env-file-error.js";
 import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
 const PROVIDER = "ssh";
@@ -18,7 +20,7 @@ function exitCodeForSignalKill(signal) {
     return 128 + (signalNumber(`SIG${signal}`) ?? 9);
 }
 export class RemoteSshExecutionEnv {
-    capabilities = { isolation: false, suspendable: false, canonicalPathAuthoritative: true, sharesProcessTable: false };
+    capabilities = capabilitiesFor({ remoteExec: { provider: "ssh" } });
     cwd;
     conn;
     sftpPromise;
@@ -51,7 +53,7 @@ export class RemoteSshExecutionEnv {
             hostKey: config.hostKey,
         };
         this.cwd = this.cfg.mountPath;
-        this.homeSeat = new LaneHomeSeat({ lane: PROVIDER, declared: config.homeDir, verifiesDeclared: true, onAbsent: config.onHomeAbsent });
+        this.homeSeat = new LaneHomeSeat(PROVIDER, config);
     }
     resolve(p) {
         return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
@@ -363,12 +365,29 @@ export class RemoteSshExecutionEnv {
         return new Promise((resolve) => {
             const outBuf = new RollingTailBuffer();
             const errBuf = new RollingTailBuffer();
+            const recordStderr = (bytes) => {
+                if (bytes.length > 0)
+                    errBuf.push(bytes);
+            };
+            const emitStderr = (bytes) => {
+                if (bytes.length > 0)
+                    options?.onStderr?.(bytes.toString());
+            };
+            const takeStderr = (bytes) => {
+                recordStderr(bytes);
+                emitStderr(bytes);
+            };
+            const captured = () => {
+                recordStderr(call.endStderr());
+                return buildCapturedOutput(outBuf, errBuf);
+            };
             let settled = false;
             let streamRef;
-            const finish = (r) => {
+            const finish = (outcome) => {
                 if (settled)
-                    return;
+                    return false;
                 settled = true;
+                const r = outcome();
                 clearTimeout(timer);
                 options?.abortSignal?.removeEventListener("abort", onAbort);
                 conn.removeListener("close", onConnClose);
@@ -378,10 +397,14 @@ export class RemoteSshExecutionEnv {
                 catch {
                 }
                 resolve(r);
+                return true;
+            };
+            const cut = (c) => {
+                finish(() => ({ ok: false, error: createCutError(c, captured()) }));
             };
-            const timer = setTimeout(() => finish({ ok: false, error: new ExecutionError("timeout", `ssh exec exceeded ${timeoutMs}ms (provider/command hang)`) }), timeoutMs);
-            const onAbort = () => finish({ ok: false, error: new ExecutionError("aborted", "ssh exec aborted") });
-            const onConnClose = () => finish({ ok: false, error: new ExecutionError("transport_lost", "ssh transport lost mid-command (connection closed before exit status) — reconnect + retry per idempotency") });
+            const timer = setTimeout(() => cut({ code: "timeout", message: `ssh exec exceeded ${timeoutMs}ms (provider/command hang)` }), timeoutMs);
+            const onAbort = () => cut({ code: "aborted", message: "ssh exec aborted" });
+            const onConnClose = () => finish(() => ({ ok: false, error: new ExecutionError("transport_lost", "ssh transport lost mid-command (connection closed before exit status) — reconnect + retry per idempotency") }));
             conn.once("close", onConnClose);
             if (options?.abortSignal) {
                 if (options.abortSignal.aborted)
@@ -390,7 +413,7 @@ export class RemoteSshExecutionEnv {
             }
             conn.exec(call.command, (err, stream) => {
                 if (err)
-                    return finish({ ok: false, error: new ExecutionError("spawn_error", `ssh exec failed: ${err.message}`, err) });
+                    return finish(() => ({ ok: false, error: new ExecutionError("spawn_error", `ssh exec failed: ${err.message}`, err) }));
                 streamRef = stream;
                 if (settled) {
                     try {
@@ -407,25 +430,20 @@ export class RemoteSshExecutionEnv {
                 })
                     .on("close", (code, signal) => {
                     if (code == null && !signal) {
-                        return finish({ ok: false, error: new ExecutionError("transport_lost", "ssh channel closed without exit status (transport lost / connection dropped)") });
+                        return finish(() => ({ ok: false, error: new ExecutionError("transport_lost", "ssh channel closed without exit status (transport lost / connection dropped)") }));
                     }
-                    const tail = call.endStderr();
-                    if (tail.length > 0) {
-                        errBuf.push(tail);
-                        options?.onStderr?.(tail.toString());
-                    }
-                    const out = outBuf.result();
-                    const err = errBuf.result();
                     const exitCode = code ?? (signal ? exitCodeForSignalKill(signal) : 1);
-                    finish(call.settle(ok({ stdout: markTruncated(out.text, out.droppedBytes), stderr: markTruncated(err.text, err.droppedBytes), exitCode })));
+                    const held = call.endStderr();
+                    const won = finish(() => {
+                        recordStderr(held);
+                        const out = outBuf.result();
+                        const err = errBuf.result();
+                        return call.settle(ok({ stdout: markTruncated(out.text, out.droppedBytes), stderr: markTruncated(err.text, err.droppedBytes), exitCode }));
+                    });
+                    if (won)
+                        emitStderr(held);
                 })
-                    .stderr.on("data", (d) => {
-                    const c = call.filterStderr(d);
-                    if (c.length === 0)
-                        return;
-                    errBuf.push(c);
-                    options?.onStderr?.(c.toString());
-                });
+                    .stderr.on("data", (d) => takeStderr(call.filterStderr(d)));
             });
         });
     }
@@ -562,7 +580,7 @@ export class RemoteSshExecutionEnv {
     async sftp(abortSignal) {
         const ready = await this.ensureConnected(abortSignal);
         if (!ready.ok)
-            return Promise.reject(ready.error.code === "aborted" ? new FileError("aborted", ready.error.message) : new Error(ready.error.message));
+            return Promise.reject(ready.error.code === "aborted" ? fileErrorFromExec(ready.error) : new FileError("target_unavailable", ready.error.message, undefined, ready.error));
         if (!this.conn)
             return Promise.reject(new Error("SSH not connected"));
         if (!this.sftpPromise) {
@@ -604,41 +622,37 @@ export class RemoteSshExecutionEnv {
             return { ok: false, error: this.fileError(e, abs) };
         }
     }
+    stagedLane(data) {
+        return {
+            upload: async (dest, signal) => {
+                try {
+                    const sftp = await this.sftp(signal);
+                    await new Promise((resolve, reject) => sftp.writeFile(dest, data, (err) => (err ? reject(err) : resolve())));
+                    return ok(undefined);
+                }
+                catch (e) {
+                    return { ok: false, error: this.fileError(e, dest) };
+                }
+            },
+            run: (cmd, signal) => this.fsExec(cmd, signal),
+        };
+    }
     async writeFile(p, content, abortSignal) {
-        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) };
-        }
-        try {
-            const sftp = await this.sftp(abortSignal);
-            const data = typeof content === "string" ? Buffer.from(content, "utf8") : Buffer.from(content);
-            await new Promise((resolve, reject) => sftp.writeFile(abs, data, (err) => (err ? reject(err) : resolve())));
-            return ok(undefined);
-        }
-        catch (e) {
-            return { ok: false, error: this.fileError(e, abs) };
-        }
+        return writeFileStaged(this.stagedLane(bytesOf(content)), this.resolve(p), abortSignal);
     }
     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);
+        const data = bytesOf(content);
+        return appendFileStaged(this.stagedLane(data), abs, abortSignal, (ctx) => ctx.inPlace(async (signal) => {
+            try {
+                const sftp = await this.sftp(signal);
+                await new Promise((resolve, reject) => sftp.appendFile(abs, data, (err) => (err ? reject(err) : resolve())));
+                return ok(undefined);
+            }
+            catch (e) {
+                return { ok: false, error: this.fileError(e, abs) };
+            }
+        }));
     }
     async fileInfo(p, abortSignal) {
         const abs = this.resolve(p);
@@ -734,4 +748,7 @@ export class RemoteSshExecutionEnv {
 export function sshExecutionEnvFactory(config) {
     return (_ctx) => new RemoteSshExecutionEnv(config);
 }
+function bytesOf(content) {
+    return typeof content === "string" ? Buffer.from(content, "utf8") : Buffer.from(content);
+}
 //# sourceMappingURL=remote-env-ssh.js.map