@sema-agent/server 7.2.0 → 7.4.0

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

@@ -27,7 +27,7 @@
  *   - schema ownership: TiDB DDL in tidb-pool.ts, PG DDL centrally in pg-pool.ts (neither store creates tables).
  */
 import { createHash } from "node:crypto";
-import { CheckpointError, validatePendingSteer, checkpointVersionOf, winnerFromOutcome, summarizeCheckpoint, MAX_SUPPORTED_CHECKPOINT_VERSION, } from "@sema-agent/core";
+import { CheckpointError, validatePendingSteer, appendPendingSteer, checkpointVersionOf, winnerFromOutcome, summarizeCheckpoint, MAX_SUPPORTED_CHECKPOINT_VERSION, } from "@sema-agent/core";
 import { redactDeep } from "../trace/redact.js";
 import { parseJsonStrict as parseJson } from "./sql-row-helpers.js";
 import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "./sql-driver.js";
@@ -76,8 +76,154 @@ export function boundedToolInput(args) {
         return { truncated: true, bytes: json.length };
     return redacted;
 }
+/**
+ * checkpoint blob → `pendingAction.toolCallId`。
+ *
+ * 🔴 三态、**不是**两态(真双库实跑抓到的缺陷,2026-08-06):「读不出」与「读出来了、但这条 park 本来就
+ * 没有 toolCallId」是两件事,压成同一个 `undefined` 会把每一条 `plan_review`/`task_done`/`resource_limit`
+ * 腿(core 的 `PendingAction` 联合里三个成员结构上就没有 toolCallId)都误报成坏行。前者应标 `unparseable`
+ * 交给收敛器当「不确定」,后者是**确定的不匹配**——干净地不是候选。
+ *  - `{ readable: false }`        —— JSON 坏 / 形状根本不是对象:真的读不出。
+ *  - `{ readable: true, toolCallId: null }` —— 读出来了,这条 park 无工具动作:确定不匹配。
+ *  - `{ readable: true, toolCallId: "…" }`  —— 读出来了,拿去比。
+ *
+ * 逐层 `typeof` 收窄,不做裸 `as` 断言:blob 是持久层读回来的 `unknown`,是信任边界(宪法 [2704])。
+ */
+function pendingActionToolCallId(blob) {
+    let parsed;
+    try {
+        parsed = typeof blob === "string" ? JSON.parse(blob) : blob;
+    }
+    catch {
+        return { readable: false };
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return { readable: false };
+    if (!("pendingAction" in parsed))
+        return { readable: true, toolCallId: null, boundInputHash: null, kind: null }; // 无 pendingAction 的 park:确定不匹配
+    const pa = parsed.pendingAction;
+    if (typeof pa !== "object" || pa === null)
+        return { readable: false };
+    const kind = "kind" in pa ? pa.kind : null;
+    if (kind !== null && typeof kind !== "string")
+        return { readable: false };
+    if (!("toolCallId" in pa))
+        return { readable: true, toolCallId: null, boundInputHash: null, kind }; // plan_review / task_done / resource_limit 腿
+    const id = pa.toolCallId;
+    if (typeof id !== "string")
+        return { readable: false };
+    // 🔴(属主兜底轮 F1)带 toolCallId 却挂着词表外的 kind = 结构漂移,不是「读得出」——这条 blob 声称
+    // 自己是一次工具审批 park(有 callId)又否认(kind 不是 tool_approval)。让它带着匹配的 callId 混进
+    // 健康候选,等于给「外部改库 / schema 偏斜」开一条错配 PARK 的路。词表判据窄取 "tool_approval":
+    // 其余合法 kind(plan_review 等)在 core 的类型里结构上**没有** toolCallId,走不到这里。
+    if (kind !== "tool_approval")
+        return { readable: false };
+    // hash 只做逐层收窄,不在这层与列比对(比对是调用处的列/blob 一致性门)。缺席 = null(旧行/无 hash 形)。
+    const bih = "boundInputHash" in pa ? pa.boundInputHash : null;
+    if (bih !== null && typeof bih !== "string")
+        return { readable: false };
+    return { readable: true, toolCallId: id, boundInputHash: bih, kind };
+}
 const DUP_ENTRY = 1062; // MySQL/TiDB ER_DUP_ENTRY
 const PG_UNIQUE_VIOLATION = "23505";
+function readActorAssertion(v) {
+    if (typeof v !== "object" || v === null)
+        return undefined;
+    const id = "id" in v ? v.id : undefined;
+    const hostAsserted = "hostAsserted" in v ? v.hostAsserted : undefined;
+    if (typeof id !== "string" || typeof hostAsserted !== "boolean")
+        return undefined;
+    const issuer = "issuer" in v ? v.issuer : undefined;
+    return { id, hostAsserted, ...(typeof issuer === "string" ? { issuer } : {}) };
+}
+/** 队列化之前的**裸单座**形(`{text,trusted}`)—— 旧行原样躺在库里,core 的 `readPendingSteerQueue`
+ *  会把它折成 member 0,所以读出来照原样保留、不改写、不迁移。 */
+function readLegacySeat(v) {
+    if (typeof v !== "object" || v === null)
+        return undefined;
+    const text = "text" in v ? v.text : undefined;
+    const trusted = "trusted" in v ? v.trusted : undefined;
+    if (typeof text !== "string" || typeof trusted !== "boolean")
+        return undefined;
+    return { text, trusted };
+}
+/** 队列条目的逐层窄读(持久层读回的是 `unknown`,是信任边界 —— 禁裸 `as`)。四个必备键任一不合形 ⇒
+ *  整条不认(返回 undefined,由调用方判 lossy);`actor`/`priority` 可选,不合形即缺席。 */
+function readQueueEntry(v) {
+    if (typeof v !== "object" || v === null)
+        return undefined;
+    const text = "text" in v ? v.text : undefined;
+    const trusted = "trusted" in v ? v.trusted : undefined;
+    const seq = "seq" in v ? v.seq : undefined;
+    const inputId = "inputId" in v ? v.inputId : undefined;
+    if (typeof text !== "string" || typeof trusted !== "boolean")
+        return undefined;
+    if (typeof seq !== "number" || !Number.isFinite(seq))
+        return undefined;
+    if (typeof inputId !== "string" || inputId === "")
+        return undefined;
+    const priority = "priority" in v ? v.priority : undefined;
+    const actor = readActorAssertion("actor" in v ? v.actor : undefined);
+    return {
+        text,
+        trusted,
+        seq,
+        inputId,
+        ...(actor !== undefined ? { actor } : {}),
+        ...(priority === "now" || priority === "next" || priority === "later" ? { priority } : {}),
+    };
+}
+/**
+ * 两个 steering 列 → `{pendingSteer?, pendingSteerQueue?}`(= core `appendPendingSteer`/`readPendingSteerQueue`
+ * 的入参形)。**两列各管一形**,不是一列两形:
+ *  · `pending_steer`(旧列,本服务只读不写)—— 裸单座 `{text, trusted}`。来源有二:队列化之前的存量行,
+ *    以及**滚动升级窗里仍在跑的旧副本**写下的座。core 的 `readPendingSteerQueue` 把它折成 member 0。
+ *  · `pending_steer_queue`(新列)—— `PendingSteerEntry[]`。
+ * 任一列有内容却读不出 ⇒ `lossy`(两个调用点对它的处置见 {@link SteerColumnRead})。
+ */
+export function readPendingSteerColumns(seatRaw, queueRaw) {
+    let lossy = false;
+    const parse = (raw) => {
+        if (raw === null || raw === undefined)
+            return undefined;
+        if (typeof raw !== "string")
+            return raw;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            lossy = true;
+            return undefined;
+        }
+    };
+    const seatParsed = parse(seatRaw);
+    const seat = seatParsed === undefined ? undefined : readLegacySeat(seatParsed);
+    if (seatParsed !== undefined && seat === undefined)
+        lossy = true;
+    const queueParsed = parse(queueRaw);
+    let queue;
+    if (queueParsed !== undefined) {
+        if (!Array.isArray(queueParsed))
+            lossy = true;
+        else {
+            queue = [];
+            for (const item of queueParsed) {
+                const entry = readQueueEntry(item);
+                if (entry === undefined)
+                    lossy = true;
+                else
+                    queue.push(entry);
+            }
+        }
+    }
+    return {
+        state: { ...(seat !== undefined ? { pendingSteer: seat } : {}), ...(queue !== undefined ? { pendingSteerQueue: queue } : {}) },
+        lossy,
+    };
+}
+/** 读-改-写的 CAS 重试上限。队列本身只有 `MAX_PENDING_STEER_ENTRIES`(= 3)个位子,再多就 fail-loud,
+ *  所以真实争用者数量天然很小;给足冗余后仍然全败 ⇒ 是异常,必须 fail-loud(见 setPendingSteer 尾注)。 */
+const STEER_CAS_ATTEMPTS = 8;
 /** Dual-dialect durable CheckpointStore. See the file header for the dialect-delta ledger. */
 export class SqlCheckpointStore {
     db;
@@ -136,7 +282,7 @@ export class SqlCheckpointStore {
         }
     }
     async get(token) {
-        const { rows } = await this.db.query(this.q("SELECT version, status, checkpoint, outcome, reopen_reason, rev, pending_steer FROM checkpoint WHERE token = ?", "SELECT version, status, checkpoint, outcome, reopen_reason, rev, pending_steer FROM checkpoint WHERE token = $1"), [token]);
+        const { rows } = await this.db.query(this.q("SELECT version, status, checkpoint, outcome, reopen_reason, rev, pending_steer, pending_steer_queue FROM checkpoint WHERE token = ?", "SELECT version, status, checkpoint, outcome, reopen_reason, rev, pending_steer, pending_steer_queue FROM checkpoint WHERE token = $1"), [token]);
         const r = rows[0];
         if (!r)
             return null;
@@ -163,9 +309,22 @@ export class SqlCheckpointStore {
         cp.rev = r.rev == null ? 0 : Number(r.rev); // legacy/pre-migration rows ⇒ 0 (the .d.ts "Absent ⇒ legacy 0")
         // design/80 D-A: overlay the parked steer off the AUTHORITATIVE column (set by setPendingSteer AFTER the
         // suspend-time blob was written) so core injects it on resume. The blob never carries it.
-        const steerRaw = parseJson(r.pending_steer);
-        if (steerRaw && cp.state)
-            cp.state.pendingSteer = steerRaw;
+        // core 5.14.0(#147):列现在承载**两个**字段 —— 队列本体 + 旧行折下来的裸单座。两者都要盖上去,
+        // core 的 `readPendingSteerQueue` 才能把「legacy 座 = member 0,其余按 seq」拼成完整投递序。
+        // 🔴 坏列在这里**只丢 steer、不抛**:resume 是这条挂起的 run 唯一的出路,为一条读不出的转向把整条
+        // run 变成不可 resume 是错误的失败方向(写侧相反,见 setPendingSteer)。
+        const steer = readPendingSteerColumns(r.pending_steer, r.pending_steer_queue);
+        if (steer.lossy) {
+            // 「静默」到此为止:读不出的部分确实丢了(投递腿不能为一条坏列把整条 run 变成不可 resume),
+            // 但它必须**留痕** —— 丢的是操作员指令,而 #147 的全部意义就是这类丢失不许无声。
+            this.logger?.info?.("checkpoint_pending_steer_unreadable", { tokenFp: tokenFingerprint(token) });
+        }
+        if (cp.state) {
+            if (steer.state.pendingSteer !== undefined)
+                cp.state.pendingSteer = steer.state.pendingSteer;
+            if (steer.state.pendingSteerQueue !== undefined)
+                cp.state.pendingSteerQueue = steer.state.pendingSteerQueue;
+        }
         // Diagnostic: log what the REAL runner.resume store.get returns for the remote
         // workspaceHandle (the isolated round-trip test can't prove the real-path get). undefined here ⇒ store/get
         // drops it; present ⇒ core's 910→614 threading drops it. Cheap, on the resume read-path only.
@@ -227,20 +386,61 @@ export class SqlCheckpointStore {
         return res.affected === 1;
     }
     /**
-     * design/80 D-A (durable steering): park a steer message on a STILL-PENDING checkpoint (last-writer-wins),
-     * surfaced via get() as `state.pendingSteer` and injected on resume. CAS on `status='pending'` (+ scope) so a
-     * steer NEVER lands on a resolved/expired checkpoint and NEVER touches status/the resolve path (§3 inv #4).
-     * Returns the CAS winner (`true` = landed on a live pending checkpoint; `false` = no pending row to steer).
+     * design/80 D-A (durable steering) —— **core 5.14.0(#147 BREAKING)起是「追加进一条有界有序队列」**,
+     * 不再是「盖掉单座」。两个人同时给一条挂起的 run 转向,旧语义会让第二条**静默销毁**第一条(一条没人
+     * 知道丢了的操作员指令);新语义是两条都在,resume 按 `seq` 全数投递。
+     *
+     * 语义与边界**全部铸在 core**,本 store 一个都不自铸(契约原文:`appendPendingSteer` is "the shared
+     * append every backend must build its next queue with: bounds + `seq` mint live there, not once per store"):
+     *  · `validatePendingSteer` —— 每个 impl 内部必跑的 fail-closed 不变式(M2,接入审计 2026-07-08):内容
+     *    越狱/控制字符 `steering.invalid_content`;**未知字段现在是 REFUSE 而不是丢弃**(领先一个版本的
+     *    producer 必须知道自己的新字段活不过这条挂起的腿);缺席的 `inputId` 在这里铸(uuidv7)。
+     *  · `appendPendingSteer` —— 铸 `seq`、判 `inputId` 幂等(同 id 同载荷 = no-op 返回 true;同 id **不同**
+     *    载荷 = `steering.duplicate_input_id`,吞掉它就等于把队列要消灭的那种静默丢失原样请回来)、
+     *    执行两条上界(条数 + 48000 字节整信封),越界一律 `steering.queue_full` fail-loud,**绝不驱逐**
+     *    一条已被接受的指令。
+     *
+     * 🔴 从「一条无条件 UPDATE」变成「读-改-写」,中间那道窗必须自己有 CAS:两个并发 steer 读到同一份
+     * 队列、后写者整个盖掉前者 —— 就是 #147 要消灭的静默丢失换了个位置复发。守卫是 `pending_steer_rev`
+     * **专用整数列**(不是拿旧列值比:本表无显式 COLLATE,*_ci 排序规则会把只差大小写的两份信封判等 ⇒
+     * CAS 假命中;也不是复用 resolve 的 `rev`:bump 它会让并发 resume 的 `resolve(expect)` 白白落败)。
+     * CAS 输了就重读重算(队列只有 3 个位子,争用者天然极少);给足冗余仍全败 ⇒ **抛**,不返回 false ——
+     * `false` 在调用方的语义是「没有 pending 行可转向」(HTTP 409「已不再挂起」),把争用报成那个是撒谎。
+     *
+     * 返回:`true` = 落在一条活的 pending 行上(含幂等重放);`false` = 没有该 (token,scope) 的 pending 行。
      */
     async setPendingSteer(token, scope, steer) {
-        // M2(接入审计 2026-07-08):契约把 validatePendingSteer 定为【每个 impl 内部】必跑的 fail-closed 不变式
-        // ("EVERY CheckpointStore.setPendingSteer impl runs [it] so the reject is IDENTICAL across the in-memory and
-        // durable backends")——core 自家 File/InMemory/Pg 三 impl 全有;此前这里裸写 UPDATE=靠调用方自觉(HTTP 层
-        // 三处前置校验只是碰巧全覆盖,下一个内部调用方不一定记得)。clean = 冻结 {text,trusted} 两字段拷贝
-        // (调用方对象上的多余字段绝不落库,契约同款)。
         const clean = validatePendingSteer(steer); // throws CheckpointError(steering.invalid_content) — per-impl 一致拒绝
-        const res = await this.db.query(this.q("UPDATE checkpoint SET pending_steer = ? WHERE token = ? AND scope = ? AND status = 'pending'", "UPDATE checkpoint SET pending_steer = $1 WHERE token = $2 AND scope = $3 AND status = 'pending'"), [this.json(clean, "pending steer"), token, scope]);
-        return res.affected > 0;
+        for (let attempt = 0; attempt < STEER_CAS_ATTEMPTS; attempt++) {
+            const { rows } = await this.db.query(this.q("SELECT status, pending_steer, pending_steer_queue, pending_steer_rev FROM checkpoint WHERE token = ? AND scope = ?", "SELECT status, pending_steer, pending_steer_queue, pending_steer_rev FROM checkpoint WHERE token = $1 AND scope = $2"), [token, scope]);
+            const row = rows[0];
+            if (!row || row.status !== "pending")
+                return false; // 没有活的 pending 行(与旧的 CAS 落空同义)
+            const read = readPendingSteerColumns(row.pending_steer, row.pending_steer_queue);
+            if (read.lossy) {
+                // 🔴 写侧与 get() 的失败方向刻意相反:往一份读不全的队列上追加,写回时就会把读不出的那部分
+                // **永久抹掉** —— 那正是 #147 存在的理由(静默丢一条已 park 的操作员指令)。宁可这一次转向失败。
+                throw new Error(`the parked steering queue on checkpoint ${tokenFingerprint(token)} is unreadable — refusing to append onto it ` +
+                    `(appending would silently drop the entries this build cannot parse)`);
+            }
+            const before = read.state.pendingSteerQueue?.length ?? 0;
+            const next = appendPendingSteer(read.state, clean); // throws steering.queue_full / steering.duplicate_input_id
+            // 幂等重放(同 inputId 同载荷):core 原样奉还既有队列 ⇒ 一个字都不用写,也不必烧一个 rev。
+            if (next.length === before)
+                return true;
+            const rev = Number(row.pending_steer_rev ?? 0);
+            // 🔴 只写队列列 —— `pending_steer`(旧单座列)本服务**从不写**:滚动升级窗里旧副本对那一列是无条件
+            // 覆盖写,两边写同一列 = 互相清零(codex 复审 F3)。分列之后旧副本的座与新队列共存,读侧合并。
+            const res = await this.db.query(this.q("UPDATE checkpoint SET pending_steer_queue = ?, pending_steer_rev = pending_steer_rev + 1 " +
+                "WHERE token = ? AND scope = ? AND status = 'pending' AND pending_steer_rev = ?", "UPDATE checkpoint SET pending_steer_queue = $1, pending_steer_rev = pending_steer_rev + 1 " +
+                "WHERE token = $2 AND scope = $3 AND status = 'pending' AND pending_steer_rev = $4"), [this.json(next, "pending steer queue"), token, scope, rev]);
+            if (res.affected > 0)
+                return true;
+            // CAS 输了:另一个 steer 抢先追加(或这行刚被 resolve/expire)⇒ 重读重算。下一轮的 SELECT 会
+            // 分辨这两种情形:行还 pending 就再追加一次,不 pending 就返回 false。
+        }
+        throw new Error(`setPendingSteer lost the pending_steer_rev CAS ${STEER_CAS_ATTEMPTS} times on checkpoint ${tokenFingerprint(token)} — ` +
+            `refusing to report it as "no pending checkpoint" (that would silently discard an operator instruction)`);
     }
     /**
      * CAS-expire a SINGLE checkpoint by token (core 1.71 `CheckpointStore.expire`, for `TaskStream.destroy`'s
@@ -377,6 +577,87 @@ export class SqlCheckpointStore {
             : await this.db.query(this.q("SELECT token FROM checkpoint WHERE session_id=? AND status='pending' LIMIT 1", "SELECT token FROM checkpoint WHERE session_id=$1 AND status='pending' LIMIT 1"), [sessionId]);
         return rows[0] ? String(rows[0].token) : null;
     }
+    /**
+     * 🔴 #151 车5 §9 C4 —— 流内审批对账收敛器判据 1 的**窄读口**(店面承载;收敛器本体不在本车)。
+     *
+     * 「这条 PARKING 的 ask 究竟 park 成了哪张 checkpoint?」的唯一读法。为什么不是「按 session 翻历史页」:
+     * 分页宽读会漏匹配,而漏匹配在收敛器那侧的后果是**假阴性 ⇒ 落一条不可逆的 DENIED**。所以这里改成
+     * 谓词精确查——`(scope, session_id, tool_call_id, created_at ≥ sinceMs)` 这组条件下的行数天然极小,
+     * 一次全量返回,结构上没有分页假阴性。
+     *
+     * 三条口径,逐条都是判据:
+     *  - **`scope` 必填**(不是 optional):对账是跨腿读,租户门是读口自己的责任,不靠调用方记得过滤
+     *    (同 `listPendingBySession` 姿势;`resolve`/`reap` 的 scope enforced 同族)。
+     *  - **不按 status 过滤**:已 `resolved`/`expired` 的行照样返回。后到的 resume 会把行翻成 resolved,
+     *    若只看 pending 就会把「park 成功过」这个既成事实读成「没 park 过」⇒ 又是一条假阴性 DENIED
+     *    (对账三约束③)。park 成功是事实,gate 的活性由 `status` 表达,交给收敛器自己判。
+     *  - **单行读不出 ⇒ 标记返回,不抛**:`unparseable` 的行由收敛器视同「不匹配」,一条坏行不许打断整段
+     *    扫描(§8 C-6)。什么算读不出:blob 的 `version` 超出本 build 支持(`get()` 那条前向兼容门在这里
+     *    不能 throw,否则一条超前行会让整个 session 的对账永久卡死)、或 blob JSON 坏。
+     *
+     * 匹配是两段的:`tool_call_id` **列**是 `put()` 从 `pendingAction.toolCallId` 盖下来的权威投影,命中它
+     * 的行零解析即候选;列为 NULL 的行(无工具动作的 park,或列存在之前的旧行)才回落去解 blob——解得出且
+     * 相等才算候选,解不出就标 `unparseable`。
+     */
+    async findCheckpointCandidatesForAsk(scope, sessionId, toolCallId, sinceMs) {
+        const { rows } = await this.db.query(this.q("SELECT token, status, created_at, tool_call_id, bound_input_hash, version, checkpoint FROM checkpoint " +
+            "WHERE scope=? AND session_id=? AND created_at>=? AND (tool_call_id=? OR tool_call_id IS NULL) ORDER BY created_at ASC", "SELECT token, status, created_at, tool_call_id, bound_input_hash, version, checkpoint FROM checkpoint " +
+            "WHERE scope=$1 AND session_id=$2 AND created_at>=$3 AND (tool_call_id=$4 OR tool_call_id IS NULL) ORDER BY created_at ASC"), [scope, sessionId, sinceMs, toolCallId]);
+        const out = [];
+        for (const r of rows) {
+            const base = {
+                token: String(r.token),
+                status: String(r.status),
+                createdAtMs: Number(r.created_at),
+                boundInputHash: r.bound_input_hash == null ? null : String(r.bound_input_hash),
+            };
+            // 🔴 前向兼容门必须在**任何**命中路径之前(codex 复审 F3,2026-08-06 真缺陷):版本超前的行是
+            // `get()` 明确拒读的行,而 `tool_call_id` 列命中与否跟能不能读懂 blob 毫无关系。若让列的快路径
+            // 绕过这道门,收敛器就会把它当健康候选去 `bindBatch` ⇒ ask 被钉成 **PARKED + 一张本进程读不出的
+            // checkpoint 的 resume 坐标**,而 PARKED 不可回滚。判据只能是「宁可不命中,绝不错配」(§8 D-2)。
+            // 门在这里**不抛**(见头注):标 unparseable 交给收敛器当「不确定」,单行不打断整段扫描。
+            if (Number(r.version) > MAX_SUPPORTED_CHECKPOINT_VERSION) {
+                out.push({ ...base, boundCallId: null, unparseable: true });
+                continue;
+            }
+            // 🔴 blob 可读性同样门在**所有**命中路径之前(codex 确认轮补抓):`tool_call_id` 列长得对,不代表
+            // 这张 checkpoint 读得出来——列是 put() 时的投影,blob 才是 resume 真正要吃的东西。让「列命中」
+            // 跳过可读性检查,等于给「blob 损坏 / schema 偏斜」留了一条与 F3 完全相同的不可逆后果:
+            // 收敛器把 ask 钉成 PARKED + 这张 checkpoint 的坐标,而后续 `get()` 必然失败。
+            // 读口的契约只有一条——**读不出就标记**,没有「有一列长得对就豁免」的例外。
+            const derived = pendingActionToolCallId(r.checkpoint);
+            if (!derived.readable) {
+                out.push({ ...base, boundCallId: null, unparseable: true });
+                continue;
+            }
+            const col = r.tool_call_id == null ? null : String(r.tool_call_id);
+            // 列与 blob **互相矛盾** ⇒ 判别不出谁对,标 unparseable(「宁可不命中,绝不错配」,§8 D-2)。
+            // 🔴 矛盾的定义是「列说得出、而 blob 不同意」——同时覆盖两形:blob 给了**别的** callId,以及
+            // blob 说这条 park **根本没有工具动作**(`toolCallId === null`)。后者一样是漂移(列声称有一次
+            // 工具调用、blob 否认),早先只判「两边都非空且不等」会把它漏成健康候选。
+            // 现网 put() 把列与 blob 同源同刻写下,矛盾只可能来自外部改库或 schema 偏斜——正是该保守的场合。
+            if (col !== null && col !== derived.toolCallId) {
+                out.push({ ...base, boundCallId: null, unparseable: true });
+                continue;
+            }
+            // 🔴 bound_input_hash 的列/blob 一致性门(属主兜底轮 F1)——与上面 toolCallId 的矛盾门同款:
+            // 返回给收敛器的 hash 是「identity ∧ hash 双等」硬谓词的**输入**,列被外部改成漂移值(乃至恰好
+            // 改成另一只 ask 的 hash)时,只信列 = 把双等谓词架空成单等。两边都在场且不等 ⇒ unparseable;
+            // 列 NULL 而 blob 有值 ⇒ 用 blob 值补齐(旧行回落,与 toolCallId 的「列 NULL 回落 blob」同规)。
+            if (base.boundInputHash !== null && derived.boundInputHash !== null && base.boundInputHash !== derived.boundInputHash) {
+                out.push({ ...base, boundCallId: null, unparseable: true });
+                continue;
+            }
+            const effectiveHash = base.boundInputHash ?? derived.boundInputHash;
+            // 列在场时以列为准(权威投影);列为 NULL 的旧行回落用 blob 解出来的值。
+            const effective = col ?? derived.toolCallId;
+            if (effective === toolCallId)
+                out.push({ ...base, boundInputHash: effectiveHash, boundCallId: effective });
+            // 解得出、但不是这只 ask 的 callId(或这条 park 本来就没有工具动作)⇒ **确定**不是候选:
+            // 既不返回也不标坏行(标坏行会让收敛器把一条明确的「不匹配」当成「不确定」)。
+        }
+        return out;
+    }
     /**
      * The owner SCOPE of a session's pending checkpoint (the multi-tenant key === the owner principal in the
      * BFF/non-operator flow, the same key listPending filters by). For the /decide owner-gate: a non-operator

package/dist/plugins/file-workflow-journal-store.d.ts

@@ -0,0 +1,12 @@
+/**
+ * SVC-2 — FILE-backed durable WorkflowJournalStore for the LOCAL (TOC) backend.
+ *
+ * Now a RE-EXPORT of core's copy (the write-here-then-core-adopts 剧本): the implementation was written here for server
+ * 1.89.0, then adopted verbatim by core (`@sema-agent/core` 1.223.0, file
+ * `src/stores/file/workflow-journal-store.ts` — crash-safe per-run JSONL, scope-guarded [CORE-9],
+ * idempotent-per-ordinal, oversize skip-journal, traversal-runId load degrade, 0o600/0o700). One source of
+ * truth in core; the SQL twins (tidb/pg) stay service-side (dialect = deployment glue). The service test
+ * suite (test/file-workflow-journal-store.test.ts) keeps pinning the contract through this re-export.
+ */
+export { FileWorkflowJournalStore } from "@sema-agent/core";
+//# sourceMappingURL=file-workflow-journal-store.d.ts.map

package/dist/plugins/file-workflow-journal-store.js

@@ -0,0 +1,12 @@
+/**
+ * SVC-2 — FILE-backed durable WorkflowJournalStore for the LOCAL (TOC) backend.
+ *
+ * Now a RE-EXPORT of core's copy (the write-here-then-core-adopts 剧本): the implementation was written here for server
+ * 1.89.0, then adopted verbatim by core (`@sema-agent/core` 1.223.0, file
+ * `src/stores/file/workflow-journal-store.ts` — crash-safe per-run JSONL, scope-guarded [CORE-9],
+ * idempotent-per-ordinal, oversize skip-journal, traversal-runId load degrade, 0o600/0o700). One source of
+ * truth in core; the SQL twins (tidb/pg) stay service-side (dialect = deployment glue). The service test
+ * suite (test/file-workflow-journal-store.test.ts) keeps pinning the contract through this re-export.
+ */
+export { FileWorkflowJournalStore } from "@sema-agent/core";
+//# sourceMappingURL=file-workflow-journal-store.js.map

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

@@ -1,4 +1,4 @@
-import { type Checkpoint, type CheckpointSummary, type CheckpointToken, type ReopenReason, type ResolveExpectation, type ResumeOutcome } from "@sema-agent/core";
+import { type Checkpoint, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ReopenReason, type ResolveExpectation, type ResumeOutcome } from "@sema-agent/core";
 import { type PendingCheckpoint } from "./checkpoint-store-sql.js";
 export interface LocalCheckpointStoreOptions {
     /** taskId join for the pending card (the local FileRunStore's `getActiveTaskId`). Absent ⇒ `taskId: null`. */
@@ -31,10 +31,11 @@ export declare class LocalCheckpointStore {
     get(token: CheckpointToken): Promise<Checkpoint | null>;
     resolve(token: CheckpointToken, scope: string, outcome: ResumeOutcome, expect?: ResolveExpectation): Promise<boolean>;
     reopen(token: CheckpointToken, scope: string, reason: ReopenReason): Promise<boolean>;
-    setPendingSteer(token: CheckpointToken, scope: string, steer: {
-        text: string;
-        trusted: boolean;
-    }): Promise<boolean>;
+    /** core 5.14.0(#147):入参是 `PendingSteerInput`(text/trusted + 可选 actor/inputId/priority),不是
+     *  两键单座 —— 形参窄成 `{text,trusted}` 会**静默丢掉**署名与幂等键(TS 的方法参数是双变的,窄形不
+     *  报错,只是把三个可选键从类型上抹掉,调用点再也传不进来)。队列语义与边界全在被包的 core
+     *  `FileCheckpointStore` 里,本 wrapper 只做转发。 */
+    setPendingSteer(token: CheckpointToken, scope: string, steer: PendingSteerInput): Promise<boolean>;
     expire(token: CheckpointToken, scope: string): Promise<boolean>;
     reap(scope: string, cutoff: number): Promise<number>;
     listByScope(scope: string): Promise<CheckpointSummary[]>;

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

@@ -133,6 +133,10 @@ export class LocalCheckpointStore {
     reopen(token, scope, reason) {
         return this.inner.reopen(token, scope, reason);
     }
+    /** core 5.14.0(#147):入参是 `PendingSteerInput`(text/trusted + 可选 actor/inputId/priority),不是
+     *  两键单座 —— 形参窄成 `{text,trusted}` 会**静默丢掉**署名与幂等键(TS 的方法参数是双变的,窄形不
+     *  报错,只是把三个可选键从类型上抹掉,调用点再也传不进来)。队列语义与边界全在被包的 core
+     *  `FileCheckpointStore` 里,本 wrapper 只做转发。 */
     setPendingSteer(token, scope, steer) {
         return this.inner.setPendingSteer(token, scope, steer);
     }

package/dist/plugins/pg-approval-store.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Thin re-export shim (design/158 A12 收编 — see src/plugins/approval-store-sql.ts for the
+ * implementation, now SINGLE-FILE DUAL-DIALECT alongside the TiDB twin). Class name, ctor arity,
+ * and every exported type/const/helper stay EXACTLY as they were so no consumer (pg-pool.ts's
+ * central schema composition, store-backend.ts, test/pg-approval-store-integration.test.ts) has
+ * to move.
+ */
+export { PgApprovalStore, PG_APPROVAL_SCHEMA, ensureSchema, type ApprovalRow, type ApprovalStatus, } from "./approval-store-sql.js";
+//# sourceMappingURL=pg-approval-store.d.ts.map

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

@@ -0,0 +1,9 @@
+/**
+ * Thin re-export shim (design/158 A12 收编 — see src/plugins/approval-store-sql.ts for the
+ * implementation, now SINGLE-FILE DUAL-DIALECT alongside the TiDB twin). Class name, ctor arity,
+ * and every exported type/const/helper stay EXACTLY as they were so no consumer (pg-pool.ts's
+ * central schema composition, store-backend.ts, test/pg-approval-store-integration.test.ts) has
+ * to move.
+ */
+export { PgApprovalStore, PG_APPROVAL_SCHEMA, ensureSchema, } from "./approval-store-sql.js";
+//# sourceMappingURL=pg-approval-store.js.map

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

@@ -0,0 +1,8 @@
+/**
+ * Re-export shim (design/158 A12 收编) — the real implementation moved to breaker-state-sql.ts
+ * (single-file dual-dialect: `SqlBreakerState` + the `TiDBBreakerState`/`PgBreakerState` ctor subclasses).
+ * Kept so every consumer's `from "./pg-breaker-state.js"` import (incl. pg-pool.ts's central ensureSchema
+ * composition and the real dual-DB integration suite) keeps working unchanged.
+ */
+export { PgBreakerState, PG_BREAKER_STATE_SCHEMA, ensureSchema } from "./breaker-state-sql.js";
+//# sourceMappingURL=pg-breaker-state.d.ts.map

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

@@ -0,0 +1,8 @@
+/**
+ * Re-export shim (design/158 A12 收编) — the real implementation moved to breaker-state-sql.ts
+ * (single-file dual-dialect: `SqlBreakerState` + the `TiDBBreakerState`/`PgBreakerState` ctor subclasses).
+ * Kept so every consumer's `from "./pg-breaker-state.js"` import (incl. pg-pool.ts's central ensureSchema
+ * composition and the real dual-DB integration suite) keeps working unchanged.
+ */
+export { PgBreakerState, PG_BREAKER_STATE_SCHEMA, ensureSchema } from "./breaker-state-sql.js";
+//# sourceMappingURL=pg-breaker-state.js.map

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

@@ -0,0 +1,10 @@
+/**
+ * PostgreSQL `CheckpointStore` — the implementation now lives in the single-file dual-dialect
+ * `checkpoint-store-sql.ts` (design/158 A12 定型半场), alongside its TiDB twin so the dialect deltas
+ * (placeholders, ON CONFLICT, `IS NOT DISTINCT FROM` + its placeholder-arity consequence, the lossless
+ * JSON envelope) read side by side instead of drifting across two files.
+ *
+ * This file is the historical import path: class name and ctor shape unchanged.
+ */
+export { PgCheckpointStore } from "./checkpoint-store-sql.js";
+//# sourceMappingURL=pg-checkpoint-store.d.ts.map

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

@@ -0,0 +1,10 @@
+/**
+ * PostgreSQL `CheckpointStore` — the implementation now lives in the single-file dual-dialect
+ * `checkpoint-store-sql.ts` (design/158 A12 定型半场), alongside its TiDB twin so the dialect deltas
+ * (placeholders, ON CONFLICT, `IS NOT DISTINCT FROM` + its placeholder-arity consequence, the lossless
+ * JSON envelope) read side by side instead of drifting across two files.
+ *
+ * This file is the historical import path: class name and ctor shape unchanged.
+ */
+export { PgCheckpointStore } from "./checkpoint-store-sql.js";
+//# sourceMappingURL=pg-checkpoint-store.js.map

package/dist/plugins/pg-file-snapshot-store.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Thin re-export shim (design/158 A12 定型半场) — the real implementation collapsed into
+ * `file-snapshot-store-sql.ts` (single file, dual dialect). Kept so every existing import path
+ * (store-backend.ts, the migration script, the contract/integration/minio-equivalence suites) is
+ * untouched: same class name, same ctor arity, same exported surface.
+ */
+export { PgFileSnapshotStore } from "./file-snapshot-store-sql.js";
+//# sourceMappingURL=pg-file-snapshot-store.d.ts.map

package/dist/plugins/pg-file-snapshot-store.js

@@ -0,0 +1,8 @@
+/**
+ * Thin re-export shim (design/158 A12 定型半场) — the real implementation collapsed into
+ * `file-snapshot-store-sql.ts` (single file, dual dialect). Kept so every existing import path
+ * (store-backend.ts, the migration script, the contract/integration/minio-equivalence suites) is
+ * untouched: same class name, same ctor arity, same exported surface.
+ */
+export { PgFileSnapshotStore } from "./file-snapshot-store-sql.js";
+//# sourceMappingURL=pg-file-snapshot-store.js.map

package/dist/plugins/pg-image-bake.d.ts

@@ -0,0 +1,12 @@
+/**
+ * PostgreSQL BAKE store — the implementation now lives in the single-file dual-dialect
+ * `image-bake-store-sql.ts` (design/158 A12 定型半场), alongside its TiDB twin so the dialect deltas
+ * (placeholders, ON CONFLICT, jsonb casts, the admission-statement divergence, the PG-only
+ * protocol-byte defenses) read side by side instead of drifting across two files.
+ *
+ * This file is the historical import path: class name, ctor shape, `PG_IMAGE_BAKE_SCHEMA` and
+ * `ensureSchema` are unchanged, so pg-pool.ts / store-backend.ts / the integration suite are untouched.
+ */
+export { PgImageBake, PG_IMAGE_BAKE_SCHEMA, ensurePgImageBakeSchema as ensureSchema } from "./image-bake-store-sql.js";
+export type { BakeStatus, BakeState, BakeErrorCode, BakeRecord, BakeEvent, CreateBakeInput, BakeTerminal, } from "./store-contracts.js";
+//# sourceMappingURL=pg-image-bake.d.ts.map

package/dist/plugins/pg-image-bake.js

@@ -0,0 +1,11 @@
+/**
+ * PostgreSQL BAKE store — the implementation now lives in the single-file dual-dialect
+ * `image-bake-store-sql.ts` (design/158 A12 定型半场), alongside its TiDB twin so the dialect deltas
+ * (placeholders, ON CONFLICT, jsonb casts, the admission-statement divergence, the PG-only
+ * protocol-byte defenses) read side by side instead of drifting across two files.
+ *
+ * This file is the historical import path: class name, ctor shape, `PG_IMAGE_BAKE_SCHEMA` and
+ * `ensureSchema` are unchanged, so pg-pool.ts / store-backend.ts / the integration suite are untouched.
+ */
+export { PgImageBake, PG_IMAGE_BAKE_SCHEMA, ensurePgImageBakeSchema as ensureSchema } from "./image-bake-store-sql.js";
+//# sourceMappingURL=pg-image-bake.js.map

package/dist/plugins/pg-image-index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * PostgreSQL-backed sandbox-image-pool INDEX store — the PG twin of {@link TiDBImageIndex}
+ * (src/plugins/tidb-image-index.ts).
+ *
+ * Thin re-export shim (design/158 A12 定型半场): the real implementation is the single-file dual-dialect
+ * `image-index-sql.ts` (`SqlImageIndex` + this file's `PgImageIndex` ctor subclass). Class name, ctor
+ * arity, and the exported type/schema surface are UNCHANGED — every consumer (store-backend.ts, pg-pool.ts,
+ * the real-DB integration suite) imports from here exactly as before.
+ */
+export { PgImageIndex, PG_IMAGE_INDEX_SCHEMA, ensureSchema } from "./image-index-sql.js";
+export type { ImageNestedBuildMode, ImageCapabilities, ImagePodContract, ImageStatus, ImageVisibility, ImageIndexEntry, ImageIndexUpsert, ImageViewer, ImageListFilter, } from "./store-contracts.js";
+//# sourceMappingURL=pg-image-index.d.ts.map

package/dist/plugins/pg-image-index.js

@@ -0,0 +1,11 @@
+/**
+ * PostgreSQL-backed sandbox-image-pool INDEX store — the PG twin of {@link TiDBImageIndex}
+ * (src/plugins/tidb-image-index.ts).
+ *
+ * Thin re-export shim (design/158 A12 定型半场): the real implementation is the single-file dual-dialect
+ * `image-index-sql.ts` (`SqlImageIndex` + this file's `PgImageIndex` ctor subclass). Class name, ctor
+ * arity, and the exported type/schema surface are UNCHANGED — every consumer (store-backend.ts, pg-pool.ts,
+ * the real-DB integration suite) imports from here exactly as before.
+ */
+export { PgImageIndex, PG_IMAGE_INDEX_SCHEMA, ensureSchema } from "./image-index-sql.js";
+//# sourceMappingURL=pg-image-index.js.map

package/dist/plugins/pg-outcome-ledger.d.ts

@@ -0,0 +1,12 @@
+/**
+ * PostgreSQL outcome ledger — the implementation now lives in the single-file dual-dialect
+ * `outcome-ledger-sql.ts` (design/158 A12 定型半场), alongside its TiDB twin so the dialect deltas
+ * (placeholders, JSON encode, the AVG boolean-coercion divergence) read side by side instead of
+ * drifting across two files.
+ *
+ * This file is the historical import path: class name, `PG_OUTCOME_LEDGER_SCHEMA` and `ensureSchema`
+ * are unchanged, so pg-pool.ts / store-backend.ts / the integration suite are untouched.
+ */
+export { PgOutcomeLedger, PG_OUTCOME_LEDGER_SCHEMA, ensurePgOutcomeLedgerSchema as ensureSchema, } from "./outcome-ledger-sql.js";
+export type { TaskOutcome, RunStatus } from "./outcome-ledger-sql.js";
+//# sourceMappingURL=pg-outcome-ledger.d.ts.map

package/dist/plugins/pg-outcome-ledger.js

@@ -0,0 +1,11 @@
+/**
+ * PostgreSQL outcome ledger — the implementation now lives in the single-file dual-dialect
+ * `outcome-ledger-sql.ts` (design/158 A12 定型半场), alongside its TiDB twin so the dialect deltas
+ * (placeholders, JSON encode, the AVG boolean-coercion divergence) read side by side instead of
+ * drifting across two files.
+ *
+ * This file is the historical import path: class name, `PG_OUTCOME_LEDGER_SCHEMA` and `ensureSchema`
+ * are unchanged, so pg-pool.ts / store-backend.ts / the integration suite are untouched.
+ */
+export { PgOutcomeLedger, PG_OUTCOME_LEDGER_SCHEMA, ensurePgOutcomeLedgerSchema as ensureSchema, } from "./outcome-ledger-sql.js";
+//# sourceMappingURL=pg-outcome-ledger.js.map

package/dist/plugins/pg-pool.js

@@ -35,6 +35,7 @@ import { ensureSchema as ensureBreakerStateSchema } from "./breaker-state-sql.js
 import { ensurePgOutcomeLedgerSchema as ensureOutcomeLedgerSchema } from "./outcome-ledger-sql.js";
 import { ensureSchema as ensureImageIndexSchema } from "./image-index-sql.js";
 import { ensurePgImageBakeSchema as ensureImageBakeSchema } from "./image-bake-store-sql.js";
+import { ensurePgApprovalAskSchema } from "./approval-ask-store-sql.js";
 export const PG_SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS task_run (
      task_id     VARCHAR(64)  NOT NULL,
@@ -93,7 +94,13 @@ export const PG_SCHEMA_STATEMENTS = [
      terminal_at  BIGINT,
      gate_kind    VARCHAR(32),
      bound_input_hash VARCHAR(190),
+     -- pending_steer / pending_steer_queue / pending_steer_rev:队列化后的 durable steering(core 5.14.0
+     -- #147)。三列的语义、「为什么队列另起一列而不是覆盖旧列」(滚动升级窗里旧副本的无条件覆盖写)、
+     -- 48000 字节预算、以及「为什么另起一个整数 rev 列而不拿 JSON 旧值当 CAS 守卫」的完整由来见 MySQL
+     -- 孪生(tidb-pool.ts 同三列的行内注)。PG text 无长度上限,预算由 core 侧统一执法。
      pending_steer TEXT,
+     pending_steer_queue TEXT,
+     pending_steer_rev BIGINT NOT NULL DEFAULT 0,
      risk_descriptor TEXT,
      PRIMARY KEY (token)
    )`,
@@ -334,6 +341,10 @@ export async function ensurePgSchema(pool) {
         await ensureOutcomeLedgerSchema(client);
         await ensureImageIndexSchema(client);
         await ensureImageBakeSchema(client);
+        // #151 流内审批协议持久层(MySQL twin 走 tidb-pool 的 SCHEMA_STATEMENTS 展开)。该 ensure 收的是裸
+        // `PgQueryFn`(而非兄弟们收的 client 形),故在这里绑一层 —— DDL 仍然跑在**同一条** client 上,
+        // advisory lock 的 session 语义不受影响(见本函数头注:路由到别的池连接会静默作废那把锁)。
+        await ensurePgApprovalAskSchema((text, params) => client.query(text, params));
     }
     finally {
         if (locked) {