@sema-agent/client-core 0.3.0 → 0.5.0

package/dist/adapt.js

@@ -5,8 +5,33 @@ import { steeringInjectedToAttachments } from './steering.js';
 import { projectDiagnosticsFrame } from './diagnostics.js';
 /** 主车道证明——本批实现的臂全在 leader lane(子代/workflow lane 的 tick 面留 #52b)。 */
 const MAIN = { lane: 'main' };
-/** cli COALESCER 节流(207 口径;187 时代是 16ms)。宿主无关,时钟从 ctx.now() 取。 */
+/**
+ * 活体增量攒批节拍的**默认值**(时钟从 ctx.now() 取;宿主可用 `ctx.coalesceIntervalMs` 覆盖)。
+ *
+ * 取值依据(两个都是实测,别把其中一个当"唯一真相"):
+ *  · **100ms** = 我们对标的 CC 2.1.207 CLI 口径(187 时代是 16ms,207 提到 100ms 降重绘频率,
+ *    长回答滚动更稳)—— 壳是 207 fork,所以库的默认值取它,壳消费本包时行为零变化;
+ *  · **16ms** = CC **桌面端**宿主 `makeStreamDeltaCoalescer` 的单帧攒批节拍(设计稿 R1 实测)。
+ * ⇒ 结论:**节拍是宿主渲染策略,不是 wire 语义** —— CC 自己两个端就是两个值。web/桌面宿主
+ *   想要 16ms 就传 `coalesceIntervalMs: 16`,合并**语义**(思考先于文本、段边界重开块、
+ *   committed 恒随后)在库里,一份。
+ *
+ * 🔴 顺带钉一句反面事实(R1 证伪,别再写进任何注释/文档):**"UI 从不见裸 token" 是错的** ——
+ * CC 攒批后 flush 的载荷仍是 `stream_event` 增量 delta,CC 的 UI 照样消费增量;
+ * 完整 assistant 消息是 SDK 另发的一路。我们这里的 `stream_delta` chrome 臂同构。
+ */
 export const FLUSH_INTERVAL_MS = 100;
+/**
+ * T40 IDLE-FLUSH 竞速窗(cli upstreamBridge `IDLE_FLUSH_MS` 逐字同值)。
+ *
+ * 病:模型转入长工具参数生成(大 Write 的 input_json 不经本桥)时 SSE 增量停摆,而 thinking/
+ * answerSegment 里**已经生成**的内容还押着陪等(pty 确证:11s 整屏 hash 恒定)。
+ * 修:增量停 ≥1.5s 且缓冲非空 ⇒ 先 drainLive()(活体预览语义不变),再提交思考+文本段
+ * (段序铁律不破:本来就该在下一张工具卡前 flush,这里只是提前)。
+ * 🔴 这是**过渡修**,正解在 core [817](wire 侧给事件);且**需要宿主定时器**:
+ * `ctx.setTimer` 缺席 ⇒ 整条竞速不启用(纯等下一帧),与 0.4.0 逐字同行为。
+ */
+export const IDLE_FLUSH_MS = 1500;
 /** cli SUBAGENT_TOOL_NAMES / WORKFLOW_TOOL_NAMES 同源(判别资产,别各自重写)。 */
 export const SUBAGENT_TOOL_NAMES = new Set(['Task', 'Agent', 'Fork']);
 export const WORKFLOW_TOOL_NAMES = new Set(['Workflow', 'RunWorkflow', 'run_workflow']);
@@ -124,6 +149,14 @@ export const ADAPTER_COVERAGE = {
         'user_task_notification',
         'system_passthrough',
     ],
+    /** B3(0.5.0)新落码的臂/半场 —— 从 todo 移过来的,别再在 todo 里留同名条目。 */
+    b3: [
+        'T38 三清第三清 + T57 第五处断闸:prompt_suggestions(turn 开场作废 + 子流断闸)',
+        'T40 IDLE-FLUSH 1.5s 竞速(需 ctx.setTimer;缺席=不启用)',
+        'T58 手动 iterator 的 finally cleanup(early break/throw 都要关上游生成器)',
+        'T59 abort 半场(ctx.signal;中断后不产终答)',
+        'T60 无 result 收尾腿(泄尾增量 → 清 liveness → 尾思考 → 尾文本段)',
+    ],
     /** 如实留白——写不动/依赖未搬运资产的臂,#52b 起分批接。 */
     todo: [
         'tool_end_result → user tool_result 正常路径(需搬 wireOutputToBody/structuredToToolUseResult/mock 合成器 + TodoWrite/ReportFindings 富卡片,约 600 行;workflow 轮询信封的人话投影已在 workflow.ts 就位,等这条接线)',
@@ -132,8 +165,7 @@ export const ADAPTER_COVERAGE = {
         'task_progress → 面板行绑定(bindTaskCard FIFO/显式父、inline stats、alias、resident 台账、SubagentStart hook、workflow lane 三级门)',
         'settlePanelTasks 三处 sweep(依赖上面的行台账)',
         '#117a bg Bash 回执探测(detectEngineBgShellReceipt 文案锚定探测器)',
-        'abort/Esc 半场(AdapterContext 无 signal 位——见 SEAM-GAP-4)',
-        'IDLE_FLUSH 1.5s 竞速(件1 大 Write 静默窗;需 ctx 侧定时器能力)',
+        'abort 半场里依赖行台账的两件:settlePanelTasks 兜底 sweep + 开卡合成器兜底关卡(见上面两条)',
         'macrotask 让渡(cli 在提交前让出宏任务给 Ink;宿主渲染策略,不进库)',
     ],
 };
