@sema-agent/server 7.145.0 → 7.147.0

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

@@ -17,6 +17,7 @@ import { LaneHomeSeat, laneHomeRefusal } 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";
+import { OWNER_ONLY_FILE_MODE } from "./owner-only-file-mode.js";
 const PROVIDER = "host";
 const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60_000;
 const inflightFsDrainWaitMs = () => numEnvOr("HOST_FS_DRAIN_WAIT_MS", 10_000, 1);
@@ -250,8 +251,8 @@ export class RemoteHostExecutionEnv {
                     await fs.mkdir(dir, { recursive: true });
                     const outPath = path.join(dir, "out");
                     const errPath = path.join(dir, "err");
-                    const outFh = await fs.open(outPath, "w");
-                    const errFh = await fs.open(errPath, "w");
+                    const outFh = await fs.open(outPath, "w", OWNER_ONLY_FILE_MODE);
+                    const errFh = await fs.open(errPath, "w", OWNER_ONLY_FILE_MODE);
                     let child;
                     try {
                         const sh = hostShell();
@@ -530,10 +531,10 @@ export class RemoteHostExecutionEnv {
             mkdirSync(dir, { recursive: true });
             const outPath = path.join(dir, "out");
             const errPath = path.join(dir, "err");
-            const fdOut = openSync(outPath, "ax", 0o600);
+            const fdOut = openSync(outPath, "ax", OWNER_ONLY_FILE_MODE);
             let fdErr;
             try {
-                fdErr = openSync(errPath, "ax", 0o600);
+                fdErr = openSync(errPath, "ax", OWNER_ONLY_FILE_MODE);
             }
             catch (e) {
                 try {
@@ -1314,7 +1315,7 @@ export class RemoteHostExecutionEnv {
     }
     childEnv(perCommand, spawnShell) {
         const base = spawnShell !== undefined
-            ? hostSubprocessEnv({ site: "server.remote-env-host.spawn-env", policy: this.cfg.inheritEnv, allow: [] })
+            ? hostSubprocessEnv({ site: this.cfg.gitBase === true ? "server.remote-env-host.git-base" : "server.remote-env-host.spawn-env", policy: this.cfg.inheritEnv, allow: [] })
             : composeHostSubprocessEnv({ policy: this.cfg.inheritEnv, allow: [] });
         if (this.cfg.env)
             Object.assign(base, this.cfg.env);

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

@@ -857,10 +857,13 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
         abortSignal?: AbortSignal;
     }): Promise<Result<string[], FileError>>;
     writeFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
-    /** 暂存写的两只面(规则与提交脚本的唯一属主 = `remote-shell.ts`;父目录与私有暂存目录由编排的准备那一步建):上传 = 分块整份写进私有目录里的暂存件;
-     *  提交 = 文件面探针 exec。两者同一身份(同一只容器里的 exec)。 */
+    /** 暂存写的两只面(规则与提交脚本的唯一属主 = `remote-shell.ts`;父目录与私有暂存目录由编排的准备那一步建):上传 = 分块整份写进私有目录里的暂存件
+     *  (阶段一 = 建连,见 {@link prepareChunked};阶段二 = 分块写);提交 = 文件面探针 exec。两者同一身份(同一只容器里的 exec)。 */
     private stagedLane;
     appendFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** 阶段一(备件):建连(懒连接;首块之前 —— 取消落在这里 ⇒ `aborted`、没有一块发出);阶段二:分块写({@link writeChunked}),每一块仍走 {@link execData}
+     *  (它的 {@link ensureConnected} 在建好连之后只剩生命周期的准入判:`destroy` 开始之后,后面的块不再写)。 */
+    private prepareChunked;
     /**
      * Write `content` to `abs` via argv-embedded base64, chunked at WRITE_CHUNK_BYTES (no stdin on the exec
      * channel we use; v4 has no per-channel close). `truncateFirst` → the FIRST chunk uses `>` (overwrite),

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

@@ -445,7 +445,7 @@ export class RemoteK8sExecutionEnv {
                 return r.ok ? { ok: true, exitCode: r.value.exitCode, stdout: r.value.stdout, stderr: r.value.stderr } : { ok: false, error: r.error.message };
             },
             write: async (abs, bytes) => {
-                const w = await this.writeChunked(abs, bytes, true, undefined, exec);
+                const w = await this.writeChunked(abs, bytes, true, exec);
                 return w.ok ? { ok: true } : { ok: false, error: w.error.message };
             },
         };
@@ -2175,13 +2175,24 @@ export class RemoteK8sExecutionEnv {
         return writeFileStaged(this.stagedLane(content), this.resolve(p), abortSignal);
     }
     stagedLane(content) {
-        return { upload: (dest, signal) => this.writeChunked(dest, content, true, signal), run: (cmd, signal) => this.fsExec(cmd, signal) };
+        return { prepare: this.prepareChunked(content, true), run: (cmd, signal) => this.fsExec(cmd, signal), provider: PROVIDER, logger: this.logger };
     }
     async appendFile(p, content, abortSignal) {
         const abs = this.resolve(p);
-        return appendFileStaged(this.stagedLane(content), abs, abortSignal, (ctx) => ctx.inPlace((signal) => this.writeChunked(abs, content, false, signal)));
+        return appendFileStaged(this.stagedLane(content), abs, abortSignal, this.prepareChunked(content, false));
     }
-    async writeChunked(abs, content, truncateFirst, abortSignal, exec = (command) => this.execData(command, abortSignal)) {
+    prepareChunked(content, truncateFirst) {
+        return async () => {
+            const c = await this.ensureConnected();
+            if (!c.ok)
+                return { ok: false, error: fileErrorFromExec(c.error) };
+            return {
+                ok: true,
+                value: { upload: (dest, signal) => this.writeChunked(dest, content, truncateFirst, (command) => this.execData(command, signal)) },
+            };
+        };
+    }
+    async writeChunked(abs, content, truncateFirst, exec) {
         const bytes = typeof content === "string" ? Buffer.from(content, "utf8") : Buffer.from(content);
         for (let off = 0, first = true; off < bytes.length || first; off += WRITE_CHUNK_BYTES, first = false) {
             const b64 = bytes.subarray(off, off + WRITE_CHUNK_BYTES).toString("base64");

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

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { type LaneHomeConfig } from "../lane-home-probe.js";
+import { type LaneLogger } from "./remote-shell.js";
 import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, type ExecutionEnvCapabilities } from "@sema-agent/core";
 import { type SandboxReadFloorKnob } from "../execution-lane-caps.js";
 import { type SandboxReadFloor } from "./sandbox-read-floor.js";
@@ -62,6 +63,8 @@ export interface LocalDockerEnvConfig extends LaneHomeConfig {
     sandboxReadFloor?: SandboxReadFloorKnob;
     /** 恢复点的填充座(`workspace-fill.ts`;工厂按 run 装配):容器新建之后、交给本环境之前,经本适配器自己的 `docker exec` 往工作区里放内容。缺席 ⇒ 不放。 */
     workspaceFill?: WorkspaceFill;
+    /** 运维日志座(起服装配递本服务的 logger):暂存写「已有目标的权限位没带过去」那一行经它(缺席 ⇒ 暂存编排自建一只,见 `remote-shell.ts` `StagedWriteLane.logger`)。 */
+    logger?: LaneLogger;
 }
 /** Inject `spawn` for tests (a fake docker CLI). Defaults to node's child_process spawn. */
 export interface LocalDockerEnvDeps {
@@ -176,7 +179,7 @@ export declare class RemoteLocalDockerExecutionEnv implements RemoteExecutionEnv
         abortSignal?: AbortSignal;
     }): Promise<Result<string[], FileError>>;
     /** 暂存写的两只面(规则与提交脚本的唯一属主 = `remote-shell.ts` `writeFileStaged` / `appendFileStaged`;父目录与私有暂存目录由编排的准备那一步建):
-     *  上传 = 容器内 `cat` 从 stdin 收整份字节落到私有目录里的暂存件({@link pipeIn});提交 = 容器内一次 shell 往返。两者同一身份 ——
+     *  上传 = 容器内 `cat` 从 stdin 收整份字节落到私有目录里的暂存件({@link pipeIn};阶段一无事可做 —— 传输调用本身就是起进程);提交 = 容器内一次 shell 往返。两者同一身份 ——
      *  同一只 argv 构造({@link startArgv}),都是镜像的用户。不用 `docker cp`:它由守护进程以 root 落盘,镜像用户 ≠ root 时暂存件属 root、
      *  提交方拿不走也清不掉,「目录不收新名字」也探不出来(root 哪里都写得进)。 */
     private stagedLane;

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

@@ -3,7 +3,7 @@ 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, appendFileStaged, writeFileStaged } from "./remote-shell.js";
+import { shellQuote, armPipeDestroyGrace, appendFileStaged, readyUpload, 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";
@@ -420,7 +420,7 @@ export class RemoteLocalDockerExecutionEnv {
         return ok(lines);
     }
     stagedLane(content) {
-        return { upload: (dest, signal) => this.pipeIn(content, dest, signal), run: (cmd, signal) => this.fsExec(cmd, signal) };
+        return { prepare: readyUpload((dest, signal) => this.pipeIn(content, dest, signal)), run: (cmd, signal) => this.fsExec(cmd, signal), provider: PROVIDER, logger: this.cfg.logger };
     }
     async writeFile(p, content, abortSignal) {
         const ready = await this.fsReady(p);
@@ -433,7 +433,7 @@ export class RemoteLocalDockerExecutionEnv {
         if (!ready.ok)
             return ready;
         const abs = this.resolve(p);
-        return appendFileStaged(this.stagedLane(content), abs, abortSignal, (ctx) => ctx.inPlace((signal) => this.pipeIn(content, abs, signal, ">>")));
+        return appendFileStaged(this.stagedLane(content), abs, abortSignal, readyUpload((dest, signal) => this.pipeIn(content, dest, 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);

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

@@ -1,4 +1,5 @@
 import { type SshHostKeyPolicy } from "../ssh-host-key.js";
+import { type LaneLogger } from "./remote-shell.js";
 import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
 import { type LaneHomeConfig } from "../lane-home-probe.js";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
@@ -36,6 +37,8 @@ export interface SshEnvConfig extends LaneHomeConfig {
     };
     /** [ref] / [ref]:主机密钥校验策略(两旋钮,语义见 {@link SshHostKeyPolicy});缺席 = 两旋钮都没配。 */
     hostKey?: SshHostKeyPolicy;
+    /** 运维日志座(起服装配递本服务的 logger):暂存写「已有目标的权限位没带过去」那一行经它(缺席 ⇒ 暂存编排自建一只,见 `remote-shell.ts` `StagedWriteLane.logger`)。 */
+    logger?: LaneLogger;
 }
 type ConnectResult = {
     ok: true;
@@ -172,13 +175,16 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
     }): Promise<Result<string[], FileError>>;
     readBinaryFile(p: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
     /** 暂存写的两只面(规则与提交脚本的唯一属主 = `remote-shell.ts` `writeFileStaged` / `appendFileStaged`;父目录与私有暂存目录由编排的准备那一步建):
-     *  上传 = sftp 整份写到私有目录里的暂存件;提交 = 文件面探针 exec。两者同一身份(sftp 子系统与 exec 都是这条连接的登录用户)。
+     *  上传 = sftp 整份写到私有目录里的暂存件(阶段一 = 拿 sftp 通道,见 {@link prepareSftp};阶段二 = 写);提交 = 文件面探针 exec。两者同一身份(sftp 子系统与 exec 都是这条连接的登录用户)。
      *  sftp 写不收取消信号 ⇒ 取消在传输结束之后、提交之前生效(目标未碰)。 */
     private stagedLane;
+    /** 阶段一(备件):拿 sftp 通道 —— 连接断了在这里懒重连,取消落在这里 ⇒ `aborted`、没有一个字节发出;阶段二:`write` 把整份字节经这条通道写到 `dest`
+     *  (sftp 写不收取消信号:一旦发出就写完,答成功)。`abs` = 目标路径(阶段一失败的错误点名它)。 */
+    private prepareSftp;
     /** 整旧或整新(暂存 → 一次 `mv -f`)。修前 `sftp.writeFile(abs)` 就地 O_TRUNC:传输中途断 ⇒ 目标 = 半份新件。 */
     writeFile(p: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
     /** 追加(暂存要加的字节 → 一次 `cat >>`;inode 不换、已有字节不重写)。修前 = 读旧 + 拼 + 整份就地重写(O(文件);中途断 ⇒ 半份)。
-     *  目录不收新名字 / 私有目录收不成私有时的退路 = sftp 直接追加到目标。 */
+     *  目录不收新名字 / 私有目录收不成私有时的退路 = sftp 直接追加到目标(拿通道是备件阶段:取消落在那里 ⇒ `aborted`、目标未碰;追加那一步不收取消,发出就写完)。 */
     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

@@ -51,6 +51,7 @@ export class RemoteSshExecutionEnv {
             dataTimeoutMs: config.dataTimeoutMs ?? 5 * 60_000,
             retry: { maxAttempts: config.retry?.maxAttempts ?? 3, backoffMs: config.retry?.backoffMs ?? 500 },
             hostKey: config.hostKey,
+            logger: config.logger,
         };
         this.cwd = this.cfg.mountPath;
         this.homeSeat = new LaneHomeSeat(PROVIDER, config);
@@ -622,37 +623,38 @@ 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) {
-        return writeFileStaged(this.stagedLane(bytesOf(content)), this.resolve(p), abortSignal);
+    stagedLane(abs, data) {
+        return { prepare: this.prepareSftp(abs, (sftp, dest, done) => sftp.writeFile(dest, data, done)), run: (cmd, signal) => this.fsExec(cmd, signal), provider: PROVIDER, logger: this.cfg.logger };
     }
-    async appendFile(p, content, abortSignal) {
-        const abs = this.resolve(p);
-        const data = bytesOf(content);
-        return appendFileStaged(this.stagedLane(data), abs, abortSignal, (ctx) => ctx.inPlace(async (signal) => {
+    prepareSftp(abs, write) {
+        return 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);
+                return ok({
+                    upload: async (dest) => {
+                        try {
+                            await new Promise((resolve, reject) => write(sftp, dest, (err) => (err ? reject(err) : resolve())));
+                            return ok(undefined);
+                        }
+                        catch (e) {
+                            return { ok: false, error: this.fileError(e, dest) };
+                        }
+                    },
+                });
             }
             catch (e) {
                 return { ok: false, error: this.fileError(e, abs) };
             }
-        }));
+        };
+    }
+    async writeFile(p, content, abortSignal) {
+        const abs = this.resolve(p);
+        return writeFileStaged(this.stagedLane(abs, bytesOf(content)), abs, abortSignal);
+    }
+    async appendFile(p, content, abortSignal) {
+        const abs = this.resolve(p);
+        const data = bytesOf(content);
+        return appendFileStaged(this.stagedLane(abs, data), abs, abortSignal, this.prepareSftp(abs, (sftp, dest, done) => sftp.appendFile(dest, data, done)));
     }
     async fileInfo(p, abortSignal) {
         const abs = this.resolve(p);

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

@@ -209,6 +209,12 @@ export declare function runSymlinkChain(absPath: string, run: ShellChainRun): Pr
  * 残留记录走 stdout、错误走 stderr:两条通道不混,分类器读到的 stderr 里没有路径文本。记录不改脚本的退出码:写照它自己的结局答,残留另行留痕。
  */
 export declare const STAGE_DIR_LEFT_MARK = "sema: staging directory left behind:";
+/**
+ * 提交脚本往 stdout 写的另一种记录(与 {@link STAGE_DIR_LEFT_MARK} 同机制:`<记号> <值>` + NUL 收尾,同一只读口 {@link scriptRecordsOf}):已有目标的权限位**没带到**换上去的新件上
+ * ({@link carryMode} 读不出 / 读不懂 / `chmod` 被拒,而随后 `mv` 换上去了)—— 值 = 目标原来的模式串(读不出时为空)。`mv` 没成、落到就地拷入那一段时不写:原 inode 的模式本来就不变。
+ * 编排读到它 ⇒ 写照样成功 + 一行运维 warn `remote_env_file_mode_failed`(「传完之后设模式」全树一种策略:尽力而为 + 一行 warn;见 {@link landStaged})。
+ */
+export declare const STAGE_MODE_NOT_CARRIED_MARK = "sema: file mode not carried:";
 /** 一次远端写的暂存位置(纯数据):`dir` = 目标目录下的私有目录,`file` = 其中那只暂存文件。 */
 export interface StagingPaths {
     readonly dir: string;
@@ -231,15 +237,20 @@ export declare function buildStagingPrepareCommand(stage: StagingPaths): string;
  * 整文件替换的提交脚本(POSIX sh,纯数据 ⇒ `build*`)。一次往返,**整条命令只有一个退出状态**(`{ …; }`,理由同
  * {@link buildSymlinkChainCommand} 头注)。`d` = 私有目录,`s` = 其中的暂存件,`t` = 目标。
  *
- *  1. 叶是符号链接 ⇒ 读**一跳**(`readlink`,不带 `-f`;相对目标锚在链接自己的目录,不折 `..`,与链视图同一词法;
- *     链接文本的结尾换行原样保留 —— `-n` 不加换行,`$(…)` 会吞掉结尾换行,所以输出后垫一个 `.` 再剥掉;`-n` 不被认 ⇒ 读不出一跳 ⇒ 第 3 步经链接就地写):那一跳是常规文件或还不存在
- *     ⇒ 提交落到那一跳上(链接保持是链接);否则(链 / 非常规)⇒ 走第 3 步就地写。
+ *  1. 叶是符号链接 ⇒ 读**一跳**(`readlink`,不带 `-f` 也不带 `-n` —— `-n` 不在 POSIX 里;相对目标锚在链接自己的目录,不折 `..`,与链视图同一词法;
+ *     输出后垫一个 `.` 再剥掉 `.` 与 `readlink` 加的那一个换行:`$(…)` 会吞掉结尾换行,垫 `.` 才保得住)。**读到的链接文本只有核过才信**:那一跳是常规文件、且与链接解出来的是同一只文件
+ *     (`[ -ef ]`:同设备同 inode),且同目录里没有「这个名字再加一个结尾换行」的另一个名字 ⇒ 提交落到那一跳上(链接保持是链接)。核这两道是因为不带 `-n` 时,结尾带换行的链接文本在有的实现(BSD)上
+ *     读不出与「少一个换行」的另一个名字的分别 —— 读错了,rename 会换掉另一只文件(或,两个名字是同一 inode 的硬链接时,`-ef` 也核得过,rename 换掉的却不是链接指的那个名字);核不上就不信。
+ *     核不上 / 读不出 / 悬空(那一跳还不存在,读到的文本无从核)/ 链 / 非常规 ⇒ 走第 3 步经链接就地写(目标正确,非原子)。
  *  2. 目标是常规文件或不存在 ⇒ 私有目录不在目标的目录里(跟了一跳)⇒ 先在目标目录里用**同一只私有目录名**、同样生来 0700、同样收紧过地**重新暂存**一份
- *     (目标机本地拷贝,不过网络;拷成了就改用新的那只、删原私有目录;拷不成就删掉新建的那只、收紧不成就放弃它,用原暂存件 ——
+ *     (目标机本地拷贝,不过网络;拷成了就改用新的那只、删原私有目录;拷不成就删掉新建的那只、用原暂存件;建不出来(目录不收新名字)同此;
+ *     新建的那只被放进了别人的 `data`(收紧之后核出)就放弃它、用原暂存件 ——
  *     删不掉的都写一条 {@link STAGE_DIR_LEFT_MARK} 记录),
  *     让 rename 不跨文件系统(与 core 把暂存放在最终目标旁边同形);
- *     已有文件的权限位带到暂存件上(`stat -c %a`,BSD 退到 `stat -f %Lp`;带不过去不拦)—— **在 `mv` 之前**,换上去的那一刻权限位已是目标的;
- *     `mv -f` 换上去,成功 ⇒ 删私有目录(删不掉 ⇒ 一条 {@link STAGE_DIR_LEFT_MARK} 记录,仍 `exit 0`:目标已是新件)。
+ *     **收不成私有**(同一只 {@link hardenPrivate} 不过)⇒ 放弃新建的那只、写 {@link RESTAGE_DIR_UNSEALED_MESSAGE}、**退出 {@link STAGE_DIR_UNSEALED_EXIT}**、目标未碰、原暂存件还在
+ *     —— 与准备那一步的同名出口是同一条退路:编排清掉原暂存件、计 `stage-seal-fallback`、直接写目标(不再静默拿原暂存件 `mv` 过去:目标在另一个文件系统上时那是一次非原子的拷贝,且不留痕);
+ *     已有文件的权限位带到暂存件上({@link carryMode}:按 {@link readModeOwner} 读目标的模式串、换成八进制再 `chmod`,含 setuid / setgid / 粘滞位;带不过去不拦,记下读到的模式串)—— **在 `mv` 之前**,换上去的那一刻权限位已是目标的;
+ *     `mv -f` 换上去,成功 ⇒ 带不过去时先写一条 {@link STAGE_MODE_NOT_CARRIED_MARK} 记录,再删私有目录(删不掉 ⇒ 一条 {@link STAGE_DIR_LEFT_MARK} 记录,仍 `exit 0`:目标已是新件)。
  *  3. 其余(链接链 / FIFO / 设备 / 目录 / `mv` 被拒,如单文件绑定挂载的 EBUSY)⇒ 已落定的暂存件就地拷进目标(与 core 的回落同形:
  *     非原子,但不再经过网络传输),见 {@link takeAndWrite}:先把暂存件**打开**(读不了 ⇒ 先补上属主读位,仍读不了 ⇒ 非零退出、目标未碰),
  *     再**删掉暂存名**(删不掉 ⇒ 非零退出、目标未碰,残留目录由脚本点名),然后才从已打开的那份拷进目标,最后关 fd、删私有目录(删不掉只记录)。于是
@@ -254,6 +265,26 @@ export declare function buildStagedCommitCommand(stage: StagingPaths, target: st
 export declare function buildStagedAppendCommand(stage: StagingPaths, target: string): string;
 /** 清掉一次写的私有目录({@link removalOf}:只删 `data` 与这只目录;不在 ⇒ 什么都不做;退出 0 ⇔ 不在了)。纯数据 ⇒ `build*`。 */
 export declare function buildStagingDiscardCommand(stage: StagingPaths): string;
+/**
+ * 一次传输的两段 —— **取消的读法只看在哪一段**:
+ *  · 阶段一 = 备件({@link PrepareUpload}):第一个字节发往目标机之前的一切 —— adb 在本机落的临时件、ssh 开 sftp 通道(含懒重连)、k8s 建连、追加退路里的读旧 + 拼。
+ *    这一段取消或失败 ⇒ 没有一个字节到过任何目的地(暂存也好、目标也好),照实答:`aborted` 就是 `aborted`、目标未碰。
+ *  · 阶段二 = {@link PreparedUpload.upload}:字节真发出的那一段。暂存路上它被取消打断 ⇒ 暂存件被删、目标未碰(`aborted`);**退路(就地写目标)上**它被取消打断 ⇒ `unknown`
+ *    (可能已有字节到了目标,见 {@link writeInPlace});它不收取消(ssh 的 sftp)⇒ 照样写完,结果照实。
+ * 阶段二只有编排调用(腿交出备好的 {@link PreparedUpload},自己不调它)—— 「哪一段包不包」不靠腿记得。
+ */
+export interface PreparedUpload {
+    /** 阶段二:把备好的**整份**字节放到 `dest`(建或覆盖,追加退路的腿把它读作追加)。 */
+    upload(dest: string, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** 放掉阶段一造的东西(adb 的本机临时件)。编排对每一份备好的东西恰调一次(传完、传败、放弃都调);**不抛**。 */
+    release?(): Promise<void>;
+}
+/** 阶段一:备好要传的字节。取消或失败 ⇒ 没有字节到过任何目的地(见 {@link PreparedUpload});答成功 ⇒ 交出阶段二。 */
+export type PrepareUpload = (abortSignal?: AbortSignal) => Promise<Result<PreparedUpload, FileError>>;
+/**
+ * 阶段一无事可做的腿(local-docker:传输调用本身就是起进程;e2b:`files.write` 是一次调用)的 {@link PrepareUpload}:备件即刻就绪,`upload` 就是腿的传输。
+ */
+export declare function readyUpload(upload: PreparedUpload["upload"]): PrepareUpload;
 /**
  * 一次暂存写交给 {@link writeFileStaged} / {@link appendFileStaged} 的两只面 —— 各腿的传输留在腿上,规则在这里。
  * 🔴 **`upload` 与 `run` 必须是同一个身份、在同一台机器上**:私有目录由 `run` 建(0700,属写入方),`upload` 要进得去;提交由 `run` 做,
@@ -261,44 +292,42 @@ export declare function buildStagingDiscardCommand(stage: StagingPaths): string;
  * 与 `run` 同一身份的传输,不能让编排迁就它。
  */
 export interface StagedWriteLane {
-    /** 把**整份**字节放到 `dest`(新建;`dest` 的目录已在且是写入方的私有目录)—— 腿自己的传输(sftp / adb push / 容器内 `cat` 收 stdin / 分块 exec / provider 文件 API)。 */
-    upload(dest: string, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /** 腿的传输(两段,见 {@link PreparedUpload}):阶段一备好整份字节;阶段二 `upload(dest)` 把它放到 `dest`(新建;暂存路上 `dest` 的目录已在且是写入方的私有目录,退路上 `dest` 就是目标)。 */
+    prepare: PrepareUpload;
     /** 目标机上的一次 shell 往返(腿的文件面探针 exec:只用绝对路径,不进工作目录)。`abortSignal` 只有准备那一步带(提交一旦发出不再听取消)。 */
     run(cmd: string, abortSignal?: AbortSignal): ReturnType<ShellChainRun>;
+    /** 车道名(运维行的 `provider` 位,与各适配器自己的运维行同一个词)。 */
+    readonly provider: string;
+    /** 运维日志座(适配器递起服装配给它的那一只;缺席 ⇒ 编排自建一只 JSON 行 logger,见 {@link fallbackLaneLogger})。今天只有「权限位没带过去」那一行经它。 */
+    readonly logger?: LaneLogger | undefined;
 }
-/**
- * 退路拿到的两样(编排为每一次退路造一只,见 {@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>>;
+/** 编排说话用的那一面(与各适配器的 logger 座同形)。 */
+export interface LaneLogger {
+    warn(event: string, fields?: Record<string, unknown>): void;
 }
 /**
- * 不暂存时的退路 —— 目录不收新名字(建私有目录被 `permission_denied` 拒)或私有目录收不成私有:腿直接对目标做的那一步(core 同一条回落:文件本身可能可写)。
- * 两只文件面、五条腿**必传**:写面 = 腿的上传直落目标;追加面 = 能追加写的腿(ssh / local-docker / k8s)直接追加到目标,只能把整份文件落到一个路径上的腿
- * (e2b 的 `files.write`、adb 的 push)读旧 + 拼 + 整份写目标(adb 的这一形就是 7.138.x 的追加)。字节流向目标的那一步必须经 `ctx.inPlace`(读旧不包)。
+ * 不暂存时的退路 —— 目录不收新名字(建私有目录被 `permission_denied` 拒)或私有目录收不成私有:腿直接对目标做的那一次写(core 同一条回落:文件本身可能可写)。
+ * 与腿的传输同一个形({@link PrepareUpload}),编排以目标本身为 `dest` 调它的 `upload`。两只文件面、五条腿**必传**:写面 = 腿自己的传输({@link StagedWriteLane.prepare});
+ * 追加面 = 能追加写的腿(ssh / local-docker / k8s)阶段二直接追加到目标,只能把整份文件落到一个路径上的腿(e2b 的 `files.write`、adb 的 push)阶段一读旧 + 拼
+ * ({@link rewriteAppend}),阶段二整份写目标(adb 的这一形就是 7.138.x 的追加)。
  */
-export type StagedWriteDirect = (ctx: StagedDirectContext) => Promise<Result<void, FileError>>;
+export type StagedWriteDirect = PrepareUpload;
 /**
- * 只能把整份文件落到一个路径上的腿(e2b 的 `files.write`、adb 的 push)在退路里的追加 —— 两腿共用这一只,各自只给读与写:
- * 读旧(`not_found` ⇒ 按空;别的读错原样透出、不写)+ 按字节拼(二进制安全)+ 整份写目标。读旧**不**经 `ctx.inPlace`(取消落在这里 ⇒ `aborted`、目标未碰),
- * 整份写经 `ctx.inPlace`(见 {@link StagedDirectContext})。adb 的这一形就是 7.138.x 的追加。
+ * 只能把整份文件落到一个路径上的腿(e2b 的 `files.write`、adb 的 push)在退路里的追加 —— 两腿共用这一只,各自只给读与「由拼好的整份字节造阶段一」:
+ * 阶段一 = 读旧(`not_found` ⇒ 按空;别的读错原样透出、不写)+ 按字节拼(二进制安全)+ 腿的备件;阶段二 = 整份写目标。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>>;
+export declare function rewriteAppend(read: (abortSignal?: AbortSignal) => Promise<Result<Uint8Array, FileError>>, prepareOf: (merged: Uint8Array) => PrepareUpload, add: string | Uint8Array): PrepareUpload;
 /**
  * 远端整文件替换(ssh / adb / local-docker / k8s / e2b 五条腿调同一只;父目录由准备那一步建)。契约:成功 ⇒ 目标整份是新内容;传输失败 ⇒ 目标整份是旧内容;
- * `aborted` ⇒ 目标未碰。私有目录清不掉 ⇒ 错误消息点名残留的目录。目录不收新名字、或私有目录收不成私有 ⇒ 不暂存,腿的上传直接落目标一次(旧形,core 同一条回落;非原子)。
+ * `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})。
+ * 远端追加(五条腿调同一只;`lane.prepare` 备的是**要加的那几个字节**)。暂存那条路的契约:成功 ⇒ 目标 = 旧内容 + 新字节;传输失败 / `aborted` ⇒
+ * 目标未碰;已有字节从不被重写、inode 不换。`direct` = 目录不收新名字 / 私有目录收不成私有时腿直接写目标的那一次(必传,见 {@link StagedWriteDirect}),
+ * 不在上面的契约里:非原子 —— 中途断 ⇒ 目标可能只加上了一部分(整份写目标的 e2b / adb:已有字节被重写,目标可能没了或只剩半份);取消落在**备件阶段**(含读旧)
+ * ⇒ `aborted`、目标未碰;传输那一步因取消中断 ⇒ `unknown`、目标可能只写了一半(见 {@link PreparedUpload})。
  */
 export declare function appendFileStaged(lane: StagedWriteLane, abs: string, abortSignal: AbortSignal | undefined, direct: StagedWriteDirect): Promise<Result<void, FileError>>;
 //# sourceMappingURL=remote-shell.d.ts.map