@sema-agent/server 7.137.0 → 7.139.0

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

@@ -1,13 +1,12 @@
 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 { fileErrorFromExec, classifyFsStderr } from "./remote-env-file-error.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
@@ -21,7 +20,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 };
+    capabilities = { isolation: true, suspendable: false, canonicalPathAuthoritative: true, sharesProcessTable: false, hostLocalPaths: false, externalContentTarget: false, io: true, keepsReadFloor: false };
     cwd;
     get homeDir() {
         return this.homeSeat.home;
@@ -383,71 +382,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}`) };
+        }
+        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 +460,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 +477,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 +500,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 +517,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) {

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

@@ -59,14 +59,21 @@ export declare class RemoteSshExecutionEnv 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,必填):命令跑在 SSH 目标机上;目标恰是本机(或本进程所在容器的宿主)时命令与本进程同表,这一形今天没有配置面可声明 `true`。 */
+    /** 能力块(引擎 [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: false;
+        io: true;
+        keepsReadFloor: false;
     };
     /** Working directory; relative paths resolve against it (ExecutionEnv contract). Starts at mountPath. */
     cwd: string;
@@ -184,7 +191,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,9 +1,10 @@
 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 { fileErrorFromExec } from "./remote-env-file-error.js";
@@ -18,7 +19,7 @@ function exitCodeForSignalKill(signal) {
     return 128 + (signalNumber(`SIG${signal}`) ?? 9);
 }
 export class RemoteSshExecutionEnv {
-    capabilities = { isolation: false, suspendable: false, canonicalPathAuthoritative: true };
+    capabilities = { isolation: false, suspendable: false, canonicalPathAuthoritative: true, sharesProcessTable: false, hostLocalPaths: false, externalContentTarget: false, io: true, keepsReadFloor: false };
     cwd;
     conn;
     sftpPromise;
@@ -363,12 +364,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 +396,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 +412,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 +429,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 +579,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 Error(ready.error.message));
         if (!this.conn)
             return Promise.reject(new Error("SSH not connected"));
         if (!this.sftpPromise) {
@@ -604,41 +621,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 +747,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

package/dist/plugins/remote-shell.d.ts

@@ -1,8 +1,8 @@
 /**
- * Shared shell/path helpers for the SSH + ADB `RemoteExecutionEnv` adapters. Kept in ONE place so the
- * security-sensitive quoting can't drift between adapters (council design/#4, #5).
+ * Shared shell/path helpers for the remote `RemoteExecutionEnv` adapters (ssh / adb / k8s / local-docker, and e2b where it
+ * shells out). Kept in ONE place so the security-sensitive quoting can't drift between adapters (council design/#4, #5).
  */
-import { ExecutionError, type FileError, type FileInfo, type RemoteExecutionError, type Result, type SymlinkChain } from "@sema-agent/core";
+import { ExecutionError, FileError, type FileInfo, type RemoteExecutionError, type Result, type SymlinkChain } from "@sema-agent/core";
 import type { ChildProcess } from "node:child_process";
 /**
  * D5 pipe-destroy grace (parity with core's vendored `EXEC_FORCE_SETTLE_GRACE_MS`, harness/env/nodejs.js):
@@ -204,4 +204,101 @@ export type ShellChainRun = (cmd: string) => Promise<Result<{
  *    三条远端腿的文件面探针不带 cwd(车PL 验修 ③)⇒ 这条命令不会因为某个工作目录不可用而不跑。
  */
 export declare function runSymlinkChain(absPath: string, run: ShellChainRun): Promise<Result<SymlinkChain, FileError>>;
+/**
+ * 脚本删一只私有目录没删掉时写到 **stdout** 的那一条记录的头:`<头> <目录路径>\0`(NUL 收尾 —— 路径里可以有换行)。
+ * 残留记录走 stdout、错误走 stderr:两条通道不混,分类器读到的 stderr 里没有路径文本。记录不改脚本的退出码:写照它自己的结局答,残留另行留痕。
+ */
+export declare const STAGE_DIR_LEFT_MARK = "sema: staging directory left behind:";
+/** 一次远端写的暂存位置(纯数据):`dir` = 目标目录下的私有目录,`file` = 其中那只暂存文件。 */
+export interface StagingPaths {
+    readonly dir: string;
+    readonly file: string;
+}
+/**
+ * 远端写的暂存位置(纯数据 ⇒ `build*`):私有目录在**目标同目录**(替换的提交是同一文件系统内的 rename),名 = `.<目标名>.stage-<12 位十六进制>`;
+ * 目标名已贴着 NAME_MAX 时逐码点截短到放得下 —— 一个目录装不下的暂存名会把一次就地形本来接得住的写拒掉。这只名字铸一次、用到底:
+ * 提交脚本跟一跳链接到别的目录里重新暂存时,用的仍是这只名字(已在上限之内,放到哪个目录都装得下)。`nonce` 只给测试钉序用。
+ */
+export declare function buildStagingPaths(abs: string, nonce?: string): StagingPaths;
+/**
+ * 准备脚本(纯数据 ⇒ `build*`):建目标的父目录(`mkdir -p`,失败 ⇒ 退出 1),再建私有目录({@link privateMkdir};失败 ⇒ 退出 {@link STAGE_DIR_REFUSED_EXIT}),
+ * 再收紧({@link hardenPrivate};不成 ⇒ 放弃这只目录({@link abandonPrivate})、写 {@link STAGE_DIR_UNSEALED_MESSAGE}、退出 {@link STAGE_DIR_UNSEALED_EXIT} —— 编排退到直接写目标),
+ * 再核里面没有 `data`({@link emptyPrivate};不成 ⇒ 放弃这只目录、写明原因、退出 1 —— 响亮答错,不退;原因句不带路径:stderr 只给分类器读)。
+ * 非零退出之后目标机上没有这次写的私有目录(删不掉的那一只由 {@link STAGE_DIR_LEFT_MARK} 记录点名)。**退出 0 ⇔ 目录是读回核实过的私有的、且是空的。**
+ */
+export declare function buildStagingPrepareCommand(stage: StagingPaths): string;
+/**
+ * 整文件替换的提交脚本(POSIX sh,纯数据 ⇒ `build*`)。一次往返,**整条命令只有一个退出状态**(`{ …; }`,理由同
+ * {@link buildSymlinkChainCommand} 头注)。`d` = 私有目录,`s` = 其中的暂存件,`t` = 目标。
+ *
+ *  1. 叶是符号链接 ⇒ 读**一跳**(`readlink`,不带 `-f`;相对目标锚在链接自己的目录,不折 `..`,与链视图同一词法;
+ *     链接文本的结尾换行原样保留 —— `-n` 不加换行,`$(…)` 会吞掉结尾换行,所以输出后垫一个 `.` 再剥掉;`-n` 不被认 ⇒ 读不出一跳 ⇒ 第 3 步经链接就地写):那一跳是常规文件或还不存在
+ *     ⇒ 提交落到那一跳上(链接保持是链接);否则(链 / 非常规)⇒ 走第 3 步就地写。
+ *  2. 目标是常规文件或不存在 ⇒ 私有目录不在目标的目录里(跟了一跳)⇒ 先在目标目录里用**同一只私有目录名**、同样生来 0700、同样收紧过地**重新暂存**一份
+ *     (目标机本地拷贝,不过网络;拷成了就改用新的那只、删原私有目录;拷不成就删掉新建的那只、收紧不成就放弃它,用原暂存件 ——
+ *     删不掉的都写一条 {@link STAGE_DIR_LEFT_MARK} 记录),
+ *     让 rename 不跨文件系统(与 core 把暂存放在最终目标旁边同形);
+ *     已有文件的权限位带到暂存件上(`stat -c %a`,BSD 退到 `stat -f %Lp`;带不过去不拦)—— **在 `mv` 之前**,换上去的那一刻权限位已是目标的;
+ *     `mv -f` 换上去,成功 ⇒ 删私有目录(删不掉 ⇒ 一条 {@link STAGE_DIR_LEFT_MARK} 记录,仍 `exit 0`:目标已是新件)。
+ *  3. 其余(链接链 / FIFO / 设备 / 目录 / `mv` 被拒,如单文件绑定挂载的 EBUSY)⇒ 已落定的暂存件就地拷进目标(与 core 的回落同形:
+ *     非原子,但不再经过网络传输),见 {@link takeAndWrite}:先把暂存件**打开**(读不了 ⇒ 先补上属主读位,仍读不了 ⇒ 非零退出、目标未碰),
+ *     再**删掉暂存名**(删不掉 ⇒ 非零退出、目标未碰,残留目录由脚本点名),然后才从已打开的那份拷进目标,最后关 fd、删私有目录(删不掉只记录)。于是
+ *     「目标被动过」⇒「暂存名已不在」,残留至多是一只空目录(或文件系统为打开着的文件留的隐藏项)。退出码 = 拷入那一步的退出码
+ *     (目录 ⇒ `Is a directory` 经 {@link classifyFsStderr} 归 `is_directory`)。
+ */
+export declare function buildStagedCommitCommand(stage: StagingPaths, target: string): string;
+/**
+ * 追加的提交脚本(纯数据 ⇒ `build*`):取走暂存件并写目标({@link takeAndWrite},次序同 {@link buildStagedCommitCommand} 第 3 步:先开、再删暂存名、后写、再关 fd 删私有目录),
+ * 一次 `cat >>` 加到目标尾(跟随链接、不换 inode、不碰已有字节)。暂存名删不掉 ⇒ 目标一个字节没加。
+ */
+export declare function buildStagedAppendCommand(stage: StagingPaths, target: string): string;
+/** 清掉一次写的私有目录({@link removalOf}:只删 `data` 与这只目录;不在 ⇒ 什么都不做;退出 0 ⇔ 不在了)。纯数据 ⇒ `build*`。 */
+export declare function buildStagingDiscardCommand(stage: StagingPaths): string;
+/**
+ * 一次暂存写交给 {@link writeFileStaged} / {@link appendFileStaged} 的两只面 —— 各腿的传输留在腿上,规则在这里。
+ * 🔴 **`upload` 与 `run` 必须是同一个身份、在同一台机器上**:私有目录由 `run` 建(0700,属写入方),`upload` 要进得去;提交由 `run` 做,
+ * 要拿得走、清得掉 `upload` 落下的东西。一条腿的传输若以别的身份落盘(例如容器守护进程以 root 拷入、而命令以镜像用户跑),那条腿必须改走
+ * 与 `run` 同一身份的传输,不能让编排迁就它。
+ */
+export interface StagedWriteLane {
+    /** 把**整份**字节放到 `dest`(新建;`dest` 的目录已在且是写入方的私有目录)—— 腿自己的传输(sftp / adb push / 容器内 `cat` 收 stdin / 分块 exec / provider 文件 API)。 */
+    upload(dest: string, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** 目标机上的一次 shell 往返(腿的文件面探针 exec:只用绝对路径,不进工作目录)。`abortSignal` 只有准备那一步带(提交一旦发出不再听取消)。 */
+    run(cmd: string, abortSignal?: AbortSignal): ReturnType<ShellChainRun>;
+}
+/**
+ * 退路拿到的两样(编排为每一次退路造一只,见 {@link createDirectContext}):`signal` = 这次写的取消信号;`inPlace(step)` = 把**写目标的那一步**包起来
+ * (连同那一步自己的通道准备:ssh 在步内拿 sftp 通道)。取消的读法只看那一步有没有被包住:包住的那一步**答了** `aborted` ⇒ 改写成 `unknown`(可能已有字节到了目标,
+ * 保守;通道准备里被取消也算在内);那一步开始之前取消已发生 ⇒ `aborted`、那一步不跑;那一步不收取消、照样写完(ssh 的 sftp)⇒ 结果照实(成功);
+ * 没包的步骤(读旧)答的 `aborted` 原样透出(目标未碰)。编排不猜退路走到了哪儿。
+ */
+export interface StagedDirectContext {
+    readonly signal: AbortSignal | undefined;
+    inPlace<T>(step: (abortSignal?: AbortSignal) => Promise<Result<T, FileError>>): Promise<Result<T, FileError>>;
+}
+/**
+ * 不暂存时的退路 —— 目录不收新名字(建私有目录被 `permission_denied` 拒)或私有目录收不成私有:腿直接对目标做的那一步(core 同一条回落:文件本身可能可写)。
+ * 两只文件面、五条腿**必传**:写面 = 腿的上传直落目标;追加面 = 能追加写的腿(ssh / local-docker / k8s)直接追加到目标,只能把整份文件落到一个路径上的腿
+ * (e2b 的 `files.write`、adb 的 push)读旧 + 拼 + 整份写目标(adb 的这一形就是 7.138.x 的追加)。字节流向目标的那一步必须经 `ctx.inPlace`(读旧不包)。
+ */
+export type StagedWriteDirect = (ctx: StagedDirectContext) => Promise<Result<void, FileError>>;
+/**
+ * 只能把整份文件落到一个路径上的腿(e2b 的 `files.write`、adb 的 push)在退路里的追加 —— 两腿共用这一只,各自只给读与写:
+ * 读旧(`not_found` ⇒ 按空;别的读错原样透出、不写)+ 按字节拼(二进制安全)+ 整份写目标。读旧**不**经 `ctx.inPlace`(取消落在这里 ⇒ `aborted`、目标未碰),
+ * 整份写经 `ctx.inPlace`(见 {@link StagedDirectContext})。adb 的这一形就是 7.138.x 的追加。
+ */
+export declare function rewriteAppend(read: (abortSignal?: AbortSignal) => Promise<Result<Uint8Array, FileError>>, write: (bytes: Uint8Array, abortSignal?: AbortSignal) => Promise<Result<void, FileError>>, add: string | Uint8Array, ctx: StagedDirectContext): Promise<Result<void, FileError>>;
+/**
+ * 远端整文件替换(ssh / adb / local-docker / k8s / e2b 五条腿调同一只;父目录由准备那一步建)。契约:成功 ⇒ 目标整份是新内容;传输失败 ⇒ 目标整份是旧内容;
+ * `aborted` ⇒ 目标未碰。私有目录清不掉 ⇒ 错误消息点名残留的目录。目录不收新名字、或私有目录收不成私有 ⇒ 不暂存,腿的上传直接落目标一次(旧形,core 同一条回落;非原子)。
+ * 提交往返本身断了(传输层错误)⇒ 答 `unknown`,消息写明提交跑没跑不可知。
+ */
+export declare function writeFileStaged(lane: StagedWriteLane, abs: string, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+/**
+ * 远端追加(五条腿调同一只;`lane.upload` 上传的是**要加的那几个字节**)。暂存那条路的契约:成功 ⇒ 目标 = 旧内容 + 新字节;传输失败 / `aborted` ⇒
+ * 目标未碰;已有字节从不被重写、inode 不换。`direct` = 目录不收新名字 / 私有目录收不成私有时腿直接写目标的那一步(必传,见 {@link StagedWriteDirect}),
+ * 不在上面的契约里:非原子 —— 中途断 ⇒ 目标可能只加上了一部分(整份写目标的 e2b / adb:已有字节被重写,目标可能没了或只剩半份);取消落在**写目标那一步开始之前**
+ * (读旧)⇒ `aborted`、目标未碰;写目标那一步因取消中断 ⇒ `unknown`、目标可能只写了一半,那一步自己的通道准备算在步内(保守,见头注与 {@link StagedDirectContext})。
+ */
+export declare function appendFileStaged(lane: StagedWriteLane, abs: string, abortSignal: AbortSignal | undefined, direct: StagedWriteDirect): Promise<Result<void, FileError>>;
 //# sourceMappingURL=remote-shell.d.ts.map