@sema-agent/client-core 0.12.2 → 0.14.0

package/dist/fleetAgentPanelProjection.js

@@ -1,6 +1,10 @@
 /**
  * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/fleetAgentPanelProjection.ts 逐字搬入(唯一 import = 同批搬入的
  * engineAgentPanelStore,包内相对路径不变;壳侧改 re-export)。
+ * 🔴 REF-CC-041/042(P3 wave2,fleet2-03/04):P1 迁移之后本文件不再是「唯一 import」——同批把
+ * `TERMINAL_STATUSES` 改成 import `./fleet/fleetProjection.js` 的 `TERMINAL_FLEET_TASK_STATUSES`
+ * (单源,原副本零测试锁着,分叉理由已不成立)、`rowIdTail` 改 import `./workflow.js`(同包另两个
+ * 消费者 `fleet/fleetLedger.ts` / `fleet/fleetProjection.ts` 早就这么做,只有本文件是例外)。
  * ⚠️ 本文件含**两个字面 NUL 字节**(`${ct.toolName}\0${ct.target}` 的 currentTool 判等键分隔符,
  * 语义承载位,搬迁时逐字节保留)—— 副作用:BSD `grep`/`file` 把本文件当二进制,`grep` 不加 `-a`
  * 会**静默零命中**(不是「没有」,是「没在找」)。改本文件的探针一律 `grep -a`。
@@ -36,37 +40,72 @@
  *    安全网不是真相源(真终态来自行帧终态 / bg_notification),宽限窗内的重连空窗(snapshot 清表)
  *    不会误结。lastSeen 恒**先**按本次在场行刷新、再判缺席,所以 footer 长时间卸载后重挂也不误结。
  * ④ 行 id 尾段判(`${runId} ${taskId}` 复合形取尾;真机 1.277.4 上子行 id 是裸 a+16hex,复合形是
- *    run 发布器双生行的形)——与 footerRowBelt.rowIdTail 同语义就地实现,保持本模块零依赖。
+ *    run 发布器双生行的形)——REF-CC-042:与同包 `workflow.rowIdTail` 同一个函数(import,不再
+ *    就地维护第二份;该函数出过等价性事故,0.1.1 修,见 `workflow.ts` 头注)。
  */
 import { publishEngineAgentPanelEvent } from './engineAgentPanelStore.js';
-/** 与 fleetClient.TERMINAL_FLEET_TASK_STATUSES 同源词汇(刻意双份,零模块图污染;drift 由本套锁)。 */
-const TERMINAL_STATUSES = new Set(['completed', 'failed', 'killed']);
+import { rowIdTail } from './workflow.js';
+import { TERMINAL_FLEET_TASK_STATUSES } from './fleet/fleetProjection.js';
+import { DEFAULT_SESSION_KEY } from './sessionSlot.js';
 /** 行从投影集消失多久之后按 completed 兜底 settle(重连空窗 / snapshot 清表远小于此)。 */
 export const ABSENT_SETTLE_MS = 30_000;
+/** REF-CC-045(fleet2-07):settled 条目的回收期 —— settle 后这么久仍未再被投影 ⇒ 台账整条
+ *  delete,给 `fleetAgentProjectionSizeFor()` 一个上界(此前 `seen` 只增不减,长会话里每个
+ *  跑过的 bg 子代永久占一条)。settle 事件已经发过,消费端 settle 幂等,delete 对外无事件。 */
+const SETTLED_RETENTION_MS = ABSENT_SETTLE_MS * 4;
 /** currentTool 判等键(POST-MERGE 行每秒重发同值,只有键变了才算变化)。 */
 function currentToolKeyOf(ct) {
     if (!ct || typeof ct.toolName !== 'string' || ct.toolName.length === 0)
         return undefined;
     return `${ct.toolName}\u0000${ct.target ?? ''}`;
 }
+/** REF-CC-045(fleet2-07):per-sessionKey 台账(W1 同款 `Map<sessionKey, Map<...>>` 形)。 */
 const seen = new Map();
