@sema-agent/server 7.149.0 → 7.151.0

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

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { anchoredPath, joinedPath } from "./exec-path-law.js";
 import { readFileSync } from "node:fs";
 import https from "node:https";
 import http from "node:http";
@@ -10,7 +11,7 @@ import { WORKSPACE_SNAPSHOT_BUCKET_DEFAULT } from "../object-store-buckets.js";
 import { SNAPSHOT_BUCKET_MISSING, isNoSuchBucketAnswer } from "./s3-answer.js";
 import { K8S_WORKSPACE_MOUNT_DEFAULT, SNAPSHOT_KEY_SEGMENT, WORKSPACE_SNAPSHOT_PREFIX_DEFAULT, WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT, mintSnapshotId, snapshotIdHolds, snapshotKeyPrefixProblem, snapshotNameOwnedBy } from "../workspace-space.js";
 import { spaceCommitAlive } from "../workspace-space-commit.js";
-import { incarnationLogPrefix, redactIncarnations } from "../session-incarnation.js";
+import { SESSION_INCARNATION_MISSING, incarnationLogPrefix, redactIncarnations } from "../session-incarnation.js";
 import { WORKSPACE_CACHE_SPACE_LABEL, workspaceCacheClaimOf, workspaceCacheEnv } from "../workspace-cache.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { PodDeleteRefused, reportPodDeleteFailed } from "./k8s-pod-delete-failure.js";
@@ -26,6 +27,7 @@ import { createPosixShellFs } from "./posix-shell-fs.js";
 import { randomUUID } from "node:crypto";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
 import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
+import { connectRefusal, createConnectSeat } from "./remote-env-connect-seat.js";
 const PROVIDER = "k8s";
 const K8S_BG_DIR_ROOT = "/tmp/.sema-bg";
 const K8S_BG_MAX_CONCURRENT = numEnvOr("K8S_BG_MAX_CONCURRENT", 8, 1);
