@sema-agent/client-core 0.12.2 → 0.14.0

package/dist/hooksWireCaps.js

@@ -21,8 +21,13 @@
  *
  * 🔴 模块级状态:`wireSessionStopHookPrompt` / `wireSessionStopHookCcSemantics`(`/goal` 的会话级
  *    Stop 钩子锁存)——写口 `setWireSessionStopHook`(命令层)、读口 `hooksForWire`(每 turn 请求
- *    构造期)与 `getWireSessionStopHook`(`/goal clear` 回显)全在本文件。两份实例 = 设了目标却
- *    投不出去(而两边代码看着都对)。单实例清单新增项。
+ *    构造期)与 `getWireSessionStopHook`(`/goal clear` 回显)。两份实例 = 设了目标却投不出去
+ *    (而两边代码看着都对)。单实例清单登记项。
+ *    ⇄ REF-CC-156(midband-04,split,2026-08-02):这份状态 + 版本判档 + prompt 组装已拆到
+ *    `./goalStopHook.ts`(原文件那一半占体量 57%、是独立关注点——`/goal` 命令专属,与本文件剩下
+ *    的「通用 settings-file hooks 投影 + 治理门」不是同一件事)。本文件只在 `hooksForWire()` 尾部
+ *    调 `goalStopHookMatcher()` 合流一次;所有对外名字原样从这里 re-export,调用方 import 路径
+ *    零改动。
  *
  * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
  *
