@sema-agent/server 7.147.0 → 7.148.0

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

@@ -1,5 +1,6 @@
 import { admitSessionPlacement, compareOccupants } from "@sema-agent/core";
 import { placementCapabilityOf } from "./session-placement.js";
+import { birthFaceOf, withdrawFaceOf } from "./session-birth.js";
 export class CachingSessionStore {
     inner;
     cache = new Map();
@@ -8,13 +9,17 @@ export class CachingSessionStore {
     timer;
     onStaleHit;
     headOf;
+    deletionHeadOf;
     register;
+    registerWithReceipt;
+    withdrawBirth;
     listSessions;
     listSessionRows;
     fork;
     forkTo;
     executionPlacement;
     deleteSession;
+    sessionDeletion;
     sessionSummaryOf;
     writeSessionRowCells;
     setTitleIfNull;
@@ -55,8 +60,24 @@ export class CachingSessionStore {
         if (typeof innerPlacementOf === "function")
             this.placementOf = (id) => innerPlacementOf.call(inner, id);
         const ownerAware = inner;
+        if (ownerAware.deletionHeadOf)
+            this.deletionHeadOf = ownerAware.deletionHeadOf.bind(inner);
         if (ownerAware.register)
             this.register = ownerAware.register.bind(inner);
+        const birth = birthFaceOf(inner);
+        if (birth !== undefined)
+            this.registerWithReceipt = birth.registerWithReceipt;
+        const withdraw = withdrawFaceOf(inner);
+        if (withdraw !== undefined) {
+            this.withdrawBirth = async (b, ownTaskId) => {
+                try {
+                    return await withdraw.withdrawBirth(b, ownTaskId);
+                }
+                finally {
+                    this.evict(b.sessionId);
+                }
+            };
+        }
         if (ownerAware.listSessions)
             this.listSessions = ownerAware.listSessions.bind(inner);
         if (ownerAware.listSessionRows)
@@ -130,10 +151,28 @@ export class CachingSessionStore {
             this.sweepStagingSessions = ownerAware.sweepStagingSessions.bind(inner);
         if (ownerAware.deleteSession) {
             const del = ownerAware.deleteSession.bind(inner);
-            this.deleteSession = async (sessionId, owner) => {
-                const removed = await del(sessionId, owner);
-                this.evict(sessionId);
-                return removed;
+            this.deleteSession = async (sessionId, owner, token, legs) => {
+                try {
+                    return await del(sessionId, owner, token, legs);
+                }
+                finally {
+                    this.evict(sessionId);
+                }
+            };
+        }
+        if (ownerAware.sessionDeletion) {
+            const face = ownerAware.sessionDeletion;
+            this.sessionDeletion = {
+                fence: async (sessionId, owner, fenceOpts) => {
+                    try {
+                        return await face.fence(sessionId, owner, fenceOpts);
+                    }
+                    finally {
+                        this.evict(sessionId);
+                    }
+                },
+                holds: (sessionId, token) => face.holds(sessionId, token),
+                pending: () => face.pending(),
             };
         }
         const interval = opts.sweepIntervalMs ?? Math.min(this.ttlMs || 60_000, 60_000);

package/dist/plugins/checkpoint-index-columns.d.ts

@@ -22,7 +22,7 @@
  * (`approval_card`,不是 facet —— 存一份 facet 会在 core 改表那天陈旧),谓词由那两张表机械生成({@link CHECKPOINT_FACET_CASES} → {@link CHECKPOINT_FACET_SQL}),
  * 逐行与 `facetOf` 同答(`test/checkpoint-index-columns.test.ts` B 节、db 组同名文件)。本仓不写第二份判据:没有手写门型表、没有手写卡词。
  * 卡那一侧不带「是不是审批门」的合取:列上的卡只在审批门上非 NULL(同一只派生),与 core 对生成谓词的成文形逐字相同。未登记门型 / NULL 门型 ⇒ 表达式 NULL(无 ELSE)。
- * 拒扫腿的选行序见 {@link CHECKPOINT_SWEEP_ORDER_SQL}:卡列有词的行先取 —— 混跑窗里旧副本写的行卡列为空,它们的 facet 要等下一次起服的 M29 才确证。
+ * 拒扫腿的选行序与游标谓词见 {@link CHECKPOINT_SWEEP_ORDER_SQL} / {@link checkpointSweepAfterSql}:截止、token 两键;拒扫按游标轮转走过期集,没有哪一行能替它后面的行占住窗。
  *
  * ## 谓词什么时候开
  * core 的迁移条款:存量行的卡列由同一只函数回填,并且只在部署自己记下「回填跑完了」之后才开生成谓词。本仓的记录 = 起服序列:M29 跑在一次性迁移段
@@ -100,6 +100,27 @@ export declare class CheckpointIndexRefusedError extends Error {
     readonly refusal: CheckpointIndexRefusal;
     constructor(sessionId: unknown, refusal: CheckpointIndexRefusal);
 }
+/**
+ * **一张卡归在哪只会话上**(`checkpoint.host_session_id` 列;local 孪生 = 归属索引的同一个事实)—— 兑现这张卡的那条 run 的会话:续跑链(决断、取消、
+ * 停驻收割、续跑输入回收、运维队列行的 run 联结)按它把卡与 run 连起来,本服务在会话上找卡的每一个读口只读它。只在写口 `put` 求值一次;
+ * 存量行由一次性迁移 M49 自 `session_id` 回填一次。卡自己的 `session_id`(那条腿的对话)仍在行上,只答「这是哪段对话」(问账匹配、问账留存锚、会话擦除)。
+ *
+ * 读法 = core 卡上的组合腿 `CheckpointState.compositionLeg`(闭集 `entry`;加一个词 ⇒ 本 `switch` 编译红,由人决定那种腿的卡归谁):
+ *  · `cascade` —— 梯子的一级:级跑在自己现铸的会话里,卡归**调用方的会话**(腿上的 `hostSessionId`;续跑入口 `resumeCascade` 接着爬梯子);
+ *  · `verify`  —— 验证器自己的腿:本服务兑现不了它(结算时当场作废,`verifier-pause-card.ts`),卡归它**自己的**会话 —— 不挂到宿主 run 上;
+ *  · 没有组合腿 —— 不是组合入口交出的腿(普通 run、verify 的实现腿与修复轮、委派子代):卡归它自己的会话。
+ * 组合腿形坏(不是对象 / `hostSessionId` 不是非空串 / 闭集外的词)⇒ 抛 {@link CheckpointHostSessionRefusedError},写口零写(引擎铸不出这样的卡;只来自嵌入方 / 手改数据)。
+ */
+export declare function hostSessionOf(cp: Pick<Checkpoint, "sessionId" | "state">): string;
+/** 写口对一张说不出归属的卡的拒(零写;理由见 {@link hostSessionOf})。店错误,不是 wire 码。 */
+export declare class CheckpointHostSessionRefusedError extends Error {
+    constructor(sessionId: unknown, why: string);
+}
+/**
+ * `host_session_id` 列的定义(两方言建表各插一处;列定义的唯一属主)。可空:存量库缺列 ⇒ 起服列册对账拒启并给 `ADD COLUMN` 句;存量行由 M49 回填,
+ * 写口恒写非空值。NULL 只剩一种来历:滚动升级窗里旧副本写下、还没被下一次起服的 M49 补上的行 —— 按会话的读口找不到它(见 MIGRATION 本版那一条)。
+ */
+export declare const CHECKPOINT_HOST_SESSION_COLUMN: Readonly<Record<SqlDialect, string>>;
 /** facet 的词(core 登记表 `facet` 列的值域)。 */
 type Facet = (typeof PAUSE_REGISTRY)[GateKind]["facet"];
 /** 生成谓词的一条 WHEN:某一列的值落在这几个词里 ⇒ 这个 facet。 */
@@ -121,10 +142,16 @@ export declare const CHECKPOINT_FACET_CASES: readonly FacetCase[];
  */
 export declare const CHECKPOINT_FACET_SQL: Readonly<Record<SqlDialect, string>>;
 /**
- * SLA 拒扫腿(`listExpiredApprovalGates`)的选行序:**卡列有词的行先取**,其后 deadline、token。卡列为 NULL 的审批行有两种来历 —— 引擎没给卡的门(照常是审批 SLA),或混跑窗里
- * 不认这一列的旧副本写的行(可能是引擎要拒收 `sla_timeout` 的问答卡,facet 要等下一次起服的 M29 回填才确证);列上没有任何东西能把两者分开,所以不在谓词里猜,而在序里:
- * 有卡词的行 facet 已确证,先占窗;卡列为空的行排在它们之后,各自仍按 deadline 升序。LIMIT 仍是调用方的界,不加旋钮。两方言同一句(`CASE` 在 MySQL 协议与 PG 上同形)。
+ * SLA 拒扫腿(`listExpiredApprovalGates`)的选行序:deadline、token 两键升序(两方言同一句)。拒扫按这个序**轮转**:每拍从上一拍读到的最后一行之后接着读一页
+ * ({@link checkpointSweepAfterSql}),一页不满就回到队首 —— 所以序只决定「一圈里谁先谁后」,不决定「谁轮得到」:一行在这一拍被拒、被跳过、留在停驻,
+ * 游标照样越过它,排在它后面的行下一拍就轮到。修前每拍只取序最前的一页,重新停驻、截止不变的行积满一页就把后面所有到期审批挡到收割;为挡住其中一种
+ * (混跑窗里旧副本写的卡列为空的行)曾把「卡列为空的排后」加成第一键 —— 轮转之后那一种与其余各种同样挡不住任何行,那一键退役。
+ */
+export declare const CHECKPOINT_SWEEP_ORDER_SQL = "deadline ASC, token ASC";
+/**
+ * 拒扫游标的「之后」谓词:严格在游标 `(deadline, token)` 之后 —— 与 {@link CHECKPOINT_SWEEP_ORDER_SQL} 同两键、同方向、同一把比较尺子(列自己的排序规则),
+ * 序与谓词住在一处:改了序必须同改这里,否则游标会跳行或重行。`ph(i)` = 第 i 个游标参数的占位符;参数依次是游标的 deadline、deadline、token。
  */
-export declare const CHECKPOINT_SWEEP_ORDER_SQL = "CASE WHEN approval_card IS NULL THEN 1 ELSE 0 END ASC, deadline ASC, token ASC";
+export declare function checkpointSweepAfterSql(ph: (i: 0 | 1 | 2) => string): string;
 export {};
 //# sourceMappingURL=checkpoint-index-columns.d.ts.map

package/dist/plugins/checkpoint-index-columns.js

@@ -64,6 +64,38 @@ export class CheckpointIndexRefusedError extends Error {
         this.refusal = refusal;
     }
 }
+export function hostSessionOf(cp) {
+    const leg = cp.state?.compositionLeg;
+    if (leg === undefined)
+        return cp.sessionId;
+    if (typeof leg !== "object" || leg === null)
+        throw new CheckpointHostSessionRefusedError(cp.sessionId, "its composition leg is not an object");
+    const { entry, hostSessionId } = leg;
+    switch (entry) {
+        case "cascade":
+            if (typeof hostSessionId !== "string" || hostSessionId === "")
+                throw new CheckpointHostSessionRefusedError(cp.sessionId, "its cascade leg names no host session");
+            return hostSessionId;
+        case "verify":
+            return cp.sessionId;
+        case undefined:
+            throw new CheckpointHostSessionRefusedError(cp.sessionId, "its composition leg names no entry");
+        default: {
+            const unknownEntry = entry;
+            throw new CheckpointHostSessionRefusedError(cp.sessionId, `its composition leg names an entry this build does not know (${JSON.stringify(unknownEntry)})`);
+        }
+    }
+}
+export class CheckpointHostSessionRefusedError extends Error {
+    constructor(sessionId, why) {
+        super(`the checkpoint row for session ${JSON.stringify(sessionId) ?? "(none)"} was not written: ${why}, so the session it is filed under cannot be read`);
+        this.name = "CheckpointHostSessionRefusedError";
+    }
+}
+export const CHECKPOINT_HOST_SESSION_COLUMN = Object.freeze({
+    mysql: "host_session_id VARCHAR(190) NULL",
+    pg: `host_session_id VARCHAR(190) COLLATE "C"`,
+});
 function groupByFacet(pairs, column) {
     const groups = new Map();
     for (const [word, facet] of pairs) {
@@ -87,5 +119,8 @@ export const CHECKPOINT_FACET_SQL = Object.freeze({
     mysql: renderFacetCase((column) => `CAST(${column} AS BINARY)`),
     pg: renderFacetCase((column) => column),
 });
-export const CHECKPOINT_SWEEP_ORDER_SQL = "CASE WHEN approval_card IS NULL THEN 1 ELSE 0 END ASC, deadline ASC, token ASC";
+export const CHECKPOINT_SWEEP_ORDER_SQL = "deadline ASC, token ASC";
+export function checkpointSweepAfterSql(ph) {
+    return `(deadline > ${ph(0)} OR (deadline = ${ph(1)} AND token > ${ph(2)}))`;
+}
 //# sourceMappingURL=checkpoint-index-columns.js.map

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

@@ -3,8 +3,9 @@
  * (运维队列 / 审批决断 / 续跑腿 / 流内审批收敛器 / 起服普查)共同读的那一层 —— 引擎的 `CheckpointStore` 契约之外、本服务自己定的东西:
  *  · 行形:运维队列行 {@link PendingCheckpoint}、流内审批候选行 {@link CheckpointAskCandidate}、已决回放行 {@link DecidedApprovalRecord};
  *  · 读口的行绑定 {@link PendingRowBinding} 与门型两分({@link LIVE_RUN_GATE_KINDS} / {@link TERMINAL_PARK_GATE_KINDS}),两孪生同序判据 {@link pendingRowPrecedes};
- *  · 两孪生同调的纯判据与投影:{@link queueRowGateKind}、{@link boundedToolInput}、{@link boundedRuleOffers}、
- *    {@link approvalDecisionOfWinner}、{@link candidateIdentityOf};常量 {@link TERMINAL_BACKSTOP_MS} / {@link TERMINAL_GRACE_MS} / {@link DECIDED_REPLAY_SCAN_CAP};
+ *  · 两孪生同调的纯判据与投影:{@link queueRowGateKind}、{@link isUnreadableSummaryForm}、{@link readRiskDescriptorBody}、{@link boundedToolInput}、{@link boundedRuleOffers}、
+ *    {@link approvalDecisionOfWinner}、{@link candidateIdentityOf};待决行的分诊序 {@link pendingTriageOrder} / {@link queueTriageOrder}(两孪生 + 助手收件箱);
+ *    常量 {@link TERMINAL_BACKSTOP_MS} / {@link TERMINAL_GRACE_MS} / {@link DECIDED_REPLAY_SCAN_CAP} / {@link DENY_SWEEP_PAGE_ROWS};SLA 拒扫选行读口的行形与游标 {@link ExpiredApprovalGate} / {@link ExpiredGatePosition};
  *  · ctx 两口的结局词 {@link CtxClaimRewrite} 与一次性迁移的 ctx 行改写店腿的型(随最后一条用它的迁移删,见 {@link CheckpointCtxRowsRewriter});
  *  · 店拒绝契约里「一行字节读不成检查点」那一只 {@link UnreadableCheckpointRowError}(SQL 孪生抛、续跑腿认)。
  *
@@ -13,7 +14,7 @@
  * SQL 孪生的文件里;它住这里,SQL 孪生经一条点名的已知欠边借它 —— 这一条边就是阶段三搬家时「服务特有面」的清单(向引擎请托的候选,只列不发)。
  * 这里零 SQL:SQL 文本、列读法与行投影仍在 SQL 孪生里。
  */
-import { type Checkpoint, type CheckpointGate, type CheckpointRowVerdict, type GateOutcome, type ResolvedOutcome, type RiskDescriptor, type ToolApprovalCard } from "@sema-agent/core";
+import { type Checkpoint, type CheckpointGate, type CheckpointRowVerdict, type CheckpointSummary, type GateOutcome, type ResolvedOutcome, type RiskDescriptor, type ToolApprovalCard } from "@sema-agent/core";
 import { type ParkRowFacts, type RuleOfferProjection, type SkillCardFacts } from "../approval-card.js";
 import { StoreCorruptError } from "./sql-json-column.js";
 import type { SealedCheckpointCtx } from "../http/checkpoint-ctx.js";
@@ -58,6 +59,25 @@ export declare const TERMINAL_BACKSTOP_MS: number;
  * it never meaningfully delays the eventual crash-safe GC.
  */
 export declare const TERMINAL_GRACE_MS = 3600000;
+/**
+ * SLA 拒扫的一页(行数):每拍至多续跑尝试这么多张过期审批(每张是一次续跑 —— 拒扫的限流界)。唯一属主:两孪生选行读口的缺省页长与拒扫判「这一页满了没有」读同一个数。
+ */
+export declare const DENY_SWEEP_PAGE_ROWS = 100;
+/**
+ * 一张过期审批在 SLA 拒扫选行序上的位置 —— 两孪生同序:截止升序,同截止按 token 升序(SQL 孪生按列的排序规则比 token,LOCAL 孪生按 UTF-16 码元比;
+ * 各孪生的游标只回到它自己,所以只要各自的序与各自的「之后」谓词同一把尺子)。LOCAL 孪生的截止读不成有限数时取 `-Infinity`(引擎读作已过 ⇒ 排最前)。
+ * **进程内的游标**:拒扫腿拿它从上一拍读到的最后一行之后接着读,不上 wire、不落盘。
+ */
+export interface ExpiredGatePosition {
+    readonly deadline: number;
+    readonly token: string;
+}
+/** SLA 拒扫选行读口(`listExpiredApprovalGates`)的一行:会话、scope、它在选行序上的位置({@link ExpiredGatePosition})。 */
+export interface ExpiredApprovalGate {
+    readonly sessionId: string;
+    readonly scope: string;
+    readonly position: ExpiredGatePosition;
+}
 /** Non-secret view of a pending checkpoint for the operator approval queue — deliberately NO token.
  *
  *  🔴 [ref]:行**顶层**另带 {@link ParkRowFacts}(`requiresRealApproval` / `ruleOffersAbsence`,真才带、缺席 ≠ false)——
@@ -97,13 +117,24 @@ export interface PendingCheckpoint extends ParkRowFacts, SkillCardFacts {
      *  ([ref], 7.132.0): every park stamps it, the one-time migration M21 filled any row without it from the row's gate,
      *  and a SQL row that still carries none is not listed by `listPending` (counted: `server.approvals.queue-row-gate-kind-missing`; no decide route binds it either). */
     gateKind: CheckpointGate["kind"];
-    /** The suspended run's taskId (task_active join) — the key to the run/trace ("view task context"). */
+    /**
+     * 🔴 [ref] —— **停在这道门上的那条腿以哪个 task 在跑**(唯一写者 {@link parkedLegTaskId};两只孪生各交自己手里的两格读数):
+     * 引擎铸这只停驻行时记下的那条腿的登记行(core `CheckpointState.rowTaskId` —— 后台委派子代的 `a…` 句柄,`/decide` 复活它的回执上的同一个 `taskId`;
+     * 不是 `/v1/runs/:id` 的键)⇒ 它;否则 = 持着这一行会话认领的那条 run(run 自己的停驻;停驻 / 待审的 run 不放认领;`/v1/runs/:id` 与 trace 的键);
+     * 两者都没有(同步 / workflow 委派子代、终局后的纯停驻)⇒ `null`。
+     */
     taskId: string | null;
     /** The pending tool call's args (post-hook), redacted + bounded — for tool_approval the write payload, for a
      *  durable AskUserQuestion the question itself. Lets the approval card render WITHOUT an N+1 trace.turns
      *  fetch. `null` for pre-migration rows (suspended before the column existed) ⇒ consumer falls back. */
     input: unknown;
-    createdAt: number;
+    /**
+     * 建行时刻(epoch ms)。SQL 孪生恒在场(本服务在存储体之外握着的建行时刻列)。LOCAL 孪生读引擎对这一行投的摘要(core `CheckpointSummary.createdAt`,同一可选性):
+     * 摘要读得出有限数才在场,读不出(存储体里不是有限数 —— 那一行判官判坏、`rowVerdict` 非 `ok`)⇒ **缺席**,从不把存储体里的原值搬上 wire。
+     * 排序读法见 {@link queueTriageOrder}(缺席计 0 = 档内最老)。
+     */
+    createdAt?: number;
+    /** 截止(epoch ms);没有截止 ⇒ `null`。LOCAL 孪生同读摘要:读不成有限数 ⇒ `null`(摘要不带它;到期两扫按引擎 `checkpointDeadlinePassed` 把它读作已过)。 */
     deadline: number | null;
     /** [ref] riskDescriptor inbox: core's INERT triage descriptor ({severity 1-5, axes, toolName, redacted
      *  summary, touchedPaths}) for human/irreversible_ask gates. listPending returns the queue severity-sorted
@@ -187,6 +218,19 @@ export interface PendingCheckpoint extends ParkRowFacts, SkillCardFacts {
      */
     rowVerdict?: CheckpointRowVerdict;
 }
+/**
+ * 🔴 [ref] —— 停驻行 {@link PendingCheckpoint.taskId} 的**唯一写者**:停在这道门上的那条腿以哪个 task 在跑。
+ *
+ * 两格读数,两只孪生各交自己手里的那一份(SQL 孪生:`checkpoint` 列的 `$.state.rowTaskId` 成员 + `task_active` 联结;local 孪生:同一行的
+ * `state.rowTaskId` + 文件 run 店的 `getActiveTaskId`):
+ *  · `recorded` —— 引擎铸这只停驻行时记下的那条腿的登记行(core `CheckpointState.rowTaskId`,每个铸点盖;只在后台车道的腿上在场 ——
+ *    顶层 run、同步子代、workflow 子代不盖)。它与行的会话(铸停驻那条腿的会话,[ref])是同一次铸、同一条腿的身份;本服务不另读后台 agent 行、
+ *    不按 scope 扫、不经会话元组(行上的 `agent.id`)回填;
+ *  · `claimHolder` —— 持着这一行会话认领的那条 run(顶层 run 引擎不盖登记行:那条腿就是 run 本身,本服务的 run 账本知道它)。
+ * 记录是一只非空串 ⇒ 它(行自己点名停在这道门上的那条腿;认领可能属于同会话上另一条 run)。构造上两者不同时在场:后台子代的会话不进 run 账本、不持认领。
+ * 记录读不成非空串(数 / 对象 / 空串 —— 被改过的行)⇒ 与没记同答:方向是少一个路由键,不放宽任何判;那一行续不续得了由它的 `rowVerdict` 另说。
+ */
+export declare function parkedLegTaskId(recorded: unknown, claimHolder: string | null): string | null;
 /**
  * [ref]([ref] / DEBTS [ref]):session 键读口(`findPendingTokenBySession` / `peekPendingScope`)的**行绑定**。
  *
@@ -228,6 +272,14 @@ export interface PendingRowBinding {
      *    赢家卡与被消费卡恒同一张(FIFO 顺带成立)。
      */
     pick?: "newest" | "oldest";
+    /**
+     * 按哪一只会话找(缺省 `"card"`)。一张卡的行上有两个会话事实,两个问题各读一只:
+     *  · `"card"`(缺省)—— 卡**自己的对话**(`checkpoint.session_id`):决断口 URL 里的会话、SLA 拒扫的复核、按会话唤醒 —— 地址就是卡停在的那段对话;
+     *  · `"run"` —— 卡**归属的那条 run 的会话**(`checkpoint.host_session_id`,读法 `checkpoint-index-columns.ts` 的 `hostSessionOf`):从 run 一侧找它等着的那张卡
+     *    (取消、steer 停放、活跃 run 409 的门材料、起服收回、本地收割探针、续跑输入回收、按 task 续跑的两扇门)。cascade 的级上卡两者不同:
+     *    卡在级自己现铸的对话里,归调用方的会话;其余每一张卡两者同值。
+     */
+    axis?: "card" | "run";
 }
 /** [ref]:一条**仍持有 claim 的 run** 可能停在的全部门型(= 除 `task_done` 外全部;派生自上表,不手抄)。
  *  给「按 run 行动」的读口用:cancel / steer 的 park 落点、409 `pendingGate` 材料 —— 这些腿手里有 run 行,
@@ -300,13 +352,32 @@ export declare class UnreadableCheckpointRowError extends StoreCorruptError {
 }
 /**
  * [ref] —— 运维队列行的门型:**两只孪生同一只判官**(SQL 孪生读 `gate_kind` 列 —— put 时从同一只门反范式下来的那一格,每次停驻都盖,一次性迁移 M21 把没有它的
- * 存量行从门子树补齐;local 孪生读快照上的门 `cp.gate.kind`)。
+ * 存量行从门子树补齐;local 孪生读引擎对这一行投的摘要上的 `gateKind` —— 门不是 core 登记的门型时摘要不带它)。
  * 读到的值是 NULL / 缺席 / 不是 core 登记的门型 ⇒ `undefined`:这一行**不列**(响亮:计一次 `server.approvals.queue-row-gate-kind-missing`)—— 与每一条决断口同一个读法:
  * 按门型绑定取行的读口对这种行本来就不命中(`pendingRowQuery` 的 `gate_kind IN (…)`,证不出门型就不当它是这道门),队列不再把一行谁也决不了的行投出去,
  * 也不按缺键投(消费方按 `gateKind` 路由、缺键即 fail-closed)。不整只拒:一行坏行不许让整个租户的队列(列表 500、SSE 心跳照常而队列永远停在旧帧)消失。
  * 按构造不可达(写口恒盖、M21 补齐);计数非零 = 写腿或手改出了错,按 `SELECT … WHERE status = 'pending' AND gate_kind IS NULL` 查那一行。
  */
 export declare function queueRowGateKind(kind: unknown): CheckpointGate["kind"] | undefined;
+export declare function isUnreadableSummaryForm(summary: CheckpointSummary): boolean;
+/**
+ * 运维队列行 `riskDescriptor` 那一格的**形读者**(两孪生同调这一只):SQL 孪生对 `risk_descriptor` 列解出来的体(`decodeJsonColumn`)、LOCAL 孪生对存储体里门上的
+ * `gate.riskDescriptor`。判到「是不是一只对象」为止 —— 描述符的键表属主在 core,core 没有导出它的验证器,手写一份就是第二份键集。读不出 ⇒ 这一行的描述符 `null` +
+ * 计 `server.approvals.risk-descriptor-cell-unreadable`(两孪生同一个 tag、同一失败方向;放行理由见登记表)。
+ */
+export declare const readRiskDescriptorBody: import("./sql-json-column.js").JsonColumnReader<RiskDescriptor>;
+/** 分诊序读的两格(运维队列行 = 描述符里的严重度;收件箱行 = 引擎摘要的严重度)。 */
+export interface TriageKeys {
+    readonly severity?: number | undefined;
+    readonly createdAt?: number | undefined;
+}
+/**
+ * 待决停驻行的**分诊序** —— 一只比较器,运维队列两孪生({@link queueTriageOrder})与助手收件箱同调:严重度降序,同档内 `createdAt` 升序(最老在前);
+ * 一格缺席或读不成有限数按 0 计 —— 确定性优于「看它恰好落在哪」,也不让一个非数让整只排序失去全序。与店的返回顺序无关(core 的 `listByScope` 零顺序声明)。
+ */
+export declare function pendingTriageOrder(a: TriageKeys, b: TriageKeys): number;
+/** 运维队列行的分诊序 = {@link pendingTriageOrder} 读行上描述符的严重度(两孪生的 `listPending` 同调)。 */
+export declare function queueTriageOrder(a: PendingCheckpoint, b: PendingCheckpoint): number;
 /** Redact + size-bound a pending tool call's args for persistence/serving. JSON-roundtrips so the stored shape
  *  matches what the operator queue serves; oversized payloads collapse to a marker rather than bloating the row.
  *  Exported for the LOCAL twin (local-checkpoint-store.ts) so the operator-queue projection can't drift. */
@@ -325,10 +396,10 @@ export interface CheckpointAskCandidate {
      * 🔴 和解三元组的第一维([ref] 件1,黑板 [ref]③①)—— checkpoint 自己带的 `sourceSessionId`(core 在
      * suspendAsk 铸行时恒填该腿的 `sessionId`)。**没有对应的列**,只能从 blob 窄读;读不出/缺席 = null。
      *
-     * 为什么必须进候选集:读口按 `(scope, session_id, tool_call_id)` 查,而委派子代那条腿的 ask 落行时
-     * `session_id` 记的是**投递上下文**(根会话),park 却发生在**子代自己**的 sessionId 上 —— 只靠
-     * (toolCallId, hash) 两维,一条根腿的 park 会被一只子代的 ask 认领(摘要相同的两次同 args 调用完全
-     * 正常)。三元组全同才算同一件事。
+     * 为什么必须进候选集:收敛器按 `(scope, session_id = 问的 sourceSessionId, tool_call_id)` 查,`session_id` 列是这只停车行
+     * 自己落在哪个会话(core 铸行时同一只变量也写进 blob 的 `sourceSessionId`)—— 列与 blob 两份陈述,身份等式比的是 blob 那一份:
+     * 列被外部改写 / 两份分家时,只靠 (toolCallId, hash) 两维会让别的会话的 park 被认领(摘要相同的两次同 args 调用完全正常)。
+     * 三元组全同才算同一件事。
      */
     sourceSessionId: string | null;
     /** 该 park 绑定的 tool call(= `pendingAction.toolCallId`)。`unparseable` 行为 null。 */
@@ -423,4 +494,6 @@ export declare function candidateIdentityOf(cp: Checkpoint): CandidateIdentity;
  *  `context_absent` 持有、但会话没有 ctx 行 ⇒ 零写(不建行)。 */
 export declare const CTX_CLAIM_REWRITES: readonly ["written", "claim_released", "context_absent"];
 export type CtxClaimRewrite = (typeof CTX_CLAIM_REWRITES)[number];
+/** 认领栅栏下**建或换**一行 ctx 的结局([ref];`putCtx` 的结局 —— 交认领的提交腿与续跑腿的写;不交认领恒 `written`):同一张词表去掉 `context_absent`(这一口没有行就建)。 */
+export type CtxClaimPut = Exclude<CtxClaimRewrite, "context_absent">;
 //# sourceMappingURL=checkpoint-store-face.d.ts.map

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

@@ -1,11 +1,15 @@
 import { isGateKind, judgeCheckpointRow, MAX_RULE_TEXT_CHARS, } from "@sema-agent/core";
 import { redactDeep, redactSecrets } from "../trace/redact.js";
 import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, readRuleOfferList } from "../approval-card.js";
-import { StoreCorruptError } from "./sql-json-column.js";
+import { createObjectColumnReader, StoreCorruptError } from "./sql-json-column.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 const MAX_TOOL_INPUT_CHARS = 8192;
 export const TERMINAL_BACKSTOP_MS = Math.max(60_000, (Number.isFinite(Number(process.env.APPROVAL_TERMINAL_BACKSTOP_MS)) ? Number(process.env.APPROVAL_TERMINAL_BACKSTOP_MS) : 0) || 30 * 86_400_000);
 export const TERMINAL_GRACE_MS = 3_600_000;
+export const DENY_SWEEP_PAGE_ROWS = 100;
+export function parkedLegTaskId(recorded, claimHolder) {
+    return typeof recorded === "string" && recorded.length > 0 ? recorded : claimHolder;
+}
 const GATE_KIND_IS_LIVE_RUN_PARK = {
     human: true,
     irreversible_ask: true,
@@ -81,6 +85,19 @@ export function queueRowGateKind(kind) {
     recordFailOpen("server.approvals.queue-row-gate-kind-missing", `gate_kind=${kind === null || kind === undefined ? "NULL" : redactSecrets(String(kind)).slice(0, 40)}`);
     return undefined;
 }
+const UNREADABLE_SUMMARY_MEMBERS = new Set(["token", "rowVerdict", "sessionId", "scope", "gateKind", "createdAt", "deadline"]);
+export function isUnreadableSummaryForm(summary) {
+    const names = UNREADABLE_SUMMARY_MEMBERS;
+    return summary.rowVerdict.kind !== "ok" && Object.keys(summary).every((member) => names.has(member));
+}
+export const readRiskDescriptorBody = createObjectColumnReader();
+const triageKey = (v) => (v !== undefined && Number.isFinite(v) ? v : 0);
+export function pendingTriageOrder(a, b) {
+    return triageKey(b.severity) - triageKey(a.severity) || triageKey(a.createdAt) - triageKey(b.createdAt);
+}
+export function queueTriageOrder(a, b) {
+    return pendingTriageOrder({ severity: a.riskDescriptor?.severity, createdAt: a.createdAt }, { severity: b.riskDescriptor?.severity, createdAt: b.createdAt });
+}
 export function boundedToolInput(args) {
     if (args === undefined)
         return null;

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

@@ -80,6 +80,7 @@ export async function ensureTiDBDeviceSchema(pool) {
 }
 export const DEVICE_INDEXES = [
     { table: `${DEVICES_TABLE}`, name: "idx_device_owner", columns: ["owner_tenant", "owner_subject"] },
+    { table: `${DEVICES_TABLE}`, name: UQ_DEVICES_PUBKEY, columns: ["owner_tenant", "pubkey"], unique: true },
     { table: `${DEVICE_AUDIT_TABLE}`, name: "idx_device_audit_device", columns: ["device_id", "at"] },
     { table: `${DEVICE_AUDIT_TABLE}`, name: "idx_device_audit_event", columns: ["event", "at"] },
 ];

package/dist/plugins/ensure-index.d.ts

@@ -1,4 +1,5 @@
 import type { SqlDialect } from "./sql-driver.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
 /**
  * 一条索引的**声明**(纯数据)。两方言共用同一份声明 —— 这就是"一处属主"的兑现物:
  * per-store 文件各导出自己那份 `readonly IndexSpec[]`,PG 侧由该 store 的 `ensurePg*Schema` 应用,
@@ -11,7 +12,7 @@ export interface IndexSpec {
     readonly name: string;
     /** 列序(等值前缀在前、排序列在后;与 MySQL 内联 `KEY` 的列序**必须**逐字一致)。 */
     readonly columns: readonly string[];
-    /** UNIQUE 索引(MySQL 内联 `UNIQUE KEY` 的孪生)。缺省 = 普通索引。 */
+    /** UNIQUE 索引(MySQL 内联 `UNIQUE KEY` / PG 表约束 `CONSTRAINT … UNIQUE` 的孪生)。缺省 = 普通索引。唯一索引多一道判形(头注「唯一索引」),列集按**集合**比。 */
     readonly unique?: boolean;
 }
 /**
@@ -28,6 +29,17 @@ export interface IndexSpec {
  *     不带参 ⇒ 这一整类接缝脆弱性结构上不存在。两方言同律,不留一边带参一边不带的不对称。
  */
 export type IndexQueryFn = (sql: string, params?: unknown[]) => Promise<unknown>;
+/**
+ * 唯一索引的确定拒启(头注「唯一索引」)。`kind`:`shape` = 同名在场而形不对;`duplicates` = 存量重复行让建索引失败。
+ * 继承 {@link StoreBootRefusalError}:SQL 开库的等待窗不重试它、「库打不开」的拒句不改写它。
+ */
+export declare class UniqueIndexRefusalError extends StoreBootRefusalError {
+    readonly kind: "shape" | "duplicates";
+    readonly spec: IndexSpec;
+    constructor(kind: "shape" | "duplicates", spec: IndexSpec, message: string, options?: {
+        readonly cause: unknown;
+    });
+}
 /**
  * 幂等地保证一条索引在场。**这是本仓唯一允许发加索引 DDL 的地方**(SCHEMA POLICY 窄放的全部内容)。
  *