docs(integration): add pre-flight, account, run-info & full endpoint inventory

Close the remaining coverage gaps in the client-facing API doc (verified against
real routes in router/api-router.go):

- §2.1 NEW "sub 可用性就绪闸门": the 4-gate composite the client must pass before
  enabling sub (capabilities.enabled + device-bound + active git binding + balance),
  with pseudo-code and per-gate data source — directly answers "客户端判断 sub 是否可用".
- §2.2 NEW account/balance: GET /api/user/self (+/self/groups,/self/models),
  quota/used_quota/request_count, model intersection rule.
- §2 capabilities: documented every field (runtime_kind/model_selection/supports_*).
- §4.2 NEW run-info interfaces with response shapes: logs(user/debug),
  timeline(events incl delivery.pushed), events, metrics, diagnostics, sk-snapshots.
- §12 NEW full endpoint inventory by flow stage (①startup ②create ③monitor
  ④approve ⑤artifacts ⑥iterate ⑦deploy ⑧resources) with 🟢/🟡/🔴 status — a
  coverage checklist mapping every real route so nothing is silently missing.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/integration/heicode-desktop-unified-api.md

@@ -87,7 +87,48 @@ signature = base64( ed25519_sign(device_priv, sha256(canonical)) )
 }}
 ```
 
-`enabled` 反映该模式 Runtime 当前是否接通。
+`enabled` 反映该模式 Runtime 当前是否接通（HM 探测 agent_management / HeiCode-Swarm 的健康；`enabled:false` 时**不要**让用户进该模式）。
+字段：`runtime_kind`（后端运行时）、`model_selection`（`default|per_role|primary`）、`supports_roles/task_graph/continue_chat`（UI 能力位）、`models[].available`（该模型当前可用）。
+
+### 2.1 判断 sub 模式是否可用（就绪闸门）🟡
+
+客户端在让用户点「sub 模式」前，必须先过**四道闸门**；任一不满足就**禁用 sub 入口**并提示对应引导。这是一个**客户端本地组合判断**（HM 不提供单一「ready」接口）：
+
+| # | 闸门 | 数据来源 | 不满足时 |
+|---|---|---|---|
+| 1 | **Runtime 接通** | `GET /api/heicode/capabilities` → `modes[id=sub_agile].enabled === true` | 灰掉 sub，提示「云端暂不可用」 |
+| 2 | **已认证（设备已绑定）** | 本地有设备绑定 token（§1；无则先走 heicode-auth 登录/配对） | 引导登录 |
+| 3 | **已绑有效 git 仓库** | `GET /api/heicode/resources?type=git&status=active`（§8.2）非空 | 引导去「资源绑定」绑 git，或改用本地模式 |
+| 4 | **余额充足** | `GET /api/user/self` → `quota - used_quota > 0`（§2.2） | 引导充值 |
+
+```text
+canUseSub =
+     capabilities.modes.find(m => m.id==='sub_agile')?.enabled
+  && isDeviceBound()
+  && gitBindings.some(b => b.status==='active')
+  && self.quota > self.used_quota
+```
+
+- 闸门 3「强制绑 git」对齐 spec §3.1；建任务时若仍没传有效 git binding，HM 也会兜底拒绝（`SUB_GIT_BINDING_REQUIRED`，§11）。
+- 闸门 1/4 用现有接口（🟢）；闸门 3 的客户端版资源列表是 🔴 待建（§8.2），上线前可临时用 `/api/resources/`（会话鉴权）联调。
+- **本地模式**（客户端自己跑 agent）不需要闸门 1/3，只需 2/4。
+
+### 2.2 账户与余额（判断能不能跑 / 给概览用）🟢
+
+| 方法 | 路径 | 鉴权 | 说明 |
+|---|---|---|---|
+| GET | `/api/user/self` | 会话/设备 | 当前用户：`quota`(剩余额度)、`used_quota`(累计已用)、`request_count`(调用次数)、分组等 |
+| GET | `/api/user/self/groups` | 同上 | 用户可用模型分组 |
+| GET | `/api/user/self/models` | 同上 | 当前用户**可用模型**列表（与 `capabilities.models` 互补，按分组过滤） |
+
+```json
+// GET /api/user/self → data 摘要
+{ "id":22, "username":"...", "quota":160470000, "used_quota":39530000, "request_count":521, "group":"default" }
+```
+
+- 余额/用量单位是内部 quota（展示按汇率换算）；`quota` 为**剩余**，`used_quota` 为**累计已用**。
+- 建任务前应检查 `quota > used_quota`（闸门 4）；运行中若超预算 HM 会把任务标 `budget_exceeded`（§4）。
+- 模型选择（需求包 `model_selection`）只能用 `capabilities.models` ∩ `/api/user/self/models` 里 `available` 的模型。
 
 ## 3. 统一任务接口
 
@@ -267,6 +308,35 @@ HM 判的是**"有没有真东西"这个事实**，**不读代码、不判对错
 
 `client_task_status`（本地交互态）由客户端自己维护，不由 Manager 返回。
 
+### 4.2 运行信息接口（日志 / 时间线 / 诊断 / 事件 / 指标）🟢
+
+work 视图除 `/workflow` 外，下列接口给**过程信息**（都只读、GET、V2 无 body 签名）。**它们只承载"运行信息"，不承载代码产物**（代码看 git_ref，§5）。
+
+| 方法 | 路径 | data 关键字段 | 用途 |
+|---|---|---|---|
+| GET | `.../tasks/{id}/logs` | `user_logs[]`（友好）、`debug_logs[]`（原始）| 日志面板分两层：普通用户看 user，调试面板看 debug |
+| GET | `.../tasks/{id}/timeline` | `events[]`（task./agent./phase./handoff./delivery.）、`callbacks[]`、`artifacts[]` 聚合 | 任务时间线 |
+| GET | `.../tasks/{id}/events` | `events[]`（原始事件流） | 细粒度事件 |
+| GET | `.../tasks/{id}/metrics` | `tokens_used`、`elapsed_seconds`、`total_messages` | 指标卡 |
+| GET | `.../tasks/{id}/diagnostics` | `runtime_status`、`warnings[]`（直查 Runtime） | 排障 |
+| GET | `.../tasks/{id}/sk-snapshots` | `snapshots[]` | SK 快照 |
+
+```json
+// GET .../logs → data
+{ "task_id":"dep_xxx",
+  "user_logs":[{"ts":"2026-06-03T..","level":"info","agent":"backend","message":"开始实现登录接口"}],
+  "debug_logs":[{"ts":"2026-06-03T..","level":"debug","message":"tool: write_file path=backend/auth.go"}] }
+```
+```json
+// GET .../timeline → data
+{ "task_id":"dep_xxx",
+  "events":[{"event_type":"phase.changed","occurred_at":"..","payload":{"phase":"development"}},
+            {"event_type":"delivery.pushed","occurred_at":"..","payload":{"git_ref":{"branch":"delivery/dep_xxx","commit_sha":"a1b2c3d"}}}],
+  "callbacks":[], "artifacts":[{"artifact_id":"art_x","artifact_type":"test_report"}] }
+```
+
+> 轮询建议：work 视图主要轮询 `/workflow`（含 display_status + agents + git_ref，一次拿全）；需要日志/时间线明细时再单独拉 `/logs`、`/timeline`。SSE 上线后这些都可由事件流推送（§4b）。
+
 ## 4b. 响应 envelope 与实时刷新
 
 **成功**：`{ "success": true, "message": "", "data": {...} }`
@@ -462,3 +532,67 @@ Schema 查询：`GET /api/agent/callbacks/runtime-events/schema`。
 | ~~`ARTIFACT_REVISION_CONFLICT`~~ / ~~`ARTIFACT_ARCHIVE_NOT_READY`~~ / ~~`ARTIFACT_ARCHIVE_FAILED`~~ / ~~`FILE_NOT_FOUND`~~ / ~~`FILE_PATH_REQUIRED`~~ | **遗留**（local-edits/archive/files 已退役，见 §5.4/§6） | — |
 
 其余错误码沿用旧文档 §13。所有错误统一形如 `{"success":false,"error":{"code","message","retryable"}}`，可读 `error.retryable` 决定是否重试。
+
+## 12. 完整接口清单（按流程，覆盖核查）
+
+> 以**真实路由**为准（`router/api-router.go`）。`sub-agile` 路径把前缀换 `swarm` 即同形。状态：🟢 已实现 / 🟡 部分 / 🔴 待建。
+
+**① 启动与就绪（§2）**
+
+| 接口 | 状态 | 章节 |
+|---|---|---|
+| `GET /api/heicode/capabilities` | 🟢 | §2 |
+| `GET /api/user/self`、`/self/groups`、`/self/models` | 🟢 | §2.2 |
+| sub 可用性组合判断（客户端本地） | 🟡 | §2.1 |
+| 设备绑定 / 登录（`/api/heicode-auth/*`、`/api/user/...`） | 🟢 | 见 heicode-auth 文档 |
+
+**② 建任务与对话（§3）**
+
+| 接口 | 状态 |
+|---|---|
+| `POST /api/heicode/sub-agile/tasks`（需求包，含 resource_bindings、X-Idempotency-Key） | 🟢 建任务 / 🔴 强制 git 校验 + 幂等 |
+| `GET .../tasks`、`GET .../tasks/{id}` | 🟢 |
+| `POST .../tasks/{id}/messages`、`.../execute` | 🟢 |
+| `POST .../tasks/{id}/stop`、`DELETE .../tasks/{id}` | 🟢 |
+
+**③ 运行监控 / work 视图（§4）**
+
+| 接口 | 状态 |
+|---|---|
+| `GET .../tasks/{id}/workflow`（含 git_ref、per-agent 富字段） | 🟢 本体 / 🔴 git_ref + per-agent 字段 |
+| `GET .../tasks/{id}/logs`、`/timeline`、`/events`、`/metrics`、`/diagnostics`、`/sk-snapshots` | 🟢 |
+| `GET .../tasks/{id}/events/stream`（SSE） | 🔴 §4b |
+
+**④ 审批（§3.2）**
+
+| 接口 | 状态 |
+|---|---|
+| `GET .../tasks/{id}/approvals?status=pending` | 🟢 |
+| `POST .../approvals/{approval_id}/approve`、`/reject` | 🟢 |
+
+**⑤ 产物（§5）**
+
+| 接口 | 状态 |
+|---|---|
+| `git_ref`（在 workflow/详情里）→ 客户端 `git clone/pull` | 🔴 |
+| `GET .../tasks/{id}/artifacts`、`.../artifacts/{aid}/content`（仅非代码运行信息） | 🟢 |
+| ~~`.../artifacts/{aid}/{manifest,files,archive,revisions,local-edits}`~~ | 退役（§5.4） |
+
+**⑥ 修改 / 重做（§6）**：复用 ②的 `messages`/`execute`（+ 将来 `/redo` 🔴）；本地改走 git。
+
+**⑦ 部署（§7）**
+
+| 接口 | 状态 |
+|---|---|
+| `POST /api/heicode/resources/{id}/lease`（短期凭据租约） | 🔴 |
+| `DELETE /api/heicode/resources/leases/{lease_id}`（吊销） | 🔴 |
+| ~~`GET /api/heicode/deployment-targets`、`POST/GET .../tasks/{id}/deployments`~~ | 废弃（旧代部署） |
+
+**⑧ 资源绑定（§8）**
+
+| 接口 | 状态 |
+|---|---|
+| `GET/POST /api/resources/`、`POST /{id}/secret`、`PUT/DELETE /{id}`（会话鉴权，网页台） | 🟢 §8.1 |
+| `GET/POST/DELETE /api/heicode/resources*`、`/{id}/lease`（V2 设备签名，客户端） | 🔴 §8.2 |
+
+> 凡标 🔴 的，客户端**按本文契约预埋字段**即可；HM 侧补齐后无需改协议直接对齐。本清单即"整个流程要用到的接口"的核查表——发现遗漏请回填本表对应分组。