docs(integration): sub-mode spec — disambiguate HM vs AM, full display_status, explicit flow

Address review feedback for three-team clarity:
- Terminology nailed: HM = Heicode Manager (Go gateway, NO AI, never executes,
  never touches a VM); AM = agent_management (the "Agent Manager" runtime, the
  one with AI that runs agents). Removed all ambiguous bare "Manager".
- Capability boundary table: who has AI / who executes commands / who connects
  the VM. Spells out that HM cannot deploy or read VM logs — deploy is run by
  the client (user-confirmed, short-lived creds from HM); code execution is AM.
- §3.0 explicit step-by-step execution flow (17 steps, each naming HM/AM/client).
- §6 full display_status definition: enum, judging algorithm, real-vs-fake
  artifact rules, success criterion — so all three teams interpret it the same.

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

docs/integration/heicode-sub-mode-flow-spec.md

@@ -13,18 +13,38 @@
 
 ---
 
-## 0. 三端角色与边界
+## 0. 术语与三端角色（先把名字钉死，避免歧义）
 
-| 端 | 角色 | 负责 | 不负责 |
+> ⚠️ **名字钉死**：本文用 **HM** = Heicode Manager（那个 Go 网关），用 **AM** = agent_management（就是你口中的「Agent Manager / Sub Mode Runtime」）。两者**完全是两个不同的服务**，本文不再用模糊的「Manager」一词。三方按下表对号入座。
+
+| 简称 | 全名 | 是什么 | 栈 |
 |---|---|---|---|
-| **桌面客户端**（cc-haha / Desktop） | 用户入口 + 本地操作 | 选模式、填需求、展示 work/日志/产物、本地 git、发起部署 | 不直连 agent_management；不自行判定成功；不存明文凭据 |
+| **客户端** | 桌面客户端 cc-haha / Desktop | 用户用的壳程序（Tauri+React） | TS |
-| **Heicode Manager**（heicode/） | 网关 + 控制面 + **唯一状态裁判** | 解密验签、鉴权、建任务、分发 runtime、收敛状态/产物、资源绑定与凭据托管、对客户端统一出口 | 不执行 agent；不直接写业务代码；不在日志/库里留明文凭据 |
+| **HM** | **Heicode Manager** | **网关 / 控制面 / 状态裁判 / 凭据中介**。**一个 Go 服务,本身没有 AI,不跑 agent,不执行任何 shell 命令,不连 VM** | Go(Gin/GORM) |
-| **agent_management**（Sub Mode Runtime） | 执行面 | 把需求拆成多 agent、调度执行、产代码、git 入库、流式上报状态/日志/产物、合并 | 不面向用户；不输出最终 `display_status`；不做最终裁决 |
+| **AM** | **agent_management**（= 你说的 Agent Manager / Sub Mode Runtime,在 `20.212.121.126`） | **真正干活的执行面**:里面的 **agent 才有 AI**,拆任务、写代码、跑工具、git 入库 | 独立服务 |
 
-**铁律**：
+### 0.1 关键能力边界（谁有 AI / 谁能执行命令 / 谁连 VM）—— 回答常见误解
-1. 客户端**只调 Manager**（`/api/heicode/*`、`/api/agent/*`），禁止直连 runtime/NewAPI/Runtime artifact。
+
-2. Manager 是**唯一状态裁判**，客户端只消费 `display_status`。
+| 能力 | 客户端 | **HM** | **AM** |
+|---|---|---|---|
+| 有 AI（大模型 agent） | ❌ | **❌ 没有** | ✅ agent 有 |
+| 执行 shell 命令 / 跑工具 | 部署阶段在用户机器上执行 | **❌ 从不执行** | ✅ 任务执行阶段在 AM 沙箱里执行 |
+| 写业务代码 | ❌ | **❌** | ✅ |
+| 连 VM / 部署 / 看 VM 日志 | ✅（**部署由客户端执行**,见 §3.8） | **❌ HM 不连 VM、不部署、不看 VM 日志** | ❌（AM 只产代码,不负责部署到用户 VM） |
+| 解密验签 / 鉴权 / 配额 | ❌ | ✅ | ❌ |
+| 裁决 display_status | ❌ | ✅ **唯一裁判** | ❌（只报执行事实） |
+| 托管凭据（KV）/ 发短期凭据 | ❌ | ✅ | ❌ |
+
+> **重点澄清(回答"HM 怎么部署 VM/执行命令/看日志"):HM 做不到,也不该做。HM 没有 AI、不执行命令、不连 VM。**
+> - **任务执行**(写代码、跑测试)= **AM 的 agent** 在 AM 自己的沙箱里干。
+> - **部署到用户 VM + 在 VM 上看日志** = **客户端**在用户机器上干(用户确认后,HM 只把短期凭据加密发给客户端,客户端拿凭据自己 ssh/部署/看日志)。
+> - HM 全程只是:解密、鉴权、把任务转给 AM、把 AM 上报的状态裁决成 display_status、把凭据从 KV 安全发出、记审计。
+
+### 0.2 三端铁律
+1. 客户端**只调 HM**（`/api/heicode/*`、`/api/agent/*`），**禁止直连 AM** / NewAPI / Runtime artifact。
+2. **HM 是唯一状态裁判**，客户端只消费 `display_status`（定义见 §6）。
 3. 凭据只进 **Azure Key Vault**，全链路只传/存 `secret_ref`，明文绝不落库/日志/回调。
