@sema-agent/server 7.2.0 → 7.4.0

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

@@ -0,0 +1,116 @@
+/**
+ * Durable approval store for the human-in-the-loop write gate (F4) — SINGLE-FILE DUAL-DIALECT
+ * (design/158 A12 定型半场). ONE implementation, TWO dialects; the historical `TiDBApprovalStore` /
+ * `PgApprovalStore` class names survive as thin ctor subclasses so every consumer (store-backend.ts,
+ * src/index.ts, the approval/audit/security-coverage suites) is untouched.
+ *
+ * When a gated tool call is about to run, a `pending` row is recorded here; the instance running the
+ * task polls it for a decision. Because the row is durable and shared, an operator's approve/deny can
+ * land on ANY instance — critical under async runs + a load balancer, where the deciding request and
+ * the waiting run are usually on different instances.
+ *
+ * Unlike the run/checkpoint PG store (whose schema is owned centrally by pg-pool.ts), this file also
+ * exports a self-contained PG schema (`PG_APPROVAL_SCHEMA` + `ensureSchema`) — the `approval` table is
+ * DISJOINT from the other PG stores' tables, so a CREATE IF NOT EXISTS here shadows nothing. Central
+ * aggregation into pg-pool.ts composes it alongside the others. Kept in lock-step with the TiDB store
+ * by the shared real-DB integration suite (test/pg-approval-store-integration.test.ts).
+ *
+ * ── Dialect deltas, kept EXPLICIT ────────────────────────────────────────────────────────────────────
+ *   - `?` placeholders vs `$n`
+ *   - null-safe scope compare: `<=>` vs `IS NOT DISTINCT FROM` (a NULL scope row — legacy/untenanted
+ *     run — is matched by a NULL scope arg; one tenant's scope NEVER matches another's — the
+ *     single-DB fleet read guard, defense-in-depth)
+ *   - JSON binding: TiDB `JSON.stringify` verbatim vs PG `pgProtocolJsonStringify` (codex R4-H2: the
+ *     persisted approval `args` is the operator's REVIEW surface and must agree byte-for-byte with the
+ *     policy-executed args — a lossy/rewriting envelope would let an operator approve one payload while
+ *     a different one runs)
+ *   - affectedRows vs rowCount (via SqlDriver)
+ *   - schema ownership: TiDB DDL lives in tidb-pool.ts SCHEMA_STATEMENTS; PG DDL is this file's own
+ *     self-contained `PG_APPROVAL_SCHEMA` (see the PG twin's original header — unlike the other PG
+ *     stores, `approval` is NOT centrally owned by pg-pool.ts's DDL array, only aggregated into its
+ *     `ensureSchema` composition).
+ *   - `getStatus` result shape: `RowDataPacket[]` (mysql2 typed query) vs a plain-record `pg` query —
+ *     normalized to `SqlRow` by the shared driver, so both arms read the same field names.
+ */
+import type { Pool as MySqlPool } from "mysql2/promise";
+import type { Pool as PgPool, PoolClient } from "pg";
+import { type SqlDriver } from "./sql-driver.js";
+export type ApprovalStatus = "pending" | "approved" | "denied" | "expired";
+export interface ApprovalRow {
+    id: string;
+    taskId: string | null;
+    sessionId: string | null;
+    owner: string | null;
+    /** Single-DB fleet scope guard (defense-in-depth): the run's tenant identity, owner-sourced. Reads filter on it. */
+    scope: string | null;
+    toolName: string;
+    args: unknown;
+    status: ApprovalStatus;
+    reason: string | null;
+    decidedBy: string | null;
+    createdAt: string;
+    decidedAt: string | null;
+}
+/** PG translation of the `approval` DDL in tidb-pool.ts SCHEMA_STATEMENTS (JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3),
+ *  inline KEY→separate CREATE INDEX).
+ *
+ *  SCHEMA POLICY: see the header of pg-pool.ts — the code is the single source of truth, schema changes are
+ *  drop-and-recreate, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead. */
+export declare const PG_APPROVAL_SCHEMA: string[];
+/** Idempotent self-contained schema apply (for the integration test; central aggregation is done separately). */
+export declare function ensureSchema(pool: PgPool | PoolClient): Promise<void>;
+/** Dual-dialect durable approval store. See the file header for the dialect-delta ledger. */
+export declare class SqlApprovalStore {
+    protected readonly db: SqlDriver;
+    constructor(db: SqlDriver);
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
+    private q;
+    /** JSON column binding: TiDB stores the string verbatim; PG goes through the LOSSLESS protocol envelope
+     *  (codex R4-H2 — the approval `args` is the operator's review surface and must agree with the
+     *  policy-executed args at the NUL position). */
+    private json;
+    createPending(id: string, scope: string | null, ctx: {
+        taskId?: string | null;
+        sessionId?: string | null;
+        owner?: string | null;
+        toolName: string;
+        args: unknown;
+    }): Promise<void>;
+    getStatus(id: string, scope: string | null): Promise<{
+        status: ApprovalStatus;
+        reason: string | null;
+        decidedBy: string | null;
+    } | undefined>;
+    /** Apply a terminal decision, but only to a still-pending row (CAS). Returns whether it applied. The scope
+     *  guard (null-safe) is carried on the operator path too for consistency with the read paths. */
+    decide(id: string, scope: string | null, decision: "approved" | "denied" | "expired", reason: string | null, decidedBy: string | null): Promise<boolean>;
+    /** Pending approvals (operator queue), scoped to one tenant (single-DB fleet read guard, null-safe), optionally
+     *  further filtered to one owner. */
+    listPending(scope: string | null, owner?: string): Promise<ApprovalRow[]>;
+    get(id: string, scope: string | null): Promise<ApprovalRow | undefined>;
+    /** Operator-only CROSS-tenant by-id read (no scope filter). The F4 operator queue serves/decides across
+     *  tenants by design; the HTTP layer gates this to an operator and then re-binds decide() to the row's OWN
+     *  scope. Tenants NEVER reach this — they use the scope-bound {@link get}. */
+    getById(id: string): Promise<ApprovalRow | undefined>;
+    /** Operator-only CROSS-tenant pending list (no scope filter) — the unfiltered operator queue across all
+     *  tenants. Tenants use the scope-bound {@link listPending}; this is HTTP-gated to an operator.
+     *  🔴 identical SQL text on both dialects (no placeholders, nothing dialect-specific) — kept as ONE literal
+     *  rather than a `q()` pair so a reader isn't misled into looking for a divergence that isn't there. */
+    listPendingAll(): Promise<ApprovalRow[]>;
+    /** Expire pending approvals older than `olderThanMs` (a never-answered operator request). Deliberately GLOBAL
+     *  (NOT scope-filtered): staleness expiry is fleet-level maintenance that protects the worker regardless of
+     *  tenant — a stale row in any scope must be reaped. Scope isolation applies to the per-tenant READ paths, not
+     *  to this maintenance sweep. */
+    expireStale(olderThanMs: number): Promise<number>;
+}
+/** approval row → {@link ApprovalRow} — shared by BOTH dialects. design/158 S8 归位 / A12 收编. */
+export declare function mapRow(r: Record<string, unknown>): ApprovalRow;
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
+export declare class TiDBApprovalStore extends SqlApprovalStore {
+    constructor(pool: MySqlPool);
+}
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
+export declare class PgApprovalStore extends SqlApprovalStore {
+    constructor(pool: PgPool);
+}
+//# sourceMappingURL=approval-store-sql.d.ts.map

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

