docs: guard workbench realtime regression

docs/reference/observability.md

@@ -25,6 +25,16 @@ Web/Workbench trace、Web 哨兵和 `web-probe observe` 的人工判定入口以
 
 Web 哨兵 dashboard/API 展示问题的第一事实源是 sentinel runner 的 `/api/overview`、`/api/runs`、`/api/runs/{id}`、`/api/findings` 和 `web-probe sentinel dashboard verify|screenshot` 远程浏览器证据。OTel/Tempo 查询不到 `hwlab-web-probe-sentinel` service span 或具体 `sentinel-run-*` id 时，只能说明当前 instrumentation 或保留窗口没有覆盖这条 dashboard/API 路径；不得因此把 UI/API 口径问题判为已追穿，也不得阻塞已由 API/DOM 证据定位的修复。需要继续追 runner 内部链路时，应把缺少 Web 哨兵 span 作为 instrumentation 问题登记到对应治理 issue。
 
+## Workbench Request Storm And Freeze
+
+Workbench 请求风暴和浏览器无响应的根因调查必须同时使用 OTel、web-probe artifact 和前端 runtime 诊断，不能只看 provider 是否成功或单个 REST route 是否返回 200。最小证据应包含同一用户动作的 `traceId/sessionId/turnId` 或脱敏 scoped key、request family 计数、SSE transport state、recovery action、refresh queue/single-flight 状态、browser memory/freeze sample、observer/run/report SHA，以及用户页面是否仍可操作。缺少其中某个观测面时，先补观测或记录 instrumentation gap，再给出根因结论。
+
+OTel 结论必须区分执行完成与可见投影完成。若 AgentRun/provider span、`turn_status_read` 或 projection write 显示 completed，但 Workbench UI 的 trace rows、final response 或 timeline 为空，这不是 provider 失败的充分证据；应继续检查 Workbench read model、projection revision、SSE cursor replay、trace event page、runtime reducer 和 request fan-out。相反，若 OTel 显示 submit/admission/dispatch/provider 已失败，则 web-probe 的空 UI 只是用户可见症状，不能把根因改写成前端布局或 dashboard 问题。
+
+请求风暴的判定重点是同一 scoped key 或同一 transport error 是否重复触发多个请求族，尤其是 session/message/turn/trace/health 互相拉起、并发重复或 error handler 递归。修复必须让所有恢复动作通过 Workbench realtime SPEC 定义的 keyed queue、single-flight、bounded recovery action 和 typed error 诊断；不得通过增加轮询间隔、隐藏错误、自动刷新页面、减少采样、关闭 web-probe 检测或把红灯降级为 warning 来消除现象。
+
+浏览器 freeze/blocker 的监控阈值、采样间隔和 kill policy 只从 YAML/source-of-truth 读取。调查报告只写字段族、采样来源、baseline 计算方式和可复测入口，不在文档或源码中复制具体数值。页面级有效内存应按 page/page epoch baseline 后增长量解释；多页面或 Chromium 启动基础成本是观测 baseline，不是 Workbench 应用内存泄漏的替代根因。
+
 ## CLI Logs
 
 异步 job 的 stdout 和 stderr 位于 `.state/jobs/`。`job|jobs list` 默认只返回最新 50 条摘要，并为已知异步工作流返回轻量 `progress.summary`；`job status <id>` 与兼容别名 `jobs get/read <id>` 会返回结构化 `progress` 与有限尾部，避免输出爆炸，同时保留完整日志文件路径便于继续排查。实现必须只读取日志尾部字节，不得先把完整 job 日志读入 CLI 内存；长时命令的阶段、关键对象名和下一步查询命令应优先沉淀到 `progress`，不能要求调用者先阅读完整日志才能知道是否卡在提交、构建、发布或观测阶段。