+4. **HM 不执行任何命令、不部署、不连 VM**；执行靠 AM（任务期）或客户端（部署期）。
 
 ---
 
@@ -46,7 +66,7 @@
 │                │        │                          │        │ 9 合并→完整产物       │
 │ 10 看产物 ─────┼───────►│  manifest/files/archive  │ ◄──────┤   (git/blob)          │
 │   (经 git 或    │        │                          │        │                      │
-│    经 Manager)  │        │                          │        │                      │
+│    经 HM)  │        │                          │        │                      │
 │ 11 不满意 ─────┼───────►│ /messages | /execute     ├──────► │ 12 修改/重做          │
 │                │        │   (带 active_revision)    │        │                      │
 │ 13 本地 git    │ ◄──────┤  (用户自己仓库直接 pull) │        │                      │
@@ -58,7 +78,9 @@
 
 ## 2. 三端颗粒度契约（一图看清谁给谁什么）
 
-| 数据/动作 | 客户端 → Manager | Manager → runtime | runtime → Manager（回调） | Manager → 客户端 |
+> 表头里 **HM = Heicode Manager**，**AM = agent_management**。
+
+| 数据/动作 | 客户端 → **HM** | **HM → AM** | **AM → HM**（回调） | **HM → 客户端** |
 |---|---|---|---|---|
 | 建任务 | 需求包（objective/context/约束/验收/模型选择/角色） | orchestration_plan + 资源授权 grants | deployment_id/swarm_id | deployment_id(=task_id) + display_status |
 | 运行状态 | — | — | `status`+`runtime_execution_status`+`phase` | **`display_status`**（裁决后） |
@@ -72,38 +94,77 @@
 
 ## 3. 阶段详解
 
+### 3.0 完整执行流程（逐步，明确每一步谁做什么）
+
+> 全程三个主体：**客户端**、**HM**（Heicode Manager，无 AI、不执行）、**AM**（agent_management，有 AI、执行）。
+
+**A. 准备（一次性）**
+1. 用户在**客户端**绑定自己的 **git 仓库**（github/gitea URL + 一个 PAT）。客户端经 V2 加密把 PAT 发给 **HM** → **HM** 把 PAT 写进 **Key Vault**，库里只留 `secret_ref`，返回一个 `resource_binding_id`。
+2. （需要部署时）同样绑定 **VM**（host + ssh key）、数据库、blob，凭据进 KV，各得一个 `resource_binding_id`。
+
+**B. 发起任务**
+3. 用户在**客户端**选 `sub` 模式、填**需求包**（目标/约束/验收/角色/模型/要用哪条 `resource_binding_id`）。
+4. **客户端** → `POST /api/heicode/sub-agile/tasks`（V2 加密 body + 设备签名）。
+5. **HM**：解密 → 验签 → 鉴权 → 查配额 → 把需求包译成 `orchestration_plan`，**从 KV 取出 git 凭据注入**（短期 token），落库，返回 `deployment_id`（= task_id）。**HM 不写代码、不跑 agent。**
+
+**C. 执行（AM 干活，HM 中转）**
+6. **HM** → `POST /api/agent/sub-agile/deployments`（给 **AM**），带：需求、角色/模型、回调地址、HMAC 签名密钥、**git 仓库 + 短期凭据**。
+7. **AM**：把需求拆成多个 **agent**（如 backend / frontend / reviewer），各自分配模型，开始干活。**这里的 agent 才有 AI。**
+8. **AM** 的每个 agent：clone 用户仓库 → 在自己分支（`agent/<role>`）写代码、跑工具/测试 → **commit & push 到用户仓库**（用第 5/6 步注入的短期 PAT）。
+9. **AM** 持续把「每个 agent 在做什么 / 跑了什么工具 / 改了哪些文件 / 当前阶段 / 产物」**流式回调**给 **HM**（HMAC 签名）：`POST /api/agent/callbacks/runtime-events`。
+10. **HM** 收回调 → 聚合事件 + **裁决 `display_status`**（见 §6）+ 持久化。
+
+**D. 客户端看 work**
+11. **客户端**轮询 `GET .../tasks/{id}/workflow`（运行中 3–5s；将来 SSE）→ 拿 `display_status` + 各 agent 状态/动作 + 阶段 + 产物列表，渲染成「work 视图」（参考 Claude Code）。
+
+**E. 合并与产物**
+12. **AM** 阶段结束 → 把各 agent 分支**合并**成一个交付分支（`delivery/<task_id>` 或 PR）→ push 到用户仓库 → 回调通知 **HM** 产物就绪（带 `git_ref` + artifact）。
+13. **客户端**看产物两条路：(a) 直接 `git clone/pull` 用户自己的仓库；(b) 经 **HM** 的 `manifest/files/archive`。
+
+**F. 不满意 → 改 / 重做**
+14. **客户端** → `POST .../messages`（追加要求）或 `.../execute`（重跑）→ **HM** 取最新 accepted 基线转给 **AM** → **AM** 在原产物上改/重做 → 回到第 9 步。
+
+**G. 部署（客户端执行 + 用户确认；HM 只发凭据）**
+15. **客户端**发起部署 → **弹窗让用户确认**（目标 VM / 环境 / 用哪条 binding / 影响）。
+16. 用户确认 → **客户端**向 **HM** 换**短期凭据租约**（HM 从 KV 解出 VM ssh key，经 V2 加密发回客户端，带 TTL）。
+17. **客户端在用户自己机器上执行**部署：`git pull` 用户仓库 → ssh 到 VM → 跑部署命令 → **在 VM 上看日志**。**HM 全程不碰 VM、不执行命令、不看日志**；**HM 只记审计**（谁、哪条 binding、何时、TTL）。
+
+> 一句话区分执行位:**写代码 = AM 沙箱里执行;部署到用户 VM + 看 VM 日志 = 客户端在用户机器上执行;HM 永远只做网关/裁判/凭据中介,不执行任何东西。**
+
+---
+
 ### 3.1 选择 sub + 准备（资源绑定前置）
 
 🟢 客户端选 `mode=sub_agile`（区别于 `swarm`）。
 ✅ **决策（2026-06-02）**：**git 仓库 = 用户绑定自己的仓库**（gitea / github，用户提供 URL）。**没有 Heicode 托管仓库**。
 - **git 流程**（agent 入库/合并、客户端 git pull 看产物）需要先绑定仓库 → 见 §4.1。
