@sema-agent/server 7.146.0 → 7.148.0

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-scratchpad.js

@@ -6,8 +6,11 @@ export function remoteScratchpadDirFor(sessionId) {
     return `/tmp/scratchpad/${sessionId}`;
 }
 export function withRemoteScratchpad(factory, logger) {
+    const decorated = new WeakSet();
     return async (ctx) => {
         const env = await factory(ctx);
+        if (decorated.has(env))
+            return env;
         const dir = remoteScratchpadDirFor(ctx.sessionId);
         if (dir === undefined) {
             if (ctx.sessionId)
@@ -17,6 +20,7 @@ export function withRemoteScratchpad(factory, logger) {
         const e = env;
         if (typeof e.exec !== "function")
             return env;
+        decorated.add(env);
         const origExec = e.exec.bind(e);
         let ensured;
         const ensure = () => (ensured ??= (async () => {

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

package/dist/plugins/remote-shell.js

@@ -1,6 +1,8 @@
 import { ExecutionError, FileError, SYMLINK_CHAIN_MAX_HOPS } from "@sema-agent/core";
 import { NAME_MAX_BYTES, classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
 import { recordFailOpen } from "../observability/fail-open.js";
+import { createLogger } from "../observability/logger.js";
+import { seatText } from "../trace/exit-seat.js";
 import { randomBytes } from "node:crypto";
 export const EXEC_FORCE_SETTLE_GRACE_MS = 3000;
 export function armPipeDestroyGrace(child) {
@@ -157,8 +159,11 @@ export async function runSymlinkChain(absPath, run) {
 const STAGED_FILE = "data";
 const STAGE_DIR_REFUSED_EXIT = 3;
 const STAGE_DIR_UNSEALED_EXIT = 4;
-const STAGE_DIR_UNSEALED_MESSAGE = "sema: the private staging directory could not be made private (chmod 700 failed or did not take effect, the mode or owner read back differently, or an inherited ACL entry could not be removed or read on this platform — the filesystem ignores permission bits or the parent directory carries a default or inheritable ACL); nothing was staged";
+const STAGE_DIR_UNSEALED_REASON = "chmod 700 failed or did not take effect, the mode or owner read back differently, or an inherited ACL entry could not be removed or read on this platform — the filesystem ignores permission bits or the parent directory carries a default or inheritable ACL";
+const STAGE_DIR_UNSEALED_MESSAGE = `sema: the private staging directory could not be made private (${STAGE_DIR_UNSEALED_REASON}); nothing was staged`;
+const RESTAGE_DIR_UNSEALED_MESSAGE = `sema: the private staging directory beside the link's target could not be made private (${STAGE_DIR_UNSEALED_REASON}); the target was not touched`;
 export const STAGE_DIR_LEFT_MARK = "sema: staging directory left behind:";
+export const STAGE_MODE_NOT_CARRIED_MARK = "sema: file mode not carried:";
 export function buildStagingPaths(abs, nonce = randomBytes(6).toString("hex")) {
     const cut = abs.lastIndexOf("/");
     const parent = abs.slice(0, cut + 1);
@@ -172,9 +177,11 @@ export function buildStagingPaths(abs, nonce = randomBytes(6).toString("hex")) {
 function privateMkdir(dir) {
     return `(umask 077 && mkdir -- ${dir})`;
 }
+function readModeOwner(path) {
+    return `l=$(ls -ldn -- ${path} 2>/dev/null) && set -f && set -- $l && [ -n "$3" ]`;
+}
 function hardenPrivate(dir) {
-    const statOf = (gnu, bsd) => `$(stat -c ${gnu} -- ${dir} 2>/dev/null || stat -f ${bsd} -- ${dir} 2>/dev/null)`;
-    return `( chmod -- 700 ${dir} 2>/dev/null && m=${statOf("%a", "%Lp")} && u=${statOf("%u", "%u")} && case "$m" in 700|[1-7]700) [ "$u" = "$(id -u)" ];; *) false;; esac && ${aclCleared(dir)} )`;
+    return `( chmod -- 700 ${dir} 2>/dev/null && ${readModeOwner(dir)} && case "$1" in drw[xs]--[-S]--[-T]*) [ "$3" = "$(id -u)" ];; *) false;; esac && ${aclCleared(dir)} )`;
 }
 function aclCleared(dir) {
     const marker = `ls_out=$(cd ${dir} && ls -ld . 2>&1) && [ -z "$(printf '%s\\n' "$ls_out" | sed -n 2p)" ] && mode_word=\${ls_out%% *} && ` +
@@ -189,9 +196,6 @@ function aclCleared(dir) {
 function emptyPrivate(dir) {
     return `[ ! -e ${dir}/${STAGED_FILE} ] && [ ! -L ${dir}/${STAGED_FILE} ]`;
 }
-function sealPrivate(dir) {
-    return `${hardenPrivate(dir)} && ${emptyPrivate(dir)}`;
-}
 function removalOf(dir) {
     return `{ [ ! -L ${dir} ] && rm -f -- ${dir}/${STAGED_FILE} && { rmdir -- ${dir} 2>/dev/null || [ ! -e ${dir} ]; }; }`;
 }
@@ -213,21 +217,31 @@ export function buildStagingPrepareCommand(stage) {
 }
 function takeAndWrite(redirect) {
     return (`[ -r "$s" ] || chmod -- u+r "$s" 2>/dev/null; exec 3< "$s" || exit 1; { [ ! -L "$d" ] && rm -f -- "$s"; } || { ${leftMark(`"$d"`)}; exit 1; }; ` +
-        `cat <&3 ${redirect} "$t"; w=$?; exec 3<&-; ${removePrivate(`"$d"`)}; exit $w; `);
+        `cat <&3 ${redirect} "$t"; w=$?; [ "$w" -eq 0 ] || w=1; exec 3<&-; ${removePrivate(`"$d"`)}; exit $w; `);
+}
+function carryMode(src, dst) {
+    const digit = `perm_digit() { case "$1" in ---|--S|--T) echo 0;; --x|--s|--t) echo 1;; -w-|-wS|-wT) echo 2;; -wx|-ws|-wt) echo 3;; ` +
+        `r--|r-S|r-T) echo 4;; r-x|r-s|r-t) echo 5;; rw-|rwS|rwT) echo 6;; rwx|rws|rwt) echo 7;; *) return 1;; esac; }`;
+    const triples = `m=\${1#?} && pu=\${m%"\${m#???}"} && m=\${m#???} && pg=\${m%"\${m#???}"} && m=\${m#???} && po=\${m%"\${m#???}"}`;
+    const special = `sp=0; case "$pu" in ??[sS]) sp=4;; esac; case "$pg" in ??[sS]) sp=$((sp+2));; esac; case "$po" in ??[tT]) sp=$((sp+1));; esac`;
+    return (`( if ${readModeOwner(src)}; then ${digit} && ${triples} && du=$(perm_digit "$pu") && dg=$(perm_digit "$pg") && do_=$(perm_digit "$po") && ` +
+        `{ ${special}; chmod "$sp$du$dg$do_" ${dst}; } && exit 0; printf '%s' "$1"; fi; exit 1 ) 2>/dev/null`);
 }
 export function buildStagedCommitCommand(stage, target) {
     return (`{ d=${shellQuote(stage.dir)}; s="$d/${STAGED_FILE}"; t=${shellQuote(target)}; ` +
-        `if [ -L "$t" ]; then h=$(readlink -n -- "$t" && printf .) || h=; h=\${h%.}; ` +
+        `if [ -L "$t" ]; then nl=$(printf '\\n.'); nl=\${nl%.}; h=$(readlink -- "$t" && printf .) || h=; h=\${h%.}; h=\${h%"$nl"}; ` +
         `case "$h" in "") ;; /*) ;; *) l="\${t%/*}"; case "$l" in "") h="/$h" ;; */) h="$l$h" ;; *) h="$l/$h" ;; esac ;; esac; ` +
-        `if [ -n "$h" ] && [ ! -L "$h" ] && { [ ! -e "$h" ] || [ -f "$h" ]; }; then t="$h"; fi; fi; ` +
+        `if [ -n "$h" ] && [ ! -L "$h" ] && [ -f "$h" ] && [ ! -e "$h$nl" ] && [ ! -L "$h$nl" ] && [ "$h" -ef "$t" ]; then t="$h"; fi; fi; ` +
         `if [ ! -L "$t" ] && { [ ! -e "$t" ] || [ -f "$t" ]; }; then ` +
         `if [ "\${t%/*}" != "\${d%/*}" ]; then e="\${t%/*}/\${d##*/}"; ` +
         `if { ${privateMkdir(`"$e"`)}; } 2>/dev/null; then ` +
-        `if { ${sealPrivate(`"$e"`)}; } 2>/dev/null; then ` +
+        `if { ${hardenPrivate(`"$e"`)}; } 2>/dev/null; then ` +
+        `if { ${emptyPrivate(`"$e"`)}; } 2>/dev/null; then ` +
         `if cat -- "$s" > "$e/${STAGED_FILE}" 2>/dev/null; then o="$d"; d="$e"; s="$e/${STAGED_FILE}"; ${removePrivate(`"$o"`)}; else ${removePrivate(`"$e"`)}; fi; ` +
-        `else ${abandonPrivate(`"$e"`)}; fi; fi; fi; ` +
-        `if [ -f "$t" ]; then m=$(stat -c %a -- "$t" 2>/dev/null || stat -f %Lp -- "$t" 2>/dev/null) && chmod "$m" "$s" 2>/dev/null; fi; ` +
-        `if mv -f -- "$s" "$t" 2>/dev/null; then ${removePrivate(`"$d"`)}; exit 0; fi; fi; ` +
+        `else ${abandonPrivate(`"$e"`)}; fi; ` +
+        `else ${abandonPrivate(`"$e"`)}; printf '%s\\n' ${shellQuote(RESTAGE_DIR_UNSEALED_MESSAGE)} >&2; exit ${STAGE_DIR_UNSEALED_EXIT}; fi; fi; fi; ` +
+        `carry_mode() { ${carryMode('"$t"', '"$s"')}; }; cm=-; if [ -f "$t" ]; then cm=$(carry_mode) && cm=-; fi; ` +
+        `if mv -f -- "$s" "$t" 2>/dev/null; then [ "$cm" = - ] || printf '%s %s\\0' ${shellQuote(STAGE_MODE_NOT_CARRIED_MARK)} "$cm"; ${removePrivate(`"$d"`)}; exit 0; fi; fi; ` +
         `${takeAndWrite(">")}}`);
 }
 export function buildStagedAppendCommand(stage, target) {
@@ -236,14 +250,77 @@ export function buildStagedAppendCommand(stage, target) {
 export function buildStagingDiscardCommand(stage) {
     return removalOf(shellQuote(stage.dir));
 }
-async function discardStaged(lane, stage) {
-    const r = await lane.run(buildStagingDiscardCommand(stage));
+export function readyUpload(upload) {
+    return async () => ({ ok: true, value: { upload } });
+}
+async function cleanOnce(lane, cmd, fallbackWhy) {
+    const r = await lane.run(cmd);
     if (!r.ok)
         return r.error.message;
-    return r.value.exitCode === 0 ? undefined : r.value.stderr.trim() || "it holds something this write did not put there, or it was replaced by a link";
+    return r.value.exitCode === 0 ? undefined : r.value.stderr.trim() || fallbackWhy;
+}
+function scriptRecordsOf(stdout) {
+    const heads = [
+        { kind: "left", head: `${STAGE_DIR_LEFT_MARK} ` },
+        { kind: "mode", head: `${STAGE_MODE_NOT_CARRIED_MARK} ` },
+    ];
+    const leftDirs = [];
+    let modeNotCarried;
+    for (const rec of stdout.split("\0")) {
+        let first;
+        for (const { kind, head } of heads) {
+            const at = rec.indexOf(head);
+            if (at >= 0 && (first === undefined || at < first.at))
+                first = { kind, at, head };
+        }
+        if (first === undefined)
+            continue;
+        const value = rec.slice(first.at + first.head.length);
+        switch (first.kind) {
+            case "left":
+                leftDirs.push(value);
+                break;
+            case "mode":
+                modeNotCarried = value;
+                break;
+            default: {
+                const unreachable = first.kind;
+                throw new Error(`unhandled script record kind ${String(unreachable)}`);
+            }
+        }
+    }
+    return { leftDirs, modeNotCarried };
+}
+async function settleStaging(lane, stage, named, discardOriginal) {
+    const todo = new Map();
+    if (discardOriginal)
+        todo.set(stage.dir, { cmd: buildStagingDiscardCommand(stage), why: "it holds something this write did not put there, or it was replaced by a link" });
+    const name = stage.dir.slice(stage.dir.lastIndexOf("/") + 1);
+    for (const dir of named) {
+        if (todo.has(dir))
+            continue;
+        const faithful = dir.endsWith(`/${name}`) && !dir.includes("\uFFFD");
+        todo.set(dir, faithful ? { cmd: reapCommandOf(dir), why: "it still holds an entry, or it was replaced by a link" } : { cmd: undefined, why: "the script named a directory that is not this write's staging directory under a path that can be trusted; left alone" });
+    }
+    const left = [];
+    for (const [dir, { cmd, why }] of todo) {
+        const still = cmd === undefined ? why : await cleanOnce(lane, cmd, why);
+        if (still === undefined)
+            continue;
+        left.push({ dir, why: still });
+        recordFailOpen("server.remote-write.staging-dir-left", dir);
+    }
+    return left;
 }
-function withResidue(e, stage, why) {
-    return why === undefined ? e : new FileError(e.code, `${e.message} (the staging directory ${stage.dir} could not be removed: ${why})`, e.path, e);
+function reapCommandOf(dir) {
+    const d = shellQuote(dir);
+    return `{ rmdir -- ${d} 2>/dev/null || { [ ! -e ${d} ] && [ ! -L ${d} ]; }; }`;
+}
+function withResidue(e, left) {
+    if (left.length === 0)
+        return e;
+    const named = left.length === 1 ? `the staging directory ${left[0].dir}` : `the staging directories ${left.map((l) => l.dir).join(", ")}`;
+    return new FileError(e.code, `${e.message} (${named} could not be removed: ${left.map((l) => l.why).join("; ")})`, e.path, e);
 }
 async function landStaged(lane, abs, abortSignal, commitOf, direct) {
     if (abortSignal?.aborted)
@@ -251,78 +328,114 @@ async function landStaged(lane, abs, abortSignal, commitOf, direct) {
     const stage = buildStagingPaths(abs);
     const prep = await lane.run(buildStagingPrepareCommand(stage), abortSignal);
     if (!prep.ok) {
-        const left = await discardStaged(lane, stage);
-        return { ok: false, error: withResidue(fileErrorFromExec(prep.error, abs), stage, left) };
+        const left = await settleStaging(lane, stage, [], true);
+        return { ok: false, error: withResidue(fileErrorFromExec(prep.error, abs), left) };
     }
     if (prep.value.exitCode !== 0) {
-        noteLeftDirs(prep.value.stdout);
+        const left = await settleStaging(lane, stage, scriptRecordsOf(prep.value.stdout).leftDirs, false);
         if (abortSignal?.aborted)
-            return { ok: false, error: new FileError("aborted", "aborted before the write started; the target was not touched", abs) };
+            return { ok: false, error: withResidue(new FileError("aborted", "aborted before the write started; the target was not touched", abs), left) };
         const e = classifyFsStderr(prep.value.stderr, abs, "unknown");
         if (prep.value.exitCode === STAGE_DIR_REFUSED_EXIT && e.code === "permission_denied")
-            return direct(createDirectContext(abs, abortSignal, "the directory does not accept new names"));
+            return viaDirect(direct, abs, abortSignal, "the directory does not accept new names", left);
         if (prep.value.exitCode === STAGE_DIR_UNSEALED_EXIT) {
             recordFailOpen("server.remote-write.stage-seal-fallback", `${abs}: ${prep.value.stderr.trim()}`);
-            return direct(createDirectContext(abs, abortSignal, "the private staging directory could not be made private"));
+            return viaDirect(direct, abs, abortSignal, "the private staging directory could not be made private", left);
         }
-        return { ok: false, error: e };
+        return { ok: false, error: withResidue(e, left) };
     }
     if (abortSignal?.aborted) {
-        const left = await discardStaged(lane, stage);
-        return { ok: false, error: withResidue(new FileError("aborted", "aborted before the write started; the target was not touched", abs), stage, left) };
+        const left = await settleStaging(lane, stage, [], true);
+        return { ok: false, error: withResidue(new FileError("aborted", "aborted before the write started; the target was not touched", abs), left) };
+    }
+    const piece = await lane.prepare(abortSignal);
+    if (!piece.ok) {
+        const left = await settleStaging(lane, stage, [], true);
+        return { ok: false, error: withResidue(piece.error, left) };
+    }
+    let up;
+    try {
+        up = abortSignal?.aborted ? { ok: false, error: new FileError("aborted", "aborted before the write started; the target was not touched", abs) } : await piece.value.upload(stage.file, abortSignal);
+    }
+    finally {
+        await piece.value.release?.();
     }
-    const up = await lane.upload(stage.file, abortSignal);
     if (!up.ok) {
-        const left = await discardStaged(lane, stage);
-        return { ok: false, error: withResidue(up.error, stage, left) };
+        const left = await settleStaging(lane, stage, [], true);
+        return { ok: false, error: withResidue(up.error, left) };
     }
     if (abortSignal?.aborted) {
-        const left = await discardStaged(lane, stage);
-        return { ok: false, error: withResidue(new FileError("aborted", "aborted before the commit; the target was not touched", abs), stage, left) };
+        const left = await settleStaging(lane, stage, [], true);
+        return { ok: false, error: withResidue(new FileError("aborted", "aborted before the commit; the target was not touched", abs), left) };
     }
     const c = await lane.run(commitOf(stage));
     if (!c.ok) {
-        const left = await discardStaged(lane, stage);
+        const left = await settleStaging(lane, stage, [], true);
         const e = fileErrorFromExec(c.error, abs);
-        return { ok: false, error: withResidue(new FileError("unknown", `${e.message} (the commit's round trip failed, so whether it ran is unknown — re-read the target before retrying)`, abs, e), stage, left) };
+        return { ok: false, error: withResidue(new FileError("unknown", `${e.message} (the commit's round trip failed, so whether it ran is unknown — re-read the target before retrying)`, abs, e), left) };
+    }
+    if (c.value.exitCode === STAGE_DIR_UNSEALED_EXIT) {
+        const left = await settleStaging(lane, stage, scriptRecordsOf(c.value.stdout).leftDirs, true);
+        if (abortSignal?.aborted)
+            return { ok: false, error: withResidue(new FileError("aborted", "aborted before the write started; the target was not touched", abs), left) };
+        recordFailOpen("server.remote-write.stage-seal-fallback", `${abs}: ${c.value.stderr.trim()}`);
+        return viaDirect(direct, abs, abortSignal, "the private staging directory could not be made private", left);
     }
-    noteLeftDirs(c.value.stdout);
     if (c.value.exitCode !== 0) {
-        const left = await discardStaged(lane, stage);
-        return { ok: false, error: withResidue(classifyFsStderr(c.value.stderr, abs, "unknown"), stage, left) };
+        const left = await settleStaging(lane, stage, scriptRecordsOf(c.value.stdout).leftDirs, true);
+        return { ok: false, error: withResidue(classifyFsStderr(c.value.stderr, abs, "unknown"), left) };
+    }
+    const records = scriptRecordsOf(c.value.stdout);
+    await settleStaging(lane, stage, records.leftDirs, false);
+    if (records.modeNotCarried !== undefined) {
+        (lane.logger ?? fallbackLaneLogger()).warn("remote_env_file_mode_failed", {
+            provider: lane.provider,
+            path: seatText("operator-log-arg", abs),
+            ...(records.modeNotCarried !== "" ? { mode: seatText("operator-log-text", records.modeNotCarried) } : {}),
+            error: records.modeNotCarried !== "" ? "the target machine refused to set the target's mode on the replacement" : "the target's mode could not be read",
+            effect: "the new bytes are in place; the target's previous mode bits were not carried over, so it now has the mode the replacement was created with (setting the mode is best effort)",
+        });
     }
     return { ok: true, value: undefined };
 }
-function noteLeftDirs(stdout) {
-    const head = `${STAGE_DIR_LEFT_MARK} `;
-    for (const rec of stdout.split("\0")) {
-        const at = rec.indexOf(head);
-        if (at >= 0)
-            recordFailOpen("server.remote-write.staging-dir-left", rec.slice(at + head.length));
+let fallbackLogger;
+function fallbackLaneLogger() {
+    return (fallbackLogger ??= createLogger());
+}
+async function viaDirect(direct, abs, abortSignal, why, left) {
+    const r = await writeInPlace(direct, abs, abortSignal, why);
+    return r.ok ? r : { ok: false, error: withResidue(r.error, left) };
+}
+async function writeInPlace(direct, abs, abortSignal, why) {
+    const abortedBefore = () => ({ ok: false, error: new FileError("aborted", `aborted before the in-place write started (${why}); the target was not touched`, abs) });
+    if (abortSignal?.aborted)
+        return abortedBefore();
+    const piece = await direct(abortSignal);
+    if (!piece.ok)
+        return piece;
+    try {
+        if (abortSignal?.aborted)
+            return abortedBefore();
+        const r = await piece.value.upload(abs, abortSignal);
+        if (r.ok || r.error.code !== "aborted")
+            return r;
+        return { ok: false, error: new FileError("unknown", `cancelled during an in-place write (${why}, so the bytes went straight to the target); the target may be partially written — re-read it before retrying`, abs, r.error) };
+    }
+    finally {
+        await piece.value.release?.();
     }
 }
-function createDirectContext(abs, abortSignal, why) {
-    return {
-        signal: abortSignal,
-        inPlace: async (step) => {
-            if (abortSignal?.aborted)
-                return { ok: false, error: new FileError("aborted", `aborted before the in-place write started (${why}); the target was not touched`, abs) };
-            const r = await step(abortSignal);
-            if (r.ok || r.error.code !== "aborted")
-                return r;
-            return { ok: false, error: new FileError("unknown", `cancelled during an in-place write (${why}, so the bytes went straight to the target); the target may be partially written — re-read it before retrying`, abs, r.error) };
-        },
+export function rewriteAppend(read, prepareOf, add) {
+    return async (abortSignal) => {
+        const existing = await read(abortSignal);
+        if (!existing.ok && existing.error.code !== "not_found")
+            return existing;
+        const merged = Buffer.concat([existing.ok ? existing.value : new Uint8Array(0), typeof add === "string" ? Buffer.from(add, "utf8") : add]);
+        return prepareOf(merged)(abortSignal);
     };
 }
-export async function rewriteAppend(read, write, add, ctx) {
-    const existing = await read(ctx.signal);
-    if (!existing.ok && existing.error.code !== "not_found")
-        return existing;
-    const merged = Buffer.concat([existing.ok ? existing.value : new Uint8Array(0), typeof add === "string" ? Buffer.from(add, "utf8") : add]);
-    return ctx.inPlace((signal) => write(merged, signal));
-}
 export function writeFileStaged(lane, abs, abortSignal) {
-    return landStaged(lane, abs, abortSignal, (stage) => buildStagedCommitCommand(stage, abs), (ctx) => ctx.inPlace((signal) => lane.upload(abs, signal)));
+    return landStaged(lane, abs, abortSignal, (stage) => buildStagedCommitCommand(stage, abs), lane.prepare);
 }
 export function appendFileStaged(lane, abs, abortSignal, direct) {
     return landStaged(lane, abs, abortSignal, (stage) => buildStagedAppendCommand(stage, abs), direct);