@sema-agent/server 7.10.0 → 7.12.0

package/dist/task-settings.js

@@ -78,6 +78,60 @@ export function withPermissionMode(settings, mode) {
     const base = settings ?? {};
     return { ...base, permissions: { ...base.permissions, defaultMode: mode } };
 }
+/**
+ * design/201 §6-1 —— 本请求的**生效** permission mode,单点。优先序逐字同 {@link withPermissionMode}:
+ * 顶层 `body.permissionMode`(本轮显式表态)赢过 bundle 的 `settings.permissions.defaultMode`;两处
+ * 都没有 ⇒ `undefined` = **无表态**(调用点据此不写键,而不是替调用方选一个默认值)。
+ *
+ * 🔴 为什么必须是一只函数:同一个「生效模式」此前在 resolve-spec 里被算了两次(hooks 腿的
+ * `permission_mode` 载荷、settings 折叠腿的 `withPermissionMode`),三审同点判定翻译表**不得**成为
+ * 第三个算点 —— 三处各算各的,任何一次优先序修订都会让三面分家,而分家在这条轴上的形态是
+ * 「壳发的 bundle bypass 在 A 面生效、在 B 面没生效」这种最难被外部发现的静默偏差。
+ */
+export function effectivePermissionMode(body, settings) {
+    return coercePermissionMode(body.permissionMode) ?? settings?.permissions?.defaultMode;
+}
+/**
+ * design/201 §2 —— 显式 permission mode → `TaskSpec.shellGate` 档位的**翻译表(单一真源)**。
+ *
+ *  · `bypassPermissions` ⇒ `"off"` —— CC `--dangerously-skip-permissions` 的对位裁定
+ *    (与 fs-write 面的 bypass 臂两面归一,见 {@link deriveSettingsPolicy})。
+ *  · `auto` ⇒ `"classify"` —— **design/201 §8 开口按施工期新披露亲裁改译**(原裁定字面是 off,
+ *    §8 保留「core auto 分类器覆盖面有新披露时可独立再裁,表驱动一行」——新披露见下段):
+ *
+ *    ⚠️ **`auto` 这一行有一条待裁的开口(design/201 §8 明列「core auto 分类器覆盖面有新披露时可独立再裁,
+ *    表驱动一行」)。施工期对抗复审给出了那条新披露,已亲读安装包核实**:
+ *      · core 只在**已经产生 `ask`** 之后才咨询分类器(`dist/core/hooks.js`:`if (input.autoMode &&
+ *        decision.action === "ask" …)`);
+ *      · 而 `shellGate:"off"` 下 core **不铸任何 shell 面的门**(`dist/core/runner/prepare-task.js` 的
+ *        `shellGate === "off"` 臂反而发一条 `classification:"shell-gate-off"` 的 onError:「真可写 Bash 挂着
+ *        却没有 shell 安全轴折叠」)。
+ *    两条合起来:`auto` × off ⇒ Bash 既不产 ask、分类器也就永不被咨询 —— off 档下「筛选权交给分类器」
+ *    不成立。故 auto 归 classify 组:分类器坐在 classify 产的 ask 之上,语义才真是「交给分类器」
+ *    (良性只读命令由分类器自动放行,其余 ask;这正是 auto 模式的本义)。发车帖向 [3378] 裁定链披露此
+ *    一行偏离;core auto 分类器若来日在 off 档下也有咨询点,可再裁回(表驱动一行)。
+ *  · `default` / `acceptEdits` / `plan` ⇒ `"classify"` —— 这一档原先由壳无条件注入 `MANUAL_MODE_SHELL_GATE`
+ *    供给(车道缺省走了 operator 通道),现在归位到表态轴。`plan` 本身 handsReadOnly(core 明写此档下
+ *    shellGate 无效),给它 classify 纯为一致性。
+ *
+ * 🔴 **入参非可选**:缺席(无表态)不是这张表的一行 —— 它的语义是「不写这个键」,只能在调用点判。
+ * 把它折进来会逼出一个 `undefined` 返回值,而那正是「写 off」与「不写」被混同的入口(core 的
+ * 缺席默认是 off,但**写**一个 off 会成为 governance 的 base,与缺席不是同一件事)。
+ *
+ * 🔴 **闭集 exhaustive switch,无 default 臂**:五个模式词是封闭词表,新增一个模式而不更新本表
+ * 是**编译错误**(#157 的安全轴纪律:词表的未知项不许有静默兜底臂)。
+ */
+export function shellGateForMode(effMode) {
+    switch (effMode) {
+        case "bypassPermissions":
+            return "off";
+        case "auto":
+        case "default":
+        case "acceptEdits":
+        case "plan":
+            return "classify";
+    }
+}
 /** Cap on `outputStyle` length — it lands in the system prompt, so it shares the `MAX_SYSTEM_PROMPT_CHARS` (16384)
  *  posture (an uncapped prompt body is a per-turn token-cost hole; adversarial review). Exported so the HTTP layer
  *  (prepareSpec) can 400 fail-loud on submit with the SAME bound this defensive parse enforces on every path. */
