@sema-agent/client-core 0.12.2 → 0.14.0

package/dist/adapt/ids.js

@@ -0,0 +1,34 @@
+import { deriveTranscriptId } from '../seam.js';
+/** 主车道证明——本批实现的臂全在 leader lane(子代/workflow lane 的 tick 面留 #52b)。 */
+export const MAIN = { lane: 'main' };
+export const chrome = (event) => ({ plane: 'chrome', event });
+/**
+ * 🔴 入参从裸 `unknown` 收窄成 `Frame`(拆分同批的真收窄,不是搬运):调用点全是「按 CC 词汇
+ * 现拼的对象字面量」或「原样透传的 wire 帧」,两者都是 `Record<string, unknown>` ——
+ * 裸 `unknown` 把窄化义务外包给了每一个调用点,而这里本来就知道自己收的是什么形。
+ * 到 `SDKMessage` 的那一步仍是 cast:CC 词汇的字面形与 SDK 类型有已登记的分歧(DIVERGENCE-2/9),
+ * 这条 cast 是**有意**的边界,不是偷懒。
+ */
+export const transcript = (message) => ({
+    plane: 'transcript',
+    message: message,
+});
+/**
+ * [1653]:稳定键优先序 = 帧 id > seq > toolCallId,全缺才 ctx.uuid()。现役 wire 的稳定键落在
+ * `uuid` 字段(§E2 core 铸的 eventId / stamp 铸的帧 id),故映到 `id` 位喂进去(见 SEAM-GAP-1)。
+ * `suffix` = 同一帧派生多条消息时的去撞位(如 tool_use 卡 + 同帧的 reject 结果)。
+ */
+export function makeIdOf(ctx) {
+    return (frame, suffix) => {
+        const base = typeof frame.id === 'string' && frame.id.length > 0
+            ? frame.id
+            : typeof frame.uuid === 'string' && frame.uuid.length > 0
+                ? frame.uuid
+                : undefined;
+        return deriveTranscriptId({
+            ...(base !== undefined ? { id: suffix !== undefined ? `${base}#${suffix}` : base } : {}),
+            ...(typeof frame.seq === 'number' ? { seq: frame.seq } : {}),
+            ...(typeof frame.toolCallId === 'string' ? { toolCallId: frame.toolCallId } : {}),
+        }, ctx);
+    };
+}

package/dist/adapt/instanceLedger.d.ts

@@ -0,0 +1,36 @@
+/**
+ * adapt/instanceLedger.ts — **适配器实例级台账**(A 族拆分 REF-CC-FIX-05;矩阵 §1.5)。
+ *
+ * 三个 Set 的持有者。它们与 turn 级状态的区别是**跨 turn 存活**:
+ *  · `renderedNotifications` —— 通知去重键(#63 的 export/import 往返面就是它);
+ *  · `seenWorkflowToolCallIds` —— W1 三级判据③ 的素材(assistant 臂写、task_progress 臂读,
+ *    覆盖 uuid 形子代 id 与**跨 turn 迟到 tick**,所以必须跨 turn 活着);
+ *  · `firedSubagentStartHookTaskIds` —— SubagentStart 一生只许一次(frame-lane-matrix #4),
+ *    同时是 task_notification 臂发 stop 的门。
+ *
+ * 🔴 FIX-05 就是本文件存在的理由:拆分前这三个 Set 挂在类上,`adapt()` 里既有 `self.` 又有
+ *   `this.` **两条访问路径**(generator 表达式的 this 不是适配器,所以当时固定了一个 `const self`)。
+ *   收成一个显式入参对象之后:① `self` 别名与它那条 eslint-disable 一起消失;② 三个 Set 的
+ *   每一个读写点都必须经 `inst.` —— 「同一台账两条路径」这件事在结构上不再可能。
+ *
+ * 🔴 DIVERGENCE-6 的现势(别把它读成「本包所有台账都是实例级」):只有本文件这三件是实例级
+ *   (= 一个 session 一份)。`notifiedRuns` / `cardEnqueuedRuns` 是 **module 台账**(notifications.ts),
+ *   因为它们的配对半场(队列 port / idle watcher / outstanding 药丸)在那儿 —— 放实例 =
+ *   前提不共享 = 双卡/零显示/模型二收(0.6.0 真缺口,[1857])。
+ */
+export interface AdapterInstanceLedger {
+    /** 通知去重键:已渲染过? */
+    hasRenderedNotification(key: string): boolean;
+    /** 通知去重键:记一条(**必须在对应 yield 之前**落,见矩阵 §2.1④ 的 1377 行判定)。 */
+    addRenderedNotification(key: string): void;
+    /** 台账导出/回植用的快照与批量吃入(返回真正新吃进去的条数)。 */
+    listRenderedNotifications(): string[];
+    takeRenderedNotifications(keys: Iterable<unknown>): number;
+    /** W1 判据③:这个 tool_use id 是本会话见过的 Workflow 工具卡? */
+    isWorkflowCard(toolUseId: string): boolean;
+    markWorkflowCard(toolUseId: string): void;
+    /** SubagentStart 一生一次的门(fire 前判、fire 时记,两步都在 yield 之前)。 */
+    hasFiredSubagentStart(taskId: string): boolean;
+    markFiredSubagentStart(taskId: string): void;
+}
+export declare function createAdapterInstanceLedger(): AdapterInstanceLedger;

