@sema-agent/server 7.10.0 → 7.11.0

package/dist/plugins/tidb-pool.js

@@ -1,5 +1,7 @@
 import mysql from "mysql2/promise";
 import { TIDB_APPROVAL_ASK_STATEMENTS } from "./approval-ask-store-sql.js";
+import { TIDB_ADOPTION_LOG_STATEMENTS } from "./adoption-log-sql.js";
+import { TIDB_PERMISSION_RULE_STATEMENTS } from "./permission-rule-store-sql.js";
 /**
  * Shared TiDB (MySQL wire-compatible) connection pool for the durable Session center (L1).
  * Owned by `main.ts`; closed on shutdown.
@@ -648,6 +650,51 @@ export const SCHEMA_STATEMENTS = [
     // 跟着中央 `ensureSchema` 在 **named-lock 的那条 conn** 上建 —— 把 pool 级 ensure 函数塞进执行循环
     // 会绕开 DDL 串行化。挂进来同时也是「这张表算生产 schema」的声明(基线导出按定义只收录被执行的语句)。
     ...TIDB_APPROVAL_ASK_STATEMENTS,
+    // design/177 shared-memory store(#192 单数纪律)—— org 盘的三张表。消费面 = shared-memory-store-sql.ts。
+    // 🔴 与 `agent_memory_engine_*`(design/138 本地记忆链)**零关系**:不 join、不共享 scope 登记、不互写
+    // (设计 182 §13)。两族同库不同面,合表/建视图会让 harvest 的私人笔记漏进团队库。
+    `CREATE TABLE IF NOT EXISTS shared_memory_scope (
+     -- 一个 org scope 一行。行缺席 = 该 org 从未开通 ⇒ 语义等价于 connected 且零 store(不是故障)。
+     scope_key     VARCHAR(190) NOT NULL,
+     -- 闭集词:connecting|unavailable|connected。读出时走 planeStateOf 的穷举 switch,未知词整拒快照。
+     state         VARCHAR(16)  NOT NULL,
+     -- host 自述原因,仅 unavailable 有意义;core 折成一行喂模型面。
+     message       VARCHAR(512) NULL,
+     updated_at_ms BIGINT       NOT NULL,
+     PRIMARY KEY (scope_key)
+   ) COLLATE utf8mb4_bin`,
+    `CREATE TABLE IF NOT EXISTS shared_memory_store (
+     -- 模型面把手,**全局唯一**:同 id 在两个 org 各一份会在跨 org 成员的快照里撞名,而 core 对撞名 id
+     -- 的处置是整行丢弃 —— 那是一次静默的库消失,所以用 PK 在库层堵死。
+     store_id      VARCHAR(64)  NOT NULL,
+     scope_key     VARCHAR(190) NOT NULL,
+     description   VARCHAR(512) NOT NULL,
+     -- 治理面结论,原样转达;core 对它零动作(模型面根本没有写通道)。
+     writable      TINYINT(1)   NOT NULL DEFAULT 0,
+     updated_at_ms BIGINT       NOT NULL,
+     PRIMARY KEY (store_id),
+     KEY idx_shared_memory_store_scope (scope_key, store_id)
+   ) COLLATE utf8mb4_bin`,
+    `CREATE TABLE IF NOT EXISTS shared_memory_entry (
+     store_id       VARCHAR(64)  NOT NULL,
+     -- 绝对路径。PK 即 keyset 分页索引:WHERE store_id = ? AND path > ? ORDER BY path。
+     path           VARCHAR(512) NOT NULL,
+     content        LONGTEXT     NOT NULL,
+     -- ISO 8601 原文逐字回放(core 只渲染匹配的 YYYY-MM-DD 前缀)。数值毫秒列是下面那根,两者不同义。
+     updated_at_iso VARCHAR(64)  NULL,
+     size_bytes     INT          NOT NULL,
+     updated_at_ms  BIGINT       NOT NULL,
+     PRIMARY KEY (store_id, path)
+   ) COLLATE utf8mb4_bin`,
+    // design/183 form b(纯身份重绑)的 **SQL 收编日志**。真源 = adoption-log-sql.ts 的
+    // `TIDB_ADOPTION_LOG_STATEMENTS`(与 PG twin 并排);展开进来的理由与 approval-ask 同款:
+    // 跟着中央 ensureSchema 在 named-lock 的那条 conn 上建,不绕开 DDL 串行化。
+    // 🔴 它**必须**与被迁的行同库(183 I2):phase 真源住别处 ⇒ 发起 host 被摧毁时与半迁移状态分家。
+    ...TIDB_ADOPTION_LOG_STATEMENTS,
+    // #154 车二(core 5.18.0 design/179 + 5.22.0 design/182)持久化权限规则店的三张表。真源 =
+    // permission-rule-store-sql.ts 的 `TIDB_PERMISSION_RULE_STATEMENTS`(与 PG twin 并排);展开进这个
+    // 数组的理由与上面那族逐字相同(named-lock 的那条 conn + 「这张表算生产 schema」的声明)。
+    ...TIDB_PERMISSION_RULE_STATEMENTS,
 ];
 /** Named MySQL/TiDB advisory lock that serializes the whole `ensureSchema` DDL run (see below). */
 export const ENSURE_SCHEMA_LOCK = "sema_ensure_schema";

