@sema-agent/server 7.55.0 → 7.57.0

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

@@ -195,16 +195,6 @@ export type RuleTicketRedeemResult = {
     ok: false;
     reason: "unknown" | "wrong-principal" | "wrong-purpose" | "expired" | "consumed";
 };
-/**
- * [ref]③/[ref]③ —— 票的**判定钟**覆写(记账钟永远不覆写,见 `consume` 内注)。
- *
- * 缺席 = 墙钟,既有行为逐字不变。在场 = 调用方(同意车道)按**单调锚**投影出来的那个时刻:
- * 铸票时刻的墙钟 + 自铸票起单调钟走过的量。它只能让判定更贴近**真实经过的时间**,给不了票额外寿命
- * (投影按单调钟前进,走满 TTL 就必然越过 `expires_at_ms`)。
- */
-export interface RuleTicketDecisionClock {
-    decisionNowMs?: number;
-}
 /**
  * [ref] A7 —— 一张票的**三态快照**(MINTED → CLAIMED → SETTLED)。
  *
@@ -243,15 +233,18 @@ export type RuleTicketReclaimResult = {
     ok: false;
 };
 /**
- * [ref]③ 同族的 **GC 宽限**:`reapExpired` 只收「按墙钟至少已死一个完整 TTL」的票行。
+ * [ref]③ 同族的 **GC 宽限**:`reapExpired` 只收「按**数据库的钟**至少已死一个完整 TTL」的票行。
  *
- * 为什么需要它:判定侧改单调锚之后,一张「按墙钟已过期、按单调钟还在窗内」的票是**可兑付**的;
- * 若 GC 仍按 `expires_at_ms <= now` 收行,判定修好了而行先没了 —— 用户拿到的从 `expired` 变成 `unknown`,
- * 缺陷只是换了个归因。宽限一个 TTL 覆盖住「铸票时钟慢了不到一个 TTL」这一族(含 [ref]③ 的真实构造)。
+ * 🔴 立论已换([ref] / [ref]):它原本是给单调锚兜底的 —— 一张「按墙钟已过期、按单调钟还在窗内」的
+ * 票当年是可兑付的,GC 不能抢在判定前面把行收走。TTL 轴整条搬到数据库的钟之后,那一族**从根上没有了**
+ * (判定与清扫从此同一口钟、同一个不等号,不可能一个说活一个说死)。留着它的现由是另外两条,都成立:
+ *  · **归因质量**:行还在 ⇒ 拒绝是 `expired`(服务端日志说得清「票过期了」);行被收走 ⇒ 塌成 `unknown`。
+ *    死票在库里多躺一个宽限,换来运维排查时一个准确的归因,而票表按设计是短命小表,代价可忽略。
+ *  · **数据库自己的钟也会被拨**(DB 主机的 NTP 纠正、或一次主从切换换了台机器)。宽限一个 TTL 覆盖住
+ *    「DB 钟被往前拨了不到一个 TTL」这一族:那种时刻 `consume` 会暂时拒,但行还在,钟走回来票就活。
  *
- * 残余(如实登记,不假称已解):墙钟被拨慢**超过**一个 TTL 时,行仍可能在单调窗内被收。彻底解需要行上
- * 存单调基准,而单调基准跨进程无意义(core [ref] 的判词)。补偿是现成的:prepare 廉价,重铸一张即可
- * ——这正是 core 建议的姿态(「接受 + 票廉价重铸」)。
+ * 残余(如实登记,不假称已解):DB 钟被往前拨**超过**一个 TTL 时,行仍会被收。补偿是现成的:prepare
+ * 廉价,重铸一张即可(core [ref] 建议的姿态)。
  */
 export declare const RULE_IMPORT_TICKET_GC_GRACE_MS: number;
 /**
@@ -262,11 +255,17 @@ export declare const RULE_IMPORT_TICKET_GC_GRACE_MS: number;
  * 生出来的权威回执下一拍就被删,而"落定之后必有一个完整的回放窗"是本批新许下的承诺 —— 它不能建立在
  * 「两台机器的钟差不多」这条没人声明过的假设上。数据库的钟是这两台副本**唯一**共享的那口钟。
  *
- * 🔴 射程更新(车K 2026-08-30 对账):`consumed_at_ms` 自 R8-F2 起**也走本钟**(`consume` 的 UPDATE
- * 直写本常量,见其行注);仍留在副本墙钟域的是 `expires_at_ms` / `created_at_ms` 两列 —— 那是
- * cc-import 车道的**既存已登记残余**([ref]③,收口方向逐字见
- * `rules-consent.ts` 的 anchors 头注),把它一并搬走会改动两条车道共用的认领谓词,不在本批射程。
- * 这一句同时也是那次收口的**样板**:形已经在这里了,下一批照抄即可。
+ * 🔴 射程收官([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)";
@@ -277,11 +276,37 @@ export declare function buildRulePayloadHash(candidates: ReadonlyArray<{
     rule: string;
     scope: RuleScope;
 }>): string;
+/**
+ * 票面三态协议的 SQL 实现。
+ *
+ * 🔴 **这只店没有本地钟 seam**([ref]):它此前收一个 `now: () => number`,而票上的每一个时刻量现在都由
+ * 数据库自己出({@link SQL_DB_NOW_MS})。留着那只形参会让人以为「注一只假钟就能改票的判决」——
+ * 那正是本批要消灭的那条依赖。测试要制造过期,改行(把 `expires_at_ms` 相对 `<db now>` 挪)即可,
+ * 而那恰恰也是生产上唯一能让票过期的方式。
+ */
 export declare class SqlRuleImportTicketStore {
     private readonly db;
-    private readonly now;
-    constructor(db: SqlDriver, now?: () => number);
+    constructor(db: SqlDriver);
     private q;
+    /**
+     * 问一次**数据库自己的钟**(毫秒)。铸票用它当基准,于是到期时刻与后续每一次判定同域。
+     *
+     * 读不出数 ⇒ **响亮抛**([ref] fail-closed):静默兜个本地 `Date.now()` 正是本批要删掉的那条腿,
+     * 而一次「钟读不出来」在授权面上是运维事件,不是一个可以猜的默认值。
+     */
+    private dbNowMs;
+    /**
+     * 铸一张票。
+     *
+     * 🔴 到期时刻 = **数据库的钟** + TTL([ref] / [ref]),不是这台副本的墙钟 + TTL。理由逐字见
+     * {@link SQL_DB_NOW_MS} 的头注:铸造点与判定点必须同一口钟,否则 TTL 在集群上不单调。
+     *
+     * 为什么是「先问一次钟、再把绝对值写进去」而不是「INSERT 里直接写 `<db now> + ?`」:`expiresAtMs`
+     * 要**原样上 wire**(prepare 的响应体里有它,客户端拿它显示倒计时),而 MySQL 的 INSERT 交不回
+     * 计算列 —— 那一形要么再补一条 SELECT 读回来(失败时留一行孤儿),要么两方言各写一套(PG 有
+     * `RETURNING`、MySQL 没有,两份会各自漂)。先问钟的形只有一个失败方向:钟没问到 ⇒ 一行都没落,
+     * 调用方原样收错。两跳之间流逝的那点时间只会让票**略短命**,方向保守。
+     */
     mint(input: {
         ticketId: string;
         principal: string;
@@ -308,7 +333,7 @@ export declare class SqlRuleImportTicketStore {
      * wrong-purpose/expired/consumed 五类给服务端日志;wire 面把五类折成同一个 404)。预读说「可以」而 UPDATE 命中零行,
      * 只可能是我们在这两跳之间输给了一个并发认领者 —— 如实报 `consumed`,而不是把这次失败当成成功。
      */
-    consume(ticketId: string, principal: string, purpose: RuleTicketPurpose, opts?: RuleTicketDecisionClock): Promise<RuleTicketRedeemResult>;
+    consume(ticketId: string, principal: string, purpose: RuleTicketPurpose): Promise<RuleTicketRedeemResult>;
     /**
      * **认领的释放**(codex 交叉复审 round1 [high] 一,验真后修)。
      *
@@ -325,7 +350,7 @@ export declare class SqlRuleImportTicketStore {
      * 期间属主可以重新走 prepare 拿一张新票(导入是幂等的:同一条规则再兑付只是同一个 dot 的重放)。
      * 要彻底消灭它需要一条带租约到期的认领状态机,属协议改动,列为后续件。
      */
-    release(ticketId: string, principal: string, claimId: string, mustRemainValidMs?: number, opts?: RuleTicketDecisionClock): Promise<boolean>;
+    release(ticketId: string, principal: string, claimId: string, mustRemainValidMs?: number): Promise<boolean>;
     /**
      * [ref] A7 —— CLAIMED → **SETTLED**:把这一次兑付的终局写进行里。
      *
@@ -427,11 +452,16 @@ export interface PermissionRuleStores {
      *    「超帽当场拒」那一条路,不收「人改主意了」)。
      *
      * 两张表的谓词都只删**可证已死**的行,所以本腿不需要旋钮(没有可调的语义):
-     *  · 票(三支 OR,A7 交叉复审定形,逐支论证见 reapExpired 实现内注):甲=从未认领且已过期;
-     *    乙=已落定且落定后过 GC 宽限(按 `settled_at_ms` 判,走 DB 钟);丙=CLAIMED-未结且认领戳老过
-     *    废弃期(按 `consumed_at_ms` 判,走 DB 钟);
-     *  · 记录:`state = 'pending' AND created_at_ms < now − {@link RULE_PENDING_APPROVAL_RETENTION_MS}`,
+     *  · 票(三支 OR,A7 交叉复审定形,逐支论证见 reapExpired 实现内注)**三支全走 DB 钟**([ref]):
+     *    甲=从未认领且过期已满 GC 宽限;乙=已落定且落定后过 GC 宽限(按 `settled_at_ms` 判);
+     *    丙=CLAIMED-未结且认领戳老过废弃期(按 `consumed_at_ms` 判);
+     *  · 记录:`state = 'pending' AND created_at_ms < nowMs − {@link RULE_PENDING_APPROVAL_RETENTION_MS}`,
      *    再加 `NOT EXISTS`(载荷必须陪着把手活,R6-F1:仍有票引用的 pending 记录不删)。
+     *
+     * 🔴 `nowMs` 形参**只剩记录那一支在用**,如实登记:`permission_rule_approval.created_at_ms` 是这台
+     * 副本自己写下的(见 {@link SqlRuleApprovalRecordStore}),按同一台副本的墙钟判"落盘满 24 小时了吗"
+     * 是**同域比较** —— 把它单独搬到 DB 钟反而会造出一次新的跨钟比较。那张表的钟域是另一条轴上的事,
+     * 不在本批射程(登记为后续件)。票那一支已经不看它了。
      */
     reapExpired(nowMs: number): Promise<number>;
 }

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

@@ -4,6 +4,7 @@ import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuar
 import { dialectProtocolJsonEncoder } 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, PERSISTED_RULE_TOOLS, RULE_APPROVAL_RECORD_SCHEMA, UNCOVERED_SEGMENT_REASONS } from "../permission-rule-vocab.js";
 export function writerOfSqlRuleStore(store) {
     const w = Reflect.get(store, PERMISSION_RULE_WRITER);
     if (w === null || typeof w !== "object")
@@ -26,8 +27,8 @@ const RuleAddSchema = z
 const PersistedAllowRuleSchema = z
     .object({
     rule: z.string(),
-    tool: z.literal("Bash"),
-    match: z.enum(["exact", "prefix"]),
+    tool: z.enum(PERSISTED_RULE_TOOLS),
+    match: z.enum(PERSISTED_RULE_MATCHES),
     command: z.string(),
     scope: DurableRuleScopeSchema,
     adds: z.array(RuleAddSchema),
@@ -52,7 +53,9 @@ const QuarantinedRuleAddSchema = z
 const FrontierSchema = z.record(z.string(), z.number().int().nonnegative().safe());
 const RuleCandidateSchema = z.object({ rule: z.string(), scope: DurableRuleScopeSchema }).strict();
 const RedeemedDotsSchema = z.record(z.string(), RuleDotSchema);
-const RuleEditedSchema = z.object({ index: z.number().int().nonnegative().safe(), text: z.string(), at: z.string() }).strict();
+const RuleEditedSchema = z
+    .object({ index: z.number().int().nonnegative().safe(), text: z.string(), at: z.string(), warnings: z.array(z.enum(EDITED_RULE_BREADTH_WARNING_CODES)).optional() })
+    .strict();
 const RuleOffer2Schema = z.union([
     z.object({ kind: z.literal("single"), candidate: z.number().int().nonnegative().safe() }).strict(),
     z
@@ -61,6 +64,7 @@ const RuleOffer2Schema = z.union([
         candidates: z.array(z.number().int().nonnegative().safe()),
         segments: z.array(z.string()).optional(),
         uncoveredSegments: z.number().int().nonnegative().safe().optional(),
+        uncoveredDetail: z.array(z.object({ segment: z.string(), reason: z.enum(UNCOVERED_SEGMENT_REASONS) }).strict()).optional(),
     })
         .strict(),
 ]);
@@ -104,8 +108,9 @@ export const TIDB_PERMISSION_RULE_STATEMENTS = [
     state VARCHAR(32) NOT NULL,
     rev BIGINT NOT NULL DEFAULT 0,
     candidates_json LONGTEXT NOT NULL,
-    -- version:**数据格式版本**(= core \`RuleApprovalRecord.schema\`,本形恒 2;OCC 守卫另在 rev,
-    -- 两轴禁混,schema-naming 门③ 白名单登记)。读侧对非 2 的行交还 design/375 §4.5 的
+    -- version:**数据格式版本**(= core \`RuleApprovalRecord.schema\`,本形恒 3 —— design/382 §3.5 由 2 升,
+    -- 代码里的单点是 RULE_APPROVAL_RECORD_SCHEMA;OCC 守卫另在 rev,两轴禁混,schema-naming 门③ 白名单
+    -- 登记)。读侧对非 3 的行(含上一形的 2)交还 design/375 §4.5 的
     -- StaleRuleApprovalRecord 信封(identity 键 only)—— 本仓 SCHEMA POLICY 是删表重建,重建后的表
     -- 不该有这种行,这一臂是「未来再换形」的防御位,绝不静默 widen 成一条本形担保不了的记录。
     version INT NOT NULL,
@@ -258,7 +263,8 @@ export async function ensurePgPermissionRuleSchema(q) {
     rev BIGINT NOT NULL DEFAULT 0,
     candidates_json TEXT COLLATE "C" NOT NULL,
     -- version / offers_json / selected_offer:design/375 换形三列(MySQL 孪生的行内注写了理由:
-    -- version=数据格式版本恒 2,非 2 的行读成 Stale 信封;offers_json=按 index 引用的 OPTION 结构,
+    -- version=数据格式版本恒 3(design/382 §3.5 由 2 升;单点 RULE_APPROVAL_RECORD_SCHEMA),非 3 的行(含 2)
+    -- 读成 Stale 信封;offers_json=按 index 引用的 OPTION 结构,
     -- 禁存文本副本;selected_offer=确认的 OFFER index,与 ticket/redeemed_dots 的 CANDIDATE index
     -- 两空间分离)。
     version INT NOT NULL,
@@ -525,7 +531,7 @@ export class SqlRuleApprovalRecordStore {
         const ownerKind = String(row.owner_kind);
         const principal = row.principal === null || row.principal === undefined ? undefined : String(row.principal);
         const identity = ownerKind === "principal" ? { principal: principal ?? "" } : { owner: { kind: "local-owner" } };
-        if (Number(row.version) !== 2) {
+        if (Number(row.version) !== RULE_APPROVAL_RECORD_SCHEMA) {
             return { staleSchema: true, id: String(row.record_id), ...identity };
         }
         const candidates = parseColumn(z.array(RuleCandidateSchema), row.candidates_json, "candidates_json", id);
@@ -541,7 +547,7 @@ export class SqlRuleApprovalRecordStore {
         return {
             id: String(row.record_id),
             ...identity,
-            schema: 2,
+            schema: RULE_APPROVAL_RECORD_SCHEMA,
             kind: kind.data,
             state: state.data,
             candidates,
@@ -584,14 +590,14 @@ export class SqlRuleApprovalRecordStore {
         ]);
     }
     async discardPendingRecord(recordId) {
-        const { affected } = await this.db.query(this.q(`DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = ? AND state = 'pending' AND version = 2`, `DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = $1 AND state = 'pending' AND version = 2`), [recordId]);
+        const { affected } = await this.db.query(this.q(`DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = ? AND state = 'pending' AND version = ${RULE_APPROVAL_RECORD_SCHEMA}`, `DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = $1 AND state = 'pending' AND version = ${RULE_APPROVAL_RECORD_SCHEMA}`), [recordId]);
         return affected === 1;
     }
     async cas(id, expectRev, next) {
         if (next.rev !== expectRev + 1) {
             throw new Error(`rule-approval CAS must advance rev by exactly one (expectRev=${expectRev}, next.rev=${next.rev})`);
         }
-        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_APPROVAL_TABLE} SET state = ?, rev = ?, candidates_json = ?, offers_json = ?, selected_offer = ?, redeemed_dots_json = ?, edited_json = ?, updated_at_ms = ? WHERE record_id = ? AND rev = ? AND version = 2`, `UPDATE ${PERMISSION_RULE_APPROVAL_TABLE} SET state = $1, rev = $2, candidates_json = $3, offers_json = $4, selected_offer = $5, redeemed_dots_json = $6, edited_json = $7, updated_at_ms = $8 WHERE record_id = $9 AND rev = $10 AND version = 2`), [
+        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_APPROVAL_TABLE} SET state = ?, rev = ?, candidates_json = ?, offers_json = ?, selected_offer = ?, redeemed_dots_json = ?, edited_json = ?, updated_at_ms = ? WHERE record_id = ? AND rev = ? AND version = ${RULE_APPROVAL_RECORD_SCHEMA}`, `UPDATE ${PERMISSION_RULE_APPROVAL_TABLE} SET state = $1, rev = $2, candidates_json = $3, offers_json = $4, selected_offer = $5, redeemed_dots_json = $6, edited_json = $7, updated_at_ms = $8 WHERE record_id = $9 AND rev = $10 AND version = ${RULE_APPROVAL_RECORD_SCHEMA}`), [
             next.state,
             next.rev,
             this.enc(next.candidates, "permission_rule_approval.candidates_json"),
@@ -616,16 +622,21 @@ export function buildRulePayloadHash(candidates) {
 }
 export class SqlRuleImportTicketStore {
     db;
-    now;
-    constructor(db, now = Date.now) {
+    constructor(db) {
         this.db = db;
-        this.now = now;
     }
     q(tidbSql, pgSql) {
         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;
+    }
     async mint(input) {
-        const nowMs = this.now();
+        const nowMs = await this.dbNowMs();
         const expiresAtMs = nowMs + input.ttlMs;
         const payloadHash = buildRulePayloadHash(input.candidates);
         await this.db.query(this.q(`INSERT INTO ${PERMISSION_RULE_TICKET_TABLE} (ticket_id, owner_key, principal, approval_id, payload_hash, payload_json, expires_at_ms, consumed_at_ms, claim_id, purpose, created_at_ms)
@@ -643,8 +654,7 @@ export class SqlRuleImportTicketStore {
         ]);
         return { ticketId: input.ticketId, approvalId: input.approvalId, payloadHash, expiresAtMs };
     }
-    async consume(ticketId, principal, purpose, opts) {
-        const decisionNowMs = opts?.decisionNowMs ?? this.now();
+    async consume(ticketId, principal, purpose) {
         const ownerKey = buildRuleOwnerKey({ kind: "principal", principal });
         const row = await this.readRow(ticketId);
         if (row === undefined)
@@ -655,17 +665,23 @@ export class SqlRuleImportTicketStore {
             return { ok: false, reason: "wrong-purpose" };
         if (row.consumedAtMs !== undefined)
             return { ok: false, reason: "consumed" };
-        if (row.expiresAtMs <= decisionNowMs)
+        if (row.expiresAtMs <= row.dbNowMs)
             return { ok: false, reason: "expired" };
         const claimId = randomUUID();
-        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = ${SQL_DB_NOW_MS.tidb}, claim_id = ? WHERE ticket_id = ? AND owner_key = ? AND purpose = ? AND consumed_at_ms IS NULL AND expires_at_ms > ?`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = ${SQL_DB_NOW_MS.pg}, claim_id = $1 WHERE ticket_id = $2 AND owner_key = $3 AND purpose = $4 AND consumed_at_ms IS NULL AND expires_at_ms > $5`), [claimId, ticketId, ownerKey, purpose, decisionNowMs]);
+        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = ${SQL_DB_NOW_MS.tidb}, claim_id = ? WHERE ticket_id = ? AND owner_key = ? AND purpose = ? AND consumed_at_ms IS NULL AND expires_at_ms > ${SQL_DB_NOW_MS.tidb}`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = ${SQL_DB_NOW_MS.pg}, claim_id = $1 WHERE ticket_id = $2 AND owner_key = $3 AND purpose = $4 AND consumed_at_ms IS NULL AND expires_at_ms > ${SQL_DB_NOW_MS.pg}`), [claimId, ticketId, ownerKey, purpose]);
         if (affected === 1)
             return { ok: true, approvalId: row.approvalId, payloadHash: row.payloadHash, claimId };
+        const after = await this.readRow(ticketId);
+        if (after === undefined)
+            return { ok: false, reason: "unknown" };
+        if (after.consumedAtMs !== undefined)
+            return { ok: false, reason: "consumed" };
+        if (after.expiresAtMs <= after.dbNowMs)
+            return { ok: false, reason: "expired" };
         return { ok: false, reason: "consumed" };
     }
-    async release(ticketId, principal, claimId, mustRemainValidMs = 0, opts) {
-        const nowMs = opts?.decisionNowMs ?? this.now();
-        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = NULL, claim_id = NULL WHERE ticket_id = ? AND owner_key = ? AND claim_id = ? AND consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND expires_at_ms > ?`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = NULL, claim_id = NULL WHERE ticket_id = $1 AND owner_key = $2 AND claim_id = $3 AND consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND expires_at_ms > $4`), [ticketId, buildRuleOwnerKey({ kind: "principal", principal }), claimId, nowMs + mustRemainValidMs]);
+    async release(ticketId, principal, claimId, mustRemainValidMs = 0) {
+        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = NULL, claim_id = NULL WHERE ticket_id = ? AND owner_key = ? AND claim_id = ? AND consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND expires_at_ms > ${SQL_DB_NOW_MS.tidb} + ?`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = NULL, claim_id = NULL WHERE ticket_id = $1 AND owner_key = $2 AND claim_id = $3 AND consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND expires_at_ms > ${SQL_DB_NOW_MS.pg} + $4`), [ticketId, buildRuleOwnerKey({ kind: "principal", principal }), claimId, mustRemainValidMs]);
         return affected === 1;
     }
     async settle(ticketId, principal, claimId, outcome) {
@@ -730,9 +746,9 @@ export function createSqlPermissionRuleStores(db, now) {
     return {
         provider: new SqlPermissionRuleStoreProvider(db, now),
         approvals: new SqlRuleApprovalRecordStore(db, now),
-        tickets: new SqlRuleImportTicketStore(db, now),
+        tickets: new SqlRuleImportTicketStore(db),
         reapExpired: async (nowMs) => {
-            const deadTickets = await db.query(q(`DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE (consumed_at_ms IS NULL AND expires_at_ms <= ?) OR (redeemed_outcome IS NOT NULL AND settled_at_ms IS NOT NULL AND settled_at_ms <= ${SQL_DB_NOW_MS.tidb} - ${RULE_IMPORT_TICKET_GC_GRACE_MS}) OR (consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND consumed_at_ms < ${SQL_DB_NOW_MS.tidb} - ${RULE_PENDING_APPROVAL_RETENTION_MS}) LIMIT ${RULE_REAP_BATCH}`, `DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ctid IN (SELECT ctid FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE (consumed_at_ms IS NULL AND expires_at_ms <= $1) OR (redeemed_outcome IS NOT NULL AND settled_at_ms IS NOT NULL AND settled_at_ms <= ${SQL_DB_NOW_MS.pg} - ${RULE_IMPORT_TICKET_GC_GRACE_MS}) OR (consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND consumed_at_ms < ${SQL_DB_NOW_MS.pg} - ${RULE_PENDING_APPROVAL_RETENTION_MS}) LIMIT ${RULE_REAP_BATCH})`), [nowMs - RULE_IMPORT_TICKET_GC_GRACE_MS]);
+            const deadTickets = await db.query(q(`DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE (consumed_at_ms IS NULL AND expires_at_ms <= ${SQL_DB_NOW_MS.tidb} - ${RULE_IMPORT_TICKET_GC_GRACE_MS}) OR (redeemed_outcome IS NOT NULL AND settled_at_ms IS NOT NULL AND settled_at_ms <= ${SQL_DB_NOW_MS.tidb} - ${RULE_IMPORT_TICKET_GC_GRACE_MS}) OR (consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND consumed_at_ms < ${SQL_DB_NOW_MS.tidb} - ${RULE_PENDING_APPROVAL_RETENTION_MS}) LIMIT ${RULE_REAP_BATCH}`, `DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ctid IN (SELECT ctid FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE (consumed_at_ms IS NULL AND expires_at_ms <= ${SQL_DB_NOW_MS.pg} - ${RULE_IMPORT_TICKET_GC_GRACE_MS}) OR (redeemed_outcome IS NOT NULL AND settled_at_ms IS NOT NULL AND settled_at_ms <= ${SQL_DB_NOW_MS.pg} - ${RULE_IMPORT_TICKET_GC_GRACE_MS}) OR (consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND consumed_at_ms < ${SQL_DB_NOW_MS.pg} - ${RULE_PENDING_APPROVAL_RETENTION_MS}) LIMIT ${RULE_REAP_BATCH})`), []);
             const orphanPending = await db.query(q(`DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE state = 'pending' AND created_at_ms < ? AND NOT EXISTS (SELECT 1 FROM ${PERMISSION_RULE_TICKET_TABLE} t WHERE t.approval_id = ${PERMISSION_RULE_APPROVAL_TABLE}.record_id) LIMIT ${RULE_REAP_BATCH}`, `DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE ctid IN (SELECT a.ctid FROM ${PERMISSION_RULE_APPROVAL_TABLE} a WHERE a.state = 'pending' AND a.created_at_ms < $1 AND NOT EXISTS (SELECT 1 FROM ${PERMISSION_RULE_TICKET_TABLE} t WHERE t.approval_id = a.record_id) LIMIT ${RULE_REAP_BATCH})`), [nowMs - RULE_PENDING_APPROVAL_RETENTION_MS]);
             return deadTickets.affected + orphanPending.affected;
         },

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

@@ -310,25 +310,29 @@ export class PgSessionStore {
             where.push(`(sm.updated_at < ${a} OR (sm.updated_at = ${b} AND sm.session_id < ${sid}))`);
         }
         const sql = "SELECT sm.session_id, sm.owner, sm.updated_at AS last_activity, sm.created_at AS first_activity, sm.title, " +
-            "  COALESCE(r.run_count, 0) AS run_count, latest.objective_preview, latest.status, latest.task_id AS last_run_id " +
+            "  COALESCE(r.run_count, 0) AS run_count, latest.objective_preview, latest.status, latest.task_id AS last_run_id, latest.last_task_run_id " +
             "FROM session_meta sm " +
             "LEFT JOIN (SELECT session_id, COUNT(*) AS run_count FROM task_run GROUP BY session_id) r ON r.session_id = sm.session_id " +
-            "LEFT JOIN (SELECT DISTINCT ON (session_id) session_id, objective_preview, status, task_id FROM task_run " +
+            "LEFT JOIN (SELECT DISTINCT ON (session_id) session_id, objective_preview, status, task_id, result ->> 'runId' AS last_task_run_id FROM task_run " +
             "  ORDER BY session_id, created_at DESC, task_id DESC) latest ON latest.session_id = sm.session_id " +
             (where.length ? "WHERE " + where.join(" AND ") + " " : "") +
             `ORDER BY sm.updated_at DESC, sm.session_id DESC LIMIT ${ph(opts.limit)}`;
         const res = await this.pool.query(sql, params);
-        return res.rows.map((r) => ({
-            sessionId: String(r.session_id),
-            owner: r.owner ?? null,
-            lastActivityAt: r.last_activity instanceof Date ? r.last_activity.toISOString() : String(r.last_activity),
-            firstActivityAt: r.first_activity instanceof Date ? r.first_activity.toISOString() : String(r.first_activity),
-            runCount: Number(r.run_count),
-            objectivePreview: r.objective_preview ?? null,
-            lastStatus: r.status == null ? "" : String(r.status),
-            lastRunId: r.last_run_id ?? null,
-            title: r.title ?? null,
-        }));
+        return res.rows.map((r) => {
+            const runId = r.last_task_run_id;
+            return {
+                sessionId: String(r.session_id),
+                owner: r.owner ?? null,
+                lastActivityAt: r.last_activity instanceof Date ? r.last_activity.toISOString() : String(r.last_activity),
+                firstActivityAt: r.first_activity instanceof Date ? r.first_activity.toISOString() : String(r.first_activity),
+                runCount: Number(r.run_count),
+                objectivePreview: r.objective_preview ?? null,
+                lastStatus: r.status == null ? "" : String(r.status),
+                lastRunId: r.last_run_id ?? null,
+                ...(typeof runId === "string" && runId !== "" ? { lastTaskRunId: runId } : {}),
+                title: r.title ?? null,
+            };
+        });
     }
     async probeTitle(sessionId) {
         const res = await this.pool.query("SELECT title FROM session_meta WHERE session_id = $1", [sessionId]);

package/dist/plugins/remote-scratchpad.js

@@ -1,3 +1,4 @@
+import { redactHead } from "../observability/run-terminal-log.js";
 const REMOTE_SCRATCHPAD_LANES = new Set(["e2b", "k8s", "local-docker", "ssh", "device"]);
 export function isRemoteScratchpadLane(provider) {
     return provider !== undefined && REMOTE_SCRATCHPAD_LANES.has(provider);
@@ -28,12 +29,12 @@ export function withRemoteScratchpad(factory, logger) {
                 if (!r.ok || r.value.exitCode !== 0) {
                     logger?.warn?.("remote_scratchpad_mkdir_failed", {
                         dir,
-                        ...(r.ok ? { exitCode: r.value.exitCode, stderr: r.value.stderr.slice(0, 256) } : { error: r.error.message }),
+                        ...(r.ok ? { exitCode: r.value.exitCode, stderr: redactHead(r.value.stderr, 256) } : { error: redactHead(r.error.message, 512) }),
                     });
                 }
             }
             catch (err) {
-                logger?.warn?.("remote_scratchpad_mkdir_failed", { dir, error: err instanceof Error ? err.message : String(err) });
+                logger?.warn?.("remote_scratchpad_mkdir_failed", { dir, error: redactHead(err instanceof Error ? err.message : String(err), 512) });
             }
         })());
         e.exec = async (command, options) => {

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

@@ -1,47 +1,8 @@
-/**
- * Async run registry (S1) + replayable event log (S2) — SINGLE-FILE DUAL-DIALECT ([ref] A12 定型半场).
- * ONE implementation, TWO dialects; the historical `TiDBRunStore` / `PgRunStore` class names survive as thin
- * ctor subclasses so every consumer (store-backend.ts, the run/reaper/session/usage suites) is untouched.
- *
- * A run is the background execution of one task. `POST /v1/runs` records it `running` and returns
- * immediately; the background driver (`src/runs.ts`) appends events here as they happen and marks the
- * run terminal when done. Because runs + events are durable and shared, any stateless instance can
- * report status or replay the event stream — a client can reconnect (even to a different instance)
- * with `Last-Event-ID` and resume. The two dialects are kept in lock-step by ONE shared integration suite
- * (test/run-store-reaper-integration.test.ts) that runs the SAME park→resume→claim scenario against BOTH
- * real engines — the anti-drift guard.
- *
- * ── Dialect deltas, kept EXPLICIT (never hidden behind an abstraction) ────────────────────────────────
- *   - `?` placeholders vs `$n` (transaction control itself is normalized by `SqlDriver`/`SqlTxConn` —
- *     mysql2's native begin/commit/rollback vs PG's statement form; see sql-driver.ts)
- *   - dup-key classification (createRun's task_active claim race) — the PREDICATE has a single owner
- *     (`sql-errors.ts`, [ref] P1-①); only the dialect DISPATCH is visible here
- *
- * ⚠️ The run ACTIVE-status word list written out in the `status IN (…)` / `NOT IN (…)` fragments below
- * is the closed set owned by `store-contracts.ts` (`isTerminalRunStatus` / `isParkedRunStatus`). The SQL
- * text stays literal ON PURPOSE (A12: both dialects readable side by side), so the tie is a PARITY GATE:
- * `test/source-hygiene-gate.test.ts` → "[ref] P1-② run 活状态 SQL 字面 ↔ store-contracts 闭集属主 parity".
- * core adding a TaskStatus member turns that gate red on every fragment here — update them in the same batch.
- *   - null-safe owner compare: `<=>` (TiDB) vs `IS NOT DISTINCT FROM` (PG) — a null-owner run still matches
- *     `owner=null` on both, single-DB-fleet defense-in-depth (see {@link requestCancel})
- *   - multi-table DELETE: `DELETE t FROM t JOIN j …` (TiDB) vs `DELETE FROM t USING j …` (PG)
- *   - `UPDATE t AS a SET col=…` — PG's SET columns are NOT alias-qualified (PG rejects `SET a.col`), while
- *     TiDB's SET clause DOES qualify (`SET tr.col = …`) — see reapSuspended / failSuspendedWithExpiredCheckpoint
- *   - JSON binding: TiDB `JSON.stringify` verbatim vs PG `pgSafeJsonStringify` + `$n::jsonb` casts
- *   - PG-only protocol-byte defenses on plain-TEXT columns: `pgSanitizeText` on objective_preview (createRun)
- *     and error/error_code (setTerminal) — a raw NUL would throw 22P05 and roll back the whole terminal write,
- *     stranding the run in a live status forever (codex R12); TiDB stores these verbatim
- *   - dynamic multi-clause builders (listRuns/listSessions): TiDB's `?` is position-agnostic so the WHERE
- *     array is built with plain string pushes; PG's `$n` needs numbered placeholders, so those two methods
- *     keep an EXPLICIT per-dialect branch (a shared positional-counter abstraction would hide the very
- *     placeholder-numbering divergence this file exists to keep visible)
- *   - schema ownership: TiDB DDL in tidb-pool.ts, PG DDL centrally in pg-pool.ts (neither store creates tables).
- */
-import type { TaskResult, TaskStatus } from "@sema-agent/core";
+import type { TaskStatus } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type UsageRow } from "../usage-analytics.js";
-import type { RunRecord, SessionSummary, RunEvent } from "./store-contracts.js";
+import type { RunRecord, SessionSummary, RunEvent, PersistedTaskResult } from "./store-contracts.js";
 import { type SqlDriver } from "./sql-driver.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 export type { RunRecord, SessionSummary, RunEvent } from "./store-contracts.js";
@@ -119,7 +80,7 @@ export declare class SqlRunStore {
      *  abort text, or vice versa). Positive form ([1.207 codex M1]): the negative NOT IN missed the
      *  blocked/timeout terminals — a first write of those could still be overwritten. The claim DELETE stays
      *  unconditional (idempotent; the first writer already released it). */
-    setTerminal(taskId: string, status: TaskStatus, result: TaskResult | null, error: string | null): Promise<void>;
+    setTerminal(taskId: string, status: TaskStatus, result: PersistedTaskResult | null, error: string | null): Promise<void>;
     /**
      * Durable F4 ([ref]): a task suspended on a policy `ask`. Sets the run NON-terminal `suspended` and
      * KEEPS the `task_active` claim — the session stays locked (no new run) until an operator resumes it to a

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

@@ -1,7 +1,9 @@
+import { redactErrorMessage, redactLedgerEventData, redactTerminalResult } from "../observability/run-terminal-log.js";
 import { projectUsageStats, USAGE_SCAN_LIMIT } from "../usage-analytics.js";
 import { escapeLike } from "./sql-escape.js";
 import { pgSanitizeText } from "./pg-safe-json.js";
 import { parseJsonLenient as parseJson, toIso as iso } from "./sql-row-helpers.js";
+import { notifyRunTerminal, runTerminalLogLevel } from "../observability/run-terminal-log.js";
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { isDupKeyError } from "./sql-errors.js";
 export class SqlRunStore {
@@ -105,6 +107,7 @@ export class SqlRunStore {
         await this.db.query(this.q("UPDATE task_run SET updated_at = ? WHERE task_id = ? AND owner <=> ? AND status = 'running'", "UPDATE task_run SET updated_at = $1 WHERE task_id = $2 AND owner IS NOT DISTINCT FROM $3 AND status = 'running'"), [new Date(), taskId, owner]);
     }
     async appendEvent(taskId, seq, type, data) {
+        data = redactLedgerEventData(type, data);
         await this.db.query(this.q("INSERT INTO task_event (task_id, seq, type, data, ts) VALUES (?,?,?,?,?)", "INSERT INTO task_event (task_id, seq, type, data, ts) VALUES ($1,$2,$3,$4::jsonb,$5)"), [taskId, seq, type, data == null ? null : this.json(data), new Date()]);
     }
     async maxSeq(taskId) {
@@ -113,9 +116,12 @@ export class SqlRunStore {
         return m == null ? 0 : Number(m);
     }
     async setTerminal(taskId, status, result, error) {
+        result = redactTerminalResult(result);
+        error = error === null ? null : (redactErrorMessage(error) ?? null);
         const errorCode = result?.errorCode ?? null;
+        let observed;
         await this.tx(async (conn) => {
-            await conn.query(this.q("UPDATE task_run SET status = ?, result = ?, error = ?, error_code = ?, updated_at = ? WHERE task_id = ? AND status IN ('running','suspended','needs_review')", "UPDATE task_run SET status = $1, result = $2::jsonb, error = $3, error_code = $4, updated_at = $5 WHERE task_id = $6 AND status IN ('running','suspended','needs_review')"), [
+            const w = await conn.query(this.q("UPDATE task_run SET status = ?, result = ?, error = ?, error_code = ?, updated_at = ? WHERE task_id = ? AND status IN ('running','suspended','needs_review')", "UPDATE task_run SET status = $1, result = $2::jsonb, error = $3, error_code = $4, updated_at = $5 WHERE task_id = $6 AND status IN ('running','suspended','needs_review')"), [
                 status,
                 result == null ? null : this.json(result),
                 this.db.dialect === "tidb" ? error : error == null ? null : pgSanitizeText(error),
@@ -123,8 +129,31 @@ export class SqlRunStore {
                 new Date(),
                 taskId,
             ]);
+            if (w.affected > 0 && runTerminalLogLevel(status, errorCode ?? undefined) !== undefined) {
+                const { rows } = await conn.query(this.q("SELECT owner, session_id, created_at FROM task_run WHERE task_id = ?", "SELECT owner, session_id, created_at FROM task_run WHERE task_id = $1"), [taskId]);
+                const row = rows[0];
+                const createdAt = row ? Date.parse(iso(row.created_at)) : NaN;
+                observed = {
+                    owner: row?.owner ?? null,
+                    sessionId: String(row?.session_id ?? result?.sessionId ?? ""),
+                    createdAt: Number.isFinite(createdAt) ? createdAt : undefined,
+                };
+            }
             await conn.query(this.q("DELETE FROM task_active WHERE task_id = ?", "DELETE FROM task_active WHERE task_id = $1"), [taskId]);
         });
+        if (observed) {
+            notifyRunTerminal({
+                runId: taskId,
+                sessionId: observed.sessionId,
+                owner: observed.owner,
+                status,
+                resultTaskId: result?.taskId,
+                model: result?.model,
+                errorCode: errorCode ?? undefined,
+                errorMessage: result?.errorMessage ?? error ?? undefined,
+                elapsedMs: observed.createdAt === undefined ? undefined : Math.max(0, Date.now() - observed.createdAt),
+            });
+        }
     }
     async setSuspended(taskId) {
         await this.db.query(this.q("UPDATE task_run SET status = 'suspended', updated_at = ? WHERE task_id = ? AND status IN ('running','suspended')", "UPDATE task_run SET status = 'suspended', updated_at = $1 WHERE task_id = $2 AND status IN ('running','suspended')"), [new Date(), taskId]);
@@ -237,8 +266,8 @@ export class SqlRunStore {
                 outer.push("(last_activity < ? OR (last_activity = ? AND session_id < ?))");
                 params.push(new Date(opts.cursor.lastActivityAt), new Date(opts.cursor.lastActivityAt), opts.cursor.sessionId);
             }
-            const sql = "SELECT session_id, owner, task_id, last_activity, first_activity, run_count, objective_preview, status FROM (" +
-                "SELECT session_id, owner, task_id, objective_preview, status," +
+            const sql = "SELECT session_id, owner, task_id, last_activity, first_activity, run_count, objective_preview, status, last_task_run_id FROM (" +
+                "SELECT session_id, owner, task_id, objective_preview, status, JSON_UNQUOTE(JSON_EXTRACT(result, '$.runId')) AS last_task_run_id," +
                 " ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY created_at DESC, task_id DESC) AS rn," +
                 " MAX(created_at) OVER (PARTITION BY session_id) AS last_activity," +
                 " MIN(created_at) OVER (PARTITION BY session_id) AS first_activity," +
@@ -264,8 +293,8 @@ export class SqlRunStore {
             const sid = p(opts.cursor.sessionId);
             outer.push(`(last_activity < ${a} OR (last_activity = ${b} AND session_id < ${sid}))`);
         }
-        const sql = "SELECT session_id, owner, task_id, last_activity, first_activity, run_count, objective_preview, status FROM (" +
-            "SELECT session_id, owner, task_id, objective_preview, status," +
+        const sql = "SELECT session_id, owner, task_id, last_activity, first_activity, run_count, objective_preview, status, last_task_run_id FROM (" +
+            "SELECT session_id, owner, task_id, objective_preview, status, result ->> 'runId' AS last_task_run_id," +
             " ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY created_at DESC, task_id DESC) AS rn," +
             " MAX(created_at) OVER (PARTITION BY session_id) AS last_activity," +
             " MIN(created_at) OVER (PARTITION BY session_id) AS first_activity," +
@@ -276,6 +305,7 @@ export class SqlRunStore {
         return rows.map((r) => this.rowToSession(r));
     }
     rowToSession(r) {
+        const lastTaskRunId = r.last_task_run_id;
         return {
             sessionId: String(r.session_id),
             owner: r.owner ?? null,
@@ -285,6 +315,7 @@ export class SqlRunStore {
             objectivePreview: r.objective_preview ?? null,
             lastStatus: String(r.status),
             lastRunId: r.task_id ?? null,
+            ...(typeof lastTaskRunId === "string" && lastTaskRunId !== "" ? { lastTaskRunId } : {}),
             title: null,
         };
     }

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

@@ -95,7 +95,7 @@ export type ImageBake = TiDBImageBake | PgImageBake;
 /** [ref] 车4 件1:durable leader-run 登记表的双方言孪生(union 同族——TS 私有字段让具体类名义上不同)。 */
 export type LeaderRunStore = TiDBLeaderRunStore | PgLeaderRunStore;
 /** The FULL checkpoint store (core CheckpointStore + the service operator-queue/ctx methods listPending/
- *  listByScope/findPendingTokenBySession/peekPendingScope/putCtx/getCtx/reapCtx) — the SQL twins carry them,
+ *  listByScope/findPendingTokenBySession/peekPendingScope/peekScopeByToken/putCtx/getCtx/reapCtx) — the SQL twins carry them,
  *  and the LOCAL lane now does too (core FileCheckpointStore + the service half — TOC plan-mode /
  *  durable HITL work on one box). */
 export type CheckpointStoreFull = TiDBCheckpointStore | PgCheckpointStore | LocalCheckpointStore;