docs(integration): sub-mode spec — lock git/deploy decisions + add edge-case analysis

- git = user-bound own repo (github/gitea by URL); auth = fine-grained PAT
  (universal, paste a token) with SSH deploy key fallback.
- deploy MUST be client-executed with mandatory user confirmation; Manager
  only issues short-lived encrypted credentials + audits.
- git executed by agent_management with an injected short-lived PAT; Manager
  records refs only; agents push to delivery/PR branch, not main.
- New section 9: additional details to settle before v1 (repo state, secret
  hygiene, budget/cancel/crash handling, acceptance, concurrency, provider
  limits, deploy confirm/rollback, work-view UX).

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

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

@@ -75,7 +75,10 @@
 ### 3.1 选择 sub + 准备（资源绑定前置）
 
 🟢 客户端选 `mode=sub_agile`（区别于 `swarm`）。
-❓ **是否必须先绑 git 才能用 sub？** → 见 §4.1。**建议：不强制**——默认走 **Heicode 托管仓库**（零配置即用），绑自己的 git 是高级选项。
+✅ **决策（2026-06-02）**：**git 仓库 = 用户绑定自己的仓库**（gitea / github，用户提供 URL）。**没有 Heicode 托管仓库**。
+- **git 流程**（agent 入库/合并、客户端 git pull 看产物）需要先绑定仓库 → 见 §4.1。
+- **未绑仓库时**：走「仅产物」轻量路径——Manager 把 runtime 产物以 `project_folder`（manifest/files/archive）形式给客户端，**无 git、无增量 diff、无分支历史**。
+- ❓ 待定（小）：sub 模式是否**强制**绑 git？建议——**全 git 流程需绑仓库；不绑则只能用轻量产物路径**，由产品决定是否在 UI 上「未绑仓库则禁用 sub」。
 
 ### 3.2 客户端 → Manager（加密 + 鉴权 + 建任务）
 
@@ -127,12 +130,13 @@
 🔴 **重做**：`POST .../tasks/{id}/execute`（或新增 `/redo`）→ runtime 丢弃旧产物重新生成。需 runtime 支持「redo」语义。
 🟢 **本地修改回传**：用户在本地改了产物 → `POST .../local-edits` 存为新 revision（accepted），后续续跑/重做以它为基线。
 
-### 3.8 部署（客户端经 Manager 加密接口取凭据 → 执行）
+### 3.8 部署（✅ 必须客户端执行 + 必须用户确认）
 
-🔴 **目标**：
-- 客户端要部署到 VM/连数据库时，**不直接拿明文凭据**；通过 Manager 的**加密密钥接口**换取**短期凭据租约**（secret 从 KV 解出，经 V2 加密通道回客户端，或由 Manager 代理执行）。
-- 两种执行位：(a) **客户端执行**（Manager 发短期租约，客户端 git→VM、跑部署）；(b) **Manager/runtime 执行**（客户端只下指令，凭据不出 Manager）。建议高危操作走 (b) + 审批。
-🟡 **现状**：有云部署控制面占位（`/deployments`，返回 `executor:pending_worker`），真实执行待 Deploy Worker；凭据租约模型（approval→lease）已有骨架。
+✅ **决策（2026-06-02）**：**部署绝对走客户端,且必须用户显式确认才执行**。Manager 不自动部署、runtime 不自动部署。
+- 流程：客户端发起部署 → **弹用户确认**(目标/环境/影响) → 用户确认 → 客户端向 Manager 的**加密密钥接口**换取**短期凭据租约**(VM SSH key / git PAT 等从 KV 解出,经 V2 加密通道回客户端,带 TTL) → **客户端本地执行**(git pull 用户仓库 → push/部署到 VM,或连库迁移)。
+- Manager 角色:**只发短期凭据 + 记审计**(谁、哪条 binding、何时、TTL),不代执行。
+- 凭据租约:短 TTL、可吊销、用完即弃;高危目标(如生产)可叠加**审批门**(waiting_approval)后再发租约。
+🟡 **现状**:有云部署控制面占位(`/deployments`,返回 `executor:pending_worker`);凭据租约模型(approval→lease)有骨架。🔴 待建:客户端取凭据的加密接口 + 客户端本地执行器。
 
 ---
 
