dsh-tower 2.0.3 → 2.1.0-beta.1

package/docs/zh/guide/scenarios-and-philosophy.md

@@ -2,9 +2,9 @@
 
 [English](../guide/scenarios-and-philosophy.md)
 
-Tower 不是所有多代理模式的替代品。它是**面向 Git 仓库变更的交付协议**：少量边界清晰的 mission、隔离的写入者、独立审查、证据与合并门禁。本页解释这些设计取舍、适用场景，以及什么时候 Agent Teams、Ralph 循环、Workflow 编排或普通并行子代理更合适。
+Tower 不是所有多代理模式的替代品。它是**面向 Git 仓库变更的交付协议**：少量边界清晰的 mission、隔离的写入者、可选独立审查、证据与合并门禁。本页解释这些设计取舍、适用场景，以及什么时候 Agent Teams、Ralph 循环、Workflow 编排或普通并行子代理更合适。
 
-如果只记一句话：**输出是需要审查并合入仓库的变更时用 Tower；输出是探索、重复尝试或程序化扇出时用其他模式。**
+如果只记一句话：**输出是需要经过受控合并落地的仓库变更时用 Tower；输出是探索、重复尝试或程序化扇出时用其他模式。**如果还需要独立审查，开启 `review.requireReview`。
 
 ## 1. 设计哲学
 
@@ -12,7 +12,7 @@ Tower 做了一组刻意的取舍，这解释了它的优势和成本。
 
 ### 1.1 仓库是责任单位
 
-mission 不是聊天线程或任务卡，而是绑定到分支与 worktree 的契约：有声明式写范围、依赖、完成证据和审查记录。"改了什么、谁改的、凭什么说改对了"有持久答案，位于 `<git-common-dir>/dsh-tower/state.json` 与 Git 历史，而不只在对话里。
+mission 不是聊天线程或任务卡，而是绑定到分支与 worktree 的契约：有声明式写范围、依赖、完成证据和可选审查记录。"改了什么、谁改的、凭什么说改对了"有持久答案，位于 `<git-common-dir>/dsh-tower/state.json` 与 Git 历史，而不只在对话里。
 
 ### 1.2 一个 mission 一个写入者
 
@@ -24,21 +24,25 @@ mission 不是聊天线程或任务卡，而是绑定到分支与 worktree 的
 
 ### 1.4 集成是独立的特权步骤
 
-worker 永远不合并。reviewer 审查特定分支 tip；控制塔运行 preflight；只有之后 `tower_merge` 才执行 `--no-ff` 合并。门禁重新检查 scope、base 新鲜度、任务、审查绑定、worktree 归属、worker 状态、测试与证据。职责分离是重点：写代码的 agent 不批准，批准的 agent 也不合并。
+worker 永远不合并。控制塔运行 preflight；只有之后 `tower_merge` 才执行 `--no-ff` 合并。门禁重新检查 scope、base 新鲜度、任务、worktree 归属、worker 状态、测试与证据。开启审查时，reviewer 还会审查特定分支 tip，门禁检查审查绑定；职责分离（写代码者不批准、批准者不合并）在审查开启时生效。
 
-独立审查默认可选：设 `review.requireReview:true` 才会强制（此时已完成 mission 必须带有绑定 tip 的 clean/merge 审查）。对敏感仓库建议开启；全局开启时仍可用 `reviewPolicy:"none"` + 理由做单个 mission 豁免。无论开关如何，都可以提交并记录 review。
+独立审查默认可选：设 `review.requireReview:true` 才会强制（此时已完成 mission 必须带有绑定 tip 的 clean/merge 审查）。对敏感仓库建议开启；全局开启时仍可用 `reviewPolicy:"none"` + 理由 + `gates.allowReviewExemption:true` 做单个 mission 豁免。无论开关如何，都可以提交并记录 review。
 
 ### 1.5 证据优先于断言
 
-"完成了"是声明；commit、diff、通过的测试回执、独立审查才是证据。Tower 全部记录：`tower_doctor` 检查环境，`tower_test` 记录发现，`tower_complete` 记录 checks，`tower_review` 把结论绑定到提交，`tower_batch` 只有在有限 mission 集合的必需证据齐全时才允许收口。
+"完成了"是声明；commit、diff、通过的测试回执、审查结论都是证据。Tower 全部记录：`tower_doctor` 检查环境，`tower_test` 记录发现，`tower_complete` 记录 checks，`tower_review` 把结论绑定到提交（开启审查时），`tower_batch` 只有在有限 mission 集合的必需证据齐全时才允许收口。
 
 ### 1.6 失败关闭，显式恢复
 
-Tower 宁可显示 blocker，也不静默修复。stale worker 被标记而不是假设已死；脏 base 阻止合并；审查后 tip 变化阻止合并；merge 期间崩溃会留下持久 intent，由下一次 `tower_merge` 对账。代价是偶尔需要人工清理，收益是状态不会谎报已集成的内容。
+Tower 宁可显示 blocker，也不静默修复。stale worker 被标记而不是假设已死；脏 base 阻止合并；开启审查时，审查后 tip 变化阻止合并；merge 期间崩溃会留下持久 intent，由下一次 `tower_merge` 对账。代价是偶尔需要人工清理，收益是状态不会谎报已集成的内容。
 
-### 1.7 人类拥有模式
+### 1.7 模式切换显式且可归因
 
-Tower 模式改变会话姿态：收窄工具面并注入 mission 协议。随包 patch 允许模型给出理由后切换，但该模式存在的前提是人类需要交付纪律。进入会暂停活跃 goal 并清除 plan mode；退出不会静默恢复。Tower 激活期间刻意拒绝 `goal`、`todo`、Team 任务板、Workflow、Ralph 与普通 subagent 工具，避免两套编排协议争夺同一会话。
+Tower 模式改变会话姿态：收窄工具面并注入 mission 协议。人类始终可以用 `/tower` 切换；默认情况下
+模型也可以带具体理由用 `tower_control` 进出，每次变更记录操作者与理由。设计重点不是某一方拥有
+开关，而是切换必须显式、可见；若部署需要仅人类控制，设 `mode.allowAgentControl:false`。进入会
+暂停活跃 goal 并清除 plan mode；退出不会静默恢复。Tower 激活期间刻意拒绝 `goal`、`todo`、
+Team 任务板、Workflow、Ralph 与普通 subagent 工具，避免两套编排协议争夺同一会话。
 
 ### 1.8 本地优先，无隐藏服务
 
@@ -50,19 +54,19 @@ Tower 是 Host 插件，只使用本地 Git、本地文件和 DSH subagent 服
 
 | 场景 | 具体例子 | 为什么用 Tower |
 |---|---|---|
-| 可拆成独立切片的特性 | 加 OAuth：`token 模型` → `callback 路由` → `UI 按钮` + 迁移，四个 scope 基本独立的 mission | 写入隔离、scope 预留、最终统一审查/合并 |
+| 可拆成独立切片的特性 | 加 OAuth：`token 模型` → `callback 路由` → `UI 按钮` + 迁移，四个 scope 基本独立的 mission | 写入隔离、scope 预留、最终统一合并（可选审查） |
 | 有顺序的迁移/重构 | monorepo 重命名 `oldApi`：codemod → import 清理 → 快照 → 文档，每步依赖前一步合并 | `deps`、分支新鲜度、合并串行 |
 | 先调查再修改 | survey mission 映射已弃用 crypto API 的所有调用者；两个 build mission 迁移与补测试 | survey 不能改文件；findings 喂给 build |
-| 敏感或发布绑定变更 | 支付服务改动或公共库发布，需要被审查 commit 与测试证据 | 审查绑定、checks/testRuns、人类可审计 |
+| 敏感或发布绑定变更 | 支付服务改动或公共库发布，需要测试证据与可审计合并（需要独立结论时开启审查） | checks/testRuns、可选审查绑定、人类可审计 |
 | 长期工作 | 多日依赖升级，期间重启、换会话、上下文重置 | mission/roster/review/worktree 持久 |
