@sema-agent/server 7.75.4 → 7.76.1

package/dist/plugins/approval-nonce-store.js

@@ -0,0 +1,126 @@
+import { join } from "node:path";
+import { atomicWriteFile, ensureDir, readJsonlRecords, AppendLog } from "@sema-agent/core";
+import { mysqlDriver, pgDriver, sqlDbNowMs, SQL_DB_NOW_MS } from "./sql-driver.js";
+import { isDupKeyError } from "./sql-errors.js";
+export const APPROVAL_NONCE_TABLE = "approval_nonce";
+export const MAX_APPROVAL_NONCE_CHARS = 190;
+export class SqlApprovalNonceStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    q(tidb, pg) {
+        return this.db.dialect === "tidb" ? tidb : pg;
+    }
+    async nowMs() {
+        return sqlDbNowMs(this.db, APPROVAL_NONCE_TABLE);
+    }
+    async consume(sessionId, nonce, expiresAtMs) {
+        try {
+            await this.db.query(this.q(`INSERT INTO ${APPROVAL_NONCE_TABLE} (session_id, nonce, consumed_at_ms, expires_at_ms) VALUES (?,?,${SQL_DB_NOW_MS.tidb},?)`, `INSERT INTO ${APPROVAL_NONCE_TABLE} (session_id, nonce, consumed_at_ms, expires_at_ms) VALUES ($1,$2,${SQL_DB_NOW_MS.pg},$3)`), [sessionId, nonce, expiresAtMs]);
+            return true;
+        }
+        catch (err) {
+            if (isDupKeyError(this.db.dialect, err))
+                return false;
+            throw err;
+        }
+    }
+    async reapExpired() {
+        const res = await this.db.query(this.q(`DELETE FROM ${APPROVAL_NONCE_TABLE} WHERE expires_at_ms <= ${SQL_DB_NOW_MS.tidb}`, `DELETE FROM ${APPROVAL_NONCE_TABLE} WHERE expires_at_ms <= ${SQL_DB_NOW_MS.pg}`), []);
+        return res.affected;
+    }
+}
+export class TiDBApprovalNonceStore extends SqlApprovalNonceStore {
+    constructor(pool) {
+        super(mysqlDriver(pool));
+    }
+}
+export class PgApprovalNonceStore extends SqlApprovalNonceStore {
+    constructor(pool) {
+        super(pgDriver(pool));
+    }
+}
+const keyOf = (sessionId, nonce) => JSON.stringify([sessionId, nonce]);
+export class MemoryApprovalNonceStore {
+    rows = new Map();
+    async nowMs() {
+        return Date.now();
+    }
+    async consume(sessionId, nonce, expiresAtMs) {
+        const k = keyOf(sessionId, nonce);
+        if (this.rows.has(k))
+            return false;
+        this.rows.set(k, expiresAtMs);
+        return true;
+    }
+    async reapExpired() {
+        const now = await this.nowMs();
+        let n = 0;
+        for (const [k, exp] of this.rows) {
+            if (exp <= now) {
+                this.rows.delete(k);
+                n++;
+            }
+        }
+        return n;
+    }
+}
+export class FileApprovalNonceStore {
+    path;
+    tmpDir;
+    rows = new Map();
+    log;
+    constructor(root) {
+        const dir = join(root, "approval-nonces");
+        ensureDir(dir);
+        this.tmpDir = join(dir, ".tmp");
+        ensureDir(this.tmpDir);
+        this.path = join(dir, "consumed.jsonl");
+        for (const r of readJsonlRecords(this.path)) {
+            if (!r || typeof r.s !== "string" || typeof r.n !== "string" || typeof r.e !== "number")
+                continue;
+            this.rows.set(keyOf(r.s, r.n), { s: r.s, n: r.n, e: r.e });
+        }
+    }
+    logFor() {
+        return (this.log ??= new AppendLog(this.path));
+    }
+    async nowMs() {
+        return Date.now();
+    }
+    async consume(sessionId, nonce, expiresAtMs) {
+        const k = keyOf(sessionId, nonce);
+        if (this.rows.has(k))
+            return false;
+        const record = { s: sessionId, n: nonce, e: expiresAtMs };
+        this.logFor().append(record, true);
+        this.rows.set(k, record);
+        return true;
+    }
+    async reapExpired() {
+        const nowMs = await this.nowMs();
+        const survivors = [];
+        let removed = 0;
+        for (const record of this.rows.values()) {
+            if (record.e <= nowMs) {
+                removed++;
+                continue;
+            }
+            survivors.push(record);
+        }
+        if (removed === 0)
+            return 0;
+        this.log?.closeForSwap();
+        atomicWriteFile(this.tmpDir, this.path, survivors.map((r) => `${JSON.stringify(r)}\n`).join(""));
+        for (const [k, record] of [...this.rows])
+            if (record.e <= nowMs)
+                this.rows.delete(k);
+        return removed;
+    }
+    dispose() {
+        this.log?.close();
+        this.log = undefined;
+    }
+}
+//# sourceMappingURL=approval-nonce-store.js.map

package/dist/plugins/permission-rule-store-sql.d.ts