-- **未绑仓库时**：走「仅产物」轻量路径——Manager 把 runtime 产物以 `project_folder`（manifest/files/archive）形式给客户端，**无 git、无增量 diff、无分支历史**。
+- **未绑仓库时**：走「仅产物」轻量路径——HM 把 AM 产物以 `project_folder`（manifest/files/archive）形式给客户端，**无 git、无增量 diff、无分支历史**。
 - ❓ 待定（小）：sub 模式是否**强制**绑 git？建议——**全 git 流程需绑仓库；不绑则只能用轻量产物路径**，由产品决定是否在 UI 上「未绑仓库则禁用 sub」。
 
-### 3.2 客户端 → Manager（加密 + 鉴权 + 建任务）
+### 3.2 客户端 → HM（加密 + 鉴权 + 建任务）
 
 🟢 **加密链路**：与模型调用完全一致。
 - 写请求（POST/PUT/DELETE）：`Content-Encoding: heicode-aead-v1`，X25519-ECDH + HKDF + ChaCha20-Poly1305 加密 body，Ed25519 设备签名（`X-Heicode-*`）。
 - GET：无 body 设备签名（同 canonical，body 哈希为空串哈希）。
-- Manager 中间件 `UserOrV2DeviceAuth` 解密 + 验签 + 从设备绑定 token 解析用户身份。
+- HM 中间件 `UserOrV2DeviceAuth` 解密 + 验签 + 从设备绑定 token 解析用户身份。
 
 🟢 **鉴权/配额**：解析 user_id、绑定 scope、计费上下文。
-🟢 **建任务**：`POST /api/heicode/sub-agile/tasks`，body = **需求包**（见客户端接口文档 §3.1），Manager 译成 `orchestration_plan` 并落库，返回 `deployment_id`（= task_id）。
+🟢 **建任务**：`POST /api/heicode/sub-agile/tasks`，body = **需求包**（见客户端接口文档 §3.1），HM 译成 `orchestration_plan` 并落库，返回 `deployment_id`（= task_id）。
 
-### 3.3 Manager → agent_management（分发）
+### 3.3 HM → agent_management（分发）
 
 🟢 `POST /api/agent/sub-agile/deployments`（env 当前指向 `http://20.212.121.126`），Bearer service token。
 🟢 注入：callback URL（`/api/agent/callbacks/runtime-events`）+ HMAC 签名密钥引用 + metadata.manager_deployment_id + 角色/模型 + **资源授权 grants（secret_ref，不含明文）**。
-🟡 **回调竞态**：runtime 回调可能早于 Manager 存 runtime_id → Manager 用「读时收敛」(`reconcileDeploymentFromRuntime`) 兜底（已实现）。
+🟡 **回调竞态**：AM 回调可能早于 HM 存 runtime_id → HM 用「读时收敛」(`reconcileDeploymentFromRuntime`) 兜底（已实现）。
 
 ### 3.4 多 agent 执行 + 流式回传（work 视图，参考 Claude Code）
 
-🟡 **现状**：runtime 通过回调上报 `deployment.status_changed / task.* / handoff.* / artifact.created / phase.changed` 等事件；Manager 聚合成 timeline/events/logs；客户端**轮询**展示。
+🟡 **现状**：AM 通过回调上报 `deployment.status_changed / task.* / handoff.* / artifact.created / phase.changed` 等事件；HM 聚合成 timeline/events/logs；客户端**轮询**展示。
 🔴 **目标（work 视图）**：像 Claude Code 的 work 面板那样**实时流式**展示「每个 agent 正在做什么、跑了哪些工具、产了哪些文件、各阶段进度」。需要补：
 
