@sema-agent/server 7.132.0 → 7.133.0

package/dist/plugins/approval-ask-store-sql.js

@@ -1,5 +1,5 @@
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
-import { canAskTransition } from "../approval-ask-machine.js";
+import { ASK_TERMINAL, canAskTransition } from "../approval-ask-machine.js";
 import { APPROVAL_ENDING_CAUSES, causeOfAskRow } from "../approval-deny-reasons.js";
 import { isDupKeyError, isMissingColumnError } from "./sql-errors.js";
 import { decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, readTriStateJsonValueColumn } from "./sql-json-column.js";
@@ -9,6 +9,11 @@ export function assertIntegralEpochMs(field, value) {
         throw new TypeError(`approval-ask store: ${field} must be an integer epoch-ms (BIGINT column), got ${String(value)}`);
     }
 }
+export function assertReapBounds(cutoffMs, limit) {
+    assertIntegralEpochMs("cutoffMs", cutoffMs);
+    if (!Number.isSafeInteger(limit) || limit <= 0)
+        throw new Error(`approval-ask-store: reap limit must be a positive integer, got ${String(limit)}`);
+}
 export function assertIdempotencyKeyShape(key) {
     if (key.length === 0 || key.length > 255 || key.trim() !== key) {
         throw new Error(`invalid idempotency key: must be 1-255 chars with no leading/trailing whitespace (got ${JSON.stringify(key.slice(0, 32))}${key.length > 32 ? "…" : ""}, length ${key.length})`);
@@ -722,6 +727,37 @@ export class SqlApprovalAskStore {
         await this.db.query(this.q(`DELETE FROM ${APPROVAL_ASK_TABLE} WHERE task_id = ?`, `DELETE FROM ${APPROVAL_ASK_TABLE} WHERE task_id = $1`), [taskId]);
         await this.db.query(this.q(`DELETE FROM ${APPROVAL_BATCH_TABLE} WHERE task_id = ?`, `DELETE FROM ${APPROVAL_BATCH_TABLE} WHERE task_id = $1`), [taskId]);
     }
+    async reapSettledAsks(cutoffMs, limit, keepAnchors) {
+        assertReapBounds(cutoffMs, limit);
+        const terminal = [...ASK_TERMINAL];
+        const keep = [...keepAnchors];
+        const dialect = this.db.dialect;
+        let n = 0;
+        const statePh = terminal.map(() => ph(dialect, ++n)).join(", ");
+        const cutPh = ph(dialect, ++n);
+        const ANCHOR_COLUMNS = ["task_id", "session_id", "source_task_id"];
+        let keepSql = "";
+        let keepParams = [];
+        if (keep.length > 0 && dialect === "tidb") {
+            const list = keep.map(() => "?").join(", ");
+            keepSql = ANCHOR_COLUMNS.map((c) => ` AND ${c} NOT IN (${list})`).join("");
+            keepParams = ANCHOR_COLUMNS.flatMap(() => keep);
+        }
+        else if (keep.length > 0) {
+            const arr = ph(dialect, ++n);
+            keepSql = ANCHOR_COLUMNS.map((c) => ` AND ${c} <> ALL(${arr}::text[])`).join("");
+            keepParams = [keep];
+        }
+        const where = `state IN (${statePh}) AND provisional = 0 AND updated_at_ms < ${cutPh}${keepSql}`;
+        const params = [...terminal, cutoffMs, ...keepParams];
+        const res = await this.db.query(this.q(`DELETE FROM ${APPROVAL_ASK_TABLE} WHERE ${where} LIMIT ${limit}`, `DELETE FROM ${APPROVAL_ASK_TABLE} WHERE ctid IN (SELECT ctid FROM ${APPROVAL_ASK_TABLE} WHERE ${where} LIMIT ${limit})`), params);
+        return res.affected;
+    }
+    async reapEmptyBatches(cutoffMs, limit) {
+        assertReapBounds(cutoffMs, limit);
+        const res = await this.db.query(this.q(`DELETE FROM ${APPROVAL_BATCH_TABLE} WHERE updated_at_ms < ? AND NOT EXISTS (SELECT 1 FROM ${APPROVAL_ASK_TABLE} a WHERE a.batch_id = ${APPROVAL_BATCH_TABLE}.batch_id) LIMIT ${limit}`, `DELETE FROM ${APPROVAL_BATCH_TABLE} WHERE ctid IN (SELECT b.ctid FROM ${APPROVAL_BATCH_TABLE} b WHERE b.updated_at_ms < $1 AND NOT EXISTS (SELECT 1 FROM ${APPROVAL_ASK_TABLE} a WHERE a.batch_id = b.batch_id) LIMIT ${limit})`), [cutoffMs]);
+        return res.affected;
+    }
     async getBatch(batchId) {
         const { rows } = await this.db.query(this.q(`SELECT ${BATCH_COLS} FROM ${APPROVAL_BATCH_TABLE} WHERE batch_id = ?`, `SELECT ${BATCH_COLS} FROM ${APPROVAL_BATCH_TABLE} WHERE batch_id = $1`), [batchId]);
         return rows[0] ? mapBatchRow(rows[0]) : null;

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

@@ -1,29 +1,25 @@
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import { type SqlEngineReading, type SqlWallSource, type SqlWallsReading } from "./sql-driver.js";
+import { type SqlEngineFacts, type SqlEngineReading, type SqlWallSource, type SqlWallsReading } from "./sql-driver.js";
+import { type Logger } from "../observability/logger.js";
 /**
  * 文本协议的 blob 膨胀律 —— mysql2 `query()` 把 Buffer 参数写成 `X'<hex>'`,一字节两个字符,所以承载一个 blob 的语句至少是它的 2 倍。
  * 包墙折成「能装下多大的 blob」只用这一只常量,推导里不手写 `/ 2`。
  */
 export declare const SQL_TEXT_PROTOCOL_BLOB_INFLATION = 2;
 /**
- * 包墙下能装多大的 blob:语句里的载荷量({@link packetWallStatementBytes},与提交体受理口读同一个折算)再按 {@link SQL_TEXT_PROTOCOL_BLOB_INFLATION} 折半。
- * 提交体按原样进语句、没有膨胀,blob 以十六进制字面进语句、有 2× —— 膨胀律是 blob 腿自己的,余量不是。
+ * 包墙下能装多大的 blob:语句里的载荷量({@link packetWallStatementBytes})再按 {@link SQL_TEXT_PROTOCOL_BLOB_INFLATION} 折半。
+ * blob 以十六进制字面进语句、有 2× —— 膨胀律是 blob 腿自己的,余量不是。
  */
 export declare function packetWallBlobCap(maxPacketBytes: number): number;
-/**
- * **事实本身还没建立**时 MySQL 协议方言的缺省帽(池上还没借出过连接,或最近一次连接初始化被拒:`SqlDriver.facts === null`)= 事实缺席时的墙
- * (`sql-driver.ts` `SQL_FACTS_ABSENT_WALLS`,判官 `sqlWallsOf`;提交受理口读同一只)走下面同一个推导 —— 不是第二份落点,只是那个推导在这组墙上的值
- * (今天 = TiDB 缺省行墙走 blob 行的折算 6 MiB − 1 KiB:最矮的包墙缺省 16 MiB 扣语句余量再折半仍近 8 MiB,行腿更矮)。
- */
-export declare const SQL_BLOB_FACTS_ABSENT_CAP_BYTES: number;
 /**
  * SQL 快照 blob 的**缺省**帽(运维没设 `SNAPSHOT_BLOB_SQL_MAX_BYTES` 时)的唯一推导 —— 入参是判官 `sqlWallsOf` 给的墙(不读事实、不判缺席、不看方言),**两堵墙取最小**:
  * 行墙腿(`SqlEngineFacts.maxRowBytes`,TiDB:{@link rowWallPayloadBytes} 的 `blob` = 行墙 − blob 行的余量 1 KiB —— 按这一行的真实形算,不借 JSON 提交体行的 64 KiB)
  * 与包墙腿(`SqlEngineFacts.maxPacketBytes`,InnoDB 与 TiDB 都有:{@link packetWallBlobCap} = ⌊(包墙 − 1 KiB 语句余量) ÷ 2⌋)。余量只在 `sql-driver.ts` 定义一次
  * (墙 × 行的形各一只),提交体受理口(`http/request-guards.ts` `refuseSubmitBody`)读同一张表的 `json` 那一只,不各抄。
- * 墙的 `null` 只表示「这堵墙不存在」;两堵都不存在(PG —— 扩展协议无这两堵墙,事实在不在都一样 —— 或没有 SQL 后端)⇒ `undefined` 不设帽。事实本身缺席时
- * 墙由判官给(MySQL 协议按最保守的墙),走同一个推导 = {@link SQL_BLOB_FACTS_ABSENT_CAP_BYTES}。显式旋钮是运维的策略帽,在本推导之上(见 {@link sqlBlobCapBytes})。
+ * 墙的 `null` 只表示「这堵墙不存在」;两堵都不存在(PG —— 扩展协议无这两堵墙 —— 或没有 SQL 后端)⇒ `undefined` 不设帽。
+ * 「事实本身缺席」不是这里的入参:店的写前判读的是借出连接自己的事实(恒已建立,见 {@link SqlConnectionReading}),缺席的读法只在提交受理口读池级读口时出现(判官 `sqlWallsOf` 给墙)。
+ * 显式旋钮是运维的策略帽,在本推导之上(见 {@link sqlBlobCapBytes})。
  *
  * 两堵墙的真库读数(clay 拍 a+c,2026-07-27;k3s8 tidb-test v7.5.1 默认配置探针):7 MiB / 31 MiB = `entry too large`(行墙,默认 6291456)、
  * 32 MiB = `max_allowed_packet`(包墙,64 MiB ÷ ~2× 文本协议膨胀)。帽=诚实拒绝:超限 blob 在 query 之前 typed 拒(消费面 HTTP 413 / capture warn
@@ -43,15 +39,29 @@ export interface SqlBlobCapReading {
  */
 export declare function sqlBlobDefaultCapOf(walls: SqlWallsReading): SqlBlobCapReading | undefined;
 /**
- * 一个 SQL 快照 blob 此刻的帽 —— **显式旋钮 ?? 判官给的墙走缺省推导**的唯一一只函数。两个读者同调它、各传本池的**引擎读口**(方言与活事实同出一只驱动,
- * 与提交受理口读的是同一种读口):店的写前帽({@link SqlBlobBackend},本池的驱动)与 `PUT /sync/blobs` 的前置 413(`boot/stage-10-http-server.ts` 装配的读口,
- * 按请求调,读 `ServiceDeps.sqlEngine`)。同一池上两个读口读的是同一份池级事实。
+ * 一条**借出连接**的引擎读口:方言(装配事实)+ 它自己那次初始化回读的事实。与 {@link SqlEngineReading} 的差别只有一处 —— `facts` 恒在:连接是借出时才有的,
+ * 借出即已初始化({@link connectJudged} 交给判决的就是借出连接的 `sqlConnectionFacts`),所以「事实缺席」在这条读法上**不可表示**(编译期拒,不是运行期一个没人走的分支)。
+ * 事实缺席(池上还没建立过、或最近一次初始化被拒)只出现在读**池级**读口的地方 —— 提交受理口 —— 那一格的墙由判官 `sqlWallsOf` 给,不经过帽的推导。
  */
-export declare function sqlBlobCapOf(explicitCapBytes: number | undefined, engine: SqlEngineReading): SqlBlobCapReading | undefined;
+export interface SqlConnectionReading {
+    readonly dialect: SqlEngineReading["dialect"];
+    readonly facts: SqlEngineFacts;
+}
+/**
+ * 一个 SQL 快照 blob 此刻的帽 —— **显式旋钮 ?? 判官给的墙走缺省推导**的唯一一只函数。唯一读者 = 店的写前判({@link SqlBlobBackend.putBlob}),传的读口({@link SqlConnectionReading})是
+ * **将要执行写入的那条连接**的(方言 + 它自己那次初始化回读的事实,墙经与提交受理口同一只判官 `sqlWallsOf`):包墙是连接的会话值,所以判决只在写入的那条连接上做,
+ * HTTP 面不替店另算一份帽。
+ */
+export declare function sqlBlobCapOf(explicitCapBytes: number | undefined, connection: SqlConnectionReading): SqlBlobCapReading | undefined;
 /** {@link sqlBlobCapOf} 的字节投影(同一个推导,不另读)。 */
-export declare function sqlBlobCapBytes(explicitCapBytes: number | undefined, engine: SqlEngineReading): number | undefined;
+export declare function sqlBlobCapBytes(explicitCapBytes: number | undefined, connection: SqlConnectionReading): number | undefined;
+/**
+ * 这一拒是不是**那条连接的包墙**定的:帽是缺省推导出的(不是运维旋钮)、那条连接有包墙、且包墙腿的折算恰是这个帽(包墙腿是最矮的一腿,或与行墙腿并列)。
+ * 只有这种拒才值得问「这条连接过时了吗」({@link connectJudged}) —— 旋钮的拒、行墙的拒与连接新旧无关。`walls` = 判出这个帽的那一份墙({@link sqlWallsOf})。
+ */
+export declare function capBoundByPacketWall(cap: SqlBlobCapReading, walls: SqlWallsReading): boolean;
 /**
- * 一次 blob 超帽的拒句 —— **唯一的组句器**(`PUT /sync/blobs` 的前置 413 与店的 typed {@link BlobTooLargeError} 同调它):句子按帽的出处({@link SqlBlobCapReading.source})
+ * 一次 blob 超帽的拒句 —— **唯一的组句器**(店的 typed {@link BlobTooLargeError} 调它;`PUT /sync/blobs` 的 413 原样转出它的句子):句子按帽的出处({@link SqlBlobCapReading.source})
  * 分三形,不把假定说成库的上限、也不把运维的旋钮说成库的上限。
  *  · `operator` —— 帽是运维设的 `SNAPSHOT_BLOB_SQL_MAX_BYTES`;
  *  · `reported` —— 帽由库报的两堵墙推出(单行上限与包墙÷文本协议膨胀的较小者);
@@ -97,21 +107,24 @@ export interface BlobBackend {
 export declare class SqlBlobBackend implements BlobBackend {
     private readonly dialect;
     private readonly pool;
-    /** Explicit per-blob cap (the operator's `SNAPSHOT_BLOB_SQL_MAX_BYTES`); absent ⇒ the derivation in {@link sqlBlobCapBytes} over this pool's live engine facts. */
+    /** Explicit per-blob cap (the operator's `SNAPSHOT_BLOB_SQL_MAX_BYTES`); absent ⇒ the derivation in {@link sqlBlobCapOf} over the walls of the connection each write borrows. */
     private readonly explicitCapBytes;
-    /** This pool's engine reading (dialect + live facts, from the pool's own driver) — the one source the cap's walls are read from. */
-    private readonly engine;
     /** Blob-domain table ([ref] blob 域隔离:file-history 域用自己的表,reap/GC 不跨域)。代码内字面量,非用户输入。 */
     private readonly table;
-    constructor(dialect: "tidb" | "pg", pool: MysqlPool | PgPool, maxBytes?: number, table?: string);
-    /** The cap in force for this write: the explicit one, else the default derived from the pool's engine facts as they
-     *  stand now (the driver refreshes them on each connection initialization). */
-    private cap;
+    /** The write path's connection source: every `putBlob` borrows ONE connection from it (through {@link connectJudged}), judges on that connection's walls, writes on it. */
+    private readonly db;
+    /** Where a stale connection's replacement is logged ({@link connectJudged}); the boot assembly passes the service logger. */
+    private readonly log;
+    constructor(dialect: "tidb" | "pg", pool: MysqlPool | PgPool, maxBytes?: number, table?: string, log?: Pick<Logger, "warn">);
     /** The created_at-refreshing content-addressed upsert — VERBATIM the tidb/pg stores' `putBlobRow`. Refreshes
      *  created_at even on a dedup hit so a re-used/just-written blob is "touched=now" and GC-grace-protected.
      *  (a): an over-cap blob is REJECTED (typed {@link BlobTooLargeError}) BEFORE the driver ever sees the bytes —
      *  the alternative is an inscrutable packet-limit error deep in the driver, and on the HTTP face a 502 that
-     *  invites the peer to retry a blob that can never land. */
+     *  invites the peer to retry a blob that can never land.
+     *  🔴 The cap is judged ON THE CONNECTION THAT WRITES (S-1746): `max_allowed_packet` is a session value, fixed per
+     *  connection, so the write borrows one connection through {@link connectJudged}, which reads ITS walls, judges, and — when
+     *  the refusal is that connection's packet wall and the server's global wall is higher — replaces the stale connection and
+     *  judges once more; the INSERT runs on the connection that passed. Never a pool-level reading, never a bare `pool.query`. */
     putBlob(hash: string, bytes: Uint8Array): Promise<void>;
     /** The bytes for `hash` (undefined if absent) — VERBATIM the tidb/pg stores' getBlob SELECT. A pool/query error
      *  PROPAGATES (a transient DB fault is loud, not a silent "missing blob" — parity with the MinIO backend's throw). */

package/dist/plugins/blob-backend.js

@@ -1,12 +1,12 @@
 import { createHash } from "node:crypto";
 import { presignS3Url, presignS3ListUrl } from "./s3-presign.js";
-import { SQL_FACTS_ABSENT_WALLS, mysqlDriver, packetWallStatementBytes, pgDriver, rowWallPayloadBytes, sqlWallsOf } from "./sql-driver.js";
+import { connectJudged, mysqlDriver, packetWallStatementBytes, pgDriver, rowWallPayloadBytes, sqlWallsOf } from "./sql-driver.js";
+import { createLogger } from "../observability/logger.js";
 const BLOB_GC_GRACE_MS = 3_600_000;
 export const SQL_TEXT_PROTOCOL_BLOB_INFLATION = 2;
 export function packetWallBlobCap(maxPacketBytes) {
     return Math.floor(packetWallStatementBytes(maxPacketBytes) / SQL_TEXT_PROTOCOL_BLOB_INFLATION);
 }
-export const SQL_BLOB_FACTS_ABSENT_CAP_BYTES = sqlBlobDefaultCapBytes(SQL_FACTS_ABSENT_WALLS);
 export function sqlBlobDefaultCapBytes(walls) {
     return sqlBlobDefaultCapOf(walls)?.capBytes;
 }
@@ -18,11 +18,14 @@ export function sqlBlobDefaultCapOf(walls) {
         legs.push({ capBytes: packetWallBlobCap(walls.maxPacketBytes), source: walls.sources.maxPacketBytes });
     return legs.reduce((best, leg) => (best === undefined || leg.capBytes < best.capBytes ? leg : best), undefined);
 }
-export function sqlBlobCapOf(explicitCapBytes, engine) {
-    return explicitCapBytes !== undefined ? { capBytes: explicitCapBytes, source: "operator" } : sqlBlobDefaultCapOf(sqlWallsOf(engine));
+export function sqlBlobCapOf(explicitCapBytes, connection) {
+    return explicitCapBytes !== undefined ? { capBytes: explicitCapBytes, source: "operator" } : sqlBlobDefaultCapOf(sqlWallsOf(connection));
 }
-export function sqlBlobCapBytes(explicitCapBytes, engine) {
-    return sqlBlobCapOf(explicitCapBytes, engine)?.capBytes;
+export function sqlBlobCapBytes(explicitCapBytes, connection) {
+    return sqlBlobCapOf(explicitCapBytes, connection)?.capBytes;
+}
+export function capBoundByPacketWall(cap, walls) {
+    return cap.source !== "operator" && walls.maxPacketBytes !== null && packetWallBlobCap(walls.maxPacketBytes) === cap.capBytes;
 }
 export function sqlBlobCapRefusalText(byteLen, cap) {
     const objectStorage = "configure MinIO object storage (MINIO_ENDPOINT/MINIO_ACCESS_KEY/MINIO_SECRET_KEY) for large snapshot blobs";
@@ -64,27 +67,34 @@ export class SqlBlobBackend {
     dialect;
     pool;
     explicitCapBytes;
-    engine;
     table;
-    constructor(dialect, pool, maxBytes, table = "snapshot_blob") {
+    db;
+    log;
+    constructor(dialect, pool, maxBytes, table = "snapshot_blob", log) {
         this.dialect = dialect;
         this.pool = pool;
         this.explicitCapBytes = maxBytes;
         this.table = table;
-        this.engine = dialect === "tidb" ? mysqlDriver(pool) : pgDriver(pool);
-    }
-    cap() {
-        return sqlBlobCapOf(this.explicitCapBytes, this.engine);
+        this.db = dialect === "tidb" ? mysqlDriver(pool) : pgDriver(pool);
+        this.log = log ?? createLogger();
     }
     async putBlob(hash, bytes) {
-        const cap = this.cap();
-        if (cap !== undefined && bytes.byteLength > cap.capBytes)
-            throw new BlobTooLargeError(bytes.byteLength, cap);
-        if (this.dialect === "tidb") {
-            await this.pool.query(`INSERT INTO ${this.table} (blob_hash, byte_len, bytes, created_at) VALUES (?,?,?,?) ON DUPLICATE KEY UPDATE created_at = VALUES(created_at)`, [hash, bytes.byteLength, Buffer.from(bytes), new Date()]);
+        const judged = await connectJudged(this.db, (facts) => {
+            const connection = { dialect: this.dialect, facts };
+            const cap = sqlBlobCapOf(this.explicitCapBytes, connection);
+            if (cap === undefined || bytes.byteLength <= cap.capBytes)
+                return undefined;
+            return { cap, packetBound: capBoundByPacketWall(cap, sqlWallsOf(connection)) };
+        }, (refusal) => refusal.packetBound, this.log);
+        if (judged.refusal !== undefined)
+            throw new BlobTooLargeError(bytes.byteLength, judged.refusal.cap);
+        try {
+            await judged.conn.query(this.dialect === "tidb"
+                ? `INSERT INTO ${this.table} (blob_hash, byte_len, bytes, created_at) VALUES (?,?,?,?) ON DUPLICATE KEY UPDATE created_at = VALUES(created_at)`
+                : `INSERT INTO ${this.table} (blob_hash, byte_len, bytes, created_at) VALUES ($1,$2,$3,$4) ON CONFLICT (blob_hash) DO UPDATE SET created_at = EXCLUDED.created_at`, [hash, bytes.byteLength, Buffer.from(bytes), new Date()]);
         }
-        else {
-            await this.pool.query(`INSERT INTO ${this.table} (blob_hash, byte_len, bytes, created_at) VALUES ($1,$2,$3,$4) ON CONFLICT (blob_hash) DO UPDATE SET created_at = EXCLUDED.created_at`, [hash, bytes.byteLength, Buffer.from(bytes), new Date()]);
+        finally {
+            judged.conn.release();
         }
     }
     async getBlob(hash) {

package/dist/plugins/breaker-state-sql.d.ts

@@ -6,7 +6,7 @@
  *
  * core's `createCircuitBreakerBrain` defaults to a per-PROCESS Map → on a multi-replica deployment
  * every replica re-discovers a provider outage independently (slow fleet-wide reaction). This backs
- * the breaker with the shared `circuit_breaker` table so a trip on one replica is learned by the others.
+ * the breaker with the shared `breaker_state` table so a trip on one replica is learned by the others.
  *
  * IMPORTANT — `BreakerState.get/set` are **synchronous** (core calls them on the hot path of every
  * brain invocation; a DB round-trip per call is untenable). So this is a **write-through cache**:
@@ -40,7 +40,7 @@ import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool, PoolClient } from "pg";
 import type { BreakerSnapshot, BreakerState } from "@sema-agent/core";
 import { type SqlDriver } from "./sql-driver.js";
-/** PG translation of the tidb-pool.ts `circuit_breaker` DDL (DATETIME(3)→TIMESTAMPTZ(3)). Disjoint from other
+/** PG translation of the tidb-pool.ts `breaker_state` DDL (DATETIME(3)→TIMESTAMPTZ(3)). Disjoint from other
  *  stores' tables, so a self-contained ensureSchema is safe (no central-schema shadowing). TiDB's DDL lives
  *  centrally in tidb-pool.ts (no PG-side twin needed there — production wires ONE ensureTidbSchema). */
 export declare const PG_BREAKER_STATE_SCHEMA: string[];

package/dist/plugins/breaker-state-sql.js

@@ -1,6 +1,6 @@
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 export const PG_BREAKER_STATE_SCHEMA = [
-    `CREATE TABLE IF NOT EXISTS circuit_breaker (
+    `CREATE TABLE IF NOT EXISTS breaker_state (
      breaker_key VARCHAR(190) COLLATE "C"   NOT NULL,
      phase       VARCHAR(16) COLLATE "C"    NOT NULL,
      failures    INTEGER        NOT NULL DEFAULT 0,
@@ -37,8 +37,8 @@ export class SqlBreakerState {
     }
     async writeThrough(key, snap) {
         try {
-            await this.db.query(this.q("INSERT INTO circuit_breaker (breaker_key, phase, failures, opened_at, updated_at) VALUES (?,?,?,?,?) " +
-                "ON DUPLICATE KEY UPDATE phase=VALUES(phase), failures=VALUES(failures), opened_at=VALUES(opened_at), updated_at=VALUES(updated_at)", "INSERT INTO circuit_breaker (breaker_key, phase, failures, opened_at, updated_at) VALUES ($1,$2,$3,$4,$5) " +
+            await this.db.query(this.q("INSERT INTO breaker_state (breaker_key, phase, failures, opened_at, updated_at) VALUES (?,?,?,?,?) " +
+                "ON DUPLICATE KEY UPDATE phase=VALUES(phase), failures=VALUES(failures), opened_at=VALUES(opened_at), updated_at=VALUES(updated_at)", "INSERT INTO breaker_state (breaker_key, phase, failures, opened_at, updated_at) VALUES ($1,$2,$3,$4,$5) " +
                 "ON CONFLICT (breaker_key) DO UPDATE SET phase=EXCLUDED.phase, failures=EXCLUDED.failures, opened_at=EXCLUDED.opened_at, updated_at=EXCLUDED.updated_at"), [key, snap.phase, snap.failures, snap.openedAt != null ? new Date(snap.openedAt) : null, new Date()]);
             this.pending.delete(key);
             if (this.writeFailStreak > 0) {
@@ -60,7 +60,7 @@ export class SqlBreakerState {
         try {
             const pendingAtStart = new Set(this.pending);
             const guarded = (key) => this.pending.has(key) || pendingAtStart.has(key);
-            const { rows } = await this.db.query("SELECT breaker_key, phase, failures, opened_at FROM circuit_breaker");
+            const { rows } = await this.db.query("SELECT breaker_key, phase, failures, opened_at FROM breaker_state");
             const seen = new Set();
             for (const r of rows) {
                 const key = String(r.breaker_key);

package/dist/plugins/caching-session-store.d.ts

@@ -4,6 +4,7 @@ import type { StagingHandle } from "../session-sync-kernel.js";
 import { type PlacementAcquireOpts } from "./session-placement.js";
 import type { InstructionSourceStore } from "../instruction-source-notice.js";
 import type { SessionFaceReader } from "../session-incarnation.js";
+import type { OwnerlessClaim } from "../delegated-session-owner.js";
 export interface CachingOptions {
     /** Idle seconds a woken session is kept warm. 0 disables caching (pure passthrough). */
     ttlSec: number;
@@ -59,6 +60,8 @@ export declare class CachingSessionStore implements SessionStore {
      *  (缓存的会话活得比「另一只店删掉又重建了这一行」长)。🔴 必须转发:k8s 工作区空间的每 run 读与起服门读的就是本类。 */
     readonly incarnationOf?: SessionStore["incarnationOf"];
     readonly register?: (sessionId: string, owner: string | null) => Promise<void>;
+    /** S-1770 委派继承律的认领口,纯转发(写的是行上的属主那一格 —— 只 CAS 子行自己,不碰暖缓存里的会话;停驻挂点在默认部署上读的就是本类 —— 与 `placementOf` 同转发同缺:内店记录委派树 ⇒ 两只都在)。 */
+    readonly claimOwnerless?: OwnerlessClaim;
     /** Delegated SessionRepo seam (§0.5) — list/fork/delete operate on the DURABLE tables directly (they bypass the
      *  warm cache by design; a fork/delete must read/write durable state, not a possibly-stale cached view). */
     readonly listSessions?: (opts: {

package/dist/plugins/caching-session-store.js

@@ -10,6 +10,7 @@ export class CachingSessionStore {
     sessionFaceOf;
     incarnationOf;
     register;
+    claimOwnerless;
     listSessions;
     fork;
     deleteSession;
@@ -57,6 +58,8 @@ export class CachingSessionStore {
             this.incarnationOf = inner.incarnationOf.bind(inner);
         if (ownerAware.register)
             this.register = ownerAware.register.bind(inner);
+        if (ownerAware.claimOwnerless)
+            this.claimOwnerless = ownerAware.claimOwnerless.bind(inner);
         if (ownerAware.listSessions)
             this.listSessions = ownerAware.listSessions.bind(inner);
         if (ownerAware.sessionSummaryOf)

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

@@ -37,6 +37,14 @@ export declare function tokenFingerprint(token: string): string;
  *  交给它、原样展开)。继承而不是在这里逐键再写一遍:core 给这一臂再加一位同类事实时,改的只有那张 Pick 表。 */
 export interface PendingCheckpoint extends ParkRowFacts {
     sessionId: string;
+    /**
+     * 这道停驻门的**非秘密稳定身份**(core `Checkpoint.checkpointId`,引擎每次停驻铸)—— 三处 durable 读面(本行 = `GET /v1/approvals` 的 `pending[]`
+     * 与 `/v1/approvals/stream` 的 `pending` 帧;停驻收件 `GET /v1/assistant/inbox` 的 `inbox[]`)共用的 **join 键**,也是 409 载体 A
+     * `pendingGate.checkpointId` / `terminal.paused.checkpointId` 的同一个值。**在场就是可信的那一个值,缺席就是缺席**:读法唯一 = `checkpoint-identity.ts` 的
+     * `durableRowIdentity`(过信任边界 —— 不含 token、有界),没有它的行(core 5.42.0 之前停驻的老行 / 没过边界的值)**照列**、键缺席(这一行没有可 join 的身份)、
+     * 每行计一次 `server.approvals.durable-row-checkpoint-id-missing`。两只店各读自己手里的那一份(SQL 孪生读 `checkpoint` 列的成员,LOCAL 孪生读 blob)。
+     */
+    checkpointId?: string;
     scope: string;
     toolName: string | null;
     toolCallId: string | null;
@@ -705,6 +713,12 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      * {@link SqlCheckpointStore.pendingRowQuery};语义与三态全文见 {@link PendingRowBinding} 顶注。
      * `scope` 传 `""`(空串)历史上与缺席同义(旧形 `scope ?` 真值判),这里逐字保留。
      */
+    /**
+     * 每一只**待决** checkpoint 的会话(去重)—— 审批账本留存律的挂靠源(`approval-ask-retention.ts`:待决 checkpoint = 一个还能动的停驻,
+     * 它的会话就是停驻那条腿上问行的 `source_task_id`)。**不按门型过滤**:运维队列 {@link listPending} 不列 `gate_kind` 读不出的行,
+     * 而决断口的令牌回落仍认它 —— 留存若跟着队列漏掉它,就会删掉一只还能被决的停驻的问。只读 `session_id`,不读 blob。
+     */
+    listPendingSessionIds(): Promise<string[]>;
     findPendingTokenBySession(sessionId: string, scope?: string, binding?: PendingRowBinding): Promise<CheckpointToken | null>;
     /**
      * 🔴 [ref] 车5 §9 C4 —— 流内审批对账收敛器判据 1 的**窄读口**(店面承载;收敛器本体不在本车)。

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

@@ -6,6 +6,7 @@ import { redactDeep, redactSecrets } from "../trace/redact.js";
 import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, RuleOfferRawSchema, backfillLegacyBatchMemberKind, parkRowFacts, screenUncoveredDetailSeat } from "../approval-card.js";
 import { assertJsonColumnWritable, createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, readJsonArrayColumn, readJsonObjectColumn, readNonNullJsonValueColumn, } from "./sql-json-column.js";
 import { recordFailOpen } from "../observability/fail-open.js";
+import { durableRowIdentity } from "../checkpoint-identity.js";
 import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "./sql-driver.js";
 import { isDupKeyError, isMissingColumnError, rowTooLargeOrSelf } from "./sql-errors.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
@@ -183,6 +184,18 @@ function readParkRowFactsCell(cell) {
     return parkRowFacts(pendingAction);
 }
 const PARK_ROW_PENDING_ACTION = { key: "pendingAction", as: "pending_action" };
+const PARK_ROW_CHECKPOINT_ID = { key: "checkpointId", as: "checkpoint_id" };
+const readCheckpointIdMemberBody = (body) => (typeof body === "string" ? { value: body } : { problem: "checkpointId is not a JSON string" });
+function readCheckpointIdCell(cell) {
+    try {
+        return decodeNullableJsonColumn(cell, readCheckpointIdMemberBody, "checkpoint.checkpoint $.checkpointId (operator queue row)");
+    }
+    catch (e) {
+        if (!isJsonColumnBodyProblem(e))
+            throw e;
+        return null;
+    }
+}
 const PARK_ROW_GATE = { key: "gate", as: "park_gate" };
 function readParkGateCell(cell) {
     try {
@@ -581,9 +594,9 @@ export class SqlCheckpointStore {
     }
     async listPending(scope) {
         const d = this.db.dialect;
-        const base = `SELECT c.session_id, c.scope, c.tool_name, c.tool_call_id, ${jsonColumnText(d, "tool_input")}, c.bound_input_hash, ` +
+        const base = `SELECT c.session_id, c.token, c.scope, c.tool_name, c.tool_call_id, ${jsonColumnText(d, "tool_input")}, c.bound_input_hash, ` +
             `${jsonColumnText(d, "risk_descriptor")}, ${jsonColumnText(d, "rule_suggestions")}, c.has_bidi_controls, c.created_at_ms, c.deadline, c.gate_kind, ta.task_id, ` +
-            `${jsonColumnText(d, "checkpoint", PARK_ROW_PENDING_ACTION)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_GATE)} ` +
+            `${jsonColumnText(d, "checkpoint", PARK_ROW_PENDING_ACTION)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_GATE)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_CHECKPOINT_ID)} ` +
             "FROM checkpoint c LEFT JOIN task_active ta ON ta.session_id = c.session_id WHERE c.status='pending'";
         const { rows } = scope
             ? await this.db.query(`${base}${this.q(" AND c.scope=?", " AND c.scope=$1")} ORDER BY c.created_at_ms ASC`, [scope])
@@ -599,6 +612,7 @@ export class SqlCheckpointStore {
             const approvalCard = parkedApprovalCard(parkedGateOfRow(r));
             return [{
                     sessionId: String(r.session_id),
+                    ...durableRowIdentity("approvals-queue", readCheckpointIdCell(r[PARK_ROW_CHECKPOINT_ID.as]), r.token),
                     scope: String(r.scope),
                     toolName,
                     toolCallId,
@@ -628,6 +642,10 @@ export class SqlCheckpointStore {
         }
         return out;
     }
+    async listPendingSessionIds() {
+        const { rows } = await this.db.query("SELECT DISTINCT session_id FROM checkpoint WHERE status='pending'", []);
+        return rows.map((r) => String(r.session_id));
+    }
     async findPendingTokenBySession(sessionId, scope, binding) {
         const { sql, params } = this.pendingRowQuery("token", sessionId, scope || undefined, binding);
         const { rows } = await this.db.query(sql, params);

package/dist/plugins/file-history-store-sql.d.ts

@@ -2,6 +2,7 @@ import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type FileHistoryRetentionPolicy, type ExecutionEnv, type FileHistoryStore, type FileHistoryResult, type FileHistoryTrackResult, type FileHistoryRestoreResult, type FileHistoryExport } from "@sema-agent/core";
 import { type BlobBackend } from "./blob-backend.js";
+import type { SyncBlobPutResult } from "./store-backend.js";
 import { type SqlDriver } from "./sql-driver.js";
 /** The file-history blob domain's SQL table (BlobBackend `table`/MinIO index binding + the A7 assert). */
 export declare const FILE_HISTORY_BLOB_TABLE = "file_history_blob";
@@ -147,8 +148,10 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
      *  Domain-isolated by construction (this store's blob table only — [ref] D1). Reaper-driven. */
     sweepOrphanBlobs(): Promise<number>;
     /** Upload ONE content-addressed blob ahead of an importHistory (§5 streamed negotiation). Store-level
-     *  integrity re-check (the route pre-verifies too — the internal caller might not). Never-throw. */
-    putBlob(hash: string, bytes: Uint8Array): Promise<FileHistoryResult>;
+     *  integrity re-check (the route pre-verifies too — the internal caller might not). Never-throw.
+     *  The SQL blob judge's refusal ({@link BlobTooLargeError}, judged on the connection that would have written the blob)
+     *  keeps its own code — the route answers it 413 (the sentence names that connection's walls), every other write failure 502 ("retry"). */
+    putBlob(hash: string, bytes: Uint8Array): Promise<SyncBlobPutResult>;
     getBlob(hash: string): Promise<Uint8Array | undefined>;
     /** The subset of `hashes` already present — one SQL INDEX probe (the import presence pre-check). */
     hasBlobs(hashes: string[]): Promise<Set<string>>;

package/dist/plugins/file-history-store-sql.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { captureFileBackupViaEnv, applyFileRestoreViaEnv, fileHistoryModeProvenDifferent, worldStillMatchesMint, boundaryPublishVerdict, fileHistoryDescribeTrackKey, fileHistoryTrackKeyOf, fileHistoryResolveTrackKey, fileHistoryExportDigest, validateFileHistoryExport, resolveFileHistoryRetention, fileHistoryBoundariesToKeep, } from "@sema-agent/core";
-import { SqlBlobBackend } from "./blob-backend.js";
+import { BlobTooLargeError, SqlBlobBackend } from "./blob-backend.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { isMissingColumnError } from "./sql-errors.js";
 import { recordFailOpen } from "../observability/fail-open.js";
@@ -594,6 +594,8 @@ export class SqlFileHistoryStore {
             return { ok: true };
         }
         catch (err) {
+            if (err instanceof BlobTooLargeError)
+                return { ok: false, error: { code: err.code, message: err.message, wallSource: err.cap.source } };
             return { ok: false, error: { code: "snapshot_failed", message: `putBlob ${hash} write/upload failed: ${discloseCaughtFailure(err)}` } };
         }
     }

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

@@ -1,6 +1,6 @@
 import { type UsageRow } from "../usage-analytics.js";
 import type { TaskStatus } from "@sema-agent/core";
-import { StoreBootRefusalError, type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
+import { StoreBootRefusalError, type FenceLanded, type InProcessClaimFence, type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
 import type { RunStoreCheckpointProbe } from "./memory-run-store.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 import { type SpaceCommitClaim, type SpaceCommitReading, type SpaceCommitState } from "../workspace-space-commit.js";
@@ -22,7 +22,7 @@ import { type SpaceCommitClaim, type SpaceCommitReading, type SpaceCommitState }
 export declare class RunStoreStrictHydrateError extends StoreBootRefusalError {
     readonly name = "RunStoreStrictHydrateError";
 }
-export declare class FileRunStore {
+export declare class FileRunStore implements InProcessClaimFence {
     private readonly runsDir;
     private readonly activeDir;
     private readonly tmpDir;
@@ -148,6 +148,8 @@ export declare class FileRunStore {
      *  [ref](codex R1 [medium]):认领 = 接管 `instanceId`(= 当前持有副本;SQL 孪生同注)。CAS 输不改。 */
     markResuming(taskId: string, instanceId: string): Promise<boolean>;
     getActiveTaskId(sessionId: string): Promise<string | undefined>;
+    /** 认领当写栅栏用(契约 = `store-contracts.ts` 的 `InProcessClaimFence`):判、刷新活性(同步落盘)与 `write` 是同一个同步段。 */
+    whileHoldingClaim(sessionId: string, taskId: string, write: () => FenceLanded): boolean;
     getRun(taskId: string): Promise<RunRecord | undefined>;
     /** Undo THIS submission's binding (key + body fingerprint → null) — called only where the submit surface refuses the submission
      *  before any work and terminalizes the row it just claimed (the sync leg's zero-work refusal, a device-placement reject):
@@ -161,17 +163,7 @@ export declare class FileRunStore {
     /** The run a submission's scoped `Idempotency-Key` names (the file twin of `uq_task_run_idem`), if any. */
     getRunByIdem(idemKey: string): Promise<RunRecord | undefined>;
     /** Runs newest-first, keyset on (createdAt, taskId) DESC; optional exact-match filters (owner is exact, like the SQL). */
-    listRuns(opts: {
-        status?: string;
-        jobId?: string;
-        source?: string;
-        owner?: string;
-        cursor?: {
-            createdAt: string;
-            taskId: string;
-        };
-        limit: number;
-    }): Promise<RunRecord[]>;
+    listRuns(opts: RunListQuery): Promise<RunRecord[]>;
     /**
      * S-297 —— 这个会话**最近一条腿**的窄指针({@link SqlRunStore.latestRunForSession} 的孪生:同一个排序口径
      *  `createdAt DESC, taskId DESC`,与本店 {@link FileRunStore.listSessions} 挑 `rn=1` 那一行的比较器逐字同一份)。

package/dist/plugins/file-run-store.js

@@ -525,6 +525,15 @@ export class FileRunStore {
     async getActiveTaskId(sessionId) {
         return this.active.get(sessionId);
     }
+    whileHoldingClaim(sessionId, taskId, write) {
+        const r = this.runs.get(taskId);
+        if (this.active.get(sessionId) !== taskId || r === undefined || r.status !== "running")
+            return false;
+        r.updatedAt = new Date();
+        this.persist(r);
+        write();
+        return true;
+    }
     async getRun(taskId) {
         const r = this.runs.get(taskId);
         return r ? this.toRecord(r) : undefined;

package/dist/plugins/fork-routing-session-store.d.ts

@@ -24,6 +24,7 @@
  * (requireExisting 的 host-first 重试仍落对店),中途 touch/noteTaskRun 缺路由=落 transient(no-op 级)。
  */
 import { type SessionStore, type AcquiredSession, type SessionStoreSummary, type SessionPlacement, type PlacedSessionRow } from "@sema-agent/core";
+import { type DelegationTree } from "../delegated-session-owner.js";
 /** acquire 选项形(core 5.48 SessionStore 契约):[ref] placement=受信 spawner 的分区建会话声明。 */
 type AcquireOpts = {
     requireExisting?: boolean;
@@ -85,8 +86,15 @@ export declare class ForkRoutingSessionStore implements SessionStore {
      *     unpin 不落错店)。
      *
      * 已在 host(路由或真行)⇒ 幂等直返。两店都无此会话 ⇒ 抛(调用方=park veto,诚实 fail-closed)。
+     *
+     * S-1770:宿主行**在建行那一笔里**带属主 `owner` —— 调用方按委派继承律算好(`delegated-session-owner.ts`:委派树根的属主,
+     * 推不出 ⇒ 孤行哨兵;`tree` = 判据读到的委派树,判断用:宿主行记着别的树 ⇒ 拒),这里经宿主店的首写登记写下、再按律定夺(core `register` 契约:登记不判授权,判在复读)。
+     * 宿主店里同 id 已有一行:记着这一棵委派树且无主 ⇒ 按同一条律认领(只有记录委派树的店);别的树的 / 属主不是它(别人先认领的空壳,或 local 店的无主空壳)⇒ 抛(停驻否决),
+     * 转录不拷进别人的行;宿主店记不了 / 读不回属主 ⇒ 同样抛 —— 晋升出一只无主的转录行就是把它交给任何拿到 id 的人。
      */
-    promoteToHost(sessionId: string): Promise<void>;
+    promoteToHost(sessionId: string, owner: string | null, tree: DelegationTree): Promise<void>;
+    /** 晋升的建行那一笔(S-1770,规则见 {@link promoteToHost} 头注):宿主店首写登记 `owner`,然后按律定下宿主行的属主(与停驻快路同一只 `settleDelegatedOwner`)。 */
+    private registerPromotedOwner;
     fork(sourceId: string, owner?: string | null): Promise<string | null>;
     get size(): number;
     dispose(): void | Promise<void>;

package/dist/plugins/fork-routing-session-store.js

@@ -1,5 +1,6 @@
 import { SessionError } from "@sema-agent/core";
 import { recordFailOpen } from "../observability/fail-open.js";
+import { delegatedOwnerHostOf, settleDelegatedOwner } from "../delegated-session-owner.js";
 const ROUTE_MAX = 8192;
 export class ForkRoutingSessionStore {
     host;
@@ -170,7 +171,7 @@ export class ForkRoutingSessionStore {
     list() {
         return this.transient.list?.() ?? Promise.resolve([]);
     }
-    async promoteToHost(sessionId) {
+    async promoteToHost(sessionId, owner, tree) {
         if (this.promoted.has(sessionId))
             return;
         if (this.route.get(sessionId) === "host") {
@@ -190,6 +191,7 @@ export class ForkRoutingSessionStore {
         }
         const entries = await src.session.getEntries();
         const leaf = await src.session.getLeafId();
+        await this.registerPromotedOwner(sessionId, owner, tree);
         const dst = await this.host.acquire(sessionId);
         try {
             const storage = dst.session.getStorage();
@@ -217,6 +219,15 @@ export class ForkRoutingSessionStore {
         this.promoted.add(sessionId);
         this.remember(sessionId, "host");
     }
+    async registerPromotedOwner(sessionId, owner, tree) {
+        const register = this.host.register;
+        const host = delegatedOwnerHostOf(this.host);
+        if (register === undefined || host === undefined) {
+            throw new Error(`session "${sessionId}" cannot be promoted: the host session store cannot record or read back a session owner (register / ownerOf / sessionFaceOf; placementOf and claimOwnerless together or neither), so the promoted transcript would land ownerless`);
+        }
+        await register.call(this.host, sessionId, owner);
+        await settleDelegatedOwner(host, sessionId, owner, tree);
+    }
     async fork(sourceId, owner) {
         const routed = this.route.get(sourceId);
         const tryFork = async (store, where) => {

package/dist/plugins/host-platform.d.ts

@@ -34,6 +34,8 @@
 import type { ChildProcess } from "node:child_process";
 import { killProcessTree, type BackgroundHardKillOutcome } from "@sema-agent/core";
 import type { Logger } from "../observability/logger.js";
+/** 平台读点全仓一处(`test/host-shell-settle-order.test.ts` 源码钉);别处要平台串从这里取,不直读 Node 的平台字段。 */
+export declare const HOST_PLATFORM: NodeJS.Platform;
 export declare const IS_WIN32: boolean;
 export interface HostShell {
     shell: string;

package/dist/plugins/host-platform.js

@@ -1,7 +1,8 @@
 import os from "node:os";
 import { getShellConfig, killProcessTree, signalProcessTree } from "@sema-agent/core";
 import { redactSecrets } from "../trace/redact.js";
-export const IS_WIN32 = process.platform === "win32";
+export const HOST_PLATFORM = process.platform;
+export const IS_WIN32 = HOST_PLATFORM === "win32";
 const POSIX_SH_FALLBACK = { shell: "/bin/sh", args: ["-c"] };
 let cachedPosixShell;
 let winShellState = { kind: "unsettled" };

package/dist/plugins/local-checkpoint-store.d.ts

@@ -98,6 +98,8 @@ export declare class LocalCheckpointStore {
     /** All still-pending checkpoints across the registered scopes (summary + full row via get). */
     private pendings;
     /** Operator approval queue — the same NON-secret card as the SQL twins (never the token). */
+    /** 每一只待决 checkpoint 的会话(去重;不按门型过滤 —— 理由与 SQL 孪生 `listPendingSessionIds` 逐字同,见那里)。 */
+    listPendingSessionIds(): Promise<string[]>;
     listPending(scope?: string): Promise<PendingCheckpoint[]>;
     /**
      * [ref]:与 SQL 孪生**同判**的 session 键读口 —— `binding.gateKinds` 过滤门型、序恒「最新优先,token 兜平局」