@@ -0,0 +1,151 @@
+import { parseJsonStrict as parseJson, toIsoOrNull as iso } from "./sql-row-helpers.js";
+import { pgProtocolJsonStringify } from "./pg-safe-json.js";
+import { mysqlDriver, pgDriver } from "./sql-driver.js";
+/** PG translation of the `approval` DDL in tidb-pool.ts SCHEMA_STATEMENTS (JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3),
+ *  inline KEY→separate CREATE INDEX).
+ *
+ *  SCHEMA POLICY: see the header of pg-pool.ts — the code is the single source of truth, schema changes are
+ *  drop-and-recreate, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead. */
+export const PG_APPROVAL_SCHEMA = [
+    `CREATE TABLE IF NOT EXISTS approval (
+     id          VARCHAR(64)  NOT NULL,
+     task_id     VARCHAR(64),
+     session_id  VARCHAR(64),
+     owner       VARCHAR(190),
+     -- Single-DB fleet scope guard (tenant isolation). NULLABLE on purpose: a NULL-scope row is an untenanted
+     -- run, and every read/decide path matches it with \`scope IS NOT DISTINCT FROM $n\` (the PG twin of TiDB
+     -- \`<=>\`) so NULL matches only NULL and one tenant's scope NEVER matches another's.
+     scope       VARCHAR(190),
+     tool_name   VARCHAR(190) NOT NULL,
+     args        JSONB,
+     status      VARCHAR(16)  NOT NULL,
+     reason      TEXT,
+     decided_by  VARCHAR(190),
+     created_at  TIMESTAMPTZ(3) NOT NULL,
+     decided_at  TIMESTAMPTZ(3),
+     PRIMARY KEY (id)
+   )`,
+    `CREATE INDEX IF NOT EXISTS idx_approval_owner_status ON approval (owner, status)`,
+    `CREATE INDEX IF NOT EXISTS idx_approval_status ON approval (status)`,
+    `CREATE INDEX IF NOT EXISTS idx_approval_scope_status ON approval (scope, status)`,
+];
+/** Idempotent self-contained schema apply (for the integration test; central aggregation is done separately). */
+export async function ensureSchema(pool) {
+    for (const stmt of PG_APPROVAL_SCHEMA)
+        await pool.query(stmt);
+}
+/** Dual-dialect durable approval store. See the file header for the dialect-delta ledger. */
+export class SqlApprovalStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
+    q(tidb, pg) {
+        return this.db.dialect === "tidb" ? tidb : pg;
+    }
+    /** JSON column binding: TiDB stores the string verbatim; PG goes through the LOSSLESS protocol envelope
+     *  (codex R4-H2 — the approval `args` is the operator's review surface and must agree with the
+     *  policy-executed args at the NUL position). */
+    json(value, label) {
+        return this.db.dialect === "tidb" ? JSON.stringify(value) : pgProtocolJsonStringify(value, label);
+    }
+    async createPending(id, scope, ctx) {
+        await this.db.query(this.q("INSERT INTO approval (id, task_id, session_id, owner, scope, tool_name, args, status, created_at) " +
+            "VALUES (?,?,?,?,?,?,?,'pending',?)", "INSERT INTO approval (id, task_id, session_id, owner, scope, tool_name, args, status, created_at) " +
+            "VALUES ($1,$2,$3,$4,$5,$6,$7::jsonb,'pending',$8)"), [
+            id,
+            ctx.taskId ?? null,
+            ctx.sessionId ?? null,
+            ctx.owner ?? null,
+            scope,
+            ctx.toolName,
+            ctx.args == null ? null : this.json(ctx.args, "approval args"),
+            new Date(),
+        ]);
+    }
+    async getStatus(id, scope) {
+        // null-safe scope match (`<=>` / `IS NOT DISTINCT FROM`): a NULL scope row (legacy / untenanted run) is
+        // matched by a NULL scope arg, and a tenant's scope NEVER matches another tenant's — the single-DB fleet
+        // read guard (defense-in-depth).
+        const { rows } = await this.db.query(this.q("SELECT status, reason, decided_by FROM approval WHERE id = ? AND scope <=> ?", "SELECT status, reason, decided_by FROM approval WHERE id = $1 AND scope IS NOT DISTINCT FROM $2"), [id, scope]);
+        const r = rows[0];
+        if (!r)
+            return undefined;
+        return { status: r.status, reason: r.reason ?? null, decidedBy: r.decided_by ?? null };
+    }
+    /** Apply a terminal decision, but only to a still-pending row (CAS). Returns whether it applied. The scope
+     *  guard (null-safe) is carried on the operator path too for consistency with the read paths. */
+    async decide(id, scope, decision, reason, decidedBy) {
+        const res = await this.db.query(this.q("UPDATE approval SET status = ?, reason = ?, decided_by = ?, decided_at = ? WHERE id = ? AND scope <=> ? AND status = 'pending'", "UPDATE approval SET status = $1, reason = $2, decided_by = $3, decided_at = $4 WHERE id = $5 AND scope IS NOT DISTINCT FROM $6 AND status = 'pending'"), [decision, reason, decidedBy, new Date(), id, scope]);
+        return res.affected === 1;
+    }
+    /** Pending approvals (operator queue), scoped to one tenant (single-DB fleet read guard, null-safe), optionally
+     *  further filtered to one owner. */
+    async listPending(scope, owner) {
+        const { rows } = owner
+            ? await this.db.query(this.q("SELECT * FROM approval WHERE status = 'pending' AND scope <=> ? AND owner = ? ORDER BY created_at ASC", "SELECT * FROM approval WHERE status = 'pending' AND scope IS NOT DISTINCT FROM $1 AND owner = $2 ORDER BY created_at ASC"), [scope, owner])
+            : await this.db.query(this.q("SELECT * FROM approval WHERE status = 'pending' AND scope <=> ? ORDER BY created_at ASC", "SELECT * FROM approval WHERE status = 'pending' AND scope IS NOT DISTINCT FROM $1 ORDER BY created_at ASC"), [scope]);
+        return rows.map(mapRow);
+    }
+    async get(id, scope) {
+        const { rows } = await this.db.query(this.q("SELECT * FROM approval WHERE id = ? AND scope <=> ?", "SELECT * FROM approval WHERE id = $1 AND scope IS NOT DISTINCT FROM $2"), [id, scope]);
+        return rows[0] ? mapRow(rows[0]) : undefined;
+    }
+    /** Operator-only CROSS-tenant by-id read (no scope filter). The F4 operator queue serves/decides across
+     *  tenants by design; the HTTP layer gates this to an operator and then re-binds decide() to the row's OWN
+     *  scope. Tenants NEVER reach this — they use the scope-bound {@link get}. */
+    async getById(id) {
+        const { rows } = await this.db.query(this.q("SELECT * FROM approval WHERE id = ?", "SELECT * FROM approval WHERE id = $1"), [id]);
+        return rows[0] ? mapRow(rows[0]) : undefined;
+    }
+    /** Operator-only CROSS-tenant pending list (no scope filter) — the unfiltered operator queue across all
+     *  tenants. Tenants use the scope-bound {@link listPending}; this is HTTP-gated to an operator.
+     *  🔴 identical SQL text on both dialects (no placeholders, nothing dialect-specific) — kept as ONE literal
+     *  rather than a `q()` pair so a reader isn't misled into looking for a divergence that isn't there. */
+    async listPendingAll() {
+        const { rows } = await this.db.query("SELECT * FROM approval WHERE status = 'pending' ORDER BY created_at ASC");
+        return rows.map(mapRow);
+    }
+    /** Expire pending approvals older than `olderThanMs` (a never-answered operator request). Deliberately GLOBAL
+     *  (NOT scope-filtered): staleness expiry is fleet-level maintenance that protects the worker regardless of
+     *  tenant — a stale row in any scope must be reaped. Scope isolation applies to the per-tenant READ paths, not
+     *  to this maintenance sweep. */
+    async expireStale(olderThanMs) {
+        const cutoff = new Date(Date.now() - olderThanMs);
+        const res = await this.db.query(this.q("UPDATE approval SET status = 'expired', reason = 'timed out before decision', decided_at = ? " +
+            "WHERE status = 'pending' AND created_at < ?", "UPDATE approval SET status = 'expired', reason = 'timed out before decision', decided_at = $1 " +
+            "WHERE status = 'pending' AND created_at < $2"), [new Date(), cutoff]);
+        return res.affected;
+    }
+}
+/** approval row → {@link ApprovalRow} — shared by BOTH dialects. design/158 S8 归位 / A12 收编. */
+export function mapRow(r) {
+    return {
+        id: String(r.id),
+        taskId: r.task_id ?? null,
+        sessionId: r.session_id ?? null,
+        owner: r.owner ?? null,
+        scope: r.scope ?? null,
+        toolName: String(r.tool_name),
+        args: parseJson(r.args),
+        status: r.status,
+        reason: r.reason ?? null,
+        decidedBy: r.decided_by ?? null,
+        createdAt: iso(r.created_at),
+        decidedAt: iso(r.decided_at),
+    };
+}
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
+export class TiDBApprovalStore extends SqlApprovalStore {
+    constructor(pool) {
+        super(mysqlDriver(pool));
+    }
+}
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
+export class PgApprovalStore extends SqlApprovalStore {
+    constructor(pool) {
+        super(pgDriver(pool));
+    }
+}
+//# sourceMappingURL=approval-store-sql.js.map

