magic-agent 1.0.2 → 1.0.46

package/internal/agent/stream.go

@@ -41,6 +41,8 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"os/exec"
+	"sort"
 	"strings"
 	"time"
 )
@@ -83,6 +85,75 @@ const (
 	// 要真正作答，得把答案作为**后续 user 消息**补进去（见 EncodeAskFollowUp），
 	// 正好复用常驻会话的 --append 通道。
 	KindAsk StreamEventKind = "ask"
+	// KindTurnFailed 一轮**没有走到终帧**（引擎流被截断、没吐 result 行）。
+	//
+	// 为什么需要它（2026-10-02，对齐 agents-anywhere 的 failed_terminal_event）：
+	// 此前这条路径只有 `return fmt.Errorf("... without result line")`，
+	// 于是「已经流出去的半截正文」在事件流上永远停在 running —— 消费方
+	// （多端同步 / 历史回放）看到的是一条**悬空**的 item：既不知道它完了没有，
+	// 也不知道该显示什么。补一条终态事件，一轮就绝不会悬空。
+	//
+	// 与 KindTurnEnd 的分工：turn_end = 引擎给出了 result 行（成功收尾）；
+	// turn_failed = 引擎没给（异常收尾，带 Error / Reason）。
+	// 两者都终结「这一轮」，消费方可以统一当边界用。
+	KindTurnFailed StreamEventKind = "turn_failed"
+	// KindImage 助手产出的**完整图片块**（2026-10-10，跨引擎渲染覆盖 P0-1）。
+	//
+	// Text 字段即图片本体：`data:<media_type>;base64,<data>` 形状的 data URI，
+	// 消费方（PC 渲染层 / 历史回放）拿它直接 <img src>。
+	//
+	// 为什么独立成一种 kind：claude 的图片是 base64 内嵌的
+	//（content_block.source{media_type,data}），不进正文流 —— 以前直接丢掉，
+	// 用户看到的是「模型说画好了，界面什么都没有」。走事件落 sessionlog 后，
+	// 历史回放（按 kind 同名词表回灌渲染层）免费还原。
+	//
+	// 去重：claude 下同一张图会走两条路各出现一次 —— stream_event 的
+	// content_block_start（--include-partial-messages 下）与随后的 assistant
+	// 聚合行。emitImage 按指纹去重，只报一次（与 askSeen 同一手法）。
+	KindImage StreamEventKind = "image"
+	// KindNotice 过程提示（2026-10-10，跨引擎渲染覆盖 P0-4）：引擎侧产生的、
+	// 不属于正文但值得让用户看见的提示，目前只有一种 —— max_tokens 截断。
+	//
+	// 为什么要有它：正文在长度上限处被掐断时，用户看到的是「说到一半没了」，
+	// 没有任何解释。各引擎的截断信号可得性（有多少算多少，不硬造）：
+	//   - claude / codebuddy：流尾 message_delta.delta.stop_reason == "max_tokens"
+	//     （handleNDJSONLine 的 message_delta 分支）；
+	//   - openclaw（ACP）：收尾时的 stopReason（openclaw_acp.go 检查点）；
+	//   - llm：仅非流式 Complete() 有 finish_reason，流式是纯文本管道，无信号；
+	//   - codex：无信号。
+	//
+	// 走事件落 sessionlog 后，历史回放免费还原；前端 09 的 case "notice" 直接渲染，
+	// 不需要新分支。emit 不进 Thinking/Text 累积（见 streamAccumulator.emit：
+	// 只有 thinking/text 写累积器），单发即走。
+	KindNotice StreamEventKind = "notice"
+	// KindCommand 斜杠命令节点（2026-10-10，跨引擎渲染覆盖 P0-3）：用户输入
+	// /xxx 形态的命令时，core 合成的一对生命周期帧 —— 开跑一条（Status="running"）、
+	// 收尾一条（Status="completed"/"cancelled"/"failed"）。引擎都不上报这个生命周期，
+	// 事件由 cli/ask.go runStreamAsk 依输入形态自己补，与 user / error 同族
+	//（core 自己补的，不走引擎流）。
+	//
+	// Status 取值对齐前端 qaStatus 渲染词表（running→进行中 / completed→已完成 /
+	// cancelled·failed→失败），不复用 StreamStatus 的三值枚举 —— 那个枚举对齐的
+	// 是 item 生命周期，这里对齐的是渲染词表。前端 09 的 case "command" 用终端
+	// 图标（SquareTerminal）渲染标记行。
+	KindCommand StreamEventKind = "command"
+)
+
+// StreamStatus 事件所描述的 item 状态 —— 对齐 agents-anywhere 的
+// timeline.item_status（2026-10-02）。
+//
+// 为什么要它：delta 广播只能告诉消费方「又来了几个字」，没法告诉它
+// 「这条消息已经完整了」。多端同步时前者要客户端自己判断何时停止拼接
+// （易错：漏拼、重复拼、乱序），后者只需「覆盖到 final 为止」。
+type StreamStatus string
+
+const (
+	// StatusRunning 还在增长中（partial）。消费方应持续覆盖同一 item。
+	StatusRunning StreamStatus = "running"
+	// StatusFinal 终态：这条 item 的内容已经定型，不会再变。
+	StatusFinal StreamStatus = "final"
+	// StatusFailed 异常终态：引擎没走完就被掐断（见 KindTurnFailed）。
+	StatusFailed StreamStatus = "failed"
 )
 
 // StreamEvent 一条流式增量。
