dsh-tower 1.2.0 → 2.0.0

package/docs/examples/first-mission.md

@@ -0,0 +1,58 @@
+# Example: first mission, end to end
+
+Assume a repository at `D:\work\demo` with a clean `main` branch and one file `README.md`.
+
+```
+/tower on
+tower_init repoRoot=D:\work\demo
+```
+
+`s` is a placeholder for tool JSON arguments; DSH accepts the object form:
+
+```json
+{"repoRoot":"D:\\work\\demo","missions":[{"title":"Add greeting","scope":["src/**"],"tasks":["write src/greet.txt","commit the change"],"kind":"build"}]}
+```
+
+`tower_plan` returns `M1`. Spawn the worker:
+
+```json
+{"repoRoot":"D:\\work\\demo","missionId":"M1","role":"worker"}
+```
+
+Wait for the worker's final report (delivered to this session) or check `tower_roster`. The worker
+creates `src/greet.txt`, commits on `tower/m1-add-greeting`, marks both tasks done, and calls
+`tower_complete`.
+
+Spawn the reviewer:
+
+```json
+{"repoRoot":"D:\\work\\demo","missionId":"M1","role":"reviewer"}
+```
+
+The read-only reviewer inspects `tower_diff`, then calls `tower_review` with:
+
+```json
+{"repoRoot":"D:\\work\\demo","missionId":"M1","status":"clean","merge":"merge","findings":"none","decision":"single in-scope file; content correct"}
+```
+
+Gate and merge:
+
+```json
+{"repoRoot":"D:\\work\\demo","missionId":"M1"}
+```
+
+Call `tower_preflight` with the same arguments; expect `ok: true`. Then `tower_merge`, and finally
+`tower_teardown` with `{"repoRoot":"D:\\work\\demo"}`.
+
+```
+/tower off
+```
+
+Typical expected output after merge:
+
+```json
+{"ok":true,"mergedCommit":"<sha>","baseTip":"<old>","branchTip":"<sha>","parents":["<old>","<sha>"]}
+```
+
+If the merge hook is slow, add `"timeoutMs": 1800000` to `tower_merge`; if a merge commit landed but the
+call failed, re-run `tower_merge` and it records the existing commit instead of merging again.

package/docs/faq.md