@@ -470,7 +524,9 @@ export function deriveSettingsPolicy(settings, gate, workflowGate) {
  * Returns `base` untouched when the parsed settings project nothing onto the spec.
  */
 // ([1557]§四 的 SHELL_GATE_RANK 副本与 shellGateSafe 守卫已随 #153 搬 runtime-governance ——
-// settings 折叠不再触碰 TaskSpec.shellGate,base 上 governance 层施加的值原样透传。)
+// settings 折叠不再触碰 TaskSpec.shellGate,base 上 governance 层施加的值原样透传。design/201 的
+// {@link shellGateForMode} 也不改这句话:那只纯函数产的是 governance 的 base,由 resolve-spec 阶段④
+// 写进 spec 字面量;本折叠拿到的 `base` 里可能因此已经带着一档 shellGate,而它照旧原样透传。)
 export function applyTaskSettings(base, settings, gate, workflowGate) {
     const { toolPolicy, handsReadOnly, enablePlanMode } = deriveSettingsPolicy(settings, gate, workflowGate);
     let next = base;

package/dist/tool-approval.d.ts

@@ -1,4 +1,5 @@
 import { type AskRequest, type AskOutcome } from "@sema-agent/core";
+import type { CardRulePersisted, RuleConsentLane } from "./rules-consent.js";
 import { type ApprovalRequestFrame, type ApprovalRevokeFrame } from "./approval-card.js";
 import type { ApprovalAskStore } from "./plugins/approval-ask-store-sql.js";
 import { type GovernanceAskMarks } from "./governance-ask-marks.js";
@@ -60,6 +61,21 @@ export interface ToolApprovalFrame {
      * `governance-ask-marks.ts` 顶注。
      */
     governanceForced?: true;
+    /**
+     * #154 车二(core 5.18.0 design/179):`"tool_approval"` only —— 引擎为这次 ask 铸的**规则候选**
+     * (`AskRequest.ruleSuggestions`,逐字透传:闭词表 `match` + 引擎铸的文本,server 不重铸不重排)。
+     * 壳据它渲「不再询问」,回决时用 `persistRule.rule` 报出选中的那一条。
+     *
+     * 🔴 **在场性即承诺**:只在**规则店真装配**(协调器拿到 `ruleConsent`,与 core 的
+     * `RunnerDeps.permissionRuleStore` 同源于 main.ts 的同一个对象 ⇒ 与 manifest 的
+     * `permissionRules.storeWired` 不可能相左)时在场。店缺席仍投 = 一格按下去无处可兑的「不再询问」,
+     * 是 wire 谎言(判据逐字见 `trace/core-keyset-guard.ts` ④ 面本键那一段)。
+     */
+    ruleSuggestions?: ReadonlyArray<{
+        rule: string;
+        match: "exact" | "prefix";
+        command: string;
+    }>;
     /** "tool_approval" only: the tool call's args, secret-redacted, UNTRUSTED-for-display. Absent (with
      *  `argsOmitted: true`) when over the byte cap or unserializable. */
     args?: unknown;
@@ -119,11 +135,29 @@ export interface ToolApprovalRunContext {
     legDeadlineMonotonic?: number;
 }
 export type ToolApprovalDecision = "allow" | "allow_session" | "deny";
+/**
+ * #154 车二:回决回执上 `ruleRefusal` 的**闭词表**(「不再询问」这次为什么没存上)。
+ *
+ * 🔴 为什么是闭集而不是 `string`(#157 词表纪律):这一格是 wire 可见的**机器可读**位 —— 壳要据它分
+ * 「这次不能存」(`rule_input_edited`:编辑过输入,换下一次)与「这台部署压根不供规则」
+ * (`rule_lane_unavailable`)。自由串会让每个消费端各自猜词,而 server 加一个新拒绝理由时没人会红。
+ * 三格 server 自铸 + 车道自己的四格(`CardRulePersisted["reason"]`,从那个类型**派生**而不是抄):
+ * 车道加员 ⇒ 这里编译期自动跟。
+ */
+export type RuleRefusalReason = Extract<CardRulePersisted, {
+    ok: false;
+}>["reason"] | "rule_lane_unavailable" | "rule_input_edited" | "rule_not_offered" | "rule_store_error"
+/** #204 件7:这只 ask 的门来自运维治理层(`governanceForced`)⇒ 它不进规则车道。**与
+ *  `rule_lane_unavailable` 刻意分词**:那个说的是「这台部署压根不供规则」(壳可以从此不渲这一格),
+ *  这个说的是「规则车道好好的,只是**这一只** ask 归 operator 管」—— 折成同一个词会让壳把一台正常
+ *  部署整条车道判死。 */
+ | "rule_governance_forced";
 /** Validate the respond body — the closed three-choice enum (rationale in the module header). */
 export declare function parseToolApprovalResponse(body: unknown): {
     ok: true;
     value: ToolApprovalDecision;
     updatedInput?: unknown;
+    persistRule?: string;
 } | {
     ok: false;
     error: string;
@@ -310,6 +344,10 @@ export declare class ToolApprovalCoordinator {
      *  缺席(生产形)⇒ 每条 run 腿由 {@link runWithContext} 现铸一张、经 ALS 与写侧共享;在场 ⇒ 测试注入的
      *  固定表(此时不进 ALS 作用域,读写都走这一张)。作用域理由见 `governance-ask-marks.ts` 顶注。 */
     private readonly governanceAskMarks;
+    /** #154 车二:持久化权限规则的**同意车道**。在场 ⇔ 规则店真装配(main.ts 与 core 的
+     *  `RunnerDeps.permissionRuleStore` 同源于一个对象)⇒ ①ask 帧投 `ruleSuggestions`;②回决带
+     *  `persistRule` 时兑付进店。缺席 ⇒ 两件都不做(诚实缺席,不发无处可兑的候选)。 */
+    private readonly ruleConsent;
     constructor(opts?: {
         ttlMs?: number;
         askStore?: ApprovalAskStore;
@@ -318,6 +356,8 @@ export declare class ToolApprovalCoordinator {
         admitMaxPerOwner?: number;
         /** 缺省 = 进程级单表(写侧默认同一张)。注入口只为测试与将来的多实例形。 */
         governanceAskMarks?: GovernanceAskMarks;
+        /** #154 车二:同意车道(在场 = 规则店已装配)。 */
+        ruleConsent?: RuleConsentLane;
     });
     /**
      * #151 车3 刀 3b —— design/172 §3.3 / 设计稿 §0 X-2 的**写侧准入门**。
@@ -339,6 +379,14 @@ export declare class ToolApprovalCoordinator {
      * 多副本级的总量控制登记为后续件(汇报存疑单)。
      */
     private admit;
+    /**
+     * #154 车二:一只 ask 的**规则车道素材**,或 `undefined`(= 本 ask 不投候选、不接受 `persistRule`)。
+     *
+     * 三个合取项(缺一即 `undefined`,理由逐字见调用点上方注):①店在场 ②引擎铸了候选 ③命令原字节可读。
+     * `req.args` 是 `unknown` ⇒ 窄读,**禁裸 as-cast**(宪法 [2704]:一个形状漂了的 args 若被 cast,
+     * 会把 `undefined` 当命令送进 `prepareCardApproval`,那是放宽面上的静默垃圾)。
+     */
+    private buildRuleLaneMaterial;
     /** 测试/可观测性钩子(X-2):某 (taskId) 维当前占用的准入名额数。 */
     admittedCount(taskId: string): number;
     /** #151 车2(D5 store 故障姿势):任何 store 调用 throw ⇒ fail-open 到进程内机械照旧(store 是记账/
@@ -466,6 +514,18 @@ export declare class ToolApprovalCoordinator {
         status: number;
         body: unknown;
     }>;
+    /**
+     * #154 车二:回决携规则确认 ⇒ prepare→confirm→redeem(实现在 `rules-consent.ts`,本方法只做门与回显)。
+     *
+     * 三道门,每道都是**拒绝**而不是降级:
+     *  ① 裁决必须真落定(200)—— 见调用点注;
+     *  ② 必须有已验明的 owner —— 规则是**某个人**的持久同意,一条 `owner === null` 的 ask 没有归属人可写;
+     *  ③ 本 ask 必须登记过规则车道素材(店在场 ∧ 引擎铸过候选 ∧ 命令可读)。
+     *
+     * 失败**不翻转裁决**:人的「允许这次」已经生效并且已经交给引擎了,把整个回决改判成 4xx 会让一次真实的
+     * 放行凭空消失。诚实的形是 200 + `rulePersisted:false`(壳据它告诉人「这次放行了,但『不再询问』没存上」)。
+     */
+    private persistRuleAfterDecision;
     /** store 在场时的回决 CAS 门(D2)——`respond()` 的异步分支,拆出以保持 `respond()` 本身在 store 缺席
      *  时仍是纯同步函数(D1)。`askStore`/`askId`/`batchId` 由调用方在已窄化的分支里传入(避免非空断言）。 */
     private respondWithCas;

package/dist/tool-approval.js

@@ -44,7 +44,7 @@
  * and asks are turn-blocking by construction — the TTL bounds the human-side exposure instead.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
-import { uuidv7 } from "@sema-agent/core";
+import { uuidv7, MAX_RULE_TEXT_CHARS } from "@sema-agent/core";
 import { redactDeep, redactSecrets } from "./trace/redact.js";
 import { createLogger } from "./observability/logger.js";
 import { deriveAskId, deriveBatchId } from "./approval-ask-machine.js";
@@ -145,7 +145,21 @@ export function parseToolApprovalResponse(body) {
         // [1458] ctrl+g 编辑放行:allow 族可带 updatedInput(编辑后的 args 整体替换形,durable /decide 腿
         // 同名位既有语义);deny 带=无意义,忽略不 400(宽收)。
         const u = body.updatedInput;
-        return { ok: true, value: d, ...(d !== "deny" && u !== undefined ? { updatedInput: u } : {}) };
+        // #154 车二:「不再询问」的回决位。**只带候选的文本**,不是自由规则 —— 服务端拿它在引擎铸出的
+        // 候选表里定位下标(对不上就拒),于是「点一次某条无害命令换来一条别的规则」在这条路上不可拼写。
+        // deny 带 = 无意义(人拒了这次操作,谈不上持久化同意),忽略不 400(同 updatedInput 的宽收姿势)。
+        const pr = body.persistRule;
+        let persistRule;
+        if (d !== "deny" && pr !== undefined) {
+            if (pr === null || typeof pr !== "object" || Array.isArray(pr))
+                return { ok: false, error: "persistRule must be an object" };
+            const rule = pr.rule;
+            if (typeof rule !== "string" || rule === "" || rule.length > MAX_RULE_TEXT_CHARS) {
+                return { ok: false, error: `persistRule.rule must be a non-empty string of at most ${MAX_RULE_TEXT_CHARS} characters` };
+            }
+            persistRule = rule;
+        }
+        return { ok: true, value: d, ...(d !== "deny" && u !== undefined ? { updatedInput: u } : {}), ...(persistRule !== undefined ? { persistRule } : {}) };
     }
     return { ok: false, error: 'decision must be one of "allow" | "allow_session" | "deny"' };
 }
@@ -349,7 +363,12 @@ export class ToolApprovalCoordinator {
      *  缺席(生产形)⇒ 每条 run 腿由 {@link runWithContext} 现铸一张、经 ALS 与写侧共享;在场 ⇒ 测试注入的
      *  固定表(此时不进 ALS 作用域,读写都走这一张)。作用域理由见 `governance-ask-marks.ts` 顶注。 */
     governanceAskMarks;
+    /** #154 车二:持久化权限规则的**同意车道**。在场 ⇔ 规则店真装配(main.ts 与 core 的
+     *  `RunnerDeps.permissionRuleStore` 同源于一个对象)⇒ ①ask 帧投 `ruleSuggestions`;②回决带
+     *  `persistRule` 时兑付进店。缺席 ⇒ 两件都不做(诚实缺席,不发无处可兑的候选)。 */
+    ruleConsent;
     constructor(opts) {
+        this.ruleConsent = opts?.ruleConsent;
         this.governanceAskMarks = opts?.governanceAskMarks;
         this.ttlMs = opts?.ttlMs ?? DEFAULT_APPROVAL_TTL_MS;
         this.askStore = opts?.askStore;
@@ -404,6 +423,49 @@ export class ToolApprovalCoordinator {
                 this.admitByOwner.set(ownerKey, o);
         };
     }
+    /**
+     * #154 车二:一只 ask 的**规则车道素材**,或 `undefined`(= 本 ask 不投候选、不接受 `persistRule`)。
+     *
+     * 三个合取项(缺一即 `undefined`,理由逐字见调用点上方注):①店在场 ②引擎铸了候选 ③命令原字节可读。
+     * `req.args` 是 `unknown` ⇒ 窄读,**禁裸 as-cast**(宪法 [2704]:一个形状漂了的 args 若被 cast,
+     * 会把 `undefined` 当命令送进 `prepareCardApproval`,那是放宽面上的静默垃圾)。
+     */
+    buildRuleLaneMaterial(req, owner, governanceForced) {
+        if (this.ruleConsent === undefined)
+            return undefined;
+        // 🔴 **治理档的 ask 不进规则车道**(#204 件7)。`governanceForced` 的语义(wire 契约逐字)是「这只
+        // ask 的门来自运维治理层,客户端表态掀不掉」;而一条持久规则会让引擎侧的规则命中臂短路掉后续
+        // **同命令**的 ask(core `hooks.js` 只排除 `decisionReason === "hook"` 与 `requiresRealApproval`),
+        // 于是一次「不再询问」= 静默拆掉 operator 的档位,且拆完之后遥测里连 ask 都不再出现。
+        // 与下面 `owner === null` 同族:这是**铸侧第一道门**,回决那侧 `persistRuleAfterDecision` 有同源的
+        // 第二道(拒因 `rule_governance_forced`)。两侧同源的理由见那一行。
+        if (governanceForced)
+            return undefined;
+        // 🔴 **归属人也是合取项**(codex 对抗复审 R1-F1,#203,验真后修)。这一条与回决那侧
+        // `persistRuleAfterDecision` 的第二道门(`owner === null ⇒ rule_lane_unavailable`)**同源** ——
+        // 一条规则是「**某个人**的持久同意」,没有人就没有桶可写。两侧不同源时的后果不是多问一次,而是
+        // 一张卡上渲出一格按下去恒被拒的「不再询问」= 本域顶注自己定义的 wire 谎言。
+        // 它在 #203 之前碰不到:local 车道没有规则店 ⇒ 上一行就返回了;本车给 local 接上 File 店之后,
+        // 「单机 + 无 principal」的部署第一次同时满足其余三项。
+        if (owner === null)
+            return undefined;
+        const suggestions = req.ruleSuggestions;
+        if (!Array.isArray(suggestions) || suggestions.length === 0)
+            return undefined;
+        const args = req.args;
+        if (args === null || typeof args !== "object" || Array.isArray(args))
+            return undefined;
+        const command = args.command;
+        if (typeof command !== "string" || command === "")
+            return undefined;
+        const boundInputHash = readBoundInputHash(req);
+        return {
+            command,
+            suggestions,
+            ...(typeof req.toolCallId === "string" && req.toolCallId !== "" ? { toolCallId: req.toolCallId } : {}),
+            ...(boundInputHash !== null ? { boundInputHash } : {}),
+        };
+    }
     /** 测试/可观测性钩子(X-2):某 (taskId) 维当前占用的准入名额数。 */
     admittedCount(taskId) {
         return this.admitByTask.get(taskId) ?? 0;
@@ -704,6 +766,24 @@ export class ToolApprovalCoordinator {
         const id = uuidv7();
         const child = isChildAsk(req);
         const bounded = boundArgs(req.args);
+        // [2942]/[2943]:治理来源标的**一次** peek(非消费式)。此前它只在下面的帧字面量里就地读 ——
+        // #204 件7 起规则车道也要它(治理档的 ask 不进车道),两处读同一个值必须是**同一次** peek:
+        // 分开读会让「帧说这是治理门 / 车道说不是」这种自相矛盾的卡在理论上存在。
+        const governanceForced = (this.governanceAskMarks ?? governanceAskMarksFor(this.streamKey(primary.owner, primary.sessionId, origin.taskId))).isMarked(req.toolCallId);
+        // 🔴 **规则车道用的是本地 peek 与持久行的并集**(#204 件7,codex 对抗复审 R1-中,验真后修)。
+        // 本地表是进程内的:failover / 重启后幂等命中一条既有行时它恒空,而行上的卡里存着落库那一刻的判定。
+        // 下面 `ensureAsk` 的对账段按「行 = 真源」同步**帧上**那个键(那是出处属性,行说了算);但规则车道
+        // 是一次**放宽**动作,它的合成必须 fail-closed —— 任一侧说「治理门」就不进车道。只同步帧键会留下
+        // 一张「说是治理门却仍带 ruleSuggestions」的卡,且回决侧第二道门跟着没武装。
+        let effectiveGovernanceForced = governanceForced;
+        // #154 车二:规则候选的投影素材。**四个合取项**,缺一不投:
+        //  ① 规则店真装配(`this.ruleConsent` 在场)—— 店缺席仍投 = 无处可兑的「不再询问」= wire 谎言;
+        //  ② 这只 ask 不是治理档产的(#204 件7)—— 治理门上铸规则 = 静默拆掉 operator 档位;
+        //  ③ 引擎真铸了候选(`req.ruleSuggestions` 非空)—— 命令不可匹配(复合/重定向/替换)时 core 交空数组;
+        //  ④ 命令原字节读得出(回决时**引擎**要拿它重铸候选;读不出就没有可兑付的路,投候选等于骗人)。
+        // 读 `req.args.command` 走窄读:`args` 是 `unknown`,禁裸 as-cast(宪法 [2704])。
+        // `let`:上面那条并集裁定可能在对账后把它撤回 undefined(行说这是治理门)。
+        let ruleLaneMaterial = this.buildRuleLaneMaterial(req, primary.owner, governanceForced);
         const frame = {
             type: "tool_approval",
             approvalId: id,
@@ -732,10 +812,10 @@ export class ToolApprovalCoordinator {
                 : {}),
             message: typeof req.message === "string" ? redactDeep(req.message) : "",
             // [2942]/[2943]:治理来源标(additive,只在为真时在场——缺席绝不编 false,见字段顶注)。
-            // 读的是**非消费式** peek:同一 toolCallId 的重播/failover 再入必须拿到同一份判定。
-            ...((this.governanceAskMarks ?? governanceAskMarksFor(this.streamKey(primary.owner, primary.sessionId, origin.taskId))).isMarked(req.toolCallId)
-                ? { governanceForced: true }
-                : {}),
+            // 值来自上方那一次**非消费式** peek(同一 toolCallId 的重播/failover 再入必须拿到同一份判定)。
+            ...(governanceForced ? { governanceForced: true } : {}),
+            // #154 车二:候选逐字透传(条件见 `ruleLaneMaterial` 上方注)。
+            ...(ruleLaneMaterial !== undefined ? { ruleSuggestions: ruleLaneMaterial.suggestions } : {}),
             ...(bounded.omitted ? { argsOmitted: true } : { args: bounded.args }),
         };
         // #151 车2(design/172 §3.3 D3 窗长三元):有效窗——legDeadlineMonotonic 缺席时退化成 ttlMs(D1 零
@@ -898,6 +978,22 @@ export class ToolApprovalCoordinator {
                     frame.governanceForced = true;
                 else
                     delete frame.governanceForced;
+                // 🔴 #204 件7(codex 对抗复审 R1-中,验真后修):行说这是治理门 ⇒ **规则车道当场撤回**。
+                // 上面那行只同步了帧上的出处键;素材、两族帧上的候选、以及回决侧第二道门的输入都还是按**本地**
+                // 表算的,而本地表在 failover / 重启后恒空。不撤就正是本件要防的形:一张卡同时带着
+                // `governanceForced:true` 与 `ruleSuggestions`,回决口还照收 —— operator 档位被一次点击拆掉。
+                // 撤三处(缺一即漏):①旧帧的候选键;②呈卡帧读的**持久卡**上的同名键(它来自行,不是本地铸的);
+                // ③素材本身(它是下面 `pendingEntry.ruleLane` 的唯一来源,也就是回决口的等式左边)。
+                // 反向(行说不是治理门、本地表说是)**刻意不放开**:见上方并集裁定 —— 少渲一格是安全方向。
+                if (cardForFrame.governanceForced === true && !effectiveGovernanceForced) {
+                    effectiveGovernanceForced = true;
+                    ruleLaneMaterial = undefined;
+                    delete frame.ruleSuggestions;
+                    if (cardForFrame.ruleSuggestions !== undefined) {
+                        const { ruleSuggestions: _dropped, ...rest } = cardForFrame;
+                        cardForFrame = rest;
+                    }
+                }
             }
             catch (err) {
                 this.noteStoreError(err, "ensureAsk");
@@ -975,10 +1071,34 @@ export class ToolApprovalCoordinator {
         // 稍后才赋值的引用格(鸡生蛋:settle 是 pendingEntry 的一个字段,pendingEntry 建好之后才能把它自己
         // 塞进这个引用里)。
         let selfEntry;
-        const settle = (allowed, outcome, updatedInput) => {
+        // core 5.23.0(#187/#114②):本次结算的**宿主自报来源**(见 {@link HostSettledBy})。
+        // 🔴 记在 `settle` 的 **done 卫兵之内**,不是在调用点旁边立一个标志:窗到期的臂是「先算、后 settle」,
+        // 而 `settle` 可能因为人已经答过了而整个是空操作 —— 标志式写法会在那种赛跑里给一个**人类的**终局盖上
+        // 「窗到期」的章。只有真正落定这次终局的那一次调用才有资格留下自报词。
+        let hostSettled;
+        /**
+         * 已落定的本地终局 → `AskOutcome` 的**唯一**成形口。本方法有两个出口(方法尾的正常路,与
+         * `earlyAbortDuringEnsure` 的早退路),它们此前各写了一份等价分派 —— 结果就是本批的 `settledBy`
+         * 只加到了一份上(codex 复审 round2 抓获)。合成一个函数,判据只写一次。
+         *  · `windowRouteUnavailable` ⇒ park 路由(持久终局是 PARKING/PARKED,压过一切);
+         *  · allow + 编辑 ⇒ 对象臂带 `updatedInput`;
+         *  · deny + 宿主自报 ⇒ 对象臂带 `settledBy`(见 {@link HostSettledBy};allow 侧恒不带 —— core 对
+         *    `{allow:true, settledBy:"timeout"}` 是响亮拒,而自报只在 deny 分支产生);
+         *  · 其余 ⇒ 裸 boolean(falsy 纪律)。
+         */
+        const shapeOutcome = (settled) => {
+            if (windowRouteUnavailable)
+                return "unavailable";
+            if (settled.allowed) {
+                return settled.updatedInput !== undefined ? { allow: true, updatedInput: settled.updatedInput } : true;
+            }
+            return hostSettled !== undefined ? { allow: false, settledBy: hostSettled } : false;
+        };
+        const settle = (allowed, outcome, updatedInput, hostSettledBy) => {
             if (done)
                 return;
             done = true;
+            hostSettled = hostSettledBy;
             if (timer)
                 clearTimeout(timer);
             for (const [sig, fn] of abortListeners)
@@ -1069,7 +1189,9 @@ export class ToolApprovalCoordinator {
         const windowExpired = () => {
             void (async () => {
                 if (!this.askStore || askId === undefined || batchId === undefined) {
-                    settle(false, "expired");
+                    // D1(无持久 ask 店)——终局**完全**由本仓这个窗决定,没有第二个写者。core 5.23.0 起如实自报
+                    // `"timeout"`:这条腿的窗归宿主,引擎观察不到它走完,不说就被记成「一个人拒绝了」。
+                    settle(false, "expired", undefined, "timeout");
                     return;
                 }
                 try {
@@ -1103,7 +1225,10 @@ export class ToolApprovalCoordinator {
                     // 两种结局都成立:真提交了 ⇒ 与行一致;没提交 ⇒ core 自己走 durable park,不劣于 deny。
                     if (err instanceof ApprovalStoreDeadlineError)
                         windowRouteUnavailable = true;
-                    settle(false, "expired"); // fail-open(D5):店抖动不挡窗到期的进程内机械照旧完成
+                    // fail-open(D5):店抖动不挡窗到期的进程内机械照旧完成。自报仍是 `"timeout"` 且如实 —— 结束这次
+                    // 等待的**确实**是本仓的窗(店只是没能给出更精确的终局);deadline 那一支已经改判 park 路由,
+                    // 走不到用得上这个词的返回臂。
+                    settle(false, "expired", undefined, "timeout");
                 }
             })();
         };
@@ -1217,12 +1342,11 @@ export class ToolApprovalCoordinator {
             // `done` 为真而落定值是 `true`,写死 false 会把一次真实的人类批准悄悄吞成拒绝(且与 durable 行矛盾)。
             // 改成把**已经落定的那个值**如实交回去(与方法尾部的返回值分派同一套判据)。
             if (done) {
-                const early = await allowedP;
-                if (windowRouteUnavailable)
-                    return "unavailable"; // 持久终局是 PARKING/PARKED ⇒ park 路由
-                if (early.allowed && early.updatedInput !== undefined)
-                    return { allow: true, updatedInput: early.updatedInput };
-                return early.allowed;
+                // 🔴 [3372] codex 复审 round2(验真后修):这里**曾经**是尾部那套分派的手抄第二份,于是本批给
+                // 窗到期加的 `settledBy` 自报只进了尾部、没进这里 —— 「窗先落定、取消臂随后才走完」的交错里,
+                // 一个由**窗**决定的终局从这个出口以裸 `false` 溜出去,core 照旧记成人类拒绝。两个出口现在共用
+                // {@link shapeOutcome} 这**一个**成形函数,结构上不可能再分家(红先钉:codex-R2-2)。
+                return shapeOutcome(await allowedP);
             }
         }
         // Register BEFORE emitting so a (fast) respond can never miss the entry. 子代 ask 的生存期挂子代
@@ -1237,6 +1361,12 @@ export class ToolApprovalCoordinator {
             ...(child ? { originTaskId: req.sourceTaskId } : { targetCtxs: new Set(aliveCtxs), onTargetGone }),
             ...(primary.sessionId ? { sessionId: primary.sessionId } : {}),
             toolName: req.toolName,
+            // #154 车二:规则车道素材 —— 与帧上的 `ruleSuggestions` **同一个条件**(店在场 ∧ 非治理档 ∧ 引擎真
+            // 铸了候选 ∧ 命令原字节读得出)。任一不成立 ⇒ 不登记,回决带 `persistRule` 时如实拒(不猜命令)。
+            ...(ruleLaneMaterial !== undefined ? { ruleLane: ruleLaneMaterial } : {}),
+            // #204 件7:治理标随条目落定(回决侧第二道门的输入,理由见字段顶注)。读的是**并集后**的值
+            // (`effectiveGovernanceForced`),不是本地 peek —— 幂等命中既有行那条路上,只有并集才是武装的。
+            ...(effectiveGovernanceForced ? { governanceForced: true } : {}),
             ...(askId !== undefined && batchId !== undefined ? { askId, batchId } : {}),
         };
         selfEntry = pendingEntry; // 供 settle() 结算时把自己从 pendingByAskId 的 Set 里摘除(上方顶注)
@@ -1391,13 +1521,12 @@ export class ToolApprovalCoordinator {
         // 方法顶注。
         if (!emitSettled && lastOutcome === "expired")
             return "unavailable";
-        // [1458] 编辑放行对象臂:core AskOutcome 公开类型已含 `{allow, updatedInput?}`([1462])——
-        // 宽铸退役,真类型直返(core BAGGAGE #17 严格化前提=对象臂 allow 恒严格 true,我方满足)。
-        // deny 恒返 false(falsy 纪律)。
-        if (settled.allowed && settled.updatedInput !== undefined) {
-            return { allow: true, updatedInput: settled.updatedInput };
-        }
-        return settled.allowed;
+        // [1458] 编辑放行对象臂 + core 5.23.0(#187/#114②)宿主自报臂 —— 两条判据都在
+        // {@link shapeOutcome} 里,与早退出口**共用同一份**(codex 复审 round2:此前这里与早退臂各写一份
+        // 等价分派,本批的 `settledBy` 于是只加到了其中一份上)。
+        // 到得了这里说明卡**确实送达过**(emit 全灭 / park 路由两条早就 return 掉了),所以自报的「窗到期」
+        // 是这次等待的真实结局,而不是「没人可送」。
+        return shapeOutcome(settled);
     }
     /** `POST /v1/tool-approvals/:id/respond` — settle a parked approval with the shell's decision. Owner-gated with a
      *  404 (no existence oracle), body validated first (400 is existence-independent) — question/steer parity. The HTTP
@@ -1418,10 +1547,79 @@ export class ToolApprovalCoordinator {
         // #151 车2 D2(回决竞争者):askStore 缺席 ⇒ finishRespond 同步收尾,逐字不变(D1)。在场 ⇒ 先打一把
         // decideAsk CAS,赢了才 finishRespond;输(某个其他竞争者已经决定了这只 ask 的终局)⇒ 不 settle,照旧
         // 回现有 404 形(响应体的 409/410 分化是车4 的活,本车只保证「输者绝不覆盖赢者」)。
-        if (this.askStore && entry.askId !== undefined && entry.batchId !== undefined) {
-            return this.respondWithCas(this.askStore, entry.askId, entry.batchId, id, entry, parsed);
+        const settled = this.askStore && entry.askId !== undefined && entry.batchId !== undefined
+            ? this.respondWithCas(this.askStore, entry.askId, entry.batchId, id, entry, parsed)
+            : this.finishRespond(id, entry, parsed);
+        // #154 车二:「不再询问」的兑付口。**在裁决落定之后**(顺序是硬的:规则是「这次同意的持久化」,
+        // 一次没有生效的裁决不该留下一条永久规则),且只在 200 那一支 —— 404(CAS 输/条目已被别人结算)
+        // 意味着这次回决不是有效终局,连带的规则确认也就不成立。
+        if (parsed.persistRule === undefined)
+            return settled;
+        return this.persistRuleAfterDecision(settled, entry, parsed.persistRule, parsed.updatedInput !== undefined);
+    }
+    /**
+     * #154 车二:回决携规则确认 ⇒ prepare→confirm→redeem(实现在 `rules-consent.ts`,本方法只做门与回显)。
+     *
+     * 三道门,每道都是**拒绝**而不是降级:
+     *  ① 裁决必须真落定(200)—— 见调用点注;
+     *  ② 必须有已验明的 owner —— 规则是**某个人**的持久同意,一条 `owner === null` 的 ask 没有归属人可写;
+     *  ③ 本 ask 必须登记过规则车道素材(店在场 ∧ 引擎铸过候选 ∧ 命令可读)。
+     *
+     * 失败**不翻转裁决**:人的「允许这次」已经生效并且已经交给引擎了,把整个回决改判成 4xx 会让一次真实的
+     * 放行凭空消失。诚实的形是 200 + `rulePersisted:false`(壳据它告诉人「这次放行了,但『不再询问』没存上」)。
+     */
+    async persistRuleAfterDecision(settled, entry, ruleText, inputWasEdited) {
+        const result = await settled;
+        if (result.status !== 200)
+            return result;
+        const lane = this.ruleConsent;
+        const material = entry.ruleLane;
+        const owner = entry.owner;
+        const withFlag = (rulePersisted, ruleRefusal) => ({
+            status: result.status,
+            body: { ...result.body, rulePersisted, ...(ruleRefusal !== undefined ? { ruleRefusal } : {}) },
+        });
+        // 🔴 **治理档第二道门**(#204 件7),排在 `rule_lane_unavailable` 那道**之前**:两道门都会命中一只
+        // 治理 ask(铸侧不登记素材 ⇒ `material === undefined`),但回给壳的词必须是精确的那一个 ——
+        // `rule_lane_unavailable` 意为「这台部署压根不供规则」,壳据它可以从此不渲这一格,而这里的真相是
+        // 「车道好好的,只是**这一只** ask 归 operator 管」。与铸侧 `buildRuleLaneMaterial` 的同源门成对:
+        // 少了这一道,一次回滚/旧壳(或将来某条不经铸侧登记的回决路径)就能把 operator 档位绕过去。
+        if (entry.governanceForced === true)
+            return withFlag(false, "rule_governance_forced");
+        if (lane === undefined || material === undefined || owner === null)
+            return withFlag(false, "rule_lane_unavailable");
+        // 🔴 codex 交叉复审 round3 [high] 二(验真后修,**真扩权面**):`updatedInput`(ctrl+g 编辑放行)
+        // 与 `persistRule` 同时在场时,**生效的**调用是编辑后的那一份,而候选是引擎从**原始**命令铸的 ——
+        // 于是「把一条危险命令改安全 + 勾上不再询问」会给原始那条危险命令装上一条常驻放行规则。
+        // v1 处置 = **拒绝这次持久化**(裁决本身照常生效;人只是这一次没能顺手存下规则)。
+        // 不选「从编辑后的输入重铸候选」:`updatedInput` 是 `unknown` 的整体替换形,它与这只 ask 上引擎
+        // 铸的候选之间没有任何等式可对 —— 那条路要先给编辑面立形,是另一件事(登记为后续件)。
+        if (inputWasEdited)
+            return withFlag(false, "rule_input_edited");
+        // 报出的文本必须**在引擎铸的候选里**(等式一道)。对不上 ⇒ 拒,不猜:一条不在候选里的文本要么是
+        // 旧卡的残留,要么是有人在试着自铸规则,两种都不该落库。
+        if (!material.suggestions.some((s) => s.rule === ruleText))
+            return withFlag(false, "rule_not_offered");
+        try {
+            const persisted = await lane.persistCardRule({
+                principal: owner,
+                toolName: entry.toolName,
+                command: material.command,
+                ruleText,
+                ...(material.toolCallId !== undefined ? { toolCallId: material.toolCallId } : {}),
+                ...(material.boundInputHash !== undefined ? { boundInputHash: material.boundInputHash } : {}),
+            });
+            if (!persisted.ok) {
+                defaultLogger.warn("permission rule was not persisted after an approval", { reason: persisted.reason, detail: persisted.detail });
+                return withFlag(false, persisted.reason);
+            }
+            return withFlag(true);
+        }
+        catch (err) {
+            // D5 同族姿势:店抖动不改判人的裁决,只如实报「没存上」。
+            this.noteStoreError(err, "persistCardRule");
+            return withFlag(false, "rule_store_error");
         }
-        return this.finishRespond(id, entry, parsed);
     }
     /** store 在场时的回决 CAS 门(D2)——`respond()` 的异步分支,拆出以保持 `respond()` 本身在 store 缺席
      *  时仍是纯同步函数(D1)。`askStore`/`askId`/`batchId` 由调用方在已窄化的分支里传入(避免非空断言）。 */

package/dist/trace/core-keyset-guard.d.ts

@@ -15,7 +15,7 @@
  * 维护:core 新键到来时,transparently 透传的加进对应 PROJECTED 并去实现投影;有意不上 wire 的加进
  * EXCLUDED 并写一行理由。谁改投影(project.ts / fleet-bus.ts / roster-store-sql.ts)谁同步本文件。
  */
-import type { TaskNotificationPayload, BackgroundChildEvent, RosterEntry, AskRequest, TaskEvent, MailboxMessage, MailboxStore } from "@sema-agent/core";
+import type { TaskNotificationPayload, BackgroundChildEvent, RosterEntry, AskRequest, TaskEvent, TraceEvent, MailboxMessage, MailboxStore } from "@sema-agent/core";
 /** 编译期断言:T 必须收敛到 never(有残余键 = tsc 红)。 */
 type AssertAllKeysHandled<T extends never> = T;
 type NotificationProjected = "task_id" | "task_type" | "toolUseId" | "status" | "summary" | "result" | "output_file" | "usage" | "sessionId" | "seq" | "lines" | "stoppedBy" | "source" | "exitCode" | "partial" | "diagnostics" | "recentSteps" | "editedFiles" | "resumable" | "completionId" | "error" | "errorCode";
@@ -26,8 +26,8 @@ type BgNotifExcluded = "kind" | "sessionScoped" | "owner" | "scope" | "descripti
 type _GuardBgNotif = AssertAllKeysHandled<Exclude<keyof BackgroundChildEvent, BgNotifProjected | BgNotifExcluded>>;
 type RosterProjected = "name" | "agentId" | "sessionId" | "toolUseId" | "owner" | "scope" | "sessionScoped" | "rootSessionId" | "model" | "modelFallback" | "createdAt";
 type _GuardRoster = AssertAllKeysHandled<Exclude<keyof RosterEntry, RosterProjected>>;
-type AskProjected = "toolName" | "toolCallId" | "args" | "message" | "sourceTaskId" | "fromSubagent" | "sourceAgentName" | "delegation";
-type AskExcluded = "preview" | "principal" | "requiresRealApproval" | "riskAxes" | "boundInputHash" | "ruleSuggestions";
+type AskProjected = "toolName" | "toolCallId" | "args" | "message" | "sourceTaskId" | "fromSubagent" | "sourceAgentName" | "delegation" | "ruleSuggestions";
+type AskExcluded = "preview" | "principal" | "requiresRealApproval" | "riskAxes" | "boundInputHash";
 type _GuardAsk = AssertAllKeysHandled<Exclude<keyof AskRequest, AskProjected | AskExcluded>>;
 type TaskEventHandled = "text_delta" | "reasoning_delta" | "tool_start" | "tool_end" | "turn_end" | "compacted" | "diagnostics" | "message_committed" | "status" | "task_notification" | "task_progress" | "steering_injected" | "workspace_changed" | "done" | "context_usage" | "compaction_outcome" | "human_input" | "wiring_manifest";
 type _GuardTaskEvent = AssertAllKeysHandled<Exclude<TaskEvent["type"], TaskEventHandled>>;
@@ -36,6 +36,14 @@ type _GuardMailbox = AssertAllKeysHandled<Exclude<keyof MailboxMessage, MailboxP
 type MailboxAppendMessage = Parameters<MailboxStore["append"]>[2];
 type MailboxAppendProjected = "from" | "content" | "sentAt" | "hopChain";
 type _GuardMailboxAppend = AssertAllKeysHandled<Exclude<keyof MailboxAppendMessage, MailboxAppendProjected>>;
+type PermissionTraceKind = Extract<TraceEvent["kind"], `permission.${string}`>;
+type PermissionTraceProjected = "permission.persisted_rule_allowed" | "permission.rule_store_unreadable";
+type PermissionTraceDropped = "permission.sandbox_admitted" | "permission.rule_sync_resurrected" | "permission.rule_sync_dropped" | "permission.org_snapshot_unavailable";
+type _GuardPermissionTrace = AssertAllKeysHandled<Exclude<PermissionTraceKind, PermissionTraceProjected | PermissionTraceDropped>>;
+type _GuardPermissionTraceReverse = AssertAllKeysHandled<Exclude<PermissionTraceProjected | PermissionTraceDropped, PermissionTraceKind>>;
+/** `T` 非 `never` 时收敛到 `never`(空集 ⇒ 残留 `"EMPTY"` ⇒ tsc 红)。 */
+type AssertNonEmpty<T> = [T] extends [never] ? "EMPTY" : never;
+type _GuardPermissionTraceNonEmpty = AssertAllKeysHandled<AssertNonEmpty<PermissionTraceKind>>;
 export type CoreKeysetGuards = [
     _GuardNotification,
     _GuardBgNotif,
@@ -43,7 +51,10 @@ export type CoreKeysetGuards = [
     _GuardAsk,
     _GuardTaskEvent,
     _GuardMailbox,
-    _GuardMailboxAppend
+    _GuardMailboxAppend,
+    _GuardPermissionTrace,
+    _GuardPermissionTraceReverse,
+    _GuardPermissionTraceNonEmpty
 ];
 export {};
 //# sourceMappingURL=core-keyset-guard.d.ts.map

package/dist/trace/project.d.ts

@@ -291,8 +291,25 @@ export declare function workspaceChangedEventData(ev: {
  *    某个可选设施」的部署形自述,而那三个早已租户可见。消费端的真需求也在租户侧:审批卡要不要渲染
  *    「不再询问」这一格,取决于这台 worker 有没有规则店 —— 剥掉它,客户端只能靠试(提交后被拒)才知道。
  *    它**不在** `governance` 段里(core 自己把它放在段外),也不构成那 4 个治理布尔的侧信道。
- *    ⚠️ 恒在段(core 侧 `permissionRules` 无 `?`):本仓未接规则店 ⇒ `storeWired: false`,这是**真值**
- *    不是缺席 —— 消费端读到 false 就是「这台 worker 没有这条车道」,不许当成「这版引擎还没这个概念」。
+ *    ⚠️ 恒在段(core 侧 `permissionRules` 无 `?`):两个真值都可能出现,**别把 false 读成缺席**。
+ *    本仓自 #154 车二 / design/203 起真接了规则店(`main.ts` 在 `PERMISSION_RULES_ENABLED` 为真 ∧
+ *    backend 在场时把 `permissionRuleStore` 装进 `RunnerDeps`,SQL 与 File 两形)⇒ 那样的部署报
+ *    `storeWired: true`;旋钮关掉或后端缺席的部署仍报 `false`。消费端读到 false 就是「这台 worker
+ *    今天没有这条车道」,不许当成「这版引擎还没这个概念」。
+ *  · `permissionRules.syncWired` / `permissionRules.orgGoverned`(布尔两位;core 5.23.0 design/182 §9/§7
+ *    给**同一段**加的员,[3372] 提货批 codex 复审 high 抓获——首版把它们静默剥了,正是本仓建这份台账要防
+ *    的「投影白名单剥键」病)—— **裁:租户可见,与同段的 `storeWired` 同待遇**。判据三条:
+ *    ① **同段同类**:core 把它们放进 `permissionRules` 而不是 `governance`(唯一带 audience 标签的段),
+ *       且形状与 `storeWired` 逐字同构(恒在的布尔,present-and-false 表示「有这个概念,这里没开」);
+ *    ② **消费端真需求在租户侧**:这两位说的是「按下『不再询问』之后,这条同意到底落到多大的信任域里」——
+ *       `syncWired` = 这台 worker 会把规则并进跨设备/传输/服务端的**同一个同意信任域**;`orgGoverned` =
+ *       组织治理层武装着(且它的 fail-closed 契约意味着读不到 org 快照时**每一次**放行都会被抬成真人审批)。
+ *       同一张审批卡上的同一个动作,后果因这两位而不同,剥掉它们等于让客户端渲一格语义不明的开关;
+ *    ③ **不是治理侧信道**:两位都不参与 `governance` 那 4 个布尔的还原(它们描述规则店这条车道自身的
+ *       形状,与 lockedConfig/compliance/memoryAdmission/retention 无函数关系)。
+ *    ⚠️ 与 `storeWired` **不同**:本仓这两条至今未接(`RunnerDeps.permissionRuleSyncWired` /
+ *    `permissionRuleOrg` 全树零声明点,2026-08-10 #204 复扫亲验)⇒ 今天恒 `false`,这是**真值**不是
+ *    缺席。哪天接上其中任一条,连本句一起改 —— 这一行是它的登记处。
  * 未来 core 加一段而它没有 audience 标签时,**先在这里补一条裁定再决定挑不挑键** —— 段级完备性钉
  * (test/wiring-manifest-projection.test.ts)会在那一刻先把人拦下来。
  */
@@ -369,6 +386,7 @@ export declare function brainStatusEventData(ev: {
     attempt?: number;
     maxRetries?: number;
     retryInMs?: number;
+    errClass?: string;
     eventId?: string;
     parentToolCallId?: string;
 }): Record<string, unknown>;