dsh-tower 1.3.0 → 2.0.1

package/CHANGELOG.md

@@ -1,5 +1,114 @@
 # Changelog
 
+> 自 2.0.0 起，每个版本按 **新增 / 变更 / 修复** 三类组织；更早的版本保留原始流水式记录。
+
+## 2.0.1（2026-10-18）
+
+### 新增
+
+- **`tower_batch` 的 `abandon` 动作**：可带 `reason` 退掉过期的 open batch，不修改 mission 状态；
+  用于"先 merge 后 close"或证据窗口已过的场景。
+
+### 修复
+
+- **#3 `allowAgentControl` 被 schema 默认值遮蔽**：移除 `mode.allowAgentControl` 的 schema 默认值，
+  在 legacy 别名解析后再应用默认；随包 patch 改用 canonical `mode.allowAgentControl: true`。
+  Cordis 校验后的配置现在能正确注册 `tower_control`。
+- **#4 `tower_preflight` 未知 mission 产生非 lossless 输出**：`evaluateGate` 的 early return 与工具
+  包装补齐 `branchTip/baseTip/changedFiles/review` 的 `null`/`[]` 形状。
+- **#5 未知依赖被分类为 `tool-internal`**：`depends on unknown mission` 归入 `invalid-argument`。
+- **#6 worker 可 spawn 到 merged/abandoned mission**：spawn 前拒绝终态 mission，不再 provision/
+  activation，不再改写已合并 mission 的 owner/generation。
+- **#7 live `tests/live/ui-slots.cjs` 在新会话 dock 隐藏时误报**：先提交 host-handled `/tower`
+  命令绑定会话，再断言 dock；`DSH_TEST_EXPECT_HINT=1` 才要求 dock 可见。
+- **#8 `plan-mode.test.mjs` 写入真实 `$DSH_HOME`**：测试前设置临时 `DSH_HOME` 并在 after 清理；
+  清理了历史 `session-plan-test` 残留。
+- **#9 `tower_batch` close 拒绝 merged 成员/无法退掉 stale batch**：`merged` 与 completed 一样
+  可 close（checks 仍从完成报告/testRuns/close-time checks 解析）；新增 `abandon` 且 batch 状态
+  可退，不会永久卡死。
+- **#10 `tower_doctor` 在成功 teardown 后误报 worktree missing**：跳过带 `worktreeRemovedAt` 的
+  mission，并在检查详情中注明已移除数量。
+
+### 变更
+
+- 离线套件增至 212 项（新增 issue 回归覆盖）；`docs:check` 仍为 28 tools / 32 blockers /
+  30 errors / 25 events。
+
+## 2.0.0（2026-10-18）
+
+### 新增
+
+- **仓库级配置层**：`Tower.open()` 读取 `<git-common-dir>/dsh-tower/config.json`，优先级为
+  代码默认 < profile 配置 < 仓库配置 < 工具参数；`review`/`merge`/`worktrees`/`spawn` 分组生效。
+- **稳定工具错误码**：新增 `lib/errors.js`，工具失败统一 `[tower:<code>]` 前缀，覆盖 17 个 code；
+  新增 `docs/reference/errors.md` 并由 `npm run docs:check` 校验。
+- **finding 生命周期**：新增 `tower_findings`（列表/读取/状态流转/备注），状态为
+  `open → triaged → fixed` / `wontfix` 且可重新打开；只有 tower 或 worker 能改状态，reviewer 只读。
+- **中文文档**：新增 `docs/zh/`（文档索引、quickstart、工具/配置/blocker/错误码参考），
+  与英文参考页保持同一套工具名、blocker 与错误码。
+- **测试与门禁**：新增仓库配置、finding 生命周期、工具别名/错误码/输出 schema、spawn mock
+  与全流程 schema 校验用例；`docs:check` 同时校验中英文参考页、工具名、blocker 与错误码。
+- **协议硬化**：`tower_interrupt`（停止 running agent）、`tower_send(interrupt:true)`；
+  `tower_init` 支持 `autoGitInit`/`snapshotDirty`/`reanchor`；worker 不能直接完成/放弃/扩界，
+  completed 必须经 `tower_complete`；单 mission 单活 worker + `takeover` 接管 + generation。
+- **治理与可观测**：可选 `mode.workspaceLock` 仓库互斥；`spawn.maxLiveWorkers`、`send.maxPerMinute`
+  与 roster stale 标记；`tower_status` 分页/单 mission 明细/gate digest/markdown；`MISSIONS.md`
+  人类可读门板；`tower/*` 进程内事件；`tower_complete.checks` + `gates.requireChecks`。
+- **热重载**：`/tower reload` 与 `tower_reload` 调用 DSH HMR `reconcileProfile`；新增
+  `npm run dev:hmr` 脚本把 linked 仓库加入 profile HMR watch root；`docs/guide/hot-reload.md`。
+- **2.1 测试准入**：读取 worktree `package.json` 的 `tower.testDiscovery`（TAP/json-array），支持
+  `tests.admission:spawn|complete`、16 MiB/60s 预算、minCount/required；`tower_test` 与
+  `tower_complete` 自动生成 `tests` check；`gates.requireTests` / `tests-missing` / `tests-failed`。
+- **2.1 批次与运营**：`tower_batch`（create/status/close，冻结成员、requiredChecks、receiptPaths）、
+  `tower_resource`（advisory lease，token/过期显式 force）、`tower_doctor`（只读健康契约）、
+  `tower_import_legacy` / `tower_legacy_map`（只读快照 + 审计映射）。
+- **2.1 治理**：per-repo roster watchdog（`spawn.staleMs` 15s 标记 stale 并阻断合并）、
+  `spawn.maxWaitMs` 90s、`mode.workspaceLockScope`、plan/tower 互斥（默认清除 plan）、
+  `/tower base <branch>`、`docs.boardLocation`、delivery ack、merge intent 持久化。
+- **2.1 UI**：ui-bundle 增加 12 个 tower tool 卡片、composer dock 最新摘要与 shell.overlay 瞬时状态条；
+  纯会话派生，无 Host RPC/iframe。
+- **2.1 文档**：`docs/reference/testing.md`、`operations.md`、`doctor.md` 与中文同步；工具面 28。
+
+### 变更
+
+- **结构化输出 schema**：全部工具声明 output schema（spawn/status/diff/merge/review/preflight
+  等核心工具含字段结构），并按 DSH 的输出校验规则保证可空字段可空。
+- **命名统一（兼容别名）**：mission 级工具同时接受 `id` 与 `missionId`；`task_done`/`taskDone`、
+  `task_drop`/`taskDrop`、`clear_blockers`/`clearBlockers`、`include_read`/`includeRead`、
+  `dry_run`/`dryRun`、`timeoutMs`/`timeout_ms`、`waitMs`/`wait_ms` 等写法均可，并在参数 schema
+  中显式声明；输出保持既有规范。
+- **诊断信息**：`tower_status` 增加 `config.path`、`config.repoConfigPresent` 与
+  `findingsByStatus`；worker/reviewer preset 允许 `tower_findings`。
+- **配置解析**：兼容别名只用于补缺——同时设置 `section` 与 `mode.promptSection` 时规范键优先；
+  仓库配置增加 1 MiB 大小上限与 `__proto__`/`constructor`/`prototype` 等危险键拒绝。
+- **配置默认值**：`mode.denyTools` 追加 workflow/ralph/subagent/subagent_fork/wait_agent/team_task_list
+  （Tower 模式与其它编排互斥）；新增 `spawn.maxLiveWorkers:4`、`spawn.staleMs:15000`、
+  `spawn.maxWaitMs:90000`、`send.maxPerMinute:120`、`gates.requireChecks:false`、
+  `gates.requireTests:false`、`docs.board:true`、`leases.ttlMs:900000`、`dev.hotReload:true`；
+  随包 patch 打开 `workspaceLock`/`interruptDefault`/`autoGitInit`。
+- **briefing**：worker/reviewer 生成历史审查、上一轮 findings/decision、completion checks 与
+  related findings，长文本截断；reviewer 必须核对 completion checks。
+- **输出/工具面**：`tower_status` 增加 total/offset/nextOffset/detail/markdown，并**默认只返回前 20 个 mission**（旧版返回全部；旧调用需要更多时用 `limit`/`offset`）；`tower_adopt`
+  支持 `retireMissing:false`；`tower_mode` 返回 pluginVersion/HMR/workspace lock；`tower_roster`
+  增加 `stale`。工具总数最多 28（含 doctor/test/batch/resource/import/legacy_map 与可选的 control/reload）。
+- **离线套件**：测试增至 206 项（含 2.1 discovery/batch/leases/legacy/doctor/UI/plan-mode/integration 用例）。
+- 除 `tower_status` 默认分页与 `mode.denyTools` 默认扩充外，既有工具参数与输出保持兼容。
+
+### 修复
+
+- **模式工具 schema 与返回值不一致**：`tower_mode`/`tower_control` 的 `lastChange`、`pausedGoal`、
+  `goalNote` 在正常路径返回 `null`，原 schema 会触发 DSH 强制输出校验失败；已改为可空并补回归测试。
+- **错误码分类补全**：state 校验失败统一归为 `state-corrupt`；`tower_complete` 的未完成任务、
+  blocker、无提交、未读消息等前置条件归为 `invalid-transition`，不再落到 `tool-internal`。
+- **findings 更新后的计数**：状态流转后返回的 `counts` 之前是旧值，现在按变更后重新统计。
+- **findings 只读路径**：列表/读取不再获取写锁，与工具描述一致，长合并或 hook 期间也能读取。
+- **mission id 规范化**：`tower_mission` 对首尾空白的 `id` 先 trim 再查找，不再误报
+  `mission-not-found`。
+- **角色绕过**：worker 之前可经 `tower_mission` 直接 completed/abandoned/扩界或清 blocker，
+  绕过 `tower_complete` 的未读/提交证据；现由服务端角色强制。
+- **并发与接管**：同一 mission 不再允许出现第二个 live worker；stale/interrupted/failed 的
+  worker 可显式 takeover，running worker 必须先中断，否则 `takeover-refused`。
+
 ## 1.3.0 — 2026-10-18
 
 - **独立的只读 reviewer preset**：新增 `reviewer.js` / `tower-reviewer`，去掉 `write`/`edit`/`pwsh`/