package/dist/adapt/instanceLedger.js

@@ -0,0 +1,50 @@
+/**
+ * adapt/instanceLedger.ts — **适配器实例级台账**(A 族拆分 REF-CC-FIX-05;矩阵 §1.5)。
+ *
+ * 三个 Set 的持有者。它们与 turn 级状态的区别是**跨 turn 存活**:
+ *  · `renderedNotifications` —— 通知去重键(#63 的 export/import 往返面就是它);
+ *  · `seenWorkflowToolCallIds` —— W1 三级判据③ 的素材(assistant 臂写、task_progress 臂读,
+ *    覆盖 uuid 形子代 id 与**跨 turn 迟到 tick**,所以必须跨 turn 活着);
+ *  · `firedSubagentStartHookTaskIds` —— SubagentStart 一生只许一次(frame-lane-matrix #4),
+ *    同时是 task_notification 臂发 stop 的门。
+ *
+ * 🔴 FIX-05 就是本文件存在的理由:拆分前这三个 Set 挂在类上,`adapt()` 里既有 `self.` 又有
+ *   `this.` **两条访问路径**(generator 表达式的 this 不是适配器,所以当时固定了一个 `const self`)。
+ *   收成一个显式入参对象之后:① `self` 别名与它那条 eslint-disable 一起消失;② 三个 Set 的
+ *   每一个读写点都必须经 `inst.` —— 「同一台账两条路径」这件事在结构上不再可能。
+ *
+ * 🔴 DIVERGENCE-6 的现势(别把它读成「本包所有台账都是实例级」):只有本文件这三件是实例级
+ *   (= 一个 session 一份)。`notifiedRuns` / `cardEnqueuedRuns` 是 **module 台账**(notifications.ts),
+ *   因为它们的配对半场(队列 port / idle watcher / outstanding 药丸)在那儿 —— 放实例 =
+ *   前提不共享 = 双卡/零显示/模型二收(0.6.0 真缺口,[1857])。
+ */
+export function createAdapterInstanceLedger() {
+    const renderedNotifications = new Set();
+    const seenWorkflowToolCallIds = new Set();
+    const firedSubagentStartHookTaskIds = new Set();
+    return {
+        hasRenderedNotification: (key) => renderedNotifications.has(key),
+        addRenderedNotification: (key) => {
+            renderedNotifications.add(key);
+        },
+        listRenderedNotifications: () => [...renderedNotifications],
+        takeRenderedNotifications: (keys) => {
+            let n = 0;
+            for (const k of keys) {
+                if (typeof k === 'string' && k.length > 0 && !renderedNotifications.has(k)) {
+                    renderedNotifications.add(k);
+                    n++;
+                }
+            }
+            return n;
+        },
+        isWorkflowCard: (toolUseId) => seenWorkflowToolCallIds.has(toolUseId),
+        markWorkflowCard: (toolUseId) => {
+            seenWorkflowToolCallIds.add(toolUseId);
+        },
+        hasFiredSubagentStart: (taskId) => firedSubagentStartHookTaskIds.has(taskId),
+        markFiredSubagentStart: (taskId) => {
+            firedSubagentStartHookTaskIds.add(taskId);
+        },
+    };
+}

package/dist/adapt/panelTasks.d.ts

