Merge branch 'main' into fix/orphan-agent-lifecycle

docs/integration/event-schema.md

@@ -14,7 +14,7 @@
 
 - Swarm → HM：`POST {callback.url}`（create 时下发）。
 - 鉴权二选一：服务令牌 `X-Agent-Service-Token`（或 `Authorization: Bearer`），或 HMAC 签名。
-- **HMAC 签名（已实现，与 HM 一致）**：
+- **HMAC 签名（机制已实现，规范与 HM 对齐；待主链路端到端联调验收）**：
   - 头：`X-Agent-Timestamp`（Unix 毫秒）、`X-Agent-Signature`、`X-Agent-Event-Id`、`X-Correlation-ID`（均含 `X-Agnet-` 兼容别名）。
   - 规范串：`canonical = f"{timestamp}.{event_id}.{raw_body}"`。
   - 签名：`X-Agent-Signature = "sha256=" + hex(HMAC_SHA256(secret, canonical))`。

docs/integration/runtime-contract.md

@@ -85,10 +85,14 @@ Swarm 拉起每个专家 agent 时注入以下进程环境变量（`agent/main.p
 | `AGENT_ID` | agent 实例 id（唯一） | **Swarm launcher** |
 | `AGENT_CAPABILITIES` | 能力集合（逗号分隔） | **Swarm launcher**（`AGENT_LAUNCH_CAPABILITIES` 池策略） |
 | `HEICODE_USER_ID` | 发起用户；用于每用户并发上限 `MAX_AGENTS_PER_USER`（注册时强制） | **Swarm 从 create `x-user-id` 透传** |
-| `WORKSPACE_DIR` / `GIT_REPO_URL` | 可选：工作区 / 代码仓 | 资源授权 |
+| `WORKSPACE_DIR` | 可选：工作区根 | 部署（`WORKSPACE_DIR`） |
+| `GIT_REPO_URL` | 代码仓克隆地址；agent 有此值才 clone | **Swarm 从 git `resource_grant.metadata.repo_url` 解析** |
+| `GIT_USERNAME` / `GIT_PASSWORD` | git HTTPS 凭据（注入 clone URL） | **Swarm 从 git `resource_grant.secret_ref`（`azkv://`）解析** |
+| `GIT_BASE_BRANCH` | 可选：基线分支（默认 `main`） | git grant `metadata.base_branch` |
 
 **约束**：
 - 模型 key 由 **Swarm 服务端从 `billing_context.secret_ref`（`azkv://`）解析**（`resolve_model_key`：override → azkv（部署 SecretResolver / dev `HEICODE_SECRET_<name>`）→ 编排器 `OPENAI_API_KEY` 兜底）后注入被拉起 agent 的 env。key **不入** create 请求体 / 回调 / 日志 / argv（满足 §3.1）；解析不到则 agent keyless 启动并明确报错（不伪造）。`billing_context` 的 `newapi_user_ref`/`quota_ref` 仍仅为归因元数据。见 [usage-billing-schema.md §2](./usage-billing-schema.md)。
+- **git 仓库绑定**（agent_swarm#63 / HM #92）由 **Swarm 服务端从 `resource_grants` 里 `resource_type=git` 的 grant 解析**（`resolve_git_grant`）：仓库地址 = `grant.metadata.repo_url`（非密文，inline 注入 `GIT_REPO_URL`）；git 凭据 = `grant.secret_ref`（`azkv://`，同模型 key 路径解析 → 注入 `GIT_USERNAME`/`GIT_PASSWORD`）。git 凭据**不入** create 请求体 / 回调 / 日志 / argv；k8s 后端 `GIT_PASSWORD` 经 per-swarm Secret 的 `secretKeyRef` 注入（绝不内联 PodSpec）。grant 有 repo 无凭据时仍注入 `GIT_REPO_URL`（公有仓可 clone；私有仓 clone 报错，不伪造）。git KV secret 值约定为 JSON `{"git_username","git_password"}`（接受 `git_token`/`token` 形式 + 裸 token），**待 HM #92 对齐**。同一用户 agent 池注入同一 git grant。
 - 同一用户的专家 agent 注入**同一把** `sk-` + `OPENAI_API_BASE=HM/v1`，计费归一到发起用户；`task_executor` 随模型请求带 `X-Agent-*` 归因头供 HM/NewAPI 关联。token 吊销走 §3.3.1 A.5 的 `swarm.pool_terminated` 握手（per-user，全部 run stop 后吊销）。
 - **运行时事件前置**：只有 (i) HM 真把 create 派发到编排器（`SWARM_RUNTIME_ENABLED=true`，非 manager-local 适配器）且 (ii) Swarm 已按上表拉起 agent 并连入，编排器才回推 `task.*`/`swarm.*` 运行时事件（否则 events feed 仅有 HM 控制面 `deployment.status_changed`，见 #39）。
 

