dsh-tower 1.3.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+> 自 2.0.0 起，每个版本按 **新增 / 变更 / 修复** 三类组织；更早的版本保留原始流水式记录。
+
+## 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,14 @@ 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`.
 
 ## Requirements
 
@@ -105,14 +113,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 +132,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 +166,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,14 @@ 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。
 
 ## 环境要求
 
@@ -105,14 +113,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 +132,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 +164,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

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

package/docs/README.md

@@ -1,13 +1,17 @@
 # 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) |
+| 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: [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

@@ -28,12 +28,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

package/docs/guide/hot-reload.md

@@ -0,0 +1,189 @@
+# Hot reload (development)
+
+Tower is a Host plugin: its tools and prompt sections are loaded when DSH boots. DSH already ships
+`@deepseek-ai/dsh-hmr`, a service that **reconciles the profile in place** — it re-reads the profile
+patch layers, replaces modules whose files changed (including a linked package such as a `dsh-tower`
+checkout), restarts the affected Loader entries and reports anything that needs a full restart. Tower
+uses that service in development so Host-side changes apply without restarting DSH.
+
+This page covers the development loop. It is not required to use Tower.
+
+## What HMR does and does not do
+
+`dsh --profile <name> --dump-config` prints the composed hmr row:
+
+```yaml
+- id: hmr
+  name: '@deepseek-ai/dsh-hmr'
+  disabled: !!js '!ctx.get(''profileContext'')'
+  config:
+    root: []
+```
+
+- `root: []` is the shipped default: **no source files are watched**. HMR is mounted but idle for
+  file-watching, so a running DSH does not reload when you edit the checkout.
+- A reconciliation can still be requested explicitly (`/tower reload`, `tower_reload` or
+  `plugin_manager`); it compares already-loaded modules with disk and replaces the changed ones even
+  with `root: []`. Watching only makes that happen automatically after a save.
+- HMR is only mounted for profile boots (`disabled` when there is no `profileContext`). A process
+  booted without a profile reports reload as unavailable (`tower_reload` stays registered while
+  `dev.hotReload` is on, so the tool returns `reload-unavailable` instead of disappearing).
+- The profile patch layer is loaded when DSH boots. Editing it — in practice the hmr `root` list —
+  takes effect after **one DSH restart**. Nothing in the running process re-reads the HMR row's own
+  configuration.
+
+## Enable watching for a checkout
+
+From a checkout of this repository:
+
+```powershell
+npm run dev:hmr
+# equivalent to:
+node scripts/enable-dev-hmr.mjs
+```
+
+The script appends one marked block to the profile's user patch layer,
+`<DSH_HOME>/profiles/<profile>/cordis.patch.yml` (`DSH_HOME` defaults to `~/.dsh`; on Windows
+usually `C:\Users\<you>\.dsh`):
+
+```yaml
+# dsh-tower:dev-hmr
+- id: hmr
+  config:
+    root:
+      - 'D:/work/dsh-tower'
+```
+
+Options:
+
+| Flag | Meaning |
+|---|---|
+| `--profile <name>` | Profile to edit. Default `desktop` (the profile the desktop app boots). |
+| `--root <dir>` | Repository directory to watch. Default: the current working directory, canonicalised. |
+| `--dry-run` | Print a diff of the patch file and exit without writing. |
+| `--remove` | Delete the marked block again. |
+
+Notes:
+
+- The script is idempotent: re-running it replaces the marked block and leaves every other line of the
+  patch file untouched. Run it from the repository root, or pass `--root D:\work\dsh-tower`.
+- The value written is the `realpath` of the root, with forward slashes. **HMR `root` accepts
+  absolute paths**; relative entries would resolve against the profile directory and are easy to get
+  wrong, so the script always writes an absolute one.
+- The profile must already exist. The script never creates a profile and never creates directories
+  outside `<DSH_HOME>/profiles/<profile>/`.
+- Pick the profile the desktop app actually boots (`desktop` by default). The desktop profile is
+  managed by the Electron app, so restart it by quitting and relaunching DSH.
+
+**Restart DSH once** after writing the block. After that restart:
+
+- HMR watches the checkout (except `node_modules`, dot-directories, `cache` and `data`, which the
+  shipped `ignored` list excludes) and reconciles the profile after edits while DSH stays open.
+- `/tower reload` (and the `tower_reload` tool, when registered) reconciles on demand even for files
+  the watcher does not cover.
+
+To stop watching, run `npm run dev:hmr -- --remove` and restart DSH once.
+
+## The edit loop
+
+1. Edit `lib/*.js`, `index.js`, `worker.js`, `reviewer.js` or `skills.js`.
+2. Save the file. The watcher debounces (DSH default 100 ms) and reconciles the profile; changed
+   modules are replaced and the affected Loader entries restart.
+3. Watch the DSH log for `reload plugin at <path>` / `restart required: …` messages.
+4. Optionally call `/tower reload` or `tower_reload` to reconcile on demand instead of waiting.
+
+Editing the repository's bundle patch (`cordis.patch.yml`) changes the plugin declaration itself;
+restart DSH after such a change rather than assuming a hot replacement.
+
+The bridge behind the tool follows the `dev` config group:
+
+| Config key | Meaning |
+|---|---|
+| `dev.hotReload` | Register `tower_reload`; `/tower reload` is disabled when off (default `true`). Without the HMR service the tool is still registered so it can return `reload-unavailable`. |
+| `dev.reloadDelayMs` | Delay before the scheduled reconciliation runs, in milliseconds (default `50`), so the tool/command result reaches the model before the plugin is replaced. |
+| `dev.reloadRequiredIds` | Loader entry ids the profile must keep active (default `tower`, `tower-skills`, `preset-tower-worker`, `preset-tower-reviewer`). An inactive required entry is reported as a reload failure even if it was already inactive. |
+
+A reload is **scheduled, not awaited**: `/tower reload` and `tower_reload` return immediately with
+`scheduled`, `delayMs`, `requiredIds` (and the current `lastError` when one is pending), then HMR
+reconciles the profile after the delay. This is deliberate — the tool result must be delivered before
+the Tower plugin replaces itself. Two consequences:
+
+- a burst of reload requests inside the delay coalesces into a single reconciliation;
+- a reconciliation failure is recorded as `lastError` instead of coming back from the tool call, so
+  check `tower_mode.hotReload` and the DSH log after a reload.
+
+### Reading a reload result
+
+The outcome of the scheduled reconciliation surfaces in:
+
+- **the DSH log** — `reload plugin at <path>` for replaced modules, plus HMR's warnings and
+  `restart required: <reason>` messages from its own watcher.
+- **`tower_mode.hotReload`** — `{available, requiredIds, delayMs, scheduled, lastRunAt, lastError}`;
+  `lastError` keeps the most recent failure and is cleared by the next successful reload.
+
+The reconciliation itself also returns `warnings`, `pending` (modules still on their previous code)
+and an optional `restartReason`. When the reload was triggered from Tower those are not returned to
+the model, so treat "new code does not appear" as a signal to restart DSH rather than to retry in a
+loop.
+
+If HMR is absent, `/tower reload` answers with an unavailable message and `tower_reload` is not
+registered at all (both are gated on the HMR service at session start).
+
+## Plugin manager and linked packages
+
+`plugin_manager` actions (`install_bundle`, `set_plugin`, upgrades) apply to the running profile
+immediately — they reconcile the profile themselves, so installing or updating a bundle does not
+require a restart. This is the intended way to install `dsh-tower` while developing: add the checkout
+as a bundle (`dsh plugin --profile <profile> add <repo-root>` or `install_bundle`), then let HMR and
+the reload tool pick up code edits.
+
+With the checkout linked as a package target, a changed file inside the checkout is replaced by the
+next `reconcileProfile` or `plugin_manager` operation **without a restart**, even when `root: []`
+means the change was not watched. What does need a restart:
+
+- the hmr row's own configuration (`root`), because that list is read when the service activates;
+- modules reported under `pending` or with a `restartReason`.
+
+## Failure recovery
+
+| Symptom | What to do |
+|---|---|
+| `[tower:reload-unavailable]` / "Tower reload is unavailable" | This process has no HMR service (booted without a profile, HMR disabled in the profile, or the service was disposed during shutdown). Restart DSH. To inspect the hmr row, run `dsh --profile <name> --dump-config` on a non-desktop profile (the desktop profile is managed by the Electron app and refuses the dump). |
+| `[tower:reload-failed]` in `hotReload.lastError` with a syntax/import error | Fix the file, then restart DSH. A replacement that fails to import stops the previous plugin instance and its old code no longer runs; the reload itself cannot roll back. |
+| `HMR is disposed` | The service shut down with the process. Restart DSH. |
+| `HMR transactions cannot be nested` | An explicit reload was requested from inside another HMR transaction; call the tool from a normal tool turn instead. |
+| `pending` is non-empty or `restartReason` is set | Restart DSH before trusting the reload result. |
+| Edit saved but nothing reloads | Confirm the file is under the configured `root` (absolute path), is not excluded by `ignored` (`node_modules`, dot-directories, `cache`, `data`), and that the profile patch contains the marked block. Run `/tower reload` to reconcile manually. |
+| Reload keeps reporting an inactive required entry | That Loader entry is disabled or failing: check the profile's plugins/bundles (a `preset-tower-*` entry is missing when a Tower preset bundle was removed) and restart after fixing it. |
+
+The offline bridge tests are part of the normal suite:
+
+```powershell
+node --test tests/hmr.test.mjs
+```
+
+## Client bundles (`ui-bundle`) are different
+
+HMR replaces **Host** plugins and prompt/tool code. The optional `ui-bundle` is a Client widget: its
+JavaScript is downloaded and evaluated by the Web page, not by the Host process. After a Host reload
+or a Client bundle install/update, the open page may keep the old widget — refresh the Web page (and,
+if a tool schema changed, open a new session) before assuming the change failed. The Tower UI widget
+is a hint only and is not required for hot reload.
+
+For a live check of the reload path against an isolated profile, use
+[`tests/live/hmr.cjs`](../../tests/live/hmr.cjs) with `DSH_TEST_URL` set to the throwaway server URL
+(see [tests/README.md](../../tests/README.md)); it never touches the desktop profile or live sessions.
+
+## Security
+
+HMR executes the code it finds in the watched roots **inside the DSH Host process**, with your OS user
+privileges, and it reloads it on save. Treat the profile patch layer like shell startup files:
+
+- only point `root` at repositories you trust (this checkout), and keep the list small and absolute;
+- do not add your home directory, a downloads folder, or a shared/network path;
+- the patched profile is same-user trusted configuration; anyone who can write it can run code in
+  your DSH process;
+- remove the block (`--remove`) and restart once when you no longer need watching.
+
+See also: [install, upgrade and migration](install-upgrade-migration.md),
+[configuration reference](../reference/config.md), [error codes](../reference/errors.md).

package/docs/guide/install-upgrade-migration.md

@@ -29,6 +29,17 @@ The Host plugin loads at DSH startup: **restart DSH after install or update**.
 
 ## Migration notes
 
+- **1.x → 2.0 (unreleased)**: no state migration is needed (`schemaVersion` stays 1; new fields are
+  optional). Behavior changes to review: `mode.denyTools` now also denies `workflow`, `ralph`, `subagent`,
+  `subagent_fork`, `wait_agent` and `team_task_list` while Tower mode is active (override with an explicit
+  list); `spawn.maxLiveWorkers` defaults to 4; `mode.workspaceLock` is off by default. Workers can no
+  longer complete/abandon/scope a mission directly — use `tower_complete`. New tools: `tower_interrupt`,
+  and `tower_reload` when HMR is available. Restart DSH once after upgrading; see
+  [hot reload](hot-reload.md).
+- **1.3 → 1.4**: no state migration is needed. New: repository-level config
+  (`<git-common-dir>/dsh-tower/config.json`), stable `[tower:<code>]` tool errors, `tower_findings`,
+  and `id`/`missionId` + snake/camel input aliases. Existing calls keep working; restart DSH to load
+  the new tool surface (`tower_findings` and the newer output schemas).
 - **1.2 → 1.3**: reviewers moved from the shared `tower-worker` preset to the new read-only
   `tower-reviewer` preset. Reinstall/restart so both preset rows exist. `tower_spawn role=reviewer`
   now requires the mission to be `completed`.

package/docs/guide/quickstart.md

@@ -58,8 +58,40 @@ worktrees and branches.
 
 ## If something fails
 
-Read the blocker code and use [the blocker reference](reference/blockers.md). The most common cases:
+Read the blocker code and use [the blocker reference](../reference/blockers.md). The most common cases:
 `stale-base` (run `tower_rebase`), `no-review` (spawn a reviewer), `merge-hook-failed` (retry, or raise
 `timeoutMs`), `tip-moved` (the branch changed after review; review again).
 
+Thrown tool failures carry a `[tower:<code>]` prefix; see [error codes](../reference/errors.md)
+(e.g. `preset-missing` means restart DSH after installing the bundle, `not-initialized` means run
+`tower_init` first).
+
+## Optional: per-repository config
+
+A repository can tune review, merge, worktree and spawn policy without touching the DSH profile. Put a
+JSON file at `<git-common-dir>/dsh-tower/config.json` (usually `.git/dsh-tower/config.json`):
+
+```json
+{
+  "review": { "maxRoundsPerReviewer": 3 },
+  "merge": { "timeoutMs": 1800000 },
+  "worktrees": { "root": "D:/tower-worktrees" }
+}
+```
+
+The repository layer overrides the profile config; per-call tool arguments override both. See the
+[config reference](../reference/config.md) for the full table and precedence.
+
+## Optional: findings
+
+Out-of-scope observations go to `tower_finding`. Later, list or close them without editing code:
+
+```
+tower_findings repoRoot=D:\work\repo
+tower_findings repoRoot=D:\work\repo id=F1 status=fixed note="fixed in M2"
+```
+
+Statuses are `open → triaged → fixed` / `wontfix`, and `fixed`/`wontfix` can reopen to `open`. Only the
+tower or a worker may change a finding; reviewers can list and read.
+
 A complete copy-paste example: [examples/first-mission.md](../examples/first-mission.md).