@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/background-agent-store-sql.js

@@ -3,28 +3,16 @@ import { pgSafeJsonStringify, pgSanitizeText } from "./pg-safe-json.js";
 import { isMysqlDupKeyError } from "./sql-errors.js";
 export const BACKGROUND_AGENT_TABLE = "background_agent";
 const SUMMARY_COLS = "handle, owner, session_scoped, session_id, parent_session_id, root_session_id, name, agent_type, status, spawned_at_ms, updated_at_ms, settled_at_ms, usage_json";
-/** put/update 共用的投影列(scope_key/handle 键列另拼;record_json 恒最后)。core 1.383([1565] 提货单)
- *  `updateIf` 的 CAS 守卫需要 `parked_checkpoint_token`/`park_claim_id` 是**专用列**——守卫条件必须在
- *  数据库层面对当前行状态原子求值,不能只靠 record_json 这个 blob(那要求先读后写,读写之间就是
- *  CAS 本要堵的竞态窗)。`writerEpoch` 不在此列:updateIf 的 guard 参数集里没有它([1565] 原文/core
- *  类型签名逐字核对过),只是 record_json 全量对象序列化里随手带上的普通字段,不需要专用列——
- *  record_json 的写法是 `json(stored)`(stored = `{...record, handle, scope, rev}` 整个对象展开),
- *  任何 record 上有的字段(含 writerEpoch)天然随之落盘/读回,无需逐字段维护投影列表。 */
 const PROJ_COLS = "scope, owner, session_scoped, session_id, parent_session_id, root_session_id, session_anchor, name, agent_type, status, spawned_at_ms, updated_at_ms, settled_at_ms, usage_json, rev, parked_checkpoint_token, park_claim_id, admitted_org_scopes, admitted_org_write_scope, record_json";
-const PROJ_N = PROJ_COLS.split(", ").length; // F5: WHERE 占位符序号从列数派生,列序变更单点同步
+const PROJ_N = PROJ_COLS.split(", ").length;
 function assertScope(record) {
     if (record.scope === undefined || record.scope === "") {
-        // core InMemory 同文案(default-deny 谓词下无 scope 行=经 fallback 面公共可读,写入即拒)
         throw new Error("BackgroundAgentStore.put: refusing a row without a scope (world-readable through the fallback)");
     }
 }
-/** stored 形归一(core put/update 语义:handle/scope/rev 以参数为准,record_json 存归一后的整行)。 */
 function storedForm(record, handle, scope, rev) {
     return { ...record, handle, scope, rev };
 }