package/dist/rules-consent.d.ts

@@ -0,0 +1,126 @@
+import { type ImportPreview, type ImportResult, type ImportedSettingsLayer, type RuleScope } from "@sema-agent/core";
+import type { PermissionRuleStoreProvider, RuleApprovalRecordStore } from "@sema-agent/core";
+import { type RuleImportTicket, type RuleTicketRedeemResult } from "./plugins/permission-rule-store-sql.js";
+/**
+ * 本车道**真正**依赖的三面(**结构**接口,不是 SQL 类)。
+ *
+ * 🔴 为什么不直接吃 `PermissionRuleStores`(SQL 束):同意车道是**纯协议逻辑**,它对「行躺在 MySQL 还是
+ * PG 还是别处」一无所知也不该知道。吃结构接口有两个真收益:①单元测试能用 core 自己的
+ * `InMemoryPermissionRuleStore` / `InMemoryRuleApprovalRecordStore` 驱动**同一段**代码(而不是为了测协议
+ * 去拉一个数据库);②将来若真出了 File 形规则店,本文件一个字不用改。SQL 束结构上满足本接口。
+ */
+export interface RuleConsentStores {
+    provider: PermissionRuleStoreProvider;
+    /** core 的记录店面 + 一个**可选**的加项:`discardPendingRecord`(超帽拒绝时收掉 `prepareCcImport`
+     *  已经落盘的那一条 pending 记录)。没有这个加项的后端只是留一条孤儿行,不影响任何判决
+     *  (语义与「已确认的记录永不被收」的硬条款见 SQL 侧同名方法)。 */
+    approvals: RuleApprovalRecordStore & {
+        discardPendingRecord?(recordId: string): Promise<boolean>;
+    };
+    tickets: {
+        mint(input: {
+            ticketId: string;
+            principal: string;
+            approvalId: string;
+            candidates: ReadonlyArray<{
+                rule: string;
+                scope: RuleScope;
+            }>;
+            ttlMs: number;
+        }): Promise<RuleImportTicket>;
+        /** 一次**认领**(不是「已完成」)。语义与「认领之后怎么办」见 {@link RuleConsentStores.tickets.release}。 */
+        consume(ticketId: string, principal: string): Promise<RuleTicketRedeemResult>;
+        /** 把认领**放回去**(认领之后遇到不确定/瞬时失败时)。`mustRemainValidMs` = 放回之后这张票至少还要
+         *  能用多久 —— 撑不过就**不算放回成功**(理由逐字见 store 侧 `release` 的头注)。 */
+        release(ticketId: string, principal: string, mustRemainValidMs?: number): Promise<boolean>;
+    };
+}
+/** 导入票的存活窗。人从「看到预览」到「按下确认」是一次交互,不是一段会话——十分钟宽到不会误伤,
+ *  窄到一张泄漏的票不会常驻。运维旋钮暂不开(没有部署形要求它可调;要开时走 config.ts 的既有姿势)。 */
+export declare const RULE_IMPORT_TICKET_TTL_MS: number;
+/** 可重试那一支通告给客户端的等待秒数(`state.rule_import_retry` 的 `retryAfterSec` / `Retry-After`)。
+ *  短 —— 它对应的是一次瞬时 store 抖动,不是排队。**单一真源在本文件**:放回认领时要用它判「这张票
+ *  还能不能撑过这段窗」,HTTP 层要用它填响应,两处用同一个数才谈得上「承诺兑得出来」。 */
+export declare const RULE_IMPORT_RETRY_AFTER_SEC = 2;
+/**
+ * **全部层合计**的候选上限(codex 交叉复审 round7 [high] 二,验真后修)。
+ *
+ * 单层 16 KiB 只管住了**请求体**,管不住**下游工作量**:紧凑的合法规则(`Bash(ls)` 十个字符)能让三层
+ * 塞进上千条候选,而 core 的 `redeemRuleBatch` 是**逐候选**跑一遍「读店 + CAS 写」的串行循环 —— 一个
+ * 已鉴权的请求就能把连接池占满、把响应撑到兆字节。全局限流器默认是关的,拦不住它(一次准入就够了)。
+ *
+ * 帽数的是 **core 已经解析好的候选**(不是我们自己再数一遍 JSON):零重复解析,而且数的正好是那条串行
+ * 循环的**真实**长度。位置在**铸票之前** —— 超限就没有票,那条昂贵的循环一次都跑不起来(代价只剩一条
+ * 已铸的 pending 记录,与任何一次没去兑付的 prepare 留下的残余同形)。
+ * 200 的取值:一份人手写的 CC settings 极少超过几十条;200 给了一个数量级的余量,又把最坏工作量钉在
+ * 「几百次 SQL」而不是「几万次」。
+ */
+export declare const MAX_IMPORT_CANDIDATES = 200;
+/** 一次导入 prepare 的产物(HTTP 200 体的素材),或**超帽**的拒绝(见 {@link MAX_IMPORT_CANDIDATES})。 */
+export type RuleImportPrepared = {
+    ok: true;
+    preview: ImportPreview;
+    ticket: string;
+    expiresAtMs: number;
+} | {
+    ok: false;
+    reason: "too-many-candidates";
+    candidates: number;
+};
+/** 导入 redeem 的结果。`refused` 的四个成因**在 wire 面折成同一个 404**(见顶注 ①)——这里保留分类
+ *  只为服务端日志/诊断。 */
+export type RuleImportRedeemed = {
+    ok: true;
+    result: ImportResult;
+}
+/** `retryable` = 这次失败**没有裁定任何事**(store 抛错 / CAS 冲突),认领已放回,属主原样重试即可。
+ *  它与裁定性拒绝(载荷被篡改、记录不存在)分家是承重的:把两者塌成一格,一次数据库抖动就会被
+ *  客户端读成「这张票永远不能用了」。⚠️ **wire 面仍然折成同一个 404**(零存在性 oracle 不因此松动);
+ *  这一位只进服务端日志与本层的重试判据。 */
+ | {
+    ok: false;
+    reason: "ticket-unusable" | "record-unusable" | "payload-mismatch";
+    detail: string;
+    retryable?: true;
+};
+/** 卡道兑付的结果。 */
+export type CardRulePersisted = {
+    ok: true;
+    rule: string;
+    rev: number;
+    alreadyRedeemed: boolean;
+} | {
+    ok: false;
+    reason: "no-candidates" | "unknown-candidate" | "confirm-refused" | "redeem-refused";
+    detail: string;
+};
+/** 一层用户交上来的 settings(HTTP 载荷已 zod 校验过的形)。 */
+export interface RuleImportLayerInput {
+    layer: ImportedSettingsLayer;
+    path: string;
+    root: string;
+    content: string;
+}
+export interface RuleConsentLane {
+    /** 卡道兑付口:一次 ask 决议携规则确认 ⇒ prepare→confirm→redeem 一气呵成。 */
+    persistCardRule(input: {
+        principal: string;
+        toolName: string;
+        /** 被裁决的命令**原字节**(与 ask 上的那份同源;规则文本由引擎从它铸,调用方不供文本)。 */
+        command: string;
+        /** 客户端选中的候选**文本**——用来在引擎铸出的候选表里定位下标。文本对不上 ⇒ 拒(不猜)。 */
+        ruleText: string;
+        toolCallId?: string;
+        boundInputHash?: string;
+        scope?: RuleScope;
+    }): Promise<CardRulePersisted>;
+    /** 导入道:读层 → 预览 + pending 记录 + 票。 */
+    prepareImport(principal: string, layers: readonly RuleImportLayerInput[]): Promise<RuleImportPrepared>;
+    /** 导入道:原子消费票 → confirm → redeemRuleBatch。 */
+    redeemImport(principal: string, ticket: string): Promise<RuleImportRedeemed>;
+}
+export declare function createRuleConsentLane(stores: RuleConsentStores, opts?: {
+    ticketTtlMs?: number;
+    newTicketId?: () => string;
+}): RuleConsentLane;
+//# sourceMappingURL=rules-consent.d.ts.map