@@ -0,0 +1,59 @@
+/**
+ * adapt/panelTasks.ts — M3 **面板行台账**(A 族拆分 REF-CC-SPLIT-04;矩阵 §1.3 六行状态)。
+ *
+ * 收编 `taskCardBinding` / `boundToolCalls` / `livePanelTasks` / `endedPanelTasks` /
+ * `liveBoundPanelTasks` / `subagentTypeById` 六行状态 + C5 laneOfTask / C6 bindTaskCard /
+ * C7 unboundSubagentCandidates / C8 fireSubagentStart / C9 settlePanelTasks 五个闭包。
+ *
+ * 引擎侧子代的 tick 只带 rollup 数字({toolUses,totalTokens}) = CC `AgentProgress` 同形,
+ * 所以忠实的 CC-187 面是 footer 的 CoordinatorTaskPanel(CC 自己对进程外 agent 的先例:
+ * 面板行 + task-notification,从不合成 inline 消息轨)。本模块把「tick → 哪张委派卡」的归属、
+ * 行的活性(live/inert/unbound)、以及三处 sweep 全部管起来。
+ *
+ * 🔴 拆分定案两条(矩阵 §3.2 #4/#6):
+ *   ① `endedPanelTasks` 拆分前被 `settlePanelTasks` **和** task_notification 臂两处直写。
+ *      现在通知臂那半场收成 `settleFromNotification()`(clearResident + panel end +
+ *      endedPanelTasks 判重 + if-started stop 整段),通知臂只调一次 ⇒ 跨臂直写消失。
+ *   ② `firedSubagentStartHookTaskIds` 的读者(通知臂)随之进了本模块内部 —— 通知臂**不再直读**
+ *      实例台账,那条跨模块读同批消失。
+ *
+ * 🔴 module 台账 `engineAgentPanelStore` 的两个写口(mark/clearEnginePanelTaskResident)拆分前有
+ *   A4/A9 **双所有者**。按记忆 `paired-mechanisms-must-share-premise` 的「整臂让位」:两处写口
+ *   现在**在 adapt 域内只在本文件**(`noteResidency()` 与 `settleFromNotification()`),不许 A 层
+ *   两个模块各写各的。
+ *   ⚠️ ADAPT-F4 判据纠偏(2026-08-02):原文写的是「只在本文件」,而 `src/notifications.ts:915`
+ *   的 bg 合成半场也调 `clearEnginePanelTaskResident`(它自陈是「真终态唯二来源」之一,是设计内的
+ *   另一条腿、不是被劈开的臂)。照字面 grep 验这条判据的人当场得到证伪,只能二选一:误判成回归去
+ *   删 notifications 那半场,或判定这条钉不可信而整条丢掉 —— 两条都是坏结局。判据的作用域必须写准。
+ *
+ * 🔴 时序留钉(矩阵 §2.1②):`start()` 里 `markFiredSubagentStart` 必须在 `yield` **之前** ——
+ *   yield* 展开后判重+记号与交付在**同一次** `.next()` 里,「已标记」⟺「已交付」原子成立;
+ *   改成 add-after-yield ⇒ 消费者收到 start 后早退就没记上 ⇒ 下一 turn 重 fire,直接违反「一生一次」。
+ */
+import type { AdapterContext, AdapterOutput, LaneProof } from '../seam.js';
+import type { AdapterInstanceLedger } from './instanceLedger.js';
+import type { OpenCardView } from './toolCards.js';
+export interface PanelTaskLedger {
+    /** T32 行绑定(typed 双键在场恒赢;缺席时 FIFO 猜父)。返回绑到的卡 id。 */
+    bind(taskId: string, parentToolCallId?: string): string | undefined;
+    /** 未绑的 subagent 形开卡张数(>1 ⇒ 含糊,上层保持 unbound)。 */
+    unboundCandidates(): number;
+    /** 行的车道证明:绑到卡的 = subagent lane(带父卡 id),未绑的 = 主 lane。 */
+    laneOf(taskId: string): LaneProof;
+    /** 这条行已经绑过卡了吗(含糊回落的前置判位;别拿 `laneOf(...) === MAIN` 代替 —— 那是
+     *  按引用相等在推断,判据锚在会决定结果的量上才对)。 */
+    isBound(taskId: string): boolean;
+    /** 本 turn 发布过面板行了吗(首 tick 判别 = 子代在壳侧可观测的起点)。 */
+    isLive(taskId: string): boolean;
+    /** 登记「本 turn 发布过面板行」。 */
+    markLive(taskId: string): void;
+    /** #6 常驻台账:live-bound ⇒ 清常驻;inert/unbound ⇒ 记常驻(module store 的**唯一**写口之一)。 */
+    noteResidency(taskId: string): void;
+    /** SubagentStart(类型恒记,fire 一生一次)。 */
+    start(taskId: string, agentType: string): Generator<AdapterOutput>;
+    /** 关卡 settle(cardId)或 turn 末/abort 防御 sweep(cardId===null)。 */
+    settle(cardId: string | null, isError: boolean, report?: string): Generator<AdapterOutput>;
+    /** #6 通知-settle 边(推送半场):真终态在此落行,session 常驻行不再被 turn sweep 假结。 */
+    settleFromNotification(taskId: string, isError: boolean): Generator<AdapterOutput>;
+}
+export declare function createPanelTaskLedger(ctx: AdapterContext, cards: OpenCardView, inst: AdapterInstanceLedger): PanelTaskLedger;

package/dist/adapt/panelTasks.js

