@sema-agent/server 7.150.0 → 7.151.0

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

@@ -13,6 +13,7 @@ import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, mar
 import { capabilitiesFor } from "../execution-lane-caps.js";
 import { ADAPTER_START, BOOTSTRAP_START, createSandboxReadFloor, dockerIdentityFlags, engineStart, floorArgv, } from "./sandbox-read-floor.js";
 import { fileErrorFromExec, classifyFsStderr } from "./remote-env-file-error.js";
+import { connectRefusal, createConnectSeat, withdrawOnAbort } from "./remote-env-connect-seat.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
 const PROVIDER = "local-docker";
 const DEFAULT_MOUNT_PATH = "/workspace";
@@ -49,7 +50,11 @@ export class RemoteLocalDockerExecutionEnv {
     handle;
     destroyed = false;
     connecting;
-    connectRefusal;
+    seat = createConnectSeat({
+        live: () => (this.containerId !== undefined ? this.workspaceHandle() : undefined),
+        inFlight: () => this.connecting,
+        establish: (config) => this.connectOnce(config, "start-or-attach"),
+    });
     homeSeat;
     lifecycle = new AbortController();
     capacityDeadline;
@@ -100,20 +105,15 @@ export class RemoteLocalDockerExecutionEnv {
             return unsupported("connect(snapshotId)");
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
-        if (this.connectRefusal)
-            return { ok: false, error: this.connectRefusal };
-        if (config?.abortSignal?.aborted)
-            return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted") };
-        if (this.containerId)
-            return ok(this.workspaceHandle());
-        return this.connectOnce(config, "start-or-attach");
+        return this.seat.connect(config);
     }
     async connectOnce(config, mode) {
         if (this.connecting)
             return this.connecting;
-        this.connecting = this.doConnect(config, mode);
-        const r = await this.connecting;
-        if (!r.ok)
+        const mine = this.doConnect(config, mode);
+        this.connecting = mine;
+        const r = await mine;
+        if (this.connecting === mine)
             this.connecting = undefined;
         return r;
     }
@@ -230,11 +230,8 @@ export class RemoteLocalDockerExecutionEnv {
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
         const filled = await this.fillWorkspace("restored");
-        if (!filled.ok) {
-            if (filled.standing)
-                this.connectRefusal = filled.error;
-            return { ok: false, error: filled.error };
-        }
+        if (!filled.ok)
+            return this.seat.answer(filled);
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") };
         this.containerId = id;
@@ -299,9 +296,7 @@ export class RemoteLocalDockerExecutionEnv {
         const filled = await this.fillWorkspace("minted");
         if (!filled.ok || this.destroyed) {
             await this.removeInstance(id);
-            if (!filled.ok && filled.standing)
-                this.connectRefusal = filled.error;
-            return { ok: false, error: filled.ok ? new RemoteExecutionError("connect_failed", "execution env destroyed during connect") : filled.error };
+            return filled.ok ? { ok: false, error: new RemoteExecutionError("connect_failed", "execution env destroyed during connect") } : this.seat.answer(filled);
         }
         this.containerId = id;
         this.handle = { sandboxId: this.containerName, provider: PROVIDER, mountPath: this.cfg.mountPath, sessionToken: this.containerName };
@@ -356,10 +351,7 @@ export class RemoteLocalDockerExecutionEnv {
         const verdict = this.homeSeat.settle(probe.ok && probe.value.exitCode === 0 ? { ok: true, stdout: probe.value.stdout } : { ok: false, reason: probe.ok ? `exit ${probe.value.exitCode}` : probe.error.message });
         if (verdict === undefined)
             return undefined;
-        const error = new RemoteExecutionError("connect_failed", verdict.refusal);
-        if (verdict.answered)
-            this.connectRefusal = error;
-        return error;
+        return verdict.answered ? this.seat.answer(connectRefusal("home_unconfirmed", verdict.refusal)).error : new RemoteExecutionError("connect_failed", verdict.refusal);
     }
     async suspendVM(_options) {
         return unsupported("suspendVM");
@@ -373,8 +365,9 @@ export class RemoteLocalDockerExecutionEnv {
     async reconnect(sessionToken) {
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "execution env already destroyed") };
-        if (this.connectRefusal)
-            return { ok: false, error: this.connectRefusal };
+        const held = this.seat.held;
+        if (held)
+            return held;
         if (sessionToken && sessionToken !== this.containerName) {
             return { ok: false, error: new RemoteExecutionError("connect_failed", `reconnect token '${String(sessionToken)}' does not match this env's container '${this.containerName}'`) };
         }
@@ -666,7 +659,7 @@ export class RemoteLocalDockerExecutionEnv {
         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);
+        const r = await this.fsExec(`cat ${redirect} ${shellQuote(dest)}`, abortSignal, { input: typeof content === "string" ? Buffer.from(content, "utf8") : content });
         if (!r.ok)
             return { ok: false, error: fileErrorFromExec(r.error, dest) };
         if (r.value.exitCode !== 0)
@@ -679,9 +672,18 @@ export class RemoteLocalDockerExecutionEnv {
             run: (cmd, abortSignal) => this.fsExec(cmd, abortSignal),
             resolve: (p) => this.resolve(p),
             tempDir: () => this.cwd,
+            boundLane: {
+                run: async (cmd, _cap, abortSignal) => {
+                    const r = await this.fsExec(cmd, abortSignal, { binary: true });
+                    return r.ok ? { ok: true, value: { stdout: r.value.stdoutBytes ?? new Uint8Array(), stderr: r.value.stderr, exitCode: r.value.exitCode } } : r;
+                },
+                payload: "raw",
+                boundSec: this.cfg.commandTimeoutMs / 1000,
+            },
         }));
     }
-    async fsExec(cmd, abortSignal, input) {
+    async fsExec(cmd, abortSignal, o = {}) {
+        const input = o.input;
         if (this.destroyed)
             return { ok: false, error: new ExecutionError("shell_unavailable", "execution env already destroyed") };
         if (!this.containerId) {
@@ -694,7 +696,7 @@ export class RemoteLocalDockerExecutionEnv {
         const argv = this.startArgv(ADAPTER_START, cmd, { stdin: input !== undefined });
         if (!argv.ok)
             return argv;
-        return this.docker(argv.value, { signal: abortSignal, timeoutMs: this.cfg.commandTimeoutMs, ...(input !== undefined ? { input } : {}) });
+        return this.docker(argv.value, { signal: abortSignal, timeoutMs: this.cfg.commandTimeoutMs, ...(input !== undefined ? { input } : {}), ...(o.binary === true ? { binary: true } : {}) });
     }
     async fileInfo(p, abortSignal) {
         return this.posixFs.statFileInfo(p, abortSignal);
@@ -708,6 +710,9 @@ export class RemoteLocalDockerExecutionEnv {
     async canonicalChain(p, abortSignal) {
         return this.posixFs.canonicalChain(p, abortSignal);
     }
+    async openBound(p, abortSignal) {
+        return this.posixFs.openBound(p, abortSignal);
+    }
     async canonicalPath(p, abortSignal) {
         return this.posixFs.canonicalPath(p, abortSignal);
     }
@@ -882,19 +887,7 @@ export class RemoteLocalDockerExecutionEnv {
         });
     }
     joinConnect(signal) {
-        const shared = this.connect();
-        if (signal === undefined)
-            return shared;
-        if (signal.aborted)
-            return Promise.resolve({ ok: false, error: new RemoteExecutionError("aborted", "aborted while connecting") });
-        return new Promise((resolve) => {
-            const onAbort = () => resolve({ ok: false, error: new RemoteExecutionError("aborted", "aborted while connecting") });
-            signal.addEventListener("abort", onAbort, { once: true });
-            void shared.then((r) => {
-                signal.removeEventListener("abort", onAbort);
-                resolve(r);
-            });
-        });
+        return withdrawOnAbort(this.connect(), signal);
     }
     containerShell = "/bin/sh";
     containerShellReady;

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 里没有路径文本。记录不改脚本的退出码:写照它自己的结局答,残留另行留痕。