Merge pull request #2597 from pikasTech/docs/workbench-native-kafka-refresh

docs(workbench): 固化 Kafka 单路径刷新诊断

docs/reference/hwlab.md

@@ -199,10 +199,14 @@ Workbench 浏览器回归需求以 UniDesk OA [PJ2026-010401 Web工作台](../..
   - API 依赖就绪入口固定为 `/health/ready`；
   - `/health` 不是 Workbench L1 health 路由，禁止通过试探 404 判断服务异常；
   - 实时验收先启动 `hwlab-cli workbench events inspect --over-api --wait-for user,backend,assistant,terminal,final`，再向同一 session/trace 提交一个新 turn；
+  - 已有 session 的刷新验收必须先检查 connected contract：
+    - `kafkaRefreshReplay=true` 时要求 `deliverySemantics=kafka-retention-then-live`、`replay=true`、`liveOnly=false`；
+    - capability 已启用但仍返回 `live-only` 时，优先定位 L1 native API 是否仍保留独立 live-only SSE adapter；
+    - 此时 retention 查询尚未开始，不得先归因 Kafka 扫描超时或历史事件缺失；
   - 通过条件是 `connected=true`、`missingSemantics=[]` 且 `terminalStatuses` 出现明确终态；
   - `eventCount` 和 `--min-events` 不能证明 assistant、terminal 或 final，不得通过反复猜事件数量重开 inspect；
   - `event-timeout` 必须直接读取 `observedSemantics` 与 `missingSemantics` 分层定位；
-  - AgentRun 冷启动仍未终态时，报告上游运行状态，不得对已结束的 live-only 窗口补读 snapshot、read-model、AgentRun `/events` 或 `/result` 冒充产品 SSE 验收。
+  - AgentRun 冷启动仍未终态时，报告上游运行状态，不得补读 snapshot、read-model、AgentRun `/events` 或 `/result` 冒充产品 SSE 验收。
   - `workbench.connected` 已到达且 `filters.sessionId` 与当前会话一致时，delivery semantics、capabilities、contract version 和 authority metadata 的缺失或漂移只记录 `blocking=false` warning；
   - 上述内部元数据 warning 不得清空 realtime ready、禁用 Composer、覆盖业务错误或产生 `workbench_live_realtime_contract_invalid` 一类阻塞状态；
   - EventSource 未连接、连接进入 error/closed/blocked，或 connected session scope 与当前会话不一致时仍可阻断，并必须返回与 transport 或 session scope 对应的 typed error；
@@ -350,6 +354,11 @@ HWLAB v0.3 订阅 AgentRun Kafka event 的权威输入是 `agentrun.event.v1`，
   - 到达 barrier 后必须退出，不得把每个浏览器连接变成新的长期 Kafka consumer；
   - 实时阶段继续复用进程级 shared consumer/fanout；
   - 同一 Workbench session 只建立一个产品 EventSource，刷新与重连不得复制业务 subscriber。
+- 单一路径禁止用状态优先级伪装：
+  - “陈旧快照不得覆盖 sealed final”、snapshot freshness、final authority priority 等 guard 都意味着多条业务写入路径仍在竞争；
+  - 应删除 HTTP session/message/turn/result、submit response 和本地缓存对业务状态的写入；
+  - retention replay 与 live frame 必须只通过同一 SSE ingress、queue、reducer、row model 和 card；
+  - HTTP 只负责命令接纳、鉴权和非业务辅助数据，不参与消息、终态或 Final Response 投影。
 - `kafkaRefreshReplay` 与 `liveKafkaSse` 是可组合、可独立开关的 capability：
   - topic、group、扫描预算、等待预算、live buffer 上限和失败策略只从选中 node/lane 的 owning YAML/runtime config 读取；
   - replay 与 live frame 必须进入同一 decode、queue、reducer、row model 和 card；