-1. 🔴 **流式协议**：Manager 提供 `GET .../tasks/{id}/events/stream`（SSE）或 WS，把 runtime 回调实时转发给客户端。**现状无 SSE**，客户端轮询 `/workflow`（3–5s）兜底（见 §5）。
+1. 🔴 **流式协议**：HM 提供 `GET .../tasks/{id}/events/stream`（SSE）或 WS，把 AM 回调实时转发给客户端。**现状无 SSE**，客户端轮询 `/workflow`（3–5s）兜底（见 §5）。
-2. 🔴 **per-agent 富字段**：runtime 在状态/回调里上报每个 agent 的 `tokens / tools(工具调用数) / elapsed_seconds / 当前动作描述 / artifact_ids`。Manager 的 `/workflow` 已预留这些字段（缺值时为 0/空），等 runtime 填。
+2. 🔴 **per-agent 富字段**：AM 在状态/回调里上报每个 agent 的 `tokens / tools(工具调用数) / elapsed_seconds / 当前动作描述 / artifact_ids`。HM 的 `/workflow` 已预留这些字段（缺值时为 0/空），等 AM 填。
-3. 🔴 **artifact 来源角色**：runtime 给 artifact 打 `source_agent_role`，Manager 才能把产物准确归到对应 agent。
+3. 🔴 **artifact 来源角色**：AM 给 artifact 打 `source_agent_role`，HM 才能把产物准确归到对应 agent。
 4. 🔴 **阶段细分**：runtime 上报 `phases[]`（每阶段 status/agents），而非单个 `phase` 字符串。
 
 > work 视图的最小可用版（不等 SSE）：客户端轮询 `/workflow` 拿 `agents[] + phases[] + metrics`，3–5s 刷新即可先跑起来；SSE 是体验升级项。
@@ -114,27 +175,27 @@
 
 ❓ **关键决策（§7 详述）**：
 - 仓库在哪？（Heicode 托管 vs 用户绑定的 git）
-- 谁负责合并？（agent_management 合并后给一个最终分支/commit；Manager 不碰 git 操作，只记录引用）
+- 谁负责合并？（agent_management 合并后给一个最终分支/commit；HM 不碰 git 操作，只记录引用）
 - 合并策略？（按目录隔离自然无冲突：backend/ + frontend/ 并列；同文件冲突由一个「集成 agent」或规则解决）
 
-🟡 **现状**：sub 模式 runtime 产物是 **blob/文本 artifact**（每角色一个 project_folder，多角色=多 artifact，见实测）；**尚未真正 git 入库 + 合并**。当前「合并成完整产物」靠客户端把多个 artifact 的 manifest 拼起来展示。git 化是目标态。
+🟡 **现状**：sub 模式 AM 产物是 **blob/文本 artifact**（每角色一个 project_folder，多角色=多 artifact，见实测）；**尚未真正 git 入库 + 合并**。当前「合并成完整产物」靠客户端把多个 artifact 的 manifest 拼起来展示。git 化是目标态。
 
 ### 3.6 产物查看（两条路）
 
-🟢 **经 Manager**（不绑 git 也能看）：`/artifacts`（列表，主产物归一化 `project_folder`）→ `/manifest`（文件树）→ `/files?path=`（单文件）→ `/archive`（整包 zip）。
+🟢 **经 HM**（不绑 git 也能看）：`/artifacts`（列表，主产物归一化 `project_folder`）→ `/manifest`（文件树）→ `/files?path=`（单文件）→ `/archive`（整包 zip）。
 🔴 **经 git**（绑了仓库）：客户端直接 `git clone/pull` 用户自己的仓库,看完整工程 + 历史 + diff。这是用户「通过 git 了解产物」的路径。
 
 ### 3.7 不满意 → 修改 / 重做
 
-🟡 **修改（续跑）**：`POST .../tasks/{id}/messages`（追加要求）→ Manager 取**最新 accepted 本地修改 revision** 作基线 → runtime 在原产物上改。（Manager 侧 revision 机制已实现；runtime 真正「中途续跑」🔴待支持）
+🟡 **修改（续跑）**：`POST .../tasks/{id}/messages`（追加要求）→ HM 取**最新 accepted 本地修改 revision** 作基线 → AM 在原产物上改。（HM 侧 revision 机制已实现；AM 真正「中途续跑」🔴待支持）
 🔴 **重做**：`POST .../tasks/{id}/execute`（或新增 `/redo`）→ runtime 丢弃旧产物重新生成。需 runtime 支持「redo」语义。
 🟢 **本地修改回传**：用户在本地改了产物 → `POST .../local-edits` 存为新 revision（accepted），后续续跑/重做以它为基线。
 
 ### 3.8 部署（✅ 必须客户端执行 + 必须用户确认）
 