@@ -0,0 +1,74 @@
+# FAQ
+
+**Why did `tower_preflight` fail with `no-review` right after the worker finished?**
+That is expected: a completed mission awaits review. Spawn a reviewer; after a clean review the gate
+turns green.
+
+**Do I need to poll the worker?**
+No. The worker's final report is delivered to this session; `tower_roster` shows live activity. Polling
+wastes turns.
+
+**`/tower` says the mode is on but `tower_control` is missing.**
+`mode.allowAgentControl` is off. Set it to `true` in the profile patch and restart DSH.
+
+**The merge hook takes minutes and `tower_merge` failed.**
+Retry with a larger `timeoutMs`: `tower_merge({ missionId, timeoutMs: 1800000 })`. The default is 15
+minutes and merge output is buffered up to 64 MB. A hook failure returns `merge-hook-failed` and leaves
+the repo clean for a retry.
+
+**A merge commit exists but Tower says the mission is not merged.**
+Call `tower_merge` again. It detects the landed merge commit (`reconciled`) or recovers a failed call
+whose commit exists (`recoveredFromFailure`) and records it.
+
+**`tower_rebase` returned `alreadyMerged` and changed nothing.**
+Correct: the branch is already contained in the base. Call `tower_merge` to record the landed merge
+instead of rebasing.
+
+**Can a reviewer edit files?**
+No. Reviewers use the read-only `tower-reviewer` preset (no write/edit/pwsh); a branch changed after the
+reviewer spawned is rejected. Reviewers file `tower_finding` for issues outside the mission.
+
+**What is the difference between `tower_finding` and `tower_findings`?**
+`tower_finding` creates one finding (`open`). `tower_findings` is the lifecycle tool: list/read, and
+transition `open → triaged → fixed`/`wontfix` (reopen allowed). Only the tower or a worker may change the
+status; a roster reviewer may list and read.
+
+**How do I set config for one repository only?**
+Create `<git-common-dir>/dsh-tower/config.json` (usually `.git/dsh-tower/config.json`) with the same
+JSON groups as the profile config (`review`, `merge`, `worktrees`, `spawn`, and legacy aliases). The
+repository layer wins over the profile; per-call tool arguments win over both. No restart is required
+because the file is read when a Tower tool opens the repository.
+
+**Can workers use Tower tools to merge or spawn?**
+No. The worker preset contains mission/progress tools only; merge and spawn live in the parent tower.
+
+**A worker is stuck or runaway. How do I stop it?**
+Use `tower_interrupt({to:"worker-m1",reason:"..."})`; it calls the host subagent interrupt and records the
+roster entry as `interrupted`. If you already interrupted it and want a new owner, spawn with
+`takeover:true`. A still-running worker cannot be taken over (`takeover-refused`).
+
+**Two sessions want to drive the same repository.**
+Enable `mode.workspaceLock:true`: the first Tower session to call a repo-scoped tool owns
+`<git-common-dir>/dsh-tower/tower.lock`; other sessions get `[tower:workspace-busy]` until the owner
+runs `/tower off` or the lock is stale (`mode.workspaceStaleMs`).
+
+**Can I reload the plugin without restarting DSH?**
+Yes, in a profile with the DSH HMR service: `/tower reload` or the `tower_reload` tool reconciles the
+profile and replaces the changed linked package. Run `npm run dev:hmr` once to add the repository to the
+profile's HMR watch roots (then restart DSH once); see [hot reload](guide/hot-reload.md).
+`plugin_manager` install/update already applies live.
+
+**How do I make the completion evidence mandatory?**
+Workers can pass `checks` to `tower_complete`; set `gates.requireChecks:true` to block merging when a
+completed mission has no checks (`no-check-evidence`).
+
+**Where does Tower store state?**
+`<git-common-dir>/dsh-tower/state.json`, `activity.jsonl` and the human-readable `MISSIONS.md`; mode state
+in `$DSH_HOME/tower-mode/modes.json`. Worktrees live next to the checkout in `.dsh-tower-worktrees/`.
+
+**How do I change the review round cap or presets?**
+Use `review.maxRoundsPerReviewer` and `spawn.workerPreset`/`spawn.reviewerPreset`; see
+[config](reference/config.md). Restart DSH after a profile config change.
+
+**Does Tower send data anywhere?**
+No. It has no telemetry and no network service; all state is local.

package/docs/guide/hot-reload.md

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

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

@@ -0,0 +1,59 @@
+# Install, upgrade and migration
+
+## Requirements
+
+- DSH `0.2.1-rc.2` or newer
+- Node.js 22+
+- Git (local worktrees; no network access is required)
+
+## Install
+
+```bash
+dsh plugin --profile web add dsh-tower
+```
+
+Or inside DSH: `plugin_manager({ action: "install_bundle", target: "dsh-tower" })`. From a checkout:
+
+```bash
+dsh plugin --profile web add github:louifinn/dsh-tower
+```
+
+The Host plugin loads at DSH startup: **restart DSH after install or update**.
+
+## Upgrade
+
+1. Read [CHANGELOG.md](../../CHANGELOG.md) for behavior changes.
+2. Update the dependency (`dsh plugin --profile web add dsh-tower@latest` or your pinned version).
+3. Restart DSH; check `tower_mode` reports `allowAgentControl` as expected.
+4. Existing mission state stays compatible: the state schema did not change in 1.2/1.3.
+
+## Migration notes
+
+- **1.x → 2.0 (unreleased)**: no state migration is needed (`schemaVersion` stays 1; new fields are
+  optional). Behavior changes to review: `mode.denyTools` now also denies `workflow`, `ralph`, `subagent`,
+  `subagent_fork`, `wait_agent` and `team_task_list` while Tower mode is active (override with an explicit
+  list); `spawn.maxLiveWorkers` defaults to 4; `mode.workspaceLock` is off by default. Workers can no
+  longer complete/abandon/scope a mission directly — use `tower_complete`. New tools: `tower_interrupt`,
+  and `tower_reload` when HMR is available. Restart DSH once after upgrading; see
+  [hot reload](hot-reload.md).
+- **1.3 → 1.4**: no state migration is needed. New: repository-level config
+  (`<git-common-dir>/dsh-tower/config.json`), stable `[tower:<code>]` tool errors, `tower_findings`,
+  and `id`/`missionId` + snake/camel input aliases. Existing calls keep working; restart DSH to load
+  the new tool surface (`tower_findings` and the newer output schemas).
+- **1.2 → 1.3**: reviewers moved from the shared `tower-worker` preset to the new read-only
+  `tower-reviewer` preset. Reinstall/restart so both preset rows exist. `tower_spawn role=reviewer`
+  now requires the mission to be `completed`.
+- **1.1 → 1.2**: merge failures gained `merge-hook-failed`, `cleanup` and reconciliation behavior; no
+  state migration is needed.
+- **1.0 → 1.1**: package name changed from `@local/dsh-tower` to `dsh-tower`. Remove the old bundle
+  (`remove_bundle` with `@local/dsh-tower`) and install `dsh-tower`.
+
+## Uninstall
+
+```text
+plugin_manager({ action: "remove_bundle", target: "dsh-tower" })
+```
+
+Restart DSH. Mission state under `<git-common-dir>/dsh-tower/` and worktrees under
+`<checkout parent>/.dsh-tower-worktrees/` are left in place; remove them manually only after no mission
+is active.