package/CONTRIBUTING.md

@@ -21,7 +21,7 @@ Requirements: Node.js 22+, Git. No package installation is needed for the offlin
 
 ## Pull request checklist
 
-1. `npm test` passes locally (26 tests today, including protocol end-to-end against a real temporary Git repository) and `npm run docs:check` passes.
+1. `npm test` passes locally (206 tests today, including protocol end-to-end against a real temporary Git repository and mock spawn coverage) and `npm run docs:check` passes.
 2. New behavior has a test. Bug fixes should add a test that fails before the fix.
 3. No secrets, tokens, personal paths, session logs, or generated artifacts are added. `.gitignore` covers local acceptance output; do not force-add it.
 4. Keep the public API and state-file formats compatible; if a change is breaking, call it out in `CHANGELOG.md` and bump the version.

package/README.en.md

@@ -18,6 +18,36 @@ The repository root **is** the DSH bundle: `package.json` declares `dsh.bundle.p
 - **Review-gated merges.** A reviewer bound to the current branch tip must submit a `clean` / `merge` verdict; the merge gate re-checks scope, staleness, task completion, review history, and worktree ownership before a `--no-ff` merge.
 - **Durable coordination.** Roster, inbox, findings, reviews, and mission state are persisted under `.git/dsh-tower/`, so a restart does not lose the plan.
 - **Safe by default.** While Tower mode is active, `create_goal`, `update_goal(resume)`, `todo_write`, the Team task board, and `spawn_teammate` are refused; a paused goal is never resumed automatically.
+- **Traceable finding lifecycle.** `tower_findings` lists, reads, and moves findings through `open → triaged → fixed` / `wontfix` (and can reopen); only the tower or a worker may change state, while reviewers can only read.
+- **Repository-level config.** Any repository can override review/merge/worktree/spawn policy in `<git-common-dir>/dsh-tower/config.json`; tool arguments override the repository layer, so no profile edit is needed per repository.
+- **Stable error codes.** Tool failures carry a `[tower:<code>]` prefix (for example `mission-not-found`, `preset-missing`, `config-invalid`) so callers can branch deterministically.
+- **Role enforcement and control.** Workers cannot complete/abandon a mission or widen its scope directly (completion goes through the `tower_complete` evidence gate); the tower can stop a runaway agent with `tower_interrupt`, and `tower_send(interrupt:true)` interrupts a running turn.
+- **Workspace exclusivity and limits.** Optional `mode.workspaceLock` allows one Tower session per repository; `spawn.maxLiveWorkers`, `send.maxPerMinute` and roster stale flags bound concurrency and message bursts.
+- **2.1 verification and operations.** `tower_test` runs the worktree's `tower.testDiscovery` (TAP/json-array, admission at spawn or complete), `tower_doctor` is a read-only health contract, `tower_batch` closes finite evidence batches, `tower_resource` manages advisory leases, and `tower_import_legacy`/`tower_legacy_map` import old snapshots and audit-map ids. Adds `worker-stale`, test gates, plan/Tower mutual exclusion, `workspaceLockScope`, `docs.boardLocation` and delivery acknowledgements.
+- **Hot reload.** In a profile with DSH HMR, `/tower reload`, `tower_reload` and `npm run dev:hmr` apply linked plugin changes without a restart; `plugin_manager` install/update already applies live.
+- **Evidence gate and events.** Workers can record `checks` in `tower_complete` and `gates.requireChecks` can require them; every mutation emits `tower/*` events and refreshes `MISSIONS.md`.
+
+## When to use Tower
+
+Tower is a **delivery protocol for changes to a Git repository**, not the default answer for every multi-agent task. It fits when:
+
+- a feature or refactor splits into 2–8 missions with clear scopes that can be reviewed independently;
+- ordering matters (migrations, dependencies, branch freshness, scope reservations);
+- the repository is sensitive or release-bound, and you need a reviewed commit, test evidence, and an auditable merge;
+- work spans context compaction, restarts, or multiple days and must be recoverable from local state;
+- "done" means tasks + tests + independent review, not just a confident message in chat.
+
+It is a poor fit for one-file or one-line hotfixes, requirements still being discovered, open-ended research, many tiny independent tasks, interactive UI pairing, or cross-repository work. Rule of thumb: **if you would not open a PR for it, Tower is probably too heavy.**
+
+How it differs (full guide: [When to use Tower](docs/guide/scenarios-and-philosophy.md)):
+
+- **Ordinary parallel subagents**: cheap and flexible for read-only exploration or trying approaches; no worktree, review, or merge gate.
+- **Agent Teams**: shared task board and peer collaboration for design, research, and cross-cutting decisions; integration is usually human, with no hard Git gate.
+- **Ralph loop**: fresh agents retry one objective, good for iterative search/repair; no mission contract or merge review.
+- **Workflow orchestration**: scripted high fan-out/pipelines for audits, batch analysis, and verification; no branch isolation or merge gate.
+- **Tower**: a few missions + isolated writers + independent review + evidence + a merge gate, for "we have decided; land it safely".
+
+Tower mode refuses Team/Workflow/Ralph/ordinary subagent tools and clears plan mode so two orchestration protocols do not drive one session. Compose by phase instead: use Workflow/Team to analyze and decide, then Tower to execute the repository change.
 
 ## Requirements
 
@@ -105,14 +135,16 @@ Image and file attachments are forwarded together with the instruction as one co
       maxDepth: 1
 ```
 
-- `mode.allowAgentControl` defaults to `false` in code; the bundled `cordis.patch.yml` enables it (`true`) so the model may enter/leave when the user intent or task state warrants it, always stating a reason.
-- Every key and default is in [docs/reference/config.md](docs/reference/config.md); unknown keys are rejected so typos cannot silently disable security-relevant settings.
+- `mode.allowAgentControl` defaults to `false` in code; the bundled `cordis.patch.yml` enables it (`true`) so the model may enter/leave when the user intent or task state warrants it, always stating a reason. The bundled patch also enables `mode.workspaceLock` (single-active tower), `send.interruptDefault`, `init.autoGitInit`, and sets `spawn.staleMs` to 15s.
+- `/tower base <branch>` records a session-level init base preference; `/tower on` clears an active plan mode (`mode.planModePolicy:"refuse"` instead refuses entry), keeping plan and Tower mutually exclusive.
+- Repository-level config: put the same JSON shape in `<git-common-dir>/dsh-tower/config.json` (usually `.git/dsh-tower/config.json`) to override `review`/`merge`/`worktrees`/`spawn`. Precedence is code defaults < profile config < repository config < tool arguments. `mode.*` is session-scoped and only the profile layer controls it.
+- Every key and default is in [docs/reference/config.md](docs/reference/config.md); unknown top-level keys are rejected so typos cannot silently disable security-relevant settings, while unknown keys inside a group are ignored. Tool error codes are in [docs/reference/errors.md](docs/reference/errors.md).
 
-## Tools (18)
+## Tools (26 core)
 
-`tower_init` · `tower_plan` · `tower_mission` · `tower_status` · `tower_spawn` · `tower_roster` · `tower_adopt` · `tower_diff` · `tower_send` · `tower_inbox` · `tower_complete` · `tower_finding` · `tower_review` · `tower_preflight` · `tower_merge` · `tower_rebase` · `tower_teardown` · `tower_mode`
+`tower_init` · `tower_plan` · `tower_mission` · `tower_status` · `tower_spawn` · `tower_roster` · `tower_adopt` · `tower_diff` · `tower_send` · `tower_inbox` · `tower_complete` · `tower_interrupt` · `tower_finding` · `tower_findings` · `tower_review` · `tower_preflight` · `tower_merge` · `tower_rebase` · `tower_teardown` · `tower_mode` · `tower_doctor` · `tower_test` · `tower_batch` · `tower_resource` · `tower_import_legacy` · `tower_legacy_map`
 
-`tower_control` exists only when `allowAgentControl: true` (the bundled patch enables it, so an installed build exposes 19 tools).
+`tower_control` exists only when `allowAgentControl: true`; `tower_reload` is registered while `dev.hotReload` is on (default true) and returns `reload-unavailable` without an HMR service (so up to 28 tools). Mission-scoped tools also accept `id` as an alias for `missionId`; snake/camel spellings such as `task_done`/`taskDone` are both accepted.
 
 ## Safety and guardrails
 
@@ -122,7 +154,7 @@ Image and file attachments are forwarded together with the instruction as one co
 - **Worktree ownership.** Dirty worktrees, a running worker, or a branch owned by a closed mission block teardown/merge.
 - **Goal isolation.** Entering Tower mode pauses the active goal and records it; leaving does not resume it. Use `/tower off` and resume the goal yourself.
 
-13 stable blocker codes (plus 6 additional gate guards and 6 merge/rebase failure codes) — the complete list with triggers and fixes is in [docs/reference/blockers.md](docs/reference/blockers.md).
+32 stable blocker/failure codes (including gate guards, `no-check-evidence`, `worker-stale`, test gates, and merge/rebase operation failures) — the complete list with triggers and fixes is in [docs/reference/blockers.md](docs/reference/blockers.md). Tool-level error codes are in [docs/reference/errors.md](docs/reference/errors.md); events are in [docs/reference/events.md](docs/reference/events.md).
 
 ## How it works
 
@@ -156,13 +188,17 @@ Workers use the bundled `tower-worker` preset (writable worktree surface); revie
 npm test        # node --test tests/*.test.mjs
 ```
 
+Hot-reload development: `npm run dev:hmr` adds this checkout to the current profile's HMR watch roots
+(one DSH restart); afterwards `/tower reload` or the automatic watcher applies `lib/` edits. See
+[docs/guide/hot-reload.md](docs/guide/hot-reload.md).
+
 The offline suite needs no DSH process and creates throwaway Git repositories in the OS temp directory. `tests/README.md` documents the isolated Web-runtime checks, model-driven acceptance, and the session-diagnostic scripts used while hardening the plugin.
 
 ## Documentation
 
 - [docs/README.md](docs/README.md) — documentation index (new user / operator / maintainer paths)
-- [Quick start](docs/guide/quickstart.md) · [Install, upgrade and migration](docs/guide/install-upgrade-migration.md)
-- [Tools reference](docs/reference/tools.md) · [Config reference](docs/reference/config.md) · [Blockers and failure codes](docs/reference/blockers.md)
+- [Chinese docs](docs/zh/README.md) · [Quick start](docs/guide/quickstart.md) · [Install, upgrade and migration](docs/guide/install-upgrade-migration.md)
+- [Tools reference](docs/reference/tools.md) · [Config reference](docs/reference/config.md) · [Blockers and failure codes](docs/reference/blockers.md) · [Error codes](docs/reference/errors.md) · [Events](docs/reference/events.md) · [Testing](docs/reference/testing.md) · [Batches/leases/legacy](docs/reference/operations.md) · [Doctor](docs/reference/doctor.md) · [Hot reload](docs/guide/hot-reload.md)
 - [Architecture and state machine](docs/architecture/overview.md) · [Operations runbook](docs/operations/runbook.md) · [Security model](docs/operations/security.md)
 - [FAQ](docs/faq.md) · [Examples](docs/examples/first-mission.md)
 

package/README.md

@@ -18,6 +18,36 @@ Tower 模式与 mission/审查工作流的灵感来自 Moonshot AI 的 **Kimi Co
 - **审查门禁合并。** 审查者必须针对当前分支 tip 给出 `clean` / `merge` 结论；合并门禁重新校验 scope、分支新鲜度、任务完成度、审查记录与 worktree 归属，通过后才执行 `--no-ff` 合并。
 - **可恢复的协作状态。** roster、inbox、findings、reviews 与 mission 状态持久化在 `.git/dsh-tower/` 下，重启不会丢计划。
 - **默认安全。** Tower 模式开启期间拒绝 `create_goal`、`update_goal(resume)`、`todo_write`、Team 任务板与 `spawn_teammate`；被暂停的 goal 不会被自动恢复。
+- **可追溯的 finding 生命周期。** `tower_findings` 列表、读取并按 `open → triaged → fixed` / `wontfix` 流转，也可重新打开；只有 tower 或 worker 能改状态，reviewer 只能读。
+- **仓库级配置。** 每个仓库可用 `<git-common-dir>/dsh-tower/config.json` 覆盖 review/merge/worktree/spawn 策略，工具参数再覆盖仓库配置；无需为不同仓库改 profile。
+- **稳定错误码。** 工具失败统一带 `[tower:<code>]` 前缀（如 `mission-not-found`、`preset-missing`、`config-invalid`），调用方可稳定分支处理。
+- **角色强制与可控中断。** worker 不能直接完成/放弃 mission 或扩界（完成必须走 `tower_complete` 证据门），tower 可随时用 `tower_interrupt` 停止跑偏的 agent；`tower_send(interrupt:true)` 可中止运行中的 turn。
+- **仓库互斥与限流。** 可选 `mode.workspaceLock` 让同一仓库只有一个 Tower 会话；`spawn.maxLiveWorkers`、`send.maxPerMinute`、roster stale 标记约束并发与消息风暴。
+- **可热重载。** 在带 DSH HMR 的 profile 中，`/tower reload`、`tower_reload` 与 `npm run dev:hmr` 让 linked 插件代码改动无需重启即生效；`plugin_manager` 安装/更新本身即时生效。
+- **测试证据门与事件。** worker 可在 `tower_complete` 记录 `checks`，`gates.requireChecks` 可强制；每次 mutation 后发射 `tower/*` 事件并刷新 `MISSIONS.md`。
+- **2.1 验证与运营。** `tower_test` 执行 worktree 声明的 `tower.testDiscovery`（TAP/json-array，准入可设 spawn/complete），`tower_doctor` 只读健康契约，`tower_batch` 批次证据收口，`tower_resource` advisory lease，`tower_import_legacy` / `tower_legacy_map` 只读旧版导入与审计映射；新增 `worker-stale`、tests 门禁、plan/tower 互斥、`workspaceLockScope`、`docs.boardLocation` 与交付 ack。
+
+## 何时使用 Tower
+
+Tower 是**面向 Git 仓库变更的交付协议**，不是所有多代理场景的默认答案。它适合：
+
+- 一个特性/重构能拆成 2–8 个 scope 清晰、可独立审查的 mission；
+- 有依赖顺序、需要分支新鲜度与 scope 约束的迁移；
+- 敏感仓库、发布绑定变更，或需要"被审查 commit + 测试证据 + 可审计合并"的工作；
+- 跨上下文压缩、重启、多天协作，需要从本地状态恢复的工作；
+- 需要把"完成"定义成任务 + 测试 + 独立审查，而不是聊天里的一句"好了"。
+
+不适合：单文件/一行 hotfix、需求仍在探索、开放式研究、大量极小的独立任务、交互式 UI 配对、或跨仓库工作。判断标准：**如果你不会为它开 PR，Tower 很可能太重。**
+
+与其他模式的区别（详见[完整指南](docs/guide/scenarios-and-philosophy.md)）：
+
+- **普通并行子代理**：便宜、灵活，适合只读探索/试方案；没有 worktree、审查与合并门禁。
+- **Agent Teams**：共享任务板与多人/多 agent 协作，适合设计、研究、横切决策；集成通常由人做，没有 Git 隔离的硬门禁。
+- **Ralph 循环**：用新鲜 agent 对同一目标反复尝试，适合迭代搜索/修复；没有 mission 契约与合并审查。
+- **Workflow 编排**：脚本化高扇出/流水线，适合批量分析、审计、验证；不做 Git 分支隔离与合并门禁。
+- **Tower**：少量 mission + 隔离写入 + 独立审查 + 证据 + 合并门禁，适合"决定要做、需要安全落地"的仓库变更。
+
+Tower 模式会拒绝 Team/Workflow/Ralph/普通 subagent 工具并清除 plan mode，避免两套编排协议同时驱动一个会话；请按阶段组合，例如先用 Workflow/Team 分析决策，再用 Tower 执行仓库变更。
 
 ## 环境要求
 
@@ -105,14 +135,16 @@ tower_teardown  repoRoot=D:\work\repo
       maxDepth: 1
 ```
 
-- 代码中 `mode.allowAgentControl` 默认 `false`；随包 `cordis.patch.yml` 设为 `true`：模型可在用户意图/任务状态明确时自行进出，但必须给出理由；设为 `false` 时只有人类能切换。
-- 所有键与默认值见 [docs/reference/config.md](docs/reference/config.md)；未知键会被拒绝（防止拼写错误静默失效）。
+- 代码中 `mode.allowAgentControl` 默认 `false`；随包 `cordis.patch.yml` 设为 `true`：模型可在用户意图/任务状态明确时自行进出，但必须给出理由；设为 `false` 时只有人类能切换。随包 patch 还默认开启 `mode.workspaceLock`（单活塔）、`send.interruptDefault`、`init.autoGitInit`，并把 `spawn.staleMs` 设为 15s。
+- `/tower base <branch>` 可设置会话级 init base 偏好；`/tower on` 会清除活跃 plan mode（`mode.planModePolicy:"refuse"` 则拒绝进入），保证 plan/tower 互斥。
+- 仓库级配置：在 `<git-common-dir>/dsh-tower/config.json`（通常是 `.git/dsh-tower/config.json`）放入同样的 JSON 结构，可覆盖 `review`/`merge`/`worktrees`/`spawn`；优先级为代码默认 < profile < 仓库配置 < 工具参数。`mode.*` 属于会话级，只在 profile 生效。
+- 所有键与默认值见 [docs/reference/config.md](docs/reference/config.md)；未知顶层键会被拒绝（防止拼写错误静默失效），嵌套分组内的未知键会被忽略。工具错误码见 [docs/reference/errors.md](docs/reference/errors.md)。
 
-## 工具（18 个）
+## 工具（26 个核心）
 
-`tower_init` · `tower_plan` · `tower_mission` · `tower_status` · `tower_spawn` · `tower_roster` · `tower_adopt` · `tower_diff` · `tower_send` · `tower_inbox` · `tower_complete` · `tower_finding` · `tower_review` · `tower_preflight` · `tower_merge` · `tower_rebase` · `tower_teardown` · `tower_mode`
+`tower_init` · `tower_plan` · `tower_mission` · `tower_status` · `tower_spawn` · `tower_roster` · `tower_adopt` · `tower_diff` · `tower_send` · `tower_inbox` · `tower_complete` · `tower_interrupt` · `tower_finding` · `tower_findings` · `tower_review` · `tower_preflight` · `tower_merge` · `tower_rebase` · `tower_teardown` · `tower_mode` · `tower_doctor` · `tower_test` · `tower_batch` · `tower_resource` · `tower_import_legacy` · `tower_legacy_map`
 
-`tower_control` 仅在 `allowAgentControl: true` 时存在（随包 patch 默认开启，因此安装后共 19 个工具）。
+`tower_control` 仅在 `allowAgentControl: true` 时注册；`tower_reload` 在 `dev.hotReload`（默认 true）时注册，无 HMR 服务调用会返回 `reload-unavailable`（因此最多 28 个工具）。mission 级工具同时接受 `id` 作为 `missionId` 的别名；`task_done`/`taskDone` 等 snake/camel 写法均可。
 
 ## 安全与约束
 
@@ -122,7 +154,7 @@ tower_teardown  repoRoot=D:\work\repo
 - **worktree 归属。** 脏工作树、运行中的 worker、已关闭 mission 的分支都会阻止合并或 teardown。
 - **goal 隔离。** 进入 Tower 模式会暂停活跃 goal 并记录；退出不会自动恢复，需要你自行恢复。
 
-13 个稳定 blocker code（另有 6 个 gate 守卫与 6 个 merge/rebase 操作失败码）——完整清单、触发条件与修复动作见 [docs/reference/blockers.md](docs/reference/blockers.md)。
+32 个稳定 blocker/failure code（含 gate 守卫、`no-check-evidence`、worker-stale、tests 门禁与 merge/rebase 操作失败码）——完整清单、触发条件与修复动作见 [docs/reference/blockers.md](docs/reference/blockers.md)。工具本身抛出的错误码见 [docs/reference/errors.md](docs/reference/errors.md)，事件见 [docs/reference/events.md](docs/reference/events.md)。
 
 ## 工作原理
 
@@ -154,13 +186,15 @@ worker 与 reviewer 是使用内置 `tower-worker` preset 的普通 DSH 子代
 npm test        # node --test tests/*.test.mjs
 ```
 
+热重载开发：`npm run dev:hmr` 把本仓库加入当前 profile 的 HMR watch root（需重启 DSH 一次），之后编辑 `lib/` 代码可用 `/tower reload` 或自动 watch 生效；详见 [docs/guide/hot-reload.md](docs/guide/hot-reload.md)。
+
 离线套件不需要 DSH 进程，只在系统临时目录创建一次性 Git 仓库。隔离 Web 运行时检查、模型驱动验收和会话诊断脚本见 `tests/README.md`。
 
 ## 文档
 
 - [docs/README.md](docs/README.md) — 文档索引（新用户 / 运维 / 维护者三条阅读路径）
-- [快速开始](docs/guide/quickstart.md) · [安装、升级与迁移](docs/guide/install-upgrade-migration.md)
-- [工具参考](docs/reference/tools.md) · [配置参考](docs/reference/config.md) · [blocker 与失败码](docs/reference/blockers.md)
+- [中文文档](docs/zh/README.md) · [快速开始](docs/guide/quickstart.md) · [安装、升级与迁移](docs/guide/install-upgrade-migration.md)
+- [工具参考](docs/reference/tools.md) · [配置参考](docs/reference/config.md) · [blocker 与失败码](docs/reference/blockers.md) · [错误码](docs/reference/errors.md) · [事件](docs/reference/events.md) · [测试准入](docs/reference/testing.md) · [批次/租约/旧版](docs/reference/operations.md) · [Doctor](docs/reference/doctor.md) · [热重载](docs/guide/hot-reload.md)
 - [架构与状态机](docs/architecture/overview.md) · [运维 runbook](docs/operations/runbook.md) · [安全模型](docs/operations/security.md)
 - [FAQ](docs/faq.md) · [示例](docs/examples/first-mission.md)
 

package/cordis.patch.yml

@@ -2,7 +2,17 @@
     - id: tower
       name: 'dsh-tower'
       config:
-        allowAgentControl: true
+        mode:
+          allowAgentControl: true
+          workspaceLock: true
+          workspaceLockScope: all
+          planModePolicy: clear
+        init:
+          autoGitInit: true
+        send:
+          interruptDefault: true
+        spawn:
+          staleMs: 15000
     - id: tower-skills
       name: 'dsh-tower/skills'
     - id: preset-tower-worker

package/docs/README.md

@@ -1,13 +1,18 @@
 # dsh-tower documentation
 
+English is the source of truth; a Chinese translation lives in [zh/README.md](zh/README.md).
+
 Choose a path:
 
 | You are | Start here |
 |---|---|
-| New user | [Quick start](guide/quickstart.md) → [Tools](reference/tools.md) → [Example](examples/first-mission.md) |
-| Operator | [Runbook](operations/runbook.md) → [Blockers](reference/blockers.md) → [Security](operations/security.md) |
-| Maintainer | [Architecture](architecture/overview.md) → [Config](reference/config.md) → [Contributing](../CONTRIBUTING.md) |
+| New user | [When to use Tower](guide/scenarios-and-philosophy.md) → [Quick start](guide/quickstart.md) → [Tools](reference/tools.md) → [Example](examples/first-mission.md) |
+| Choosing a workflow | [When to use Tower, and how it differs from Agent Teams, Ralph, Workflow and parallel subagents](guide/scenarios-and-philosophy.md) |
+| Operator | [Runbook](operations/runbook.md) → [Blockers](reference/blockers.md) → [Error codes](reference/errors.md) → [Events](reference/events.md) → [Doctor](reference/doctor.md) → [Testing](reference/testing.md) → [Batches/leases/legacy](reference/operations.md) → [Security](operations/security.md) |
+| Maintainer | [Architecture](architecture/overview.md) → [Config](reference/config.md) → [Hot reload](guide/hot-reload.md) → [Contributing](../CONTRIBUTING.md) |
 
-Reference pages are the source of truth for the current release; the [tools reference](reference/tools.md) and [blocker list](reference/blockers.md) are checked by `npm run docs:check` in CI.
+Reference pages are the source of truth for the current release; the [tools reference](reference/tools.md),
+[blocker list](reference/blockers.md) and [error codes](reference/errors.md) are checked against the
+implementation by `npm run docs:check` in CI (including the Chinese pages).
 
-Other useful pages: [Install, upgrade and migration](guide/install-upgrade-migration.md), [FAQ](faq.md), [CHANGELOG](../CHANGELOG.md).
+Other useful pages: [When to use Tower](guide/scenarios-and-philosophy.md), [Install, upgrade and migration](guide/install-upgrade-migration.md), [Hot reload](guide/hot-reload.md), [FAQ](faq.md), [CHANGELOG](../CHANGELOG.md).

package/docs/architecture/overview.md

@@ -4,16 +4,20 @@
 
 ```
 Host plugin (index.js)
- ├─ /tower command + Tower mode (guard, prompt section, tower_control)
- ├─ lib/tools.js  -> 17 tools (+ tower_diff) registered on ctx.tools
- └─ lib/tower.js  -> Tower domain: missions, gates, worktrees, roster, review, merge
-       ├─ lib/git.js     minimal git port (execFile, bounded output, timeout classification)
-       ├─ lib/store.js   repo-scoped lock + atomic JSON + activity.jsonl
-       ├─ lib/config.js  Config schema + runtime snapshot
-       └─ lib/modeStore.js  per-agent Tower mode persistence
+ ├─ /tower command + Tower mode (guard, prompt section, tower_mode/tower_control, /tower reload)
+ ├─ lib/tools.js  -> 19 repository tools incl. tower_diff, tower_findings and tower_interrupt
+ │                   (+ tower_reload while dev.hotReload is on; fails reload-unavailable without HMR)
+ └─ lib/tower.js  -> Tower domain: missions, gates, worktrees, roster, review, findings, merge
+       ├─ lib/git.js          minimal git port (execFile, bounded output, timeout classification)
+       ├─ lib/store.js        repo-scoped lock + atomic JSON + activity.jsonl
+       ├─ lib/config.js       Config schema + profile/repo layers + runtime snapshot
+       ├─ lib/errors.js       stable tool error codes and classification
+       ├─ lib/workspaceLock.js  optional one-Tower-session-per-repository advisory lock
+       ├─ lib/hmr.js          optional DSH HMR bridge (tower_reload / /tower reload)
+       └─ lib/modeStore.js    per-agent Tower mode persistence
 Subagents
- ├─ tower-worker   (dsh-tower/worker)   read/write/edit/pwsh + mission tools
- └─ tower-reviewer (dsh-tower/reviewer) read/glob/grep + tower_diff + review/finding
+ ├─ tower-worker   (dsh-tower/worker)   read/write/edit/pwsh + mission tools + findings
+ └─ tower-reviewer (dsh-tower/reviewer) read/glob/grep + tower_diff + review/finding (read-only)
 ```
 
 The main checkout is the control-tower repo; each mission has a branch `tower/<id>-<slug>` and a

package/docs/faq.md

@@ -1,5 +1,17 @@
 # FAQ
 
+**When should I use Tower instead of Agent Teams, Ralph, Workflow, or ordinary subagents?**
+Use Tower when the output is a reviewed, integrated change to one Git repository. Use ordinary
+subagents for read-only exploration or quick independent subtasks, Agent Teams for cross-cutting human
+collaboration, Ralph for repeated fresh attempts at one objective, and Workflow for programmatic
+high-fan-out analysis. The full decision guide, scenarios, and comparison table are in
+[When to use Tower](guide/scenarios-and-philosophy.md).
+
+**Can I combine Tower with Team/Workflow/Ralph?**
+Not concurrently in the same session: Tower mode refuses their tools and clears plan mode. Compose by
+phase instead—use Workflow/Team to analyze and decide, then start Tower to execute and review the
+repository change. See the [full guide](guide/scenarios-and-philosophy.md#4-how-tower-differs-from-other-dsh-workflow-patterns).
+
 **Why did `tower_preflight` fail with `no-review` right after the worker finished?**
 That is expected: a completed mission awaits review. Spawn a reviewer; after a clean review the gate
 turns green.
@@ -28,12 +40,43 @@ instead of rebasing.
 No. Reviewers use the read-only `tower-reviewer` preset (no write/edit/pwsh); a branch changed after the
 reviewer spawned is rejected. Reviewers file `tower_finding` for issues outside the mission.
 
+**What is the difference between `tower_finding` and `tower_findings`?**
+`tower_finding` creates one finding (`open`). `tower_findings` is the lifecycle tool: list/read, and
+transition `open → triaged → fixed`/`wontfix` (reopen allowed). Only the tower or a worker may change the
+status; a roster reviewer may list and read.
+
+**How do I set config for one repository only?**
+Create `<git-common-dir>/dsh-tower/config.json` (usually `.git/dsh-tower/config.json`) with the same
+JSON groups as the profile config (`review`, `merge`, `worktrees`, `spawn`, and legacy aliases). The
+repository layer wins over the profile; per-call tool arguments win over both. No restart is required
+because the file is read when a Tower tool opens the repository.
+
 **Can workers use Tower tools to merge or spawn?**
 No. The worker preset contains mission/progress tools only; merge and spawn live in the parent tower.
 
+**A worker is stuck or runaway. How do I stop it?**
+Use `tower_interrupt({to:"worker-m1",reason:"..."})`; it calls the host subagent interrupt and records the
+roster entry as `interrupted`. If you already interrupted it and want a new owner, spawn with
+`takeover:true`. A still-running worker cannot be taken over (`takeover-refused`).
+
+**Two sessions want to drive the same repository.**
+Enable `mode.workspaceLock:true`: the first Tower session to call a repo-scoped tool owns
+`<git-common-dir>/dsh-tower/tower.lock`; other sessions get `[tower:workspace-busy]` until the owner
+runs `/tower off` or the lock is stale (`mode.workspaceStaleMs`).
+
+**Can I reload the plugin without restarting DSH?**
+Yes, in a profile with the DSH HMR service: `/tower reload` or the `tower_reload` tool reconciles the
+profile and replaces the changed linked package. Run `npm run dev:hmr` once to add the repository to the
+profile's HMR watch roots (then restart DSH once); see [hot reload](guide/hot-reload.md).
+`plugin_manager` install/update already applies live.
+
+**How do I make the completion evidence mandatory?**
+Workers can pass `checks` to `tower_complete`; set `gates.requireChecks:true` to block merging when a
+completed mission has no checks (`no-check-evidence`).
+
 **Where does Tower store state?**
-`<git-common-dir>/dsh-tower/state.json` and `activity.jsonl` in the target repo; mode state in
-`$DSH_HOME/tower-mode/modes.json`. Worktrees live next to the checkout in `.dsh-tower-worktrees/`.
+`<git-common-dir>/dsh-tower/state.json`, `activity.jsonl` and the human-readable `MISSIONS.md`; mode state
+in `$DSH_HOME/tower-mode/modes.json`. Worktrees live next to the checkout in `.dsh-tower-worktrees/`.
 
 **How do I change the review round cap or presets?**
 Use `review.maxRoundsPerReviewer` and `spawn.workerPreset`/`spawn.reviewerPreset`; see