-| 硬集成边界 | monorepo 四个服务各有 owner，最后统一发布审查 | 多 mission 并行，单一合并门禁 |
+| 硬集成边界 | monorepo 四个服务各有 owner，最后统一发布合并 | 多 mission 并行，单一合并门禁 |
 | 可检查的完成定义 | 任务清单 + 必需测试 + 可选独立审查结论 | 另一个 agent 能检查证据 |
 
 ### 2.1 能自然拆成独立切片的特性
 
-例：OAuth 登录拆成"token 模型"、"callback 路由"、"UI 按钮"、"迁移 + 测试"。切片大多改不同文件，可以并行，最后需要集成审查。Tower 的 scope 预留与重叠自动依赖可以避免碰撞。
+例：OAuth 登录拆成"token 模型"、"callback 路由"、"UI 按钮"、"迁移 + 测试"。切片大多改不同文件，可以并行，最后统一合并（需要时再加审查）。Tower 的 scope 预留与重叠自动依赖可以避免碰撞。
 
-**为什么用 Tower：** 并行写入被隔离；每个切片有 owner 与审查；合并在最后统一门禁，而不是逐段即兴处理。
+**为什么用 Tower：** 并行写入被隔离；每个切片有 owner，需要时再审查；合并在最后统一门禁，而不是逐段即兴处理。
 
 ### 2.2 有顺序约束的迁移或重构
 
@@ -78,9 +82,9 @@ Tower 是 Host 插件，只使用本地 Git、本地文件和 DSH subagent 服
 
 ### 2.4 敏感仓库或与发布绑定的变更
 
-例：支付服务、有外部用户的库、release 分支。你需要独立 reviewer、特定被审查 commit、测试证据和人类可审计记录。
+例：支付服务、有外部用户的库、release 分支。你需要测试证据和人类可审计记录；开启审查时，还会得到独立 reviewer、特定被审查 commit 与绑定 tip 的结论。
 
-**为什么用 Tower：** 审查绑定、证据门禁、`MISSIONS.md`、活动日志和可选测试发现提供了可辩护的记录；reviewer 是独立的只读 agent，不是作者。
+**为什么用 Tower：** 证据门禁、`MISSIONS.md`、活动日志和可选测试发现提供了可辩护的记录；开启审查时，reviewer 是独立的只读 agent，不是作者，结论绑定 tip。
 
 ### 2.5 跨上下文压缩或重启的长期工作
 
@@ -90,23 +94,23 @@ Tower 是 Host 插件，只使用本地 Git、本地文件和 DSH subagent 服
 
 ### 2.6 有硬集成边界的并行工作
 
-例：monorepo 中四个独立服务，各有 owner，最后统一发布审查。Tower 给每个 mission 分支/worktree 并预留写范围；控制塔可用 `tower_batch` 审计有限的发布证据。
+例：monorepo 中四个独立服务，各有 owner，最后统一发布合并。Tower 给每个 mission 分支/worktree 并预留写范围；控制塔可用 `tower_batch` 审计有限的发布证据。
 
 **为什么用 Tower：** 并行是真的，但集成仍然是一个统一的、带门禁的步骤。
 
 ### 2.7 需要另一个 agent 能检查的"完成定义"
 
-例：任务清单 + 测试 + 必需审查结论。Tower 的 mission 契约与 completion/review 工具让"完成"可观察。如果你的完成定义只是"用户在聊天里满意"，Tower 是过度设计。
+例：任务清单 + 测试 + 可选审查结论。Tower 的 mission 契约与 completion/review 工具让"完成"可观察。如果你的完成定义只是"用户在聊天里满意"，Tower 是过度设计。
 
 ## 3. Tower 不适合的场景
 
 | 场景 | 更合适的模式 | 原因 |
 |---|---|---|
-| 单文件修改、typo、小 hotfix | 普通会话中的单个 agent | worktree、审查与合并开销大于收益。 |
+| 单文件修改、typo、小 hotfix | 普通会话中的单个 agent | worktree 与合并开销（开启审查时再加审查）大于收益。 |
 | 需求仍在发现阶段 | 普通 agent、Plan mode 或 Agent Teams | Tower 要求先给 scope/tasks；错误契约会导致重新规划。 |
 | 开放式研究或头脑风暴 | Agent Teams、Workflow 或普通子代理 | 没有要隔离和合并的仓库变更。 |
-| 很多极小的独立任务 | Workflow 或普通并行子代理 | 每个 mission 的审查/合并成本太高。 |
-| 交互式 UI 配对或探索式调试 | 普通 agent（或单个 worker） | 需要紧密反馈与频繁人工引导，审查门禁增加延迟。 |
+| 很多极小的独立任务 | Workflow 或普通并行子代理 | 每个 mission 的合并成本（开启审查时再加审查）太高。 |
+| 交互式 UI 配对或探索式调试 | 普通 agent（或单个 worker） | 需要紧密反馈与频繁人工引导，开启审查时门禁增加延迟。 |
 | 一次性生成、没有集成 | 普通子代理/Workflow | 不需要分支、审查、合并决策。 |
 | 跨仓库产品工作 | Agent Teams + 普通工具 | Tower 只作用于单个 Git 仓库。 |
 
@@ -118,11 +122,11 @@ Tower 是 Host 插件，只使用本地 Git、本地文件和 DSH subagent 服
 
 | 维度 | Tower | Agent Teams | Ralph 循环 | Workflow 编排 | 普通并行子代理 |
 |---|---|---|---|---|---|
-| 主要目标 | 交付经审查的仓库变更 | 围绕共享目标协作 | 对同一目标用新鲜 agent 反复尝试 | 程序化扇出/流水线 | 并行探索或实现 |
-| 工作单位 | mission（分支 + worktree + scope + 任务 + 审查） | 共享任务板上的任务/teammate | 轮次/尝试 | 脚本步骤/阶段 | 每个子代理一个 prompt/任务 |
+| 主要目标 | 交付经门禁集成的仓库变更（可选独立审查） | 围绕共享目标协作 | 对同一目标用新鲜 agent 反复尝试 | 程序化扇出/流水线 | 并行探索或实现 |
+| 工作单位 | mission（分支 + worktree + scope + 任务 + 可选审查） | 共享任务板上的任务/teammate | 轮次/尝试 | 脚本步骤/阶段 | 每个子代理一个 prompt/任务 |
 | 隔离 | 每 mission 独立 worktree/分支；单写入者 | 共享工作区；靠任务归属协调 | 每轮新 child；无内置分支/合并契约 | 每步 child；无 Git 隔离 | 子会话；可能共享工作区 |
 | 持久状态 | Git 元数据 + JSON state + 活动日志 + 看板 | Team 任务板 + 会话 | 很少；每轮从零开始 | 运行记录/结果；不是合并账本 | 会话/子代理记录 |
-| 集成权限 | 仅控制塔，且需审查 + 门禁 | 人类/teammate 手动合并或编辑 | 通常由父 agent/worker 应用结果 | 脚本应用结果 | 父 agent 应用结果 |
+| 集成权限 | 仅控制塔，经 preflight/merge 门禁（可选再加审查） | 人类/teammate 手动合并或编辑 | 通常由父 agent/worker 应用结果 | 脚本应用结果 | 父 agent 应用结果 |
 | 审查/门禁 | 可选独立审查（`review.requireReview` 开启）+ preflight/merge 门禁 | 审查是协作约定，不是硬门禁 | 无内置审查门禁 | 无内置审查门禁 | 无内置审查门禁 |
 | 并行度 | 多 mission、互斥 scope、合并串行 | 多 teammate、共享任务板 | 顺序轮次（或外部扇出） | 高扇出，由脚本控制 | 高扇出 |
 | 人的角色 | 拥有模式；可检查证据与发布 | 协作者/协调者 | 重复目标的作者 | 编排脚本作者 | 委派者 |
@@ -133,33 +137,41 @@ Tower 是 Host 插件，只使用本地 Git、本地文件和 DSH subagent 服
 
 普通 `subagent`/`subagent_fork` 便宜灵活，适合"并行读五个文件"或"试三种方案"。它们不提供写范围、专用 worktree、持久 mission、独立审查或合并门禁。Tower 用这些契约包装同一个子代理原语，因此每个 child 更贵。
 
