@sema-agent/server 7.47.0 → 7.49.0

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 CheckpointState, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ResumeOutcome, type ResolveExpectation, type ReopenReason, type RiskDescriptor, type StoreDurability, type StoreFidelity } from "@sema-agent/core";
+import { type Checkpoint, type CheckpointGate, type CheckpointState, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ResumeOutcome, type ResolvedOutcome, type ResolveExpectation, type ReopenReason, type RiskDescriptor, type StoreDurability, type StoreFidelity } from "@sema-agent/core";
 import { type RuleOfferProjection } from "../approval-card.js";
 import { type SqlDriver } from "./sql-driver.js";
 /**
@@ -175,6 +175,80 @@ export interface CheckpointAskCandidate {
     /** 在场 ⇒ 这行读不出(blob 版本超前 / JSON 坏)。收敛器视同不匹配;**从不是** false,缺席即可读。 */
     unparseable?: true;
 }
+/**
+ * #368 件1 —— legacy `/v1/approvals/:sessionId/decide` 腿的**幂等回放**判别行(窄读,非凭据面)。
+ *
+ * 刻意**不带 token**:回放只需要「这条已决的行归谁、绑的是哪一次调用、判词是什么」三件,而 token 是
+ * resume 凭据(§12-C「checkpointToken 从不外发」;`CheckpointAskCandidate` 带它是因为收敛器要拿它去
+ * `bindBatch`,本口没有那个用途 ⇒ 不给)。
+ */
+export interface DecidedApprovalRecord {
+    /** 行的属主 scope 列(`encodeCheckpointScope` 的产物:principal 或匿名哨兵 `"_"`)。回放属主门的输入。 */
+    scope: string;
+    /** 行上的 D-1 入参摘要(`bound_input_hash` 列);pre-D-1 行为 null。 */
+    boundInputHash: string | null;
+    /**
+     * 这条已决行的**工具审批判词**,或 `null` = **判别不出**(codex R1-[medium] 四的收敛形):
+     * outcome 读不出 / 没有 winner / winner 绑的是**另一个** callId / 判词是 REVIEW 门那三个词。
+     *
+     * 🔴 `null` **不是**「无所谓」:调用方必须把它当「这条命中的行我读不懂」⇒ **整次回放拒绝**。
+     * 一条读不懂的已决行与一条判词相反的已决行在风险上同级 —— 都意味着这只 callId 上的持久事实
+     * 不是本次回放能如实复述的。
+     */
+    decision: "approve" | "deny" | null;
+    /**
+     * 判词**之外**的决议载荷指纹(codex R2-[high] 一,验真后补):`updatedInput` / `answer` / `reason`
+     * 三件都在 core 的持久 winner 里,而**同判词不等于同决议** —— 「approve + 编辑后的实参 A」与
+     * 「approve + 实参 B」是两次不同的放行,只比判词就会把后者谎报成「你的请求已被处理」(而 B 从未执行)。
+     * 调用方按**同一份请求重发**的语义要求它与本次请求的同三件逐字相等。
+     * `null` = 算不出(载荷序列化不了)⇒ 与 `decision: null` 同判:整次拒绝。
+     * 铸法见 {@link approvalPayloadFingerprint}(两条车道共用同一只,免得指纹口径漂)。
+     */
+    payloadFp: string | null;
+}
+/**
+ * #368 件1(codex R2-[high] 一)—— 决议载荷的比对指纹:`[updatedInput, answer, reason]` 三件的规范串。
+ *
+ * 为什么是指纹而不是把三件原样交出来:`updatedInput` 可能携人写的命令原文/密钥形字节,而本读口的
+ * 契约是「窄读、非凭据面」—— 交指纹够比对,也不给任何调用点把它误投上 wire 的机会。
+ *
+ * 🔴 **必须是 canonical(键序无关)**,不是裸 `JSON.stringify`(codex R3-[high] 二,验真后修):行侧那份
+ * 载荷是从 `JSON`/`JSONB` 列**回读**的,而 **PG 的 jsonb 不保留输入键序**(它按自己的规则重排)⇒ 客户端
+ * 逐字重发原 body 时,请求侧按原键序、行侧按库的键序,裸 stringify 出来的两串不等 ⇒ 一次**合法重试**
+ * 被误拒成 404。方向虽保守(不是谎报成功),但那正是本件要修的那个场景,所以指纹按**递归键排序 +
+ * 数组保序**铸(见 {@link canonicalFingerprintJson})。
+ *
+ * 缺席一律折 `null` 哨兵(不是省位):`{updatedInput: undefined}` 与「没有这个键」在本比对里是同一件事。
+ * ⚠️ 调用方**必须**按 outcome 铸点的在场规则喂参(`updatedInput` 只在 approve 上、`reason` 走真值判)——
+ * 铸点丢掉的字节行上就没有,请求侧多喂一件会把一次合法重试误判成「不同的决议」。
+ * 序列化失败(循环引用/BigInt 等)⇒ `null` = 判别不出,调用方据此拒绝回放(fail-closed)。
+ */
+export declare function approvalPayloadFingerprint(v: {
+    updatedInput?: unknown;
+    answer?: unknown;
+    reason?: string;
+}): string | null;
+/**
+ * #368 件1 —— {@link SqlCheckpointStore.findDecidedApprovalsForBinding} 的扫描上界。
+ *
+ * 🔴 它**同时是判据**,不只是一道 LIMIT:调用方按「命中集里每条判词都一致才回放」判,而一次被截断的
+ * 集合可能把分歧藏在第 N+1 行 ⇒ 消费点约定「**回满 = 判别不出**」,整次拒绝回放(回落 404)。现网正常形
+ * 恒 0 或 1 行,回满只可能是数据异常。
+ */
+export declare const DECIDED_REPLAY_SCAN_CAP = 8;
+/**
+ * #368 件1 —— core 的 `ResolvedOutcome` → 本腿(工具审批 decide)的二值词表。**闭集穷举**(#157):
+ * core 哪天给 `ResolvedOutcome.decision` 加员,下面的 `never` 当场编译期红,而不是让一个新判词被
+ * 静默折成 `deny` 或漏成「没有决议」。
+ *
+ * 三条判据,缺一即 `null`(= 不回放,调用方逐字回落修前 404 —— **绝不**把 not-found 洗成成功):
+ *  ① 有 winner —— `resource_limit` / `wake` / `task_done` 的 resolve 不记 winner(core 契约),那些行
+ *     不是「一次人给的工具审批」,没有可回放的判词;
+ *  ② winner 绑的正是这次请求回显的那个 `boundCallId` —— 身份第二锚(列谓词是第一锚),两锚同意才算同一件事;
+ *  ③ 判词属于**工具审批**那两个词(`allow`/`deny`)—— `approve`/`reject`/`edit` 是 REVIEW 门
+ *     (plan_review / dry_run_review)的判词,那些门的决议入口不是本腿,回放它们等于跨门作答。
+ */
+export declare function approvalDecisionOfWinner(winner: ResolvedOutcome | undefined, boundCallId: string): "approve" | "deny" | null;
 /** `pending_steer` 列承载的两个 CheckpointState 字段(= core `appendPendingSteer` / `readPendingSteerQueue`
  *  的入参形)。列是**唯一**权威(suspend 时写的 blob 从不带它们)。 */
 type SteerColumnState = Pick<CheckpointState, "pendingSteer" | "pendingSteerQueue">;