@@ -250,30 +250,6 @@ export type RuleTicketReclaimResult = {
  * 廉价,重铸一张即可(core [ref] 建议的姿态)。
  */
 export declare const RULE_IMPORT_TICKET_GC_GRACE_MS: number;
-/**
- * [ref] A7 —— **数据库自己的钟**(毫秒),两方言各一句(codex 交叉轮 R5-F1,验真后修)。
- *
- * 用处:`settled_at_ms` 的写入与清扫「已落定」那一支的截止**必须在同一个钟域**。它们此前各拿各副本的
- * 墙钟:落定那台若比跑清扫那台慢过一个宽限(本仓 [ref]③ 记过一次真实的 11 分钟 NTP 纠正),一份**刚刚**
- * 生出来的权威回执下一拍就被删,而"落定之后必有一个完整的回放窗"是本批新许下的承诺 —— 它不能建立在
- * 「两台机器的钟差不多」这条没人声明过的假设上。数据库的钟是这两台副本**唯一**共享的那口钟。
- *
- * 🔴 射程收官([ref] / [ref],2026-09-02):**这张票上的每一个时刻量都走本钟**,一个不剩 ——
- * `consumed_at_ms` / `settled_at_ms`(R8-F2 起)、`expires_at_ms` / `created_at_ms`(本批)。
- *
- * 本批补上的是 **TTL 轴**,也是最后一条:铸票 `expires_at_ms = <本钟> + ttl`、判定
- * `expires_at_ms > <本钟>`、清扫 `expires_at_ms <= <本钟> − 宽限`。修前那一形是**两台副本各出一半**的
- * 比较(铸票副本的墙钟定到期时刻,兑付副本的墙钟做判定),于是 TTL 在集群上**不单调**:同一张票在钟慢
- * 的那台上还活着、在钟快的那台上已经死了;极端形是「出生即过期」(铸票副本慢过一个 TTL ⇒ 票铸出来就
- * 没人兑得动)。这不需要故障就能发作 —— 负载均衡把 prepare 与 redeem 分到两台副本是**常态**。
- * 上一批的进程内单调锚只覆盖「同一副本铸、同一副本兑」那一格,连同它的台账在本批一并删除。
- *
- * 判定读不到本钟 ⇒ 语句抛错 ⇒ 调用方按不确定失败处置(fail-closed:绝不退回本地墙钟放行)。
- */
-export declare const SQL_DB_NOW_MS: {
-    readonly tidb: "CAST(UNIX_TIMESTAMP(NOW(3)) * 1000 AS SIGNED)";
-    readonly pg: "(EXTRACT(EPOCH FROM clock_timestamp()) * 1000)::bigint";
-};
 /** prepare 时刻候选集的规范摘要(载荷绑定 F1 ④ 的判据)。纯数据 ⇒ `build*`。
  *
  *  🔴 入参型收到 core 的 `RuleCandidate`(core 7.9.0 [ref] 起含 `behavior`)—— 规则的身份是
@@ -294,12 +270,7 @@ export declare class SqlRuleImportTicketStore {
     private readonly db;
     constructor(db: SqlDriver);
     private q;
-    /**
-     * 问一次**数据库自己的钟**(毫秒)。铸票用它当基准,于是到期时刻与后续每一次判定同域。
-     *
-     * 读不出数 ⇒ **响亮抛**([ref] fail-closed):静默兜个本地 `Date.now()` 正是本批要删掉的那条腿,
-     * 而一次「钟读不出来」在授权面上是运维事件,不是一个可以猜的默认值。
-     */
+    /** 问一次**数据库自己的钟**(毫秒,{@link sqlDbNowMs})。铸票用它当基准,于是到期时刻与后续每一次判定同域。 */
     private dbNowMs;
     /**
      * 铸一张票。

package/dist/plugins/permission-rule-store-sql.js

@@ -1,7 +1,7 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { z } from "zod";
 import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, parseRuleText, readRowBehavior, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_BEHAVIORS, RULE_SYNC_DROP_CODES, EMPTY_DURABLE_RULE_PARTITION, } from "@sema-agent/core";
-import { dialectProtocolJsonEncoder } from "./sql-driver.js";
+import { dialectProtocolJsonEncoder, sqlDbNowMs, SQL_DB_NOW_MS } from "./sql-driver.js";
 import { isMissingColumnError } from "./sql-errors.js";
 import { canonicalJson } from "../canonical-json.js";
 import { EDITED_RULE_BREADTH_WARNING_CODES, PERSISTED_RULE_MATCHES, isPersistedRuleTool, RULE_APPROVAL_RECORD_SCHEMA, UNCOVERED_SEGMENT_REASONS } from "../permission-rule-vocab.js";
@@ -624,10 +624,6 @@ export class SqlRuleApprovalRecordStore {
     }
 }
 export const RULE_IMPORT_TICKET_GC_GRACE_MS = 10 * 60_000;
-export const SQL_DB_NOW_MS = {
-    tidb: "CAST(UNIX_TIMESTAMP(NOW(3)) * 1000 AS SIGNED)",
-    pg: "(EXTRACT(EPOCH FROM clock_timestamp()) * 1000)::bigint",
-};
 export function buildRulePayloadHash(candidates) {
     return createHash("sha256").update(canonicalJson(candidates), "utf8").digest("hex");
 }
@@ -640,11 +636,7 @@ export class SqlRuleImportTicketStore {
         return this.db.dialect === "tidb" ? tidbSql : pgSql;
     }
     async dbNowMs() {
-        const { rows } = await this.db.query(this.q(`SELECT ${SQL_DB_NOW_MS.tidb} AS db_now_ms`, `SELECT ${SQL_DB_NOW_MS.pg} AS db_now_ms`), []);
-        const n = Number(rows[0]?.["db_now_ms"] ?? Number.NaN);
-        if (!Number.isFinite(n))
-            throw new Error(`${PERMISSION_RULE_TICKET_TABLE}: the database clock came back unreadable (${String(rows[0]?.["db_now_ms"])})`);
-        return n;
+        return sqlDbNowMs(this.db, PERMISSION_RULE_TICKET_TABLE);
     }
     async mint(input) {
         const nowMs = await this.dbNowMs();

package/dist/plugins/pg-pool.js

@@ -125,6 +125,14 @@ export const PG_SCHEMA_STATEMENTS = [
      created_at TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (session_id, tool_name)
    )`,
+    `CREATE TABLE IF NOT EXISTS approval_nonce (
+     session_id     VARCHAR(64) COLLATE "C"    NOT NULL,
+     nonce          VARCHAR(190) COLLATE "C"   NOT NULL,
+     consumed_at_ms BIGINT         NOT NULL,
+     expires_at_ms  BIGINT         NOT NULL,
+     PRIMARY KEY (session_id, nonce)
+   )`,
+    `CREATE INDEX IF NOT EXISTS idx_approval_nonce_expires ON approval_nonce (expires_at_ms)`,
     `CREATE TABLE IF NOT EXISTS sendfile_link (
      id         VARCHAR(64) COLLATE "C"    NOT NULL,
      scope      VARCHAR(190) COLLATE "C"   NOT NULL,

package/dist/plugins/pg-session-storage.js

@@ -49,6 +49,7 @@ export const PG_SESSION_SCHEMA = [
      PRIMARY KEY (session_id, seq)
    )`,
     `CREATE UNIQUE INDEX IF NOT EXISTS uq_session_event_entry ON session_event (session_id, entry_id)`,
+    `CREATE INDEX IF NOT EXISTS idx_session_event_type ON session_event (session_id, type, seq)`,
 ];
 export async function ensureSchema(pool) {
     for (const stmt of PG_SESSION_SCHEMA)

package/dist/plugins/sql-driver.d.ts

@@ -158,6 +158,33 @@ export interface SqlEngineFacts {
     /** TiDB's session `tidb_txn_mode`; `null` = this engine has no such indicator (NOT "optimistic"). */
     readonly txnMode: "pessimistic" | null;
 }