@@ -143,8 +175,13 @@ export const ADAPTER_DIVERGENCES = [
         '现役 wire 不产 user 帧(eventToSdkMessage 无该出口),故对真流是惰性的;保留是为了 desktop 重放存量转录。',
     'DIVERGENCE-2:transcript uuid 取值形——cli 铸随机 v4 / 原样透传帧 uuid,adapt 一律走 ' +
         'deriveTranscriptId(稳定键前缀形 `wid_*`)。差分守卫按「别名结构」比对(同一侧内的复用/区分关系),不比字面值。',
-    'DIVERGENCE-3:合并节流的**分片边界**不比对——cli 用 Date.now() 真时钟,adapt 用 ctx.now()。' +
+    'DIVERGENCE-3:合并节流的**分片边界**不比对——cli 用 Date.now() 真时钟,adapt 用 ctx.now();' +
+        '且 B3 起节拍可由宿主 `ctx.coalesceIntervalMs` 覆盖(缺席=cli 同值 100ms)。' +
         '守卫比对的是 chrome 增量按 channel 拼接后的全文与顺序(语义不变量),不是 chunk 切分。',
+    'DIVERGENCE-4(B3):流探针的**开关与时间戳**不同形——cli 是 `process.env.SEMA_STREAM_PROBE` ' +
+        '文件探针写 `${Date.now()} text_flush len=N`,adapt 是 `ctx.probe(\'stream\', …)` 注入口写 ' +
+        '`${ctx.now()} text_flush len=N`。行格式与触发点(每次文本 flush 一次)逐字相同,' +
+        '差在时钟源与落地方式(宿主决定落文件/上报/丢弃)。',
 ];
 const TASK_NOTIFICATION_TAG = 'task-notification';
 const TASK_ID_TAG = 'task-id';