@@ -0,0 +1,193 @@
+import { clearEnginePanelTaskResident, markEnginePanelTaskResident } from '../engineAgentPanelStore.js';
+import { chrome, MAIN } from './ids.js';
+import { SUBAGENT_TOOL_NAMES } from './wireShapes.js';
+export function createPanelTaskLedger(ctx, cards, inst) {
+    /** taskId → 绑定的 open tool_use id。 */
+    const taskCardBinding = new Map();
+    /** 已被某 taskId 认领的 tool_use id(一张卡只认一个子代)。 */
+    const boundToolCalls = new Set();
+    /** 本 turn 发布过面板行的全部 taskId(绑定与否都算)。 */
+    const livePanelTasks = new Set();
+    /** 已落终态的行(settle 幂等)。 */
+    const endedPanelTasks = new Set();
+    /**
+     * #6 —— 绑定时那张卡**正开着**的 taskId(= "live" 绑定)。只有这些行属本 turn 生命周期、
+     * 可被 turn 末防御 sweep 结掉。inert(显式父指向已关/没见过的卡 —— 跨 turn bg 子代的典型形)
+     * 与 unbound 行是 **session 常驻**:终态只认 task_notification / bg_notification。
+     */
+    const liveBoundPanelTasks = new Set();
+    /** taskId → 子代类型(Stop hook 查它;cli 同为 turn 局部)。 */
+    const subagentTypeById = new Map();
+    const laneOf = (taskId) => {
+        const card = taskCardBinding.get(taskId);
+        return card !== undefined ? { lane: 'subagent', parentToolCallId: card } : MAIN;
+    };
+    return {
+        laneOf,
+        isBound: (taskId) => taskCardBinding.has(taskId),
+        /**
+         * T32 行绑定。**typed 双键在场恒赢**(B6 定案):wire 点名了 `parentToolCallId` 时,下面的
+         * FIFO 臂**一次都不会被考虑** —— 连「点名的卡不合格」那一支也是直接返回 unbound,而不是
+         * 退回去猜。判据锚在这里:显式支的两条出口(绑定 / 拒绝)都不落进 else。
+         */
+        bind(taskId, parentToolCallId) {
+            const existing = taskCardBinding.get(taskId);
+            if (existing !== undefined)
+                return existing;
+            let target;
+            if (parentToolCallId !== undefined) {
+                // P1② 精确绑定 —— wire 点名了委派卡。信但不无条件信([1617]①,frame-lane-matrix #1):
+                // 被点名的卡**开着**且**不是** subagent 形工具(Task/Agent/Fork)时拒绝绑定 —— 否则
+                // workflow/Bash 卡一关就会把这条行 settle 掉、还会收走它的 inline stats(错归因)。
+                // 行保持 unbound(taskId 键的 rollup 仍是真的)。已关/没见过的 id 仍**惰性绑定**(inert):
+                // 终态由通知落,严格优于错绑另一张开着的卡。
+                const named = cards.peek(parentToolCallId);
+                if (named !== undefined && !SUBAGENT_TOOL_NAMES.has(named.name))
+                    return undefined;
+                target = parentToolCallId;
+            }
+            else {
+                // ── old-engine fallback(FIFO 猜父)—— B6 P1-2 归属定案:**不删** ────────────────────
+                // 🔴 判据先摆正:这条臂不是「P1-2 之前的临时权宜」,它是 **tolerate-absent 的保护臂**。
+                //   决定后果方向的量 = 「这条子代行有没有归属」:
+                //     · 回落在 ⇒ 老引擎(不发 parentToolCallId)上行仍绑到唯一那张开着的委派卡 ⇒ 行有归属、
+                //       inline stats 有去处、关卡时被 settle;
+                //     · 回落删掉 ⇒ 老引擎上行恒 unbound ⇒ 转录里那条群组行永远不长统计、卡关了也不结,
+                //       用户看到一条转圈到 turn 末的行。
+                //   ⇒ **保护型缺席 = 漏保护**,与 `parked → awaiting approval` 同判(不删)。
+                //   猜错的风险已被两道门收窄:只考虑**未绑**且**subagent 形**的卡;≥2 张候选时上层
+                //   直接判含糊、保持 unbound(见 task_progress 臂的 unboundCandidates() > 1)。
+                // 退役条件(登记在 compensations.ts T32):P1-2 到货 **且** 达标线 ≥ server 1.290 —— 即
+                //   「不再支持不发 typed 双键的引擎」那一天,才是删它的日子;只要还能连老引擎就得留着。
+                // 覆盖:diff 门 14 条 task_progress 帧里有 6 条不带 parentToolCallId(其中 2 条走 workflow
+                //   lane 门、不到这里),真正压这条回落臂的是 4 条(FIFO 命中 / 含糊拒绝 / settle / 跨 turn)。
+                // 🔴 依赖 `cards.entries()` 的**开卡顺序**(Map 插入序 = FIFO 语义本身),换成任何
+                //   无序容器都会静默改判别结果。
+                for (const [id, p] of cards.entries()) {
+                    if (!boundToolCalls.has(id) && SUBAGENT_TOOL_NAMES.has(p.name)) {
+                        target = id;
+                        break;
+                    }
+                }
+            }
+            if (target === undefined)
+                return undefined;
+            taskCardBinding.set(taskId, target);
+            boundToolCalls.add(target);
+            // #6 live vs inert:只有绑到**此刻开着**的卡才把行系进本 turn 的生命周期
+            // (FIFO 目标恒开着;显式目标可能已关 = inert)。
+            if (cards.has(target))
+                liveBoundPanelTasks.add(taskId);
+            // cli 的 `SEMA_BIND_PROBE` 文件探针 → 注入口(载荷逐字同形,见 ADAPTER_DIVERGENCES-5)。
+            ctx.probe?.('bind', `bind ${taskId} -> ${target} via=${parentToolCallId !== undefined ? 'explicit' : 'fifo'}`);
+            return target;
+        },
+        /** 对抗复审修(w0zwpa251 #1):≥2 张未绑的 subagent 形卡开着且 wire 没点名 ⇒ 任何猜都是错归因。 */
+        unboundCandidates() {
+            let n = 0;
+            for (const [id, p] of cards.entries()) {
+                if (!boundToolCalls.has(id) && SUBAGENT_TOOL_NAMES.has(p.name))
+                    n++;
+            }
+            return n;
+        },
+        isLive: (taskId) => livePanelTasks.has(taskId),
+        markLive: (taskId) => {
+            livePanelTasks.add(taskId);
+        },
+        // #6 session 常驻台账:live-bound(卡本 turn 开着)= 本 turn 生命周期,turn 末可 sweep;
+        // inert/unbound(跨 turn bg 子代形)= 常驻,两处 sweep 都放行,终态只认通知帧。
+        noteResidency: (taskId) => {
+            if (liveBoundPanelTasks.has(taskId))
+                clearEnginePanelTaskResident(taskId);
+            else
+                markEnginePanelTaskResident(taskId);
+        },
+        /** SubagentStart(cli fireSubagentStartHook 的臂化):类型恒记,fire 一生一次。 */
+        *start(taskId, agentType) {
+            subagentTypeById.set(taskId, agentType); // Stop 的类型查找恒记(fire 与否无关)
+            // 🔴 判重 + 记号都在**唯一那条 yield 之前**(矩阵 §2.1②:零残余窗,别挪)。
+            if (inst.hasFiredSubagentStart(taskId))
+                return;
+            inst.markFiredSubagentStart(taskId);
+            ctx.probe?.('hook', `start ${taskId} type=${agentType}`);
+            yield chrome({ kind: 'subagent_lifecycle', laneProof: laneOf(taskId), phase: 'start', taskId, agentType });
+        },
+        /**
+         * 结掉一张关闭中的卡所绑的面板行(`cardId`),或 turn 末/abort 结掉**本 turn 活绑**的全部行
+         * (`cardId===null` 的防御 sweep —— 子代从不发终态 tick)。
+         * 拍1 查看态:显式关卡臂携委派卡的 output(= 子代最终报告)到 end 事件上;sweep 无报告。
+         */
+        *settle(cardId, isError, report) {
+            // inline 群组行孪生(clay dogfood 2026-07-03):冻结该卡的 tick 终值,免得"N agents finished"
+            // 行把真实工具数/token 重置回 0。null-cardId 的 sweep 结掉每一条活着的 inline 条目。
+            if (cardId !== null) {
+                yield chrome({ kind: 'inline_task_stats', laneProof: { lane: 'subagent', parentToolCallId: cardId }, op: 'settle', cardId, isError });
+            }
+            else {
+                yield chrome({ kind: 'inline_task_stats', laneProof: MAIN, op: 'settle_all' });
+            }
+            for (const taskId of livePanelTasks) {
+                if (cardId !== null && taskCardBinding.get(taskId) !== cardId)
+                    continue;
+                // #6 —— 防御 sweep 只结**本 turn 活绑**的行(流被截断的形)。session 常驻行
+                // (inert 绑定 / unbound = 跨 turn bg 子代)绝不在这里冻成假 completed:它的终态真相
+                // 由 task_notification / bg_notification 落(通知-settle 边)。
+                if (cardId === null && !liveBoundPanelTasks.has(taskId))
+                    continue;
+                if (endedPanelTasks.has(taskId))
+                    continue;
+                endedPanelTasks.add(taskId);
+                const lane = laneOf(taskId);
+                const agentType = subagentTypeById.get(taskId);
+                yield chrome({
+                    kind: 'subagent_lifecycle',
+                    laneProof: lane,
+                    phase: 'stop',
+                    taskId,
+                    ...(agentType !== undefined ? { agentType } : {}),
+                });
+                yield chrome({
+                    kind: 'panel_task',
+                    laneProof: lane,
+                    event: {
+                        kind: 'end',
+                        taskId,
+                        isError,
+                        ...(cardId !== null && report !== undefined ? { report } : {}),
+                    },
+                });
+            }
+        },
+        /**
+         * 通知臂(task_notification)那半场,整段收进来 —— 拆分前它在臂里直写 `endedPanelTasks`
+         * 与直读 `firedSubagentStartHookTaskIds`,是矩阵点名的两条跨模块面。
+         * 产出与判重次序**逐字保持**拆分前的形:先清常驻 → 发 end 行 → 再判重 → 再 if-started stop。
+         */
+        *settleFromNotification(taskId, isError) {
+            // #6 通知-settle 边(推送半场):session 常驻的 bg 子代行不再被 turn sweep 假结,
+            // 真终态在此落行(failed/killed ⇒ isError 真归因)。
+            clearEnginePanelTaskResident(taskId);
+            yield chrome({
+                kind: 'panel_task',
+                laneProof: MAIN,
+                event: { kind: 'end', taskId, isError },
+            });
+            if (!endedPanelTasks.has(taskId)) {
+                endedPanelTasks.add(taskId);
+                // SubagentStop 只对**真 fire 过 Start** 的子代(workflow runId / 外来 id 不配对乱 fire)。
+                // cli 同门 `firedSubagentStartHookTaskIds.has(taskId)` —— B4 前本臂无条件发 stop,
+                // 宿主若照 guard 注释自建台账才不会乱 fire;台账在库里就该库来判。
+                if (inst.hasFiredSubagentStart(taskId)) {
+                    yield chrome({
+                        kind: 'subagent_lifecycle',
+                        laneProof: MAIN,
+                        phase: 'stop',
+                        taskId,
+                        guard: 'if-started',
+                    });
+                }
+            }
+        },
+    };
+}

