@sema-agent/server 7.43.0 → 7.44.0

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

@@ -1,24 +1,3 @@
-/**
- * `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";
@@ -32,30 +11,16 @@ const unsupported = (op) => ({
     ok: false,
     error: new RemoteExecutionError("unsupported", `${op} is not supported on an SSH target (real machine — not snapshotable; capabilities.suspendable=false)`),
 });
-/** ssh2's ClientChannel "close" event gives the killing signal's BARE POSIX name (e.g. "KILL"), unlike Node's
- *  own `child.on("close")` which gives `NodeJS.Signals` names (e.g. "SIGKILL") — re-prefix before looking it
- *  up in the shared, authoritative signal table (host-platform.ts `signalNumber`; single pattern-home, no
- *  hand-written table here). `?? 9` matches the convention every other exec adapter uses for an unmapped name. */
 function exitCodeForSignalKill(signal) {
     return 128 + (signalNumber(`SIG${signal}`) ?? 9);
 }
 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;
@@ -81,20 +46,13 @@ 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;
@@ -112,15 +70,12 @@ 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"], // NOT auth_failed (permanent — retrying a rejected key burns budget)
+            retryableCodes: ["connect_failed", "timeout"],
             maxAttempts: this.cfg.retry.maxAttempts,
             backoffMs: (failed) => this.cfg.retry.backoffMs * failed,
         };
@@ -135,28 +90,22 @@ 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"); // 四轮复审:single-flight join(与显式 connect/reconnect 同记录)
+        const shared = this.startConnect("establish");
         let r;
         if (signal) {
-            // 可中止等待:只退出本 caller 的 await,不动共享在飞记录(其他等待者照常拿结果)。
             let onAbort;
             const aborted = new Promise((res) => {
                 onAbort = () => res("aborted");
@@ -175,8 +124,6 @@ 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")
@@ -184,7 +131,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") });
@@ -199,19 +146,15 @@ export class RemoteSshExecutionEnv {
             };
             c.on("ready", () => {
                 if (this.destroyed || epoch !== this.connEpoch) {
-                    // [1165] 三轮复审 teardown/代际竞窗:destroy 或 reconnect 之后才 ready 的旧代连接——立即断掉
-                    // 且不赋 conn(否则 sole destroy 之后留一条活连接+可执行面,或旧代顶掉新代)。
                     try {
                         c.end();
                     }
-                    catch { /* noop */ }
+                    catch { }
                     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;
@@ -224,7 +167,6 @@ export class RemoteSshExecutionEnv {
                     c.end();
                 }
                 catch {
-                    /* noop */
                 }
                 resolve({ ok: false, error: this.connErr(e) });
             });
@@ -245,29 +187,24 @@ 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++; // [1165] 在飞旧代自灭(每轮起跳查 + ready 守卫双闸)
+        this.connEpoch++;
         this.conn?.end();
         this.conn = undefined;
         this.sftpPromise = undefined;
-        return this.startConnect("replace"); // 四轮复审:发起点唯一——重连期间的 exec/sftp join 同一记录
+        return this.startConnect("replace");
     }
-    /** Close the SSH connection. Does NOT destroy the machine (real system) — idempotent, never throws. */
     async destroy() {
-        this.destroyed = true; // [1165] 懒连接不复活已拆毁的 env(fail-closed 契约保持)
-        this.connEpoch++; // 在飞连接每轮起跳查+ready 守卫自灭(handshake 余命 ≤ readyTimeout,有界)
+        this.destroyed = true;
+        this.connEpoch++;
         try {
             this.conn?.end();
         }
         catch {
-            /* best-effort */
         }
         this.conn = undefined;
         this.sftpPromise = undefined;
@@ -275,10 +212,7 @@ 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;
@@ -287,10 +221,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) => {
-            // 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;
@@ -303,18 +233,14 @@ export class RemoteSshExecutionEnv {
                 options?.abortSignal?.removeEventListener("abort", onAbort);
                 conn.removeListener("close", onConnClose);
                 try {
-                    streamRef?.close(); // timeout/abort: close the channel so the remote command stops (council #1). No-op if already closed.
+                    streamRef?.close();
                 }
                 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) {
@@ -329,30 +255,23 @@ export class RemoteSshExecutionEnv {
                 streamRef = stream;
                 if (settled) {
                     try {
-                        stream.close(); // already timed out/aborted before the exec callback fired → don't leak the channel
+                        stream.close();
                     }
                     catch {
-                        /* noop */
                     }
                     return;
                 }
                 stream
                     .on("data", (d) => {
-                    outBuf.push(d); // streaming callback still gets the full chunk; only the buffered return value is bounded
+                    outBuf.push(d);
                     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)") });
                     }
                     const out = outBuf.result();
                     const err = errBuf.result();
-                    // code==null WITH a signal = the remote command was killed by that signal — conventional 128+signo,
-                    // NOT a fake success 0 ([R78]#2; was silently mapped to exitCode 0 before this fix). The `: 1`
-                    // arm is unreachable (the transport_lost return above already covers code==null && !signal) but
-                    // keeps the type honest without a non-null assertion.
                     const exitCode = code ?? (signal ? exitCodeForSignalKill(signal) : 1);
                     finish(ok({ stdout: markTruncated(out.text, out.droppedBytes), stderr: markTruncated(err.text, err.droppedBytes), exitCode }));
                 })
@@ -363,9 +282,8 @@ export class RemoteSshExecutionEnv {
             });
         });
     }
