@sema-agent/client-core 0.12.1 → 0.13.0

package/README.md

@@ -23,7 +23,7 @@ Renamed from **`@sema-agent/wire-cc-adapter`** (0.1.x, deprecated — see *Migra
 
 ## Scope
 
-**Version:** 0.12.1
+**Version:** 0.13.0
 
 - **Today** — the adapter seam, the whole `adapt()` pipeline (all 14 A-layer arms plus the
   B/D/E tool-card layers), the notification/caps/model families, the adapter kernel (stream driver
@@ -203,6 +203,13 @@ npm test   # = node scripts/run-client-core-all-gates.mjs — runs every suite b
 absent) does not short-circuit the ones after it, and the runner prints the three-part verdict
 itself (FAILED names + skipped names + arithmetic reconciliation). All-SKIP reports exit 3, never 0.
 
+The suite set is a **name-equality gate**, not a lower bound: the runner cross-checks what it finds
+on disk against `scripts/gates-manifest.json` in both directions. A registered suite that is missing
+is red (a guard was deleted or renamed); a suite on disk that is not registered is red (whoever
+added it skipped the registration). Adding a guard is therefore three actions in one commit — the
+`run-*-test.mjs` file, its row in `gates-manifest.json`, and its row in the table below (the
+public-surface guard checks that last one).
+
 | Suite | What it guards |
 |---|---|
 | `scripts/run-client-core-pure-test.mjs` | Consumer-view behaviour of every moved-in module; segment floors (B1–B8 + C) that only move up |
@@ -218,7 +225,13 @@ itself (FAILED names + skipped names + arithmetic reconciliation). All-SKIP repo
 | `scripts/run-fleet-view-keys-test.mjs` | The fleet projection views, **both directions**: `FleetTaskView`/`FleetWorkflowView` ⇄ their key lists (compile-pinned) ⇄ what a maximal/minimal row really projects, plus a wire-key coverage ledger (every `FleetTaskRow` key is either projected or carries a written reason why not) and a drift ledger against the shell's render contract. A one-directional assignability check is blind to optional keys — which is how `startedAt` was silently dropped |
 | `scripts/run-usage-verbatim-channel-test.mjs` | The two complementary usage disciplines (core 3.0.0 metering semantics): the CC `ModelUsage` mirror stays pure (five pinned keys, `totalInputTokens` has no seat), while the sema-owned channel forwards the engine `turn_end.usage` object **verbatim** (six keys, incl. `totalInputTokens`) via `last_turn_usage.engineUsage` / `handle.latestEngineUsage` — honest absence on pre-3.0.0 engines, no fabricated zeros |
 | `scripts/run-plan-review-decide-verify-test.mjs` | `decidePlanReview`'s post-decide honesty ([2315]/[2316], engine RB-471 family): a 2xx from the decide endpoint is **not** a terminal — the wire re-pulls the task status and words the outcome by the real shape (still-locked / legal new gate / genuinely left park / unverified), never claiming success it hasn't earned. Driven against a real fake-engine HTTP server through the shipped dist |
-| `scripts/run-public-surface-test.mjs` | The outward promises: the npm export surface baseline, the peer floor witness, and this README's claims |
+| `scripts/run-shell-gate-durable-allow-test.mjs` | #110: the durable approval leg for **shell** gates. The tool_end HOLD/REJECT predicate must cover Bash the same way park detection already does (otherwise the park poison frame `Operation aborted` hits the transcript, `endedCalls` swallows the real replayed result, and the user who pressed Yes watches a command that really ran be reported as aborted); a replayed, already-decided park must resume reading the stream instead of being reported as a failed turn; `lastEventId` must track numeric `seq` too. Mutation-proven: each of the three fixes reverted turns the gate red |
+| `scripts/run-public-surface-test.mjs` | The outward promises: the npm export surface baseline (an **exact set**, both directions — a new export that never entered the baseline is one nobody watched leave, and deleting it later would not be red), the peer floor witness, and this README's claims |
+| `scripts/run-client-core-message-branching-test.mjs` | §B8 (branching on error **text**) and §B10 (truthiness standing in for existence when the value can be `0`). AST + type-checker census over `src/`, a named ALLOW list carrying owner and expiry, a known-site floor, and two fixed corpora with a known verdict judged by the same classifier on every run |
+| `scripts/run-client-core-failloud-test.mjs` | §C1/§C2: an empty `catch` with no comment anywhere inside it, a pure-swallow `catch` nobody reasoned about, and `void <write>` that really returns a Promise with no `.catch`. The exemption instrument is a comment saying why *this* failure may die; the documented-swallow count is a ratchet that only goes down |
+| `scripts/run-client-core-typeshape-test.mjs` | Type discipline as a guard rather than a build side effect: the set of enabled strict knobs (one silently switched off is red), `tsc --noEmit`, and export-surface ratchets for inline anonymous shapes (≥3 members), `unknown` leaving the surface, and bare `unknown` returns — zero slack in either direction |
+| `scripts/run-client-core-singleton-test.mjs` | Module-level singletons ⇄ `docs/refactor/p1-scan/singleton-manifest.json`, **both directions**: an unregistered singleton is red (registering it forces someone to answer "what if this got duplicated"), a stale entry is red, and the `dupRisk: high` count only goes down |
+| `scripts/run-abortable-sleep-test.mjs` | The shared `abortableSleep(ms, signal)` leaf (consumed by `workflowClient.ts` and `agentSession/backgroundView.ts`'s poll backoff): normal timeout resolution, immediate wake-up on `abort` mid-wait, `clearTimeout` really firing on that path, and a post-resolve late abort staying a no-op |
 
 Each suite carries a floor that only moves up — a refactor that stops executing a group of
 assertions is a failure, not a quieter pass. Guards anchor on the **installed artefact's content**

package/dist/abortableSleep.d.ts

@@ -0,0 +1,29 @@
+/**
+ * abortableSleep.ts — REF-CC-147(域词表-17)+ REF-CC-149(域词表-21)裁定的落地面:P2 裁决
+ * (docs/refactor/P2-LEDGER-DRAFT.md「I族」)明确 D 族(8 处轮询/重试/看门狗循环)不收编成通用
+ * poller——循环体裁/终止量/节拍语义/失败后是否继续/abort 归属/谁持有状态六个维度互不兼容,
+ * 统一后正确性核心会消失在配置参数里。**只抽两个低层原语**,这是其中之一(另一个是
+ * unrefTimer/TimersPort 接线,见 host.ts):统一「怎么安全地睡一觉」,不统一「该睡多久/睡完
+ * 干什么」——退避曲线、终止预算这些策略维度仍各自留在调用点。
+ *
+ * 原实现 = agentSession/backgroundView.ts 的私有 `sleep()`(D 族六处循环里唯一做对「dispose
+ * 必须唤醒在飞的等待」这条不变量的一处,P1 lexicon 镜头点名「全仓最佳形」)。workflowClient.ts
+ * 的 `sleep()` 此前是裸 `new Promise(r => setTimeout(r, ms))`——不感知 abort:dispose() 只置位
+ * `disposed`/abort 掉 AbortController,但正在等待的这一轮 sleep 不会被唤醒,后果两条:
+ * ① consume() 循环在 dispose 后最多还会多跑一轮(sleep 到期才重新检查 `!disposed` 退出);
+ * ② 那个未被清理的 setTimeout 在 Node 上继续维持事件循环存活,把 headless `-p` 车道的进程退出
+ *    拖慢最多一个退避周期(当前三处退避常量的最大值,见 workflowClient.ts 的 *_BACKOFF_MS)。
+ */
+/**
+ * abort 感知的 sleep:到点正常 resolve;`signal` 在等待期间被 abort 时立即 resolve 并清掉
+ * 定时器——不留悬挂 timer 拖住宿主进程。调用方的循环在下一轮入口自会读到 `signal.aborted`
+ * 并退出,本函数只负责「别让等待本身变成一个新的悬挂句柄」,不负责终止判断。
+ *
+ * 入口先查 `signal.aborted`(wave1 回炉修:此前只在等待期间监听 'abort' 事件——若 signal
+ * 在**调用前**就已 aborted,事件早已派发完毕,`addEventListener('abort', …)` 上的 listener
+ * 永不触发,函数会退化成裸 `setTimeout` 照睡满整个 `ms` 并留一个未清的句柄,这正是本文件要
+ * 消灭的那个病,只是窗口从「sleep 期间 abort」挪到了「abort 后才进 sleep」。可达路径见
+ * workflowClient.ts 的 527→529→530:dispose 掐在一次 GET 在飞时,catch 会原样返回上一轮的
+ * `degraded=true`,回到 consume() 循环拿到的正是一个已 aborted 的 signal。
+ */
+export declare function abortableSleep(ms: number, signal: AbortSignal): Promise<void>;

package/dist/abortableSleep.js

@@ -0,0 +1,43 @@
+/**
+ * abortableSleep.ts — REF-CC-147(域词表-17)+ REF-CC-149(域词表-21)裁定的落地面:P2 裁决
+ * (docs/refactor/P2-LEDGER-DRAFT.md「I族」)明确 D 族(8 处轮询/重试/看门狗循环)不收编成通用
+ * poller——循环体裁/终止量/节拍语义/失败后是否继续/abort 归属/谁持有状态六个维度互不兼容,
+ * 统一后正确性核心会消失在配置参数里。**只抽两个低层原语**,这是其中之一(另一个是
+ * unrefTimer/TimersPort 接线,见 host.ts):统一「怎么安全地睡一觉」,不统一「该睡多久/睡完
+ * 干什么」——退避曲线、终止预算这些策略维度仍各自留在调用点。
+ *
+ * 原实现 = agentSession/backgroundView.ts 的私有 `sleep()`(D 族六处循环里唯一做对「dispose
+ * 必须唤醒在飞的等待」这条不变量的一处,P1 lexicon 镜头点名「全仓最佳形」)。workflowClient.ts
+ * 的 `sleep()` 此前是裸 `new Promise(r => setTimeout(r, ms))`——不感知 abort:dispose() 只置位
+ * `disposed`/abort 掉 AbortController,但正在等待的这一轮 sleep 不会被唤醒,后果两条:
+ * ① consume() 循环在 dispose 后最多还会多跑一轮(sleep 到期才重新检查 `!disposed` 退出);
+ * ② 那个未被清理的 setTimeout 在 Node 上继续维持事件循环存活,把 headless `-p` 车道的进程退出
+ *    拖慢最多一个退避周期(当前三处退避常量的最大值,见 workflowClient.ts 的 *_BACKOFF_MS)。
+ */
+/**
+ * abort 感知的 sleep:到点正常 resolve;`signal` 在等待期间被 abort 时立即 resolve 并清掉
+ * 定时器——不留悬挂 timer 拖住宿主进程。调用方的循环在下一轮入口自会读到 `signal.aborted`
+ * 并退出,本函数只负责「别让等待本身变成一个新的悬挂句柄」,不负责终止判断。
+ *
+ * 入口先查 `signal.aborted`(wave1 回炉修:此前只在等待期间监听 'abort' 事件——若 signal
+ * 在**调用前**就已 aborted,事件早已派发完毕,`addEventListener('abort', …)` 上的 listener
+ * 永不触发,函数会退化成裸 `setTimeout` 照睡满整个 `ms` 并留一个未清的句柄,这正是本文件要
+ * 消灭的那个病,只是窗口从「sleep 期间 abort」挪到了「abort 后才进 sleep」。可达路径见
+ * workflowClient.ts 的 527→529→530:dispose 掐在一次 GET 在飞时,catch 会原样返回上一轮的
+ * `degraded=true`,回到 consume() 循环拿到的正是一个已 aborted 的 signal。
+ */
+export function abortableSleep(ms, signal) {
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/dist/adapt/arms.d.ts

@@ -0,0 +1,58 @@
+/**
+ * adapt/arms.ts — 15 条帧臂的**注册表**(A 族拆分 REF-CC-SPLIT-01 的臂表化半场)。
+ *
+ * 拆分前这是驱动壳里一个 600 行的 `switch (m.type)`。改成注册表之后:
+ *  · 每条臂是一个具名 generator,`break` 变 `return`(语义逐条对位,`default:` 空臂 = 表里查不到);
+ *  · 臂拿不到驱动壳的局部变量 —— 它要什么状态,必须写在自己的 deps 类型里。
+ *
+ * 🔴 表用 `Map` 而不是普通对象(codex verdict 3):对象表被 `{type:'__proto__'}` /
+ *   `{type:'toString'}` 这种帧一命中就是原型污染(wire 帧是 UNTRUSTED 的开集)。
+ *
+ * 🔴 **两级 deps 是判别力本身,不是洁癖**(矩阵 §3.5):
+ *   `ProjectionArmFn` 只吃 `{ctx, idOf}` —— 于是「这几条臂碰不到任何适配器状态」这件事从
+ *   注释里的断言变成**编译期事实**。全量注入(一个大 deps 喂所有臂)会让封闭性声明失去判别力,
+ *   那正是 A 族 codex 复审里 5/11 那次翻车的根因。
+ *
+ * 🔴 **7 组由输入帧顺序耦合的臂对**(codex verdict 3 的清单;源码级无顺序耦合 —— 每帧单键分发 +
+ *   return,但**帧到达顺序**会改判别结果)。逐条点名在下面各臂的注释里,标记 `⟨帧序耦合 N/7⟩`:
+ *     1. assistant(开卡)→ task_progress(FIFO 猜父只认**已开**的卡)
+ *     2. assistant(Workflow 卡)→ task_progress(判据③ 认 seenWorkflowToolCallIds)
+ *     3. assistant(开卡)→ tool_end_result(没开过的卡,tool_end 直接丢)
+ *     4. task_progress(首 tick)→ tool_end_result(关卡 settle 只结**已发布**的行)
+ *     5. task_progress(首 tick,fire Start)→ task_notification(if-started 门)
+ *     6. retry_status(挂旗)→ 任一主 lane 内容帧(恢复即清)
+ *     7. turn_usage(endEmitted)→ result(`!endEmitted` 门决定 end 度量发不发第二遍)
+ */
+import type { AdapterContext, AdapterOutput } from '../seam.js';
+import { type Frame, type IdOf } from './ids.js';
+import type { AdapterInstanceLedger } from './instanceLedger.js';
+import type { PanelTaskLedger } from './panelTasks.js';
+import type { TextStream } from './textStream.js';
+import type { ToolCardLedger } from './toolCards.js';
+import type { TurnFlags } from './turnFlags.js';
+/** 纯投影臂的 deps —— **零适配器状态**(类型即证明)。 */
+export interface ProjectionArmDeps {
+    readonly ctx: AdapterContext;
+    readonly idOf: IdOf;
+}
+/** 有状态臂的 deps —— 矩阵 §3.5 收窄成的六件,不多给。 */
+export interface ArmDeps extends ProjectionArmDeps {
+    readonly text: TextStream;
+    readonly cards: ToolCardLedger;
+    readonly panel: PanelTaskLedger;
+    readonly flags: TurnFlags;
+    readonly inst: AdapterInstanceLedger;
+}
+/**
+ * 只碰 `{ctx, idOf}` 的臂。`ProjectionArmFn` 可赋给 `ArmFn`(入参逆变),所以两级可以放同一张表,
+ * 而**声明成哪一级**就是那条臂的封闭性声明 —— 想碰状态就得改签名,改签名就在 diff 里显形。
+ * ⚠️ 判别力边界说清楚:它证明的是「碰不到 M1/M2/M3/M6/inst 五个**适配器状态**模块」,
+ * 不是「零副作用」—— `workflow_complete` 就是个例子,它写 notifications.ts 的 **module 台账**。
+ */
+export type ProjectionArmFn = (m: Frame, deps: ProjectionArmDeps) => Generator<AdapterOutput>;
+export type ArmFn = (m: Frame, deps: ArmDeps) => Generator<AdapterOutput>;
+/**
+ * 帧类型 → 臂。**Map 而不是对象字面量**:`{type:'__proto__'}` 这种 UNTRUSTED 帧命中对象表
+ * 就是原型污染(codex verdict 3)。表里查不到 = 拆分前 `switch` 的 `default:` 空臂,行为同。
+ */
+export declare const ARMS: ReadonlyMap<string, ArmFn>;