dsh-tower 2.0.4 → 2.1.0-beta.1

package/docs/reference/tools.generated.md

@@ -0,0 +1,33 @@
+# Tools overview (generated)
+
+> Generated by `npm run docs:generate:tools` from the registered tool definitions. Do not edit by hand.
+
+| Tool | Description |
+|---|---|
+| `tower_adopt` | Reconcile the roster with the durable subagent catalog after a restart or new session. Agents that are provably gone are marked retired (records are kept) or missing (retireMissing:false, so the tower can inspect/take over); agents whose parent catalog cannot be read stay unknown and are never changed. Only the tower may adopt. |
+| `tower_batch` | Manage finite evidence batches: create freezes missionIds/requiredChecks/receiptPaths, status summarizes members, close verifies every required check and receipt hash, abandon retires a stale open batch. Membership and exclusions are immutable after create; close/abandon never remove missions. |
+| `tower_complete` | Worker-only: report mission completion. Enforced by the store: every task done or dropped, no blockers, the current owner, the mission branch has at least one commit since its spawn base, and no unread inbox messages. checks records verifiable evidence (name/command/exitCode/evidence); gates.requireChecks can require at least one before merge. Stores the full report; completion means ready for preflight and optional review, not merged. |
+| `tower_diff` | Read-only view of a mission branch for review: merge base, changed files, commits, and a capped patch against the recorded base. Safe for reviewers; it never modifies the repository. |
+| `tower_doctor` | Read-only environment and repository health check: git, state schema, config, presets/subagents/HMR, workspace lock, roster staleness, worktree ownership, test discovery, leases. Returns checks with pass/warn/fail and an environment contract. Never writes state. |
+| `tower_finding` | File a structured finding (bug / improve / vuln / idea) for the tower to route. Use this for anything notable OUTSIDE your mission scope instead of editing out-of-scope files. Severity is one of low|medium|high|critical. Use tower_findings to list, read, or close findings later. |
+| `tower_findings` | List, read, or update findings for a repository. Without id it lists findings newest-first with counts by status (filters: status, type, severity, missionId, open, limit). With id it returns that finding; with id plus status and/or note it records a lifecycle transition. Statuses are open -> triaged -> fixed|wontfix, and fixed/wontfix can be reopened to open. Only the tower or a worker may change a finding; reviewers may only list and read. Read-only when no id is given. |
+| `tower_import_legacy` | Read-only import of a Tower Codex (schemaVersion 1) or DSH legacy state file. Stores the full payload under <common>/dsh-tower/legacy/<sha256>.json and records only a summary in state.legacySnapshots; never activates, adopts, or resumes paused missions. |
+| `tower_inbox` | Read your tower inbox: messages addressed to you plus broadcasts, newest first. Only returned messages are acknowledged; the result reports unreadRemaining, so keep reading until it reaches 0. Set include_read for history. Unread messages block tower_complete. |
+| `tower_init` | Initialize Tower mission state for a repository (absolute repoRoot). Creates <git-common-dir>/dsh-tower/state.json and an activity log; idempotent on an existing workspace. Options: autoGitInit (git init + empty initial commit when the directory is not a repository), snapshotDirty (snapshot uncommitted work into a dangling commit used as the mission baseline), reanchor (change base when every mission is merged/abandoned). Only the tower may initialize. |
+| `tower_interrupt` | Interrupt one running tower roster agent (worker or reviewer) and record it as interrupted in the roster. Only the tower may interrupt. Idempotent: an agent that is not running returns interrupted:false. Use it before takeover after a runaway worker, or to stop work that is no longer wanted. |
+| `tower_legacy_map` | Audit-only mapping between a legacy snapshot id and a current mission. map records sourceHash/oldId/newMissionId; status lists mappings. Mapping never adopts or resumes a legacy mission. |
+| `tower_merge` | Merge a mission branch into the recorded base branch with --no-ff, after the hard gate passes. Verifies the two merge parents and records the mission as merged. If the merge commit already landed (manual merge, crashed or slow pre-merge hook), it detects the merge commit and records it as reconciled instead of merging again. A failed gate returns stable blocker codes without merging; a hook failure aborts cleanly and returns "merge-hook-failed" while a real content conflict returns "merge-conflict". |
+| `tower_mission` | Update one mission: lifecycle status, decision note, blocker, clear blockers, mark a task done, drop a task with a reason, or widen the scope (tower only). "merged" is never set here; only a future tower_merge records it. Merged and abandoned are terminal. |
+| `tower_plan` | Plan one or more missions in an initialized repository. Each mission has a printable-ASCII title, relative scope globs, optional task checklist, optional mission-id dependencies, and kind build|survey. Assigns M1.. ids and auto-adds a dependency when build scopes overlap (serializes merges); rejects dependency cycles. |
+| `tower_preflight` | Read-only merge gate for one mission: returns ok plus stable blocker codes (branch-missing, deps-unmerged, read-only-survey, stale-base, out-of-scope, base-dirty, branch-owned-by-closed-missions, and mission/worker guards). Review blockers (no-review, review-hold, not-clean, review-not-approved, tip-moved, review-mission-mismatch) apply only when review.requireReview is on. Never changes anything. |
+| `tower_rebase` | Rebase a mission branch onto the current base tip inside its own worktree. Refuses while its worker is running or the worktree is dirty. A clean conflict-free rebase waives re-review for the old review; a conflict is aborted and the mission is marked blocked. If the branch is already contained in the base, it returns alreadyMerged and leaves the branch untouched so tower_merge can record the landed merge. |
+| `tower_recover` | Read-only recovery diagnostics and an explicit stale-state-lock repair. status reports the state lock owner; clear-stale-lock requires confirm:"CLEAR_STALE_LOCK" and only moves a lock whose PID is provably dead to a backup file. It never resets Tower state or worktrees. |
+| `tower_reload` | Dev-only: ask DSH HMR to reconcile this profile and reload the Tower Host plugin from disk. The reload is scheduled a few milliseconds after this call returns (so the result reaches the model first). Use after editing the plugin source in a linked profile; plugin_manager install/update already triggers reconciliation by itself. Registered while dev.hotReload is on; fails with reload-unavailable when the HMR service is absent. |
+| `tower_resource` | Advisory resource leases per repository (coordination only; no OS CPU/memory hard cap). acquire/release require a token and are tower-only; status is read-only. Expired leases are never taken over silently. |
+| `tower_review` | Submit an independent review verdict for a completed mission, bound to the current branch tip. status is "clean", "p1-Nitems", or "p2-Nitems"; merge is "merge", "fix-then-merge", or "hold" (only clean + merge is later approval). Non-clean returns the mission to active. Reviewers are capped at 5 rounds per branch; a tower-submitted review is break-glass and requires breakGlassReason. |
+| `tower_roster` | List tower roster agents with authoritative live activity from the subagent catalog (running/inactive/missing/unknown). Read-only; never resumes children. Use before completion or merge decisions. |
+| `tower_send` | Send a durable inbox message to a tower participant: a roster agent name, "tower", or "all" (broadcast). The message is persisted first; when the recipient is a currently running roster agent the tower also steers it into that child's current turn. Returns delivery results. |
+| `tower_spawn` | Spawn a worker or reviewer for a mission. Workers use the tower-worker preset; reviewers require a completed mission and use the read-only tower-reviewer preset. Provisions (or reuses) the mission git worktree and branch, generates a self-contained briefing, and starts a background subagent in that worktree. The child final report is delivered back to this session; tower_roster shows authoritative activity. Records the agent in the roster; reviewer spawns record the branch tip so a reviewer that modifies the branch cannot submit a review. Returns immediately unless wait=true. |
+| `tower_status` | Read the Tower dashboard for a repository: state path, base branch, revision, mission status counts, paged mission summaries (scope/deps/tasks/worktree/owner), roster size, findings, config path and the activity tail. Pass missionId for one full mission (tasks, notes, reviews, findings, completion report); offset/limit page the mission list (default 20, max 100); includeGate adds preflight gate digests for the page; format:"markdown" returns the human-readable mission board. Read-only. |
+| `tower_teardown` | Tear down eligible mission worktrees after their missions are merged or abandoned. A worktree whose roster agent is running is always kept (force cannot override); dirty worktrees need force; exclude keeps named missions. dry_run previews the remove/keep decisions without changing anything. |
+| `tower_test` | Run the mission worktree's declared tower.testDiscovery (package.json) and record the receipt. Returns ok:false with diagnostics when discovery fails; does not change mission status. Use tower_complete for automatic admission checks. |