-✅ **决策（2026-06-02）**：**部署绝对走客户端,且必须用户显式确认才执行**。Manager 不自动部署、runtime 不自动部署。
+✅ **决策（2026-06-02）**：**部署绝对走客户端,且必须用户显式确认才执行**。HM 不自动部署、AM 不自动部署。
-- 流程：客户端发起部署 → **弹用户确认**(目标/环境/影响) → 用户确认 → 客户端向 Manager 的**加密密钥接口**换取**短期凭据租约**(VM SSH key / git PAT 等从 KV 解出,经 V2 加密通道回客户端,带 TTL) → **客户端本地执行**(git pull 用户仓库 → push/部署到 VM,或连库迁移)。
+- 流程：客户端发起部署 → **弹用户确认**(目标/环境/影响) → 用户确认 → 客户端向 HM 的**加密密钥接口**换取**短期凭据租约**(VM SSH key / git PAT 等从 KV 解出,经 V2 加密通道回客户端,带 TTL) → **客户端本地执行**(git pull 用户仓库 → push/部署到 VM,或连库迁移)。
-- Manager 角色:**只发短期凭据 + 记审计**(谁、哪条 binding、何时、TTL),不代执行。
+- HM 角色:**只发短期凭据 + 记审计**(谁、哪条 binding、何时、TTL),不代执行。
 - 凭据租约:短 TTL、可吊销、用完即弃;高危目标(如生产)可叠加**审批门**(waiting_approval)后再发租约。
 🟡 **现状**:有云部署控制面占位(`/deployments`,返回 `executor:pending_worker`);凭据租约模型(approval→lease)有骨架。🔴 待建:客户端取凭据的加密接口 + 客户端本地执行器。
 
@@ -147,9 +208,9 @@
 ### 4.0 通用模型
 
 每个资源绑定 = `{ resource_binding_id, type, name, metadata(非敏感), secret_ref(azkv://…), permission_scope, binding_scope(租户/工作区), status }`。
-- 客户端**只传 `resource_binding_id`** 给任务；Manager 内部解析为凭据注入 runtime。
+- 客户端**只传 `resource_binding_id`** 给任务；HM 内部解析为凭据注入 AM。
 - 客户端**禁止 inline** secret_ref / AccessKey / 连接串。
-- 凭据录入**一次性**：客户端经 V2 加密通道把凭据传给 Manager → Manager 写 KV → 库里只留 `azkv://`。
+- 凭据录入**一次性**：客户端经 V2 加密通道把凭据传给 HM → HM 写 KV → 库里只留 `azkv://`。
 
 ### 4.1 Git 仓库绑定 ✅（已定方向）
 
@@ -158,10 +219,10 @@
 | 项 | 方案（已定 / 建议） |
 |---|---|
 | **仓库归属** | ✅ **用户自己的仓库**。用户提供 `repo_url`（github.com/... 或自建 gitea URL）。无 Heicode 托管仓库。 |
-| **绑定鉴权（用户输入密钥）** | ✅ **HTTPS + 细粒度 PAT（个人访问令牌）为主**——github 与 gitea **通用**、用户只需粘贴一个 token、可按仓库范围授权、可随时吊销、不暴露账号密码。流程：用户在自己 git 生成范围化 PAT（建议 `repo` 读写）→ 客户端经 V2 加密通道把 PAT 传 Manager → Manager 写 KV，库里只留 `secret_ref`。**备选**：SSH deploy key（用户把 Manager 出示的公钥加到仓库 Deploy keys；适合不愿发 PAT 的场景）。 |
+| **绑定鉴权（用户输入密钥）** | ✅ **HTTPS + 细粒度 PAT（个人访问令牌）为主**——github 与 gitea **通用**、用户只需粘贴一个 token、可按仓库范围授权、可随时吊销、不暴露账号密码。流程：用户在自己 git 生成范围化 PAT（建议 `repo` 读写）→ 客户端经 V2 加密通道把 PAT 传 HM → HM 写 KV，库里只留 `secret_ref`。**备选**：SSH deploy key（用户把 HM 出示的公钥加到仓库 Deploy keys；适合不愿发 PAT 的场景）。 |
 | **provider 识别** | 由 `repo_url` 推断（github.com → github API；其他 → gitea，需带 `api_base`）。metadata：`provider / repo_url / default_branch / api_base?`。 |
 | **绑定粒度** | 单仓库级（一个 binding = 一个 repo + 默认分支 + 允许路径 allowed_paths）。permission_scope：`repo:read` / `repo:write`。 |
-| **凭据有效性/过期** | PAT 会过期/被吊销 → Manager 在用前**预检**（一次 `GET repo`），失效则标记 binding `status=invalid` 并提示用户**重新绑定**，不静默失败。 |
+| **凭据有效性/过期** | PAT 会过期/被吊销 → HM 在用前**预检**（一次 `GET repo`），失效则标记 binding `status=invalid` 并提示用户**重新绑定**，不静默失败。 |
 | **工单 / 里程碑** | **可选增强**（默认关，用户显式开）：把 sub 子任务映射为 **issues**、阶段映射为 **milestone**、handoff/审批映射为 **issue 评论**，让用户在自己 git 看板跟踪 agent 进度。需要 PAT 额外授 issues 权限。 |
 | **分支模型 / 合并** | 见 §7。 |
 
