@sema-agent/server 7.3.0 → 7.5.0

package/USAGE.md

@@ -118,6 +118,8 @@ MODEL_DEGRADE_ON=rate_limit,breaker_open   # 可选,反应式触发器子集;词
 # 是 core 退化检测(安全网)的预防。长链推理/council 易跑飞的部署建议设。
 MODEL_FREQUENCY_PENALTY=0.5   MODEL_PRESENCE_PENALTY=0.3
 MODEL_EXTRA_BODY='{"top_k":40}'   # JSON 逃生口(top_k / logit_bias 等;penalty 同名键会覆盖它)
+                                  # ⚠️ core ≥5.15 起 max_completion_tokens 是保留键(config.extra_body_output_cap
+                                  #    响亮拒)——输出上限请用任务面的 limits.maxOutputTokens,别从这里塞
 ```
 - **brain 拥有的键永远赢**:`temperature`/`max_tokens` 等放进 `extraBody` 会被 strip + core 警告(`phase:"config"`),不会静默改;auth/content-type/version 头硬锁不可顶替(1.60 安全修复)。
 - **必须静态**:`extraBody` 在 boot 时按固定 env 建一次(稳定键序),**不可逐任务变**,否则破前缀缓存(design/9/31)。未设 → 请求字节级不变。
@@ -148,6 +150,26 @@ MODEL_CODE_ROLES=default,subagent     # 不设=全中立;仅这些角色在「
 - 经 `RoleSpec.systemPrompt` 挂在**角色**上，非开发角色保持中立、全局默认 `DEFAULT_SYSTEM_PROMPT` 不变；任务自带 `systemPrompt`(或客户端注入)时仍优先。
 - **验证门**（core 1.44，opt-in）：请求体带 `verify:true`(可选 `verifyRounds`，夹到 [1,5]、默认 2)→ 任务跑完后由**独立只读对抗 verifier**(`verifier` 角色，默认=主模型)证据强制地"试图 break 它"，FAIL 则把 findings 注回同 session 续跑修复→重验，循环到 PASS 或轮数上限。结果带 `verification:{verdict,rounds,findings,evidence}`（`verdict` 看质量，`result`/`status` 仍是实现的）。**仅 `/v1/tasks`(同步)与 `/v1/runs`(异步)**——`/v1/tasks/stream` 不支持(多轮非单流，请求 verify 会 400)。verifier 工具默认 = 实现任务工具滤掉 `effect:"write"`(只读边界)。`/metrics` 加 `verifications_total{verdict}`。
 - **记忆(design/138 文件记忆引擎,2026-07-08 起唯一记忆面)**:core 注入式文件引擎——任务开始时 materialize 记忆目录(`MEMORY_ENGINE_DIR`,默认 `~/.ai-agent`),模型用**普通文件技能**读写记忆(CC `# Memory` 指令 + 派生索引;无 remember/recall 工具),任务边界 harvest 门(secret/cap 扫描)提交。单用户默认开,`MEMORY_ENGINE=off` 显式关;多租户恒关(文件基座无租户隔离,fail-closed)。旧 SQL 记忆面(`MEMORY_BACKEND`/`EMBEDDING_*`/`MEMORY_READ_LIMIT`/去重/向量检索、`GET/DELETE /v1/memory` 与 session memory 写 verb)已退役,数据不迁移——升级后对库跑一次 `scripts/drop-memory-tables.sql`。`body.memoryWrite:false` 仍是每请求只读开关(harvest 不提交)。
