dsh-tower 2.0.3 → 2.1.0-beta.1

package/README.md

@@ -2,6 +2,7 @@
 
 [![CI](https://github.com/louifinn/dsh-tower/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/louifinn/dsh-tower/actions/workflows/test.yml)
 [![npm](https://img.shields.io/npm/v/dsh-tower.svg)](https://www.npmjs.com/package/dsh-tower)
+[![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/louifinn/dsh-tower)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [English](README.en.md)
 
@@ -13,9 +14,9 @@ Tower 模式与 mission/审查工作流的灵感来自 Moonshot AI 的 **Kimi Co
 
 ## 特性
 
-- **由人类掌握的 Tower 模式。** `/tower` 切换会话级模式：收窄工具面并注入 Tower 协议；`/tower on|off <指令>` 还能把指令作为下一步用户消息转发给模型。
+- **可配置的 Tower 模式。** `/tower` 切换会话级模式：收窄工具面并注入 Tower 协议；`/tower on|off <指令>` 还能把指令作为下一步用户消息转发给模型。默认也允许 Agent 通过 `tower_control` 带理由进出；设 `mode.allowAgentControl:false` 可改为仅人类控制。
 - **任务级隔离。** 每个 mission 使用独立分支和 Git worktree，worker 不会碰到你的主检出。
-- **审查门禁合并。** 审查者针对当前分支 tip 给出 `clean` / `merge` 结论；合并门禁重新校验 scope、分支新鲜度、任务完成度、审查记录与 worktree 归属，通过后才执行 `--no-ff` 合并。独立审查默认可选，设 `review.requireReview:true` 可全局强制（仍可随时提交 review）。
+- **审查门禁合并。** 开启 `review.requireReview:true` 时，审查者针对当前分支 tip 给出 `clean` / `merge` 结论；合并门禁重新校验 scope、分支新鲜度、任务完成度、审查记录与 worktree 归属，通过后才执行 `--no-ff` 合并。独立审查默认可选（门禁关闭）；全局开启时，单个 mission 用 `reviewPolicy:"none"` + 理由并开启 `gates.allowReviewExemption:true` 做更窄豁免。
 - **可恢复的协作状态。** 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 只能读。
@@ -33,7 +34,7 @@ Tower 是**面向 Git 仓库变更的交付协议**，不是所有多代理场
 
 - 一个特性/重构能拆成 2–8 个 scope 清晰、可独立审查的 mission；
 - 有依赖顺序、需要分支新鲜度与 scope 约束的迁移；
-- 敏感仓库、发布绑定变更，或需要"被审查 commit + 测试证据 + 可审计合并"的工作；
+- 敏感仓库、发布绑定变更，或需要"可审计合并 + 测试证据"（需要时开启独立审查）的工作；
 - 跨上下文压缩、重启、多天协作，需要从本地状态恢复的工作；
 - 需要把"完成"定义成任务 + 测试（可选独立审查），而不是聊天里的一句"好了"。
 
@@ -51,7 +52,7 @@ Tower 模式会拒绝 Team/Workflow/Ralph/普通 subagent 工具并清除 plan m
 
 ## 环境要求
 
-- DeepSeek Harness `0.2.1-rc.2`（或兼容的新版本）
+- DeepSeek Harness `0.2.1-rc.2`（已验证的 host 构建见 [COMPATIBILITY.md](COMPATIBILITY.md)）
 - Node.js 22+
 - Git（worktree 在本地创建，不需要联网）
 
@@ -78,6 +79,16 @@ dsh plugin --profile <profile> add <本仓库的绝对路径>
 
 Host 插件在 DSH 进程启动时加载，**安装或更新后需重启 DSH**。卸载使用 `remove_bundle`，包名 `dsh-tower`。
 
+可选的 Web UI 随 npm 包一起发布在 `ui-bundle/`：npm 安装后目标为
+`<profile>/node_modules/dsh-tower/ui-bundle`，源码安装时为目标仓库的 `ui-bundle/` 目录。用
+`plugin_manager({action:"install_bundle", target:"<该目录>"})` 安装并重启 DSH，然后刷新页面。
+
+### 已知冲突
+
+不要同时安装 `dsh-plugins-tower`（第三方包）。它的 loader row 也使用 `name: dsh-tower`，会解析到
+本包，导致本包被加载两次或对方代码不生效。`tower_doctor` 的 `loader-conflicts` 检查会报告该情况；
+卸载冲突包并重启 DSH。
+
 ## 快速开始
 
 ```text
@@ -87,16 +98,17 @@ tower_init      repoRoot=D:\work\repo            # 首次初始化，记录 base
 tower_plan      repoRoot=D:\work\repo missions=[{"title":"Feature A","scope":["src/a/**"],"tasks":["implement","commit"],"kind":"build"}]
 tower_spawn     repoRoot=D:\work\repo missionId=M1 role=worker
 # worker 在 worktree 内实现并提交，调用 tower_complete；最终报告会返回本会话
+# 可选：需要强制独立审查时，先开启 review.requireReview:true
 tower_spawn     repoRoot=D:\work\repo missionId=M1 role=reviewer
 # reviewer 只读审查并调用 tower_review（clean+merge 或 p1-Nitems/p2-Nitems）
-tower_preflight repoRoot=D:\work\repo missionId=M1    # 审查前 预期 no-review；审查后应为 ok:true
+tower_preflight repoRoot=D:\work\repo missionId=M1    # 默认审查可选；开启 review.requireReview 时审查前预期 no-review，审查后 ok:true
 tower_merge     repoRoot=D:\work\repo missionId=M1
 tower_teardown  repoRoot=D:\work\repo
 
 /tower off
 ```
 
-小改动通常一轮 worker + 一轮 reviewer 即可完成。完整可复制示例见 [docs/examples/first-mission.md](docs/examples/first-mission.md)，逐工具参数见 [docs/reference/tools.md](docs/reference/tools.md)。
+小改动通常一轮 worker 即可完成；需要独立审查时再加一轮 reviewer。完整可复制示例见 [docs/examples/first-mission.md](docs/examples/first-mission.md)，逐工具参数见 [docs/reference/tools.md](docs/reference/tools.md)。
 
 ## 命令
 
@@ -107,10 +119,22 @@ tower_teardown  repoRoot=D:\work\repo
 | `/tower on <指令>` | 开启/保持，并把 `<指令>` 作为下一条用户消息转发 |
 | `/tower off` | 退出 Tower 模式 |
 | `/tower off <指令>` | 退出并转发 `<指令>` |
+| `/tower ack` | 记录人类确认，供 `mode.requireHumanAckOnFirstEntry` 使用 |
 | `/tower <指令>` | 确保开启，然后转发 `<指令>` |
 
 图片与文件附件会随指令一起作为一条完整的 `UserMessage` 转发。
 
+## 组件模型
+
+本 bundle 采用 **all-or-nothing**：`cordis.patch.yml` 只插入一个 `tower-bundle`
+`cordis:group` 行，Host 插件、skills、worker/reviewer preset 都是它的内部 section。插件页只应把
+这个 group 当作一个组件；关闭它时四个 section 一起关闭，不会留下指向已消失 `tower_*` 工具的
+orphan preset/skill。不要再把子行单独启停。
+
+进入 Tower 模式与 `tower_plan` 前会校验两个 preset 是否已注册；缺失时直接以 `preset-missing`
+拒绝（并在消息中点名 `preset-tower-worker` / `preset-tower-reviewer`），不会先完成规划/派发再在
+review/merge 阶段死锁。
+
 ## 配置
 
 ```yaml
@@ -124,6 +148,7 @@ tower_teardown  repoRoot=D:\work\repo
       autoPauseGoal: true
       denyTools: [create_goal, todo_write, team_task_create, team_task_update, team_task_reopen, spawn_teammate]
     review:
+      requireReview: false       # 默认审查可选；需要强制独立审查时改为 true
       maxRoundsPerReviewer: 5
     merge:
       timeoutMs: 900000
@@ -135,21 +160,21 @@ tower_teardown  repoRoot=D:\work\repo
       maxDepth: 1
 ```
 
-- 代码中 `mode.allowAgentControl` 默认 `false`；随包 `cordis.patch.yml` 设为 `true`：模型可在用户意图/任务状态明确时自行进出，但必须给出理由；设为 `false` 时只有人类能切换。随包 patch 还默认开启 `mode.workspaceLock`（单活塔）、`send.interruptDefault`、`init.autoGitInit`，并把 `spawn.staleMs` 设为 15s。
+- 代码中 `mode.allowAgentControl` 默认 `true`；随包 `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)。
 
-## 工具（26 个核心）
+## 工具（27 个核心）
 
-`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_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_recover` · `tower_test` · `tower_batch` · `tower_resource` · `tower_import_legacy` · `tower_legacy_map`
 
-`tower_control` 仅在 `allowAgentControl: true` 时注册；`tower_reload` 在 `dev.hotReload`（默认 true）时注册，无 HMR 服务调用会返回 `reload-unavailable`（因此最多 28 个工具）。mission 级工具同时接受 `id` 作为 `missionId` 的别名；`task_done`/`taskDone` 等 snake/camel 写法均可。
+`tower_control` 默认注册（`allowAgentControl:true`）；设为 `false` 可禁用；`tower_reload` 在 `dev.hotReload`（默认 true）时注册，无 HMR 服务调用会返回 `reload-unavailable`（因此最多 29 个工具）。mission 级工具同时接受 `id` 作为 `missionId` 的别名；`task_done`/`taskDone` 等 snake/camel 写法均可。
 
 ## 安全与约束
 
 - **门禁不全绿不合并。** `tower_preflight` 是只读检查，返回稳定的 blocker code；存在 blocker 时 `tower_merge` 拒绝合并。
-- **审查绑定提交。** 审查后分支 tip 变化会报 `tip-moved`，必须重新审查；reviewer 使用只读 preset，若在审查期间改动分支，提交审查会被拒绝。
+- **审查绑定提交。** 开启 `review.requireReview` 时，审查后分支 tip 变化会报 `tip-moved`，必须重新审查；reviewer 使用只读 preset，若在审查期间改动分支，提交审查会被拒绝。
 - **scope 强制。** mission 只能修改其 scope glob 匹配的文件，越界会以 `out-of-scope` 阻止合并。
 - **worktree 归属。** 脏工作树、运行中的 worker、已关闭 mission 的分支都会阻止合并或 teardown。
 - **goal 隔离。** 进入 Tower 模式会暂停活跃 goal 并记录；退出不会自动恢复，需要你自行恢复。
@@ -173,12 +198,12 @@ worker 与 reviewer 是使用内置 `tower-worker` preset 的普通 DSH 子代
 
 | 路径 | 内容 |
 |---|---|
-| `package.json`、`cordis.patch.yml` | bundle 清单与 loader patch（插入 Host 插件和 `tower-worker` preset） |
+| `package.json`、`cordis.patch.yml` | bundle 清单与 loader patch（单个 `tower-bundle` group，内含 Host、skills 与两个 preset） |
 | `index.js`、`lib/`、`worker.js` | Host 入口、协议实现、worker preset 策略 |
 | `locale/`、`icon.svg` | 本地化与图标 |
 | `tests/` | 纯函数、协议 e2e、插件级测试；可选的真实 Web 运行时脚本 |
 | `ui-bundle/` | 可选 Client 小挂件（Tower 工具卡片、Tower·on 状态 chip、模式感知的 disabled 行、dock 摘要、临时 overlay 状态条），默认不安装 |
-| `.github/workflows/test.yml` | CI：Node 22/24 上跑离线套件 |
+| `.github/workflows/test.yml` | CI：Node 22/24 离线套件、release 与覆盖率检查、Node 22 挂载 smoke 与种子失败 fixtures |
 
 ## 开发与测试
 
@@ -190,10 +215,26 @@ npm test        # node --test tests/*.test.mjs
 
 离线套件不需要 DSH 进程，只在系统临时目录创建一次性 Git 仓库。隔离 Web 运行时检查、模型驱动验收和会话诊断脚本见 `tests/README.md`。
 
+## CI 证明了什么
+
+每次 push 与 PR 都运行同一组 job；每个 job 对应一条可检查的声明，而不是一句 README 承诺。
+
+| Job | 声明 | 证据 |
+|---|---|---|
+| `test`（Node 22/24） | 离线套件、文档一致性、生成文档、发布文件清单、架构、类型与 domain 纯度全部成立 | `npm test`、`npm run docs:check`、三个 `docs:check:generated*`、`pack:check`、`architecture:check`、`types:check`、`domain:check` |
+| `test` 的 `Coverage (Node 22)` 步骤 | 覆盖率在 CI 中真实测量（只报告，不设阈值、不加徽章） | `npm run test:coverage` |
+| `test` 的 `Release check`（Node 22）步骤 | tag 是一种声明：版本已越过上一个版本 tag、推送的 tag 是 `v<version>`、CHANGELOG 带有发布内容 | `npm run release:check` |
+| `mount`（Node 22） | 打出的 tarball 经 plugin CLI 装进一次性 profile 后，真实 loader 挂载并注册了 bundle 声称的表面 | `npm run smoke:mount` |
+| `mount-fixtures`（Node 22，非必需检查） | mount smoke 仍会因正确的种子失败而变红（改名一个工具 id、删除 skills 段），三次运行共用一次缓存的 host 安装 | `npm run smoke:fixtures -- --host-dir <缓存的 host>` |
+
+`mount` 断言一次性 profile 的**已加载表面**，而不是 `cordis.patch.yml` 的文本：29 个 `tower_*` 工具（27 个 `tools/*.js` 模块 + `tower_mode` / `tower_control`）、3 个内置 skill、`tower-worker` / `tower-reviewer` 两个 preset、`/tower` 命令，以及唯一一个顶层 `tower-bundle` group 行（#66）。它不调用模型、不打开浏览器。在维护者的 Windows 机器上实测：host 冷装（含安装）约 100 秒，host 已缓存约 85 秒；CI 中该步骤上限为 3 分钟（`timeout-minutes: 3`），`mount` job 上限 5 分钟。红叉会打印解析后的 profile 路径、host build、已加载计数与每一条未满足的声明。
+
+host build 只固定在一个地方：`scripts/mount-smoke/host.json`，`COMPATIBILITY.md` 最新一行由单元测试强制与它一致，发布时不再各写一遍。`npm run smoke:fixtures` 用两种种子失败（改名一个工具 id、删除 skills 段）证明 smoke 会以正确原因变红；CI 中它作为非必需的 `mount-fixtures` job 运行，control 与两个种子通过 `--host-dir` 共用一次缓存的 host 安装（本机热跑约 2 分钟）。
+
 ## 文档
 
 - [docs/README.md](docs/README.md) — 文档索引（新用户 / 运维 / 维护者三条阅读路径）
-- [中文文档](docs/zh/README.md) · [快速开始](docs/guide/quickstart.md) · [安装、升级与迁移](docs/guide/install-upgrade-migration.md)
+- [中文文档](docs/zh/README.md) · [快速开始](docs/guide/quickstart.md) · [何时使用 Tower](docs/guide/scenarios-and-philosophy.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)
@@ -201,7 +242,7 @@ npm test        # node --test tests/*.test.mjs
 ## 常见问题
 
 - **安装/更新后插件不出现。** Host 插件在 DSH 启动时加载，请重启 DSH；并确认安装目标指向本仓库根目录（含 `package.json` 与 `cordis.patch.yml` 的那一层），而不是子目录。
-- **没有 `tower_control`。** 配置 `allowAgentControl` 为 `false`；改为 `true` 并重启。
+- **没有 `tower_control`。** 配置中被设为 `allowAgentControl:false`；改回 `true` 并重启。
 - **合并被阻止。** 运行 `tower_preflight` 查看 blocker code；`stale-base` 表示先执行 `tower_rebase`。
 - **基线前进后分支过期。** `tower_rebase` 在 worktree 内完成 rebase；干净且无冲突的 rebase 可免去上一轮审查的重审。
 - **合并提交已经存在，但 `tower_merge` 报了失败。** 重新执行 `tower_merge` 即可：它会检测已落地的合并提交（或分支已包含在 base 中）并记录为 reconciled，不会重复合并。
@@ -213,7 +254,7 @@ npm test        # node --test tests/*.test.mjs
 
 ## 致谢
 
-- **Kimi Code（Moonshot AI）**：Tower 模式的整体概念——由人类开启的模式、每个 mission 独立 Git worktree、审查门禁合并协议——灵感来自 Kimi Code 的实验性 Tower 模式（[官网](https://www.kimi.com/code)、[源码](https://github.com/MoonshotAI/kimi-code)）。本项目在 DeepSeek Harness 的服务之上重新实现这些想法，不包含 Kimi Code 源码，也与 Moonshot AI 无隶属关系。
+- **Kimi Code（Moonshot AI）**：Tower 模式的整体概念——明确的会话级模式开关、每个 mission 独立 Git worktree、审查门禁合并协议——灵感来自 Kimi Code 的实验性 Tower 模式（[官网](https://www.kimi.com/code)、[源码](https://github.com/MoonshotAI/kimi-code)）。本项目在 DeepSeek Harness 的服务之上重新实现这些想法，不包含 Kimi Code 源码，也与 Moonshot AI 无隶属关系。
 - **DeepSeek Harness**：本插件构建所依赖的插件、工具、会话与子代理 API。
 
 ## License

package/SECURITY.md

@@ -11,10 +11,40 @@ Areas that matter for security reports:
 - Command forwarding: injecting content into the model history that the user did not send.
 - Writes outside the declared scope, the mission worktree, or the DSH home directory.
 
+## Repository protection on `main`
+
+The repository's own landing path is part of the security surface, not separate from it: the merge
+gate, state lock, persistence and scope code decide whether a user's repository is modified, so a bad
+change there is exploitable for every repository that installs the plugin. `main` is therefore
+protected with:
+
+- a pull request required for every change, with **admins enforced** — a direct push is rejected even
+  for the maintainer;
+- required checks `test (22)`, `test (24)` and `mount` — the packed bundle must mount and register its
+  surface before a change can merge, and a red or missing check blocks the merge;
+- force-pushes and branch deletion blocked, so a released tag's history cannot be rewritten;
+- no mandatory approvals and no CODEOWNERS gate. With one maintainer, self-merge is the workflow;
+  what replaces the second approval is the four-line PR body for the two-key paths in
+  [CONTRIBUTING.md](CONTRIBUTING.md#landing-changes).
+
+Rationale, the enforcement boundary (server-side protection is not a plugin feature) and the list of
+what the setting does **not** buy are in
+[docs/operations/security.md](docs/operations/security.md#repository-protection). Verify the setting:
+
+```bash
+gh api repos/louifinn/dsh-tower/branches/main/protection \
+  --jq '{checks: .required_status_checks.contexts, strict: .required_status_checks.strict,
+         admins: .enforce_admins.enabled, force_push: .allow_force_pushes.enabled,
+         deletions: .allow_deletions.enabled, reviews: .required_pull_request_reviews}'
+```
+
 ## Reporting
 
 Please do **not** publish exploit details in a public issue. Open a minimal issue titled `security: request private contact` describing only the impact category (for example “merge gate bypass”), and a maintainer will arrange a private channel. Include the affected version and, if possible, a minimal reproduction in the private follow-up.
 
 ## Supported versions
 
-Security fixes target the latest released version (`1.x`). Older pre-release snapshots are not maintained.
+Security fixes target the latest released `2.x` line (currently `2.0.4`). Older pre-release snapshots
+are not maintained. Private reports are acknowledged in the minimal public issue and handled through
+the maintainer's private channel; do not attach exploit details, tokens, or production logs to a
+public issue.

package/adapters/default.js

@@ -0,0 +1,10 @@
+// Default composition root for Tower dependencies (#50).
+import * as store from '../lib/store.js'
+import * as vcs from '../lib/git.js'
+
+export const defaultDeps = {
+  store,
+  vcs,
+  clock: { now: () => Date.now() },
+  ids: { uuid: () => crypto.randomUUID() },
+}

package/adapters/store-fs.js

@@ -0,0 +1,6 @@
+// The only lib/ module that imports node:fs (#50).
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+
+const { createWriteStream } = fs
+export { fs, fsp, createWriteStream }

package/adapters/vcs-git.js

@@ -0,0 +1,4 @@
+// The only lib/ module that imports node:child_process (#50).
+import { execFile, spawn } from 'node:child_process'
+
+export { execFile, spawn }

package/app/batch.js

@@ -0,0 +1,79 @@
+// Batch use cases.
+import { TowerToolError } from '../domain/errors.js'
+import { withLock, writeJsonAtomic, appendJsonl } from '../lib/store.js'
+import { validateState } from '../domain/state.js'
+import { validateCreate as validateBatchCreate, validateClose as validateBatchClose } from '../domain/batch.js'
+import {
+  nextBatchId,
+  createBatchRecord,
+  closeBatchRecord,
+  abandonBatchCheck,
+  applyBatchAbandon,
+  batchStatusPayload,
+} from '../domain/collab/batch.js'
+
+function fail(message, code = 'batch-invalid') {
+  throw new TowerToolError(code, message)
+}
+
+export async function createBatch(tower, input = {}, actor = 'tower') {
+    return withLock(tower.paths, async () => {
+      const state = await tower.load()
+      const normalized = validateBatchCreate(state, input)
+      if (!Array.isArray(state.batches)) state.batches = []
+      const batch = createBatchRecord(nextBatchId(state.batches), normalized, actor, Date.now())
+      state.batches.push(batch)
+      state.revision += 1
+      state.updatedAt = batch.createdAt
+      validateState(state, tower.paths.state)
+      await writeJsonAtomic(tower.paths.state, state)
+      await appendJsonl(tower.paths.activity, {
+        at: batch.createdAt,
+        type: 'batch',
+        text: `created ${batch.id}: ${batch.missionIds.join(', ')}`,
+      })
+      return batch
+    })
+  }
+
+  export async function closeBatch(tower, batchId, options = {}, actor = 'tower') {
+    return withLock(tower.paths, async () => {
+      const state = await tower.load()
+      const batch = (state.batches ?? []).find((entry) => entry.id === batchId)
+      if (!batch) fail(`unknown batch "${batchId}"`)
+      const result = validateBatchClose(state, batch, { ...options, state })
+      const blockers = Array.isArray(result.blockers) ? result.blockers : []
+      if (blockers.length > 0) return { ok: false, batch, blockers, checks: result.checks ?? [] }
+      closeBatchRecord(batch, options, actor, Date.now())
+      state.revision += 1
+      state.updatedAt = batch.closedAt
+      validateState(state, tower.paths.state)
+      await writeJsonAtomic(tower.paths.state, state)
+      await appendJsonl(tower.paths.activity, { at: batch.closedAt, type: 'batch', text: `closed ${batch.id}` })
+      return { ok: true, batch, blockers: [], checks: result.checks ?? [] }
+    })
+  }
+
+  /** @param {string} batchId @param {string} [actor] @param {string | null} [reason] */
+  export async function abandonBatch(tower, batchId, actor = 'tower', reason = null) {
+    return withLock(tower.paths, async () => {
+      const state = await tower.load()
+      const batch = (state.batches ?? []).find((entry) => entry.id === batchId)
+      if (!batch) fail(`unknown batch "${batchId}"`)
+      const { alreadyAbandoned } = abandonBatchCheck(batch, batchId)
+      if (alreadyAbandoned) return { ok: true, batch, alreadyAbandoned: true }
+      const now = Date.now()
+      applyBatchAbandon({ batch, actor, reason, now })
+      state.revision += 1
+      state.updatedAt = batch.abandonedAt
+      validateState(state, tower.paths.state)
+      await writeJsonAtomic(tower.paths.state, state)
+      await appendJsonl(tower.paths.activity, { at: batch.abandonedAt, type: 'batch', text: `abandoned ${batch.id}` })
+      return { ok: true, batch, alreadyAbandoned: false }
+    })
+  }
+
+  export async function batchStatus(tower, batchId) {
+    const state = await tower.load()
+    return batchStatusPayload(state, batchId)
+  }

package/app/board.js

@@ -0,0 +1,25 @@
+// Mission board (MISSIONS.md) writing use cases.
+import path from 'node:path'
+import { fsp } from '../adapters/store-fs.js'
+import { renameWithRetry } from '../lib/store.js'
+
+export function boardFile(tower) {
+  return tower.config.docs?.boardLocation === 'repo'
+    ? path.join(tower.root, 'MISSIONS.md')
+    : path.join(tower.paths.dir, 'MISSIONS.md')
+}
+
+export async function writeBoard(tower) {
+  if (tower.config.docs?.board === false) return null
+  try {
+    const state = await tower.load()
+    const file = boardFile(tower)
+    await tower.ensureExcluded(file)
+    const tmp = `${file}.tmp-${process.pid}-${Date.now()}`
+    await fsp.writeFile(tmp, tower.boardMarkdown(state), 'utf8')
+    await renameWithRetry(tmp, file)
+    return file
+  } catch {
+    return null
+  }
+}

package/app/checkCompletion.js

@@ -0,0 +1,76 @@
+// Worker completion preparation and commit use cases.
+import { TowerToolError } from '../domain/errors.js'
+import {
+  normalizeChecks,
+  assertCompletionRequest,
+  assertCompletionInbox,
+  completionReport,
+} from '../domain/missions/completion.js'
+import { fullMission } from '../domain/summary.js'
+import { validateState } from '../domain/state.js'
+import { countCommits, isClean } from '../lib/git.js'
+import { withLock, writeJsonAtomic, appendJsonl } from '../lib/store.js'
+
+export { normalizeChecks }
+
+export async function checkCompletion(tower, input) {
+  const state = await tower.load()
+  const mission = state.missions.find((entry) => entry.id === input.missionId)
+  if (!mission) {
+    throw new TowerToolError('invalid-argument', `unknown mission "${input.missionId}"`)
+  }
+  const worker = assertCompletionRequest({ mission, roster: state.roster, input })
+  await tower.assertWorktree(mission.worktree)
+  const commits = await countCommits(mission.worktree.path, mission.worktree.baseCommit)
+  if (commits < 1) {
+    throw new TowerToolError(
+      'invalid-argument',
+      `mission branch has no commits since ${String(mission.worktree.baseCommit).slice(0, 12)}`,
+    )
+  }
+  if (!(await isClean(mission.worktree.path))) {
+    const dirty = (await tower.git(mission.worktree.path, ['status', '--porcelain']))
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => line.slice(3).trim())
+    throw new TowerToolError(
+      'worktree-dirty',
+      `mission ${mission.id} worktree has uncommitted changes (${dirty.slice(0, 8).join(', ')}${dirty.length > 8 ? ', …' : ''}); commit, remove, or record them before tower_complete`,
+    )
+  }
+  const unread = tower.unreadFor(state, worker.name)
+  assertCompletionInbox({ mission, worker, unread })
+  return { state, mission, worker, commits }
+}
+
+export async function complete(tower, input) {
+  // Two-phase pilot (#51): expensive git/state checks run before the lock;
+  // the lock only revalidates the state revision and commits the transition.
+  const prepared = await tower.checkCompletion(input)
+  return withLock(tower.paths, async () => {
+    const state = await tower.load()
+    if (state.revision !== prepared.state.revision) {
+      throw new TowerToolError('stale-base', 'tower state changed while completion was being prepared; retry')
+    }
+    const mission = state.missions.find((entry) => entry.id === input.missionId)
+    if (!mission) throw new TowerToolError('mission-not-found', `unknown mission "${input.missionId}"`)
+    const { worker, commits } = prepared
+    const checks = normalizeChecks(input.checks)
+    const now = Date.now()
+    mission.status = 'completed'
+    mission.completionReport = completionReport({ report: input.report, worker, checks, now })
+    mission.updatedAt = now
+    state.revision += 1
+    state.updatedAt = now
+
+    validateState(state, tower.paths.state)
+    await writeJsonAtomic(tower.paths.state, state)
+    await appendJsonl(tower.paths.activity, {
+      at: now,
+      type: 'complete',
+      missionId: mission.id,
+      text: `${worker.name} reported completion (${commits} commit(s))`,
+    })
+    return { mission: fullMission(mission), commits, unread: 0 }
+  })
+}

package/app/enrichedMissions.js

@@ -0,0 +1,26 @@
+// Dashboard mission enrichment use case.
+import { exists } from '../lib/store.js'
+import { revParse } from '../lib/git.js'
+import {
+  enrichedMissionView,
+  latestReviewForMission,
+  missionsToEnrich,
+} from '../domain/read/enrichedMissions.js'
+
+export async function enrichedMissions(tower, state, onlyIds) {
+  const out = []
+  for (const mission of missionsToEnrich(state.missions, onlyIds)) {
+    const latest = latestReviewForMission(state, mission)
+    let tipMoved = false
+    if (latest && mission.worktree && (await exists(mission.worktree.path))) {
+      try {
+        const tip = await revParse(mission.worktree.path, 'HEAD')
+        tipMoved = tip !== latest.reviewedCommit
+      } catch {
+        tipMoved = false
+      }
+    }
+    out.push(enrichedMissionView({ mission, latest, tipMoved }))
+  }
+  return out
+}

package/app/findings.js

@@ -0,0 +1,78 @@
+// Findings use cases.
+import { withLock, writeJsonAtomic, appendJsonl } from '../lib/store.js'
+import { validateState } from '../domain/state.js'
+import { TowerToolError } from '../domain/errors.js'
+import {
+  normalizeFindingInput,
+  newFinding,
+  normalizeFindingActor,
+  wantsFindingUpdate,
+  readFindingsView,
+  applyFindingUpdate,
+  findingUpdateView,
+} from '../domain/missions/findings.js'
+
+function fail(message, code = 'invalid-argument') {
+  throw new TowerToolError(code, message)
+}
+
+export async function addFinding(tower, input) {
+    return withLock(tower.paths, async () => {
+      const state = await tower.load()
+      if (!Array.isArray(state.findings)) state.findings = []
+      const fields = normalizeFindingInput(input, state.missions)
+      const now = Date.now()
+      const seq = (state.findingSeq ?? 0) + 1
+      state.findingSeq = seq
+      const finding = newFinding(fields, { seq, now, reportedBy: input.reportedBy })
+      state.findings.push(finding)
+      state.revision += 1
+      state.updatedAt = now
+
+      validateState(state, tower.paths.state)
+      await writeJsonAtomic(tower.paths.state, state)
+      await appendJsonl(tower.paths.activity, {
+        at: now,
+        type: 'finding',
+        missionId: finding.missionId,
+        text: `${finding.id} ${finding.type}: ${finding.title}`,
+      })
+      return finding
+    })
+  }
+
+  /** List or read findings. Read-only paths never take the writer lock. */
+  export async function readFindings(tower, input = {}) {
+    const state = await tower.load()
+    return readFindingsView(state.findings ?? [], input)
+  }
+
+  /**
+   * List, read, or transition findings. Listing and reading are lock-free;
+   * only a transition takes the writer lock. Reviewers may only read.
+   */
+  export async function findings(tower, input = {}) {
+    const actor = normalizeFindingActor(input.actor)
+    if (!wantsFindingUpdate(input)) return tower.readFindings(input)
+
+    return withLock(tower.paths, async () => {
+      const state = await tower.load()
+      const all = state.findings ?? []
+      const finding = all.find((entry) => entry.id === input.id)
+      if (!finding) fail(`unknown finding "${input.id}"`, 'finding-not-found')
+      const now = Date.now()
+      const { noteAdded } = applyFindingUpdate({ finding, input, actor, now })
+      state.revision += 1
+      state.updatedAt = now
+      validateState(state, tower.paths.state)
+      await writeJsonAtomic(tower.paths.state, state)
+      await appendJsonl(tower.paths.activity, {
+        at: now,
+        type: 'finding',
+        missionId: finding.missionId,
+        text: `${finding.id} ${finding.status}${noteAdded ? ' +note' : ''} (${actor.name})`,
+      })
+      // Counts must reflect the transition just recorded.
+      return findingUpdateView(finding, all)
+    })
+  }