@sema-agent/server 7.150.0 → 7.152.0

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

@@ -2,6 +2,7 @@ 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";
+import { type ConnectResult } from "./remote-env-connect-seat.js";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 export interface SshEnvConfig extends LaneHomeConfig {
     host: string;
@@ -40,13 +41,6 @@ export interface SshEnvConfig extends LaneHomeConfig {
     /** 运维日志座(起服装配递本服务的 logger):暂存写「已有目标的权限位没带过去」那一行经它(缺席 ⇒ 暂存编排自建一只,见 `remote-shell.ts` `StagedWriteLane.logger`)。 */
     logger?: LaneLogger;
 }
-type ConnectResult = {
-    ok: true;
-    value: WorkspaceHandle;
-} | {
-    ok: false;
-    error: RemoteExecutionError;
-};
 /**
  * Test seam ([ref] §9.3 fault-injection): inject a `connectOnce` that replays an error sequence, so the
  * retry policy (retryable codes / maxAttempts / "first fail → second success") is deterministically testable
@@ -80,8 +74,12 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
     private readonly homeSeat;
     /** 家目录声明 × 实测的判定,按连接记(同一条连接只问一次;重连换了连接再问 —— 登录用户不变时答案相同,代价一次往返;没声明且已量到绝对路径之后不再问)。 */
     private homeChecked?;
-    /** 目标机答了而与声明不一致 ⇒ 这只环境的拒,记一次、此后每个面原样回它(同一目标机同一登录用户同一答案:不再问、不再发命令)。 */
-    private homeRefusal?;
+    /**
+     * 建连座(`remote-env-connect-seat.ts`):`connect` 的唯一次序(记住的拒 ⇒ 原样再答 · 同代际的连接在飞 ⇒ 等它,调用方的取消只退它自己的等待 · 已连 ⇒ 当下的把手 · 否则起一条),
+     * 并持有这只环境记住的拒 —— 两件立定的事实:目标机答了家目录而与声明不一致(`env.home_unconfirmed`;同一目标机同一登录用户同一答案:不再问、不再发命令),
+     * 目标机出示的主机密钥过不了部署钉的判(`env.host_key_rejected`;同一配置同一主机每次同答:不再拨号)。此后每个面原样回它。
+     */
+    private readonly seat;
     /** core 7.49.0 [ref]:shell 子进程真拿到的 `CDPATH` 条目 —— 本车道的命令跑在远端登录 shell 里(目标机的 profile / env),本类不读那份 env ⇒ `"unknown"`(core 契约:说不出就说 unknown,
      *  不许报一张没读过的空表;删除守卫因此对裸 `cd <相对名>` 之后的删除问人,而不是按「没有 CDPATH」放行)。 */
     readonly cdPath: "unknown";
@@ -100,8 +98,8 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
         ok: false;
         error: RemoteExecutionError;
     }>;
-    /** 五轮复审:per-caller 可中止等待(共享诺不动,只退本 caller)。 */
-    private raceConnAbort;
+    /** 一只建连的拒在 exec / 文件面上的那一句:拒句原文(cause = 那只拒,文件面据它答 `target_unavailable`)。 */
+    private refusalOnExecFace;
     /** [ref] 四轮复审:三路(connect/reconnect/懒连接)唯一的连接发起点——同代际在飞记录 join,settle
      *  身份清;代际抓拍一次贯穿全部重试轮,每轮起跳先查(陈旧/destroyed=不再开 socket,用不可重试的
      *  aborted 码即刻收敛 withRetry)。五轮复审:共享尝试零 caller 信号(取消面全在 per-caller race)。 */
@@ -162,8 +160,16 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
     /** 文件面探针的 exec(车PL 验修 ③):只用绝对路径,**不进工作目录**、没有 cwd 守卫 —— 工作目录进不去时探针照样答真话(`permission_denied` /
      *  `not_found` 由命令自己的 stderr 归),core 的 `isDeadCwd` 不会把「进不去」读成「没了」。 */
     private fsExec;
-    /** buffered exec 的唯一体:`call` 定了整串、stderr 的 started 行剥法与收口(`remote-shell.ts` `createCwdGuardedCall`)。 */
+    /** buffered exec(命令面 + 文件面探针):stdout 走 8 MiB 滚动尾(模型的 `yes` / `cat big` 撑不爆 worker),截掉的字节在结果里如实标出。 */
     private execCall;
+    /**
+     * 绑定读一答的往返(`remote-shell.ts` 的脚本经它跑):与文件面探针同一起动(不进工作目录、没有 cwd 守卫)、数据界;stdout **逐字节**收、只留开头
+     * `cap + 1` 字节 —— 本答该有多长由读法定(`cap`),比它长的答由读法拒,从不解码一段尾巴(命令面那只 8 MiB 滚动尾在这里不许用)。
+     */
+    private boundExec;
+    /** buffered exec 的唯一体:`call` 定了整串、stderr 的 started 行剥法与收口(`remote-shell.ts` `createCwdGuardedCall`);stdout 的收法由 `sink` 定
+     *  (命令面 = 滚动尾;绑定读 = 封顶的逐字节头)。`sink.tail` = 切断时随错误带出的 stdout(绑定读不带)。 */
+    private runBuffered;
     execStream(command: string, options?: ExecStreamOptions): AsyncIterable<OutputChunk>;
     private sftp;
     absolutePath(p: string): Promise<Result<string, FileError>>;

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

