@sema-agent/client-core 0.77.0 → 0.77.2

package/dist/hitl/hitlBridge.js

@@ -3,23 +3,8 @@ import { eventSeq } from '../adapter/types.js';
 import { hostLog } from '../host.js';
 import { abortableSleep } from '../abortableSleep.js';
 import { suspendedReopenOf } from './suspendedReopen.js';
-// ── deny/plan-review 归因的 wire 窄化(0.28.0 发版扫描 F1/F2/F3 收编;单源,三条腿共用)──────
-//
-// server 对 `/decide` 与 plan-review 两条腿的 `reason` 同限 `MAX_APPROVAL_REASON_CHARS`(4096 字符,
-// 超限 **413 `reason_too_large`**;server 侧 reason 入签后无法替发送方截 —— 超长原样发出去,丢掉的
-// 不是归因而是**整次决断**:413 ⇒ 决断没送达 ⇒ run 留 suspended)。所以三条 reason 出口(卡 deny /
-// canUseTool deny / plan-review)全部经本窄化器,绝不裸发。
-/** durable `/decide` 腿的既有缺省拒因(不带归因时逐字不变 —— 0.27.0 及之前的 wire 字节)。 */
 export const DEFAULT_DENY_REASON = 'The user rejected this tool use';
-/** server 两条腿共用的 reason 字符上限(超限 413,决断被打回)。 */
 const MAX_DENY_REASON_CHARS = 4096;
