dsh-tower 2.0.4 → 2.1.0-beta.1

package/docs/architecture/overview.md

@@ -2,24 +2,61 @@
 
 ## Components
 
+The bundle is all-or-nothing: `cordis.patch.yml` inserts one `tower-bundle` `cordis:group` row whose
+internal sections are the Host plugin, the skills provider, and the worker/reviewer presets. The
+group is the only user-facing component; disabling it disables every section together, so no preset
+or skill can remain mounted while the `tower_*` tools are gone.
+
 ```
 Host plugin (index.js)
  ├─ /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
+ ├─ lib/tool-registry.js -> registration aggregator, actor guards, shared helpers
+ │                    (+ 27 registered repository tools)
+ │                    (+ tower_reload while dev.hotReload is on; fails reload-unavailable without HMR)
+ ├─ tools/index.js  -> thin public wiring (re-exports the registry + briefings)
+ └─ app/tower.js   -> orchestration surface; delegates to use-case modules
+       ├─ app/init.js, provision.js, merge.js, rebase.js, teardown.js
+       ├─ app/review.js, findings.js, batch.js, messages.js, roster.js
+       ├─ app/plan.js, mission.js, checkCompletion.js, spawn.js, recording.js
+       └─ app/gate.js, read.js, board.js, missionContext.js, enrichedMissions.js
+ ports (explicit contracts):
+       ports/store.js vcs.js clock.js ids.js
+ adapters (the only I/O):
+       adapters/store-fs.js   the only module importing node:fs
+       adapters/vcs-git.js    the only module importing node:child_process
+       adapters/default.js    composition root: store, vcs, clock, ids
+ infrastructure (lib/):
+       lib/store.js           repo-scoped lock + atomic JSON + activity.jsonl
+       lib/git.js             bounded git commands + timeout classification
+       lib/config.js          profile/repo config layers over the pure schema
+       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
+ pure domain modules (no fs/git):
+       domain/errors.js     stable, structural tool error catalog
+       domain/batch.js      batch admission create/close/summary validation
+       domain/config/schema.js  Schemastery config schema, defaults, validation
+       domain/contracts/outputs.js  tool output-schema catalog
+       domain/contracts/tool-inputs/  per-area TypeBox input schemas + ToolInputs map
+       domain/vocabulary.js  canonical status/type/action enums + predicates
+       domain/mission.js    statuses, transitions, pause causes
+       domain/gate.js       completion and merge-gate snapshot decisions
+       domain/scope.js      glob/scope validation and overlap
+       domain/summary.js    mission/finding summaries
+       domain/planning.js   mission numbering, dependency DAG, auto-deps
+       domain/state.js      load-time state validation
+       domain/report.js     board rendering
+       domain/roster.js     roster predicates
+ tools layer:
+       lib/tool-registry.js     registration aggregator + shared guards/helpers
+       tools/index.js           thin public wiring (re-exports only)
+       tools/*.js               one module per tool, handler + imported input schema
+ Subagents
  ├─ 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
 worktree in `.dsh-tower-worktrees/<hash>/<missionId>`. The plugin never operates on the main checkout's
 working tree except merge and the read-only diff.
@@ -66,6 +103,68 @@ After the command, regardless of exit status, it inspects `HEAD`:
 |---|---|
 | `<git-common-dir>/dsh-tower/state.json` | missions, roster, reviews, findings, messages, reviews sequence |
 | `<git-common-dir>/dsh-tower/activity.jsonl` | append-only activity |
-| `<git-common-dir>/dsh-tower/state.lock` | single-writer lock (stale locks are reported, never stolen) |
+| `<git-common-dir>/dsh-tower/state.lock` | single-writer state lock (dead-PID reclaimed, live lock reported) |
+| `<git-common-dir>/dsh-tower/git.lock` | repo-scoped serialization for git mutations outside the state lock |
+| `<git-common-dir>/dsh-tower/lock-holds.jsonl` | state/git lock-hold telemetry |
 | `<checkout parent>/.dsh-tower-worktrees/<hash>/<missionId>` | mission worktree |
 | `$DSH_HOME/tower-mode/modes.json` | Tower mode per agent/session |
+| `$DSH_HOME/tower-mode/modes.lock` | mode-store single-writer lock |
+
+`state.json` and `modes.json` both use an atomic write (temp + rename), token-checked lock release,
+dead-PID reclamation, and bounded lock waits. `state.json` is the mission persistence contract;
+`modes.json` is the per-agent mode contract; neither is written without its own lock.
+
+## Layering rules
+
+`npm run architecture:check` (also in CI) enforces the rules as **errors**:
+
+- `domain/**` must not import I/O or adapters (`domain-pure`).
+- Only `adapters/vcs-git.js` may import `node:child_process`, and only
+  `adapters/store-fs.js` may import `node:fs` (`child-process-surface`, `fs-surface`).
+  The rule is enforced over the source roots — `lib/`, `app/`, `domain/`, `tools/`,
+  `adapters/`, `ports/` — and does not cover `scripts/**`, which holds maintenance
+  entry points (release check, mount smoke, docs generators) that may spawn git or npm.
+- `tools/**` must stay thin and free of status/type literals (`tools-thin`, `tools-vocabulary`);
+  `tools/index.js` is the thin public wiring module and stays exempt from the thinness rule,
+  while registration/shared machinery lives in `lib/tool-registry.js`.
+- Aggregate files have size ceilings; top-level mutable state is limited to explicit composition
+  roots (`aggregate-size`, `ambient-state`). The per-tool ceiling is 200 lines; only the
+  `tools/index.js` wiring module is exempt, and it is now far below the ceiling.
+
+A fixture test seeds one violation per rule, so a rule that cannot fail is itself a test failure.
+
+## Mount smoke and host internals
+
+`npm run smoke:mount` (#95) boots a real profile through the pinned host instead of mocking the loader.
+`scripts/mount-smoke/probe.mjs` is the one file that imports the host's internals — `runProfile` from
+`dsh/lib/profile-boot.js` and the layered env from `dsh-app-boot` — because those are the entry points
+`dsh` itself calls to compose a profile; the probe uses them to boot without a model, browser, or
+session. `scripts/mount-smoke/host.json` is the single host/pnpm pin (a unit test keeps its `dsh` field
+equal to the newest `COMPATIBILITY.md` row), so a host bump can move those entry points and may require
+probe adjustments in the same change.
+
+## #56 definition of done
+
+All epic DoD items now have an executable gate:
+
+- Pure domain share: **37.9%** (5,993 / 15,820 source lines), enforced by
+  `npm run domain:check` (threshold 35%).
+- `domain/**` imports no fs, child_process, adapters, app, tools, or lib infrastructure;
+  `domain-pure` is a blocking architecture rule.
+- Inside the source roots, only `adapters/vcs-git.js` imports `node:child_process`; only
+  `adapters/store-fs.js` imports `node:fs`; both are blocking rules with fixtures.
+- `lib`, `app`, and `domain` files stay <= 800 lines; every `tools/**` file stays
+  40-200 lines (one handler module per tool; `tools/index.js` is 40-line wiring).
+- No `withLock` scope starts a process; the two-phase tests instrument every git call.
+- `tools/**` has no status/type/enum literal; vocabulary is owned by
+  `domain/vocabulary.js`; the `tools-vocabulary` rule is blocking.
+- `validateState` has a four-line body over `domain/state/schema.js` and
+  `domain/state/semantics.js`.
+- `state.json` and `modes.json` share `lib/persistence.js` atomic write, token-owned
+  lock, dead-PID quarantine, and bounded-wait primitives.
+- The in-memory lifecycle and adapter contracts run a full mission lifecycle with no
+  disk and no git.
+- The seven fitness rules are errors, each with a seeded failing fixture.
+
+
+

package/docs/board.md

@@ -0,0 +1,72 @@
+# Tracker board
+
+The three questions an owner asks weekly, as commands that actually work. Run them from the
+repository root (or add `--repo louifinn/dsh-tower`). Verified against the live tracker on
+2026-10-22; the counts below are evidence for the commands, not a promise they stay fixed.
+
+Priority lives in the `P0`–`P3` labels and area in `area/*`; issue titles carry no `[P*]`
+prefix any more. Every open issue has exactly one `P*` label and at least one `area/*` label.
+
+## Open P1
+
+```bash
+gh issue list --state open --label P1
+```
+
+Verified: **10** open on 2026-10-22 (#56, #69, #76, #77, #82, #94, #95, #96, #97, #98).
+
+`--label` uses REST filters, so it does not wait for the search index after an edit. Do **not**
+write `--label P0,P1`: `gh` treats that as one literal label name and returns nothing (verified).
+For "P0 or P1" use `--search 'label:P0,P1'` — inside `--search`, the comma means OR, while
+`label:P0 label:P1` (a space) means AND and returns only issues carrying both.
+
+## Unmilestoned P0/P1
+
+```bash
+gh issue list --state open --search 'no:milestone label:P0,P1'
+```
+
+Verified: **0** on 2026-10-22 — every open P0/P1 is in a milestone. A non-zero result means a
+release-scoped issue has no home; put it in the next release milestone or demote it to P2/P3.
+
+## Closed this week by area
+
+```bash
+# week starts Monday; compute it rather than pasting yesterday's date
+# GNU date (Linux/CI); on macOS use `gdate` or work the date out by hand
+MONDAY=$(date -d 'last monday' +%F)
+gh issue list --state closed --search "closed:>=$MONDAY label:area/ci"
+```
+
+```powershell
+$MONDAY = (Get-Date).Date.AddDays(-(([int](Get-Date).DayOfWeek+6)%7)).ToString('yyyy-MM-dd')
+gh issue list --state closed --search "closed:>=$MONDAY label:area/ci"
+```
+
+Swap `area/ci` for `area/state`, `area/tools`, `area/docs`, `area/release`, `area/process`,
+`area/architecture`, or `area/scope`. Verified for `area/ci` with `closed:>=2026-10-19`:
+**0**, because all **54** issues closed that week carry no `area/*` label at all. The query is
+right; the history is unlabelled. Label a closure before you close it (or backfill) and the
+by-area view starts working.
+
+## Release rule query
+
+A release may not be tagged while its milestone holds an open P0/P1 unless the release notes
+say why. Check the milestone that is about to ship (see the [release checklist](guide/release.md)):
+
+```bash
+gh issue list --state open --search 'milestone:2.1.0-beta.1 label:P0,P1' --json number,title
+```
+
+Verified: **8** on 2026-10-22 (#76, #77, #82, #94, #95, #96, #97, #98) — the delivery gate's own
+tickets block the release until they land. That is the rule doing its job, not a false positive.
+
+## Milestones
+
+```bash
+gh api 'repos/louifinn/dsh-tower/milestones?state=all&per_page=100' \
+  --jq '.[] | "\(.number)\t\(.title)\topen=\(.open_issues)\tclosed=\(.closed_issues)"'
+```
+
+Only issues that actually block a release belong in a milestone; everything else stays
+unmilestoned and is queried by priority.

package/docs/guide/hot-reload.md

@@ -101,7 +101,7 @@ The bridge behind the tool follows the `dev` config group:
 |---|---|
 | `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. |
+| `dev.reloadRequiredIds` | Loader entry ids the profile must keep active (default `tower-bundle`, `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

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

@@ -2,7 +2,7 @@
 
 ## Requirements
 
-- DSH `0.2.1-rc.2` or newer
+- DSH `0.2.1-rc.2`; see [COMPATIBILITY.md](../../COMPATIBILITY.md) for the builds actually verified per release
 - Node.js 22+
 - Git (local worktrees; no network access is required)
 
@@ -29,6 +29,13 @@ The Host plugin loads at DSH startup: **restart DSH after install or update**.
 
 ## Migration notes
 
+- **2.0.4 → 2.1.0-beta.1**: no state/config migration. This is a **pre-release** published on the
+  `next` dist-tag, so `latest` still resolves to 2.0.4 — install it with
+  `dsh plugin --profile web add dsh-tower@next` (or the exact version). The runtime behavior is
+  unchanged; the release carries the delivery gate (mount smoke in CI, `npm run release:check`, the
+  evidence conventions and the tracker policy) rather than tool changes. These docs merge before the
+  human publish step: `next` only resolves to 2.1.0-beta.1 after the [release checklist](release.md)
+  runs `npm publish --tag next`, and `latest` stays on 2.0.4 until a stable release.
 - **2.0.3 → 2.0.4**: no state/config migration. This is a security-hardening and integrity release
   (authorization, merge SHA binding, dirty-worktree completion, stale-lock recovery, limited test/git
   process environment, `tower_recover`, UI 0.2.2). Review `review.requireReview`, `tests.admission` and

package/docs/guide/release.md

@@ -0,0 +1,125 @@
+# Release checklist
+
+One page, six steps, in order. The only **human-only** step is `npm publish` (npm
+credentials + 2FA); an agent can do everything else in this repository. A release is a claim —
+`npm run release:check` is the mechanical half of it.
+
+## Milestone rule (before step 1)
+
+A release may not be tagged while its milestone holds an open P0/P1, unless the release
+notes say why it was accepted:
+
+```bash
+gh issue list --state open --search 'milestone:2.1.0-beta.1 label:P0,P1' --json number,title
+```
+
+Empty output → proceed. Non-empty → close the issues (with the two-line closure contract in
+[CONTRIBUTING.md](../../CONTRIBUTING.md#the-two-line-closure-contract)), or name each accepted
+issue and the reason in the release notes. The same query is saved in [the board](../board.md);
+comma means OR inside `--search`, while `--label P0,P1` matches one literal label name and
+returns nothing.
+
+`npm run release:check` prints `git describe`, the previous tag, the commit count since that
+tag and whether Unreleased is non-empty on every run. On a PR it warns; on a tag push it fails
+when `package.json` did not move past the last tag, when the tag is not `v<version>`, or when
+the CHANGELOG has no release content. CI runs it on every push and PR.
+
+## 1. Bump the version
+
+Edit `package.json` (`"version": "2.1.0-beta.1"`). The previous tag is found from the pushed
+tag's parent (`<tag>^`), so a tag push that repeats the old version fails.
+
+```bash
+npm run release:check -- --mode tag --tag v2.1.0-beta.1
+```
+
+## 2. Write the changelog
+
+Move the Unreleased entries under a version heading, so the GitHub Release body can be
+extracted mechanically. Keep the `## 未发布（Unreleased）` heading (it may be empty).
+
+```markdown
+## 未发布（Unreleased）
+
+## 2.1.0-beta.1（2026-10-22）
+
+- feat: ...
+```
+
+The gate accepts a non-empty Unreleased section (bump first, rename later) **or** a non-empty
+section whose heading names the version. Write the version section as user-facing notes.
+
+## 3. Add the COMPATIBILITY row
+
+`COMPATIBILITY.md` keeps the columns `| dsh version | tag / commit | verified on | what was run |`.
+Put the **host build in cell 0** and the **tag in cell 1**:
+
+```markdown
+| 0.2.1-rc.2 | v2.1.0-beta.1 | 2026-10-22 | `npm test`, `npm run docs:check`, mount smoke |
+```
+
+`lib/compatibility.js#parseCompatibility` reads cells 0–3 only: never insert a column before
+the tag and never add one before "what was run", or `tower_doctor` stops seeing the row. The
+host pin in `scripts/mount-smoke/host.json` must equal cell 0 of the newest row (a unit test
+enforces it).
+
+Commit steps 1–3 as the release PR against protected `main`, merge it, then continue from a
+**clean clone/worktree at the merge commit** — not the integration worktree.
+
+## 4. Publish — human-only (2FA)
+
+```bash
+git status --porcelain          # must be empty: files:["docs/"] packs untracked docs too
+npm ci
+npm test && npm run docs:check && npm run pack:check
+npm pack --dry-run              # inspect the published file list
+npm publish --tag next --otp <code>
+npm view dsh-tower dist-tags --json
+npm view dsh-tower@next version
+```
+
+- Publish pre-releases with `--tag next`, **never** `latest`; `latest` moves only for a stable minor.
+- Publish **before tagging**. If publishing fails, do not tag. If you already tagged, delete it
+  (`git tag -d <tag>` and `git push --delete origin <tag>`) instead of leaving a tag on an
+  unpublished commit.
+- Both checks must name the version just published, and `next` must differ from `latest`.
+
+## 5. Annotated tag on the published commit
+
+```bash
+npm run release:check -- --mode tag --tag v2.1.0-beta.1
+git tag -a "v2.1.0-beta.1" -m "dsh-tower 2.1.0-beta.1"
+git push origin "v2.1.0-beta.1"
+git for-each-ref refs/tags/v2.1.0-beta.1 --format='%(objecttype)|%(subject)'
+# tag|dsh-tower 2.1.0-beta.1      (a lightweight tag prints commit, and is not allowed)
+```
+
+The pushed tag must be exactly `v<version>`. The tag push re-runs `release:check` against
+`<tag>^`; this is why tagging a commit whose `package.json` did not move fails.
+
+## 6. GitHub Release from the CHANGELOG section
+
+```bash
+VERSION=2.1.0-beta.1
+awk -v v="$VERSION" '$0 ~ "^##[[:space:]]+.*" v {s=1; next} s && /^##[[:space:]]/ {exit} s {print}' \
+  CHANGELOG.md > release-notes.md
+test -s release-notes.md || { echo "empty section for $VERSION" >&2; exit 1; }
+gh release create "v$VERSION" --title "dsh-tower $VERSION" --notes-file release-notes.md \
+  --prerelease --verify-tag --latest=false
+gh release view "v$VERSION" --json tagName,isPrerelease,body
+```
+
+PowerShell extraction of the same section:
+
+```powershell
+$version = '2.1.0-beta.1'; $lines = Get-Content CHANGELOG.md
+$start = ($lines | Select-String -Pattern "^##\s+.*$([regex]::Escape($version))" | Select-Object -First 1).LineNumber
+if (-not $start) { throw "CHANGELOG has no section for $version" }
+$next = ($lines | Select-String -Pattern '^##\s+' | Where-Object LineNumber -gt $start | Select-Object -First 1).LineNumber
+$end = if ($next) { $next - 2 } else { $lines.Count - 1 }
+($lines[$start..$end] -join "`n").Trim() | Set-Content release-notes.md -Encoding utf8
+```
+
+`--verify-tag` refuses to create the tag at the default branch when the pushed tag is missing;
+`--prerelease --latest=false` keeps the GitHub "latest" marker on the stable release. Releases
+are what consumers and the plugin directory can see — a tag alone is not a release.

package/docs/operations/security.md

@@ -44,6 +44,49 @@ Tower's guarantees are **coordination guarantees**, not a sandbox. Understand wh
 - **Legacy import is read-only.** Imported snapshots live under the canonical state directory and are never
   activated, adopted, or resumed; an operator must explicitly re-plan/migrate work.
 
+## Repository protection
+
+This section is about **this repository**, not about a repository Tower runs on. Server-side branch
+protection is not a plugin feature — Tower writes to the local base branch and cannot configure a
+remote — but `dsh-tower` enables it for its own `main`, because the code that is the gate is also the
+code an attacker would most want to change:
+
+- `main` requires a pull request for every change, **enforced for admins**, so a direct push is
+  rejected even for the maintainer.
+- Required checks are `test (22)`, `test (24)` and `mount`. The mount job packs the tarball and boots
+  it in a throwaway profile, so "the tests pass" cannot land a bundle that fails to appear after
+  `dsh plugin add`.
+- Force-push and branch deletion are blocked, so history cannot be rewritten under a published tag.
+- There are no mandatory approvals: with one maintainer, a self-approval requirement would be a rubber
+  stamp. The evidence instead is the four-line PR body (failure mode, change, test, blast radius) for
+  the two-key paths, written in [CONTRIBUTING.md](../../CONTRIBUTING.md#landing-changes).
+
+What this buys: no untested change reaches `main`, a red or missing required check cannot be bypassed
+by the owner, and history is append-only. What it does **not** buy: a second reader, protection against
+a compromised maintainer token, or any protection for the repositories Tower itself operates on — those
+remain deployment concerns. The settings, their rationale and a verification command are recorded in
+[SECURITY.md](../../SECURITY.md#repository-protection-on-main).
+
+## Model-initiated mode entry (threat model)
+
+`mode.allowAgentControl:true` means a prompt injection in a repository file, issue text, or fetched
+page can ask the model to “enter tower mode and fix this”. Tower does **not** authenticate the human
+intent behind that entry. What it does provide:
+
+- the entry is recorded with actor, action, reason, and timestamp; `tower_status.mode.history`
+  surfaces the recent transitions without grepping the activity log;
+- the model cannot merge without the preflight gate, review policy, scope checks, tests, and
+  clean-base checks; writing the plan does not bypass them;
+- workers are tool-restricted and instructed to stay in their worktree, but the main-checkout
+  protection is enforced by scope/merge checks and the preset, **not** by an OS sandbox;
+- `mode.workspaceLock` prevents a second Tower session from driving the same repository.
+
+It does **not** defend against: a model that legitimately passes every gate while acting on malicious
+instructions; repository hooks or test commands the repository itself declares; or filesystem/shell
+access outside the worktree by a worker that ignores its instructions. For a higher-assurance team,
+set `mode.allowAgentControl:false`, keep `review.requireReview:true`, review the repository before
+Tower work, and run the host under OS-level isolation.
+
 ## Not enforced by the plugin (deployment concerns)
 
 - **Worktree isolation is a protocol convention, not an OS sandbox.** Workers are assigned a dedicated
@@ -65,8 +108,10 @@ Tower's guarantees are **coordination guarantees**, not a sandbox. Understand wh
   from disk. Only enable HMR watch roots for checkouts you trust; a reload executes the current files.
 - **Prompt injection.** The reviewer reads untrusted branch content (diff/comments). The read-only preset
   limits impact, but no model-side protection is absolute.
-- **Base branch protection.** Tower writes to the local base branch; server-side branch protection/push
-  rules are not part of the plugin.
+- **Base branch protection.** Tower writes to the local base branch; server-side branch protection and
+  push rules are not part of the plugin. This repository's own `main` protection is described in
+  [Repository protection](#repository-protection); enabling equivalent protection on the repository you
+  run Tower on remains a deployment concern.
 
 ## Reporting
 

package/docs/reference/config.generated.md

@@ -0,0 +1,66 @@
+# Config reference (generated)
+
+> Generated by `npm run docs:generate:config` from `domain/config/schema.js`. Values are defaults before repo config.
+
+| Key | Default | Description |
+|---|---|---|
+| `section` | `""` | Legacy alias for mode.promptSection: replaces the whole Tower-mode system prompt text. |
+| `allowAgentControl` | `` | Legacy alias for mode.allowAgentControl: register tower_control so the model may toggle the mode. |
+| `init.autoGitInit` | `false` | tower_init may run git init and create an empty initial commit when the directory is not a repository. |
+| `init.snapshotDirty` | `false` | tower_init may snapshot uncommitted tracked changes into a dangling commit used as the mission baseline. |
+| `init.autoExclude` | `true` | Add in-repo Tower artifacts (MISSIONS.md, in-repo worktree roots) to .git/info/exclude so they do not look like user dirt. |
+| `mode.promptSection` | `` | Replacement Tower-mode system prompt text. Empty keeps the built-in reminder. |
+| `mode.sectionAppend` | `` | Extra text appended to the Tower-mode system prompt section (team conventions). |
+| `mode.allowAgentControl` | `true` | Register tower_control so the model may enter/leave the mode with a reason. |
+| `mode.autoPauseGoal` | `true` | Pause an active goal when entering Tower mode. |
+| `mode.requireResumeAuthorization` | `false` | Require an authorization reference when resuming a mission paused with pauseCause=user. |
+| `mode.requireHumanAckOnFirstEntry` | `false` | Require a human /tower ack before the model may enter Tower mode for the first time in a session. |
+| `mode.workspaceLock` | `false` | Allow only one Tower session per repository (advisory <git-common-dir>/dsh-tower/tower.lock). |
+| `mode.workspaceLockScope` | `"all"` | all = every repo-scoped tool acquires the workspace lock; mutations = only tools that write state/worktrees do. |
+| `mode.planModePolicy` | `"clear"` | On Tower entry: clear an active plan mode, or refuse to enter until the plan is exited. |
+| `mode.workspaceStaleMs` | `300000` | A workspace lock older than this is stale and can be taken over. |
+| `mode.heartbeatMs` | `10000` | Workspace-lock heartbeat interval while Tower mode is on. |
+| `mode.denyTools` | `["create_goal","todo_write","team_task_create","team_task_update","team_task_reopen","team_task_list","spawn_teammate","wait_agent","workflow","ralph","subagent","subagent_fork"]` | Tools refused while Tower mode is active. |
+| `mode.storePath` | `` | Directory for modes.json; defaults to $DSH_HOME/tower-mode. |
+| `mode.maxEntries` | `200` | Maximum persisted mode entries. |
+| `mode.lockTimeoutMs` | `5000` | How long saveModes waits for the cross-process modes.lock before giving up. |
+| `review.requireReview` | `false` | Require an independent clean review before merge. Default false: review is optional; set true to enforce the review gate globally. |
+| `review.maxRoundsPerReviewer` | `5` | Review-round cap per reviewer per mission branch. |
+| `merge.timeoutMs` | `900000` | Default tower_merge timeout, including pre-merge hooks. |
+| `merge.maxBufferBytes` | `67108864` | Captured merge output buffer. |
+| `git.timeoutMs` | `15000` | Default timeout for Git commands other than merge; merge uses merge.timeoutMs. |
+| `worktrees.root` | `` | Default parent directory for mission worktrees; empty derives <main-checkout-parent>/.dsh-tower-worktrees/<hash>. |
+| `spawn.workerPreset` | `"tower-worker"` | Agent preset for worker missions. |
+| `spawn.reviewerPreset` | `"tower-reviewer"` | Agent preset for reviewers. |
+| `spawn.maxDepth` | `1` | Subagent depth requested when spawning tower agents. |
+| `spawn.provider` | `` | Subagent provider id; empty picks spawn, then the first registered provider. |
+| `spawn.workerModel` | `{}` | Model route for workers; omitted inherits the parent session. |
+| `spawn.reviewerModel` | `{}` | Model route for reviewers; omitted inherits the parent session (recommended). |
+| `spawn.maxLiveWorkers` | `4` | Maximum live worker entries allowed per repository at once. |
+| `spawn.staleMs` | `15000` | Roster entries with no catalog activity after this age are marked stale and block merge (0 disables). |
+| `spawn.maxWaitMs` | `90000` | Upper bound for tower_spawn waitMs (default 90s, Kimi-compatible). |
+| `spawn.requireLease` | `` | Optional lease name tower_spawn must hold before starting a worker. |
+| `send.maxPerMinute` | `120` | Per-repository tower_send rate limit per minute (0 disables). |
+| `send.interruptDefault` | `false` | Default value of tower_send.interrupt when the caller omits it. |
+| `tests.enabled` | `true` | Run declared test discovery when a mission configures it. |
+| `tests.admission` | `"off"` | Run discovery before spawning a worker, when completing, or only on explicit tower_test (default off: repository code runs only on an explicit tower_test). |
+| `tests.timeoutMs` | `60000` | Per discovery command timeout. |
+| `tests.maxBytes` | `16777216` | Maximum captured stdout bytes per command. |
+| `tests.autoChecks` | `true` | Attach a tests check to the completion report when discovery runs. |
+| `tests.allowPackageDiscovery` | `true` | Allow package.json tower.testDiscovery commands from the mission worktree (executes repository code; see security docs). |
+| `gates.requireChecks` | `false` | Require at least one completion check (tower_complete.checks) before a mission can merge. |
+| `gates.requireTests` | `false` | Require a passing test-discovery receipt for the reviewed worktree tip before merge. |
+| `gates.allowReviewExemption` | `false` | Allow reviewPolicy:none missions with a non-empty reviewExemptionReason to skip review blockers. |
+| `docs.board` | `true` | Write a human-readable MISSIONS.md after mission changes. |
+| `docs.boardLocation` | `"common"` | common = <git-common-dir>/dsh-tower/MISSIONS.md; repo = <repoRoot>/MISSIONS.md. |
+| `tools.exposeOperational` | `true` | Master switch for batch/resource/import/legacy/recover/test/doctor tools. |
+| `tools.exposeBatch` | `true` | Register tower_batch. |
+| `tools.exposeImport` | `true` | Register tower_import_legacy/tower_legacy_map. |
+| `tools.exposeLeases` | `true` | Register tower_resource advisory leases. |
+| `tools.exposeTests` | `true` | Register tower_test; gates.requireTests requires it. |
+| `tools.exposeRecovery` | `true` | Register tower_recover (stale state-lock escape). |
+| `tools.exposeDoctor` | `true` | Register tower_doctor (read-only health contract). |
+| `leases.ttlMs` | `900000` | Default advisory lease lifetime; expiry never auto-releases. |
+| `dev.hotReload` | `true` | Register tower_reload and /tower reload when the DSH HMR service is available. |
+| `dev.reloadDelayMs` | `50` | Delay before a scheduled reload, so the tool result is delivered first. |
+| `dev.reloadRequiredIds` | `["tower-bundle","tower","tower-skills","preset-tower-worker","preset-tower-reviewer"]` | Loader entry ids passed to reconcileProfile as required. |

package/docs/reference/config.md

@@ -41,11 +41,13 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
 | `allowAgentControl` | `true` (alias of `mode.allowAgentControl`) | Legacy alias: register `tower_control` so the model may toggle the mode. |
 | `init.autoGitInit` | `false` (bundled patch: `true`) | `tower_init` may run `git init` + an empty initial commit when `repoRoot` is an absolute, existing directory that is not a repository. |
 | `init.snapshotDirty` | `false` | `tower_init` may snapshot uncommitted **tracked** changes into a dangling commit used as the mission baseline (untracked files are not included; the commit is kept alive under `refs/tower/snapshot/*`). |
+| `init.autoExclude` | `true` | Append in-repo artifacts (`MISSIONS.md`, in-repo worktree roots) to `.git/info/exclude`; never touches `.gitignore`. |
 | `mode.promptSection` | `''` | Replacement prompt text (takes precedence over `section` when both set). |
 | `mode.sectionAppend` | `''` | Extra text appended after the reminder (team conventions). |
 | `mode.allowAgentControl` | `true` | Register `tower_control`; the model may enter/leave with a reason. Set `false` for human-only mode control. |
 | `mode.autoPauseGoal` | `true` | Pause an active goal on entry; the goal is never auto-resumed on exit. |
 | `mode.requireResumeAuthorization` | `false` | Resuming a mission paused with `pauseCause:user` requires an `authorization` reference. |
+| `mode.requireHumanAckOnFirstEntry` | `false` | Require a human `/tower ack` before the model may make the first Tower-mode entry in a session. |
 | `mode.workspaceLock` | `false` (bundled patch: `true`) | Allow only one Tower session per repository (`tower.lock`); others get `workspace-busy`. |
 | `mode.workspaceLockScope` | `all` | `all` locks every repo tool; `mutations` skips the workspace lock for read-only tools. |
 | `mode.planModePolicy` | `clear` | Tower entry clears an active plan mode (or `refuse` until the plan is exited); a pre-step also clears a plan activated later. |
@@ -83,10 +85,11 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
 | `gates.allowReviewExemption` | `false` | With `review.requireReview:true`, allow `reviewPolicy:"none"` + a non-empty reason to skip review blockers. Off deliberately; irrelevant while the global review gate is off. |
 | `docs.board` | `true` | Write `MISSIONS.md` after mutations. |
 | `docs.boardLocation` | `common` | `common` = `<git-common-dir>/dsh-tower/MISSIONS.md`; `repo` = `<repoRoot>/MISSIONS.md`. |
+| `tools.exposeOperational` | `true` | Register batch/resource/import/legacy/recover/test/doctor tools; `false` shrinks the fixed tool-schema context. |
 | `leases.ttlMs` | `900000` | Default advisory lease lifetime; expiry never auto-releases. |
 | `dev.hotReload` | `true` | Register `tower_reload`; `/tower reload` is disabled when off. It returns `reload-unavailable` when the profile has no HMR service. |
 | `dev.reloadDelayMs` | `50` | Delay before a scheduled reload so the tool result is delivered first. |
-| `dev.reloadRequiredIds` | four Tower loader ids | Entry ids passed to `reconcileProfile` as required. |
+| `dev.reloadRequiredIds` | five Tower loader ids | Entry ids passed to `reconcileProfile` as required. |
 
 ## Example
 

package/docs/reference/errors.generated.md

@@ -0,0 +1,39 @@
+# Error code catalog (generated)
+
+> Generated by `npm run docs:generate:errors` from `domain/errors.js`. Do not edit by hand.
+
+| Code | Description |
+|---|---|
+| `invalid-argument` | A tool argument is missing, malformed, or not allowed. |
+| `repo-invalid` | repoRoot is missing, relative, or not inside a Git repository. |
+| `not-initialized` | Tower is not initialized for this repository; run tower_init. |
+| `mission-not-found` | No mission with that id exists. |
+| `finding-not-found` | No finding with that id exists. |
+| `invalid-transition` | The requested state transition is not allowed. |
+| `stale-base` | The repository state changed while the operation was being prepared; retry. |
+| `state-locked` | Another Tower writer holds the state lock. |
+| `state-corrupt` | The Tower state file is unreadable or invalid. |
+| `config-invalid` | Tower configuration is invalid. |
+| `config-unknown-key` | Tower configuration has an unknown top-level key. |
+| `git-failed` | A git command failed. |
+| `git-timeout` | A git command timed out or exceeded its output buffer. |
+| `worktree-dirty` | The mission worktree has uncommitted changes and cannot complete. |
+| `spawn-unavailable` | The subagents service is unavailable. |
+| `provider-missing` | No subagent provider is registered. |
+| `provider-cooldown` | The provider is throttled; spawn is in a short cooldown. |
+| `preset-missing` | The configured agent preset is not registered. |
+| `reviewer-prerequisite` | The reviewer spawn prerequisite is not met. |
+| `not-authorized` | The calling agent role may not perform this action. |
+| `workspace-busy` | Another Tower session owns this repository workspace lock. |
+| `worker-limit` | The repository reached spawn.maxLiveWorkers live workers. |
+| `rate-limited` | The tower_send per-minute rate limit was reached. |
+| `takeover-refused` | The mission already has a live worker that was not stopped first. |
+| `reload-unavailable` | The DSH HMR service is not available in this profile. |
+| `reload-failed` | The HMR reload failed; check the DSH log and restart if needed. |
+| `tests-failed` | Declared test discovery failed or did not meet its admission requirements. |
+| `tests-timeout` | Test discovery exceeded its time or output budget. |
+| `lease-busy` | Another holder owns the requested advisory lease. |
+| `lease-token` | The lease release token does not match the current holder. |
+| `batch-invalid` | The batch request or its close evidence is invalid. |
+| `legacy-invalid` | The legacy snapshot or mapping is invalid. |
+| `tool-internal` | An unexpected failure; read the message and the activity log. |

package/docs/reference/errors.md

@@ -2,7 +2,7 @@
 
 Tool failures are thrown errors, not `{ok:false}` results (gate outcomes are the exception: see
 [blockers.md](blockers.md)). Every thrown error carries a stable code as a message prefix. This
-release defines 31 tool error codes.
+release defines 33 tool error codes.
 
 Every `TowerToolError` also carries `retryable` (boolean), `nextAction` (string or `null`) and `details`
 (structured context or `null`) for programmatic callers; the message prefix remains the stable contract
@@ -13,7 +13,7 @@ for text-only clients.
 ```
 
 Callers can match the prefix instead of the prose. Codes are reserved for the conditions below; a
-message without a more specific match is reported as `tool-internal`.
+plain `Error` without a structured code is reported as `tool-internal`.
 
 | Code | Meaning | Typical trigger |
 |---|---|---|
@@ -23,6 +23,7 @@ message without a more specific match is reported as `tool-internal`.
 | `mission-not-found` | No mission with that id exists. | a stale or mistyped `M9` |
 | `finding-not-found` | No finding with that id exists. | `tower_findings({id:"F99"})` |
 | `invalid-transition` | The requested state transition is not allowed. | a blocked→merged attempt; a finding transition not in the graph; a reviewer mutating findings; completing a mission with open tasks, blockers, no commits, or unread inbox messages. |
+| `stale-base` | The repository state changed while the operation was being prepared; retry. | two-phase mutation revalidation |
 | `worktree-dirty` | The mission worktree has uncommitted changes and cannot complete. | staged, modified, or untracked files left behind before `tower_complete` |
 | `state-locked` | Another Tower writer holds the state lock. | concurrent mutation after the lock timeout |
 | `state-corrupt` | The Tower state file is unreadable or invalid. | hand-edited `state.json` |
@@ -32,6 +33,7 @@ message without a more specific match is reported as `tool-internal`.
 | `git-timeout` | A git command timed out or exceeded its output buffer. | slow pre-merge hook, huge diff |
 | `spawn-unavailable` | The subagents service is unavailable. | a Host without `subagents` |
 | `provider-missing` | No subagent provider is registered. | an empty provider list |
+| `provider-cooldown` | spawn is in a short cooldown after repeated retryable provider failures. | wait for `blockedUntil`, then retry |
 | `preset-missing` | The configured agent preset is not registered. | missing `tower-worker`/`tower-reviewer` preset rows, DSH not restarted |
 | `reviewer-prerequisite` | The reviewer spawn prerequisite is not met. | reviewer spawned before the mission is `completed`, or before a worktree exists |
 | `not-authorized` | The calling agent role may not perform this action. | a worker calling a tower-only tool or changing mission status/scope; a reviewer mutating findings |