@@ -147,17 +151,19 @@
 - 客户端**禁止 inline** secret_ref / AccessKey / 连接串。
 - 凭据录入**一次性**：客户端经 V2 加密通道把凭据传给 Manager → Manager 写 KV → 库里只留 `azkv://`。
 
-### 4.1 Git 仓库绑定 ❓
+### 4.1 Git 仓库绑定 ✅（已定方向）
 
-**用途**：agent 在此仓库读写代码、git 入库、合并；客户端 clone/pull 看产物；后续 git 到 VM 部署。
+**模型**：**用户绑定自己的仓库**（gitea / github，用户提供 URL）。agent 在此仓库读写代码、git 入库、合并；客户端 clone/pull 看产物；后续从此仓库 git 到 VM 部署。
 
-| 决策点 | 我的建议 |
+| 项 | 方案（已定 / 建议） |
 |---|---|
-| **是否必须绑 git 才能用 sub** | **否，不强制**。默认 **Heicode 托管仓库**（每个 sub 任务自动开一个托管 repo，用户零配置即用）；绑自己的 git 是**高级选项**（能用自己的工作流/工单/CI）。这样降低门槛又保留高级能力。 |
-| **绑定鉴权方式（SSH 还是？）** | **首选 HTTPS + 细粒度 token**：GitHub → **GitHub App**（最小权限、可按仓库授权、可吊销、有 rate limit 优势）或 fine-grained PAT；Gitea/GitLab → 范围化 PAT。**SSH deploy key** 作为备选（适合纯 push/pull、不需要 API 的场景）。凭据进 KV。**不建议**用账号密码。 |
-| **绑定粒度** | 单仓库级（一个 binding = 一个 repo + 一个分支基线 + 允许路径）。permission_scope：`repo:read` / `repo:write`。 |
-| **能否用 git 的工单/里程碑** | **可选增强**，不影响主流程：若绑的是 GitHub/Gitea 且授了 issues 权限，可把 sub 任务的**子任务映射为 issues**、**阶段映射为 milestone**、**handoff/审批映射为 issue 评论**。默认关闭，用户显式开启。这能让用户在自己的 git 看板里跟踪 agent 进度。 |
-| **分支模型** | 见 §7。 |
+| **仓库归属** | ✅ **用户自己的仓库**。用户提供 `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 的场景）。 |
+| **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` 并提示用户**重新绑定**，不静默失败。 |
+| **工单 / 里程碑** | **可选增强**（默认关，用户显式开）：把 sub 子任务映射为 **issues**、阶段映射为 **milestone**、handoff/审批映射为 **issue 评论**，让用户在自己 git 看板跟踪 agent 进度。需要 PAT 额外授 issues 权限。 |
+| **分支模型 / 合并** | 见 §7。 |
 
 ### 4.2 VM 连接绑定 🔴
 `type=vm`，metadata：host/port/user/连接方式（ssh key / 密码）；secret 进 KV。用于部署/运维。高危,建议绑定时声明用途 + 部署需审批。
