dsh-tower 2.3.0 → 2.4.1

package/docs/agents/workflow.md

@@ -24,7 +24,7 @@ This repository uses two workflows together. They are not alternatives: the **Ma
    - **Parallel or long-lived wave (architecture epics, >3 tickets, review needed):** **Tower**. `tower_init` → `tower_plan` with one mission per ticket, `scope` = the ticket's write fence, `deps` = the ticket's blocking edges → `tower_spawn` a worker per mission → optional reviewer (`tower-reviewer`) → `tower_merge` (gate checks scope, branch freshness, review, tasks) → `tower_teardown`. Tower's persistent state makes the wave resumable after a restart.
    - Never run both orchestrators over the same files at once.
 4. **Build.** Each unit starts with `/tdd`: one failing test, then the implementation, then the next slice. Commit messages carry `Refs #n`; the completing commit uses `Fixes #n`. Workers do not merge; they hand off a branch.
-5. **Verify before landing.** Run `npm test`, `npm run docs:check`, all four `docs:check:generated*`, `npm run pack:check`, `npm run architecture:check`, `npm run types:check`, `npm run domain:check`. Bundle changes also run `npm run smoke:mount`. CI must be green on the required checks (`test (22)`, `test (24)`, `test (22, windows)`, `mount`). Then `/code-review` runs both axes on the diff (Standards against CONTRIBUTING/architecture docs, Spec against the ticket); every finding is fixed in the same PR or explicitly deferred with a reason.
+5. **Verify before landing.** Run `npm test`, `npm run docs:check`, all five `docs:check:generated*` (including the generated type vocabulary), `npm run pack:check`, `npm run architecture:check`, `npm run types:coverage`, `npm run types:strict:check`, `npm run types:check` (both tsconfigs), `npm run domain:check`. Bundle changes also run `npm run smoke:mount`. CI must be green on the required checks (`test (22)`, `test (24)`, `test (22, windows)`, `mount`). Then `/code-review` runs both axes on the diff (Standards against CONTRIBUTING/architecture docs, Spec against the ticket); every finding is fixed in the same PR or explicitly deferred with a reason.
 6. **Land.** PR body follows the four-line contract (failure mode → change → test that fails without it → blast radius). `main` is protected: PR + required checks, admins included, no force-push. A closure comment carries `verified-by: <test file>` and `commit: <sha>`; `npm run audit:issues` flags closures whose evidence is missing.
 7. **Release.** `release:check` compares the version, the previous tag and the CHANGELOG; a tag push fails when the version did not move or the tag does not match. Releases are either **tag-only** (version + changelog + compatibility row + annotated tag; no npm publish, no GitHub Release) or **published** (adds the human `npm publish --tag latest` with 2FA, `dist-tags` verification, then the GitHub Release). The mode is recorded in the milestone/plan.
 8. **Learn.** After a release (or a wave that went sideways) run `/retro`: mechanical mistakes become deterministic checks (scripts, CI jobs, preflight), judgement calls become written standards. Periodically run `/improve-codebase-architecture` for deepening opportunities and `/domain-modeling` to keep the vocabulary and ADRs (2.3.0) honest.

package/docs/architecture/overview.md

@@ -2,17 +2,78 @@
 
 ## 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.