@@ -58,218 +63,29 @@
  * shell to scrub here (commands are the user's own text).
  */
 import { hostLog, hostSettings } from './host.js';
-import { hostEnv } from './hostEnv.js';
-import { engineCapString } from './engineCapsCache.js';
+// REF-CC-156(split):`/goal` 版本判档 + prompt 组装 + 模块状态搬到 goalStopHook.ts。
+// `goalStopHookMatcher`/`__resetGoalStopHookForTests` 是两文件间的私有接口(不 re-export);
+// 其余七个名字原样 re-export,外部 import 路径(index 的 `export *`)零改动。
+import { goalStopHookMatcher, __resetGoalStopHookForTests } from './goalStopHook.js';
+export { GOAL_STOP_HOOK_WIRE_ENV, CC_STOP_SEMANTICS_MIN_SERVER, ccStopSemanticsFromVersion, engineCcStopSemantics, isGoalStopHookWireArmed, setWireSessionStopHook, getWireSessionStopHook, getWireSessionStopHookCcSemantics, buildGoalStopHookPrompt, } from './goalStopHook.js';
 const EDITABLE_HOOK_SOURCES = ['userSettings', 'projectSettings', 'localSettings'];
+/**
+ * REF-CC-155(midband-03,fix-outright):此前这里是静默 `catch { return null }` —— 零 hostLog、零
+ * 注释说明「为什么这次失败可以死」。settings 读取失败(格式损坏 / 端内部错误)会被悄悄当成
+ * 「该来源没配 hooks」处理,与真实的「没配」在结果上不可分辨,排查只能靠猜。补一行 debug 记录被吞的
+ * 异常(与本文件其余分支的记账习惯一致);这一处仍按「无 hooks」降级 —— 单来源读失败不是安全门
+ * (信任门/policy 门另有专门处置,见 hooksForWire),不必 fail-closed 整条腿。
+ */
 function hooksOfSource(source) {
     try {
         const s = hostSettings()?.getSettingsForSource(source);
         return s?.hooks && typeof s.hooks === 'object' && !Array.isArray(s.hooks) ? s.hooks : null;
     }
-    catch {
+    catch (err) {
+        hostLog('debug', `hooksWireCaps: ${source} settings read threw — treated as no hooks from this source: ${String(err)}`);
         return null;
     }
 }
-// ── SESSION-SCOPED Stop hook overlay(`/goal`,任务 #75 · C-7,2026-07-26)───────────────────────
-// CC 220 的 `/goal <condition>` 会往 `sessionHooksRegistry` 注册一条会话级 Stop×prompt 钩子
-// (`t.sessionHooksRegistry.add(sessionId,"Stop","",{type:"prompt",prompt})`),那才是「干到条件满足
-// 再停」的机制半边。CC 是单进程,注册进壳内 registry 就够。
-//
-// 🔴 **sema 是双进程壳,壳侧那条钩子在 live 模式 fire 不到**(实证,不是推测):壳的 Stop 钩子只有
-// `src/query/stopHooks.ts handleStopHooks` 一个执行点,调用方是 `src/query.ts` —— 壳自己的 query
-// 循环;live 模式 turn 循环在引擎里跑,壳的 query.ts 不参与。upstreamBridge 只 fire SubagentStop 且
-// observe-only。所以引擎腿必须走 `settings.hooks` 投影,这个 overlay 就是那条腿。
-//
-// 🟢 **本 overlay 默认开**(2026-07-26 翻默认;逃生口 `SEMA_GOAL_STOP_HOOK_WIRE=0/false/no/off`)。
-//
-// 修前默认关,理由是两条**前提**——两条都已被 server 侧行为取证**证伪**(黑板 [1721],6 条行为
-// 用例已进 server 仓;cli 仓另有 scripts/run-goal-stop-hook-live-test.mjs 的真引擎+真模型复验):
-//   ① 旧论断「SDK 类型 DEFERRED ⇒ 服务端会 400」**是把类型面当成了运行时校验面**,对 server
-//      不成立:`parseHooksConfig({Stop:[{hooks:[{type:"prompt",prompt}]}]})` 无 error、真解析;
-//      prompt 形在 server 的条目白名单里与 command/http/agent **并列**
-//      (@sema-agent/server hooks/hook-runner `entry.type !== "command" && … !== "prompt" && …`
-//      那道 type_not_supported 闸口把 prompt 放行,1.277.1 dist 对应 hook-runner.js:390)。
-//      卡着的只是 **SDK / registry-core 的类型**(见下方 cast),与 server 运行时接受与否两件事。
-//   ② 旧论断「引擎侧 Stop×prompt 是否真 fire 未取证」已取证:**真 fire**(Stop 触发时 prompt
-//      载体调用一次,`$ARGUMENTS` 已替换为 payload JSON)、**能拦停**(模型输出
-//      `{"decision":"block","reason":…}` → `{block: reason}`,core `runner/runtask.js:1663`
-//      `(spec.hooks ?? deps.hooks)?.stop` 起 stop gate,整条链通)、非决策 JSON 不拦(与 command
-//      形 exit-0 非 JSON 同语义)、`stop_hook_active:true` 如实进 payload(模型可自己收手;core
-//      另有 STOP_HOOK_BLOCK_CAP=8 连续拦停硬上限兜底,不会无限拦停)。
-//   ③ 最坏情况**不是** 400,而是**钩子不生效**:部署没组装 prompt 载体(`ctx.hookLlm` 缺席)⇒
-//      server 记账 `hook_entries_skipped{reason:"llm_carrier_unavailable"}` 并跳过,**非阻断**。
-// ⇒ 默认开。等件(不阻断本腿):registry-core hooks 契约建模 prompt 形([1717]① 在飞)、SDK
-//   `SettingsHookCommand` 放开 prompt 形 —— 到位后把下方 cast 换成直类型即可。
-//
-// 纪律:
-//  - 只放 goal 这一条(单值,不是通用会话钩子通道)——通用会话/插件钩子仍按模块头所述不投影;
-//  - 走 hooksForWire() 的**同一套治理门**(trust / disableAllHooks / allowManagedHooksOnly):
-//    overlay 在门之后才合并,策略禁钩子时一并禁掉;
-//  - `/goal clear` 传 null 收回。
-let wireSessionStopHookPrompt = null;
-/**
- * CC 语义档的**锁存位**(见 {@link setWireSessionStopHook})。投影形按它分道:
- * 真 ⇒ 裸条件(引擎自己包 CC 形);假 ⇒ 壳自造的门 prompt(老引擎唯一能落地的形)。
- */
-let wireSessionStopHookCcSemantics = false;
-/** The env ESCAPE HATCH for the engine leg (see the block comment above). */
-export const GOAL_STOP_HOOK_WIRE_ENV = 'SEMA_GOAL_STOP_HOOK_WIRE';
-// ── 引擎档位:CC 220 Stop×prompt 完整语义(达标线 = CC_STOP_SEMANTICS_MIN_SERVER,见下)────────
-//
-// server 1.279.0 把 CC 220 的 prompt-hook 半场搬进了引擎(dist/hooks/cc-stop-prompt.js +
-// branch-transcript.js,源码直读):
-//   ① Stop×prompt 触发时先取 `sctx.getBranch()`(core 1.419+ 就在 stop gate ctx 里传了它)渲染成
-//      会话转录;**证据面为空则整条 prompt 条目被过滤掉、评估者根本不被调用**
-//      (`hook_entries_skipped{reason:"stop_prompt_no_evidence:<why>"}`)——这正是老引擎那条
-//      「白烧一次模型调用、零效果」的反面;
-//   ② 调用时带 CC 220 **逐字**的系统提示(`ccPromptSystemFor("Stop")` = CC 的 full 档)+ CC 逐字的
-//      条件包装(`wrapCondition`);
-//   ③ 判词 `{ok,reason,impossible}` 在**引擎翻译层**映射:ok ⇒ 放行、impossible ⇒ 记 warn 后**放行**
-//      (真 fail-open,既不 block 也不产 additionalContext)、其余 ⇒ block(reason 喂回模型)。
-//
-// ⇒ 到这一档,壳侧唯一正确的动作是把 CC `Xdr` 的**原形(裸条件)**投出去 —— 引擎会自己包。继续投
-//   壳自造的门 prompt 只会被再包一层、并与 CC 系统提示要求的判词 schema 打架。
-// 🔴 但老引擎**没有这套**(1.278.0 的 hooks/ 目录里既无 cc-stop-prompt 也无 branch-transcript,
-//   hook-llm 连 `system` 形参都没有):裸条件送过去评估者对本会话是瞎的,回散文 ⇒ 一次都不拦。
-//   所以判档失败/探不到时**必须**退回老形,绝不「因为代码里写了 enforced 就真拦」。
-//
-// 🔴 **为什么达标线钉 1.279.3 而不是 CC 面首次出现的 1.279.0** —— 两道闸,缺一道都不许翻档:
-//
-//   ① **core 下限**(1.279.1 才补上):CC Stop 语义在 1.279.0 就在了,但 1.279.1 才把
-//      `@sema-agent/core` 的下限提到 `^1.422.0`。core <1.422 上,一条只带 `additionalContext` 的
-//      Stop 反馈**不结束 + 不计数 + 清零计数** ⇒ block 与 additionalContext 交替时计数呈锯齿
-//      (`[0,1,0,1,0]`)、`STOP_HOOK_BLOCK_CAP` 永远到不了 ⇒ 无界循环;1.422 起它计入上限且不再清零。
-//      (注:goal 这条路本身产不出 additionalContext —— CC 判词的 ok/impossible 两支在引擎翻译层都
-//       直接 `continue`;但那条通道对 command 形钩子是开着的,而**上限修好的是最坏值,不是这条通道的
-//       性质**:它仍然会让那一轮不结束。所以措辞面一步都不许放松,见 cmd-goal 的 meta 四档。)
-//
-//   ② **判词额度**(1.279.3 才补上):1.279.1/1.279.2 的引擎侧 hook 载体把 `max_tokens` 钳死在
-//      `Math.min(…, 1024)`(dist/hooks/hook-llm.js)。而 CC 的评估者系统提示要求「quote evidence
-//      from the transcript」,推理档模型的 thinking 还与输出**共用**这份额度 ⇒ 判词被截断(JSON 不
-//      闭合)或干脆零 text 块 ⇒ `parseCcVerdict` 拿不到 ⇒ 引擎**丢弃整条判词并 fail-open 放行**。
-//      🔴 这条缺口的形状与 ① 不同,但危害更隐蔽:它让 enforced 档对模型讲的那两句承诺在**守卫失效
-//      的那些轮里变成空话,而且没有任何人知道**(引擎侧只留一行 `hook_llm_unparsed_verdict` /
-//      `hook_llm_failed{returned no content}` 记账,壳侧、用户侧、模型侧全都看不到)。
-//      1.279.3 起 `maxOutputTokens` 由调用方声明,CC 评估者路声明 `CC_EVALUATOR_MAX_OUTPUT_TOKENS`
-//      = 4096,并对「无内容」重试一次(**不**重试「有内容但读不懂」)。
-//
-// ⇒ 达标线钉的是「**承诺能兑现**的那个组合」,不是「能力面在场」的那一版。差一档就翻,等于把用户
-//   放到一个「守卫会静默失效」的搭配上,还对着模型把话说满。
-export const CC_STOP_SEMANTICS_MIN_SERVER = '1.279.3';
-/** `x.y.z` → 数值三元组;非法形 ⇒ null(预发标记按「未达标」处理,见下)。 */
-function parseSemverCore(v) {
-    const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
-    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
-}
-/**
- * 引擎自报版本是否达到 CC Stop 语义线({@link CC_STOP_SEMANTICS_MIN_SERVER})。
- *
- * 🔴 三条纪律:
- *   · **数值比较**,不是字典序(`1.9.0` < `1.279.0`,字符串比较会判反);
- *   · **预发版不算达标**(`1.279.0-rc.1` 里那套可能还在改)——正则只认三段纯数字,带 `-` 的直接落
- *     null ⇒ false;
- *   · 读不出/探不到 ⇒ **false**(降级方向恒安全:老形在新引擎上仍能拦,新形在老引擎上一次都拦不住)。
- */
-export function ccStopSemanticsFromVersion(version) {
-    if (typeof version !== 'string' || version.length === 0)
-        return false;
-    const got = parseSemverCore(version);
-    const min = parseSemverCore(CC_STOP_SEMANTICS_MIN_SERVER);
-    if (got === null || min === null)
-        return false;
-    for (let i = 0; i < 3; i++) {
-        if (got[i] !== min[i])
-            return got[i] > min[i];
-    }
-    return true;
-}
-/**
- * 本会话连着的引擎是否具备 CC Stop 语义?判据 = live 车道的 `/v1/capabilities` 自报 `version`
- * (engineCapsCache 的 boot-kick 缓存,与 `/health.version` 同源)。
- *
- * 🔴 「未判即降级」:caps 探测是构造期 fire-and-forget,`/goal` 真被敲下时通常早已落袋;万一没落袋
- * 就按老引擎走(meta 也同步退档)——**宁可少承诺,不可多承诺**。
- */
-export function engineCcStopSemantics(env = hostEnv()) {
-    const base = env.SEMA_LIVE_BASEURL;
-    if (!base)
-        return false;
-    return ccStopSemanticsFromVersion(engineCapString(base, 'version'));
-}
-/**
- * Is the `/goal` Stop-hook engine leg armed? **Default ON** since 2026-07-26 — both of the premises
- * that kept it opt-in were disproved by server-side behavior evidence ([1721]) and re-verified against
- * a real engine + real model (cli scripts/run-goal-stop-hook-live-test.mjs). Set
- * `SEMA_GOAL_STOP_HOOK_WIRE=0|false|no|off` to disarm (an operator escape hatch, not a default).
- */
-export function isGoalStopHookWireArmed(env = hostEnv()) {
-    const v = env[GOAL_STOP_HOOK_WIRE_ENV]?.trim().toLowerCase();
-    if (v === undefined || v === '')
-        return true;
-    return !(v === '0' || v === 'false' || v === 'no' || v === 'off');
-}
-/**
- * Register (or clear, with `null`) the session-scoped `/goal` Stop prompt hook that rides
- * `settings.hooks.Stop` to the engine. Single-valued: a new goal replaces the previous one,
- * exactly like CC 220's `Xdr` (remove-then-add). Projection is gated by
- * {@link isGoalStopHookWireArmed} — storing is always safe, sending is not (yet).
- */
-export function setWireSessionStopHook(prompt, opts) {
-    wireSessionStopHookPrompt = prompt && prompt.length > 0 ? prompt : null;
-    wireSessionStopHookCcSemantics = wireSessionStopHookPrompt === null ? false : opts?.ccSemantics === true;
-}
-/** The currently registered `/goal` Stop prompt, or null (registered ≠ projected — see the gate). */
-export function getWireSessionStopHook() {
-    return wireSessionStopHookPrompt;
-}
-/** 当前这条目标登记时锁存的档位(真 = 投裸条件,假 = 投壳自造的门)。 */
-export function getWireSessionStopHookCcSemantics() {
-    return wireSessionStopHookCcSemantics;
-}
-/**
- * 把 `/goal` 的**原始条件**包成一条对引擎 prompt 载体**可执行**的 Stop 门 prompt。
- *
- * 🔴 适用面(2026-07-26 提货批后):**只用于未达标线的引擎档**(见 {@link CC_STOP_SEMANTICS_MIN_SERVER})。
- * 达标档起引擎自己按 CC
- * 220 逐字组装(系统提示 + 会话转录 + `wrapCondition`),那一档投的是**裸条件** —— 见
- * {@link ccStopSemanticsFromVersion} 与 {@link hooksForWire} 的分道。本函数保留,是 tolerate-absent
- * 的实体:老引擎上退回它,仍能拦一次;删掉它等于在老引擎上静默失效。
- *
- * 🔴 为什么必须包(2026-07-26 live 围栏实测,不是设计偏好):CC 单进程的 prompt 钩子执行器
- * (`src/utils/hooks/execPromptHook.ts`)会给条件**套一层系统提示**(「You are evaluating a hook…
- * 回 `{ok:true}` / `{ok:false,reason}`」)**并把整段会话前置**,所以裸条件在 CC 那边能被真评估。
- * 引擎侧的载体两样都没有:
- *   · 无系统提示、无会话历史;
- *   · Stop payload 的 `transcript_path` 是**空串**(server basePayload),评估者对本会话是**瞎的**;
- *   · 判据 schema 也不同 —— core 只认 stdout JSON 的 `decision:"block"`。
- * 实测(钉版 server 1.277.1 + core 1.416 + 真模型):裸条件 `the project contains a file named
- * DONE.txt` 送过去,载体照样被调用,模型回的是**散文**(「I don't have direct access to your file
- * system…」)⇒ `parseHookStdout` 拿不到 decision ⇒ **一次都不拦**。即:不包 = 每次停机白烧一次
- * 模型调用、零效果。
- *
- * 所以这里把条件包成引擎契约里**能落地**的形状。诚实标注它**够不到 CC 的完整语义**:
- *   · 能做到:每个 turn 的**第一次**停机尝试被拦下,目标原文重新注入给模型,逼它自查后再收尾
- *     (`stop_hook_active` 为真时门自己收手 ⇒ 不会无限拦停);真正「条件是否成立」的判断交给
- *     **有会话、有工具的主模型**,而不是让瞎的评估者假装判断;
- *   · 做不到:CC 那种「拦到条件真成立为止」(需要引擎把 transcript 交给载体)、以及「条件满足后
- *     自动清除目标」。这两条是**等件**,meta 文案因此不照抄 CC `Pwo`(见 cmd-goal.tsx)。
- *
- * 台账仍存**原始条件**({@link getWireSessionStopHook}),所以 `/goal clear` 读回的是用户写的那句。
- */
-export function buildGoalStopHookPrompt(condition) {
-    const reason = `[session goal] Before you stop: verify that this goal actually holds — ${condition}. ` +
-        `If it does hold, say so plainly and finish. If it does not, keep working toward it and do not ` +
-        `pause to ask the user what to do.`;
-    return ('You are the Stop gate for an autonomous coding agent session. The user set this session goal, ' +
-        'which the agent is supposed to satisfy before it stops:\n' +
-        `<goal>\n${condition}\n</goal>\n` +
-        'Stop-hook input JSON: $ARGUMENTS\n' +
-        'Reply with RAW JSON only — no prose, no explanation, no code fences.\n' +
-        'If the input JSON has "stop_hook_active" set to true, this gate already fired once for this turn: ' +
-        'reply with exactly {"continue":true} so the agent may stop.\n' +
-        'Otherwise reply with exactly:\n' +
-        JSON.stringify({ decision: 'block', reason }));
-}
 /**
  * The merged, GOVERNANCE-GATED settings-file hooks for the wire, or undefined when none apply.
  * Per-event arrays concatenate across sources (policy → user → project → local).
@@ -282,21 +98,36 @@ 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 是
+    // `disableAllHooks`/`allowManagedHooksOnly` 两道治理门的唯一读口。此前读取失败(格式损坏 / 端内部
+    // 错误)与「本来就没配 policy」在这里被静默折成同一个 `policy = null` ⇒ 等价于「无限制」——而这条
+    // 恰恰是安全敏感面:治理策略读不出来时,更安全的默认应是「当作有限制」而不是「当作无限制」。改成
+    // fail-closed:读取真的**抛出**(不是「值合法地缺席」)⇒ 整条腿按 disableAllHooks 同款处置,不再
+    // 往下算 managedOnly / 拼装钩子。
     try {
         policy = settings.getSettingsForSource('policySettings');
     }
-    catch {
-        policy = null;
+    catch (err) {
+        hostLog('debug', `hooksWireCaps: policySettings read threw — fail-closed (no hooks projected to the engine): ${String(err)}`);
+        return undefined;
     }
     if (policy?.disableAllHooks === true) {
         hostLog('debug', 'hooksWireCaps: disableAllHooks (managed) — no hooks projected to the engine');
@@ -322,38 +153,14 @@ export function hooksForWire() {
     // `/goal` 的会话级 Stop×prompt 钩子(CC 220 Xdr)——在治理门之后合并,所以 trust /
     // disableAllHooks / allowManagedHooksOnly 任一命中时它同样不投影(managedOnly 下用户态的
     // goal 钩子也一并禁掉,与 EDITABLE_HOOK_SOURCES 被排除同理)。默认开,见上方 overlay 注释。
-    if (wireSessionStopHookPrompt !== null && !managedOnly && isGoalStopHookWireArmed()) {
-        // 🔴 这个双 cast 是**类型面的最小且诚实的局部处置**,不是「绕过校验」:
-        //   · server **运行时接受** prompt 形(hook-runner 条目白名单与 command/http/agent 并列,
-        //     [1721] 6 条行为用例 + cli 仓 live 围栏双证);
-        //   · 卡着的是 **SDK 类型**:`SettingsHookCommand.type` 仍是字面量 `"command"`
-        //     (@sema-agent/sdk dist/settings.d.ts,prompt 形 v1 标 DEFERRED);
-        //   · **registry-core 建模 prompt 形在 [1717]① 等件中**,SDK 随后放开。
-        // 到位后这里换成直类型、去掉 cast(唯一改动点,调用面不动)。
-        const goalMatcher = {
-            matcher: '',
-            // 🔴 投影形**按引擎档位分道**(锁存于 set 那一刻,见 setWireSessionStopHook):
-            //   · CC 语义档(server ≥ CC_STOP_SEMANTICS_MIN_SERVER)⇒ **裸条件** —— 与 CC `Xdr` 注册的
-            //     `{type:"prompt",prompt:condition}` 逐字同形;引擎自己套 CC 系统提示 + 会话转录 +
-            //     `wrapCondition`,再包一层只会打架;
-            //   · 老引擎档 ⇒ 包装后的可执行门 prompt(裸条件在老引擎上一次都拦不住 —— 见
-            //     buildGoalStopHookPrompt 的实测说明)。
-            // 台账两档都存**原始条件**,供 `/goal clear` 读回。
-            hooks: [
-                {
-                    type: 'prompt',
-                    prompt: wireSessionStopHookCcSemantics
-                        ? wireSessionStopHookPrompt
-                        : buildGoalStopHookPrompt(wireSessionStopHookPrompt),
-                },
-            ],
-        };
+    // REF-CC-156(split):判档/锁存态/包装全归 goalStopHook.ts,本文件只调尾部合流点。
+    const goalMatcher = goalStopHookMatcher(managedOnly);
+    if (goalMatcher !== null) {
         merged['Stop'] = [...(merged['Stop'] ?? []), goalMatcher];
     }
     return Object.keys(merged).length > 0 ? merged : undefined;
 }
 /** 测试钩:清 `/goal` 锁存(壳里靠进程边界隔离;包内同进程多组断言必须能清)。 */
 export function __resetHooksWireCapsForTests() {
-    wireSessionStopHookPrompt = null;
-    wireSessionStopHookCcSemantics = false;
+    __resetGoalStopHookForTests();
 }

package/dist/host.d.ts

@@ -19,8 +19,15 @@
  * miss 计数(`hostPortMisses()`),宿主自检断言它恒为 0 —— 与 `notificationQueuePortMisses()`
  * 同一套姿势([probe-must-prove-it-speaks]:不能让「什么都没有」看起来像「一切正常」)。
  */
-import type { AdapterLogLevel } from './seam.js';
+import type { AdapterLogLevel, TimerHandle } from './seam.js';
 import { type NotificationQueuePort } from './notifications.js';
+/**
+ * settings 文件的顶层文档形状(TYPESHAPE-11)。开集是**有理由的**:settings 文件本身是用户
+ * 自由格式(壳三层合并后的 JSON、web center 下发、桌面主进程各自的形状都不同),库不认识
+ * 具体键——窄化点在各消费者(如 hooksWireCaps)按各自需要的子形状 cast。缺席该来源的
+ * settings ⇒ `null`(与本包既有 mock/消费点已经在用的口径一致,不是新增语义)。
+ */
+export type SettingsDocument = Record<string, unknown>;
 /**
  * settings 口 —— 用户 settings 文件的读取面(壳=三层合并后的文件读;web=center 下发;桌面=主进程)。
  *
@@ -29,7 +36,7 @@ import { type NotificationQueuePort } from './notifications.js';
  */
 export interface SettingsPort {
     /** 按来源取 settings(cli `utils/settings/settings.ts` 的 `getSettingsForSource`)。 */
-    getSettingsForSource(source: string): unknown;
+    getSettingsForSource(source: string): SettingsDocument | null;
     /**
      * 信任门:hook 是否因工作区未受信而跳过。**返回 true = 跳过**。
      * 🔴 B6 更正:壳侧真身 `utils/hooks.shouldSkipHookDueToTrust()` 是**零参**的(门是工作区级、
@@ -49,10 +56,14 @@ export interface FsPort {
     /** 🔴 壳侧真身是 **async**(mkdir 0o700);端可返 void 或 Promise,库两种都吞(fire-and-forget)。 */
     ensureScratchpadDir(): void | Promise<void>;
 }
-/** 定时器口(进程级默认;`ctx.setTimer` 仍可按 turn 覆盖)。 */
+/**
+ * 定时器口(进程级默认;`ctx.setTimer` 仍可按 turn 覆盖)。
+ * 🔴 TYPESHAPE-10:句柄用 seam.ts 已有的命名不透明别名 `TimerHandle`(不透明本身不变 —— Node 是
+ * Timeout 对象、浏览器是 number,库侧只负责回传;只是把裸 `unknown` 收进一个有名字的口)。
+ */
 export interface TimersPort {
-    setTimer(ms: number, fn: () => void): unknown;
-    clearTimer(handle: unknown): void;
+    setTimer(ms: number, fn: () => void): TimerHandle;
+    clearTimer(handle: TimerHandle): void;
 }
 /**
  * session 口(**B6 引入**)—— 「现在是哪个会话 / 哪个 run 在飞」。

package/dist/index.d.ts

@@ -150,6 +150,7 @@ export * from './engineToolLabelStore.js';
 export * from './fleetTaskDesc.js';
 export type * from './types/engineState.js';
 export * from './hostEnv.js';
+export * from './unrefTimer.js';
 export * from './controlRouter.js';
 export * from './sseIdleTriage.js';
 export * from './engineWireSdk.js';
@@ -211,6 +212,7 @@ export * from './hooksWireCaps.js';
 export * from './liveInitToolFace.js';
 export * from './model/providerPresets.js';
 export * from './hitl/hitlBridge.js';
+export * from './hitl/hitlHostSurface.js';
 export * from './hitl/toolApprovalWire.js';
 export * from './hitl/askGateWire.js';
 export * from './hitl/planReviewWire.js';

package/dist/index.js

@@ -153,6 +153,10 @@ export * from './fleetTaskDesc.js';
 // 通知族(engineTaskNotification + taskNotificationErrorSupplement + hookNoticeStore 判定半场)
 // 已并入 notifications.js,不需要新增导出行。
 export * from './hostEnv.js';
+export * from './unrefTimer.js';
+// REF-CC-141 dup-02(wave1 卡B,2026-08-01):envFlag.ts 是十处 SEMA_* 布尔 env 旋钮拼写集
+// 单源叶模块,但只被十个已在闭包里的模块值级 import 消费,不需要经 barrel 发到 npm 公面
+// (wave1 回炉 advisory:摘掉此行,envFlagOff/envFlagOn 保持包内部,不进 public-export-baseline)。
 export * from './controlRouter.js';
 export * from './sseIdleTriage.js';
 export * from './engineWireSdk.js';
@@ -197,6 +201,12 @@ export * from './clientSlice.js';
 // 包级宿主装配(per-turn 的 AdapterContext 之外的那一层:settings / fs / queue / timers)。
 // 🔴 `installNotificationQueuePort` 仍是队列的真源出口,`installHost({queue})` 只是直通它。
 export * from './host.js';
+// REF-CC-147/REF-CC-149(P2「I族」裁定):D 族循环收编只抽的两个低层原语之一——「怎么安全地睡
+// 一觉」,workflowClient.ts 与 agentSession/backgroundView.ts 的轮询退避共用。wave1 回炉复审
+// (opus advisory)撤回:这是包内实现叶,不出 barrel(与下面 `createSessionSlot` 同一先例)——
+// 出了 barrel 就是 public-export-baseline.json 自述的**不可撤回承诺**,而没有任何门要求它公开;
+// 内部两处消费点都是相对路径 `import { abortableSleep } from './abortableSleep.js'`,门也改吃
+// `dist/abortableSleep.js`(见 scripts/run-abortable-sleep-test.mjs)。
 // W1(design/161):五个模块级单槽位的 per-session 注册表键。零参旧 API 全部等价于用这个键调
 // `*For(sessionKey, …)` 变体;多会话宿主(desktop)每会话一键。`createSessionSlot` 是包内实现件,
 // 刻意不出 barrel(公面只承诺键与各槽位的 *For API)。
@@ -264,9 +274,13 @@ export * from './model/providerPresets.js';
 // 🔴 两个新拆缝口(缺席都计 miss,宿主自检恒应为 0):
 //    · `installApprovalCardPort` —— 三选卡本体(vendored CC `PermissionRequest` / 桌面模态);
 //    · `installHitlHostSurface` —— footer 通知与 /permissions Recent Denials 记账(端状态形状)。
-// 🔴 单实例:`toolApprovalWire` 的卡口槽 + `askGateWire` 的宿主面槽是 module 级变量;两份实例 ⇒
+// 🔴 单实例:`toolApprovalWire` 的卡口槽 + `hitlHostSurface` 的宿主面槽是 module 级变量;两份实例 ⇒
 //    装在一份、读另一份 = 每张 gate 都走 fail-closed deny(卡根本不弹)。
+// 🆕 REF-CC-023(2026-08-02,P3 wave2 卡C-bridge):`hitlHostSurface.ts` 从 `askGateWire.ts` 里提出的
+//    共享宿主通知面 + cancel-by-deny 有界观察 —— `askGateWire.ts` 已 import `toolApprovalWire.ts`,
+//    反向 import 会成环,所以两条腿共用的那一组挪进一个两边都能到达的独立模块。
 export * from './hitl/hitlBridge.js';
+export * from './hitl/hitlHostSurface.js';
 export * from './hitl/toolApprovalWire.js';
 export * from './hitl/askGateWire.js';
 export * from './hitl/planReviewWire.js';

package/dist/interactiveToolsWire.d.ts

@@ -16,8 +16,9 @@
  *   · 显式交互意图恒赢:CLI 无 --interactive-tools 类旗(gap-check 2026-07-16:上游 CC 2.1.207
  *     与本壳 argv 面均无,不发明);既有旗里唯一表达「我要交互门」的是 `--permission-mode plan`
  *     (plan 流程本身要 plan-review 交互)——该旗在场时不 stamp(维持引擎缺省判据);
- *   · SEMA_HEADLESS_INTERACTIVE_TOOLS 部署旋钮(settings env 车道):true/1 = 不 stamp(回引擎
- *     缺省判据),false/0 = 显式 stamp false(与缺省同效,显式垫);非法值一次性 warn + 回缺省;
+ *   · SEMA_HEADLESS_INTERACTIVE_TOOLS 部署旋钮(settings env 车道,拼写集 = envFlagOn/envFlagOff、
+ *     REF-CC-141 dup-02 单源):真值拼写 = 不 stamp(回引擎缺省判据),假值拼写 = 显式 stamp false
+ *     (与缺省同效,显式垫);非法值一次性 warn + 回缺省;
  *   · 缺省 = stamp false(无人值守正解);
  *   · 旧 server 白名单 fail-soft:server resolveSpec 逐字段白名单拼 TaskSpec,未知 body 字段静默
  *     忽略(limits wire 同款勘察结论)——本字段发了白发不炸。gap-check 实拆 server 1.210.0 dist:
@@ -36,8 +37,18 @@ export type InteractiveToolsResolution = {
     /** 非法 env 值的告警文案(调用层一次性打 stderr)。 */
     warning?: string;
 };
-/** argv 里是否显式要了 plan 交互意图(`--permission-mode plan` / `--permission-mode=plan`;
- *  后出现者赢,commander 同语义;`--` 之后不是 flag)。 */
+/**
+ * argv 里是否显式要了 plan 交互意图(`--permission-mode plan` / `--permission-mode=plan`;
+ * 后出现者赢,commander 同语义;`--` 之后不是 flag)。
+ *
+ * REF-CC-143(dup-10)收编,2026-08-01:这个函数原本自带一份与 headlessPermissionModeWire.
+ * permissionModeFromArgv 逐字重复的 argv 扫描循环(两个 headless 旋钮读的是同一个 `--permission-mode`
+ * flag,必须是同一份读法)。dup-10 证明过等价性:`permissionModeFromArgv` 的
+ * `--dangerously-skip-permissions` 分支只在没有显式 `--permission-mode` 时才返回
+ * `'bypassPermissions'`,那个值永远不等于 `'plan'`,所以对任意 argv 恒有
+ * `planModeExplicitlyRequested(argv) === (permissionModeFromArgv(argv) === 'plan')`——折成薄壳,
+ * 循环整个消失,而不只是「提取逻辑」被共享。
+ */
 export declare function planModeExplicitlyRequested(argv: readonly string[]): boolean;
 /**
  * 解析 headless `-p` 的 interactiveTools stamp。纯函数除告警 latch。

package/dist/interactiveToolsWire.js

@@ -16,8 +16,9 @@
  *   · 显式交互意图恒赢:CLI 无 --interactive-tools 类旗(gap-check 2026-07-16:上游 CC 2.1.207
  *     与本壳 argv 面均无,不发明);既有旗里唯一表达「我要交互门」的是 `--permission-mode plan`
  *     (plan 流程本身要 plan-review 交互)——该旗在场时不 stamp(维持引擎缺省判据);
- *   · SEMA_HEADLESS_INTERACTIVE_TOOLS 部署旋钮(settings env 车道):true/1 = 不 stamp(回引擎
- *     缺省判据),false/0 = 显式 stamp false(与缺省同效,显式垫);非法值一次性 warn + 回缺省;
+ *   · SEMA_HEADLESS_INTERACTIVE_TOOLS 部署旋钮(settings env 车道,拼写集 = envFlagOn/envFlagOff、
+ *     REF-CC-141 dup-02 单源):真值拼写 = 不 stamp(回引擎缺省判据),假值拼写 = 显式 stamp false
+ *     (与缺省同效,显式垫);非法值一次性 warn + 回缺省;
  *   · 缺省 = stamp false(无人值守正解);
  *   · 旧 server 白名单 fail-soft:server resolveSpec 逐字段白名单拼 TaskSpec,未知 body 字段静默
  *     忽略(limits wire 同款勘察结论)——本字段发了白发不炸。gap-check 实拆 server 1.210.0 dist:
@@ -25,29 +26,24 @@
  *     壳先备(黑板记账)。
  */
 import { hostEnv } from './hostEnv.js';
+import { envFlagOff, envFlagOn } from './envFlag.js';
+import { permissionModeFromArgv } from './headlessPermissionModeWire.js';
 /** 部署旋钮 env 键名(settings.json env 块 → 1a-envseed → process.env 同车道)。 */
 export const HEADLESS_INTERACTIVE_TOOLS_ENV = 'SEMA_HEADLESS_INTERACTIVE_TOOLS';
-/** argv 里是否显式要了 plan 交互意图(`--permission-mode plan` / `--permission-mode=plan`;
- *  后出现者赢,commander 同语义;`--` 之后不是 flag)。 */
+/**
+ * argv 里是否显式要了 plan 交互意图(`--permission-mode plan` / `--permission-mode=plan`;
+ * 后出现者赢,commander 同语义;`--` 之后不是 flag)。
+ *
+ * REF-CC-143(dup-10)收编,2026-08-01:这个函数原本自带一份与 headlessPermissionModeWire.
+ * permissionModeFromArgv 逐字重复的 argv 扫描循环(两个 headless 旋钮读的是同一个 `--permission-mode`
+ * flag,必须是同一份读法)。dup-10 证明过等价性:`permissionModeFromArgv` 的
+ * `--dangerously-skip-permissions` 分支只在没有显式 `--permission-mode` 时才返回
+ * `'bypassPermissions'`,那个值永远不等于 `'plan'`,所以对任意 argv 恒有
+ * `planModeExplicitlyRequested(argv) === (permissionModeFromArgv(argv) === 'plan')`——折成薄壳,
+ * 循环整个消失,而不只是「提取逻辑」被共享。
+ */
 export function planModeExplicitlyRequested(argv) {
-    let mode;
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === '--permission-mode') {
-            const v = argv[i + 1];
-            if (typeof v === 'string' && !v.startsWith('-')) {
-                mode = v;
-                i++;
-            }
-        }
-        else if (a?.startsWith('--permission-mode=')) {
-            mode = a.slice('--permission-mode='.length);
-        }
-        else if (a === '--') {
-            break;
-        }
-    }
-    return mode === 'plan';
+    return permissionModeFromArgv(argv) === 'plan';
 }
 // 一次性告警 latch(-p 是 one-shot 进程;测试钩子可重置)
 let warnedInvalidEnv = false;
