@sema-agent/server 1.322.0 → 2.0.0

package/dist/plugins/background-shell-support.d.ts

@@ -1,43 +1,109 @@
+/**
+ * design/103 — shared support for the remote (TOB) `BackgroundShellCapability` implementations.
+ *
+ * core defines the seam (`@sema-agent/core` `BackgroundShellCapability` + `hasBackgroundShell`) and ships the TOC
+ * reference (`NodeExecutionEnv`). This module centralises the **security + lifecycle red-lines** that EVERY remote
+ * adapter (E2B, kata/k8s, …) must enforce identically, so a transport author only writes the 4 transport
+ * primitives and cannot accidentally re-implement (or skip) an invariant:
+ *
+ *  - **opaque shellId** — a fresh `bg_<n>_<uuid>` brand, NEVER derived from the provider's job/pid (越权红线,
+ *    design/103 §3.8). The provider id lives only inside the driver state.
+ *  - **owned-id isolation** — `poll`/`kill` look the shellId up in THIS manager's registry; an id from another env
+ *    (or a forged one) is `not_found`, never resolved against the provider (design/103 §3.8 / interface 越权契约).
+ *  - **maxConcurrent** — counts only `running` shells (terminal entries are kept for residual polling but free their
+ *    slot, so "KillShell one first" is actionable — matches the TOC `maxConcurrent 终态占槽` review fix).
+ *  - **timeout hard wall** — a control-plane timer kills the shell and flips it to `killed` at the bounded BG
+ *    timeout (design/103 §3.6); the driver may set an additional provider-level backstop ≥ this wall.
+ *  - **dispose** — kills + cleans up EVERY shell, best-effort, MUST NOT throw, idempotent (design/103 §3.7).
+ *
+ * The two transports legitimately take different "按-id-可重读" paths (design/103 §5.2): E2B holds a resident
+ * `CommandHandle` reader feeding a control-plane tail buffer (path ②); kata/k8s buffers into pod-side files
+ * re-read by byte cursor on each poll (path ①). Both are expressed through {@link BackgroundShellDriver}.
+ */
 import { BackgroundShellError } from "@sema-agent/core";
 import type { BackgroundShellId, BackgroundPoll, BackgroundSpawnOptions, Result } from "@sema-agent/core";
 import { StringDecoder } from "node:string_decoder";
+/** Per-端 background capability bounds, surfaced as `backgroundCapabilities` on the env (design/103 §3.1/§3.6).
+ *
+ *  ⚠️ 有据不接:core 契约的 `retainBackgroundProcesses` 能力字段【有意】不在此声明(2026-07-08 定谳):
+ *  TB 的声明与兑现全在 core 自己 runtime 内闭环(sema-tb bin 进程内 TOC local env 声明,core task-registry
+ *  settle/reap 双门控读取)——service env 全程不在链上;k8s/e2b 隔离 env 拆机进程必然消亡,声明只是名义。
+ *  接单信号=「远端 TB / 常驻服务题落到 service host env」,届时切片很薄(dispose `{except}` 管道已通,
+ *  retain 只是 env 级常开白名单)。 */
 export interface BackgroundCaps {
     readonly supported: boolean;
     readonly maxConcurrent: number;
     readonly defaultBgTimeoutSec: number;
     readonly maxBgTimeoutSec: number;
 }
+/** One stream's adopt-mode drain state. `pendingBytes` = queued-undrained (≤ cap); `totalBytes` = cursor metadata. */
 export interface BgMemStream {
     chunks: string[];
     pendingBytes: number;
     totalBytes: number;
     droppedBytes: number;
+    /** Per-stream stateful UTF-8 decoder for Buffer inputs (WS frames / pipe chunks split at arbitrary byte offsets —
+     *  a multibyte codepoint straddling two chunks must NOT decode to U+FFFD; the incomplete tail rides to the next
+     *  write). Mirrors the fg-path `StringDecoder` (remote-env-k8s.ts runExec, council BUG#1). Undefined until first
+     *  Buffer feed. STRING inputs (E2B-style, already decoded by the SDK) bypass it. */
     decoder?: StringDecoder;
 }
+/** Fresh drain buffer pre-seeded with the output captured before adoption (rides the first poll). `initialDropped` =
+ *  bytes the fg segment's rolling-tail already evicted (surfaced as `truncated` on the first drain — the seed text is
+ *  RAW, so the truncation marker is NOT baked into the stream content: review LOW, avoids double-marking + accounting
+ *  pollution). */
 export declare function seedMemStream(text: string, initialDropped?: number): BgMemStream;
+/** Append a live chunk, evicting the OLDEST queued chunks beyond `cap` (counted → surfaced as `truncated`). A Buffer
+ *  goes through the per-stream StringDecoder (multibyte-safe across chunk boundaries); a string passes through. */
 export declare function feedMemStream(s: BgMemStream, d: Buffer | string, cap: number): void;
+/** Drain everything queued since the last read (a driver `read`); resets the pending queue + dropped counter. */
 export declare function drainMemStream(s: BgMemStream): {
     text: string;
     dropped: number;
 };
+/** Context handed to {@link BackgroundShellDriver.launch}. */
 export interface LaunchCtx {
+    /**
+     * Push-model terminal notification (E2B `CommandHandle.wait()` resolves/rejects): the driver invokes this exactly
+     * once when the process ends. Pull-model drivers (k8s, which discovers termination during {@link
+     * BackgroundShellDriver.read}) simply never call it and return `terminal` from `read` instead. The manager
+     * ignores either source once a shell has left `running` (kill/timeout win).
+     */
     onTerminal(failed: boolean, exitCode?: number): void;
+    /** Bounded effective BG timeout (sec) the driver MAY use as a provider-level backstop. ≥ the manager hard wall. */
     readonly bgTimeoutSec: number;
 }