+/**
+ * **数据库自己的钟**(毫秒),两方言各一句 —— 本仓这口钟在 SQL 面的**唯一**铸点([ref] A7 / [ref] /
+ * 合并复审 R2 把 S-280 的 nonce 店并进来)。
+ *
+ * 用处永远是同一条:**一个时刻量的铸造点与它的判定点必须在同一个钟域**。副本各拿各的墙钟时,两台机器
+ * 之间的偏差没有任何一条腿强制过上界(本仓 [ref]③ 记过一次真实的 11 分钟 NTP 纠正),于是
+ * 「A 铸的东西 B 判着还活着」这类承诺就建立在一条没人声明过的假设上。数据库的钟是一组副本**唯一**
+ * 共享的那口钟,所以每一条「谁生谁死」的判决都落到它身上:
+ *  · 规则导入票(`permission-rule-store-sql.ts`):`expires_at_ms` 的铸造 / 判定 / 清扫三处;
+ *  · 直连门 plan_review 的消费记录(`approval-nonce-store.ts`):受理窗的判定与记录的清扫。
+ *
+ * 读不到本钟 ⇒ 语句抛错 ⇒ 调用方按不确定失败处置([ref] fail-closed:**绝不**退回本地墙钟放行)。
+ *
+ * 它住在 driver 这只叶子模块里,是因为「这个引擎怎么说『现在几点』」是**方言事实**,与任何一只店无关;
+ * 放在某一只店里会让下一个需要它的店要么 import 一整只无关的店、要么自己抄一份(抄出来的两份会漂)。
+ */
+export declare const SQL_DB_NOW_MS: {
+    readonly tidb: "CAST(UNIX_TIMESTAMP(NOW(3)) * 1000 AS SIGNED)";
+    readonly pg: "(EXTRACT(EPOCH FROM clock_timestamp()) * 1000)::bigint";
+};
+/**
+ * 问一次 {@link SQL_DB_NOW_MS} —— 所有需要「库钟此刻」的店共用这**一份**读法。
+ *
+ * `subject` 只进错误文案(出问题时运维要知道是哪一张表的判决卡住了)。读不出数 ⇒ **响亮抛**:
+ * 一次「钟读不出来」在授权面上是运维事件,不是一个可以猜的默认值,更不是掉回 `Date.now()` 的理由。
+ */
+export declare function sqlDbNowMs(db: SqlDriver, subject: string): Promise<number>;
 export interface SqlDriver extends SqlExec {
     readonly dialect: SqlDialect;
     /**

package/dist/plugins/sql-driver.js

@@ -1,4 +1,16 @@
 import { pgSafeJsonStringify, pgProtocolJsonStringify } from "./pg-safe-json.js";
+export const SQL_DB_NOW_MS = {
+    tidb: "CAST(UNIX_TIMESTAMP(NOW(3)) * 1000 AS SIGNED)",
+    pg: "(EXTRACT(EPOCH FROM clock_timestamp()) * 1000)::bigint",
+};
+export async function sqlDbNowMs(db, subject) {
+    const sql = db.dialect === "tidb" ? `SELECT ${SQL_DB_NOW_MS.tidb} AS db_now_ms` : `SELECT ${SQL_DB_NOW_MS.pg} AS db_now_ms`;
+    const { rows } = await db.query(sql, []);
+    const n = Number(rows[0]?.["db_now_ms"] ?? Number.NaN);
+    if (!Number.isFinite(n))
+        throw new Error(`${subject}: the database clock came back unreadable (${String(rows[0]?.["db_now_ms"])})`);
+    return n;
+}
 function mysqlResult(r) {
     if (Array.isArray(r))
         return { rows: r, affected: 0 };

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

@@ -8,6 +8,7 @@ import { type OneTimeMigrationReport } from "./one-time-migrations.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";
 import { type ApprovalExemptionStore } from "./approval-exemption-store.js";
+import { type ApprovalNonceStore } from "./approval-nonce-store.js";
 import { type ApprovalAskStore as ApprovalAskStoreType } from "./approval-ask-store-sql.js";
 import { type MemoryOptOutGrantStore } from "./memory-optout-grant-store-sql.js";
 import { type SendFileLedger } from "./send-file-ledger.js";
@@ -39,6 +40,7 @@ export type RunStore = TiDBRunStore | PgRunStore | FileRunStore;
  *  FileResumeAnchorStore is the FILE-backed local twin (P0.5 variant-1; survives restart). */
 export type ResumeAnchorStore = TiDBResumeAnchorStore | PgResumeAnchorStore | FileResumeAnchorStore;
 export type { ApprovalExemptionStore } from "./approval-exemption-store.js";
+export type { ApprovalNonceStore } from "./approval-nonce-store.js";
 /** [ref]([ref] v3.1 §3.0-§3.2 流内审批协议持久层):`ApprovalAskStore` 接口 + 行/补丁类型。
  *  车3 刀 3a 起 `StoreBackend.approvalAsk()` 已在(见接口体的那条注)。 */
 export type { ApprovalAskStore, AskRow, NewAskRow, AskTransitionPatch, DecideAskInput, DecideResult, ExpireResult, BindGateInput, BatchRow, AskDecision } from "./approval-ask-store-sql.js";
@@ -147,6 +149,10 @@ export interface StoreBackend {
     /** Per-session per-toolName approval exemption ("本会话不再询问") — an approval MEMORY the F4
      *  ask-gate consults after deny/neverAuto. REQUIRED on all backends (works local, like resumeAnchor). */
     approvalExemption(): ApprovalExemptionStore;
+    /** S-280 直连门审批证明的一次性消费记录(`plan_review` 的 nonce)。REQUIRED on all backends —— 与
+     *  `approvalExemption` 同姿势:tidb/pg = SQL 双方言(单类双语句),local = File 追加日志 + 压实。
+     *  **不能**退化成进程内易失形:一次重启若把记录抹掉,JWT TTL 窗内的重放就复活了,而那正是本店要关的洞。 */
+    approvalNonce(): ApprovalNonceStore;
     /** [ref]([ref] §3.0-§3.2)流内审批协议持久层:每个流内工具调用一行的 ask 状态机 + 批行。
      *  REQUIRED on all backends — tidb/pg = SQL 双方言 twin;local = {@link InMemoryApprovalAskStore}。
      *

package/dist/plugins/store-backend.js

@@ -12,6 +12,7 @@ import { LocalSessionStore } from "./local-session-store.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";
 import { TiDBApprovalExemptionStore, PgApprovalExemptionStore, FileApprovalExemptionStore } from "./approval-exemption-store.js";
+import { TiDBApprovalNonceStore, PgApprovalNonceStore, FileApprovalNonceStore } from "./approval-nonce-store.js";
 import { TiDBApprovalAskStore, PgApprovalAskStore } from "./approval-ask-store-sql.js";
 import { InMemoryApprovalAskStore } from "./approval-ask-store-memory.js";
 import { TiDBMemoryOptOutGrantStore, PgMemoryOptOutGrantStore } from "./memory-optout-grant-store-sql.js";
@@ -112,6 +113,7 @@ class TiDBBackend {
     run() { return new TiDBRunStore(this.pool); }
     resumeAnchor() { return new TiDBResumeAnchorStore(this.pool); }
     approvalExemption() { return new TiDBApprovalExemptionStore(this.pool); }
+    approvalNonce() { return new TiDBApprovalNonceStore(this.pool); }
     approvalAsk() { return new TiDBApprovalAskStore(this.pool); }
     permissionRule() { return createSqlPermissionRuleStores(mysqlDriver(this.pool)); }
     sendFileLedger() { return new TiDBSendFileLedger(this.pool); }
@@ -159,6 +161,7 @@ class PgBackend {
     run() { return new PgRunStore(this.pool); }
     resumeAnchor() { return new PgResumeAnchorStore(this.pool); }
     approvalExemption() { return new PgApprovalExemptionStore(this.pool); }
+    approvalNonce() { return new PgApprovalNonceStore(this.pool); }
     approvalAsk() { return new PgApprovalAskStore(this.pool); }
     permissionRule() { return createSqlPermissionRuleStores(pgDriver(this.pool)); }
     sendFileLedger() { return new PgSendFileLedger(this.pool); }
@@ -200,6 +203,7 @@ class LocalBackend {
     sessionStore;
     resumeAnchorStore;
     approvalExemptionStore;
+    approvalNonceStore;
     approvalAskStore = new InMemoryApprovalAskStore();
     sendFileLedgerStore;
     workflowJournalStore;
@@ -238,6 +242,7 @@ class LocalBackend {
         });
         this.resumeAnchorStore = new FileResumeAnchorStore(this.fileBackend.root);
         this.approvalExemptionStore = new FileApprovalExemptionStore(this.fileBackend.root);
+        this.approvalNonceStore = new FileApprovalNonceStore(this.fileBackend.root);
         this.sendFileLedgerStore = new FileSendFileLedger(this.fileBackend.root);
         this.workflowJournalStore = new FileWorkflowJournalStore(this.fileBackend.root);
         this.outcomeSinkInst = new FileOutcomeSink(this.fileBackend.root);
@@ -255,6 +260,7 @@ class LocalBackend {
         this.runStore.dispose();
         this.resumeAnchorStore.dispose();
         this.approvalExemptionStore.dispose();
+        this.approvalNonceStore.dispose();
         this.sendFileLedgerStore.dispose();
         this.workflowJournalStore.dispose();
         this.checkpointStoreInst?.close();
@@ -264,6 +270,7 @@ class LocalBackend {
     run() { return this.runStore; }
     resumeAnchor() { return this.resumeAnchorStore; }
     approvalExemption() { return this.approvalExemptionStore; }
+    approvalNonce() { return this.approvalNonceStore; }
     approvalAsk() { return this.approvalAskStore; }
     permissionRule() {
         if (!this.permissionRuleStoresInst) {

package/dist/plugins/tidb-pool.js

@@ -69,7 +69,24 @@ export const SCHEMA_STATEMENTS = [
      payload     JSON        NOT NULL,
      ts          DATETIME(3) NOT NULL,
      PRIMARY KEY (session_id, seq),
-     UNIQUE KEY uq_session_event_entry (session_id, entry_id)
+     UNIQUE KEY uq_session_event_entry (session_id, entry_id),
+     -- S-284(7.76.0):「本会话按 seq 倒序的最新一条某 type 事件」这一**类**读法的访问路径。
+     -- 列序 = 等值前缀 (session_id, type) + 排序列 seq。
+     --  · **热路径(本索引的存在理由)**:computeFloor 的 type = 'compaction' ORDER BY seq DESC LIMIT 1 ——
+     --    每次 wake 的第一条 SQL。缺这条路径时两库都退化成**整会话扫**:TiDB 按 PK 取整 session 区间
+     --    (keep order:false)把 N 行 ~1KB payload 全读进 cop 侧 TopN(实测 N=100 → 10000:0.91ms → 30.91ms);
+     --    PG 的规划器随表变大从 Index Scan Backward 翻成 Bitmap Heap Scan、再翻成 Seq Scan + Sort
+     --    (0.23ms → 1.42ms)。于是「每轮热读 = floor 之上那 ~30 行」这条 §1.5 承诺被第一条 SQL 单方面毁掉。
+     --    补上之后两库都是一次索引定位 + 一行回表:TiDB IndexRangeScan keep order:true, desc + cop Limit 1
+     --    (1.04 / 0.90 / 0.87ms),PG Index Scan Backward(0.23 / 0.21 / 0.21ms)—— 与 N 无关。
+     --  · **冷路径(**只有 PG 实测吃到**,如实登记)**:getEpochAnchor 的
+     --    seq < ? AND type IN ('prompt_epoch','compaction') ORDER BY seq DESC LIMIT 100。实测(N=10058、
+     --    58 条候选):PG 走 Index Scan + 小 Sort,2.04ms → 0.49ms;**TiDB 在 pseudo 统计下不选这条索引**,
+     --    计划仍是整会话 TableRangeScan keep order:true, desc + cop Selection —— 与无索引时同一个计划。
+     --    不在本版加方言索引提示(那是一条特判,且该路径是 rewind 切在 kept tail 内才走的冷回退,不是每轮热读)。
+     -- 写路径代价(实测,非估计):多一条二级索引项 ⇒ TiDB 单行 append p50 1.34 → 1.58ms、10058 行批量装载
+     -- 845 → 952ms;PG 单行 append p50 0.82 → 0.80ms(噪声内)、批量装载 375 → 405ms。
+     KEY idx_session_event_type (session_id, type, seq)
    ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS task_run (
      -- ⚠️ 表级 COLLATE 的**非键列**影响(#192 A11,codex 复审 2026-08-08 round2 点名——先前"只有
@@ -298,6 +315,14 @@ export const SCHEMA_STATEMENTS = [
      granted_by VARCHAR(190) NULL,
      created_at DATETIME(3)  NOT NULL,
      PRIMARY KEY (session_id, tool_name)
+   ) COLLATE utf8mb4_bin`,
+    `CREATE TABLE IF NOT EXISTS approval_nonce (
+     session_id     VARCHAR(64)  NOT NULL,
+     nonce          VARCHAR(190) NOT NULL,
+     consumed_at_ms BIGINT       NOT NULL,
+     expires_at_ms  BIGINT       NOT NULL,
+     PRIMARY KEY (session_id, nonce),
+     KEY idx_approval_nonce_expires (expires_at_ms)
    ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS sendfile_link (
      id         VARCHAR(64)  NOT NULL,

package/dist/plugins/tidb-session-storage.d.ts

@@ -1,5 +1,9 @@
 import { BaseSessionStorage, type PromptEpochDescriptor, type SessionMetadata, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
+export declare const SESSION_EVENT_LATEST_BY_TYPE_SQL: {
+    readonly floor: "SELECT /*+ USE_INDEX(session_event, idx_session_event_type) */ payload FROM session_event WHERE session_id = ? AND type = 'compaction' ORDER BY seq DESC LIMIT 1";
+    readonly epochAnchor: "SELECT /*+ USE_INDEX(session_event, idx_session_event_type) */ seq, payload FROM session_event WHERE session_id = ? AND seq < ? AND type IN ('prompt_epoch','compaction') ORDER BY seq DESC LIMIT 100";
+};
 /**
  * TiDB-backed {@link BaseSessionStorage} — the durable L1 event log for one session.
  *

package/dist/plugins/tidb-session-storage.js

@@ -3,6 +3,11 @@ import { BaseSessionStorage, SessionError, leafIdAfterEntry, normalizePromptEpoc
 import { toIso } from "./sql-row-helpers.js";
 import { isMysqlDupKeyError } from "./sql-errors.js";
 import { PLACEMENT_SELECT_COLUMNS, placementFromRow } from "./session-placement.js";
+const SESSION_EVENT_BY_TYPE_HINT = "/*+ USE_INDEX(session_event, idx_session_event_type) */";
+export const SESSION_EVENT_LATEST_BY_TYPE_SQL = {
+    floor: `SELECT ${SESSION_EVENT_BY_TYPE_HINT} payload FROM session_event WHERE session_id = ? AND type = 'compaction' ORDER BY seq DESC LIMIT 1`,
+    epochAnchor: `SELECT ${SESSION_EVENT_BY_TYPE_HINT} seq, payload FROM session_event WHERE session_id = ? AND seq < ? AND type IN ('prompt_epoch','compaction') ORDER BY seq DESC LIMIT 100`,
+};
 const isDupKey = isMysqlDupKeyError;
 export class TiDBSessionStorage extends BaseSessionStorage {
     pool;
@@ -19,7 +24,7 @@ export class TiDBSessionStorage extends BaseSessionStorage {
             return undefined;
         let cursor = this.floorSeq;
         for (;;) {
-            const [rows] = await this.pool.query("SELECT seq, payload FROM session_event WHERE session_id = ? AND seq < ? AND type IN ('prompt_epoch','compaction') ORDER BY seq DESC LIMIT 100", [this.sessionId, cursor]);
+            const [rows] = await this.pool.query(SESSION_EVENT_LATEST_BY_TYPE_SQL.epochAnchor, [this.sessionId, cursor]);
             if (rows.length === 0)
                 return undefined;
             for (const r of rows) {
@@ -44,7 +49,7 @@ export class TiDBSessionStorage extends BaseSessionStorage {
         return new TiDBSessionStorage(pool, sessionId, metadata, entries, meta.leaf_id ?? null, floorEntryId, floorSeq);
     }
     static async computeFloor(pool, sessionId) {
-        const [compRows] = await pool.query("SELECT payload FROM session_event WHERE session_id = ? AND type = 'compaction' ORDER BY seq DESC LIMIT 1", [sessionId]);
+        const [compRows] = await pool.query(SESSION_EVENT_LATEST_BY_TYPE_SQL.floor, [sessionId]);
         if (!compRows[0])
             return { floorEntryId: null, floorSeq: 0 };
         const comp = (typeof compRows[0].payload === "string" ? JSON.parse(compRows[0].payload) : compRows[0].payload);

package/dist/principal-jwt.d.ts

@@ -1,4 +1,15 @@
 import type { ApprovalHmacKey, PrincipalJwtKey } from "./auth-keys.js";
+/**
+ * 验签允许的**时钟不一致容差**(秒)—— 本仓这条轴上的单一来源。
+ *
+ * 它回答的是**一跳**:签发方(issuer)与判定这份 token 的那口钟可以差多少(exp/nbf 门的宽限)。
+ *
+ * 🔴 它**不**回答「两台副本之间差多少」:S-280 的消费记录不再靠任何钟差上界活着 —— 受理窗的判定、
+ * 落地后的复核、到期清扫三处读的是**同一口钟**(消费记录店自己的钟,见
+ * `plugins/approval-nonce-store.ts` 的 `nowMs()`)。曾经由本常量推导出的那个「副本间钟差」常量已
+ * 整条删除:它是一条**猜出来的**上界,没有任何一条腿强制它,而正确的修法是根本不需要这个数。
+ */
+export declare const PRINCIPAL_JWT_CLOCK_SKEW_SEC = 30;
 /**
  * [ref] D-G: verify a compact JWS principal token. Returns the crypto-verified principal (`sub`) + the
  * channel-binding (`bnd`) on success, or `null` on ANY failure (caller fail-closes — NEVER falls back to a header).
@@ -14,15 +25,62 @@ export declare function verifyPrincipalJwt(token: string, keys: PrincipalJwtKey[
 }): {
     sub: string;
     bnd?: string;
+    acceptedBeforeMs: number;
 } | null;
 /** The channel-binding value a direct client's principal JWT must carry in `cnf.bnd`: the hex SHA-256 of the
  *  CLIENT-VISIBLE action identity (sessionId + boundCallId + boundInputHash — NOT the unexposed checkpointToken).
  *  Binds the identity assertion to THIS specific suspended action so a captured JWT cannot be lifted onto another. */
+/**
+ * 直连门信封**第三槽**的 plan_review 半场:**决定所作用内容的哈希**。
+ *
+ * 第三槽在两种门上是**同一条规则**「这份决定作用在哪份内容上」:动作门填被批工具调用的 `boundInputHash`
+ * (core 铸);非动作门 `plan_review` 的 `edit` 填**修订后的计划**的哈希(计划随本次请求一起提交,签名器手上
+ * 就有原文),`approve` / `reject` 不作用于任何新内容 ⇒ null。B-121(test 黑盒发现,验真后修):此前 edit 也填
+ * null,于是为「只改 README」签出的证明可以拿去提交任意 `editedPlan`——签名只护住了 decision/reason,没护住
+ * 决定真正落地的那份内容。`cnf.bnd` 与 HMAC 都吃第三槽,所以 JWT 与信封同时绑住它;不匹配 ⇒
+ * `401 principal_unbound`(既有码,cnf.bnd 不符)。旧注记「计划哈希被拒」说的是 approve(worker 没有可哈希的
+ * 原文),不覆盖 edit。
+ *
+ * 形:`sha256(utf8(editedPlan))` hex —— 与 `approvalBnd` 同摘要、同编码;逐字节,不归一化(签名器与 worker
+ * 必须对同一串字节达成一致,任何"归一化"都是第二个写者)。
+ */
+/** 良构 Unicode(无孤立代理项)。`u` 旗下配对代理项是一个码点、不匹配 `\p{Surrogate}`;只有孤立的才命中。 */
+export declare function isWellFormedUnicode(s: string): boolean;
+export declare function editedPlanBinding(editedPlan: string): string;
 export declare function approvalBnd(env: {
     sessionId: string;
     boundCallId?: string | null;
     boundInputHash?: string | null;
 }): string;
+/**
+ * 一次性凭据:这份证明**必须被消费掉一次**才算数,以及它的消费记录该活到什么时候。
+ * 只有非动作门(plan_review)的证明带它 —— 动作门的一次性由 checkpointToken 给(见 {@link verifyDirectDoorProof})。
+ */
+export interface SingleUseProof {
+    /** 签名器为这一次决定新铸的随机值(= 信封第 2 位 `boundCallId`,同时进 `cnf.bnd` 与 HMAC)。 */
+    readonly nonce: string;
+    /**
+     * 这份证明**不再被受理**的时刻(epoch ms,**开区间上界**:`店钟 >= 它` ⇒ 验签已经不收它)。
+     * 一个值、两处用,所以它们不可能漂:
+     *  · 消费记录的到期列逐字落它 —— 清理腿的删除线就是**店钟**,没有任何余量、也不需要;
+     *  · 消费**落地之后**的复核线(再问一次店钟)—— 消费是一次跨网络的写,验签发生在它之前。
+     *
+     * 🔴 「它」与「店钟」必须是同一口钟:本值由 `verifyPrincipalJwt` 从 `exp + skew` 算出,而那一关的
+     * `nowSec` 由调用方从**店钟**喂进来(`routes/approvals-assistant.ts`)。
+     */
+    readonly acceptedBeforeMs: number;
+}
+/** {@link verifyDirectDoorProof} 的判决。`singleUse` 在场 = 调用方必须在改任何状态**之前**消费它一次。 */
+export type DirectDoorProofResult = {
+    ok: true;
+    principal: string;
+    singleUse?: SingleUseProof;
+} | {
+    ok: false;
+    status: number;
+    errorCode: string;
+    error: string;
+};
 /**
  * [ref] D-G: verify the WHOLE direct-door proof for one /decide — the signed principal JWT (identity) + its
  * cnf.bnd channel-binding + the HMAC envelope (integrity) — and return the CRYPTO-VERIFIED principal, or a typed
@@ -30,13 +88,22 @@ export declare function approvalBnd(env: {
  * verify principal → bind → mac-present → mac-valid (so a non-operator never gets a MAC oracle, an unverified
  * caller never reaches the operator list).
  *
+ * 🔴 `opts.nowSec`(S-280 / 合并复审 R2):受理窗要按**哪口钟**判。非动作门(plan_review)的反重放是
+ * 一条**消费记录**,而那条记录的生死由**消费记录店的钟**决定 —— 所以那条腿必须把店钟喂进来
+ * (`floor(店钟/1000)`),否则「还受理 ⇒ 记录还在」就退化成「两台副本的钟差不多」这条没人声明过的假设。
+ * 缺席 = 本机墙钟,这对动作门(`/decide`)是对的:它的反重放是 checkpointToken 的一次性,不牵扯第二台
+ * 机器上的一张行。
+ *
  * 🔴 `opts.actionBinding`: the boundCallId/boundInputHash action-binding is `policy_ask`-
  * SPECIFIC (a pending TOOL call). A NON-ACTION gate — `plan_review` (and any review-pause) — `binds NO action`
  * (core checkpoint-store.ts: pendingAction `{kind:"plan_review"}`, editedPlan is a typed sibling that binds no
  * action), so the proof correctly DEGRADES to "verify WHO": JWT identity + cnf.bnd channel-binding + the HMAC over
- * {sessionId, decision} (bound fields null) — WITHOUT requiring a boundInputHash. Pass `actionBinding:false` for a
- * non-action gate; the default (true) keeps the /decide tool-approval contract byte-identical. Binding the decision
- * to a plan HASH was REJECTED (the plan artifact lives in a profile ref store; the worker has no TOCTOU original).
+ * {sessionId, nonce, <content hash>, decision, reason}. Pass `actionBinding:false` for a non-action gate; the default
+ * (true) keeps the /decide tool-approval contract byte-identical. The THIRD slot carries one rule on both gates —
+ * "the content this decision acts on": the bound tool input for /decide, `editedPlanBinding(editedPlan)` for a
+ * plan_review `edit` (B-121), null for approve/reject. Binding approve/reject to a hash of the EXISTING plan was
+ * rejected (the plan artifact lives in a profile ref store; the worker has no TOCTOU original) — that ruling never
+ * covered `edit`, whose content arrives with the request.
  */
 export declare function verifyDirectDoorProof(proof: {
     jwt?: string;
@@ -56,13 +123,6 @@ export declare function verifyDirectDoorProof(proof: {
     approvalHmacKeys: ApprovalHmacKey[];
 }, opts?: {
     actionBinding?: boolean;
-}): {
-    ok: true;
-    principal: string;
-} | {
-    ok: false;
-    status: number;
-    errorCode: string;
-    error: string;
-};
+    nowSec?: number;
+}): DirectDoorProofResult;
 //# sourceMappingURL=principal-jwt.d.ts.map

package/dist/principal-jwt.js

@@ -1,5 +1,6 @@
 import { createHash, createPublicKey, verify as cryptoVerify } from "node:crypto";
 import { verifyApprovalHmac } from "./approval-hmac.js";
+export const PRINCIPAL_JWT_CLOCK_SKEW_SEC = 30;
 function b64urlToBuf(s) {
     return Buffer.from(s, "base64url");
 }
@@ -61,15 +62,23 @@ export function verifyPrincipalJwt(token, keys, expect) {
     if (typeof payload.sub !== "string" || payload.sub.length === 0)
         return null;
     const now = expect.nowSec ?? Math.floor(Date.now() / 1000);
-    const skew = expect.skewSec ?? 30;
-    if (typeof payload.exp !== "number" || payload.exp + skew < now)
+    const skew = expect.skewSec ?? PRINCIPAL_JWT_CLOCK_SKEW_SEC;
+    if (typeof payload.exp !== "number" || !Number.isFinite(payload.exp) || payload.exp + skew < now)
         return null;
-    if (payload.nbf !== undefined && (typeof payload.nbf !== "number" || payload.nbf - skew > now))
+    if (payload.nbf !== undefined && (typeof payload.nbf !== "number" || !Number.isFinite(payload.nbf) || payload.nbf - skew > now))
         return null;
     if (expect.maxTtlSec && payload.exp - now > expect.maxTtlSec + skew)
         return null;
     const bnd = typeof payload.cnf?.bnd === "string" ? payload.cnf.bnd : undefined;
-    return { sub: payload.sub, bnd };
+    return { sub: payload.sub, bnd, acceptedBeforeMs: (Math.floor(payload.exp + skew) + 1) * 1000 };
+}
+export function isWellFormedUnicode(s) {
+    return !/\p{Surrogate}/u.test(s);
+}
+export function editedPlanBinding(editedPlan) {
+    if (!isWellFormedUnicode(editedPlan))
+        throw new Error("editedPlanBinding: editedPlan is not well-formed Unicode (lone surrogate) — utf8 hashing would be lossy");
+    return createHash("sha256").update(editedPlan, "utf8").digest("hex");
 }
 export function approvalBnd(env) {
     return createHash("sha256").update(JSON.stringify([env.sessionId, env.boundCallId ?? null, env.boundInputHash ?? null])).digest("hex");
@@ -78,11 +87,16 @@ export function verifyDirectDoorProof(proof, envelope, config, opts) {
     const actionBinding = opts?.actionBinding ?? true;
     if (!proof.jwt)
         return { ok: false, status: 401, errorCode: "principal_unverified", error: "direct door requires a signed principal token (X-Approval-Principal-Token)" };
-    const verified = verifyPrincipalJwt(proof.jwt, config.principalJwtPubkeys, { iss: config.principalJwtIss ?? "\0", aud: config.principalJwtAud ?? "\0", maxTtlSec: config.principalJwtMaxTtlSec });
+    const verified = verifyPrincipalJwt(proof.jwt, config.principalJwtPubkeys, { iss: config.principalJwtIss ?? "\0", aud: config.principalJwtAud ?? "\0", maxTtlSec: config.principalJwtMaxTtlSec, nowSec: opts?.nowSec });
     if (!verified)
         return { ok: false, status: 401, errorCode: "principal_unverified", error: "principal token failed verification" };
-    if (actionBinding && !envelope.boundInputHash)
-        return { ok: false, status: 400, errorCode: "approval_mac_required", error: "direct door requires boundInputHash (the bound action) in the body" };
+    if (actionBinding) {
+        if (!envelope.boundInputHash)
+            return { ok: false, status: 400, errorCode: "approval_mac_required", error: "direct door requires boundInputHash (the bound action) in the body" };
+    }
+    else if (!envelope.boundCallId) {
+        return { ok: false, status: 400, errorCode: "approval_nonce_required", error: "direct door requires a single-use nonce in boundCallId for a non-action gate (sign it into cnf.bnd and the HMAC envelope; see ASSISTANT-WIRE-CONTRACT §6.1/§6.2)" };
+    }
     if (verified.bnd !== approvalBnd(envelope))
         return { ok: false, status: 401, errorCode: "principal_unbound", error: "principal token is not bound to this decision (cnf.bnd mismatch)" };
     if (!proof.mac)
@@ -90,6 +104,8 @@ export function verifyDirectDoorProof(proof, envelope, config, opts) {
     const ok = verifyApprovalHmac({ sessionId: envelope.sessionId, boundCallId: envelope.boundCallId ?? null, boundInputHash: envelope.boundInputHash ?? null, decision: envelope.decision, reason: envelope.reason ?? null }, proof.mac, proof.kid, config.approvalHmacKeys);
     if (!ok)
         return { ok: false, status: 401, errorCode: "approval_mac_invalid", error: "approval envelope MAC invalid" };
-    return { ok: true, principal: verified.sub };
+    return actionBinding
+        ? { ok: true, principal: verified.sub }
+        : { ok: true, principal: verified.sub, singleUse: { nonce: envelope.boundCallId, acceptedBeforeMs: verified.acceptedBeforeMs } };
 }
 //# sourceMappingURL=principal-jwt.js.map

package/dist/tool-approval.d.ts

@@ -468,7 +468,8 @@ export type RuleRefusalReason = Extract<CardRulePersisted, {
  *  部署整条车道判死。 */
  | "rule_governance_forced"
 /**
- * [ref]:**这一行**没有可铸规则的素材 —— durable(PARKED)迟到决议腿专属。
+ * [ref]:**这一行**没有可铸规则的素材。原为 durable(PARKED)迟到决议腿专属;自 live 腿也接上素材闸起**两腿同词**
+ * (第四条成因:命令含脱敏器认得的凭据形 ⇒ 素材整只扣下,两腿同谓词)。
  *
  * 成因闭集(三条,处置相同):①这只 ask 从没进过规则车道(治理档 / 无属主 / 引擎没铸候选 / args 里
  * 读不出命令原字节)⇒ `rule_command` 列 NULL;②行由**加这两列之前**的构建落下;③行上的卡读不回来