pikasTech-HWLAB/docs/reference/spec-v02-code-agent-trace.md

# v0.2 Code Agent Trace 规格

本文定义 HWLAB v0.2 Code Agent trace、result 和 Cloud Web trace 展示的数据权威、读写路径和回归判定。Trace 是 Workbench 最复杂的用户可见状态面；实现必须先收敛 source of truth，再生成派生 UI/cache，不得通过叠加 fallback、多路径或兼容快照掩盖状态污染。

## 当前态总览

当前 Trace 架构只有一条 completed/final 权威路径：用户入口提交 turn 后，Cloud API 用 `traceId` 绑定 AgentRun command；terminal 读取时重新通过 AgentRun command registry 找到当前 `commandId`，再从 command result 重建 final response；running trace 刷新只轻量同步 AgentRun events，不等待 command result；Web 和 CLI 只消费同一个 API payload，并通过同一个 row renderer 展示 trace。其他状态只能是 seed、cache 或 render-only evidence。

| 阶段 | 唯一路径 | 不允许 |
| --- | --- | --- |
| 提交 | Cloud Web 或 `hwlab-cli client` -> Cloud Web 同源 `/v1/agent/chat` -> Cloud API -> AgentRun run/command。 | 绕到内部 manager、临时 job、旧 agent worker、浏览器历史拼 prompt 或 runner 直连入口。 |
| Result | `/v1/agent/chat/result/{traceId}` -> session/run seed -> AgentRun command registry -> command result -> `terminalEvidence`。 | `latest`、top-level session snapshot、旧 `traceResults`、内存旧 cache 或共享 `runId` 直接当 final response。 |
| Trace | `/v1/agent/chat/trace/{traceId}` -> 同一 `traceId -> commandId` 映射 -> AgentRun events 按 command 过滤 -> running 直接返回 live events；terminal 才同步 command result 形成 `terminalEvidence`。 | running trace 每轮先等待 command result、重复拉 events，未按 commandId 分割事件，或把其他 command 的 assistant/tool/terminal row 挤进当前 trace。 |
| 渲染 | API payload -> `tools/src/hwlab-cli/trace-renderer.ts` 的 `traceDisplayRows` -> CLI `--render web` 和 Web `MessageTracePanel`。 | Web、CLI 各自实现一套 row 过滤/去噪/final 展示逻辑。 |
| CI | 后端合同测试 + CLI/Web renderer 测试 + G14 component plan 共同覆盖同一 API path 和同一 renderer 文件。 | CI 只测内部 helper、fixture、裸 API 或旧 fallback contract，却不覆盖 Web 用户路径会用到的 API/renderer。 |

这条路径的核心约束是“final response 只有 AgentRun command result 一个 authority”。`agent_sessions`、`codeAgentChatResults`、`runnerTrace`、Web local state 和 CLI summary 都不得产生第二个 final response；它们只能保存可被上述 authority 重建或解释的派生证据。

## 身份模型

| 身份 | 归属 | 语义 |
| --- | --- | --- |
| `traceId` | HWLAB Cloud API | 用户一次 Code Agent turn 的可见追踪 ID，也是 result/trace API 的主键。 |
| `conversationId` | HWLAB Workbench | 用户可见对话容器；只用于业务上下文和 UI 分组。 |
| `sessionId` | HWLAB Code Agent session | 用户显式创建或选择的业务 session，绑定 owner、provider profile 和权限。 |
| `threadId` | HWLAB/AgentRun/Codex | 会话连续性的唯一标准字段；不得新增历史 thread 别名或拼 prompt 替代。 |
| `runId` | AgentRun | 可复用执行壳；同一个 run 可承载同一 session 的多条 command。 |
| `commandId` | AgentRun | 单个 turn 的执行 identity；同一 `runId` 下每个 `traceId` 必须映射到唯一 command。 |
| `runnerId` / `jobName` | AgentRun / k8s | runner 尝试身份，只能作为执行诊断，不代表业务 session。 |

`traceId -> AgentRun commandId` 是 AgentRun 接入后的核心映射。`runId` 只能说明执行壳复用，不能单独说明某个用户 turn 的 final response。Cloud Web、CLI 和 issue closeout 必须同时展示业务身份和执行身份，避免把共享 run 的上一个 command 误认为当前 trace。

## 权威数据源