-/** 投影参数(键列除外,与 PROJ_COLS 同序)。json 序列化器/展示文本清洗器按方言注入([1439]:PG
- *  lossy 标记,TiDB verbatim)。展示列截到列宽(#3:超长 name 不该让整行 durable 写失败——真源在
- *  record_json,摘要投影截断是诚实形)。 */
 function projParams(stored, json, text) {
     return [
         stored.scope,
@@ -44,20 +32,11 @@ function projParams(stored, json, text) {
         stored.rev,
         stored.parkedCheckpointToken ?? null,
         stored.parkClaimId ?? null,
-        // core 5.14.0 #22([2854] 提货单⑤):每条腿在 injector-ready 栅上写下自己被裁定的 org 准入结果。
-        // 🔴 三态必须区分,这是 core 契约试剂盒硬钉的那条:**缺席(undefined)≠ 空数组**。
-        //   · 字段缺席 ⇒ 列 NULL(「没有记录」)。老行免回填,读空即零准入 fail-closed。
-        //   · `[]` / `null` ⇒ 列上是 JSON "[]" / 真 NULL 写域 —— 「裁定过,结果是什么都没有」。
-        // 两列是**写侧投影**(真源恒是 record_json,`get()` 只读它)——语义上不可能漂移:缺席的键根本
-        // 不进 JSON.stringify,所以「缺席读回缺席」由真源结构保证,不靠这两列。
-        // 📌 记账(诚实清单):本仓今天**没有**读这两列的消费者;它们存在是为了让 org 治理审计能按列
-        //    查询(「哪些后台子代拿到过 org:acme 的写权」),不必全表扫 JSON。谁要接,先上黑板对表。
         stored.admittedOrgScopes !== undefined ? json(stored.admittedOrgScopes) : null,
         stored.admittedOrgWriteScope !== undefined ? stored.admittedOrgWriteScope : null,
         json(stored),
     ];
 }
-/** 摘要行 → core BackgroundAgentRowSummary(缺席键省略,core toSummary 形逐字;usage 从 usage_json)。 */
 function rowToSummary(r) {
     return {
         handle: String(r.handle),
@@ -77,11 +56,6 @@ function rowToSummary(r) {
             : {}),
     };
 }
-// 共享归因句:core 5.4.0 起上包根([2436] 请求→[2437] 兑现),值拷贝退役——同一常量,双生与
-// InMemory 语义源头彻底同源;试剂盒条目仍逐字断言它(真双库),但漂移自此在编译期就不可能发生。
-/** core reap 的 staleRunning 翻转形(逐字段照抄 InMemory,background-agent-store.js:266-272):
- *  summary **和 error** 都只在缺席时补共享归因句——error 半边 5.2.0 起就该有,双生此前只写 summary
- *  且是手写旧句(core 5.3.0 新试剂盒首跑两方言一致揪红,[2425] bg-agent B 族同源),真失败文本永不覆写。 */
 function flippedForm(live, now) {
     return {
         ...live,
@@ -93,7 +67,6 @@ function flippedForm(live, now) {
         updatedAt: now,
     };
 }
-/** terminal doomed 集合(core reap 的 maxAge + keep 两策略;rows 已按 spawnedAt DESC)。 */
 function doomedHandles(rows, now, opts) {
     const doomed = new Set();
     if (opts.maxAgeMs !== undefined) {
@@ -108,11 +81,6 @@ function doomedHandles(rows, now, opts) {
     }
     return doomed;
 }
-/** core 1.383([1565] 提货单,design/153 件3a)`updateIf` 的三个可选守卫条件——dialect-neutral 描述,
- *  各方言自行渲染成 `?`(TiDB)或 `$N`(PG)占位符。core InMemoryBackgroundAgentStore.updateIf 逐字同源
- *  (background-agent-store.js:175-187)语义:`value === null` = 该列当前**必须缺席**(SQL `IS NULL`,
- *  对应 core `live.X !== undefined` 的取反);`value` 是字符串 = 必须**字面相等**;字段整体缺席
- *  (expect.X === undefined,不在返回数组里)= 不设该条守卫,与该列当前值无关。 */
 function parkGuardConditions(expect) {
     const out = [];
     if (expect.status !== undefined)
@@ -127,38 +95,12 @@ function reapInert(opts) {
     return !opts || (opts.maxAgeMs === undefined && opts.keep === undefined && opts.staleRunningMaxAgeMs === undefined);
 }
 function limitClause(limit) {
-    // #2 病态边界与 core slice 语义对齐:Infinity=全量(无 LIMIT),NaN/-Infinity=空(LIMIT 0)
     if (limit === undefined || limit === Infinity)
         return "";
     const n = Math.floor(limit);
     return ` LIMIT ${Number.isFinite(n) ? Math.max(0, n) : 0}`;
 }
-/* ┌─ 历史:曾经的运行期 ADD COLUMN 迁移腿(已折进 CREATE,2026-07-26 clay 裁「删库重建」)──────────┐
- * 两个 ensure 曾在每次 boot 给 `background_agent` 补三列;现已全部折叠为 CREATE TABLE 里的列定义。
- * 保留由来,因为它解释了这些列**为什么存在**,以及当年为什么 TiDB 腿用探针而不是 `IF NOT EXISTS`:
- *
- * ① root_session_id(core 1.367 δ,additive):1.248 建的存量表没有这列,靠迁移补。
- * ② parked_checkpoint_token / park_claim_id(core 1.383,[1565] 提货单 / design/153 件3a,ε,additive):
- *    1.382 前建的表没有这两列。它们**必须是专用列**(不能只躺在 record_json 里)的理由见 {@link PROJ_COLS}
- *    顶注:`updateIf` 的 CAS 守卫要在数据库层面对当前行状态原子求值。
- *
- * ③ 为什么 TiDB 腿曾是 `information_schema.COLUMNS` **探针 + ALTER** 两步,而不是一条
- *    `ADD COLUMN IF NOT EXISTS`(复审 F2):**MySQL 8 没有该语法**(TiDB/MariaDB 才有),而本仓
- *    MySQL-protocol 口径要求可移植——tidb-pool.ts COLUMN_MIGRATIONS 同姿势。PG 腿则本来就用 IF NOT EXISTS。
- *    ⚠️ 这个探针姿势有一个真实缺陷([1522] LOW5,当年如实记并判定可接受):探针→ALTER **不是原子的**,
- *    多副本并发首 boot 存在竞态窗——两个副本双双探到缺列、一方 ALTER 赢、另一方 ALTER 撞
- *    「column exists」砖**当次** boot;下次 boot 探到列在即自愈。
- *    → 折叠后该窗**消失**:新库列由 CREATE TABLE 一次建全,不存在「探到缺列再补」的第二步;
- *      `CREATE TABLE IF NOT EXISTS` 本身在服务端是单条原子 DDL,并发首 boot 只有「建了」/「已存在」两态。
- *
- * ④ 语义位:当年 `root_session_id IS NULL` 兼有「pre-δ 行」一义。删库重建后**不再产生**这类行——NULL
- *    只剩「该记录没有 root 锚」一义。读侧因此**仍然可达**、一律不动:{@link rowToSummary} 的
- *    root_session_id 条件展开、listBySession 的 `root_session_id = ?` 第二臂(NULL 行恒不命中)、
- *    以及 parked 两列的 `IS NULL` 守卫({@link parkGuardConditions}:那是 core 的 CAS 语义,不是迁移遗留)。
- * └────────────────────────────────────────────────────────────────────────────────────────────┘ */
 export async function ensureTiDBBackgroundAgentSchema(pool) {
-    // VARBINARY 键列(roster F2 同案):scope/handle 的 '=' 必须是纯字节——utf8mb4_bin 仍 PAD SPACE,
-    // 'x' 与 'x ' 会同键。record_json LONGTEXT:终报快照(finalOutput/recentSteps)可超 64K TEXT。
     await pool.query(`CREATE TABLE IF NOT EXISTS ${BACKGROUND_AGENT_TABLE} (
     scope_key VARBINARY(190) NOT NULL,
     handle VARBINARY(190) NOT NULL,
@@ -195,7 +137,6 @@ export async function ensureTiDBBackgroundAgentSchema(pool) {
   ) COLLATE utf8mb4_bin`);
 }
 export async function ensurePgBackgroundAgentSchema(q) {
-    // COLLATE "C"(roster F2 双方言对齐):隔离键列的 '=' 必须字节等价。
     await q(`CREATE TABLE IF NOT EXISTS ${BACKGROUND_AGENT_TABLE} (
     scope_key VARCHAR(190) COLLATE "C" NOT NULL,
     handle VARCHAR(190) COLLATE "C" NOT NULL,
@@ -239,8 +180,6 @@ export class TiDBBackgroundAgentStore {
             await this.pool.query(`INSERT INTO ${BACKGROUND_AGENT_TABLE} (scope_key, handle, ${PROJ_COLS}) VALUES (${Array.from({ length: PROJ_N + 2 }, () => "?").join(", ")})`, [stored.scope, stored.handle, ...projParams(stored, JSON.stringify, (t) => t)]);
         }
         catch (e) {
-            // 判据属主 = `sql-errors.ts`(A-032 P1-①:旧形只认 `code`,只带 errno 的驱动错误会让
-            // `agent_record.already_exists` 这条 typed 分流腿静默失效)。
             if (isMysqlDupKeyError(e)) {
                 throw new BackgroundAgentStoreError("agent_record.already_exists", "agent record already exists");
             }
@@ -257,9 +196,6 @@ export class TiDBBackgroundAgentStore {
        WHERE scope_key = ? AND handle = ? AND rev = ?`, [...projParams(stored, JSON.stringify, (t) => t), scope, handle, expect.rev]));
         return res.affectedRows === 1;
     }
-    /** core 1.383([1565] 提货单)REQUIRED 新方法——原子守卫 CAS(claim 的 reservation/rollback/finalize
-     *  绑定字段态非仅 rev:rev 可因无关写移动而字段义已变)。语义逐字对齐 core InMemoryBackgroundAgentStore
-     *  ({@link parkGuardConditions} 顶注)。 */
     async updateIf(handle, scope, record, expect) {
         const stored = storedForm(record, handle, scope, expect.rev + 1);
         const guards = parkGuardConditions(expect);
@@ -283,18 +219,6 @@ export class TiDBBackgroundAgentStore {
         const [res] = (await this.pool.query(`DELETE FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND handle = ?${expect !== undefined ? " AND rev = ?" : ""}`, expect !== undefined ? [scope, handle, expect.rev] : [scope, handle]));
         return res.affectedRows === 1;
     }
-    /** 🔴 返回值语义 = **受影响的不同行数**,不是「翻转数 + 删除数」的和(core 1.411 起)。
-     *
-     *  core 1.411 把自己 InMemory 的 `return touched + doomed.size` 改成
-     *  `return new Set([...flippedKeys, ...doomed]).size` —— 因为一行可能在**同一轮** reap 里既被翻转
-     *  (stale running → failed)、又因为翻转后变成终态而落进 maxAge/keep 的删除集,旧写法把它算了两次。
-     *  这条被真双库对拆套件当场抓到(升 core 1.411 后 `tidb: reaped 计数: expected 4 to be 3`,core 1.404
-     *  下同文件全绿 —— A/B 判明是 core 的语义修,我们跟上)。
-     *
-     *  ⚠️ 两个引擎**机制不同但语义一致**:PG 有 `DELETE … RETURNING handle`,可以单语句拿到真被删的 handle
-     *  直接并入同一个 Set;TiDB/MySQL **没有 RETURNING**,`affectedRows` 只给数量不给身份,所以按「是否已在
-     *  翻转集里」把 doomed 拆两批删 —— 重叠那批照样真删、只是不再计数。两边都不能用「doomed.size 当删除数」
-     *  近似:并发写者(真心跳复活)会让 `status <> 'running'` 守卫少删几行,那时 doomed.size 会虚高。 */
     async reap(scope, now, opts) {
         if (reapInert(opts))
             return 0;
@@ -303,22 +227,14 @@ export class TiDBBackgroundAgentStore {
             const [stale] = (await this.pool.query(`SELECT handle, record_json FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND status = 'running' AND updated_at_ms < ?`, [scope, now - opts.staleRunningMaxAgeMs]));
             for (const row of stale) {
                 const live = JSON.parse(String(row.record_json));
-                // rev-CAS 翻转:并发写者(真心跳复活/别副本先翻)赢了就跳过不计——core 单进程无此窗,SQL 侧诚实
                 if (await this.update(String(row.handle), scope, flippedForm(live, now), { rev: live.rev }))
                     flipped.add(String(row.handle));
             }
         }
-        // core 1.382([1561] 提货单③;InMemoryBackgroundAgentStore.reap 逐字同源,background-agent-store.js:206
-        // `r.status !== "running" && r.status !== "parked"`):doomed 候选池排除 parked——parked 是非活非终态
-        // (durably suspended pending approval),`doomedHandles` 只按 spawnedAt/settledAt 判定年龄/keep 排名,
-        // 完全不看 status,所以排除必须在这条 SQL WHERE 里做到,不能指望 JS 侧再筛一次(它收到的行里根本
-        // 没带 status 字段)。
         const [term] = (await this.pool.query(`SELECT handle, spawned_at_ms, settled_at_ms FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND status <> 'running' AND status <> 'parked' ORDER BY spawned_at_ms DESC, handle DESC`, [scope]));
         const doomed = doomedHandles(term.map((r) => ({ handle: String(r.handle), spawnedAt: Number(r.spawned_at_ms), settledAt: r.settled_at_ms === null ? null : Number(r.settled_at_ms) })), now, opts);
         if (doomed.size === 0)
             return flipped.size;
-        // 去重(见方法头注):本轮已翻转过的 handle 若同时落进 doomed,删它但**不再计数**。
-        // 无 RETURNING ⇒ 拆两批发,靠「哪一批」而不是靠返回的身份来分辨。
         const alreadyCounted = [...doomed].filter((h) => flipped.has(h));
         const newlyAffected = [...doomed].filter((h) => !flipped.has(h));
         const del = async (handles) => {
@@ -327,16 +243,10 @@ export class TiDBBackgroundAgentStore {
         };
         const deletedNew = newlyAffected.length > 0 ? await del(newlyAffected) : 0;
         if (alreadyCounted.length > 0)
-            await del(alreadyCounted); // 真删,计数已由 flipped 承担
+            await del(alreadyCounted);
         return flipped.size + deletedNew;
     }
-    /** core 1.368([1516]②)可选接口成员落位(原 server 扩展 listReapScopes 更名对齐):当前持行
-     *  scope 枚举——reaper 的 per-scope 联合 reap 入口。JS 侧 sort 与 core InMemory 逐字节同序
-     *  (SQL ORDER BY 按 collation,非码元序)。 */
     async listScopes() {
-        // [1522] MED1(两路复审撞车坐实):枚举必须走 **scope_key 字节列**——utf8mb4_bin 的 VARCHAR DISTINCT
-        // 仍 PAD SPACE,尾空格近撞 scope 被塌缩成一个,塌缩掉的分区永不被 reap(行/转录无界)。键纪律
-        // 贯彻到枚举面;VARBINARY 读回 Buffer → utf8 归一。
         const [rows] = (await this.pool.query(`SELECT DISTINCT scope_key FROM ${BACKGROUND_AGENT_TABLE}`));
         return rows.map((r) => (Buffer.isBuffer(r.scope_key) ? r.scope_key.toString("utf8") : String(r.scope_key))).sort();
     }
@@ -349,8 +259,6 @@ export class PgBackgroundAgentStore {
     async put(record) {
         assertScope(record);
         const stored = storedForm(record, record.handle, record.scope, record.rev ?? 0);
-        // create-once:ON CONFLICT DO NOTHING + RETURNING——空 rows = 键已存在(PgQueryFn 无 rowCount,
-        // RETURNING 是双方言里 PG 侧的 affected 判别;错误码路径留给真障碍)。
         const { rows } = await this.q(`INSERT INTO ${BACKGROUND_AGENT_TABLE} (scope_key, handle, ${PROJ_COLS})
        VALUES (${Array.from({ length: PROJ_N + 2 }, (_, i) => `$${i + 1}`).join(", ")})
        ON CONFLICT (scope_key, handle) DO NOTHING RETURNING handle`, [stored.scope, stored.handle, ...projParams(stored, pgSafeJsonStringify, pgSanitizeText)]);
@@ -368,13 +276,11 @@ export class PgBackgroundAgentStore {
        WHERE scope_key = $${PROJ_N + 1} AND handle = $${PROJ_N + 2} AND rev = $${PROJ_N + 3} RETURNING handle`, [...projParams(stored, pgSafeJsonStringify, pgSanitizeText), scope, handle, expect.rev]);
         return rows.length === 1;
     }
-    /** core 1.383([1565] 提货单)REQUIRED 新方法(TiDB twin 同案注释)。PG 侧占位符是显式编号 `$N`
-     *  (不像 TiDB `?` 靠数组顺序)——`n` 是跑动计数器,只在真正消耗一个占位符(非 IS NULL 分支)时前增。 */
     async updateIf(handle, scope, record, expect) {
         const stored = storedForm(record, handle, scope, expect.rev + 1);
         const setParams = projParams(stored, pgSafeJsonStringify, pgSanitizeText);
         const guards = parkGuardConditions(expect);
-        let n = setParams.length + 3; // + scope_key/handle/rev,三条基础守卫已固定占用 setParams.length+1..+3
+        let n = setParams.length + 3;
         const guardSql = guards.map((g) => (g.value === null ? `${g.column} IS NULL` : `${g.column} = $${++n}`)).join(" AND ");
         const guardParams = guards.filter((g) => g.value !== null).map((g) => g.value);
         const { rows } = await this.q(`UPDATE ${BACKGROUND_AGENT_TABLE} SET ${PROJ_COLS.split(", ").map((c, i) => `${c} = $${i + 1}`).join(", ")}
@@ -395,9 +301,6 @@ export class PgBackgroundAgentStore {
         const { rows } = await this.q(`DELETE FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND handle = $2${expect !== undefined ? " AND rev = $3" : ""} RETURNING handle`, expect !== undefined ? [scope, handle, expect.rev] : [scope, handle]);
         return rows.length === 1;
     }
-    /** 返回值 = 受影响的**不同行数**(core 1.411 语义;TiDB twin 的方法头注写了完整由来 + A/B 取证)。
-     *  PG 这半有 `DELETE … RETURNING handle`,所以真被删的 handle 直接并进同一个 Set —— 不需要 TiDB 那边的
-     *  「拆两批发」变通,但两边的**结果**必须逐个相等(真双库对拆套件按 core InMemory 的计数逐字比)。 */
     async reap(scope, now, opts) {
         if (reapInert(opts))
             return 0;
@@ -410,20 +313,16 @@ export class PgBackgroundAgentStore {
                     affected.add(String(row.handle));
             }
         }
-        // core 1.382([1561] 提货单③;TiDB twin 同案注释)——doomed 候选池排除 parked。
         const { rows: term } = await this.q(`SELECT handle, spawned_at_ms, settled_at_ms FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND status <> 'running' AND status <> 'parked' ORDER BY spawned_at_ms DESC, handle DESC`, [scope]);
         const doomed = doomedHandles(term.map((r) => ({ handle: String(r.handle), spawnedAt: Number(r.spawned_at_ms), settledAt: r.settled_at_ms === null ? null : Number(r.settled_at_ms) })), now, opts);
         if (doomed.size === 0)
             return affected.size;
         const { rows: deleted } = await this.q(`DELETE FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND status <> 'running' AND status <> 'parked' AND handle IN (${[...doomed].map((_, i) => `$${i + 2}`).join(", ")}) RETURNING handle`, [scope, ...doomed]);
         for (const r of deleted)
-            affected.add(String(r.handle)); // 同一 Set ⇒ 翻转+删除的同一行只算一次
+            affected.add(String(r.handle));
         return affected.size;
     }
-    /** core 1.368 可选接口成员(TiDB twin 同案注释)。 */
     async listScopes() {
-        // [1522] MED1(TiDB twin 同案注):枚举走 COLLATE "C" 的 scope_key 键列——非确定性缺省 collation
-        // 部署下 VARCHAR DISTINCT 同构塌缩,键列字节确定。
         const { rows } = await this.q(`SELECT DISTINCT scope_key FROM ${BACKGROUND_AGENT_TABLE}`);
         return rows.map((r) => String(r.scope_key)).sort();
     }

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

@@ -1,44 +1,16 @@
-/**
- * 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 "TaskStop 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; // decoder buffered an incomplete-codepoint tail → nothing to enqueue this frame
+        return;
     const n = Buffer.byteLength(text, "utf8");
     s.chunks.push(text);
     s.pendingBytes += n;
@@ -49,21 +21,14 @@ 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"); // re-measure: the cut may add a replacement char
+        s.pendingBytes = Buffer.byteLength(s.chunks[0], "utf8");
         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 = [];
@@ -72,17 +37,6 @@ 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;
@@ -93,12 +47,9 @@ 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())
@@ -106,7 +57,6 @@ 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)
@@ -115,7 +65,7 @@ export class BackgroundShellManager {
             if (this.shells.size <= max)
                 break;
             if (e.status === "running")
-                continue; // never evict a live shell
+                continue;
             this.shells.delete(id);
             if (e.timer)
                 clearTimeout(e.timer);
@@ -125,44 +75,17 @@ 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).
-     */
-    /** #131-T0:两条注册腿共用的 BG 超时钳制。非有限值(NaN/±Infinity)当缺席回退 default——
-     *  Math.max/min 对 NaN 全塌 NaN,setTimeout(NaN) 被 Node 折成 1ms = 后台 shell 秒杀
-     *  (方向反转:想给超时变成即杀;同族判例 TASK_TIMEOUT_SEC / leader 旋钮非法值)。 */
     boundedBgTimeoutSec(timeoutSec) {
         const wanted = timeoutSec !== undefined && Number.isFinite(timeoutSec) ? timeoutSec : undefined;
-        // caps 同座防御:default/max 由各 lane 从常数×cfg 推导(k8s 腿含 cfg.timeoutMs 除法),坏输入会把
-        // NaN 带进 caps——任何一格非有限即回退安全常数(30min/24h,方向:保「有界但不即杀」,§3.6 不破)。
         const dflt = Number.isFinite(this.caps.defaultBgTimeoutSec) ? this.caps.defaultBgTimeoutSec : 1_800;
         const max = Number.isFinite(this.caps.maxBgTimeoutSec) ? this.caps.maxBgTimeoutSec : 86_400;
-        // Bounded BG timeout — never unbounded (design/103 §3.6). `maxBgTimeoutSec` is the fail-closed ceiling.
         return Math.min(Math.max(1, wanted ?? dflt), max);
     }
     adoptSync(builder, timeoutSec) {
         if (this.liveCount() >= this.caps.maxConcurrent)
-            return undefined; // refused → exec keeps the foreground
+            return undefined;
         const bgTimeoutSec = this.boundedBgTimeoutSec(timeoutSec);
-        const shellId = `bg_${++this.counter}_${randomUUID()}`; // opaque — never the provider pid (§3.8)
+        const shellId = `bg_${++this.counter}_${randomUUID()}`;
         const applyTerminal = (e, failed, exitCode) => {
             if (e.status !== "running")
                 return;
@@ -172,8 +95,6 @@ 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) => {
@@ -184,10 +105,10 @@ export class BackgroundShellManager {
         };
         let state;
         try {
-            state = builder({ onTerminal, bgTimeoutSec }); // SYNC — no await, no interleaving event
+            state = builder({ onTerminal, bgTimeoutSec });
         }
         catch {
-            return undefined; // adoption failed → exec keeps the foreground (never a dropped process)
+            return undefined;
         }
         const timer = setTimeout(() => {
             const e = this.shells.get(shellId);
@@ -204,28 +125,21 @@ 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}); TaskStop one first.`));
         }
-        const bgTimeoutSec = this.boundedBgTimeoutSec(timeoutSec); // #131-T0:与 adoptSync 同座(NaN 当缺席)
-        // Opaque brand — NOT derived from the provider job/pid (design/103 §3.8 越权红线).
+        const bgTimeoutSec = this.boundedBgTimeoutSec(timeoutSec);
         const shellId = `bg_${++this.counter}_${randomUUID()}`;
         const applyTerminal = (e, failed, exitCode) => {
             if (e.status !== "running")
-                return; // kill / timeout already classified it (terminal-latch)
+                return;
             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) => {
@@ -245,32 +159,21 @@ export class BackgroundShellManager {
             const e = this.shells.get(shellId);
             if (!e || e.status !== "running")
                 return;
-            e.status = "killed"; // BG timeout is a HARD wall → killed (design/103 §3.6)
+            e.status = "killed";
             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); // process already exited during launch
-        this.evictOldTerminal(); // bound the heap (recent terminal shells stay pollable; old ones are reaped)
+            applyTerminal(entry, pendingTerminal.failed, pendingTerminal.exitCode);
+        this.evictOldTerminal();
         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 {
@@ -279,7 +182,6 @@ 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)
@@ -287,14 +189,12 @@ 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,
@@ -312,31 +212,24 @@ 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; // 留活:不 kill、不清 timer、不出注册表
+                    continue;
                 this.shells.delete(id);
                 doomed.push(entry);
             }
         }
         else {
             doomed.push(...this.shells.values());
-            this.shells.clear(); // idempotent: a second dispose iterates nothing
+            this.shells.clear();
         }
         for (const entry of doomed) {
             try {
@@ -347,7 +240,6 @@ export class BackgroundShellManager {
                 await this.driver.disposeOne(entry.state);
             }
             catch {
-                /* best-effort; disposeBackgroundShells MUST never throw (design/103 §3.7) */
             }
         }
     }