docs: record code agent failed final response rule

docs/reference/hwlab.md

@@ -72,6 +72,8 @@ Code Agent trace/result 展示类问题的 typed CLI 关闭证据以 `hwlab-cli
 
 失败详情类问题必须优先核对 `client agent result <traceId>` 的顶层 `error` 与 `agentRun`。`trace --render web` 只证明 rows/timeline 渲染，可能不携带 terminal result 的 `error`、`agentRun.runId`、`commandId`、`runnerId`、`jobName`、`namespace` 或 `terminalStatus`；Cloud Web 恢复会话时必须从 result 补齐这些诊断，再渲染详情弹窗。空字段不得渲染成大面积“未观测”占位；用户第一眼应看到错误码、错误类别和错误消息，有值的 AgentRun provenance 才进入状态摘要。
 
+AgentRun terminal `failed`、`blocked` 或 `canceled` 也是最终结果，不是“没有 final response”。当 `/v1/agent/chat/result/:traceId` 或 `/v1/agent/turns/:traceId` 返回顶层 `error.message`、`blocker.summary` 或 terminal failure message 时，HWLAB Cloud API 必须把可读错误生成为 `finalResponse.text` 和 `traceSummary.finalAssistantRow`，Cloud Web 的 final response 展示区必须直接显示该错误文本。TraceTimeline 可以同时展示失败事件，但不能让用户只能从 trace rows 里找错误；也不能用“没有返回可展示的 final response”覆盖已有 terminal error。
+
 `traceResultSummary.valuesPrinted=false` 只是脱敏声明，不等于免检。关闭前仍应扫描输出中是否出现完整 `HWLAB_API_KEY`、`hwl_live_*`、Authorization Bearer header、DB DSN、Secret payload 或 provider token。若 `upstreamGaps` 出现 `prompt_not_returned_by_upstream`，表示上游 trace/result payload 没有返回可脱敏展示的 prompt metadata；客户端不得发明 prompt 真相，应把该缺口拆到 Agent 编排或 trace payload issue，并说明它是否阻塞当前展示项。
 
 ### Web Live DOM Probe 验收
@@ -90,6 +92,8 @@ Workbench prompt、TraceTimeline、final response、详情弹窗或工具调用
 
 一次完整的 Workbench prompt UI 证据应覆盖：Web session 登录成功；模型通道选择符合目标 provider profile；显式创建或选择 session；prompt 被 `/v1/agent/chat` 接受并得到 `traceId/sessionId/conversationId/threadId`；页面可见用户消息、Agent message、final response；若 TraceTimeline 初始是 compact/result 压缩态，应在 Web 上触发 `回放 Trace` 后展开 timeline，让页面本身可见 `commandExecution` 等工具行。随后在同一 node/lane public origin 上，用 `hwlab-cli client agent result <traceId>`、`trace <traceId>` 和必要的 `inspect <traceId>` 交叉确认 terminal status、toolCalls、finalResponse、AgentRun run/command/runner ID 和脱敏状态。
 
+对于失败终态的 final response UI 验收，浏览器证据必须读取 final response 正文或 `.message-text` 中的用户可见错误，并与同一 trace 的 `client agent result` / turn endpoint 的 `finalResponse.text` 对齐。若 API 已返回 `error.message` 但没有 `finalResponse.text`，问题在 HWLAB API/adapter 结果映射；若 API 已返回 `finalResponse.text` 但页面仍显示空 final、通用 fallback 或只在 trace row 中展示错误，问题在 Cloud Web 恢复/terminal 文本选择。两类问题都不能用 trace timeline 展示正常来关闭。
+
 详情弹窗和恢复会话类验收还应覆盖“从持久化 conversation 恢复”的路径，而不是只在刚完成 turn 的内存态截图。若用户报告的原始 conversation 对当前验收 actor 不可见，但同一 trace 的 `result` 可读，可以创建当前 actor 可见的临时 conversation，消息中挂载同一个真实 `traceId` 和最小 terminal agent message，再在 Web 中选择该临时会话、打开运行详情并等待 result 诊断自动补齐；验收后删除临时 conversation。closeout 必须写明这是同 trace 的恢复路径验证，不能声称修改或读取了原始用户 conversation。
 
 Session 切换、session rail 或 Workbench 恢复路径类问题必须同时验证点击态和持久化恢复态。浏览器证据应在同一 public origin 中选择一个非当前 session，等待足够覆盖 `hydrate`、`select-conversation`、active trace repair 等异步返回的空闲窗口，确认 active tab 没有回退；随后读取 `/v1/workbench/workspace?projectId=<projectId>` 确认后端 `selectedConversationId` 已改变并持久化；最后刷新页面并再次等待 session tabs，确认同一个 session 仍是 active。若当前 selected conversation 没有出现在 `/v1/agent/conversations` 当前列表窗口中，前端必须把 workspace 当前选中 conversation 合入 session rail；刷新后没有 active tab、状态显示“等待 workspace”，或只靠内存态显示成功，均不能作为通过证据。session rail 的刷新列表只是候选窗口，不是 selected session 的完整真相；list API 临时缺当前 conversation 时，不得清空当前 tab、取消 active 状态或让标签在刷新/深链恢复中闪烁消失。自定义 Playwright 验收不要只按 tab index 或重复标题判断，应锁定唯一 title、conversationId 或后端 selected id，并记录 `select-conversation` response；与 session 切换无关的 health/RPC 噪声应拆成独立 issue，不阻塞已经通过的切换闭环。