@@ -106,6 +177,58 @@ type StreamEvent struct {
 	// 有了它，调用方不必再分辨这次是 claude 的 tool_use 形态还是 control_request 形态
 	//（两种形态在 wire 上字段完全不同，见 ask.go 的 ParseAskLine）。
 	Ask *AskRequest
+
+	/* ── 状态收敛字段（2026-10-02，对齐 agents-anywhere 的 timeline item）──
+	 *
+	 * 此前的事件模型是**纯 delta 广播**：只说「又来了这几个字」，
+	 * 消费方要自己拼、自己判断何时完整。对「终端直打」够用，但撑不起
+	 * 多端同步 / 历史回放 / 断线重连 —— 那些场景里同一条消息会被
+	 * 反复投递、乱序到达，前端不得不自己去重、排序、猜终态。
+	 *
+	 * agents-anywhere 的做法（claude/timeline/stream.py + core/timeline.py）：
+	 * 事件语义是**状态收敛**而非增量广播：
+	 *   · 每个可更新 item 有**稳定 id**（引擎原生 message id 派生）
+	 *   · 每次更新带**单调递增的 revision**
+	 *   · partial 与 final 用**同一个 id**，final 只是 revision 更高的覆盖
+	 *   · 幂等公式 revision = max(item.revision, existing.revision+1)
+	 *     ⇒ 重复投递不产生新版本
+	 * 消费方于是只需要「按 (id, revision) 覆盖式 upsert」，天然幂等。
+	 *
+	 * ⚠️ **Text 的语义保持不变（仍是增量片段）** —— 这是本设计最重要的一条
+	 * 取舍。`--stream -o text` 的正文直打、sessionlog 落盘、老客户端的
+	 * 逐行拼接全都依赖它，改成整段快照会静默打断所有既有消费方。
+	 * 想做 upsert 的消费方读 Snapshot；想增量拼接的继续读 Text。
+	 * 两个字段并存，引擎层一次投影同时喂饱两类消费方。 */
+
+	// ItemID 稳定的 item 标识（timeline item id）。空串 = 本事件不参与状态收敛
+	//（老引擎 / 无法归一化身份时）。取值形如 "msg_<native message id>"。
+	//
+	// 同一轮里的 thinking / text / 工具事件共享同一个 message item id，
+	// revision 各自递增 —— 消费方按 (ItemID, Revision) upsert 即得最终全文。
+	ItemID string
+
+	// Revision 该 item 的第几个版本，从 1 起单调递增。
+	// 同一个 ItemID 下：partial 是 1..N，final 是 N+1（覆盖，不是追加）。
+	ItemRevision uint64
+
+	// Status 本事件描述的 item 状态（见 StreamStatus）。空串 = 老语义
+	//（纯增量，既无终态也无状态机），消费方可按「非空才启用收敛」处理。
+	Status StreamStatus
+
+	// Snapshot 该 item 的**当前完整内容**（累积到此刻为止），与 Text（增量）并存。
+	//
+	// 为什么已经累积了还要发增量：两类消费方要的东西不同 ——
+	// 终端直打要增量（否则重打一遍全文）；多端同步要快照（否则要自己拼，
+	// 且拼不回去的历史/乱序场景无解）。发了快照，消费方可以完全忽略 Text。
+	//
+	// 仅在 ItemID 非空时携带；Snapshot 不可靠的引擎留空（消费方回退到 delta 拼接）。
+	Snapshot string
+
+	// Error 本轮异常收尾的原因（仅 KindTurnFailed 携带）。
+	Error string
+	// Reason 根因摘要（仅 KindTurnFailed 携带），与 -o json 的失败 envelope 同源
+	//（同走 agent.ReasonOf），同一次失败在事件流与 stderr 两处的说法必然一致。
+	Reason string
 }
 
 // ToolCall 一次完整的工具调用记录（用于收尾汇总）。