@@ -270,6 +307,10 @@ class WireToCcAdapterImpl {
         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;
         let messageStartEmitted = false;
         let endEmitted = false;
         let assistantResponseId = null;
@@ -338,6 +379,10 @@ class WireToCcAdapterImpl {
             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,
@@ -349,417 +394,508 @@ class WireToCcAdapterImpl {
                 textPending = '';
             }
         }
-        // turn 开场卫生(cli:清上一 turn 的 retry 覆盖层 + 思考活动行,再发 request-start)。
+        // turn 开场卫生(T38 三清,cli 逐条同序):清上一 turn 的 retry 覆盖层 + **上一轮的建议批** +
+        // 思考活动行,再发 request-start(T39)。三清缺一都是"上一轮的东西挂着不掉"。
         yield chrome({ kind: 'retry_status', laneProof: MAIN, status: null });
+        yield chrome({ kind: 'prompt_suggestions', laneProof: MAIN, suggestions: null });
         yield chrome({ kind: 'thinking_activity', laneProof: MAIN, active: false });
         yield chrome({ kind: 'request_start', laneProof: MAIN });
-        for await (const rawFrame of frames) {
-            const m = rawFrame;
-            if (m === null || typeof m !== 'object')
-                continue;
-            if (m.type === 'stream_event' && !messageStartEmitted) {
-                messageStartEmitted = true;
-                yield chrome({
-                    kind: 'response_metrics',
-                    laneProof: MAIN,
-                    phase: 'start',
-                    ttftMs: ctx.now() - turnStartAt,
-                });
-            }
-            // 持久臂之前先把活体增量泄干净(活体预览恒先于它 settle 成的 committed 消息)。
-            if (m.type !== 'stream_event')
-                yield* drainLive();
-            switch (m.type) {
-                case 'assistant': {
-                    const message = m.message;
-                    const blocks = Array.isArray(message?.content)
-                        ? message.content
-                        : [];
-                    const toolUseIdx = blocks.findIndex(b => b?.type === 'tool_use');
-                    if (toolUseIdx >= 0) {
-                        const original = blocks[toolUseIdx];
-                        const decision = decisionOf(original);
-                        const san = sanitizeToolUseBlock(original);
-                        const renderBlocks = blocks.map((b, i) => (i === toolUseIdx ? san.block : b));
-                        const toolUseId = String(san.block.id);
-                        const toolName = typeof san.block.name === 'string' ? san.block.name : 'unknown';
-                        // 引擎模式下壳工具 call() 从不执行 —— ctrl+t 面板台账只能靠这条侧信道(宿主义务)。
-                        if (TASK_TOOL_NAMES.has(toolName)) {
-                            yield chrome({
-                                kind: 'task_ledger_sync',
-                                laneProof: MAIN,
-                                source: 'tool_use',
-                                toolName,
-                                toolUseId,
-                                input: san.block.input,
-                            });
-                        }
-                        // #27 段序:先把这张卡之前的散文提交,再提交它之前的思考(思考恒在卡上方)。
-                        yield* takeAnswerSegment();
+        // ── T40/T58/T59:手动 iterator + IDLE-FLUSH 竞速 + abort 断流 ────────────────────────────────
+        // `for await` 换成手动 next():① 才能与 idle 计时器 race(T40);② 才能在 abort 时立刻停;
+        // 代价是失去 for-await 的隐式 cleanup ⇒ finally 里手动 return()(T58,少了它 = SSE 不拆)。
+        const iterator = frames[Symbol.asyncIterator]();
+        let iteratorDone = false;
+        try {
+            for (;;) {
+                const nextPromise = iterator.next();
+                let step;
+                while (step === undefined) {
+                    const hasPendingContent = thinking.length > 0 ||
+                        answerSegment.length > 0 ||
+                        thinkingPending.length > 0 ||
+                        textPending.length > 0;
+                    // 缓冲全空 ⇒ 零开销路径;宿主没给定时器 ⇒ 竞速整条不启用(绝不 setTimeout 兜底)。
+                    if (!hasPendingContent || ctx.setTimer === undefined) {
+                        step = await nextPromise;
+                        break;
+                    }
+                    let idleTimer;
+                    const raced = await Promise.race([
+                        nextPromise.then(r => ({ tag: 'next', r })),
+                        new Promise(resolve => {
+                            idleTimer = ctx.setTimer?.(IDLE_FLUSH_MS, () => resolve({ tag: 'idle' }));
+                        }),
+                    ]);
+                    if (idleTimer !== undefined)
+                        ctx.clearTimer?.(idleTimer);
+                    if (raced.tag === 'next') {
+                        step = raced.r;
+                    }
+                    else {
+                        if (ctx.signal?.aborted)
+                            break;
+                        // Idle ≥1.5s 且有已生成未提交的内容:现在就上屏(活体预览在前,再按 思考→文本 的
+                        // committed 序 —— 与工具卡前的边界 flush 逐字同序,只是提前发生)。
+                        yield* drainLive();
                         yield* takeThinking();
-                        yield transcript({
-                            type: 'assistant',
-                            // S1:per-RESPONSE 铸 id —— CC 的 grouped-agent 渲染按 `${message.id}:${toolName}`
-                            // 分组;id-less 帧会把整个 session 的 Agent 卡塌成一张。tool_use 帧才盖章。
-                            message: { id: mintResponseId(m), role: 'assistant', content: renderBlocks },
-                            uuid: idOf(m),
-                            session_id: ctx.sessionId,
-                            parent_tool_use_id: null,
-                        });
-                        if (decision === 'reject' || decision === 'cancel') {
+                        yield* takeAnswerSegment();
+                        // 缓冲已空 ⇒ 下一圈直接 plain-await。
+                    }
+                }
+                if (step === undefined)
+                    break; // abort while idle-waiting
+                if (step.done) {
+                    iteratorDone = true;
+                    break;
+                }
+                const rawFrame = step.value;
+                // T59 — 信号一跳就停止投影(后续任何臂都不再渲染)。
+                if (ctx.signal?.aborted)
+                    break;
+                const m = rawFrame;
+                if (m === null || typeof m !== 'object')
+                    continue;
+                if (m.type === 'stream_event' && !messageStartEmitted) {
+                    messageStartEmitted = true;
+                    yield chrome({
+                        kind: 'response_metrics',
+                        laneProof: MAIN,
+                        phase: 'start',
+                        ttftMs: ctx.now() - turnStartAt,
+                    });
+                }
+                // 持久臂之前先把活体增量泄干净(活体预览恒先于它 settle 成的 committed 消息)。
+                if (m.type !== 'stream_event')
+                    yield* drainLive();
+                switch (m.type) {
+                    case 'assistant': {
+                        const message = m.message;
+                        const blocks = Array.isArray(message?.content)
+                            ? message.content
+                            : [];
+                        const toolUseIdx = blocks.findIndex(b => b?.type === 'tool_use');
+                        if (toolUseIdx >= 0) {
+                            const original = blocks[toolUseIdx];
+                            const decision = decisionOf(original);
+                            const san = sanitizeToolUseBlock(original);
+                            const renderBlocks = blocks.map((b, i) => (i === toolUseIdx ? san.block : b));
+                            const toolUseId = String(san.block.id);
+                            const toolName = typeof san.block.name === 'string' ? san.block.name : 'unknown';
+                            // 引擎模式下壳工具 call() 从不执行 —— ctrl+t 面板台账只能靠这条侧信道(宿主义务)。
+                            if (TASK_TOOL_NAMES.has(toolName)) {
+                                yield chrome({
+                                    kind: 'task_ledger_sync',
+                                    laneProof: MAIN,
+                                    source: 'tool_use',
+                                    toolName,
+                                    toolUseId,
+                                    input: san.block.input,
+                                });
+                            }
+                            // #27 段序:先把这张卡之前的散文提交,再提交它之前的思考(思考恒在卡上方)。
+                            yield* takeAnswerSegment();
+                            yield* takeThinking();
                             yield transcript({
-                                type: 'user',
-                                message: {
-                                    role: 'user',
-                                    content: [
-                                        {
-                                            type: 'tool_result',
-                                            tool_use_id: san.block.id,
-                                            content: decision === 'reject' ? REJECT_MESSAGE : CANCEL_MESSAGE,
-                                            is_error: false,
-                                        },
-                                    ],
-                                },
-                                uuid: idOf(m, decision),
+                                type: 'assistant',
+                                // S1:per-RESPONSE 铸 id —— CC 的 grouped-agent 渲染按 `${message.id}:${toolName}`
+                                // 分组;id-less 帧会把整个 session 的 Agent 卡塌成一张。tool_use 帧才盖章。
+                                message: { id: mintResponseId(m), role: 'assistant', content: renderBlocks },
+                                uuid: idOf(m),
                                 session_id: ctx.sessionId,
+                                parent_tool_use_id: null,
                             });
-                            assistantResponseId = null; // 一个结果关闭该 model response
+                            if (decision === 'reject' || decision === 'cancel') {
+                                yield transcript({
+                                    type: 'user',
+                                    message: {
+                                        role: 'user',
+                                        content: [
+                                            {
+                                                type: 'tool_result',
+                                                tool_use_id: san.block.id,
+                                                content: decision === 'reject' ? REJECT_MESSAGE : CANCEL_MESSAGE,
+                                                is_error: false,
+                                            },
+                                        ],
+                                    },
+                                    uuid: idOf(m, decision),
+                                    session_id: ctx.sessionId,
+                                });
+                                assistantResponseId = null; // 一个结果关闭该 model response
+                                break;
+                            }
+                            if (decision === 'error') {
+                                yield transcript({
+                                    type: 'user',
+                                    message: {
+                                        role: 'user',
+                                        content: [
+                                            {
+                                                type: 'tool_result',
+                                                tool_use_id: san.block.id,
+                                                content: 'The tool failed to execute.',
+                                                is_error: true,
+                                            },
+                                        ],
+                                    },
+                                    uuid: idOf(m, 'error'),
+                                    session_id: ctx.sessionId,
+                                });
+                                assistantResponseId = null;
+                                break;
+                            }
+                            pending.set(toolUseId, {
+                                id: toolUseId,
+                                name: toolName,
+                                rawInput: san.rawInput,
+                                ...(san.eventId !== undefined ? { eventId: san.eventId } : {}),
+                                ...(san.parentToolCallId !== undefined ? { parentToolCallId: san.parentToolCallId } : {}),
+                            });
+                            if (WORKFLOW_TOOL_NAMES.has(toolName))
+                                this.seenWorkflowToolCallIds.add(toolUseId);
                             break;
                         }
-                        if (decision === 'error') {
+                        const textBlock = blocks.find(b => b?.type === 'text');
+                        if (textBlock && typeof textBlock.text === 'string' && textBlock.text.length > 0) {
+                            answer += textBlock.text;
+                            yield* takeThinking();
                             yield transcript({
-                                type: 'user',
-                                message: {
-                                    role: 'user',
-                                    content: [
-                                        {
-                                            type: 'tool_result',
-                                            tool_use_id: san.block.id,
-                                            content: 'The tool failed to execute.',
-                                            is_error: true,
-                                        },
-                                    ],
-                                },
-                                uuid: idOf(m, 'error'),
+                                type: 'assistant',
+                                message: { role: 'assistant', content: [{ type: 'text', text: textBlock.text }] },
+                                uuid: idOf(m),
                                 session_id: ctx.sessionId,
+                                parent_tool_use_id: null,
+                            });
+                            emittedAssistantText = true;
+                        }
+                        const thinkingBlock = blocks.find(b => b?.type === 'thinking');
+                        if (thinkingBlock && typeof thinkingBlock.thinking === 'string') {
+                            yield transcript({
+                                type: 'assistant',
+                                message: { role: 'assistant', content: [thinkingBlock] },
+                                uuid: idOf(m, 'durable-thinking'),
+                                session_id: ctx.sessionId,
+                                parent_tool_use_id: null,
                             });
-                            assistantResponseId = null;
-                            break;
                         }
-                        pending.set(toolUseId, {
-                            id: toolUseId,
-                            name: toolName,
-                            rawInput: san.rawInput,
-                            ...(san.eventId !== undefined ? { eventId: san.eventId } : {}),
-                            ...(san.parentToolCallId !== undefined ? { parentToolCallId: san.parentToolCallId } : {}),
-                        });
-                        if (WORKFLOW_TOOL_NAMES.has(toolName))
-                            this.seenWorkflowToolCallIds.add(toolUseId);
                         break;
                     }
-                    const textBlock = blocks.find(b => b?.type === 'text');
-                    if (textBlock && typeof textBlock.text === 'string' && textBlock.text.length > 0) {
-                        answer += textBlock.text;
-                        yield* takeThinking();
-                        yield transcript({
-                            type: 'assistant',
-                            message: { role: 'assistant', content: [{ type: 'text', text: textBlock.text }] },
-                            uuid: idOf(m),
-                            session_id: ctx.sessionId,
-                            parent_tool_use_id: null,
-                        });
-                        emittedAssistantText = true;
+                    // DIVERGENCE-1 —— 现役 wire 不产 user 帧;透传是给 desktop 重放存量转录留的门。
+                    case 'user': {
+                        if (m.message === undefined)
+                            break;
+                        yield transcript({ ...m, uuid: idOf(m), session_id: ctx.sessionId });
+                        break;
                     }
-                    const thinkingBlock = blocks.find(b => b?.type === 'thinking');
-                    if (thinkingBlock && typeof thinkingBlock.thinking === 'string') {
-                        yield transcript({
-                            type: 'assistant',
-                            message: { role: 'assistant', content: [thinkingBlock] },
-                            uuid: idOf(m, 'durable-thinking'),
-                            session_id: ctx.sessionId,
-                            parent_tool_use_id: null,
-                        });
+                    case 'tool_end_result': {
+                        // 本批只做**卡台账出栈 + response-id 复位**(S1:一个结果关闭该 response,后续 tool_use
+                        // 必须换新 id 才不会被 CC 分组塌成一张卡)。tool_result 消息本体见 ADAPTER_COVERAGE.todo。
+                        const callId = typeof m.toolCallId === 'string' ? m.toolCallId : undefined;
+                        if (callId !== undefined && pending.has(callId)) {
+                            pending.delete(callId);
+                            assistantResponseId = null;
+                        }
+                        break;
                     }
-                    break;
-                }
-                // DIVERGENCE-1 —— 现役 wire 不产 user 帧;透传是给 desktop 重放存量转录留的门。
-                case 'user': {
-                    if (m.message === undefined)
+                    case 'stream_event': {
+                        const ev = m.event;
+                        if (ev && ev.type === 'text_delta' && typeof ev.delta === 'string') {
+                            // MOD-1 思考→回答边界:回答一起头就把思考块 committed 上屏(它推理的内容之前)。
+                            if (thinking.length > 0 || thinkingPending.length > 0) {
+                                yield* drainLive();
+                                yield* takeThinking();
+                            }
+                            if (answerSegment.length === 0)
+                                segmentAnchor = m;
+                            answer += ev.delta;
+                            answerSegment += ev.delta;
+                            textPending += ev.delta;
+                        }
+                        else if (ev && ev.type === 'thinking_delta' && typeof ev.delta === 'string') {
+                            // 子流(parentToolCallId)的推理绝不喂 leader 的计数与预览(#9 的壳侧半场)。
+                            if (ev.parentToolCallId !== undefined)
+                                break;
+                            if (thinking.length === 0) {
+                                thinkingAnchor = m;
+                                // P2d:elapsed 锚在**首条** leader 推理增量(token 累计由 stream_delta.estimatedTokens
+                                // 承载,宿主自加;>30s 无增量的 stall 提示同样由宿主按增量时间戳判)。
+                                yield chrome({ kind: 'thinking_activity', laneProof: MAIN, active: true });
+                            }
+                            thinking += ev.delta;
+                            thinkingPending += ev.delta;
+                        }
                         break;
-                    yield transcript({ ...m, uuid: idOf(m), session_id: ctx.sessionId });
-                    break;
-                }
-                case 'tool_end_result': {
-                    // 本批只做**卡台账出栈 + response-id 复位**(S1:一个结果关闭该 response,后续 tool_use
-                    // 必须换新 id 才不会被 CC 分组塌成一张卡)。tool_result 消息本体见 ADAPTER_COVERAGE.todo。
-                    const callId = typeof m.toolCallId === 'string' ? m.toolCallId : undefined;
-                    if (callId !== undefined && pending.has(callId)) {
-                        pending.delete(callId);
-                        assistantResponseId = null;
                     }
-                    break;
-                }
-                case 'stream_event': {
-                    const ev = m.event;
-                    if (ev && ev.type === 'text_delta' && typeof ev.delta === 'string') {
-                        // MOD-1 思考→回答边界:回答一起头就把思考块 committed 上屏(它推理的内容之前)。
-                        if (thinking.length > 0 || thinkingPending.length > 0) {
+                    case 'turn_usage': {
+                        const ot = typeof m.outputTokens === 'number' ? m.outputTokens : undefined;
+                        if (ot != null) {
                             yield* drainLive();
-                            yield* takeThinking();
+                            yield chrome({ kind: 'response_metrics', laneProof: MAIN, phase: 'end', outputTokens: ot });
+                            endEmitted = true;
+                            messageStartEmitted = false; // 下一 model round 重新压基线
                         }
-                        if (answerSegment.length === 0)
-                            segmentAnchor = m;
-                        answer += ev.delta;
-                        answerSegment += ev.delta;
-                        textPending += ev.delta;
+                        break;
                     }
-                    else if (ev && ev.type === 'thinking_delta' && typeof ev.delta === 'string') {
-                        // 子流(parentToolCallId)的推理绝不喂 leader 的计数与预览(#9 的壳侧半场)。
-                        if (ev.parentToolCallId !== undefined)
-                            break;
-                        if (thinking.length === 0) {
-                            thinkingAnchor = m;
-                            // P2d:elapsed 锚在**首条** leader 推理增量(token 累计由 stream_delta.estimatedTokens
-                            // 承载,宿主自加;>30s 无增量的 stall 提示同样由宿主按增量时间戳判)。
-                            yield chrome({ kind: 'thinking_activity', laneProof: MAIN, active: true });
+                    case 'result': {
+                        yield chrome({ kind: 'retry_status', laneProof: MAIN, status: null });
+                        yield* takeThinking();
+                        if (!endEmitted) {
+                            const u = m.usage;
+                            if (typeof u?.outputTokens === 'number') {
+                                yield chrome({
+                                    kind: 'response_metrics',
+                                    laneProof: MAIN,
+                                    phase: 'end',
+                                    outputTokens: u.outputTokens,
+                                });
+                                endEmitted = true;
+                            }
                         }
-                        thinking += ev.delta;
-                        thinkingPending += ev.delta;
-                    }
-                    break;
-                }
-                case 'turn_usage': {
-                    const ot = typeof m.outputTokens === 'number' ? m.outputTokens : undefined;
-                    if (ot != null) {
-                        yield* drainLive();
-                        yield chrome({ kind: 'response_metrics', laneProof: MAIN, phase: 'end', outputTokens: ot });
-                        endEmitted = true;
-                        messageStartEmitted = false; // 下一 model round 重新压基线
-                    }
-                    break;
-                }
-                case 'result': {
-                    yield chrome({ kind: 'retry_status', laneProof: MAIN, status: null });
-                    yield* takeThinking();
-                    if (!endEmitted) {
-                        const u = m.usage;
-                        if (typeof u?.outputTokens === 'number') {
-                            yield chrome({
-                                kind: 'response_metrics',
-                                laneProof: MAIN,
-                                phase: 'end',
-                                outputTokens: u.outputTokens,
-                            });
-                            endEmitted = true;
+                        yield* takeAnswerSegment();
+                        if (!emittedAssistantText) {
+                            const text = typeof m.result === 'string' ? m.result : '';
+                            if (text.length > 0) {
+                                yield transcript({
+                                    type: 'assistant',
+                                    message: { role: 'assistant', content: [{ type: 'text', text }] },
+                                    uuid: idOf(m, 'terminal-text'),
+                                    session_id: ctx.sessionId,
+                                    parent_tool_use_id: null,
+                                });
+                                emittedAssistantText = true;
+                            }
                         }
+                        break;
                     }
-                    yield* takeAnswerSegment();
-                    if (!emittedAssistantText) {
-                        const text = typeof m.result === 'string' ? m.result : '';
-                        if (text.length > 0) {
-                            yield transcript({
-                                type: 'assistant',
-                                message: { role: 'assistant', content: [{ type: 'text', text }] },
-                                uuid: idOf(m, 'terminal-text'),
-                                session_id: ctx.sessionId,
-                                parent_tool_use_id: null,
-                            });
-                            emittedAssistantText = true;
+                    case 'system': {
+                        yield transcript(m);
+                        // core 1.219 attachWorkingFiles:compact_boundary 可携 attachedFiles → CC 的
+                        // "Referenced file {path}" 行(post-compact attachment,零新 UI)。
+                        const attachedFiles = m.attachedFiles;
+                        if (Array.isArray(attachedFiles)) {
+                            let i = 0;
+                            for (const f of attachedFiles) {
+                                if (typeof f?.path !== 'string' || f.path.length === 0)
+                                    continue;
+                                yield chrome({
+                                    kind: 'attachment',
+                                    laneProof: MAIN,
+                                    id: idOf(m, `attached-file-${i++}`),
+                                    attachment: {
+                                        type: 'compact_file_reference',
+                                        filename: f.path,
+                                        displayPath: f.path,
+                                    },
+                                });
+                            }
                         }
+                        break;
                     }
-                    break;
-                }
-                case 'system': {
-                    yield transcript(m);
-                    // core 1.219 attachWorkingFiles:compact_boundary 可携 attachedFiles → CC 的
-                    // "Referenced file {path}" 行(post-compact attachment,零新 UI)。
-                    const attachedFiles = m.attachedFiles;
-                    if (Array.isArray(attachedFiles)) {
-                        let i = 0;
-                        for (const f of attachedFiles) {
-                            if (typeof f?.path !== 'string' || f.path.length === 0)
-                                continue;
+                    case 'task_notification': {
+                        const n = (m.notification ?? {});
+                        const fields = normalizeTaskNotification(n);
+                        if (fields === null)
+                            break; // 空/缺 task_id:RB-75 同族,丢弃
+                        const taskId = fields.taskId;
+                        const rawStatus = fields.status;
+                        const terminal = rawStatus === 'completed' || rawStatus === 'failed' || rawStatus === 'killed';
+                        // #117a settle 半场 —— **故意在渲染去重之前**:settle 幂等,重放帧仍须 settle 一条
+                        // 首投之后才注册的行。#47 矩阵 #7:只有 bash 行(或老引擎无 task_type)能被 settle。
+                        const settleAllowed = n.task_type === undefined || n.task_type === 'background_bash';
+                        if (settleAllowed && terminal) {
                             yield chrome({
-                                kind: 'attachment',
+                                kind: 'bgshell_settle',
                                 laneProof: MAIN,
-                                id: idOf(m, `attached-file-${i++}`),
-                                attachment: {
-                                    type: 'compact_file_reference',
-                                    filename: f.path,
-                                    displayPath: f.path,
-                                },
+                                taskId,
+                                status: rawStatus,
+                                ...(typeof n.output_file === 'string' && n.output_file.length > 0
+                                    ? { outputPath: n.output_file }
+                                    : {}),
                             });
                         }
-                    }
-                    break;
-                }
-                case 'task_notification': {
-                    const n = (m.notification ?? {});
-                    const fields = normalizeTaskNotification(n);
-                    if (fields === null)
-                        break; // 空/缺 task_id:RB-75 同族,丢弃
-                    const taskId = fields.taskId;
-                    const rawStatus = fields.status;
-                    const terminal = rawStatus === 'completed' || rawStatus === 'failed' || rawStatus === 'killed';
-                    // #117a settle 半场 —— **故意在渲染去重之前**:settle 幂等,重放帧仍须 settle 一条
-                    // 首投之后才注册的行。#47 矩阵 #7:只有 bash 行(或老引擎无 task_type)能被 settle。
-                    const settleAllowed = n.task_type === undefined || n.task_type === 'background_bash';
-                    if (settleAllowed && terminal) {
-                        yield chrome({
-                            kind: 'bgshell_settle',
-                            laneProof: MAIN,
-                            taskId,
-                            status: rawStatus,
-                            ...(typeof n.output_file === 'string' && n.output_file.length > 0
-                                ? { outputPath: n.output_file }
-                                : {}),
-                        });
-                    }
-                    const dedupKey = taskNotificationDedupKey({
-                        taskId,
-                        status: rawStatus,
-                        ...(typeof n.seq === 'number' || typeof n.seq === 'string' ? { seq: n.seq } : {}),
-                        ...(typeof n.task_type === 'string' ? { taskType: n.task_type } : {}),
-                    });
-                    if (this.renderedNotifications.has(dedupKey))
-                        break;
-                    this.renderedNotifications.add(dedupKey);
-                    // B1 + #6 —— 必须在 cardEnqueued 早退**之前**:probe 合成先入队的场景恰是双投主形。
-                    if (n.task_type !== 'external' && terminal) {
-                        yield chrome({
-                            kind: 'notification_terminal',
-                            laneProof: MAIN,
+                        const dedupKey = taskNotificationDedupKey({
                             taskId,
                             status: rawStatus,
+                            ...(typeof n.seq === 'number' || typeof n.seq === 'string' ? { seq: n.seq } : {}),
                             ...(typeof n.task_type === 'string' ? { taskType: n.task_type } : {}),
                         });
-                        if (n.task_type !== 'background_bash') {
-                            yield chrome({
-                                kind: 'panel_task',
-                                laneProof: MAIN,
-                                event: { kind: 'end', taskId, isError: rawStatus !== 'completed' },
-                            });
+                        if (this.renderedNotifications.has(dedupKey))
+                            break;
+                        this.renderedNotifications.add(dedupKey);
+                        // B1 + #6 —— 必须在 cardEnqueued 早退**之前**:probe 合成先入队的场景恰是双投主形。
+                        if (n.task_type !== 'external' && terminal) {
                             yield chrome({
-                                kind: 'subagent_lifecycle',
+                                kind: 'notification_terminal',
                                 laneProof: MAIN,
-                                phase: 'stop',
                                 taskId,
-                                guard: 'if-started',
+                                status: rawStatus,
+                                ...(typeof n.task_type === 'string' ? { taskType: n.task_type } : {}),
                             });
+                            if (n.task_type !== 'background_bash') {
+                                yield chrome({
+                                    kind: 'panel_task',
+                                    laneProof: MAIN,
+                                    event: { kind: 'end', taskId, isError: rawStatus !== 'completed' },
+                                });
+                                yield chrome({
+                                    kind: 'subagent_lifecycle',
+                                    laneProof: MAIN,
+                                    phase: 'stop',
+                                    taskId,
+                                    guard: 'if-started',
+                                });
+                            }
                         }
-                    }
-                    // 双通道反向去重:probe 合成的完成卡已入队 ⇒ 后到的推送帧只做上面的记账,不渲第二条。
-                    if (n.task_type !== 'external' && this.cardEnqueuedRuns.has(taskId))
-                        break;
-                    // 跨通道记账(cli markEngineWorkflowNotified 同位、同条件:非 external,不看终态):
-                    // 这帧到达 = 引擎已 server-side steer-inject 过,补发通道(workflow_complete)不得再注入。
-                    // external 豁免([769] 对抗复审收紧:external 从不经补发通道,mark 只会缴械 probe 兜底)。
-                    if (n.task_type !== 'external')
-                        this.notifiedRuns.add(taskId);
-                    yield transcript({
-                        type: 'user',
-                        message: { role: 'user', content: [{ type: 'text', text: renderTaskNotificationXml(fields) }] },
-                        uuid: idOf(m),
-                        session_id: ctx.sessionId,
-                    });
-                    break;
-                }
-                case 'workflow_complete': {
-                    const runId = typeof m.runId === 'string' ? m.runId : undefined;
-                    if (runId === undefined)
-                        break;
-                    // 跨通道去重(cli enqueueEngineWorkflowNotification 首行):该 run 已由推送帧记账过
-                    // (引擎 server-side 注入过)⇒ Path B 绝不再喂模型一遍。适配器自持,不摊给宿主。
-                    if (this.notifiedRuns.has(runId))
+                        // 双通道反向去重:probe 合成的完成卡已入队 ⇒ 后到的推送帧只做上面的记账,不渲第二条。
+                        if (n.task_type !== 'external' && this.cardEnqueuedRuns.has(taskId))
+                            break;
+                        // 跨通道记账(cli markEngineWorkflowNotified 同位、同条件:非 external,不看终态):
+                        // 这帧到达 = 引擎已 server-side steer-inject 过,补发通道(workflow_complete)不得再注入。
+                        // external 豁免([769] 对抗复审收紧:external 从不经补发通道,mark 只会缴械 probe 兜底)。
+                        if (n.task_type !== 'external')
+                            this.notifiedRuns.add(taskId);
+                        yield transcript({
+                            type: 'user',
+                            message: { role: 'user', content: [{ type: 'text', text: renderTaskNotificationXml(fields) }] },
+                            uuid: idOf(m),
+                            session_id: ctx.sessionId,
+                        });
                         break;
-                    this.notifiedRuns.add(runId);
-                    const wfStatus = m.status === 'failed' ? 'failed' : 'completed';
-                    const wfSummary = typeof m.summary === 'string' ? m.summary : '';
-                    yield chrome({
-                        kind: 'workflow_notification_enqueue',
-                        laneProof: MAIN,
-                        runId,
-                        status: wfStatus,
-                        summary: wfSummary,
-                        // 模型面正文照铸(宿主直接入队即可,不必各自拼 XML;与 core 的 tag/段序同形)
-                        message: renderTaskNotificationXml({ taskId: runId, status: wfStatus, summary: wfSummary }),
-                    });
-                    this.cardEnqueuedRuns.add(runId);
-                    break;
-                }
-                case 'diagnostics': {
-                    if (typeof m.parentToolCallId === 'string')
-                        break; // 子流帧不上 leader 面
-                    const att = projectDiagnosticsFrame(m);
-                    if (att === null)
+                    }
+                    case 'workflow_complete': {
+                        const runId = typeof m.runId === 'string' ? m.runId : undefined;
+                        if (runId === undefined)
+                            break;
+                        // 跨通道去重(cli enqueueEngineWorkflowNotification 首行):该 run 已由推送帧记账过
+                        // (引擎 server-side 注入过)⇒ Path B 绝不再喂模型一遍。适配器自持,不摊给宿主。
+                        if (this.notifiedRuns.has(runId))
+                            break;
+                        this.notifiedRuns.add(runId);
+                        const wfStatus = m.status === 'failed' ? 'failed' : 'completed';
+                        const wfSummary = typeof m.summary === 'string' ? m.summary : '';
+                        yield chrome({
+                            kind: 'workflow_notification_enqueue',
+                            laneProof: MAIN,
+                            runId,
+                            status: wfStatus,
+                            summary: wfSummary,
+                            // 模型面正文照铸(宿主直接入队即可,不必各自拼 XML;与 core 的 tag/段序同形)
+                            message: renderTaskNotificationXml({ taskId: runId, status: wfStatus, summary: wfSummary }),
+                        });
+                        this.cardEnqueuedRuns.add(runId);
                         break;
-                    yield chrome({ kind: 'attachment', laneProof: MAIN, id: idOf(m), attachment: att });
-                    break;
-                }
-                case 'steering_injected': {
-                    if (typeof m.parentToolCallId === 'string')
+                    }
+                    case 'diagnostics': {
+                        if (typeof m.parentToolCallId === 'string')
+                            break; // 子流帧不上 leader 面
+                        const att = projectDiagnosticsFrame(m);
+                        if (att === null)
+                            break;
+                        yield chrome({ kind: 'attachment', laneProof: MAIN, id: idOf(m), attachment: att });
                         break;
-                    const source = typeof m.source === 'string' ? m.source : '';
-                    if (source.length === 0)
+                    }
+                    case 'steering_injected': {
+                        if (typeof m.parentToolCallId === 'string')
+                            break;
+                        const source = typeof m.source === 'string' ? m.source : '';
+                        if (source.length === 0)
+                            break;
+                        const preview = typeof m.preview === 'string' ? m.preview : '';
+                        let i = 0;
+                        for (const att of steeringInjectedToAttachments(source, preview)) {
+                            yield chrome({
+                                kind: 'attachment',
+                                laneProof: MAIN,
+                                id: idOf(m, `steering-${i++}`),
+                                attachment: att,
+                            });
+                        }
                         break;
-                    const preview = typeof m.preview === 'string' ? m.preview : '';
-                    let i = 0;
-                    for (const att of steeringInjectedToAttachments(source, preview)) {
+                    }
+                    case 'workspace_changed': {
+                        if (typeof m.parentToolCallId === 'string')
+                            break;
+                        const cwd = typeof m.cwd === 'string' ? m.cwd : '';
+                        if (cwd.length === 0)
+                            break;
                         yield chrome({
                             kind: 'attachment',
                             laneProof: MAIN,
-                            id: idOf(m, `steering-${i++}`),
-                            attachment: att,
+                            id: idOf(m),
+                            attachment: { type: 'workspace_changed', cwd },
                         });
+                        break;
                     }
-                    break;
-                }
-                case 'workspace_changed': {
-                    if (typeof m.parentToolCallId === 'string')
+                    case 'prompt_suggestions': {
+                        // T57 第五处断闸(#47 矩阵 #5 同族):子流(parentToolCallId 标)的建议绝不骑主 composer。
+                        if (typeof m.parentToolCallId === 'string')
+                            break;
+                        const list = Array.isArray(m.suggestions)
+                            ? m.suggestions.filter((s) => typeof s === 'string')
+                            : [];
+                        // 空批不发(cli 同门:`if (list.length > 0)`)—— 作废由 turn 开场那一发负责,
+                        // 这里再发一次 null 会把本轮真产出的建议在极端交错下擦掉。
+                        if (list.length > 0) {
+                            yield chrome({ kind: 'prompt_suggestions', laneProof: MAIN, suggestions: list });
+                        }
                         break;
-                    const cwd = typeof m.cwd === 'string' ? m.cwd : '';
-                    if (cwd.length === 0)
+                    }
+                    case 'retry_status': {
+                        // #47 矩阵 #5:子代 lane 帧绝不骑主 spinner(无判别守卫的无条件 store 写=默认可疑)。
+                        if (typeof m.parentToolCallId === 'string')
+                            break;
+                        yield chrome({
+                            kind: 'retry_status',
+                            laneProof: MAIN,
+                            status: mapBrainStatusToRetry({
+                                phase: typeof m.phase === 'string' ? m.phase : '',
+                                ...(typeof m.detail === 'string' ? { detail: m.detail } : {}),
+                                ...(typeof m.retryInSec === 'number' ? { retryInSec: m.retryInSec } : {}),
+                            }, ctx.now()),
+                        });
                         break;
-                    yield chrome({
-                        kind: 'attachment',
-                        laneProof: MAIN,
-                        id: idOf(m),
-                        attachment: { type: 'workspace_changed', cwd },
-                    });
-                    break;
-                }
-                case 'retry_status': {
-                    // #47 矩阵 #5:子代 lane 帧绝不骑主 spinner(无判别守卫的无条件 store 写=默认可疑)。
-                    if (typeof m.parentToolCallId === 'string')
+                    }
+                    default:
                         break;
-                    yield chrome({
-                        kind: 'retry_status',
-                        laneProof: MAIN,
-                        status: mapBrainStatusToRetry({
-                            phase: typeof m.phase === 'string' ? m.phase : '',
-                            ...(typeof m.detail === 'string' ? { detail: m.detail } : {}),
-                            ...(typeof m.retryInSec === 'number' ? { retryInSec: m.retryInSec } : {}),
-                        }, ctx.now()),
-                    });
-                    break;
                 }
-                default:
-                    break;
+                // COALESCER 节拍:一个间隔至多一次 flush(同步 SSE 突发先攒着,过闸再一次泄干)。
+                if (m.type === 'stream_event') {
+                    const now = ctx.now();
+                    if ((textPending.length > 0 || thinkingPending.length > 0) && now - lastFlushAt >= flushEveryMs) {
+                        yield* drainLive();
+                        lastFlushAt = now;
+                    }
+                }
             }
-            // COALESCER 节拍:一个间隔至多一次 flush(同步 SSE 突发先攒着,过闸再一次泄干)。
-            if (m.type === 'stream_event') {
-                const now = ctx.now();
-                if ((textPending.length > 0 || thinkingPending.length > 0) && now - lastFlushAt >= FLUSH_INTERVAL_MS) {
-                    yield* drainLive();
-                    lastFlushAt = now;
+        }
+        finally {
+            // T58 — 手动 iterator 没有 for-await 的隐式 cleanup:early break(abort)或抛错都必须关上游
+            // 生成器(SSE 拆链)。正常跑完(done)不用关,上游自己结束了。
+            if (!iteratorDone) {
+                try {
+                    void iterator.return?.();
+                }
+                catch {
+                    // best-effort close — 绝不遮蔽原本的退出路径
                 }
             }
         }
-        // turn 收口(cli 尾部同序):泄尾增量 → 清 liveness → 提交尾思考 → 提交尾文本段。
+        // T59 — abort 后到此为止:不发合成终答、不做兜底(这个 turn 被打断了;CC 自己的 abort 路径
+        // 渲 InterruptedByUser chrome,那是宿主的事)。但**瞬态覆盖层必须收干净**,否则 Esc 之后
+        // 上一轮的 retry 行/思考活动行会一直挂着。
+        if (ctx.signal?.aborted) {
+            yield chrome({ kind: 'retry_status', laneProof: MAIN, status: null });
+            yield chrome({ kind: 'thinking_activity', laneProof: MAIN, active: false });
+            ctx.log?.('debug', 'turn aborted (Esc) — no terminal answer emitted');
+            return;
+        }
+        // T60 —— turn 收口(cli 尾部同序,覆盖"流结束了但没有 result 臂"的路径):
+        // 泄尾增量 → 清 liveness → 提交尾思考 → 提交尾文本段。
         yield* drainLive();
         yield chrome({ kind: 'retry_status', laneProof: MAIN, status: null });
         yield* takeThinking();
         yield* takeAnswerSegment();
+        ctx.log?.('debug', `turn done · emittedAssistantText=${emittedAssistantText} answerLen=${answer.length}`);
         void answer; // 全流无 text 臂时的兜底源(result 臂已消费);保留供调试/后续批
     }
 }