@sema-agent/client-core 0.12.2 → 0.14.0

package/dist/hitl/planReviewWire.js

@@ -36,7 +36,7 @@
  * 挂账(诚实边界):approve 后壳本地的 plan-mode footer 徽章不自动退(CC 会退)——退 mode 的
  * app-state seam 不在本模块可达面,记 rc.47 接 REPL 层;engine 侧 handsReadOnly 已由 resume 处理。
  */
-import { publishQuestionFrame, registerLocalQuestionResponder, } from '../liveQuestionStore.js';
+import { publishQuestionFrame, registerLocalQuestionResponder, hasLocalQuestionResponder, } from '../liveQuestionStore.js';
 import { hostLog } from '../host.js';
 import { makeEngineWireClient } from '../engineWireSdk.js';
 import { engineWireTarget } from '../engineWireTarget.js';
@@ -44,8 +44,31 @@ import { enqueuePlanReviewOutcome } from '../notifications.js';
 /** resume 是 SYNC 驱动到终态的(可能分钟级)——原 raw fetch 无超时;SDK Transport 恒有每请求
  *  超时,取 6h 宽上界(诚实预算:超过它基本是引擎僵死,超时文案与网络失败同走 outcome 通知)。 */
 const PLAN_REVIEW_RESUME_TIMEOUT_MS = 6 * 60 * 60_000;
-const APPROVE_LABEL = 'Yes, approve and run the plan';
-const REJECT_LABEL = 'No, reject it (keep planning)';
+/**
+ * REF-CC-026:此前是 module-private 常量,唯一另一个消费者(cli `planReviewReopen.ts`)只能靠
+ * 人眼手抄同步(头注写着「与 client-core planReviewWire 的原卡逐字一致」)——漂一个字节,判决就
+ * 落到危险的默认臂(见下方 `planReviewDecisionFromAnswer` 的头注)。现在导出成唯一真源;cli 侧改
+ * import 是后续跟车工单(壳仓文件域,不在本卡范围)。
+ */
+export const PLAN_REVIEW_APPROVE_LABEL = 'Yes, approve and run the plan';
+export const PLAN_REVIEW_REJECT_LABEL = 'No, reject it (keep planning)';
+const APPROVE_LABEL = PLAN_REVIEW_APPROVE_LABEL;
+const REJECT_LABEL = PLAN_REVIEW_REJECT_LABEL;
+/**
+ * REF-CC-026:三值判决(此前 `selected === APPROVE_LABEL ? 'approve' : 'reject'` 把「没读懂/没
+ * 选」的第三种输入静默塌缩进危险的 reject 臂——overlay 的 dismiss/拒答语义是「送空 answers」,
+ * 与用户真的点了 REJECT_LABEL 长得一模一样)。两个标签都做**显式**等值比对,任何第三种输入
+ * (含 undefined)落 `'dismissed'`,由调用方决定是保持 park 还是显式当 reject 处理——本函数只
+ * 负责如实分类,不替调用方做选择。
+ */
+export function planReviewDecisionFromAnswer(answer) {
+    const selected = answer?.answers?.[0]?.selected?.[0];
+    if (selected === APPROVE_LABEL)
+        return 'approve';
+    if (selected === REJECT_LABEL)
+        return 'reject';
+    return 'dismissed';
+}
 /** done 帧的 plan_review park 形状(结构性读,别的终态一律 false)。 */
 export function isPlanReviewPark(result) {
     const r = result;
@@ -55,45 +78,109 @@ export function isPlanReviewPark(result) {
         typeof r.taskId === 'string' &&
         r.taskId.length > 0);
 }