@@ -91,6 +93,10 @@ function spaceLaneOf(policy, occupant) {
 function spaceReadFailed(what, detail, cause) {
     return { ok: false, error: new RemoteExecutionError("connect_failed", `workspace space ${what} read failed${detail}`, cause instanceof Error ? cause : undefined) };
 }
+function isQuotaExceeded(json) {
+    const message = typeof json === "object" && json !== null ? json.message : undefined;
+    return typeof message === "string" && /\bexceeded quota\b/.test(message);
+}
 function restoreFailureIsTransient(cls) {
     switch (cls) {
         case "timeout":
@@ -221,7 +227,18 @@ export class RemoteK8sExecutionEnv {
     idleWaiters = [];
     connectInFlight;
     resumeInFlight;
-    connectRefusal;
+    seat = createConnectSeat({
+        live: () => (this.podName !== undefined && this.connectInFlight === undefined && !this.destroyed ? this.workspaceHandle() : undefined),
+        inFlight: () => this.connectInFlight,
+        establish: (config) => {
+            const walk = this.establish(config).finally(() => {
+                if (this.connectInFlight === walk)
+                    this.connectInFlight = undefined;
+            });
+            this.connectInFlight = walk;
+            return walk;
+        },
+    });
     get homeDir() {
         return this.homeSeat.home;
     }
@@ -300,7 +317,7 @@ export class RemoteK8sExecutionEnv {
         return this.cfg.timeoutMs;
     }
     resolve(p) {
-        return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
+        return anchoredPath(path.posix, this.cwd, p);
     }
     workspaceHandle() {
         return { sandboxId: this.podName ?? "(unconnected)", provider: PROVIDER, mountPath: this.cwd, ...(this.handleSnapshotId ? { snapshotId: this.handleSnapshotId } : {}) };
@@ -385,18 +402,12 @@ export class RemoteK8sExecutionEnv {
         });
     }
     connect(config) {
-        if (this.connectInFlight)
-            return this.connectInFlight;
-        const walk = this.establish(config).finally(() => {
-            if (this.connectInFlight === walk)
-                this.connectInFlight = undefined;
-        });
-        this.connectInFlight = walk;
-        return walk;
+        return this.seat.connect(config);
     }
     async establish(config) {
-        if (this.connectRefusal)
-            return this.connectRefusal;
+        const held = this.seat.held;
+        if (held)
+            return held;
         const signal = config?.abortSignal;
         const lane = this.spaceLane;
         switch (lane.state) {
@@ -433,7 +444,7 @@ export class RemoteK8sExecutionEnv {
             const filled = await fill.fill(this.fillChannel(), this.cwd, c.origin);
             if (!filled.ok) {
                 await this.releasePod();
-                return filled.standing ? this.holdRefusal(filled.error) : { ok: false, error: filled.error };
+                return this.seat.answer(filled);
             }
         }
         if (this.destroyed) {
@@ -487,10 +498,6 @@ export class RemoteK8sExecutionEnv {
             effect: "WORKSPACE_PERSIST=space, but the session store has no occupant (incarnation) for this run's session — its /workspace is neither restored nor saved (it is never keyed by the session id instead)",
         });
     }
-    holdRefusal(error) {
-        this.connectRefusal = { ok: false, error };
-        return this.connectRefusal;
-    }
     refusePod(pod, phase, reason, message) {
         this.logger?.warn("sandbox_pod_refused", {
             pod,
@@ -500,19 +507,24 @@ export class RemoteK8sExecutionEnv {
             ...(this.cfg.sessionId ? { sessionId: this.cfg.sessionId } : {}),
             effect: "the cluster created this run's sandbox pod and it ended before it ran — this run's operations answer the same refusal without creating another pod; a retry of the run builds a fresh sandbox",
         });
-        return this.holdRefusal(new RemoteExecutionError("connect_failed", `pod entered ${phase} before Running (${reason ?? "?"}) — the cluster refused this run's sandbox pod; the refusal stands for the run (no pod is created again), a retry of the run asks the cluster afresh`));
+        return this.seat.answer(connectRefusal("pod_admission_refused", `pod entered ${phase} before Running (${reason ?? "?"}) — the cluster refused this run's sandbox pod; the refusal stands for the run (no pod is created again), a retry of the run asks the cluster afresh`));
     }
     refuseUnreadableOccupant(code) {
         const ways = [...(this.spaceLane.state === "unreadable" ? ["WORKSPACE_PERSIST=off"] : []), ...(this.cacheLane.state === "unreadable" ? ["WORKSPACE_CACHE=off"] : [])].join(" and ");
+        const missing = code === SESSION_INCARNATION_MISSING;
         if (!this.unreadableOccupantSaid) {
             this.unreadableOccupantSaid = true;
             this.logger?.warn("workspace_space_unreadable_occupant", {
                 sessionId: this.cfg.sessionId,
                 code,
-                effect: `the session store did not answer for this run's session occupant (incarnation) — this run is refused rather than started on a workspace that is neither restored nor saved; ${ways} runs without it`,
+                effect: missing
+                    ? `the session row for this run carries no occupant (incarnation) token — this run is refused rather than started on a workspace that is neither restored nor saved; ${ways} runs without it`
+                    : `the session store did not answer for this run's session occupant (incarnation) — this run is refused rather than started on a workspace that is neither restored nor saved; ${ways} runs without it`,
             });
         }
-        return spaceReadFailed("occupant", ` (${code}) — refusing to start this run on a workspace that could be neither restored nor saved; retry the run once the session store answers, or set ${ways}`);
+        return missing
+            ? this.seat.answer(connectRefusal("occupant_missing", `workspace space occupant read failed (${code}) — the session row carries no occupant token, so this run is not started on a workspace that could be neither restored nor saved; give the row its token or delete the session, or set ${ways}`))
+            : connectRefusal("occupant_unreadable", `workspace space occupant read failed (${code}) — refusing to start this run on a workspace that could be neither restored nor saved; retry the run once the session store answers, or set ${ways}`);
     }
     spaceLine(event, space, fields) {
         this.snapshotLine(event, { space: incarnationLogPrefix(space.incarnation), ...fields });
@@ -523,8 +535,9 @@ export class RemoteK8sExecutionEnv {
     provision(signal) {
         const space = this.spaceLane;
         const cache = this.cacheLane;
-        if (this.connectRefusal)
-            return Promise.resolve(this.connectRefusal);
+        const held = this.seat.held;
+        if (held)
+            return Promise.resolve(held);
         if (space.state === "unreadable")
             return Promise.resolve(this.refuseUnreadableOccupant(space.code));
         if (cache.state === "unreadable")
@@ -539,7 +552,7 @@ export class RemoteK8sExecutionEnv {
         const halt = signal ? AbortSignal.any([signal, refused.signal]) : refused.signal;
         return withRetry(async () => {
             const r = await once(signal);
-            if (!r.ok && this.connectRefusal)
+            if (!r.ok && this.seat.held)
                 refused.abort();
             return r;
         }, policy, { signal: halt });
@@ -715,7 +728,7 @@ export class RemoteK8sExecutionEnv {
         const leaseName = broker !== undefined ? `${SANDBOX_LEASE_NAME_PREFIX}${randomUUID()}` : undefined;
         const placeholder = broker !== undefined ? buildSandboxLeaseFile(broker.origins, placeholderLeaseEntries(broker.origins)) : undefined;
         if (placeholder !== undefined && !placeholder.ok) {
-            return this.holdRefusal(new RemoteExecutionError("connect_failed", `the member-credential broker cannot be set up for this pod: ${placeholder.problem}`));
+            return this.seat.answer(connectRefusal("credential_broker_refused", `the member-credential broker cannot be set up for this pod: ${placeholder.problem}`));
         }
         const layered = { ...(cache ? workspaceCacheEnv(cache.mount) : {}), ...(this.cfg.podEnv ?? {}) };
         const envEntries = [
@@ -769,7 +782,7 @@ export class RemoteK8sExecutionEnv {
                 applyPodSpecPatch(pod, this.cfg.podSpecPatch, { broker: true });
             }
             catch (e) {
-                return this.holdRefusal(new RemoteExecutionError("connect_failed", `${errorMessageOf(e)} — no pod is created (the member-credential broker never shares a pod with a patch that could reach it)`));
+                return this.seat.answer(connectRefusal("credential_broker_refused", `${errorMessageOf(e)} — no pod is created (the member-credential broker never shares a pod with a patch that could reach it)`));
             }
         }
         else if (this.cfg.podSpecPatch)
@@ -782,7 +795,8 @@ export class RemoteK8sExecutionEnv {
             return { ok: false, error: new RemoteExecutionError("connect_failed", `pod create RPC failed: ${e instanceof Error ? e.message : String(e)}`, e instanceof Error ? e : undefined) };
         }
         if (created.status === 401 || created.status === 403) {
-            return { ok: false, error: new RemoteExecutionError("auth_failed", `pod create denied (${created.status}): ${JSON.stringify(created.json).slice(0, 200)}`) };
+            const denied = `pod create denied (${created.status}): ${JSON.stringify(created.json).slice(0, 200)}`;
+            return created.status === 403 && isQuotaExceeded(created.json) ? connectRefusal("pod_quota_exceeded", denied) : { ok: false, error: new RemoteExecutionError("auth_failed", denied) };
         }
         if (created.status >= 300) {
             return { ok: false, error: new RemoteExecutionError("connect_failed", `pod create failed (${created.status}): ${JSON.stringify(created.json).slice(0, 300)}`) };
@@ -875,8 +889,7 @@ export class RemoteK8sExecutionEnv {
             if (verdict !== undefined) {
                 await this.deletePod(name).catch(() => { });
                 this.podName = undefined;
-                const error = new RemoteExecutionError("connect_failed", verdict.refusal);
-                return verdict.answered ? this.holdRefusal(error) : { ok: false, error };
+                return verdict.answered ? this.seat.answer(connectRefusal("home_unconfirmed", verdict.refusal)) : { ok: false, error: new RemoteExecutionError("connect_failed", verdict.refusal) };
             }
         }
         if (cache?.fresh)
@@ -1128,7 +1141,7 @@ export class RemoteK8sExecutionEnv {
         const detail = ` (${SNAPSHOT_BUCKET_MISSING}): the workspace snapshot bucket "${bucket}" (WORKSPACE_SNAPSHOT_BUCKET; default ${WORKSPACE_SNAPSHOT_BUCKET_DEFAULT}) does not exist in the object store — ` +
             `refusing to start this run on a workspace that could be neither restored nor saved. Ways out: create the bucket, or set WORKSPACE_SNAPSHOT_BUCKET to one that exists, ` +
             "or set WORKSPACE_PERSIST=off for a deployment that keeps no workspace between runs";
-        return this.holdRefusal(read === "pointer" ? spaceReadFailed("pointer", detail).error : new RemoteExecutionError("connect_failed", `workspace snapshot archive read failed${detail}`));
+        return this.seat.answer(connectRefusal("snapshot_bucket_missing", read === "pointer" ? `workspace space pointer read failed${detail}` : `workspace snapshot archive read failed${detail}`));
     }
     async readLatest(space, signal) {
         const r = await this.readPointer(space, "latest", signal);
@@ -1390,7 +1403,7 @@ export class RemoteK8sExecutionEnv {
                 case "space": {
                     const tries = attempt === 1 ? "1 attempt" : `${attempt} attempts`;
                     this.spaceLine("workspace_restore_failed", target.space, { snapshotId, class: failure.cls, attempts: attempt, boundMs: this.cfg.dataTimeoutMs, error: failure.detail });
-                    return this.holdRefusal(new RemoteExecutionError("connect_failed", `${failure.detail} — the workspace's latest snapshot (${snapshotId}) is in the store but did not come back (${failure.cls}, ${tries}, bound ${this.cfg.dataTimeoutMs}ms each), ` +
+                    return this.seat.answer(connectRefusal("archive_unrecoverable", `${failure.detail} — the workspace's latest snapshot (${snapshotId}) is in the store but did not come back (${failure.cls}, ${tries}, bound ${this.cfg.dataTimeoutMs}ms each), ` +
                         "so this run does not start on an empty /workspace. Ways out: raise WORKSPACE_SNAPSHOT_TIMEOUT_MS if the archive is large, " +
                         "or set WORKSPACE_PERSIST=off for one run (it starts from an empty /workspace and deletes no snapshot)", failure.cause));
                 }
@@ -2196,7 +2209,7 @@ export class RemoteK8sExecutionEnv {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
-        return ok(path.posix.join(...parts));
+        return ok(joinedPath(path.posix, parts));
     }
     async readBinaryFile(p, abortSignal) {
         const abs = this.resolve(p);
@@ -2262,6 +2275,14 @@ export class RemoteK8sExecutionEnv {
             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.execData(cmd, abortSignal);
+                    return r.ok ? { ok: true, value: { stdout: Buffer.from(r.value.stdout, "utf8"), stderr: r.value.stderr, exitCode: r.value.exitCode } } : r;
+                },
+                payload: "base64",
+                boundSec: this.cfg.dataTimeoutMs / 1000,
+            },
         }));
     }
     async fileInfo(p, abortSignal) {
@@ -2276,6 +2297,9 @@ export class RemoteK8sExecutionEnv {
     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);
     }

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

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { type LaneHomeConfig } from "../lane-home-probe.js";
 import { type LaneLogger } from "./remote-shell.js";
 import { type CustodyMember } from "./workspace-custody.js";
-import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, type ExecutionEnvCapabilities } from "@sema-agent/core";
+import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type SymlinkChain, type BoundFileObject, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory, type ExecutionEnvCapabilities } from "@sema-agent/core";
 import { type SandboxReadFloorKnob } from "../execution-lane-caps.js";
 import { type SandboxReadFloor } from "./sandbox-read-floor.js";
 import type { WorkspaceFill, WorkspaceFillOf } from "./workspace-fill.js";
@@ -140,9 +140,12 @@ export declare class RemoteLocalDockerExecutionEnv implements CustodyMember<Loca
     private destroyed;
     /** In-flight connect, memoized so concurrent lazy first-use starts exactly one container (no double-run). */
     private connecting?;
-    /** 这只环境的拒 —— 记一次、此后每次连接原样回它(同一镜像同一答案:不再起容器、不再问)。两个写者:家目录(环境答了而与声明不一致)
-     *  与恢复点的填充(换一只容器也是同一个答的拒:种子不是项目包、摘要不符、镜像没有 `tar`、镜像预置撞名 —— `FillOutcome.standing`)。 */
-    private connectRefusal?;
+    /**
+     * 建连座(`remote-env-connect-seat.ts`):`connect` 的唯一次序(记住的拒 ⇒ 原样再答 · 起容器在飞 ⇒ 等那一次 · 已连 ⇒ 当下的把手 · 否则起或附着一只),并持有这只环境记住的拒 ——
+     * 记一次、此后每次连接原样回它(同一镜像同一答案:不再起容器、不再问)。两件立定的事实写它:家目录(环境答了而与声明不一致;`env.home_unconfirmed`)
+     * 与恢复点的填充(换一只容器也是同一个答的拒:种子不是项目包、摘要不符、镜像没有 `tar`、镜像预置撞名 —— `FillOutcome.standing`;`env.sandbox_refused`)。
+     */
+    private readonly seat;
     /** 家目录的座(声明在场 ⇒ 开环境那一拍对证 · 否则开容器那一拍实测 · 实测缺席 ⇒ 缺席 + 一行 warn)。与其余读得出家目录的车道同一只判官、同一句拒。 */
     private readonly homeSeat;
     /** 本环境的生命期信号:{@link destroy} 先断它 —— 在帽前等空位的那一次起动立刻收场(不拖满预算)。 */
@@ -171,7 +174,7 @@ export declare class RemoteLocalDockerExecutionEnv implements CustodyMember<Loca
         ok: false;
         error: RemoteExecutionError;
     }>;
-    /** 一只在飞的连接(并发的首用调用方 / 附着都 join 它 —— 只起一只容器、只附着一次);失败 ⇒ 清掉备忘,下一次重来。 */
+    /** 一只在飞的连接(并发的首用调用方 / 附着都 join 它 —— 只起一只容器、只附着一次);落定即清(按身份):连上 = `containerId`,失败 ⇒ 下一次重来。 */
     private connectOnce;
     /**
      * 先问 daemon 这只身份的容器({@link sightContainer}),再按它的样子(状态闭集,穷举):
@@ -214,8 +217,8 @@ export declare class RemoteLocalDockerExecutionEnv implements CustodyMember<Loca
     private fillChannel;
     /**
      * 家目录:座要问({@link LaneHomeSeat.asks}:声明在场 ⇒ 对证;没声明 ⇒ 实测)⇒ 在本容器里问一次 `$HOME`(与命令同一条 `docker exec` 通道、同一份 `-e` env),读数交座。
-     * 声明在场:环境答了而不一致 / 不是绝对路径 ⇒ 回拒并记在环境上(同一镜像同一答案:此后每次连接原样回它,不再起容器、不再问);没答上(exec 失败 / 超时 / 非零退出)⇒ 这一次同样不开,
-     * 但不记(与任何一次起容器失败同:下一次连接重问)。没声明:座收下绝对路径;答不上 / 不是绝对路径 ⇒ 座缺席 + 一行 warn,环境照开(没声明就没有声明可拒)。
+     * 声明在场:环境答了而不一致 / 不是绝对路径 ⇒ 立定的拒(`env.home_unconfirmed`,建连座记住它:同一镜像同一答案,此后每次连接原样回它,不再起容器、不再问);
+     * 没答上(exec 失败 / 超时 / 非零退出)⇒ 这一次同样不开(`connect_failed`),但不记(与任何一次起容器失败同:下一次连接重问)。没声明:座收下绝对路径;答不上 / 不是绝对路径 ⇒ 座缺席 + 一行 warn,环境照开(没声明就没有声明可拒)。
      * 调用方中止 ⇒ `aborted`、不记、不交座。容器由调用方收。
      */
     private homeVerdict;
@@ -306,7 +309,7 @@ export declare class RemoteLocalDockerExecutionEnv implements CustodyMember<Loca
     private get posixFs();
     /** 文件面的一次容器内 shell 往返(基座、暂存写的准备 / 上传 / 提交 / 清理共用)。承 fsReady 契约(其余三腿走公有 exec、守卫天然在;本腿直用私有
      *  docker,必须自带):destroyed 守卫 + 懒连接,fail closed 不抛 —— 消息保留 "destroyed" 字样(测试钉的就是它)。`input` 在场 ⇒ 同一只 argv 多一个
-     *  `-i`、载荷走 stdin({@link pipeIn});身份与工作目录与不带载荷的往返逐字相同。 */
+     *  `-i`、载荷走 stdin({@link pipeIn});身份与工作目录与不带载荷的往返逐字相同。`binary` ⇒ stdout 逐字节收(`stdoutBytes`,绑定读的载荷;与 readBinaryFile 同一收集器)。 */
     private fsExec;
     fileInfo(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
     listDir(p: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
@@ -315,6 +318,8 @@ export declare class RemoteLocalDockerExecutionEnv implements CustodyMember<Loca
      *  循环(上限 64、只锚不折、遇环即止),脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份。
      *  缺席读法用不上(本腿在场);`ok:false` 由 core 读作「这一次没有跳」,永不是拒绝。 */
     canonicalChain(p: string, abortSignal?: AbortSignal): Promise<Result<SymlinkChain, FileError>>;
+    /** 绑定读(逐答重绑,Linux 读法;脚本与读法的单一属主在 `remote-shell.ts`,四条 shell 腿共用同一份)。 */
+    openBound(p: string, abortSignal?: AbortSignal): Promise<Result<BoundFileObject, FileError>>;
     canonicalPath(p: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
     exists(p: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
     createDir(p: string, options?: {

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

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { anchoredPath, joinedPath } from "./exec-path-law.js";
 import { spawn } from "node:child_process";
 import { hostSubprocessEnv } from "../server-secret-env.js";
 import { LANE_HOME_PROBE_COMMAND, LaneHomeSeat } from "../lane-home-probe.js";
@@ -12,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";
@@ -48,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;
@@ -89,7 +95,7 @@ export class RemoteLocalDockerExecutionEnv {
         return this.teardownSettled && this.leftover === undefined;
     }
     resolve(p) {
-        return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
+        return anchoredPath(path.posix, this.cwd, p);
     }
     workspaceHandle() {
         return this.handle ?? { sandboxId: "(unconnected)", provider: PROVIDER, mountPath: this.cfg.mountPath };
@@ -99,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;
     }
@@ -229,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;
@@ -298,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 };
@@ -355,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");
@@ -372,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}'`) };
         }
@@ -618,7 +612,7 @@ export class RemoteLocalDockerExecutionEnv {
         return ok(this.resolve(p));
     }
     async joinPath(parts) {
-        return ok(path.posix.join(...parts));
+        return ok(joinedPath(path.posix, parts));
     }
     async readBinaryFile(p, abortSignal) {
         const ready = await this.fsReady(p, abortSignal);
@@ -665,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)
@@ -678,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) {
@@ -693,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);
@@ -707,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);
     }
@@ -881,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>>;