-/**
- * 归因原文 → 可上 wire 的形。缺席/非串/纯空白 ⇒ `undefined`(调用方自定回落:deny 腿落
- * {@link DEFAULT_DENY_REASON},plan-review 腿键不落);超上限 ⇒ 截到上限并 debug 留痕。
- * 🔴 截断**边界安全**:切点落在代理对中间会产出孤高代理 —— server 长度检查放行,但 UTF-8
- * 落库/入签时末尾退化成 U+FFFD,两侧字节不一致还会毒化签名对账。末码元是高代理就再退一位。
- * 🔴 只做归因,不参与裁决:任何返回值都不改变这次决断本身。
- */
 export function denyReasonForWire(reason, tag) {
     if (typeof reason !== 'string')
         return undefined;
@@ -31,66 +16,25 @@ export function denyReasonForWire(reason, tag) {
     let cut = trimmed.slice(0, MAX_DENY_REASON_CHARS);
     const last = cut.charCodeAt(cut.length - 1);
     if (last >= 0xd800 && last <= 0xdbff)
-        cut = cut.slice(0, -1); // 孤高代理:退一位,绝不发半个字符
+        cut = cut.slice(0, -1);
     hostLog('debug', `hitlBridge: reason for ${tag} truncated ${trimmed.length}→${cut.length} chars ` +
         `(server caps approval reason at ${MAX_DENY_REASON_CHARS}; over-cap is a 413 reason_too_large that would drop the DECISION, not just the reason)`);
     return cut;
 }
-/** 契约 §4c `permissionModeAfter` 的闭集两词(`acceptEdits` = 工作目录内的写不再逐次征询;`default` = 每次写照常征询)。 */
 export const PLAN_REVIEW_MODE_AFTER_WORDS = Object.freeze(['default', 'acceptEdits']);
-/** 这个值是不是闭集里的词(词表外 —— 含 `plan` / `bypassPermissions` / `auto` —— 引擎 400:一次批准不许顺带关掉征询面)。 */
 export function isPlanReviewModeAfter(v) {
     return v !== undefined && PLAN_REVIEW_MODE_AFTER_WORDS.includes(v);
 }
-/** A safety stop: a contract law was about to be violated (e.g. a binding mismatch, a wrong-gate route).
- *  The caller MUST re-present to the human or surface the error — NEVER silently retry or auto-decide
- *  (contract/04 §9.1 fail-closed law). */
 export class HitlSafetyError extends Error {
     code;
-    constructor(message, 
-    /** A stable code the shell can branch on (REF-CC-036,2026-08-02:闭集联合,不再是开集 string —
-     *  与同族兄弟 `controlRouter.ts` 的 `ControlSafetyError.code` 同形)。 */
-    /** 🔴 闭集(FIX② 2026-08-07 加 `empty_answer`,第 5 员)。加员必须**同批**改齐
-     *  `parkResolver.GATE_FAILURE_CODES` 白名单 —— 那道白名单把不认得的码降成 `undefined`,
-     *  一边加一边不改另一边 = 新码在消费端被静默吞掉(比不加还坏:本地拦住了,判词却丢了)。 */
-    code) {
+    constructor(message, code) {
         super(message);
         this.code = code;
         this.name = 'HitlSafetyError';
     }
 }
-/**
- * 🔴 **编译期负控**(对抗复审 [medium] 采纳,0.48.0):三位必须**全 `readonly`**。
- *
- * 0.47.0 的自铸形三位逐个写着 `readonly`,而上游 `ApprovalStaleCurrentPending` 的成员是**可写**的
- * —— 首版别名(`NonNullable<…>`,不带 `Readonly<>`)把这条已发布的类型契约悄悄弱了一档:
- * 消费方从此可以直接改写 `boundCallId` / `boundInputHash`,而那两位的契约恰恰是
- * **逐字回显、绝不本地重算**(§9.1;本地重算一次就会把一次合法审批 fail-close 掉)。
- * 🔴 这类退化**没有任何行为门看得见**(它不改变任何运行期字节)—— 名字在、字段在、行为门全绿。
- *    所以钉必须下在编译期:`Readonly<>` 哪天被顺手摘掉,这一行当场编译错。
- */
 const _gateCurrentPendingReadonlyPin = true;
 void _gateCurrentPendingReadonlyPin;
-/**
- * 从一次 decide 失败(任意抛出物)里读出 {@link GateCurrentPending} —— 读不出即 `undefined`。
- *
- * 🔴 **结构视图读,不 `instanceof`**(两条理由,都是承重的):
- *   ① **供给面**:本包的 decide 出站走的是宿主注入的 `HitlClientLike`(见该型)。抛出来的到底是不是
- *      SDK 的 `ApprovalStaleError` 由**宿主**决定 —— web/desktop 完全可以注入自己的传输层。拿
- *      `instanceof` 当闸,等于让「宿主用的是哪一份 SDK 实例」决定一个纯读值的位在不在
- *      (跨 realm / 双实例 = `HitlSafetyError` 判型契约踩过的同一个坑,见 §4e)。
- *   ② **类型面**(0.48.0 就地订正):0.47.0 这条写的是「`ApprovalStaleError.currentPending` 只在
- *      sdk ≥7.3.0 上声明,而本包地板是 7.2.0」——**地板已抬到 `>=7.4.0`,那半条不再成立**。
- *      但本条的**结论不变**,因为承重的从来是 ① 那半:即使类型面现在够得着,抛出来的对象仍由宿主
- *      的传输层决定,`instanceof` 依旧是错的判据。⇒ 保留宽读,只订正理由。
- * 🔴 **判据锚在「值本身合不合形」,不锚它骑在哪个类/哪个 errorCode 上**
- *    ([anchor-on-the-deciding-quantity]):真正决定「壳能不能一跳重定位」的量,是**这个三元组的
- *    两件必填位在不在且是非空串** —— 而不是错误的类名。宽读在这里是**方向安全**的:本位不参与
- *    任何裁决(见 {@link GateCurrentPending} 顶注),多读到一次的代价 = 多一条指路;漏读的代价 =
- *    退回整队重拉。
- * 🔴 **两件必填位缺一即整只不铸**:半个三元组重定位不了(`decide` 要的是 boundCallId 本体),
- *    铸一个残形只会让消费点以为「有指路」。`boundInputHash` 是**行上有才带**的可选位,缺席照铸。
- */
 export function readDecideCurrentPending(e) {
     const raw = e?.currentPending;
     if (typeof raw !== 'object' || raw === null)
@@ -108,132 +52,23 @@ export function readDecideCurrentPending(e) {
             : {}),
     };
 }
-/**
- * 从一次 decide / 取件失败(任意抛出物)里读出**引擎的机器码** —— 读不出即 `undefined`。
- *
- * 🔴 **为什么这一位非透出不可**(0.60.0;上游候包件 ②,与 0.47.0 补 `currentPending` **同形**):
- *    本包把 typed 错**拍平成 `reason` 串**交给消费点(`FsApprovalOutcome.failed.reason`),于是
- *    「只读 outcome 形」的消费者(壳的重开链、迟到决断代理)对机读码**全盲** —— 要分辨
- *    `resume.preflight_rejected` / `approval_stale` / 传输类失败,只能去正则匹配那句拍平文案,
- *    而那句文案里嵌的是 `String(e)`(上游一改措辞就静默空转)。上游为此在壳里绕了一整圈
- *    (把 client 套进代理、站在拍平**之前**读)——那圈本该由这一位省掉。
- * 🔴 **结构视图读,不 `instanceof`**:理由与 {@link readDecideCurrentPending} 逐字同一条 ——
- *    抛出来的是不是 SDK 的错误类由**宿主注入的传输层**决定(跨 realm / 双实例)。
- * 🔴 **键位只认 `errorCode`**([2055] 死键纪律,退役的 `code` 槽不做兼容);非空串才算数,
- *    其余一律诚实缺席。
- * 🔴 **只搬运不解释**:本读口不判任何码属于哪一族(词表属主在 server/core,开集)——消费点分支
- *    已知码、永远带 `default`。
- * 🔴 **绝不把它当凭证面**:`errorCode` 是机器码,不是错误正文;错误正文(可能含凭据/内部路径)
- *    照旧**不**经本位外流。
- */
 export function readWireErrorCode(e) {
     const raw = e?.errorCode;
     return typeof raw === 'string' && raw.length > 0 ? raw : undefined;
 }
-// ── decide 出站的瞬断分诊与有界重试(Inkglow-1085 P0a,2026-08-19;[4664] server 定谳后对表)────
-//
-// 病形(案卷 INKGLOW-1085 车1 全链):`approvals.decide` 是**非 submit POST** —— SDK transport 对它
-// `maxAttempts = 1`(「a decide must not double-act」),且每发带显式 `AbortSignal.timeout(timeoutMs)`
-// (缺省 60s;per-call opts 只有 `signal`,调用方 signal 与之**合流取先**,只能收短、不能放长 ——
-// timeoutMs 是 client 构造级旋钮,本包对已构造的注入 client 不可配)。于是一次网络瞬断/超时 =
-// decide 单发即死 → 上层拼 `failed` → parkResolver 合成 `hitl_unanswered` 终帧 → ask 死局。
-//
-// 🔴 **口径换代(#318 件②,2026-08-21):超时从「常态」变「真异常」** —— [4664] 的长调用口径作废。
-// server #316([4687] 点名 BREAKING,随 7.37.0 发车)把任务级 decide 的 200 体从**终局形**改成
-// **受理回执** `{taskId, sessionId, status:"resuming", bindingEnforced:true}`:受理点设在 core
-// `resumeStream` 解析之后,一切会变成拒绝的判定(lease 429 / markResuming CAS 409 / core pre-CAS
-// 守卫 / 绑定不符 409 / 卡不在 404)**仍同步发生**,受理后只剩模型段异步跑。实测受理即回 ≈23ms。
-// ⇒ 对 ≥7.37 的部署,一次 60s 超时**不再是**「server 还在跑 resume」的常态,而是**真异常**
-// (网络路径断在半途 / server 病态卡死 / 见下两条残余形)。口径随之收窄:
-//   · **超时类**(TimeoutError = SDK per-attempt 帽掐断)⇒ 仍带退避重试(重试环结构不动),但总窗
-//     从 10 分钟收到 {@link DECIDE_TIMEOUT_RETRY_TOTAL_BUDGET_MS}(十秒级,见该常量的取值推导);
-//   · **网络断类**(ECONNREFUSED / fetch failed 等:连语义答复都没拿到,引擎多半真死)⇒ 重试
-//     **恰一次**,让真死尽快显形;
-//   · 语义答复类(带 HTTP status 的 4xx/5xx —— 引擎收到并回答了)⇒ 零重试,原样上抛;
-//   · `HitlSafetyError`(binding mismatch 等安全信号)⇒ 恒零重试(§9.1 铁律,原有行为不动);
-//   · 调用方已中止(用户 Esc)⇒ 零重试(AbortError 是人按的,不是瞬断)。
-//
-// 🔴 为什么重试不违反「decide 绝不 double-act」:①[4664] 原话 —— **重复 decide 不双跑,server CAS
-// 保证**(重试幂等安全,放心重试);②D-1 绑定回显(boundCallId+boundInputHash 逐字回显,server
-// fail-closed on mismatch)—— 第一发其实送达时,重发只能撞 4xx(approval not found / conflict),
-// 绝不可能批掉**另一件**事;那个 4xx 原样上抛,parkResolver 的「已解决重放救回」判据照认。
-// 重试耗尽(超时类窗尽 / 网络断类第二发仍断)⇒ 抛 {@link DecideTransportRetryExhaustedError}
-// (typed 判别位)—— 消费方(toolApprovalWire / parkResolver)据此走**重呈臂**而不是把 turn 判死。
-// 引擎真死时失败也会尽快显形:重呈臂的下一步(approvals.list / runs.events)对死引擎当场失败,
-// 走既有诚实红。
-// 🔴 **两条残余的同步形如实登记**(收窄不是「长调用消失了」,[4687] 逐字):终局形仍存在于
-//   ① **pre-7.37 的 server**(所有 decide 都是终局形 = 真长调用);② **≥7.37 但没有 durable run 行
-//   可跟的部署**(那里提前受理 = 把结果扔掉,所以腿如实保持同步)。本包是三端共用件,面向的是
-//   任意部署 —— 所以重试环**保留**、总窗**不设 0**。这两形上窗尽的代价是可接受的:耗尽走的是
-//   {@link DecideTransportRetryExhaustedError} → **重呈臂**(re-attach ⇒ durable 流重放 park ⇒
-//   同一张卡重交用户),而不是把 turn 判死;若第一发其实已送达,重呈的下一步会撞
-//   `isAlreadyResolvedGateReason` 的已解决判据被救回。
-// 🔴 请托半场(候协作板):SDK decide 若开 per-call timeoutMs(或对 HITL 面单列长缺省),本层的
-// 超时类重试环可整段收敛成一发长等待。
-/** 瞬断重试的起始退避(×2 递增,封顶 {@link DECIDE_RETRY_BACKOFF_MAX_MS};别把 decide 打成连发)。 */
 const DECIDE_TRANSPORT_RETRY_BACKOFF_MS = 750;
 const DECIDE_RETRY_BACKOFF_MAX_MS = 5_000;
-/**
- * SDK 的 **per-attempt 超时帽**(`AbortSignal.timeout(timeoutMs)`)的**缺省值**。
- *
- * 🔴 **它是「观察到的缺省」,不是本包能保证的量**(对抗复审 [medium] 采纳,2026-08-21)。
- * per-call opts 只有 `signal`(与之合流取先,只能收短不能放长),但 `timeoutMs` 是 **client
- * 构造级**旋钮,而本桥吃的是**宿主注入的** client(`HitlClientLike` 根本不暴露它)⇒ 一个 web/桌面
- * 宿主完全可以用 30s 或 120s 的 client 构造本桥。所以任何「总窗 ÷ 帽 = 发数」的推导都只在缺省值
- * 上成立,**不能当成本共用件的性质**。
- * ⇒ 本常量只用来推导下面那个**墙钟上界**;「至少重试一次」这条**性质**改由
- * {@link DECIDE_TIMEOUT_MIN_ATTEMPTS} 用**发数**保证,与宿主的 timeoutMs 无关。
- */
 const DECIDE_ATTEMPT_TIMEOUT_CAP_MS = 60_000;
-/**
- * 超时类**最少发数**(首发 + 至少一次重试)—— 与墙钟窗**两个独立的界**,不是第二层节奏。
- *
- * 🔴 为什么必须有它([4687] 登记的两条残余同步形是承重理由):终局形仍存在于 pre-7.37 的 server
- * 与「≥7.37 但没有 durable run 行可跟」的部署 —— 那两形上一次超时**极可能是真的还在跑**,
- * 至少给一次重试是这条腿唯一的补救。若只用墙钟窗判,宿主拿 120s 的 client 构造本桥时首发超时
- * 那一刻 elapsed 已经 ≥ 窗 ⇒ **一次重试都没有**,而这件事在代码里毫无痕迹(注释还写着「恰一次重试」)。
- * 🔴 这**不是** [4675] 说的「第二层节奏叠乘」:没有新增任何定时器/退避层,退避仍是同一条
- * `backoff` 链;这只是同一个循环上的第二个**终止条件**(发数尽 ∧ 窗尽,两者都满足才停)。
- */
 const DECIDE_TIMEOUT_MIN_ATTEMPTS = 2;
-/**
- * 超时类重试的总窗(#318 件② 收窄:`10 * 60_000` → 本值)。
- *
- * ── 取值推导(锚在 {@link DECIDE_ATTEMPT_TIMEOUT_CAP_MS} 上,不是拍脑袋的整数)────────────────
- * 窗的语义是**不再起新发**(见下),而每一发超时类失败**本身**就要吃满一个 per-attempt 帽 ⇒
- * 实际发数由「总窗 ÷ 帽」决定,且量化得很粗:
- *   · 窗 ≤ 1 帽  ⇒ 窗判本身当场耗尽;
- *   · 1 帽 < 窗 ≤ 2 帽 ⇒ 窗判允许恰一次重试(共 2 发);
- *   · > 2 帽 ⇒ 3 发起步,一路回到分钟级。
- * 受理形下超时是**真异常**(不是「还在跑」),所以取**恰一次重试**那一档:一次重试足够吃掉单次
- * 网络抖动,再多就是对着一个病态 server 空等。取 90s = 1.5 帽,**刻意落在区间中部**而不是边界
- * (120s 恰等于 2 帽 + 退避,会让发数悬在退避时序的一根头发上)。
- * ⇒ 在缺省帽上可预算的最坏墙钟 ≈ 60s(首发)+ 0.75s(退避)+ 60s(重发)≈ 121s,而不是旧口径的 10 分钟。
- *
- * 🔴 **本窗只是墙钟上界,不承诺发数**(复审 [medium] 采纳):宿主可以用非缺省 `timeoutMs` 构造
- * client(见 {@link DECIDE_ATTEMPT_TIMEOUT_CAP_MS}),那时「窗 ÷ 帽」得出的发数与这里写的不同。
- * 与宿主无关的那条性质(**至少重试一次**)由 {@link DECIDE_TIMEOUT_MIN_ATTEMPTS} 单独保证 ——
- * 两个界合取:**发数达标 ∧ 窗尽** 才停。所以在 120s client 上是「2 发、~240s」,在 30s client 上
- * 是「3 发、~92s」,在缺省 60s 上是「2 发、~121s」—— 三者都有界,且都拿得到那一次重试。
- *
- * 🔴 窗的语义是**不再起新发**,刻意不掐在飞那一发(对抗复审议题,驳回后成文):给一发可能已被
- * server 受理的 decide 塞截止 signal 换不来任何安全 —— server 侧照跑,客户端只多制造一个「送达
- * 未知」。
- * 🔴 **写成「帽 × 系数」而不是裸 90_000**:上面那段推导只有在两者绑在一起时才会随 SDK 改帽自动
- * 跟手;写裸整数的话,SDK 哪天把帽改成 30s,注释里的「恰一次重试」当天变成假话而代码全绿。
- */
 const DECIDE_TIMEOUT_RETRY_BUDGET_ATTEMPT_MULTIPLE = 1.5;
 const DECIDE_TIMEOUT_RETRY_TOTAL_BUDGET_MS = DECIDE_ATTEMPT_TIMEOUT_CAP_MS * DECIDE_TIMEOUT_RETRY_BUDGET_ATTEMPT_MULTIPLE;
 let decideTimeoutRetryBudgetOverrideMs;
-/** 测试钩:把超时类重试总窗调小(传 undefined 还原缺省)。 */
 export function __setDecideTimeoutRetryBudgetForTests(ms) {
     decideTimeoutRetryBudgetOverrideMs = ms;
 }
 function decideTimeoutRetryBudgetMs() {
     return decideTimeoutRetryBudgetOverrideMs ?? DECIDE_TIMEOUT_RETRY_TOTAL_BUDGET_MS;
 }
-/** 超时类判别(自身或 cause 链上的 TimeoutError —— SDK per-attempt `AbortSignal.timeout` 的产物;
- *  [4664] 口径下它多半意味着 server 仍在同步跑 resume,不是引擎死了)。 */
 function isDecideAttemptTimeout(e, depth = 0) {
     if (depth > 3 || e === null || typeof e !== 'object')
         return false;
@@ -242,17 +77,11 @@ function isDecideAttemptTimeout(e, depth = 0) {
         return true;
     return isDecideAttemptTimeout(o.cause, depth + 1);
 }
-/** 瞬断类网络错误码(自身或 cause 链上;undici 的 fetch failed 把真因挂在 cause)。 */
 const TRANSIENT_NETWORK_CODES = new Set([
     'ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EPIPE', 'EAI_AGAIN',
     'ENETUNREACH', 'EHOSTUNREACH', 'ECONNABORTED',
     'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT', 'UND_ERR_SOCKET',
 ]);
-/**
- * decide 出站失败的瞬断判别(module 私有 —— 唯一消费点是 {@link HitlBridge} 的 decide choke point)。
- * 🔴 方向:判不出一律**非瞬断**(fail 到「不重试」侧 —— 语义拒绝被误判成瞬断才是真事故:那会把
- * 一次已被拒绝的决断再发一遍)。带数字 `status` 的错误 = 引擎**答了**,无论 4xx/5xx 都不是瞬断。
- */
 function isTransientDecideTransportFailure(e, depth = 0) {
     if (depth > 3 || e === null || typeof e !== 'object')
         return false;
@@ -269,96 +98,16 @@ function isTransientDecideTransportFailure(e, depth = 0) {
         return true;
     return isTransientDecideTransportFailure(o.cause, depth + 1);
 }
-/**
- * decide 出站在瞬断类失败上重试一次**仍未送达**(两发都没拿到引擎的语义答复)。
- *
- * 🔴 判别位契约:消费方(`toolApprovalWire` 的 catch 臂 / `parkResolver.surfaceGateAndDecide`)
- * 据 `instanceof` 在 outcome 上 stamp `retryExhausted: true`,parkResolver 对该位走**重呈臂**
- * (re-attach ⇒ durable 流重放 park ⇒ 同一张卡重新交给用户),不再合成 `hitl_unanswered` 把 turn
- * 判死 —— run 仍 parked、pending 行仍可决,判死是三条出路里唯一不可逆的那条。
- * 🔴 message 刻意避开 `isAlreadyResolvedGateReason` 的词表(no pending checkpoint / resolved /
- * already / not found):被那把兜底尺误判成「已解决」会走成静默 reattach,判别位就白铸了 ——
- * pure 门(hitl-gate-honesty F6-d)有常驻负控钉着这一条。
- */
 export class DecideTransportRetryExhaustedError extends Error {
     attempts;
-    constructor(
-    /** 实际发出的次数(网络断类 = 2:首发 + 单次重试;超时类 = 总窗内发出的全部)。 */
-    attempts, lastFailureText) {
+    constructor(attempts, lastFailureText) {
         super(`decide did not reach the engine after ${attempts} attempts (transient transport failure): ${lastFailureText}`);
         this.attempts = attempts;
         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`)
- * BEFORE they know which specific call/question they're presenting — that is the FIRST fetch, the one
- * that decides what gets rendered on the card/overlay.
- *
- * REF-CC-029(2026-08-02,消 hitl2-08/hitl2-01 双病根):this used to be three near-identical copies
- * (this file's own `HitlBridge.findPending` plus one each in `toolApprovalWire.ts` / `askGateWire.ts`),
- * and only `HitlBridge.findPending`'s copy had a `?? pending[0]` last-resort fallback (REF-CC-022) that
- * could resolve a DIFFERENT session's or a background subagent lane's pending row once this taskId's own
- * rows were gone — they all share the same `/v1/approvals` queue. Single-sourcing this lookup here means
- * that divergence can't recur, and passing the resolved row straight into `decideTool`/`answerQuestion`'s
- * `preResolvedPending` param closes the TOCTOU window between "the row the human saw" (this fetch) and
- * "the row decide resolves" (previously a SECOND independent fetch inside the bridge).
- *
- * Match by `taskId` + a caller-supplied predicate over the row's `toolName` (the tool family this wire
- * cares about, e.g. fs-write vs AskUserQuestion) first; fall back to ANY row for this `taskId` (a gate
- * 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
- * empty-toolName card whose decide then 409s (`gate_not_tool_approval`). A foreign-kind row is filtered
- * 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, 
-/**
- * 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)) {
+export async function findPendingForTask(client, taskId, matches, opts, callId, identityAccepts = (r) => matches(typeof r.toolName === 'string' ? r.toolName : undefined)) {
     let rows;
     try {
         rows = (await client.approvals.list(opts)).pending;
@@ -367,29 +116,10 @@ identityAccepts = (r) => matches(typeof r.toolName === 'string' ? r.toolName : u
         return { ok: false, reason: `approvals.list failed: ${String(e)}` };
     }
     const decidable = rows.filter((r) => askParkForeignGateKind(r) === null);
-    // 🔴 身份腿**约束在本 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)) ??
@@ -398,25 +128,17 @@ identityAccepts = (r) => matches(typeof r.toolName === 'string' ? r.toolName : u
         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 };
 }
-/**
- * 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.
- */
 export class HitlBridge {
     client;
     taskId;
     active = null;
-    constructor(client, 
-    /** The suspended run's taskId — the handle plan_review/resume address (RunReceipt.taskId). */
-    taskId) {
+    constructor(client, taskId) {
         this.client = client;
         this.taskId = taskId;
     }
-    /** Observe a downstream event; latch the gate on `suspended`, clear it on a resuming/terminal arm. */
     observe(ev) {
         switch (ev.type) {
             case 'suspended':
-                // gate may be null (Event_suspended 'null' arm) → a generic "needs you" pause (contract/08 CS-9).
                 if (ev.gate) {
                     this.active = { gate: ev.gate, seq: eventSeq(ev), reopened: suspendedReopenOf(ev) };
                 }
@@ -429,63 +151,26 @@ export class HitlBridge {
                 this.active = null;
                 break;
             default:
-                // running again (text / tool_start / turn_end / …) → the gate cleared when decide resumed the stream.
                 if (this.active && (ev.type === 'text' || ev.type === 'tool_start' || ev.type === 'turn_end')) {
                     this.active = null;
                 }
                 break;
         }
     }
-    /** The gate currently awaiting a human, if any. The shell branches on `gate.kind` to pick the chrome. */
     currentGate() {
         return this.active?.gate ?? null;
     }
-    /**
-     * 0.74.3 CC-73:当前挂起是不是一次 reopen(`suspended.reopened` 三态);没挂起 ⇒ `null`。
-     * 消费方据此把「真 reopen 成功、重试会重放」那半句说出来:`reopened` 在场码 ⇒ 卡仍 pending、决定没被消费、可再决;
-     * `not_reopened` / `unstated` ⇒ 普通挂起,一个字都不多说。
-     */
     currentGateReopen() {
         return this.active?.reopened ?? null;
     }
-    /**
-     * 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`)。
-     * 名字也一并换掉:撞名正是「看起来只有一份实现」的成因。
-     *
-     * 谓词传 {@link ANY_TOOL_FAMILY}:桥这一层对工具族**没有意见**(人刚刚决断的是哪张门就是哪张),
-     * 与旧私有件的 taskId 兜底逐字同语义;身份腿(`toolUseID`)由单源函数的 `callId` 参数承接。
-     */
     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;
         throw new Error(found.reason);
     }
-    /**
-     * 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;
-     * compliant clients send ONLY the two-tuple, approvals.ts:23-27).
-     *
-     * pre-D-1 的 `{}` 回落臂已删(2026-08-03,#117 提货 / [2356]#2):server 5.x 的 decide 三键必填、
-     * 缺键 400,「发一个注定 400 的请求」不如在本地响亮失败——pending 行缺绑定键只可能来自
-     * 不再支持的旧 worker 或坏数据,fail-loud 带坐标好过静默烧一轮 HTTP。
-     */
     bindingOf(p) {
         if (p.boundCallId === undefined || p.boundInputHash === undefined) {
             throw new HitlSafetyError(`pending checkpoint ${p.id ?? '<no-id>'} is missing D-1 binding fields ` +
@@ -494,41 +179,7 @@ export class HitlBridge {
         }
         return { boundCallId: p.boundCallId, boundInputHash: p.boundInputHash };
     }
-    // ── §2. Permission gate: approve / deny a tool ──────────────────────────────
-    /**
-     * Resolve a `human` / `irreversible_ask` permission gate (contract/04 §2, §6.2; 08 IH-4/IH-10).
-     *
-     *  - `approve` → `{decision:"approve", boundCallId, boundInputHash}`; `updatedInput` rides along for
-     *    approve-with-edit (applied AFTER the binding check — the hash still binds the ORIGINAL input).
-     *  - `deny`    → `{decision:"deny", reason}`.
-     *
-     * 🔴 **§2.4「DENY-abort」撤稿(0.42.0;server [4833] 明请,契约成文 `4631a0f` 随 7.39 出)**。
-     *    本段原文写的是:「CANCEL a suspended run by DENYING, never by `runs.cancel` (**which 409s on a
-     *    suspended run** — contract/04 §2.4); the deny-and-abort `interrupt:true` EFFECT is *the run ends
-     *    after the deny*」。**三句话里有两句已被上游证伪,逐条**:
-     *      · **「deny 用来 cancel 一条 run」** —— `ASSISTANT-WIRE-CONTRACT.md` §4a 逐字反过来说:
-     *        **DENY is a TOOL-level answer, NEVER a run kill**;客户端不得把用户的拒绝译成 cancel。
-     *        两个动词的 wire 判别式是 `cancelled`(真取消)vs `gate.batch_halted`(裸拒的兄弟结算)。
-     *      · **「`runs.cancel` 对 suspended run 回 409」** —— 自 server [868] 起**就地取消**:
-     *        `runs.js` 的 cancel 腿对 SUSPENDED/needs_review 先结算 pending checkpoint(CAS expire)再
-     *        终态化,`cancelSuspended` 有实体,409 只剩 `conflict.approval_settled` 一条
-     *        (本仓 `docs/fresh-scan-client-core-2026-08-08.md` B型-5 已按真字节证伪,当时未跟修注释)。
-     *      · **仍然成立的那一句**:deny 之后 run 是否结束由**后端编排**决定,不是 wire 上的旗标
-     *        (裸拒 ⇒ `gate.batch_halted` + `haltedOnUserRejection`;带留言拒 ⇒ run 续跑)。
-     *    ⇒ 本方法的**行为一字未改**(它本来走的就是 §4a 说的那条 TOOL 级 decide 通路);改的是这段
-     *      引用错权威、并把一条早已失效的 409 断言当理由的散文。
-     *
-     * The resumed run continues its SAME durable stream. A binding mismatch (409) is re-raised as a
-     * `HitlSafetyError('binding_mismatch')` — the caller re-presents, NEVER auto-retries.
-     */
-    async decideTool(outcome, toolUseID, opts, 
-    /** REF-CC-029(2026-08-02):the pending row the caller ALREADY fetched (via `findPendingForTask`,
-     *  below) to render the card/overlay the human just decided on. When supplied, this method skips
-     *  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(缺省回落 `pendingForDecide` — 见其头注,那是单源 `findPendingForTask` 的一层出参映射). */
-    preResolvedPending) {
+    async decideTool(outcome, toolUseID, opts, preResolvedPending) {
         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');
@@ -537,12 +188,7 @@ export class HitlBridge {
             ? {
                 decision: 'approve',
                 ...this.bindingOf(pending),
-                // updatedInput is applied AFTER the binding check; binding still binds the ORIGINAL input.
                 ...(outcome.updatedInput !== undefined ? { updatedInput: outcome.updatedInput } : {}),
-                // accept-session 的 durable-park 半场(server 1.191 decide 契约 `remember:"session"` →
-                // approvalExemptionStore.grant(sessionId, toolName)= 同 session 该工具后续 ask 免 park。
-                // 需要 binding(上面已 echo)。调用方只在三选第 2 项才带;老 server 收到未知键按契约 400,
-                // 故带 remember 的 decide 失败时调用方要能回退纯 approve(见 liveToolApprovalWire)。
                 ...(outcome.remember !== undefined ? { remember: outcome.remember } : {}),
             }
             : {
@@ -552,30 +198,7 @@ export class HitlBridge {
             };
         return this.decideRaw(pending.sessionId, decision, opts);
     }
-    // ── §3. AskUserQuestion: answer through the same gate ───────────────────────
-    /**
-     * Answer an `AskUserQuestion` gate (contract/04 §4; 08 CS-16). Same suspended → decide loop as a
-     * permission gate, but the answer rides `ApprovalDecision.answer` as the worker-validated
-     * `{ answers: [{ header, selected, note? }] }` shape. The D-1 binding STILL binds (it is still a
-     * checkpoint). Each answer's `header` MUST match a question header (the worker 400s on mismatch).
-     *
-     * 🔴 FIX②(2026-08-07)—— **本地 fail-loud**:此前本方法对 `answers: []` 与「某条 `selected: []`」
-     * 零校验,一条注定 400 的请求照样出门。这不是「多一次往返」而已 ——
-     *   · 用户面只看到「作答失败」,而失败的原因(空作答)在壳侧一个字都没说;
-     *   · `ToolPermissionDecision.answer` 的头注自己写着「a silently emptied answer is the user's
-     *     choice being thrown away without anyone noticing」—— 那条纪律此前只写在类型注释里,
-     *     没有任何一层真的执行它;
-     *   · `{answers:[]}` 在 wire 上另有确切含义(question 域 **deny** 的 NO_HUMAN 形),把它当成一次
-     *     approve 发出去 = 拿 deny 的载荷冒充 approve。
-     * 三形一律抛 `HitlSafetyError('empty_answer')`,一次 decide 都不发:空 `answers[]` /
-     * 任一条 `selected[]` 为空 / 任一条 `header` 为空串。
-     */
-    async answerQuestion(answers, toolUseID, opts, 
-    /** REF-CC-029(2026-08-02):see `decideTool`'s same-named param — the pending row the caller already
-     *  fetched via `findPendingForTask`. */
-    preResolvedPending) {
-        // 🔴 校验在取件**之前**:入参坏了跟 pending 行在不在场无关,而先 list 再拒会把
-        //    「你的作答是空的」这条真判词换成「no_pending」那条假判词(行恰好过期时)。
+    async answerQuestion(answers, toolUseID, opts, preResolvedPending) {
         assertAnswersSendable(answers);
         const pending = preResolvedPending ?? (await this.pendingForDecide(toolUseID, opts));
         if (!pending) {
@@ -588,28 +211,11 @@ export class HitlBridge {
         };
         return this.decideRaw(pending.sessionId, decision, opts);
     }
-    // ── §4. plan_review: the distinct wire ──────────────────────────────────────
-    /**
-     * Resolve a plan-mode gate (contract/04 §3; 08 IH-6). Routed to `assistant.planReview`, NOT `decide`/
-     * `resume`. Also guards the `editedPlan` invariant (REQUIRED iff `decision==="edit"`, FORBIDDEN
-     * otherwise → 400) so the bad call never leaves the shell — that check is unconditional (no
-     * `observe()` dependency). The gate-kind guard below is host-optional (see its own comment); the
-     * server's 409 `gate_not_plan_review` is the real backstop either way.
-     */
     async reviewPlan(outcome, opts) {
-        // Gate-kind guard (contract/04 §3.1): plan_review parks as needs_review / plan_review, distinct from the
-        // approval family. REF-CC-028(2026-08-02,评注现势):this.active only latches when the host calls
-        // `observe(ev)` on the downstream stream — BOTH production construction points
-        // (askGateWire.ts / toolApprovalWire.ts) build a fresh `HitlBridge` per decide and never call
-        // `observe`, so `this.active` is null and this guard is a no-op there today. It is a host-optional
-        // auxiliary: a host that DOES drive `observe()` gets a local refuse instead of a round-trip; a host
-        // that doesn't (today's shell) relies entirely on the server's 409 `gate_not_plan_review` fail-closed
-        // path — the safety property holds either way, this guard just saves the round-trip when wired.
         const kind = this.active?.gate.kind;
         if (kind && kind !== 'plan_review' && kind !== 'needs_review') {
             throw new HitlSafetyError(`cannot plan-review a "${kind}" gate — a plan decision must never resolve a tool approval`, 'wrong_gate');
         }
-        // editedPlan invariant (contract/04 §3.1): REQUIRED iff edit, FORBIDDEN otherwise.
         if (outcome.decision === 'edit') {
             if (!outcome.editedPlan || outcome.editedPlan.length === 0) {
                 throw new HitlSafetyError('plan-review "edit" requires a non-empty editedPlan', 'bad_plan_edit');
@@ -618,8 +224,6 @@ export class HitlBridge {
         else if (outcome.editedPlan !== undefined) {
             throw new HitlSafetyError(`plan-review "${outcome.decision}" must NOT carry editedPlan`, 'bad_plan_edit');
         }
-        // 0.72.13 CC-46:permissionModeAfter invariant(契约 §4c)—— 只配 approve、闭集两词;坏形本地拦,一个字节都不出门
-        // (server 会 400 field_conflict / field_invalid,而那次决断就整个丢了)。拒文不回显调用方给的值。
         const modeAfter = outcome.permissionModeAfter;
         if (modeAfter !== undefined) {
             if (outcome.decision !== 'approve') {
@@ -629,16 +233,11 @@ export class HitlBridge {
                 throw new HitlSafetyError('plan-review permissionModeAfter must be "default" or "acceptEdits"', 'bad_plan_mode');
             }
         }
-        // sdk 9.6.0 的 PlanReviewRequest 尚未声明 permissionModeAfter ⇒ 交集型加一可选位(不断言、不 any);缺席 = 键不落。
         const req = { decision: outcome.decision };
         if (modeAfter !== undefined && isPlanReviewModeAfter(modeAfter))
             req.permissionModeAfter = modeAfter;
-        // eopt:上面的 invariant 检查已经保证 decision==='edit' ⇒ editedPlan 非空,但那道保证隔着一个
-        // 已经关闭的 if 块,TS 不跨块记账——这里重新直接判一次 undefined,narrowing 与赋值同一表达式内完成
-        // (PlanReviewRequest 是 SDK 外部 wire 型,不能改;诚实缺席 = 键不落,不传 `editedPlan: undefined`)。
         if (outcome.decision === 'edit' && outcome.editedPlan !== undefined)
             req.editedPlan = outcome.editedPlan;
-        // 0.28.0 发版扫描 F2:reason 经窄化器(超 4096 截断防 413 丢整次计划决断);空白 ⇒ 键不落。
         if (outcome.reason !== undefined) {
             const r = denyReasonForWire(outcome.reason, `plan-review ${this.taskId}`);
             if (r !== undefined)
@@ -646,15 +245,6 @@ export class HitlBridge {
         }
         return this.client.assistant.planReview(this.taskId, req, opts);
     }
-    // ── §5. resource_limit: continue ────────────────────────────────────────────
-    /**
-     * Continue a `resource_limit` slice pause (contract/04 §6.1; 08 IH-9). Bodyless `assistant.resume` — NOT
-     * `decide`. A `human`/`irreversible_ask` gate routed here would 409 `gate_not_resumable` (a "continue"
-     * must NEVER bypass a human approval). REF-CC-028(2026-08-02,评注现势):the local guard below is
-     * host-optional — it only fires when the host drives `observe(ev)` (neither production call site does
-     * today, see `reviewPlan`'s comment); the server's 409 is the fail-closed backstop that actually holds
-     * this invariant.
-     */
     async resumeResourceLimit(opts) {
         const kind = this.active?.gate.kind;
         if (kind && kind !== 'resource_limit') {
@@ -662,13 +252,7 @@ export class HitlBridge {
         }
         return this.client.assistant.resume(this.taskId, opts);
     }
-    // ── decide transport (the single choke point; maps 409 binding mismatch → safety stop) ──
     async decideRaw(sessionId, decision, opts) {
-        // Inkglow-1085 P0a([4664] 对表后形):瞬断类失败带退避有界重试 —— 超时类按长调用总窗,
-        // 网络断类恰一次;为什么重试不违反「decide 绝不 double-act」、哪些失败绝不重试,见文件上方
-        // DECIDE_TRANSPORT_RETRY 段总注。
-        // 🔴 经函数读 aborted(waitForClaimRelease.isAborted 同注):它在 await 两侧会变,直接读两次
-        // 会被 tsc 控制流分析把第二次窄成恒假比较(TS2367)。
         const callerAborted = () => opts?.signal?.aborted === true;
         const startedAt = Date.now();
         let attempts = 0;
@@ -678,45 +262,20 @@ export class HitlBridge {
             attempts++;
             try {
                 const r = await this.client.approvals.decide(sessionId, decision, opts);
-                // 🔴 **B-070(0.65.0):200 是投递受理,不是「门已解决」——所以这里不再清 `active`。**
-                //    sdk README §9.0.0 逐字:「workflow 车道的 200 只是**投递受理** —— 子代的 checkpoint 仍
-                //    pending,`/v1/approvals` 上那张卡**可能还在**。据 200 立刻把卡从 UI 抹掉,用户会看到
-                //    一张『批过了却还在』的幽灵卡」;core `runner/contracts.d.ts:1492` 同向(这一步
-                //    **launches the run that re-invokes**)。修前这一行正上方的注释自己写着「the gate clears
-                //    on the next running arm」—— 而代码在同一拍就把它清了,注释与码互相矛盾,矛盾的那一半
-                //    是码。
-                // ⇒ 判据锚换到**真正决定结果的量**上:`active` 由 {@link HitlBridge.observe} 在**流上的下一条
-                //   running 臂 / 终态臂**上清([anchor-on-the-deciding-quantity])。那条腿修前就在
-                //   (`observe` 的 `text`/`tool_start`/`turn_end`/`done`/`failed` 五臂),本批只是把抢跑的
-                //   那一行拿掉,没有新增任何清除路径。
-                // ⚠️ 影响面如实说:`active` 今天只在宿主真的驱动 `observe()` 时才 latch(两处生产调用点都
-                //    不驱动,见 `reviewPlan` 顶注),所以这一行的现实效果 = 对已驱动 observe 的宿主
-                //    (desktop/web 的座位层)不再谎报「门没了」;不驱动的宿主逐字节不变。
                 return r;
             }
             catch (e) {
                 if (isBindingMismatch(e)) {
-                    // contract/04 §2.2 / §9.1: a binding mismatch means the pending action changed under the human.
-                    // SAFETY signal — re-present to the human, NEVER auto-retry / auto-re-decide.
                     throw new HitlSafetyError('approval_binding_mismatch — the pending action changed under the human; refetch + re-present', 'binding_mismatch');
                 }
-                // 调用方已中止(用户 Esc)⇒ 这个 AbortError 是人按的,不是瞬断 —— 原错上抛,零重试。
                 if (!isTransientDecideTransportFailure(e) || callerAborted())
                     throw e;
                 if (isDecideAttemptTimeout(e)) {
-                    // #318 件② 后口径:受理形(server ≥7.37)下 decide 受理即回,一次 per-attempt 帽掐断
-                    // **是真异常**,不再是「server 还在跑 resume」的常态 —— 所以总窗只留恰一次重试的量
-                    // (推导见 DECIDE_TIMEOUT_RETRY_TOTAL_BUDGET_MS)。重发仍然安全:重复 decide 由 server CAS
-                    // 保证不双跑,首发其实送达时下一发只会撞 4xx(conflict/not-found ⇒ 上抛,已解决判据接手)。
-                    // 🔴 **两个界合取**(复审 [medium] 采纳):发数没达标就一定再发一次(与宿主的
-                    //    per-attempt timeoutMs 无关),达标之后才由墙钟窗决定还发不发。少了前半句,
-                    //    120s client 的宿主一次重试都拿不到;少了后半句,30s client 会一路重试到分钟级。
                     if (attempts >= DECIDE_TIMEOUT_MIN_ATTEMPTS && Date.now() - startedAt >= decideTimeoutRetryBudgetMs()) {
                         throw new DecideTransportRetryExhaustedError(attempts, String(e));
                     }
                 }
                 else if (netRetriesUsed >= 1) {
-                    // 网络断类(连语义答复都没有)重试恰一次 —— 引擎真死时让失败尽快显形。
                     throw new DecideTransportRetryExhaustedError(attempts, String(e));
                 }
                 else {
@@ -727,51 +286,30 @@ export class HitlBridge {
                     'at-most-once-effective: a landed first shot turns the retry into a 4xx, never a second act)');
                 await abortableSleep(backoff, opts?.signal ?? new AbortController().signal);
                 backoff = Math.min(backoff * 2, DECIDE_RETRY_BACKOFF_MAX_MS);
-                // 退避期间被中止 ⇒ 不再补发(abortableSleep 对 abort 是提前 resolve,不抛)。
                 if (callerAborted())
                     throw e;
             }
         }
     }
 }
-/**
- * Build a `CanUseToolFn` backed by the bridge. CC's loop calls it before any guarded tool; it surfaces the
- * gate via `prompt`, routes the human's decision to `approvals.decide` (binding echoed verbatim), and
- * returns the same `PermissionDecision` to unblock the loop. A `forceDecision` (CC's pre-resolved path)
- * short-circuits the prompt but STILL drives the decide verb so the backend resolves the checkpoint.
- */
 export function makeHitlCanUseTool(bridge, prompt) {
     return async (tool, input, _toolUseContext, _assistantMessage, toolUseID, forceDecision) => {
         const gate = bridge.currentGate();
         const decision = forceDecision ??
             (await prompt({ toolName: tool.name, input, toolUseID, gate }));
         if (decision.behavior === 'deny') {
-            // Deny → 一次 **TOOL 级**的 deny 应答(server `ASSISTANT-WIRE-CONTRACT.md` §4a;0.42.0 撤稿:
-            // 原文写的是「cancel-by-deny (contract/04 §2.4)」,而 §4a 逐字反对把拒绝读成 run kill ——
-            // 详见 `decideTool` 头注的撤稿段)。The deny message rides `reason`.
-            // 0.28.0 发版扫描 F1(P2):message 逐字嵌原始命令(壳侧 bashPermissions 无上限)——必须与
-            // 卡腿同门经窄化器截到 4096,否则 server 413 丢的是整次 deny(run 留 suspended)。
             await bridge.decideTool({ decision: 'deny', reason: denyReasonForWire(decision.message, `canUseTool ${toolUseID}`) ?? DEFAULT_DENY_REASON }, toolUseID);
             return decision;
         }
         if (decision.behavior === 'allow') {
-            // Approve (+ approve-with-edit via updatedInput, applied after the binding check).
             await bridge.decideTool(decision.updatedInput !== undefined
                 ? { decision: 'approve', updatedInput: decision.updatedInput }
                 : { decision: 'approve' }, toolUseID);
             return decision;
         }
-        // behavior === 'ask': not a wire decision — re-surface (the shell loops the prompt). Returned as-is so
-        // CC's loop re-asks; the bridge does NOT decide on an `ask`.
         return decision;
     };
 }
-// ── helpers ───────────────────────────────────────────────────────────────────
-/**
- * FIX②(2026-08-07):作答**出门前**的本地闭集校验(fail-closed;详见 `answerQuestion` 头注)。
- * 只判「这批作答在 wire 上有没有意义」,不判 header 与题面对不对得上 —— 后者的真源在 worker
- * (它持有题面),壳侧猜一份题面副本只会造出第二个真源。
- */
 function assertAnswersSendable(answers) {
     if (!Array.isArray(answers) || answers.length === 0) {
         throw new HitlSafetyError('refusing to send an EMPTY AskUserQuestion answer set — `{answers:[]}` is the wire\'s DENY/NO_HUMAN form, ' +
@@ -787,8 +325,6 @@ function assertAnswersSendable(answers) {
         }
     }
 }
-/** Marshal one answer into the worker-validated wire entry (contract/04 §4.1). Drops undefined `note`.
- *  REF-CC-038(2026-08-02):return 类型是 `AskAnswer` 本身(唯一源),不再是一份重写的内联匿名形。 */
 function marshalAnswer(a) {
     const entry = {
         header: a.header,
@@ -798,22 +334,17 @@ function marshalAnswer(a) {
         entry.note = a.note;
     return entry;
 }
-/** Detect a 409 `approval_binding_mismatch` across the SDK error shape variants (errorCode / code / status). */
 function isBindingMismatch(e) {
     if (!e || typeof e !== 'object')
         return false;
     const o = e;
-    // [1912] errorCode 恒在(server ≥1.302 canonical;全端引擎达标线 ≥1.303)——`?? o.code` 老兜底已清。
     const code = o.errorCode;
     if (code === 'approval_binding_mismatch')
         return true;
-    // SDK throws a named ApprovalBindingMismatchError (index.ts:19).
     if (typeof o.name === 'string' && o.name === 'ApprovalBindingMismatchError')
         return true;
     return false;
 }
-/** Build a CC deny `PermissionDecision` from a backend-driven denial (e.g. an SLA / policy auto-deny).
- *  The decisionReason is `asyncAgent` — the denial originated upstream, not from a local rule/mode. */
 export function backendDeny(reason) {
     return {
         behavior: 'deny',