-    // ─────────────────────────────── streaming exec ───────────────────────────────
     async *execStream(command, options) {
-        const ready = await this.ensureConnected(options?.signal); // [1165] 同 exec:首用自动建连(等待可中止)
+        const ready = await this.ensureConnected(options?.signal);
         if (!ready.ok)
             throw new RemoteExecutionError(ready.error.code === "aborted" ? "aborted" : "connect_failed", ready.error.message, ready.error);
         const conn = this.conn;
@@ -386,9 +304,7 @@ export class RemoteSshExecutionEnv {
         let streamRef;
         let onAbort;
         let paused = 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".
+        let done = false;
         const onConnClose = () => {
             if (!finished) {
                 failure = failure ?? new RemoteExecutionError("transport_lost", "ssh transport lost mid-stream (connection closed) — reconnect + retry per idempotency");
@@ -398,8 +314,6 @@ 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) {
@@ -410,7 +324,6 @@ export class RemoteSshExecutionEnv {
                 streamRef?.close();
             }
             catch {
-                /* noop */
             }
         };
         const full = this.withCwdEnv(command, options?.cwd, options?.env);
@@ -424,10 +337,9 @@ export class RemoteSshExecutionEnv {
             streamRef = stream;
             if (done) {
                 try {
-                    stream.close(); // consumer already cancelled (.return()/throw) before this callback ran → close the late channel (council #3)
+                    stream.close();
                 }
                 catch {
-                    /* noop */
                 }
                 return;
             }
@@ -446,7 +358,7 @@ export class RemoteSshExecutionEnv {
                 lastChunk = Date.now();
                 queue.push(chunk);
                 if (queue.length >= 512 && !paused) {
-                    paused = true; // backpressure: stop a fast producer from growing the queue unbounded (council design #1)
+                    paused = true;
                     stream.pause();
                 }
                 signalReady();
@@ -455,11 +367,8 @@ 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)");
                 }
-                // code==null WITH a signal = the remote command was killed by that signal — conventional 128+signo,
-                // NOT a fake success 0 ([R78]#2; was silently mapped to exitCode 0 before this fix).
                 exitCode = code ?? (signal ? exitCodeForSignalKill(signal) : 0);
                 finished = true;
                 signalReady();
@@ -478,9 +387,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;
-                // [4947] A-002.11 sibling: clear the losing timer — wake() firing first used to leave it armed.
                 let waitTimer;
                 try {
                     await new Promise((r) => {
@@ -503,11 +410,8 @@ export class RemoteSshExecutionEnv {
             teardown();
         }
     }
-    // ─────────────────────────────── FileSystem (sftp + shell hybrid) ───────────────────────────────
     async sftp(abortSignal) {
-        const ready = await this.ensureConnected(abortSignal); // [1165] fs 面同享懒连接(scratchpad mkdir 是 POC 实红点)
-        // 四轮复审:取消跨 sftp 边界保码——aborted 直铸 FileError("aborted")(fileError() 对 FileError 原样
-        // 放行),不得降级成 "unknown" 触发上游误重试。
+        const ready = await this.ensureConnected(abortSignal);
         if (!ready.ok)
             return Promise.reject(ready.error.code === "aborted" ? new FileError("aborted", ready.error.message) : new Error(ready.error.message));
         if (!this.conn)
@@ -553,14 +457,9 @@ 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)
@@ -609,7 +508,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; // readdir gives raw Attributes (no isDirectory() helper, unlike lstat's Stats) → derive from mode bits
+                const a = e.attrs;
                 return { name: e.filename, path: path.posix.join(abs, e.filename), kind: kindFromMode(a.mode), size: a.size ?? 0, mtimeMs: (a.mtime ?? 0) * 1000 };
             }));
         }
@@ -617,13 +516,12 @@ 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, // R5:ssh 无 workspace 概念,临时件落系统 temp(mktemp -t)
+            tempDir: () => null,
         }));
     }
     async readLink(p, abortSignal) {
@@ -652,7 +550,6 @@ 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);
@@ -667,7 +564,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); // permanent — not retried
+            return new RemoteExecutionError("auth_failed", `ssh auth failed: ${msg}`, e);
         }
         if (e.level === "client-timeout" || /timed out|timeout/i.test(msg))
             return new RemoteExecutionError("timeout", `ssh connect timed out: ${msg}`, e);