- **AgentRun command registry 是 completed AgentRun trace 的执行权威**：Cloud API 必须通过 `GET /api/v1/runs/{runId}/commands?afterSeq=0&limit=100` 用 `idempotencyKey === traceId` 或 `payload.traceId === traceId` 找到当前 trace 的 command。
- **AgentRun command result 是 final response 权威**：找到 command 后，Cloud API 必须通过 `GET /api/v1/runs/{runId}/commands/{commandId}/result` 生成 `reply.content`、`finalResponse`、`providerTrace` 和 completed result payload。
- **AgentRun events 是 trace row 权威**：Cloud API 从 `GET /api/v1/runs/{runId}/events` 读取事件，并按当前 `commandId` 过滤 assistant/tool/terminal rows。旧 command 的 assistant/tool/terminal 事件不得进入当前 trace 的可读事件列表。
- **`agent_sessions` 是业务 session 和 seed store，不是 final response authority**：它保存 owner、project、conversation/session/thread、lastTraceId、AgentRun run seed 和必要派生证据；读取 terminal result 时不得把 `session.finalResponse`、`session.traceSummary` 或旧 `traceResults` 当成 completed 文本权威。
- **内存 `codeAgentChatResults` 是短连接缓存，不是 terminal authority**：running 状态可用它承接轮询状态；terminal AgentRun result 再次读取时必须重新走 command registry/result 或使用由该路径刚生成的新 payload。
- **`traceStore` 是 live event buffer，不是历史 final authority**：它服务增量轮询和短期 trace 展示；事件过期时可以报告 missing/expired，但不能用别的 trace 的 final response 填补。

## 写入流程

1. Cloud Web 或 `hwlab-cli client` 通过同源 `POST /v1/agent/chat` 提交 turn；请求必须携带显式选中的 `conversationId/sessionId/threadId` 和 provider profile 语义。
2. Cloud API 认证 actor，按 session owner 和 tool capability 装配 AgentRun 请求；HWPOD/runner 使用的用户 API key 只允许来自 owner 的 `HWLAB_API_KEY`，浏览器 session、cookie 或其他 env 别名不得成为 CLI/runner key 来源。
3. Cloud API 创建或复用 AgentRun `runId`，再创建新 command；command `idempotencyKey` 和 `payload.traceId` 必须等于本次 `traceId`，`payload.conversationId`、`payload.hwlabSessionId`、`payload.threadId` 和 `payload.providerProfile` 必须保留。
4. Cloud API 写入 session seed：业务 session、lastTraceId、AgentRun `runId`、可选当前 `commandId`、provider profile 和 owner 归属。该 seed 只用于后续找到 run，不承诺 final response 正确。
5. 初始 result 返回 `running/accepted`，Web 和 CLI 进入短连接 result/trace 轮询。

写入路径不得把浏览器历史 messages、旧 trace final response、旧 command tail 或 session top-level snapshot 拼入新 command payload。历史只用于 UI 展示和排障，不是模型上下文，也不是新 result 的数据来源。

## Result 读取流程

`GET /v1/agent/chat/result/{traceId}` 是 terminal result 的唯一用户入口。AgentRun adapter 启用时，Cloud API 必须执行以下顺序：

1. 校验 `traceId` 和 session owner；普通用户只能读自己的 trace，admin 按授权读。
2. 从内存缓存或 `agent_sessions` 读取最小 AgentRun seed，至少需要 `runId`；如果没有 seed，返回 not found，不猜测其他 session。
3. 对 terminal 或可能 terminal 的 AgentRun result，必须用 AgentRun command registry 按 `traceId` 解析当前 `commandId`。不得相信缓存里的 `agentRun.commandId`、`providerTrace.commandId`、`traceSummary.agentRun.commandId` 或 top-level `lastTraceId` 作为最终映射。
4. 找到 command 后，读取 command result，并从 command result 重建 `reply`、`finalResponse`、`providerTrace`、`traceSummary` 和 `agentRun` 字段。
5. 写回内存缓存和 session 派生证据时，只能写刚由 command result 生成的 payload；旧 `finalResponse`、旧 `traceSummary` 和旧 `traceResults` 不得参与 merge 覆盖。
6. 如果 command registry 找不到该 `traceId` 对应 command，返回结构化错误，例如 `agentrun_trace_command_not_found`；不得回退到旧缓存、top-level snapshot、latest trace 或其他 command result。