@@ -218,9 +341,9 @@ func runStreamCLIEnvIn(ctx context.Context, dir string, extraEnv []string, bin s
 // runStreamCLIStdinIn = runStreamCLIEnvIn + 可给子进程喂 stdin 内容（一次性字符串）。
 func runStreamCLIStdinIn(ctx context.Context, dir string, extraEnv []string, bin string, args []string, stdin string, lineHandler func(line string) error) error {
 	if stdin == "" {
-		return runStreamCLIStdinReaderIn(ctx, dir, extraEnv, bin, args, nil, lineHandler)
+		return runStreamCLIStdinReaderIn(ctx, dir, extraEnv, bin, args, nil, nil, lineHandler)
 	}
-	return runStreamCLIStdinReaderIn(ctx, dir, extraEnv, bin, args, strings.NewReader(stdin), lineHandler)
+	return runStreamCLIStdinReaderIn(ctx, dir, extraEnv, bin, args, strings.NewReader(stdin), nil, lineHandler)
 }
 
 // runStreamCLIStdinReaderIn = 上面那个 + stdin 可以是**流**（常驻会话靠它持续喂消息）。
@@ -228,7 +351,7 @@ func runStreamCLIStdinIn(ctx context.Context, dir string, extraEnv []string, bin
 // 为什么需要流：claude/codebuddy 的 `--input-format stream-json` 允许在一个进程里
 // 持续接收 user 消息（「会话中追加需求」）。调用方给的 reader 不 EOF，子进程就一直活着；
 // reader EOF（或关闭）→ 子进程收尾退出。
-func runStreamCLIStdinReaderIn(ctx context.Context, dir string, extraEnv []string, bin string, args []string, stdin io.Reader, lineHandler func(line string) error) error {
+func runStreamCLIStdinReaderIn(ctx context.Context, dir string, extraEnv []string, bin string, args []string, stdin io.Reader, stderrOut *streamStderrBuf, lineHandler func(line string) error) error {
 	cmd := newStreamCmdIn(dir, bin, args)
 	if len(extraEnv) > 0 {
 		// Go exec 语义：重复 key 取最后一个 → extraEnv 覆盖继承值
@@ -254,7 +377,24 @@ func runStreamCLIStdinReaderIn(ctx context.Context, dir string, extraEnv []strin
 		stdoutW.Close()
 		return fmt.Errorf("stderr pipe: %w", err)
 	}
-	stderrBuf := &streamStderrBuf{}
+	// stderrOut 非空时由调用方持有同一份缓冲（它要拿 stderr 尾巴拼错误摘要，
+	// 见 streamNoResultErr）；为空就只在这里兜底收着。
+	stderrBuf := stderrOut
+	if stderrBuf == nil {
+		stderrBuf = &streamStderrBuf{}
+	}
+	/* 返回前给 stderr 的 drain 一点时间把**已到达**的内容抄进缓冲 —— 调用方
+	   （或本函数返回后的上层）立刻就要读它拼错误摘要，而 drain 是独立 goroutine，
+	   进程刚退出时它可能还没被调度。
+	   ⚠️ **有界**等待：后代进程可能还握着 stderr 写端（见下面的管道注释），
+	   无限等会把「引擎已死」变成「magic-agent 挂着不退」。 */
+	stderrDrained := make(chan struct{})
+	defer func() {
+		select {
+		case <-stderrDrained:
+		case <-time.After(300 * time.Millisecond):
+		}
+	}()
 	cmd.Stderr = stderrW
 	if err := cmd.Start(); err != nil {
 		stdoutR.Close()
@@ -266,7 +406,7 @@ func runStreamCLIStdinReaderIn(ctx context.Context, dir string, extraEnv []strin
 	notifySpawn(ctx, cmd.Process.Pid) // 会话登记表据此记住引擎子进程 pid
 	stdoutW.Close()                   // 父进程不再持有写端；EOF 只取决于子进程一侧
 	stderrW.Close()
-	go func() { defer stderrR.Close(); _, _ = io.Copy(stderrBuf, stderrR) }()
+	go func() { defer close(stderrDrained); defer stderrR.Close(); _, _ = io.Copy(stderrBuf, stderrR) }()
 
 	// 看门狗：ctx 结束 → 杀整组；否则等进程自然退出。
 	done := make(chan error, 1)
@@ -338,16 +478,25 @@ func runStreamCLIStdinReaderIn(ctx context.Context, dir string, extraEnv []strin
 	}
 }
 
-// runStreamStderrIn 启动 CLI 并把它的 **stderr 逐行回调**，收尾返回 stdout 全文与 stderr 全文。
+// runStreamLinesIn 启动 CLI，把**选定的一路**（stdout 或 stderr）逐行回调，
+// 收尾返回 stdout 全文与 stderr 全文。
 //
-// 为什么需要它（与上面几个 helper 正好相反）：其余引擎的增量走 stdout，
-// 而 dsh 的 headless 把**推理增量写到 stderr**（"dsh: reasoning:" 起头），
-// 最终正文才一次性打到 stdout。要把它接成 Streamer，就必须扫 stderr 而不是 stdout。
+// 为什么需要它（与上面几个 helper 正好相反）：其余引擎的增量走 stdout 且直接透传；
+// 而 dsh 有两种形态要扫：
+//   - `--json`：事件流在 **stdout**（streamStdout = true）；
+//   - 旧版 headless：推理增量在 **stderr**（"dsh: reasoning:" 起头），最终正文才到 stdout
+//     （streamStdout = false）。
 //
 // 管道与 Wait 的处理沿用上面同一条经验（自建管道 + 自己 drain，不让 cmd.Wait 等
 // Go 的内部拷贝 goroutine，否则后代进程握着写端时 Wait 永不返回）。
-func runStreamStderrIn(ctx context.Context, dir string, bin string, args []string, onStderrLine func(line string) error) (string, string, error) {
+//
+// extraEnv 追加到继承环境之后（重复 key 取后者）—— dsh 的权限档位就是这么下发的
+// （它没有逐调用的权限 flag，只有 DSH_PERMISSION_MODE，见 permission.go）。
+func runStreamLinesIn(ctx context.Context, dir string, extraEnv []string, bin string, args []string, streamStdout bool, onLine func(line string) error) (string, string, error) {
 	cmd := newStreamCmdIn(dir, bin, args)
+	if len(extraEnv) > 0 {
+		cmd.Env = append(cmd.Env, extraEnv...)
+	}
 
 	stdoutR, stdoutW, err := os.Pipe()
 	if err != nil {
@@ -375,34 +524,28 @@ func runStreamStderrIn(ctx context.Context, dir string, bin string, args []strin
 	stdoutW.Close()                   // 父进程不再持有写端；EOF 只取决于子进程一侧
 	stderrW.Close()
 
-	// stdout 只做收集（最终正文），不逐行回调。
+	// 选定的一路逐行扫 + 回调；另一路只做收集（最终正文 / 错误摘要）。
 	stdoutDone := make(chan error, 1)
 	go func() {
 		defer stdoutR.Close()
-		_, cerr := io.Copy(&stdoutBuf, stdoutR)
-		stdoutDone <- cerr
+		if !streamStdout {
+			_, cerr := io.Copy(&stdoutBuf, stdoutR)
+			stdoutDone <- cerr
+			return
+		}
+		stdoutDone <- scanCallbackLines(stdoutR, &stdoutBuf, onLine, cmd)
 	}()
 
-	// stderr 逐行扫 + 回调（推理增量）。
+	// stderr：streamStdout 时只收集；否则逐行扫 + 回调。
 	stderrDone := make(chan error, 1)
 	go func() {
 		defer stderrR.Close()
-		sc := bufio.NewScanner(stderrR)
-		sc.Buffer(make([]byte, 0, 64*1024), 16*1024*1024)
-		for sc.Scan() {
-			line := sc.Text()
-			stderrBuf.WriteString(line)
-			stderrBuf.WriteByte('\n')
-			if onStderrLine == nil {
-				continue
-			}
-			if herr := onStderrLine(line); herr != nil {
-				killProcessGroup(cmd)
-				stderrDone <- herr
-				return
-			}
+		if streamStdout {
+			_, cerr := io.Copy(&stderrBuf, stderrR)
+			stderrDone <- cerr
+			return
 		}
-		stderrDone <- sc.Err()
+		stderrDone <- scanCallbackLines(stderrR, &stderrBuf, onLine, cmd)
 	}()
 
 	waitErr := make(chan error, 1)
@@ -455,6 +598,26 @@ func waitDrainedBounded(ch <-chan error, d time.Duration) {
 	}
 }
 
+// scanCallbackLines 逐行扫 r（同时抄进 buf），每行回调一次；
+// 回调返回错误即杀掉整个进程组并返回该错误（与 runStreamLinesIn 的收尾约定一致）。
+func scanCallbackLines(r io.Reader, buf *bytes.Buffer, onLine func(line string) error, cmd *exec.Cmd) error {
+	sc := bufio.NewScanner(r)
+	sc.Buffer(make([]byte, 0, 64*1024), 16*1024*1024)
+	for sc.Scan() {
+		line := sc.Text()
+		buf.WriteString(line)
+		buf.WriteByte('\n')
+		if onLine == nil {
+			continue
+		}
+		if herr := onLine(line); herr != nil {
+			killProcessGroup(cmd)
+			return herr
+		}
+	}
+	return sc.Err()
+}
+
 // streamAccumulator 聚合增量与收尾 result 行。
 type streamAccumulator struct {
 	Text     strings.Builder
@@ -488,6 +651,38 @@ type streamAccumulator struct {
 	// 留空也能跑：解析本身与引擎无关，只有 header 上限之类的归一化需要它。
 	Engine string
 
+	// AggregateOnly 标记本引擎的正文走 assistant 聚合行兜底通道。
+	//
+	// 语义演变（两次实测）：
+	//   - 2026-10-01：codebuddy **只**发聚合行、不发 content_block_delta，
+	//     不开这个开关 `-o text` 实时输出全程空白。
+	//   - 2026-10-11：新版 CLI **增量与聚合行并存** —— delta 正常逐字发，
+	//     流尾再补一份 assistant 聚合行。所以这里不再是「非此即彼」，
+	//     emitAggregateText 必须与已发正文做前缀比对只发差量
+	//     （无条件重发全文 = snapshot 全文×2 = 移动端「消息显示重复」）。
+	//
+	// 由引擎显式声明，而不是「猜」（猜错就是重复输出，两种错法都很难查）。
+	AggregateOnly bool
+
+	// SanitizeTurnText 该引擎的「轮次正文清洗器」：把 result 行的**原始**
+	// result 字段整理成可以直接当正文交出去的样子。
+	//
+	// 为什么需要它（2026-10-01，codebuddy 实测）：result 行里的 result 字段是
+	// 未经处理的引擎原始输出 —— codebuddy 把思维链以 <think>…</think>
+	// 塞在同一个字符串里。于是同一轮里三个来源的"干净程度"并不一致：
+	//
+	//	acc.Text    已清洗（emit 时过 stripThinkBlock）
+	//	fin.Result  未清洗（← turn_end 直接拿它发，于是漏了）
+	//	最终正文     由调用方 stripThinkBlock(finalizeStreamText(...)) 得到，已清洗
+	//
+	// 于是 `-o json` 的 NDJSON 里会出现「text 干净、turn_end 脏」的自相矛盾。
+	// 症状极隐蔽：内容本身是对的，只是 turn_end 那一条夹着一段英文推理，
+	// 消费方（观物台把 turn_end 当轮次边界）就会把推理当成正文收进去。
+	//
+	// 由引擎声明（claude 留 nil = 原样不动），而不是在 emitTurnEnd 里对所有引擎
+	// 无脑套 think 剥离 —— 那会把合法输出里恰好出现的 <think> 字面量也切掉。
+	SanitizeTurnText func(string) string
+
 	// SessionID 流里最近见到的 session_id（system/init、assistant、result 行都带）。
 	//
 	// 为什么要它：KindAsk 事件必须能**直接接住** —— 宿主看到提问后要把用户的答案
@@ -509,6 +704,263 @@ type streamAccumulator struct {
 	// 被识别到 —— 一次是 content_block_start/stop 累积出的 tool_use（含完整 questions），
 	// 一次是随后那份聚合 assistant 消息（也带完整 input）。只该报一次。
 	askSeen map[string]bool
+
+	// imgSeen 已发过的图片指纹（imageFingerprint：长度 + 首尾采样）。
+	// 与 askSeen 同一个由来：claude 的同一张图走两条路各出现一次
+	//（stream_event 的 content_block_start 与 assistant 聚合行），只该报一次。
+	imgSeen map[string]bool
+
+	// maxTokensNoticed 本轮是否已发过 max_tokens 截断提示（2026-10-10，P0-4）。
+	// message_delta 有很多条、stop_reason 只有最后一条带值 —— 这里是防御性去重：
+	// 万一引擎推了多条 max_tokens 也只报一次（与 askSeen / imgSeen 同一手法）。
+	maxTokensNoticed bool
+
+	/* ── 状态收敛状态机（2026-10-02，见 StreamEvent 的状态收敛字段注释）──
+	 *
+	 * agents-anywhere 的 ClaudeStreamAccumulator（runtimes/claude/timeline/stream.py）
+	 * 维护三样东西，本文件照抄同一套：
+	 *   partial_message_id  稳定 item id（message_start 记原生 id 派生）
+	 *   partial_*_blocks    按 content block index 的累积文本
+	 *   partial_revision    当前 revision 计数
+	 * 终帧沿用同 id + revision+1 覆盖。 */
+
+	/* 正文与思考各一条 item（2026-10-02 修正，理由见 itemtracker.go
+	   itemLane 的注释）：共享一个 item id 时消费方覆盖式 upsert 会丢掉
+	   先到的那一半。两条 item 内嵌同一个原生 message id，合并展示时
+	   按原生 id 关联即可。 */
+	textTrack  *itemTracker
+	thinkTrack *itemTracker
+
+	// textBlocks 按 content block index 累积的正文片段。
+	textBlocks map[int]string
+	// thinkBlocks 按 content block index 累积的思考片段。
+	thinkBlocks map[int]string
+}
+
+// trackers 惰性建立两条 lane 的跟踪器（prefix 依赖 Engine，
+// 累加器是零值构造的，不能在字段声明处建）。
+func (a *streamAccumulator) trackers() trackerPair {
+	if a.textTrack == nil {
+		a.textTrack = newItemTracker(a.Engine, laneText)
+	}
+	if a.thinkTrack == nil {
+		a.thinkTrack = newItemTracker(a.Engine, laneThink)
+	}
+	return trackerPair{text: a.textTrack, think: a.thinkTrack}
+}
+
+/* ── 稳定 item id 的建立与降级链 ──────────────────────────────────
+ *
+ * agents-anywhere 的规则（claude/timeline/messages.py stable_message_item_id）：
+ * 从 message_start 记下的原生 id 派生 `claude_msg_<hash>`，**跨事件稳定**。
+ * 拿不到 message_start.id 时它「丢弃并 warning，不猜」。
+ *
+ * 我们同理，但降级链多两级（引擎协议不保证每次都有原生 id）：
+ *
+ *	1. 原生 message id（claude/codebuddy 实测必有，贯穿整条消息）
+ *	2. 本轮内稳定的**序号**（首个 text/thinking 块出现时定下，
+ *	   之后本轮不再变）—— 同一轮内稳定，重放时靠 seq 也能推回同一个
+ *
+ * ⚠️ 降级到 2 时**绝不能**每帧新造一个 id（否则一条消息被拆成 N 个 item），
+ * 所以序号在首次建立后写进 tracker.itemID，之后只读不重算。 */
+
+// beginMessage 声明一条新 assistant message 开始，清空块桶。
+//
+// 为什么必须切：一轮里可能有**多条** assistant message（工具调用后
+// 继续对话，每次 tool_result 之后都是新的 message_start）。不切的话它们
+// 共用一个 item id，前一条被后一条覆盖 —— 症状是「只看到最后一段回复」。
+//
+// 与 agents-anywhere 同动作（runtimes/claude/timeline/stream.py:35-36 在
+// message_start 里 clear() 块桶并把 revision 归零），这里是封装。
+func (a *streamAccumulator) beginMessage(nativeID string) {
+	p := a.trackers()
+	p.text.Begin(nativeID)
+	p.think.Begin(nativeID)
+	a.textBlocks = nil
+	a.thinkBlocks = nil
+}
+
+// observeNativeMessageID 从任意 NDJSON 行里捞出原生 assistant message id。
+//
+// 2026-10-02 实测（claude stream-json 抓包）：message_start 事件里
+// event.message.id 与后续 assistant 聚合行 message.id **完全一致**，
+// 且整条消息期间不变 —— 所以两条路任一先到都能定下同一个 id。
+func (a *streamAccumulator) observeNativeMessageID(line string) {
+	var probe struct {
+		Type    string `json:"type"`
+		Message struct {
+			ID string `json:"id"`
+		} `json:"message"`
+		Event struct {
+			Type    string `json:"type"`
+			Message struct {
+				ID string `json:"id"`
+			} `json:"message"`
+		} `json:"event"`
+	}
+	if json.Unmarshal([]byte(line), &probe) != nil {
+		return
+	}
+	// message_start = 一条新 assistant message 开始：切 item、记原生 id。
+	// 必须在事件路由**之前**做（message_start 早于所有 content_block_delta），
+	// 否则新消息的第一个 delta 会挂到上一条消息的 item 上。
+	if probe.Event.Type == "message_start" {
+		nativeID := probe.Event.Message.ID
+		if nativeID == "" && probe.Type == "assistant" {
+			nativeID = probe.Message.ID
+		}
+		a.beginMessage(nativeID)
+		return
+	}
+	// 聚合 assistant 行也带 message.id（实测与 message_start 的 id 一致），
+	// 作为 message_start 缺失时定下 id 的第二条路。
+	if probe.Type == "assistant" && probe.Message.ID != "" {
+		p := a.trackers()
+		p.text.Note(probe.Message.ID)
+		p.think.Note(probe.Message.ID)
+	}
+}
+
+// appendBlock 往某个 index 累积文本块。
+func (a *streamAccumulator) appendBlock(store map[int]string, index int, text string) {
+	if text == "" || store == nil {
+		return
+	}
+	store[index] += text
+}
+
+// joinBlocks 按 index 升序拼接所有块（与到达顺序无关）。
+func (a *streamAccumulator) joinBlocks(store map[int]string) string {
+	if len(store) == 0 {
+		return ""
+	}
+	idx := make([]int, 0, len(store))
+	for i := range store {
+		idx = append(idx, i)
+	}
+	sort.Ints(idx)
+	var sb strings.Builder
+	for _, i := range idx {
+		sb.WriteString(store[i])
+	}
+	return sb.String()
+}
+
+// emit 聚合并转发一条增量（基础版本：thinking / text）。
+//
+// 两种模式并存（2026-10-02）：
+//   - OnEvent == nil：不发事件，只累积到 Text / Thinking（老行为）。
+//   - 已建立 item：Text 仍带增量（**不破坏**终端直打与老客户端），
+//     同时带 ItemID / ItemRevision / Status / Snapshot 四元组，
+//     消费方按 (ItemID, Revision) upsert 即得状态收敛。
+func (a *streamAccumulator) emit(kind StreamEventKind, text string) {
+	switch kind {
+	case KindThinking:
+		a.Thinking.WriteString(text)
+	case KindText:
+		a.Text.WriteString(text)
+	}
+	if a.OnEvent == nil {
+		return
+	}
+	ev := StreamEvent{Kind: kind, Text: text}
+	if kind == KindThinking || kind == KindText {
+		a.decorateTextEvent(&ev, kind)
+	}
+	a.OnEvent(ev)
+}
+
+// decorateTextEvent 给 thinking/text 事件补上状态收敛四元组。
+//
+// 累积策略：**整段 snapshot**（不是增量片段）—— 与 agents-anywhere 一致。
+// 消费方覆盖式 upsert，天然去重，不需要「先删 partial 再插 final」的顺序逻辑。
+func (a *streamAccumulator) decorateTextEvent(ev *StreamEvent, kind StreamEventKind) {
+	/* snapshot 从「按 content block index 升序拼接的块」取，而不是从
+	   到达顺序累积的 builder 取。区别是实质性的：一条消息里正文可能分散
+	   在多个 text 块，而块的**到达顺序**不保证等于 index 顺序
+	   （实测：index=1 的块先到、index=0 的块后到是可能的）。
+	   按到达顺序拼会给消费方一份顺序错乱的正文，而且错得很隐蔽 ——
+	   内容都在，只是读起来不对。 */
+	if kind == KindThinking {
+		a.trackers().think.nextWith(StatusRunning, a.joinBlocks(a.thinkBlocks)).apply(ev)
+		return
+	}
+	a.trackers().text.nextWith(StatusRunning, a.joinBlocks(a.textBlocks)).apply(ev)
+}
+
+// emitTextDelta 累积一个内容块的增量并发出带状态收敛元数据的事件。
+//
+// index 来自 claude 的 content_block index（-1 = 协议没给，如 trae /
+// codebuddy 聚合行）。按 index 分桶累积而不是一路 append，是因为
+// 一条 assistant 消息里正文可能分散在多个 text 块，而块的**到达顺序**
+// 不保证等于 index 顺序（实测 thinking=0 先到、text=1 后到，但反过来也可能）。
+func (a *streamAccumulator) emitTextDelta(index int, kind StreamEventKind, text string) {
+	if text == "" {
+		return
+	}
+	if a.textBlocks == nil {
+		a.textBlocks = make(map[int]string)
+	}
+	if a.thinkBlocks == nil {
+		a.thinkBlocks = make(map[int]string)
+	}
+	store := a.textBlocks
+	if kind == KindThinking {
+		store = a.thinkBlocks
+	}
+	a.appendBlock(store, index, text)
+	a.emit(kind, text)
+}
+
+// emitAggregateText 从 assistant 聚合行发正文（AggregateOnly 引擎专用）。
+//
+// ⚠️ 与 emitTextDelta 的**关键区别**：聚合行给的是**整条消息的全文**，
+// 不是增量。所以 snapshot 是「整体替换」而不是「追加」——
+// 追加会得到 "你好你好"（同一份内容被数了两遍），这正是 codebuddy 路径
+// 最容易踩的坑。
+//
+// 2026-10-11 实测（新版 CLI）：codebuddy 的增量与聚合行**并存**了——
+// stream_event 的 content_block_delta 正常逐字发，流尾再补一份 assistant
+// 聚合行（2026-10-01「只发聚合行」的前提已失效）。若仍无条件把聚合行
+// 全文当增量 emit，两处各重复一份：
+//   - a.Text 多追一份全文（终端直打重复）；
+//   - textBlocks 里「增量桶 + 0 号聚合桶」并存，joinBlocks 拼出全文×2
+//     进 snapshot —— 消费方按 (item_id, revision) upsert 后整条消息
+//     显示两遍（移动端「消息显示重复」的根因）。
+//
+// 所以先与已累积正文做前缀比对：完全一致静默收敛、多尾巴只补差量。
+// 旧版 CLI（聚合行是正文唯一来源）行为不变：accumulated 为空时原样发。
+func (a *streamAccumulator) emitAggregateText(full string) {
+	if full == "" {
+		return
+	}
+	if a.textBlocks == nil {
+		a.textBlocks = make(map[int]string)
+	}
+	accumulated := a.joinBlocks(a.textBlocks)
+	var delta string
+	switch {
+	case accumulated == "":
+		// 真 AggregateOnly（旧版 CLI / 首条聚合行）：聚合行是正文唯一
+		// 来源，原样发 —— 否则 `-o text` 实时输出全程空白。
+		delta = full
+	case full == accumulated:
+		// 增量已发过同一份全文（新版 CLI 的流尾聚合行）：静默收敛，
+		// 不补发 —— 补发就是「消息显示重复」。
+	case strings.HasPrefix(full, accumulated):
+		// 聚合行比已发增量多尾巴（增量被截断等）：只补差量。
+		delta = strings.TrimPrefix(full, accumulated)
+	default:
+		// 与已发内容对不上：按「下一条独立聚合行」处理（多条聚合行
+		// 依次到达的旧形态），整段替换并照发 —— 覆盖语义不回归。
+		delta = full
+	}
+	// 无论哪条路，桶都收敛为单份全文：增量桶（可能散在多个 index）与
+	// 0 号聚合桶不能并存，否则 joinBlocks 拼出全文×2。
+	a.textBlocks = map[int]string{0: full}
+	if delta != "" {
+		a.emit(KindText, delta)
+	}
 }
 
 // toolUseOrphanGuard 安全释放：若 content_block_stop 到来但 openToolName 为空，
@@ -628,6 +1080,12 @@ func (a *streamAccumulator) handleNDJSONLine(line string) (isResult bool, err er
 			a.OnSessionID(probe.SessionID)
 		}
 	}
+	/* 原生 assistant message id（状态收敛的锚点，2026-10-02）。
+	   必须**在事件路由之前**观察：message_start 早于所有 content_block_delta，
+	   在它之后才建立 item id 的话，前几个 delta 会落到「序号降级」id 上。
+	   实测（claude 抓包）：message_start.event.message.id 与 assistant 聚合行的
+	   message.id 一致，所以两条路都能定下同一个 id。 */
+	a.observeNativeMessageID(line)
 
 	switch probe.Type {
 	case "result":
@@ -642,12 +1100,22 @@ func (a *streamAccumulator) handleNDJSONLine(line string) (isResult bool, err er
 		// trae: delta.content 直出增量
 		var se struct {
 			Event struct {
-				Type         string `json:"type"`
+				Type    string `json:"type"`
+				Message struct {
+					ID string `json:"id"`
+				} `json:"message"`
 				ContentBlock struct {
 					Type      string `json:"type"`
 					Name      string `json:"name"`
 					ID        string `json:"id"`
 					ToolUseID string `json:"tool_use_id"`
+					// Source 图片块的载体（type=image 时必有）：base64 内嵌，
+					// start 一次到位、没有 delta（与 tool_use 的 input_json_delta 不同）。
+					Source struct {
+						Type      string `json:"type"`
+						MediaType string `json:"media_type"`
+						Data      string `json:"data"`
+					} `json:"source"`
 				} `json:"content_block"`
 				Index int `json:"index"`
 				Delta struct {
@@ -689,6 +1157,13 @@ func (a *streamAccumulator) handleNDJSONLine(line string) (isResult bool, err er
 					a.openResultID = se.Event.ContentBlock.ID
 				}
 				a.expectingResultStart = true
+			case "image":
+				// 图片块（P0-1）：content_block_start 一次到位（source 已含完整
+				// base64，不会有 delta）。发 KindImage（text = data URI）；
+				// 与随后聚合行里的同一张图靠 emitImage 的指纹去重。
+				if uri := imageDataURI(se.Event.ContentBlock.Source.MediaType, se.Event.ContentBlock.Source.Data); uri != "" {
+					a.emitImage(uri)
+				}
 			}
 
 		case "content_block_delta":
@@ -714,12 +1189,14 @@ func (a *streamAccumulator) handleNDJSONLine(line string) (isResult bool, err er
 				a.flushToolResult(d.Text)
 			case d.Type == "thinking_delta" || d.Thinking != "":
 				if d.Thinking != "" {
-					a.emit(KindThinking, d.Thinking)
+					// 按 content block index 累积：思考与正文可能分处不同块，
+					// snapshot 必须按 index 拼，不能按到达顺序 append。
+					a.emitTextDelta(se.Event.Index, KindThinking, d.Thinking)
 				}
 			case d.Type == "text_delta" || d.Text != "":
 				if d.Text != "" {
 					if cbType == "" || cbType == "text" {
-						a.emit(KindText, d.Text)
+						a.emitTextDelta(se.Event.Index, KindText, d.Text)
 					}
 				}
 			}
@@ -735,8 +1212,9 @@ func (a *streamAccumulator) handleNDJSONLine(line string) (isResult bool, err er
 		}
 
 		// trae delta.content 直出增量（无 thinking / tool 通道）。
+		// index 恒为 -1（协议不给），单桶累积 = 整段拼接，与到达顺序一致。
 		if c := se.Delta2.Content; c != "" && se.Delta2.Role == "assistant" {
-			a.emit(KindText, c)
+			a.emitTextDelta(-1, KindText, c)
 		}
 
 	case "assistant":
@@ -755,6 +1233,23 @@ func (a *streamAccumulator) handleNDJSONLine(line string) (isResult bool, err er
 		if req, ok := ParseAskLine(a.Engine, line); ok {
 			a.emitAsk(req)
 		}
+		/* AggregateOnly 引擎（2026-10-01，codebuddy 实测）：它**不发**
+		   content_block_delta，正文只出现在这份聚合行里。若不在这里 emit，
+		   `-o text` 的实时 stdout 会全程空（用户看到「转圈然后什么都没有」），
+		   只有 json 模式收尾的 result 行才有正文。
+		   claude/trae 走 stream_event 增量，这里再 emit 会**重复输出**，
+		   所以由引擎显式声明（见 streamAccumulator.AggregateOnly）。 */
+		if a.AggregateOnly {
+			if txt := assistantLineText(line); txt != "" {
+				// 与收尾路径同一个过滤器：codebuddy 会把推理以 <think>…</think>
+				// 的形式塞进正文，不剥的话实时输出里会混进英文推理。
+				a.emitAggregateText(stripThinkBlock(txt))
+			}
+		}
+		// 聚合行里的 image 块（P0-1）：claude 在 content_block_start 与聚合行各发
+		// 一次（emitImage 的指纹去重兜住），没开 partial 的路径则只在聚合行出现
+		// —— 所以这里**无条件扫**，不能挂在 AggregateOnly 下面。
+		a.emitImagesFromAssistantLine(line)
 
 	case "control_request":
 		// SDK 层请求（宿主自己实现了 canUseTool 回调时才会出现）：
@@ -776,6 +1271,27 @@ func (a *streamAccumulator) handleNDJSONLine(line string) (isResult bool, err er
 		// 这里把 tool_result 文本回填到对应的 ToolCall.Result，并 emit 一条
 		// KindToolResult 事件（id 与之关联的 tool_use 相同）。
 		a.handleUserToolResult(line)
+
+	case "message_delta":
+		/* 流式收尾信号（2026-10-10，跨引擎渲染覆盖 P0-4）：claude / codebuddy 在
+		   --include-partial-messages 下，流尾会推
+		     {"type":"message_delta","delta":{"stop_reason":"max_tokens",...}}
+		   生成中 stop_reason 为空，只有最后一条带值。"max_tokens" = 本轮输出在
+		   长度上限处被掐断 —— 正文戛然而止，用户看到的是「说到一半没了」，却没有任何
+		   解释。转成一条 KindNotice（前端 09 的 case "notice" 渲染成时钟标记行），
+		   落盘后历史回放同样可见。
+		   其他引擎的截断信号：openclaw(ACP) 在收尾检查 stopReason（openclaw_acp.go）；
+		   llm 仅非流式有 finish_reason；codex 无信号 —— 没信号的引擎就是「截断了
+		   也不知道」，这是协议边界，不硬造。 */
+		var md struct {
+			Delta struct {
+				StopReason string `json:"stop_reason"`
+			} `json:"delta"`
+		}
+		if json.Unmarshal([]byte(line), &md) == nil && md.Delta.StopReason == "max_tokens" && !a.maxTokensNoticed {
+			a.maxTokensNoticed = true
+			a.emit(KindNotice, "本轮输出在 max_tokens 上限处被截断")
+		}
 	}
 	return false, nil
 }
@@ -859,24 +1375,242 @@ func extractToolResultText(raw json.RawMessage) string {
 	return ""
 }
 
-// emit 聚合并转发一条增量（基础版本：thinking / text）。
-func (a *streamAccumulator) emit(kind StreamEventKind, text string) {
-	switch kind {
-	case KindThinking:
-		a.Thinking.WriteString(text)
-	case KindText:
-		a.Text.WriteString(text)
+// assistantLineText 从 assistant 聚合行里取出纯文本正文。
+//
+// 行形状（claude / codebuddy 同族）：
+//
+//	{"type":"assistant","message":{"content":[{"type":"text","text":"…"}]}}
+//
+// content 可能是字符串（少见）或块数组。tool_use / tool_result 块跳过 ——
+// 它们由 content_block_* 与 user 消息两条路负责，不在这里重复发。
+// 嵌套的 thinking 块也跳过（codebuddy 会把推理塞在 result 字符串里，
+// 由 codebuddy.go 的 stripThinkBlock 在收尾时整段剥离）。
+func assistantLineText(line string) string {
+	var msg struct {
+		Message struct {
+			Content json.RawMessage `json:"content"`
+		} `json:"message"`
 	}
-	if a.OnEvent != nil {
-		a.OnEvent(StreamEvent{Kind: kind, Text: text})
+	if err := json.Unmarshal([]byte(line), &msg); err != nil {
+		return ""
+	}
+	raw := msg.Message.Content
+	if len(raw) == 0 {
+		return ""
+	}
+	// 形态 1：content 直接是字符串。
+	var s string
+	if err := json.Unmarshal(raw, &s); err == nil {
+		return s
+	}
+	// 形态 2：块数组，只取 type=="text" 的 text 拼接。
+	var blocks []struct {
+		Type string `json:"type"`
+		Text string `json:"text"`
+	}
+	if err := json.Unmarshal(raw, &blocks); err != nil {
+		return ""
+	}
+	var sb strings.Builder
+	for _, b := range blocks {
+		if b.Type == "text" && b.Text != "" {
+			if sb.Len() > 0 {
+				sb.WriteString("\n")
+			}
+			sb.WriteString(b.Text)
+		}
+	}
+	return sb.String()
+}
+
+// imageDataURI 把图片块的 source 字段拼成 data URI。
+// media_type 缺省按 PNG 兜底；data 为空返回空串（调用方跳过）。
+func imageDataURI(mediaType, data string) string {
+	if data == "" {
+		return ""
+	}
+	if mediaType == "" {
+		mediaType = "image/png"
+	}
+	return "data:" + mediaType + ";base64," + data
+}
+
+// imageFingerprint 图片去重指纹：长度 + 首尾 24 字节采样。
+// 完整哈希当然更稳，但这里的输入是**同一张图走了两条路** —— 两条路给的
+// 字节完全一致，这个采样已足够判同，还省去对几百 KB base64 做两次哈希。
+func imageFingerprint(uri string) string {
+	n := len(uri)
+	head := uri
+	if len(head) > 24 {
+		head = head[:24]
+	}
+	tail := ""
+	if n > 48 {
+		tail = uri[n-24:]
+	}
+	return fmt.Sprintf("%d|%s|%s", n, head, tail)
+}
+
+// emitImage 发一张助手图片（KindImage，text = data URI），按指纹去重。
+//
+// 为什么必须去重：claude 的同一张图会**走两条路**各出现一次 ——
+// stream_event 的 content_block_start 与随后的 assistant 聚合行
+// （与 askSeen 的双路去重同一个由来）。不去重的话 PC 端同一张图画两张。
+func (a *streamAccumulator) emitImage(uri string) {
+	if uri == "" {
+		return
+	}
+	key := imageFingerprint(uri)
+	if a.imgSeen == nil {
+		a.imgSeen = make(map[string]bool)
+	}
+	if a.imgSeen[key] {
+		return
+	}
+	a.imgSeen[key] = true
+	a.emit(KindImage, uri)
+}
+
+// emitImagesFromAssistantLine 从 assistant 聚合行里抽出 image 块并 emit。
+//
+// 块形状（claude / codebuddy 同族）：
+//
+//	{"type":"assistant","message":{"content":[
+//	  {"type":"image","source":{"type":"base64","media_type":"image/png","data":"…"}}]}}
+//
+// claude 开了 --include-partial-messages 时这张图已在 content_block_start
+// 发过一次（emitImage 去重兜住）；没开（带附件的非流式路径）时这里是唯一入口，
+// 所以这条路径必须无条件走，不能挂在 AggregateOnly 下面。
+func (a *streamAccumulator) emitImagesFromAssistantLine(line string) {
+	var msg struct {
+		Type    string `json:"type"`
+		Message struct {
+			Content []struct {
+				Type   string `json:"type"`
+				Source struct {
+					Type      string `json:"type"`
+					MediaType string `json:"media_type"`
+					Data      string `json:"data"`
+				} `json:"source"`
+			} `json:"content"`
+		} `json:"message"`
+	}
+	if jerr := json.Unmarshal([]byte(line), &msg); jerr != nil || msg.Type != "assistant" {
+		return
+	}
+	for _, b := range msg.Message.Content {
+		if b.Type != "image" {
+			continue
+		}
+		if uri := imageDataURI(b.Source.MediaType, b.Source.Data); uri != "" {
+			a.emitImage(uri)
+		}
 	}
 }
 
 // emitTurnEnd 发一轮结束事件：text = 该轮正文（引擎 result 行的 result），
 // sessionID = 该轮的会话 id（见 StreamEvent.SessionID 的说明）。
+//
+// text 会先过一遍 SanitizeTurnText（由引擎声明的清洗器）——
+// 不然这里发出去的是引擎**原始** result，与同一轮的 text / result 事件不一致
+// （codebuddy 的 <think> 泄漏正是从这条路出去的，见 SanitizeTurnText 的注释）。
 func (a *streamAccumulator) emitTurnEnd(text, sessionID string) {
 	if a.OnEvent == nil {
 		return
 	}
-	a.OnEvent(StreamEvent{Kind: KindTurnEnd, Text: text, SessionID: sessionID})
+	if a.SanitizeTurnText != nil {
+		text = a.SanitizeTurnText(text)
+	}
+	ev := StreamEvent{Kind: KindTurnEnd, Text: text, SessionID: sessionID}
+	/* 终帧 = 状态收敛的**最后一次 upsert**：沿用与 partial 同一个 ItemID、
+	   revision 再 +1、Status 标 final。消费方按 (ItemID, Revision) 覆盖即可，
+	   不需要「先删 partial 再插 final」这种有顺序要求的逻辑（agents-anywhere
+	   的做法，见 claude/timeline/stream.py next_final_revision）。
+	   Snapshot 用 result 行的正文而非累积分片 —— 引擎给出的 result 是权威值，
+	   与增量拼接有出入时以它为准（claude 的 result 行 = 完整正文；codebuddy 的
+	   result 行还要过 stripThinkBlock，上面已过）。
+
+	   ⚠️ 只收尾**正文** lane：result 行是整条消息的正文，不含思考链。
+	   思考 lane 已经在最后一个 thinking_delta 上收到过内容，此后不会再增长；
+	   若也给它发 final，消费方会看到一条「内容中途消失」的 final（快照回退成空），
+	   反而制造出比不收尾更糟的状态。想标记思考已结束，靠消费方见到 result
+	   事件后停止等待即可 —— 它拿得到 turn 级的终态信号。 */
+	if attrs, ok := a.trackers().finalize(text); ok {
+		attrs.apply(&ev)
+	}
+	a.OnEvent(ev)
+}
+
+// emitTurnFailed 补一条「本轮异常收尾」事件（引擎没给 result 行）。
+//
+// 对齐 agents-anywhere 的 failed_terminal_event（claude/turns/lifecycle.py）：
+// 流被截断也**必须**发终态事件，绝不让一轮悬空。
+//
+// 为什么这条不能省（2026-10-02）：此前这条路径只有 return error，
+// 于是「已经流出去、正打到一半」的正文在事件流上永远停在 running ——
+// 多端同步的客户端看到的是一个既不增长也不结束的 item，
+// 只能靠超时猜；历史回放更糟：那一条永远显示「生成中」。
+//
+// 语义与 KindTurnEnd 的分工：
+//
+//	turn_end    = 引擎给出了 result 行（成功收尾）
+//	turn_failed = 引擎没给（异常收尾），带 Error / Reason
+func (a *streamAccumulator) emitTurnFailed(sessionID string, err error) {
+	if a.OnEvent == nil || err == nil {
+		return
+	}
+	ev := StreamEvent{
+		Kind:      KindTurnFailed,
+		SessionID: sessionID,
+		Error:     err.Error(),
+		Reason:    ReasonOf(err),
+		Status:    StatusFailed,
+	}
+	// 已建立 item 时把失败也挂到同一个 item 上：partial 的内容仍然存在，
+	// 只是这条 item 不会再更新了（Status=failed 明确终止增长）。
+	if attrs, ok := a.trackers().failText(a.joinBlocks(a.textBlocks)); ok {
+		attrs.apply(&ev)
+	}
+	a.OnEvent(ev)
+}
+
+// emitLimitNoticeFailed 一轮的正文其实是供应商的「限流 / 额度通告」时的终态（见 limitnotice.go）。
+//
+// 与 emitTurnFailed 的分工：那条是「引擎**没给** result 行」（协议没跑完）；这条是
+// 「**给了** result 行，但正文是一条通告」（引擎拿 200 + 一段正文回来的，本质仍是失败）。
+// 两者都发 KindTurnFailed —— 消费方只需认一种失败终态，不必知道上游是从哪一步看出来的。
+// 差别在三个字段：
+//
+//	· Error / Reason = 通告原文（它就是用户此刻唯一有用的信息：谁限流了、什么时候恢复）；
+//	· Text           = **剥掉通告之后的正文** —— 消费方拿它覆盖气泡，流式时已经拼进去的
+//	                   那半句通告也随之被擦掉（这正是用户报障要的效果）。
+//
+// ⚠️ 必须在 emitTurnEnd **之前**判（调用方在 streamjson.go 的 result 分支里就是这么做的）：
+// turn_end 的语义是「这一轮成功收尾」，先发出去就成了假成功。
+func (a *streamAccumulator) emitLimitNoticeFailed(sessionID, notice, body string) {
+	if a.OnEvent == nil {
+		return
+	}
+	ev := StreamEvent{
+		Kind:      KindTurnFailed,
+		Text:      body,
+		SessionID: sessionID,
+		Error:     notice,
+		Reason:    notice,
+		Status:    StatusFailed,
+	}
+	/* 快照 = 剥掉通告的正文；正文为空（这一轮引擎只回了通告）时退回**累积正文** ——
+	   引擎把通告混在最后一条 assistant 消息里时，那里面也夹着它，再判一次剥掉。
+	   （累积正文里判不出来就原样留着：宁可多留一句话，也不把用户真看过的正文抹成空。） */
+	snap := strings.TrimSpace(body)
+	if snap == "" {
+		snap = a.joinBlocks(a.textBlocks)
+		if _, b, hit := splitLimitNotice(snap); hit {
+			snap = b
+		}
+	}
+	if attrs, ok2 := a.trackers().failText(snap); ok2 {
+		attrs.apply(&ev)
+	}
+	a.OnEvent(ev)
 }