-只读、短生命周期、或你准备自己集成结果时，用普通子代理；结果必须落到分支并经过审查时，用 Tower。
+只读、短生命周期、或你准备自己集成结果时，用普通子代理；结果必须落到分支并经受控合并时，用 Tower；需要独立审查时再开启 `review.requireReview`。
 
 ### 4.2 Tower vs Agent Teams
 
 Agent Teams 是**协作**模式：共享任务板、持久 teammate、消息、wait/interrupt，以及人类/Lead 协调。它适合横切、探索性或需要多视角的工作，且集成决定通常由人类做。
 
-Tower 是**交付**模式：mission 契约、Git 隔离、审查与硬合并门禁。它的点对点协作更少、结构更多。Agent Teams 可以决定"做什么、是否继续"；Tower 可以把决定执行成 mission。二者应顺序或互补，而非并发：Tower 模式会拒绝 Team 任务板工具，避免两套协议争抢同一会话。
+Tower 是**交付**模式：mission 契约、Git 隔离、可选审查门禁与硬合并门禁。它的点对点协作更少、结构更多。Agent Teams 可以决定"做什么、是否继续"；Tower 可以把决定执行成 mission。二者应顺序或互补，而非并发：Tower 模式会拒绝 Team 任务板工具，避免两套协议争抢同一会话。
 
 ### 4.3 Tower vs Ralph 循环
 
 Ralph 用新鲜 agent 一轮轮执行**同一目标**，以工作区为长期记忆。它适合迭代搜索、修复 flaky、以及"换上下文再试一次"。它没有 mission 契约、独立审查或合并门禁。
 
-Tower 是增量的：每个 mission 有边界清晰的交付物，并经审查落地。如果问题是"我不知道能不能做成，反复新鲜尝试也许能找到路"，Ralph 往往更合适；如果问题是"我知道切片，需要安全地构建并集成"，Tower 更合适。可以在 Tower 模式之外先用 Ralph 找到方案，再把结果编码成 Tower mission。
+Tower 是增量的：每个 mission 有边界清晰的交付物，并经合并门禁落地（开启审查时再经审查）。如果问题是"我不知道能不能做成，反复新鲜尝试也许能找到路"，Ralph 往往更合适；如果问题是"我知道切片，需要安全地构建并集成"，Tower 更合适。可以在 Tower 模式之外先用 Ralph 找到方案，再把结果编码成 Tower mission。
 
 ### 4.4 Tower vs Workflow 编排
 
 Workflow 是**程序化编排**：JS 脚本把工作扇出到许多 subagent，带阶段、pipeline 与结构化结果。它适合审计、批量迁移、多角度研究与对抗性验证。它不为每一步提供 Git worktree、审查结论或合并门禁。
 
-Tower 是**仓库交付协议**，mission 数量少，不是高扇出数据平面。用 Workflow "并行分析 200 个文件"；用 Tower "把分析证明需要的 6 个修改，经审查与门禁合入"。Tower 模式会拒绝 Workflow，避免脚本在 Tower 契约下制造竞争写入。
+Tower 是**仓库交付协议**，mission 数量少，不是高扇出数据平面。用 Workflow "并行分析 200 个文件"；用 Tower "把分析证明需要的 6 个修改，经可选审查与合并门禁落地"。Tower 模式会拒绝 Workflow，避免脚本在 Tower 契约下制造竞争写入。
 
 ### 4.5 Tower vs Plan mode
 
 Plan mode 决定做什么；Tower 把已决定的计划执行到仓库。进入 Tower 会清除活跃 plan（`mode.planModePolicy:"refuse"` 时拒绝进入），且 Tower 会话不能使用 goal/todo/team/workflow 工具。先规划，再执行；不要指望 Tower 替你发现计划。
 
-### 4.6 各工作流的具体例子
+### 4.6 审查默认可选
 
-**Tower** —— 输出是必须经过隔离与审查才能落地的仓库变更：
+`review.requireReview:false` 是默认值，因此低风险仓库、临时工作或人类逐轮监督的会话可以在没有
+reviewer 时合并已完成 mission。设为 `true` 才启用强制独立审查门禁；此时检查 `no-review`、
+`not-clean`、`review-hold`、`review-not-approved`、`tip-moved`、`review-mission-mismatch`。
+`tower_review` 始终可用并记录结论。只豁免单个 mission 时，在全局开启的前提下用
+`reviewPolicy:"none"` + 理由 + `gates.allowReviewExemption:true`。
+
+### 4.7 各工作流的具体例子
+
+**Tower** —— 输出是必须经过隔离与合并门禁落地的仓库变更（可选独立审查）：
 
 - **OAuth 登录**：四个 mission（`token 模型`、`callback 路由`、`接受/拒绝 API`、`UI`）；API 依赖 token 与邮件。
 - **Node 18 → 22 升级**：先 survey 破坏性 API，再拆 codemod、测试更新、CI 配置、release notes 为独立 mission。
@@ -199,17 +211,9 @@ Plan mode 决定做什么；Tower 把已决定的计划执行到仓库。进入
 
 1. Workflow 审计 200 个文件 → 结构化 findings。
 2. Agent Teams 评审 findings，决定前六个改动。
-3. Tower mission 实现这六个改动，经审查与合并落地。
+3. Tower mission 实现这六个改动，经可选审查与合并门禁落地。
 4. 合并后仍有一个顽固 flaky 测试、且不需要新 mission 契约时，再用 Ralph。
 
-### 4.7 审查默认可选
-
-`review.requireReview:false` 是默认值，因此低风险仓库、临时工作或人类逐轮监督的会话可以在没有
-reviewer 时合并已完成 mission。设为 `true` 才启用强制独立审查门禁；此时检查 `no-review`、
-`not-clean`、`review-hold`、`review-not-approved`、`tip-moved`、`review-mission-mismatch`。
-`tower_review` 始终可用并记录结论。只豁免单个 mission 时，在全局开启的前提下用
-`reviewPolicy:"none"` + 理由。
-
 ## 5. 具体场景示例
 
 ### 场景 A：四切片特性
@@ -219,24 +223,24 @@ reviewer 时合并已完成 mission。设为 `true` 才启用强制独立审查
 1. 规划四个 build mission，scope 分别 `src/tokens/**`、`src/email/**`、`src/api/invites/**`、`src/ui/invites/**`；让 API 依赖 token 与 email。
 2. 对独立 mission 启动 worker；API 等依赖完成。
 3. 每个 worker 在自己分支提交，带 checks 完成。
-4. 启动 reviewer；要求 clean + merge。
+4. 若开启 `review.requireReview:true`，启动 reviewer 并要求 clean + merge；否则审查可选。
 5. 逐 mission `tower_preflight` + `tower_merge`，处理 scope/base/review blocker。
 6. `tower_teardown`；`MISSIONS.md` 是人类可读记录。
 
-**为什么不用 Team/Workflow？** 这是已知的仓库变更集合，需要按顺序落地并独立审查。Team 任务板不隔离写入；Workflow 会分析但不会门禁合并。
+**为什么不用 Team/Workflow？** 这是已知的仓库变更集合，需要按顺序经受控合并落地（可选独立审查）。Team 任务板不隔离写入；Workflow 会分析但不会门禁合并。
 
 ### 场景 B：带 survey 的迁移
 
 1. Survey mission："映射 `oldApi` 的所有调用者"，scope 为空，只读。
 2. Build mission：codemod、测试更新、文档；依赖 survey 结果。
-3. Reviewer 对照 survey 检查 diff；被审查 tip 的测试必须通过。
+3. 开启审查时，Reviewer 对照 survey 检查 diff；测试门禁仍校验当前分支 tip。默认审查可选时，可跳过 reviewer，仍受门禁/测试约束。
 4. 按依赖顺序合并。
 
-**为什么不用普通子代理？** survey 不能误改；codemod 不能越界；审查必须绑定精确提交。
+**为什么不用普通子代理？** survey 不能误改；codemod 不能越界；开启审查时，审查必须绑定精确提交。
 
 ### 场景 C：事故 hotfix
 