package/dist/plugins/background-agent-store-sql.js

@@ -9,7 +9,7 @@ const SUMMARY_COLS = "handle, owner, session_scoped, session_id, parent_session_
  *  类型签名逐字核对过),只是 record_json 全量对象序列化里随手带上的普通字段,不需要专用列——
  *  record_json 的写法是 `json(stored)`(stored = `{...record, handle, scope, rev}` 整个对象展开),
  *  任何 record 上有的字段(含 writerEpoch)天然随之落盘/读回,无需逐字段维护投影列表。 */
-const PROJ_COLS = "scope, owner, session_scoped, session_id, parent_session_id, root_session_id, session_anchor, name, agent_type, status, spawned_at_ms, updated_at_ms, settled_at_ms, usage_json, rev, parked_checkpoint_token, park_claim_id, record_json";
+const PROJ_COLS = "scope, owner, session_scoped, session_id, parent_session_id, root_session_id, session_anchor, name, agent_type, status, spawned_at_ms, updated_at_ms, settled_at_ms, usage_json, rev, parked_checkpoint_token, park_claim_id, admitted_org_scopes, admitted_org_write_scope, record_json";
 const PROJ_N = PROJ_COLS.split(", ").length; // F5: WHERE 占位符序号从列数派生,列序变更单点同步
 function assertScope(record) {
     if (record.scope === undefined || record.scope === "") {
@@ -43,6 +43,16 @@ function projParams(stored, json, text) {
         stored.rev,
         stored.parkedCheckpointToken ?? null,
         stored.parkClaimId ?? null,
+        // core 5.14.0 #22([2854] 提货单⑤):每条腿在 injector-ready 栅上写下自己被裁定的 org 准入结果。
+        // 🔴 三态必须区分,这是 core 契约试剂盒硬钉的那条:**缺席(undefined)≠ 空数组**。
+        //   · 字段缺席 ⇒ 列 NULL(「没有记录」)。老行免回填,读空即零准入 fail-closed。
+        //   · `[]` / `null` ⇒ 列上是 JSON "[]" / 真 NULL 写域 —— 「裁定过,结果是什么都没有」。
+        // 两列是**写侧投影**(真源恒是 record_json,`get()` 只读它)——语义上不可能漂移:缺席的键根本
+        // 不进 JSON.stringify,所以「缺席读回缺席」由真源结构保证,不靠这两列。
+        // 📌 记账(诚实清单):本仓今天**没有**读这两列的消费者;它们存在是为了让 org 治理审计能按列
+        //    查询(「哪些后台子代拿到过 org:acme 的写权」),不必全表扫 JSON。谁要接,先上黑板对表。
+        stored.admittedOrgScopes !== undefined ? json(stored.admittedOrgScopes) : null,
+        stored.admittedOrgWriteScope !== undefined ? stored.admittedOrgWriteScope : null,
         json(stored),
     ];
 }
@@ -171,6 +181,12 @@ export async function ensureTiDBBackgroundAgentSchema(pool) {
     -- 行状态原子求值,不能只靠 record_json blob(那要求先读后写,读写之间就是 CAS 本要堵的竞态窗)。
     parked_checkpoint_token VARCHAR(190) NULL,
     park_claim_id VARCHAR(190) NULL,
+    -- core 5.14.0 #22:该腿被裁定的 org 准入结果(写侧投影,真源恒是 record_json)。
+    -- NULL = 字段缺席(「没有记录」,老行天然如此,免回填);JSON "[]" = 裁定过、结果为空。
+    -- admitted_org_write_scope 的 NULL 兼表「缺席」与「裁定为无写域」——两者在 core 侧都落 fail-closed
+    -- 的零写权,列上不必再分,真源(record_json)里仍然分得清 undefined 与 null。
+    admitted_org_scopes TEXT NULL,
+    admitted_org_write_scope VARCHAR(190) NULL,
     record_json LONGTEXT NOT NULL,
     PRIMARY KEY (scope_key, handle),
     KEY idx_bga_anchor (scope_key, session_anchor, spawned_at_ms),
@@ -201,6 +217,9 @@ export async function ensurePgBackgroundAgentSchema(q) {
     -- core 1.383([1565] / design/153 件3a)ε(TiDB 同案注):updateIf 的 CAS 守卫专用列
     parked_checkpoint_token VARCHAR(190),
     park_claim_id VARCHAR(190),
+    -- core 5.14.0 #22(TiDB 同案注:三态与「写侧投影」口径见 MySQL 孪生的行内注)。
+    admitted_org_scopes TEXT,
+    admitted_org_write_scope VARCHAR(190),
     record_json TEXT NOT NULL,
     PRIMARY KEY (scope_key, handle)
   )`);

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

@@ -1,6 +1,6 @@
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import { type Checkpoint, type CheckpointGate, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type ResumeOutcome, type ResolveExpectation, type ReopenReason, type RiskDescriptor } from "@sema-agent/core";
+import { type Checkpoint, type CheckpointGate, type CheckpointState, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ResumeOutcome, type ResolveExpectation, type ReopenReason, type RiskDescriptor } from "@sema-agent/core";
 import { type SqlDriver } from "./sql-driver.js";
 /**
  * design/80 D-1 (§3 invariant #3 — crash-safe reaper backstop): an ABSOLUTE upper bound on a pending
@@ -67,6 +67,42 @@ export interface PendingCheckpoint {
  *  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. */
 export declare function boundedToolInput(args: unknown): unknown;
+/**
+ * 🔴 #151 车5 §9 C4:`findCheckpointCandidatesForAsk` 的 typed 候选行。刻意只有对账收敛器判据 1 真需要的
+ * 五件——**没有 token 之外的任何凭据面**,`token` 本身是 resume 凭据、只在服务端内部流转(同
+ * `findPendingTokenBySession`:它从不出网,§12-C「checkpointToken 从不外发」)。
+ */
+export interface CheckpointAskCandidate {
+    token: string;
+    /** `checkpoint.status` 列(权威;`pending` | `resolved` | `expired`)。不做过滤,由收敛器判活性。 */
+    status: string;
+    createdAtMs: number;
+    /** 该 park 绑定的 tool call(= `pendingAction.toolCallId`)。`unparseable` 行为 null。 */
+    boundCallId: string | null;
+    /** 服务端铸的入参摘要——判据 1 的第二道硬等式(与 `approval_asks.bound_input_hash` 相等才算命中)。 */
+    boundInputHash: string | null;
+    /** 在场 ⇒ 这行读不出(blob 版本超前 / JSON 坏)。收敛器视同不匹配;**从不是** false,缺席即可读。 */
+    unparseable?: true;
+}
+/** `pending_steer` 列承载的两个 CheckpointState 字段(= core `appendPendingSteer` / `readPendingSteerQueue`
+ *  的入参形)。列是**唯一**权威(suspend 时写的 blob 从不带它们)。 */
+type SteerColumnState = Pick<CheckpointState, "pendingSteer" | "pendingSteerQueue">;
+/** 读列结果。`lossy` = 列里有东西但**没能完整读出来**(JSON 坏 / 条目形不认)。两个调用点对它的处置
+ *  刻意相反,见各自的旁注:`get()` 容忍(坏列不许把一条挂起的 run 变成不可 resume),`setPendingSteer`
+ *  fail-loud(往一份读不全的队列上追加 = 把别人 park 的指令悄悄写没,正是 #147 要消灭的那件事)。 */
+interface SteerColumnRead {
+    state: SteerColumnState;
+    lossy: boolean;
+}
+/**
+ * 两个 steering 列 → `{pendingSteer?, pendingSteerQueue?}`(= core `appendPendingSteer`/`readPendingSteerQueue`
+ * 的入参形)。**两列各管一形**,不是一列两形:
+ *  · `pending_steer`(旧列,本服务只读不写)—— 裸单座 `{text, trusted}`。来源有二:队列化之前的存量行,
+ *    以及**滚动升级窗里仍在跑的旧副本**写下的座。core 的 `readPendingSteerQueue` 把它折成 member 0。
+ *  · `pending_steer_queue`(新列)—— `PendingSteerEntry[]`。
+ * 任一列有内容却读不出 ⇒ `lossy`(两个调用点对它的处置见 {@link SteerColumnRead})。
+ */
+export declare function readPendingSteerColumns(seatRaw: unknown, queueRaw: unknown): SteerColumnRead;
 /** Dual-dialect durable CheckpointStore. See the file header for the dialect-delta ledger. */
 export declare class SqlCheckpointStore implements CheckpointStore {
     protected readonly db: SqlDriver;
@@ -123,15 +159,30 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      */
     reopen(token: CheckpointToken, scope: string, reason: ReopenReason): Promise<boolean>;
     /**
-     * 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 行。
      */
-    setPendingSteer(token: CheckpointToken, scope: string, steer: {
-        text: string;
-        trusted: boolean;
-    }): Promise<boolean>;
+    setPendingSteer(token: CheckpointToken, scope: string, steer: PendingSteerInput): Promise<boolean>;
     /**
      * CAS-expire a SINGLE checkpoint by token (core 1.71 `CheckpointStore.expire`, for `TaskStream.destroy`'s
      * suspended-worker reap — core [R33] {delta}). `pending → expired`, returns the CAS winner (true = we
@@ -199,6 +250,29 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      * can only resolve within its own tenant. Returns null if there is no pending checkpoint for that session/scope.
      */
     findPendingTokenBySession(sessionId: string, scope?: string): Promise<CheckpointToken | 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`。
+     */
+    findCheckpointCandidatesForAsk(scope: string, sessionId: string, toolCallId: string, sinceMs: number): Promise<CheckpointAskCandidate[]>;
     /**
      * 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
@@ -251,4 +325,5 @@ export declare class PgCheckpointStore extends SqlCheckpointStore {
         info?(msg: string, meta?: unknown): void;
     });
 }
+export {};
 //# sourceMappingURL=checkpoint-store-sql.d.ts.map