package/docs/guide/quickstart.md

@@ -0,0 +1,97 @@
+# Quick start
+
+Prerequisites: DSH `0.2.1-rc.2`+, Node.js 22+, Git. Install `dsh-tower` and restart DSH (see
+[install](install-upgrade-migration.md)).
+
+## 1. Enter Tower mode
+
+```
+/tower
+```
+
+The session reports `Tower mode ON`. You are now the control tower; goal/todo/team delegation tools are
+reserved for normal mode.
+
+## 2. Initialize and plan
+
+```
+tower_init repoRoot=D:\work\repo
+tower_plan repoRoot=D:\work\repo missions=[{"title":"Feature A","scope":["src/a/**"],"tasks":["implement the feature","commit the change"],"kind":"build"}]
+```
+
+`tower_plan` returns mission ids (`M1`). Each mission gets a branch and a worktree when spawned.
+
+## 3. Run the worker
+
+```
+tower_spawn repoRoot=D:\work\repo missionId=M1 role=worker
+```
+
+The call returns immediately with the child agent id. The worker works inside the mission worktree,
+commits, marks tasks done, and calls `tower_complete`; its final report is delivered back to this
+session. Use `tower_roster` to observe activity; do not poll in a loop.
+
+## 4. Review
+
+```
+tower_spawn repoRoot=D:\work\repo missionId=M1 role=reviewer
+```
+
+Reviewers use the read-only `tower-reviewer` preset. They inspect `tower_diff` and submit
+`tower_review`. A `clean` + `merge` verdict is required to merge.
+
+## 5. Gate, merge, clean up
+
+```
+tower_preflight repoRoot=D:\work\repo missionId=M1
+tower_merge     repoRoot=D:\work\repo missionId=M1
+tower_teardown  repoRoot=D:\work\repo
+```
+
+`tower_preflight` before review is expected to report `no-review`; after a clean review it should be
+`ok:true`. `tower_merge` refuses while blockers remain. `tower_teardown` removes merged/abandoned
+worktrees and branches.
+
+```
+/tower off
+```
+
+## If something fails
+
+Read the blocker code and use [the blocker reference](../reference/blockers.md). The most common cases:
+`stale-base` (run `tower_rebase`), `no-review` (spawn a reviewer), `merge-hook-failed` (retry, or raise
+`timeoutMs`), `tip-moved` (the branch changed after review; review again).
+
+Thrown tool failures carry a `[tower:<code>]` prefix; see [error codes](../reference/errors.md)
+(e.g. `preset-missing` means restart DSH after installing the bundle, `not-initialized` means run
+`tower_init` first).
+
+## Optional: per-repository config
+
+A repository can tune review, merge, worktree and spawn policy without touching the DSH profile. Put a
+JSON file at `<git-common-dir>/dsh-tower/config.json` (usually `.git/dsh-tower/config.json`):
+
+```json
+{
+  "review": { "maxRoundsPerReviewer": 3 },
+  "merge": { "timeoutMs": 1800000 },
+  "worktrees": { "root": "D:/tower-worktrees" }
+}
+```
+
+The repository layer overrides the profile config; per-call tool arguments override both. See the
+[config reference](../reference/config.md) for the full table and precedence.
+
+## Optional: findings
+
+Out-of-scope observations go to `tower_finding`. Later, list or close them without editing code:
+
+```
+tower_findings repoRoot=D:\work\repo
+tower_findings repoRoot=D:\work\repo id=F1 status=fixed note="fixed in M2"
+```
+
+Statuses are `open → triaged → fixed` / `wontfix`, and `fixed`/`wontfix` can reopen to `open`. Only the
+tower or a worker may change a finding; reviewers can list and read.
+
+A complete copy-paste example: [examples/first-mission.md](../examples/first-mission.md).