package/dist/adapt/textStream.d.ts

@@ -0,0 +1,63 @@
+/**
+ * adapt/textStream.ts — M1 **流合并器**(A 族拆分 REF-CC-SPLIT-02;矩阵 §1.1 十二行状态)。
+ *
+ * 收编 ADAPT-RW-MATRIX §1.1 的 12 个变量(answer / answerSegment / thinking /
+ * emittedAssistantText / textPending / thinkingPending / textBlockOpen / thinkingBlockOpen /
+ * lastFlushAt / flushEveryMs / segmentAnchor / thinkingAnchor)+ 三个闭包(C12 takeThinking /
+ * C13 takeAnswerSegment / C14 drainLive)+ 两处原本长在驱动壳里的判据:
+ *   · `hasPendingContent()` = D3 IDLE-FLUSH 竞速的四项 or(矩阵说的「接口化即封闭」);
+ *   · `maybeFlushOnBeat(now)` = D5 COALESCER 节拍尾。
+ * 收进来之后这 12 行里**只剩两行**还跨模块(矩阵 §1.8):`answer` 与 `emittedAssistantText` ——
+ * 它们由 `appendAnswer()` / `markEmittedText()` 两个具名动作暴露给 assistant / result 两臂,
+ * 而不是把裸变量交出去(裸 `= true` 在拆分后没有任何人能追得住)。
+ *
+ * 🔴 不变量(段序铁律,本包最高不变量之一):**活体增量 → 思考 committed → 文本段 committed**。
+ * 三个 take/drain 的**相对次序**由调用点决定,本模块只保证每一个自身的内部序;拆分后
+ * 收口三形(result 臂 / abort 尾 / T60 尾)的次序差异登记在 ADAPT-RW-MATRIX §2.4,别归一。
+ *
+ * 🔴 时序坑(矩阵 §2.3 ⑤,拆分专属):`drainLive()` 里两处 `pending = ''` 在 `yield` **之后**,
+ * 载荷是在 yield 之前**按值捕获**的,所以逻辑正确。**机械地把清空前移会读到已清空的串** ——
+ * 谁想「统一成 reset-before-yield」,先读这一条。
+ */
+import type { AdapterContext, AdapterOutput } from '../seam.js';
+import { type Frame, type IdOf } from './ids.js';
+/** M1 对外的六个动作 + 两个读位(矩阵 §3.2 的 #2/#3 两条跨模块接口就是最后那三件)。 */
+export interface TextStream {
+    /** A5 `text_delta` 半场:MOD-1 思考→回答边界(思考在场就先 committed 上屏)+ 段锚 + 三缓冲累加。 */
+    feedText(delta: string, frame: Frame): Generator<AdapterOutput>;
+    /** A5 `thinking_delta` 半场:首条推理增量点亮活动行(P2d elapsed 锚)。 */
+    feedThinking(delta: string, frame: Frame): Generator<AdapterOutput>;
+    /** 合并后的活体增量下泄(思考先于文本 = 持久臂序)。 */
+    drainLive(): Generator<AdapterOutput>;
+    /** 提交累积的思考块。 */
+    takeThinking(): Generator<AdapterOutput>;
+    /** 提交累积的文本段(#27 段序铁律)。 */
+    takeAnswerSegment(): Generator<AdapterOutput>;
+    /** D3 IDLE-FLUSH 竞速判据:四个缓冲有任何一个非空。 */
+    hasPendingContent(): boolean;
+    /** D5 攒批节拍:一个间隔至多一次 flush(判据与 `lastFlushAt` 一起收在本模块内)。 */
+    maybeFlushOnBeat(nowMs: number): Generator<AdapterOutput>;
+    /**
+     * A1 durable text 臂:把整块 text 计进 `answer`(它不走增量通道)。
+     *
+     * ── ADAPT-F8 留/删裁定(2026-08-02;矩阵 §338 点名要的那条裁定,此前仓内零落痕)──────────
+     * 事实:`answer` 的**唯一读者**是驱动壳 D8 收口的 `ctx.log?.('debug', … answerLen=…)`;拆分把
+     * 旧本一行 `void answer`(自陈「保留供调试/后续批」)换成了 `appendAnswer` + `answerLength`
+     * 两个模块级出口 —— 净效果与矩阵意图相反(包袱没裁,反而升了格)。
+     * **裁定 = 留**,理由与代价一起记明:
+     *  · 留:D8 那行是「这个 turn 到底产没产出文本」的**唯一**分诊锚,而它恰好是本域最常翻车的
+     *    一类现象(终答兜底/段序/markEmittedText 三处任一漏配都在这里现形)。删掉等于把一条真在
+     *    用的诊断腿换成「下次再从头加仪器」。它不是「不报错的妥协」,是有读者的可观测面。
+     *  · 代价(认领,不粉饰):两个出口是 turn 级状态的模块 API 面,`appendAnswer` 的调用点漂了
+     *    没有门会说话(答案长度只进 debug 行,没人对账)。所以它**不许再长第三个读者** —— 想读
+     *    正文的人去读段缓冲,别把这个累加器当答案来源。
+     */
+    appendAnswer(text: string): void;
+    /** 「本 turn 已经产过 assistant 文本」的具名写口(A1 durable / A7 终答兜底两处)。 */
+    markEmittedText(): void;
+    /** A7 终答兜底的门 + D8 收口日志读位。 */
+    readonly emittedAssistantText: boolean;
+    /** D8 收口日志读位(`answer` 本体不出模块)。 */
+    readonly answerLength: number;
+}
+export declare function createTextStream(ctx: AdapterContext, idOf: IdOf): TextStream;