Completed result 响应必须把 AgentRun command result 的终态证据公开为 `terminalEvidence`，并与 `agentRun.commandId`、`finalResponse.traceId` 保持一致。`/result` 和 `/trace` 响应不得导出 `fallback` 字段；降级、缺失或过期只能用 `status`、`traceStatus`、`retention`、`error` 和 `terminalEvidence` 表达，避免旧 fallback contract 重新成为并行 final response 路径。

Running 轮询可以返回 `202` 和当前 runnerTrace；这只是“尚未 terminal”的轮询语义，不是 final fallback。Completed / failed / canceled / blocked 等 terminal 状态必须经过同一 command registry/result 路径确认。

## Running Trace 刷新流程

`GET /v1/agent/chat/trace/{traceId}` 的 running 刷新是 Trace 用户可见性的关键路径，必须保持轻量、单向和可预测：

1. Cloud API 先从当前 result/session seed 取得 AgentRun `runId` 和可用 `commandId` 线索，再调用 `refreshAgentRunTrace` 刷新 AgentRun events。刷新 events 是 running `/trace` 的第一动作；不得在刷新前等待 `syncAgentRunChatResult` 或 command result。
2. AgentRun events 仍按当前 `traceId -> commandId` 过滤并写入 trace buffer。running 响应返回 live events、eventCount、traceStatus 和必要 error/blocker 信息；它不生成 assistant final response。
3. `/trace` 只有在明确 terminal 状态、terminal result event 或 command result 已 terminal 时，才调用 `syncAgentRunChatResult` 读取 command result。此时 `/trace` 已经刷新过 events，result 同步不得再次重复拉同一批 events；实现应显式走 no-refresh-events 语义，避免同一轮请求 events fetch/append 两次。
4. AgentRun/provider 执行失败、限流或 high-demand 错误必须作为 trace/result 状态和 terminal error 暴露；不得把执行层失败隐藏成 trace 缺失，也不得为了给 UI 拼完整回复而从 trace rows 反填 final response。
5. running trace 的用户可见刷新目标是小于 5 秒。这里的目标衡量 Web/CLI 对同源 `/v1/agent/chat/trace/{traceId}` 的可见更新延迟，而不是要求模型执行成功或 final result 小于 5 秒。即使 `/result` 仍 running 或最终 failed，`/trace` 也应能在该窗口内暴露新增 events 或明确错误状态。

这条流程禁止把 running `/trace` 做成“先同步最终 result、再刷新 trace”的重路径。Result 慢、provider 慢或 command result 暂不可用时，trace 面板仍必须能独立显示当前 AgentRun events；terminal final response 则继续只由 command result 权威路径生成。

## Trace 读取与渲染流程

`GET /v1/agent/chat/trace/{traceId}` 服务完整 trace 回放，Cloud Web 与 `hwlab-cli client agent trace --render web` 必须共享同一 row 转换语义：

1. Cloud API 先用 result 同一路径解析当前 `traceId -> commandId`；对于 AgentRun trace，events 必须按该 `commandId` 过滤。
2. 可读 rows 至少覆盖 request/setup、tool call、assistant message、terminal/result 和 blocker。低价值 AgentRun backend echo、状态 echo、terminal boilerplate 和重复噪声可被 row renderer 去噪，但原始 trace JSON 仍应通过 `--full` 或下载保留。
3. Web 默认显示完整可读事件列表。Result polling 返回的 compacted head-tail runnerTrace 不能冒充完整 trace；发现 `eventsCompacted=true` 时必须继续请求 `/trace/{traceId}`。
4. 如果完整 trace 已过期或缺失，UI 必须显式展示 missing/expired，并提供 result/inspect 可用证据；不得用最新 trace 或 session final response 填补历史 trace。
5. 同一 run 多 command 时，旧 command 的 assistant/tool/terminal rows 不能挤到新 command 的 final response 或 trace 尾部。取消/失败前的有价值上下文应作为脱敏 conversation facts 或当前 command 自身事件展示，不通过串线实现。
6. Steer 事件归属原 target trace。`POST /v1/agent/chat/steer` 被接受后，原 trace 的完整 trace/read/render 路径必须能看到 `agentrun:steer:accepted` 和 `agentrun:steer:command-created`，并保留目标 `runId`、`targetCommandId` 和 `steerCommandId`。后续 provider/backend terminal failure 仍是目标 turn 的终态；它不得删除 steer accepted/command-created rows，也不得被报告成 steer POST 短请求失败。

## Web/CLI/CI 同路径保证

Web、CLI 和 CI 的一致性按“入口同源、API 同 path、renderer 同代码、CI 同组件模型”保证：