@@ -689,11 +586,6 @@ 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.js

@@ -1,46 +1,26 @@
-/** 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; // probe-guard: no exec face, nothing to ride
+            return env;
         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 {
@@ -57,17 +37,11 @@ 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);
@@ -76,16 +50,12 @@ 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); // 同 exec 腿:预中止不强启 VM
+                    return origCanonical(p, abortSignal);
                 await ensure();
                 return origCanonical(p, abortSignal);
             };

package/dist/plugins/remote-shell.js

@@ -1,20 +1,4 @@
-/**
- * D5 pipe-destroy grace (parity with core's vendored `EXEC_FORCE_SETTLE_GRACE_MS`, harness/env/nodejs.js):
- * after a `kill()` on an abort/timeout, the child's `close` may NEVER fire — a re-parented grandchild that
- * inherited the stdout/stderr pipe (or a D-state process) can hold those FDs open indefinitely. Our buffered
- * exec already SETTLES the promise synchronously on abort/timeout (no hang), but the dangling pipe FDs leak.
- * So after a kill we arm a short grace timer; if `close` hasn't fired by then we `destroy()` the pipes to
- * force the FDs released. Core does NOT export this const (it's a vendor-local value), so service defines its
- * own — a plain number, not a security/behavioural boundary.
- */
 export const EXEC_FORCE_SETTLE_GRACE_MS = 3000;
