docs: clarify HWLAB AgentRun projection recovery

docs/reference/agentrun.md

@@ -179,6 +179,8 @@ AgentRun `command-result` / result API 的 `finalResponse` 必须来自当前 co
 
 AgentRun result/session 可见性必须把正在运行的目标 command 与后续 steer command 分开判定。排查 active turn 卡顿、恢复或 closeout 时，优先读取目标 command result/session status 中的 `liveness`，用 `liveness.phase` 区分 `waiting-runner`、`waiting-model`、`waiting-tool`、`idle-after-tool`、`transport-disconnected`、`runner-heartbeat-stale` 和 `terminal`；禁止只凭长时间没有新 event、外层超时或 runner 已回连来推断 turn 已恢复或失败。`steerDelivery` 只说明 steer RPC 在 runner/app-server 链路上的 ack、forward 和 backend accept 状态；`steer completed` 不能替代目标 command 终态，也不能作为目标 turn 已继续输出的证据。关闭 HWLAB/CaseRun 问题时，应同时引用目标 command id、目标 result/session 的 `liveness`、raw trace/terminal command 序列和原入口证据；字段需求以 UniDesk OA 的 [AgentRun核心](../../project-management/PJ2026-01/specs/PJ2026-010201-agentrun-core.md) 与 [队列会话](../../project-management/PJ2026-01/specs/PJ2026-010203-queue-session.md) 为准，UniDesk `docs/reference` 只记录跨仓库归因与验收口径。
 
+持久 runner 模式下，`run.status=claimed` 可以表示 runner/session 仍被占用，不等同于当前 command 未完成。判定 HWLAB Workbench 或 CaseRun 的单个 turn 是否完成时，必须以目标 `commandId` 的 result/session terminal status、raw event 中 terminal command 序列和最后 assistant/tool 输出为权威；不要用 run 级 `claimed`、runner 仍存活、Pod 仍在运行或外层 session 持久化状态覆盖 command 级终态。若 command result 已 terminal 而 HWLAB turn/read model 仍显示 running，应先按 HWLAB projection/read model 消费链路排查，不要反向要求 AgentRun 改写持久 runner 语义。
+
 ## 中文规则
 
 AgentRun 仓库内容默认中文。AgentRun 长期文档、过程文档、issue 标题与正文、PR 标题与正文、PR 评论、review 说明和交付总结都必须使用中文。代码标识符、API path、命令名、配置键、日志字段、协议字段和不可避免的外部专有名词可以保留英文，但解释性文字必须使用中文。

docs/reference/hwlab.md

@@ -70,6 +70,8 @@ Code Agent trace 的长期 API 和 Web 行为规格以 UniDesk OA 为权威：AP
 
 实时 Trace 展示必须把 turn 状态和 trace event 分页视为两条独立读路径。`/v1/agent/turns/:traceId` 只回答 running/terminal/final/error 等 turn 状态；`/v1/agent/traces/:traceId` 只负责按下游读 cursor 拉取已经持久化的 trace events。Web 在运行中不能等 turn terminal 后才 hydrate trace，也不能让 compact turn snapshot 覆盖已经拉到的 trace rows。后端刷新 AgentRun 上游失败时，trace API 仍应返回本地 trace store 中已有的分页快照，并把 refresh failure 作为诊断字段暴露；已有事件不得被硬 502 遮住。关闭“运行中 Trace 加载不出”类 issue 时，应证明 running 期间 trace API 与 Web DOM 都能看到已写入事件，而不是只展示最终完成后的 timeline。
 
+Workbench projection/read model 是持久化投影，不是 GET 侧隐式修复路径。Cloud API 重启、内存 finalizer 丢失或投影 worker 中断后，恢复只能由受控后台 projector/resumer 从 durable session、durable trace 和 AgentRun source cursor 继续推进；`/v1/agent/turns/:traceId`、`/v1/agent/traces/:traceId` 和 Web hydrate 不得为了让一次读取看起来正确而隐藏写入或 remap command。排查“AgentRun 已完成但 Workbench 仍 running/pending”时，先比较 AgentRun command result/session terminal、AgentRun raw event 最大 `sourceSeq`、HWLAB durable trace 最大 `sourceSeq` 和 session/turn 投影状态；若 AgentRun 已 terminal 且 HWLAB trace 落后，应归为 HWLAB projection resume gap，并用 YAML-first 配置的 projector/resumer 修复与验收。
+
 Code Agent trace/result 展示类问题的 typed CLI 关闭证据以 `hwlab-cli client agent result <traceId>`、`hwlab-cli client agent trace <traceId> --render web` 和必要的 `hwlab-cli client agent inspect --trace-id <traceId>` 为准，具体操作说明见 `$hwlab-code-agent` skill。三者的默认 JSON 都应暴露 `traceResultSummary`，其中 `ids`、`toolCalls`、`agentMessages`、`finalResponse`、`diagnostics`、`counts` 和 `upstreamGaps` 是给用户和审计者阅读的稳定摘要；不要要求关闭者从 raw `body`、`runnerTrace.events`、`rows` 或 `terminalEvidence` 人工拼事实。
 
 `result` 和 `trace --render web` 必须能直接证明 final assistant response、实际工具调用及状态、关键 trace/session/conversation/run/command/runner ID 和 runner/provider/lane 诊断。`inspect` 用于确认 trace 所属 session/conversation/thread、恢复上下文和下一步入口；它可以佐证 ID 和上下文，但不能单独替代 final response 或 Web renderer 行。验证必须打到 issue/CLI 选中的同一 node/lane public origin 或等价 Cloud Web/Cloud API dispatcher，不能用临时 AgentRun manager 调用、手写 raw request 或旧 lane trace 代替。