@@ -60,12 +56,14 @@ export function resolveHeadlessInteractiveTools(argv, env = hostEnv()) {
     if (planModeExplicitlyRequested(argv)) {
         return { fields: {}, source: 'plan-flag' };
     }
-    // 2) 部署旋钮。
+    // 2) 部署旋钮。拼写集 = envFlagOn/envFlagOff(REF-CC-141 dup-02 单源)—— 修前本处是四份重复
+    //    实现里唯一不 lowercase 的一份(`raw==='true'||raw==='1'`),`SEMA_HEADLESS_INTERACTIVE_
+    //    TOOLS=False` 会落进下面的「不是布尔值」warn 分支,现改为大小写不敏感 + 拼写集与其它九处同源。
     const raw = env[HEADLESS_INTERACTIVE_TOOLS_ENV]?.trim();
     if (raw !== undefined && raw !== '') {
-        if (raw === 'true' || raw === '1')
+        if (envFlagOn(raw))
             return { fields: {}, source: 'env' }; // 回引擎缺省判据
-        if (raw === 'false' || raw === '0')
+        if (envFlagOff(raw))
             return { fields: { interactiveTools: false }, source: 'env' };
         const resolution = {
             fields: { interactiveTools: false },
@@ -73,7 +71,7 @@ export function resolveHeadlessInteractiveTools(argv, env = hostEnv()) {
         };
         if (!warnedInvalidEnv) {
             warnedInvalidEnv = true;
-            resolution.warning = `sema: ${HEADLESS_INTERACTIVE_TOOLS_ENV}="${raw}" is not a boolean (expected true/1/false/0) — ignoring it, headless -p keeps interactive tools OFF by default`;
+            resolution.warning = `sema: ${HEADLESS_INTERACTIVE_TOOLS_ENV}="${raw}" is not a recognized boolean spelling (expected true/1/yes/on or false/0/no/off/none) — ignoring it, headless -p keeps interactive tools OFF by default`;
         }
         return resolution;
     }

package/dist/limitsWire.js

@@ -33,6 +33,7 @@
  * Unreachable /health or an unparsable version stays silent (can't confirm staleness — fail-soft).
  */
 import { hostEnv } from './hostEnv.js';
+import { lastFlagValue } from './argvFlagValue.js';
 /** Settings-lane env knobs (settings.json `env` block → 1a-envseed → process.env). */
 export const HEADLESS_DEADLINE_ENV = 'SEMA_HEADLESS_DEADLINE_SEC';
 export const HEADLESS_MAX_TURNS_ENV = 'SEMA_HEADLESS_MAX_TURNS';
@@ -53,46 +54,12 @@ const MAX_TURNS_USAGE = `sema: --max-turns expects a whole number of turns betwe
     '  (no flag)            no turn cap — today\'s behaviour';
 /** STRICT integer shape for explicit flag values: ASCII digits only (no sign/decimal/exponent/space). */
 const INT_RE = /^\d+$/;
-/**
- * Pull the LAST value of a `--name <v>` / `--name=<v>` flag out of an argv slice (everything before a
- * bare `--` — positionals are never flags; scenarioWire 纪律). Returns:
- *   {present:false}                 — flag absent
- *   {present:true, raw}             — flag present with a value token
- *   {present:true, raw:undefined}   — flag present but the value is missing/flag-shaped (fail-loud at caller)
- */
-function lastFlagValue(argv, name) {
-    const eq = `${name}=`;
-    let present = false;
-    let raw;
-    let valueMissing = false;
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === '--')
-            break; // positionals — never flags
-        if (a === name) {
-            present = true;
-            const nxt = argv[i + 1];
-            if (nxt === undefined || nxt.startsWith('-')) {
-                // note: a NEGATIVE number would look flag-shaped too — the domains are all-positive, so the
-                // fail-loud usage hint is the right answer for `--deadline -5` as well.
-                valueMissing = true;
-                raw = undefined;
-                continue;
-            }
-            valueMissing = false;
-            raw = nxt;
-            i++; // consume the value token
-        }
-        else if (a.startsWith(eq)) {
-            present = true;
-            valueMissing = false;
-            raw = a.slice(eq.length);
-        }
-    }
-    if (present && (valueMissing || raw === undefined))
-        return { present: true };
-    return present ? { present: true, raw } : { present: false };
-}
+// `lastFlagValue` (the `--name <v>`/`--name=<v>`/repeated-flag-last-wins scan) now lives in
+// argvFlagValue.ts (REF-CC-143/dup-07, P3 wave1 卡C-argv, 2026-08-01) — this was the fullest of five
+// hand-rolled copies (present/raw/valueMissing three-state) and is the one the shared leaf was cribbed
+// from verbatim; see that file's header for the shared 缺值 contract. `--deadline`/`--max-turns` are
+// both all-positive domains, so a NEGATIVE number (which looks flag-shaped to the scanner) correctly
+// falls into the same fail-loud usage-hint path as a genuinely missing value below.
 /** Validate a RAW flag value against an inclusive integer domain. Returns the number or null. */
 function parseIntInDomain(raw, min, max) {
     const v = raw.trim();