package/docs/operations/runbook.md

@@ -0,0 +1,80 @@
+# Operations runbook
+
+## Daily checks
+
+- `tower_status` — counts, open tasks, roster, unread messages, recent activity.
+- `tower_roster` — live activity; retired agents are recorded but never resumed.
+- `tower_preflight missionId` before every merge.
+
+## Recover from a failed merge
+
+1. Read the blocker: `merge-hook-failed` (retryable) vs `merge-conflict` (mission blocked) vs
+   `merge-shape` (inspect manually).
+2. For a slow `pre-merge-commit` hook, retry with a larger timeout:
+   `tower_merge({ missionId, timeoutMs: 1800000 })`.
+3. If a merge commit landed but the call failed, re-run `tower_merge`; it records the commit
+   (`recoveredFromFailure`) or reconciles an already-landed merge (`reconciled`) without a second merge.
+4. Never reset or rewrite the base branch by hand while Tower state exists; use Tower tools so state and
+   Git stay aligned.
+
+## Recover from a stale branch
+
+`tower_rebase` first. If the branch is already contained in the base it returns `alreadyMerged` and
+leaves the branch untouched — then call `tower_merge` to record it. A conflict marks the mission
+`blocked`; resolve in the worktree, set the mission back to `active` (or `completed`), retry.
+
+## Interrupt, stale roster and takeover
+
+A runaway agent: `tower_interrupt({to:"worker-m1",reason:"..."})` interrupts the host subagent turn and
+records `state:"interrupted"`. `tower_roster` shows `stale:true` when an active entry has no catalog
+activity beyond `spawn.staleMs`; `tower_adopt` retires such entries (`retireMissing:false` marks them
+`missing` instead). After the old owner is interrupted/failed/missing, spawn a replacement with
+`takeover:true`; a still-running owner returns `takeover-refused`.
+
+## Workspace lock
+
+With `mode.workspaceLock:true`, `<git-common-dir>/dsh-tower/tower.lock` names the owning session. A second
+Tower session gets `[tower:workspace-busy]`. Let the owner run `/tower off`; if the owner is gone, wait
+`mode.workspaceStaleMs` (default 5 min) for the stale takeover, or delete the lock deliberately only after
+confirming no Tower session is active. Heartbeats refresh the lock every `mode.heartbeatMs`.
+
+## Hot reload
+
+`/tower reload` or `tower_reload` asks DSH HMR to reconcile the profile and reload the Host plugin; the
+reload is scheduled after the tool result (`dev.reloadDelayMs`). It fails with `reload-unavailable` on a
+profile without HMR. Run `npm run dev:hmr` once to add this checkout to the profile's HMR watch roots
+(one DSH restart after the profile patch change); see [hot reload](../guide/hot-reload.md). If a reload
+fails, the previous plugin code no longer runs: restart DSH and check the HMR log.
+
+## State lock
+
+`tower state is locked by another writer` means an operation holds `state.lock`. Wait and retry. Only if
+the owning process is gone, remove `<git-common-dir>/dsh-tower/state.lock` deliberately; never delete it
+while an agent may still be running.
+
+## Worktrees and teardown
+
+`tower_teardown` removes worktrees only for `merged`/`abandoned` missions; a running agent is always
+kept, and a dirty worktree requires `force: true`. Use `dry_run: true` to preview decisions. A missing
+worktree can be re-added from its branch with `git worktree add`, but do not do this while the mission
+is active without updating the roster.
+
+## Stale or corrupt state
+
+If `state.json` is unreadable, stop all agents first. The plugin reports corruption instead of guessing.
+Restore from a backup if you have one; otherwise remove `<git-common-dir>/dsh-tower/` and re-run
+`tower_init` — this loses mission history but not Git branches/worktrees.
+
+## Full recovery of a repo's Tower data
+
+Only when no mission is in flight and you accept losing history:
+
+1. Stop all tower agents.
+2. Remove merged/abandoned worktrees (`tower_teardown` first when the state is readable).
+3. Remove `<git-common-dir>/dsh-tower/`.
+4. `tower_init` again; re-plan any work still needed.
+
+## Mode state
+
+Tower mode is stored in `$DSH_HOME/tower-mode/modes.json` (atomic writes, capped entries). If a mode is
+stuck, `/tower off`; if the session is gone, remove its entry with the file unlocked and restart DSH.