- **Web 入口**：浏览器只从 Cloud Web origin 调用相对 `/v1/agent/chat*` 路径，经 Cloud Web/edge 进入 Cloud API；浏览器代码不得直连 AgentRun、内部 manager、pod service 或临时 debug endpoint。
- **CLI 入口**：`hwlab-cli client agent send/result/trace/inspect/steer` 的标准 base-url 是目标 lane 的 Cloud Web origin，v0.2 public Web 等价入口为 `http://74.48.78.17:19666`；CLI 再请求同一 `/v1/agent/chat*` path，并且只从 `HWLAB_API_KEY` 生成 `Authorization: Bearer`。Cloud API 直连 `19667` 只允许作为 API 合同、admin/setup/gateway 或明确诊断证据，不能替代 Web trace/result issue 的 Web 等价验收。
- **Trace renderer**：CLI 的 `agent trace --render web` 和 Web 的 `MessageTracePanel` 必须共同 import `tools/src/hwlab-cli/trace-renderer.ts`；任何 row 分类、noise count、completion row、assistant markdown、tool row 或 compacted trace 展示改动都先改这个共享 renderer，再由 Web/CLI 测试覆盖。
- **Result/Trace state**：Web 的 result polling、trace replay、`mergeTraceResults` 和 CLI 的 poll/wait/trace 命令都必须以 `/v1/agent/chat/result/{traceId}` 和 `/v1/agent/chat/trace/{traceId}` 为唯一用户 API；Web 每个刷新 tick 必须并行启动 result 和 trace 请求，不得先等待 result 再请求 trace；不得给 Web 增加一条 session-level final response 查询，或给 CLI 增加一条内部 result manager 查询。
- **CI component model**：`tools/src/hwlab-cli/trace-renderer.ts` 是 Cloud Web code input；改动、移动或重命名共享 renderer 时，必须同步 G14 CI component planner 和 planner 测试，保证 renderer 变化触发 Cloud Web 相关验证/rollout。服务端 trace/result 代码、Web trace state 和 CLI trace client 的 affected component 也必须保持在同一发布计划里。
- **CI 语义边界**：CI 同路径不是要求单元测试访问公网；它要求 mock/contract 测试表达同一 HTTP path、同一 identity mapping、同一 renderer import 和同一失败语义。真实关闭 Web trace/result issue 时，再用目标 public Cloud Web origin 或 Web 等价 CLI 做 P4 验收。

如果 Web、CLI 或 CI 只覆盖了上述链路的一段，不能称为同路径修复。例如只修 Web DOM、只修 CLI formatter、只修 session cache、只修 AgentRun events filter、或只让 CI mock helper 变绿，都可能继续保留另一条 final/trace 路径，导致“修过很多次但现象还在”。Trace 相关变更必须同时对齐 authority、API、renderer 和 component plan 四层中的相关部分。

## 组合优先原则

CaseRun、harness、runner、诊断脚本和其他上层编排工具需要查看 Code Agent trace 时，必须采用“ID + 既有工具组合”的方式，而不是在上层工具里重新实现 trace/result/session 查询和渲染逻辑。上层工具的职责是稳定返回 `traceId`、`sessionId`、`conversationId`、`threadId`、AgentRun `runId/commandId` 线索和可复制的下一条 HWLAB CLI 命令；完整 trace、result、inspect 和 Web renderer 语义继续由 `hwlab-cli client agent trace/result/inspect` 提供。

推荐输出合同：

- `traceLookup.source=hwlab-cli.client.agent`，说明后续查询复用既有 HWLAB Agent CLI。
- `traceLookup.strategy=id_plus_existing_cli`，说明当前工具只提供 identity 和组合 hint。
- `traceLookup.commands.result=hwlab-cli client agent result <traceId> --base-url <web-origin>`。
- `traceLookup.commands.trace=hwlab-cli client agent trace <traceId> --base-url <web-origin> --render web`。
- `traceLookup.commands.inspect=hwlab-cli client agent inspect --trace-id <traceId> --base-url <web-origin>`。
- 有 `sessionId` 时可以补 `traceLookup.commands.sessionStatus=hwlab-cli client agent session status <sessionId> --base-url <web-origin>`。