@@ -11,6 +11,7 @@ import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTail
 import { capabilitiesFor } from "../execution-lane-caps.js";
 import { fileErrorFromExec } from "./remote-env-file-error.js";
 import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
+import { connectRefusal, createConnectSeat, withdrawOnAbort } from "./remote-env-connect-seat.js";
 const PROVIDER = "ssh";
 const ok = (value) => ({ ok: true, value });
 const unsupported = (op) => ({
@@ -33,7 +34,11 @@ export class RemoteSshExecutionEnv {
     }
     homeSeat;
     homeChecked;
-    homeRefusal;
+    seat = createConnectSeat({
+        live: () => (this.conn !== undefined && !this.destroyed ? this.workspaceHandle() : undefined),
+        inFlight: () => (this.inFlight !== undefined && this.inFlight.epoch === this.connEpoch ? this.inFlight.promise : undefined),
+        establish: (config) => withdrawOnAbort(this.startConnect("establish"), config?.abortSignal),
+    });
     cdPath = "unknown";
     withheldEnv = [];
     cfg;
@@ -66,26 +71,10 @@ export class RemoteSshExecutionEnv {
     async connect(config) {
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "SSH env destroyed — create a fresh env instead of reviving") };
-        if (this.conn)
-            return ok(this.workspaceHandle());
-        return this.raceConnAbort(this.startConnect("establish"), config?.abortSignal);
+        return this.seat.connect(config);
     }
-    async raceConnAbort(shared, signal) {
-        if (!signal)
-            return shared;
-        if (signal.aborted)
-            return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted") };
-        let onAbort;
-        const aborted = new Promise((res) => {
-            onAbort = () => res("aborted");
-            signal.addEventListener("abort", onAbort, { once: true });
-        });
-        const raced = await Promise.race([shared, aborted]);
-        if (onAbort)
-            signal.removeEventListener("abort", onAbort);
-        if (raced === "aborted")
-            return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted while waiting") };
-        return raced;
+    refusalOnExecFace(refusal) {
+        return new ExecutionError("shell_unavailable", refusal.error.message, refusal.error);
     }
     startConnect(kind) {
         if (this.inFlight && this.inFlight.epoch === this.connEpoch)
@@ -115,10 +104,15 @@ export class RemoteSshExecutionEnv {
     }
     async ensureConnected(signal) {
         for (let round = 0; round < 3; round++) {
-            if (this.homeRefusal)
-                return { ok: false, error: this.homeRefusal };
+            const held = this.seat.held;
+            if (held)
+                return { ok: false, error: this.refusalOnExecFace(held) };
             const transport = await this.ensureTransport(signal);
-            if (!transport.ok || !this.homeSeat.asks)
+            if (!transport.ok) {
+                const now = this.seat.held;
+                return now ? { ok: false, error: this.refusalOnExecFace(now) } : transport;
+            }
+            if (!this.homeSeat.asks)
                 return transport;
             const conn = this.conn;
             if (!conn)
@@ -127,7 +121,7 @@ export class RemoteSshExecutionEnv {
                 const checked = { conn, verdict: this.homeVerdict(conn) };
                 this.homeChecked = checked;
                 void checked.verdict.then((r) => {
-                    if (!r.ok && this.homeRefusal === undefined && this.homeChecked === checked)
+                    if (!r.ok && this.seat.held === undefined && this.homeChecked === checked)
                         this.homeChecked = undefined;
                 });
             }
@@ -185,10 +179,9 @@ export class RemoteSshExecutionEnv {
                 const verdict = this.homeSeat.settle(probe);
                 if (verdict === undefined)
                     return resolve(ok(undefined));
-                const error = new ExecutionError("shell_unavailable", verdict.refusal);
                 if (verdict.answered)
-                    this.homeRefusal = error;
-                resolve({ ok: false, error });
+                    return resolve({ ok: false, error: this.refusalOnExecFace(this.seat.answer(connectRefusal("home_unconfirmed", verdict.refusal))) });
+                resolve({ ok: false, error: new ExecutionError("shell_unavailable", verdict.refusal) });
             };
             const timer = setTimeout(() => settle({ ok: false, reason: `no answer within ${this.cfg.readyTimeoutMs}ms` }), this.cfg.readyTimeoutMs);
             try {
@@ -222,33 +215,14 @@ export class RemoteSshExecutionEnv {
             return { ok: false, error: new ExecutionError("shell_unavailable", "SSH env destroyed — no lazy reconnect after teardown") };
         if (signal?.aborted)
             return { ok: false, error: new ExecutionError("aborted", "aborted before SSH lazy-connect") };
-        if (this.conn)
-            return ok(undefined);
-        const shared = this.startConnect("establish");
-        let r;
-        if (signal) {
-            let onAbort;
-            const aborted = new Promise((res) => {
-                onAbort = () => res("aborted");
-                signal.addEventListener("abort", onAbort, { once: true });
-            });
-            const raced = await Promise.race([shared, aborted]);
-            if (onAbort)
-                signal.removeEventListener("abort", onAbort);
-            if (raced === "aborted")
-                return { ok: false, error: new ExecutionError("aborted", "aborted while waiting for SSH lazy-connect") };
-            r = raced;
-        }
-        else {
-            r = await shared;
-        }
+        const r = await this.seat.connect(signal ? { abortSignal: signal } : undefined);
         if (r.ok) {
             if (this.conn)
                 return ok(undefined);
             return { ok: false, error: new ExecutionError("shell_unavailable", "SSH connection dropped right after connect") };
         }
         if (r.error.code === "aborted")
-            return { ok: false, error: new ExecutionError("aborted", r.error.message, r.error) };
+            return { ok: false, error: new ExecutionError("aborted", signal?.aborted ? "aborted while waiting for SSH lazy-connect" : r.error.message, r.error) };
         return { ok: false, error: new ExecutionError("shell_unavailable", `SSH lazy-connect failed: ${r.error.message}`, r.error) };
     }
     connectOnce(signal, opEpoch) {
@@ -273,7 +247,7 @@ export class RemoteSshExecutionEnv {
                 hostVerifier: (key) => {
                     const verdict = verifyHostKey(key);
                     if (!verdict.ok) {
-                        hostKeyRejection = verdict.reason;
+                        hostKeyRejection = { reason: verdict.reason, standing: verdict.standing };
                         return false;
                     }
                     return true;
@@ -303,10 +277,9 @@ export class RemoteSshExecutionEnv {
                 }
                 catch {
                 }
-                resolve({
-                    ok: false,
-                    error: hostKeyRejection !== undefined ? new RemoteExecutionError("connect_failed", hostKeyRejection, e) : this.connErr(e),
-                });
+                if (hostKeyRejection === undefined)
+                    return resolve({ ok: false, error: this.connErr(e) });
+                resolve(hostKeyRejection.standing ? this.seat.answer(connectRefusal("host_key_rejected", hostKeyRejection.reason, e)) : { ok: false, error: new RemoteExecutionError("connect_failed", hostKeyRejection.reason, e) });
             });
             try {
                 c.connect(opts);
@@ -328,6 +301,9 @@ export class RemoteSshExecutionEnv {
     async reconnect(_sessionToken) {
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "SSH env destroyed — create a fresh env instead of reviving") };
+        const held = this.seat.held;
+        if (held)
+            return held;
         if (this.inFlight && this.inFlight.epoch === this.connEpoch && this.inFlight.kind === "replace")
             return this.inFlight.promise;
         this.connEpoch++;
@@ -356,7 +332,33 @@ export class RemoteSshExecutionEnv {
     fsExec(command, abortSignal) {
         return this.execCall(createCwdGuardedCall("ssh", command, undefined, undefined), { abortSignal });
     }
-    async execCall(call, options) {
+    execCall(call, options) {
+        const outBuf = new RollingTailBuffer();
+        return this.runBuffered(call, options, {
+            push: (d) => outBuf.push(d),
+            tail: outBuf,
+            take: () => {
+                const out = outBuf.result();
+                return markTruncated(out.text, out.droppedBytes);
+            },
+        });
+    }
+    boundExec(cmd, cap, abortSignal) {
+        const chunks = [];
+        let kept = 0;
+        return this.runBuffered(createCwdGuardedCall("ssh", cmd, undefined, undefined), { abortSignal, timeout: this.cfg.dataTimeoutMs / 1000 }, {
+            push: (d) => {
+                if (kept > cap)
+                    return;
+                const piece = d.length > cap + 1 - kept ? d.subarray(0, cap + 1 - kept) : d;
+                chunks.push(piece);
+                kept += piece.length;
+            },
+            tail: undefined,
+            take: () => new Uint8Array(Buffer.concat(chunks)),
+        });
+    }
+    async runBuffered(call, options, sink) {
         const ready = await this.ensureConnected(options?.abortSignal);
         if (!ready.ok)
             return ready;
@@ -365,7 +367,6 @@ export class RemoteSshExecutionEnv {
             return { ok: false, error: new ExecutionError("shell_unavailable", "SSH not connected — call connect() first") };
         const timeoutMs = options?.timeout != null ? options.timeout * 1000 : this.cfg.commandTimeoutMs;
         return new Promise((resolve) => {
-            const outBuf = new RollingTailBuffer();
             const errBuf = new RollingTailBuffer();
             const recordStderr = (bytes) => {
                 if (bytes.length > 0)
@@ -381,7 +382,7 @@ export class RemoteSshExecutionEnv {
             };
             const captured = () => {
                 recordStderr(call.endStderr());
-                return buildCapturedOutput(outBuf, errBuf);
+                return buildCapturedOutput(sink.tail, errBuf);
             };
             let settled = false;
             let streamRef;
@@ -427,7 +428,7 @@ export class RemoteSshExecutionEnv {
                 }
                 stream
                     .on("data", (d) => {
-                    outBuf.push(d);
+                    sink.push(d);
                     options?.onStdout?.(d.toString());
                 })
                     .on("close", (code, signal) => {
@@ -438,9 +439,8 @@ export class RemoteSshExecutionEnv {
                     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 }));
+                        return call.settle(ok({ stdout: sink.take(), stderr: markTruncated(err.text, err.droppedBytes), exitCode }));
                     });
                     if (won)
                         emitStderr(held);
@@ -688,6 +688,7 @@ export class RemoteSshExecutionEnv {
             run: (cmd, abortSignal) => this.fsExec(cmd, abortSignal),
             resolve: (p) => this.resolve(p),
             tempDir: () => null,
+            boundLane: { run: (cmd, cap, abortSignal) => this.boundExec(cmd, cap, abortSignal), payload: "base64", boundSec: this.cfg.dataTimeoutMs / 1000 },
         }));
     }
     async readLink(p, abortSignal) {

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

@@ -2,7 +2,7 @@
  * 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, FileError, type FileInfo, type RemoteExecutionError, type Result, type SymlinkChain } from "@sema-agent/core";
+import { ExecutionError, FileError, type BoundFileObject, 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):
@@ -206,6 +206,103 @@ export type ShellChainRun = (cmd: string) => Promise<Result<{
  *    三条远端腿的文件面探针不带 cwd(车PL 验修 ③)⇒ 这条命令不会因为某个工作目录不可用而不跑。
  */
 export declare function runSymlinkChain(absPath: string, run: ShellChainRun): Promise<Result<SymlinkChain, FileError>>;
+/**
+ * 绑定读脚本的退出码闭集(与 shell / 工具自己的 1 / 2 / 124–127 / 128+ 不撞)。读法只在 {@link boundReadRefusal}(穷举 switch,无 default 臂)。
+ *  · `link`     —— 预检:叶是链接(没有 `O_NOFOLLOW` 可用,先查);
+ *  · `moved`    —— 打开之后的那一次观测不在规范键上(叶 / 父段打开时是链接、打开后被改名 / 删掉),或身份 / 类型不等于开答时;
+ *  · `kind`     —— 既非普通文件也非目录(预检或打开之后);
+ *  · `over`     —— 这一答量到的大小超过 `max`(先量后读:超了一个字节都不读);
+ *  · `platform` —— 给不出那一次观测或缺工具(见上段)⇒ `not_supported`;
+ *  · `name`     —— 列目录时有一个名字带换行:一行一条的答装不下它而不生歧义(名字里的换行能伪造出一条假条目),整答拒、不列一半。
+ */
+export declare const BOUND_READ_EXITS: {
+    readonly link: 90;
+    readonly moved: 91;
+    readonly kind: 92;
+    readonly over: 93;
+    readonly platform: 94;
+    readonly name: 95;
+};
+export type BoundReadExit = keyof typeof BOUND_READ_EXITS;
+/** 一答的操作闭集(工厂的四个成员各一答;`open` 是 `openBound` 那一答)。 */
+export type BoundReadOp = "open" | "size" | "readBytes" | "list";
+/**
+ * 绑定读的 POSIX sh 脚本 —— **常量**(不拼任何值;路径与参数经位置参数 `$1…$6` 进来):五条远端腿发的是逐字节同一串。
+ * 位置参数:`$1` 规范键 · `$2` 操作 · `$3` 开答时的身份 · `$4` 开答时的类型 · `$5` `max` · `$6` 载荷编码(`raw` / `base64`)。
+ *
+ * 步骤(每一答都整走一遍):
+ *  ① 平台与工具:`/proc/self/fd` 不在、或缺工具 ⇒ `platform`,**在打开任何东西之前**;
+ *  ② 预检:叶是链接 ⇒ `link`;在场却既非普通文件也非目录(FIFO / 设备 / 套接字)⇒ `kind` —— 预检只缩小窗口(shell 没有 `O_NOFOLLOW` / `O_NONBLOCK`),关不上它;
+ *  ③ 一次打开、整条答共用:复合命令重定向 `{ …; } < "$f"`(**不用** `exec 3<`:ksh93 给 `exec` 开的 > 2 号描述符置 close-on-exec,子进程读不到它;
+ *     复合命令重定向的 0 号描述符照常继承 —— 外部命令、命令替换、shell 自己都看见同一只打开);打开失败 ⇒ shell 自己的报错 + 退 1(读法归 stderr 分类);
+ *  ④ 那一次观测:`readlink /proc/self/fd/0`(内核给出「这只打开的对象此刻叫什么」;`/proc/self` 在外部命令里就是它自己,它继承的 0 号描述符就是这次打开)
+ *     须逐字等于规范键,否则 `moved` —— 命令替换会吞掉**全部**尾随换行,所以读数后面垫一个哨兵字符、只剥 `readlink` 自己那一个换行(名字以换行结尾的对象
+ *     与规范键不等);身份与类型 `stat -L -c '%d:%i %s %F' /proc/self/fd/0`(跟的是魔法链接:这只打开的对象本身,不是按路径再查;`%F` 是人读的词,
+ *     GNU 按区域设置翻译 ⇒ 整只脚本在 `LC_ALL=C` 下跑,工具的报错句也因此是共享分类器认得的英文);
+ *     类型须是普通文件或目录,否则 `kind`;带了开答身份的答(size / read / list)⇒ 身份**与类型**须都等于开答时,否则 `moved`;
+ *  ⑤ 作答,只经这一次打开:`open` 一行 `<身份> <file|directory>`;`size` 一行十进制;`readBytes` 先量(> `max` ⇒ 打出量到的大小、`over`,一个字节不读),
+ *     一行十进制大小 + 载荷 —— 大小 > 0 读恰好那么多(与 core 读口同读:开读那一刻的大小),= 0(procfs 一类)读到流尽、至多 `max + 1`;
+ *     base64 腿的 `head | base64` 管道里 `head` 自己的退出码经 4 号描述符带出来(复合命令重定向,不用 `exec`):读失败 ⇒ 退 1,不交 `base64` 的 0;
+ *     `list` 经 `cd -P /proc/self/fd/0` 进**这只打开的目录**,逐条 lstat 语义一行 `<十六进制模式> <大小> <mtime 秒> <名>`;名字带换行 ⇒ `name`。
+ * 全程不用 `!`(某些登录 shell 的历史展开)、不用 `pipefail`(dash 没有);读的截短另由读法按大小对拍兜住({@link createShellRebindingAnswers})。
+ */
+export declare const BOUND_READ_SCRIPT: string;
+/** 一答的入参(开答之后的三答带开答时的身份与类型)。 */
+export interface BoundReadArgs {
+    readonly bound?: BoundPlacement;
+    readonly max?: number;
+}
+/**
+ * 一答发给目标的整串(**纯数据** ⇒ `build*`):先判 `timeout(1)` 在不在(不在 ⇒ `platform`,有界给不出就不答),再以 `timeout <boundSec 向下取整,至少 1> sh -c <脚本>` 跑 ——
+ * 显式套一层 `sh`,把方言钉在目标的 POSIX `/bin/sh` 上(容器的命令 shell 可能是 bash、e2b 起的是登录 bash、ssh 交给远端登录 shell)。
+ * 整条包在一个 `{ …; }` 里,只有一个退出状态(与 {@link buildSymlinkChainCommand} 同一条理由)。值全经 {@link shellQuote} 进位置参数,脚本串里不拼值。
+ */
+export declare function buildBoundReadCommand(abs: string, op: BoundReadOp, args: BoundReadArgs, payload: BoundReadLane["payload"], boundSec: number): string;
+/**
+ * 一条远端腿交给绑定读的那一条传输(各腿只造这一只闭包;读法与归码不在腿上)。
+ * 🔴 字节回程律:`stdout` **逐字节**(任何丢弃 / 截尾的收集器都不许接在这里 —— ssh 的命令面收集器是 8 MiB 滚动尾,所以 ssh 另造一只按本答上界封顶的);
+ * 收集器有上界的腿保留至多 `stdoutCap + 1` 字节,读法见到比上界长的答即拒(不解码一段尾巴)。
+ */
+export interface BoundReadLane {
+    run(cmd: string, stdoutCap: number, abortSignal?: AbortSignal): Promise<Result<{
+        stdout: Uint8Array;
+        stderr: string;
+        exitCode: number;
+    }, ExecutionError | RemoteExecutionError>>;
+    /** 载荷在这条腿的 stdout 上怎么走:`raw`(二进制收集器:local-docker / adb)或 `base64`(文本面:k8s 的 WS 文本帧 / e2b SDK 的字符串 / ssh)。 */
+    readonly payload: "raw" | "base64";
+    /** 一答在目标上的墙钟(整秒,`timeout(1)`)= 该腿的数据界。 */
+    readonly boundSec: number;
+}
+/** 开答定下的那只对象(工厂与答者之间的唯一凭据):身份 `<dev>:<inode>` + 类型。 */
+export interface BoundPlacement {
+    readonly identity: string;
+    readonly kind: "file" | "directory";
+}
+/** 一只目录条目(没有 `path`:工厂把它锚在规范键之下,答者给的拼法不作数)。 */
+export type BoundListEntry = Omit<FileInfo, "path">;
+/**
+ * 逐答重绑的答者(传输那一半):每一答都是一次完整的重绑 —— 打开、核对它就是 `bound`、经这一次打开作答。shell 腿 = {@link createShellRebindingAnswers};
+ * 设备腿 = 一条 `openBound` 协议指令。
+ */
+export interface RebindingAnswers {
+    open(abortSignal?: AbortSignal): Promise<Result<BoundPlacement, FileError>>;
+    size(bound: BoundPlacement): Promise<Result<number, FileError>>;
+    readBytes(bound: BoundPlacement, max: number, abortSignal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
+    list(bound: BoundPlacement, abortSignal?: AbortSignal): Promise<Result<BoundListEntry[], FileError>>;
+}
+/** 五条远端腿的答者:四个成员各一答,每一答 = {@link BOUND_READ_SCRIPT} 的一次往返(`createShellRebindingAnswers` 返回活对象 ⇒ `create*`)。 */
+export declare function createShellRebindingAnswers(abs: string, lane: BoundReadLane): RebindingAnswers;
+/**
+ * 逐答重绑的 `BoundFileObject`(活对象 ⇒ `create*`):每个成员一答;`close()` 不发往返(远端什么都不持有)。
+ * 工厂自己的三道闸(不信任答者):读的不是文件 / 列的不是目录 ⇒ 不发往返、照 core 句拒;`max` 不是非负安全整数 ⇒ `invalid`;
+ * 答回的字节比 `max` 多 ⇒ `invalid`(二道闸,同 {@link symlinkChainHopsFromStdout} 的「再切一次」);条目名不是单段 ⇒ 整答拒,条目锚在 `abs` 之下(执行缝路径律)。
+ */
+export declare function createRebindingBoundFile(abs: string, bound: BoundPlacement, answers: RebindingAnswers): BoundFileObject;
+/** `openBound` 的整只半场(开答 → 工厂)。答者给的身份与类型就是工厂之后每一答对拍的凭据。 */
+export declare function openRebinding(abs: string, answers: RebindingAnswers, abortSignal?: AbortSignal): Promise<Result<BoundFileObject, FileError>>;
+/** 远端腿 `openBound` 的一行调用(经基座的腿与 e2b 直调;本版 ssh 缓装、不暴露):同一只脚本、同一只读法、同一只工厂。 */
+export declare function openBoundOverShell(abs: string, lane: BoundReadLane, abortSignal?: AbortSignal): Promise<Result<BoundFileObject, FileError>>;
 /**
  * 脚本删一只私有目录没删掉时写到 **stdout** 的那一条记录的头:`<头> <目录路径>\0`(NUL 收尾 —— 路径里可以有换行)。
  * 残留记录走 stdout、错误走 stderr:两条通道不混,分类器读到的 stderr 里没有路径文本。记录不改脚本的退出码:写照它自己的结局答,残留另行留痕。

package/dist/plugins/remote-shell.js

@@ -1,5 +1,9 @@
 import { ExecutionError, FileError, SYMLINK_CHAIN_MAX_HOPS } from "@sema-agent/core";
+import { posix } from "node:path";
+import { anchorUnder } from "./exec-path-law.js";
+import { isCanonicalBase64 } from "../device-ws-protocol.js";
 import { NAME_MAX_BYTES, classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
+import { echoCallerText } from "../caller-text-echo.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { createLogger } from "../observability/logger.js";
 import { seatText } from "../trace/exit-seat.js";
@@ -156,6 +160,220 @@ export async function runSymlinkChain(absPath, run) {
         return { ok: false, error: classifyFsStderr(r.value.stderr, absPath, "unknown") };
     return { ok: true, value: { hops: symlinkChainHopsFromStdout(r.value.stdout, absPath) } };
 }
+export const BOUND_READ_EXITS = { link: 90, moved: 91, kind: 92, over: 93, platform: 94, name: 95 };
+const BOUND_READ_TIMEOUT_EXITS = [124, 137, 143];
+export const BOUND_READ_SCRIPT = [
+    "f=$1; op=$2; want=$3; wk=$4; max=$5; enc=$6; LC_ALL=C; export LC_ALL; nl=$(printf '\\n.'); nl=${nl%.}",
+    `[ -d /proc/self/fd ] || exit ${BOUND_READ_EXITS.platform}`,
+    `for t in readlink stat head; do command -v "$t" >/dev/null 2>&1 || exit ${BOUND_READ_EXITS.platform}; done`,
+    `if [ "$enc" = base64 ]; then command -v base64 >/dev/null 2>&1 || exit ${BOUND_READ_EXITS.platform}; fi`,
+    `if [ -L "$f" ]; then exit ${BOUND_READ_EXITS.link}; fi`,
+    `if [ -e "$f" ]; then if [ -f "$f" ] || [ -d "$f" ]; then :; else exit ${BOUND_READ_EXITS.kind}; fi; fi`,
+    "{",
+    `  p=$(readlink /proc/self/fd/0 && printf .) || exit ${BOUND_READ_EXITS.platform}`,
+    '  p=${p%.}; p=${p%"$nl"}',
+    `  s=$(stat -L -c '%d:%i %s %F' /proc/self/fd/0) || exit ${BOUND_READ_EXITS.platform}`,
+    `  [ "$p" = "$f" ] || exit ${BOUND_READ_EXITS.moved}`,
+    '  id=${s%% *}; r=${s#* }; sz=${r%% *}; t=${r#* }',
+    `  case $t in "regular file"|"regular empty file") k=file ;; directory) k=directory ;; *) exit ${BOUND_READ_EXITS.kind} ;; esac`,
+    `  if [ "$op" = open ]; then :; elif [ "$id" = "$want" ] && [ "$k" = "$wk" ]; then :; else exit ${BOUND_READ_EXITS.moved}; fi`,
+    "  case $op in",
+    `    open) printf '%s %s\\n' "$id" "$k" ;;`,
+    `    size) printf '%s\\n' "$sz" ;;`,
+    `    readBytes) if [ "$sz" -le "$max" ]; then :; else printf '%s\\n' "$sz"; exit ${BOUND_READ_EXITS.over}; fi`,
+    '      n=$sz; [ "$sz" -gt 0 ] || n=$((max + 1))',
+    `      printf '%s\\n' "$sz"`,
+    '      if [ "$enc" = base64 ]; then { rc=$( { { head -c "$n"; echo "$?" >&4; } | base64 >&3; } 4>&1 ); } 3>&1; [ "$rc" = 0 ] || exit 1; else head -c "$n"; fi ;;',
+    "    list) cd -P /proc/self/fd/0 || exit 1",
+    "      set --",
+    `      for n in * .[!.]* ..?*; do case $n in *"$nl"*) exit ${BOUND_READ_EXITS.name} ;; esac; if [ -e "$n" ] || [ -L "$n" ]; then set -- "$@" "$n"; fi; done`,
+    `      if [ "$#" -gt 0 ]; then stat -c '%f %s %Y %n' -- "$@"; fi ;;`,
+    "    *) exit 1 ;;",
+    "  esac",
+    "  exit",
+    '} < "$f"',
+    "exit 1",
+].join("\n");
+export function buildBoundReadCommand(abs, op, args, payload, boundSec) {
+    const argv = [abs, op, args.bound?.identity ?? "-", args.bound?.kind ?? "-", String(args.max ?? 0), payload].map(shellQuote).join(" ");
+    return `{ command -v timeout >/dev/null 2>&1 || exit ${BOUND_READ_EXITS.platform}; exec timeout ${Math.max(1, Math.floor(boundSec))} sh -c ${shellQuote(BOUND_READ_SCRIPT)} sema-bound-read ${argv}; }`;
+}
+const BOUND_SMALL_ANSWER_BYTES = 4096;
+const BOUND_LIST_ANSWER_BYTES = 16 * 1024 * 1024;
+const BOUND_IDENTITY_RE = /^\d+:\d+$/;
+const BOUND_DECIMAL_RE = /^\d+$/;
+function overCapError(abs, max, bytes) {
+    return new FileError("invalid", `The held file is over the ${max}-byte read cap (${bytes} bytes or more); it was not read`, abs);
+}
+function malformedAnswer(abs, what) {
+    return new FileError("unknown", `the target's bound-read answer was malformed (${what}); nothing was read`, abs);
+}
+function boundReadRefusal(word, abs, max, stdout) {
+    switch (word) {
+        case "link":
+            return new FileError("precondition_failed", "The path is now a link, not the object that was checked", abs);
+        case "moved":
+            return new FileError("precondition_failed", "The path named another object than the one opened", abs);
+        case "kind":
+            return new FileError("invalid", "Neither a regular file nor a directory", abs);
+        case "over":
+            return overCapError(abs, max, BOUND_DECIMAL_RE.test(stdout.trim()) ? stdout.trim() : "more than the cap");
+        case "platform":
+            return new FileError("not_supported", "This target cannot bind a read: it gives no /proc/self/fd observation of an opened file (not Linux, or /proc is not mounted), or it lacks timeout / readlink / stat / head / base64", abs);
+        case "name":
+            return new FileError("invalid", "A name in this directory contains a newline, which this listing cannot carry unambiguously; the directory was not listed", abs);
+    }
+}
+function boundReadExitOf(code) {
+    for (const word of Object.keys(BOUND_READ_EXITS))
+        if (BOUND_READ_EXITS[word] === code)
+            return word;
+    return undefined;
+}
+function answerCap(op, max, payload) {
+    switch (op) {
+        case "open":
+        case "size":
+            return BOUND_SMALL_ANSWER_BYTES;
+        case "list":
+            return BOUND_LIST_ANSWER_BYTES;
+        case "readBytes": {
+            const body = payload === "base64" ? Math.ceil((max + 1) / 3) * 4 : max + 1;
+            return BOUND_SMALL_ANSWER_BYTES + body + Math.ceil(body / 76) + 1;
+        }
+    }
+}
+async function runBoundOp(abs, op, args, lane, abortSignal) {
+    const max = args.max ?? 0;
+    const cap = answerCap(op, max, lane.payload);
+    const r = await lane.run(buildBoundReadCommand(abs, op, args, lane.payload, lane.boundSec), cap, abortSignal);
+    if (!r.ok)
+        return { ok: false, error: r.error.code === "timeout" ? new FileError("timeout", `the bound read ran past the lane's bound: ${r.error.message}`, abs, r.error) : fileErrorFromExec(r.error, abs) };
+    const { exitCode, stderr } = r.value;
+    const stdout = Buffer.from(r.value.stdout);
+    if (exitCode !== 0) {
+        const word = boundReadExitOf(exitCode);
+        if (word !== undefined)
+            return { ok: false, error: boundReadRefusal(word, abs, max, stdout.subarray(0, 64).toString("latin1")) };
+        if (BOUND_READ_TIMEOUT_EXITS.includes(exitCode))
+            return { ok: false, error: new FileError("timeout", `the bound read on the target ran past its ${lane.boundSec}s bound and was killed; nothing was read`, abs) };
+        return { ok: false, error: classifyFsStderr(stderr, abs, "unknown") };
+    }
+    if (stdout.length > cap)
+        return { ok: false, error: malformedAnswer(abs, `over the ${cap}-byte bound of a ${op} answer`) };
+    return { ok: true, value: stdout };
+}
+function bytesOfReadAnswer(abs, out, payload) {
+    const nl = out.indexOf(0x0a);
+    const head = nl < 0 ? "" : out.subarray(0, nl).toString("latin1");
+    if (!BOUND_DECIMAL_RE.test(head))
+        return { ok: false, error: malformedAnswer(abs, "no size line") };
+    const size = Number(head);
+    const rest = out.subarray(nl + 1);
+    let bytes;
+    if (payload === "base64") {
+        const text = rest.toString("latin1").replace(/\s+/g, "");
+        if (!isCanonicalBase64(text))
+            return { ok: false, error: malformedAnswer(abs, "the payload is not canonical base64") };
+        bytes = Buffer.from(text, "base64");
+    }
+    else {
+        bytes = rest;
+    }
+    if (size > 0 && bytes.length !== size) {
+        return { ok: false, error: new FileError("unknown", `the file was ${size} bytes when the read started but ${bytes.length} arrived (it changed while it was read, or the transfer was cut); nothing was read`, abs) };
+    }
+    return { ok: true, value: new Uint8Array(bytes) };
+}
+function entriesOfListAnswer(abs, out) {
+    const entries = [];
+    for (const line of out.toString("utf8").split("\n")) {
+        if (line === "")
+            continue;
+        const m = /^([0-9a-fA-F]+) (\d+) (\d+) (.+)$/.exec(line);
+        if (m === null)
+            return { ok: false, error: malformedAnswer(abs, "a listing line is not `<mode> <size> <mtime> <name>`") };
+        const type = parseInt(m[1], 16) & 0o170000;
+        const kind = type === 0o100000 ? "file" : type === 0o040000 ? "directory" : type === 0o120000 ? "symlink" : undefined;
+        if (kind === undefined)
+            continue;
+        entries.push({ name: m[4], kind, size: Number(m[2]), mtimeMs: Number(m[3]) * 1000 });
+    }
+    return { ok: true, value: entries };
+}
+export function createShellRebindingAnswers(abs, lane) {
+    return {
+        async open(abortSignal) {
+            const r = await runBoundOp(abs, "open", {}, lane, abortSignal);
+            if (!r.ok)
+                return r;
+            const [identity, kind, ...more] = r.value.toString("latin1").trim().split(" ");
+            if (identity === undefined || !BOUND_IDENTITY_RE.test(identity) || (kind !== "file" && kind !== "directory") || more.length > 0)
+                return { ok: false, error: malformedAnswer(abs, "the open answer is not `<dev>:<inode> <file|directory>`") };
+            return { ok: true, value: { identity, kind } };
+        },
+        async size(bound) {
+            const r = await runBoundOp(abs, "size", { bound }, lane);
+            if (!r.ok)
+                return r;
+            const text = r.value.toString("latin1").trim();
+            if (!BOUND_DECIMAL_RE.test(text))
+                return { ok: false, error: malformedAnswer(abs, "the size answer is not a decimal") };
+            return { ok: true, value: Number(text) };
+        },
+        async readBytes(bound, max, abortSignal) {
+            const r = await runBoundOp(abs, "readBytes", { bound, max }, lane, abortSignal);
+            return r.ok ? bytesOfReadAnswer(abs, r.value, lane.payload) : r;
+        },
+        async list(bound, abortSignal) {
+            const r = await runBoundOp(abs, "list", { bound }, lane, abortSignal);
+            return r.ok ? entriesOfListAnswer(abs, r.value) : r;
+        },
+    };
+}
+export function createRebindingBoundFile(abs, bound, answers) {
+    return {
+        identity: bound.identity,
+        kind: bound.kind,
+        size: () => answers.size(bound),
+        async readBytes(max, abortSignal) {
+            if (bound.kind !== "file")
+                return { ok: false, error: new FileError("is_directory", "The held object is a directory", abs) };
+            if (!Number.isSafeInteger(max) || max < 0)
+                return { ok: false, error: new FileError("invalid", `the read cap must be a non-negative integer (got ${String(max)})`, abs) };
+            const r = await answers.readBytes(bound, max, abortSignal);
+            if (!r.ok)
+                return r;
+            if (r.value.length > max)
+                return { ok: false, error: overCapError(abs, max, r.value.length) };
+            return r;
+        },
+        async list(abortSignal) {
+            if (bound.kind !== "directory")
+                return { ok: false, error: new FileError("not_directory", "The held object is a file", abs) };
+            const r = await answers.list(bound, abortSignal);
+            if (!r.ok)
+                return r;
+            const out = [];
+            for (const e of r.value) {
+                if (e.name === "" || e.name === "." || e.name === ".." || e.name.includes("/"))
+                    return { ok: false, error: malformedAnswer(abs, `a listed name is not one path segment: ${JSON.stringify(echoCallerText(e.name, { maxChars: 80 }))}`) };
+                out.push({ ...e, path: anchorUnder(posix, abs, e.name) });
+            }
+            return { ok: true, value: out };
+        },
+        close: async () => undefined,
+    };
+}
+export async function openRebinding(abs, answers, abortSignal) {
+    const opened = await answers.open(abortSignal);
+    if (!opened.ok)
+        return opened;
+    return { ok: true, value: createRebindingBoundFile(abs, opened.value, answers) };
+}
+export function openBoundOverShell(abs, lane, abortSignal) {
+    return openRebinding(abs, createShellRebindingAnswers(abs, lane), abortSignal);
+}
 const STAGED_FILE = "data";
 const STAGE_DIR_REFUSED_EXIT = 3;
 const STAGE_DIR_UNSEALED_EXIT = 4;