-/** 复合行键(`<runId> <taskId>`)的尾段 = 引擎 taskId(handle)。 */
-function rowIdTail(id) {
-    return id.split(/\s+/).pop() ?? id;
+function seenFor(sessionKey) {
+    let m = seen.get(sessionKey);
+    if (!m) {
+        m = new Map();
+        seen.set(sessionKey, m);
+    }
+    return m;
 }
-/** 测试钩:清投影台账。 */
+/**
+ * 测试钩:清投影台账 —— **全部 sessionKey**,不是只清 default 桶。
+ *
+ * 🔴 回炉定谳(P3 wave2 复审 blocker④):per-session 化那一批一度把它收窄成
+ * `resetFleetAgentPanelProjectionFor(DEFAULT_SESSION_KEY)`。它的契约是「清投影台账」,不是一个
+ * 会话语义位 —— 收窄等于给多会话宿主的用例之间留一条跨用例串扰通道(用例 A 先
+ * `projectFleetAgentRowsFor('sess-b', …)`,用例间调零参 reset,`sess-b` 桶存活 ⇒ 下个用例首次
+ * 投影同 taskId 时 `prev` 非空且 `settled:true`,`fleet-row`/`end` 被去重门吞掉)。
+ * 对位实现同形:`fleet/fleetLedger.__resetFleetLedgerRegistryForTests()` = `liveBgViews.clear()`;
+ * W1 段五个槽位的现成规约也逐个钉的是「reset 清全部键」。
+ * 要只清一个会话请用 `resetFleetAgentPanelProjectionFor(sessionKey)`。
+ */
 export function resetFleetAgentPanelProjection() {
     seen.clear();
 }
+/** W1 keyed variant(REF-CC-045):只清**这一个会话**的桶。 */
+export function resetFleetAgentPanelProjectionFor(sessionKey) {
+    seen.delete(sessionKey);
+}
 /** 台账读面(测试/诊断):当前记着的行数。 */
 export function fleetAgentProjectionSize() {
-    return seen.size;
+    return fleetAgentProjectionSizeFor(DEFAULT_SESSION_KEY);
+}
+/** W1 keyed variant。 */
+export function fleetAgentProjectionSizeFor(sessionKey) {
+    return seen.get(sessionKey)?.size ?? 0;
 }
 /**
  * 把一次 fleet 投影(已经过 own 判别 + workflow belt 的 FleetTask[])喂给面板事件流。
  * 幂等、无副作用地重复调用安全 —— 每秒被 footer 调用两次就是常态。
  */
 export function projectFleetAgentRows(rows, nowMs = Date.now()) {
+    projectFleetAgentRowsFor(DEFAULT_SESSION_KEY, rows, nowMs);
+}
+/** W1 keyed variant(REF-CC-045):多会话宿主每会话一份台账,互不顶盖。 */
+export function projectFleetAgentRowsFor(sessionKey, rows, nowMs = Date.now()) {
+    const seenMap = seenFor(sessionKey);
     const present = new Set();
     for (const row of rows) {
         if (!row?.id)
@@ -83,8 +122,8 @@ export function projectFleetAgentRows(rows, nowMs = Date.now()) {
         const startedAt = typeof row.startedAt === 'number' && row.startedAt > 0 ? row.startedAt : undefined;
         const currentTool = currentToolKeyOf(row.currentTool) !== undefined ? row.currentTool : undefined;
         const currentToolKey = currentToolKeyOf(row.currentTool);
-        const prev = seen.get(taskId);
-        if (TERMINAL_STATUSES.has(status)) {
+        const prev = seenMap.get(taskId);
+        if (TERMINAL_FLEET_TASK_STATUSES.has(status)) {
             // ② 终态一次性 settle(幂等台账;消费端 settle 也幂等)。
             if (!prev?.settled) {
                 // 终态行也把最后一拍的累计工具数/转录锚带上:详情页在行翻终态后仍要显示真计数与
@@ -109,7 +148,7 @@ export function projectFleetAgentRows(rows, nowMs = Date.now()) {
                     isError: status === 'failed' || status === 'killed',
                 });
             }
-            seen.set(taskId, {
+            seenMap.set(taskId, {
                 status,
                 tokens,
                 toolUses: toolUses !== undefined ? toolUses : prev?.toolUses,
@@ -147,7 +186,7 @@ export function projectFleetAgentRows(rows, nowMs = Date.now()) {
             });
         }
         // 台账对这几位是**粘性**的:缺席帧不擦掉已知值(同上的单向语义)。
-        seen.set(taskId, {
+        seenMap.set(taskId, {
             status,
             tokens,
             toolUses: toolUses !== undefined ? toolUses : prev?.toolUses,
@@ -160,12 +199,20 @@ export function projectFleetAgentRows(rows, nowMs = Date.now()) {
     }
     // ③ 缺席兜底 —— 必须在【本次在场行全部刷完 lastSeen 之后】判,否则 footer 长时间卸载后重挂
     //    会把仍在跑的行按「陈旧」误结。
-    for (const [taskId, s] of seen) {
+    for (const [taskId, s] of seenMap) {
         if (present.has(taskId) || s.settled)
             continue;
         if (nowMs - s.lastSeenAt <= ABSENT_SETTLE_MS)
             continue;
         publishEngineAgentPanelEvent({ kind: 'end', taskId, isError: false });
-        seen.set(taskId, { ...s, settled: true });
+        seenMap.set(taskId, { ...s, settled: true });
+    }
+    // ④ REF-CC-045(fleet2-07):settled 条目回收 —— 给台账一个上界(此前只增不减)。settle 已发过
+    //    事件,delete 对外无事件,消费端 settle 本身幂等。
+    for (const [taskId, s] of seenMap) {
+        if (s.settled && nowMs - s.lastSeenAt > SETTLED_RETENTION_MS)
+            seenMap.delete(taskId);
     }
+    if (seenMap.size === 0)
+        seen.delete(sessionKey);
 }

package/dist/forkWireCaps.d.ts

@@ -21,5 +21,6 @@ import { type EnvLike } from './hostEnv.js';
 /** The env key the shell reads. SEMA_-namespaced so it never collides with a worker's own deploy env. */
 export declare const ENABLE_FORK_ENV: "SEMA_ENABLE_FORK";
 /** ENV source → explicit `true`/`false` when the user set SEMA_ENABLE_FORK either way, else
- *  `undefined` (⇒ no stamp ⇒ the engine default applies — GRANTED on core ≥1.257, CC parity). */
+ *  `undefined` (⇒ no stamp ⇒ the engine default applies — GRANTED on core ≥1.257, CC parity).
+ *  Spelling set = {@link envFlagOn}/{@link envFlagOff}(REF-CC-141 dup-02 单源)。 */
 export declare function enableForkFromEnv(env?: EnvLike): boolean | undefined;

package/dist/forkWireCaps.js

@@ -18,25 +18,19 @@
  * request shape never changes.
  */
 import { hostEnv } from './hostEnv.js';
+import { envFlagOff, envFlagOn } from './envFlag.js';
 /** The env key the shell reads. SEMA_-namespaced so it never collides with a worker's own deploy env. */
 export const ENABLE_FORK_ENV = 'SEMA_ENABLE_FORK';
-function isTruthy(v) {
-    const s = v.trim().toLowerCase();
-    return s === '1' || s === 'true' || s === 'yes' || s === 'on';
-}
-function isFalsy(v) {
-    const s = v.trim().toLowerCase();
-    return s === '0' || s === 'false' || s === 'no' || s === 'off';
-}
 /** ENV source → explicit `true`/`false` when the user set SEMA_ENABLE_FORK either way, else
- *  `undefined` (⇒ no stamp ⇒ the engine default applies — GRANTED on core ≥1.257, CC parity). */
+ *  `undefined` (⇒ no stamp ⇒ the engine default applies — GRANTED on core ≥1.257, CC parity).
+ *  Spelling set = {@link envFlagOn}/{@link envFlagOff}(REF-CC-141 dup-02 单源)。 */
 export function enableForkFromEnv(env = hostEnv()) {
     const raw = env[ENABLE_FORK_ENV];
     if (typeof raw !== 'string' || raw.trim() === '')
         return undefined;
-    if (isTruthy(raw))
+    if (envFlagOn(raw))
         return true;
-    if (isFalsy(raw))
+    if (envFlagOff(raw))
         return false;
     return undefined; // unrecognized spelling — don't guess, let the engine default apply
 }

package/dist/goalStopHook.d.ts

@@ -0,0 +1,142 @@
+/**
+ * REF-CC-156(midband-04,split,2026-08-02):拆自 `hooksWireCaps.ts`——那个文件里约 220 行(占其
+ * 387 行的 57%)是 `/goal` 命令专属的 Stop-hook 版本判档 + prompt 组装 + 模块级单实例状态,与
+ * `hooksWireCaps.ts` 其余部分(通用 settings-file hooks 投影 + 治理门)是两个不同的关注点,原文件
+ * 只在 `hooksForWire()` 尾部合流一次。纯搬迁,行为不变:所有导出名字原样保留(`hooksWireCaps.ts`
+ * 显式 re-export,外部 import 路径零改动),模块级状态(`wireSessionStopHookPrompt`/
+ * `wireSessionStopHookCcSemantics`)随代码一起搬到本文件,`docs/refactor/p1-scan/singleton-manifest.json`
+ * 的两条登记同批把 `file` 改成本文件坐标。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * 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 这一条(单值,不是通用会话钩子通道)——通用会话/插件钩子仍按 `hooksWireCaps.ts`
+ *    模块头所述不投影;
+ *  - 走 `hooksForWire()` 的**同一套治理门**(trust / disableAllHooks / allowManagedHooksOnly):
+ *    overlay 在门之后才合并,策略禁钩子时一并禁掉;
+ *  - `/goal clear` 传 null 收回。
+ */
+import { type EnvLike } from './hostEnv.js';
+import type { WireHooksConfig } from './finalVerifyWire.js';
+/** The env ESCAPE HATCH for the engine leg (see the block comment above). */
+export declare const GOAL_STOP_HOOK_WIRE_ENV = "SEMA_GOAL_STOP_HOOK_WIRE";
+export declare const CC_STOP_SEMANTICS_MIN_SERVER = "1.279.3";
+/**
+ * 引擎自报版本是否达到 CC Stop 语义线({@link CC_STOP_SEMANTICS_MIN_SERVER})。
+ *
+ * 🔴 三条纪律:
+ *   · **数值比较**,不是字典序(`1.9.0` < `1.279.0`,字符串比较会判反);
+ *   · **预发版不算达标**(`1.279.0-rc.1` 里那套可能还在改)——正则只认三段纯数字,带 `-` 的直接落
+ *     null ⇒ false;
+ *   · 读不出/探不到 ⇒ **false**(降级方向恒安全:老形在新引擎上仍能拦,新形在老引擎上一次都拦不住)。
+ */
+export declare function ccStopSemanticsFromVersion(version: string | undefined | null): boolean;
+/**
+ * 本会话连着的引擎是否具备 CC Stop 语义?判据 = live 车道的 `/v1/capabilities` 自报 `version`
+ * (engineCapsCache 的 boot-kick 缓存,与 `/health.version` 同源)。
+ *
+ * 🔴 「未判即降级」:caps 探测是构造期 fire-and-forget,`/goal` 真被敲下时通常早已落袋;万一没落袋
+ * 就按老引擎走(meta 也同步退档)——**宁可少承诺,不可多承诺**。
+ */
+export declare function engineCcStopSemantics(env?: EnvLike): boolean;
+/**
+ * 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` to an {@link envFlagOff} spelling(REF-CC-141 dup-02 单源)to disarm
+ * (an operator escape hatch, not a default).
+ */
+export declare function isGoalStopHookWireArmed(env?: EnvLike): boolean;
+/**
+ * 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 declare function setWireSessionStopHook(prompt: string | null, opts?: {
+    /**
+     * 这条目标登记时,引擎是否已判定为 CC 语义档({@link engineCcStopSemantics})?
+     *
+     * 🔴 **为什么要在 set 那一刻锁存,而不是在 `hooksForWire()` 里现读**:`/goal` 的 meta
+     * (对模型讲「会不会拦到条件成立为止」)是在 set 那一刻发出去的,而投影发生在随后每个 turn。
+     * 两处各读一次的话,caps 探测中途落袋就会造出「meta 承诺拦到底、投出去的却还是老门」的错配 ——
+     * 判据必须锚在**真正决定结果的那个量**上,而它只有一个:**这条目标登记时的档位**。
+     * 缺省 false ⇒ 不传就是老引擎档:翻档只能靠证据打开,不能靠默认值。
+     */
+    ccSemantics?: boolean;
+}): void;
+/** The currently registered `/goal` Stop prompt, or null (registered ≠ projected — see the gate). */
+export declare function getWireSessionStopHook(): string | null;
+/** 当前这条目标登记时锁存的档位(真 = 投裸条件,假 = 投壳自造的门)。 */
+export declare function getWireSessionStopHookCcSemantics(): boolean;
+/**
+ * 把 `/goal` 的**原始条件**包成一条对引擎 prompt 载体**可执行**的 Stop 门 prompt。
+ *
+ * 🔴 适用面(2026-07-26 提货批后):**只用于未达标线的引擎档**(见 {@link CC_STOP_SEMANTICS_MIN_SERVER})。
+ * 达标档起引擎自己按 CC
+ * 220 逐字组装(系统提示 + 会话转录 + `wrapCondition`),那一档投的是**裸条件** —— 见
+ * {@link ccStopSemanticsFromVersion} 与 `hooksForWire()` 的分道(见 {@link goalStopHookMatcher})。
+ * 本函数保留,是 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 declare function buildGoalStopHookPrompt(condition: string): string;
+/**
+ * `hooksWireCaps.ts` 的 `hooksForWire()` 尾部合流点(REF-CC-156 拆分的接口):治理门跑完之后,
+ * 调用方传入 `managedOnly`(allowManagedHooksOnly 是否命中),本函数原样返回要 concat 进
+ * `merged['Stop']` 的那一条 matcher,或 `null`(未登记 / 被 managedOnly 挡 / overlay 未 armed)。
+ * 非导出到包外(不进 `index.ts` 的公开面)——只是本文件与 `hooksWireCaps.ts` 之间的私有接口。
+ */
+export declare function goalStopHookMatcher(managedOnly: boolean): NonNullable<WireHooksConfig[string]>[number] | null;
+/** 测试钩:清 `/goal` 锁存(壳里靠进程边界隔离;包内同进程多组断言必须能清)。 */
+export declare function __resetGoalStopHookForTests(): void;

package/dist/goalStopHook.js

@@ -0,0 +1,258 @@
+/**
+ * REF-CC-156(midband-04,split,2026-08-02):拆自 `hooksWireCaps.ts`——那个文件里约 220 行(占其
+ * 387 行的 57%)是 `/goal` 命令专属的 Stop-hook 版本判档 + prompt 组装 + 模块级单实例状态,与
+ * `hooksWireCaps.ts` 其余部分(通用 settings-file hooks 投影 + 治理门)是两个不同的关注点,原文件
+ * 只在 `hooksForWire()` 尾部合流一次。纯搬迁,行为不变:所有导出名字原样保留(`hooksWireCaps.ts`
+ * 显式 re-export,外部 import 路径零改动),模块级状态(`wireSessionStopHookPrompt`/
+ * `wireSessionStopHookCcSemantics`)随代码一起搬到本文件,`docs/refactor/p1-scan/singleton-manifest.json`
+ * 的两条登记同批把 `file` 改成本文件坐标。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * 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 这一条(单值,不是通用会话钩子通道)——通用会话/插件钩子仍按 `hooksWireCaps.ts`
+ *    模块头所述不投影;
+ *  - 走 `hooksForWire()` 的**同一套治理门**(trust / disableAllHooks / allowManagedHooksOnly):
+ *    overlay 在门之后才合并,策略禁钩子时一并禁掉;
+ *  - `/goal clear` 传 null 收回。
+ */
+import { hostEnv } from './hostEnv.js';
+import { envFlagOff } from './envFlag.js';
+import { engineCapString } from './engineCapsCache.js';
+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;
+    const [gotMajor, gotMinor, gotPatch] = got;
+    const [minMajor, minMinor, minPatch] = min;
+    if (gotMajor !== minMajor)
+        return gotMajor > minMajor;
+    if (gotMinor !== minMinor)
+        return gotMinor > minMinor;
+    if (gotPatch !== minPatch)
+        return gotPatch > minPatch;
+    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` to an {@link envFlagOff} spelling(REF-CC-141 dup-02 单源)to disarm
+ * (an operator escape hatch, not a default).
+ */
+export function isGoalStopHookWireArmed(env = hostEnv()) {
+    return !envFlagOff(env[GOAL_STOP_HOOK_WIRE_ENV]);
+}
+/**
+ * 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} 与 `hooksForWire()` 的分道(见 {@link goalStopHookMatcher})。
+ * 本函数保留,是 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 }));
+}
+/**
+ * `hooksWireCaps.ts` 的 `hooksForWire()` 尾部合流点(REF-CC-156 拆分的接口):治理门跑完之后,
+ * 调用方传入 `managedOnly`(allowManagedHooksOnly 是否命中),本函数原样返回要 concat 进
+ * `merged['Stop']` 的那一条 matcher,或 `null`(未登记 / 被 managedOnly 挡 / overlay 未 armed)。
+ * 非导出到包外(不进 `index.ts` 的公开面)——只是本文件与 `hooksWireCaps.ts` 之间的私有接口。
+ */
+export function goalStopHookMatcher(managedOnly) {
+    if (wireSessionStopHookPrompt === null || managedOnly || !isGoalStopHookWireArmed())
+        return null;
+    // 🔴 这个双 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(唯一改动点,调用面不动)。
+    return {
+        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),
+            },
+        ],
+    };
+}
+/** 测试钩:清 `/goal` 锁存(壳里靠进程边界隔离;包内同进程多组断言必须能清)。 */
+export function __resetGoalStopHookForTests() {
+    wireSessionStopHookPrompt = null;
+    wireSessionStopHookCcSemantics = false;
+}

package/dist/headlessPermissionModeWire.d.ts

@@ -42,6 +42,16 @@ export type HeadlessPermissionResolution = {
  * argv 里的 `--permission-mode <v>` / `--permission-mode=<v>`(后者/后出现者赢,commander 同语义)与
  * `--dangerously-skip-permissions`(= bypassPermissions;`--permission-mode` 在场时让位)。
  * 返回 undefined = flag 车道未显式表态。
+ *
+ * REF-CC-143(dup-07)收编:`--permission-mode` 的取值改吃共用 lastFlagValue(argvFlagValue.ts,
+ * `onMissingValue:'latch-previous'`)——旧手写循环对「某一次 occurrence 缺值」的处置是跳过这一次、
+ * 锁存(latch)住之前已经取到的合法值,不是把整个旗塌缩成「从没写过」(`--permission-mode plan
+ * --permission-mode` 的旧行为是 `mode==='plan'`,不是 `undefined`)。共用叶的缺省策略
+ * (`'invalidate'`,sandboxWire/scenarioWire 用)会把这个情形塌缩成「有旗无值」,与本函数原有语义
+ * 不符,所以本调用点显式传 `'latch-previous'` 保住旧行为——这才是任务书说的「各调用方保持自己现有
+ * 对缺值的处置」(wave1 回炉修复,blocker:此前误用了共用叶的 invalidate 缺省,详见 commit 记账)。
+ * `--dangerously-skip-permissions` 的存在性判别不属于「取某旗最后值」这个不变量,单独一个小循环即
+ * 可,零重复。
  */
 export declare function permissionModeFromArgv(argv: readonly string[]): string | undefined;
 /**