fix(herdr): 统一原生终端流与 Web 历史

[deepcoldy]

改了什么

• 将 Herdr 终端输出从 500ms 轮询切换为 terminal session observe 原生 NDJSON 流，并保留 full/delta/seq/尺寸语义。
• 在已合并的 fix(web-terminal): 修复 Herdr 只读终端小窗展示 #419 Web 终端能力上统一 managed agent attach 尺寸 ownership、光标、历史合并和 /restart 重绑定。
• 修复 full frame 被当增量追加、observer 槽位冲突误报退出、pendingData 无界增长、history 持续输出冻结等问题。
• 历史抓取改为 120ms settle + 600ms max-wait 的串行调度；无人观看时停止抓取，重连后主动刷新。
• 页面 xterm 写入/reset 串行化，WebSocket 增加背压与 resync。
• Herdr 最低版本门槛为 0.7.2，并脱敏计划文档里的内部地址。

为什么

PR #484 的原生流方向与已合并 #419 的 Web 终端实现存在强实现冲突。直接按序合并会破坏 scrollback、历史快照与 resize 生命周期。本 PR 在最新 master 上给出经两轮独立审查后的统一实现，作为 #484 的整合替代版本。

影响面

• Herdr 后端：spawn / reattach / adopt / reconnect / resize / exit 判活全链路。
• Web terminal：Herdr 历史、光标、触控滚动、重连；页面写队列的等价序列化同时覆盖 Pty/Tmux。
• 其它 CLI 与非 Herdr 后端仍走原 onData 路径。

验证

• pnpm build
• TZ=Asia/Shanghai pnpm test：583 files，9324/9324
• pnpm vitest run test/herdr-backend.e2e.ts test/worker-herdr-web-terminal.e2e.ts：11/11（真实 Herdr 0.7.3）
• Claude 三轮独立 review：最终 Approve，所有 P2/blocker 已关闭

[deepcoldy]

独立复核结论（relay + codex 交叉验证）：先别合

方向正确（原生 terminal session observe 流替代 500ms 轮询），build / 单测 / Herdr e2e 都过；但合入前有两个真 bug 需要修，且与最新 master 有内容冲突。

Bug 1：Herdr + Workflow 可能丢最终输出

src/worker.ts:4111 if (!frame?.full) captureWorkflowTranscript(data); 把所有 full 帧都排除在 workflow transcript 外。

• 测试 test/herdr-backend.test.ts 多处确认：fresh spawn 的 seq=0 首帧是 full: true（baseline）。
• 时序：agent 先 spawn → observer 后启动 → 首帧是当前整屏快照。若 CLI 在 observer 起来前已把 <WORKFLOW_OUTPUT>...</WORKFLOW_OUTPUT> 打完，这段只存在于首帧里，被跳过；之后没有 delta，workflowTranscript 永远不含 END_MARKER，maybeEmitWorkflowTranscriptOutput()（prompt_ready 时调用）不会发 final_output，workflow 一直等不到结束。
• 修复方向：区分「fresh spawn 首 baseline」（应进 transcript）和「reattach / resize 重基线」（应跳过，避免重复记账）；补一条「快速输出 workflow」e2e。

Bug 2：Web 慢客户端 resync / 新连接在累计超 1MB 后残屏

relayHerdrWebDelta 把 full baseline + 后续坐标 delta 累加到 scrollback；超 MAX_SCROLLBACK 时 scrollback = '\x1bc' + scrollback.slice(cut)，从中间裁，会把开头唯一的 full baseline 一起裁掉。

• 新连接 seed（src/worker.ts:7165）：usesHerdrSnapshotWebHistory() 对 HerdrBackend 恒为 true，直接用 scrollback 当 seed → 新客户端拿到「reset + 一截 delta 尾巴」，没被 delta 覆盖的格子空白。
• 慢客户端 resync（herdrWebNeedsResync 分支）：同样发 \x1b]1989;history;0\x07${scrollback}...，同样残屏。
• 修复方向：裁剪前先 captureCurrentScreenAsync() 生成新的权威整屏重置 scrollback，或 frame 模式超限时主动切一次 history 模式刷新；不能把 delta 尾巴当完整快照。

与 master 的冲突

git merge-tree --write-tree origin/master HEAD：

• 内容冲突（需手工解）：src/adapters/backend/herdr-backend.ts、src/worker.ts、test/herdr-backend.test.ts
• 自动合并（无 content conflict）：test/worker-pipe-initial-screen-order.test.ts

验证状态

• pnpm build：通过
• 相关单测：85/85
• Herdr 0.7.3 真实 e2e：11/11
• 全量：9322/9324（2 条失败是本机 PID 2000000 恰好存在的 smoke test，与本 PR 无关）

结论

不 Approve、不合码。建议申晗修完上述两个 bug、rebase 最新 master 解 3 个内容冲突、重跑 build + 全量 + Herdr e2e 后再复核。

此次只做审查，没有改源码、提交或合并，也没有触碰 platform 仓。