@@ -210,28 +216,86 @@
 ```
 
 **决策点**：
-| 点 | 建议 |
+| 点 | 方案（已定 / 建议） |
 |---|---|
-| 仓库归属 | 托管仓库（Heicode 名下，任务级）或用户绑定仓库（用户名下，复用其工作流）。两者都支持，绑定优先。 |
-| 谁执行 git | **agent_management 执行**所有 git 操作（commit/merge）；Manager 只**记录引用**（repo/branch/commit_sha）并在 artifact metadata 里带 `git_ref`。Manager 不做 git。 |
-| 合并冲突 | 目录隔离（backend/、frontend/ 并列）天然无冲突；同文件冲突由「集成 agent」或规则化合并解决，冲突无法自动解则上报 `needs_codegen` 让用户/再跑一轮。 |
-| 客户端看产物 | 绑定仓库 → 直接 git；托管仓库 → 经 Manager `/archive` 或给只读 clone 凭据（短期租约）。 |
+| 仓库归属 | ✅ **用户绑定的仓库**（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**。 |
+| 提交身份 | 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 时）。 |
 
 ---
 
-## 8. 开放决策点汇总（需你拍板）
+## 8. 决策点（部分已定，2026-06-02）
 
-1. **git 前置**：默认托管仓库 + 可选绑自己的 git（我建议如此）—— 确认？
-2. **git 鉴权**：GitHub App / 细粒度 PAT 为主，SSH deploy key 备选 —— 确认？
-3. **工单/里程碑**：作为可选增强（子任务→issue、阶段→milestone）默认关 —— 要不要纳入 v1？
-4. **流式**：v1 先轮询 work 视图，SSE 作为 v1.1 —— 接受？
-5. **git 执行方**：agent_management 执行 git、Manager 只记引用 —— 确认？
-6. **部署执行位**：高危走「Manager/runtime 执行 + 审批」，低危可发短期租约让客户端执行 —— 确认？
-7. **托管仓库技术选型**：用哪套 git 服务承载托管仓库（自建 Gitea / GitHub org / Azure Repos）？
+| # | 决策 | 结论 |
+|---|---|---|
+| 1 | git 归属 | ✅ **用户绑自己的仓库**(github/gitea,给 URL),无托管仓库 |
+| 2 | git 鉴权 | ✅ **HTTPS + 细粒度 PAT 为主**(github/gitea 通用、用户粘贴 token)、SSH deploy key 备选 |
+| 3 | 部署 | ✅ **必须客户端执行 + 必须用户确认**;Manager 只发短期凭据 + 记审计 |
+| 4 | git 执行方 | ✅ **agent_management 执行 git**(用注入的短期 PAT),Manager 只记引用 |
+| 5 | 工单/里程碑 | 可选增强,默认关 —— ❓ 是否纳入 v1? |
+| 6 | 流式 | v1 先轮询 work、SSE 放 v1.1 —— ❓ 接受? |
+| 7 | 写入方式 | ❓ agent 是 push 到 `delivery/<task_id>` 分支 / 开 PR,还是直接进 main? 建议 PR/分支模式 |
+| 8 | 未绑仓库 | ❓ 是否「未绑 git 则禁用 sub」,还是允许「仅产物」轻量路径? |
 
 ---
 
-## 9. 与现状的差距清单（三端 TODO）
+## 9. 更多需要考虑的细节（我补充的，超出已提问题）
+
+> 这些是我认为**必须在 v1 前定清**的边界/细节,大多附我的建议,标 ❓ 的需你拍板。
+
+### 9.1 仓库与代码库状态
+- **空仓库 vs 已有代码**：agent 是在**已有代码库上增量改**,还是**绿地新建**? 建议 binding 时声明 `mode: greenfield | existing`;existing 时 agent 先读现有结构再改,且**只动 allowed_paths 内**的文件。
+- **多仓库任务**：一个任务是否可能跨多个仓库(前端仓 + 后端仓)? 建议 v1 **单仓库**,多仓库 v2。
+- **monorepo / 子目录**：用 `allowed_paths` 限定 agent 工作目录,避免动到无关代码。
+- **大文件 / LFS**：是否支持 git-lfs? v1 可不支持,但要**拒绝把大二进制/数据集塞进 git**(走 blob 绑定)。
+- **.gitignore + 防止误提交密钥**：agent **绝不能把任何凭据/secret_ref/.env 提交进仓库**;runtime 侧需有 secret 扫描,提交前拦截。
+
+### 9.2 凭据与安全
+- **PAT 最小权限 + 短时效**：注入 runtime 的 PAT 应尽量是**短期/单仓库范围**;若用户给的是长期 PAT,Manager 至少做范围校验并提醒。
+- **凭据只在内存**：runtime 用完 PAT 不落盘、不进日志;Manager 注入走加密。
+- **scope 隔离**：一条 binding 的凭据**只能被该用户(binding_scope)的任务**使用,跨用户禁用。
+- **审计**：每次「解 KV、注入 runtime、发客户端租约」都留审计(user / binding / 用途 / 时间 / TTL),明文不入审计。
+- **吊销**：用户删 binding 或吊销租约后,进行中的任务该如何? 建议:已注入的短期凭据自然过期,新操作立即失效。
+
+### 9.3 任务执行与失败
+- **预算/配额**：每任务 token/时长/成本上限;**跑超预算**时如何? 建议:到上限**暂停 + 标 `needs_codegen`/`budget_exceeded`**,让用户决定续不续,不静默烧钱。
+- **中途停止(stop)**：停止时已 commit 的代码**保留在分支**(不回滚),任务标 stopped;用户可在该分支续跑或丢弃。
+- **agent 崩溃 / 部分失败**：多 agent 里某个失败 → 整体 `completed_without_deliverable`/部分交付? 建议:Manager 裁决时若有 agent 失败但有有效产物,仍可 `completed` 但带 warning;全失败则 failed。
+- **幂等**：同一需求重复提交(网络重试)用 `X-Idempotency-Key` 去重,避免建重复任务/重复 git 分支。
+- **超时**：runtime 长时间无回调 → Manager 标 `stale`/超时,客户端可见。
+
+### 9.4 产物与验收
+- **验收标准如何验证**：需求包里的 `acceptance_criteria` 谁来验? 建议:runtime 跑测试(若有)并把**测试结果**作为 artifact 回传;Manager 把「测试通过」纳入 `completed` 裁决参考。
+- **产物版本/标签**：每次交付打 tag(`delivery-<task>-rev<N>`)或记 commit_sha,便于回溯 + 部署指定版本。
+- **修改 vs 重做的边界**：`/messages`(在现有产物上改)与 `/redo`(重新生成)语义要清晰;redo 是否丢弃旧分支? 建议:redo 开新分支,旧的保留可对比。
+
+### 9.5 协作与团队
+- **谁能看/操作一个任务**：binding_scope = 租户/工作区;同 scope 内成员可见,跨 scope 禁。
+- **并发任务同仓库**：两个任务同时改一个 repo → 用不同 `delivery/<task_id>` 分支隔离,合并到 main 时各自 PR,冲突由用户处理。
+
+### 9.6 git provider 细节
+- **rate limit**：github/gitea API 有限流,频繁 commit/查询要退避,避免触发封禁。
+- **私有 / 公开仓库**：都支持;私有仓库凭 PAT 访问。
+- **网络可达**：runtime 要能访问用户的 git(公网 github 没问题;自建 gitea 若在内网,需用户提供可达地址或白名单)。
+- **webhook 回写(可选)**：若用户在自己仓库手动改了代码,是否要 webhook 通知 Manager 同步基线? v2 考虑。
+
+### 9.7 部署细节(客户端执行 + 用户确认)
+- **确认内容**：弹窗要清楚展示**部署目标、环境(prod/staging)、用哪条 binding、影响范围**,用户确认后才发凭据。
+- **目标多样性**：v1 先支持 **VM(SSH)**;k8s/serverless v2。
+- **回滚**：部署失败/效果不好 → 客户端能回滚到上一个交付 tag。
+- **租约最小化**：发给客户端的凭据是**单目标、短 TTL**;用完吊销。
+
+### 9.8 体验(参考 Claude Code work)
+- **work 视图最小信息**:每个 agent 的「当前在做什么(一句话)+ 正在改哪个文件 + 跑了什么命令/工具 + 产出」,实时滚动。
+- **可中断**:用户能在 work 视图里随时停/插话(`/messages`)。
+- **可读日志分层**:普通用户看 `user_logs`(友好),调试面板看 `debug_logs`(原始)。
+
+---
+
+## 10. 与现状的差距清单（三端 TODO）
 
 **Phase 0（运维，硬卡点）**
 - 🔴 打通 Key Vault 托管身份（VM identity 授 KV Secrets Officer）——不通则资源绑定/凭据全链路不可用。