package/docs/reference/tools.md

@@ -33,7 +33,7 @@ findings but not mutate them. Violations throw `[tower:not-authorized]` or
 | `tower_init` | `base?`, `autoGitInit?`, `snapshotDirty?`, `reanchor?` | Create `<git-common-dir>/dsh-tower/state.json`. `autoGitInit` runs `git init` + empty initial commit; `snapshotDirty` records a dangling snapshot commit of uncommitted tracked changes used as the mission baseline; `reanchor` changes base only when no non-terminal mission exists. Returns `dirty`, `snapshotCommit`, `reanchored`. |
 | `tower_plan` | `missions[]` (`title`, `scope[]`, `tasks[]?`, `deps[]?`, `kind?`, `context?`, `references[]?` ≤20, `reviewPolicy?`, `reviewExemptionReason?`) | Create missions `M1..`; overlapping build scopes auto-add a dependency; rejects unknown deps and cycles. `reviewPolicy:"none"` requires a non-empty reason; when the review gate is on, preflight also requires `gates.allowReviewExemption`. |
 | `tower_mission` | `id` (alias `missionId`), `status?`, `task_done?`, `task_drop?`+`task_drop_reason?`, `blocker?`, `clear_blockers?`, `note?`, `scope?`, `pause_cause?`, `authorization?` | Update one mission. Worker-safe fields are task/blocker/note; `merged` cannot be set here. Paused missions record `pause_cause` (user/failure/resource/dependency); resuming a user-paused mission honors `mode.requireResumeAuthorization`. |