docs/integration/security-boundary.md

@@ -60,7 +60,8 @@
 - 服务间鉴权：HM→Swarm 用 `AGENT_RUNTIME_SERVICE_TOKEN`（Bearer）；回调 HMAC 签名。
 - **每用户并发 Agent 配额**：一个 `user_id` 同时连接的 Agent 数上限为 `MAX_AGENTS_PER_USER`（env，默认 10）。注册（WS `register` 消息携带 `user_id`）超额即被拒绝（回 `registration_rejected` 并关闭，code 1008），断开后释放名额。归因主轴仍为 `user.id`/`channelId`。未带 `user_id` 的 Agent 为 unbound，不计入该配额。实现：`ConnectionManager.can_bind_user/bind_user/unbind` + 注册处强制；测试 `scripts/test-max-agents-per-user.py`。
 - **Swarm 拉起 agent + 服务端解析 key（team 决议，runtime-contract §3.3）**：由 **Swarm 运行时**（`orchestrator/agent_launcher.py`）拉起专家 agent 池（拉起数 `min(池大小, MAX_AGENTS_PER_USER − 已连)`，与上面的注册兜底一致）。模型 key 由 **Swarm 从 `billing_context.secret_ref`（`azkv://`）服务端解析**后注入被拉起 agent——**不入** create 请求体 / 回调 / 日志 / argv。azkv 真实解析为部署侧 SecretResolver；dev/CI 用 `HEICODE_SECRET_<name>`。解析不到即 keyless 启动并明确报错（不伪造）。
-- **K8s pod 边界（`AGENT_LAUNCH_BACKEND=kubernetes`，生产）**：**每 agent 一个 Pod**，带 CPU/内存 requests+limits、标签（`heicode-swarm-id`/`heicode-user-id`）。模型 key 经**每-swarm k8s Secret**（manifest via stdin 应用）由 Pod `secretKeyRef` 引用，**绝不内联进 PodSpec env**（否则暴露于 etcd / `kubectl get pod -o yaml`）。编排器需 `kubectl` + 一个仅对 `AGENT_POD_NAMESPACE` 有 pod/secret 权限的 **ServiceAccount（最小 RBAC）**；Pod 出网由 NetworkPolicy 限定到 HM `/v1` + git；停止/删除按标签 `kubectl delete pod,secret`。**更硬化（推荐 Infra 评估）**：azkv **CSI SecretProviderClass** 让 Pod 直接从 Key Vault 挂载密钥，编排器**全程不接触明文**。代码执行沙箱仍按 §8.1 在 Pod 层强制。
+- **Git 仓库绑定凭据服务端解析（agent_swarm#63 / HM #92）**：git 绑定经 `resource_grants` 里 `resource_type=git` 的 grant 下发。Swarm 同模型 key 方式**服务端解析**（`resolve_git_grant`）：`metadata.repo_url`（非密文）→ `GIT_REPO_URL`；`secret_ref`（`azkv://` git 凭据引用）→ `GIT_USERNAME`/`GIT_PASSWORD`。git 凭据**不入** create 请求体 / 回调 / 日志 / argv；明文 git token/密码不得进 create 体（`_reject_plaintext_secrets` 已覆盖 `resource_grants`）。git KV secret 值约定 JSON `{"git_username","git_password"}`（接受 token 形式），**待 HM #92 对齐**。
+- **K8s pod 边界（`AGENT_LAUNCH_BACKEND=kubernetes`，生产）**：**每 agent 一个 Pod**，带 CPU/内存 requests+limits、标签（`heicode-swarm-id`/`heicode-user-id`）。模型 key 与 **git 凭据（`GIT_PASSWORD`）** 均经**每-swarm k8s Secret**（manifest via stdin 应用）由 Pod `secretKeyRef` 引用，**绝不内联进 PodSpec env**（否则暴露于 etcd / `kubectl get pod -o yaml`）；`GIT_REPO_URL`/`GIT_USERNAME` 为非密文，inline 注入。编排器需 `kubectl` + 一个仅对 `AGENT_POD_NAMESPACE` 有 pod/secret 权限的 **ServiceAccount（最小 RBAC）**；Pod 出网由 NetworkPolicy 限定到 HM `/v1` + git；停止/删除按标签 `kubectl delete pod,secret`。**更硬化（推荐 Infra 评估）**：azkv **CSI SecretProviderClass** 让 Pod 直接从 Key Vault 挂载密钥，编排器**全程不接触明文**。代码执行沙箱仍按 §8.1 在 Pod 层强制。
 - 🟡 待接入：多租户运行时隔离（命名空间/网络/配额）由 Agent 平台（AKS Workload Identity）承载，非本仓编排器；归因主轴为 `user.id`/`channelId`（见 `usage-billing-schema.md`），不引入 tenant 概念。
 
 ## 7. 外部 API 与传输