这条规则的目的是通过组合复用保持单一 trace authority：CaseRun 或 harness 可以归档 `traceLookup` 和由 result payload 直接可得的终态摘要，但不得为了方便再发明一套 `/trace/{traceId}` fetch、row renderer、session 反查、final response 归因或 AgentRun events 过滤器。需要更多可见性时，先改进 `hwlab-cli client agent trace/result/inspect` 这些已有入口，再让上层工具返回新的 hint 或消费这些入口的稳定字段。

## 派生缓存边界

允许存在的派生状态只有两个用途：降低轮询开销和提升 UI 可见性。派生状态必须可被权威路径重建，且不得成为 terminal result 的替代 authority。

| 派生状态 | 允许用途 | 禁止用途 |
| --- | --- | --- |
| `codeAgentChatResults` | 保存刚提交的 running result、刚由 command result 生成的 terminal payload。 | 在 terminal 读取时跳过 command registry；返回旧 final response。 |
| `session.traceResults` | 保存按 traceId 写回的审计证据，加快 inspect/list 展示。 | 覆盖 command result；把旧 command 文本当成当前 trace final。 |
| `session.agentRun` | 保存最近或可复用 run seed。 | 证明当前 trace 的 commandId 或 final response。 |
| `session.finalResponse` / `session.traceSummary` | 只作为最近消息的派生展示，必须标明 traceId。 | 历史 result/trace 的 authority；修复其他 trace 时覆盖 latest。 |
| `runnerTrace` compact window | result 轮询里的轻量进度。 | Web 完整 trace 列表；历史 trace closeout 证据。 |

当派生状态和 AgentRun command registry 冲突时，以 command registry 和 command result 为准；冲突的派生状态应被下一次权威读取覆盖或忽略，不新增兼容分支。

## 后续变更纪律

后续任何 trace/result/final response 变更，必须先按本节收敛路径，再改实现或测试：

1. **先定 authority**：新增字段或状态必须归类为 authority、seed、cache、render-only evidence 或 diagnostic；除了 AgentRun command result，其他类别都不能生成 terminal `reply.content` 或 `finalResponse`。
2. **先删旧路再接新路**：如果新需求确实改变 authority 或 API path，必须在同一变更中删除旧 reader/writer、旧测试和旧门禁；不得保留 legacy mode、feature flag、双读、双写、兼容 fallback 或“查不到再试旧路径”。
3. **失败要 fail closed**：找不到 `traceId -> commandId`、owner 不匹配、events 过期、command result 缺失或 cache 冲突时，返回结构化错误/retention/terminalEvidence，不用 latest、cached、top-level session 或其他 command result 补洞。
4. **共享代码优先**：Web/CLI row 语义只能落在共享 renderer；Web state 只负责请求、合并和展示状态，CLI 只负责调用同一 API 和输出同一 renderer 结果，不能在两端分头补过滤规则。
5. **组件模型跟着代码走**：移动 trace server、Web trace state、CLI trace client 或共享 renderer 时，必须同步 CI component planner；不能让文件路径变化把 Web/CLI trace 代码移出 Cloud Web 验证面。
6. **旧断言一律拆除**：任何测试、预检、guard、gate 或 fixture 还在要求 `fallback` 字段、latest result、session top-level final、legacy trace snapshot 或双路径兼容时，删除并改写为本 SPEC 的当前目标行为；不得为了让旧断言通过而补兼容分支。
7. **证据按路径给出**：trace/result closeout 必须同时列出 `traceId`、`runId`、`commandId`、API path、renderer 入口和 Web/CLI base-url；只给 job id、PipelineRun、单测或源码 diff 不足以证明用户路径已收敛。
8. **刷新延迟按同源 trace 测**：trace 刷新性能问题必须用 public Cloud Web origin 或 Web 等价 CLI 采样 `/v1/agent/chat/trace/{traceId}`，记录 eventCount 变化和 trace endpoint latency；不得用内部 AgentRun events、pod log 或 `/result` 完成时间替代用户可见 trace 延迟。

## 禁止路径