package/dist/adapt/textStream.js

@@ -0,0 +1,141 @@
+import { chrome, MAIN, transcript } from './ids.js';
+import { estimateCjkTokens, FLUSH_INTERVAL_MS } from './wireShapes.js';
+export function createTextStream(ctx, idOf) {
+    // ── turn 级状态(cli generator 局部变量的等价;矩阵 §1.1 逐行对位)──────────────────────────
+    let answer = '';
+    let answerSegment = '';
+    let thinking = '';
+    let emittedAssistantText = false;
+    let textPending = '';
+    let thinkingPending = '';
+    let textBlockOpen = false;
+    let thinkingBlockOpen = false;
+    let lastFlushAt = 0;
+    /** T29 攒批节拍:宿主策略优先(桌面/web 可传 16ms 对齐 CC 桌面端),缺席=207 CLI 口径 100ms。 */
+    const flushEveryMs = typeof ctx.coalesceIntervalMs === 'number' && ctx.coalesceIntervalMs >= 0
+        ? ctx.coalesceIntervalMs
+        : FLUSH_INTERVAL_MS;
+    /** committed 消息的 id 锚 —— 该段/该思考块的**第一帧**(重放确定性:同流同 id)。 */
+    let segmentAnchor = null;
+    let thinkingAnchor = null;
+    /** 提交累积的思考块(cli takeThinking:committed 形 + 关活体块 + 收活动行)。 */
+    function* takeThinking() {
+        if (thinking.length === 0)
+            return;
+        const anchor = thinkingAnchor ?? {};
+        const msg = {
+            type: 'assistant',
+            message: { role: 'assistant', content: [{ type: 'thinking', thinking }] },
+            uuid: idOf(anchor, 'thinking'),
+            session_id: ctx.sessionId,
+            parent_tool_use_id: null,
+        };
+        thinking = '';
+        thinkingAnchor = null;
+        thinkingBlockOpen = false;
+        // P2d:活体 "∴ Thinking…" 行在 committed 块落地的**同一刻**收掉(先收行再上消息,cli 同序)
+        yield chrome({ kind: 'thinking_activity', laneProof: MAIN, active: false });
+        yield transcript(msg);
+    }
+    /** 提交累积的文本段(cli takeAnswerSegment:#27 段序铁律——工具卡前/turn 末各 flush 一次)。 */
+    function* takeAnswerSegment() {
+        if (answerSegment.length === 0)
+            return;
+        const anchor = segmentAnchor ?? {};
+        const msg = {
+            type: 'assistant',
+            message: { role: 'assistant', content: [{ type: 'text', text: answerSegment }] },
+            uuid: idOf(anchor, 'text'),
+            session_id: ctx.sessionId,
+            parent_tool_use_id: null,
+        };
+        answerSegment = '';
+        segmentAnchor = null;
+        emittedAssistantText = true;
+        textBlockOpen = false;
+        yield transcript(msg);
+    }
+    /** 合并后的活体增量下泄(cli drainLive:思考先于文本 = 持久臂序)。 */
+    function* drainLive() {
+        if (thinkingPending.length > 0) {
+            const opening = !thinkingBlockOpen;
+            thinkingBlockOpen = true;
+            yield chrome({
+                kind: 'stream_delta',
+                laneProof: MAIN,
+                channel: 'thinking',
+                text: thinkingPending,
+                estimatedTokens: estimateCjkTokens(thinkingPending),
+                opening,
+            });
+            thinkingPending = '';
+        }
+        if (textPending.length > 0) {
+            const opening = !textBlockOpen;
+            textBlockOpen = true;
+            // B3:cli 的 `SEMA_STREAM_PROBE` 文件探针换成 ctx.probe 口(体检 #5 同款用途:Ink 挂载后
+            // console 被吞,harness 只能靠这条证明「引擎是**逐 token 增量**到的」而不是整块一次性 dump)。
+            // 载荷格式与 cli 逐字同形,只把 Date.now() 换成 ctx.now()(注入时钟纪律)。
+            ctx.probe?.('stream', `${ctx.now()} text_flush len=${textPending.length}`);
+            yield chrome({
+                kind: 'stream_delta',
+                laneProof: MAIN,
+                channel: 'text',
+                text: textPending,
+                estimatedTokens: estimateCjkTokens(textPending),
+                opening,
+            });
+            textPending = '';
+        }
+    }
+    return {
+        *feedText(delta, frame) {
+            // MOD-1 思考→回答边界:回答一起头就把思考块 committed 上屏(它推理的内容之前)。
+            if (thinking.length > 0 || thinkingPending.length > 0) {
+                yield* drainLive();
+                yield* takeThinking();
+            }
+            if (answerSegment.length === 0)
+                segmentAnchor = frame;
+            answer += delta;
+            answerSegment += delta;
+            textPending += delta;
+        },
+        *feedThinking(delta, frame) {
+            if (thinking.length === 0) {
+                thinkingAnchor = frame;
+                // P2d:elapsed 锚在**首条** leader 推理增量(token 累计由 stream_delta.estimatedTokens
+                // 承载,宿主自加;>30s 无增量的 stall 提示同样由宿主按增量时间戳判)。
+                yield chrome({ kind: 'thinking_activity', laneProof: MAIN, active: true });
+            }
+            thinking += delta;
+            thinkingPending += delta;
+        },
+        drainLive,
+        takeThinking,
+        takeAnswerSegment,
+        hasPendingContent: () => thinking.length > 0 ||
+            answerSegment.length > 0 ||
+            thinkingPending.length > 0 ||
+            textPending.length > 0,
+        *maybeFlushOnBeat(nowMs) {
+            // COALESCER 节拍:一个间隔至多一次 flush(同步 SSE 突发先攒着,过闸再一次泄干)。
+            if ((textPending.length > 0 || thinkingPending.length > 0) && nowMs - lastFlushAt >= flushEveryMs) {
+                yield* drainLive();
+                lastFlushAt = nowMs;
+            }
+        },
+        appendAnswer: (text) => {
+            answer += text;
+        },
+        markEmittedText: () => {
+            emittedAssistantText = true;
+        },
+        get emittedAssistantText() {
+            return emittedAssistantText;
+        },
+        get answerLength() {
+            return answer.length;
+        },
+    };
+}

