Merge pull request #53 from xmindlab-heicode/feat/hm-swarm-query-phase1

feat(swarm): HM-side Swarm Run read-only query — Phase1 (#45)

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

@@ -289,6 +289,37 @@ signature = base64( ed25519_sign( device_priv, sha256(canonical) ) )
 
 ---
 
+## 5.2 Swarm 运行查询 🟡（#45 Phase1 · 只读预览）
+
+多 Agent 蜂群运行(`agent_swarm` / HeiCode Swarm)的**只读查询**。数据全部来自 HM 已持久化的运行时回调(Swarm → HM 带签名回调),**无需实时调 Swarm**,故不受 `agent_swarm#2` 契约冻结阻塞。
+
+| 方法 | 路径 | 说明 | 状态 |
+|---|---|---|---|
+| GET | `/api/heicode/swarms` | 列出我的 swarm 运行 | 🟢 本地数据 |
+| GET | `/api/heicode/swarms/:id` | 单个运行状态(:id = deployment_id / swarm_id / correlation_id 任一) | 🟢 |
+| GET | `/api/heicode/swarms/:id/events?after=&limit=` | 事件增量拉取(`after`=上次返回的 `next_after`,oldest-first) | 🟢 |
+| GET | `/api/heicode/swarms/:id/artifacts` | 从已存事件派生的产物 | 🟢(派生) |
+| POST | `/api/heicode/swarms/:id/stop` | 停止运行(**写**) | 🟡 待 `agent_swarm#2` 冻结 + `SWARM_RUNTIME_ENABLED=true` |
+
+```json
+// GET /api/heicode/swarms/:id
+{ "success": true, "data": {
+  "deployment_id":"dep_…", "swarm_id":"swarm-…", "correlation_id":"…",
+  "status":"running", "phase":"…", "runtime_state":"…", "failure_reason":"",
+  "created_at":"…","updated_at":"…","runtime_last_sync_at":"…" }}
+
+// GET /api/heicode/swarms/:id/events?after=120
+{ "success": true, "data": {
+  "items":[ {"id":121,"event_type":"task.completed","task_id":"…","result":"ok","occurred_at":"…","payload":{…}} ],
+  "next_after":121, "count":1 }}
+```
+
+- 状态机(契约 §4):`waiting_approval → running →(blocked ⇄ running)→ completed/failed/stopped`。
+- `events` 用 `id` 游标(`next_after`)增量轮询;事件 `payload` **已脱敏**(递归剔除 `secret_ref`/credentials/大字段 + `RedactText` 兜底,绝不下发 `azkv://` secret_ref 或 sk-/Bearer)。事件查询按**当前用户**作用域(防跨用户泄漏)。
+- `stop` 在契约冻结前**一律不伪造成功**:未启用 → `POLICY_REJECTED`;即使 `SWARM_RUNTIME_ENABLED=true` 也返回 `NOT_IMPLEMENTED`(未真正转发运行时),直到 `agent_swarm#2` 冻结后接上真实 stop。
+
+---
+
 ## 6. 直连 Agent（客户端 ↔ agent，A2A 协议）
 
 > 客户端**直接连 agent 子域名**(§5 的 `subdomain`),不经过 HM。agent 是 AM 的 `coding_a2a_agent`,走 **A2A 协议**。