@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/leader-run-store-sql.js

@@ -1,65 +1,14 @@
-/**
- * Durable **leader-run** registry — SINGLE-FILE DUAL-DIALECT (design/158 A12 定型半场;先例 =
- * `image-bake-store-sql.ts`)。#193 车4 件1(台账 P1-9;设计稿 `docs/DESIGN-193-CAR4-leader-failclosed.md`)。
- *
- * ── 为什么这张表必须存在 ────────────────────────────────────────────────────────────────────────────
- * 一次 leader run = 规划成 N 个子任务 → 起 N 个 worker 沙箱 → 真模型编码 → 合并 → **真 git push**,
- * 最长 24h。它此前的登记表是 `leader/endpoint.ts` 里的一只进程内 `Map`,于是三条缺口同源:
- *   ① 跨副本 GET 404(提交打到 A、轮询打到 B),违反仓级前提「durable state lives in an external SQL store」;
- *   ② POST 零幂等 —— 每次都铸新 uuidv7,一次网络重试 = 第二次真跑 + 可能第二次 push;
- *   ③ `fanout.ts` 的 `claim` 面全链路无人传,而它的头注称并发去重「已解决」。
- * 一张带 `idem_key UNIQUE` 的表一次解掉三条:①靠行本身,②靠 UNIQUE 的「原子赢或观察」,
- * ③ 的真属主就是 ② —— 提交幂等挡在**准入**那一刻,比在 worker 层再补一道 CAS 早得多也准得多
- * (worker 的 sessionId 是每次现铸的 `leader-<workerId>-<Date.now()>`,拿它做 CAS 键**永远不会**冲突,
- * 那道 claim 由构造即无效;详见同批对 `fanout.ts` 头注的更正)。
- *
- * ── 这是一张 DEDICATED 表,不是 `task_run` 的复用 ────────────────────────────────────────────────────
- * 与 bake 店同一条理由:`task_run` 与 `task_active`/run reaper/`GET /v1/runs` 列表 FK 式耦合,把 leader run
- * (无 session、无 spend 账、无 checkpoint)混进去 = 让非任务行漏进 reapStale/listRuns 的类别错误。
- *
- * ── 两条保留/清算裁定(分开的两件事,别混)────────────────────────────────────────────────────────
- * **① 行的保留:不建 TTL 腿。** 进程内 Map 时代那条 1h 的 `RUN_RETENTION_MS` 驱逐,目的是**给进程内存
- * 封顶**,不是保留策略。落库后这个理由消失:一行 leader run 对应一次「N 个沙箱 + 数分钟到 24h + 一次真
- * push」的动作,它就是这次动作的审计记录;行的产生速率与它的价值都不支持自动清账。要清账时按
- * workflow_run/roster 的先例加一个 `*_RETENTION_MS` 旋钮 + reaper 腿,那是独立一件。
- *
- * **② 陈旧 `running` 的清算:建了**({@link SqlLeaderRunStore.reapStaleRunning},旋钮 `LEADER_RUN_STALE_MS`,
- * 腿在 `boot/reapers.ts`)。这条与 ① 无关 —— 它不是为了控表大小,而是因为准入与驱动是两步、驱动腿只活在
- * 受理它的那个进程里:副本一死,行就永远停在 `running`,跨副本读面永远显示「在跑」而没有任何东西在跑。
- * 那是**静默**,不是保留问题。(本裁定是 codex 对抗复审 R1-high② 逼出来的:初版把两件事合成一件、一起
- * 判了「不建」,而第二件的论据完全不同。)
- *
- * ── 方言差异台账(显式,永不藏进抽象;A12 判据)────────────────────────────────────────────────────
- *   - `?` 占位符 vs `$n`                         - `CAST(? AS JSON)` vs `$n::jsonb`
- *   - 表级 `COLLATE utf8mb4_bin` vs 逐列 `COLLATE "C"`(PG 无表级形;`isolation-key-collation` 门执法)
- *   - dup-key 判别走 `sql-errors.ts` 单一属主(`isDupKeyError`),本店只有一根 UNIQUE ⇒ 无需归属判别
- *   - schema 属主:MySQL DDL 由本文件导出、展开进 `tidb-pool.ts` 的 SCHEMA_STATEMENTS(跟着中央
- *     named-lock 的那条 conn 建);PG DDL 由本文件的 `ensurePgLeaderRunSchema` 导出、由 `pg-pool.ts`
- *     的中央 `ensurePgSchema` 组合(与 approval-ask 同姿势)。
- */
 import { uuidv7 } from "@sema-agent/core";
 import { createHash } from "node:crypto";
 import { isDupKeyError } from "./sql-errors.js";
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { parseJsonOr } from "./sql-row-helpers.js";
-/** 表名(#192 单数纪律;`schema-naming-invariants` 的闭集词表执法)。 */
 export const LEADER_RUN_TABLE = "leader_run";
 const LEADER_RUN_STATUSES = new Set(["running", "completed", "failed", "needs_human"]);