@@ -175,8 +236,8 @@
 `type=blob`，metadata：账号/容器；key/SAS 进 KV。用于大产物/数据集存取。
 
 ### 4.5 凭据生命周期
-- 录入 → KV（Manager 写）→ 只存 secret_ref。
+- 录入 → KV（HM 写）→ 只存 secret_ref。
-- 使用 → 任务/部署时 Manager 从 KV 解出注入 runtime，或发**短期租约**（TTL + 可吊销）给客户端。
+- 使用 → 任务/部署时 HM 从 KV 解出注入 AM，或发**短期租约**（TTL + 可吊销）给客户端。
 - 审计 → 谁在什么 scope 用了哪条绑定、发了哪些租约、何时吊销（只记 secret_ref + 打码摘要）。
 
 ---
@@ -186,22 +247,64 @@
 | 阶段 | 协议 | 状态 |
 |---|---|---|
 | 现状 | 客户端轮询 `GET .../workflow`（运行中 3–5s、终态 15–30s） | 🟢 |
-| 目标 | `GET .../tasks/{id}/events/stream`（SSE）：Manager 把 runtime 回调实时转发；事件含 `agent.action / tool.call / artifact.created / phase.changed / log.line` | 🔴 |
+| 目标 | `GET .../tasks/{id}/events/stream`（SSE）：HM 把 AM 回调实时转发；事件含 `agent.action / tool.call / artifact.created / phase.changed / log.line` | 🔴 |
 
 **规范**：
 - SSE event 统一信封：`{ event_type, deployment_id, agent_id?, phase?, occurred_at, payload }`。
-- 客户端断线重连用 `Last-Event-ID`（基于 Manager 的事件游标）。
+- 客户端断线重连用 `Last-Event-ID`（基于 HM 的事件游标）。
 - **降级**：SSE 不可用时自动回落轮询，UI 行为一致（只是延迟）。
 - 客户端**不要**订阅不存在的流（未上线前 `/events/stream` 返回未实现，别硬连）。
 
 ---
 
-## 6. 状态模型（唯一裁判 = Manager）
+## 6. 状态模型与 `display_status` 裁决（完整定义，给三方）
 
-🟢 三层 + 裁决（见客户端接口文档 §4）：
+🟢 已实现。**这是全文最关键的概念之一,三方必须一致理解。**
-- `cloud_deployment_status`（Manager 控制面）/ `runtime_execution_status`（runtime 事实）/ **`display_status`（客户端只看这个）**。
+
-- 裁决：runtime `completed` + 有真实交付物（非 `metadata.synthesized`、非纯总结）→ `completed`；否则降级 `needs_codegen`（只有方案/总结）/ `completed_without_deliverable`（无产物）。
+### 6.1 为什么要"裁决"
-- `waiting_approval` 透传（高风险/需审批时）。
+**AM（agent_management）只会上报"执行事实"**(它说 `completed` 只代表"我跑完了"),但"跑完了"**不等于"交付成功"**——可能跑完了却没产出真实代码(只产了一段总结/兜底)。**如果直接把 AM 的 `completed` 给用户,会出现"显示成功、实际没东西"的假成功。** 所以由 **HM 做唯一裁判**:综合 AM 的状态 + 实际产物,算出一个**给用户看的最终状态 `display_status`**。**客户端只看 `display_status`,不看 AM 的原始状态。**
+
+### 6.2 三层状态（`GET .../tasks/{id}/workflow` 同时返回）
+| 字段 | 含义 | 谁产生 |
+|---|---|---|
+| `cloud_deployment_status` | HM 控制面状态（accepted/running/stopped…） | HM |
+| `runtime_execution_status` | **AM 上报的原始执行状态**（AM 说它自己到哪了） | AM |
+| **`display_status`** | **HM 裁决后、给用户展示的唯一状态** | **HM** |
+
+### 6.3 `display_status` 的全部取值（枚举）
+| 值 | 含义 | 客户端该怎么展示 |
+|---|---|---|
+| `accepted` | 已受理,排队中 | 进行中（灰/黄） |
+| `running` | 正在执行 | 进行中（蓝，转圈） |
+| `waiting_approval` | 等用户审批高风险操作 | 黄，弹审批 |
+| `completed` | **完成,且有真实可交付的代码产物** | **绿,成功** |
+| `needs_codegen` | AM 说完成了,但**只产了方案/总结、没有真实代码** → 需继续生成 | 黄,提示"需补充代码/继续" |
+| `completed_without_deliverable` | AM 说完成了,但**完全没有产物** | 红/橙,**视为没成功** |
+| `failed` | 执行失败 | 红,失败 |
+| `stopped` | 被用户/系统停止 | 灰,已停止 |
+
+### 6.4 裁决算法（HM 收到 AM 状态后怎么算 `display_status`）
+```text
+输入: AM 的 runtime_status, 该任务的 artifacts 列表
+规则:
+  if runtime_status 不是 "completed":
+        display_status = runtime_status 原样透传
+        (running / waiting_approval / failed / stopped / accepted ...)
+  else  # AM 说 completed,进入"是否真有交付物"的裁决
+        遍历该任务的 artifacts:
+          只要存在 1 个"真实交付物"        → display_status = "completed"   ✅
+        否则 if 有 artifacts 但全是总结/兜底  → display_status = "needs_codegen"
+        否则 (一个 artifact 都没有)          → display_status = "completed_without_deliverable"
+```
+**"真实交付物"的判定**(逐条排除"假产物"):一个 artifact 满足以下**才算真实**——
+- `metadata.synthesized != true`(不是 AM 的兜底占位产物),**且**
+- 不是纯总结类(标题/正文不含 "runtime execution summary"、"without per-agent artifacts" 等兜底标记;`artifact_type` 不是 `document`/`summary`),**且**
+- 属于交付类型(`code_patch`/`code_bundle`/`diff`/`test_report`/`deployment_manifest` 等)或带有"改了 N 个文件"的结构化信号。
+
+> 一句话:**`completed` 必须"AM 说完成 + 真的有代码产物"两个条件都满足;只有总结没代码 = `needs_codegen`;啥都没有 = `completed_without_deliverable`。客户端据此就能准确区分成败,不会被假成功骗到。**
+
+### 6.5 成功判据（客户端用）
+> **`display_status == "completed"` 且 artifacts 非空 = 真成功**;其余都不是成功(各有不同处理)。
 
 ---
 