-生产一行修复。用普通 agent，按你正常的提交/推送流程处理。Tower 会额外增加 worktree、reviewer、门禁与合并步骤；对一行紧急修复主要是延迟。如果"hotfix"实际是多个协调变更，Tower 才合理。
+生产一行修复。用普通 agent，按你正常的提交/推送流程处理。Tower 会额外增加 worktree、合并门禁与（开启时）reviewer；对一行紧急修复主要是延迟。如果"hotfix"实际是多个协调变更，Tower 才合理。
 
 ### 场景 D：大范围代码审计
 
@@ -244,22 +248,22 @@ reviewer 时合并已完成 mission。设为 `true` 才启用强制独立审查
 
 ### 场景 E：敏感发布
 
-有外部用户的库发布。为变更、迁移指南、release notes 规划 mission；要求测试与审查；用 `tower_batch` 只有在所有必需检查齐全时才收口发布证据；按你的发布流程在 Tower 之外合并/打 tag。
+有外部用户的库发布。为变更、迁移指南、release notes 规划 mission；如发布需要独立审查，开启 `review.requireReview:true`；要求测试，并用 `tower_batch` 只有在所有必需检查齐全时才收口发布证据；按你的发布流程在 Tower 之外合并/打 tag。
 
 ## 6. 实践中的选择路径
 
 1. **输出是 Git 变更吗？** 否 → 普通 agent、Agent Teams、Workflow 或 Ralph。
 2. **你会为它开 PR 吗？** 否 → Tower 太重，用普通 agent。
 3. **切片有稳定 scope 和已知完成定义吗？** 否 → 先规划/探索，再回到 Tower。
-4. **需要独立审查与合并门禁吗？** 是 → Tower；否，普通子代理可能足够。
+4. **需要合并门禁吗？** 有集成风险的仓库变更 → Tower；如果还需要独立审查，开启 `review.requireReview:true`。两者都不需要时，普通子代理可能足够。
 5. **需要大量并行分析或重复新鲜尝试吗？** 那个阶段用 Workflow/Ralph；把结果编码成 Tower mission。
 6. **需要横切的人类协作吗？** 用 Agent Teams 决定；用 Tower 执行决定的仓库工作。
 
 ## 7. 成本、限制与反模式
 
-- **每个 mission 有真实开销**：worktree、spawn、完成检查、审查轮次、门禁、合并。mission 应有意义（大致 PR 大小），不要一个函数一个 mission。
+- **每个 mission 有真实开销**：worktree、spawn、完成检查、可选审查轮次、门禁、合并。mission 应有意义（大致 PR 大小），不要一个函数一个 mission。
 - **合并会串行**：重叠 scope 自动加依赖；独立 mission 仍然逐个合入 base。合并密集的工作不要期待线性加速。
-- **审查不是免费**：每个 mission 需要 reviewer 与 clean 结论；豁免是显式开启且需要理由，不是默认。
+- **审查不是免费的（开启时）**：每个 mission 需要 reviewer 与 clean 结论；`review.requireReview:false`（默认）让审查可选；开启后豁免是显式且需要理由。
 - **过细的 mission** 增加协调与合并成本；**过粗的 mission** 失去并行审查收益，scope 冲突概率高。
 - **Tower 不是沙箱**：它是协调协议；Host 权限、仓库 hooks、测试命令仍以 DSH 用户的 OS 权限执行。
 - **不要同时跑两套编排协议**：Tower 模式会拒绝 Team/Workflow/Ralph/subagent 工具并清除 plan mode；请顺序分阶段。
@@ -269,9 +273,10 @@ reviewer 时合并已完成 mission。设为 `true` 才启用强制独立审查
 
 - [ ] 工作会产生值得 PR 式审查的仓库变更。
 - [ ] 我能列出 2–8 个 scope 不重叠、依赖顺序大致的 mission。
-- [ ] 每个 mission 有可测试的完成定义（任务、checks/测试、审查）。
+- [ ] 每个 mission 有可测试的完成定义（任务、checks/测试、可选审查）。
+- [ ] 如果这次变更需要独立审查，已开启 `review.requireReview`（默认关闭）。
 - [ ] 我知道哪些 mission 可并行、哪些必须等待。
-- [ ] 我接受审查/合并开销，并会检查 `MISSIONS.md`/分支。
+- [ ] 我接受合并门禁开销（以及开启审查时的审查开销），并会检查 `MISSIONS.md`/分支。
 - [ ] 当前没有在同一会话依赖 Team 任务板、Workflow 脚本、Ralph 循环或 plan mode。
 - [ ] 如果 worker 卡住（interrupt/adopt）或合并冲突，我有恢复路径。
 

package/docs/zh/operations/security.md

@@ -6,9 +6,9 @@ Tower 提供的是**协作层面的保证**，不是沙箱。需要理解哪些
 
 ## 由插件强制执行的约束
 
-- **审查绑定。** `tower_review` 会记录它检查的分支 tip；tip 变化后门禁会拒绝（`tip-moved`），除非
-  一次干净且无冲突的 rebase 给予了豁免。reviewer 在 spawn 之后修改分支会被拒绝
-  （`reviewer must not modify the mission branch`）。
+- **审查绑定（开启审查时）。** `tower_review` 会记录它检查的分支 tip；开启 `review.requireReview` 后
+  tip 变化会被门禁拒绝（`tip-moved`），除非一次干净且无冲突的 rebase 给予了豁免。reviewer 在 spawn
+  之后修改分支会被拒绝（`reviewer must not modify the mission branch`）。
 - **审查默认可选，可配置强制。** `review.requireReview:false` 是默认值；设为 `true` 才启用独立审查
   门禁。全局开启时，mission 级 `reviewPolicy:"none"` + 理由是更窄的豁免。关闭门禁时插件不强制职责
   分离；只应用于可信仓库或有人类监督的会话。
@@ -19,26 +19,62 @@ Tower 提供的是**协作层面的保证**，不是沙箱。需要理解哪些
 - **只读 reviewer preset。** `tower-reviewer` preset 从工具面移除 `write`、`edit`、`pwsh`、
   `tower_mission` 与 `tower_complete`；reviewer 只能读、看 diff、发消息、记录 finding 和提交审查。
 - **Scope 门禁。** mission 只能修改其声明 scope glob 匹配的文件；越界改动会阻止合并。
-- **Worktree 隔离。** worker 在独立 worktree 与分支上工作；主检出只会被 merge/teardown 触及。
-- **人类掌握模式。** `/tower` 归用户所有。开启 `mode.allowAgentControl` 后模型可以切换，但必须
-  给出理由；随包 patch 默认开启——设为 `false` 可让模式只由人类控制。
+- **模式控制显式且可配置。** `/tower` 始终可用。`mode.allowAgentControl:true`（默认）时，模型也可以
+  带必填理由用 `tower_control` 进出；每次变更记录操作者与理由。设为 `false` 则仅人类可控制模式。
+  重点是变更可归因，而不是固定由某一方拥有。
 - **不自动恢复 goal。** 进入模式会暂停活跃 goal；退出时不会恢复它。
 - **建议性 workspace 锁。** `mode.workspaceLock` 防止两个 Tower 会话意外驱动同一个仓库；它是同用户
   之间的协调锁，不是用户间的认证机制。
 