@@ -431,6 +505,39 @@ export declare class SqlCheckpointStore implements CheckpointStore {
      * 维,列命中行结构上也必须解 blob 才拿得到它。
      */
     findCheckpointCandidatesForAsk(scope: string, sessionId: string, toolCallId: string, sinceMs: number): Promise<CheckpointAskCandidate[]>;
+    /**
+     * #368 件1 —— 「这条会话上的这一次工具调用,**是不是已经被决过了**?」的窄读口(legacy `/decide`
+     * 腿的幂等回放判别器;返回形见 {@link DecidedApprovalRecord})。
+     *
+     * 为什么必须有这一口(而不是复用 `findPendingTokenBySession`):后者硬 `status='pending'`,首决之后
+     * 恒 null ⇒ 重试与「压根没有这条审批」在 wire 上同形(404)。而合规客户端的重试体里**没有**
+     * checkpointToken(它只回显二元组),所以既有的 `approval_stale` 409 那条判别路对它结构性不可达。
+     *
+     * 四条口径,逐条都是判据:
+     *  · **谓词 = (session_id, tool_call_id, status='resolved')**:`tool_call_id` 列是 `put()` 从
+     *    `pendingAction.toolCallId` 盖下来的权威投影,也正是 listPending 交给客户端回显的 `boundCallId`
+     *    ⇒ 客户端手里那把与库里这一列同源。`(session_id, status)` 是既有索引 `idx_checkpoint_session_status`
+     *    的前缀,不新增索引面。
+     *  · **只认 `resolved`**:`expired`(窗到期被 reaper 抹掉)**不是**一次决议 —— 把它回放成
+     *    「已决」等于把「没人来得及答」谎报成「有人答过」。那一形照旧落 404(诚实缺席)。
+     *  · **`decided_at_ms IS NOT NULL`**:与 respond 腿 `decidedRowIsAuthoritative` 的合取项③同判据
+     *    (「这条决议真的被结算腿落过」的印记);顺带消掉 MySQL/PG 对 `ORDER BY … DESC` 里 NULL 排序
+     *    方向不同这个方言差(MySQL NULL 最后、PG NULL 最前)—— 谓词先滤掉,排序就不含 NULL。
+     *  · **不带 scope 谓词、由调用方判属主**:与本类 `findPendingTokenBySession` 同姿势(读口不做租户
+     *    判决,判决在调用点)。回放腿据返回的 `scope` 做与 pending 那道**逐字同判**的属主门,非属主
+     *    拿到的仍是 404(不给存在性谕示)。
+     *
+     * 🔴 **返回的是全部命中行,不是「最近那一条」**(codex R1-[medium] 四,验真后改向):本口原先按
+     * `decided_at_ms DESC LIMIT 1` 取「最近一次决议」,而 local 孪生手里根本没有这个时间戳(core 的
+     * `Checkpoint` 上没有 decidedAt 字段),它只能按 `createdAt` 排 —— 两条车道于是可能对**同一批行**给出
+     * **不同**的判词(创建序与决议序相反时)。判据因此改成一条与排序**无关**的:调用方要求**全部命中行
+     * 判词一致**才回放,分歧即拒。同毫秒并列、两方言 NULL 排序差、跨车道排序键不同 —— 三个问题一起消失,
+     * 而现网正常形(恒 0 或 1 行)一个字节不变。上限 8 行足够:超过它的形已经不是「重试」而是数据异常。
+     *
+     * 坏 `outcome` cell **不抛**:回放是一条锦上添花的腿,让一条读不出的 JSON 把一次 decide 重试变成 500
+     * 比 404 更坏。留痕后交出 `decision: null`(= 判别不出),由调用方按「整次拒绝」处置。
+     */
+    findDecidedApprovalsForBinding(sessionId: string, boundCallId: string): Promise<DecidedApprovalRecord[]>;
     /**
      * 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/checkpoint-store-sql.js

@@ -4,10 +4,12 @@ import { CheckpointError, MAX_RULE_TEXT_CHARS, validatePendingSteer, appendPendi
 import { redactDeep, redactSecrets } from "../trace/redact.js";
 import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, RuleOfferRawSchema } from "../approval-card.js";
 import { parseJsonStrict as parseJson } from "./sql-row-helpers.js";
+import { createLogger } from "../observability/logger.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "./sql-driver.js";
 import { isDupKeyError } from "./sql-errors.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
+const fingerprintLogger = createLogger();
 const MAX_TOOL_INPUT_CHARS = 8192;
 export const TERMINAL_BACKSTOP_MS = Math.max(60_000, (Number.isFinite(Number(process.env.APPROVAL_TERMINAL_BACKSTOP_MS)) ? Number(process.env.APPROVAL_TERMINAL_BACKSTOP_MS) : 0) || 30 * 86_400_000);
 export const TERMINAL_GRACE_MS = 3_600_000;
@@ -79,6 +81,48 @@ export function boundedToolInput(args) {
         return { truncated: true, bytes: json.length };
     return redacted;
 }
+function canonicalFingerprintJson(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v) ?? "null";
+    if (Array.isArray(v))
+        return `[${v.map(canonicalFingerprintJson).join(",")}]`;
+    const entries = Object.entries(v)
+        .filter(([, val]) => val !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, val]) => `${JSON.stringify(k)}:${canonicalFingerprintJson(val)}`).join(",")}}`;
+}
+export function approvalPayloadFingerprint(v) {
+    try {
+        const fp = canonicalFingerprintJson([v.updatedInput ?? null, v.answer ?? null, v.reason ?? null]);
+        return fp;
+    }
+    catch (e) {
+        fingerprintLogger.warn("approval decision payload is not serializable — idempotent replay refused", { error: e instanceof Error ? e.message : String(e) });
+        return null;
+    }
+}
+export const DECIDED_REPLAY_SCAN_CAP = 8;
+export function approvalDecisionOfWinner(winner, boundCallId) {
+    if (winner === undefined)
+        return null;
+    if (winner.boundCallId !== boundCallId)
+        return null;
+    switch (winner.decision) {
+        case "allow":
+            return "approve";
+        case "deny":
+            return "deny";
+        case "approve":
+        case "reject":
+        case "edit":
+            return null;
+        default: {
+            const unhandled = winner.decision;
+            void unhandled;
+            return null;
+        }
+    }
+}
 function pendingActionToolCallId(blob) {
     let parsed;
     try {
@@ -429,6 +473,27 @@ export class SqlCheckpointStore {
         }
         return out;
     }
+    async findDecidedApprovalsForBinding(sessionId, boundCallId) {
+        const { rows } = await this.db.query(this.q("SELECT scope, bound_input_hash, outcome FROM checkpoint " +
+            `WHERE session_id=? AND tool_call_id=? AND status='resolved' AND decided_at_ms IS NOT NULL ORDER BY decided_at_ms DESC LIMIT ${DECIDED_REPLAY_SCAN_CAP}`, "SELECT scope, bound_input_hash, outcome FROM checkpoint " +
+            `WHERE session_id=$1 AND tool_call_id=$2 AND status='resolved' AND decided_at_ms IS NOT NULL ORDER BY decided_at_ms DESC LIMIT ${DECIDED_REPLAY_SCAN_CAP}`), [sessionId, boundCallId]);
+        return rows.map((r) => {
+            let winner;
+            try {
+                const outcome = parseJson(r.outcome);
+                winner = outcome ? winnerFromOutcome(outcome) : undefined;
+            }
+            catch (e) {
+                this.logger?.info?.("checkpoint_decided_outcome_unreadable", { sessionId, error: e instanceof Error ? e.message : String(e) });
+            }
+            return {
+                scope: String(r.scope),
+                boundInputHash: r.bound_input_hash == null ? null : String(r.bound_input_hash),
+                decision: approvalDecisionOfWinner(winner, boundCallId),
+                payloadFp: winner === undefined ? null : approvalPayloadFingerprint(winner),
+            };
+        });
+    }
     async peekPendingScope(sessionId) {
         const { rows } = await this.db.query(this.q("SELECT scope FROM checkpoint WHERE session_id=? AND status='pending' LIMIT 1", "SELECT scope FROM checkpoint WHERE session_id=$1 AND status='pending' LIMIT 1"), [sessionId]);
         if (!rows[0])

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

@@ -1,5 +1,5 @@
 import { type Checkpoint, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ReopenReason, type ResolveExpectation, type ResumeOutcome, type StoreDurability, type StoreFidelity } from "@sema-agent/core";
-import { type PendingCheckpoint } from "./checkpoint-store-sql.js";
+import { type DecidedApprovalRecord, type PendingCheckpoint } from "./checkpoint-store-sql.js";
 export interface LocalCheckpointStoreOptions {
     /** taskId join for the pending card (the local FileRunStore's `getActiveTaskId`). Absent ⇒ `taskId: null`. */
     getActiveTaskId?: (sessionId: string) => Promise<string | undefined>;
@@ -91,6 +91,19 @@ export declare class LocalCheckpointStore {
      *  索引里,其 expired 对本探针不可见(core File store 的 listByScope 是 pending-only,无法枚举历史行回填)。
      *  旧存量锁死的恢复把手 = cancel verb([868]①,不依赖本索引);增量行全覆盖。 */
     hasExpiredBySession(sessionId: string): Promise<boolean>;
+    /**
+     * #368 件1 —— SQL 孪生 `findDecidedApprovalsForBinding` 的本地形(判据、词表、失败方向逐条同源;
+     * 那处顶注是唯一真源,这里只记两处**本地形自己的**差别)。
+     *
+     *  · 枚举面走 [868] 的 `sessionTokens` 索引 —— 与 `hasExpiredBySession` 同一条路(core 的 File store
+     *    只能 pending-only 枚举,跨态读只有 `get(token)`),所以它那条**存量限制**在这里逐字同样成立:
+     *    索引建立之前 park 的老行对本口不可见 ⇒ 回放判别不出 ⇒ 调用方逐字回落 404(保守方向)。
+     *  · **没有排序**:本口交出全部命中行,由调用方按「判词一致才回放」判(理由见 SQL 孪生顶注的
+     *    codex R1-[medium] 四段——正是为了消掉「local 只有 createdAt、SQL 有 decided_at_ms」这条排序键
+     *    分岔)。同理回放的 wire 形**刻意不投** `decidedAtMs`:core 的 `Checkpoint` 上没有那个字段,
+     *    投了就是「SQL 车道有、local 车道没有」的键集分岔。
+     */
+    findDecidedApprovalsForBinding(sessionId: string, boundCallId: string): Promise<DecidedApprovalRecord[]>;
     /** `undefined` = no pending row; else the owner scope (local scopes are always strings — never null). */
     peekPendingScope(sessionId: string): Promise<string | null | undefined>;
     /**

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

@@ -3,7 +3,7 @@ import { existsSync, readFileSync, readdirSync, renameSync, unlinkSync, mkdirSyn
 import { join } from "node:path";
 import { isApprovalGateKind } from "../tool-approval.js";
 import { FileCheckpointStore, atomicWriteFile, sanitizePathComponent, } from "@sema-agent/core";
-import { boundedRuleOffers, boundedToolInput, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS } from "./checkpoint-store-sql.js";
+import { approvalDecisionOfWinner, approvalPayloadFingerprint, boundedRuleOffers, boundedToolInput, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS } from "./checkpoint-store-sql.js";
 import { UNMANAGED_RETENTION } from "./retention-store-sql.js";
 function terminalAtOf(cp) {
     return Math.max(cp.createdAt + TERMINAL_BACKSTOP_MS, (cp.deadline ?? 0) + TERMINAL_GRACE_MS);
@@ -195,6 +195,27 @@ export class LocalCheckpointStore {
         }
         return false;
     }
+    async findDecidedApprovalsForBinding(sessionId, boundCallId) {
+        const tokens = this.sessionTokens.get(sessionId);
+        if (!tokens)
+            return [];
+        const out = [];
+        for (const t of [...tokens]) {
+            const cp = await this.inner.get(t);
+            if (!cp || cp.status !== "resolved")
+                continue;
+            const pa = cp.pendingAction;
+            if (pa?.toolCallId !== boundCallId)
+                continue;
+            out.push({
+                scope: cp.scope,
+                boundInputHash: pa?.boundInputHash ?? null,
+                decision: approvalDecisionOfWinner(cp.resolvedOutcome, boundCallId),
+                payloadFp: cp.resolvedOutcome === undefined ? null : approvalPayloadFingerprint(cp.resolvedOutcome),
+            });
+        }
+        return out;
+    }
     async peekPendingScope(sessionId) {
         for (const { cp } of await this.pendings())
             if (cp.sessionId === sessionId)

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

@@ -34,6 +34,39 @@ export declare const TIDB_PERMISSION_RULE_STATEMENTS: readonly string[];
 /** {@link TIDB_PERMISSION_RULE_STATEMENTS} 的遍历壳(生产路径走 `tidb-pool.ts` 中央 `ensureSchema`;
  *  本函数留给只需要这三张表的集成测试)。 */
 export declare function ensureTiDBPermissionRuleSchema(pool: MySqlPool): Promise<void>;
+/**
+ * #340 升级前置断言 —— **拒启**,不是 warn(codex 对抗复审 [high],验真后修;形照 #119 的
+ * `assertToolResultProvenanceSchema` 先例)。
+ *
+ * 病:本仓不发 `ALTER TABLE` 迁移(SCHEMA POLICY:改列就改 CREATE + 删库重建)。于是一台**没删表**就升
+ * 上来的部署,`CREATE TABLE IF NOT EXISTS` 对存量 `permission_rule_approval` 是空操作 —— 本车新加的
+ * `command` / `edited_json` 两列不在,而 `get` / `create` / `cas` 三条语句**无条件**引用它们。
+ * 后果不是「少一个新功能」,是**整条审批记录面**在那台机器上是坏的:
+ *  · 卡道「不再询问」(**修前就有**的候选臂也一样)每次撞 unknown column,被回决腿的 catch 吞成
+ *    `rule_store_error` —— 裁决照常 200,服务看起来完全健康;
+ *  · CC 导入的 prepare 连 pending 记录都落不下;
+ *  · 而 `/v1/capabilities` 的 `permissionRules` 仍然报 true ⇒ 本仓「says yes ⟺ route works」整句为假。
+ * 没有这道断言,运维得不到**任何**「这次升级必须重建表」的信号 —— 那正是 #157「禁静默降级」要挡的形态。
+ *
+ * 判据用**能力探测**而不是版本号/information_schema:发一条恒空的 `WHERE 1=0` 读,列不在就报错。
+ * 只判「两列在不在」,不判宽度(两列都是 TEXT 族,没有截断轴)。
+ *
+ * 🔴 **只有可证的缺列才给破坏性指路**(codex 对抗复审 round2/round3 [high],两轮收窄后的终形):
+ * 「探针失败」**不等于**「列不在」。超时、连接被重置、取消、资源不足、列级权限被拒、表整个不存在 ——
+ * 每一种都会让这条读抛错,而把它们诊断成「去 DROP TABLE」是一条**会真的毁掉审计记录**的建议(比它要
+ * 挡的缺陷更贵)。round2 的两步探(先读一列老列)也不够:两次读之间同样可以插进一次瞬时故障。
+ * 终形判据 = **方言的缺列错误码**,一行一方言的闭集(见 {@link isMissingColumnError});其余错误
+ * **原样 rethrow**,一个字都不加工。真库两条腿各自跑过这条路径(db-integration 的存量表格),所以
+ * 这张码表不是抄手册抄来的,是实测钉住的。
+ * 🔴 位置与 #119 同款:**不在** `ensureSchema` 里(那条通道的契约是「只发 CREATE」,有运行时门看着),
+ * 放在 DDL 之后、任何路由装配之前 —— 还没开始服务,拒启的意义仍在;且**只在规则车道真会被装配时**跑
+ * (`PERMISSION_RULES_ENABLED=false` 的部署根本不碰这张表,为它拒启是纯误伤,见调用点)。
+ */
+/**
+ * 「这个错误**是**『列不存在』吗」——判据属主自 #363 起收在 `sql-errors.ts`(与 `isDupKeyError` 同族、
+ * 同理由:识别集复制一次就会漂,而这条谓词守的是一句**破坏性**指路)。本文件此前那份逐字实现已下车,
+ * 语义一个字不变(闭集与 fail-safe 方向逐字见那边的头注)。
+ */
 export declare function assertPermissionRuleApprovalSchema(query: (sql: string) => Promise<{
     rows: Record<string, unknown>[];
 }>, dialect: "tidb" | "pg"): Promise<void>;

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

@@ -2,6 +2,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { z } from "zod";
 import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, foldDelta, parseAllowRuleText, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_SYNC_DROP_CODES, } from "@sema-agent/core";
 import { dialectProtocolJsonEncoder } from "./sql-driver.js";
+import { isMissingColumnError } from "./sql-errors.js";
 export function writerOfSqlRuleStore(store) {
     const w = Reflect.get(store, PERMISSION_RULE_WRITER);
     if (w === null || typeof w !== "object")
@@ -160,14 +161,6 @@ export async function ensureTiDBPermissionRuleSchema(pool) {
     for (const stmt of TIDB_PERMISSION_RULE_STATEMENTS)
         await pool.query(stmt);
 }
-function isMissingColumnError(err, dialect) {
-    if (err === null || typeof err !== "object")
-        return false;
-    const code = Reflect.get(err, "code");
-    if (dialect === "pg")
-        return code === "42703";
-    return Reflect.get(err, "errno") === 1054 || code === "ER_BAD_FIELD_ERROR";
-}
 export async function assertPermissionRuleApprovalSchema(query, dialect) {
     try {
         await query(`SELECT command, edited_json, version, offers_json, selected_offer FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE 1=0`);

package/dist/plugins/scheduler-support.d.ts

@@ -1,6 +1,6 @@
 import { SchedulerError } from "@sema-agent/core";
 import type { SchedulerCapability, ScheduledIntent, SchedulerContext, ScheduledTaskId, ScheduledTaskSummary } from "@sema-agent/core";
-import type { SchedulerRecord } from "@sema-agent/registry-core/scheduler-store";
+import type { SchedulerRecord } from "@sema-agent/settings-schema/scheduler-store";
 export type { SchedulerRecord };
 /** core `Result<T,E>` shape (harness/types) — `{ok:true,value} | {ok:false,error}`. */
 type Result<T, E> = {

package/dist/plugins/scheduler-support.js

@@ -2,7 +2,7 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { randomBytes, createHash } from "node:crypto";
 import { SchedulerError, isValidCronExpr } from "@sema-agent/core";
-import { loadSchedulerStore, saveSchedulerStore } from "@sema-agent/registry-core/node";
+import { loadSchedulerStore, saveSchedulerStore } from "@sema-agent/settings-schema/node";
 const ok = (value) => ({ ok: true, value });
 const err = (error) => ({ ok: false, error });
 export const DEFAULT_SCHEDULER_CAPS = {

package/dist/plugins/sql-errors.d.ts

@@ -38,4 +38,22 @@ export declare function isMysqlDupKeyError(err: unknown): boolean;
 export declare function isPgUniqueViolation(err: unknown): boolean;
 /** 方言分派口——双方言店的调用形(`isDupKeyError(this.db.dialect, e)`)。 */
 export declare function isDupKeyError(dialect: SqlDialect, err: unknown): boolean;
+/** PostgreSQL `undefined_column` 的 SQLSTATE。⚠️ 与 `42P01`(`undefined_table`)刻意分开。 */
+export declare const PG_UNDEFINED_COLUMN_SQLSTATE = "42703";
+/** MySQL/TiDB `ER_BAD_FIELD_ERROR`(未知列)的数字 errno。 */
+export declare const MYSQL_ER_BAD_FIELD_ERRNO = 1054;
+/** MySQL/TiDB `ER_BAD_FIELD_ERROR` 的字符串错误码。 */
+export declare const MYSQL_ER_BAD_FIELD_CODE = "ER_BAD_FIELD_ERROR";
+/**
+ * 「这个错误**是**『列不存在』吗」——升级前置断言(`assert*Schema` 族)的**唯一**判据。
+ *
+ * 🔴 单一属主的理由与 {@link isDupKeyError} 逐字同源(本文件顶注的 single-semantic-multi-site-drift):
+ * 判据一旦复制,两处的识别集就会各自漂,而这条谓词的错判方向**特别贵** —— 它守的是一句**破坏性**的
+ * 错误指路(「去 DROP TABLE」)。超时、连接重置、取消、资源不足、列级权限被拒、表整个不存在,每一种
+ * 都会让探针抛错;把它们诊断成「删表重建」比它要挡的缺陷更贵(#340 codex 对抗复审 round2/round3
+ * [high] 两轮收窄后的终形)。认不出的一律**不是**缺列(fail-safe:宁可把一次真缺列报成原始错误)。
+ *
+ * MySQL 侧两个归因键都认(mysql2 的 `code`/`errno` 是同一件事的两种写法),与 dup-key 那条同姿势。
+ */
+export declare function isMissingColumnError(err: unknown, dialect: SqlDialect): boolean;
 //# sourceMappingURL=sql-errors.d.ts.map

package/dist/plugins/sql-errors.js

@@ -15,4 +15,14 @@ export function isPgUniqueViolation(err) {
 export function isDupKeyError(dialect, err) {
     return dialect === "tidb" ? isMysqlDupKeyError(err) : isPgUniqueViolation(err);
 }
+export const PG_UNDEFINED_COLUMN_SQLSTATE = "42703";
+export const MYSQL_ER_BAD_FIELD_ERRNO = 1054;
+export const MYSQL_ER_BAD_FIELD_CODE = "ER_BAD_FIELD_ERROR";
+export function isMissingColumnError(err, dialect) {
+    if (err === null || typeof err !== "object")
+        return false;
+    if (dialect === "pg")
+        return keyOf(err, "code") === PG_UNDEFINED_COLUMN_SQLSTATE;
+    return keyOf(err, "errno") === MYSQL_ER_BAD_FIELD_ERRNO || keyOf(err, "code") === MYSQL_ER_BAD_FIELD_CODE;
+}
 //# sourceMappingURL=sql-errors.js.map

package/dist/resource-window.d.ts

@@ -0,0 +1,111 @@
+/**
+ * [3833] 件 S-4 —— **running 态跨片用量投影**的数据面(`GET /v1/runs/:id` 的 `crossSliceUsage`)。
+ *
+ * 【为什么需要它】S-3 把三条跨片总额旋钮(`RESOURCE_SUSPEND_TOTAL_TOKENS` / `_BUDGET_USD` /
+ * `_MAX_SLICES`)供到了 `TaskSpec.resourceSuspend`,core 那本跨片账(`ResourceLedger`)也确实在记 ——
+ * 但**跑的过程中 wire 上一个数都读不到**。运维第一次知道「这条 run 逼近过上限」是在**爆窗那一刻**
+ * (行翻 `suspended` + `resource_limit` gate),想提前介入无读面。[3833] 的 75 万 token 就是这样烧完的。
+ *
+ * 【两半各自的真源(刻意不自建第三本账)】
+ *  · **上限半**:本模块的进程内登记册 —— 记的是**这条 run 真正铸给 core 的那只 `resourceSuspend`**
+ *    (装配点 `boot/resolve-spec.ts` 的 `resourceSuspendOptIn`),不是读时现取 env。差别是承重的:
+ *    ① verify/cascade 腿被 `resourceSuspendOptIn` **整只排除**(opt-in 不成立)⇒ 登记册里没有它 ⇒
+ *       整键缺席,绝不显示一个没人执行的天花板;② 滚动改 env 之后,已在跑的 run 报的仍是它自己那份。
+ *  · **已耗半**:run 自己的 durable 账本行 `model_usage`(`trace/project.ts` 的 `aggregateModelUsage`)——
+ *    与 `TaskStats.modelUsage` 回声**同一份账**,append-only、跨 slice、跨进程(每条腿只追加自己的
+ *    delta,和跨越 park 边界)。**本模块不累加任何东西**:读时求和,不落第二本账(两本账必漂移)。
+ *
+ * 【与 core `ResourceLedger` 的关系(诚实登记,别读成「就是那本账」)】core 执法读的是挂在
+ * `resource_limit` checkpoint 行上的 `ResourceLedger`,它对本仓在 running 期**结构性不可达**(没有
+ * 「按 taskId 找 checkpoint」的面,而且跑的时候那行是 `resolved` 的)。两边量的是**同一个量**:
+ * core 的 `spentTokens` 轴 = 每片 `TaskStats.tokens`(= Σ 每次调用 `usage.totalTokens`,**不含**委派子代,
+ * 子代在 `stats.nested`),而 `model_usage` 行正是同一批 `brain.call` 的逐 turn delta、同样只收顶层 run。
+ * 已知差:① **滞后至多一个 turn**(delta 在 turn 边界 drain,进行中的那一 turn 还没入账);② 账本行
+ * 写失败(F 类)会少计。⇒ 本投影是**分诊/预警**读面,**不是**任何门/CAS/resume 判定的输入。
+ *
+ * 【登记册的语义边界(与 `turn-activity.ts` 的 `msSinceLastActivity` 逐字同族)】
+ *  · **同副本 best-effort**:只活在本进程。跨副本 poll(run 跑在别的副本)或本副本重启后 ⇒ 读不到 ⇒
+ *    **整键诚实缺席**。缺席 = 「本副本无法证明这条 run 有跨片窗」,不是「它没有窗」——绝不铸零上限
+ *    (`0` 在 core 那边是**合法且极紧**的上限,与「没配」两义必须可判别,S-3 顶注同一条纪律)。
+ *  · 不落库、不进 SQL 面。有界性由插入序近似 LRU 兜底(CAP 条,每条 ≈ 100B)。
+ *  · **新世代必须清**:session purge 后客户端合法复用自带 taskId 重提交 —— {@link recordResourceWindow}
+ *    每次先删后写,于是「新腿没窗」不会读到旧腿的窗(`turn-activity` codex S1-F2 同款陷阱)。
+ *
+ * 【已声明的代价:每次 poll 一次全量账本读(codex 对抗复审 R2-[medium],如实登记、本批不修)】
+ * {@link buildCrossSliceUsage} 要对**全部** `model_usage` 行求和 ⇒ 调用点(`routes/runs.ts` 的 poll)在
+ * 窗已登记时每拍读一次 `getEvents(taskId, 0)`,工作量随「轮询次数 × 已积累事件数」增长。三条限幅是**结构性**
+ * 的,不是「应该很少见」:① **只有登记过窗的 run 才读**(没开三旋钮的部署、以及 verify/cascade 腿,一次都不读);
+ * ② 只在 `running` 且非 stale 时读;③ 同一条路上早已存在同形读(终局 + 配了 infra 价目表时的 `needCost` 臂,
+ * 同样是 `getEvents(taskId, 0)`)—— 本批加的是**跑动期**这一档,不是新病种。
+ * 🔴 真正的收口在**存储面**(不在本模块):给 run store 加一条「累计用量 + resource_limit park 计数」的
+ * 聚合投影/游标,让 poll 的工作量与账本长度解耦。缓存一份读时结果是**不采纳**的方向——那正是本模块顶注
+ * 拒绝的「第二本账」(它会与账本漂移,且缺席语义会被缓存住)。
+ */
+import type { TaskSpec } from "@sema-agent/core";
+import type { RunEvent } from "./plugins/store-contracts.js";
+/** 这条 run 铸给 core 的**跨片上限**(三轴各自可缺席;至少一根在场本记录才存在)。
+ *  $ 轴用 micro-USD —— 与 core `ResourceLedger.totalBudgetMicroUsd` 同单位、整数,避免浮点累积误差
+ *  (core 自己的换算就是 `Math.round(totalBudgetUsd * 1e6)`,此处逐字同式)。 */
+export interface ResourceWindowTotals {
+    totalTokens?: number;
+    totalBudgetMicroUsd?: number;
+    maxSlices?: number;
+}
+/** wire 上的投影体(`GET /v1/runs/:id` 顶层 `crossSliceUsage`)。**三轴各自成对**:上限键不在 ⇒ 它那根
+ *  的已耗键也不在(没有天花板就没有「逼近天花板」这件事可读)。`spentMicroUsd` 另有一条缺席理由 ——
+ *  unpriced 部署下用量行不带 `costMicroUsd` = **未知**,折 0 会谎报「还没花钱」(RB-368 未知传染)。 */
+export interface CrossSliceUsage {
+    totalTokens?: number;
+    spentTokens?: number;
+    totalBudgetMicroUsd?: number;
+    spentMicroUsd?: number;
+    maxSlices?: number;
+    sliceCount?: number;
+}
+/**
+ * 登记这条 run 的跨片窗(装配点 = 三个 `createRun` 成功分支,与 `clearTurnActivity` 同位同理由)。
+ *
+ * `rs` 就是 `TaskSpec.resourceSuspend` 本身 —— 缺席、或三根总额一根都没有(`resourceSuspendOptIn` 只在
+ * `> 0` 时才铸键,所以「有键」即「有真上限」)⇒ **不留记录**(并清掉同 taskId 的旧世代残留)。
+ */
+export declare function recordResourceWindow(taskId: string, rs: TaskSpec["resourceSuspend"] | undefined): void;
+/**
+ * **续跑腿**的登记(与 {@link recordResourceWindow} 分家,codex 对抗复审 R2-[high] 验真后修)。
+ *
+ * 🔴 三根旋钮在续跑腿上的下场**不同**,所以登记法也必须不同(S-3 已成文的上游契约,此处是它的读面孪生):
+ *  · `totalTokens` / `totalBudgetUsd` —— core **冻在账本上**(`debitLedger` 逐字 `prior ?? total`)。
+ *    续跑腿的 spec 里那两个值是**当期 env 现读**的,与这条链真正在被执法的值**可以不同**(运维在两片
+ *    之间把 500k 改成 1M:core 仍按 500k 停,而现读值会让人以为还剩一倍余量)。⇒ **一律不取**:
+ *    已有记录就保留(那是首片登记的、也就是被冻住的那份),没有记录就诚实缺这一轴。
+ *  · `maxSlices` —— core **不冻结**,每片现读当期部署值去比账本上的 `sliceCount`。⇒ **取当期值**才是真的。
+ *
+ * 缺席语义不变:两条 totals 缺、`maxSlices` 也缺 ⇒ 不留记录(整键缺席)。
+ */
+export declare function recordResumeResourceWindow(taskId: string, rs: TaskSpec["resourceSuspend"] | undefined): void;
+/**
+ * 本副本记得的跨片窗;无记录 ⇒ `undefined`(缺席语义见顶注:「无法证明」,不是「没有窗」)。
+ *
+ * 🔴 **读命中会刷新插入序**(codex 对抗复审 R1-[high] 的逐出半场,验真后修):终局的 run **不主动清**
+ * (与 `turn-activity.ts` 同理由:主动清会制造「done 已打点、行还没翻终态」窗口里的假缺席),于是纯
+ * 写序 FIFO 下,一条长跑的 run 会被它之后的 8192 条**早已终局**的记录挤掉 —— 恰好挤掉唯一还需要这份
+ * 数据的那一条。改成「按读刷新」= 真 LRU:被 poll 的(=活着且有人看的)那条永远是最年轻的。
+ * 代价如实:本函数因此**有副作用**(只改顺序、不改值),调用点是 poll 路径,幂等无碍。
+ */
+export declare function readResourceWindow(taskId: string): ResourceWindowTotals | undefined;
+/** 测试隔离用(生产路径不调 —— 终局不主动清,理由与 `turn-activity.ts` 同:清反而制造假缺席窗口)。 */
+export declare function clearResourceWindow(taskId: string): void;
+/**
+ * 投影体的**纯**构造:上限来自登记册,已耗来自这条 run 的 durable 账本行。
+ *
+ * 三轴的已耗读法:
+ *  · `spentTokens` = 全账本 `model_usage` 行逐模型四分量求和(input MISS + output + cacheRead + cacheWrite
+ *    = 与 `usage-analytics` 读侧同口径,也就是 core `stats.tokens` 量的那个总量)。零行 = 真的还没记到
+ *    账 ⇒ `0`(而不是缺席:token 轴没有「未知」这一格,append-only 保证它单调不减)。
+ *  · `spentMicroUsd` = 同样逐模型求和;**任一模型的成本未知 ⇒ 整个和未知 ⇒ 键缺席**
+ *    (`aggregateModelUsage` 已按模型做了未知传染,这里只要看键在不在)。
+ *  · `sliceCount` = 账本上 `resource_limit` park 行的条数 —— core 的 `ResourceLedger.sliceCount` 正是在
+ *    每次 resource 挂起时 +1,而每一次那样的挂起在本仓都恰好落一行 `suspended{gate.kind:"resource_limit"}`
+ *    (审批 park / plan_review park 的 gate.kind 不同,不计)。
+ */
+export declare function buildCrossSliceUsage(totals: ResourceWindowTotals, events: readonly RunEvent[]): CrossSliceUsage | undefined;
+//# sourceMappingURL=resource-window.d.ts.map

package/dist/resource-window.js

@@ -0,0 +1,80 @@
+import { aggregateModelUsage } from "./trace/project.js";
+const CAP = 8192;
+const windowByTask = new Map();
+const positive = (v) => (typeof v === "number" && Number.isFinite(v) && v > 0 ? v : undefined);
+export function recordResourceWindow(taskId, rs) {
+    if (!taskId)
+        return;
+    windowByTask.delete(taskId);
+    const totalTokens = positive(rs?.totalTokens);
+    const totalBudgetUsd = positive(rs?.totalBudgetUsd);
+    const maxSlices = positive(rs?.maxSlices);
+    if (totalTokens === undefined && totalBudgetUsd === undefined && maxSlices === undefined)
+        return;
+    if (windowByTask.size >= CAP) {
+        const oldest = windowByTask.keys().next().value;
+        if (oldest !== undefined)
+            windowByTask.delete(oldest);
+    }
+    windowByTask.set(taskId, {
+        ...(totalTokens !== undefined ? { totalTokens } : {}),
+        ...(totalBudgetUsd !== undefined ? { totalBudgetMicroUsd: Math.round(totalBudgetUsd * 1e6) } : {}),
+        ...(maxSlices !== undefined ? { maxSlices } : {}),
+    });
+}
+export function recordResumeResourceWindow(taskId, rs) {
+    if (!taskId)
+        return;
+    const prior = windowByTask.get(taskId);
+    const maxSlices = positive(rs?.maxSlices);
+    const merged = {
+        ...(prior?.totalTokens !== undefined ? { totalTokens: prior.totalTokens } : {}),
+        ...(prior?.totalBudgetMicroUsd !== undefined ? { totalBudgetMicroUsd: prior.totalBudgetMicroUsd } : {}),
+        ...(maxSlices !== undefined ? { maxSlices } : {}),
+    };
+    windowByTask.delete(taskId);
+    if (merged.totalTokens === undefined && merged.totalBudgetMicroUsd === undefined && merged.maxSlices === undefined)
+        return;
+    if (windowByTask.size >= CAP) {
+        const oldest = windowByTask.keys().next().value;
+        if (oldest !== undefined)
+            windowByTask.delete(oldest);
+    }
+    windowByTask.set(taskId, merged);
+}
+export function readResourceWindow(taskId) {
+    const hit = windowByTask.get(taskId);
+    if (hit !== undefined) {
+        windowByTask.delete(taskId);
+        windowByTask.set(taskId, hit);
+    }
+    return hit;
+}
+export function clearResourceWindow(taskId) {
+    windowByTask.delete(taskId);
+}
+export function buildCrossSliceUsage(totals, events) {
+    if (totals.totalTokens === undefined && totals.totalBudgetMicroUsd === undefined && totals.maxSlices === undefined)
+        return undefined;
+    const perModel = totals.totalTokens !== undefined || totals.totalBudgetMicroUsd !== undefined ? aggregateModelUsage([...events]) : undefined;
+    let spentTokens = 0;
+    let spentMicroUsd = 0;
+    for (const d of Object.values(perModel ?? {})) {
+        spentTokens += d.inputTokens + d.outputTokens + d.cacheReadTokens + d.cacheWriteTokens;
+        if (d.costMicroUsd === undefined)
+            spentMicroUsd = undefined;
+        else if (spentMicroUsd !== undefined)
+            spentMicroUsd += d.costMicroUsd;
+    }
+    const sliceCount = totals.maxSlices === undefined
+        ? undefined
+        : events.filter((e) => e.type === "suspended" && e.data?.gate?.kind === "resource_limit").length;
+    return {
+        ...(totals.totalTokens !== undefined ? { totalTokens: totals.totalTokens, spentTokens } : {}),
+        ...(totals.totalBudgetMicroUsd !== undefined
+            ? { totalBudgetMicroUsd: totals.totalBudgetMicroUsd, ...(spentMicroUsd !== undefined ? { spentMicroUsd } : {}) }
+            : {}),
+        ...(totals.maxSlices !== undefined ? { maxSlices: totals.maxSlices, sliceCount } : {}),
+    };
+}
+//# sourceMappingURL=resource-window.js.map