@@ -219,11 +322,11 @@
 | 点 | 方案（已定 / 建议） |
 |---|---|
 | 仓库归属 | ✅ **用户绑定的仓库**（github/gitea，用户给 URL）。无托管仓库。 |
-| 谁执行 git | ✅ **agent_management 执行**所有 git 操作（clone 用户仓库、各 agent commit 到分支、合并到交付分支、push）——用 Manager 注入的**短期 PAT**（从 KV 解出，最小权限）。Manager **只记录引用**（repo_url/branch/commit_sha）并在 artifact metadata 带 `git_ref`，**不做 git**。 |
+| 谁执行 git | ✅ **agent_management 执行**所有 git 操作（clone 用户仓库、各 agent commit 到分支、合并到交付分支、push）——用 HM 注入的**短期 PAT**（从 KV 解出，最小权限）。HM **只记录引用**（repo_url/branch/commit_sha）并在 artifact metadata 带 `git_ref`，**不做 git**。 |
 | 提交身份 | agent 提交用一个明确的 **bot 身份**（如 `heicode-agent <bot@heicode>`）+ commit message 带任务/agent/角色标注,便于用户在 git 历史里分辨人/机改动。 |
 | 合并冲突 | 目录隔离（backend/、frontend/ 并列）天然无冲突；同文件冲突由「集成 agent」或规则化合并解决，无法自动解则上报 `needs_codegen` 让用户介入/再跑一轮。 |
 | 写入方式 | ❓建议：agent **不直接 push 到用户的 `main`**,而是 push 到 `delivery/<task_id>` 或开 **PR**,由用户在自己 git 上 review/merge → 既安全又复用用户的 PR/CI 工作流。是否强制 PR 模式待定。 |
-| 客户端看产物 | 直接对用户自己的仓库 `git clone/pull`；或经 Manager `/archive`（不想本地 git 时）。 |
+| 客户端看产物 | 直接对用户自己的仓库 `git clone/pull`；或经 HM `/archive`（不想本地 git 时）。 |
 
 ---
 
@@ -233,8 +336,8 @@
 |---|---|---|
 | 1 | git 归属 | ✅ **用户绑自己的仓库**(github/gitea,给 URL),无托管仓库 |
 | 2 | git 鉴权 | ✅ **HTTPS + 细粒度 PAT 为主**(github/gitea 通用、用户粘贴 token)、SSH deploy key 备选 |
-| 3 | 部署 | ✅ **必须客户端执行 + 必须用户确认**;Manager 只发短期凭据 + 记审计 |
+| 3 | 部署 | ✅ **必须客户端执行 + 必须用户确认**;HM 只发短期凭据 + 记审计 |
-| 4 | git 执行方 | ✅ **agent_management 执行 git**(用注入的短期 PAT),Manager 只记引用 |
+| 4 | git 执行方 | ✅ **agent_management 执行 git**(用注入的短期 PAT),HM 只记引用 |
 | 5 | 工单/里程碑 | 可选增强,默认关 —— ❓ 是否纳入 v1? |
 | 6 | 流式 | v1 先轮询 work、SSE 放 v1.1 —— ❓ 接受? |
 | 7 | 写入方式 | ❓ agent 是 push 到 `delivery/<task_id>` 分支 / 开 PR,还是直接进 main? 建议 PR/分支模式 |
@@ -254,21 +357,21 @@
 - **.gitignore + 防止误提交密钥**：agent **绝不能把任何凭据/secret_ref/.env 提交进仓库**;runtime 侧需有 secret 扫描,提交前拦截。
 
 ### 9.2 凭据与安全