-/**
- * D5 helper: arm a one-shot grace timer that `destroy()`s {@link ChildProcess.stdout}/`stderr` if the child's
- * `close` never lands after a kill (a re-parented grandchild holding the pipe → dangling FD). Returns the
- * timer so the caller can {@link clearTimeout} it the moment a real `close` (or any settle) arrives — the timer
- * is `unref`'d so it can never keep the process alive on its own. This ONLY frees pipe FDs; it does NOT settle
- * any promise (the buffered exec already settled synchronously on abort/timeout — that path is unchanged).
- */
 export function armPipeDestroyGrace(child) {
     const t = setTimeout(() => {
         try {
@@ -22,18 +6,14 @@ export function armPipeDestroyGrace(child) {
             child.stderr?.destroy();
         }
         catch {
-            /* best-effort pipe teardown — never throw from a timer */
         }
     }, EXEC_FORCE_SETTLE_GRACE_MS);
     t.unref?.();
     return t;
 }
-/** POSIX single-quote a string for safe interpolation into a remote shell command (the only metacharacter
- *  inside '' is ' itself, closed/escaped/reopened). */
 export function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
-/** Derive FileInfo kind from POSIX st_mode bits (raw stat/readdir attrs carry no isDirectory() helper). */
 export function kindFromMode(mode) {
     const t = (mode ?? 0) & 0o170000;
     if (t === 0o040000)
@@ -42,13 +22,6 @@ export function kindFromMode(mode) {
         return "symlink";
     return "file";
 }
-// ── design/158 B4 交接小件:plugins 数值旋钮的 fail-loud ─────────────────────────────────────────────
-// HOST_BG_*/K8S_BG_*/E2B_* 是模块级、import 时读的常量,不走 ServiceConfig;此前手搓
-// `Math.max(min, Math.floor(Number(env ?? "")) || def)` 让非法字面量(`1mb`)静默落默认——与 config.ts
-// boolEnv 修掉的同族病。告警收本模块自带通道(不造 plugins→config 依赖边),main.ts 在 boot 诊断点
-// (logConfigDiagnostics 旁)排空——ESM import 先于 main 体执行,时序成立。
-// 语义逐字承原形:unset/"" 静默默认;显式 0 仍落默认(0 在这族旋钮上无合法语义,关功能走 *_ENABLED);
-// 合法值 floor+min 夹紧。唯一新增行为=非法字面量推一条警告。
 const NUM_ENV_WARNINGS = [];
 const NUM_ENV_SEEN = new Set();
 export function drainNumEnvWarnings() {
@@ -57,12 +30,8 @@ export function drainNumEnvWarnings() {
 export function numEnvOr(name, def, min) {
     const raw = process.env[name] ?? "";
     const n = Math.floor(Number(raw));
-    // A-067 C1-1(F2a):判据必须是 isFinite,不是 isNaN——`"Infinity"`/`"1e999"` 穿过 NaN 检查后
-    // `n || def` 取 Infinity、`Math.max(min, Infinity)` 恒 Infinity ⇒ 本函数独供的 17 个执行 lane
-    // 旋钮里,E2B_SANDBOX_MAX_MS 的消费点 `Math.min(callerDeadline, cap)`(BL-31 防挂钳)被整条击穿。
-    // 非有限=非法字面量同待遇:警告 + 落默认。
     if (raw !== "" && !Number.isFinite(n) && !NUM_ENV_SEEN.has(name)) {
-        NUM_ENV_SEEN.add(name); // 首登记守卫(boolEnv 同款):懒/重复读不无界增长
+        NUM_ENV_SEEN.add(name);
         NUM_ENV_WARNINGS.push({ env: name, raw });
     }
     return Math.max(min, (Number.isFinite(n) ? n : 0) || def);

package/dist/plugins/resume-anchor-store-sql.js

@@ -1,46 +1,35 @@
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
-/** Dual-dialect durable resume-at anchor map. See the file header for the dialect-delta ledger. */
 export class SqlResumeAnchorStore {
     db;
     constructor(db) {
         this.db = db;
     }
-    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
-    /** Record/overwrite the anchor for one settled message boundary (idempotent upsert on the (session_id,event_id) PK). */
     async put(sessionId, eventId, entryId, owner) {
         await this.db.query(this.q("INSERT INTO resume_anchor (session_id, event_id, entry_id, owner, created_at) VALUES (?,?,?,?,?) " +
             "ON DUPLICATE KEY UPDATE entry_id = VALUES(entry_id), owner = VALUES(owner)", "INSERT INTO resume_anchor (session_id, event_id, entry_id, owner, created_at) VALUES ($1,$2,$3,$4,$5) " +
             "ON CONFLICT (session_id, event_id) DO UPDATE SET entry_id = EXCLUDED.entry_id, owner = EXCLUDED.owner"), [sessionId, eventId, entryId, owner, new Date()]);
     }
-    /** Resolve a shell-supplied eventId → the persisted SessionTreeEntry.id; undefined = unknown anchor. */
     async resolve(sessionId, eventId, owner) {
         const { rows } = await this.db.query(this.q("SELECT entry_id FROM resume_anchor WHERE session_id = ? AND event_id = ? AND owner <=> ?", "SELECT entry_id FROM resume_anchor WHERE session_id = $1 AND event_id = $2 AND owner IS NOT DISTINCT FROM $3"), [sessionId, eventId, owner]);
         return rows[0] ? String(rows[0].entry_id) : undefined;
     }
-    /** 2c session-sync: ALL anchors for a session (every eventId→entryId + its owner), UNFILTERED — a cross-backend
-     *  session EXPORT bundles the whole anchor map so the importer can RE-KEY owner to the target principal (§9). The
-     *  route already proved session ownership (the export gate), so no per-row owner filter here. owner carried verbatim. */
     async listBySession(sessionId) {
         const { rows } = await this.db.query(this.q("SELECT event_id, entry_id, owner FROM resume_anchor WHERE session_id = ?", "SELECT event_id, entry_id, owner FROM resume_anchor WHERE session_id = $1"), [sessionId]);
         return rows.map((r) => ({ eventId: String(r.event_id), entryId: String(r.entry_id), owner: r.owner == null ? null : String(r.owner) }));
     }
-    /** E21 — purge ALL anchors for a session, scoped by session_id ALONE (the route proved ownership; a per-row owner
-     *  guard would orphan rows whose per-run principal diverged from the session owner). Idempotent (affected count). */
     async deleteBySession(sessionId) {
         const res = await this.db.query(this.q("DELETE FROM resume_anchor WHERE session_id = ?", "DELETE FROM resume_anchor WHERE session_id = $1"), [sessionId]);
         return res.affected;
     }
 }
-/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export class TiDBResumeAnchorStore extends SqlResumeAnchorStore {
     constructor(pool) {
         super(mysqlDriver(pool));
     }
 }
-/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export class PgResumeAnchorStore extends SqlResumeAnchorStore {
     constructor(pool) {
         super(pgDriver(pool));