package/dist/adapt/toolCards.d.ts

@@ -0,0 +1,65 @@
+/**
+ * adapt/toolCards.ts — M2 **工具卡台账**(A 族拆分 REF-CC-SPLIT-03;矩阵 §1.2 三行状态)。
+ *
+ * 收编 `pending`(开卡表)/ `assistantResponseId`(S1 per-RESPONSE id)/ `lastLiveTodos`
+ * (TodoWrite 划删线 diff 的 oldTodos)三行状态 + C4 mintResponseId / C10 buildToolResult /
+ * C11 sweepOpenCards 三个闭包 + `PendingToolUse` 形本身。
+ *
+ * 🔴 拆分硬约束(SPLIT-03,codex verdict 2 采纳形):**S1 复位在 `close()` 内部、第一个 `yield`
+ *   之前**。理由是生成器语义 —— yield 之后的语句只有消费者再要下一个值时才跑,消费者早退
+ *   (`it.return()` / break)时永不执行。把复位留在调用方,调用方就还能写出「yield 后复位」的形;
+ *   收进被调方之后,这条时序由**一处**保证。原 `tool_end_result` 臂 :1054-1056(delete → 复位 →
+ *   yield)与 sweep :743-747 是同一个三步,现在是同一段代码。
+ *
+ * 🔴 同批把 assistant 臂 reject/cancel(:970)与 error(:990)两条路径的复位**前移到各自 yield 之前**
+ *   —— 矩阵 §2.2 的定性:那两处是**形不一致的技术债、不是缺陷**(`assistantResponseId` 是 L1
+ *   turn 级,两行之后紧跟 `break`,早退时生成器已死、再无读者 ⇒ 零可观测后果),所以前移是
+ *   **纯一致性改动、零行为差**。反钉见矩阵 §2.2:前移不影响 mint —— 影响窗口只有
+ *   「复位语句与原复位点(yield 之后)」之间那几行,窗口内无 mint 点;三条支随即退出本臂,
+ *   后续帧的 mint 走各自臂的常规路径,与拆分前同(codex 复审校准:break 退出的是臂不是 turn)。
+ *
+ * 🔴 `pending` 是唯一跨 M2→M3 的数据面(矩阵 §1.2 注):面板族只读两个字段(`name` 判
+ *   SUBAGENT_TOOL_NAMES / `rawInput` T50 双形读)。所以对外给的是 `OpenCardView` **只读视图**,
+ *   不交 Map 本体 —— 交出去 M3 就能 `delete`,而「一张开卡一条 tool_result」是本模块的不变量。
+ */
+import type { AdapterContext, AdapterOutput } from '../seam.js';
+import { type Frame, type IdOf } from './ids.js';
+/** 一张开着的卡(assistant tool_use 臂开、tool_end_result 臂关)。 */
+export interface PendingToolUse {
+    id: string;
+    name: string;
+    rawInput: unknown;
+    eventId?: string;
+    parentToolCallId?: string;
+}
+/** `tool_end_result` 帧上与关卡有关的那几位(原 `buildToolResult` 的内联入参形,具名化)。 */
+export interface ToolEndPayload {
+    output?: unknown;
+    structured?: unknown;
+    truncated?: boolean;
+    isError?: boolean;
+    eventId?: string | undefined;
+    parentToolCallId?: string | undefined;
+}
+/** 交给面板族(M3)的**只读**视图 —— 不含任何写口。 */
+export interface OpenCardView {
+    /** 这张卡此刻还开着吗(#6 live vs inert 的判位)。 */
+    has(id: string): boolean;
+    /** 读卡(面板族只用 `name` 与 `rawInput` 两个字段)。 */
+    peek(id: string): PendingToolUse | undefined;
+    /** 按**开卡顺序**遍历(FIFO 猜父臂依赖这个顺序)。 */
+    entries(): Iterable<readonly [string, PendingToolUse]>;
+}
+export interface ToolCardLedger extends OpenCardView {
+    /** 开卡(assistant tool_use 臂)。 */
+    open(p: PendingToolUse): void;
+    /** 关一张卡:出栈 + S1 复位 + 铸 tool_result(三步都在第一个 yield 之前完成前两步)。 */
+    close(p: PendingToolUse, end?: ToolEndPayload): Generator<AdapterOutput>;
+    /** 关掉所有还开着的卡(流被截断 / 无 result 收尾;abort 路径**不做**)。 */
+    sweep(): Generator<AdapterOutput>;
+    /** S1:per-RESPONSE 铸 id(同一个 model response 内的多张卡共用)。 */
+    mintResponseId(frame: Frame): string;
+    /** S1:一个结果关闭该 model response(reject/cancel/error 三支的显式复位口)。 */
+    resetResponseId(): void;
+}
+export declare function createToolCardLedger(ctx: AdapterContext, idOf: IdOf): ToolCardLedger;