@sema-agent/server 1.323.0 → 2.0.1

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

@@ -4,12 +4,18 @@ export interface SshEnvConfig {
     host: string;
     port?: number;
     username: string;
+    /** PEM private key — from the adapter-held secret env (NEVER the workspace). design/61 §5 #2. */
     privateKey: string;
     passphrase?: string;
+    /** Workspace root; relative paths resolve against it. Default "." (the login dir). */
     mountPath?: string;
+    /** Connect handshake bound (ms). */
     readyTimeoutMs?: number;
+    /** Per-command wall-clock bound (ms) when the caller gives none — NOT the connection lifetime. */
     commandTimeoutMs?: number;
+    /** File-transfer (sftp) bound (ms). */
     dataTimeoutMs?: number;
+    /** connect retry (idempotent establishment only — withRetry, design/61 §2A). */
     retry?: {
         maxAttempts?: number;
         backoffMs?: number;
@@ -22,6 +28,11 @@ type ConnectResult = {
     ok: false;
     error: RemoteExecutionError;
 };
+/**
+ * Test seam (design/61 §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
+ * without a live host.
+ */
 export interface SshEnvDeps {
     connectOnce?: (signal?: AbortSignal) => Promise<ConnectResult>;
 }
@@ -30,11 +41,21 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
         isolation: boolean;
         suspendable: boolean;
     };
+    /** Working directory; relative paths resolve against it (ExecutionEnv contract). Starts at mountPath. */
     cwd: string;
     private conn?;
     private sftpPromise?;
     private destroyed;
+    /** [1165] 代际闸:destroy/reconnect 各自 +1。逻辑连接操作(startConnect)起飞时抓拍一次并贯穿全部
+     *  重试轮(四轮复审:抓拍若在 connectOnce 内,被顶替代的下一轮重试会抓到**新**代际混进新代)——
+     *  每轮起跳先查代际/destroyed(陈旧=不再开 socket),ready 到达再查一次(在飞握手 late-ready=end
+     *  不赋 conn)。关死「A 在飞→reconnect 起 B→A 竞后抢占/成孤儿活连接」的全部竞窗。 */
     private connEpoch;
+    /** [1165] 四轮复审 single-flight:connect()/reconnect()/懒连接三路共用一条代际键在飞记录——任何一路
+     *  在飞时其余路 join 同一 promise(同代际),绝不并起两条连接;settle 时按记录身份清(旧败诺清不掉
+     *  新记录)。五轮复审:①记录带 kind——并发 reconnect join 已在飞的 replace 记录(不再各自 bump 代际
+     *  =重连风暴);②共享尝试**不携带任何 caller 信号**(首创者的 pre-abort 不得毒化 joiner;单 caller
+     *  取消只退它自己的等待,底层握手余命 ≤ readyTimeout 有界,彻底取消归 destroy 代际闸)。 */
     private inFlight?;
     private readonly cfg;
     private readonly injectedConnectOnce?;
@@ -48,8 +69,15 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /** 五轮复审:per-caller 可中止等待(共享诺不动,只退本 caller)。 */
     private raceConnAbort;
+    /** [1165] 四轮复审:三路(connect/reconnect/懒连接)唯一的连接发起点——同代际在飞记录 join,settle
+     *  身份清;代际抓拍一次贯穿全部重试轮,每轮起跳先查(陈旧/destroyed=不再开 socket,用不可重试的
+     *  aborted 码即刻收敛 withRetry)。五轮复审:共享尝试零 caller 信号(取消面全在 per-caller race)。 */
     private startConnect;
+    /** [1165] exec/execStream/sftp 共用的懒连接入口。已连=零开销直过;未连=走完整 connect()(含重试策略)。
+     *  caller 的 signal 只中止**它自己的等待**(共享在飞尝试继续伺服其他等待者;彻底取消归 destroy 的代际
+     *  闸管,handshake 余命 ≤ readyTimeout 有界)。 */
     private ensureConnected;
     private connectOnce;
     suspendVM(_options?: VmLifecycleOptions): Promise<{
@@ -73,6 +101,7 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /** Re-establish a dropped connection (supported — unlike suspend, reconnect is idempotent establishment). */
     reconnect(_sessionToken: SessionToken): Promise<{
         ok: true;
         value: WorkspaceHandle;
@@ -80,6 +109,7 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /** Close the SSH connection. Does NOT destroy the machine (real system) — idempotent, never throws. */
     destroy(): Promise<void>;
     cleanup(): Promise<void>;
     exec(command: string, options?: ExecOpts): Promise<Result<{
@@ -125,6 +155,11 @@ export declare class RemoteSshExecutionEnv implements RemoteExecutionEnv {
     private connErr;
     private fileError;
 }
+/**
+ * `ExecutionEnvFactory` for the SSH backend — one fresh (unconnected) env per task against the same host
+ * (lazy: connects on first use). Config (host/user/key) is control-plane-supplied; the Runner owns the
+ * lifetime and calls `destroy()` (= disconnect) on task end.
+ */
 export declare function sshExecutionEnvFactory(config: SshEnvConfig): ExecutionEnvFactory;
 export {};
 //# sourceMappingURL=remote-env-ssh.d.ts.map

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

@@ -1,3 +1,24 @@
+/**
+ * `RemoteSshExecutionEnv` — the SSH implementation of core's `RemoteExecutionEnv` seam (design/61). A PEER
+ * adapter to the E2B one (NOT chained): `docker(agent) → [SSH adapter] → real machine`. Use case: an AI
+ * orchestrating batch deployment over SSH-reachable hosts.
+ *
+ * 🔴 **SSH targets a REAL system, not a disposable sandbox** (design/61 §5):
+ *  - `capabilities = { isolation: false, suspendable: false }` — actions are PERMANENT, no snapshot. The
+ *    orchestrator/leader tightens autonomy + the design/37 policy gate + HITL on a non-isolated env (design/53).
+ *  - `destroy()` / `cleanup()` **close the SSH connection** — they do NOT destroy the machine (vs E2B's
+ *    teardown). Anything the agent created on the host PERSISTS (cleanup is the gate/operator's job).
+ *  - `suspendVM`/`resumeVM`/`postResumeInit` → typed `"unsupported"` (a real machine isn't snapshotable;
+ *    design/45 durable suspend N/A). `reconnect` re-establishes the connection.
+ *
+ * 🔴 **Credential isolation (design/61 §5 #2 / design/53):** the private key is held by the control plane and
+ * injected to the ADAPTER as a secret env (`SecretRef.destination:"adapter"`) — it NEVER enters the workspace
+ * / agent-reachable surface. The agent operates via exec/sftp; it cannot read the key.
+ *
+ * Liveness: every SSH op is a network round-trip that can hang — `connect` is wrapped in `withRetry` (idempotent
+ * establishment only), exec/sftp carry a bounded timeout, and a hang surfaces a typed retryable error (the
+ * shared timeout/liveness contract, reused).
+ */
 import path from "node:path";
 import { Client } from "ssh2";
 import { shellQuote, kindFromMode } from "./remote-shell.js";
@@ -12,11 +33,21 @@ const unsupported = (op) => ({
 });
 export class RemoteSshExecutionEnv {
     capabilities = { isolation: false, suspendable: false };
+    /** Working directory; relative paths resolve against it (ExecutionEnv contract). Starts at mountPath. */
     cwd;
     conn;
     sftpPromise;
     destroyed = false;
+    /** [1165] 代际闸:destroy/reconnect 各自 +1。逻辑连接操作(startConnect)起飞时抓拍一次并贯穿全部
+     *  重试轮(四轮复审:抓拍若在 connectOnce 内,被顶替代的下一轮重试会抓到**新**代际混进新代)——
+     *  每轮起跳先查代际/destroyed(陈旧=不再开 socket),ready 到达再查一次(在飞握手 late-ready=end
+     *  不赋 conn)。关死「A 在飞→reconnect 起 B→A 竞后抢占/成孤儿活连接」的全部竞窗。 */
     connEpoch = 0;
+    /** [1165] 四轮复审 single-flight:connect()/reconnect()/懒连接三路共用一条代际键在飞记录——任何一路
+     *  在飞时其余路 join 同一 promise(同代际),绝不并起两条连接;settle 时按记录身份清(旧败诺清不掉
+     *  新记录)。五轮复审:①记录带 kind——并发 reconnect join 已在飞的 replace 记录(不再各自 bump 代际
+     *  =重连风暴);②共享尝试**不携带任何 caller 信号**(首创者的 pre-abort 不得毒化 joiner;单 caller
+     *  取消只退它自己的等待,底层握手余命 ≤ readyTimeout 有界,彻底取消归 destroy 代际闸)。 */
     inFlight;
     cfg;
     injectedConnectOnce;
@@ -42,13 +73,20 @@ export class RemoteSshExecutionEnv {
     workspaceHandle() {
         return { sandboxId: `${this.cfg.host}:${this.cfg.port}`, provider: PROVIDER, mountPath: this.cwd };
     }
+    // ─────────────────────────────── lifecycle ───────────────────────────────
     async connect(config) {
+        // [1165] 三轮复审:destroy 后一律不复活(显式 connect/reconnect 同禁)——destroyed env 是 teardown
+        // 终态,复活=任务清理后还能执行命令/留活连接(资源与安全双漏)。恢复流程走工厂新铸实例。
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "SSH env destroyed — create a fresh env instead of reviving") };
+        // 已连=幂等成功(四轮复审:旧形二次 connect 会并起第二条连接顶掉第一条=孤儿活连接)。
         if (this.conn)
             return ok(this.workspaceHandle());
+        // 五轮复审:caller 信号只管 caller 自己的等待(race),共享尝试不沾——pre-abort 的首创者不得
+        // 毒化同拍 joiner,反向 pre-abort 的 joiner 也必须即时退出。
         return this.raceConnAbort(this.startConnect("establish"), config?.abortSignal);
     }
+    /** 五轮复审:per-caller 可中止等待(共享诺不动,只退本 caller)。 */
     async raceConnAbort(shared, signal) {
         if (!signal)
             return shared;
@@ -66,12 +104,15 @@ export class RemoteSshExecutionEnv {
             return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted while waiting") };
         return raced;
     }
+    /** [1165] 四轮复审:三路(connect/reconnect/懒连接)唯一的连接发起点——同代际在飞记录 join,settle
+     *  身份清;代际抓拍一次贯穿全部重试轮,每轮起跳先查(陈旧/destroyed=不再开 socket,用不可重试的
+     *  aborted 码即刻收敛 withRetry)。五轮复审:共享尝试零 caller 信号(取消面全在 per-caller race)。 */
     startConnect(kind) {
         if (this.inFlight && this.inFlight.epoch === this.connEpoch)
             return this.inFlight.promise;
         const epoch = this.connEpoch;
         const policy = {
-            retryableCodes: ["connect_failed", "timeout"],
+            retryableCodes: ["connect_failed", "timeout"], // NOT auth_failed (permanent — retrying a rejected key burns budget)
             maxAttempts: this.cfg.retry.maxAttempts,
             backoffMs: (failed) => this.cfg.retry.backoffMs * failed,
         };
@@ -86,22 +127,28 @@ export class RemoteSshExecutionEnv {
         const record = { epoch, kind, promise: raw };
         record.promise = raw.then((r) => {
             if (this.inFlight === record)
-                this.inFlight = undefined;
+                this.inFlight = undefined; // 身份清:旧败诺清不掉新记录
             return r;
         });
         this.inFlight = record;
         return record.promise;
     }
+    /** [1165] exec/execStream/sftp 共用的懒连接入口。已连=零开销直过;未连=走完整 connect()(含重试策略)。
+     *  caller 的 signal 只中止**它自己的等待**(共享在飞尝试继续伺服其他等待者;彻底取消归 destroy 的代际
+     *  闸管,handshake 余命 ≤ readyTimeout 有界)。 */
     async ensureConnected(signal) {
+        // destroyed 先于 conn 查(三轮复审:teardown 竞窗里 conn 可能在 destroy 后才被 ready 赋上——那条
+        // 连接由 ready 守卫立即 end,这里也不得放行)。
         if (this.destroyed)
             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");
+        const shared = this.startConnect("establish"); // 四轮复审:single-flight join(与显式 connect/reconnect 同记录)
         let r;
         if (signal) {
+            // 可中止等待:只退出本 caller 的 await,不动共享在飞记录(其他等待者照常拿结果)。
             let onAbort;
             const aborted = new Promise((res) => {
                 onAbort = () => res("aborted");
@@ -120,6 +167,8 @@ export class RemoteSshExecutionEnv {
         if (r.ok) {
             if (this.conn)
                 return ok(undefined);
+            // 旗到手但连接已不在(建后即断竞窗)——在飞记录 settle 时已自清;诚实报不可用,下次调用自然
+            // 重建(不递归重连:防断连风暴无界重试)。
             return { ok: false, error: new ExecutionError("shell_unavailable", "SSH connection dropped right after connect") };
         }
         if (r.error.code === "aborted")
@@ -127,7 +176,7 @@ export class RemoteSshExecutionEnv {
         return { ok: false, error: new ExecutionError("shell_unavailable", `SSH lazy-connect failed: ${r.error.message}`, r.error) };
     }
     connectOnce(signal, opEpoch) {
-        const epoch = opEpoch ?? this.connEpoch;
+        const epoch = opEpoch ?? this.connEpoch; // 代际=逻辑连接操作抓拍(四轮复审:重试轮不得混进新代)
         return new Promise((resolve) => {
             if (signal?.aborted)
                 return resolve({ ok: false, error: new RemoteExecutionError("aborted", "connect aborted") });
@@ -142,15 +191,19 @@ export class RemoteSshExecutionEnv {
             };
             c.on("ready", () => {
                 if (this.destroyed || epoch !== this.connEpoch) {
+                    // [1165] 三轮复审 teardown/代际竞窗:destroy 或 reconnect 之后才 ready 的旧代连接——立即断掉
+                    // 且不赋 conn(否则 sole destroy 之后留一条活连接+可执行面,或旧代顶掉新代)。
                     try {
                         c.end();
                     }
-                    catch { }
+                    catch { /* noop */ }
                     resolve({ ok: false, error: new RemoteExecutionError("connect_failed", this.destroyed ? "SSH env destroyed while connecting" : "SSH connection superseded while connecting (reconnect)") });
                     return;
                 }
                 this.conn = c;
                 this.sftpPromise = undefined;
+                // If this live connection later drops, clear our handles so the next exec()/fs op fails closed with
+                // "shell_unavailable" (council #3) instead of hitting a dead-but-truthy client with a raw ssh2 error.
                 c.on("close", () => {
                     if (this.conn === c) {
                         this.conn = undefined;
@@ -163,6 +216,7 @@ export class RemoteSshExecutionEnv {
                     c.end();
                 }
                 catch {
+                    /* noop */
                 }
                 resolve({ ok: false, error: this.connErr(e) });
             });
@@ -183,24 +237,29 @@ export class RemoteSshExecutionEnv {
     async postResumeInit() {
         return unsupported("postResumeInit");
     }
+    /** Re-establish a dropped connection (supported — unlike suspend, reconnect is idempotent establishment). */
     async reconnect(_sessionToken) {
         if (this.destroyed)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "SSH env destroyed — create a fresh env instead of reviving") };
+        // 五轮复审:并发 reconnect join 已在飞的 replace 记录(不再各自 bump 代际=每路一条握手的重连风暴);
+        // 只有「无在飞 replace」才推代际顶掉旧 establish/旧连接。
         if (this.inFlight && this.inFlight.epoch === this.connEpoch && this.inFlight.kind === "replace")
             return this.inFlight.promise;
-        this.connEpoch++;
+        this.connEpoch++; // [1165] 在飞旧代自灭(每轮起跳查 + ready 守卫双闸)
         this.conn?.end();
         this.conn = undefined;
         this.sftpPromise = undefined;
-        return this.startConnect("replace");
+        return this.startConnect("replace"); // 四轮复审:发起点唯一——重连期间的 exec/sftp join 同一记录
     }
+    /** Close the SSH connection. Does NOT destroy the machine (real system) — idempotent, never throws. */
     async destroy() {
-        this.destroyed = true;
-        this.connEpoch++;
+        this.destroyed = true; // [1165] 懒连接不复活已拆毁的 env(fail-closed 契约保持)
+        this.connEpoch++; // 在飞连接每轮起跳查+ready 守卫自灭(handshake 余命 ≤ readyTimeout,有界)
         try {
             this.conn?.end();
         }
         catch {
+            /* best-effort */
         }
         this.conn = undefined;
         this.sftpPromise = undefined;
@@ -208,7 +267,10 @@ export class RemoteSshExecutionEnv {
     async cleanup() {
         return this.destroy();
     }
+    // ─────────────────────────────── exec ───────────────────────────────
     async exec(command, options) {
+        // [1165] lazy-connect:core prepare-task 铸 env 不显式 connect(k8s 道同前提)——首用自动建连;
+        // caller 的 abortSignal 覆盖建连等待段(pre-abort 与等待中 abort 都即时退出)。
         const ready = await this.ensureConnected(options?.abortSignal);
         if (!ready.ok)
             return ready;
@@ -217,6 +279,10 @@ 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) => {
+            // D2: bounded rolling-TAIL (core's RollingTailBuffer) so a model-driven `yes`/`cat big` can't OOM the
+            // durable worker — keep only the last 8MB (tail = errors+exit) + a dropped-byte marker, O(maxBytes) memory.
+            // SAFE: this is the model-facing TEXT exec path only; readBinaryFile uses SFTP (sftp.readFile), a separate
+            // byte-exact path that NEVER flows through these buffers.
             const outBuf = new RollingTailBuffer();
             const errBuf = new RollingTailBuffer();
             let settled = false;
@@ -229,14 +295,18 @@ export class RemoteSshExecutionEnv {
                 options?.abortSignal?.removeEventListener("abort", onAbort);
                 conn.removeListener("close", onConnClose);
                 try {
-                    streamRef?.close();
+                    streamRef?.close(); // timeout/abort: close the channel so the remote command stops (council #1). No-op if already closed.
                 }
                 catch {
+                    /* noop */
                 }
                 resolve(r);
             };
             const timer = setTimeout(() => finish({ ok: false, error: new ExecutionError("timeout", `ssh exec exceeded ${timeoutMs}ms (provider/command hang)`) }), timeoutMs);
             const onAbort = () => finish({ ok: false, error: new ExecutionError("aborted", "ssh exec aborted") });
+            // Transport mapping: the TCP/SSH transport dying mid-command must NOT look like success or a vague
+            // failure. Typed "transport_lost" since core 1.89 (outcome UNKNOWN — reconnect, then retry
+            // only per the op's idempotency); the close-without-exit-status path below catches the same condition.
             const onConnClose = () => finish({ ok: false, error: new ExecutionError("transport_lost", "ssh transport lost mid-command (connection closed before exit status) — reconnect + retry per idempotency") });
             conn.once("close", onConnClose);
             if (options?.abortSignal) {
@@ -251,18 +321,21 @@ export class RemoteSshExecutionEnv {
                 streamRef = stream;
                 if (settled) {
                     try {
-                        stream.close();
+                        stream.close(); // already timed out/aborted before the exec callback fired → don't leak the channel
                     }
                     catch {
+                        /* noop */
                     }
                     return;
                 }
                 stream
                     .on("data", (d) => {
-                    outBuf.push(d);
+                    outBuf.push(d); // streaming callback still gets the full chunk; only the buffered return value is bounded
                     options?.onStdout?.(d.toString());
                 })
                     .on("close", (code, signal) => {
+                    // code==null without a kill signal = the channel died without delivering an exit status (transport drop),
+                    // NOT a successful exit — was silently mapped to exitCode 0 before ([R78]#1).
                     if (code == null && !signal) {
                         return finish({ ok: false, error: new ExecutionError("transport_lost", "ssh channel closed without exit status (transport lost / connection dropped)") });
                     }
@@ -277,8 +350,9 @@ export class RemoteSshExecutionEnv {
             });
         });
     }
+    // ─────────────────────────────── streaming exec ───────────────────────────────
     async *execStream(command, options) {
-        const ready = await this.ensureConnected(options?.signal);
+        const ready = await this.ensureConnected(options?.signal); // [1165] 同 exec:首用自动建连(等待可中止)
         if (!ready.ok)
             throw new RemoteExecutionError(ready.error.code === "aborted" ? "aborted" : "connect_failed", ready.error.message, ready.error);
         const conn = this.conn;
@@ -299,7 +373,9 @@ export class RemoteSshExecutionEnv {
         let streamRef;
         let onAbort;
         let paused = false;
-        let done = false;
+        let done = false; // set in teardown; a conn.exec callback that fires AFTER the consumer cancelled must close its late stream
+        // [R78]#1: the SSH transport dying mid-stream is a typed, retryable condition — map to "transport_lost"
+        // (in the upper layer's retry allowlist) instead of a silent finish or "unknown".
         const onConnClose = () => {
             if (!finished) {
                 failure = failure ?? new RemoteExecutionError("transport_lost", "ssh transport lost mid-stream (connection closed) — reconnect + retry per idempotency");
@@ -309,6 +385,8 @@ export class RemoteSshExecutionEnv {
         };
         conn.once("close", onConnClose);
         const teardown = () => {
+            // runs on EVERY exit path (normal end, idle-timeout/failure throw, AND consumer early-break via the generator's
+            // .return()): drop the abort listener (council #5) + close the channel (council #2 idle-timeout leak).
             done = true;
             conn.removeListener("close", onConnClose);
             if (onAbort) {
@@ -319,6 +397,7 @@ export class RemoteSshExecutionEnv {
                 streamRef?.close();
             }
             catch {
+                /* noop */
             }
         };
         const full = this.withCwdEnv(command, options?.cwd, options?.env);
@@ -332,9 +411,10 @@ export class RemoteSshExecutionEnv {
             streamRef = stream;
             if (done) {
                 try {
-                    stream.close();
+                    stream.close(); // consumer already cancelled (.return()/throw) before this callback ran → close the late channel (council #3)
                 }
                 catch {
+                    /* noop */
                 }
                 return;
             }
@@ -353,7 +433,7 @@ export class RemoteSshExecutionEnv {
                 lastChunk = Date.now();
                 queue.push(chunk);
                 if (queue.length >= 512 && !paused) {
-                    paused = true;
+                    paused = true; // backpressure: stop a fast producer from growing the queue unbounded (council design #1)
                     stream.pause();
                 }
                 signalReady();
@@ -362,6 +442,7 @@ export class RemoteSshExecutionEnv {
                 .on("data", (d) => enqueue({ type: "stdout", data: d.toString() }))
                 .on("close", (code, signal) => {
                 if (code == null && !signal && !failure) {
+                    // channel died without an exit status (transport drop) — typed retryable, not a fake exit 0 ([R78]#1)
                     failure = new RemoteExecutionError("transport_lost", "ssh channel closed without exit status (transport lost)");
                 }
                 exitCode = code ?? 0;
@@ -382,6 +463,7 @@ export class RemoteSshExecutionEnv {
                     throw failure;
                 if (finished)
                     break;
+                // idle/liveness bound: no chunk within readTimeoutMs → typed timeout (unreachable host)
                 const waitMs = idleMs ? Math.max(1, idleMs - (Date.now() - lastChunk)) : 30_000;
                 await new Promise((r) => {
                     wake = r;
@@ -398,8 +480,11 @@ export class RemoteSshExecutionEnv {
             teardown();
         }
     }
+    // ─────────────────────────────── FileSystem (sftp + shell hybrid) ───────────────────────────────
     async sftp(abortSignal) {
-        const ready = await this.ensureConnected(abortSignal);
+        const ready = await this.ensureConnected(abortSignal); // [1165] fs 面同享懒连接(scratchpad mkdir 是 POC 实红点)
+        // 四轮复审:取消跨 sftp 边界保码——aborted 直铸 FileError("aborted")(fileError() 对 FileError 原样
+        // 放行),不得降级成 "unknown" 触发上游误重试。
         if (!ready.ok)
             return Promise.reject(ready.error.code === "aborted" ? new FileError("aborted", ready.error.message) : new Error(ready.error.message));
         if (!this.conn)
@@ -445,9 +530,14 @@ export class RemoteSshExecutionEnv {
     }
     async writeFile(p, content, abortSignal) {
         const abs = this.resolve(p);
+        // sftp.writeFile does NOT create parent dirs → mkdir -p the parent first (parity with E2B's auto-create).
         const dir = path.posix.dirname(abs);
         if (dir && dir !== "." && dir !== "/") {
             const mk = await this.exec(`mkdir -p -- ${shellQuote(dir)}`, { abortSignal });
+            // 🔴 `!mk.ok` 也必须 fail-closed(2026-07-25 补):原来只看 `exitCode !== 0`,于是 **exec 本身失败**
+            // (设备/连接在这一拍掉线 ⇒ `transport_lost` / `shell_unavailable`)被整条吞掉,后面照样推载荷,
+            // 而整个 `writeFile` 返回 **ok:true** —— 调用方看到的成功与真实故障点完全脱节。同族的
+            // local-docker / k8s 用的正是 `if (!mk.ok) return`,这两条腿是漏的。
             if (!mk.ok)
                 return { ok: false, error: fileErrorFromExec(mk.error, dir) };
             if (mk.value.exitCode !== 0)
@@ -496,7 +586,7 @@ export class RemoteSshExecutionEnv {
             const sftp = await this.sftp(abortSignal);
             const entries = await new Promise((resolve, reject) => sftp.readdir(abs, (err, list) => (err ? reject(err) : resolve(list))));
             return ok(entries.map((e) => {
-                const a = e.attrs;
+                const a = e.attrs; // readdir gives raw Attributes (no isDirectory() helper, unlike lstat's Stats) → derive from mode bits
                 return { name: e.filename, path: path.posix.join(abs, e.filename), kind: kindFromMode(a.mode), size: a.size ?? 0, mtimeMs: (a.mtime ?? 0) * 1000 };
             }));
         }
@@ -504,12 +594,13 @@ export class RemoteSshExecutionEnv {
             return { ok: false, error: this.fileError(e, abs) };
         }
     }
+    // ── design/158 B6:shell-out 文件面委托共享基座(posix-shell-fs.ts;fileInfo/listDir/exists 走 SFTP 原生,不并)──
     posixFsInst;
     get posixFs() {
         return (this.posixFsInst ??= createPosixShellFs({
             run: (cmd, abortSignal) => this.exec(cmd, { abortSignal }),
             resolve: (p) => this.resolve(p),
-            tempDir: () => null,
+            tempDir: () => null, // R5:ssh 无 workspace 概念,临时件落系统 temp(mktemp -t)
         }));
     }
     async readLink(p, abortSignal) {
@@ -538,6 +629,7 @@ export class RemoteSshExecutionEnv {
     async createTempFile(options) {
         return this.posixFs.createTempFile(options);
     }
+    // ─────────────────────────────── helpers ───────────────────────────────
     withCwdEnv(command, cwd, env) {
         const parts = [];
         const dir = cwd ?? (this.cwd !== "." ? this.cwd : undefined);
@@ -552,7 +644,7 @@ export class RemoteSshExecutionEnv {
     connErr(e) {
         const msg = e.message || String(e);
         if (e.level === "client-authentication" || /authentication|all configured authentication methods failed/i.test(msg)) {
-            return new RemoteExecutionError("auth_failed", `ssh auth failed: ${msg}`, e);
+            return new RemoteExecutionError("auth_failed", `ssh auth failed: ${msg}`, e); // permanent — not retried
         }
         if (e.level === "client-timeout" || /timed out|timeout/i.test(msg))
             return new RemoteExecutionError("timeout", `ssh connect timed out: ${msg}`, e);
@@ -574,6 +666,11 @@ export class RemoteSshExecutionEnv {
         return new FileError("unknown", msg, p);
     }
 }
+/**
+ * `ExecutionEnvFactory` for the SSH backend — one fresh (unconnected) env per task against the same host
+ * (lazy: connects on first use). Config (host/user/key) is control-plane-supplied; the Runner owns the
+ * lifetime and calls `destroy()` (= disconnect) on task end.
+ */
 export function sshExecutionEnvFactory(config) {
     return (_ctx) => new RemoteSshExecutionEnv(config);
 }

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

@@ -1,8 +1,46 @@
+/**
+ * [848] remote scratchpad(server 半场)— the REMOTE sandbox lanes' session scratchpad convention.
+ *
+ * host lane already has one (env-facts.ts ensureScratchpadDir, worker-local under localDataRoot). The remote
+ * lanes (e2b/k8s/local-docker/ssh) run their hands OFF this box, so a worker-local dir would be a lie — the
+ * convention there is a path INSIDE the sandbox: `/tmp/scratchpad/<sessionId>`. This module decorates the
+ * deployment's `executionEnvFactory` so that dir EXISTS by the time the model's first command could use it:
+ *
+ *   - 🔴 LAZY, never factory-time: e2b is a lazy-VM adapter — an exec at factory time would force-boot the
+ *     VM for every task whether or not it ever runs a command. So the `mkdir -p` rides the env's OWN first
+ *     `exec` (the original exec, NOT the wrapped one — no recursion), single-flighted via a cached PROMISE
+ *     (a boolean would let two concurrent first commands both fire the mkdir).
+ *   - Best-effort: a failed mkdir warns ONCE and the user command still runs (a scratchpad nicety must never
+ *     fail the task). The settled promise is kept — no retry — so after a failure the ADVERTISED path may not
+ *     exist; accepted (the model's write then errors like any bad path, same class as a swept host scratchpad).
+ *   - mkdir runs with the adapter's DEFAULT exec options (no cwd/env/timeout): option semantics differ per
+ *     adapter and the command is trivial.
+ *
+ * Lanes: e2b/k8s/local-docker = one sandbox per task; ssh = a shared persistent host, where the
+ * sessionId-scoped subdir is exactly what keeps sessions apart. adb is NOT a lane (no standard /tmp on
+ * Android); host keeps its own worker-local scratchpad — neither is wrapped (main.ts gates on
+ * {@link isRemoteScratchpadLane}).
+ *
+ * Trust: sessionId is minted by us (uuid), but it is caller-adjacent — defence in depth, the path is only
+ * built for `[A-Za-z0-9._-]+` ids ({@link remoteScratchpadDirFor}); anything else ⇒ NOT decorated (+warn),
+ * never a quoted-shell gamble. The same helper feeds the envFacts advertisement (main.ts), so the fact and
+ * the mkdir can never disagree on the path or on the validity rule.
+ */
 import type { ExecutionEnvFactory } from "@sema-agent/core";
+/** Structured logger surface (matches the service `logger`; calls optional-chained — same shape as the
+ *  worktree-isolation wrapper's). */
 export interface RemoteScratchpadLogger {
     warn?(event: string, fields?: Record<string, unknown>): void;
 }
 export declare function isRemoteScratchpadLane(provider: string | undefined): boolean;
+/** THE remote scratchpad path convention: `/tmp/scratchpad/<sessionId>` (raw id — the sandbox is already
+ *  session/task-scoped tenancy, no hash segment needed). Returns undefined for an absent/unsafe id — the
+ *  single validity rule shared by the factory decorator AND the envFacts advertisement. */
 export declare function remoteScratchpadDirFor(sessionId: string | undefined): string | undefined;
+/**
+ * Decorate a factory so each minted env lazily `mkdir -p`s its session scratchpad before its FIRST exec.
+ * The env is mutated IN PLACE (rebind `env.exec`, evictLspOnDestroy precedent) — a copy would drop the
+ * adapter's prototype methods and identity (registries key on the instance).
+ */
 export declare function withRemoteScratchpad(factory: ExecutionEnvFactory, logger?: RemoteScratchpadLogger): ExecutionEnvFactory;
 //# sourceMappingURL=remote-scratchpad.d.ts.map

package/dist/plugins/remote-scratchpad.js

@@ -1,26 +1,46 @@
+/** The remote lanes that get the in-sandbox scratchpad convention. adb (no standard /tmp) and host
+ *  (worker-local scratchpad already exists) are deliberately absent. */
 const REMOTE_SCRATCHPAD_LANES = new Set(["e2b", "k8s", "local-docker", "ssh"]);
 export function isRemoteScratchpadLane(provider) {
     return provider !== undefined && REMOTE_SCRATCHPAD_LANES.has(provider);
 }
+/** Charset gate for embedding the sessionId in a shell command. Dots allowed (unlike the host-lane segment
+ *  sanitizer, which REWRITES): here an id either passes verbatim or the feature stays off. "/" can't pass, so a
+ *  multi-segment escape can't — but the two SINGLE-segment escapes `.` (= the shared scratchpad root) and `..`
+ *  (= /tmp itself) DO match the charset and are rejected explicitly below (codex HIGH: an opaque caller-chosen
+ *  sessionId of exactly "."/".." would alias another session's root on a shared ssh host). */
 const SESSION_ID_RE = /^[A-Za-z0-9._-]+$/;
+/** THE remote scratchpad path convention: `/tmp/scratchpad/<sessionId>` (raw id — the sandbox is already
+ *  session/task-scoped tenancy, no hash segment needed). Returns undefined for an absent/unsafe id — the
+ *  single validity rule shared by the factory decorator AND the envFacts advertisement. */
 export function remoteScratchpadDirFor(sessionId) {
     if (!sessionId || sessionId === "." || sessionId === ".." || !SESSION_ID_RE.test(sessionId))
         return undefined;
     return `/tmp/scratchpad/${sessionId}`;
 }
+/**
+ * Decorate a factory so each minted env lazily `mkdir -p`s its session scratchpad before its FIRST exec.
+ * The env is mutated IN PLACE (rebind `env.exec`, evictLspOnDestroy precedent) — a copy would drop the
+ * adapter's prototype methods and identity (registries key on the instance).
+ */
 export function withRemoteScratchpad(factory, logger) {
     return async (ctx) => {
         const env = await factory(ctx);
         const dir = remoteScratchpadDirFor(ctx.sessionId);
         if (dir === undefined) {
+            // absent id (adhoc no-session spawn) = silently no scratchpad; a NON-empty id failing the charset gate
+            // is a wiring anomaly worth a warn (our ids are uuids — this should never fire outside a bug).
             if (ctx.sessionId)
                 logger?.warn?.("remote_scratchpad_skipped_unsafe_session_id", { sessionId: ctx.sessionId });
             return env;
         }
         const e = env;
         if (typeof e.exec !== "function")
-            return env;
+            return env; // probe-guard: no exec face, nothing to ride
         const origExec = e.exec.bind(e);
+        // Single-flight via a cached PROMISE (not a boolean): concurrent first commands await the SAME mkdir.
+        // The promise never rejects (failure is swallowed into the warn) and stays cached once settled — mkdir
+        // runs AT MOST once per env, success or not (best-effort posture, see file header).
         let ensured;
         const ensure = () => (ensured ??= (async () => {
             try {
@@ -37,11 +57,17 @@ export function withRemoteScratchpad(factory, logger) {
             }
         })());
         e.exec = async (command, options) => {
+            // Pre-aborted call must NOT trigger the mkdir prelude: on a lazy-VM lane the adapter's own exec guard
+            // refuses BEFORE provisioning, but our optionless mkdir would bypass that guard and force-boot a billable
+            // VM just to abort (codex M2). Mid-mkdir aborts stay coarse (the command is trivial) — accepted.
             if (options?.abortSignal?.aborted)
                 return origExec(command, options);
             await ensure();
             return origExec(command, options);
         };
+        // Background leg (codex M1): core's background path calls `spawnBackground`, NOT `exec` — a task whose FIRST
+        // command is a bg spawn must ride the SAME single-flight mkdir or its scratchpad write fails. Duck-typed (the
+        // capability is optional per hasBackgroundShell); BackgroundSpawnOptions has no abortSignal, so no pre-abort leg.
         const bgHost = e;
         if (typeof bgHost.spawnBackground === "function") {
             const origSpawn = bgHost.spawnBackground.bind(bgHost);
@@ -50,12 +76,16 @@ export function withRemoteScratchpad(factory, logger) {
                 return origSpawn(command, options);
             };
         }
+        // PAIR-REVIEW F-5:canonicalPath 腿**显式**接 ensure——core 1.351 的 prepare 期 scratchpad 实体化/
+        // additionalRoots canonicalize 走 env.canonicalPath;local-docker 的实现私径直调 docker(绕 exec 包装)
+        // → 目录未建 not_found → 围栏不 admit(广告了但 Write 恒拒,[1339] 原病残留)。e2b/ssh/k8s 此前只是
+        // **恰好**内部走 this.exec 被顺带救活(巧合承重)——此腿把六 adapter 拉到同一显式契约。
         const cpHost = e;
         if (typeof cpHost.canonicalPath === "function") {
             const origCanonical = cpHost.canonicalPath.bind(cpHost);
             cpHost.canonicalPath = async (p, abortSignal) => {
                 if (abortSignal?.aborted)
-                    return origCanonical(p, abortSignal);
+                    return origCanonical(p, abortSignal); // 同 exec 腿:预中止不强启 VM
                 await ensure();
                 return origCanonical(p, abortSignal);
             };