-| `tower_status` | `missionId?`, `offset?`, `limit?`, `includeGate?`, `format?` | Dashboard by default. `missionId` returns full detail (tasks/notes/reviews/findings/completionReport). `offset`/`limit` page missions (default 20, max 100), `includeGate` adds gate digests, `format:"markdown"` returns the board. |
+| `tower_status` | `missionId?`, `offset?`, `limit?`, `includeGate?`, `format?` | Dashboard by default. `missionId` returns full detail (tasks/notes/reviews/findings/completionReport). `offset`/`limit` page missions (default 20, max 100), `includeGate` adds gate digests, `format:"markdown"` returns the board. Includes `mode` with `lastChange` and recent `history` when the host mode hook is available. |
 | `tower_spawn` | `missionId` (alias `id`), `role` (`worker`/`reviewer`), `name?`, `instructions?`, `worktreeRoot?`, `wait?`, `waitMs?`, `takeover?`, `includeDirtyBase?` | Provision/reuse the worktree and start a subagent. Worker uses `tower-worker`; reviewer requires a `completed` mission and uses the read-only `tower-reviewer`. `takeover:true` replaces a live worker entry that is no longer running (increments ownerGeneration). Only one live worker per mission; `spawn.maxLiveWorkers` caps the repository. |
 | `tower_roster` | — | Roster with live activity (`running`/`inactive`/`missing`/`unknown`) and `stale` flags from the subagent catalog. Read-only. |
 | `tower_adopt` | `retireMissing?` | Reconcile roster entries with the durable subagent catalog. Provably gone agents are retired (default) or marked `missing` (`retireMissing:false`) so they can be inspected/taken over. |

package/docs/zh/README.md

@@ -29,7 +29,7 @@
 | 新用户 | [什么时候用 Tower](guide/scenarios-and-philosophy.md) → [快速开始](guide/quickstart.md) → [工具参考](reference/tools.md) → [第一个 mission 示例（英文）](../examples/first-mission.md) |
 | 正在选择工作流 | [Tower 与 Agent Teams、Ralph、Workflow、普通并行子代理的区别](guide/scenarios-and-philosophy.md) |
 | 运维 | [运维 runbook（英文）](../operations/runbook.md) → [blocker 与失败码](reference/blockers.md) → [错误码](reference/errors.md) → [事件](reference/events.md) → [Doctor](reference/doctor.md) → [测试](reference/testing.md) → [批次/租约/旧版](reference/operations.md) → [安全模型](operations/security.md) |
-| 维护者 | [架构与状态机（英文）](../architecture/overview.md) → [配置参考](reference/config.md) → [热重载](guide/hot-reload.md) → [贡献指南](../../CONTRIBUTING.md) |
+| 维护者 | [架构与状态机（英文）](../architecture/overview.md) → [配置参考](reference/config.md) → [热重载](guide/hot-reload.md) → [发布检查清单（英文）](../guide/release.md) → [看板查询（英文）](../board.md) → [贡献指南](../../CONTRIBUTING.md) |
 
 参考页是当前发行版的权威说明；CI 中的 `npm run docs:check` 会校验文档与实现一致（包括中文页）。
 
@@ -51,7 +51,8 @@
 - [安全模型](operations/security.md)
 
 以下页面目前只有英文版：[架构与状态机](../architecture/overview.md)、
-[运维 runbook](../operations/runbook.md)、[示例：第一个 mission](../examples/first-mission.md)。
+[运维 runbook](../operations/runbook.md)、[示例：第一个 mission](../examples/first-mission.md)、
+[发布检查清单](../guide/release.md)、[看板查询](../board.md)。
 
 ## 语言 / Language
 

package/docs/zh/guide/hot-reload.md

@@ -97,7 +97,7 @@ Windows 上通常是 `C:\Users\<you>\.dsh`）：
 |---|---|
 | `dev.hotReload` | 注册 `tower_reload`；关闭时 `/tower reload` 也被禁用（默认 `true`）。无 HMR 服务时工具仍注册，以便返回 `reload-unavailable`。 |
 | `dev.reloadDelayMs` | 计划中的对账运行前的延迟，单位毫秒（默认 `50`），让工具/命令结果先送达模型，再替换插件。 |
-| `dev.reloadRequiredIds` | profile 必须保持活跃的 Loader 条目 id（默认 `tower`、`tower-skills`、`preset-tower-worker`、`preset-tower-reviewer`）。即使某个 required 条目早已处于非活跃状态，也会被报告为重载失败。 |
+| `dev.reloadRequiredIds` | profile 必须保持活跃的 Loader 条目 id（默认 `tower-bundle`、`tower`、`tower-skills`、`preset-tower-worker`、`preset-tower-reviewer`）。即使某个 required 条目早已处于非活跃状态，也会被报告为重载失败。 |
 
 重载是**调度而非等待**：`/tower reload` 与 `tower_reload` 立即返回 `scheduled`、`delayMs`、
 `requiredIds`（以及存在待处理错误时的 `lastError`），随后 HMR 在延迟后对账 profile。这是有意为之——

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

@@ -4,7 +4,7 @@
 
 ## 环境要求
 
-- DSH `0.2.1-rc.2` 或更新版本
+- DSH `0.2.1-rc.2`；每个版本实际验证过的 host 构建见 [COMPATIBILITY.md](../../../COMPATIBILITY.md)
 - Node.js 22+
 - Git（本地 worktree；不需要网络访问）
 