package/docs/operations/security.md

@@ -0,0 +1,62 @@
+# Security model
+
+Tower's guarantees are **coordination guarantees**, not a sandbox. Understand what is enforced where.
+
+## Enforced by the plugin
+
+- **Review binding.** `tower_review` records the branch tip it inspected; the gate rejects a moved tip
+  (`tip-moved`) unless a clean conflict-free rebase waived it. A reviewer that modifies the branch after
+  spawning is rejected (`reviewer must not modify the mission branch`).
+- **Role enforcement.** The caller is resolved against the roster. Worker mission updates are limited to
+  task/blocker/note; `completed`, `abandoned`, scope widening and blocker clearing are tower-only, and
+  completion (with its unread-inbox/commit gates) must go through `tower_complete`. Tower-only tools reject
+  roster workers with `[tower:not-authorized]`. One live worker per mission; taking over a stopped worker
+  is explicit.
+- **Read-only reviewer preset.** The `tower-reviewer` preset removes `write`, `edit`, `pwsh`,
+  `tower_mission` and `tower_complete` from the tool surface; reviewers can only read, diff, message,
+  file findings, and submit a review.
+- **Scope gate.** A mission may only change files matched by its declared scope globs; out-of-scope
+  changes block the merge.
+- **Worktree isolation.** Workers operate in a dedicated worktree and branch; the main checkout is only
+  touched by merge/teardown.
+- **Human-owned mode.** `/tower` is user-owned. With `mode.allowAgentControl` the model may toggle it,
+  but must state a reason; the shipped patch enables that by default — set it to `false` to make the
+  mode human-only.
+- **No automatic goal resume.** Entering pauses the active goal; leaving does not resume it.
+- **Advisory workspace lock.** `mode.workspaceLock` prevents two Tower sessions from accidentally driving
+  one repository; it is a same-user coordination lock, not authentication between users.
+- **Test discovery is repository code.** `tower_test`/`tower_complete` execute `package.json`
+  `tower.testDiscovery` commands in the mission worktree with the DSH process's OS permissions. Set
+  `tests.allowPackageDiscovery:false` for untrusted repositories; output/time budgets fail closed but are
+  not a sandbox.
+- **Review exemption is opt-in.** `reviewPolicy:"none"` requires `gates.allowReviewExemption:true` and a
+  non-empty reason. It is off by default because a model-driven tower could otherwise self-exempt; the
+  exemption and its reason are recorded in state/events and never granted to workers.
+- **Leases are coordination, not quotas.** `tower_resource` prevents accidental co-scheduling via a local
+  JSON ledger; it does not cap CPU, memory, or process count. DSH exposes no public Job-object quota API,
+  so OS-level isolation remains a deployment concern.
+- **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.
+
+## Not enforced by the plugin (deployment concerns)
+
+- **Sandboxing.** Host plugins run outside the filesystem sandbox; the reviewer's shell ability is
+  removed at the tool-surface level, but the underlying process still has whatever OS permissions DSH
+  has. Deployments that need hard isolation must restrict the process/user themselves.
+- **Reviewer trust.** A review is an attestation by the reviewer agent/model; the plugin binds it to a
+  commit but cannot prove the reviewer actually reasoned correctly. Use independent models/roles for
+  high-value branches.
+- **Repository hooks.** `git merge` runs the target repository's hooks (`pre-merge-commit` etc.). Tower
+  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
+  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.
+
+## Reporting
+
+Do not paste secrets, tokens, or session logs in public issues. See [SECURITY.md](../../SECURITY.md).