docs: 固化 HWLAB 基线承接 SPEC

docs/reference/spec-v01-agentrun-mgr.md

@@ -59,6 +59,19 @@ POST  /api/v1/commands/:commandId/ack
 
 所有 API 成功和失败响应都必须是 JSON。失败响应至少包含 `failureKind`、`message` 和 trace correlation；不得出现空 stdout/空 response 被误判为成功的情况。
 
+## HWLAB v0.2 基线承接
+
+Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实，不承接 HWLAB 的用户鉴权、device-pod 授权或 Workbench schema。HWLAB 侧能力吸收总表见 [spec-v01-hwlab-manual-dispatch.md](spec-v01-hwlab-manual-dispatch.md)。本服务需要把以下能力固化为 AgentRun 自身合同：
+
+| HWLAB 原有能力 | Manager 承接合同 | 不归 Manager 管的内容 |
+| --- | --- | --- |
+| `/v1/agent/chat` 短连接提交后后台运行 | `POST /api/v1/runs`、`POST /api/v1/runs/:runId/commands` 和 `POST /api/v1/runs/:runId/runner-jobs` 均短返回 JSON，持久化 run/command/job identity | HWLAB HTTP route、浏览器同源代理、用户登录态 |
+| result 轮询判断终态 | `GET /api/v1/runs/:runId/result` 和 command result 必须聚合 terminal status、reply、failureKind、blocker、event cursor 和 attempt | HWLAB result schema 和用户可见文案 |
+| trace 轮询/回放 | `events` 是 append-only durable facts，单 run 内 `seq` 单调，支持 `afterSeq/limit` 分页 | Workbench trace UI、HWLAB event 展示分组 |
+| 取消当前 turn | run/command cancel 幂等；pending cancel 阻止新 runner job，running cancel 通过 runner/backend interrupt 收敛，terminal 后返回当前终态 | HWLAB cancel 按 owner/admin 鉴权 |
+| provider/backend 失败分类 | manager 统一保存并返回 failureKind；缺少 Secret、provider 鉴权失败、provider 不可用、backend 失败、infra 失败和 cancelled 必须可区分 | HWLAB 业务 blocker 分类或 device 授权失败 |
+| runner/job 定位证据 | runner job 创建响应和后续查询至少能回答 `attemptId`、`jobName`、namespace、runnerId、pod/log identity 和当前 terminal 摘要 | 直接暴露 Kubernetes 控制权给业务客户端 |
+
 ## Run 与 Command 合同
 
 `POST /api/v1/runs` 必须持久化以下字段：
@@ -93,6 +106,22 @@ POST  /api/v1/commands/:commandId/ack
 - health/readiness 必须返回 Postgres reachable、schema migration ready、SecretRef redacted 状态和 build/source metadata。
 - 日志、event、trace、health 和 diagnostics 不得输出 provider credential、Codex auth/config 内容、DSN password、token 或 URL credential。
 
+### Result envelope
+
+面向 HWLAB v0.2 原有 Code Agent 的承接基线，manager 的 run/command result envelope 至少包含：
+
+| 字段 | 规则 |
+| --- | --- |
+| `status` | run/command 当前聚合状态，只能由 command state 和 terminal_status 推导。 |
+| `terminalStatus` | `completed`、`failed`、`blocked` 或 `cancelled`；没有 terminal event 时为 `null` 或 equivalent running 状态。 |
+| `reply` | 从 `assistant_message` 聚合的最终用户可见文本；没有 terminal completed 时不得伪造 completed reply。 |
+| `failureKind` / `blocker` | 结构化失败分类和摘要；必须 redacted。 |
+| `lastSeq` / `eventCount` | 支持调用方增量轮询和 result/trace reconciliation。 |
+| `runId` / `commandId` / `attemptId` | 支持调用方持久关联和问题定位。 |
+| `artifactSummary` | 第一阶段只放有界摘要、字节数、截断标记和必要引用；不内嵌大 stdout/stderr。 |
+
+`assistant_message` partial、`command_output` 存在、stdout 非空、backend transport close 或 idle timeout 都不能单独让 result 进入 `completed`。
+
 ## 测试规格
 
 ### T1 Manager health/readiness