@sema-agent/client-core 0.39.0 → 0.41.0

package/dist/hitl/gateLedger.js

@@ -1,14 +1,117 @@
+/**
+ * 连坐 abort 帧的 additive 超集机读位(#324 / [4907] 裁定;登记见 `docs/type-superset.json`)。
+ *
+ * `flushHeld` 对**已知不是 gate 主角**的帧 stamp `true`,别的帧一个字节不改。消费方(壳 / web /
+ * desktop)据此把连坐簇按 repeated-error 族软化折叠,**不猜文案**。
+ *
+ * 🔴 刻意**不动** `isError` 与 `output`:core 5.51 的 `[DEFERRED]` / `gate.batch_halted` 词汇
+ *    ([4826]③)尚未到货,那一面的定形归 core;本键只是机读位,到货后与官方形对表,
+ *    additive 键保留兼容(裁定原文)。
+ */
+export const SEMA_COLLATERAL_ABORT_KEY = '_sema_collateral_abort';
 /** 造一份 turn 级 gate 台账(**不是单例**,见文件头注)。 */
 export function createGateLedger() {
     const startedCalls = new Set();
     const endedCalls = new Set();
+    /** 只存帧:出身不在入表当拍冻结(那一拍 gate 身份还没到),改在 `flushHeld` 当拍求值。 */
     const heldAskEnds = new Map();
     const gatedStartArgsByCall = new Map();
     const deniedCalls = new Set();
     const pendingFsCalls = [];
     const resolvedAnswers = new Map();
     const decidedGates = new Set();
+    // ── 批级判据(四样同生共死,退休点见 `retireBatchState` 的两处调用)────────────────────────
+    /** 本批 park 属 fs/shell 族的准入证(唯一性兜底的前置)。 */
+    let fsOrShellFamilyGate = false;
+    /** 本批里被 `dropHeld` 摘出扣留表的 call(decide 成功会把主角摘走,判据还得认它)。 */
+    const droppedFromBatch = new Set();
+    /** 本批登记过几张 park。≠1 ⇒ 归属无从证明 ⇒ 整表不标(硬门)。 */
+    let batchParkCount = 0;
+    /** 上一次 park 登记之后有没有新帧进过扣留表 —— 用来把「同一张 park 被 durable 重放」认出来。 */
+    let heldSinceLastPark = false;
+    /** 本 turn 见过的 fs 写 / shell 执行族 gated tool_start —— 只做**族成员**判据,不做主角判据。 */
+    const fsOrShellGatedCalls = new Set();
     let lastFsOrShellGatedCall;
+    /**
+     * flush 当拍解析「谁是主角」:登记在案的优先;否则唯一性兜底(要准入证 + 扣留表内族成员唯一);
+     * 都拿不到 ⇒ `undefined` = 不知道,调用方一个都不 stamp。
+     *
+     * 🔴 返回 `undefined` 与返回空集合是**两件事**,别合并([honest-absence-not-fabricated-zero]):
+     *    空集合意味着「知道谁是主角,且一个都不是」。
+     * 🔴 兜底在**扣留表内**求唯一 —— 主角必在这一批被同一次 abort 连坐的 call 里;拿整个 turn 的
+     *    历史集求唯一会把「已经收口过的旧 call」算进来,又是一次「拿旁证冒充身份」。
+     */
+    const resolveGateSubjects = () => {
+        // 🔴 硬门:归属可结构性证明 = 本批恰好一张 park。零张(同步帧腿 / 纯取消批)与多张(两次
+        //    gate 的 abort 混进同一张扣留表)都无解 —— 诚实不标,绝不猜。
+        if (batchParkCount !== 1)
+            return undefined;
+        // 准入证:这张 park 的 gate **本体**属 fs 写 / shell 执行族 —— 主角必是该族的某个 call。
+        if (!fsOrShellFamilyGate)
+            return undefined;
+        // 前置:每一条扣留帧的 `tool_start` 都得是本连接亲眼见过的。族成员判据取自 tool_start 当拍
+        // 记的集合,没见过 start 的 call 在「唯一」这件事上是隐形的;而续流只消费 `runs.events` 的一段
+        // (re-attach 从 `lastEventId` 起),主角的 start 完全可能落在这次连接之外 —— 那时表里剩下的
+        // 唯一族成员是**旁观者**,会被当成主角、反手给真主角打上连坐位。信息不全就不许声称「唯一」。
+        for (const id of heldAskEnds.keys()) {
+            if (!startedCalls.has(id))
+                return undefined;
+        }
+        // 主角 = 本批(扣留帧 ∪ 已出批帧)里**唯一**属该族的 call。并上出批帧是因为决断成功那一下会
+        // 把主角的毒化帧 `dropHeld` 掉;不并上就等于主角「不在这一批」,整批判据当场失效。
+        const family = [...new Set([...heldAskEnds.keys(), ...droppedFromBatch])].filter((id) => fsOrShellGatedCalls.has(id));
+        return family.length === 1 ? new Set(family) : undefined;
+    };
+    /**
+     * `dropHeld` / `dropHeldForDecidedPark` 的**唯一**实现(两个动词共用一份,批级退休那条不变量
+     * 只写一处 —— 两份写法各自漂正是本模块存在的理由)。
+     * `callId === undefined` = 「这次什么都不摘」:退休检查照跑,别的一律不动。
+     */
+    const dropHeldImpl = (callId) => {
+        if (callId !== undefined && heldAskEnds.delete(callId))
+            droppedFromBatch.add(callId);
+        // 🔴 扣留表空 = 这一批没有(或不再有)任何待判的帧,批级判据当场退休 —— 不能等下一次
+        //    flush:「决断成功但本批压根没有毒化帧」的路径上 `flushHeld` 一次都不会跑,判据会就这么
+        //    活到下一批去把那一批的**真主角**判成连坐(实测 `new-main=STAMP`)。
+        // 🔴 「摘的那个不在表里」也要走这一步(不能早退):零 HOLD 批正是**每次** delete 都落空的
+        //    形状,早退就等于那种批永远不退休 —— 上一版的漏洞就在这里。
+        if (heldAskEnds.size === 0)
+            retireBatchState();
+    };
+    /**
+     * 件④ 保守臂的判据:候选在扣留表里**同族唯一**吗。
+     *
+     * 「族」的口径与**取件谓词**同轴(那才是可能撞车的那一层 —— `findPendingForTask` 是按族选行的):
+     *   · 候选属 fs 写 / shell 执行族(`fsOrShellGatedCalls`,tool_start 当拍记)⇒ 数扣留表里同属
+     *     该族的条数(两个 Bash / 一个 Write 一个 Edit 都算同族,因为取件谓词对它们不可分);
+     *   · 否则(ask / kind-only 等)⇒ 数扣留表里 `toolName` 逐字相同的条数。
+     * 不在扣留表里 ⇒ `false`(没有可摘的帧,也就谈不上「唯一」)。
+     */
+    const soleOfItsFamilyInHold = (callId) => {
+        const ev = heldAskEnds.get(callId);
+        if (ev === undefined)
+            return false;
+        let n = 0;
+        if (fsOrShellGatedCalls.has(callId)) {
+            for (const id of heldAskEnds.keys())
+                if (fsOrShellGatedCalls.has(id))
+                    n++;
+        }
+        else {
+            const name = ev.toolName;
+            for (const held of heldAskEnds.values())
+                if (held.toolName === name)
+                    n++;
+        }
+        return n === 1;
+    };
+    /** 一批判完(或整批被摘空)⇒ 四样批级判据同批退休:下一批从零证起。 */
+    const retireBatchState = () => {
+        fsOrShellFamilyGate = false;
+        droppedFromBatch.clear();
+        batchParkCount = 0;
+        heldSinceLastPark = false;
+    };
     let denyStampNextFsEnd = false;
     let seq;
     return {
@@ -41,20 +144,55 @@ export function createGateLedger() {
             endedCalls.add(callId);
         },
         hold(callId, ev) {
+            // 🔴 只有**新** call 进批才算「批里来了新东西」:durable re-attach 会把仍被扣留的毒化帧
+            //    连同 park 一起重放,那一下若也置位,同一张 park 就会被当成第二张而触发硬门弃判
+            //    (实测:重放后本该带位的兄弟帧变成 ABSENT)。覆盖同一 callId = 重放,不置位。
+            if (!heldAskEnds.has(callId))
+                heldSinceLastPark = true;
             heldAskEnds.set(callId, ev);
         },
         dropHeld(callId) {
-            heldAskEnds.delete(callId);
+            dropHeldImpl(callId);
+        },
+        dropHeldForDecidedPark(candidateCallId, trustedCallId) {
+            // ① wire 身份**对上了这次真被决断的那一行** ⇒ 身份确证,点名摘。
+            //    🔴 摘的永远是「真的被决断的那一行」(`candidateCallId`),wire 身份在这里的角色是**确证**
+            //    而不是另一个独立的摘取目标 —— 异源复审 finding①:决断腿按队列首行选行、这里却按 wire
+            //    身份摘帧,两边指向不同 call 时就是 split-brain(用户批的是旁观者,被摘的是主角帧)。
+            //    取件腿今天已经优先按同一个身份选行(见 `surfaceFsApprovalAndDecide` 的 parkGatedCallId),
+            //    所以正常路径上两者恒相等;不相等只发生在「身份在场但队列里没有那一行」的回落形 ——
+            //    那时决断落在别的行上,任何一帧都证明不了自己已过时,走②/③ 的保守判。
+            if (trustedCallId !== undefined && trustedCallId === candidateCallId) {
+                dropHeldImpl(trustedCallId);
+                return;
+            }
+            // ② 无可信身份:候选同族唯一才摘 —— 同族多条时任何选择都是猜,而猜错的代价是一帧永久消失。
+            if (candidateCallId !== undefined && soleOfItsFamilyInHold(candidateCallId)) {
+                dropHeldImpl(candidateCallId);
+                return;
+            }
+            // ③ 判不出 ⇒ 一条都不摘(退休检查仍照跑,见 dropHeldImpl 头注)。
+            dropHeldImpl(undefined);
         },
         heldCount() {
             return heldAskEnds.size;
         },
         *flushHeld() {
-            for (const [callId, held] of heldAskEnds) {
+            // 🔴 出身在**这一拍**求值(不是入表当拍):五个 flush 出口全部晚于 park 被看见,
+            //    gate 身份此时已在手。`undefined` = 不知道谁是主角 ⇒ 整表一个字节不改。
+            const subjects = resolveGateSubjects();
+            for (const [callId, ev] of heldAskEnds) {
                 endedCalls.add(callId);
-                yield held;
+                // 已知不是主角 ⇒ additive 机读位(帧的其余部分逐字节原样);主角与「不知道」走原路。
+                yield subjects !== undefined && !subjects.has(callId)
+                    ? { ...ev, [SEMA_COLLATERAL_ABORT_KEY]: true }
+                    : ev;
             }
             heldAskEnds.clear();
+            // 🔴 判完即弃:这一批帧就是这张 gate 的 abort 批。不退休 ⇒ 判完之后又来一批**背后没有
+            //    任何 gate**的 abort 帧(例如整轮被取消)时,上一批的证会给它们派判词。
+            //    身份不在退休之列(turn 级事实),它靠上面的「∩ 本批」求交集来限定作用域。
+            retireBatchState();
         },
         markDenied(callId) {
             deniedCalls.add(callId);
@@ -87,10 +225,26 @@ export function createGateLedger() {
         },
         noteFsOrShellGate(callId) {
             lastFsOrShellGatedCall = callId;
+            fsOrShellGatedCalls.add(callId);
         },
         lastFsOrShellGatedCallId() {
             return lastFsOrShellGatedCall;
         },
+        noteParkGate(evidence) {
+            // 自上次登记以来没有**新 call** 进过扣留表 ⇒ 按 durable 重放同一张 park 处置:不计新的一张。
+            // 🔴 而且**一个字节都不写**。「没有新帧进批」证明得了「这一批的组成没变」,证明不了
+            //    「这张 park 就是上一张」—— 一张**真的新 park** 同样可以零毒化帧(例如上一张 park 走
+            //    already-resolved 重放救回、续流紧接着来一张别的 gate 的 park)。此时若顺手刷新族属,
+            //    本批的判据就被一张与这批帧无关的 gate 改写:实测 `WebFetch` 主角 + `Bash` 旁观者的批
+            //    被一张零毒化 `Bash` park 改成 fs/shell 族,兜底选中旁观者、反手给真主角打位
+            //    (`web-main=STAMP`)。真是重放时族属本就相同,不写零损失;是新 park 时不写才安全。
+            //    (本批的帧全部早于第一张 park,归属本来就该按第一张算。)
+            if (batchParkCount > 0 && !heldSinceLastPark)
+                return;
+            batchParkCount += 1;
+            fsOrShellFamilyGate = evidence.fsOrShellFamily;
+            heldSinceLastPark = false;
+        },
         rememberAnswer(callId, answered) {
             resolvedAnswers.set(callId, answered);
         },

package/dist/hitl/hitlBridge.d.ts

@@ -213,6 +213,14 @@ export type FindPendingOutcome = {
  * whose toolName the predicate doesn't recognize, but which still belongs to this run). Never `pending[0]`
  * — a typed failure when nothing for this taskId is queued.
  *
+ * F4947-1(2026-08-22,0.41.0):`callId` 是**更强的身份腿**,在场时先于上面两条跑。它来自
+ * `HitlBridge.decideTool`/`answerQuestion` 的 `toolUseID`(CC 的 tool_use id)—— 那两处此前走的是
+ * 本类里一个**同名私有** `findPending`,REF-CC-029 的收编没覆盖到它、P-30 的门种闸也没加到它,
+ * 于是真实生产入口(`makeHitlCanUseTool` → `decideTool`,从不传 `preResolvedPending`)一直在一条
+ * **没有闸**的复刻上跑(test 线 P0-KPI 复现)。收口方式是把私有件删掉改调本函数,而不是给它补第二
+ * 份过滤 —— 复刻正是这条缺陷的成因。身份腿同样只在**过完门种闸的行**里找:一个 `plan_review` 行
+ * 哪怕 callId 逐字命中也不该被工具审批 decide 掉(server 那边照样 409 `gate_not_tool_approval`)。
+ *
  * P-30(2026-08-14):both legs only consider rows whose `gateKind` belongs to the ask/approval family
  * ({@link askParkForeignGateKind} — the same single-source guard `classifyAskParkRows` uses). Without it
  * the ANY-row fallback would hand a `plan_review`/`resource_limit` row to the tool-approval wire — an
@@ -222,7 +230,34 @@ export type FindPendingOutcome = {
  */
 export declare function findPendingForTask(client: HitlClientLike, taskId: string, matches: (toolName: string | undefined) => boolean, opts?: {
     signal?: AbortSignal;
-}): Promise<FindPendingOutcome>;
+}, 
+/**
+ * F4947-1:调用方手上的**更强身份** —— CC 的 `toolUseID`(`HitlBridge`),或这张 park 的
+ * wire 身份(server ≥7.41.0,两条决断腿)。在场 ⇒ 先在**本 taskId** 的行里按
+ * `boundCallId`/`toolCallId` 逐字命中(仍在门种闸之内);不命中再走下面两条 taskId 腿。
+ *
+ * 🔴 **刻意不 fail-closed**(异源复审二审 finding① 的部分驳回,理由成文):身份在场而队列里
+ * 没有那一行时**照旧回落**,不铸「身份不匹配」的硬拒。两条理由:
+ *   · 回落的失效面 = 与本参数出现之前**逐字节相同**(那时压根没有身份腿);fail-closed 的失效面
+ *     = **每一次审批都决断不了**(用户点了 Yes 也过不去)。代价严重不对称;
+ *   · 这个 join(checkpoint 的 `pendingAction.toolCallId` ↔ `/v1/approvals` 富行的
+ *     `toolCallId`/`boundCallId`)本仓**没有对真 server 的实证**,只有上游帖面的口径。拿一个
+ *     没实证的键去关整条 HITL 的门,是把「可能对不上」赌成「一定对得上」。
+ * 跨 run 那一半的风险由上面的 taskId 约束关掉;「决断落在同 task 的另一行」这一格与本参数出现
+ * 之前同形,且下游 `dropHeldForDecidedPark` 对这一格自带保守判(身份对不上 ⇒ 一帧都不摘)。
+ */
+callId?: string, 
+/**
+ * 身份腿的**族闸**(整行可读)。缺省 = 退回 `matches(toolName)`。
+ *
+ * 🔴 为什么必须能读**整行**而不是只读 toolName(五审 finding①):工具审批族有**两条腿** ——
+ * 一等 `kind === 'tool_approval'`(放行**任意** toolName)与 fs 写 / shell 名字腿。而 wire 模块
+ * 传下来的 `matches` 只有名字腿那半(它服务的是「同族第一行」那条 leg 2)。拿它当身份闸,一个
+ * **合法的 kind-only 行**即使 taskId+callId 逐字命中也会被判出局 ⇒ 回落挑了同 task 的另一行,
+ * 卡面与决断全落在别的审批上、真 gate 继续 suspended。⇒ 调用方按自己那条腿的**完整**族判据
+ * 供给本闸(fs 腿 = `isToolApprovalGate({kind: row.gateKind, toolName})`,ask 腿 = `isAskTool`)。
+ */
+identityAccepts?: (row: PendingCheckpoint) => boolean): Promise<FindPendingOutcome>;
 /**
  * The bridge state. One per run/session. The shell feeds it `suspended` events (observe) and the human's
  * outcome (decide / answer / planReview); it owns the `approvals.list()` join + the verbatim binding echo.
@@ -240,17 +275,24 @@ export declare class HitlBridge {
     /** The gate currently awaiting a human, if any. The shell branches on `gate.kind` to pick the chrome. */
     currentGate(): CheckpointGate | null;
     /**
-     * Find the `PendingCheckpoint` the human is about to decide on. Joins by `toolCallId` when CC hands a
-     * `toolUseID`; otherwise falls back to the single pending row for this run's `taskId`. Returns null when
-     * the queue is empty (e.g. resolved/expired under the human → the caller must refetch + re-present).
+     * Fetch the `PendingCheckpoint` this decide/answer is about to resolve, for the callers that do NOT
+     * already have one in hand (see `decideTool`/`answerQuestion`'s `preResolvedPending` param — the wire
+     * modules that surface a card/overlay BEFORE deciding fetch the row themselves and pass it straight
+     * through, closing the TOCTOU window between "the row the human saw" and "the row decide resolves",
+     * REF-CC-029/hitl2-08).
+     *
+     * 🔴 F4947-1(2026-08-22,0.41.0):本方法**没有自己的查找逻辑** —— 它是 {@link findPendingForTask}
+     * 的一层出参映射,一个字节的行过滤都不在这里。上一版是一个与那个单源导出**撞名**的私有复刻
+     * (`findPending`),REF-CC-029 的三合一没覆盖到它、P-30 的门种闸也只加在导出那一份上,于是
+     * `makeHitlCanUseTool` → `decideTool`(真实用户点 Yes/No 那条路,从不传 `preResolvedPending`)
+     * 一直在没有闸的老复刻上跑:同 task 停着 `plan_review` 行时,它被当成「这个 run 的 pending」
+     * 交给工具审批 decide(空 toolName 卡 / 409 `gate_not_tool_approval`)。
+     * 名字也一并换掉:撞名正是「看起来只有一份实现」的成因。
      *
-     * Used only as the fallback when a caller does NOT already have the pending row in hand (see
-     * `decideTool`/`answerQuestion`'s `preResolvedPending` param) — the wire modules that surface a card/
-     * overlay BEFORE calling decide/answer fetch the row themselves via `findPendingForTask` (below) and
-     * pass it straight through, closing the TOCTOU window between "the row the human saw" and "the row
-     * decide resolves" (REF-CC-029/hitl2-08).
+     * 谓词传 {@link ANY_TOOL_FAMILY}:桥这一层对工具族**没有意见**(人刚刚决断的是哪张门就是哪张),
+     * 与旧私有件的 taskId 兜底逐字同语义;身份腿(`toolUseID`)由单源函数的 `callId` 参数承接。
      */
-    private findPending;
+    private pendingForDecide;
     /**
      * Build the D-1 binding off the pending row the human SAW. Echo VERBATIM — NEVER recompute the hash
      * (contract/04 §2.2). `checkpointToken` is DELIBERATELY never set (deprecated legacy path;
@@ -288,7 +330,7 @@ export declare class HitlBridge {
      *  its own `approvals.list()` — closing the TOCTOU window between "the row the human saw" and "the
      *  row decide resolves" (two independent fetches could otherwise land on different rows if the
      *  first one got resolved/expired in between, hitl2-01/hitl2-08). Omit only when the caller has no
-     *  such row in hand (falls back to `findPending`). */
+     *  such row in hand(缺省回落 `pendingForDecide` — 见其头注,那是单源 `findPendingForTask` 的一层出参映射). */
     preResolvedPending?: PendingCheckpoint): Promise<unknown>;
     /**
      * Answer an `AskUserQuestion` gate (contract/04 §4; 08 CS-16). Same suspended → decide loop as a

package/dist/hitl/hitlBridge.js

@@ -213,6 +213,12 @@ export class DecideTransportRetryExhaustedError extends Error {
         this.name = 'DecideTransportRetryExhaustedError';
     }
 }
+/**
+ * 「本层对工具族没有意见」的谓词(`HitlBridge.pendingForDecide` 用)。桥不是 wire 模块:它决断的
+ * 就是人刚刚看过的那张门,族属由那两条 wire 在**取件时**说了算。写成具名常量而不是就地 `() => true`
+ * —— 一个匿名恒真谓词读起来像「忘了填」,而这里的恒真是**有理由**的(理由即本注)。
+ */
+const ANY_TOOL_FAMILY = () => true;
 /**
  * The single source for "which `PendingCheckpoint` row is the human about to decide on", used by the two
  * decision wires (`toolApprovalWire.surfaceFsApprovalAndDecide` / `askGateWire.surfaceGateAndDecide`)
@@ -233,6 +239,14 @@ export class DecideTransportRetryExhaustedError extends Error {
  * whose toolName the predicate doesn't recognize, but which still belongs to this run). Never `pending[0]`
  * — a typed failure when nothing for this taskId is queued.
  *
+ * F4947-1(2026-08-22,0.41.0):`callId` 是**更强的身份腿**,在场时先于上面两条跑。它来自
+ * `HitlBridge.decideTool`/`answerQuestion` 的 `toolUseID`(CC 的 tool_use id)—— 那两处此前走的是
+ * 本类里一个**同名私有** `findPending`,REF-CC-029 的收编没覆盖到它、P-30 的门种闸也没加到它,
+ * 于是真实生产入口(`makeHitlCanUseTool` → `decideTool`,从不传 `preResolvedPending`)一直在一条
+ * **没有闸**的复刻上跑(test 线 P0-KPI 复现)。收口方式是把私有件删掉改调本函数,而不是给它补第二
+ * 份过滤 —— 复刻正是这条缺陷的成因。身份腿同样只在**过完门种闸的行**里找:一个 `plan_review` 行
+ * 哪怕 callId 逐字命中也不该被工具审批 decide 掉(server 那边照样 409 `gate_not_tool_approval`)。
+ *
  * P-30(2026-08-14):both legs only consider rows whose `gateKind` belongs to the ask/approval family
  * ({@link askParkForeignGateKind} — the same single-source guard `classifyAskParkRows` uses). Without it
  * the ANY-row fallback would hand a `plan_review`/`resource_limit` row to the tool-approval wire — an
@@ -240,7 +254,34 @@ export class DecideTransportRetryExhaustedError extends Error {
  * out, not a rejection of the whole queue: a genuine approval row for the same task still resolves.
  * Rows with no `gateKind` (pre-`gate_kind` history) keep the old behaviour — no stronger signal exists.
  */
-export async function findPendingForTask(client, taskId, matches, opts) {
+export async function findPendingForTask(client, taskId, matches, opts, 
+/**
+ * F4947-1:调用方手上的**更强身份** —— CC 的 `toolUseID`(`HitlBridge`),或这张 park 的
+ * wire 身份(server ≥7.41.0,两条决断腿)。在场 ⇒ 先在**本 taskId** 的行里按
+ * `boundCallId`/`toolCallId` 逐字命中(仍在门种闸之内);不命中再走下面两条 taskId 腿。
+ *
+ * 🔴 **刻意不 fail-closed**(异源复审二审 finding① 的部分驳回,理由成文):身份在场而队列里
+ * 没有那一行时**照旧回落**,不铸「身份不匹配」的硬拒。两条理由:
+ *   · 回落的失效面 = 与本参数出现之前**逐字节相同**(那时压根没有身份腿);fail-closed 的失效面
+ *     = **每一次审批都决断不了**(用户点了 Yes 也过不去)。代价严重不对称;
+ *   · 这个 join(checkpoint 的 `pendingAction.toolCallId` ↔ `/v1/approvals` 富行的
+ *     `toolCallId`/`boundCallId`)本仓**没有对真 server 的实证**,只有上游帖面的口径。拿一个
+ *     没实证的键去关整条 HITL 的门,是把「可能对不上」赌成「一定对得上」。
+ * 跨 run 那一半的风险由上面的 taskId 约束关掉;「决断落在同 task 的另一行」这一格与本参数出现
+ * 之前同形,且下游 `dropHeldForDecidedPark` 对这一格自带保守判(身份对不上 ⇒ 一帧都不摘)。
+ */
+callId, 
+/**
+ * 身份腿的**族闸**(整行可读)。缺省 = 退回 `matches(toolName)`。
+ *
+ * 🔴 为什么必须能读**整行**而不是只读 toolName(五审 finding①):工具审批族有**两条腿** ——
+ * 一等 `kind === 'tool_approval'`(放行**任意** toolName)与 fs 写 / shell 名字腿。而 wire 模块
+ * 传下来的 `matches` 只有名字腿那半(它服务的是「同族第一行」那条 leg 2)。拿它当身份闸,一个
+ * **合法的 kind-only 行**即使 taskId+callId 逐字命中也会被判出局 ⇒ 回落挑了同 task 的另一行,
+ * 卡面与决断全落在别的审批上、真 gate 继续 suspended。⇒ 调用方按自己那条腿的**完整**族判据
+ * 供给本闸(fs 腿 = `isToolApprovalGate({kind: row.gateKind, toolName})`,ask 腿 = `isAskTool`)。
+ */
+identityAccepts = (r) => matches(typeof r.toolName === 'string' ? r.toolName : undefined)) {
     let rows;
     try {
         rows = (await client.approvals.list(opts)).pending;
@@ -249,8 +290,33 @@ export async function findPendingForTask(client, taskId, matches, opts) {
         return { ok: false, reason: `approvals.list failed: ${String(e)}` };
     }
     const decidable = rows.filter((r) => askParkForeignGateKind(r) === null);
-    const pending = decidable.find((r) => r.taskId === taskId && matches(typeof r.toolName === 'string' ? r.toolName : undefined)) ??
-        decidable.find((r) => r.taskId === taskId);
+    // 🔴 身份腿**约束在本 taskId 之内**(异源复审二审 finding①):`/v1/approvals` 是 scope 级单队列,
+    // 别的 run / 后台子代 lane 的行同在表里 —— 一个撞名或被复用的 callId 就能把**别人会话**的 pending
+    // 行交给这次 decide。REF-CC-022 拆掉 `?? pending[0]` 防的正是这件事;身份腿是「更强的身份」,
+    // 不是「可以跨 run 的身份」,不能自带一个新的绕行口。
+    const identityRow = callId !== undefined
+        ? decidable.find((r) => r.taskId === taskId && (r.boundCallId === callId || r.toolCallId === callId))
+        : undefined;
+    // 🔴 身份命中还要过**族闸**(四审 finding② / 五审 finding①,闸读整行见 `identityAccepts`):
+    // 门种闸只挡 plan_review/resource_limit 这类外族,AskUserQuestion 与工具审批**同在** `decidable` 里。
+    // 一个陈旧/错配/被复用的 park 身份否则就能让 fs 腿选中一行 ask(反之亦然),而那一行随后原样当
+    // `preResolvedPending` 去呈卡 + decide —— 卡面全错、决断打在另一个 checkpoint 上。
+    const identityConflicts = identityRow !== undefined && !identityAccepts(identityRow);
+    // 🔴 身份证据与本腿族属**冲突**时,这一轮的候选池整体收紧到族闸放行的行(六审 finding① +
+    // 七审 finding①)。两步演进的理由要写清楚:
+    //   · 只拦身份腿是自相矛盾的 —— 最后那条「同 taskId 任意行」兜底会把**同一行**重新捞出来
+    //     (队列里只剩它时必然发生),刚判定「这一行不是本腿的」,转头又拿它去呈卡 + 决断;
+    //   · 只剔除命中的**那一个对象**也不够 —— 同 task 排着两条反族行时,删掉第一条,兜底照样捡起
+    //     第二条(七审实撞)。
+    // 冲突 = wire 数据自相矛盾(park 说 gate 是 A 族、身份却指着 B 族的行),这一轮**整体**保守:
+    // 只在族闸放行的行里选;一条都不剩 ⇒ 诚实 `no_pending`(调用方走既有 fail-soft / 重呈路)。
+    // 🔴 收紧**只发生在冲突路径上**:身份缺席(绝大多数路径)时候选池一个字节不动 —— 那条
+    // 「任意行」兜底本来就是给 kind-only / 名字腿认不得的合法行留的(见上方 leg 说明),不能被
+    // 一条与它无关的规则顺手削掉。
+    const pool = identityConflicts ? decidable.filter((r) => identityAccepts(r)) : decidable;
+    const pending = (identityConflicts ? undefined : identityRow) ??
+        pool.find((r) => r.taskId === taskId && matches(typeof r.toolName === 'string' ? r.toolName : undefined)) ??
+        pool.find((r) => r.taskId === taskId);
     if (!pending)
         return { ok: false, reason: 'no pending checkpoint for this run (resolved/expired?)', code: 'no_pending' };
     return { ok: true, pending, gatedCallId: pending.toolCallId ?? pending.boundCallId ?? undefined };
@@ -298,32 +364,33 @@ export class HitlBridge {
         return this.active?.gate ?? null;
     }
     /**
-     * Find the `PendingCheckpoint` the human is about to decide on. Joins by `toolCallId` when CC hands a
-     * `toolUseID`; otherwise falls back to the single pending row for this run's `taskId`. Returns null when
-     * the queue is empty (e.g. resolved/expired under the human → the caller must refetch + re-present).
+     * Fetch the `PendingCheckpoint` this decide/answer is about to resolve, for the callers that do NOT
+     * already have one in hand (see `decideTool`/`answerQuestion`'s `preResolvedPending` param — the wire
+     * modules that surface a card/overlay BEFORE deciding fetch the row themselves and pass it straight
+     * through, closing the TOCTOU window between "the row the human saw" and "the row decide resolves",
+     * REF-CC-029/hitl2-08).
      *
-     * Used only as the fallback when a caller does NOT already have the pending row in hand (see
-     * `decideTool`/`answerQuestion`'s `preResolvedPending` param) — the wire modules that surface a card/
-     * overlay BEFORE calling decide/answer fetch the row themselves via `findPendingForTask` (below) and
-     * pass it straight through, closing the TOCTOU window between "the row the human saw" and "the row
-     * decide resolves" (REF-CC-029/hitl2-08).
+     * 🔴 F4947-1(2026-08-22,0.41.0):本方法**没有自己的查找逻辑** —— 它是 {@link findPendingForTask}
+     * 的一层出参映射,一个字节的行过滤都不在这里。上一版是一个与那个单源导出**撞名**的私有复刻
+     * (`findPending`),REF-CC-029 的三合一没覆盖到它、P-30 的门种闸也只加在导出那一份上,于是
+     * `makeHitlCanUseTool` → `decideTool`(真实用户点 Yes/No 那条路,从不传 `preResolvedPending`)
+     * 一直在没有闸的老复刻上跑:同 task 停着 `plan_review` 行时,它被当成「这个 run 的 pending」
+     * 交给工具审批 decide(空 toolName 卡 / 409 `gate_not_tool_approval`)。
+     * 名字也一并换掉:撞名正是「看起来只有一份实现」的成因。
+     *
+     * 谓词传 {@link ANY_TOOL_FAMILY}:桥这一层对工具族**没有意见**(人刚刚决断的是哪张门就是哪张),
+     * 与旧私有件的 taskId 兜底逐字同语义;身份腿(`toolUseID`)由单源函数的 `callId` 参数承接。
      */
-    async findPending(toolUseID, opts) {
-        const { pending } = await this.client.approvals.list(opts);
-        if (pending.length === 0)
+    async pendingForDecide(toolUseID, opts) {
+        const found = await findPendingForTask(this.client, this.taskId, ANY_TOOL_FAMILY, opts, toolUseID);
+        if (found.ok)
+            return found.pending;
+        // 🔴 `no_pending`(良性缺席)才是「没有行可决」;`approvals.list` 自身失败必须照旧**抛**出去。
+        //    旧私有件让 list 的错原样逃逸,而下游 `parkResolver` 对 `no_pending` 的处置是「这张 gate
+        //    早就被解决了 ⇒ 继续读流」—— 把一次网络失败降级成那个码 = 谎报已解决(#110 烧会话的路径)。
+        if (found.code === 'no_pending')
             return null;
-        if (toolUseID) {
-            const byCall = pending.find((p) => p.boundCallId === toolUseID || p.toolCallId === toolUseID);
-            if (byCall)
-                return byCall;
-        }
-        // Fall back to this run's pending row (the suspended run holding the session claim).
-        // REF-CC-022(2026-08-02): NEVER `?? pending[0]` — once this taskId's own rows are exhausted, the
-        // first queue row can belong to a DIFFERENT session or a background subagent lane (they share the
-        // same `/v1/approvals` queue); deciding on it would resolve someone else's gate. A miss here is a
-        // real `no_pending` — the caller's existing typed-fail path (and exactly the signal #110's
-        // cancel-by-deny-recovery arm expects), not "decide on whatever happens to be first".
-        return pending.find((p) => p.taskId === this.taskId) ?? null;
+        throw new Error(found.reason);
     }
     /**
      * Build the D-1 binding off the pending row the human SAW. Echo VERBATIM — NEVER recompute the hash
@@ -361,9 +428,9 @@ export class HitlBridge {
      *  its own `approvals.list()` — closing the TOCTOU window between "the row the human saw" and "the
      *  row decide resolves" (two independent fetches could otherwise land on different rows if the
      *  first one got resolved/expired in between, hitl2-01/hitl2-08). Omit only when the caller has no
-     *  such row in hand (falls back to `findPending`). */
+     *  such row in hand(缺省回落 `pendingForDecide` — 见其头注,那是单源 `findPendingForTask` 的一层出参映射). */
     preResolvedPending) {
-        const pending = preResolvedPending ?? (await this.findPending(toolUseID, opts));
+        const pending = preResolvedPending ?? (await this.pendingForDecide(toolUseID, opts));
         if (!pending) {
             throw new HitlSafetyError('no pending checkpoint to decide (resolved/expired under the human) — refetch + re-present', 'no_pending');
         }
@@ -408,10 +475,10 @@ export class HitlBridge {
     /** REF-CC-029(2026-08-02):see `decideTool`'s same-named param — the pending row the caller already
      *  fetched via `findPendingForTask`. */
     preResolvedPending) {
-        // 🔴 校验在 findPending **之前**:入参坏了跟 pending 行在不在场无关,而先 list 再拒会把
+        // 🔴 校验在取件**之前**:入参坏了跟 pending 行在不在场无关,而先 list 再拒会把
         //    「你的作答是空的」这条真判词换成「no_pending」那条假判词(行恰好过期时)。
         assertAnswersSendable(answers);
-        const pending = preResolvedPending ?? (await this.findPending(toolUseID, opts));
+        const pending = preResolvedPending ?? (await this.pendingForDecide(toolUseID, opts));
         if (!pending) {
             throw new HitlSafetyError('no pending AskUserQuestion checkpoint to answer — refetch + re-present', 'no_pending');
         }

package/dist/hitl/parkResolver.js

@@ -90,7 +90,10 @@ export function toAnsweredOutput(questions, answer) {
  * 弹既有 AskUserQuestion overlay → 等作答 → 经 HitlBridge decide(答案/拒答)。
  * decide 成功即引擎已把 run 驱到下一状态(sync);调用方随后 attach runs.events 续流。
  */
-async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal) {
+async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, 
+/** 这张 park 的待批 call 身份(server ≥7.41.0;缺席是常态)。语义与不 fail-closed 的理由
+ *  与 fs 腿同一条,见 `toolApprovalWire.surfaceFsApprovalAndDecide` 的同名参数头注。 */
+parkGatedCallId) {
     if (!hasQuestionOverlay()) {
         return { kind: 'failed', reason: 'no question overlay mounted (print/non-REPL mode)' };
     }
@@ -98,7 +101,9 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal) {
     // REF-CC-029(单源取件)+ REF-CC-033(no_pending 判别码):findPendingForTask 是唯一取件口
     // (三份近似复刻已收敛),其失败形带 code 判别位,本处原样透传给 GateOutcome ——
     // 「没有待决 gate」(良性,park 重放常见)与「approvals.list 真失败」自此结构可分。
-    const found = await findPendingForTask(deps.client, taskId, isAskTool, signal ? { signal } : undefined);
+    const found = await findPendingForTask(deps.client, taskId, isAskTool, signal ? { signal } : undefined, parkGatedCallId, // 身份在场 ⇒ 逐字命中优先;缺席/不命中 ⇒ 原两腿(不 fail-closed,理由见参数头注)
+    // 本腿的族就是 ask 一族(整行可读闸的 ask 半场,与 fs 腿的 `isToolApprovalGate` 对称)。
+    (row) => isAskTool(typeof row.toolName === 'string' ? row.toolName : undefined));
     if (!found.ok)
         return { kind: 'failed', reason: found.reason, ...(found.code !== undefined ? { code: found.code } : {}) };
     const { pending, gatedCallId } = found;
@@ -208,7 +213,7 @@ export async function resolvePark(park, ctx) {
     else if (park.gate === 'fs') {
         candidateGatedCallId = led.lastFsOrShellGatedCallId();
         // [816] 放宽腿:fs 写权限 gate → CC 三选卡(vendored PermissionRequest)→ decide。
-        outcome = await surfaceFsApprovalAndDecide({ client: deps.client }, taskId, argsByCallOf(led), ctx.signal);
+        outcome = await surfaceFsApprovalAndDecide({ client: deps.client }, taskId, argsByCallOf(led), ctx.signal, park.gatedCallId);
         // #51: `outcome`'s declared type is the wider `GateOutcome |
         // FsApprovalOutcome`; both unions share a 'decided' kind with
         // different optional fields (`answered` vs `denied`), so a plain
@@ -221,7 +226,7 @@ export async function resolvePark(park, ctx) {
         }
     }
     else {
-        outcome = await surfaceGateAndDecide(deps, taskId, argsByCallOf(led), ctx.signal);
+        outcome = await surfaceGateAndDecide(deps, taskId, argsByCallOf(led), ctx.signal, park.gatedCallId);
     }
     // #110 缺陷② b/c —— **重放的、早已决断过的 park 不是失败**。
     // durable re-attach 必然会把 park 帧再送一遍(`lastEventId` 再准也只能精确到帧,park 就在
@@ -288,8 +293,28 @@ export async function resolvePark(park, ctx) {
     }
     // decide 成功:丢弃该 call 的毒化 HOLD(续流重放会带 isError:false 的解答帧收口卡片),
     // 并记下真实答案供该解答帧 stamp `structured`(否则卡片渲成结果不可用)。
+    //
+    // 🔴 件④([4933] 立案的存量,0.41.0 根修):摘扣留帧走 `dropHeldForDecidedPark` 而不是裸
+    //    `dropHeld(outcome.gatedCallId)` —— 后者的入参是 `findPendingForTask` 的**卡面渲染宽口**
+    //    (同 taskId + 谓词命中的第一行),同族多行排队时它可能是旁观者,于是摘掉的是**另一条**
+    //    call 的扣留帧、那一帧再也不吐(「一帧不丢」在这一格上不成立)。新动词的两条腿见其头注:
+    //    `park.gatedCallId`(server ≥7.41.0 的 wire 身份)在场就点名摘,缺席则只在同族唯一时摘。
+    //    这一行**刻意排在 `if (outcome.gatedCallId)` 之外**:身份在 wire 上时,摘不摘与 pending
+    //    行给没给出 callId 无关(park 有主角,decide 也成功了)。
+    led.dropHeldForDecidedPark(outcome.gatedCallId, park.gatedCallId);
     if (outcome.gatedCallId) {
-        led.dropHeld(outcome.gatedCallId);
+        // 🔴 #324:**刻意不把 pending 行的 callId 当成连坐判别的主角身份**。durable `checkpointGate`
+        //    不带 callId,`findPendingForTask` 取的是「同 taskId + 谓词命中的**第一行**」(谓词不命中
+        //    时还退「任意行」)—— 那是给**卡面渲染**用的宽口,证明不了这一行就是这张 park 的主角:
+        //    同族两行排队时它可能给出旁观者,于是真主角被挤成「非主角」而 stamp(异源复审实测)。
+        //    连坐判别改由台账按「本批唯一的该族 call」自证(`gateLedger.flushHeld` 头注),
+        //    分不出来就整批不标。下面两行是 gate 生命周期(#110 / REF-CC-034),与判别无关,照旧。
+        //    ✅ **记案已销**(0.41.0 件④):此处原先那句「`dropHeld` 用的也是这个不可信 callId」的
+        //    存量记案,已由上方 `dropHeldForDecidedPark` 收口(wire 身份点名 / 判不出就不摘)。
+        //    🔴 `markDecided` **刻意仍用** `outcome.gatedCallId`:它喂的是 #110 那条「重放的 park 不是
+        //    失败」的承重判据,而那条判据的候选取自 `lastFsOrShellGatedCallId()`(同一条 pending 宽口
+        //    时代的口径),两边必须同源才对得上;换成 wire 身份是**另一件**改动(要连着上方
+        //    `candidateGatedCallId` 一起换,且会改动烧会话那条路径的行为),不搭本批的车。
         led.markDecided(outcome.gatedCallId); // #110 缺陷② b / REF-CC-034:身份留痕,上方候选匹配消费
         if ('answered' in outcome && outcome.answered)
             led.rememberAnswer(outcome.gatedCallId, outcome.answered);

package/dist/hitl/toolApprovalWire.d.ts

@@ -344,7 +344,21 @@ export declare function surfaceApprovalCard(req: ApprovalCardRequest): Promise<A
  *
  * @param argsByCall tool_start.args(toolCallId → args)——题干/diff 的一手源;缺则 pending.input。
  */
-export declare function surfaceFsApprovalAndDecide(deps: FsApprovalWireDeps, taskId: string, argsByCall: Map<string, unknown>, signal?: AbortSignal): Promise<FsApprovalOutcome>;
+export declare function surfaceFsApprovalAndDecide(deps: FsApprovalWireDeps, taskId: string, argsByCall: Map<string, unknown>, signal?: AbortSignal, 
+/**
+ * 这张 park 的**待批 call 身份**(server ≥7.41.0 的 `done{suspended}.result.toolCallId` /
+ * durable `suspended` 事件同键;供给见 `frameRouter.parkGatedCallId`,缺席是常态)。
+ *
+ * 🔴 它必须从**取件**这一步就起作用,不能只拿去删扣留帧(0.41.0 件④ 的异源复审 finding①):
+ * 取件按 taskId + 族谓词选**第一行**,同 task 同族多行排队时那可能是旁观者 —— 只用身份删帧就成了
+ * split-brain(决断绑的是旁观者行、删掉的是主角帧):用户其实在批准/拒绝**另一个**工具调用,
+ * 而真 park 原地不动、反复重挂。
+ * 🔴 **不 fail-closed**:身份在场但队列里没有对应行时**照旧回落**既有两条腿(taskId + 族谓词)。
+ * 这个 join(checkpoint 的 `pendingAction.toolCallId` ↔ `/v1/approvals` 行的 `toolCallId`/
+ * `boundCallId`)本仓没有对真 server 的实证,而 fail-closed 的失效面是**每一次审批都决断不了**;
+ * 回落的失效面则与本键出现之前逐字节相同。方向按代价不对称取:宁可退回原状,不赌一个没实证的键。
+ */
+parkGatedCallId?: string): Promise<FsApprovalOutcome>;
 /** server 包 src/tool-approval.ts 头注的帧契约(redactDeep + 16KiB 帽;超帽 argsOmitted 仍出帧)。 */
 export interface ToolApprovalFrame {
     type: 'tool_approval' | 'tool_approval_complete';

package/dist/hitl/toolApprovalWire.js

@@ -221,7 +221,21 @@ function cardPortMissReason() {
  *
  * @param argsByCall tool_start.args(toolCallId → args)——题干/diff 的一手源;缺则 pending.input。
  */
-export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signal) {
+export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signal, 
+/**
+ * 这张 park 的**待批 call 身份**(server ≥7.41.0 的 `done{suspended}.result.toolCallId` /
+ * durable `suspended` 事件同键;供给见 `frameRouter.parkGatedCallId`,缺席是常态)。
+ *
+ * 🔴 它必须从**取件**这一步就起作用,不能只拿去删扣留帧(0.41.0 件④ 的异源复审 finding①):
+ * 取件按 taskId + 族谓词选**第一行**,同 task 同族多行排队时那可能是旁观者 —— 只用身份删帧就成了
+ * split-brain(决断绑的是旁观者行、删掉的是主角帧):用户其实在批准/拒绝**另一个**工具调用,
+ * 而真 park 原地不动、反复重挂。
+ * 🔴 **不 fail-closed**:身份在场但队列里没有对应行时**照旧回落**既有两条腿(taskId + 族谓词)。
+ * 这个 join(checkpoint 的 `pendingAction.toolCallId` ↔ `/v1/approvals` 行的 `toolCallId`/
+ * `boundCallId`)本仓没有对真 server 的实证,而 fail-closed 的失效面是**每一次审批都决断不了**;
+ * 回落的失效面则与本键出现之前逐字节相同。方向按代价不对称取:宁可退回原状,不赌一个没实证的键。
+ */
+parkGatedCallId) {
     // REF-CC-031(2026-08-02):卡口缺席判据不在此前置重复一遍 —— `surfaceApprovalCard`(下方调用)
     // 已经计 miss + 出 typed `{kind:'failed', reason:...}`,card.kind==='failed' 走既有汇流分支
     // (下面 switch 的 'failed' 臂);两处各写一份文案会在 SEMA_DEBUG 里出现两种措辞,取决于走的是
@@ -232,7 +246,11 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
     // 二次 list(),消掉 hitl2-01/hitl2-08 的 TOCTOU 窗。
     // 🔴 常驻判据不是「看得见 pending 这个实参」,是 pure 门那四条「approvals.list 全程恰好 1 次」——
     // 漏传一条腿,形状断言全绿而计数当场翻红(回炉车前的实况:只有 aborted 臂传了)。
-    const found = await findPendingForTask(deps.client, taskId, (toolName) => toolName !== undefined && (toolNameIsFsWrite(toolName) || toolNameIsShellExec(toolName)), signal ? { signal } : undefined);
+    const found = await findPendingForTask(deps.client, taskId, (toolName) => toolName !== undefined && (toolNameIsFsWrite(toolName) || toolNameIsShellExec(toolName)), signal ? { signal } : undefined, parkGatedCallId, // 见本参数头注:身份在场 ⇒ 逐字命中优先于「同族第一行」;缺席/不命中 ⇒ 原两腿
+    // 身份腿的族闸走**整行**判据:本腿的族是 `isToolApprovalGate` 的**两条腿**(一等 kind 放行任意
+    // toolName + fs/shell 名字腿),而上面那个 `matches` 只有名字腿那半 —— 拿它当身份闸会把合法的
+    // kind-only 行判出局(五审 finding①)。gateKind = 行上的扁平投影,与 gate.kind 同一权威。
+    (row) => isToolApprovalGate({ kind: row.gateKind, toolName: row.toolName }));
     if (!found.ok)
         return { kind: 'failed', reason: found.reason };
     const { pending, gatedCallId } = found;