- 不得为 trace/result 增加 parallel final response path、legacy mode、feature flag、旧 top-level fallback 或“查不到 command 就用 latest/cached result”的分支。
- 不得把 `runId` 当成 trace authority；共享 run 下必须使用 `commandId` 分割事件和 final response。
- 不得把 `provider=agentrun-v01` 当成真实模型/provider；`agentrun-v01` 只属于 adapter/runner infrastructure 字段。
- 不得让 running `/trace` 每轮先等待 command result、重复同步 events 或串行依赖 `/result`；trace 刷新慢不能靠加 Web 专用轮询、CLI 专用快速接口或 latest/cache fallback 解决。
- 不得在 Web、CLI 或 closeout 中把 `AgentRun result is ready`、terminal status echo、boilerplate completion row 或 placeholder status 当成 assistant final response。
- 不得通过拼接浏览器历史消息、旧 trace rows 或旧 summary 来制造 continuity；continuity 只由标准 `threadId` 和 AgentRun/Codex 原生 resume 证明。
- 不得新增 `HWLAB_API_KEY` 以外的 CLI/runner API key 来源，也不得让 Web session/cookie 成为 runner key fallback。

## 回归测试要求

源码层测试必须覆盖以下最小场景：

- 同一 `runId` 下两个 `traceId` / `commandId`，读取第一条历史 trace 时不显示第二条 command 的 assistant/tool/terminal rows。
- 第二条 trace 的 session top-level、`traceResults` 或内存 cache 被污染成第一条 command/final 时，`GET /result/{secondTraceId}` 必须通过 command registry/result 返回第二条 command 的 final response。
- 已 completed 的 AgentRun 内存缓存也必须走 command registry/result；不能只同步 running。
- command registry 找不到目标 `traceId` 时返回结构化错误，不返回旧 cache/latest/top-level。
- running `GET /trace/{traceId}` 必须先刷新 AgentRun events 并返回 live trace；未 terminal 时不得调用 command result 同步，terminal 时 result 同步不得重复刷新同一批 events。
- Web renderer 的纯逻辑测试覆盖 request/setup、tool call、assistant markdown、completion row、noise count 和 compacted trace 自动回放条件。
- Result/trace 响应序列化测试必须断言没有 `fallback` 字段，且 `traceId`、`agentRun.commandId`、`terminalEvidence.agentRun.commandId` 和 `finalResponse.traceId` 一致。
- CLI 测试必须覆盖 `agent result`、`agent trace --render web`、`harness result` 和 `harness trace` 都请求 Cloud Web base-url 下的 `/v1/agent/chat/result/{traceId}` 或 `/v1/agent/chat/trace/{traceId}`，并暴露共享 renderer 标识。
- Steer 回归测试必须覆盖 `/v1/agent/chat/steer` 在 AgentRun steer command 创建后短连接 202 返回，不等待 owner/session/workspace 持久化；同一 target trace 的 render rows 必须包含 `agentrun:steer:accepted` 和 `agentrun:steer:command-created`。
- Web 测试必须覆盖 `mergeTraceResults`、compacted trace 自动请求完整 `/trace/{traceId}`、`subscribeToTrace` 在同一 refresh tick 并行启动 `/result` 与 `/trace`、`MessageTracePanel` 共享 renderer import，以及 final response 不从 trace row 或 session latest 反填。
- CI planner 测试必须覆盖共享 renderer、服务端 trace/result、Web trace state 和 CLI trace client 的 affected component 归属；路径重命名时先更新 planner 测试，不用旧路径断言保护旧架构。

真实入口验收必须走目标 lane 的 public Cloud Web origin 或 Web 等价 CLI：`POST /v1/agent/chat`、`GET /v1/agent/chat/result/{traceId}`、`GET /v1/agent/chat/trace/{traceId}` 和 `inspect/session list`。v0.2 默认用 `http://74.48.78.17:19666` 作为 Web 等价 base-url；`19667` API 直连只能补充证明 Cloud API contract，不能单独关闭 Web trace/result 类 issue。Trace 刷新延迟类 issue 还必须给出至少一轮 running `/trace` eventCount 在小于 5 秒窗口内增长的证据；模型 high-demand、backend failed 或工具执行失败可以作为 out-of-scope 执行层状态记录，但不能替代 trace 可见性判定。仅有单测、PR merge、PipelineRun 或源码证据不能关闭 trace/result 类 issue。

## 相关文档

- [spec-v02-hwlab-cloud-web.md](spec-v02-hwlab-cloud-web.md)：Cloud Web 工作台、trace renderer 和 Web/CLI 同路径要求。
- [agentrun-code-agent-dispatch.md](agentrun-code-agent-dispatch.md)：AgentRun run/command/resource bundle/credential 装配边界。
- [code-agent-chat-readiness.md](code-agent-chat-readiness.md)：Code Agent 真实 completed 判定和 provider readiness。
- [spec-user-access.md](spec-user-access.md)：Code Agent session owner、trace/result/cancel 权限边界。