@@ -31,6 +31,11 @@ Host 插件在 DSH 启动时加载：**安装或更新后需要重启 DSH**。
 
 ## 迁移说明
 
+- **2.0.4 → 2.1.0-beta.1**：不需要迁移 state/config。这是发布到 `next` dist-tag 的**预发布**，
+  `latest` 仍指向 2.0.4——请用 `dsh plugin --profile web add dsh-tower@next`（或精确版本号）安装。
+  运行时行为未变；本版本承载的是交付闸门（CI 中的 mount smoke、`npm run release:check`、证据约定
+  与追踪策略），而不是工具变化。本文档先于人工发布步骤合入：只有在[发布清单](release.md)执行
+  `npm publish --tag next` 之后，`next` 才会解析到 2.1.0-beta.1；`latest` 在稳定版发布前保持 2.0.4。
 - **2.0.3 → 2.0.4**：不需要迁移 state/config。本版本是安全加固与完整性修复（授权、merge SHA 绑定、
   dirty worktree 完成拒绝、stale lock 恢复、限制 test/git 进程环境、`tower_recover`、UI 0.2.2）。
   升级后请按威胁模型重新检查 `review.requireReview`、`tests.admission` 与 worker 工具权限。

package/docs/zh/operations/security.md

@@ -26,6 +26,35 @@ Tower 提供的是**协作层面的保证**，不是沙箱。需要理解哪些
 - **建议性 workspace 锁。** `mode.workspaceLock` 防止两个 Tower 会话意外驱动同一个仓库；它是同用户
   之间的协调锁，不是用户间的认证机制。
 