-/** `objective_preview` 的字符上限,与 DDL 的 VARCHAR(160) 同源(`task_run.objective_preview` 先例同宽)。 */
 export const LEADER_OBJECTIVE_PREVIEW_CHARS = 160;
-/**
- * 幂等键的**落库形** = `sha256(scope \x1f raw)` 的 hex(64 字符,定宽)。
- *
- * 为什么 hash 而不是像 bake 店那样存 scope 过的明文:明文形的列宽(VARCHAR(255))与「principal(≤190)
- * + 调用方自选的 raw 键(≤255)」的上界对不上 —— 溢出时 PG 报 `value too long`、非严格 MySQL **静默截断**,
- * 而截断一个去重键的后果是**两个不同的请求折叠成同一次 leader run**(= 一次该跑的 run 被静默吞掉)。
- * 定宽 hash 让这条路径按构造不存在;顺带,库里也不再留调用方的原始键字面量。
- * (碰撞面:sha256,不在工程风险量级。)
- */
 export function leaderIdemKey(raw, owner) {
     return createHash("sha256").update(`${owner ?? ""}\x1f${raw}`).digest("hex");
 }
-/** MySQL 协议方言的建表语句(真源;由 `tidb-pool.ts` 展开进中央 SCHEMA_STATEMENTS)。 */
 export const TIDB_LEADER_RUN_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS ${LEADER_RUN_TABLE} (
      leader_run_id  VARCHAR(64)  NOT NULL,
@@ -83,7 +32,6 @@ export const TIDB_LEADER_RUN_STATEMENTS = [
      KEY idx_leader_run_started (started_at_ms)
    ) COLLATE utf8mb4_bin`,
 ];
-/** PG 方言的建表语句(MySQL 孪生的逐条翻译:JSON→JSONB,逐列 `COLLATE "C"`,内联 KEY→独立 CREATE INDEX)。 */
 export const PG_LEADER_RUN_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS ${LEADER_RUN_TABLE} (
      leader_run_id  VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -101,16 +49,13 @@ export const PG_LEADER_RUN_SCHEMA = [
     `CREATE INDEX IF NOT EXISTS idx_leader_run_owner ON ${LEADER_RUN_TABLE} (owner)`,
     `CREATE INDEX IF NOT EXISTS idx_leader_run_started ON ${LEADER_RUN_TABLE} (started_at_ms)`,
 ];
-/** 幂等的 PG schema 应用(中央 `ensurePgSchema` 组合它;集成套件也直接调)。 */
 export async function ensurePgLeaderRunSchema(q) {
     for (const stmt of PG_LEADER_RUN_SCHEMA)
         await q(stmt);
 }
-/** 清算腿写进 `error` 列的 WHY(消费方读到的就是这句;不是一个空的 failed)。 */
 export const STALE_SWEEP_REASON = "leader run went stale: no replica settled it within LEADER_RUN_STALE_MS (the replica driving it most likely died). " +
     "The run was NOT taken over — re-submit with a NEW Idempotency-Key to run it again.";
 const SELECT_COLS = "leader_run_id, owner, objective_preview, status, result, error, started_at_ms, finished_at_ms";
-/** 未知 status 字面量 = 库里躺着一条本进程不认识的行 ⇒ **响亮拒**,不静默折成 failed(闭集词表纪律 #157)。 */
 function statusOf(raw, id) {
     const s = String(raw);
     if (!LEADER_RUN_STATUSES.has(s)) {
@@ -134,24 +79,14 @@ function mapRow(r) {
         ...(finished === undefined ? {} : { finishedAtMs: finished }),
     };
 }
-/** 双方言 leader-run 店。方言差异台账见文件头注。 */
 export class SqlLeaderRunStore {
     db;
     constructor(db) {
         this.db = db;
     }
-    /** 挑本方言的 SQL 文本。两条语句**都写在调用点**(A12 判据:读者一眼看到两份)。 */
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
-    /**
-     * 准入一次 leader run(状态 `running`)。提交幂等照 `createBake`/`createRun` 的**原子赢或观察**:
-     * `idem_key` 是 UNIQUE,重投的那一方 INSERT 撞 dup-key ⇒ 回读**既有行**返回 `{created:false}`,
-     * 调用方据此**不再**起第二条后台腿。`idemKey=null` 恒插入(没要求去重)。
-     *
-     * 🔴 为什么不是「先 SELECT 再 INSERT」:两个副本的 check-then-act 会双双看到「没有」然后双双插入 ——
-     * 而这条路径的第二次插入意味着**第二次真 git push**。UNIQUE 是唯一能在两个进程之间成立的判据。
-     */
     async createRun(input) {
         const id = uuidv7();
         const now = Date.now();
@@ -163,8 +98,6 @@ export class SqlLeaderRunStore {
         catch (err) {
             if (isDupKeyError(this.db.dialect, err) && input.idemKey) {
                 const existing = await this.getByIdem(input.idemKey);
-                // 回读为空 = 赢家的行在这两步之间消失了(本店无删除口 ⇒ 只可能是外部 DELETE)。原样上抛而不是
-                // 悄悄再插一次:后者会在「运维正在手工清行」的窗口里放出第二次真 push。
                 if (existing)
                     return { created: false, run: existing };
             }
@@ -175,69 +108,35 @@ export class SqlLeaderRunStore {
             throw new Error(`createRun: leader_run ${id} vanished right after insert`);
         return { created: true, run };
     }
-    /** 按 id 读一行(跨副本可见性的全部依据)。不存在 ⇒ undefined。 */
     async getRun(id) {
         const res = await this.db.query(this.q(`SELECT ${SELECT_COLS} FROM ${LEADER_RUN_TABLE} WHERE leader_run_id = ?`, `SELECT ${SELECT_COLS} FROM ${LEADER_RUN_TABLE} WHERE leader_run_id = $1`), [id]);
         const row = res.rows[0];
         return row ? mapRow(row) : undefined;
     }
-    /** 按幂等键读回既有行(dup-key 观察臂;也给集成套件直查)。 */
     async getByIdem(idemKey) {
         const res = await this.db.query(this.q(`SELECT ${SELECT_COLS} FROM ${LEADER_RUN_TABLE} WHERE idem_key = ?`, `SELECT ${SELECT_COLS} FROM ${LEADER_RUN_TABLE} WHERE idem_key = $1`), [idemKey]);
         const row = res.rows[0];
         return row ? mapRow(row) : undefined;
     }
-    /**
-     * 陈旧 `running` 清算(codex 对抗复审 R1-high②,验真后修)。
-     *
-     * 病:准入(INSERT)与驱动(后台腿)是**两步**,而驱动腿只活在受理它的那个进程里。副本在这两步之间
-     * 挂掉、或在一条 24h 的 run 中途挂掉,行就永远停在 `running`:跨副本读面永远显示「在跑」,而没有任何
-     * 东西在跑;更坏的是那把幂等键被永久绑在这条无人驱动的行上,重投拿回的还是它。
-     *
-     * 处置 = **有界地说实话**,不是自动接管:把超期的 `running` 迁成 `failed` 并写清 WHY。
-     * 🔴 刻意**不做**跨副本接管(claim/lease/queued 状态机):接管一条产物是「真 git push」的 24h run
-     * 是一个独立的设计决定(要持久化完整可恢复请求、要 fencing、要想清楚两个副本同时以为自己是属主时
-     * 谁去 push),不是一次清算腿能顺手带过的。本腿把「永远 running」这个**静默**面消灭掉,把接管留给
-     * 一件具名的后续设计;当前语义写在这里,不藏着。
-     *
-     * 幂等键的后果同批写明:键**永久绑定**它当初准入的那条 run(与 `/v1/runs` 的 taskId 幂等同语义)。
-     * 一条被清算成 `failed` 的 run,用**同一个键**重投拿回的仍是那条 failed —— 调用方要重跑就换一个新键。
-     *
-     * @param staleMs 超过这个时长仍是 `running` 就算陈旧(部署旋钮 `LEADER_RUN_STALE_MS`)。
-     * @param now 注入时钟(测试要确定性)。
-     * @returns 本次迁走的行数。
-     */
     async reapStaleRunning(staleMs, now) {
         const cutoff = now - staleMs;
         const res = await this.db.query(this.q(`UPDATE ${LEADER_RUN_TABLE} SET status = 'failed', error = ?, finished_at_ms = ? WHERE status = 'running' AND started_at_ms < ?`, `UPDATE ${LEADER_RUN_TABLE} SET status = 'failed', error = $1, finished_at_ms = $2 WHERE status = 'running' AND started_at_ms < $3`), [STALE_SWEEP_REASON, now, cutoff]);
         return res.affected;
     }
-    /**
-     * TEST-ONLY:把一行的 `started_at_ms` 推到过去,好让 {@link reapStaleRunning} 的判据在一次测试里成立。
-     * 生产零调用(`started_at_ms` 只在准入时写一次)——具名 `ForTest` 是为了让这件事在 grep 里一眼可见,
-     * 而不是长成一个看起来像正经写口的方法(本仓 `setStatus` 那条欠账的教训)。
-     */
     async backdateStartedAtForTest(id, startedAtMs) {
         await this.db.query(this.q(`UPDATE ${LEADER_RUN_TABLE} SET started_at_ms = ? WHERE leader_run_id = ?`, `UPDATE ${LEADER_RUN_TABLE} SET started_at_ms = $1 WHERE leader_run_id = $2`), [startedAtMs, id]);
     }
-    /**
-     * 落终局。**只从 `running` 迁**(`WHERE status = 'running'`):终局是一次性的,一条已经结算过的 run
-     * 不该被后来的写者改写。回执 = 是否真的迁了,调用方据此决定要不要出声(静默丢一次终局写 = 用户永远
-     * 看到 `running`)。
-     */
     async finishRun(id, patch) {
         const json = dialectJsonEncoder(this.db.dialect);
         const res = await this.db.query(this.q(`UPDATE ${LEADER_RUN_TABLE} SET status = ?, result = CAST(? AS JSON), error = ?, finished_at_ms = ? WHERE leader_run_id = ? AND status = 'running'`, `UPDATE ${LEADER_RUN_TABLE} SET status = $1, result = $2::jsonb, error = $3, finished_at_ms = $4 WHERE leader_run_id = $5 AND status = 'running'`), [patch.status, patch.result === undefined ? null : json(patch.result), patch.error ?? null, Date.now(), id]);
         return res.affected > 0;
     }
 }
-/** MySQL-协议孪生(TiDB / MySQL / MariaDB 同一只 mysql2 池)。 */
 export class TiDBLeaderRunStore extends SqlLeaderRunStore {
     constructor(pool) {
         super(mysqlDriver(pool));
     }
 }
-/** PostgreSQL 孪生。 */
 export class PgLeaderRunStore extends SqlLeaderRunStore {
     constructor(pool) {
         super(pgDriver(pool));

package/dist/plugins/local-checkpoint-store.js

@@ -1,70 +1,20 @@
-/**
- * LOCAL (file-backed) checkpoint store — EnterPlanMode / durable HITL for the TOC local lane.
- *
- * Shape: core's `FileCheckpointStore` (crash-safe ledger+snapshot, per-token CAS — the ENGINE contract) is the
- * inner authority; this wrapper adds the SERVICE half the SQL twins carry (operator queue / session lookups /
- * resume ctx / reapers) WITHOUT re-implementing any core abstraction ([[core-service-boundary]]: engine contract
- * stays core's; wire/ops glue is ours).
- *
- * Enumeration seam: core's File store exposes only `listByScope(scope)` (pending-only summaries) + `get(token)`.
- * Cross-scope queries (fleet listPending / reapExpired / session lookups) therefore ride a service-side SCOPES
- * REGISTRY: `put` records each scope once into `checkpoint-scopes.json` (registered BEFORE the inner put so a
- * crash can't leave an unenumerable pending row; a scope whose rows are gone is harmless — its listByScope is
- * simply empty). Projection fields come from `get(token)` (the full Checkpoint), so listPending serves the same
- * non-secret card as the SQL twins (shared `boundedToolInput` bound, same severity-DESC sort).
- *
- * Honest degrades (documented, single-user local lane):
- *  - `deleteBySession` EXPIRES the session's pending gates + unlinks its ctx file — the ledger/snapshot keeps
- *    terminal history like the local tool-result/transcript stores do (no physical row delete primitive in
- *    core's File store; the E21 functional contract — "a deleted session has no resumable future" — holds).
- *  - `taskId` on the pending card comes from an injected `getActiveTaskId` (the local FileRunStore) — `null`
- *    when not wired, which every consumer already tolerates.
- */
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, renameSync, unlinkSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
-import { isApprovalGateKind } from "../tool-approval.js"; // A-002.1 单一属主
+import { isApprovalGateKind } from "../tool-approval.js";
 import { FileCheckpointStore, atomicWriteFile, sanitizePathComponent, } from "@sema-agent/core";
 import { boundedRuleSuggestions, boundedToolInput, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS } from "./checkpoint-store-sql.js";
 import { UNMANAGED_RETENTION } from "./retention-store-sql.js";
-/** design/80 D-D read-time twin of the TiDB put-time `terminal_at_ms` column (same formula — anti-drift). */
 function terminalAtOf(cp) {
     return Math.max(cp.createdAt + TERMINAL_BACKSTOP_MS, (cp.deadline ?? 0) + TERMINAL_GRACE_MS);
 }
-/** Collision-proof ctx filename: readable prefix + content hash of the FULL sessionId (sanitize can collide). */
 function ctxFileOf(sessionId) {
     return `${sanitizePathComponent(sessionId).slice(0, 48)}-${createHash("sha256").update(sessionId).digest("hex").slice(0, 12)}.json`;
 }
 export class LocalCheckpointStore {
-    /** #270 车1:托管留存声明 —— **诚实的 none**(与 local session 店同一条判据:本店的行没有按期删除的腿;
-     *  留存三方法只实现在 SQL 聚合店上)。locked policy + 本店 ⇒ core 的门拒启,那是契约的正确行为。 */
     retention = UNMANAGED_RETENTION;
-    /**
-     * `CheckpointStore.durability` 声明(#167 欠账,#168 件5)——**如实按内核判**:本类的内核是 core 的
-     * `FileCheckpointStore`(crash-safe ledger + snapshot,自身声明 `"durable"`),本地 scope 注册表也落
-     * 在同一个盘上目录里 ⇒ 进程重启后 park 全部还在、还赎得回,`"durable"` 是诚实读数而不是抬举。
-     *
-     * 它与「session store 的 local 形声明 durable 就拒启」不矛盾:那条判据管的是**声明 vs 介质**,而这里
-     * 的介质就是盘。真正的 process-local 形(`InMemoryCheckpointStore`)由 core 自己声明 `"process-local"`。
-     */
     durability = "durable";
-    /**
-     * `CheckpointStore.fidelity` 声明(core 5.17.0 [3052] 提货批 #172)——**如实按内核判**,与 durability
-     * 同一条判据:本类的读写内核是 core 的 `FileCheckpointStore`,它自己声明 `"json"`(盘上是 JSON 行),
-     * 包装层只加 scope/session 索引与 ctx 附属文件,不改这条 round-trip 的宽度 ⇒ 抄内核的读数是诚实的。
-     *
-     * ⚠️ 包装类**不继承**被包装者的声明(本类是委派不是子类),所以这一格必须自己写。它与内核那一格
-     * 是否仍然一致由测试盯着(`wiring-governance-operator.test.ts` 的 #172 组直接读内核那一格对表)——
-     * 内核哪天改宽度,包装层的声明会被那条钉当场揪出来,而不是靠人记得同步。
-     */
     fidelity = "json";
-    /**
-     * `CheckpointStore.redecision` 声明(core 5.22.0 F-012 L2/L3;[3342] clay 裁放行)——**如实按内核判**,
-     * 与 durability/fidelity 同一条判据:内核 core `FileCheckpointStore` **自己**声明 `{ reopen: true }`,
-     * 本类的 {@link LocalCheckpointStore.reopen} 纯委派给它 ⇒ 抄内核的读数是诚实的。包装类**不继承**被
-     * 包装者的声明(委派不是子类),所以这一格必须自己写。`validatingLease` 不声明(内核也没声明)。
-     * 翻向钉:`wiring-governance-operator.test.ts`(修前恰红,与本声明同 commit)。
-     */
     redecision = { reopen: true };
     inner;
     scopesPath;
@@ -72,14 +22,6 @@ export class LocalCheckpointStore {
     ctxDir;
     tmpDir;
     scopes = new Set();
-    /** [868] sessionId → every token ever put for it — the service-side index that stands in for the SQL twins'
-     *  `WHERE checkpoint.session_id = ?` on NON-pending rows (core's File store enumerates pending only via
-     *  listByScope; get(token) is the sole read for resolved/expired rows, so cross-status session queries need
-     *  this registry). Registered BEFORE the inner put (same crash direction as the scopes registry: a stale
-     *  index entry is a harmless empty lookup; an unindexed EXPIRED row would silently disable the
-     *  failSuspendedWithExpiredCheckpoint leg — the bad direction). Persisted so a restart keeps the
-     *  suspend→crash→expire-later lifecycle visible. Entries are never dropped while the inner row exists
-     *  (a `resolved` row can be reopen()ed back to pending — pruning it would be wrong). */
     sessionTokens = new Map();
     opts;
     constructor(root, opts = {}) {
@@ -100,18 +42,11 @@ export class LocalCheckpointStore {
                             this.scopes.add(s);
             }
             catch (e) {
-                // C4(clay 裁 2026-07-26,C 先行 + B 根治):此前这里静默吞 ⇒ 存量待决审批整体从枚举面隐身,
-                // 操作员看到的是**空列表而不是错误**,没人会对空列表排障。处置两层:
-                // ①fail-visible(C):warn 大声 + 坏文件改名隔离留证(也防下一次 put 的整写把证据盖掉);
-                // ②重建(B,core 1.424 `listScopes?` seam,[1800]② 索 → [1803] 交付):constructor 是同步的,
-                //   重建挂在读路径懒执行一次(见 ensureScopesRebuilt)—— 从数据本体枚举 pending scope 集,
-                //   枚举面完整恢复,不再依赖「下次 suspend 自愈」只救新件。
                 const quarantine = `${this.scopesPath}.corrupt-${Date.now()}`;
                 try {
                     renameSync(this.scopesPath, quarantine);
                 }
                 catch {
-                    /* 移不动就留原地 —— warn 里已给路径,人工可查 */
                 }
                 this.scopeRegistryCorrupt = true;
                 console.warn(`LocalCheckpointStore: checkpoint-scopes.json is corrupt (${e instanceof Error ? e.message : String(e)}) — ` +
@@ -131,23 +66,17 @@ export class LocalCheckpointStore {
                 }
             }
             catch {
-                /* a corrupt index only narrows hasExpiredBySession (fail-safe: the reaper skips, cancel still works) */
             }
         }
     }
-    /** Persist the session→tokens index (whole-file atomic replace — puts are per-suspend, low frequency). */
     persistSessionTokens() {
         atomicWriteFile(this.tmpDir, this.sessionTokensPath, JSON.stringify(Object.fromEntries([...this.sessionTokens].map(([sid, set]) => [sid, [...set]]))));
     }
-    // ─────────── core CheckpointStore contract — delegated to core's File store (the engine authority) ───────────
     async put(token, cp) {
-        // Register the scope BEFORE the inner commit: a crash between the two leaves a stale scope entry
-        // (harmless empty enumeration), never an unenumerable pending checkpoint (the bad direction).
         if (!this.scopes.has(cp.scope)) {
             this.scopes.add(cp.scope);
             atomicWriteFile(this.tmpDir, this.scopesPath, JSON.stringify([...this.scopes]));
         }
-        // [868] session→token index, same before-the-inner-put crash rationale (see the field doc).
         if (!this.sessionTokens.get(cp.sessionId)?.has(token)) {
             const set = this.sessionTokens.get(cp.sessionId) ?? new Set();
             set.add(token);
@@ -165,10 +94,6 @@ export class LocalCheckpointStore {
     reopen(token, scope, reason) {
         return this.inner.reopen(token, scope, reason);
     }
-    /** core 5.14.0(#147):入参是 `PendingSteerInput`(text/trusted + 可选 actor/inputId/priority),不是
-     *  两键单座 —— 形参窄成 `{text,trusted}` 会**静默丢掉**署名与幂等键(TS 的方法参数是双变的,窄形不
-     *  报错,只是把三个可选键从类型上抹掉,调用点再也传不进来)。队列语义与边界全在被包的 core
-     *  `FileCheckpointStore` 里,本 wrapper 只做转发。 */
     setPendingSteer(token, scope, steer) {
         return this.inner.setPendingSteer(token, scope, steer);
     }
@@ -184,17 +109,13 @@ export class LocalCheckpointStore {
     close() {
         this.inner.close();
     }
-    // ─────────── service extensions (the SQL twins' operator/ops half) ───────────
-    /** C4-B:注册表损坏时从**数据本体**懒重建 scope 集(core 1.424 `listScopes?` = 「有 ≥1 条 pending 的
-     *  distinct scope 集」,与 listByScope 可见面对齐 —— 恰好是本注册表要的内容)。一次性:重建后回写
-     *  sidecar,恢复正常路径。seam 缺席(第三方旧 inner)⇒ 保持 C 案的可见降级,不装恢复了。 */
     scopeRegistryCorrupt = false;
     async ensureScopesRebuilt() {
         if (!this.scopeRegistryCorrupt)
             return;
         const listScopes = this.inner.listScopes;
         if (typeof listScopes !== "function")
-            return; // 无 seam:维持已 warn 的降级
+            return;
         const rebuilt = await listScopes.call(this.inner);
         for (const s of rebuilt)
             this.scopes.add(s);
@@ -202,7 +123,6 @@ export class LocalCheckpointStore {
         atomicWriteFile(this.tmpDir, this.scopesPath, JSON.stringify([...this.scopes]));
         console.warn(`LocalCheckpointStore: scope registry REBUILT from the data plane (${rebuilt.length} scope(s) with pending gates) — enumeration restored`);
     }
-    /** All still-pending checkpoints across the registered scopes (summary + full row via get). */
     async pendings(scope) {
         await this.ensureScopesRebuilt();
         const out = [];
@@ -216,7 +136,6 @@ export class LocalCheckpointStore {
         }
         return out;
     }
-    /** Operator approval queue — the same NON-secret card as the SQL twins (never the token). */
     async listPending(scope) {
         const rows = [];
         for (const { cp } of await this.pendings(scope)) {
@@ -228,32 +147,20 @@ export class LocalCheckpointStore {
                 scope: cp.scope,
                 toolName: pa?.toolName ?? null,
                 toolCallId,
-                // [1995]②: the D-1 binding fields are OMITTED when the park has no tool action (plan_review /
-                // resource_limit / task_done) — the wire contract says an absent nullable field is ABSENT, not `null`
-                // (a consumer branching on "key present ⇒ there is a binding" would echo `null` back into /decide).
                 ...(toolCallId !== null ? { boundCallId: toolCallId } : {}),
                 ...(pa?.boundInputHash !== undefined ? { boundInputHash: pa.boundInputHash } : {}),
-                // [1995]③ additive: which gate this row is parked on, so a durable-recovery consumer can route
-                // plan / tool / resource off the SAME queue (toolName is null for every non-tool gate).
                 ...(gate?.kind !== undefined ? { gateKind: gate.kind } : {}),
                 taskId: (await this.opts.getActiveTaskId?.(cp.sessionId)) ?? null,
                 input: boundedToolInput(pa?.args),
                 createdAt: cp.createdAt,
                 deadline: cp.deadline ?? null,
                 riskDescriptor: gate?.riskDescriptor ?? null,
-                // [3684]②:与 SQL 孪生**同一个** `boundedRuleSuggestions`(窄读+脱敏+截基数)。本地形没有列,
-                // 直接从 blob 上的 `pendingAction` 取——投影结果必须与两条 SQL 腿逐字同形,否则 local 档的运维
-                // 队列会给出一份别人没有的卡面。无供给 ⇒ 省键(绝不 null/[])。
-                // 🔴 这里**连计数一起**保留(不同于 SQL 腿的回读形 `{ countRedactions: false }` —— 那条腿脱敏
-                // **照跑**,关掉的只是计数):本地形每次读的是**未脱敏的原始 blob**,这一遍是它唯一的一次脱敏,
-                // 不是重扫已脱敏文本 ⇒ `redactions_applied_total` 记的是真命中,该计。
                 ...(() => {
                     const rs = boundedRuleSuggestions(pa?.ruleSuggestions);
                     return rs !== undefined ? { ruleSuggestions: rs } : {};
                 })(),
             });
         }
-        // Same triage order as the SQL twins: severity DESC, then oldest-first within a tier.
         return rows.sort((a, b) => (b.riskDescriptor?.severity ?? 0) - (a.riskDescriptor?.severity ?? 0) || a.createdAt - b.createdAt);
     }
     async findPendingTokenBySession(sessionId, scope) {
@@ -262,14 +169,6 @@ export class LocalCheckpointStore {
                 return token;
         return null;
     }
-    /** [868] read-only probe face: does this session have an EXPIRED checkpoint row? The local twin of the SQL
-     *  `EXISTS (SELECT 1 FROM checkpoint ce WHERE ce.session_id = ? AND ce.status = 'expired')` that drives the
-     *  run stores' failSuspendedWithExpiredCheckpoint. Scans the session→token index (get(token) is the only
-     *  cross-status read core's File store offers); an index entry whose inner row vanished is pruned lazily.
-     *  Backed by a persisted registry, so it stays honest — never a guessed "true".
-     *  ⚠️ 存量限制(codex M2,如实):索引随 put 增量建立,无升级迁移——本版本部署前已存在的 checkpoint 不在
-     *  索引里,其 expired 对本探针不可见(core File store 的 listByScope 是 pending-only,无法枚举历史行回填)。
-     *  旧存量锁死的恢复把手 = cancel verb([868]①,不依赖本索引);增量行全覆盖。 */
     async hasExpiredBySession(sessionId) {
         const tokens = this.sessionTokens.get(sessionId);
         if (!tokens)
@@ -278,7 +177,7 @@ export class LocalCheckpointStore {
         for (const t of [...tokens]) {
             const cp = await this.inner.get(t);
             if (!cp) {
-                tokens.delete(t); // inner row gone (e.g. a wiped data plane) — the index entry is stale
+                tokens.delete(t);
                 pruned = true;
                 continue;
             }
@@ -292,24 +191,16 @@ export class LocalCheckpointStore {
                 this.persistSessionTokens();
             }
             catch {
-                /* best-effort — a stale on-disk entry is re-pruned on the next scan */
             }
         }
         return false;
     }
-    /** `undefined` = no pending row; else the owner scope (local scopes are always strings — never null). */
     async peekPendingScope(sessionId) {
         for (const { cp } of await this.pendings())
             if (cp.sessionId === sessionId)
                 return cp.scope;
         return undefined;
     }
-    /**
-     * design/80 D-D global expiry sweep — same kind-split as the TiDB twin: the deadline branch abort-expires
-     * every kind EXCEPT a human/irreversible_ask approval gate (those get the graceful resolve-DENY via
-     * listExpiredApprovalGates), with the AskUserQuestion carve-back (denying a question is incoherent → expire);
-     * the terminal_at_ms branch (derived read-time via the SAME formula the TiDB put stamps) abort-expires ANY kind.
-     */
     async reapExpired(cutoff) {
         let n = 0;
         for (const { token, cp } of await this.pendings()) {
@@ -324,7 +215,6 @@ export class LocalCheckpointStore {
         }
         return n;
     }
-    /** design/80 D-D SLA deny-sweep input — pending human/irreversible_ask gates past deadline (excl. AskUserQuestion). */
     async listExpiredApprovalGates(cutoff, limit = 100) {
         const hits = [];
         for (const { cp } of await this.pendings()) {
@@ -342,7 +232,6 @@ export class LocalCheckpointStore {
             .slice(0, limit)
             .map(({ sessionId, scope }) => ({ sessionId, scope }));
     }
-    // ─────────── checkpoint ctx (resume rebuild inputs; sessionId-keyed, one JSON file per session) ───────────
     async putCtx(sessionId, ctx) {
         const rec = { sessionId, updatedAt: Date.now(), ctx };
         atomicWriteFile(this.tmpDir, join(this.ctxDir, ctxFileOf(sessionId)), JSON.stringify(rec));
@@ -353,13 +242,12 @@ export class LocalCheckpointStore {
             return null;
         try {
             const rec = JSON.parse(readFileSync(p, "utf8"));
-            return rec.sessionId === sessionId ? (rec.ctx ?? null) : null; // hash-collision paranoia: verify the embedded id
+            return rec.sessionId === sessionId ? (rec.ctx ?? null) : null;
         }
         catch {
-            return null; // a torn/corrupt ctx reads as absent — the resume 409s "resume context missing" (fail-loud upstream)
+            return null;
         }
     }
-    /** GC ctx files whose lifecycle is over — same three guards as the SQL twins (stale ∧ no pending ∧ no active run). */
     async reapCtx(cutoff) {
         let n = 0;
         for (const f of readdirSync(this.ctxDir)) {
@@ -371,7 +259,7 @@ export class LocalCheckpointStore {
                 rec = JSON.parse(readFileSync(p, "utf8"));
             }
             catch {
-                continue; // unreadable ⇒ leave for inspection (never a blind unlink)
+                continue;
             }
             if (rec.updatedAt >= cutoff)
                 continue;
@@ -384,27 +272,20 @@ export class LocalCheckpointStore {
                 n++;
             }
             catch {
-                /* racing unlink is fine */
             }
         }
         return n;
     }
-    /**
-     * E21 session purge — functional contract: a deleted session has no resumable future. Expires every pending
-     * gate of the session (all scopes) + unlinks its ctx file. Owner guard mirrors the SQL EXISTS guard: with an
-     * `ownerOf` source the owner must null-safe-match; without one, only an ownerless call (owner=null) purges.
-     * Returns the number of gates expired. (Terminal ledger history stays on disk — local transcripts posture.)
-     */
     async deleteBySession(sessionId, owner) {
         if (this.opts.ownerOf) {
             const actual = await this.opts.ownerOf(sessionId);
             if (actual === undefined)
-                return 0; // no session row ⇒ EXISTS guard fails ⇒ purge nothing
+                return 0;
             if ((actual ?? null) !== (owner ?? null))
                 return 0;
         }
         else if (owner !== null) {
-            return 0; // no owner source to verify a non-null owner against — fail-closed
+            return 0;
         }
         let n = 0;
         for (const { token, cp } of await this.pendings()) {
@@ -417,7 +298,6 @@ export class LocalCheckpointStore {
                 unlinkSync(p);
         }
         catch {
-            /* best-effort ctx unlink */
         }
         return n;
     }