+- **org 记忆准入(design/170 件A,7.0.0 起 BREAKING)**:`org:*` 记忆 scope 分**两个来源**——部署自证
+  (env `MEMORY_SCOPE` 的 org 形 + **单用户部署**的 `projects[].defaultScopes` org 键)直通;**多租户**
+  部署里由调用方 `projectId` 选中的登记簿 org 键算 **request 来源**,必须拿到授权目录的逐 principal
+  授予才准入,拿不到一律 fail-closed 拒(纯读泄露面:projectId 只过形状门不过授权)。目录源**三态单选,
+  授权面不双源合并**:config-center 远程腿(per-principal `orgMemory` 段)> `MEMORY_ORG_DIRECTORY_JSON`
+  静态表 > 缺席(request 来源的 org scope 恒拒)。同一个目录也是 `GET /v1/memory/export` /
+  `POST /v1/memory/sync/:scope` 的 `org:` 属主门真源(写面另需条目 `write:true`);拒绝形 = 终局
+  `memory.admission_denied`(403)/ 瞬时 `memory.admission_required`(503,带 `retryAfterSec`)。
+
+| env | 缺省 | 说明 |
+|---|---|---|
+| `MEMORY_ORG_ADMISSION_MODE` | `enforce` | `enforce`=判决即结果;`audit`=**运维诊断位**——准入面判决照算、拒绝降为日志+metric,零行为变化(不整拒、不窄化写面);`/v1/memory/export`、`/v1/memory/sync/:scope` 的 `org:` 属主门在 audit 下**逐字保持收编前的 operator-only**(未验证的目录不得开数据面)。两模式都要求目录 client 在场 |
+| `MEMORY_ORG_DIRECTORY_JSON` | 缺省 | 单机形静态授权表 `{"<principal>":{"org:acme":{"write":true}}}`。**启动期整表校验,坏表拒启动**。有 config-center 时被忽略(center 胜 + warn) |
+| `MEMORY_ORG_GRANT_TTL_MS` | `60000`(`[1000, 3600000]`) | 授予/负结果的缓存 TTL = 「有界 LKG」:**新任务/新 resume 腿**的准入判决滞后 ≤ 此值;**在跑任务不受吊销影响**(判决点在 prepare 期) |
+| `MEMORY_ORG_UNAVAILABLE_BACKOFF_MS` | `10000`(`[500, 600000]`) | 目录取不到之后的退避窗(只用于取数失败臂,不用于负结果) |
+
+  ⚠️ **拒启动**:多租户 + 记忆面点亮 + `projects[].defaultScopes` 里有 org 键 + 目录源缺席 ⇒ 启动报错
+  并点名 projectId(该部署的每个此类请求都会在 prepare 期整拒,响亮拒启动比静默全拒服务诚实)。
+  ⚠️ **回滚脚枪**:回滚到「无 config-center」模板前先清掉残留的 `MEMORY_ORG_DIRECTORY_JSON` —— 否则
+  它作为 operator 自证通道**复活旧授权**(详见 `docs/DEPLOY-PREREQS.md`)。
 
 **可选 — 模型级联 cascade（core 1.45，opt-in）**
 ```bash
@@ -231,6 +253,19 @@ FLEET_ADVERTISE_ADDRESS=http://<本机可达IP>:8090  # 可选:设了才启 flee
 - **仅 `/v1/tasks`(同步)+ `/v1/runs`(异步)**——`/v1/tasks/stream` 不支持(多次尝试非单流,400)。与 `verify` **互斥**(同时给 → 400)。
 - 成本上界 = 任务的 `maxCostUsd`(防冷重跑税)。**三条 core 警示**:① 每档**冷重跑**重付输入成本(便宜档常过才划算);② 门收到**未脱敏**输出(自定义门转发外部 verifier 要脱敏);③ **写工具会跑 N 次**——**只用于只读/幂等任务**(每次升级整任务重跑)。开放式任务(找全 bug/文笔)没有可判定 oracle、级联会空转,那种用 `team`(广度对抗)而非级联(深度阶梯)。
 
+**可选 — AskUserQuestion 的裁量窗(问活人的三个帽子)**
+```bash
+# 每条 run 腿同时能挂几个问题(并发帽,1..64)
+QUESTION_MAX_CONCURRENT_PER_RUN=2
+# 每条 run 腿一共能问人几次(总量帽=防刷屏,1..10000)
+QUESTION_MAX_TOTAL_PER_RUN=20
+# 一个没人答的问题挂多久后释放(毫秒,1000..3600000;默认 5 分钟)
+QUESTION_TTL_MS=300000
+```
+- 三个值都有出厂缺省(即上面写的值),**不设=行为不变**;越界值**启动期响亮拒**(不静默夹取)。
+- 窗用尽 / 到期 **不是替人作答**:服务只报「此刻无人可答」,落点由引擎选——**durable 部署**(`DURABLE_APPROVAL=true` 且这条腿没有活的流)把问题 **park** 成待办,运维随后经审批面带答案补答;**无 durable 的部署**则让模型被告知"没人在"后按自己的判断继续(run 永不挂死)。
+- 想让人有更长时间答就调大 `QUESTION_TTL_MS`;想让 agent 少打扰人就调小 `QUESTION_MAX_TOTAL_PER_RUN`。
+
 **布尔旋钮的取值与极性(运维必读)**
 
 布尔 env **只认 `true` / `false` 两个字面量**。写成 `1` / `yes` / `TRUE` ⇒ 该旋钮退回自己的缺省值,并在启动时
@@ -393,6 +428,29 @@ curl -N http://<host>:8090/v1/tasks/stream -H 'content-type: application/json' \
 
 > **operator 鉴权(审批队列)**:`OPERATOR_PRINCIPALS=ops:alice,ops:bob`(CSV)= 谁能当 operator——列任意 owner 待办 + 决议(批/否)。**单租户部署不设=旧行为**(握 service token 即 operator,向后兼容);设了之后,非名单 principal 列待办只看自己的、且**不能决议**(403,防"请求方批自己的高危操作"绕过 F4 闸)。⚠️ **多租户形拒启**(#157-①):`DURABLE_APPROVAL=true` + `REQUIRE_PRINCIPAL=true` 而 `OPERATOR_PRINCIPALS` 空 ⇒ 进程启动失败并点名修法——否则空名单会让任一已验证租户读到其他租户的待批队列(读面 true-for-all)。设名单,或确属单租户则不设 `REQUIRE_PRINCIPAL`。
 >
+> **🔧 升级到 7.5.0(引擎 core 5.17.0)前:把待决审批排空。** 5.17.0 起,park 铸行按**后端能承载的
+> 宽度**落——审批人看到的 args / 预览、盘上躺着的行、resume 真正执行的那份参数,以及运维在 `/decide`
+> 上要回显的那个不透明 `boundInputHash`,都从同一份投影铸出。**本服务的两条 checkpoint 后端
+> (SQL 双生 / 本地文件)都是 JSON 序列化**,已按 5.17.0 的新轴显式声明 `fidelity: "json"`,所以对
+> **JSON 值域**(模型产出的 args 恒在此域内)这次折叠规则变更是**逐字节零变化**:同一份 args 在 7.4.0
+> 和 7.5.0 上算出的 `boundInputHash` 相同,已经发出去的哈希不需要重新取。
+> 需要动作的只有一种行:**升级前就已经 pending 的那些**——它们带的是旧版本铸的哈希与(可能已降级的)
+> 参数,新引擎不会追认改写。**滚版前把它们批/否掉**(`GET /v1/approvals` 列出来,逐个 `/decide`),
+> 或明确接受那批老行仍按旧语义结算。新铸的行不受影响。
+> **同一次升级还要重建 mailbox 两表。** `mailbox_messages` 新增 `hop_chain` 列(引擎的 peer 消息守卫),
+> 而建表语句是 `CREATE TABLE IF NOT EXISTS` —— 对已存在的旧表**一字不改**,升级后每一次 teammate 消息
+> 投递都会报 unknown column 并失败。按本服务的 schema 契约(删库重建、不做增量迁移),滚版时
+> **重建 `mailboxes` / `mailbox_messages` 两表**(或整库),基线见 `docs/schema/baseline-*.sql`。
+> 该表是带 TTL 的短命投递队列而非账本,重建只丢排队中的 teammate 消息;介意就先让在飞的 peer 会话收敛。
+>
+> 顺带一提,新引擎会在铸点**直接拒绝 park**(点名后端、退回同步门)的只有两类值,而且都只可能由
+> 部署侧的 hook / policy 改写进 args —— 模型自己给的参数永远是 JSON,碰不到任何一条:
+> ① **拿不住的值**(函数、symbol、活句柄这些 `structuredClone` 复制不了的),以及 **`SharedArrayBuffer`**
+> ——后者的理由不是「编不成 JSON」而是「克隆之后仍与原持有者共享同一块内存」,一行存下去别人还能改它,
+> 所以在捕获性检查那一步就被拒;② **编不成 JSON 的值**(`BigInt`、循环引用)。
+> 至于 `Date` / `Map` / 正则这类**能编码但会被 JSON 投影压扁**的值,不拒绝 —— 它们按投影后的形态入行,
+> 若投影改变了值,引擎会拿投影后的那份**重新过一遍部署策略**再决定 park。
+>
 > **parked 后台子代的待办分两个 scope 桶**(durable 审批面,core 1.389 起):父任务显式转发审批范围的常规 ask 落在该范围的 scope 下(可预算);无转发时无人值守拦下的敏感操作 ask 落在按 principal 派生的隔离 scope 下(带缺省 deadline、永不自动放行)。operator 全量列表天然两桶全见;**按 `?owner` 过滤时注意两桶可能不同名**,展示面要两个都查。
 
 ---
@@ -433,6 +491,11 @@ curl -N http://<host>:8090/v1/tasks/stream -H 'content-type: application/json' \
 `limit.` / `usage.`(部署级治理窗)/ `capability.`(本部署没接这个面)/ `feature.`(开关没开)/
 `internal.` / `state.`;未知码按前缀兜底永远安全。完整码表见 `docs/ASSISTANT-WIRE-CONTRACT.md` §附录 A。
 
+**进程警告面(日志采集方注意)**:引擎(core ≥5.16)在持久 agent 行的 org 判决写回被丢弃等场合走
+Node `process.emitWarning`,警告文案前缀固定 `sema durable-agents:`——采集规则按该前缀匹配,别当噪音过滤掉。
+server 自身的兜底留痕走 stderr 契约行 `[sema] fail-open: <tag>`(逐 tag 一次)+ `fail_open_total` 指标,
+tag 词表与每条的最坏后果见 `docs/FAIL-OPEN-CENSUS.md`。
+
 ### 9.1 limits.approachNotice(6.1.0 起)
 
 引擎默认在上下文用量到 80%/95% 时各注入一次接近提示(SSE 上是 `steering_injected` 帧、

package/dist/approval-card.d.ts

@@ -32,7 +32,11 @@ export declare const MAX_AGENT_NAME = 200;
  * `risk` 的三态形(设计稿 §14.1,core [2794] 回帖后定):`AskRequest.riskAxes?.{irreversible,egress}`
  * 是 **additive optional**,**缺席 = 引擎未判,不是「安全」**。所以两轴在这里是 `optional()`:
  * `true` / `false` / **缺席(未标注)** 三态各自可分,投影层**禁把缺席折算成 false** —— 那等于替引擎
- * 打包票。`requiresRealApproval` 是 core 今天唯一在场的粗粒度安全类标记(必填,车2 已有真值来源)。
+ * 打包票。`requiresRealApproval` 是**粗粒度**安全类标记,两侧的在场契约**不同、别混**:core 侧是
+ * `AskRequest.requiresRealApproval?: boolean`(**可选、只在为真时带**,缺席 = 这不是一次安全类 ask,是
+ * 正常的否定形而不是坏形);本卡面这一格是**必填 boolean**,由车2 的入参归一化(`=== true`)而来。
+ * 它与两轴是两件事而不是新旧替代——原注写的「core 今天唯一在场的标记」是 `riskAxes` 上树之前的现势话,
+ * 自 core **5.14.0**(其 CHANGELOG 的 `AskRequest.riskAxes` additive 条)起两者并存。
  */
 export declare const ApprovalCardSchema: z.ZodObject<{
     toolName: z.ZodString;
@@ -45,6 +49,7 @@ export declare const ApprovalCardSchema: z.ZodObject<{
         egress: z.ZodOptional<z.ZodBoolean>;
         requiresRealApproval: z.ZodBoolean;
     }, z.core.$strict>;
+    governanceForced: z.ZodOptional<z.ZodLiteral<true>>;
     fromSubagent: z.ZodOptional<z.ZodLiteral<true>>;
     sourceTaskId: z.ZodOptional<z.ZodString>;
     sourceAgentName: z.ZodOptional<z.ZodString>;
@@ -75,6 +80,7 @@ export declare const ApprovalCardEnvelopeSchema: z.ZodObject<{
             egress: z.ZodOptional<z.ZodBoolean>;
             requiresRealApproval: z.ZodBoolean;
         }, z.core.$strict>;
+        governanceForced: z.ZodOptional<z.ZodLiteral<true>>;
         fromSubagent: z.ZodOptional<z.ZodLiteral<true>>;
         sourceTaskId: z.ZodOptional<z.ZodString>;
         sourceAgentName: z.ZodOptional<z.ZodString>;
@@ -107,6 +113,9 @@ export interface ApprovalCardSource {
     args?: unknown;
     argsOmitted?: boolean;
     toolCallId?: string;
+    /** [2942]/[2943]:治理来源标 —— 与 wire 帧**同一份素材**(`ToolApprovalFrame` 结构上满足本接口),
+     *  于是 live 帧 / `card_json` / 重放帧三面同源,不是三处各判一遍。 */
+    governanceForced?: true;
     fromSubagent?: true;
     sourceTaskId?: string;
     /** 已 redactSecrets。 */
@@ -121,8 +130,11 @@ export interface ApprovalCardSource {
  * design/172 §3.1 的**中性投影**(设计稿 §6.2)—— 写侧的唯一铸造点。
  *
  * `risk` 三态(§14.1):两轴 `optional`,`true`/`false`/**缺席(未标注)** 各自可分。`req` 是 core 交来的
- * `AskRequest`(可能带、也可能不带 `riskAxes`),按 `unknown` 窄读;`requiresRealApproval` 是 core 今天
- * 唯一在场的粗粒度安全类标记,缺席 = 这不是一次安全类 ask(core 的铸造点语义,不是我们的折算)。
+ * `AskRequest`(可能带、也可能不带 `riskAxes`),按 `unknown` 窄读;`requiresRealApproval` 走**独立入参**
+ * (车2 已归一化的 boolean),不从 `req` 里读。core 侧它是可选、只在为真时带,缺席 = 这不是一次安全类
+ * ask(core 的铸造点语义,不是我们的折算);卡面这一格恒在,`false` 就是那个否定形的如实投影。
+ * (原注写的「core 今天唯一在场的粗粒度标记」自 core 5.14.0 的 `riskAxes` 起过期,见 `ApprovalCardSchema`
+ * 头注。)
  */
 export declare function buildApprovalCard(source: ApprovalCardSource, req: unknown, requiresRealApproval: boolean): ApprovalCard;
 /** 落库信封的纯构造(写侧;读侧 = `ApprovalCardEnvelopeSchema.safeParse`,**同一个 schema**)。 */

package/dist/approval-card.js

@@ -35,7 +35,11 @@ const MAX_MESSAGE = 8192;
  * `risk` 的三态形(设计稿 §14.1,core [2794] 回帖后定):`AskRequest.riskAxes?.{irreversible,egress}`
  * 是 **additive optional**,**缺席 = 引擎未判,不是「安全」**。所以两轴在这里是 `optional()`:
  * `true` / `false` / **缺席(未标注)** 三态各自可分,投影层**禁把缺席折算成 false** —— 那等于替引擎
- * 打包票。`requiresRealApproval` 是 core 今天唯一在场的粗粒度安全类标记(必填,车2 已有真值来源)。
+ * 打包票。`requiresRealApproval` 是**粗粒度**安全类标记,两侧的在场契约**不同、别混**:core 侧是
+ * `AskRequest.requiresRealApproval?: boolean`(**可选、只在为真时带**,缺席 = 这不是一次安全类 ask,是
+ * 正常的否定形而不是坏形);本卡面这一格是**必填 boolean**,由车2 的入参归一化(`=== true`)而来。
+ * 它与两轴是两件事而不是新旧替代——原注写的「core 今天唯一在场的标记」是 `riskAxes` 上树之前的现势话,
+ * 自 core **5.14.0**(其 CHANGELOG 的 `AskRequest.riskAxes` additive 条)起两者并存。
  */
 export const ApprovalCardSchema = z
     .object({
@@ -55,6 +59,25 @@ export const ApprovalCardSchema = z
         requiresRealApproval: z.boolean(),
     })
         .strict(),
+    /**
+     * [2942]/[2943] **ADDITIVE**:`true` ⇔ 这只 ask 的门来自运维治理层(语义、判定缝与「缺席 ≠ false」
+     * 的硬条款逐字见 `tool-approval.ts` 的 `ToolApprovalFrame.governanceForced` 与
+     * `governance-ask-marks.ts` 顶注)。放在**卡的顶层**而不是 `risk` 里:`risk` 讲的是引擎对这次操作的
+     * 风险判定(不可逆/出网/安全类),本键讲的是**门是谁下的**,两件事。
+     *
+     * ⚠️ **回滚窗的行为(codex 交叉复审 round1 [high],验真后按「真实但内生」收下)**。形版本闩
+     * (`schemaVersion`)**不动**:additive optional 键在 `.strict()` 下对**旧行**无碍(缺席合法),代价
+     * 全在**回滚方向** —— 一个降级回旧二进制的副本读到带本键的新行,`safeParse` 会失败,两条读面各自:
+     *   · 重放腿(`buildReplayFrame`)⇒ 该行**跳过** + 一次 warn(§5.3),不炸流;
+     *   · `askBroadcast` 幂等命中该行 ⇒ 走「持久行不可用」臂 ⇒ `"unavailable"` = **park 路由**
+     *     (tool-approval.ts 的 `persisted-row-unusable`)。park 是本协议的 fail-safe 出口:人仍可经
+     *     durable gate 补批 —— 不是「批准凭空消失」,更不是把它折算成 deny。
+     * 这个代价是**任何** additive 键在一个 `.strict()` schema 下的内生代价,不是本键独有:bump 到
+     * `schemaVersion: 2` 只会更糟(旧读面 `z.literal(1)` 直接全量拒收**所有**新行,连缺席本键的行都收不了)。
+     * ⇒ 处置 = 不改形版本;**发车条款**写进 CHANGELOG:整队滚前(不留长期混版窗),回滚窗内新卡降级为
+     * park(fail-safe),回滚窗结束即自愈。
+     */
+    governanceForced: z.literal(true).optional(),
     /** 委派出处(子代 ask 才在场;判别键 = `fromSubagent`,core RB-39②)。 */
     fromSubagent: z.literal(true).optional(),
     sourceTaskId: z.string().max(MAX_IDENT).optional(),
@@ -86,10 +109,16 @@ export const APPROVAL_CARD_SCHEMA_VERSION = 1;
 /**
  * core 的风险轴(`AskRequest.riskAxes`,[2829]/§14.1)的**边界窄读**。
  *
- * 🔴 为什么是 `safeParse` 而不是读 `req.riskAxes`:树上的 core d.ts(5.13.0)**还没有这个键**,
- * 而字段形已由 core 认领(5.14.0-pre)。窄读让**编译与行为解耦**——今天编译得过、缺席=未标注;
- * 终版到货后同一行代码自然点亮,不需要回来改一个字。裸 `as` 转型会在两个方向上都出错:既绕过了
- * 宪法 [2704] 的「边界必 schema」,也会在 core 真发出一个形状不同的键时静默把垃圾投上卡面。
+ * ✅ **已点亮**:`riskAxes` 现在既在类型面也在真码面(树上 core 5.16.0,`core/tool-policy.d.ts` 的
+ * `readonly riskAxes?: {…}`;package.json 的 floor 已抬到 `^5.16.0`)。窄读当初写下时的现势前提是
+ * 「树上 core d.ts(5.13.0)还没有这个键、字段形只由 core 认领」——该键自 core **5.14.0** 起就在
+ * (其 CHANGELOG 的 `AskRequest.riskAxes` additive 条),那句现势话早已过期,**别再据它判断「core 还没
+ * 供值 ⇒ 卡面 risk 恒缺席」**。判在不在场以**装树的 d.ts 为准**,不要读注里的版本号
+ * (同族销账见 `tool-approval.ts` 的 `readBoundInputHash` 头注,#164)。
+ *
+ * 🔴 保留 `safeParse` 而不改成直读 `req.riskAxes` 的理由不变(它从来不只是等字段):窄读让**编译与行为
+ * 解耦**,缺席=未标注;裸 `as` 转型会在两个方向上都出错——既绕过宪法 [2704] 的「边界必 schema」,也会在
+ * core 发出一个形状不同的键(或加轴)时静默把垃圾投上卡面。
  *
  * 未知键被 zod 默认 strip(此处**故意不 `.strict()`**:core additive 加轴时不该让整只 ask 的卡面塌掉);
  * 形不合(如 `irreversible: "yes"`)⇒ 整个 safeParse 失败 ⇒ 按**缺席**处置 = 「未标注」,
@@ -115,8 +144,11 @@ function clip(s, max) {
  * design/172 §3.1 的**中性投影**(设计稿 §6.2)—— 写侧的唯一铸造点。
  *
  * `risk` 三态(§14.1):两轴 `optional`,`true`/`false`/**缺席(未标注)** 各自可分。`req` 是 core 交来的
- * `AskRequest`(可能带、也可能不带 `riskAxes`),按 `unknown` 窄读;`requiresRealApproval` 是 core 今天
- * 唯一在场的粗粒度安全类标记,缺席 = 这不是一次安全类 ask(core 的铸造点语义,不是我们的折算)。
+ * `AskRequest`(可能带、也可能不带 `riskAxes`),按 `unknown` 窄读;`requiresRealApproval` 走**独立入参**
+ * (车2 已归一化的 boolean),不从 `req` 里读。core 侧它是可选、只在为真时带,缺席 = 这不是一次安全类
+ * ask(core 的铸造点语义,不是我们的折算);卡面这一格恒在,`false` 就是那个否定形的如实投影。
+ * (原注写的「core 今天唯一在场的粗粒度标记」自 core 5.14.0 的 `riskAxes` 起过期,见 `ApprovalCardSchema`
+ * 头注。)
  */
 export function buildApprovalCard(source, req, requiresRealApproval) {
     const axes = RiskAxesEnvelopeSchema.safeParse(req);
@@ -134,6 +166,8 @@ export function buildApprovalCard(source, req, requiresRealApproval) {
             ...(riskAxes?.egress !== undefined ? { egress: riskAxes.egress } : {}),
             requiresRealApproval,
         },
+        // [2942]/[2943]:只在为真时投影(`=== true` 严判:非布尔真值不得把一张普通卡染成治理卡)。
+        ...(source.governanceForced === true ? { governanceForced: true } : {}),
         ...(source.fromSubagent === true ? { fromSubagent: true } : {}),
         ...(sourceTaskId !== undefined ? { sourceTaskId } : {}),
         ...(sourceAgentName !== undefined ? { sourceAgentName } : {}),

package/dist/approval-reconciler.d.ts

@@ -5,12 +5,26 @@
  * `PARKED | DENIED | VOID`,并在崩溃后补位那些没人打 expire 的孤儿 `STREAM_PENDING` 行。
  *
  * ── 判据表 v2(设计稿 §9 尾的五臂汇总,逐字落地;每臂注读口)────────────────────────────────────────
- *  ① **identity ∧ hash 双等** ⇒ `bindBatch`(判别式返回;`ok:false` ⇒ 降级续判)
- *     identity = (scope=owner, sessionId, toolCallId, 因果下界 `cp.createdAtMs ≥ ask.createdAtMs`)
- *     ∧ `cp.boundInputHash === ask.boundInputHash`,**任一侧 hash 缺席 = 不命中**(§9 C2:同 session 内
- *     `toolCallId` 会被网关重用,只靠 identity 会把旧 ask PARK 到别人的 resume 坐标上,而 `PARKED` 是
- *     不可回滚的终态)。读口 = `findCheckpointCandidatesForAsk`(§9 C4 窄谓词精确查,无分页假阴性);
- *     `unparseable` 候选**视同不匹配**(单行读不出不许打断整段扫描,§8 C-6)。
+ *  ① **身份三元组 ∧ hash 双等** ⇒ `bindBatch`(判别式返回;`ok:false` ⇒ 降级续判)
+ *     身份 = `sourceTaskId` 相等 ∧ `toolCallId` 相等 ∧ **因果下界**(不是等式)`cp.createdAtMs ≥
+ *     ask.createdAtMs`;再 ∧ `cp.boundInputHash === ask.boundInputHash`。三维里只有前两维是等式,把时间
+ *     那一维读成等式会让合法 park 几乎命不中。逐字实现在 {@link classifyGateMatch};判据的**唯一
+ *     属主**是那个函数的头注,这里只列纲要,细则(祖先层 fold 否决、多候选取舍)不在此复述。
+ *     🔴 两处易错,写在这里免得下一个人照旧口径改码:
+ *      · 承重的第一维是 **`sourceTaskId`**(#168 件1,黑板 [2897]③①)——`sessionId` **不进身份等式**
+ *        (委派子代的 ask 落行记的是投递上下文的根会话,park 却发生在子代自己的 sessionId 上,只按
+ *        session 等值会张冠李戴),它在这一层只是读口 `findCheckpointCandidatesForAsk` 的入参。
+ *        ⚠️ 但别据此把它当无用键:{@link isAncestorFoldMint} 的祖先层否决判的正是
+ *        `sourceTaskId !== sessionId` —— 那是内存里的承重用法,只是不属于身份等式;
+ *      · hash **任一侧缺席一律不 bind**(硬相等不放宽,理由同下)。缺席的**归因**分两级,别写成一句:
+ *        身份先判 —— 同身份候选一条都没有且候选集非空 ⇒ `identity_miss`(有对家但不是这一只,或读不出);
+ *        只有在身份这一层没被判掉时,hash 缺席才落 `single_mint` 三形
+ *        (`ask_only` / `checkpoint_only` / `neither`)。`single_mint` 是可观测分类、不是放宽的命中;
+ *        把「只有一侧铸过」这格结构事实混进 `identity_miss` 的噪声底,运维就读不出两者的区别。
+ *     两道等式都不许放宽的原因不变(§9 C2:同 session 内 `toolCallId` 会被网关重用,身份不严会把旧 ask
+ *     PARK 到别人的 resume 坐标上,而 `PARKED` 是不可回滚的终态)。读口 = `findCheckpointCandidatesForAsk`
+ *     (§9 C4 窄谓词精确查,无分页假阴性);`unparseable` 候选**视同不匹配**(单行读不出不许打断整段
+ *     扫描,§8 C-6)。
  *  ② run 终局分臂(读口 `runStore.getRun`):`status ∈ {completed, failed, blocked}`(§8 A-1 词表修正 ——
  *     `cancelled` 不是 run 状态,取消 = `failed` + `errorCode`)——
  *       - `failed ∧ errorCode === "cancelled"`,或批行已 `ABORTED` ⇒ `VOID`(取消不是路由失败,§9 C3);
@@ -82,18 +96,82 @@ export interface ReconcileInput {
     allowBind?: boolean;
 }
 /**
- * 判据 1 的**硬谓词**(纯函数,§9 C2 + §8 D-2)。
+ * 判据 1 的一次**分类**结果(#168 件1;纯数据)。
  *
- * 返回选中的候选,或 `undefined` = 不命中。逐条:
+ * 为什么不只回「命中 / 不命中」:黑板 [2897]/[2898] 两帖把「两侧摘要不等」拆成了**四种成因**,处置各不
+ * 相同 —— 只有一种是真的「两个值不一样」,其余三种根本只有一侧(或零侧)铸过摘要。压成同一个
+ * `undefined` 会让运维看着一条「不匹配」去查一件从没发生过的事。
+ */
+export type GateMatchOutcome = 
+/** 三元组身份 ∧ 摘要双等 —— 判据 1 命中。 */
+{
+    kind: "match";
+    candidate: CheckpointAskCandidate;
+}
+/** 祖先冻结 approver 层 fold 中途的那一次铸造:其后还可能有 rewrite,两侧**本不该等**([2912]③)。 */
+ | {
+    kind: "ancestor_fold_mint";
+}
+/**
+ * 单铸路径 —— **不是** mismatch([2897]③②):
+ *  - `ask_only`：纯 sync 腿(同轮结算,永无 checkpoint 行)/ 再审批链(2 次 ask 铸造、0 次 checkpoint);
+ *  - `checkpoint_only`：durable-first 干净 args(ask 侧 0 次铸造,checkpoint 铸出);
+ *  - `neither`：字符串模式 `onAsk` + durableApproval(两侧都没铸)。
+ */
+ | {
+    kind: "single_mint";
+    side: "ask_only" | "checkpoint_only" | "neither";
+}
+/**
+ * 三元组身份对得上、两侧摘要都在场却**不等** —— 唯一的真 mismatch。成因是**部署自伤**而非攻击
+ * ([2897]②:hook/policy 把自己仍持引用的活对象在两铸点之间改了,或每读返回新值的有状态 getter)。
+ * 处置 = 留痕不拒:计数 + 一条 warn,行照 ②③④⑤ 走(判据 1 不命中的既有 fail-safe 路径不变)。
+ */
+ | {
+    kind: "hash_mismatch";
+    candidates: number;
+}
+/** 三元组身份就对不上(不是摘要的事):别的 sourceTaskId / 别的 callId / 早于本 ask 的 park。 */
+ | {
+    kind: "identity_miss";
+};
+/**
+ * 这只 ask 是不是**祖先冻结 approver 层**在委派 fold 中途铸的那一份(#168 件1④,黑板 [2912]③)。
+ *
+ * 判别位是**产品自己发的**,不是外部约定:core 的 `withDelegationProvenance` 只包**子代自己那条缝**,
+ * 祖先层那次走未包装的原函数 ⇒ `AskRequest.delegation` 在不在,就是「这一份是哪一层发的」。落到行上,
+ * `delegation.parentToolCallId` 是必填字段,铸行时逐字透传进 `parent_tool_call_id` 列 ⇒ **列非 NULL
+ * ⇔ delegation 在场**(不需要新列,也不需要回 `req` 里再读一次)。
+ *
+ * 第二维 `sourceTaskId !== sessionId` 把「根腿」摘出去:根腿的 `sourceTaskId` 恒等于会话锚(core 给
+ * `AskRequest.sourceTaskId` 填的就是该腿 sessionId),它根本不在任何 fold 里,`parent_tool_call_id`
+ * 为 NULL 是它的常态而不是信号。
+ *
+ * 命中 ⇒ 退出硬相等(判据 1 结构上不命中,行落 ②③④⑤)。实测(test AI 围栏)checkpoint 存的摘要**逐字
+ * 等于子代自己那条缝**、只不等于祖先层那一次 —— 所以收窄到这一层,子代自己的缝照常参与。
+ */
+export declare function isAncestorFoldMint(ask: AskRow): boolean;
+/**
+ * 判据 1 的**硬谓词**(纯函数,§9 C2 + §8 D-2;#168 件1 起返回分类而不是布尔)。
+ *
+ * 逐条:
+ *  - 祖先层 fold 中途铸点 ⇒ 直接退出(见 {@link isAncestorFoldMint});
  *  - `unparseable` 候选直接出局(读不出 ⇒ 不确定 ⇒ 不命中);
- *  - `boundCallId` 必须逐字等于 `ask.toolCallId`(读口已按它查,这里是纵深防御);
- *  - **因果下界**:`cp.createdAtMs >= ask.createdAtMs`(park 不可能早于它要 park 的那次 ask);
- *  - **hash 双等**:两侧都必须在场且相等 —— 任一侧缺席即不命中(禁「能取到时才比」的可选谓词)。
+ *  - **身份三元组**:`sourceTaskId` **相等** ∧ `toolCallId` **相等** ∧ 时间维的**因果下界**
+ *    `candidate.createdAtMs >= ask.createdAtMs`(⚠️ 第三维**不是等式** —— 把它读成等式会让合法的 park
+ *    几乎命不中,行随后落 ②③⑤ 被误判)—— 摘要**不是**身份([2897]③①:
+ *    同 args 的两次调用摘要天然相同,只靠摘要硬相等会把第二次投递并进第一次的票);任一维在候选侧
+ *    缺席(读不出的 blob 没有 `sourceTaskId`)即身份不成立;
+ *  - **hash 双等**:两侧都必须在场且相等,任一侧缺席一律不 bind;禁「能取到时才比」的可选谓词。
+ *    归因分两级(顺序即代码顺序):身份这一层先判 —— 同身份候选为空**且**候选集非空 ⇒ `identity_miss`;
+ *    走到 hash 这一层才把缺席记成**单铸** `single_mint`(见 {@link GateMatchOutcome})。
  *
  * 多候选时的取舍:优先 `status === "pending"`(活着的那张 gate),否则取最早的一条(读口按
  * `created_at ASC` 返回)。两者都满足全部硬谓词,选谁都不会错配;取 pending 只是让 `PARKED` 行落到
  * 一个还能被 resume 的坐标上,对壳更有用。
  */
+export declare function classifyGateMatch(ask: AskRow, candidates: readonly CheckpointAskCandidate[]): GateMatchOutcome;
+/** {@link classifyGateMatch} 的布尔面(判据 1 命中即返回那条候选)。分类信息由调用方按需另取。 */
 export declare function selectGateCandidate(ask: AskRow, candidates: readonly CheckpointAskCandidate[]): CheckpointAskCandidate | undefined;
 /** 判据表 v2 的判定(纯函数;顺序 = 设计稿 §9 尾的五臂汇总,注见文件头)。 */
 export declare function decideReconcileAction(input: ReconcileInput): ReconcileAction;
@@ -105,13 +183,39 @@ export interface ReconcileStats {
      * 🔴 判据 1 **结构上无法命中**的行数(`bound_input_hash` 列为 NULL ⇒ 双等硬谓词永远不成立)。
      *
      * 存在理由(codex 交叉复审 C1,2026-08-06 验真):设计稿 §9 C2 的前提是「`AskRequest.boundInputHash`
-     * core 侧已在场」——**对树上的 core 5.13.0 不成立**:`AskRequest`(core/tool-policy.d.ts:78-90)没有这个
-     * 字段,铸行侧也就无值可存;唯一能算出同一摘要的 `boundInputHashOf`(core/canonical-json)既不在
-     * `index` 导出面也没有 subpath 出口。⇒ 在 core 供值之前,判据 1 恒不命中,PARKING 行只会落 ②③④⑤。
-     * 这个计数把「盲区」变成**可观测量**而不是静默行为(下面每 tick 一条 warn),也是协议开关翻真的前置
-     * 判据之一。
+     * core 侧已在场」——对**当时**树上的 core 5.13.0 不成立(`AskRequest` 没有这个字段,铸行侧无值可存),
+     * 于是判据 1 恒不命中、PARKING 行只会落 ②③④⑤。这个计数把那片盲区变成**可观测量**而不是静默行为
+     * (下面每 tick 一条 warn),并被写成协议开关翻真的前置判据之一。
+     *
+     * ✅ **该前置判据已销账**(#164 翻真验证车,2026-08-07 亲验 core 5.15.0):字段在
+     * `core/tool-policy.d.ts:83`,真码 `core/tool-policy.js:610` 每一只 ask 都填 ——
+     * 判据 1 现在会真命中(钉:test/stream-approval-on-e2e.test.ts 件4 末条,同构两行只差 hash 一位,
+     * 有 hash 的 bind 成 PARKED、无 hash 的进本计数)。
+     *
+     * 🔴 **本字段与它的 warn 都不删**:语义从「结构性盲区」变成「边缘异常」—— 翻真之后一条非零读数说明
+     * 有 ask 的铸行侧没拿到 hash(旧版 core 的存量行 / 回滚形 / 未来某条不经 `resolveAsk` 的新路径),
+     * 那正是运维需要当场看见的东西。恒零才是健康态,不是这条计数没用了。
      */
     unmatchableNoHash: number;
+    /**
+     * 🔴 判据 1 的**真** mismatch 行数(#168 件1③,黑板 [2897]②):三元组身份对得上、两侧摘要都在场却不等。
+     *
+     * 成因裁定 = **部署自伤,不是攻击**:core 已证在真正产生两次铸造的弧上摘要恒等,两条分歧路径都要求
+     * 部署自己交出活对象(hook/policy 返回己持引用后在两铸点之间突变;或每读返回新值的有状态 getter)。
+     * 所以处置是**留痕不拒**:计一笔 + 一条 warn,行照 ②③④⑤ 的既有 fail-safe 走 —— 判据 1 不命中本来
+     * 就不会产生终态 denial(约束②),这里不新增任何拒绝语义。
+     */
+    hashMismatch: number;
+    /**
+     * 单铸路径行数(#168 件1②)——**不计入** {@link hashMismatch}。三形分列:
+     *  `askOnly` 纯 sync / 再审批链;`checkpointOnly` durable-first 干净 args;`neither` 两侧都没铸。
+     *  它们都是**结构上只有一侧(或零侧)有摘要**,把它们读成「比过了、不匹配」是把没发生的事记成异常。
+     */
+    singleMintAskOnly: number;
+    singleMintCheckpointOnly: number;
+    singleMintNeither: number;
+    /** 祖先冻结 approver 层 fold 中途铸点(#168 件1④):退出硬相等,不是 mismatch 也不是单铸。 */
+    ancestorFoldMint: number;
     parked: number;
     denied: number;
     voided: number;