package/dist/rules-consent.js

@@ -0,0 +1,198 @@
+/**
+ * #154 车二 —— **同意车道的 server 半场**(core 5.18.0 design/179 `permission-rule-consent.ts` 的宿主侧)。
+ *
+ * core 把一条规则进店的路钉成三步:`durable approval record (pending)` → `authenticated confirmation
+ * transfer (approved)` → `principal-bound redemption (redeemed)`,而且**只有第三步**够得着写面。core 明写
+ * 「The confirmation transfer is an in-process call. **A deployment must reach it only from its
+ * authenticated approval channel**」—— 那句话是把一段责任**交给宿主**,不是一段已经完成的检查。本文件就是
+ * 那段责任的落点:
+ *
+ *  · 卡道(兑付口):一次 ask 决议携「不再询问」时,由**这里**去 prepare→confirm→redeem。人是谁 =
+ *    回决端点已验明的 principal(不是请求体里的任何字段);规则文本 = **引擎**从被裁决的命令铸的候选
+ *    (`prepareCardApproval` 不收调用方候选,core 在那条入口上已经把「写自己的规则」这件事变成不可拼写),
+ *    客户端只能说「我选第几个」。
+ *
+ *  · 导入道(CC settings):`prepare` 读用户交上来的 settings 层、铸 pending 记录 + **server 自铸的票**;
+ *    `redeem` 原子消费票、confirm、`redeemRuleBatch`。
+ *
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * 🔴 票的信任边界四条,**全部是 server 附加的**(不是 core 的语义)
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * 亲读 core 的 `mintRuleTicket`(dist,5.22.0):`return \`rt.${candidateIndex}.${recordId}\`` —— 它**没有**
+ * TTL、没有签名、没有消费位、没有载荷绑定。core 的票在**进程内**是够的(它的相邻语义是「重放同一次兑付是
+ * 幂等的」),但一条跨网络、由客户端保管、可被复制的票需要另外四样:
+ *   ① **principal 绑定** —— redeem 的已验明 principal 必须 = prepare 铸票的那一位。跨 principal redeem 与
+ *      unknown ticket **同形 404**:两者返回不同的码就是一台存在性 oracle(拿别人的票撞库能探到「它存在」)。
+ *   ② **过期** —— `RULE_IMPORT_TICKET_TTL_MS`;过期 redeem 拒。
+ *   ③ **一次性原子消费** —— 同票二次 redeem 拒,并发双 redeem **恰一成功**。判据由 SQL 的单条条件
+ *      `UPDATE … WHERE consumed_at_ms IS NULL` 回答,**禁 read-then-write**(见 store 那侧的 🔴 注)。
+ *   ④ **载荷绑定** —— redeem 应用的规则集 = prepare 时刻的快照。core 已经结构上保证了「规则文本来自记录」,
+ *      本层再加一道:票上钉着 prepare 时刻候选集的摘要,redeem 时与记录上的候选集重算比对,不符即拒 ——
+ *      于是「篡改记录再拿旧票兑付」这条路上多一道等式,而不是只靠「记录只有我们能写」这一条信念。
+ *
+ * 命名(CLAUDE.md 工厂律):`build*` = 纯数据;`create*` = 活对象。本文件的 {@link createRuleConsentLane}
+ * 返回一个带方法的束 ⇒ `create*`。
+ */
+import { randomUUID } from "node:crypto";
+import { recordFailOpen } from "./observability/fail-open.js";
+import { confirmRuleApproval, prepareCardApproval, prepareCcImport, redeemRuleBatch, redeemRuleTicket, } from "@sema-agent/core";
+import { buildRulePayloadHash } from "./plugins/permission-rule-store-sql.js";
+/** 导入票的存活窗。人从「看到预览」到「按下确认」是一次交互,不是一段会话——十分钟宽到不会误伤,
+ *  窄到一张泄漏的票不会常驻。运维旋钮暂不开(没有部署形要求它可调;要开时走 config.ts 的既有姿势)。 */
+export const RULE_IMPORT_TICKET_TTL_MS = 10 * 60_000;
+/** 可重试那一支通告给客户端的等待秒数(`state.rule_import_retry` 的 `retryAfterSec` / `Retry-After`)。
+ *  短 —— 它对应的是一次瞬时 store 抖动,不是排队。**单一真源在本文件**:放回认领时要用它判「这张票
+ *  还能不能撑过这段窗」,HTTP 层要用它填响应,两处用同一个数才谈得上「承诺兑得出来」。 */
+export const RULE_IMPORT_RETRY_AFTER_SEC = 2;
+/**
+ * **全部层合计**的候选上限(codex 交叉复审 round7 [high] 二,验真后修)。
+ *
+ * 单层 16 KiB 只管住了**请求体**,管不住**下游工作量**:紧凑的合法规则(`Bash(ls)` 十个字符)能让三层
+ * 塞进上千条候选,而 core 的 `redeemRuleBatch` 是**逐候选**跑一遍「读店 + CAS 写」的串行循环 —— 一个
+ * 已鉴权的请求就能把连接池占满、把响应撑到兆字节。全局限流器默认是关的,拦不住它(一次准入就够了)。
+ *
+ * 帽数的是 **core 已经解析好的候选**(不是我们自己再数一遍 JSON):零重复解析,而且数的正好是那条串行
+ * 循环的**真实**长度。位置在**铸票之前** —— 超限就没有票,那条昂贵的循环一次都跑不起来(代价只剩一条
+ * 已铸的 pending 记录,与任何一次没去兑付的 prepare 留下的残余同形)。
+ * 200 的取值:一份人手写的 CC settings 极少超过几十条;200 给了一个数量级的余量,又把最坏工作量钉在
+ * 「几百次 SQL」而不是「几万次」。
+ */
+export const MAX_IMPORT_CANDIDATES = 200;
+export function createRuleConsentLane(stores, opts) {
+    const deps = { provider: stores.provider, approvals: stores.approvals };
+    const ticketTtlMs = opts?.ticketTtlMs ?? RULE_IMPORT_TICKET_TTL_MS;
+    const newTicketId = opts?.newTicketId ?? (() => randomUUID());
+    return {
+        async persistCardRule(input) {
+            // 🔴 候选**由引擎铸**(core `prepareCardApproval` 不收调用方候选;那条入口上「写自己的规则」
+            // 结构上不可拼写)。本层只把「人选了哪一个」翻译成下标。
+            const prepared = await prepareCardApproval({
+                principal: input.principal,
+                toolName: input.toolName,
+                command: input.command,
+                ...(input.toolCallId !== undefined ? { toolCallId: input.toolCallId } : {}),
+                ...(input.boundInputHash !== undefined ? { boundInputHash: input.boundInputHash } : {}),
+                ...(input.scope !== undefined ? { scope: input.scope } : {}),
+                deps,
+            });
+            if (prepared === undefined) {
+                return { ok: false, reason: "no-candidates", detail: "the rule lane cannot speak for this command (compound / redirection / unsupported tool)" };
+            }
+            const index = prepared.candidates.findIndex((c) => c.rule === input.ruleText);
+            const ticket = index < 0 ? undefined : prepared.tickets[index];
+            if (index < 0 || ticket === undefined) {
+                return { ok: false, reason: "unknown-candidate", detail: "the chosen rule text is not one the engine minted for this command" };
+            }
+            const confirmed = await confirmRuleApproval({ approvalId: prepared.approvalId, principal: input.principal, selectedCandidate: index, deps });
+            if (!confirmed.ok)
+                return { ok: false, reason: "confirm-refused", detail: confirmed.reason };
+            const redeemed = await redeemRuleTicket({ ticket, principal: input.principal, deps });
+            if (redeemed.status !== "redeemed")
+                return { ok: false, reason: "redeem-refused", detail: redeemed.reason };
+            return { ok: true, rule: redeemed.rule, rev: redeemed.rev, alreadyRedeemed: redeemed.alreadyRedeemed };
+        },
+        async prepareImport(principal, layers) {
+            // core 的 `CcImportLayer.readFile` 是一条**注入的**读口 —— 云端部署没有用户的文件系统,内容由
+            // 调用方交上来(这是本仓的部署形,不是绕过:读的仍然只是 allow 桶,拒/问桶是收紧方向、另有通道)。
+            const ccLayers = layers.map((l) => ({
+                layer: l.layer,
+                path: l.path,
+                root: l.root,
+                readFile: async () => l.content,
+            }));
+            const { preview, approvalId } = await prepareCcImport({ layers: ccLayers, principal, deps });
+            // 帽在**铸票之前**(见 {@link MAX_IMPORT_CANDIDATES}):没有票 ⇒ 那条逐候选的串行 SQL 循环跑不起来。
+            if (preview.candidates.length > MAX_IMPORT_CANDIDATES) {
+                // core 在**返回预览之前**就把 pending 记录落了盘 ⇒ 这次不做的导入会留一条永远没人要的行。
+                // 收掉它(codex round8 [medium]:被拒的 prepare 不该在共享库里长东西)。best-effort:收不掉
+                // 也只是留一条 pending 孤儿,不影响任何判决 —— 但**绝不**因此把 413 变成 500。
+                try {
+                    await stores.approvals.discardPendingRecord?.(approvalId);
+                }
+                catch (err) {
+                    recordFailOpen("server.rules.rejected-prepare-row-left", err instanceof Error ? err.message : String(err));
+                }
+                return { ok: false, reason: "too-many-candidates", candidates: preview.candidates.length };
+            }
+            const minted = await stores.tickets.mint({ ticketId: newTicketId(), principal, approvalId, candidates: preview.candidates, ttlMs: ticketTtlMs });
+            return { ok: true, preview, ticket: minted.ticketId, expiresAtMs: minted.expiresAtMs };
+        },
+        async redeemImport(principal, ticket) {
+            // ①②③ 一次原子**认领**同时回答(principal 绑定 / 未过期 / 未认领);四类拒绝在 wire 面同形。
+            const consumed = await stores.tickets.consume(ticket, principal);
+            if (!consumed.ok)
+                return { ok: false, reason: "ticket-unusable", detail: consumed.reason };
+            // 🔴 codex round1 [high] 一(验真后修):认领**之后**的每一步都可能失败,而旧形把认领当终局 ⇒
+            // 一次 store 抖动就永久烧掉这张票,客户端拿到与「票不存在」同形的 404,重试无门。
+            // 处置:裁定性拒绝(载荷被篡改 / 记录不存在)**留着**认领(重试不改判);不确定/瞬时失败**放回**
+            // 认领并标 `retryable`。放回不打开双兑付的门(认领仍是单持有者),兑付腿本身按 core 的设计幂等。
+            // 🔴 codex 交叉复审 round3 [high] 一(验真后修):返回值是**「认领确实放回去了吗」**,不是 void。
+            // 旧形无条件回 `retryable: true`,而释放本身也可能失败(同一场 store 故障往往两跳一起挂)——
+            // 那就变成对客户端**撒谎**:它拿着一张其实已经烧掉的票去重试,只会收到 404,人的确认永久丢失。
+            // 判据必须是「释放**确认**成功」;没确认就不许承诺重试(如实按不可重试报,四类同形 404)。
+            const releaseClaim = async () => {
+                try {
+                    return await stores.tickets.release(ticket, principal, RULE_IMPORT_RETRY_AFTER_SEC * 1000);
+                }
+                catch (err) {
+                    // 放不回去 = 回到「认领即烧票」的旧形(属主这一轮不能重试,票随 TTL 消失)。**不**把一次
+                    // 已经失败的请求再变成一次抛错;但也**不**静默 —— 登记的 F 类兜底,理由逐字见 tag 词表。
+                    recordFailOpen("server.rules.ticket-claim-release-failed", err instanceof Error ? err.message : String(err));
+                    return false;
+                }
+            };
+            /** 「不确定」那一支的统一收口:**释放确认成功**才承诺可重试。 */
+            const indeterminate = async (detail) => {
+                // 放回之后这张票至少要能撑过我们通告的等待窗 —— 撑不过就不承诺重试(见 store 侧 `release` 头注)。
+                const released = await releaseClaim();
+                return { ok: false, reason: "record-unusable", detail, ...(released ? { retryable: true } : {}) };
+            };
+            try {
+                // ④ 载荷绑定:记录上的候选集必须与铸票时刻的快照同摘要。
+                const record = await stores.approvals.get(consumed.approvalId);
+                if (record === undefined)
+                    return { ok: false, reason: "record-unusable", detail: "the approval record behind this ticket is gone" };
+                if (buildRulePayloadHash(record.candidates) !== consumed.payloadHash) {
+                    return { ok: false, reason: "payload-mismatch", detail: "the approval record's candidates changed after the ticket was minted" };
+                }
+                // 🔴 确认是**一次性状态跃迁**,不是每次兑付都要过的门:重试一张**放回过认领**的票时,记录
+                // 早已不是 `pending` 了(core 的崩溃序:`redeemRuleTicket` 在调用写面**之前**就把记录推到
+                // `redeemed`,所以哪怕一个候选都没落地,状态也已经变了)。对已确认的记录再调一次
+                // `confirmRuleApproval` 会拿到 `not_pending` —— 把它当拒绝就等于「放回了认领却永远兑不动」,
+                // round1/round3/round5 那一串修复到此全部白做。判据用记录**自己的状态**,不是猜错误串。
+                if (record.state === "pending") {
+                    const confirmed = await confirmRuleApproval({ approvalId: consumed.approvalId, principal, deps });
+                    if (!confirmed.ok) {
+                        // `conflict` = CAS 输给了一个并发写者(瞬时);其余是裁定(记录不存在/状态不对)。
+                        if (confirmed.reason === "conflict")
+                            return await indeterminate(confirmed.reason);
+                        return { ok: false, reason: "record-unusable", detail: confirmed.reason };
+                    }
+                }
+                const result = await redeemRuleBatch({ approvalId: consumed.approvalId, principal, deps });
+                if ("status" in result) {
+                    // core 的 refused 里既有裁定也有瞬时(OCC 用尽 / 店读不出来)——分不清就按**可重试**放回:
+                    // 兑付是幂等的,多放一次认领最坏是多跑一遍同样的重放;烧掉一张真票是不可逆的。
+                    return await indeterminate(result.reason);
+                }
+                // 🔴 codex 交叉复审 round5 [high] 二(验真后修):core 的 `redeemRuleBatch` 把**逐候选**的失败
+                // 记在 `skippedAtRedeem` 里,顶层照样返回一个 ImportResult —— 只判顶层 `status` 会把「一半没落地」
+                // 当成功回 200,而认领已经烧掉,那一半再也补不回来。
+                // 为什么这条车道可以把「非空 skippedAtRedeem」一律当**不确定**:候选在 `prepareCcImport` 那一步
+                // 就已经全过了同一个验证器(过不了的进 `preview.skipped`,压根不进记录),所以兑付期的逐候选拒绝
+                // 实际只剩「店读不出/写不进 / OCC 用尽 / 隔离栅栏」这类**瞬时或异常**成因。重放是幂等的
+                // (记录里存着每个候选已铸的 dot),所以放回认领让人重试,代价上界只是再跑一遍同样的重放。
+                // 残留(如实登记):真出现一条**永久**被拒的候选时,客户端会一直拿到 503 直到票到期(10 分钟)——
+                // 有界、且不破坏任何已落地的规则;要更好得让 core 把逐候选拒绝分成瞬时/裁定两类,已列后续件。
+                if (result.skippedAtRedeem.length > 0) {
+                    return await indeterminate(`partial import: ${result.skippedAtRedeem.length} candidate(s) did not land (${result.skippedAtRedeem.map((x) => x.reason).join("; ")})`);
+                }
+                return { ok: true, result };
+            }
+            catch (err) {
+                return await indeterminate(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+}
+//# sourceMappingURL=rules-consent.js.map

package/dist/shared-memory-scope-authorizer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * design/177 v2/F4 —— shared-memory 读面的**授权折叠**:principal → 可读 org scope 集。
+ *
+ * 为什么复用 {@link OrgMemoryDirectory} 而不是另立一张表:「谁属于 org:acme」在一个进程里必须只有一个
+ * 答案。core 的记忆准入 seam、`/v1/memory/*` 的属主门、以及这里的共享库读面读的是**同一个目录实例**
+ * (`createOrgMemoryAdmissionWiring` 的产物),因此共享同一份 TTL 缓存 / 退避窗 / gen 高水位——吊销窗内
+ * 三面不会公开分歧。各建各的目录 = 三个答案,那正是 design/170 §7 收编要消灭的东西。
+ *
+ * 🔴 判别联合原样透传(N3/C5 裁定的下游一致性):目录说 `unavailable` 时**绝不**折成「你不属于任何
+ * org」。前者在模型面渲染成「连接不可用,恢复前拒读」(可重试),后者渲染成「本会话没有连接任何记忆库」
+ * (终局,模型就此放弃)。两句话是相反的指令,把前者塌进后者是一次静默的 fail-open。
+ *
+ * 🔴 deployment-origin scope 的多租户切断:operator 在配置里自证的 org scope(`MEMORY_SCOPE=org:x`、
+ * 单用户部署的 projects 登记簿)只在**无租户边界**的部署里授予。多租户部署(`requirePrincipal`)下,
+ * 一条部署级声明会同时授予每一个 principal —— 那是跨租户读,不是配置便利。装配点因此按部署形态把这个
+ * 集合择净后再传进来(见 main.ts 的构造行),本模块只忠实使用它:哪些 scope 算「部署自证」是装配点的
+ * 判断,不是这里的。
+ */
+import type { SharedMemoryScopeAuthorizer } from "./plugins/shared-memory-store-sql.js";
+import type { OrgMemoryDirectory } from "./org-memory-admission.js";
+export interface SharedMemoryScopeAuthorizerOptions {
+    /** 目录实例。**必须**与 core 准入 seam / memory-policy 面同一只(见头注)。 */
+    directory: OrgMemoryDirectory;
+    /** 部署自证的 org scope(装配点已按部署形态择净;多租户下应为空)。 */
+    deploymentScopes?: readonly string[];
+}
+/** 活对象(闭包持有目录与集合)⇒ `create*`(CLAUDE.md 工厂命名律)。 */
+export declare function createSharedMemoryScopeAuthorizer(opts: SharedMemoryScopeAuthorizerOptions): SharedMemoryScopeAuthorizer;
+//# sourceMappingURL=shared-memory-scope-authorizer.d.ts.map

package/dist/shared-memory-scope-authorizer.js

@@ -0,0 +1,17 @@
+/** 活对象(闭包持有目录与集合)⇒ `create*`(CLAUDE.md 工厂命名律)。 */
+export function createSharedMemoryScopeAuthorizer(opts) {
+    const deploymentScopes = [...new Set(opts.deploymentScopes ?? [])];
+    return {
+        async resolve(principal) {
+            // principal 缺席 = 单用户部署(多租户下 core 与 HTTP 门都先要求身份)。此时唯一的授权事实就是
+            // operator 自证的那一组;目录无从查起,但这不是「不可用」——它是一个**已知的**答案。
+            if (principal === undefined)
+                return { kind: "granted", scopes: deploymentScopes };
+            const lookup = await opts.directory.lookup(principal);
+            if (lookup.kind === "unavailable")
+                return { kind: "unavailable", reason: lookup.reason };
+            return { kind: "granted", scopes: [...new Set([...deploymentScopes, ...Object.keys(lookup.scopes)])] };
+        },
+    };
+}
+//# sourceMappingURL=shared-memory-scope-authorizer.js.map

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,24 @@ 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";
 /** 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 +339,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 +351,8 @@ export declare class ToolApprovalCoordinator {
         admitMaxPerOwner?: number;
         /** 缺省 = 进程级单表(写侧默认同一张)。注入口只为测试与将来的多实例形。 */
         governanceAskMarks?: GovernanceAskMarks;
+        /** #154 车二:同意车道(在场 = 规则店已装配)。 */
+        ruleConsent?: RuleConsentLane;
     });
     /**
      * #151 车3 刀 3b —— design/172 §3.3 / 设计稿 §0 X-2 的**写侧准入门**。
@@ -339,6 +374,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 +509,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;