+## 仓库保护
+
+本节描述的是**本仓库**，不是 Tower 所操作的仓库。服务端分支保护不是插件功能——Tower 只写入本地基线分支，无法配置远端——但 `dsh-tower` 为自己的 `main` 开启了保护，因为门禁代码本身也是攻击者最想修改的代码：
+
+- `main` 的所有变更都必须经过 pull request，且**对 admin 同样生效**，因此维护者也无法直接 push。
+- 必需检查为 `test (22)`、`test (24)` 与 `mount`。mount 任务会打包压缩包并在一次性 profile 中启动，所以“测试通过”不能把一个安装后不出现的 bundle 合入。
+- 禁止 force-push 与删除分支，已发布 tag 的历史不能被改写。
+- 不要求强制审批：只有一个维护者时，自我审批只是橡皮图章。替代它的是 two-key 路径的四行 PR 正文（failure mode、change、test、blast radius），见 [CONTRIBUTING.md](../../../CONTRIBUTING.md#landing-changes)。
+
+它带来的保证：未经验证的变更无法进入 `main`，必需检查变红或缺失时连所有者也不能绕过，历史只追加。它**不**提供：第二个审阅者、对泄露的维护者 token 的防护，或对 Tower 所操作仓库的任何保护——那些仍是部署关注点。设置、理由与校验命令记录在 [SECURITY.md](../../../SECURITY.md#repository-protection-on-main)。
+
+## 模型主动进入模式的威胁模型
+
+`mode.allowAgentControl:true` 意味着仓库文件、issue 文本或抓取页面中的提示注入可以让模型“进入
+Tower 模式并修复它”。Tower **不认证**这句话背后的人类意图。它提供的是：
+
+- 进入会记录操作者、动作、理由与时间；`tower_status.mode.history` 直接展示最近的模式切换，
+  不必手工 grep 活动日志；
+- 模型不能绕过 preflight 门禁、review policy、scope、测试与 clean-base 检查；自己写 plan 也不会
+  自动获得合并权；
+- worker 的工具面受限并被要求留在 worktree，但主检出保护来自 scope/merge 检查与 preset，
+  **不是** OS 沙箱；
+- `mode.workspaceLock` 防止第二个 Tower 会话驱动同一仓库。
+
+它**不**防御：完全通过所有门禁但被恶意指令操纵的模型；仓库自己声明的 hooks/测试命令；或无视
+指令、通过 shell 访问 worktree 之外文件的 worker。更高保证的团队应设
+`mode.allowAgentControl:false`、保持 `review.requireReview:true`、在运行 Tower 前审查仓库，并用
+OS 级隔离运行 host。
+
 ## 不由插件强制执行的约束（部署关注点）
 
+- **Worktree 隔离是协议约定，不是 OS 沙箱。** worker 会被分配独立 worktree/分支并被要求留在其中，但
+  `tower-worker` preset 仍包含 `pwsh`、`write`、`edit`；这些工具可写绝对路径或在主检出执行 Git。
+  scope 门禁检查的是提交后的分支 diff，不是文件系统访问。硬隔离需要容器、独立 OS 用户或受限的 host
+  工具策略。
 - **沙箱。** Host 插件运行在文件系统沙箱之外；reviewer 的 shell 能力是在工具面层面移除的，但底层
   进程仍拥有 DSH 的 OS 权限。需要硬隔离的部署必须自行限制进程/用户。
 - **reviewer 信任。** 审查是 reviewer agent/模型给出的背书；插件能把它绑定到提交，但无法证明
   reviewer 真的推理正确。高价值分支建议使用独立模型/角色。
 - **仓库钩子。** `git merge` 会运行目标仓库的钩子（`pre-merge-commit` 等）。Tower 无法让这些钩子
   变安全；在不受信任的仓库上运行 Tower 前请先审查钩子。
+- **测试发现是仓库代码。** `tests.admission` 默认 `off`，只有显式 `tower_test` 才会执行仓库
+  `package.json` 的 `tower.testDiscovery` 命令；该命令以 DSH 的 OS 权限运行，不是沙箱。不可信仓库应
+  设 `tests.allowPackageDiscovery:false`。
 - **HMR 重载。** 开启 `dev.hotReload` 时，`/tower reload`/`tower_reload` 会让 DSH 从磁盘重新导入
   插件。只为你信任的检出配置 HMR 监视 root；重载会执行这些文件当前的代码。
 - **提示注入。** reviewer 会读取不受信任的分支内容（diff/评论）。只读 preset 限制了影响面，但模型侧
   没有绝对防护。
-- **基线分支保护。** Tower 会写入本地基线分支；服务端的 branch protection/push 规则不属于本插件。
+- **基线分支保护。** Tower 会写入本地基线分支；服务端 branch protection/push 规则不属于本插件。本仓库自身 `main` 的保护见[仓库保护](#仓库保护)；为你运行 Tower 的仓库开启同等保护仍属于部署关注点。
 
 ## 报告问题
 

package/docs/zh/reference/blockers.md

@@ -3,14 +3,14 @@
 [English](../../reference/blockers.md) | **简体中文**
 
 `tower_preflight` 返回 `{ok:false, blockers:[{code, detail}]}`。`tower_merge` 与 `tower_rebase`
-在操作失败时返回相同结构。code 稳定；detail 面向人。
+在操作失败时返回相同结构。code 稳定；detail 面向人。下表共定义 32 个稳定 blocker/failure code。
 
 ## 门禁 blocker（26 个）
 
 | Code | 含义 / 下一步 |
 |---|---|
 | `mission-missing` | 未知 mission id。用 `tower_status` 查看。 |
-| `mission-not-completed` | mission 不是 `completed`；只有 `completed`（等待审查）的 mission 才能合并。 |
+| `mission-not-completed` | mission 不是 `completed`；只有 `completed`（可进入 preflight/合并）的 mission 才能合并。 |
 | `tasks-open` | 仍有未完成任务；worker 必须先完成，或带理由 `task_drop`。 |
 | `blockers-present` | mission 仍有 blocker；解决后清除。 |
 | `no-check-evidence` | 启用了 `gates.requireChecks` 且完成报告没有 `checks`。把 completed mission 退回 `active`，带 checks 重新调用 `tower_complete`，然后重新审查。 |
@@ -20,20 +20,20 @@
 | `out-of-scope` | 改动文件超出 mission scope；有意为之就扩大 scope，否则回退。 |
 | `base-dirty` | 主检出存在未提交改动，合并会覆盖它们。 |
 | `deps-unmerged` | 依赖 mission 尚未 merged/abandoned。 |
-| `no-review` | 分支上没有审查：spawn reviewer。 |
-| `review-mission-mismatch` | 最新审查属于另一个 mission。 |
-| `not-clean` | 最新审查是 `p1-Nitems`/`p2-Nitems`；需要再来一轮。 |
-| `review-hold` | 最新审查建议 hold；必须由后续的干净审查取代。 |
-| `review-not-approved` | 最新干净审查给出的是 `fix-then-merge` 或 `hold`；只有 `merge` 才算批准。 |
-| `tip-moved` | 审查之后分支发生变化；重新审查（或使用干净 rebase 的免审豁免）。 |
+| `no-review` | `review.requireReview:true` 且分支上没有审查：spawn reviewer（或关闭审查门禁）。 |
+| `review-mission-mismatch` | `review.requireReview:true` 且最新审查属于另一个 mission。 |
+| `not-clean` | `review.requireReview:true` 且最新审查是 `p1-Nitems`/`p2-Nitems`；需要再来一轮。 |
+| `review-hold` | `review.requireReview:true` 且最新审查建议 hold；必须由后续的干净审查取代。 |
+| `review-not-approved` | `review.requireReview:true` 且最新干净审查给出的是 `fix-then-merge` 或 `hold`；只有 `merge` 才算批准。 |
+| `tip-moved` | `review.requireReview:true` 且审查之后分支发生变化；重新审查（或使用干净 rebase 的免审豁免）。 |
 | `worker-busy` | 该 mission 的 roster agent 正在运行；等待或让其退役。 |
 | `worker-status-unknown` | 父目录不可用，无法证明 live roster agent 已停止；等目录恢复后重试，或先 adopt。 |
 | `base-wrong-branch` | 主检出不在记录的基线分支上。 |
 | `branch-owned-by-closed-missions` | mission 已 merged/abandoned；用新标题重新 plan。 |
 | `worker-stale` | 该 mission 的 roster worker 超过 `spawn.staleMs` 没有目录活动；合并前 adopt（只有确实还在运行时才 interrupt）。 |
-| `tests-missing` | 启用了 `gates.requireTests` 且没有针对被审查 tip 的通过测试回执；运行 `tower_test` 或 `tower_complete`。 |
+| `tests-missing` | 启用了 `gates.requireTests` 且没有针对当前分支 tip 的通过测试回执；运行 `tower_test` 或 `tower_complete`。 |
 | `tests-failed` | 最新测试发现回执失败，或不满足 minCount/required 检查。修复测试并重跑。 |
-| `review-exemption-invalid` | mission 请求 `reviewPolicy:"none"`，但 `gates.allowReviewExemption` 关闭（或缺少理由）。 |
+| `review-exemption-invalid` | `review.requireReview:true` 且 mission 请求 `reviewPolicy:"none"`，但 `gates.allowReviewExemption` 关闭（或缺少理由）。 |
 | `merge-intent-pending` | 崩溃/失败前记录了合并意图；先运行 `tower_merge` 对账，再进行其他门禁。 |
 
 ## 合并失败（4 个）

package/docs/zh/reference/config.md

@@ -22,7 +22,7 @@ merge、worktree 与 spawn 策略。它使用与 profile 配置相同的 JSON
 
 ```json
 {
-  "review": { "maxRoundsPerReviewer": 3 },
+  "review": { "requireReview": true, "maxRoundsPerReviewer": 3 },
   "merge": { "timeoutMs": 1800000 },
   "worktrees": { "root": "D:/tower-worktrees" },
   "spawn": { "reviewerPreset": "tower-reviewer", "maxDepth": 2 }
@@ -37,14 +37,16 @@ merge、worktree 与 spawn 策略。它使用与 profile 配置相同的 JSON
 | 键 | 默认值 | 含义 |
 |---|---|---|
 | `section` | `''` | 兼容别名：替换整段 Tower 模式提示文案。空值保留内置提醒。 |
-| `allowAgentControl` | `false`（随包 patch：`true`） | 兼容别名：注册 `tower_control`。 |
+| `allowAgentControl` | `true`（`mode.allowAgentControl` 的别名） | 兼容别名：注册 `tower_control`，允许模型切换模式。 |
 | `init.autoGitInit` | `false`（随包 patch：`true`） | 当 `repoRoot` 是绝对、已存在但不是仓库的目录时，`tower_init` 可以执行 `git init` 并创建一个空的初始提交。 |
 | `init.snapshotDirty` | `false` | `tower_init` 可以把未提交的**已跟踪**改动快照为游离提交作为 mission 基线（不含未跟踪文件；该提交通过 `refs/tower/snapshot/*` 保持存活）。 |
+| `init.autoExclude` | `true` | 把仓库内产物（`MISSIONS.md`、仓库内 worktree root）追加到 `.git/info/exclude`；绝不修改 `.gitignore`。 |
 | `mode.promptSection` | `''` | 替换用的提示文案（与 `section` 同时设置时优先）。 |
 | `mode.sectionAppend` | `''` | 追加在提醒之后的额外文本（团队约定）。 |
-| `mode.allowAgentControl` | `false` | 注册 `tower_control`；模型可带理由进入/退出。 |
+| `mode.allowAgentControl` | `true` | 注册 `tower_control`；模型可带理由进入/退出。设为 `false` 则仅人类可控制模式。 |
 | `mode.autoPauseGoal` | `true` | 进入模式时暂停活跃 goal；退出时不会自动恢复。 |
 | `mode.requireResumeAuthorization` | `false` | 恢复因 `pauseCause:user` 暂停的 mission 时，必须提供 `authorization` 引用。 |
+| `mode.requireHumanAckOnFirstEntry` | `false` | 要求人类先执行 `/tower ack`，模型才能在当前会话首次进入 Tower 模式。 |
 | `mode.workspaceLock` | `false`（随包 patch：`true`） | 每个仓库只允许一个 Tower 会话（`tower.lock`）；其他会话得到 `workspace-busy`。 |
 | `mode.workspaceLockScope` | `all` | `all` 锁定所有仓库工具；`mutations` 对只读工具跳过 workspace 锁。 |
 | `mode.planModePolicy` | `clear` | 进入 Tower 模式会清除活跃的 plan mode（或 `refuse` 直到退出计划）；前置步骤也会清除稍后激活的计划。 |
@@ -57,6 +59,7 @@ merge、worktree 与 spawn 策略。它使用与 profile 配置相同的 JSON
 | `review.maxRoundsPerReviewer` | `5` | 每个 reviewer 对每条分支的审查轮数上限。 |
 | `merge.timeoutMs` | `900000`（15 分钟） | `tower_merge` 默认超时，包含钩子；单次调用的 `timeoutMs` 优先。 |
 | `merge.maxBufferBytes` | `67108864`（64 MB） | 合并输出缓冲区。 |
+| `git.timeoutMs` | `15000` | 除 merge 外 Git 命令的默认超时；merge 使用 `merge.timeoutMs`。 |
 | `worktrees.root` | `''` | 默认 worktree 父目录；空值推导为 `<主检出父目录>/.dsh-tower-worktrees/<hash>`。 |
 | `spawn.workerPreset` | `tower-worker` | `role=worker` 使用的 preset。 |
 | `spawn.reviewerPreset` | `tower-reviewer` | `role=reviewer` 使用的 preset。 |
@@ -71,20 +74,21 @@ merge、worktree 与 spawn 策略。它使用与 profile 配置相同的 JSON
 | `send.maxPerMinute` | `120` | 每个仓库的 `tower_send` 每分钟速率限制（0 关闭）；超出返回 `rate-limited`。 |
 | `send.interruptDefault` | `false`（随包 patch：`true`） | `tower_send.interrupt` 的默认值（投递前先中断运行中的回合）。 |
 | `tests.enabled` | `true` | worktree 的 `package.json` 配置了测试发现时运行它。 |
-| `tests.admission` | `complete` | `spawn` 在启动 worker 前运行发现（fail-closed，不启动子代理）；`complete` 在 `tower_complete` 时运行；`off` 只在显式 `tower_test` 时运行。 |
+| `tests.admission` | `off` | `spawn` 在启动 worker 前运行发现（fail-closed，不启动子代理）；`complete` 在 `tower_complete` 时运行；`off` 只在显式 `tower_test` 时运行（默认；不会自动执行仓库代码）。 |
 | `tests.timeoutMs` | `60000` | 每条发现命令的超时。 |
 | `tests.maxBytes` | `16777216`（16 MiB） | 每条命令捕获的 stdout 上限。 |
 | `tests.autoChecks` | `true` | 向完成报告附加自动 `tests` 检查。 |
 | `tests.allowPackageDiscovery` | `true` | 允许仓库控制的 `tower.testDiscovery` 命令（会执行 worktree 代码；见安全页）。 |
 | `gates.requireChecks` | `false` | 合并前要求至少一条 `tower_complete.checks` 证据（`no-check-evidence`）。 |
-| `gates.requireTests` | `false` | 要求针对被审查 tip 的通过测试回执（`tests-missing`）。 |
-| `gates.allowReviewExemption` | `false` | 允许用 `reviewPolicy:"none"` + 理由跳过审查 blocker；默认故意关闭。 |
+| `gates.requireTests` | `false` | 要求针对当前 mission 分支 tip 的通过测试回执（`tests-missing`）；与审查门禁独立。 |
+| `gates.allowReviewExemption` | `false` | 在 `review.requireReview:true` 时，允许用 `reviewPolicy:"none"` + 非空理由跳过审查 blocker；默认故意关闭；全局审查关闭时无影响。 |
 | `docs.board` | `true` | 变更后写入 `MISSIONS.md`。 |
 | `docs.boardLocation` | `common` | `common` = `<git-common-dir>/dsh-tower/MISSIONS.md`；`repo` = `<repoRoot>/MISSIONS.md`。 |
+| `tools.exposeOperational` | `true` | 注册 batch/resource/import/legacy/recover/test/doctor 工具；`false` 可缩小固定工具 schema 上下文。 |
 | `leases.ttlMs` | `900000` | 默认咨询式租约寿命；过期不会自动释放。 |
 | `dev.hotReload` | `true` | 注册 `tower_reload`；关闭时 `/tower reload` 也被禁用。无 HMR 服务时调用返回 `reload-unavailable`。 |
 | `dev.reloadDelayMs` | `50` | 计划中的 reload 延迟，先让工具结果送达。 |
-| `dev.reloadRequiredIds` | 四个 Tower loader id | 作为 required 传给 `reconcileProfile` 的条目 id。 |
+| `dev.reloadRequiredIds` | 五个 Tower loader id | 作为 required 传给 `reconcileProfile` 的条目 id。 |
 
 ## 示例
 

package/docs/zh/reference/errors.md

@@ -3,7 +3,7 @@
 [English](../../reference/errors.md) | **简体中文**
 
 工具失败是抛出的错误，不是 `{ok:false}` 结果（门禁结果是例外：见 [blockers.md](blockers.md)）。
-每个抛出的错误都以稳定 code 作为消息前缀：
+每个抛出的错误都以稳定 code 作为消息前缀。本版本定义 33 个工具错误码。
 
 ```
 [tower:mission-not-found] unknown mission "M9"
@@ -20,6 +20,8 @@
 | `mission-not-found` | 不存在该 id 的 mission。 | 过期或拼错的 `M9` |
 | `finding-not-found` | 不存在该 id 的 finding。 | `tower_findings({id:"F99"})` |
 | `invalid-transition` | 请求的状态转换不被允许。 | 尝试 blocked→merged；finding 状态图之外的流转；reviewer 修改 finding；在还有未完成任务、blocker、无提交或未读消息时完成 mission。 |
+| `stale-base` | 操作准备期间仓库状态已变化，需要重试。 | two-phase mutation 重校验 |
+| `worktree-dirty` | mission worktree 有未提交改动，不能完成。 | `tower_complete` 前遗留 staged/modified/untracked 文件 |
 | `state-locked` | 另一个 Tower 写入者持有 state 锁。 | 锁超时后的并发写 |
 | `state-corrupt` | Tower state 文件不可读或无效。 | 手工编辑过的 `state.json` |
 | `config-invalid` | Tower 配置无效。 | 格式错误的仓库 `config.json`、违反 schema 的值 |
@@ -28,6 +30,7 @@
 | `git-timeout` | git 命令超时或输出超出缓冲区。 | 慢 pre-merge 钩子、超大 diff |
 | `spawn-unavailable` | subagents 服务不可用。 | 没有 `subagents` 的 Host |
 | `provider-missing` | 没有注册的 subagent provider。 | provider 列表为空 |
+| `provider-cooldown` | 连续可重试的 provider 失败后，spawn 进入短暂冷却。 | 等待 `blockedUntil` 后重试 |
 | `preset-missing` | 配置的 agent preset 未注册。 | 缺少 `tower-worker`/`tower-reviewer` preset 行、DSH 未重启 |
 | `reviewer-prerequisite` | reviewer spawn 的前置条件未满足。 | mission 尚未 `completed` 或还没有 worktree 就 spawn reviewer |
 | `not-authorized` | 调用方 agent 角色无权执行该操作。 | worker 调用仅限控制塔的工具，或修改 mission 状态/scope；reviewer 修改 finding |

package/docs/zh/reference/events.md

@@ -3,7 +3,7 @@
 [English](../../reference/events.md) | **简体中文**
 
 Tower 在工具成功调用（变更与只读）后发出进程内 Cordis 事件，其他插件因此可以观察仓库，而不必轮询。
-事件**不会**通过网络发送，也不包含遥测。
+本版本发出 29 个进程内事件。事件**不会**通过网络发送，也不包含遥测。
 
 ```js
 ctx.on('tower/merge', (payload) => {
@@ -33,14 +33,17 @@ ctx.on('tower/merge', (payload) => {
 | `tower/status` | `tower_status` 读取面板之后 |
 | `tower/preflight` | `tower_preflight` 评估门禁之后 |
 | `tower/doctor` | `tower_doctor` 完成只读检查之后 |
+| `tower/recover` | `tower_recover` 查看或清理 stale state 锁之后 |
 | `tower/test` | `tower_test` 运行测试发现之后 |
 | `tower/batch` | `tower_batch` 创建、查看或关闭 batch 之后 |
 | `tower/resource` | `tower_resource` 获取/释放/查看租约之后 |
 | `tower/import_legacy` | `tower_import_legacy` 保存旧版快照之后 |
 | `tower/legacy_map` | `tower_legacy_map` 映射或列出旧 id 之后 |
+| `tower/mode` | `tower_mode` 读取/变更会话模式之后（`value.mode`、`allowAgentControl`、`deniedWhileActive`） |
+| `tower/control` | `tower_control` 进入/退出模式之后（`value.mode`，操作者/理由在 `value` 中） |
+| `tower/reload` | `tower_reload` 返回重载调度/结果之后 |
 
-`tower_mode`、`tower_control` 与 `tower_reload` 不发出 Tower 事件。payload 是 JSON：
-`{tool, repoRoot, value}`。监听器抛错不会影响工具结果。
+payload 是 JSON：`{tool, repoRoot, value}`。监听器抛错不会影响工具结果。
 
 需要可持久审计的调用链时，请使用 `<git-common-dir>/dsh-tower/activity.jsonl` 与 `MISSIONS.md`；
 事件是进程内的，不会重放。

package/docs/zh/reference/testing.md

@@ -49,8 +49,9 @@ stdout/stderr 文件、SHA-256 哈希、退出码、计数、required 名称、w
 
 - `tower_test({repoRoot,missionId})` 按需运行发现并记录回执。
 - `tests.autoChecks` 开启时，`tower_complete` 会添加一条 `tests` 检查。
-- `gates.requireChecks` 要求任意完成检查；`gates.requireTests` 要求针对被审查 tip 的通过回执
-  （`tests-missing`）。
+- `gates.requireChecks` 要求任意完成检查；`gates.requireTests` 要求针对当前 mission 分支 tip 的
+  通过回执（`tests-missing`）。测试门禁与审查独立：即使 `review.requireReview:false`，测试门禁仍
+  检查分支 tip。
 
 ## 信任边界
 

package/docs/zh/reference/tools.md

@@ -3,9 +3,9 @@
 [English](../../reference/tools.md) | **简体中文**
 
 所有工具都接受 `repoRoot`（目标 Git 仓库内的绝对路径）并返回 JSON。
-本构建最多 28 个工具：下列 19 个核心仓库工具（含 `tower_interrupt`）、`tower_mode`、
-`mode.allowAgentControl` 开启时注册的 `tower_control`、`dev.hotReload` 开启时注册的
-`tower_reload`，以及 2.1 的验证/运维工具 `tower_doctor`、`tower_test`、`tower_batch`、
+本构建最多 29 个工具：下列 19 个核心仓库工具（含 `tower_interrupt`）、`tower_mode`、默认注册的
+`tower_control`（设 `mode.allowAgentControl:false` 可禁用）、`dev.hotReload` 开启时注册的
+`tower_reload`，以及 2.1 的验证/运维工具 `tower_doctor`、`tower_recover`、`tower_test`、`tower_batch`、
 `tower_resource`、`tower_import_legacy`、`tower_legacy_map`。
 
 `tower_mission` 使用 `id`（别名 `missionId`）；其他所有 mission 级工具使用 `missionId`
@@ -32,16 +32,16 @@ roster 角色由 `exec.agent` 与 roster 共同决定。mission 级工具（`tow
 | 工具 | 参数 | 用途 / 说明 |
 |---|---|---|
 | `tower_init` | `base?`、`autoGitInit?`、`snapshotDirty?`、`reanchor?` | 创建 `<git-common-dir>/dsh-tower/state.json`。`autoGitInit` 执行 `git init` 并创建空的初始提交；`snapshotDirty` 记录一个游离快照提交作为 mission 基线；`reanchor` 仅在没有非终态 mission 时修改基线。返回 `dirty`、`snapshotCommit`、`reanchored`。 |
-| `tower_plan` | `missions[]`（`title`、`scope[]`、`tasks[]?`、`deps[]?`、`kind?`、`context?`、`references[]?` ≤20、`reviewPolicy?`、`reviewExemptionReason?`） | 创建 mission `M1..`；重叠的 build scope 会自动加依赖；拒绝未知依赖与依赖循环。`reviewPolicy:"none"` 需要理由，并且要求 `gates.allowReviewExemption`。 |
+| `tower_plan` | `missions[]`（`title`、`scope[]`、`tasks[]?`、`deps[]?`、`kind?`、`context?`、`references[]?` ≤20、`reviewPolicy?`、`reviewExemptionReason?`） | 创建 mission `M1..`；重叠的 build scope 会自动加依赖；拒绝未知依赖与依赖循环。`reviewPolicy:"none"` 需要非空理由；审查门禁开启时，preflight 还要求 `gates.allowReviewExemption`。 |
 | `tower_mission` | `id`（别名 `missionId`）、`status?`、`task_done?`、`task_drop?`+`task_drop_reason?`、`blocker?`、`clear_blockers?`、`note?`、`scope?`、`pause_cause?`、`authorization?` | 更新单个 mission。worker 可安全使用的字段是 task/blocker/note；不能在这里设置 `merged`。暂停的 mission 记录 `pause_cause`（user/failure/resource/dependency）；恢复用户暂停的 mission 会遵循 `mode.requireResumeAuthorization`。 |
-| `tower_status` | `missionId?`、`offset?`、`limit?`、`includeGate?`、`format?` | 默认返回面板。`missionId` 返回完整详情（任务/备注/审查/finding/完成报告）。`offset`/`limit` 对 mission 分页（默认 20，最大 100），`includeGate` 附带门禁摘要，`format:"markdown"` 返回看板。 |
+| `tower_status` | `missionId?`、`offset?`、`limit?`、`includeGate?`、`format?` | 默认返回面板。`missionId` 返回完整详情（任务/备注/审查/finding/完成报告）。`offset`/`limit` 对 mission 分页（默认 20，最大 100），`includeGate` 附带门禁摘要，`format:"markdown"` 返回看板。host 提供 mode hook 时还会包含 `mode.lastChange` 与最近 `history`。 |
 | `tower_spawn` | `missionId`（别名 `id`）、`role`（`worker`/`reviewer`）、`name?`、`instructions?`、`worktreeRoot?`、`wait?`、`waitMs?`、`takeover?`、`includeDirtyBase?` | 准备或复用 worktree 并启动子代理。worker 使用 `tower-worker`；reviewer 要求 mission 为 `completed`，并使用只读的 `tower-reviewer`。`takeover:true` 替换已不再运行的 worker 条目（ownerGeneration 递增）。每个 mission 只能有一个活跃 worker；`spawn.maxLiveWorkers` 限制整个仓库。 |
 | `tower_roster` | — | roster 及来自子代理目录的实时活动（`running`/`inactive`/`missing`/`unknown`）与 `stale` 标记。只读。 |
 | `tower_adopt` | `retireMissing?` | 把 roster 条目与持久子代理目录对账。可证明已消失的 agent 会被标记为 retired（默认），或标记为 `missing`（`retireMissing:false`）以便检查/接管。 |
 | `tower_diff` | `missionId`（别名 `id`）、`maxBytes?` | 只读 merge-base diff：文件、提交、有上限的 patch。供 reviewer 安全使用。 |
 | `tower_send` | `to`、`subject`、`body`、`scope?`、`interrupt?`、`consentRef?` | 向 roster 名称、`tower` 或 `all` 发送持久消息；对运行中的 agent 会即时投递。`interrupt:true` 先中断运行中的回合（Kimi 风格）再投递；`consentRef` 记录用于审计。受 `send.maxPerMinute` 限速。 |
 | `tower_inbox` | `limit?`、`include_read?` | 读取并确认发给调用者的消息；未读消息会阻止 `tower_complete`。 |
-| `tower_complete` | `missionId`（别名 `id`）、`report`、`checks?` | worker 报告完成（mission 变为 `completed`，等待审查）。要求当前 owner、无未完成任务/blocker、≥1 个提交、无未读消息。`checks` 记录 `{name, command?, exitCode?, evidence?}` 证据；`gates.requireChecks` 可以强制要求。配置了测试发现时还会自动运行并添加 `tests` 检查；失败会抛出 `[tower:tests-failed]`。 |
+| `tower_complete` | `missionId`（别名 `id`）、`report`、`checks?` | worker 报告完成（mission 变为 `completed`，可进入 preflight 与可选审查）。要求当前 owner、无未完成任务/blocker、≥1 个提交、无未读消息。`checks` 记录 `{name, command?, exitCode?, evidence?}` 证据；`gates.requireChecks` 可以强制要求。配置了测试发现时还会自动运行并添加 `tests` 检查；失败会抛出 `[tower:tests-failed]`。 |
 | `tower_interrupt` | `to?`（roster 名称）、`agentId?`、`reason?` | 通过 `subagents.interrupt` 中断一个运行中的 roster agent，并记录 `state:"interrupted"`。幂等（未运行 → `interrupted:false`）。 |
 | `tower_finding` | `type`、`title`、`summary`、`details`、`suggested_fix`、`severity?`、`missionId?`、`location?` | 记录 scope 之外的问题；reviewer 用它代替直接改文件。新 finding 初始为 `open`。 |
 | `tower_findings` | `id?`、`status?`、`note?`、过滤（`type?`、`severity?`、`missionId?`、`open?`、`limit?`） | 生命周期工具：列出/读取/流转。状态为 `open → triaged → fixed`/`wontfix`，允许重新打开。只有控制塔或 worker 能修改；reviewer 只能列出/读取。 |
@@ -51,9 +51,10 @@ roster 角色由 `exec.agent` 与 roster 共同决定。mission 级工具（`tow
 | `tower_rebase` | `missionId`（别名 `id`） | 在 worktree 内把分支 rebase 到基线。worker 运行中或 worktree 脏时拒绝。分支已包含在基线中时返回 `alreadyMerged` 且保持分支不动。 |
 | `tower_teardown` | `force?`、`exclude?`、`dry_run?`（别名 `dryRun`） | 移除符合条件的 merged/abandoned worktree 与分支；运行中的 agent 始终保留。 |
 | `tower_mode` | — | 报告模式、最近修改、被暂停的 goal、被拒绝的工具、store 路径、插件版本、HMR 可用性、workspace 锁持有者。 |
-| `tower_control` | `action`（`enter`/`exit`）、`reason` | 模型主动切换模式；仅当 `mode.allowAgentControl` 为 `true` 时可用；`reason` 必填。 |
+| `tower_control` | `action`（`enter`/`exit`）、`reason` | 模型主动切换模式；默认注册，设 `mode.allowAgentControl:false` 可禁用；`reason` 必填。 |
 | `tower_reload` | `repoRoot?` | 仅开发用：请求 DSH HMR 对账 profile 并从磁盘重载 Host 插件。`dev.hotReload` 开启时注册；在工具结果返回后调度（默认 50 ms）；没有 HMR 时以 `reload-unavailable` 失败。传入 `repoRoot` 时调用者必须是控制塔。 |
 | `tower_doctor` | —（需要 `repoRoot`） | 只读健康契约：git、state schema、config、preset/subagents/HMR、workspace 锁、roster、worktree realpath/归属、测试配置、leases。返回 `{ok, checks[{id,status,detail}], environmentContract}`。从不写状态。 |
+| `tower_recover` | `action`（`status`/`clear-stale-lock`）、`confirm?` | 恢复诊断与显式 stale state-lock 修复。`clear-stale-lock` 需要 `confirm:"CLEAR_STALE_LOCK"`，只把 PID 已死的锁移到备份文件；不会重置状态或 worktree。 |
 | `tower_test` | `missionId`（别名 `id`） | 运行 worktree 的 `package.json` 中 `tower.testDiscovery` 配置的发现命令并记录回执；失败时 `ok:false`。自动准入检查请用 `tower_complete`。 |
 | `tower_batch` | `action`（`create`/`status`/`close`/`abandon`）、`missionIds?`、`exclusions?`、`requiredChecks?`、`receiptPaths?`、`batchId?`、`checks?`、`treeTip?`、`receiptHashes?`、`reason?` | 有限证据批次。create 冻结成员/检查/回执；close 校验每条必需检查与回执哈希；`merged` 成员也可参与 close；abandon 可退掉过期的 open batch 且不删除 mission。成员关系不可变。 |
 | `tower_resource` | `action`（`acquire`/`release`/`status`）、`name?`、`holder?`、`token?`、`ttlMs?`、`force?` | 每个仓库的咨询式租约，位于 `<common>/dsh-tower/leases.json`。没有 OS CPU/内存硬上限；过期的租约需要显式 `force` 与正确 token。 |