@sema-agent/server 7.146.0 → 7.148.0

package/dist/tool-approval.d.ts

@@ -4,6 +4,7 @@ import type { IncomingMessage } from "node:http";
 import { type AskClass, type AskRequest, type AskOutcome, type PermissionResult, type CheckpointGate, type PendingAction, type PersistedRuleMandate, type ReadRootGrantCandidate, type RuleOffer, type AutoModeFallbackCause, type BoundGrantAbsence, type BoundSkillGrants, type ToolApprovalCard, type ReopenReason } from "@sema-agent/core";
 import { type CardRulePersisted, type RuleConsentLane } from "./rules-consent.js";
 import type { GateCurrencyStore } from "./approval-gate-currency.js";
+import { type HitlTransport } from "./hitl-delivery.js";
 import { type AllowRuleShadowProjection, type DenialLimitFallback, type RuleOffersAbsence, type ApprovalRequestFrame, type ApprovalRevokeFrame, type ApprovalCardLegFrame, type ApprovalCompleteFrame, type RuleEvidenceProjection } from "./approval-card.js";
 import { type ApprovalAskStore, type AskRow } from "./plugins/approval-ask-store-sql.js";
 import type { ApprovalAskAuditSink } from "./approval-ask-audit-store.js";
@@ -31,14 +32,28 @@ interface OpenAskAdoption {
  * (`test/parked-late-decision.test.ts` G3-c:本函数的输出经 `lookupRoute` 落 `approval-decide`)。会话段按路由的 `safeDecode` 对称编码。
  */
 export declare function approvalDecidePath(sessionId: string): string;
+/**
+ * 一只转停驻的问**去哪只会话决** —— 它的停车行(检查点卡)落在哪只会话上,耐久回决口 `POST /v1/approvals/:sessionId/decide` 就按这只会话找卡(卡自己的会话,
+ * 决断口的地址;不是卡归属的 run 会话 —— cascade 级上的卡归调用方的 run,却只能在级自己的会话上决)。三处同读这一只:决断口对 PARKED 行的 `410 gone.ask_parked`
+ * 回显、迟到回决口对 PARKING 行的 `202` 与按问读口 `parked` 的 `decidePath`。
+ * 停车行落在**铸它那条腿**的会话上 = 行上的发起会话 `sourceSessionId`(core 铸停车行的 `sessionId` 与铸这一问的发起会话是同一只变量;根腿 = 行上的会话,
+ * 委派 / 后台子代腿 = 子代自己的会话,不是行上记的投递会话):
+ *  · PARKED —— 收敛器只把问绑到这只会话上的卡(身份第一维按 `sourceSessionId` 比,候选读口按它查)⇒ 绑上了,卡就在它上面,恒给;
+ *  · PARKING —— 还没绑:发起会话可能是会话缺席时的 taskId 替身(不经 Runner 铸的问,`sourceSessionId ?? taskId`;adhoc 腿的会话也是 taskId)⇒ 等于 taskId 时
+ *    读不准,给 `undefined`(宁缺不错:指错会话的路径会把人的作答送去一张不存在的卡)。
+ */
+export declare function parkSessionOf(row: Pick<AskRow, "state" | "sourceSessionId" | "taskId">): string | undefined;
 /**
  * [ref] 随批小件:`tool_approval.not_pending` 404 的**判别位**([ref] 排障代价实证 —— 三因合并成一句人话,现场分不出「答案没地方兑」与「打错副本了」)。
- * DECIDED/PARKED 已从 404 分流(DECIDED ⇒ 200 回放首决,回执带 `decidedBy`,**不是**成因;PARKED ⇒ 赎回席),残余两类:
+ * 🔴 `tool_approval.not_pending` 整个码**只在已过属主门的面上出**(属主看得见的「这张卡不在待决」)。调用方**看不见**这只问 —— 无行 / 行不是调用方的 /
+ * 行读不出 / 这台部署没有问账可判 —— 一律 404 `not_found.ask`(与耐久决断口同一个词:两扇门底下是同一只问;不带任何状态位,属主门不过与未知 id 逐字节同,
+ * 唯一成形口 {@link ToolApprovalCoordinator.askNotVisible})。
+ * DECIDED/PARKED 已从 404 分流(DECIDED ⇒ 200 回放首决,回执带 `decidedBy`,**不是**成因;PARKED ⇒ 赎回席),过了属主门的残余两类:
  *  · 行 `VOID` / `DENIED`(没有人决过它)—— `cause` = **行上记的那个成因词**(问账 `ending_cause` 列;与决断口 410 `gone.ask` 体的 `cause`、审计 settle 行
  *    的 `cause` 同一个词,闭集 {@link SettleCause});行上没写归因(存量行)⇒ 缺席,不替没写的行编一个词;
- *  · {@link NOT_PENDING_UNKNOWN_CAUSE} —— 无行 / 行不是调用方的 / 行仍在别处活着:换副本或换端点重试才有意义(这个词只属于 404 面,不是结局成因)。
- * 对齐 [ref] 反枚举语义:cause 只在**已过属主门**的面上出,不扩枚举面(属主门不过 = 与未知 id 同形)。
- * **无持久店的部署上恒不带**:那台机器压根没有行可判,编一个 cause 是撒谎(D1 体逐字不变)。
+ *  · {@link NOT_PENDING_UNKNOWN_CAUSE} —— 行仍待决而本副本没有在等它的登记(本副本不认得它的活卡:它活在别的副本上,或本副本这条登记已散场):
+ *    换副本或换端点重试才有意义(这个词只属于 404 面,不是结局成因)。
+ * **无持久店的部署上恒不带 `cause`**:那台机器压根没有行可判,编一个 cause 是撒谎。
  */
 export declare const NOT_PENDING_UNKNOWN_CAUSE: "unknown_or_other_replica";
 export type NotPendingCause = AskRowEndingCause | typeof NOT_PENDING_UNKNOWN_CAUSE;
@@ -145,7 +160,10 @@ export interface ParkedAskRedeemRequest {
     decider: ApprovalDecider;
     /** [ref] ctrl+g 编辑放行的实参整体替换(approve 才有意义)。 */
     updatedInput?: unknown;
-    /** 发起本次 respond 的**已验证**调用方(live 腿 `gatedPrincipal` 的那一把)。席在赎回之前拿它与
+    /** 卡上点的是 `allow_session` ⇒ `"session"`:与 `/decide` 体上的 `remember:"session"` 是**同一只**「本会话放行」请求,交同一个铸点
+     *  (续跑腿 `resumeCheckpoint`;可记与否从同一条停驻行判、落同一只豁免店、只在结清之后落)。缺席 = 只放行这一次的那两个词。 */
+    remember?: "session";
+    /** 发起本次 respond 的**已验证**调用方(live 腿 `gatedSubject` 的那一把)。席在赎回之前拿它与
      *  **checkpoint 当下的 scope** 对一次(codex R1-[high] 一:收编改写身份之后,任何缓存的属主判据都
      *  过期;门必须贴在当下的持久事实上)。 */
     principal?: string;
@@ -153,14 +171,23 @@ export interface ParkedAskRedeemRequest {
      *  缺席 ⇒ 那条腿按「无请求」形处置(它自己的成文语义,本席不替它决定)。 */
     httpReq?: IncomingMessage;
 }
-/** [ref]:赎回席(装配层注入;缺席 ⇒ PARKED 臂逐字回落修前 404)。回的是赎回腿的原始 HTTP 结果面。 */
-export type ParkedAskRedeem = (req: ParkedAskRedeemRequest) => Promise<{
+/** [ref]:赎回席的结局 = 赎回腿的原始 HTTP 结果面 + 请求带了 `remember` 时铸点的真答(`rememberApplied`:落没落;不进 `body` —— 首次受理的回执挂它,
+ *  受理回执(幂等回放的那一份)不存它)。 */
+export interface ParkedAskRedeemResult {
     status: number;
     body: Record<string, unknown>;
-}>;
+    rememberApplied?: boolean;
+    /**
+     * [ref]:这次赎回所决的那道门的世代(席读到的那一行 checkpoint 的世代号,core `checkpointRevOf`)—— 受理回执的键的一半,由**真正决了它的那一席**交回。
+     * 生产席读到行之后的每一答都带(行读不到的拒答不带);缺席 ⇒ 回执说不出这一代 ⇒ 照旧回放({@link receiptAnswersNow})。
+     */
+    gateGeneration?: number;
+}
+/** [ref]:赎回席(装配层注入;缺席 ⇒ PARKED 臂逐字回落修前 404)。 */
+export type ParkedAskRedeem = (req: ParkedAskRedeemRequest) => Promise<ParkedAskRedeemResult>;
 /**
  * 一张门被引擎**重开**过的停驻卡([ref]):决过之后,续跑腿在被批准的动作开跑之前失败,引擎把同一张门(同一把 token)翻回待决。
- * `reason` = core 记在行上的重开因由词原样(闭集 `REOPEN_REASONS`:`env_failed` 同一个决议经耐久回决口(`decidePath`)再交一次即可续跑 —— 本副本还留着首次受理回执时(缺省 1 小时内、未被容量帽逐出)应答口回放那张回执、不驱续跑;`tool_unavailable` / `constraint_rejected` 要重新决;`config_refused` 改好部署配置后再交原决议,或重新决);
+ * `reason` = core 记在行上的重开因由词原样(闭集 `REOPEN_REASONS`:`env_failed` 同一个决议再交一次即可续跑(两扇决议口都行:应答口的受理回执键带门世代,重开之后不再回放首次受理,[ref]);`tool_unavailable` / `constraint_rejected` 要重新决;`config_refused` 改好部署配置后再交原决议,或重新决);
  * `decision` / `decidedAtMs` / `decisionNote?` = 重开之前的那次决议(读法与已结算门的 `decided` 同一只;读不出 ⇒ 三键缺席,只带因由词)。
  */
 export type ReopenedGate = {
@@ -174,6 +201,7 @@ export type ReopenedGate = {
 /**
  * 按问读口对一张 `PARKED` 卡的**门读法**([ref];判官的唯一属主 = `approval-gate-currency.ts`,协调器本身不认识 checkpoint 的形):
  *  · `open` —— 这张卡的门仍是该会话当前待决的审批门(应答口收得下)⇒ 读口说 `parked`;门被引擎重开过 ⇒ 另带 `reopened`([ref],{@link ReopenedGate});
+ *    `generation` = 这道门此刻的世代号(core `checkpointRevOf`:每一次 resolve / reopen 都推它)—— 应答口受理回执的键的一半([ref]:重开 = 新一代 = 新键);
  *  · `decided` —— 门已被决:方向 / 时刻 / 理由取自 checkpoint 上的结算赢家 ⇒ 读口说 `decided`;
  *  · `void` —— 门已过期 / 被取代(含停驻 run 被取消:取消先把门 expire)⇒ 读口说 `void`(没有人决过它,答案无处兑现);
  *  · `unknown` —— 说不出可信的话:`row_absent` = checkpoint 行没了;`decision_unreadable` = 门已结算却读不出可用的决议(行的 status 词或结算种类不在闭集表里 / 结算记录过不了 core 的
@@ -182,6 +210,7 @@ export type ReopenedGate = {
  */
 export type ParkedGateReading = {
     readonly kind: "open";
+    readonly generation: number;
     readonly reopened?: ReopenedGate;
 } | {
     readonly kind: "decided";
@@ -315,9 +344,8 @@ export declare function standingAnswerDurablyRecordable(facts: StandingAnswerFac
  * 答 `false`(两腿同一个问题、两份事实覆盖;两腿复审同报)。三格各自的来源(全在**这一条**已属主校验的载入行上,不另读):
  *  · `governanceForced` —— 行上的治理标:`gate.riskDescriptor.shellGateDoctrine` × 本部署治理姿态,经 **同一只**
  *    `governanceOriginOf`(`runtime-governance.ts`;运维队列 `projectPendingForWire` / 409 体同一个属主,不另判)。它在
- *    本读者这里只**收窄**(失真两个方向的代价登记在 `governanceMandatesShellGateAlways` 顶注)。⚠️ 它**只覆盖 shell 门的
- *    `always` 档** —— live 腿的治理标来自进程内标记表(敏感写路径 / `commandPolicy` / `AUTONOMY` 内层策略 / shellGate 各档),
- *    park 行上唯一的取证格只有 `riskDescriptor.shellGateDoctrine`(见下方 🚧);
+ *    本读者这里只**收窄**(失真两个方向的代价登记在 `governanceMandatesShellGateAlways` 顶注)。它**只归因 shell 地板 `always`**;
+ *    治理层别的源产的停驻卡不靠这一格 —— 它们由行上的 `mandated` 与类集判(见下方「治理产的停驻卡」段);
  *  · `requiresRealApproval` —— 行上 core 铸的那一位,经 `approval-card.ts` 的 {@link readParkRowTrueSeat}(与运维
  *    队列 `parkRowFacts` 同一只读法,`=== true`)。刻意**不**经 `parkRowFacts` 本身:那只展示投影顺手对 `ruleOffersAbsence`
  *    的集外词计展示面 F 类 tag,而本读者对同一格是 fail-closed([ref] codex r1 钉「权限面不计展示面 tag」);
@@ -328,12 +356,14 @@ export declare function standingAnswerDurablyRecordable(facts: StandingAnswerFac
  *    充分条件),而 [ref] 之前铸的行(7.30.x 引擎 park、升级后才被 `/decide`)没有孪生座 —— 只读孪生座会让这类在飞行照旧落豁免,
  *    是对上一版的回归;读不出按强制是 fail-closed(一个本仓不认识的新词可能正是一种强制因由)。
  *
- * 🚧 **剩余不对称一处**(耐久腿读得到的事实比 live 腿少,读不到的一律照旧可记):
- *  ① (已关,[ref] 二段)`mandated` 孪生位 —— core [ref] 到货,行上词为 `shadowed` / 缺席的强制卡由孪生座读到
- *    (`test/approval-exemption-http.test.ts` 原 🚧 格已按钉翻成「false + 零行」);
- *  ② **非 shell 治理(候 [ref])**:治理位经 `governanceOriginOf` 只覆盖 shell 门 `always` 档;敏感写路径
- *    (`SENSITIVE_WRITE_PATTERNS`)、`commandPolicy`、`AUTONOMY` 内层策略产的门与 shellGate `classify` 档,park 行上没有取证格
- *    (live 腿靠进程内标记表,跨副本 / 重启后够不着),本折法读不到它们的治理出身。
+ * **治理产的停驻卡**(与 live 腿同答,不靠 `governanceForced` 这一格):本仓治理层逐叶给自己的 ask 盖部署出身(`operator-ask.ts` 的
+ * `createDeploymentAuthoredPolicy`:`commandPolicy` 的 ask 臂与守卫集),引擎对盖了出身的问铸 `mandated`、停驻行上同铸孪生座(`mandated` / `authoredBy`);
+ * shell 地板 `always`(`AUTONOMY=ask` / `MANUAL_MODE_SHELL_GATE=always`)的问由引擎铸 `mandate:"operator_always"`,同为 `mandated`。⇒ 治理产的停驻卡
+ * 在本折法里恒 `mandated:true`,行上类集也带规则清不掉的类(`operator_forced` / `shell_floor`)—— 两件各自接住、判据答不可记,且不随部署姿态热改而变
+ * (行上是铸行那一刻的事实)。守卫集的模式叶对守卫段上的写只产 deny(不停驻);同一守卫集在部署有本地店根时随挂的会话誊本门产 ask,
+ * 同样盖了部署出身 ⇒ 停驻行 `mandated`、不可记。
+ * 真引擎读数钉在 `test/governance-park-standing-answer.test.ts`(四源逐格)。`governanceForced` 这一格在停驻读面上仍只是 shell 地板的展示归因
+ * (运维队列行 / 409 体同读 `governanceOriginOf`):卡上(问账行的 `card_json`)才有铸卡那一刻的全量治理标 —— 停驻读面改读卡,要等「停驻卡按问的身份读」那一步。
  */
 export declare function parkRowStandingAnswerFacts(stored: Extract<PendingAction, {
     kind: "tool_approval";
@@ -840,52 +870,25 @@ export interface LivePendingRow {
     consumerState?: typeof ASK_DECISION_CONSUMER_ABSENT;
 }
 /**
- * 一条执行腿的审批上下文 = 腿的身份三位 + 腿轴 + **恰一个帧族的投递口**。
+ * 一条执行腿的审批上下文 = 腿的身份三位 + 腿轴 + **帧族词 + 一只同族传输**。
+ *
+ * 🔴 **一条腿一个帧族**({@link ApprovalLegFamily}):呈卡协议在本腿上场(装配点按 `resolveApprovalLeg(...).active`)⇒ 族词 `approval_request`,
+ * 本腿上一只 ask 的开卡 / 消卡 / 撤卡只走呈卡族(`approval_request` / `approval_complete` / `approval_revoke`),旧族帧一帧不发;协议未上场 ⇒
+ * 族词 `tool_approval`(`tool_approval` / `tool_approval_complete`)。传输按族定型:呈卡族上下文的传输收不进旧族帧,「同一只 ask 在同一条腿上
+ * 发两种开卡帧」不可构造。消费方在 wire 上判别本腿是哪一族:`GET /v1/capabilities` 的 `streamApproval`(与装配点同一只判据
+ * `resolveStreamApprovalGate`,按 worker 求值;为真 ⇒ 本 worker 每条呈卡的腿都是呈卡族)。
  *
- * 🔴 **一条腿一个帧族**({@link ApprovalLegFamilyPorts}):呈卡协议在本腿上场(装配点按 `resolveApprovalLeg(...).active` 接
- * `emitCard`)⇒ 本腿上一只 ask 的开卡 / 消卡 / 撤卡只走呈卡族(`approval_request` / `approval_complete` / `approval_revoke`),
- * 旧族帧一帧不发;协议未上场 ⇒ 只走旧族(`tool_approval` / `tool_approval_complete`,经 `emit`)。两族的口在类型上互斥,
- * 「同一只 ask 在同一条腿上发两种开卡帧」不可构造。消费方在 wire 上判别本腿是哪一族:`GET /v1/capabilities` 的 `streamApproval`
- * (与装配点同一只判据 `resolveStreamApprovalGate`,按 worker 求值;为真 ⇒ 本 worker 每条呈卡的腿都是呈卡族)。
+ * 传输是本腿**一只**(问题 / 表单两只协调器的上下文共用同一只;律在 `hitl-delivery.ts`:先本 run 账本、再直写,账本落不下 ⇒ 不上直写)。
  */
-export type ToolApprovalRunContext = ToolApprovalRunContextBase & ApprovalLegFamilyPorts;
-/** 帧族投递口的二选一(见 {@link ToolApprovalRunContext} 顶注)。 */
-export type ApprovalLegFamilyPorts = LegacyApprovalFamilyPorts | CardApprovalFamilyPorts;
-/** 旧族腿(呈卡协议未上场):开卡 `tool_approval` 与消卡 `tool_approval_complete` 都经 `emit`。 */
-export interface LegacyApprovalFamilyPorts {
-    emit: (frame: ToolApprovalFrame) => void | Promise<void>;
-    emitCard?: never;
-    emitRevoke?: never;
-}
-/** 呈卡族腿(呈卡协议上场):开卡 / 消卡经 `emitCard`,批级撤卡经 `emitRevoke`。 */
-export interface CardApprovalFamilyPorts {
-    emit?: never;
-    /**
-     * [ref] 车6:**批级撤卡帧**(`approval_revoke`,语义与发射面见 approval-card.ts 的
-     * `ApprovalRevokeFrame` 顶注 —— [ref] 起 bg/resume durable 腿的钩子写本腿账本,sync 腿仍 live)
-     * 的投递口。
-     *
-     * 与 {@link CardApprovalFamilyPorts.emitCard} 分口的理由是**失败语义**不同:开卡帧的投递结果参与「卡送到人手上没有」的判定
-     * (零 sink 接下 ⇒ 抛 ⇒ park 路由),撤卡帧是通知、行才是真源(失败由 `emitRevokeTo` 的 catch 如实吞);且 sync 腿的撤卡帧
-     * 刻意维持 live 单口(detach 账本撤帧是另一件行为面变更)。
-     *
-     * 缺席 ⇒ 本连接不收撤卡帧;壳侧的结构补偿恒是重连 preamble 的全量对账基准。
-     * (接线现状:[ref] 起三腿全接 —— sync 腿 live 口(`routes/tasks.ts`),bg/resume 两腿 durable
-     * append(`runs.ts` / `http/server.ts`),与 `emitCard` 的三腿同批对齐。)
-     */
-    emitRevoke?: (frame: ApprovalRevokeFrame) => void | Promise<void>;
-    /**
-     * 呈卡族的**单卡帧**投递口:开卡帧(`approval_request`,[ref] §3.1)与消卡帧(`approval_complete`)。
-     *
-     * 三条装配腿都把它接到本腿的投递面(sync 腿 live SSE + detach 车道账本,bg / resume 腿本腿账本;双 sink 的成败判定在唯一
-     * 属主 `createApprovalCardEmitter`)—— 卡帧在哪,消卡帧就在哪。开卡帧只在 `askId` **确认落盘**时铸(设计稿 §2.2(b) 硬条款一:
-     * 无持久身份不发帧);本腿没有旧族兜底 ⇒ 身份没落盘的 ask 在呈卡腿上**呈不出卡**,按无人可答收场(协调器 `askBroadcast`)。
-     *
-     * 第二参 `registration` = 协调器这一次**登记**的本地 id(每次注册各一个,同一只 ask 的重复登记各不相同):同一次登记的开卡帧与消卡帧
-     * 带同一个值,投递口据它把开与合配对(帧上的 askId / approvalId 在重复登记之间相同,配不了对)。它不上 wire。
-     */
-    emitCard: (frame: ApprovalCardLegFrame, registration: string) => void | Promise<void>;
-}
+export type ToolApprovalRunContext = ToolApprovalRunContextBase & ApprovalLegFamily;
+/** 帧族词 + 同族传输(见 {@link ToolApprovalRunContext} 顶注)。族词取自 {@link APPROVAL_FRAME_FAMILIES} 闭集。 */
+export type ApprovalLegFamily = {
+    readonly family: "approval_request";
+    readonly transport: HitlTransport<ApprovalCardLegFrame | ApprovalRevokeFrame>;
+} | {
+    readonly family: "tool_approval";
+    readonly transport: HitlTransport<ToolApprovalFrame>;
+};
 /** 两族共有的腿身份与腿轴。 */
 interface ToolApprovalRunContextBase {
     taskId: string;
@@ -1133,7 +1136,7 @@ export declare function resolveStreamApprovalGate<TStore extends GateCurrencySto
  *  · `tool_approval`:旧族(活卡帧 `tool_approval` / 消卡帧 `tool_approval_complete`);
  *  · `approval_request`:呈卡族(开卡帧 `approval_request` / 消卡帧 `approval_complete` / 批级撤卡帧 `approval_revoke`)。
  *
- * 一条腿选哪个族只由上面 {@link resolveStreamApprovalGate} 的 `active` 定(为真 ⇒ 接呈卡族的口 `emitCard` / `emitRevoke`;为假 ⇒ 只接旧族的口 `emit`,
+ * 一条腿选哪个族只由上面 {@link resolveStreamApprovalGate} 的 `active` 定(为真 ⇒ 上下文的族词 `approval_request`;为假 ⇒ `tool_approval`,
  * 见 {@link ToolApprovalRunContext});`GET /v1/capabilities` 的 `approvalFrameFamilies` 把**同一份**判据结果(能力事实 `streamApproval` 的那一次求值)
  * 译成本词表里的词(`capability-facts.ts` 的 `approvalFrameFamilies`,对判据拒因的穷举 switch:拒因多一个 ⇒ 编译红)。
  * 腿选口的规则与能力位的映射是同一条,由 `test/stream-approval-on-e2e.test.ts` 在同一台 worker 上拿真腿发出的开卡帧族对拍能力位,不靠注释互相提醒。
@@ -1232,8 +1235,8 @@ export interface ApprovalLegInput {
  * 旧文「bg/resume 无装配点,不包 ALS 即等价」的缺席论证已退役,别再据它推断「少装一件也行」。
  */
 export interface ApprovalLegAssembly {
-    /** 协议在本腿上是否上场。false ⇒ **既不包 ALS、也不接** `emitCard`/`emitRevoke`/`legKey`/
-     *  `legDeadlineMonotonic` —— **协议件**逐字保持协议之前的行为。
+    /** 协议在本腿上是否上场。false ⇒ 呈卡族的上下文不接(族词 `approval_request`、`legKey` /
+     *  `legDeadlineMonotonic` 都不接)—— **协议件**逐字保持协议之前的行为。
      *  ⚠️ [ref] 门职分离(codex R1-F1 随修):本位**不再兼职**「审批席在场性」—— `spec.onAsk = boundAsk`
      *  三腿恒装(判据 = 协调器在场,即 `TOOL_APPROVAL_ENABLED`),协议关时 bg/resume 腿的 ask 也能命中
      *  同 (owner, session) 活流呈活卡(sync 腿 [ref] 起本就如此;bg/resume 的这条行为差 = [ref] CHANGELOG
@@ -1253,32 +1256,6 @@ export interface ApprovalLegAssembly {
      *  有 walltime 墙` 时在场 —— 关着时供值会把既有 5min 活卡窗按三元公式缩短(§7.2 真行为变更)。 */
     legDeadlineMonotonic?: number;
 }
-/**
- * [ref] 车3 刀 3b(codex 交叉复审 round2 R2-1,2026-08-06 真 finding)—— 呈卡腿的**双 sink 投递口**(开卡帧 + 消卡帧)。
- *
- * 🔴 为什么必须收成一个有属主的工厂:「呈卡帧送达」决定「卡到底有没有送到人手上」(见 `emitOne` 顶注;[ref] 起呈卡腿只有这一族)。
- * sync 腿原来那个内联闭包把两个 sink 的失败都吞掉、然后**正常返回** —— 于是「账本写失败 ∧ socket 已死」这种**真的一路都没送到**的
- * 情形被上报成成功,`anySucceeded` 因此压住了 park 路由。诚实的形只有一个:**至少一个 sink 真的接下了才算送达**,一个都没接下就抛 ——
- * 调用点(`emitOne`)的 catch 会把它如实记成没送到。
- *
- * 🔴 **两只 sink 各自推进、各自配对**([ref] codex 一轮 F1 / F2,红先钉在 `test/approval-leg-frame-family.test.ts`):
- *  · 开卡帧同时交两只 sink,**任一只接下即算送达**(不按序串行 —— 旧族退场后 live 面只剩呈卡族这一条路,一只挂住的账本写不能挡住
- *    健康的 live 出口;修前先 await 账本再写 live)。两只都失败才抛。
- *  · 消卡帧只交给**接下过本卡开卡帧**的那只 sink,且排在该 sink 自己的开卡写之后(每只 sink 内开在合前;没接下开卡的 sink 不收消卡 =
- *    不留孤儿消卡行)。没有任何 sink 接下过开卡 ⇒ 不投(调用点本就只对送达过开卡的连接发消卡)。
- *  · 配对按**登记**记(第二参 `registration` = 协调器那一次登记的本地 id;codex 修复验证轮 V1:按 askId 先进先出会让第二次登记的消卡取走
- *    第一次失败 / 挂起的开卡记录)。开卡全失败的登记当场清账(它不会有消卡);消卡取走即清;挂住的开卡留账到本腿闭包结束。
- *
- * detach 车道的用武之地仍是「live 面已死、账本还在」(§4.3(c) 的案A):那一形里 live 抛、账本接下 ⇒ 送达;消卡只进账本。
- *
- * 命名(CLAUDE.md 工厂命名律):`create*` —— 返回的是**捕获了两个 sink 与配对账的闭包**,不是纯数据。
- */
-export declare function createApprovalCardEmitter(sinks: {
-    /** durable 账本口(bg/resume 腿恒有;sync 腿只有 detach 车道有)。抛 = 这一路没接下。 */
-    appendDurable?: (frame: ApprovalCardLegFrame) => Promise<void>;
-    /** live SSE 口。**已死的流应当由调用方判成缺席或让它抛**,不要写一个静默 no-op —— 那正是本 finding。 */
-    writeLive?: (frame: ApprovalCardLegFrame) => void | Promise<void>;
-}): (frame: ApprovalCardLegFrame, registration: string) => Promise<void>;
 export declare function resolveApprovalLeg(input: ApprovalLegInput): ApprovalLegAssembly;
 /**
  * 🔴 **开流 preamble 往本连接投卡与否的唯一判据**([ref] / H5)—— 两条 preamble 共用:sync 腿(`routes/tasks.ts`,入参的声明读本次请求的 `settings`:
@@ -1291,8 +1268,9 @@ export declare function approvalPreambleReplays(input: Omit<ApprovalLegInput, "n
 /** 一条 **DECIDED 行**能交还给引擎的全部形(`AskOutcome` 减掉 park 路由那一臂 —— 一条有决议的行
  *  从定义上不是「投递面拿走了它」)。{@link ToolApprovalCoordinator.notifyExternalDecision} 收的就是它。 */
 export type DecidedAskOutcome = Exclude<AskOutcome, "unavailable">;
-/** 铸点的入参形 = 行上与**这条决议本身**有关的三格。整行(`AskRow`)与 claim 败方读数都满足。 */
-type DecidedRowFacts = Pick<AskRow, "decision" | "settledBy" | "decidedVia"> & {
+/** 铸点的入参形 = 行上与**这条决议本身**有关的四格。整行(`AskRow`)与 claim 败方读数都满足。
+ *  `decisionNote` 与 `settledBy` / `decidedVia` 同律**必填**(可空)—— 可选会让一个漏挑这一列的投影静默编译过,而漏挑的后果正是把带说明的拒交成裸拒。 */
+type DecidedRowFacts = Pick<AskRow, "decision" | "settledBy" | "decidedVia" | "decisionNote"> & {
     updatedInput?: unknown;
 };
 /**
@@ -1303,12 +1281,17 @@ type DecidedRowFacts = Pick<AskRow, "decision" | "settledBy" | "decidedVia"> & {
  * 重放 / 兄弟广播 / 歧义提交恢复三条路上全都退化成裸 `false`,而裸 `false` 在 core 那边逐字是
  * 「**一个人**拒绝了」。手抄投影全面下线([ref]):消费点交行,形由这里铸。
  *
- * 三条读法,每条的属主注在别处,这里只落笔:
+ * 四条读法,每条的属主注在别处,这里只落笔:
  *  · **方向** —— `decision !== "approve"` 即拒(列的二值由店的 CAS 保证);
  *  · **编辑载荷**([ref])—— `updatedInput` 键缺席 = 没带编辑 ⇒ 裸 `true`;在场(**含 `null`**)= 编辑的
  *    字面值 ⇒ 对象臂(语义三态的唯一属主 = `AskRow.updatedInput` 顶注);
  *  · **结算来源**([ref])—— 行上非 null 即宿主自报的那个词(`null` = 人决,与「不铸这个键」同义;
- *    语义属主 = `AskRow.settledBy` 顶注)。
+ *    语义属主 = `AskRow.settledBy` 顶注);
+ *  · **拒因**([ref] 的行派生半场)—— 拒行上**非空**的 `decisionNote` 铸成 `reason`(与应答口 `shapeDeny` 同键同形:core 以带说明的人拒句
+ *    把它交给模型,围栏 `delimitUntrusted` 与长度上限 `REVIEWER_NOTE_MAX_BODY` 全在 core,本仓只透传不预判;空串按 core 契约的缺席读,不铸只装了
+ *    空值的对象臂)。**allow 行的说明恒不铸**:core 对 allow 行的 `reason` 恒销毁,说明只走审计面(行的 `decisionNote` 列)。
+ *    此前这一格不在铸点里 ⇒ 耐久决断口 / 重放 / 兄弟广播 / claim 败方 / 歧义提交恢复 / 悬挂轮询六条行派生的路,都把带说明的拒交成裸 `false`
+ *    (core 读作「一个人拒了、没说怎么办」:STOP 句 + 本轮收住),而同一段说明经应答口到达却带着 `reason` 进模型 —— 一扇门两种去向。
  *
  * 🔴 [ref]:来源位**两向都读**。决定体的出处位 `decidedBy:"policy"` 在 allow 与 deny 上都会落列(引擎 7.39.0 起铸
  * `policy_allowed`),所以 approve 行带来源位是一条合法的行,它的每条读回路径交还 `{allow:true, settledBy:"policy", updatedInput?}`
@@ -1421,7 +1404,7 @@ export declare class ToolApprovalCoordinator {
      *  ask 的 `sessionId` 咨询一次——「这次授权是在**哪里**点的」在授权发生时捕获,不在回决时再猜。
      *  回 `undefined` = 该部署形上 run 的 workspace root 不可知(远程沙箱/多租户等)⇒ 不铸 scope,落
      *  core 的 global 缺省(= 现行为,恒不更宽;也绝不错铸一个坐标系不对的 root)。装配见 main.ts:
-     *  registry cwd(host lane 显式注册的 launch dir)?? in-process 单用户形的 `process.cwd()`。 */
+     *  registry cwd(host lane 显式注册的 launch dir)?? 无手(`none`)单用户形的 `process.cwd()`。 */
     private readonly ruleScopeRootFor;
     /** [ref]:停驻行迟到决议的受理回执表(键 = 行的键 `askId`,插入序 = 逐出序)。语义与有界理由见
      *  {@link ParkRedemption} 顶注。 */
@@ -1605,7 +1588,7 @@ export declare class ToolApprovalCoordinator {
     /**
      * [ref] 车二:一只 ask 的**规则车道素材**,或 `undefined`(= 本 ask 不投候选、不接受 `persistRule`)。
      *
-     * 三个合取项(缺一即 `undefined`,理由逐字见调用点上方注):①店在场 ②引擎铸了候选 ③命令原字节可读。
+     * 三个合取项(缺一即 `undefined`,理由逐字见调用点上方注):①店在场 ②引擎铸了候选 ③卡形的绑定值读得出(见 `cardBindingOf`)。
      * `req.args` 是 `unknown` ⇒ 窄读,**禁裸 as-cast**(宪法 [ref]:一个形状漂了的 args 若被 cast,
      * 会把 `undefined` 当命令送进 `prepareCardApproval`,那是放宽面上的静默垃圾)。
      */
@@ -1639,22 +1622,24 @@ export declare class ToolApprovalCoordinator {
     /** 兑付侧座(single 的 rule/command、command 成员的 rule/command、directoryRead 成员的 rule/directory)任一超尺?
      *  `segment` 与 `uncoveredDetail[].segment` 是纯渲染座,不在此列(截长是诚实省略)。 */
     private static ruleOfferTextsOverSize;
-    /** codex r1 [high]([ref]):offer 的自称座与 `parseRuleText(rule, "allow")` 派生的三元组逐字一致?(理由见调用点) */
+    /** codex r1 [high]([ref]):offer 的自称座与 `parseRuleText(rule, "allow")` 派生的三元组逐字一致?(理由见调用点)`cardTool` = 这张卡的工具(`req.toolName`)。 */
     private static ruleOfferDerivedFactsAgree;
     /**
-     * 一只 single 候选的工具与它的匹配词对得上吗(卡上的 single 只有两族):命令形(exact / prefix / wildcard / pattern)⇒ 规则是 shell 的;
-     * 整工具(`tool`,core 7.57.0:没有规则词替它说话的工具的卡铸「这只工具不再问」)⇒ 工具必须是一键整工具同意落得下的那一族
-     * ({@link cardTakesWholeToolConsent}:没有自己的规则文法、不在 shell 面上 —— 一张 shell 卡上的整工具候选 = 一键放行每一个程序,引擎不铸,兑付时也兑不动)。
-     * 其余匹配词(路径 / 名字 / 主机)不是本服务卡面的 single 候选 ⇒ 丢(那些卡今天没有本服务的规则车道)。穷举 `switch`:core 给匹配词加员时这里编译红。
+     * 一只 single 候选属于这张卡吗 —— 一条规则:**它的规则文本点名的就是这张卡的工具,且它的匹配词的卡形就是这只工具的卡形**(两只读法都在
+     * `permission-rule-vocab.ts`:{@link cardRuleFormOf} / {@link CARD_RULE_FORM_OF_MATCH})。core 为一张卡铸的 single 恰是这一形:shell 卡上的命令规则、
+     * 名字 / 主机工具卡上那一条精确值规则、没有规则词替它说话的工具卡上的整工具规则;兑付侧 `prepareCardApproval` 按「这张卡的工具 + 绑定值」重铸,
+     * 别的形 / 别的工具的候选在那里恒兑不动 ⇒ 渲出来就是一格按不动的「不再询问」。丢(与本文件其余撤回 / 丢弃臂同一方向:少渲一格是安全方向)。
      */
-    private static singleOfferToolAgrees;
+    private static singleOfferBelongsOnCard;
     private static boundRuleOfferTexts;
     /**
-     * 这张卡的**绑定值**(`prepareCardApproval` 的 `command`,也是耐久行的 `rule_command`)= 引擎为这张卡铸的候选所说的那一形(core 只按卡的规则形铸候选):
-     *  · 候选全是整工具候选(`match: "tool"`,core 7.57.0;至少一只)⇒ `""` —— 整只工具不绑任何值;core 恰在 `command` 是 `""` 时为这类工具铸卡;
-     *  · 其余(命令形候选,或读者把候选丢光了)⇒ 被裁决的命令原字节 `args.command`(非空串;读不出 ⇒ 没有素材)。空候选表不说「整工具」:
-     *    它什么形都没说,绑定值回到调用自己的命令(编辑面兑的就是它)。
-     * 两形混在一张卡上 = 不是 core 铸得出的卡 ⇒ 没有素材(整条车道撤回,与本文件其余撤回臂同形)。`req.args` 窄读,禁裸 as-cast。
+     * 这张卡的**绑定值**(`prepareCardApproval` 的 `command`,也是耐久行的 `rule_command`)= **卡形的绑定值**(core `prepareCardApproval` 对 `command` 入参的逐形定义):
+     *  · 值形(整工具 / 名字 / 主机:core 对这三形只铸**一只** single,它的 `command` 座就是那个值 —— 整工具 `""`、名字工具是调用带的名字、主机工具是调用到达的主机)
+     *    ⇒ 那一只候选自己的 `command`;
+     *  · 其余(命令形候选 / 批,或读者把候选丢光了)⇒ 被裁决的命令原字节 `args.command`(非空串;读不出 ⇒ 没有素材)。空候选表不说任何值形:
+     *    绑定值回到调用自己的命令(编辑面兑的就是它)。
+     * 候选走到这里之前已过 {@link singleOfferBelongsOnCard}:每只 single 都是这张卡的工具、这只工具的卡形 ⇒ 值形与命令形不会同卡。值形候选不止一只 = 不是 core 铸得出的卡
+     * ⇒ 没有素材(整条车道撤回,与本文件其余撤回臂同形)。`req.args` 窄读,禁裸 as-cast。
      */
     private static cardBindingOf;
     private buildRuleLaneMaterial;
@@ -1762,7 +1747,7 @@ export declare class ToolApprovalCoordinator {
      * 进程内表(按能力桶,[ref]② 修2)或耐久 `/decide` `remember:"session"` 的豁免店(按 canonical 工具名,`/decide` 写的同一只店;
      * 读失败 ⇒ 不命中 = fail-closed,人多看一张卡而不是被静默代答)∧ ④ 行上没有与本地 peek 矛盾的出处({@link sessionGrantUncontestedByRow})。
      *
-     * **两个读位、一只店、按问句的作者分**(收车档 ⑩ 16):本席兑现**引擎自装的问**(模式写门 / 形状层 —— core 7.34.0 起它们是引擎
+     * **两个读位、一只店、问的人按自己这一问的事实读**(收车档 ⑩ 16):本席兑现**引擎自装的问**(模式写门 / 形状层 —— core 7.34.0 起它们是引擎
      * 自己的层、不读任何豁免,折叠 ask 赢 ⇒ 策略层探针对它们恒无效,codex F2;7.133.0 起 acceptEdits 的写也只有引擎模式门这一问);
      * **本仓自己的问**(durable 名单门、workflow 问句门)照旧在各自的层上读同一只店「不问」。为什么两处都要:子代经父约束链继承到的问到达祖先审批席时 core
      * 盖 `mandated`(`ruleClearanceOf` 的 inheritedUnresolved / ancestorResolved 门),本席依约不退役 —— 只有策略层的「不问」够得着继承链
@@ -1930,13 +1915,11 @@ export declare class ToolApprovalCoordinator {
         settled: number;
     };
     /**
-     * [ref] 车6:把一张**批级撤卡帧**投给给定的一组连接(逐 ctx 分发 —— 见 `ApprovalRevokeFrame` 顶注:
-     * [ref] 起 durable 腿的钩子把帧落进本腿账本、sync 腿仍 live;丢帧的结构补偿是重连 preamble 的
-     * 全量对账基准)。
+     * [ref] 车6:把一张**批级撤卡帧**投给给定的一组连接 —— 逐 ctx 经本腿那一只传输(`deliverHitlNotice`:先本 run 账本、再直写,
+     * 与开卡帧同一条律、同一条账本链;账本里的序 = 入链序)。只有呈卡族的腿收撤卡帧(旧族没有撤卡帧)。
      *
-     * 空名单不发(零信息的帧只会让壳多一次无意义的对账)。每路独立 catch:一路 emit 失败(连接刚死、
-     * durable-append 目标抖动)**绝不回滚已经落定的持久 CAS** —— 帧是通知,行才是真源。[ref] 的 durable
-     * append 失败同落这只 catch(不新铸失败臂;账本行 VOID 是真源,撤帧丢失由 preamble 对账补偿)。
+     * 空名单不发(零信息的帧只会让壳多一次无意义的对账)。投递永不 reject、**绝不回滚已经落定的持久 CAS** —— 帧是通知,行才是真源;
+     * 没送到记一次 `server.hitl.close-frame-dropped`,壳侧的结构补偿是重连 preamble 的全量对账基准。
      */
     private emitRevokeTo;
     /**
@@ -1997,11 +1980,11 @@ export declare class ToolApprovalCoordinator {
     /** 广播版裁决路径——`ask()`(ALS,恒单元素数组)与 `boundAsk`([ref]四多活集合,可能多元素)共用。
      *  全体 `ctxs` 保证同一 (owner, sessionId)(streamKey 分组不变式;单元素数组平凡成立)。
      *
-     *  [ref]三 emit-race 加固(回黑板 [ref]三1,core 确认方向):「等 emit 完成」与「等
-     *  TTL/abort/respond 三选一落定」显式 race——`emit` 的类型契约允许异步实现(durable-append 目标),
-     *  若挂死,旧形 `await ctx.emit(...)` 会让整条 ask 乃至调用方 turn 一起卡死,TTL/abort 定时器虽已
-     *  触发也无人读取其结果。核心不变式:race 由非人类结局(TTL/abort)先赢、且 emit 广播尚未有任何一路
-     *  确认完成时,不可扣一个武断的「deny」终局(不知道卡是否曾送达任何人)——按 G1 回路交
+     *  [ref]三 emit-race 加固(回黑板 [ref]三1,core 确认方向):「等开卡投递全部落定」与「等
+     *  TTL/abort/respond 三选一落定」显式 race——投递先落账本(异步),若挂死,裸 await 会让整条 ask 乃至
+     *  调用方 turn 一起卡死,TTL/abort 定时器虽已触发也无人读取其结果。核心不变式:race 由非人类结局
+     *  (TTL/abort)先赢、且开卡广播的**全部目标尚未落定**时,不可扣一个武断的「deny」终局(不知道卡是否
+     *  曾送达任何人)——按 G1 回路交
      *  "unavailable"。人类 respond() 落地的裁决永远照旧信任、不受本判据影响:它只可能在 approvalId 已经
      *  送达某个客户端之后发生(respond 需要客户端手上有这个 id),这是 outcome==="allowed"/"denied" 与
      *  "expired"(TTL/abort/run-exit-cleanup/emit 广播全灭四类共用)的天然分野。 */
@@ -2010,7 +1993,7 @@ export declare class ToolApprovalCoordinator {
     private askBroadcastCounted;
     /** `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
-     *  layer owns auth (gatedPrincipal + REQUIRE_PRINCIPAL) before calling.
+     *  layer owns auth (gatedSubject + REQUIRE_PRINCIPAL) before calling.
      *
      *  [ref] 车2(D1/D2):return type 是 UNION,不是把整个方法标 `async`——askStore 缺席时这个方法逐字同步
      *  完成(D1 现行为不变;现存量测试对它的同步断言/`void` 调用零改动)。在场时才真的变成 Promise(D2 的
@@ -2046,7 +2029,7 @@ export declare class ToolApprovalCoordinator {
      *  `judgedOwner` = 这次决议的门判过的那位属主([ref]:一次决议只读一次属主 —— 决议 CAS、会话放行、规则落店、豁免记账都用这一份,不回头重读登记上的那一格)。 */
     private afterLiveDecision;
     /**
-     * **部署名单(`APPROVAL_REQUIRE`)那一问的「本会话放行」只落 server 的会话豁免店**(谁问的,谁的站着的答案算数):名单的问是 server 铸的,
+     * **部署名单(`APPROVAL_REQUIRE`)那一问的「本会话放行」只落 server 的会话豁免店**(问的人按自己这一问的事实决定退不退):名单的问是 server 铸的,
      * 名单门在出问之前读这只店(键 = 会话 × wire 工具名,与耐久 `/decide` 的 `remember:"session"` 写下的同形),命中就不出问 —— 引擎看到的
      * 是「这次调用没出问」。不铸进程内授权(那是审批席替引擎的问记的答案;本席不代答名单的问),不交任何东西给引擎的规则店。
      *
@@ -2073,15 +2056,22 @@ export declare class ToolApprovalCoordinator {
     /** [ref]:回执上两个新键的**唯一**成形口 —— 只在这次请求真的走了**自由文本臂**时铸。
      *  候选臂的回执因此逐字节不变(老壳按固定键集解析,多一个键就是一次没人要的 wire 变更)。 */
     private editedArmEcho;
-    /** [ref]:`tool_approval.not_pending` 的**唯一**成形口。文案逐字不变(存量壳/SDK 按它认这条 404),
-     *  只 additive 加判别位;`cause` 缺席 = 这台部署没有行可判(D1 无店)或行形不可信(见各调用点)。 */
+    /** [ref]:`tool_approval.not_pending` 的**唯一**成形口 —— 只在已过属主门的面上调(调用方看不见这只问 ⇒ {@link askNotVisible})。文案逐字不变
+     *  (存量壳/SDK 按它认这条 404),只 additive 加判别位;`cause` 缺席 = 这台部署没有行可判(D1 无店)或行形不可信(见各调用点)。 */
     private notPending;
+    /**
+     * 调用方**看不见**这只问的**唯一**成形口(应答口与按问读口同一只):无行 / 行不是调用方的 / 行读不出(不知道属主是谁 ⇒ 属主门 fail-closed)/
+     * 这台部署没有问账可判。404 `not_found.ask` —— 与耐久决断口 `POST /v1/tasks/:taskId/asks/:askId/decision` 的属主门同一个词(两扇门底下是同一只问),
+     * 不带任何状态位:属主门不过与未知 id 逐字节同,404 对看不见它的人不做存在 / 状态神谕。
+     */
+    private askNotVisible;
     /**
      * `GET /v1/tool-approvals/:approvalId` —— **按问读口**:一只 ask 此刻在哪一态({@link TOOL_APPROVAL_READ_STATES})。与 {@link respond} 同根同门
-     * (HTTP 层的鉴权 / 属主身份同一只 `gatedPrincipal`;属主不过与未知同形 404,无存在性谕示),读法与应答口逐条同源:
+     * (HTTP 层的鉴权 / 属主身份同一只 `gatedSubject`;看不见这只问 —— 属主不过 / 查无 / 行读不出 / 没有问账 —— 与应答口同答 404 `not_found.ask`({@link askNotVisible}),
+     * 无存在性 / 状态谕示),读法与应答口逐条同源:
      * 本副本上在等它的活登记({@link liveEntryFor})⇒ `pending`(行投影 = 列表面 `livePending[]` 的同一只投影);否则按 id 读行
      * ({@link askRowFor} + {@link askRowVisibleTo}),行态 → 读态与晚答口的分派同一张表;行仍 `STREAM_PENDING` 而本副本没有在等它的登记 ⇒ 它活在别的副本上,
-     * 与晚答口同答 404 `unknown_or_other_replica`(那里才有兑现它的闭包)。没有 ask 账的部署 ⇒ 晚答口那句 404,不带 `cause`。
+     * 与晚答口同答 404 `tool_approval.not_pending` + `unknown_or_other_replica`(那里才有兑现它的闭包;属主看得见的态)。
      * 纯读:零写、零结算、不碰本地登记(晚答口的 DECIDED 臂会顺手同步本副本的活登记,读口不做)。
      */
     readApproval(id: string, principal: string | undefined): {
@@ -2102,31 +2092,39 @@ export declare class ToolApprovalCoordinator {
     private readAskRowState;
     /**
      * `PARKED` 行的门读法([ref]):问判官「这张卡的门此刻还是不是该会话当前待决的审批门」。行是终态、不随赎回 / 取消改写,所以只有 checkpoint 知道。
-     * 没有门读席 / 行上没有 gate token ⇒ `open`(读口只能说行说的话;应答口对同一张卡的 PARKED 臂此时也答不了受理,不另有第二个答案)。
-     * 读不出(店故障 / 超时)⇒ 按本协调器的店故障姿势(D5:记账 + 一次 warn)退回 `open` —— 这一臂只影响**展示**,应答口对同一张卡仍按自己的判官 fail-closed。
+     * `undefined` = **没读到**:没有门读席 / 行上没有 gate token / 读不出(店故障 / 超时,按本协调器的店故障姿势记账 + 一次 warn)。两个读者各自表态:
+     * 按问读口读作 `parked`(读口只能说行说的话;只影响**展示**,应答口对同一张卡仍按自己的判官 fail-closed);应答口的受理回执读作「说不出这一代」({@link receiptAnswersNow})。
      */
     private readParkedGate;
+    /** [ref]:这张停驻卡的门此刻站开在哪一代 —— 门读席读到它仍是该会话当前待决的审批门 ⇒ 它的世代号;没读到 / 门不在待决 ⇒ `undefined`。 */
+    private openGateGeneration;
     /** 一条行 → 按问读口的答案(行态六态穷举:新增 `AskState` 而不在此表态 = **编译错**)。 */
     private readStateOfRow;
     /**
      * [ref] —— live 未命中之后的**状态感知分派**(设计 §三的那张表)。
      *
-     * 有行的 ask 的 wire 身份就是行的键 ⇒ 按 id **直接读行**(任一副本、重启前后都读得到;不再经任何进程内的桥)。持久店缺席 ⇒ D1 体逐字不变
-     * (没有行可判,编一个 cause 是撒谎);店在场而行不在 / 不是调用方的 ⇒ 404 `unknown_or_other_replica`(那正是「换副本/换端点重试才
-     * 有意义」的那一因;属主不过与未知同形,无存在性谕示)。
+     * 有行的 ask 的 wire 身份就是行的键 ⇒ 按 id **直接读行**(任一副本、重启前后都读得到;不再经任何进程内的桥)。持久店缺席(没有行可判)/ 店在场而行不在 /
+     * 行读不出 / 不是调用方的 ⇒ 调用方看不见这只问 ⇒ 404 `not_found.ask`({@link askNotVisible};属主不过与未知同形,无存在性谕示)。行在、调用方是属主、
+     * 行仍待决而本副本没有在等它的登记 ⇒ 404 `tool_approval.not_pending` + `unknown_or_other_replica`(那正是「换副本/换端点重试才有意义」的那一因)。
      */
     private respondLate;
     /**
      * 新开的 sync 连接经 **preamble** 呈出的卡 → 登记进这条连接的**消卡订阅**(连接的 `approval_complete` 只投给接下过开卡帧的连接 —— 这些卡的开卡帧
-     * 就是 preamble 那一帧)。这几只 ask 在本副本上的最后一条活登记落定时,`deliver` 收一帧 `approval_complete`(与那次 settle 的判决同值)。
+     * 就是 preamble 那一帧)。这几只 ask 在本副本上的最后一条活登记落定时,`deliver` 收一帧 `approval_complete`(落定那一拍铸定的那一只对象)。
      *  · 只订本副本上**此刻在等**的 ask(`pendingByAskId` 有登记):活在别的副本上的 / 订阅之前已经落定的,本副本无从得知它何时落定 ——
      *    那几形的结构补偿仍是下一次 preamble 的全量对账基准(不在基准内的卡一律清)。
-     *  · 投递是 live-only 的通知:`deliver` 抛错 / 连接已死 ⇒ 吞掉(卡的终局是行上的事实,不因通知没送到而改变)。
+     *  · **唯一写者**(订阅与登记之间不双写):本连接(`connection` 交回的那只腿传输)也是这张卡登记的投递目标、且有一次登记的开卡帧被本连接的
+     *    直写接下了 ⇒ 消卡只由登记的收帧写(先账本后直写;账本落不下 ⇒ 本连接 live 也不收;每次登记的收帧配它自己的开卡帧 —— 登记 N 次就是
+     *    N 对开 / 收,与回放同数,消费方按 askId 幂等);否则(卡只经 preamble 呈出,或登记的开卡在本连接上都没送到)⇒ 由本订阅写一帧。
+     *    落定那一拍本连接上还有登记的开卡悬着 ⇒ 本订阅让位到它们落定再判。
+     *  · 投递是 live-only 的通知:`deliver` 抛错 / 连接已死 ⇒ 吞掉(卡的终局是行上的事实,不因通知没送到而改变),留一行。
      * 返回退订口(连接收场时调;投递一次之后自动退订)。
      */
-    watchPresentedCards(askIds: readonly string[], deliver: (frame: ApprovalCompleteFrame) => void): () => void;
+    watchPresentedCards(askIds: readonly string[], deliver: (frame: ApprovalCompleteFrame) => void, connection: () => HitlTransport<ApprovalCardLegFrame | ApprovalRevokeFrame> | undefined): () => void;
+    /** 一次登记的开卡投给了 `transport` 那条连接:订了这只 ask 的、连接就是它的那条订阅记下这次开卡的直写接下与否(唯一写者规则的让位判据)。 */
+    private notePresentedCardRegistration;
     private dropPresentedCardWatcher;
-    /** settle 咽喉调:一只 ask 在本副本上的最后一条活登记落定 ⇒ 给订了它的每条连接投一帧消卡,随即退订。 */
+    /** settle 咽喉调:一只 ask 在本副本上的最后一条活登记落定 ⇒ 订了它的每条连接按唯一写者规则收一帧消卡(见 {@link watchPresentedCards}),随即退订。 */
     private notifyPresentedCardWatchers;
     /**
      * 一个 wire 身份 → 本副本上**此刻在等它**的那一条活登记(应答口与读口共用这一只读法)。
@@ -2271,8 +2269,25 @@ export declare class ToolApprovalCoordinator {
      * (不发帧 —— 问不是被谁答掉的,编一帧消卡就是撒谎;壳的结构补偿仍是下一次 preamble 的全量对账基准)。还有活登记 ⇒ 订阅留给它的结算。
      */
     private forgetAdoptedAsk;
-    /** [ref]:接管登记的属主跟行走 —— 悬挂轮询每读到一次仍待决的行就对齐一次(`/v1/adoption` 改写 `approval_ask.owner` 之后,列表面在一拍之内跟上;应答口与读口另读行当下的 owner)。 */
-    private followAdoptedOwner;
+    /**
+     * 🔴 [ref]:**有行的登记,属主跟行走** —— 本协调器每读到这只问仍待决的行一次(悬挂轮询 / 应答口读行 / 读口读行 / 收编后的重读),就把这只问在本副本上的
+     * **每一条**登记对齐到行上当下的属主。活登记与接管登记同一条(修前只有接管登记跟,活登记的那一格停在铸卡那一刻:收编之后列表面仍按前属主列、
+     * 店写失败 + 确认读也失败的那一支按前属主放行一次)。行的属主只有 `/v1/adoption` 改写;这里只对齐、不判授权(授权照旧在各扇门里按面表判)。
+     */
+    private followRowOwner;
+    /** [ref]:行读的单调序号 —— 每一次会拿来对齐属主的行读在**发起之前**取一个;同一副本内后发起的读看到的行不比先发起的旧(店的单行读按提交序)。 */
+    private rowReadSeq;
+    private nextRowReadSeq;
+    /**
+     * [ref]:**收编落定后的重读** —— `approval_ask.owner` 唯一的写者(`/v1/adoption`)在本副本落成回执后由路由调一次:本副本每一只有行的问点读一次
+     * (带墙钟期限),仍待决 ⇒ {@link followRowOwner}。读不出 ⇒ 记账(与其它店调用同一只 `noteStoreError`)、这只问原样留着上一次读到的属主,不编;
+     * 行没了 / 已终局 ⇒ 不在这里处置(悬挂轮询与应答口各有自己的收法)。射程 = 本副本(多副本部署里别的副本的登记由它们自己的行读跟上;收编的运维前提是先停引擎)。
+     */
+    followRowOwners(): Promise<{
+        read: number;
+        followed: number;
+        unreadable: number;
+    }>;
     /** 这只 askId 在本副本上有几条**有引擎腿在等**的登记(接管登记不算)—— 轮询腿的「被唤醒数」读它。 */
     private waitingRegistrationCount;
     listLivePending(scope: string | undefined): LivePendingRow[];