+Since #121 the bundle ships a mandatory host anchor plus individually switchable
+optional rows: `cordis.patch.yml` declares top-level `tower` (a `cordis:group`
+that mounts the Host plugin and the mandatory worker preset), then
+`tower-skills`, `tower-batch`, `tower-import`, `tower-leases`, `tower-tests`,
+`tower-hmr` (shipped off) and `preset-tower-reviewer`. Turning one optional row
+off removes exactly that capability; the host, the diagnostics and the recovery
+escape keep working.
+
+[Principle 11](../../PRINCIPLES.md) and
+[ADR 0005](../adr/0005-component-surface.md) say a component may exist only for
+a capability whose off state leaves the rest intact, and that the host, health,
+recovery, review and merge-gate capabilities are never switches. Which keys are
+allowed to be switches is a table lookup in
+[component-surface.md](../reference/component-surface.md), generated from
+`scripts/component-surface.json`; the component count is baselined and checked by
+`npm run docs:check:components`. That gate also refuses a `tools.expose*` route
+to a tool that is not on the recorded allowlist (empty since #122) and any
+`cordis.patch.yml` row that defaults a forbidden key off.
+
+### Row display metadata (#121)
+
+The Plugins page renders an optional row as `row.meta.title ?? row.moduleName`
+plus `row.meta.description`. The Host fills `row.meta` by resolving
+`<specifier>/locale/en.json` and then every sibling `<lang>.json` in that
+directory, reading `meta.title` / `meta.description`; title falls back to the full
+module specifier and description to empty when no resource resolves. That is why
+the mandatory `tower` card explains itself (the package root ships
+`locale/*.json`) while a bare subpath row would show only `dsh-tower/batch`.
+
+Each optional capability therefore ships its own resolvable subpath resource:
+`dsh-tower/skills/locale/{en,zh}.json` and the same for `batch`, `import`,
+`leases`, `tests` and `hmr`. `package.json` `exports` maps every
+`./<capability>/locale/*.json` to `./locale/<capability>/*.json`, and
+`files: ["locale/"]` ships the nested tree, so the lookup matches the installed
+package. The root `./locale/*.json` export stays so the Tower group keeps its own
+`meta`.
+
+The capability files are generated, never hand-written. `npm run
+docs:generate:locale` renders them from the `components` block of
+`locale/en.json` and `locale/zh.json` (the same source `docs:check:components`
+audits): `meta.title` is the component `title`, and `meta.description` joins the
+component `summary` (what the capability enables) with its `disables` text (what
+turning it off removes) behind a per-language "When off / 关闭后" label. The
+row is therefore decidable from the page alone. `npm run
+docs:check:generated:locale` fails on drift, runs in `npm run check`, and is its
+own step in the `test` CI job (`.github/workflows/test.yml`).
+
+To label a new capability row:
+
+1. Classify it in `scripts/component-surface.json`, ship it in
+   `cordis.patch.yml`, and add `title` / `summary` / `disables` to the
+   `components` block of both `locale/en.json` and `locale/zh.json`.
+2. Add `{ specifier, component }` to `CAPABILITY_LOCALES` in
+   `scripts/generate-capability-locale.mjs`, the matching
+   `./<specifier>/locale/*.json` export in `package.json`, and the row to the
+   coverage map in `tests/capability-locales.test.mjs`.
+3. Run `npm run docs:generate:locale`, then regenerate
+   `scripts/pack-manifest.txt` with `npm run pack:check -- --write`.
+
+The reviewer preset row is the one visible component that is not a package
+specifier: its label comes from the `cordis.patch.yml` preset `config.name` /
+`description`. The generated capability files never touch the root locale `meta`.
 
 ```
 Host plugin (index.js)
- ├─ /tower command + Tower mode (guard, prompt section, tower_mode/tower_control, /tower reload)
+ ├─ /tower command + Tower mode (guard, prompt section, tower_mode/tower_control)
  ├─ host/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)
+ │                    (+ 21 define()-registered host tools)
+ │                    (+ tower_mode/tower_control registered by the Host entry, 29 total
+ │                       once every optional capability row is on)
+ │                    (tower_doctor/tower_recover are host tools, never switches)
+ ├─ host/capability-*.js -> optional capability entry points (batch/import/leases/tests/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
@@ -24,6 +85,7 @@ Host plugin (index.js)
        host/tool-registry.js   registration aggregator + shared guards/helpers
        host/config.js          profile/repo config layers over the pure schema
        host/doctor.js          read-only environment contract and health checks
+       host/capability-registry.js  mounted-component report for status/doctor
        host/hmr.js             optional DSH HMR bridge (tower_reload / /tower reload)
        host/modeStore.js       per-agent Tower mode persistence
        host/modeState.js       owned in-memory mode state

package/docs/guide/hot-reload.md

@@ -26,8 +26,8 @@ This page covers the development loop. It is not required to use Tower.
   `plugin_manager`); it compares already-loaded modules with disk and replaces the changed ones even
   with `root: []`. Watching only makes that happen automatically after a save.
 - HMR is only mounted for profile boots (`disabled` when there is no `profileContext`). A process
-  booted without a profile reports reload as unavailable (`tower_reload` stays registered while
-  `dev.hotReload` is on, so the tool returns `reload-unavailable` instead of disappearing).
+  booted without a profile reports reload as unavailable (`tower_reload` stays registered while the
+  `tower-hmr` component row is on, so the tool returns `reload-unavailable` instead of disappearing).
 - The profile patch layer is loaded when DSH boots. Editing it — in practice the hmr `root` list —
   takes effect after **one DSH restart**. Nothing in the running process re-reads the HMR row's own
   configuration.
@@ -99,9 +99,9 @@ The bridge behind the tool follows the `dev` config group:
 
 | Config key | Meaning |
 |---|---|
-| `dev.hotReload` | Register `tower_reload`; `/tower reload` is disabled when off (default `true`). Without the HMR service the tool is still registered so it can return `reload-unavailable`. |
+| `tower-hmr` (component row) | The switch: on registers `tower_reload` and `/tower reload`, off reports "disabled by component tower-hmr". The row ships off; enable it from the plugin page for a linked dev profile. `dev.hotReload` was removed in 2.4.0 and is now an unknown key. |
 | `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-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. |
+| `dev.reloadRequiredIds` | Loader entry ids the profile must keep active (default `tower`, `tower-host`, `preset-tower-worker`). An inactive required entry is reported as a reload failure even if it was already inactive. Optional capability rows are deliberately not required, so a row switched off is not a reload failure. |
 
 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

@@ -45,6 +45,19 @@ The Host plugin loads at DSH startup: **restart DSH after install or update**.
   overlapping and case-only mismatches are no longer refused by the out-of-scope gate. Stored scope
   strings are never rewritten: the board keeps showing what the operator typed.
 
+- **2.3.0 → 2.4.0 (unreleased)**: the single `tower-bundle` group row is gone. `cordis.patch.yml`
+  now ships the mandatory `tower` host anchor (the Host plugin and the worker preset are its internal
+  sections) plus individually switchable top-level rows: `tower-skills`, `tower-batch`, `tower-import`,
+  `tower-leases`, `tower-tests`, `tower-hmr` (shipped off) and `preset-tower-reviewer` (conditional on
+  `review.requireReview`). The `tools` config group and `dev.hotReload` were removed: a profile that
+  still carries them is now rejected as an unknown key (`config-unknown-key`) and the host stops
+  mounting until they are deleted, so no silent no-op switch remains. Move each capability to its row
+  in the plugin page instead; `tower-hmr` ships off, so `tower_reload` and `/tower reload` are reported
+  as "disabled by component tower-hmr" until you enable it for a linked dev profile. `tower_doctor` and
+  `tower_recover` are registered for every configuration and need no key. The reviewer row may be off
+  only while `review.requireReview` is false; with the gate on, planning and mode entry refuse the
+  combination with an explanatory error. No state migration is needed.
+
 - **2.0.4 → 2.1.0-beta.1**: no config migration; the state file migrates automatically (v1/v2 → v3) as
   described above. This is a **pre-release** published on the
   `next` dist-tag, so `latest` still resolves to 2.0.4 — install it with

package/docs/operations/security.md

@@ -104,7 +104,7 @@ Tower work, and run the host under OS-level isolation.
   cannot make those safe; review hooks before running Tower on an untrusted repository.
 - **Package test commands.** Declared discovery commands have the same trust as repository hooks; a
   malicious `package.json` can run code. Disable `tests.allowPackageDiscovery` and review the file.
-- **HMR reload.** With `dev.hotReload`, `/tower reload`/`tower_reload` asks DSH to re-import the plugin
+- **HMR reload.** With the `tower-hmr` component row on, `/tower reload`/`tower_reload` asks DSH to re-import the plugin
   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.

package/docs/reference/component-surface.md

@@ -0,0 +1,135 @@
+# Component surface (generated)
+
+> Generated by `npm run docs:generate:components` from `scripts/component-surface.json` and
+> `scripts/surface-baseline.json`. Do not edit by hand.
+
+Decision: [ADR 0005](../adr/0005-component-surface.md) · decision date: 2026-10-23 · baseline 2026-10-23 · visible components: 8 (`tower`, `tower-skills`, `tower-batch`, `tower-import`, `tower-leases`, `tower-tests`, `tower-hmr`, `preset-tower-reviewer`)
+
+The component axis answers one question for every config key: may a user turn it
+off, and if so, must that switch be a component? Four classes cover every key, so
+"should this be a component?" is a table lookup rather than a judgement call.
+
+| Class | Meaning |
+|---|---|
+| `core` | Removing it breaks the Tower contract. It is never a switch. |
+| `optional-component` | A capability whose off state leaves the rest of Tower intact. It must be a user-visible switch with a documented fallback. |
+| `optional-config` | A tuning knob, not a capability. It stays in the config form and never hides a component. |
+| `forbidden-to-disable` | The host, the health contract, the recovery escape, the review contract and the merge gates. No group, row or boolean key may turn it off. |
+
+## Components
+
+The shipped `cordis.patch.yml` rows, with the fallback contract each off state
+must satisfy. A visible row is a component the plugin page may switch; an internal
+row is a section of its parent and is not independently switchable.
+
+| Component | Scope | Kind | Off state and fallback |
+|---|---|---|---|
+| `tower` | visible | group | Off equals uninstalling Tower: no tools, presets or skills remain. That is the accepted all-off boundary of the mandatory host anchor, not an optional capability. |
+| `tower-host` | internal | row | The Host plugin itself, nested under the mandatory tower anchor. A mandatory dependency, never its own switch. |
+| `tower-skills` | visible | row | The 3 skills leave the catalog; the worker/reviewer PROTOCOL sections still ship through systemPrompt.section, so only the tower-recovery guidance is lost. |
+| `tower-batch` | visible | row | tower_batch is not registered; missions, gates and merges are unaffected because no state depends on a batch. |
+| `tower-import` | visible | row | tower_import_legacy and tower_legacy_map are not registered; new repository state is unaffected. |
+| `tower-leases` | visible | row | tower_resource is not registered; advisory leases are coordination only, so nothing else depends on them. |
+| `tower-tests` | visible | row | tower_test is not registered and no test receipt can be recorded. With gates.requireTests:true planning/mode entry is rejected with an explanation, and the merge gate still reports tests-missing. |
+| `tower-hmr` | visible | row | tower_reload and /tower reload are unavailable; a profile without HMR behaves exactly as before. Shipped disabled: enable the row for a linked dev profile. |
+| `preset-tower-worker` | internal | row | tower_spawn fails without the worker preset. A mandatory dependency, never a switch. |
+| `preset-tower-reviewer` | visible | row | The reviewer cannot be dispatched. Supported while review.requireReview is false (merge is unaffected); with the gate on planning/mode entry is locked with an explanatory error. |
+
+## Forbidden to disable
+
+The host, the health contract, the recovery escape, the review contract and the
+merge gates are configuration or code, never switches. `npm run
+docs:check:components` derives the live disablers from `host/tool-registry.js`
+and `cordis.patch.yml`; a disabler that is not recorded here fails the gate.
+
+| Capability | Why it may not be disabled | Recorded disablers | Decision |
+|---|---|---|---|
+| the Tower host | Without the host the plugin registers nothing; there is no off state that leaves the rest working, and no config boolean may remove it. The visible `tower` anchor is the all-off boundary, and the host section nested under it may never become its own switch. | none | none may exist |
+| tower_doctor (read-only health contract) | Diagnosis must always exist so a failure message can point at it. #122 removed exposeDoctor and the exposeOperational master switch; the tool is registered for every configuration. | none | none may exist |
+| tower_recover (stale state-lock escape) | The escape hatch must exist whenever the lock it repairs can be left behind. #122 removed exposeRecovery and the exposeOperational master switch; the tool is registered for every configuration. | none | none may exist |
+| the review contract | review.requireReview is a merge blocker, not a component; a row may not switch it off. The reviewer row is conditional, not a way to weaken the gate. | none | none may exist |
+| the merge gates | gates.* decides delivery; a component may not bypass it. | none | none may exist |
+
+## Gateable tools
+
+The allowlist of boolean routes in `host/tool-registry.js`. Every shipped
+`tools.expose*` route must match this table. A route to a tool that is not listed
+here is refused, so no boolean key can quietly remove a review, merge or host
+tool. Since #122 the shipped table is empty: `tower_doctor` and `tower_recover`
+are registered for every configuration and no other capability may become a
+boolean switch.
+
+| Tool | Switch key |
+|---|---|
+| _(none)_ | — |
+
+## Config keys
+
+All keys from `domain/config/schema.js`, classified on the component axis.
+
+| Key | Component class | Decision note |
+|---|---|---|
+| `section` | `core` | Legacy alias for mode.promptSection: the Tower-mode prompt contract, not a capability. |
+| `allowAgentControl` | `core` | Legacy alias for mode.allowAgentControl: the human-owned mode rule (ADR 0003), not a component. |
+| `init.autoGitInit` | `optional-config` | Bootstrap convenience; off only means tower_init will not run git init. |
+| `init.snapshotDirty` | `optional-config` | Dirty-work baseline convenience; no capability is removed. |
+| `init.autoExclude` | `optional-config` | Keeps Tower artifacts out of .git/info/exclude; safe either way. |
+| `mode.promptSection` | `core` | Replaces the whole Tower-mode prompt text; contract text, not a capability. |
+| `mode.sectionAppend` | `optional-config` | Appends team conventions to the prompt. |
+| `mode.allowAgentControl` | `core` | Decides whether the model may toggle the mode (ADR 0003). A governance rule, never a component. |
+| `mode.autoPauseGoal` | `core` | Entering the mode pauses an active goal; exit never resumes it. |
+| `mode.requireResumeAuthorization` | `core` | Guards resuming a user-paused mission. |
+| `mode.requireHumanAckOnFirstEntry` | `core` | First entry can require an explicit human ack. |
+| `mode.workspaceLock` | `core` | One Tower session per repository is a safety contract; a row may not turn it off. |
+| `mode.workspaceLockScope` | `optional-config` | Chooses whether read-only tools take the workspace lock. |
+| `mode.planModePolicy` | `core` | Plan mode and Tower mode stay mutually exclusive. |
+| `mode.workspaceStaleMs` | `optional-config` | Stale window for the advisory workspace lock. |
+| `mode.heartbeatMs` | `optional-config` | Heartbeat interval while the mode is on. |
+| `mode.denyTools` | `core` | The denied-tool list is part of the mode guard. |
+| `mode.storePath` | `optional-config` | Custom mode-store location; no capability is removed. |
+| `mode.maxEntries` | `optional-config` | Bounds the persisted mode store. |
+| `mode.lockTimeoutMs` | `optional-config` | Bounded wait for the cross-process mode lock. |
+| `review.requireReview` | `forbidden-to-disable` | Turns independent review into a merge blocker; no component may switch it off. With it on, the preset-tower-reviewer row may not be off (planning/mode entry refuse the combination). |
+| `review.maxRoundsPerReviewer` | `forbidden-to-disable` | Caps review rounds; part of the review contract. |
+| `merge.timeoutMs` | `optional-config` | Default merge timeout; a per-call value wins. |
+| `merge.maxBufferBytes` | `optional-config` | Captured merge output buffer. |
+| `git.timeoutMs` | `optional-config` | Default Git command timeout outside merge. |
+| `worktrees.root` | `optional-config` | Default worktree placement. |
+| `spawn.workerPreset` | `core` | Chooses the worker tool surface; a dependency, never a switch. |
+| `spawn.reviewerPreset` | `core` | Chooses the read-only reviewer surface; a dependency, never a switch. |
+| `spawn.maxDepth` | `optional-config` | Subagent depth requested at spawn. |
+| `spawn.provider` | `optional-config` | Provider route for spawned agents. |
+| `spawn.workerModel` | `optional-config` | Optional model route for workers. |
+| `spawn.reviewerModel` | `optional-config` | Optional independent model route for reviewers. |
+| `spawn.maxLiveWorkers` | `core` | Resource-safety cap on live workers. |
+| `spawn.staleMs` | `optional-config` | Roster staleness window before merge is blocked. |
+| `spawn.maxWaitMs` | `optional-config` | Upper bound for a blocking spawn wait. |
+| `spawn.requireLease` | `optional-config` | Advisory-lease gate before a worker starts. |
+| `send.maxPerMinute` | `optional-config` | Message rate limit; zero disables it. |
+| `send.interruptDefault` | `optional-config` | Default for the interrupt-before-deliver flag. |
+| `tests.enabled` | `optional-component` | Tuning inside the optional tower-tests component: it decides whether discovery runs when the row is on. Off with gates.requireTests:true is rejected at config resolution. |
+| `tests.admission` | `optional-config` | Chooses when discovery runs inside the optional tests capability. |
+| `tests.timeoutMs` | `optional-config` | Per-command discovery timeout. |
+| `tests.maxBytes` | `optional-config` | Captured discovery output cap. |
+| `tests.autoChecks` | `optional-config` | Attaches a tests check to completion when discovery runs. |
+| `tests.allowPackageDiscovery` | `core` | Allows repository code to execute; a security contract, not a component. |
+| `gates.requireChecks` | `forbidden-to-disable` | Requires completion evidence before merge; a merge gate. |
+| `gates.requireTests` | `forbidden-to-disable` | Requires a test receipt before merge; a merge gate. With the tower-tests row off, planning/mode entry refuse the combination. |
+| `gates.allowReviewExemption` | `forbidden-to-disable` | The review-exemption path is part of the review and merge contract. |
+| `gates.maxReportBytes` | `forbidden-to-disable` | The report cap is part of the completion contract; the refusal itself is never configurable away. |
+| `docs.board` | `optional-config` | Writes the human-readable board; no capability is removed. |
+| `docs.boardLocation` | `optional-config` | Chooses the board location. |
+| `archive.enabled` | `optional-config` | Archival is maintenance, not a tool capability; off only leaves terminal missions hot. |
+| `archive.afterDays` | `optional-config` | Archive age threshold. |
+| `archive.maxMissions` | `optional-config` | Hot terminal-mission cap. |
+| `leases.ttlMs` | `optional-config` | Tuning inside the optional tower-leases component. |
+| `dev.reloadDelayMs` | `optional-config` | Delay so a tool result is delivered before a scheduled reload inside the optional tower-hmr component. |
+| `dev.reloadRequiredIds` | `optional-config` | Loader ids passed to reconcileProfile as required by the tower-hmr component. |
+
+## Non-goals
+
+This page does not decide whether a key is useful, and it is not an approval
+process. It records the class so the gate can refuse an unclassified or
+forbidden surface.
+
+Enforced by: `scripts/check-components.mjs`; tests in `tests/components.test.mjs`; gate: `npm run docs:check:components`.

package/docs/reference/config.generated.md

@@ -1,7 +1,7 @@
 # Config reference (generated)
 
 > Generated by `npm run docs:generate:config` from `domain/config/schema.js`. Values are defaults before repo config.
-> Surface: config keys: 64 · sections: 15 · tools: 27 · baseline 2026-10-23. Generated from `scripts/surface-baseline.json`; do not edit by hand.
+> Surface: config keys: 56 · sections: 14 · tools: 29 · baseline 2026-10-23. Generated from `scripts/surface-baseline.json`; do not edit by hand.
 
 | Key | Default | Description |
 |---|---|---|
@@ -58,14 +58,6 @@
 | `archive.enabled` | `true` | Move terminal (merged/abandoned) missions whose worktree is gone into <git-common-dir>/dsh-tower/archive/ at the next mutation, so state.json stops carrying their full history. |
 | `archive.afterDays` | `30` | Terminal missions untouched for at least this many days are archived on the next mutation (0 archives them immediately). |
 | `archive.maxMissions` | `100` | Maximum terminal missions kept hot; once exceeded, the oldest eligible terminal missions are archived until the cap holds (0 archives every eligible terminal mission). |
-| `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. |
+| `dev.reloadRequiredIds` | `["tower","tower-host","preset-tower-worker"]` | Loader entry ids passed to reconcileProfile as required. Optional component rows are deliberately not required, so a row switched off is not a reload failure. |

package/docs/reference/config.md

@@ -74,14 +74,14 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
 | `spawn.requireLease` | `''` | Optional lease name that must be held before a worker can spawn. |
 | `send.maxPerMinute` | `120` | Per-repository `tower_send` rate limit (0 disables); exceeding it returns `rate-limited`. |
 | `send.interruptDefault` | `false` (bundled patch: `true`) | Default for `tower_send.interrupt` (interrupt the running turn before delivering). |
-| `tests.enabled` | `true` | Run declared test discovery when the worktree `package.json` configures it. |
+| `tests.enabled` | `true` | Run declared test discovery when the worktree `package.json` configures it. It only tunes the optional `tower-tests` component: with that row off there is no `tower_test` tool and no receipt, and `gates.requireTests:true` is refused rather than silently unmet. |
 | `tests.admission` | `off` | `spawn` runs discovery before starting a worker, `complete` at `tower_complete`, `off` only on explicit `tower_test` (default; repository code is not executed automatically). |
 | `tests.timeoutMs` | `60000` | Per discovery command timeout. |
 | `tests.maxBytes` | `16777216` (16 MiB) | Captured stdout cap per command. |
 | `tests.autoChecks` | `true` | Attach an automatic `tests` check to the completion report. |
 | `tests.allowPackageDiscovery` | `true` | Allow repo-controlled `tower.testDiscovery` commands (executes worktree code; see security). |
 | `gates.requireChecks` | `false` | Require at least one `tower_complete.checks` entry before merge (`no-check-evidence`). |
-| `gates.requireTests` | `false` | Require a passing discovery receipt for the current mission branch tip (`tests-missing`); independent of the review gate. |
+| `gates.requireTests` | `false` | Require a passing discovery receipt for the current mission branch tip (`tests-missing`); independent of the review gate. With the `tower-tests` component row off, planning/mode entry refuse this combination with an explanation. |
 | `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. |
 | `gates.maxReportBytes` | `32768` (32 KiB) | Hard cap in UTF-8 bytes for `tower_complete.report`. A larger report is rejected with `invalid-argument` and an actionable `nextAction` (file the full text in the mission worktree and reference its path); it is never truncated. Existing larger reports still load. |
 | `docs.board` | `true` | Write `MISSIONS.md` after mutations. |
@@ -89,16 +89,14 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
 | `archive.enabled` | `true` | Move terminal (`merged`/`abandoned`) missions whose worktree is gone into `<git-common-dir>/dsh-tower/archive/` at a mutation boundary. Archived missions keep tasks, reviews, findings and the completion report; they are moved, never deleted. |
 | `archive.afterDays` | `30` | Age trigger: a terminal mission untouched for at least this many days is archived on the next mutation (`0` archives immediately). |
 | `archive.maxMissions` | `100` | Cap trigger: once more than this many terminal missions are hot, the oldest eligible ones are archived until the cap holds (`0` archives every eligible terminal mission). A mission with a live worktree is never archived. |
-| `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` | five Tower loader ids | Entry ids passed to `reconcileProfile` as required. |
+| `dev.reloadDelayMs` | `50` | Delay before a scheduled reload so the tool result is delivered first. Tuning inside the optional `tower-hmr` component. |
+| `dev.reloadRequiredIds` | three Tower loader ids | Entry ids passed to `reconcileProfile` as required by the `tower-hmr` component. Optional component rows are deliberately not required. |
 
 ## Example
 
 ```yaml
-- id: tower
+- id: tower-host
   name: 'dsh-tower'
   config:
     mode:
@@ -113,10 +111,14 @@ violates the declared schema (for example `merge.timeoutMs` below 1000) fail wit
       reviewerModel:
         provider: deepseek-account
         model: deepseek-flash
-    dev:
-      hotReload: true
 ```
 
+The optional capabilities (`tower-skills`, `tower-batch`, `tower-import`,
+`tower-leases`, `tower-tests`, `tower-hmr`, `preset-tower-reviewer`) are switched
+from the plugin page, not from a config key. The keys that used to switch them
+(`tools.expose*`, `dev.hotReload`) were removed in 2.4.0 and are rejected as
+unknown keys.
+
 ## Looking up the effective schema
 
 `cordis_inspect_query` with `Config.listConfigs({ name: "dsh-tower" })` returns the projected JSON

package/docs/reference/doctor.md

@@ -8,17 +8,17 @@ It returns:
   "ok": true,
   "checks": [
     { "id": "git", "status": "pass", "detail": "git version 2.55.0" },
-    { "id": "surface", "status": "pass", "detail": "config keys: 64 · sections: 15 · tools: 27 (baseline 2026-10-23)" },
+    { "id": "surface", "status": "pass", "detail": "config keys: 56 · sections: 14 · tools: 29 (baseline 2026-10-23)" },
     { "id": "state", "status": "pass", "detail": ".../state.json revision 7" },
     { "id": "state-schema", "status": "pass", "detail": "schemaVersion 3 is current" },
     { "id": "case-mode", "status": "pass", "detail": "caseInsensitive: true; scope matching uses case-insensitive comparison" }
   ],
   "surface": {
-    "configKeys": 64,
-    "sections": 15,
-    "tools": 27,
+    "configKeys": 56,
+    "sections": 14,
+    "tools": 29,
     "baselineDate": "2026-10-23",
-    "line": "config keys: 64 · sections: 15 · tools: 27"
+    "line": "config keys: 56 · sections: 14 · tools: 29"
   },
   "stateLock": {
     "held": true,
@@ -67,10 +67,15 @@ It returns:
 
 `surface` (and the `surface` check) reports the concept budget in the same format
 as the generated references: `config keys: N · sections: N · tools: N`, plus the
-committed baseline date from `scripts/surface-baseline.json`. The counts are live
-(the config schema and the defined tool surface, independent of the operational
-switches); `npm run surface:check` is what fails when a count grew without an ADR
-or a matching deletion. See
+committed baseline date from `scripts/surface-baseline.json`. The counts are live:
+the config schema and every tool the build ships — `define()`-registered tools,
+the `tower_mode`/`tower_control` pair the Host entry registers directly (#118),
+and the capability tools whose optional component row may be off (#121) —
+independent of the operational switches. The `tools` count is therefore the full
+build surface (29 in 2.4.0), even though the shipped profile mounts 28 because
+`tower-hmr` ships off; the `components` check names the mounted subset and every
+disabled row. `npm run surface:check` is what fails when a count grew without an
+ADR, a matching deletion or a recorded measurement correction. See
 [surface-budget.md](surface-budget.md) for the classification table.
 
 `stateSchema` describes the file **on disk**, not the in-memory document: `currentVersion` is the

package/docs/reference/surface-budget.md

@@ -1,10 +1,12 @@
 # Surface budget
 
-The plugin measures its user-facing surface in three numbers: **config leaf keys**,
-**config sections**, and **registered tools**. The committed baseline is
-[`scripts/surface-baseline.json`](../../scripts/surface-baseline.json); the brake
-is `npm run surface:check`; the decision record is
-[ADR 0004](../adr/0004-surface-budget.md).
+The plugin measures its user-facing surface in four numbers: **config leaf keys**,
+**config sections**, **registered tools**, and **visible component rows**. The
+committed baseline is [`scripts/surface-baseline.json`](../../scripts/surface-baseline.json);
+the brakes are `npm run surface:check` for the first three and
+`npm run docs:check:components` for the component count; the decision records are
+[ADR 0004](../adr/0004-surface-budget.md) and
+[ADR 0005](../adr/0005-component-surface.md).
 
 Decision date: 2026-10-23
 
@@ -14,6 +16,37 @@ default a user may want to change, and `niche` was added for one workflow and
 must carry a removal note for the next minor. A live key or tool missing from
 these tables fails `npm run surface:check`.
 
+A second axis asks who may turn a key off. It is generated from
+[`scripts/component-surface.json`](../../scripts/component-surface.json) into
+[component-surface.md](component-surface.md): every key is `core`,
+`optional-component`, `optional-config` or `forbidden-to-disable`, and the
+component count is the fourth baselined surface, two-way: a contraction needs a
+dated decision just like growth does (`npm run docs:check:components`,
+[ADR 0005](../adr/0005-component-surface.md)). The same source of truth records
+the `gateableTools` allowlist; it is empty since #122, so a future
+`tools.expose*` route to any tool is refused before it can remove a review,
+merge or host tool.
+
+The 2.3.0 baseline counted 27 tools because it recorded only the `define()` path.
+`tower_mode` and `tower_control` are registered directly by `index.js`, so the
+shipped surface was always 29. The 27 → 29 step is an explicit
+*measurement correction* with a reason and date in
+[`scripts/surface-baseline.json`](../../scripts/surface-baseline.json) (see
+[ADR 0004](../adr/0004-surface-budget.md)), not surface growth; a later count
+change still needs an ADR or a provably matching deletion.
+
+The tool count is the **build** surface, not one profile's mounted subset (#121):
+the recorder includes every tool this build can register, so a component row that
+ships off (`tower-hmr`, whose `tower_reload` keeps the count at 29) does not
+shrink the budget. `tower_doctor` reports the same 29 and names the mounted
+subset through its `components` check; the mount smoke asserts the shipped
+profile's 28 loaded tools and pins 29 for the all-rows-on surface.
+
+#121 also shrank the config surface: the seven capability `tools.expose*` keys
+and `dev.hotReload` became component rows, so config keys went 64 → 56 and
+sections 15 → 14. Those are recorded shrank values in the committed baseline,
+not free growth: a later increase still needs its own decision.
+
 ## Config keys
 
 | Key | Class | Note |
@@ -71,53 +104,49 @@ these tables fails `npm run surface:check`.
 | `archive.enabled` | core | Controls whether terminal missions leave the hot state. |
 | `archive.afterDays` | tuning | Archive age threshold. |
 | `archive.maxMissions` | tuning | Hot terminal-mission cap. |
-| `tools.exposeOperational` | core | Master switch for the operational tool surface. |
-| `tools.exposeBatch` | core | Registers the evidence-batch tool. |
-| `tools.exposeImport` | core | Registers the legacy import tools. |
-| `tools.exposeLeases` | core | Registers advisory leases. |
-| `tools.exposeTests` | core | Registers test discovery; required when the test gate is on. |
-| `tools.exposeRecovery` | core | Registers the stale-lock escape hatch. |
-| `tools.exposeDoctor` | core | Registers the read-only health contract. |
 | `leases.ttlMs` | tuning | Default advisory lease lifetime. |
-| `dev.hotReload` | tuning | Registers the dev reload tool when HMR exists. |
 | `dev.reloadDelayMs` | tuning | Delay so a tool result is delivered before reload. |
 | `dev.reloadRequiredIds` | niche | Loader ids added for one linked-profile development setup. Removal note: derive the required ids from the bundle manifest in the next minor. |
 
 ## Tools
 
 Tools are `core` when the product does not work without them and `optional` when
-an operational switch (`tools.expose*`) or the dev mode can legitimately remove
-them from the surface.
+a component row (`tower-batch`, `tower-import`, `tower-leases`, `tower-tests`,
+`tower-hmr`), `mode.allowAgentControl`, or the dev mode can legitimately remove
+them from the surface. `tower_doctor` and `tower_recover` are core: #122 made
+them mandatory for every configuration.
 
 | Tool | Class | Note |
 |---|---|---|
 | `tower_adopt` | core | Reconciles a restored roster with the durable catalog. |
-| `tower_batch` | optional | Evidence-batch workflow; `tools.exposeBatch`. |
+| `tower_batch` | optional | Evidence-batch workflow; component `tower-batch`. |
 | `tower_complete` | core | The only completion path for a worker. |
+| `tower_control` | optional | Model-initiated mode change; `mode.allowAgentControl:false` removes it (ADR 0003). |
 | `tower_diff` | core | The read-only review view. |
-| `tower_doctor` | optional | Read-only health contract; `tools.exposeDoctor`. |
+| `tower_doctor` | core | Read-only health contract; registered for every configuration (#122). |
 | `tower_finding` | core | Out-of-scope issue recording. |
 | `tower_findings` | core | Finding lifecycle. |
-| `tower_import_legacy` | optional | Legacy migration; `tools.exposeImport`. |
+| `tower_import_legacy` | optional | Legacy migration; component `tower-import`. |
 | `tower_inbox` | core | Message delivery and acknowledgement. |
 | `tower_init` | core | Creates the repository state. |
 | `tower_interrupt` | core | Stops a runaway worker. |
-| `tower_legacy_map` | optional | Legacy audit mapping; `tools.exposeImport`. |
+| `tower_legacy_map` | optional | Legacy audit mapping; component `tower-import`. |
 | `tower_merge` | core | The only merge path. |
 | `tower_mission` | core | Mission progress and blockers. |
+| `tower_mode` | core | Reports the session stance, workspace lock, HMR and plugin version; always registered. |
 | `tower_plan` | core | Mission planning. |
 | `tower_preflight` | core | The read-only merge gate. |
 | `tower_rebase` | core | Keeps a mission branch current. |
-| `tower_recover` | optional | Stale-lock recovery; `tools.exposeRecovery`. |
-| `tower_reload` | optional | Dev-only reload; registered while the HMR/dev mode is on. |
-| `tower_resource` | optional | Advisory leases; `tools.exposeLeases`. |
+| `tower_recover` | core | Stale-lock recovery; registered for every configuration (#122). |
+| `tower_reload` | optional | Dev-only reload; component `tower-hmr` (shipped off). |
+| `tower_resource` | optional | Advisory leases; component `tower-leases`. |
 | `tower_review` | core | Independent review verdicts. |
 | `tower_roster` | core | Roster and live activity. |
 | `tower_send` | core | Durable messages to agents. |
 | `tower_spawn` | core | Starts workers and reviewers. |
 | `tower_status` | core | The dashboard. |
 | `tower_teardown` | core | Worktree cleanup and archiving. |
-| `tower_test` | optional | Explicit discovery; `tools.exposeTests`. |
+| `tower_test` | optional | Explicit discovery; component `tower-tests`. |
 
 ## Non-goals
 

package/docs/reference/tools.generated.md

@@ -1,13 +1,14 @@
 # Tools overview (generated)
 
 > Generated by `npm run docs:generate:tools` from the registered tool definitions. Do not edit by hand.
-> Surface: config keys: 64 · sections: 15 · tools: 27 · baseline 2026-10-23. Generated from `scripts/surface-baseline.json`; do not edit by hand.
+> Surface: config keys: 56 · sections: 14 · tools: 29 · baseline 2026-10-23. Generated from `scripts/surface-baseline.json`; 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, capped at gates.maxReportBytes (default 32768 UTF-8 bytes); a larger report is rejected with invalid-argument and an actionable nextAction, never truncated. Persists reportBytes on the stored report. completion means ready for preflight and optional review, not merged. |
+| `tower_control` | Enter or leave Tower mode for the calling agent. Allowed only when the deployment enables allowAgentControl; use it when the user intent or task state clearly calls for Tower orchestration or a return to normal collaboration, and always state a concrete reason. |
 | `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: the concept-budget surface (config keys/sections/tools), git, state schema, case-sensitivity detection (caseInsensitive and the active scope comparison mode), config, presets/subagents/HMR, the state lock age/heartbeat freshness, the repo-scoped git lock holder (gitLock: {held,pid,phase,heldMs}), workspace lock, roster staleness, worktree ownership, test discovery, leases, and the terminal-mission archive (count, bytes, years, unreadable diagnostics and the configured afterDays/maxMissions policy). Returns checks with pass/warn/fail, state-lock and git-lock reports and an environment contract. Never writes state and never probes the filesystem. |
 | `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. |
@@ -19,11 +20,12 @@
 | `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_mode` | Report whether Tower mode is active for the calling agent, who changed it last, whether the model may toggle it, any goal paused on entry, the workspace lock, HMR availability and the plugin version. |
 | `tower_plan` | Plan one or more missions in an initialized repository. Each mission has a printable-Unicode title (NFC-normalized, at most 120 characters), 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 with its age, heartbeat age and staleness; clear-stale-lock requires confirm:"CLEAR_STALE_LOCK" and only moves a lock whose PID is provably dead to a backup file. force:true additionally clears a live-but-silent PID (a recycled PID) and still renames the record to a .recovered-<ts> backup. 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_reload` | Dev-only: ask DSH HMR to reconcile this profile and reload the Tower Host plugin from disk. Registered only while the tower-hmr component is on (the row is shipped off). 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. 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 bound to the current branch tip: a completed mission starts a review round, and while the mission is active a later route may still record a verdict for that same reviewed tip, appending to the same round without changing the status (a moved tip is rejected with an explanation). 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. |