docs: guard workbench realtime regression

docs/reference/frontend.md

@@ -59,6 +59,14 @@ frontend shell 必须把左侧主模块与顶部子标签编译为统一的 URL
 - 浏览器直开、刷新、`history.back()` / `history.forward()`、点击总览 drilldown 卡片、点击左侧边栏、点击顶部标签都必须走同一个路由状态机；不得出现“页面内容切换了，但 URL 没变”或“URL 变了，但 shell 仍停在旧 tab”的分裂状态。
 - frontend Bun server 必须把这些模块前缀下的深链接路由作为 SPA 入口返回同一个 `index.html` 和同一个 UniDesk shell；实现上允许统一把非静态资源路径都回到同一个 shell，但判定标准是公网直开 `/ops/status/`、`/nodes/docker/`、`/app/pipeline/`、`/app/code-queue/` 等深链接时都不得 404，且必须和从主页导航进入时一样显示左侧主模块边栏、顶部状态栏、顶部子标签和完整业务页面。禁止为某个用户服务 deep link 返回缺少 UniDesk shell 的独立/standalone bundle；新增应用服务、普通页面和性能优化入口也必须满足“直开 URL 与站内导航同壳同页”的一致性要求。
 
+## Workbench Runtime Guard
+
+Workbench 卡死、浏览器内存上涨、SSE 断线后 REST 请求风暴、刷新后消息堆叠、跨 session/trace 串线和 final response 投影缺失都属于 Workbench 运行面或唯一投影问题，权威规格是 [Workbench实时运行面](../../project-management/PJ2026-01/specs/PJ2026-0106050514-workbench-realtime-runtime.md) 与 [Workbench唯一投影](../../project-management/PJ2026-01/specs/PJ2026-0104010803-workbench-unique-projection.md)。修复方向必须优先回到 Workbench runtime、projection writer/finalizer、read model、SSE/REST contract、Vue store/reducer 和共享 runtime 模块；不得通过降低 Playwright/Chromium 能力、减少 web-probe 采样、自动刷新页面、切换 session repair、吞掉 submit 失败或把错误降级为提示文案来让 smoke 变绿。
+
+Workbench 前端的 SSE、REST gap-fill、health probe、session refresh、trace refresh、storage、scroll 和 timeline row 更新必须经过统一 runtime 模块：typed error、scoped key、refresh queue/single-flight、SSE transport、timeline row model、safe storage、scroll runtime 和 health runtime。新增 `watch`、`setInterval`、visibility handler、EventSource error handler 或组件级 `fetch` 时，必须先确认是否能接入这些模块；不能在组件、store 或 analyzer 中再散写一套 retry、防抖、补洞、缓存、排序或 root-cause 逻辑。
+
+当线上 web-probe 或哨兵发现请求风暴或浏览器无响应时，web-probe 是证据来源，不是业务修复目标。浏览器内存预算和 kill policy 的数值由 YAML/source-of-truth 控制，判定应按每个 page/page epoch 的 baseline 后有效内存和响应性证据；多页面启动的基础 RSS 不得被当成应用请求风暴的根因，也不得以压低 web-probe baseline 作为 Workbench 修复。
+
 ## Overview Task Drilldown
 
 `态势总览` 中的 `待处理任务` 指标必须可点击进入任务调度的 `待处理任务` 子标签，展示具体 queued、dispatched、running 任务的状态、Provider、已等待时间、payload 摘要和显式 `查看原始JSON` 操作。总览不得只给出无法追溯的数字；当后台把超时未终态任务转为 failed 后，待处理指标应回落，历史记录仍可在任务历史和执行结果中查看。核心指标还必须展示 `PGDATA`，显示 PostgreSQL 当前数据库用量、命名卷 `unidesk_pgdata_10gb` 和配置容量，便于从总览判断数据库状态。

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`，不能要求调用者先阅读完整日志才能知道是否卡在提交、构建、发布或观测阶段。