+/** One poll's worth of driver output: raw increment since the driver's own cursor + head-evict accounting. */
 export interface DriverPoll {
+    /** New stdout since last read (RAW — core's `BashOutput` tool applies `filter` + display truncation). */
     stdout: string;
+    /** New stderr since last read. */
     stderr: string;
+    /** Total output bytes the process has produced from start (cursor metadata; design/103 §3.4). */
     bytesFromStart: number;
+    /** Bytes permanently lost to head-eviction before this read's cursor (0 if none). */
     bytesDroppedBeforeCursor: number;
+    /**
+     * Pull-model termination signal (k8s): the process is no longer running. `undefined` ⇒ still running / unknown.
+     * Push-model drivers (E2B) leave this `undefined` and use {@link LaunchCtx.onTerminal} instead.
+     */
     terminal?: {
         failed: boolean;
         exitCode?: number;
     };
 }
+/**
+ * Transport primitives a remote adapter implements. The driver owns its per-shell state `S` (handles, tail buffers,
+ * pod-side cursors) and the transport mechanics; the {@link BackgroundShellManager} owns all the shared invariants.
+ */
 export interface BackgroundShellDriver<S> {
+    /** Launch a detached process. Return per-shell transport state. MUST NOT block on exit. Throw `BackgroundShellError` on failure. */
     launch(command: string, options: BackgroundSpawnOptions | undefined, ctx: LaunchCtx): Promise<S>;
+    /** Read incremental output (+ maybe terminal). Safe to call repeatedly across independent poll calls. */
     read(state: S): Promise<DriverPoll>;
+    /** Transport-level kill (best-effort, idempotent — killing an already-dead process is a no-op). */
     kill(state: S): Promise<void>;
+    /** Best-effort cleanup of ONE shell's transport resources (kill + remove temp dirs/handles). Should not throw. */
     disposeOne(state: S): Promise<void>;
 }
 export declare class BackgroundShellManager<S> {
@@ -46,18 +112,50 @@ export declare class BackgroundShellManager<S> {
     private readonly shells;
     private counter;
     constructor(driver: BackgroundShellDriver<S>, caps: BackgroundCaps);
+    /** [1116] 六轮复审:destroy 端判「还有 shell 依赖 spool 文件吗」——running(驻留 keep-alive)与
+     *  terminal 残余(dispose 前仍可轮询)都算;有=env 不得整树删 spool 根(逐 shell 清理归 dispose 面)。 */
     hasShells(): boolean;
+    /** Count live shells; KillShell/timeout flip a shell out of `running` and free its slot. */
     private liveCount;
+    /** Bound heap: evict the OLDEST terminal entries (never a running one) once the registry exceeds the retention cap. */
     private evictOldTerminal;
     spawn(command: string, options?: BackgroundSpawnOptions): Promise<Result<{
         shellId: BackgroundShellId;
     }, BackgroundShellError>>;
+    /**
+     * design/116 detach (clay 排,1.81): adopt an EXTERNALLY-created RUNNING process as a background shell — the
+     * mid-flight ctrl+b path, where the process was spawned by a FOREGROUND `exec` and must move under this
+     * manager's ownership instead of being killed. The `builder` receives the same {@link LaunchCtx} a driver
+     * `launch` would (terminal notification + the bounded BG timeout it may use as a backstop) and returns the
+     * driver state the normal `read`/`kill`/`disposeOne` primitives operate on — after adoption the shell is
+     * indistinguishable from a spawned one (poll/kill/dispose/timeout wall all apply). Returns `undefined` when
+     * the live-shell limit is hit OR the builder throws: detach REFUSED, the caller keeps the process running in
+     * the foreground (core NodeExecutionEnv semantics — never a silently dropped process).
+     *
+     * 🔴 SYNCHRONOUS by contract (double-review of the first async cut, 3 confirmed findings): the builder must
+     * attach the live child's pipe listeners in the SAME synchronous tick it snapshots the seed, with NO `await`
+     * before registration — otherwise (a) output produced during an async open/mkdir window is lost, (b) file fds
+     * leak on natural exit, and (c) an exec-settle can race the async adoption and orphan a shell. A sync builder
+     * (memory-buffered, no files) closes all three: no Node data/close event can interleave a synchronous block.
+     *
+     * 🔴 builder side-effect contract (Fable-5 review #5): the catch below returns undefined WITHOUT undoing any
+     * side effects the builder already performed (listener attach, stream reroute). A builder must therefore be
+     * all-or-nothing: put every operation that can throw BEFORE the first side effect, or clean up on the throw
+     * path itself. Today's three lane builders are entirely non-throwing (listener attach + object construction).
+     */
     adoptSync(builder: (ctx: LaunchCtx) => S, timeoutSec?: number): {
         shellId: BackgroundShellId;
     } | undefined;
+    /** The shared spawn/adopt body: limit check, opaque id, terminal-latch buffering, BG-timeout hard wall. */
     private register;
     poll(shellId: BackgroundShellId): Promise<Result<BackgroundPoll, BackgroundShellError>>;
     kill(shellId: BackgroundShellId): Promise<Result<void, BackgroundShellError>>;
+    /** Kill + clean up EVERY shell. Best-effort, MUST NOT throw, idempotent (design/103 §3.7).
+     *
+     *  core `except` 契约(background-shell.d.ts:core runtask 尾调 `{except: keepAlive}`):
+     *  这些 shellId **留活**——session 驻留 persistent Monitor 的进程,其全部意义就是跨 turn 存活;run-end
+     *  全灭会留下「registry handle 活着、进程死了」的孤儿 watch。留活条目连注册表一起保留(poll/kill 继续
+     *  可用,timeout 墙钟 timer 不清=到点照杀)。无参=既有全灭行为(suspend/review 前的 dispose 不带 except)。 */
     dispose(opts?: {
         except?: readonly BackgroundShellId[];
     }): Promise<void>;

package/dist/plugins/background-shell-support.js

@@ -1,16 +1,44 @@
+/**
+ * design/103 — shared support for the remote (TOB) `BackgroundShellCapability` implementations.
+ *
+ * core defines the seam (`@sema-agent/core` `BackgroundShellCapability` + `hasBackgroundShell`) and ships the TOC
+ * reference (`NodeExecutionEnv`). This module centralises the **security + lifecycle red-lines** that EVERY remote
+ * adapter (E2B, kata/k8s, …) must enforce identically, so a transport author only writes the 4 transport
+ * primitives and cannot accidentally re-implement (or skip) an invariant:
+ *
+ *  - **opaque shellId** — a fresh `bg_<n>_<uuid>` brand, NEVER derived from the provider's job/pid (越权红线,
+ *    design/103 §3.8). The provider id lives only inside the driver state.
+ *  - **owned-id isolation** — `poll`/`kill` look the shellId up in THIS manager's registry; an id from another env
+ *    (or a forged one) is `not_found`, never resolved against the provider (design/103 §3.8 / interface 越权契约).
+ *  - **maxConcurrent** — counts only `running` shells (terminal entries are kept for residual polling but free their
+ *    slot, so "KillShell one first" is actionable — matches the TOC `maxConcurrent 终态占槽` review fix).
+ *  - **timeout hard wall** — a control-plane timer kills the shell and flips it to `killed` at the bounded BG
+ *    timeout (design/103 §3.6); the driver may set an additional provider-level backstop ≥ this wall.
+ *  - **dispose** — kills + cleans up EVERY shell, best-effort, MUST NOT throw, idempotent (design/103 §3.7).
+ *
+ * The two transports legitimately take different "按-id-可重读" paths (design/103 §5.2): E2B holds a resident
+ * `CommandHandle` reader feeding a control-plane tail buffer (path ②); kata/k8s buffers into pod-side files
+ * re-read by byte cursor on each poll (path ①). Both are expressed through {@link BackgroundShellDriver}.
+ */
 import { BackgroundShellError } from "@sema-agent/core";
 import { randomUUID } from "node:crypto";
 import { StringDecoder } from "node:string_decoder";
 const ok = (value) => ({ ok: true, value });
 const fail = (error) => ({ ok: false, error });
+/** Fresh drain buffer pre-seeded with the output captured before adoption (rides the first poll). `initialDropped` =
+ *  bytes the fg segment's rolling-tail already evicted (surfaced as `truncated` on the first drain — the seed text is
+ *  RAW, so the truncation marker is NOT baked into the stream content: review LOW, avoids double-marking + accounting
+ *  pollution). */
 export function seedMemStream(text, initialDropped = 0) {
     const n = Buffer.byteLength(text, "utf8");
     return { chunks: text ? [text] : [], pendingBytes: n, totalBytes: n, droppedBytes: initialDropped };
 }
+/** Append a live chunk, evicting the OLDEST queued chunks beyond `cap` (counted → surfaced as `truncated`). A Buffer
+ *  goes through the per-stream StringDecoder (multibyte-safe across chunk boundaries); a string passes through. */
 export function feedMemStream(s, d, cap) {
     const text = typeof d === "string" ? d : (s.decoder ??= new StringDecoder("utf8")).write(d);
     if (!text)
-        return;
+        return; // decoder buffered an incomplete-codepoint tail → nothing to enqueue this frame
     const n = Buffer.byteLength(text, "utf8");
     s.chunks.push(text);
     s.pendingBytes += n;
@@ -21,14 +49,21 @@ export function feedMemStream(s, d, cap) {
         s.pendingBytes -= db;
         s.droppedBytes += db;
     }
+    // A SINGLE chunk larger than the cap (a giant WS frame / one enormous SDK string) is not covered by the
+    // drop-oldest loop above (it never evicts the last chunk) — trim its HEAD so the retained bytes stay ~cap
+    // instead of max(cap, largestChunk) (the cap comment otherwise promised more than the
+    // code delivered). Byte-slice like RollingTailBuffer's partial head-drop: a multibyte codepoint cut at the trim
+    // point decodes to replacement char(s) at the very start of the retained tail (may exceed cap by a few bytes on
+    // re-measure) — harmless, the stream is already marked truncated.
     if (s.pendingBytes > cap && s.chunks.length === 1) {
         const only = Buffer.from(s.chunks[0], "utf8");
         const over = only.length - cap;
         s.chunks[0] = only.subarray(over).toString("utf8");
-        s.pendingBytes = Buffer.byteLength(s.chunks[0], "utf8");
+        s.pendingBytes = Buffer.byteLength(s.chunks[0], "utf8"); // re-measure: the cut may add a replacement char
         s.droppedBytes += over;
     }
 }
+/** Drain everything queued since the last read (a driver `read`); resets the pending queue + dropped counter. */
 export function drainMemStream(s) {
     const text = s.chunks.join("");
     s.chunks = [];
@@ -37,6 +72,17 @@ export function drainMemStream(s) {
     s.droppedBytes = 0;
     return { text, dropped };
 }
+/**
+ * Drives the {@link BackgroundShellCapability} contract over a {@link BackgroundShellDriver}. One instance per env
+ * (its registry == that env's owned shells), so cross-env / forged ids never resolve.
+ */
+/**
+ * Recent terminal (exited/killed/failed) shells are kept pollable for residual output until dispose (design/103),
+ * but an unbounded run that spawns thousands of short background shells would otherwise accumulate them — and each
+ * E2B entry pins an 8MB tail buffer — until the task ends (workflow MED, worker-heap bound). Cap how many terminal
+ * entries linger: evicting the OLDEST → a later poll of it is `not_found` ("already reaped"), which the BashOutput
+ * tool already handles gracefully.
+ */
 const RETAIN_TERMINAL = 32;
 export class BackgroundShellManager {
     driver;
@@ -47,9 +93,12 @@ export class BackgroundShellManager {
         this.driver = driver;
         this.caps = caps;
     }
+    /** [1116] 六轮复审:destroy 端判「还有 shell 依赖 spool 文件吗」——running(驻留 keep-alive)与
+     *  terminal 残余(dispose 前仍可轮询)都算;有=env 不得整树删 spool 根(逐 shell 清理归 dispose 面)。 */
     hasShells() {
         return this.shells.size > 0;
     }
+    /** Count live shells; KillShell/timeout flip a shell out of `running` and free its slot. */
     liveCount() {
         let n = 0;
         for (const e of this.shells.values())
@@ -57,6 +106,7 @@ export class BackgroundShellManager {
                 n++;
         return n;
     }
+    /** Bound heap: evict the OLDEST terminal entries (never a running one) once the registry exceeds the retention cap. */
     evictOldTerminal() {
         const max = this.caps.maxConcurrent + RETAIN_TERMINAL;
         if (this.shells.size <= max)
@@ -65,7 +115,7 @@ export class BackgroundShellManager {
             if (this.shells.size <= max)
                 break;
             if (e.status === "running")
-                continue;
+                continue; // never evict a live shell
             this.shells.delete(id);
             if (e.timer)
                 clearTimeout(e.timer);
@@ -75,11 +125,33 @@ export class BackgroundShellManager {
     async spawn(command, options) {
         return this.register((ctx) => this.driver.launch(command, options, ctx), options?.timeout);
     }
+    /**
+     * design/116 detach (clay 排,1.81): adopt an EXTERNALLY-created RUNNING process as a background shell — the
+     * mid-flight ctrl+b path, where the process was spawned by a FOREGROUND `exec` and must move under this
+     * manager's ownership instead of being killed. The `builder` receives the same {@link LaunchCtx} a driver
+     * `launch` would (terminal notification + the bounded BG timeout it may use as a backstop) and returns the
+     * driver state the normal `read`/`kill`/`disposeOne` primitives operate on — after adoption the shell is
+     * indistinguishable from a spawned one (poll/kill/dispose/timeout wall all apply). Returns `undefined` when
+     * the live-shell limit is hit OR the builder throws: detach REFUSED, the caller keeps the process running in
+     * the foreground (core NodeExecutionEnv semantics — never a silently dropped process).
+     *
+     * 🔴 SYNCHRONOUS by contract (double-review of the first async cut, 3 confirmed findings): the builder must
+     * attach the live child's pipe listeners in the SAME synchronous tick it snapshots the seed, with NO `await`
+     * before registration — otherwise (a) output produced during an async open/mkdir window is lost, (b) file fds
+     * leak on natural exit, and (c) an exec-settle can race the async adoption and orphan a shell. A sync builder
+     * (memory-buffered, no files) closes all three: no Node data/close event can interleave a synchronous block.
+     *
+     * 🔴 builder side-effect contract (Fable-5 review #5): the catch below returns undefined WITHOUT undoing any
+     * side effects the builder already performed (listener attach, stream reroute). A builder must therefore be
+     * all-or-nothing: put every operation that can throw BEFORE the first side effect, or clean up on the throw
+     * path itself. Today's three lane builders are entirely non-throwing (listener attach + object construction).
+     */
     adoptSync(builder, timeoutSec) {
         if (this.liveCount() >= this.caps.maxConcurrent)
-            return undefined;
+            return undefined; // refused → exec keeps the foreground
+        // Bounded BG timeout — never unbounded (design/103 §3.6). `maxBgTimeoutSec` is the fail-closed ceiling.
         const bgTimeoutSec = Math.min(Math.max(1, timeoutSec ?? this.caps.defaultBgTimeoutSec), this.caps.maxBgTimeoutSec);
-        const shellId = `bg_${++this.counter}_${randomUUID()}`;
+        const shellId = `bg_${++this.counter}_${randomUUID()}`; // opaque — never the provider pid (§3.8)
         const applyTerminal = (e, failed, exitCode) => {
             if (e.status !== "running")
                 return;
@@ -89,6 +161,8 @@ export class BackgroundShellManager {
             if (e.timer)
                 clearTimeout(e.timer);
         };
+        // terminal-latch: an already-exited adopted child fires onTerminal DURING the builder (before shells.set) —
+        // buffer it, drain after registration (else the shell lies "running" until the timeout wall).
         let entry;
         let pending;
         const onTerminal = (failed, exitCode) => {
@@ -99,10 +173,10 @@ export class BackgroundShellManager {
         };
         let state;
         try {
-            state = builder({ onTerminal, bgTimeoutSec });
+            state = builder({ onTerminal, bgTimeoutSec }); // SYNC — no await, no interleaving event
         }
         catch {
-            return undefined;
+            return undefined; // adoption failed → exec keeps the foreground (never a dropped process)
         }
         const timer = setTimeout(() => {
             const e = this.shells.get(shellId);
@@ -119,21 +193,29 @@ export class BackgroundShellManager {
         this.evictOldTerminal();
         return { shellId };
     }
+    /** The shared spawn/adopt body: limit check, opaque id, terminal-latch buffering, BG-timeout hard wall. */
     async register(launch, timeoutSec) {
         if (this.liveCount() >= this.caps.maxConcurrent) {
             return fail(new BackgroundShellError("limit_exceeded", `Too many running background shells (max ${this.caps.maxConcurrent}); KillShell one first.`));
         }
+        // Bounded BG timeout — never unbounded (design/103 §3.6). `maxBgTimeoutSec` is the fail-closed ceiling.
         const bgTimeoutSec = Math.min(Math.max(1, timeoutSec ?? this.caps.defaultBgTimeoutSec), this.caps.maxBgTimeoutSec);
+        // Opaque brand — NOT derived from the provider job/pid (design/103 §3.8 越权红线).
         const shellId = `bg_${++this.counter}_${randomUUID()}`;
         const applyTerminal = (e, failed, exitCode) => {
             if (e.status !== "running")
-                return;
+                return; // kill / timeout already classified it (terminal-latch)
             e.status = failed ? "failed" : "exited";
             if (exitCode !== undefined)
                 e.exitCode = exitCode;
             if (e.timer)
                 clearTimeout(e.timer);
         };
+        // 🔴 A FAST-exiting process can settle `handle.wait()` and fire `onTerminal` (a microtask) BEFORE this method's
+        // post-`launch` continuation registers the entry — so onTerminal MUST buffer into `pendingTerminal` when the
+        // entry isn't live yet, and the continuation drains it after `shells.set` (else the shell would lie "running"
+        // until the timeout, wedging a maxConcurrent slot). (An ADOPTED child can equally have already
+        // exited between the detach request and adoption — the same latch covers it.)
         let entry;
         let pendingTerminal;
         const onTerminal = (failed, exitCode) => {
@@ -153,21 +235,32 @@ export class BackgroundShellManager {
             const e = this.shells.get(shellId);
             if (!e || e.status !== "running")
                 return;
-            e.status = "killed";
+            e.status = "killed"; // BG timeout is a HARD wall → killed (design/103 §3.6)
             void this.driver.kill(e.state).catch(() => { });
         }, bgTimeoutSec * 1000);
         timer.unref?.();
         entry = { state, status: "running", timer };
         this.shells.set(shellId, entry);
         if (pendingTerminal)
-            applyTerminal(entry, pendingTerminal.failed, pendingTerminal.exitCode);
-        this.evictOldTerminal();
+            applyTerminal(entry, pendingTerminal.failed, pendingTerminal.exitCode); // process already exited during launch
+        this.evictOldTerminal(); // bound the heap (recent terminal shells stay pollable; old ones are reaped)
         return ok({ shellId });
     }
     async poll(shellId) {
         const entry = this.shells.get(shellId);
+        // Owned-id isolation: unknown / cross-env / forged id → not_found, never leak existence (design/103 §3.8).
         if (!entry)
             return fail(new BackgroundShellError("not_found", `Unknown background shell: ${shellId}`));
+        // 🔴 **状态快照必须在 read 之前取**(2026-07-26,一条整天间歇红的 CI 追下来的真缺陷)。
+        // push 模型的终态是**异步**落地的(host: `child.on("close") → ctx.onTerminal`;E2B: `wait()` resolve),
+        // 所以「先 read 再读 entry.status」存在这个窗口:
+        //   读完输出(尾巴还没写完)→ 进程写完尾巴并结束 → status 变终态 → 返回 `{stdout: 缺尾巴, status: 终态}`。
+        // 而 `BashOutput` 这类消费方**看到终态就停止轮询** ⇒ 那段尾巴此后没有任何人会去读 = **静默丢输出**。
+        // (单跑时窗口极窄——隔离跑 12/12 全绿;高并行负载下两个 await 之间被调度出去,窗口变宽就复现。)
+        // ⇒ 只把「read **之前**就已经是终态」或「本次 read **自己**带回 terminal」这两种情况报为终态:
+        //   前者说明这次读发生在进程结束之后(输出必然完整),后者是同一次读里的一致视图(输出与终态同源)。
+        //   终态若是在读**之后**才到的,这一拍如实报 `running` —— 消费方多轮询一拍即可拿到尾巴 + 终态。
+        //   代价:最多多一拍轮询。收益:「终态 ⇒ 输出已完整」这条消费方真正依赖的保证成立。
         const statusBeforeRead = entry.status;
         let r;
         try {
@@ -176,6 +269,7 @@ export class BackgroundShellManager {
         catch (e) {
             return fail(e instanceof BackgroundShellError ? e : new BackgroundShellError("io", e instanceof Error ? e.message : String(e), e));
         }
+        // Pull-model terminal reconciliation (k8s): apply only if not already classified by kill/timeout.
         if (r.terminal && entry.status === "running") {
             entry.status = r.terminal.failed ? "failed" : "exited";
             if (r.terminal.exitCode !== undefined)
@@ -183,12 +277,14 @@ export class BackgroundShellManager {
             if (entry.timer)
                 clearTimeout(entry.timer);
         }
+        // 见上方旁注:读之后才到的终态,本拍不报(下一拍的快照就是终态,那时输出已完整)。
         const reportTerminal = statusBeforeRead !== "running" || r.terminal !== undefined;
         const reportedStatus = reportTerminal ? entry.status : "running";
         return ok({
             stdout: r.stdout,
             stderr: r.stderr,
             status: reportedStatus,
+            // exitCode 只随终态一起报——报 running 却带 exitCode 会让消费方读出自相矛盾的一拍。
             ...(reportTerminal && entry.exitCode !== undefined ? { exitCode: entry.exitCode } : {}),
             ...(r.bytesDroppedBeforeCursor > 0 ? { truncated: true, bytesDroppedBeforeCursor: r.bytesDroppedBeforeCursor } : {}),
             bytesFromStart: r.bytesFromStart,
@@ -206,24 +302,31 @@ export class BackgroundShellManager {
                 await this.driver.kill(entry.state);
             }
             catch {
+                /* idempotent: killing an already-dead shell is a no-op success (design/103 §4.3) */
             }
         }
         return ok(undefined);
     }
+    /** Kill + clean up EVERY shell. Best-effort, MUST NOT throw, idempotent (design/103 §3.7).
+     *
+     *  core `except` 契约(background-shell.d.ts:core runtask 尾调 `{except: keepAlive}`):
+     *  这些 shellId **留活**——session 驻留 persistent Monitor 的进程,其全部意义就是跨 turn 存活;run-end
+     *  全灭会留下「registry handle 活着、进程死了」的孤儿 watch。留活条目连注册表一起保留(poll/kill 继续
+     *  可用,timeout 墙钟 timer 不清=到点照杀)。无参=既有全灭行为(suspend/review 前的 dispose 不带 except)。 */
     async dispose(opts) {
         const keep = opts?.except?.length ? new Set(opts.except) : undefined;
         const doomed = [];
         if (keep) {
             for (const [id, entry] of [...this.shells]) {
                 if (keep.has(id))
-                    continue;
+                    continue; // 留活:不 kill、不清 timer、不出注册表
                 this.shells.delete(id);
                 doomed.push(entry);
             }
         }
         else {
             doomed.push(...this.shells.values());
-            this.shells.clear();
+            this.shells.clear(); // idempotent: a second dispose iterates nothing
         }
         for (const entry of doomed) {
             try {
@@ -234,6 +337,7 @@ export class BackgroundShellManager {
                 await this.driver.disposeOne(entry.state);
             }
             catch {
+                /* best-effort; disposeBackgroundShells MUST never throw (design/103 §3.7) */
             }
         }
     }

package/dist/plugins/blob-backend.d.ts

@@ -1,26 +1,76 @@
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
+/** (a)(clay 拍 a+c,2026-07-27)tidb 方言的默认 per-blob 帽 = **6 MiB,TiDB 自己的默认
+ *  `txn-entry-size-limit`**。两堵墙真库实测(k3s8 tidb-test v7.5.1 默认配置,2026-07-27 探针):
+ *  7MiB=`entry too large`(entry 墙,默认 6291456)、31MiB=同、32MiB=`max_allowed_packet`(包墙,
+ *  64MiB ÷ ~2× 文本协议膨胀)——矮墙是 entry 的 6MiB,不是先前推测的包墙 ~31MiB。帽=诚实拒绝:
+ *  超限 blob 在 query 之前 typed 拒(消费面 HTTP 413 / capture warn 拿到可行动信息);**帽拒绝的
+ *  在默认配置下本来也落不进去 ⇒ 零回归**。调大过 entry 限/packet 的部署用 SNAPSHOT_BLOB_SQL_MAX_BYTES
+ *  放宽(两方言都生效)。**pg 方言默认不设帽**(扩展协议无这两堵墙,不人为降档)。D-1 附件战役同墙
+ *  教训:task-attachment-store.ts:19。 */
 export declare const SQL_BLOB_DEFAULT_MAX_BYTES = 6291456;
+/** typed 判别错:blob 超过 SQL 店的承载帽。判别码供店侧结果映射/HTTP 面/日志使用——绝不能与
+ *  transient 写失败混在一类(那类是可重试的 502;这类重试永远不会成功)。 */
 export declare class BlobTooLargeError extends Error {
     readonly code: "blob_too_large_for_sql";
     constructor(byteLen: number, capBytes: number);
 }
+/**
+ * The content-addressed byte store. All four methods are keyed on the sha256 `hash` of the bytes:
+ *  - putBlob: store bytes (idempotent — a repeat for the same hash is a no-op-equivalent; the SQL twin refreshes
+ *    created_at so a just-written/re-used blob is GC-grace-protected). MinIO PUTs the object AND upserts the SQL INDEX.
+ *  - getBlob: the bytes for `hash`, or undefined if absent. A TRANSIENT backend fault THROWS (so a restore/import fails
+ *    LOUD, not a silent "missing blob"); only a genuine absence / corruption is undefined.
+ *  - hasBlobs: the subset of `hashes` that already exist — a single SQL `IN(...)` over the index for BOTH backends
+ *    (migration idempotency + reap probing + the §10 import presence pre-check; cheaper than a HEAD-per-hash on MinIO).
+ *  - deleteBlobs: byte-delete the given hashes (called ONLY by the async sweep reaper). Honors the SAME created_at
+ *    grace window as the SQL backend (MinIO reads the index's created_at) — delete-in-use is impossible. Returns the
+ *    count ACTUALLY deleted (the grace-passed subset), so the sweep reports real work, not the pre-grace orphan count.
+ */
 export interface BlobBackend {
     putBlob(hash: string, bytes: Uint8Array): Promise<void>;
     getBlob(hash: string): Promise<Uint8Array | undefined>;
     hasBlobs(hashes: string[]): Promise<Set<string>>;
     deleteBlobs(hashes: string[]): Promise<number>;
 }
+/**
+ * SQL BlobBackend — the `snapshot_blob` table ops EXTRACTED VERBATIM from the tidb/pg file-snapshot stores (the
+ * created_at-refreshing upsert, the bytes SELECT, the grace-window orphan DELETE→deleteBlobs, a has via SELECT). Two
+ * dialect twins selected by `dialect`. Keeping the SQL byte-identical means the existing behaviour + the env-gated
+ * real-DB integration suite are unchanged when MinIO is unset (the DEFAULT backend the file-snapshot stores construct).
+ *
+ * NOTE deleteBlobs here is the BYTE delete ONLY — it does NOT do the `NOT IN (SELECT … snapshot_manifest)` orphan
+ * filter (that reference check stays in the file-snapshot store, which computes the orphan hash SET from the manifest
+ * and hands it here). The grace-window `created_at < cutoff` guard is RETAINED on the delete so a just-written blob
+ * that a concurrent in-flight snapshot still needs is never byte-deleted (delete-in-use is data loss; under-delete is
+ * harmless — the next sweep collects it).
+ */
 export declare class SqlBlobBackend implements BlobBackend {
     private readonly dialect;
     private readonly pool;
+    /** Effective per-blob cap: explicit ctor value wins; else tidb=SQL_BLOB_DEFAULT_MAX_BYTES, pg=uncapped. */
     private readonly capBytes;
     constructor(dialect: "tidb" | "pg", pool: MysqlPool | PgPool, maxBytes?: number);
+    /** The created_at-refreshing content-addressed upsert — VERBATIM the tidb/pg stores' `putBlobRow`. Refreshes
+     *  created_at even on a dedup hit so a re-used/just-written blob is "touched=now" and GC-grace-protected.
+     *  (a): an over-cap blob is REJECTED (typed {@link BlobTooLargeError}) BEFORE the driver ever sees the bytes —
+     *  the alternative is an inscrutable packet-limit error deep in the driver, and on the HTTP face a 502 that
+     *  invites the peer to retry a blob that can never land. */
     putBlob(hash: string, bytes: Uint8Array): Promise<void>;
+    /** The bytes for `hash` (undefined if absent) — VERBATIM the tidb/pg stores' getBlob SELECT. A pool/query error
+     *  PROPAGATES (a transient DB fault is loud, not a silent "missing blob" — parity with the MinIO backend's throw). */
     getBlob(hash: string): Promise<Uint8Array | undefined>;
+    /** The subset of `hashes` that exist — a single `blob_hash IN (...)` SELECT (idempotency / reap probe). */
     hasBlobs(hashes: string[]): Promise<Set<string>>;
+    /** Byte-delete the given hashes (the orphan SET is computed by the caller from snapshot_manifest). Retains the
+     *  grace-window guard so a just-written blob a concurrent in-flight snapshot needs is never delete-in-use — VERBATIM
+     *  the tidb/pg stores' gcOrphanBlobs delete, minus the `NOT IN (SELECT … manifest)` clause (the caller already
+     *  excluded referenced hashes). Best-effort: a delete error is swallowed (under-delete is harmless). */
     deleteBlobs(hashes: string[]): Promise<number>;
 }
+/** SHARED index op(workspace 浏览面 #3,[1894]②)—— per-blob 字节数,读 SQL INDEX 的 `byte_len`
+ *  列(sqlHasBlobs 同款单 IN 查询;MinIO 后端的 bytes-NULL 索引行同样带 byte_len,两后端同源)。
+ *  tree/file 面的 size 投影与「超限先拒后拉」都靠它——绝不为拿大小去 getBlob 整块字节。 */
 export declare function sqlBlobSizes(dialect: "tidb" | "pg", pool: MysqlPool | PgPool, hashes: string[]): Promise<Map<string, number>>;
 export interface MinioBlobBackendConfig {
     endpoint: string;
@@ -28,14 +78,38 @@ export interface MinioBlobBackendConfig {
     accessKey: string;
     secretKey: string;
     region?: string;
+    /** Key prefix for blob objects, e.g. "blobs/". Object key = keyPrefix + hash. Default "blobs/". */
     keyPrefix?: string;
+    /** Presigned-URL TTL (seconds). Default 3600 (1h) — must comfortably exceed a ~64 MiB single-PUT/GET on a slow link
+     *  (a SigV4 X-Amz-Expires bounds the WHOLE transfer from X-Amz-Date; a too-short TTL fails mid-stream). */
     presignTtlSec?: number;
+    /** 测试注入口(listObjects 分页钉用);生产缺省 global fetch。 */
     fetchImpl?: typeof fetch;
 }
+/**
+ * MinIO BlobBackend — content-addressed bytes in an S3-compatible object store, via the zero-dependency
+ * {@link presignS3Url} SigV4 generator + `fetch` (NO S3 SDK; the repo's no-SDK posture). The object key is
+ * `keyPrefix + hash` (content-addressed → idempotent PUT, dedup across snapshots is automatic).
+ *
+ * THE SQL INDEX: the bytes go to MinIO, but a `snapshot_blob` INDEX row `(blob_hash, byte_len, created_at)` with bytes
+ * NULL is kept in SQL (same pool/dialect). This is what makes the orphan-reference computation + the created_at grace
+ * window + the §10 presence pre-check work identically to the SQL backend (see the file header). hasBlobs reads the
+ * index; putBlob PUTs then upserts the index (created_at-refresh on conflict); deleteBlobs deletes the grace-passed
+ * index rows AND the matching MinIO objects (called ONLY from the async sweep reaper).
+ *
+ * INTEGRITY (security-critical): getBlob VERIFIES sha256(bytes) === hash before returning. A content-addressed store's
+ * whole safety rests on bytes-match-hash; a mismatch means corruption (network) or POISONING (a hostile object written
+ * under a hash it doesn't match) — treated as ABSENT (undefined), NEVER returning wrong bytes. This mirrors the
+ * importManifest content-address check the SQL stores already do.
+ */
 export declare class MinioBlobBackend implements BlobBackend {
     private readonly cfg;
     private readonly keyPrefix;
     private readonly ttl;
+    /** The SQL index pool+dialect, or undefined for an index-LESS backend (the migration script + the unit suite, which
+     *  exercise ONLY the object I/O — put/get/has-by-HEAD/delete — with no DB). When undefined, hasBlobs falls back to a
+     *  HEAD-per-hash probe and deleteBlobs ignores the grace window (the script is a stop-the-world copy, not the live GC
+     *  path). The file-snapshot stores ALWAYS pass the pool, so the live reference-tracking always has the index. */
     private readonly indexPool?;
     private readonly indexDialect?;
     constructor(cfg: MinioBlobBackendConfig, index?: {
@@ -44,16 +118,46 @@ export declare class MinioBlobBackend implements BlobBackend {
     });
     private objectKey;
     private presign;
+    /** PUT the bytes under the content-addressed key, THEN upsert the SQL INDEX row (bytes NULL, created_at refresh on
+     *  conflict — the SAME grace discipline as SqlBlobBackend, so a just-PUT blob an in-flight snapshot needs is touched=
+     *  now and protected). Idempotent (same hash ⇒ overwrite-with-identical-bytes + created_at bump). A non-2xx PUT throws
+     *  (an upload failure must surface — a silent drop would later read_failed on restore). The PUT happens BEFORE the
+     *  index upsert so an index row never claims a blob the object store doesn't hold (an index row with no object would
+     *  let hasBlobs report a phantom present; the reverse — an object with no index — is harmless and pruned by a bucket
+     *  lifecycle if it ever happens). NOTE no post-PUT read-back verify on the LIVE path (perf): content-addressing
+     *  catches a corrupted PUT at the next getBlob sha-check (fail-closed); the one-time migration script DOES read-back. */
     putBlob(hash: string, bytes: Uint8Array): Promise<void>;
+    /** GET the bytes for `hash`, then VERIFY content-address (sha256(bytes)===hash). THREE branches (finding 11):
+     *   - 404 → undefined (genuinely ABSENT — the file-snapshot store treats undefined as a missing blob).
+     *   - sha256 MISMATCH → undefined (corruption/poisoning; treat corrupt-as-absent, fail-CLOSED, NEVER wrong bytes).
+     *   - a NON-2xx-NON-404 (5xx/throttle) OR a network/fetch REJECT → THROW (a TRANSIENT fault must fail LOUD so the
+     *     restore/import surfaces an error, NOT silently drop a file as "missing"; the SQL backend likewise propagates a
+     *     pool error). The snapshot store's restore() wraps applyManifest so this throw becomes a {ok:false} restore_failed. */
     getBlob(hash: string): Promise<Uint8Array | undefined>;
+    /** The subset of `hashes` present — reads the SQL INDEX (cheaper than a HEAD-per-hash AND consistent with the SQL
+     *  backend). Falls back to a presigned HEAD per hash ONLY in object-only mode (no index pool: the migration / unit
+     *  path). The caller passes DISTINCT hashes (migration idempotency batch / reap orphan set / §10 presence pre-check). */
     hasBlobs(hashes: string[]): Promise<Set<string>>;
+    /** D-1 孤儿对象 GC(clay 拍 2026-07-28):列举本后端 keyPrefix 下的全部对象(ListObjectsV2 分页,
+     *  零依赖 XML 取 <Key>/<LastModified>/<NextContinuationToken>)。**server 端 sweep 专用**——presign 的
+     *  bucket-GET 列举能力绝不外发。响应非 2xx 即 throw(sweep 调用方自 catch:列举失败=本轮跳过,
+     *  绝不把「列不出来」当「没有孤儿」)。 */
     listObjects(): AsyncGenerator<{
         hash: string;
         lastModifiedMs: number;
     }>;
+    /** 单对象 HEAD 探针(复审 B-F1 的删前复查面):返回当前 LastModified(缺席=对象已不在)。
+     *  put 会 PUT 同键 ⇒ 刷新 LastModified,所以「删前再 HEAD 一次」能看见「刚刚被重新引用」的对象。 */
     headObject(hash: string): Promise<{
         lastModifiedMs: number;
     } | undefined>;
+    /** Byte-delete the given hashes — called ONLY from the async sweepOrphanBlobs reaper (NEVER the synchronous purge
+     *  path). Honors the SAME created_at grace window as the SQL backend: with an index, DELETE the grace-passed index
+     *  rows first (the index's created_at is the authoritative age — an S3 object carries no service-controlled timestamp
+     *  the backend reads), then delete the MinIO objects ONLY for those grace-passed hashes (so a just-PUT blob an
+     *  in-flight snapshot needs is NOT delete-in-use). ERROR-TOLERANT + BOUNDED: each object delete is independent (a
+     *  failure is skipped → retried next sweep), at most MINIO_OP_CONCURRENCY in flight (no FD/throttle storm). In
+     *  object-only mode (no index pool: the migration/unit cleanup path) it deletes every given hash with no grace. */
     deleteBlobs(hashes: string[]): Promise<number>;
 }
 //# sourceMappingURL=blob-backend.d.ts.map