@sema-agent/server 1.322.0 → 2.0.0

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

@@ -1,8 +1,30 @@
+/**
+ * Shared shell/path helpers for the SSH + ADB `RemoteExecutionEnv` adapters. Kept in ONE place so the
+ * security-sensitive quoting can't drift between adapters (council design/#4, #5).
+ */
 import type { FileInfo } from "@sema-agent/core";
 import type { ChildProcess } from "node:child_process";
+/**
+ * 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 declare 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 declare function armPipeDestroyGrace(child: ChildProcess): ReturnType<typeof setTimeout>;
+/** POSIX single-quote a string for safe interpolation into a remote shell command. */
 export declare function shellQuote(s: string): string;
+/** Derive FileInfo kind from POSIX st_mode bits (raw stat/readdir attrs carry no isDirectory() helper). */
 export declare function kindFromMode(mode?: number): FileInfo["kind"];
 export declare function drainNumEnvWarnings(): Array<{
     env: string;

package/dist/plugins/remote-shell.js

@@ -1,4 +1,20 @@
+/**
+ * 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 {
@@ -6,14 +22,17 @@ 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. */
 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)
@@ -22,6 +41,13 @@ 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() {
@@ -31,7 +57,7 @@ export function numEnvOr(name, def, min) {
     const raw = process.env[name] ?? "";
     const n = Math.floor(Number(raw));
     if (raw !== "" && Number.isNaN(n) && !NUM_ENV_SEEN.has(name)) {
-        NUM_ENV_SEEN.add(name);
+        NUM_ENV_SEEN.add(name); // 首登记守卫(boolEnv 同款):懒/重复读不无界增长
         NUM_ENV_WARNINGS.push({ env: name, raw });
     }
     return Math.max(min, n || def);

package/dist/plugins/resume-anchor-store-sql.d.ts

@@ -1,22 +1,50 @@
+/**
+ * Durable resume-at anchor map (E18) — SINGLE-FILE DUAL-DIALECT (design/158 A12 收编). The service-owned
+ * eventId→entryId translation: the shell holds the live E2 `eventId` (core never persists it); core's
+ * `TaskSpec.resumeAt` takes a persisted `SessionTreeEntry.id`. Keyed (session_id, event_id) so `resolve`
+ * is a PK point-lookup. `owner` is the single-DB-fleet null-safe defense-in-depth guard, the data-layer
+ * twin of the route's session-owner gate. GC'd with the session (E21 delete). The historical
+ * `TiDBResumeAnchorStore` / `PgResumeAnchorStore` class names survive as thin ctor subclasses so every
+ * consumer (store-backend.ts, the resume-anchor integration suite) is untouched.
+ *
+ * ── Dialect deltas, kept EXPLICIT (no genuinely-divergent algorithm in this pair — every method is
+ *    SQL-text-only) ──────────────────────────────────────────────────────────────────────────────────
+ *   - `?` placeholders vs `$n`
+ *   - `ON DUPLICATE KEY UPDATE … VALUES(col)` vs `ON CONFLICT (session_id, event_id) DO UPDATE SET …
+ *     EXCLUDED.col`
+ *   - null-safe owner compare: `<=>` vs `IS NOT DISTINCT FROM`
+ *   - affectedRows vs rowCount (via SqlDriver)
+ */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type SqlDriver } from "./sql-driver.js";
+/** Dual-dialect durable resume-at anchor map. See the file header for the dialect-delta ledger. */
 export declare class SqlResumeAnchorStore {
     protected readonly db: SqlDriver;
     constructor(db: SqlDriver);
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
+    /** Record/overwrite the anchor for one settled message boundary (idempotent upsert on the (session_id,event_id) PK). */
     put(sessionId: string, eventId: string, entryId: string, owner: string | null): Promise<void>;
+    /** Resolve a shell-supplied eventId → the persisted SessionTreeEntry.id; undefined = unknown anchor. */
     resolve(sessionId: string, eventId: string, owner: string | null): Promise<string | 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. */
     listBySession(sessionId: string): Promise<Array<{
         eventId: string;
         entryId: string;
         owner: string | null;
     }>>;
+    /** 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). */
     deleteBySession(sessionId: string): Promise<number>;
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class TiDBResumeAnchorStore extends SqlResumeAnchorStore {
     constructor(pool: MySqlPool);
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgResumeAnchorStore extends SqlResumeAnchorStore {
     constructor(pool: PgPool);
 }

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

@@ -1,35 +1,46 @@
 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));

package/dist/plugins/roster-store-sql.d.ts

@@ -1,7 +1,30 @@
+/**
+ * RosterStore SQL twins(agent-team S1 server 半场,[1070]① 提货单)——core `RunnerDeps.rosterStore`
+ * 的 TiDB/PG 双方言实现:具名子 agent 的持久名册(具名 spawn advisory 写入;SendMessage 活注册表
+ * miss 后咨询;v1=诚实指针 roster_only,非跨 run resume)。
+ *
+ * 语义三条([1070]① 必守,与 core roster-store.js 参考实现字节对齐):
+ *  1. resolve **查询内** filter-before-reduce:access 轴在 SQL WHERE 完成(scope 先拒 → owner 匹配 →
+ *     sessionScoped 显式位才认 session 匹配),绝不先取全集再内存过滤(跨租户行连查询结果都不进);
+ *  2. 同 `(normalizedName, owner, scope)` 域 upsert(core upsertKey 同键);
+ *  3. 写失败降级 miss 不出错答案 —— 已核 core 调用侧兜底(subagent.js record=`void …catch(()=>{})`,
+ *     resolve=try/catch),store 侧诚实 THROW 即可(绝不吞成假成功)。
+ *
+ * latest 语义:core `latestOf` 用 `>=`(同 createdAt 后遍历者赢=写入序)。SQL 无插入序 ⇒ 次序键三连
+ * `created_at_ms DESC, recorded_at_ms DESC, agent_id DESC`——第三键保**确定性**(发版复审 F3:并发
+ * spawn 可共享毫秒、多副本时钟可偏斜,无第三键的 LIMIT 1 非确定)。诚实记账:同毫秒并写时选择=
+ * agent_id 字典序最大,与 core 单进程的「后遍历者赢」可能不同——多副本本就无全序,确定性优先。
+ *
+ * normalize 私拷已回收(2026-07-19):core 公共出口落地(黑板 [1070]① 所请的 additive 导出),按
+ * 头注预案换回单行 import。⚠️ 语义仍是**存储键**:DB 行按 normalize 后的键写入——core 若改语义,
+ * 存量行查不回;test/roster-store-db-integration.test.ts 的 golden corpus 钉守这条(非私拷漂移钉,
+ * 是「core 变语义必须先过迁移裁量」的告警钉)。
+ */
 import type { Pool } from "mysql2/promise";
 import { normalizeAgentName, type RosterStore, type RosterEntry } from "@sema-agent/core";
 type RosterAccess = Parameters<RosterStore["resolve"]>[1];
 import type { PgQueryFn } from "./pg-query.js";
+/** 兼容名保留(测试/历史引用),现=core 导出直引(私拷已删)。 */
 export declare const normalizeAgentNameLocal: typeof normalizeAgentName;
 export declare const ROSTER_TABLE = "agent_roster";
 export declare function ensureTiDBRosterSchema(pool: Pool): Promise<void>;
@@ -14,6 +37,9 @@ export declare class TiDBRosterStore implements RosterStore {
     resolve(name: string, access: RosterAccess): Promise<RosterEntry | undefined>;
     list(): Promise<RosterEntry[]>;
     releaseAgent(agentId: string): Promise<void>;
+    /** [1522] MED2(server 扩展,非 core 接口;core RB-23②③ 派给部署的清理半场):TTL 清理——
+     *  task-scoped 具名 spawn 的 owner=宿主 taskId=每 run 一新行,无清理=线性无界。按 recorded_at_ms
+     *  (最后一次 upsert 触碰)删,latest 语义不受影响(活跃名恒被新 spawn 刷新)。 */
     reapOlderThan(cutoffMs: number): Promise<number>;
 }
 export declare class PgRosterStore implements RosterStore {
@@ -24,6 +50,7 @@ export declare class PgRosterStore implements RosterStore {
     resolve(name: string, access: RosterAccess): Promise<RosterEntry | undefined>;
     list(): Promise<RosterEntry[]>;
     releaseAgent(agentId: string): Promise<void>;
+    /** [1522] MED2(TiDB twin 同案注)。 */
     reapOlderThan(cutoffMs: number): Promise<number>;
 }
 export {};

package/dist/plugins/roster-store-sql.js

@@ -1,6 +1,10 @@
 import { normalizeAgentName } from "@sema-agent/core";
+/** 兼容名保留(测试/历史引用),现=core 导出直引(私拷已删)。 */
 export const normalizeAgentNameLocal = normalizeAgentName;
 export const ROSTER_TABLE = "agent_roster";
+/** 行 → RosterEntry(缺席键省略,core 形逐字;session_scoped 数值/布尔双方言归一)。
+ *  core 1.365 BREAKING:owner/scope 升类型必填——两方言 CREATE 直接建成 NOT NULL(当年的「清死行 +
+ *  MODIFY/SET NOT NULL」运行期迁移腿已折进建表,由来见两 ensure 上方顶注 ①),故此处直取不条件展开。 */
 function rowToEntry(r) {
     return {
         name: String(r.name),
@@ -15,10 +19,51 @@ function rowToEntry(r) {
         createdAt: Number(r.created_at_ms),
     };
 }
+// F2(发版复审):TiDB 表级 COLLATE utf8mb4_bin / PG 授权列 COLLATE "C"——'=' 恢复字节等价(JS 严格
+// 相等同义),大小写/重音/PAD 近撞值不再穿过谓词;真库混合大小写+尾空格案钉住。
+/** resolve 的 access 谓词(两方言同形,占位符各自)——core 1.365 A-2 终态:**default-deny 双轴**
+ *  (entryAccessible 新极性,旧「缺轴=放行」两支已删)。scope 轴:`scope = :accessScope` 硬等——行值
+ *  NULL(前代残行)或 access.scope 缺席(参数 NULL,`= NULL` 恒假)都拒 ✓。owner 轴:相等,或
+ *  sessionScoped 显式真且 owner=access.sessionId;owner NULL 行两支 `= NULL` 恒假=拒 ✓。
+ *  全部在查询内完成(语义条 1)。
+ *  ⚠️ 上面两处「行值 NULL」现在只是**推理留档**:两列自建表起 NOT NULL,行值侧 NULL 结构上不可能
+ *  (顶注 ③);仍然可达的是**参数侧** NULL —— access 缺 scope/owner 时 `= NULL` 恒假 = default-deny。 */
+// 数据列(owner/scope)仍是 VARCHAR——谓词一侧 CAST 为 BINARY 即整个比较按字节(残余过滤行数极小,
+// 无索引损耗;主过滤=VARBINARY name_key PK 前缀)。
 const RESOLVE_WHERE_TIDB = `name_key = ? AND BINARY scope = ? AND (BINARY owner = ? OR (session_scoped = 1 AND ? IS NOT NULL AND BINARY owner = ?))`;
 const RESOLVE_WHERE_PG = `name_key = $1 AND scope = $2 AND (owner = $3 OR (session_scoped = 1 AND $4::varchar IS NOT NULL AND owner = $5))`;
+// core 1.373 additive:RosterEntry.model(spawn 记录的解析后模型 id)——列投影型 store 必须显式接
+// (File/Memory 后端整对象持久化天然保住;列白名单剥键=SDK 0.0.72 中继剥键同族教训,发车复审抓获)。
 const COLS = "name, agent_id, session_id, tool_use_id, owner, scope, session_scoped, root_session_id, model, created_at_ms";
+/* ┌─ 历史:曾经的运行期迁移腿(已折进 CREATE,2026-07-26 clay 裁「删库重建」)────────────────────┐
+ * 本文件的两个 ensure 曾在每次 boot 跑三族迁移语句,现已全部折叠为 CREATE TABLE 里的列定义。
+ * 保留由来,因为它解释了这些列**为什么长这样**,以及当年为什么不能只写一条 CREATE:
+ *
+ * ① owner / scope 曾是 nullable(1.247 及更早的 `agent_roster`)。core 1.365 BREAKING(本仓
+ *    commit `1172f31`,[1509] 对表)把注册面改成 **default-deny 双轴**:缺轴行在新谓词下永不可达
+ *    (resolve 恒拒)= 死行。于是当年的 ensure 必须先 `DELETE … WHERE owner IS NULL OR scope IS NULL`
+ *    再 `MODIFY/SET … NOT NULL`——带数据的收紧遇 NULL 会**砖 boot**,清完才幂等。
+ *    ⚠️ 该迁移腿有一个真实的**滚动升级窗**(当年复审 #1 如实记):共库上仍在跑的 1.247 旧副本此后写
+ *    缺轴条目会撞 NOT NULL 约束错——core 调用侧 record 有 catch 兜底,窗内退化为该条 roster-miss、
+ *    不崩;而 DELETE→ALTER 之间旧副本恰好插入一行 NULL,会砖**当次** ALTER(boot 失败),下次 boot
+ *    再清即自愈。BREAKING 当年在 CHANGELOG 声明整队同拍升级。
+ *    → 删库重建口径下这个窗**消失**:两列自建表起即 NOT NULL,不存在「先有 NULL 行再收紧」的时刻;
+ *      那条 DELETE 也结构上删不到任何行(NOT NULL 列不可能有 NULL 值),删之无损。
+ *
+ * ② root_session_id(core 1.367 δ)/ model(core 1.373)曾靠**探针式 ADD COLUMN** 补进存量表:
+ *    先查 information_schema.COLUMNS、缺了才 ALTER。之所以不用 `ADD COLUMN IF NOT EXISTS`,是因为
+ *    MySQL 8 没有该语法(TiDB/MariaDB 才有),而本仓 MySQL-protocol 口径要求可移植
+ *    (tidb-pool.ts COLUMN_MIGRATIONS 同姿势;PG 腿则直接用 IF NOT EXISTS)。
+ *    → 新库 CREATE 已带列,探针恒 no-op,连同 ALTER 一并删。
+ *
+ * ③ 语义位:当年 `model IS NULL` 兼有「pre-1.373 行」一义。删库重建后**不再产生**这类行——NULL 只
+ *    剩「该 spawn 没记录模型」一义(RosterEntry.model 本就可选)。读侧的条件展开分支({@link rowToEntry}
+ *    里 root_session_id / model 两支)因此仍然可达,**不动**;同理 RESOLVE_WHERE_* 谓词里
+ *    「行值 NULL ⇒ `= NULL` 恒假」那一层推理只对 **参数侧** NULL(access 缺轴)仍成立,行值侧已结构不可能。
+ * └────────────────────────────────────────────────────────────────────────────────────────────┘ */
 export async function ensureTiDBRosterSchema(pool) {
+    // VARBINARY 键列(F2 终形):`utf8mb4_bin` 仍是 PAD SPACE collation——VARCHAR '=' 尾空格填充,
+    // 'x' 与 'x ' 同键/同谓词命中(真库红实测)。VARBINARY 比较=纯字节,upsert 域键与授权谓词双正。
     await pool.query(`CREATE TABLE IF NOT EXISTS ${ROSTER_TABLE} (
     name_key VARBINARY(190) NOT NULL,
     owner_key VARBINARY(190) NOT NULL,
@@ -42,6 +87,8 @@ export async function ensureTiDBRosterSchema(pool) {
   ) COLLATE utf8mb4_bin`);
 }
 export async function ensurePgRosterSchema(q) {
+    // COLLATE "C"(F2 双方言对齐):授权谓词列的 '=' 必须是字节等价——数据库缺省 collation 若非确定性/
+    // 大小写不敏感,近撞 scope/owner 会穿过 in-query access 过滤(信任边界弱化)。
     await q(`CREATE TABLE IF NOT EXISTS ${ROSTER_TABLE} (
     name_key VARCHAR(190) COLLATE "C" NOT NULL,
     owner_key VARCHAR(190) COLLATE "C" NOT NULL,
@@ -64,6 +111,7 @@ export async function ensurePgRosterSchema(q) {
   )`);
     await q(`CREATE INDEX IF NOT EXISTS idx_roster_agent ON ${ROSTER_TABLE} (agent_id)`);
 }
+/** upsert 参数序(两方言共用;core 1.365 起 owner/scope 类型必填——键列直取,与 core upsertKey 同键)。 */
 function upsertParams(entry, now) {
     return [
         normalizeAgentNameLocal(entry.name),
@@ -75,6 +123,8 @@ function upsertParams(entry, now) {
         entry.toolUseId ?? null,
         entry.owner,
         entry.scope,
+        // TINYINT(1) 归一(clay 批 2026-07-26):写入参双方言统一 0/1(PG 列已 SMALLINT,裸 boolean 参数
+        // 会在 'true'::smallint 上炸;MySQL TINYINT 本就收 0/1)。三态保留:undefined → NULL。
         entry.sessionScoped === undefined ? null : entry.sessionScoped ? 1 : 0,
         entry.rootSessionId ?? null,
         entry.model ?? null,
@@ -111,6 +161,9 @@ export class TiDBRosterStore {
     async releaseAgent(agentId) {
         await this.pool.query(`DELETE FROM ${ROSTER_TABLE} WHERE agent_id = ?`, [agentId]);
     }
+    /** [1522] MED2(server 扩展,非 core 接口;core RB-23②③ 派给部署的清理半场):TTL 清理——
+     *  task-scoped 具名 spawn 的 owner=宿主 taskId=每 run 一新行,无清理=线性无界。按 recorded_at_ms
+     *  (最后一次 upsert 触碰)删,latest 语义不受影响(活跃名恒被新 spawn 刷新)。 */
     async reapOlderThan(cutoffMs) {
         const [res] = (await this.pool.query(`DELETE FROM ${ROSTER_TABLE} WHERE recorded_at_ms < ?`, [cutoffMs]));
         return res.affectedRows;
@@ -145,6 +198,7 @@ export class PgRosterStore {
     async releaseAgent(agentId) {
         await this.q(`DELETE FROM ${ROSTER_TABLE} WHERE agent_id = $1`, [agentId]);
     }
+    /** [1522] MED2(TiDB twin 同案注)。 */
     async reapOlderThan(cutoffMs) {
         const { rows } = await this.q(`DELETE FROM ${ROSTER_TABLE} WHERE recorded_at_ms < $1 RETURNING agent_id`, [cutoffMs]);
         return rows.length;

package/dist/plugins/run-store-sql.d.ts

@@ -1,3 +1,35 @@
+/**
+ * Async run registry (S1) + replayable event log (S2) — SINGLE-FILE DUAL-DIALECT (design/158 A12 定型半场).
+ * ONE implementation, TWO dialects; the historical `TiDBRunStore` / `PgRunStore` class names survive as thin
+ * ctor subclasses so every consumer (store-backend.ts, the run/reaper/session/usage suites) is untouched.
+ *
+ * A run is the background execution of one task. `POST /v1/runs` records it `running` and returns
+ * immediately; the background driver (`src/runs.ts`) appends events here as they happen and marks the
+ * run terminal when done. Because runs + events are durable and shared, any stateless instance can
+ * report status or replay the event stream — a client can reconnect (even to a different instance)
+ * with `Last-Event-ID` and resume. The two dialects are kept in lock-step by ONE shared integration suite
+ * (test/run-store-reaper-integration.test.ts) that runs the SAME park→resume→claim scenario against BOTH
+ * real engines — the anti-drift guard.
+ *
+ * ── Dialect deltas, kept EXPLICIT (never hidden behind an abstraction) ────────────────────────────────
+ *   - `?` placeholders vs `$n` (transaction control itself is normalized by `SqlDriver`/`SqlTxConn` —
+ *     mysql2's native begin/commit/rollback vs PG's statement form; see sql-driver.ts)
+ *   - dup-key `ER_DUP_ENTRY` vs SQLSTATE `23505` (createRun's task_active claim race)
+ *   - null-safe owner compare: `<=>` (TiDB) vs `IS NOT DISTINCT FROM` (PG) — a null-owner run still matches
+ *     `owner=null` on both, single-DB-fleet defense-in-depth (see {@link requestCancel})
+ *   - multi-table DELETE: `DELETE t FROM t JOIN j …` (TiDB) vs `DELETE FROM t USING j …` (PG)
+ *   - `UPDATE t AS a SET col=…` — PG's SET columns are NOT alias-qualified (PG rejects `SET a.col`), while
+ *     TiDB's SET clause DOES qualify (`SET tr.col = …`) — see reapSuspended / failSuspendedWithExpiredCheckpoint
+ *   - JSON binding: TiDB `JSON.stringify` verbatim vs PG `pgSafeJsonStringify` + `$n::jsonb` casts
+ *   - PG-only protocol-byte defenses on plain-TEXT columns: `pgSanitizeText` on objective_preview (createRun)
+ *     and error/error_code (setTerminal) — a raw NUL would throw 22P05 and roll back the whole terminal write,
+ *     stranding the run in a live status forever (codex R12); TiDB stores these verbatim
+ *   - dynamic multi-clause builders (listRuns/listSessions): TiDB's `?` is position-agnostic so the WHERE
+ *     array is built with plain string pushes; PG's `$n` needs numbered placeholders, so those two methods
+ *     keep an EXPLICIT per-dialect branch (a shared positional-counter abstraction would hide the very
+ *     placeholder-numbering divergence this file exists to keep visible)
+ *   - schema ownership: TiDB DDL in tidb-pool.ts, PG DDL centrally in pg-pool.ts (neither store creates tables).
+ */
 import type { TaskResult, TaskStatus } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
@@ -5,13 +37,27 @@ import { type UsageRow } from "../usage-analytics.js";
 import type { RunRecord, SessionSummary, RunEvent } from "./store-contracts.js";
 import { type SqlDriver } from "./sql-driver.js";
 export type { RunRecord, SessionSummary, RunEvent } from "./store-contracts.js";
+/** Dual-dialect async run registry + event log. See the file header for the dialect-delta ledger. */
 export declare class SqlRunStore {
     protected readonly db: SqlDriver;
     constructor(db: SqlDriver);
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
+    /** mysql2 names the dup-key `ER_DUP_ENTRY`; PG raises SQLSTATE `23505`. */
     private isDupKey;
+    /** JSON column binding: TiDB stores the string verbatim; PG goes through the protocol-safe envelope
+     *  (a raw NUL byte in an event payload would otherwise throw 22P05 mid-write). */
     private json;
+    /** Run statements atomically; rolls back on failure. */
     private tx;
+    /**
+     * Create a run, but only if the session has no other active run (double-text guard).
+     *
+     * Mutual exclusion is a unique-key claim on `task_active(session_id)` — NOT a SELECT…FOR UPDATE,
+     * which on TiDB (no gap locks) would fail to serialize two concurrent createRuns when the session
+     * has no prior row. A plain INSERT either claims the session or throws a duplicate-key error (TiDB
+     * does NOT report a reliable affectedRows for `ON DUPLICATE KEY UPDATE …=…`, so we catch dup-key).
+     */
     createRun(taskId: string, sessionId: string, owner: string | null, instanceId: string, meta?: {
         jobId?: string | null;
         source?: string | null;
@@ -22,20 +68,92 @@ export declare class SqlRunStore {
         ok: false;
         activeTaskId: string;
     }>;
+    /** Request cancel of a RUNNING run (durable, cross-replica). Sets the flag the owning instance's heartbeat
+     *  tick polls; a same-replica caller additionally aborts the in-flight controller for instant effect. Only
+     *  flags a `running` row (terminal/suspended → 0 affected = no-op). Returns whether a running row was flagged.
+     *
+     *  `owner` is a single-DB-fleet defense-in-depth guard: the WHERE pins the row to the authenticated owner
+     *  (null-safe compare so a legacy null-owner run matches owner=null), so even if the HTTP owner-gate has a bug
+     *  a caller can never flip another tenant's run. Pass the run's owner (from the looked-up RunRecord). */
     requestCancel(taskId: string, owner: string | null): Promise<boolean>;
+    /** Whether a cancel has been requested for this run (polled by the owning instance's heartbeat tick).
+     *  `owner` is the single-DB-fleet null-safe owner guard (see {@link requestCancel}). */
     isCancelRequested(taskId: string, owner: string | null): Promise<boolean>;
+    /** design/80 seam #2: request PREEMPT (graceful durable yield, ≠ cancel's kill) of a RUNNING run — durable +
+     *  cross-replica. Sets the flag the owning instance's heartbeat tick polls (it then aborts its preemptSignal →
+     *  the task suspends at the next clean turn boundary, gate resource_limit/reason preempt); a same-replica caller
+     *  additionally aborts the in-flight preempt controller for instant effect. Only flags a `running` row
+     *  (terminal/suspended → 0 affected = no-op). Returns whether a running row was flagged.
+     *  `owner` is the single-DB-fleet null-safe owner guard (see {@link requestCancel}). */
     requestPreempt(taskId: string, owner: string | null): Promise<boolean>;
+    /** Whether a preempt has been requested for this run (polled by the owning instance's heartbeat tick).
+     *  `owner` is the single-DB-fleet null-safe owner guard (see {@link requestCancel}). */
     isPreemptRequested(taskId: string, owner: string | null): Promise<boolean>;
+    /** Liveness heartbeat: refresh updated_at for a still-running run, independent of events. The
+     *  running instance calls this on a timer so a long-but-alive turn (e.g. a subagent that emits no
+     *  parent events for minutes) is not mistaken for a dead instance.
+     *  `owner` is the single-DB-fleet null-safe owner guard (see {@link requestCancel}); the heartbeat is
+     *  always issued by the owning instance with the run's own owner, so this only narrows, never blocks. */
     heartbeat(taskId: string, owner: string | null): Promise<void>;
+    /** Append one event. A single INSERT — `updated_at` (liveness) is owned by `heartbeat`, so there
+     *  is no second statement to keep atomic here. */
     appendEvent(taskId: string, seq: number, type: string, data: unknown): Promise<void>;
+    /** Highest event seq for a task (0 if none). Lets a resumed leg CONTINUE the durable event log past the
+     *  suspend (core 1.70 `resumeStream`) — the suspend wrote events 1..K, the resume appends from K+1 without
+     *  colliding on the (task_id, seq) PK. */
     maxSeq(taskId: string): Promise<number>;
+    /** Mark terminal AND release the single-active-run claim atomically — if the DELETE were a separate
+     *  statement that failed, the session would stay permanently locked. [888] FIRST terminal writer wins:
+     *  the UPDATE is CAS'd POSITIVELY on the live statuses (running/suspended/needs_review) — every call site
+     *  is a settle-once flow whose backstops may double-fire (cancel × leg-throw × reaper), and an
+     *  unconditional write let the LAST racer overwrite errorCode (a `cancelled` row flipping to a generic
+     *  abort text, or vice versa). Positive form ([1.207 codex M1]): the negative NOT IN missed the
+     *  blocked/timeout terminals — a first write of those could still be overwritten. The claim DELETE stays
+     *  unconditional (idempotent; the first writer already released it). */
     setTerminal(taskId: string, status: TaskStatus, result: TaskResult | null, error: string | null): Promise<void>;
+    /**
+     * Durable F4 (design/45): a task suspended on a policy `ask`. Sets the run NON-terminal `suspended` and
+     * KEEPS the `task_active` claim — the session stays locked (no new run) until an operator resumes it to a
+     * terminal state or the reaper expires it. The token-bearing result is NOT stored (the submitter polling
+     * this row must never receive the capability token); only the status flips.
+     */
     setSuspended(taskId: string): Promise<void>;
+    /**
+     * design/80 D-B: PARK a run that paused on a REVIEW gate — a `needs_review` result (a dry-run diff review OR a
+     * pre-action `plan_review`; core assemble-result slot 8.6). Like {@link setSuspended} this is a NON-terminal park
+     * that KEEPS the `task_active` session claim (it does NOT delete it — only {@link setTerminal} does), so the
+     * resume path (`getActiveTaskId` → `markResuming`) can find + claim the row. core treats a review pause "like a
+     * suspend, an INTENTIONAL durable pause" (design/76 §2.5) — the service MUST park it the same way, else the run is
+     * terminalized + its lock released and the plan_review/dry_run_review resume can never run (it gets
+     * taskId=undefined and drives the model unprotected on an unlocked session). CAS on `running`/`needs_review`
+     * (reaper-revert guard, mirrors setSuspended). 🔴 The store SQL here is exercised by mocked unit tests only — a
+     * real-TiDB integration test of the park→resume→claim invariant is a required-before-GA TODO (the lesson from the
+     * P2 lease-SQL + this needs_review-park bug: mocked tests hide store-SQL defects).
+     */
     setNeedsReview(taskId: string): Promise<void>;
+    /**
+     * Durable F4 resume: a suspended run is being actively resumed. Flip it back to `running` (CAS — only if
+     * still suspended) and refresh liveness, so the in-flight resume is protected by the running-run heartbeat
+     * and is NOT killed by `reapSuspended` (which targets `status='suspended'` past the approval TTL). Without
+     * this the row sits at `suspended`/updated_at=suspend-time for the WHOLE resume execution, so a resume that
+     * crosses the TTL is marked `failed` mid-run and its session lock (`task_active`) is released. Returns true
+     * if it claimed the flip (false ⇒ the reaper already expired it, or it isn't suspended).
+     */
     markResuming(taskId: string): Promise<boolean>;
+    /** The active run's taskId for a session (the `task_active` claim) — lets resume find the suspended run row. */
     getActiveTaskId(sessionId: string): Promise<string | undefined>;
+    /** Shared row→record mapper — byte-identical between dialects (both drivers hand back the same column
+     *  names + comparable JS types after SqlDriver's result normalization). */
     private rowToRun;
     getRun(taskId: string): Promise<RunRecord | undefined>;
+    /** Task Trace list (S1): runs newest-first, keyset-paginated on (created_at, task_id). Optional status +
+     *  jobId filters (jobId = the work-view group, served by idx_job). Caller passes `limit+1` to detect a next
+     *  page. Cursor fields are bound as params (no SQL injection).
+     *
+     *  🔴 Genuinely-divergent BUILDER (not just SQL text): TiDB's `?` is position-agnostic, so the WHERE array is
+     *  built with plain string pushes in call order. PG's `$n` needs a NUMBERED placeholder per param, so that arm
+     *  keeps its own positional-counter closure (`p()`) — collapsing the two into one shared counter would hide
+     *  the very placeholder-numbering divergence this file exists to keep visible. */
     listRuns(opts: {
         status?: string;
         jobId?: string;
@@ -47,6 +165,12 @@ export declare class SqlRunStore {
         };
         limit: number;
     }): Promise<RunRecord[]>;
+    /** GET /v1/sessions (CC /resume picker): DISTINCT sessions newest-first by last activity, keyset-paginated on
+     *  (last_activity, session_id). Aggregates task_run by session_id — one window pass picks the latest run per
+     *  session (rn=1) for the preview/status and rolls up first/last/count. Owner-scoped when set (the per-user view).
+     *  Bounded by per-tenant data today; a denormalized session table is the optimization if it ever goes hot.
+     *
+     *  🔴 Same builder divergence as {@link listRuns} — see its header note. */
     listSessions(opts: {
         owner?: string;
         cursor?: {
@@ -56,17 +180,44 @@ export declare class SqlRunStore {
         limit: number;
         q?: string;
     }): Promise<SessionSummary[]>;
+    /** Shared row→summary mapper for listSessions (byte-identical between dialects). */
     private rowToSession;
+    /**
+     * E21 (§0.5 session delete) — purge the service-owned RUNS LEDGER for one session: task_event (the replayable
+     * event log), task_active (the single-active-run claim), and task_run (the run rows). Owner-guarded (null-safe
+     * compare, single-DB defense-in-depth, mirrors {@link requestCancel}) so even a buggy HTTP gate can't purge
+     * another tenant's runs. Idempotent — returns `{ removed }` (the count of task_run rows removed; 0 = nothing to
+     * purge). The conversation HISTORY (session_meta/session_event) is purged separately by the session store; the
+     * checkpoint/tool-result rows by their stores — this method owns only the runs-ledger tables. Done in one TX so a
+     * partial purge can't leak a task_active claim with no run row (a permanent session lock).
+     *
+     * 🔴 Active-run re-assert INSIDE the TX (adversarial-review LOW — TOCTOU): the route's pre-purge `getActiveTaskId`
+     * 409 check is a non-transactional SELECT — a concurrent createRun can claim `task_active(session_id)` in the
+     * window between that check and this purge, then have its LIVE rows deleted here. So we re-take the no-active-run
+     * invariant transactionally: `SELECT task_id FROM task_active WHERE session_id=? FOR UPDATE` at the TOP of the TX.
+     * `FOR UPDATE` serializes against createRun's unique-key INSERT on the SAME session_id (createRun either already
+     * holds the row — we see it and abort — or blocks on our lock until commit, then fails its own unique-key claim
+     * against the now-absent row). If a claim exists we return `{ active }` (the route maps it to 409) and delete
+     * NOTHING. Returns `{ removed }` on a clean purge.
+     *
+     * 🔴 The multi-table DELETEs are dialect-divergent SQL FORMS (not just placeholders): TiDB's
+     * `DELETE te FROM te JOIN tr ON …` vs PG's `DELETE FROM te USING tr WHERE …`.
+     */
     deleteBySession(sessionId: string, owner: string | null): Promise<{
         removed: number;
     } | {
         active: string;
     }>;
+    /** Per-door usage rollup (center systems-UI input): COUNT by (source,status) since a cutoff. Reads the
+     *  denormalized columns only — no JSON parsing; served by full scan bounded by created_at (small windows). */
     sourceSummary(sinceMs: number): Promise<Array<{
         source: string | null;
         status: string;
         count: number;
     }>>;
+    /** 用量扫窗(usage-analytics):按时间窗取 {owner,created_at,status,result} 四列,行内投影
+     *  stats(JSON 提取在 JS,免 SQL JSON 方言分叉);LIMIT+1 探测截断(触顶=truncated:true 诚实上抛)。
+     *  聚合在 src/usage-analytics.ts 纯函数(三后端同代码)。可选 owner 过滤=JWT 主体只看自己。 */
     usageScan(fromMs: number, toMs: number, opts?: {
         owner?: string;
         limit?: number;
@@ -74,15 +225,58 @@ export declare class SqlRunStore {
         rows: UsageRow[];
         truncated: boolean;
     }>;
+    /** Earliest retained event seq for a task (0 if none) → `retainedFrom` for /turns and the 416 boundary for
+     *  /stream (a resume point below this has been evicted past retention). */
     retainedFrom(taskId: string): Promise<number>;
+    /** Events with seq strictly greater than `afterSeq` (use 0 for the whole stream). */
     getEvents(taskId: string, afterSeq: number): Promise<RunEvent[]>;
+    /**
+     * Mark stale `running` rows as failed (best-effort recovery for runs whose instance died), then
+     * free any active-run claim whose run is no longer running (reaped here, or a terminal whose
+     * DELETE was lost). `olderThanMs` must exceed the longest expected gap between a run's events
+     * (each event refreshes `updated_at`), else a healthy slow run is wrongly reaped.
+     */
     reapStale(olderThanMs: number): Promise<number>;
+    /**
+     * Durable F4 expiry: an approval parked beyond `olderThanMs` (the approval TTL) was never answered → fail
+     * the run + RELEASE its task_active (unlock the session). Mirrors the checkpoint reaper's CAS-expire (≈ deny);
+     * idempotent across replicas. Returns count.
+     *
+     * 🔴 design/80 D-D (adversarial blocker fix): SKIPS any row whose checkpoint is STILL pending — that row is
+     * owned by a checkpoint-state-driven sweep (the SLA deny-sweep for human/irreversible_ask, or
+     * failSuspendedWithExpiredCheckpoint once the checkpoint is expired). Without this guard, this time-based
+     * UPDATE fired at the SAME instant as the deny-sweep (deadline == createdAt + ttl, both keyed on the TTL),
+     * almost always committed FIRST (it is a single UPDATE), and deleted task_active + failed the run BEFORE the
+     * deny-sweep's resumeCheckpoint ran — so resumeCheckpoint saw no task row (markResuming skipped) yet STILL ran
+     * the model on a now-unlocked session (the pending checkpoint's resolve-CAS wins), orphaning a model leg and
+     * opening a two-runs-one-session window. The NOT-EXISTS-pending guard (same shape as
+     * failSuspendedWithExpiredCheckpoint) means this only ever reaps a row whose checkpoint is already gone/expired.
+     *
+     * 🔴 Alias-qualification divergence (kept EXPLICIT, never "fixed" to match): TiDB's SET clause QUALIFIES with
+     * `tr.` (`SET tr.status = …`); PG's SET clause must NOT be alias-qualified (`SET status = …` — PG rejects
+     * `SET a.col`). Both WHERE clauses use the `tr.` alias.
+     */
     reapSuspended(olderThanMs: number): Promise<number>;
+    /**
+     * design/80 §3 inv#3 (crash-safe backstop — the run-row half of the checkpoint `terminal_at` sweep): fail a
+     * suspended run whose durable checkpoint was ALREADY EXPIRED by `reapExpired` (past its `deadline` or its
+     * absolute `terminal_at`), and release its task_active (unlock the session). Runs UNCONDITIONALLY (no
+     * approval-TTL gate), CHECKPOINT-STATE-driven not time-driven, so it aligns EXACTLY with the per-row
+     * `terminal_at` (which never falls before an operator's >30d deadline) — unlike a uniform timer, which would
+     * either be inert (gated off at APPROVAL_TIMEOUT_SEC=0) or prematurely kill a long gate. Safe against the two
+     * windows a naive predicate mis-fires on: (a) the transient suspend-write window — a run suspended before its
+     * checkpoint row exists has NO expired checkpoint, so it is not matched; (b) a re-suspended session that minted
+     * a NEW pending checkpoint — the `NOT EXISTS pending` clause excludes it. Idempotent across replicas. Returns count.
+     *
+     * Same alias-qualification divergence as {@link reapSuspended} — see its header note.
+     */
     failSuspendedWithExpiredCheckpoint(): Promise<number>;
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class TiDBRunStore extends SqlRunStore {
     constructor(pool: MySqlPool);
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgRunStore extends SqlRunStore {
     constructor(pool: PgPool);
 }