-- **PAT 最小权限 + 短时效**：注入 runtime 的 PAT 应尽量是**短期/单仓库范围**;若用户给的是长期 PAT,Manager 至少做范围校验并提醒。
+- **PAT 最小权限 + 短时效**：注入 AM 的 PAT 应尽量是**短期/单仓库范围**;若用户给的是长期 PAT,HM 至少做范围校验并提醒。
-- **凭据只在内存**：runtime 用完 PAT 不落盘、不进日志;Manager 注入走加密。
+- **凭据只在内存**：AM 用完 PAT 不落盘、不进日志;HM 注入走加密。
 - **scope 隔离**：一条 binding 的凭据**只能被该用户(binding_scope)的任务**使用,跨用户禁用。
-- **审计**：每次「解 KV、注入 runtime、发客户端租约」都留审计(user / binding / 用途 / 时间 / TTL),明文不入审计。
+- **审计**：每次「解 KV、注入 AM、发客户端租约」都留审计(user / binding / 用途 / 时间 / TTL),明文不入审计。
 - **吊销**：用户删 binding 或吊销租约后,进行中的任务该如何? 建议:已注入的短期凭据自然过期,新操作立即失效。
 
 ### 9.3 任务执行与失败
 - **预算/配额**：每任务 token/时长/成本上限;**跑超预算**时如何? 建议:到上限**暂停 + 标 `needs_codegen`/`budget_exceeded`**,让用户决定续不续,不静默烧钱。
 - **中途停止(stop)**：停止时已 commit 的代码**保留在分支**(不回滚),任务标 stopped;用户可在该分支续跑或丢弃。
-- **agent 崩溃 / 部分失败**：多 agent 里某个失败 → 整体 `completed_without_deliverable`/部分交付? 建议:Manager 裁决时若有 agent 失败但有有效产物,仍可 `completed` 但带 warning;全失败则 failed。
+- **agent 崩溃 / 部分失败**：多 agent 里某个失败 → 整体 `completed_without_deliverable`/部分交付? 建议:HM 裁决时若有 agent 失败但有有效产物,仍可 `completed` 但带 warning;全失败则 failed。
 - **幂等**：同一需求重复提交(网络重试)用 `X-Idempotency-Key` 去重,避免建重复任务/重复 git 分支。
-- **超时**：runtime 长时间无回调 → Manager 标 `stale`/超时,客户端可见。
+- **超时**：AM 长时间无回调 → HM 标 `stale`/超时,客户端可见。
 
 ### 9.4 产物与验收
-- **验收标准如何验证**：需求包里的 `acceptance_criteria` 谁来验? 建议:runtime 跑测试(若有)并把**测试结果**作为 artifact 回传;Manager 把「测试通过」纳入 `completed` 裁决参考。
+- **验收标准如何验证**：需求包里的 `acceptance_criteria` 谁来验? 建议:AM 跑测试(若有)并把**测试结果**作为 artifact 回传;HM 把「测试通过」纳入 `completed` 裁决参考。
 - **产物版本/标签**：每次交付打 tag(`delivery-<task>-rev<N>`)或记 commit_sha,便于回溯 + 部署指定版本。
 - **修改 vs 重做的边界**：`/messages`(在现有产物上改)与 `/redo`(重新生成)语义要清晰;redo 是否丢弃旧分支? 建议:redo 开新分支,旧的保留可对比。
 
@@ -280,7 +383,7 @@
 - **rate limit**：github/gitea API 有限流,频繁 commit/查询要退避,避免触发封禁。
 - **私有 / 公开仓库**：都支持;私有仓库凭 PAT 访问。
 - **网络可达**：runtime 要能访问用户的 git(公网 github 没问题;自建 gitea 若在内网,需用户提供可达地址或白名单)。
-- **webhook 回写(可选)**：若用户在自己仓库手动改了代码,是否要 webhook 通知 Manager 同步基线? v2 考虑。
+- **webhook 回写(可选)**：若用户在自己仓库手动改了代码,是否要 webhook 通知 HM 同步基线? v2 考虑。
 
 ### 9.7 部署细节(客户端执行 + 用户确认)
 - **确认内容**：弹窗要清楚展示**部署目标、环境(prod/staging)、用哪条 binding、影响范围**,用户确认后才发凭据。
@@ -304,7 +407,7 @@
 - 🟡→🟢 资源绑定 API（git/vm/db/blob CRUD + 凭据写 KV + secret_ref；KV 通后启用）
 - 🔴 SSE 事件流转发（`/events/stream`）
 - 🔴 给 agent/客户端的「绑定读取 + 短期租约」接口（部署取凭据用）
-- 🟡 workflow per-agent 富字段（已预留，等 runtime 填）
+- 🟡 workflow per-agent 富字段（已预留，等 AM 填）
 - 🔴 资源绑定 UI（重做干净版）
 
 **agent_management（runtime）**
@@ -317,7 +420,7 @@
 **桌面客户端**
 - 🟡 work 视图（先轮询 workflow，SSE 后接）
 - 🔴 多 artifact 合并展示（多角色产物拼成一棵完整项目树）
-- 🔴 经 git 看产物 / 本地 git / 经 Manager 取凭据部署
+- 🔴 经 git 看产物 / 本地 git / 经 HM 取凭据部署
 
 ---