+/**
+ * REF-CC-027:已武装未消解的 taskId 去重集(与 `HitlBridge`/`liveQuestionStore` 同款「进程内单例
+ * 承重不变量」——见 `docs/refactor/p1-scan/singleton-manifest.json` 登记)。durable re-attach 会把
+ * 同一个 `done{needs_review}` 帧再送一遍(与 askGateWire 的 `decidedGates` 同一族问题);此前
+ * `armPlanReviewApproval` 对同一 taskId 的重复调用会**再注册一次** responder(旧的注销函数被整个
+ * 丢掉),第二次注册会覆盖 `localResponders` 里的条目——若第一张卡此刻还没答,它的 unregister
+ * 闭包会变成一个指向"已被覆盖"槽位的悬空引用。这个集合让重复 arm 直接幂等短路,不再产生第二次
+ * `registerLocalQuestionResponder` 调用。
+ */
+const armedPlanReviewTaskIds = new Set();
+/** 测试钩:清掉武装态(不动 liveQuestionStore 本身,那边有自己的 reset)。 */
+export function _resetArmedPlanReviewsForTest() {
+    armedPlanReviewTaskIds.clear();
+}
+/** 合成 questionId 的唯一铸口(短路臂与首次 arm 共用,别各铸各的)。 */
+function planReviewQuestionId(taskId) {
+    return `plan-review:${taskId}`;
+}
+/** 审批卡的题面 —— 首次 arm 与「重放 arm 重新弹卡」共用同一份,两处不许各写一份。 */
+function publishPlanReviewCard(taskId) {
+    publishQuestionFrame({
+        type: 'question',
+        questionId: planReviewQuestionId(taskId),
+        questions: [
+            {
+                header: 'Plan review',
+                question: 'The plan is ready for review. Approve it and start the implementation?',
+                options: [
+                    { label: APPROVE_LABEL, description: 'Resume the task now and execute the plan (runs to completion engine-side)' },
+                    { label: REJECT_LABEL, description: 'Discard this plan and stay in plan mode to refine it' },
+                ],
+                multiSelect: false,
+            },
+        ],
+    });
+}
 /**
  * Arm the approval card for a parked plan_review (call with the RAW done.result). Returns true when
- * armed (live path + shape matched); false = caller renders the terminal as usual. Fail-soft: any
- * error inside must never break the stream drain.
+ * armed (live path + shape matched, INCLUDING the idempotent "already armed" short-circuit — see
+ * REF-CC-027 above); false = caller renders the terminal as usual. Fail-soft: any error inside must
+ * never break the stream drain.
  */
 export function armPlanReviewApproval(result) {
+    let armedTaskId;
     try {
         if (!isPlanReviewPark(result))
             return false;
         if (!engineWireTarget())
             return false;
         const { taskId } = result;
-        const questionId = `plan-review:${taskId}`;
-        registerLocalQuestionResponder(questionId, async (_id, answer) => {
-            const selected = answer?.answers?.[0]?.selected?.[0];
-            const decision = selected === APPROVE_LABEL ? 'approve' : 'reject';
+        if (armedPlanReviewTaskIds.has(taskId)) {
+            // REF-CC-027:同一张卡还没消解就被重放的 arm 撞上——幂等,**不二次注册** responder。
+            //
+            // [2393] hitl-F3(2026-08-02):但「不二次注册」不等于「什么都不做」。旧码在这里只打一行
+            // debug 就 `return true`,于是这条短路成了一堵挡死重开路径的墙:
+            //   · `liveQuestionStore.ts` 的契约明写「dialog dismissed without answering ⇒ caller cleans
+            //     up」,而本模块**没有** dismiss/abort 腿 —— 用户 Esc 关掉卡(不作答)之后,武装态
+            //     一直是 true,responder 也一直挂着;
+            //   · 此后每一次 arm(durable re-attach 重放 / 409 撞上再开)都走这条短路:**一张卡都不弹**,
+            //     调用方拿到 true 于是也不渲终帧 —— 用户面静默挂住,plan 卡在 park 里没有任何出口。
+            // 修法按「还在不在」分两支,两支都不产生第二次 `registerLocalQuestionResponder`:
+            if (hasLocalQuestionResponder(planReviewQuestionId(taskId))) {
+                // responder 还绑着 ⇒ 这张卡仍然可作答,只是可能已经不在屏上了。**重新弹一次**
+                // (同一个 questionId、同一份题面、同一个 responder):卡还开着的宿主只是收到一帧同形
+                // 的重绘,卡已经被 dismiss 的宿主则拿回了它的重开路径。
+                hostLog('debug', `planReviewWire: arm replayed — re-presenting the still-armed card for task ${taskId}`);
+                publishPlanReviewCard(taskId);
+                return true;
+            }
+            // responder 不在了(被别的注册顶掉后注销 / 被单方面清理)⇒ 武装态是**陈旧**的。
+            // 复用它 = 弹一张没有任何人能收答的卡(比不弹更坏:它看起来能点)。丢掉陈旧记号,
+            // 往下走整条重新 arm —— 这正是 REF-CC-027 头注里那个「悬空引用」形的收尾。
+            hostLog('debug', `planReviewWire: stale armed state for task ${taskId} (no local responder) — re-arming from scratch`);
+            armedPlanReviewTaskIds.delete(taskId);
+        }
+        armedPlanReviewTaskIds.add(taskId);
+        armedTaskId = taskId;
+        const questionId = planReviewQuestionId(taskId);
+        const unregister = registerLocalQuestionResponder(questionId, async (_id, answer) => {
+            // REF-CC-027:一次性 —— 首句就注销 + 清武装态(照 askGateWire 的 cleanup() 形)。
+            // liveQuestionStore.respondToQuestion 自身也是一次性取件(delete-before-invoke),这里是
+            // 第二道钉:武装态一清,同 taskId 才能重新正常 arm(证明 responder 真的落定了)。
+            unregister();
+            armedPlanReviewTaskIds.delete(taskId);
+            const decided = planReviewDecisionFromAnswer(answer);
+            if (decided === 'dismissed') {
+                // dismiss/无法判读:诚实缺席优先于编造默认值(REF-CC-026)——不静默驱动 decidePlanReview,
+                // 卡的重开路径把决定权还给用户。
+                return { ok: true };
+            }
             // fire-and-forget:resume 同步驱动到终态可能分钟级,不能挂住 overlay;结果经 queue 通知回来
-            void decidePlanReview(taskId, decision);
+            void decidePlanReview(taskId, decided);
             return { ok: true };
         });
-        publishQuestionFrame({
-            type: 'question',
-            questionId,
-            questions: [
-                {
-                    header: 'Plan review',
-                    question: 'The plan is ready for review. Approve it and start the implementation?',
-                    options: [
-                        { label: APPROVE_LABEL, description: 'Resume the task now and execute the plan (runs to completion engine-side)' },
-                        { label: REJECT_LABEL, description: 'Discard this plan and stay in plan mode to refine it' },
-                    ],
-                    multiSelect: false,
-                },
-            ],
-        });
+        publishPlanReviewCard(taskId);
         hostLog('debug', `planReviewWire: approval card armed for parked plan (task ${taskId})`);
         return true;
     }
     catch (e) {
+        // REF-CC-027:arm 本身失败(register/publish 抛)绝不能把 taskId 永久锁在武装态里
+        // ——那样这张卡再也无法被正常 arm 一次。
+        if (armedTaskId !== undefined)
+            armedPlanReviewTaskIds.delete(armedTaskId);
         hostLog('debug', `planReviewWire: arm failed (fail-soft): ${String(e)}`);
         return false;
     }
@@ -104,80 +191,99 @@ export function armPlanReviewApproval(result) {
  *  server body.error 原文)→ 同款「HTTP <status> <error>」outcome 文案;网络失败走原「could not
  *  reach the engine」臂。 */
 export async function decidePlanReview(taskId, decision) {
+    // REF-CC-025:此前 `cfg`/`client` 缺席各自 `return` 静默——卡已经对用户回了「收到」
+    // (armPlanReviewApproval 的 responder 早就 `return {ok:true}` 过了),但决断本身连一次网络
+    // 请求都没发出去,而模型/用户没有任何回程信号。两条早退现在都汇进同一条 outcome 管道(下方
+    // 唯一的 enqueue 调用点),不再是两条独立的静默 return。
+    let outcome;
     const cfg = engineWireTarget();
-    if (!cfg)
-        return;
-    const client = makeEngineWireClient({
-        baseUrl: cfg.baseUrl,
-        ...(cfg.token ? { token: cfg.token } : {}),
-        principal: cfg.principal,
-        timeoutMs: PLAN_REVIEW_RESUME_TIMEOUT_MS,
-    });
-    if (!client)
-        return;
-    let outcome = '';
-    try {
-        const body = await client.assistant.planReview(taskId, { decision });
-        hostLog('debug', `planReviewWire: ${decision} → ok ${JSON.stringify(body).slice(0, 200)}`);
-        // [2315]/[2316](#109,2026-08-02):decide 的 **2xx 不当终态** —— test 黑盒实测 reject 9/9
-        // 返回 200 而会话仍锁在同一 gate(core RB-471:重开兜底对 reject 腿恒真误触发)。这里回拉
-        // 一次任务状态,按真形分三路措辞;根因归 core/server,本腿是「对外动作回读验证」在产品面的
-        // 同款,上游修后仍有价值(approve 合法推进新 gate 的形也靠它说真话)。
-        // 回拉用**短超时**独立 client(15s):verify 腿挂住不该占用 decide 的 6h 宽预算。
-        let postStatus;
-        try {
-            const probe = makeEngineWireClient({
-                baseUrl: cfg.baseUrl,
-                ...(cfg.token ? { token: cfg.token } : {}),
-                principal: cfg.principal,
-                timeoutMs: 15_000,
-            });
-            const post = probe ? (await probe.runs.get(taskId)) : null;
-            postStatus = typeof post?.status === 'string' ? post.status : undefined;
-        }
-        catch (e) {
-            hostLog('debug', `planReviewWire: post-decide status re-pull failed (fail-soft): ${String(e)}`);
-        }
-        // 回拉失败时回落 decide 200 体自带的 status(次级来源;两者都缺=unverified,措辞如实降级)。
-        const effective = postStatus ?? (typeof body?.status === 'string' ? body.status : undefined);
-        if (effective === 'needs_review') {
-            // 决定没生效,仍锁原 gate。不渲「已处理」;真出路只有 approve 或 cancel(下一次提交撞 409
-            // 时 activeRunSelfHeal 会把审批卡重开——这里不自动重弹卡,避免「刚拒绝又弹卡」的突袭感,
-            // 决定权经卡的重开路径还给用户)。
-            outcome =
-                `The plan_review ${decision} returned HTTP 200 but the session is STILL locked on the same review gate ` +
-                    `(post-decide status: needs_review). The decision did NOT take effect (known engine issue, RB-471 family). ` +
-                    `Tell the user plainly that the ${decision} did not go through; the reliable exits today are approving the plan or cancelling the task.`;
-        }
-        else if (effective === 'suspended') {
-            // 合法推进到新 gate(test [2315] ②形):不是「完成」,如实说下一张审批卡会跟上。
-            outcome =
-                `The plan was ${decision === 'approve' ? 'approved' : 'rejected'} and the task advanced to a NEW approval gate ` +
-                    `(post-decide status: suspended) — the next approval card will surface it; this is not a completion yet.`;
-        }
-        else if (effective !== undefined) {
-            outcome = `The plan was ${decision === 'approve' ? 'approved and the parked task resumed to completion' : 'rejected (plan discarded)'} — final status: ${effective} (post-decide re-checked: task left the review gate).`;
-        }
-        else {
-            outcome = `The plan was ${decision === 'approve' ? 'approved and the parked task resumed to completion' : 'rejected (plan discarded)'} — final status: unknown (post-decide verification unavailable; treat as unconfirmed).`;
-        }
+    if (!cfg) {
+        hostLog('error', `planReviewWire: ${decision} NOT sent — engineWireTarget() unavailable`);
+        outcome = `The plan_review ${decision} could NOT be sent: no engine connection is configured on this host. Tell the user plainly that the decision did not go through.`;
     }
-    catch (e) {
-        // APIError 判型走 status duck-check(sseIdleTriage 同款纪律:双包时 instanceof 会分叉)。
-        const status = e?.status;
-        if (typeof status === 'number') {
-            const msg = e instanceof Error ? e.message : String(e);
-            hostLog('debug', `planReviewWire: ${decision} → ${status} ${msg.slice(0, 200)}`);
-            outcome = `The plan_review decision failed: HTTP ${status} ${msg}`.trim();
+    else {
+        const client = makeEngineWireClient({
+            baseUrl: cfg.baseUrl,
+            ...(cfg.token ? { token: cfg.token } : {}),
+            principal: cfg.principal,
+            timeoutMs: PLAN_REVIEW_RESUME_TIMEOUT_MS,
+        });
+        if (!client) {
+            hostLog('error', `planReviewWire: ${decision} NOT sent — makeEngineWireClient() returned null`);
+            outcome = `The plan_review ${decision} could NOT be sent: the engine client could not be constructed. Tell the user plainly that the decision did not go through.`;
         }
         else {
-            outcome = `The plan_review decision could not reach the engine: ${String(e)}`;
+            try {
+                const body = await client.assistant.planReview(taskId, { decision });
+                hostLog('debug', `planReviewWire: ${decision} → ok ${JSON.stringify(body).slice(0, 200)}`);
+                // [2315]/[2316](#109,2026-08-02):decide 的 **2xx 不当终态** —— test 黑盒实测 reject 9/9
+                // 返回 200 而会话仍锁在同一 gate(core RB-471:重开兜底对 reject 腿恒真误触发)。这里回拉
+                // 一次任务状态,按真形分三路措辞;根因归 core/server,本腿是「对外动作回读验证」在产品面的
+                // 同款,上游修后仍有价值(approve 合法推进新 gate 的形也靠它说真话)。
+                // 回拉用**短超时**独立 client(15s):verify 腿挂住不该占用 decide 的 6h 宽预算。
+                let postStatus;
+                try {
+                    const probe = makeEngineWireClient({
+                        baseUrl: cfg.baseUrl,
+                        ...(cfg.token ? { token: cfg.token } : {}),
+                        principal: cfg.principal,
+                        timeoutMs: 15_000,
+                    });
+                    const post = probe ? (await probe.runs.get(taskId)) : null;
+                    postStatus = typeof post?.status === 'string' ? post.status : undefined;
+                }
+                catch (e) {
+                    hostLog('debug', `planReviewWire: post-decide status re-pull failed (fail-soft): ${String(e)}`);
+                }
+                // 回拉失败时回落 decide 200 体自带的 status(次级来源;两者都缺=unverified,措辞如实降级)。
+                const effective = postStatus ?? (typeof body?.status === 'string' ? body.status : undefined);
+                if (effective === 'needs_review') {
+                    // 决定没生效,仍锁原 gate。不渲「已处理」;真出路只有 approve 或 cancel(下一次提交撞 409
+                    // 时 activeRunSelfHeal 会把审批卡重开——这里不自动重弹卡,避免「刚拒绝又弹卡」的突袭感,
+                    // 决定权经卡的重开路径还给用户)。
+                    outcome =
+                        `The plan_review ${decision} returned HTTP 200 but the session is STILL locked on the same review gate ` +
+                            `(post-decide status: needs_review). The decision did NOT take effect (known engine issue, RB-471 family). ` +
+                            `Tell the user plainly that the ${decision} did not go through; the reliable exits today are approving the plan or cancelling the task.`;
+                }
+                else if (effective === 'suspended') {
+                    // 合法推进到新 gate(test [2315] ②形):不是「完成」,如实说下一张审批卡会跟上。
+                    outcome =
+                        `The plan was ${decision === 'approve' ? 'approved' : 'rejected'} and the task advanced to a NEW approval gate ` +
+                            `(post-decide status: suspended) — the next approval card will surface it; this is not a completion yet.`;
+                }
+                else if (effective !== undefined) {
+                    outcome = `The plan was ${decision === 'approve' ? 'approved and the parked task resumed to completion' : 'rejected (plan discarded)'} — final status: ${effective} (post-decide re-checked: task left the review gate).`;
+                }
+                else {
+                    outcome = `The plan was ${decision === 'approve' ? 'approved and the parked task resumed to completion' : 'rejected (plan discarded)'} — final status: unknown (post-decide verification unavailable; treat as unconfirmed).`;
+                }
+            }
+            catch (e) {
+                // APIError 判型走 status duck-check(sseIdleTriage 同款纪律:双包时 instanceof 会分叉)。
+                const status = e?.status;
+                if (typeof status === 'number') {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    hostLog('debug', `planReviewWire: ${decision} → ${status} ${msg.slice(0, 200)}`);
+                    outcome = `The plan_review decision failed: HTTP ${status} ${msg}`.trim();
+                }
+                else {
+                    outcome = `The plan_review decision could not reach the engine: ${String(e)}`;
+                }
+            }
         }
     }
+    // REF-CC-025:唯一的 enqueue 调用点(三条上游路径——cfg 缺席 / client 缺席 / 正常决断—— 都汇到
+    // 这里)。返回值此前被丢弃:`enqueuePlanReviewOutcome` 返回 `false` 意味着队列口没装或没实现
+    // `enqueueMetaPrompt`(notifications.ts 头注:「模型永远不知道 plan 被批准/驳回后引擎跑出了
+    // 什么结果」),这是与 HTTP 失败同等重量的静默丢失,必须留痕。
     try {
-        enqueuePlanReviewOutcome(`<plan-review-outcome>\n${outcome}${decision === 'approve' ? `\nUse TaskOutput("${taskId}") if you need the resumed task's full output, then give the user a brief report of what was done.` : '\nBriefly acknowledge to the user that the plan was rejected and continue planning.'}\n</plan-review-outcome>`);
+        const delivered = enqueuePlanReviewOutcome(`<plan-review-outcome>\n${outcome}${decision === 'approve' ? `\nUse TaskOutput("${taskId}") if you need the resumed task's full output, then give the user a brief report of what was done.` : '\nBriefly acknowledge to the user that the plan was rejected and continue planning.'}\n</plan-review-outcome>`);
+        if (!delivered) {
+            hostLog('error', `planReviewWire: outcome enqueue MISSED (queue port not installed or lacks enqueueMetaPrompt) for task ${taskId} — model will not learn the ${decision} result`);
+        }
     }
     catch (e) {
-        hostLog('debug', `planReviewWire: outcome enqueue failed: ${String(e)}`);
+        hostLog('debug', `planReviewWire: outcome enqueue threw: ${String(e)}`);
     }
 }

package/dist/hitl/toolApprovalWire.d.ts

@@ -1,3 +1,66 @@
+/**
+ * ⇄ B7 批搬迁(2026-07-27,设计稿 §3 B7):cli `src/sema/liveToolApprovalWire.ts`(508 行)——
+ *    **拆**(设计稿原文:「liveToolApprovalWire.ts | 509 | …… | **拆分**,B7;工具 schema 属
+ *    agent-types 域」)。
+ *
+ * ── 拆缝在哪 ────────────────────────────────────────────────────────────────────────────────
+ * **进包(本文件)**:gate 判定(`isFsApprovalGate` / `toolNameIsFsWrite`)· 结构等值
+ *   (`structurallyEqual`,ctrl+g amend 的「真编辑过」判据)· 同步帧契约与判别式
+ *   (`ToolApprovalFrame` / `isToolApprovalFrame` / `isFromSubagent`)· 徽章合成
+ *   (`subagentBadgeFor`)· gate 文案兜 path(`pathFromGateMessage`)· **两条决断腿的编排**
+ *   (`surfaceFsApprovalAndDecide` durable-park 腿 / `surfaceToolApprovalFrameAndRespond` 同步帧腿)。
+ * **留宿主**:**卡本身**(`surfaceApprovalCard`)—— 它要 leader `ToolUseConfirm` 队列、壳的
+ *   vendored `Tool` 注册表(`FileWriteTool`/`FileEditTool`/`NotebookEditTool`/`EngineWorkflowTool`)、
+ *   `applyPermissionUpdates` 与 `AppState.toolPermissionContext`。那是**端的渲染与权限态**,
+ *   web/桌面各有各的形(浏览器根本没有 Ink 三选卡)。落点 = 下面的 `ApprovalCardPort`。
+ *
+ * 🔴 **拆缝的失效形**([paired-mechanisms-must-share-premise]):卡口没装 ⇒ 两条腿都拿不到人的
+ *   决断。**这不是「静默不启用」可以接受的面** —— 同步帧腿上引擎正同步阻塞着,不 respond 就干等
+ *   TTL;durable 腿上 run 卡在 suspended。所以本口:
+ *     · **计 miss**(`approvalCardPortMisses()`,宿主自检恒应为 0);
+ *     · 缺席时返回 `{kind:'failed', reason:'no approval card port installed …'}` —— 与壳原文
+ *       「no leader ToolUseConfirm queue registered(print/non-REPL mode)」**同一条 fail-soft 语义**
+ *       (print/headless 本来就没有卡面),调用方照旧走 fail-closed deny / 诚实红。
+ *
+ * 🔴 搬迁差分(逐条,零行为变化):
+ *   1. `toolForName`(4 个 `require('../tools/…')`)整条留宿主 —— 工具注册表是壳资产。
+ *   2. `getLeaderToolUseConfirmQueue` / `getLeaderSetToolPermissionContext` / `applyPermissionUpdates` /
+ *      `getAppStateStoreRef` / `syntheticAssistantMessage` / `stubToolUseContext` 全部随卡留宿主。
+ *   3. `logForDebugging` → `hostLog('debug'|'error', …)`(本包零 `utils/debug`,portability 门盯着)。
+ *   4. `require('./fleetClient.js').readEngineActiveBgTasks()` → 静态 import 包内
+ *      `fleet/fleetLedger.js` 的同名读口(B6 已搬入;延迟 require 的理由「纯 wire 模块不背 fleet 图
+ *      冷启动」在包内不成立 —— 同一个包)。⚠️ try/catch 保留:台账不可用时兜 taskId 短形那一支
+ *      仍要成立。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * liveToolApprovalWire — 权限三选卡的壳侧半场([816] 壳侧承诺① / [819]② / [820] 四模式表,2026-07-14)。
+ *
+ * WIRE(server 1.191 已到货,[830]①):引擎对 fs 写工具(Write/Edit/NotebookEdit)出 ask ——
+ * 真腿=同步 `tool_approval` 帧(named SSE,redactDeep+16KiB 帽)→ 三选卡 → POST
+ * /v1/tool-approvals/:id/respond {allow|allow_session|deny}(本文件下半)。durable park 腿
+ * (checkpointGate → approvals.decide)🔴 **现势(REF-CC-023/031,2026-08-02)**:不是「旧引擎兜底」——
+ * [2150] S1 半场(83-87 行)证实产品默认 durable 投递下,引擎对 Bash 出的 durable park 就是**活路径**
+ * (r1 E5 fail-stuck 实例);synthApprovalProbe 合成单测仍在,但这条腿今天会被真用户真流量走到。
+ * 本模块把 gate 面翻成壳的 VENDORED CC 权限对话框(PermissionRequest → FileWritePermissionRequest,
+ * 三选文案逐字 CC 207:`Yes` / `Yes, allow all edits during this session (shift+tab)`[cwd 外变体带
+ * dirname] / `No`,题干 `Do you want to create <basename>?` verb=create/overwrite/write to)——零新 UI,
+ * 键行为(1/2/3、shift+tab 聚焦第 2 项、esc=reject)全部继承 vendor 组件。
+ *
+ * 决断腿:
+ *  - Yes(accept-once)→ HitlBridge.decideTool({decision:'approve'})(D-1 绑定 verbatim,合 [819]②)。
+ *  - Yes-allow-all(accept-session)→ 同 approve,且 permissionUpdates 里 vendor 产出的
+ *    `{type:'setMode', mode:'acceptEdits', destination:'session'}` 经 leader setter 落壳 AppState →
+ *    seamQuery 的 permissionModeField 下一 turn 起 stamp `permissionMode:"acceptEdits"`([816] 壳侧
+ *    承诺②:accept-session=升 intent,wire 已通)。cwd 外变体还带 addDirectories(session)——照 CC 收。
+ *  - No(reject)→ decideTool({decision:'deny'});调用方(liveHitlAskWire)对该 call 的重放 tool_end
+ *    stamp REJECT_MESSAGE,vendor 的 renderToolUseRejectedMessage 渲 `User rejected <op> to <path>`
+ *    (subtle 色,CC 逐字)。
+ *
+ * 🔴 fail-soft 铁律(与 ask 桥同款):leader 队列未注册(print/非 REPL)、pending 蒸发、decide 409/404
+ *   都返回 failed —— 调用方回退「flush + 原样终帧」的诚实红,绝不更糟。
+ * 🔴 UNTRUSTED:gate args 为模型作文(service 已 redact),只渲染绝不回喂;决断只带 decision 枚举。
+ */
 import { type HitlClientLike } from './hitlBridge.js';
 /** fs 写权限 gate 判定:未来的一等 kind(tool_approval)或按 toolName(server 桥首批=fs 写三件,
  *  [820] 表)。AskUserQuestion 永不进这里(ask 桥先判)。 */
@@ -19,14 +82,14 @@ export declare function isToolApprovalGate(gate: {
 } | undefined | null): boolean;
 export type FsApprovalOutcome = {
     kind: 'decided';
-    gatedCallId?: string;
-    denied?: boolean;
+    gatedCallId?: string | undefined;
+    denied?: boolean | undefined;
 } | {
     kind: 'aborted';
-    gatedCallId?: string;
+    gatedCallId?: string | undefined;
 } | {
     kind: 'failed';
-    gatedCallId?: string;
+    gatedCallId?: string | undefined;
     reason: string;
 };
 /** 本桥消费的 wire 面(liveHitlAskWire 的 AskGateWireDeps 同形切片,mock 可注入)。 */