+## 仓库保护
+
+本节描述的是**本仓库**，不是 Tower 所操作的仓库。服务端分支保护不是插件功能——Tower 只写入本地基线分支，无法配置远端——但 `dsh-tower` 为自己的 `main` 开启了保护，因为门禁代码本身也是攻击者最想修改的代码：
+
+- `main` 的所有变更都必须经过 pull request，且**对 admin 同样生效**，因此维护者也无法直接 push。
+- 必需检查为 `test (22)`、`test (24)` 与 `mount`。mount 任务会打包压缩包并在一次性 profile 中启动，所以“测试通过”不能把一个安装后不出现的 bundle 合入。
+- 禁止 force-push 与删除分支，已发布 tag 的历史不能被改写。
+- 不要求强制审批：只有一个维护者时，自我审批只是橡皮图章。替代它的是 two-key 路径的四行 PR 正文（failure mode、change、test、blast radius），见 [CONTRIBUTING.md](../../../CONTRIBUTING.md#landing-changes)。
+
+它带来的保证：未经验证的变更无法进入 `main`，必需检查变红或缺失时连所有者也不能绕过，历史只追加。它**不**提供：第二个审阅者、对泄露的维护者 token 的防护，或对 Tower 所操作仓库的任何保护——那些仍是部署关注点。设置、理由与校验命令记录在 [SECURITY.md](../../../SECURITY.md#repository-protection-on-main)。
+
+## 模型主动进入模式的威胁模型
+
+`mode.allowAgentControl:true` 意味着仓库文件、issue 文本或抓取页面中的提示注入可以让模型“进入
+Tower 模式并修复它”。Tower **不认证**这句话背后的人类意图。它提供的是：
+
+- 进入会记录操作者、动作、理由与时间；`tower_status.mode.history` 直接展示最近的模式切换，
+  不必手工 grep 活动日志；
+- 模型不能绕过 preflight 门禁、review policy、scope、测试与 clean-base 检查；自己写 plan 也不会
+  自动获得合并权；
+- worker 的工具面受限并被要求留在 worktree，但主检出保护来自 scope/merge 检查与 preset，
+  **不是** OS 沙箱；
+- `mode.workspaceLock` 防止第二个 Tower 会话驱动同一仓库。
+
+它**不**防御：完全通过所有门禁但被恶意指令操纵的模型；仓库自己声明的 hooks/测试命令；或无视
+指令、通过 shell 访问 worktree 之外文件的 worker。更高保证的团队应设
+`mode.allowAgentControl:false`、保持 `review.requireReview:true`、在运行 Tower 前审查仓库，并用
+OS 级隔离运行 host。
+
 ## 不由插件强制执行的约束（部署关注点）
 
 - **Worktree 隔离是协议约定，不是 OS 沙箱。** worker 会被分配独立 worktree/分支并被要求留在其中，但
@@ -45,7 +74,7 @@ Tower 提供的是**协作层面的保证**，不是沙箱。需要理解哪些
   插件。只为你信任的检出配置 HMR 监视 root；重载会执行这些文件当前的代码。
 - **提示注入。** reviewer 会读取不受信任的分支内容（diff/评论）。只读 preset 限制了影响面，但模型侧
   没有绝对防护。
-- **基线分支保护。** Tower 会写入本地基线分支；服务端的 branch protection/push 规则不属于本插件。
+- **基线分支保护。** Tower 会写入本地基线分支；服务端 branch protection/push 规则不属于本插件。本仓库自身 `main` 的保护见[仓库保护](#仓库保护)；为你运行 Tower 的仓库开启同等保护仍属于部署关注点。
 
 ## 报告问题
 

package/docs/zh/reference/config.md

@@ -40,11 +40,13 @@ merge、worktree 与 spawn 策略。它使用与 profile 配置相同的 JSON
 | `allowAgentControl` | `true`（`mode.allowAgentControl` 的别名） | 兼容别名：注册 `tower_control`，允许模型切换模式。 |
 | `init.autoGitInit` | `false`（随包 patch：`true`） | 当 `repoRoot` 是绝对、已存在但不是仓库的目录时，`tower_init` 可以执行 `git init` 并创建一个空的初始提交。 |
 | `init.snapshotDirty` | `false` | `tower_init` 可以把未提交的**已跟踪**改动快照为游离提交作为 mission 基线（不含未跟踪文件；该提交通过 `refs/tower/snapshot/*` 保持存活）。 |
+| `init.autoExclude` | `true` | 把仓库内产物（`MISSIONS.md`、仓库内 worktree root）追加到 `.git/info/exclude`；绝不修改 `.gitignore`。 |
 | `mode.promptSection` | `''` | 替换用的提示文案（与 `section` 同时设置时优先）。 |
 | `mode.sectionAppend` | `''` | 追加在提醒之后的额外文本（团队约定）。 |
 | `mode.allowAgentControl` | `true` | 注册 `tower_control`；模型可带理由进入/退出。设为 `false` 则仅人类可控制模式。 |
 | `mode.autoPauseGoal` | `true` | 进入模式时暂停活跃 goal；退出时不会自动恢复。 |
 | `mode.requireResumeAuthorization` | `false` | 恢复因 `pauseCause:user` 暂停的 mission 时，必须提供 `authorization` 引用。 |
+| `mode.requireHumanAckOnFirstEntry` | `false` | 要求人类先执行 `/tower ack`，模型才能在当前会话首次进入 Tower 模式。 |
 | `mode.workspaceLock` | `false`（随包 patch：`true`） | 每个仓库只允许一个 Tower 会话（`tower.lock`）；其他会话得到 `workspace-busy`。 |
 | `mode.workspaceLockScope` | `all` | `all` 锁定所有仓库工具；`mutations` 对只读工具跳过 workspace 锁。 |
 | `mode.planModePolicy` | `clear` | 进入 Tower 模式会清除活跃的 plan mode（或 `refuse` 直到退出计划）；前置步骤也会清除稍后激活的计划。 |
@@ -82,10 +84,11 @@ merge、worktree 与 spawn 策略。它使用与 profile 配置相同的 JSON
 | `gates.allowReviewExemption` | `false` | 在 `review.requireReview:true` 时，允许用 `reviewPolicy:"none"` + 非空理由跳过审查 blocker；默认故意关闭；全局审查关闭时无影响。 |
 | `docs.board` | `true` | 变更后写入 `MISSIONS.md`。 |
 | `docs.boardLocation` | `common` | `common` = `<git-common-dir>/dsh-tower/MISSIONS.md`；`repo` = `<repoRoot>/MISSIONS.md`。 |
+| `tools.exposeOperational` | `true` | 注册 batch/resource/import/legacy/recover/test/doctor 工具；`false` 可缩小固定工具 schema 上下文。 |
 | `leases.ttlMs` | `900000` | 默认咨询式租约寿命；过期不会自动释放。 |
 | `dev.hotReload` | `true` | 注册 `tower_reload`；关闭时 `/tower reload` 也被禁用。无 HMR 服务时调用返回 `reload-unavailable`。 |
 | `dev.reloadDelayMs` | `50` | 计划中的 reload 延迟，先让工具结果送达。 |
-| `dev.reloadRequiredIds` | 四个 Tower loader id | 作为 required 传给 `reconcileProfile` 的条目 id。 |
+| `dev.reloadRequiredIds` | 五个 Tower loader id | 作为 required 传给 `reconcileProfile` 的条目 id。 |
 
 ## 示例
 

package/docs/zh/reference/errors.md

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

package/docs/zh/reference/tools.md

@@ -34,7 +34,7 @@ roster 角色由 `exec.agent` 与 roster 共同决定。mission 级工具（`tow
 | `tower_init` | `base?`、`autoGitInit?`、`snapshotDirty?`、`reanchor?` | 创建 `<git-common-dir>/dsh-tower/state.json`。`autoGitInit` 执行 `git init` 并创建空的初始提交；`snapshotDirty` 记录一个游离快照提交作为 mission 基线；`reanchor` 仅在没有非终态 mission 时修改基线。返回 `dirty`、`snapshotCommit`、`reanchored`。 |
 | `tower_plan` | `missions[]`（`title`、`scope[]`、`tasks[]?`、`deps[]?`、`kind?`、`context?`、`references[]?` ≤20、`reviewPolicy?`、`reviewExemptionReason?`） | 创建 mission `M1..`；重叠的 build scope 会自动加依赖；拒绝未知依赖与依赖循环。`reviewPolicy:"none"` 需要非空理由；审查门禁开启时，preflight 还要求 `gates.allowReviewExemption`。 |
 | `tower_mission` | `id`（别名 `missionId`）、`status?`、`task_done?`、`task_drop?`+`task_drop_reason?`、`blocker?`、`clear_blockers?`、`note?`、`scope?`、`pause_cause?`、`authorization?` | 更新单个 mission。worker 可安全使用的字段是 task/blocker/note；不能在这里设置 `merged`。暂停的 mission 记录 `pause_cause`（user/failure/resource/dependency）；恢复用户暂停的 mission 会遵循 `mode.requireResumeAuthorization`。 |
-| `tower_status` | `missionId?`、`offset?`、`limit?`、`includeGate?`、`format?` | 默认返回面板。`missionId` 返回完整详情（任务/备注/审查/finding/完成报告）。`offset`/`limit` 对 mission 分页（默认 20，最大 100），`includeGate` 附带门禁摘要，`format:"markdown"` 返回看板。 |
+| `tower_status` | `missionId?`、`offset?`、`limit?`、`includeGate?`、`format?` | 默认返回面板。`missionId` 返回完整详情（任务/备注/审查/finding/完成报告）。`offset`/`limit` 对 mission 分页（默认 20，最大 100），`includeGate` 附带门禁摘要，`format:"markdown"` 返回看板。host 提供 mode hook 时还会包含 `mode.lastChange` 与最近 `history`。 |
 | `tower_spawn` | `missionId`（别名 `id`）、`role`（`worker`/`reviewer`）、`name?`、`instructions?`、`worktreeRoot?`、`wait?`、`waitMs?`、`takeover?`、`includeDirtyBase?` | 准备或复用 worktree 并启动子代理。worker 使用 `tower-worker`；reviewer 要求 mission 为 `completed`，并使用只读的 `tower-reviewer`。`takeover:true` 替换已不再运行的 worker 条目（ownerGeneration 递增）。每个 mission 只能有一个活跃 worker；`spawn.maxLiveWorkers` 限制整个仓库。 |
 | `tower_roster` | — | roster 及来自子代理目录的实时活动（`running`/`inactive`/`missing`/`unknown`）与 `stale` 标记。只读。 |
 | `tower_adopt` | `retireMissing?` | 把 roster 条目与持久子代理目录对账。可证明已消失的 agent 会被标记为 retired（默认），或标记为 `missing`（`retireMissing:false`）以便检查/接管。 |

package/domain/collab/batch.js

@@ -0,0 +1,112 @@
+// Pure batch lifecycle decisions and status projection.
+//
+// `domain/batch.js` owns the admission/close evidence validation; this module
+// owns the id assignment, close/abandon record transitions, and status payload
+// that app/batch.js used to keep inline. Receipt file reads stay in the tool
+// layer.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+import { summarize } from '../batch.js'
+
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+/**
+ * @param {string} message
+ * @param {string} [code]
+ * @returns {never}
+ */
+function fail(message, code = 'batch-invalid') {
+  throw new TowerToolError(code, message)
+}
+
+/**
+ * Next free `B<n>` id.
+ * @param {any[]} batches
+ * @returns {string}
+ */
+export function nextBatchId(batches) {
+  const max = batches.reduce((value, batch) => {
+    const match = /^B(\d+)$/.exec(String(batch.id ?? ''))
+    return match ? Math.max(value, Number(match[1])) : value
+  }, 0)
+  return `B${max + 1}`
+}
+
+/**
+ * Project the persisted batch record from normalized create input.
+ * @param {string} id
+ * @param {any} normalized
+ * @param {string} actor
+ * @param {number} now
+ * @returns {any}
+ */
+export function createBatchRecord(id, normalized, actor, now) {
+  return {
+    id,
+    status: 'open',
+    ...normalized,
+    createdBy: actor,
+    createdAt: now,
+  }
+}
+
+/**
+ * Mark a validated open batch closed with its evidence snapshot.
+ * @param {any} batch
+ * @param {{ checks?: unknown, treeTip?: unknown, receiptHashes?: unknown }} options
+ * @param {string} actor
+ * @param {number} now
+ * @returns {any}
+ */
+export function closeBatchRecord(batch, options, actor, now) {
+  batch.status = 'closed'
+  batch.closedAt = now
+  batch.closedBy = actor
+  batch.close = {
+    checks: options.checks ?? [],
+    treeTip: options.treeTip ?? null,
+    receiptHashes: options.receiptHashes ?? {},
+    at: now,
+  }
+  return batch
+}
+
+/**
+ * A closed batch cannot be abandoned; an already-abandoned one is a no-op.
+ * @param {any} batch
+ * @param {string} batchId
+ * @returns {{ alreadyAbandoned: boolean }}
+ */
+export function abandonBatchCheck(batch, batchId) {
+  if (batch.status === 'closed') fail(`batch ${batchId} is already closed`)
+  return { alreadyAbandoned: batch.status === 'abandoned' }
+}
+
+/**
+ * Apply an abandonment to the draft batch.
+ * @param {{ batch: any, actor: string, reason?: unknown, now: number }} params
+ * @returns {any}
+ */
+export function applyBatchAbandon({ batch, actor, reason, now }) {
+  batch.status = 'abandoned'
+  batch.abandonedAt = now
+  batch.abandonedBy = actor
+  batch.abandonReason = typeof reason === 'string' && reason.trim() ? reason.trim() : null
+  return batch
+}
+
+/**
+ * Read-only `tower_batch status` payload.
+ * @param {TowerState} state
+ * @param {string | undefined} batchId
+ * @returns {any}
+ */
+export function batchStatusPayload(state, batchId) {
+  const batches = state.batches ?? []
+  const batch = batchId ? batches.find((entry) => entry.id === batchId) : null
+  if (batchId && !batch) fail(`unknown batch "${batchId}"`)
+  return {
+    batches: batches.map((entry) => summarize(state, entry)),
+    ...(batch ? { batch: summarize(state, batch) } : {}),
+  }
+}

package/domain/collab/messages.js

@@ -0,0 +1,127 @@
+// Pure message routing, read tracking, and inbox projections.
+//
+// app/messages.js owns the state lock, load, persistence, and activity log;
+// app/roster.js's unreadFor delegates to `unreadMessages` here.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+
+/** @typedef {import('../../types/index.js').RosterEntry} RosterEntry */
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+/**
+ * @param {string} message
+ * @returns {never}
+ */
+function fail(message) {
+  throw new TowerToolError('invalid-argument', message)
+}
+
+/**
+ * Validate the recipient against the roster plus the synthetic `tower` name.
+ * @param {{ roster?: RosterEntry[], to: string, from: string }} params
+ * @returns {void}
+ */
+export function assertMessageRecipient({ roster = [], to, from }) {
+  const names = new Set(roster.map((entry) => entry.name))
+  names.add('tower')
+  if (to !== 'all' && !names.has(to)) {
+    fail(`unknown message recipient "${to}" (known: ${[...names].join(', ')}, all)`)
+  }
+  if (to === from) fail('refusing to send a message to yourself')
+}
+
+/**
+ * Project the persisted message record.
+ * @param {any} input
+ * @param {number} seq
+ * @param {number} now
+ * @returns {any}
+ */
+export function createMessage(input, seq, now) {
+  return {
+    id: `msg-${seq}`,
+    seq,
+    from: input.from,
+    to: input.to,
+    subject: input.subject,
+    body: input.body,
+    scope: input.scope ?? null,
+    consentRef: input.consentRef ?? null,
+    at: now,
+    readBy: [],
+    delivery: [],
+  }
+}
+
+/**
+ * Append delivery results to a message, preserving earlier entries.
+ * @param {{ delivery?: unknown[] }} message
+ * @param {unknown[]} results
+ * @returns {unknown[]}
+ */
+export function addDelivery(message, results) {
+  message.delivery = [...(message.delivery ?? []), ...results]
+  return message.delivery
+}
+
+/**
+ * Inbox page plus read-marking mutation. Returns `changed` so the use case can
+ * decide whether the state file needs a write.
+ * @param {any[]} messages
+ * @param {{ reader: string, limit?: number, includeRead?: boolean }} input
+ * @param {number} now
+ * @returns {{ payload: any, changed: boolean }}
+ */
+export function inboxView(messages, input, now) {
+  const reader = input.reader
+  const limit = Math.max(1, Math.min(100, input.limit ?? 20))
+  const includeRead = input.includeRead === true
+  const visible = [...messages]
+    .reverse()
+    .filter((message) => (message.to === reader || message.to === 'all') && message.from !== reader)
+  const unread = visible.filter((message) => !(message.readBy ?? []).includes(reader))
+  const page = (includeRead ? visible : unread).slice(0, limit)
+
+  let changed = false
+  for (const message of page) {
+    if (!(message.readBy ?? []).includes(reader)) {
+      message.readBy = [...(message.readBy ?? []), reader]
+      message.readAt = { ...(message.readAt ?? {}), [reader]: now }
+      changed = true
+    }
+  }
+  const unreadRemaining = visible.filter((message) => !(message.readBy ?? []).includes(reader)).length
+  return {
+    payload: {
+      reader,
+      messages: page.map((message) => ({
+        id: message.id,
+        from: message.from,
+        to: message.to,
+        subject: message.subject,
+        body: message.body,
+        scope: message.scope ?? null,
+        at: message.at,
+        delivery: message.delivery ?? [],
+        ackAt: message.readAt?.[reader] ?? null,
+      })),
+      pageSize: page.length,
+      unreadRemaining,
+    },
+    changed,
+  }
+}
+
+/**
+ * Unread inbox rows for one recipient (messages from self never count).
+ * @param {TowerState} state
+ * @param {string} name
+ * @returns {any[]}
+ */
+export function unreadMessages(state, name) {
+  return (state.messages ?? []).filter((message) => {
+    if (message.from === name) return false
+    if (message.to !== name && message.to !== 'all') return false
+    return !(/** @type {any[]} */ (message.readBy ?? [])).includes(name)
+  })
+}

package/domain/collab/roster.js

@@ -0,0 +1,158 @@
+// Pure roster observation and stale/inactive policy.
+//
+// app/roster.js owns the state lock, load, persistence, and activity log; the
+// transitions below mutate only the in-memory roster rows they are given.
+// @ts-check
+import { ROSTER_INACTIVE } from '../roster.js'
+
+/** @typedef {import('../../types/index.js').RosterEntry} RosterEntry */
+
+/**
+ * @param {RosterEntry} entry
+ * @returns {void}
+ */
+export function clearStale(entry) {
+  delete entry.stale
+  delete entry.staleAt
+}
+
+/**
+ * Count repeated absence observations and list rows ready to adopt.
+ * @param {RosterEntry[]} roster
+ * @param {{ present?: unknown[], absent?: unknown[], confirmations?: unknown }} observations
+ * @param {number} now
+ * @returns {{ candidates: string[], changed: boolean }}
+ */
+export function recordRosterObservations(roster, { present = [], absent = [], confirmations = 2 }, now) {
+  const presentIds = new Set(present)
+  const absentIds = new Set(absent)
+  /** @type {string[]} */
+  const candidates = []
+  let changed = false
+  for (const entry of roster) {
+    if (presentIds.has(entry.agentId)) {
+      if (entry.absentObservations !== undefined) {
+        delete entry.absentObservations
+        delete entry.absentSince
+        changed = true
+      }
+      continue
+    }
+    if (!absentIds.has(entry.agentId)) continue
+    entry.absentObservations = (/** @type {number} */ (entry.absentObservations ?? 0)) + 1
+    entry.absentSince ??= now
+    changed = true
+    const observations = /** @type {number} */ (entry.absentObservations)
+    if (observations >= Math.max(2, Number(confirmations) || 2)) {
+      candidates.push(/** @type {string} */ (entry.agentId))
+    }
+  }
+  return { candidates, changed }
+}
+
+/**
+ * Release live slots whose catalog activity is explicitly inactive.
+ * @param {RosterEntry[]} roster
+ * @param {Record<string, string>} activity
+ * @param {number} now
+ * @returns {{ released: string[] }}
+ */
+export function reconcileObservedInactive(roster, activity = {}, now) {
+  /** @type {string[]} */
+  const released = []
+  for (const entry of roster) {
+    if (entry.state === 'reserved' || ROSTER_INACTIVE.has(entry.state)) continue
+    const agentId = /** @type {string} */ (entry.agentId)
+    if (activity[agentId] !== 'inactive') continue
+    entry.state = 'inactive'
+    entry.outcome = 'catalog reported inactive'
+    entry.outcomeAt = now
+    clearStale(entry)
+    released.push(entry.name)
+  }
+  return { released }
+}
+
+/**
+ * Retire entries by agent id, skipping rows already retired.
+ * @param {RosterEntry[]} roster
+ * @param {unknown[]} agentIds
+ * @param {number} now
+ * @returns {{ retired: string[] }}
+ */
+export function retireEntries(roster, agentIds, now) {
+  if (!Array.isArray(agentIds) || agentIds.length === 0) return { retired: [] }
+  /** @type {string[]} */
+  const retired = []
+  for (const entry of roster) {
+    if (entry.state !== 'retired' && agentIds.includes(entry.agentId)) {
+      entry.state = 'retired'
+      entry.retiredAt = now
+      clearStale(entry)
+      retired.push(/** @type {string} */ (entry.agentId))
+    }
+  }
+  return { retired }
+}
+
+/**
+ * Mark entries missing unless they are already inactive.
+ * @param {RosterEntry[]} roster
+ * @param {unknown[]} agentIds
+ * @param {number} now
+ * @returns {{ missing: string[] }}
+ */
+export function markMissingEntries(roster, agentIds, now) {
+  if (!Array.isArray(agentIds) || agentIds.length === 0) return { missing: [] }
+  /** @type {string[]} */
+  const missing = []
+  for (const entry of roster) {
+    if (!ROSTER_INACTIVE.has(entry.state) && agentIds.includes(entry.agentId)) {
+      entry.state = 'missing'
+      entry.missingSince = now
+      clearStale(entry)
+      missing.push(/** @type {string} */ (entry.agentId))
+    }
+  }
+  return { missing }
+}
+
+/**
+ * Watchdog sweep: catalog-inactive rows become inactive; rows absent from an
+ * authoritative catalog and older than `staleMs` become stale. Unknown catalog
+ * state is never treated as stopped.
+ * @param {RosterEntry[]} roster
+ * @param {{ activity?: Record<string, string>, staleMs?: unknown, authoritative?: unknown }} input
+ * @param {number} now
+ * @returns {{ marked: string[], idled: string[] }}
+ */
+export function sweepRosterState(roster, input = {}, now) {
+  const staleMs = Number(input.staleMs) || 0
+  if (staleMs <= 0 || input.authoritative !== true) return { marked: [], idled: [] }
+  const activity = input.activity ?? {}
+  /** @type {string[]} */
+  const marked = []
+  /** @type {string[]} */
+  const idled = []
+  for (const entry of roster) {
+    if (ROSTER_INACTIVE.has(entry.state)) continue
+    const observed = activity[/** @type {string} */ (entry.agentId)]
+    if (observed === 'inactive') {
+      entry.state = 'inactive'
+      entry.outcome = entry.outcome ?? 'idle (catalog)'
+      entry.outcomeAt = now
+      idled.push(entry.name)
+      continue
+    }
+    if (observed === 'running') continue
+    if (observed !== undefined) continue
+    const age = now - Number(entry.spawnedAt ?? now)
+    if (age > staleMs) {
+      entry.state = 'stale'
+      entry.stale = true
+      entry.staleAt = now
+      marked.push(entry.name)
+    }
+  }
+  return { marked, idled }
+}