fix: 修复纯 Kafka Trace 实时可见性

docs/MDTODO/pure-kafka-live-single-step-debug.md

@@ -30,4 +30,19 @@
 修复隔离 debug replay 的 producer/barrier 与分层结果合同：保留 source lineage、replayId、offset range，报告 scanned/matched/delivered/decoded/applied/terminal，区分 producer-not-invoked、trace missing、filter mismatch、decoder/reducer rejection 与 terminal missing；仅写 debug topic。上下文：[隔离根因 #2476](https://github.com/pikasTech/HWLAB/issues/2476#issuecomment-4935398125)、[主方案 #2474](https://github.com/pikasTech/HWLAB/issues/2474#issuecomment-4935408473)。依赖：无。验证：empty、matched-no-terminal、reducer-rejected、terminal-complete 四类 typed 结果及 semantic internal web-probe command，完成任务后将详细报告写入[任务报告](./details/pure-kafka-live-single-step-debug/R2.3_Task_Report.md)。
 ### R2.4 [in_progress]
 
-集成前三个子任务，受控部署到 NC01/v03 并用原入口验证运行中及结束后 Trace 可读、同一 ingress raw/reducer 计数可解释、隔离 debug 命中 terminal；保持 OTel 三服务完整、error=0、projection=0 且产品链无补洞路径。上下文：[验收 #2474](https://github.com/pikasTech/HWLAB/issues/2474)、[OTel 基线 #2477](https://github.com/pikasTech/HWLAB/issues/2477#issuecomment-4935385934)。依赖：Trace 序列权威修复、单一 ingress raw 观察窗、隔离 debug replay 分层诊断。验证：定向测试、YAML/render/runtime contract、受控 CI/CD、semantic --origin internal web-probe 与 Kafka/SSE/DOM/OTel bounded counts，完成任务后将详细报告写入[任务报告](./details/pure-kafka-live-single-step-debug/R2.4_Task_Report.md)。
+以 [HWLAB #2474](https://github.com/pikasTech/HWLAB/issues/2474) 和固定 trace trc_fb6031c28d79495e 完成纯 Kafka 集成闭环：先增强 CLI 直接读取持久 hwlab.event 并复用前端 decode、merge、row model、summary 输出同构 Markdown，再修复 Trace 内 final response 重复、tool-call summary 可见性和每个 HWLAB SSE ingress 刷新 lastEventAt；最后受控部署 NC01/v03，以 Kafka 重放、semantic internal web-probe、DOM 与 OTel 验收 projection=0 且无补洞路径，完成任务后将详细报告写入[任务报告](./details/pure-kafka-live-single-step-debug/R2.4_Task_Report.md)。
+## R3
+
+在纯 Kafka SSE 权威链内实现页面刷新后的可重放引导，明确区别于 projector/read model/snapshot/sync/gap-fill/finalizer 补洞；承接上下文：[HWLAB #2474](https://github.com/pikasTech/HWLAB/issues/2474)，完成任务后将详细报告写入[任务报告](./details/pure-kafka-live-single-step-debug/R3_Task_Report.md)。
+### R3.1
+
+深入分析 Kafka retention、SSE 刷新连接、offset barrier、live handoff 与去重身份，形成不引入第二事实源的方案和失败可见性，完成任务后将详细报告写入[任务报告](./details/pure-kafka-live-single-step-debug/R3.1_Task_Report.md)。
+### R3.2
+
+实现 trace/session scoped Kafka refresh bootstrap 与 live fanout 无缝交接，全部开关、group、容量和时限保持 YAML-first，完成任务后将详细报告写入[任务报告](./details/pure-kafka-live-single-step-debug/R3.2_Task_Report.md)。
+### R3.3
+
+优先使用既有 trace 通过 CLI 单步重放验证顺序、terminal、final 唯一性、tool summary 和 timing，不启动新真实运行，完成任务后将详细报告写入[任务报告](./details/pure-kafka-live-single-step-debug/R3.3_Task_Report.md)。
+### R3.4
+
+完成定向测试、受控 CI/CD 与 semantic internal web-probe 页面刷新验收，确认 projection=0 且无 snapshot/sync/gap-fill/finalizer 路径，完成任务后将详细报告写入[任务报告](./details/pure-kafka-live-single-step-debug/R3.4_Task_Report.md)。

docs/reference/kafka-source-direct-debug.md

@@ -1,5 +1,50 @@
 # Kafka 源码直连调试
 
+- `hwlab-cli kafka render trace` 用于把持久 HWLAB Kafka 事件直接渲染为与 Web 同构的 Markdown Trace：
+  - 命令为 `hwlab-cli kafka render trace --from kafka --trace-id <traceId> --format markdown`；
+  - 默认输入 topic 优先读取 owning YAML 注入的 `HWLAB_KAFKA_EVENT_TOPIC`；
+  - 未注入时使用 canonical `hwlab.event.v1`；
+  - Kafka 读取必须使用 `--group-prefix` 或 owning YAML 注入的 `HWLAB_KAFKA_HWLAB_DEBUG_GROUP_PREFIX`；
+  - group prefix 必须标识独立 debug group，不复用产品 consumer group；
+  - 命令只读取 Kafka，不发布事件，不启动 Cloud API，不访问数据库，也不依赖 projector。
+
+- Trace 渲染与 Web 共享最后一个展示分叉之前的生产管线：
+  - JSON frame 使用 `decodeWorkbenchRealtimeEventFrame` 解码；
+  - 事件使用 `reduceWorkbenchRealtimeEvent` 与 `planWorkbenchRealtimeApply` 分类；
+  - 卡片使用 `projectWorkbenchLiveKafkaMessage` 增量归约；
+  - Trace 行使用 `traceDisplayRows` 生成同一 row model；
+  - Web 最后渲染 HTML，CLI 最后使用 `renderTraceRowsMarkdown` 渲染 Markdown；
+  - Final Response 只放在 Trace 外层，Trace 内保留非最终的助手进展消息。
+
+- Kafka Trace 查询必须披露有界扫描事实：
+  - `--run-id` 与 `--command-id` 用于在复用或异常混合的 traceId 内精确隔离一轮；
+  - `--command-id` 先按 trace、session 与 run 读取基础流，再在 CLI 内形成 command 生命周期；
+  - 只有基础流中至少存在一条精确 commandId 事件，才允许吸附同一 run 的无 commandId final/terminal；
+  - 精确 commandId 不存在时必须返回 `source_command_missing`，不得由 commandless 生命周期冒充成功；
+  - 精确 command 事件保留；
+  - 同一 run 中缺少 commandId 的 final/terminal 生命周期事件保留；
+  - 其他 command 和无法归属的 commandless 事件排除；
+  - 禁止把 commandId 直接下推后丢失 run-scoped terminal/final；
+  - identity 输出必须同时披露观测到的 session、run、command 和 source event 去重计数；
+  - command scope 输出必须披露每个 commandId 的计数、缺失 commandId 数、可归属生命周期数、歧义数与排除数；
+  - command 生命周期只有在 `scanComplete=true` 时才可判定完整；
+  - `limit` 或 `timeout` 只能作为部分流证据，`commandLifecyclePreserved` 必须保持 false；
+  - 输出 `scannedCount`、`parsedCount`、`matchedCount`、`invalidJsonCount` 与 `filterRejectedCount`；
+  - 输出 topic end offsets、最后扫描 offsets 与 `completionReason`；
+  - `completionReason=end-offset` 表示已经扫描到命令启动时捕获的 Kafka 上界；
+  - `completionReason=limit` 表示达到显式事件上限，不能冒充完整 trace；
+  - `completionReason=timeout` 表示未在 YAML 或 CLI 时限内证明到达上界；
+  - 没有匹配事件时以 `source_trace_missing` 失败，并保留上述扫描计数。
+
+- Trace Markdown artifact 默认写入 `.state/hwlab-cli/kafka-render/`：
+  - `--output-markdown` 可显式选择路径；
+  - `--from jsonl --jsonl-file <path>` 可完全离线复用同一管线；
+  - 默认文本输出保持 compact；
+  - 默认 JSON 只返回 `--row-limit` 指定的尾部行，并披露 returned/omitted/window；
+  - `--full` 仅用于显式下钻完整 row payload；
+  - `--format markdown` 输出 Markdown 正文；
+  - `--json` 输出身份、投影、row model、终态、计数和 artifact SHA 的结构化证据。
+
 - `hwlab-cli kafka regenerate hwlab` 用于把指定 AgentRun session 的事件直接映射为 HWLAB debug 事件：
   - 调用生产路径同源的 AgentRun 解码与 HWLAB 事件映射函数；
   - 不启动 Cloud API；