@sema-agent/server 7.75.3 → 7.76.0

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/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,6 +25,7 @@ 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).
@@ -23,6 +35,35 @@ export declare function approvalBnd(env: {
     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,6 +71,12 @@ 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
@@ -56,13 +103,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,15 @@ 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 approvalBnd(env) {
     return createHash("sha256").update(JSON.stringify([env.sessionId, env.boundCallId ?? null, env.boundInputHash ?? null])).digest("hex");
@@ -78,11 +79,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 +96,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;②行由**加这两列之前**的构建落下;③行上的卡读不回来

package/dist/tool-approval.js

@@ -31,10 +31,13 @@ const DEFAULT_PARK_TOMBSTONE_MAX = 2000;
 const DEFAULT_PARK_TOMBSTONE_TTL_MS = 60 * 60_000;
 const DEFAULT_PARK_TOMBSTONE_PER_PRINCIPAL_MAX = 128;
 const PARKING_RETRY_AFTER_MS = 250;
+function ruleMaterialCarriesCredentialShape(command) {
+    return redactSecrets(command, { observe: false }) !== normalizeForRedaction(command);
+}
 function durableRuleMaterial(material) {
     if (material === undefined)
         return { ruleCommand: null, ruleScopeRoot: null };
-    if (redactSecrets(material.command, { observe: false }) !== normalizeForRedaction(material.command)) {
+    if (ruleMaterialCarriesCredentialShape(material.command)) {
         defaultLogger.warn("approval rule material withheld: the adjudicated command carries credential-shaped bytes", {
             commandChars: material.command.length,
         });
@@ -1799,6 +1802,10 @@ export class ToolApprovalCoordinator {
             return withFlag(false, "rule_store_error");
         if (inputWasEdited)
             return withFlag(false, "rule_input_edited");
+        if (ruleMaterialCarriesCredentialShape(material.command)) {
+            defaultLogger.warn("approval rule material withheld on the live leg: the adjudicated command carries credential-shaped bytes", { commandChars: material.command.length });
+            return withFlag(false, "rule_material_absent");
+        }
         if (persistRule.kind === "batch") {
             const offer = material.offers[persistRule.batchOfferIndex];
             if (offer === undefined || offer.kind !== "batch")

package/dist/trace/redact.d.ts

@@ -28,10 +28,13 @@
  * `redactModelText`(四座同调:结果两叶经 `redactTerminalResult`,账本两行经 `redactLedgerEventData`);
  * 它定的是**写回**判据(认出凭据形才改字节、抛则占位),不是第二张规则表。
  *
- * 两组臂,顺序即优先序:{@link FULL_SECRET_PATTERNS}(完整形)在前,{@link FRAGMENT_SECRET_PATTERNS}
- * ([ref] 前缀残片,上游先截后脱的产物 ⇒ 带 `:partial` 后缀的 token)在后。
- * ⚠️ **一个例外,自 7.75.2**:完整臂里的**裸形段**内部没有优先序 —— 该段全臂一次收候选跨度、解重叠、一次替换
- * ({@link shapeSectionRule}),段内臂序对输出无语义。段**之间**的先后照旧是契约。
+ * 臂分**三段 + 一个候选池**,段之间的先后是契约(上下文越多越靠前):结构段(PEM/URL/JSON + 三条体扫描器)
+ * → 词法关键字段(`Bearer`/`Basic`/`token`)→ **候选池** → URL 收尾归一化。
+ * ⚠️ **池内没有优先序,自 7.76.0**:{@link SHAPE_SECRET_PATTERNS}(裸形八条)与 {@link FRAGMENT_SECRET_PATTERNS}
+ * ([ref] 前缀残片八条,上游先截后脱的产物 ⇒ 带 `:partial` 后缀的 token)并进**同一个**候选池
+ * ({@link armPoolRule}):全臂看同一份未改写文本收候选跨度 → 不动点 → 并集律解重叠 → 一次替换,
+ * **池内臂序对输出无语义**(7.75.2 只做到裸形一段,残片段仍逐臂改写 ⇒ S-282 的两条漏形)。
+ * 左边界律因此有**三种**边界:非词内字符 ∨ 转义分隔单元尾 ∨ **一枚已收候选跨度的尾**(= 凭据尾)。
  */
 /** 本模块替换 token 的**闭形**正则源(`«redacted»` / `«redacted:aws-key»` / `«redacted:gh-token:partial»` …):
  *  URL-userinfo 臂用它把「用户名位上已经是本模块 token」整个当一个用户名单元吃掉。模块加载时对