@sema-agent/client-core 0.13.0 → 0.15.0

package/dist/hitl/frameRouter.js

@@ -26,11 +26,17 @@ export function isAskTool(toolName) {
     return isAskToolLoose(toolName);
 }
 /**
- * 「这个工具名归 gate 管」的**统一**判据(#110 修,2026-08-02)。
+ * 「这个**工具名**归 gate 管」的判据(#110 修,2026-08-02)。
  *
- * 🔴 它必须与 park 判定(`isAskTool` / `isToolApprovalGate`)覆盖**同一个集合** ——
- * 两边不同集就是 [paired-mechanisms-must-share-premise] 那种「park 认得出、HOLD 认不出」的
- * 半场病:[2150] S1 给 park 判定加了 `toolNameIsShellExec`(Bash/shell 类进 gate 了),但
+ * ⚠️ 它只是 park 判定的**名字腿**对位件,不是全部 —— park 判定 `isToolApprovalGate` 还有一条
+ * 一等 kind 腿(`gate.kind==='tool_approval'`,放行任意 toolName),名字面上没有对位物。
+ * tool_end 手柄用的是下面的 `isGatedToolEnd`(名字腿 ∪ abort 标记腿),两者的集合关系与理由
+ * 写在那个函数的头注里([2393] hitl-F1)。本函数还被 `routeToolStart` 用来决定「要不要记 args /
+ * 要不要跟 `lastFsOrShellGatedCallId`」,那两件事本来就只对名字识别得出的族成立。
+ *
+ * 🔴 它必须与 park 判定的**名字腿**(`isAskTool` / `toolNameIsFsWrite` / `toolNameIsShellExec`)
+ * 覆盖同一个集合 —— 两边不同集就是 [paired-mechanisms-must-share-premise] 那种「park 认得出、
+ * HOLD 认不出」的半场病:[2150] S1 给 park 判定加了 `toolNameIsShellExec`(Bash/shell 类进 gate 了),但
  * tool_end 手柄的 HOLD/REJECT 谓词还停在 `isAskTool || toolNameIsFsWrite` ——
  * 于是 Bash 的 durable gate 走到这里就两件事同时出错:
  *   ① park 期的毒化帧(`tool_end{isError:true, output:"Operation aborted"}`)没被 HOLD,
@@ -47,6 +53,36 @@ function isGatedToolName(name) {
         return false;
     return toolNameIsFsWrite(name) || toolNameIsShellExec(name);
 }
+/**
+ * 「这一帧 tool_end 归 gate 管」的判据 —— 上面那条**名字腿**加一条 kind 腿的替身([2393] hitl-F1,
+ * 2026-08-02)。
+ *
+ * 🔴 为什么名字腿一条不够(上面那句「必须覆盖同一个集合」在 kind 腿上的反例):park 判定
+ * `isToolApprovalGate` 有**两条**腿 —— 名字族(ask / fs 写三件 / Bash)与**一等 kind**
+ * (`gate.kind === 'tool_approval'`,`toolApprovalWire.isFsApprovalGate` 首行)。后者放行**任意**
+ * toolName:server 对名单外的工具出一等 kind 审批 park 时,park 侧认、tool_end 侧的名字腿认不出,
+ * 于是 #110 那三件事在这类 gate 上原样重演一遍(毒化帧上屏 / `markEnded` 吃掉重放的真结果 /
+ * deny 的 CC 文案进不去)。
+ *
+ * 🔴 为什么不能在名字腿里补 kind:`tool_end` 帧上**根本没有 kind 位** —— gate 的 kind 只在
+ * `done{suspended}.checkpointGate` / `suspended.gate` 上,而那两帧**晚于**毒化 tool_end 到达
+ * (park 帧序:tool_start → tool_end(毒化)→ done{suspended})。「park 时按 callId 打标、
+ * tool_end 时读台账」这条路对**这一帧**来得太晚。帧面上唯一可读的信号是引擎铸的**确切 abort
+ * 标记** `ENGINE_ABORT_TOOL_RESULT`(见下方 ④ 臂头注:core 对被 gate/连坐 abort 的 call 恒铸
+ * 这一串),所以本判据 = 名字腿 ∪ abort 标记腿。
+ *
+ * 🔴 集合关系(说清楚,别让下一棒再以为两边逐字相等):本判据是 park 判定的**超集**(它还会盖到
+ * 被同 turn 连坐 abort 的非 gate call)。方向是有意的,且不对称成立 —— 多盖一帧的代价是那一帧
+ * **晚**上屏(HOLD 的帧在模型推进 / 终帧 / fail-soft 三处必被 flush,一帧都不会丢),而少盖一帧
+ * 的代价是用户按了 Yes 却只看到 `Error: Operation aborted`。顺带把连坐 abort 的 call 从
+ * `markEnded` 里救出来:它们本来也会在 resume 后被模型重发,而旧码已把它们记成已收口。
+ * ⚠️ 普通工具错(非 abort 标记)照旧**不进** HOLD —— [2084]①-b 的收窄没有被放宽,负控 F1-c 钉着。
+ */
+function isGatedToolEnd(ev) {
+    if (isGatedToolName(ev.toolName))
+        return true;
+    return ev.output === ENGINE_ABORT_TOOL_RESULT;
+}
 /** done 帧的 AskUserQuestion park 形状(结构性读;别的终态一律 false)。 */
 function isAskGatePark(result) {
     const r = result;
@@ -128,9 +164,11 @@ const TOOL_END_ARMS = [
     {
         // ② 同步帧腿 deny 且 callId 没关联上:下一张 gated 报错帧即该 gate 的收口帧,stamp REJECT 文案。
         //    #110:stamp 也要盖 shell —— 否则按 No 时用户看到的是引擎原文 `Operation aborted`。
+        //    [2393] hitl-F1:改用 `isGatedToolEnd`(名字腿 ∪ abort 标记腿)—— 一等 kind gate 的
+        //    收口帧名字腿认不出,不盖它 = 用户按了 No 却看到引擎原文。
         id: 'deny-stamp-next',
         run(ev, callId, led) {
-            if (ev.isError !== true || !isGatedToolName(ev.toolName) || led.isDenied(callId))
+            if (ev.isError !== true || !isGatedToolEnd(ev) || led.isDenied(callId))
                 return undefined;
             if (!led.takeDenyStamp())
                 return undefined;
@@ -143,7 +181,7 @@ const TOOL_END_ARMS = [
         // ③ 三选卡 No:重放的报错帧 stamp REJECT 文案 → vendored 卡渲 `User rejected <op> to <path>`。
         id: 'denied-call',
         run(ev, callId, led) {
-            if (ev.isError !== true || !isGatedToolName(ev.toolName))
+            if (ev.isError !== true || !isGatedToolEnd(ev))
                 return undefined;
             if (!led.takeDenied(callId))
                 return undefined;
@@ -160,7 +198,7 @@ const TOOL_END_ARMS = [
         //    —— 收窄后它们零滞后直达转录(落到 ⑤ 通用收口),不再依赖「推进信号放行」。
         id: 'hold-poison',
         run(ev, callId, led) {
-            if (ev.isError !== true || !isGatedToolName(ev.toolName))
+            if (ev.isError !== true || !isGatedToolEnd(ev))
                 return undefined;
             if (ev.output !== ENGINE_ABORT_TOOL_RESULT)
                 return undefined;
@@ -288,7 +326,10 @@ function routeSuspended(ev, ctx) {
         ctx.taskId.current) {
         return { kind: 'park', gate: 'fs' };
     }
-    return { kind: 'yield', events: [ev] }; // 其余 gate:透传(现状,eventToSdkMessage 出 null)
+    // 其余 gate:透传。⚠️ ADAPTER-F8 注纠(2026-08-02):原文写「eventToSdkMessage 出 null」——
+    // 那个返回形已随 REF-CC-058 退役,今天它出的是 `EventProjection` 三态,永不是 null;本臂的
+    // 帧走到投影器时落 `none/hitl_out_of_slice`(HITL 登记是 run driver 的活,不在投影切片内)。
+    return { kind: 'yield', events: [ev] };
 }
 function routeDone(ev, ctx) {
     const { led } = ctx;

package/dist/hitl/gateLedger.d.ts

@@ -99,7 +99,19 @@ export interface GateLedger {
      * 「已解决」最多多读一轮、被 hop 预算兜底;误判成「真失败」烧会话)。
      */
     markDecided(callId: string): void;
-    isDecided(callId: string): boolean;
+    /**
+     * 一次性消费([2393] hitl-F2,2026-08-02):记号被一次 park 失败消费掉就**失效**。
+     *
+     * 🔴 为什么必须一次性:这条判据的正当性完全来自「durable re-attach 会把**那一次**已决断的 park
+     * 重放一遍」——重放窗口只有一次。而它的两个输入都是单调的:`lastFsOrShellGatedCallId()` 不随
+     * tool_end 清空(见上方声明处注,那是**故意**的,park 重放时没有新的 tool_start 可跟),
+     * `decidedGates` 又只增不删 ⇒ 只要这个 turn 里成功决断过一次,**之后每一次** park 失败都会命中
+     * 身份匹配,不论真因是什么。实测后果:`approvals.list` 网络失败这类真失败被连续 24 次判成
+     * 「已解决」,吃满 `MAX_GATE_HOPS` 才吐一句 `gate hop limit exceeded` —— 用户白等 24 轮往返,
+     * 拿到的还是一句与真因无关的话(真因被预算话术顶掉了)。
+     * 消费一次即失效之后:第一次(= 真的重放)照旧救回,第二次就是诚实的 fail-soft。
+     */
+    takeDecided(callId: string): boolean;
     /** 只给 debug 串用的规模位(`[decided so far: N]`)。 */
     decidedCount(): number;
 }

package/dist/hitl/gateLedger.js

@@ -103,8 +103,8 @@ export function createGateLedger() {
         markDecided(callId) {
             decidedGates.add(callId);
         },
-        isDecided(callId) {
-            return decidedGates.has(callId);
+        takeDecided(callId) {
+            return decidedGates.delete(callId);
         },
         decidedCount() {
             return decidedGates.size;

package/dist/hitl/parkResolver.js

@@ -200,7 +200,16 @@ export async function resolvePark(park, ctx) {
     // `FsApprovalOutcome` 今天没有 `code`(toolApprovalWire.ts,C-bridge 域),失败原因若不是
     // 那三个文案子串(例如 `approvals.list` 自身网络失败)就会漏判。已决断身份匹配是独立于
     // 文案的第二判据 —— 两臂任一命中都按「已解决」处置,方向偏宽(见台账 `markDecided` 处注)。
-    const alreadyDecidedById = candidateGatedCallId !== undefined && led.isDecided(candidateGatedCallId);
+    //
+    // [2393] hitl-F2(2026-08-02):这条身份判据**一次性消费**(`takeDecided` 而不是 `isDecided`)。
+    // 它的正当性只覆盖「durable re-attach 把**那一次**已决断的 park 重放一遍」这一个窗口,而它的两个
+    // 输入都是单调的(`lastFsOrShellGatedCallId()` 故意不随 tool_end 清空 + `decidedGates` 只增),
+    // 不消费就等于:本 turn 只要成功决断过一次,之后**每一次** park 失败都被判「已解决」——
+    // `approvals.list` 网络失败这类真失败会连吃 24 个 hop,最后吐一句与真因无关的 `gate hop limit`。
+    // 消费点写在 `outcome.kind === 'failed'` 之内:决断成功的那一轮压根不该动这个记号。
+    const alreadyDecidedById = outcome.kind === 'failed' &&
+        candidateGatedCallId !== undefined &&
+        led.takeDecided(candidateGatedCallId);
     if (outcome.kind === 'failed' && (isAlreadyResolvedFailure(outcome) || alreadyDecidedById)) {
         const seq = led.lastSeq();
         hostLog('debug', `liveHitlAskWire: gate already resolved (${outcome.reason}) — replayed park, re-attaching runs.events(${taskId})${seq ? ` from seq ${seq}` : ''} instead of failing the turn` +

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';
@@ -92,6 +92,28 @@ const armedPlanReviewTaskIds = new Set();
 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, INCLUDING the idempotent "already armed" short-circuit — see
@@ -107,13 +129,33 @@ export function armPlanReviewApproval(result) {
             return false;
         const { taskId } = result;
         if (armedPlanReviewTaskIds.has(taskId)) {
-            // REF-CC-027:同一张卡还没消解就被重放的 arm 撞上——幂等,不二次弹卡/二次注册。
-            hostLog('debug', `planReviewWire: arm skipped — task ${taskId} is already armed (durable replay, idempotent)`);
-            return true;
+            // 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 = `plan-review:${taskId}`;
+        const questionId = planReviewQuestionId(taskId);
         const unregister = registerLocalQuestionResponder(questionId, async (_id, answer) => {
             // REF-CC-027:一次性 —— 首句就注销 + 清武装态(照 askGateWire 的 cleanup() 形)。
             // liveQuestionStore.respondToQuestion 自身也是一次性取件(delete-before-invoke),这里是
@@ -130,21 +172,7 @@ export function armPlanReviewApproval(result) {
             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;
     }

package/dist/hitl/toolApprovalWire.js

@@ -61,7 +61,7 @@
  *   都返回 failed —— 调用方回退「flush + 原样终帧」的诚实红,绝不更糟。
  * 🔴 UNTRUSTED:gate args 为模型作文(service 已 redact),只渲染绝不回喂;决断只带 decision 枚举。
  */
-import { HitlBridge, findPendingForTask } from './hitlBridge.js';
+import { HitlBridge, HitlSafetyError, findPendingForTask } from './hitlBridge.js';
 import { hostLog } from '../host.js';
 import { createSessionSlot, DEFAULT_SESSION_KEY } from '../sessionSlot.js';
 import { readEngineActiveBgTasks } from '../fleet/fleetLedger.js';
@@ -256,6 +256,16 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
                         return { kind: 'decided', gatedCallId };
                     }
                     catch (e) {
+                        // 🔴 [2393] hitl-F4(2026-08-02):回退臂**只**兜「老 server 不识别 remember ⇒ 400 未知键」
+                        // 这一形。`HitlSafetyError` 是 hitlBridge 的**安全信号**闭集(hitlBridge.ts:9 / decideTool
+                        // 头注末句逐字:「A binding mismatch (409) is re-raised as a `HitlSafetyError`
+                        // ('binding_mismatch') — the caller re-presents, NEVER auto-retries」),旧的 catch-all
+                        // 把它一并吞了,然后**立刻自动重发**一次纯 approve —— 正是那条铁律禁的动作:
+                        // binding 不匹配意味着「人看见的那一行在他决断期间被换掉了」,自动重试等于替人对一件
+                        // 他没看过的事按了 Yes。`no_pending` 同族(那一行已经没了,重试同样只会再失败一次)。
+                        // 上抛给外层 catch ⇒ typed `failed` ⇒ 调用方走 fail-soft 诚实红,由人重新决断。
+                        if (e instanceof HitlSafetyError)
+                            throw e;
                         hostLog('debug', `liveToolApprovalWire: decide(approve+remember) failed (${String(e)}) — falling back to plain approve`);
                     }
                 }

package/dist/hooksWireCaps.js

@@ -98,14 +98,22 @@ export function hooksForWire() {
         return undefined;
     // trust gate first (cheapest + broadest): untrusted interactive workspace ⇒ no hooks anywhere,
     // the engine leg included — same invariant the local executor enforces per-fire.
+    // [2393] F-2(fix-outright):此前这条 catch 是 **fail-OPEN**(fall through),理由句写「端侧本地
+    // 执行器仍 per-fire 把门」—— 那句在本包语境下是**假话**,本文件头第三段自己写明:壳里那条
+    // catch 的前提是单进程本地执行器,**库里没有那个兜底**。后果是「未受信工作区的 hooks 绝不上
+    // wire」这条被文件头称作安全门的不变量,在 SettingsPort 抛错时整个失效(用户/项目 settings 里的
+    // `command` 型 hook 照投给引擎真执行)。而同一函数下方对**同类失败**(port 抛)的 policy 读已选
+    // fail-closed 并写明「治理策略读不出来时更安全的默认应是当作有限制」—— 两道门相邻、同类输入,
+    // 结论必须一致,更敏感的那道不许留在宽的一侧。改成 fail-closed:信任查不出来 = 当作未受信。
     try {
         if (settings.shouldSkipHookDueToTrust()) {
             hostLog('debug', 'hooksWireCaps: workspace not trusted — no hooks projected to the engine');
             return undefined;
         }
     }
-    catch {
-        /* trust check threw (early boot) — fall through; 端侧本地执行器仍 per-fire 把门 */
+    catch (err) {
+        hostLog('debug', `hooksWireCaps: workspace trust check threw — fail-closed (no hooks projected to the engine): ${String(err)}`);
+        return undefined;
     }
     let policy = null;
     // REF-CC-155(midband-03,fix-outright,行为面已裁 GO — 安全敏感面 [2374] 背书):policy 是

package/dist/index.d.ts

@@ -223,5 +223,7 @@ export * from './seatContract.js';
 export * from './agentSession/contract.js';
 export * from './agentSession/backgroundView.js';
 export * from './model/catalog.js';
+export * from './model/catalogLoader.js';
+export * from './model/providerAuth.js';
 export * from './websearch/searchProviderPresets.js';
 export * from './env/localeGeo.js';

package/dist/index.js

@@ -324,6 +324,19 @@ export * from './agentSession/backgroundView.js';
 // 🔴 绝不半解析:schemaVersion 超区间/任一行形状坏 ⇒ 整份弃用走兜底(端渲「内置版本(离线)」
 //    靠 `source` + `online.reason`,所以「静默用兜底」在本层是可观测的)。
 export * from './model/catalog.js';
+// ── design/166(2026-08-04):目录客户端消费链 —— 候选链 loader + 供应商凭证双轨 seam ──────────
+// 🔴 `model/catalogLoader.ts` 是 catalog.ts 的**宿主面**,不是第二个解析器:候选链遍历 +
+//    传输硬门(https + 域白名单,**重定向目标过同一道门**)+ `catalog.sha256` 旁签 + 缓存信封,
+//    载荷判决(schemaVersion/逐行形状/整份弃)全部委托 `resolveModelCatalog`,一行不重写。
+// 🔴 缓存**落盘**走注入口 `CatalogCachePort`(本包 index 闭包零 Node 内建是机械门守着的硬法;
+//    tmp+rename 的原子性是实现方的契约,参考实现在 catalogLoader.ts 的类型注释里)。
+export * from './model/catalogLoader.js';
+// 🔴 `model/providerAuth.ts` 与 registry SSO(cloudAuth)**物理分文件、零共享代码**
+//    ([reuse-single-sso-no-parallel-auth]:它是模型供应商凭证轨,不是 sema 登录轨)。
+//    `DEVICE_AUTH_PROVIDERS` 今天是**空表**(宁空勿假:没有我们自己名下的 client_id 之前,
+//    填别的编辑器插件的 app id = 冒用,与 §6 判 C 档出局同一条判据),因此
+//    `supportsDeviceCodeAuth` 对每一家如实返回 false、UI 不显示该选项 —— 注册一家 = 加一行。
+export * from './model/providerAuth.js';
 // ── 搜索 provider 目录 + 地域预选(2026-07-31)──────────────────────────────────────────────────
 // `websearch/searchProviderPresets` = model 目录的**同形不同表**姊妹件:数据在 json、类型与查询
 // 在 ts。它编译出来的不是模型目录而是**引擎部署 env**(`WEB_SEARCH_*`)。

package/dist/liveQuestionStore.d.ts

@@ -68,6 +68,19 @@ type RespondFn = (id: string, answer: QuestionAnswer, opts?: {
 /** Register a one-shot local responder for a SYNTHETIC question frame (e.g. `plan-review:<taskId>`).
  *  Returns an unregister fn (dialog dismissed without answering ⇒ caller cleans up). */
 export declare function registerLocalQuestionResponder(id: string, fn: RespondFn): () => void;
+/**
+ * Is a local responder for this synthetic questionId still bound?([2393] hitl-F3,2026-08-02)
+ *
+ * 🔴 为什么这是**只读探询**而不是「谁注册谁自己记着就行」:上面那条契约把「对话框被 dismiss 却没
+ * 作答」的清理责任交给了 caller,而 caller(planReviewWire)自己那份武装态与这张表是**两个**容器 ——
+ * 两个容器各自都可能被单方面改动(`respondToQuestion` 的一次性 delete、别的注册把同 id 顶掉后再
+ * 注销),于是「我以为还武装着」和「表里还真有人收答」会漂开。漂开的后果不是多弹一张卡,是
+ * **一张都不弹**:去重短路认为卡还在,而实际上没有任何 responder 能收答([paired-mechanisms-must-
+ * share-premise])。给出这条探询口,让去重臂能问真相而不是问自己的记忆。
+ *
+ * 🔴 只回答布尔:responder 函数本身绝不出境(它闭包着 caller 的一次性状态,交出去就有第二个调用者)。
+ */
+export declare function hasLocalQuestionResponder(id: string): boolean;
 /**
  * Publish a demuxed live question frame (called from liveClient's demuxQuestionFrames on each
  * `question`/`question_complete`). Best-effort: a UI handler error is swallowed so a broken overlay can NEVER

package/dist/liveQuestionStore.js

@@ -20,6 +20,21 @@ export function registerLocalQuestionResponder(id, fn) {
         localResponders.delete(id);
     };
 }
+/**
+ * Is a local responder for this synthetic questionId still bound?([2393] hitl-F3,2026-08-02)
+ *
+ * 🔴 为什么这是**只读探询**而不是「谁注册谁自己记着就行」:上面那条契约把「对话框被 dismiss 却没
+ * 作答」的清理责任交给了 caller,而 caller(planReviewWire)自己那份武装态与这张表是**两个**容器 ——
+ * 两个容器各自都可能被单方面改动(`respondToQuestion` 的一次性 delete、别的注册把同 id 顶掉后再
+ * 注销),于是「我以为还武装着」和「表里还真有人收答」会漂开。漂开的后果不是多弹一张卡,是
+ * **一张都不弹**:去重短路认为卡还在,而实际上没有任何 responder 能收答([paired-mechanisms-must-
+ * share-premise])。给出这条探询口,让去重臂能问真相而不是问自己的记忆。
+ *
+ * 🔴 只回答布尔:responder 函数本身绝不出境(它闭包着 caller 的一次性状态,交出去就有第二个调用者)。
+ */
+export function hasLocalQuestionResponder(id) {
+    return localResponders.has(id);
+}
 /**
  * Publish a demuxed live question frame (called from liveClient's demuxQuestionFrames on each
  * `question`/`question_complete`). Best-effort: a UI handler error is swallowed so a broken overlay can NEVER

package/dist/model/catalogLoader.d.ts

@@ -0,0 +1,170 @@
+/**
+ * catalogLoader.ts — **目录候选链的宿主 loader**(design/166 §1-§3,2026-08-04)。
+ *
+ * ## 它与 `catalog.ts` 的分工(🔴 委托,不平行重做)
+ *
+ * `catalog.ts` 已经是三层源解析器:`resolveModelCatalog`(线上→包内→用户覆盖三层合并)+
+ * `validateOnlineCatalog`(schemaVersion 区间 / 逐行 `isProviderRow` / **绝不半解析** / 不回显载荷)
+ * + `CatalogFetchJson` 注入端口 + `CatalogSource`·`CatalogRejectReason` 两张词表。
+ * 本文件**只补 catalog.ts 声明不管的宿主面**,四件事:
+ *
+ *   ① **候选链遍历**(`DEFAULT_CATALOG_SOURCES` = raw.githubusercontent → jsDelivr,可配);
+ *   ② **传输安全硬门**:https + 域白名单(拨号**之前**判,域外源连请求都不发)——
+ *      而且**重定向目标过同一道门**(fetch 默认跟随重定向,不设门 = 白名单可被 302 绕过);
+ *   ③ **`catalog.sha256` 旁签**(同源同路径,SHA-256 hex 比对);
+ *   ④ **缓存**(`configHome/cache/model-catalog.json`)的信封与读回语义。
+ *
+ * 载荷面的判决(schemaVersion / 逐行形状 / 整份弃 / 不回显)**一行都不在这里重写** ——
+ * 本文件拿到字节流之后做的唯一一件事是 `JSON.parse`,然后把结果交给 `resolveModelCatalog`,
+ * 由它去 `validateOnlineCatalog`。UI 渲染也只认 `ModelCatalogResult.source` + `online.reason`
+ * (+ 本文件加的 `cacheHit`),**不发明第二套 origin 词表**。
+ *
+ * ## 🔴 为什么缓存的**落盘动作**在宿主而不在这里(与设计档 §3 的偏差,记在这)
+ *
+ * 设计档 §3 写的是「loader 原子写(tmp+rename)」。但本包有一条机械门守着的硬法:
+ * `src/**` 的 index 值级闭包**零 Node 内建**(`scripts/run-client-core-portability-test.mjs`
+ * ①c 段),因为同一份代码要在浏览器/桌面渲染进程里跑。`node:fs` 一进来,那道门当场红。
+ * ⇒ 落盘走**注入口** `CatalogCachePort`(与 `host.ts` 的 `FsPort`、`catalog.ts` 的
+ * `CatalogFetchJson` 同一条纪律:能力由宿主注入,库不自己 `require('fs')`)。
+ * **tmp+rename 的原子性是 `writeAtomic` 实现方的契约**,本文件在类型注释里把它写成要求;
+ * Node 宿主的十行参考实现见 `CatalogCachePort.writeAtomic` 的注释。
+ * 缺席该口 ⇒ 缓存腿整条不启用(`cacheHit` 键**缺席**,不是 `false` —— 「没查过」和「查过没用上」
+ * 是两件事,[honest-absence-not-fabricated-zero])。
+ *
+ * ## 🔴 `forceRefresh` 为什么没有(与设计档 §1 签名的偏差)
+ *
+ * 本 loader **恒先走网络**,缓存只在候选链**全败**时顶上(设计档 §3 自己就是这么定的读时机)。
+ * 也就是说没有任何一条「优先吃缓存」的路径可供 `forceRefresh` 去绕过 —— 收下这个参数只会
+ * 得到一个恒为空操作的旋钮,而空操作的旋钮是**假 affordance**(调用方以为自己强制刷新了)。
+ * 真要「手动刷新」,直接再调一次本函数就是最新语义。
+ *
+ * ## 时钟
+ *
+ * 与 `catalog.ts` 同一口径:**绝不偷读时钟**。`nowMs` 缺席 ⇒ 缓存信封不写 `fetchedAt`、
+ * 陈旧判定不做(`cacheStale` 键缺席),而不是 `Date.now()` 兜底。
+ */
+import { type EnvLike } from '../hostEnv.js';
+import { type ModelCatalogResult, type OnlineCatalogDoc } from './catalog.js';
+import type { ProviderPreset } from './providerPresets.js';
+/**
+ * 默认候选链(design/166 §1;clay 裁「可配置,默认 github」)。
+ * 第二跳 jsDelivr 对 gh 仓是被动 CDN、零接入成本 —— 这就是大陆可达性的零维护替身。
+ * 🔴 顺序即优先级:逐源尝试,前一跳成了就不拨下一跳。
+ */
+export declare const DEFAULT_CATALOG_SOURCES: readonly string[];
+/** 默认域白名单 = 默认链两跳的 host。用户显式配置的源 host 在运行期并入(用户自担)。 */
+export declare const CATALOG_DEFAULT_HOSTS: readonly string[];
+/** 候选链的 env 键(一键安装脚本改这里;settings.json `env` 块同名同义,见 design/166 §2)。 */
+export declare const CATALOG_SOURCES_ENV = "SEMA_CATALOG_SOURCES";
+/** 每源传输预算(design/166 §1:onboard 不能被网络拖住)。 */
+export declare const DEFAULT_CATALOG_TIMEOUT_MS = 3500;
+/** 缓存相对 configHome 的落点(design/166 §3)。 */
+export declare const CATALOG_CACHE_RELATIVE_PATH = "cache/model-catalog.json";
+/** 缓存陈旧阈值:30 天(照用,但如实标 stale)。 */
+export declare const CATALOG_CACHE_STALE_MS: number;
+/**
+ * 单源的**传输层**结局。
+ *
+ * 🔴 它**不是**第二套 origin 词表:UI 渲染「目录从哪来」恒读 `ModelCatalogResult.source` +
+ * `online.reason` + `cacheHit`。本词表只服务于 **doctor 的逐源分诊**(「两跳分别为什么没成」),
+ * 那是 `catalog.ts` 的单 URL 视角在结构上说不出来的量 —— 它只有一个 `online` 结局位。
+ */
+export type CatalogSourceOutcome = 'ok' | 'insecure-url' | 'host-not-allowed' | 'redirect-blocked' | 'redirect-opaque' | 'redirect-loop' | 'http-error' | 'network-error' | 'invalid-json' | 'sha-mismatch';
+/** 一次逐源尝试的留痕(doctor 用;🔴 绝不带载荷内容,只带判决与被截断的 message)。 */
+export interface CatalogSourceAttempt {
+    url: string;
+    outcome: CatalogSourceOutcome;
+    /** HTTP 状态码(只在真收到响应时在场)。 */
+    status?: number;
+    /** 旁签是否**真的比对过**(只在 `outcome:'ok'` 时在场;false = sha 拿不到,已记 warn 放行)。 */
+    shaChecked?: boolean;
+    /** 人话细节(判决相关短语 / 被截断的错误 message)。 */
+    detail?: string;
+}
+/** 缓存文件的信封(design/166 §3)。`fetchedAt` 缺席 = 写入时宿主没给时钟。 */
+export interface CatalogCacheEnvelope {
+    fetchedAt?: number;
+    sourceUrl: string;
+    catalog: OnlineCatalogDoc;
+}
+/**
+ * 缓存口 —— 宿主注入(本包零 `node:fs`,理由见文件头)。
+ *
+ * `writeAtomic` 的契约是**原子替换**(临时文件 + rename),不是 `writeFile` 的别名:
+ * 半截文件会让下一次冷启动读到一份坏缓存。Node 宿主的参考实现:
+ * ```js
+ * async writeAtomic(path, text) {
+ *   await mkdir(dirname(path), { recursive: true })
+ *   const tmp = `${path}.${process.pid}.tmp`
+ *   await writeFile(tmp, text, 'utf8')
+ *   await rename(tmp, path)     // 同目录 rename = 原子
+ * }
+ * ```
+ * 两个动词都允许同步或异步实现;抛异常由 loader 收成 warning(缓存是纵深,不是主路径)。
+ */
+export interface CatalogCachePort {
+    read(path: string): string | null | Promise<string | null>;
+    writeAtomic(path: string, text: string): void | Promise<void>;
+}
+/** `loadCatalogWithSources` 的入参。 */
+export interface LoadCatalogOptions {
+    /** 缓存落点的根(`configHome/cache/model-catalog.json`)。缺席 ⇒ 缓存腿不启用。 */
+    configHome?: string;
+    /** 覆盖候选链(缺省 `DEFAULT_CATALOG_SOURCES`;env 恒赢本项,见 `resolveCatalogSources`)。 */
+    sources?: readonly string[];
+    /** 宿主 env(缺省 `hostEnv()`)。 */
+    env?: EnvLike;
+    /** 每源传输预算(缺省 `DEFAULT_CATALOG_TIMEOUT_MS`)。 */
+    timeoutMs?: number;
+    /** 宿主时钟。缺席 ⇒ 不算 ageMs、不写 fetchedAt、不判 stale(绝不偷读时钟)。 */
+    nowMs?: number;
+    /** 传输注入口(缺省全局 `fetch`;本包既有姿势 = limitsWire/detachWire 的 `fetchImpl`)。 */
+    fetchImpl?: typeof fetch;
+    /** 缓存口。缺席 ⇒ 缓存腿整条不启用(`cacheHit` 键缺席)。 */
+    cache?: CatalogCachePort;
+    /** 用户本地覆盖层,原样透传给 `resolveModelCatalog`。 */
+    overrides?: readonly ProviderPreset[];
+}
+/**
+ * 结果 = `ModelCatalogResult`(来源标注/新鲜度/合并表全归 catalog.ts)+ 宿主面四位。
+ * 🔴 只**加**位不改位:端渲染仍读 `source` / `online.reason`。
+ */
+export interface LoadedModelCatalog extends ModelCatalogResult {
+    /** 真正被吃下的那一跳(线上成功或缓存自述的来源);全败 ⇒ 缺席。 */
+    sourceUrl?: string;
+    /** 这份线上载荷是不是从缓存顶上来的。**缓存口缺席 ⇒ 本键缺席**(没查过 ≠ 查过没用上)。 */
+    cacheHit?: boolean;
+    /** 缓存是否已过 30 天(照用但如实标)。只在 `cacheHit:true` 且宿主给了时钟时在场。 */
+    cacheStale?: boolean;
+    /** 逐源留痕(doctor 分诊用)。 */
+    attempts: CatalogSourceAttempt[];
+    /** 非致命的诚实记账(sha 拿不到 / 缓存读写失败 / 缓存半截)。 */
+    warnings: string[];
+}
+/** `SEMA_CATALOG_SOURCES` 的逗号列表解析(去空白、丢空项;缺席 ⇒ 空列表)。 */
+export declare function parseCatalogSources(raw: string | undefined | null): string[];
+/** `resolveCatalogSources` 的入参。 */
+export interface ResolveCatalogSourcesOptions {
+    env?: EnvLike;
+    sources?: readonly string[];
+}
+/**
+ * 候选链优先级(design/166 §2,高→低):env `SEMA_CATALOG_SOURCES` > 调用方(settings)> 默认链。
+ * 🔴 「配了但解析出空列表」按**没配**处理:空链会把目录腿整条静默关掉,而调用方以为自己配了。
+ */
+export declare function resolveCatalogSources(opts?: ResolveCatalogSourcesOptions): string[];
+/**
+ * 传输面硬门:**https + host 在白名单内**。拨号之前判 —— 不合格的地址连请求都不发。
+ * 🔴 白名单是**域**的门、https 是**协议**的门,两道都要过:白名单里的 host 走 http 照样拒
+ * (明文信道下目录可被改写成钓鱼网关,而目录决定的正是出站地址)。
+ */
+export declare function isAllowedCatalogUrl(url: string, allowedHosts: ReadonlySet<string>): boolean;
+/** 旁签地址 = 同源同路径换后缀(design/165 §4:`dist/catalog.sha256`)。 */
+export declare function catalogShaUrlFor(catalogUrl: string): string;
+/** 缓存文件绝对路径(design/166 §3)。POSIX 分隔符 —— Node 侧 `path.join` 对它是幂等的。 */
+export declare function catalogCachePath(configHome: string): string;
+/**
+ * 解析出一份可用的 provider 目录 —— **候选链 + 传输硬门 + 旁签 + 缓存**,载荷判决全委托
+ * `resolveModelCatalog`。🔴 **永不 reject**:onboard 不能因为网络死。
+ */
+export declare function loadCatalogWithSources(opts?: LoadCatalogOptions): Promise<LoadedModelCatalog>;