dsh-tower 1.3.0 → 2.0.1

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

@@ -29,6 +29,17 @@ The Host plugin loads at DSH startup: **restart DSH after install or update**.
 
 ## 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`.

package/docs/guide/quickstart.md

@@ -58,8 +58,40 @@ worktrees and branches.
 
 ## If something fails
 
-Read the blocker code and use [the blocker reference](reference/blockers.md). The most common cases:
+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/guide/scenarios-and-philosophy.md

@@ -0,0 +1,309 @@
+# When to use Tower, and how it differs from other workflows
+
+[简体中文](../zh/guide/scenarios-and-philosophy.md)
+
+Tower is not a replacement for every multi-agent pattern. It is a **delivery protocol for changes to a
+Git repository**: a small number of bounded missions, isolated writers, independent review, evidence,
+and a merge gate. This page explains the design choices behind it, the situations where it pays off,
+and when Agent Teams, Ralph loops, Workflow orchestration, or ordinary parallel subagents are a better
+fit.
+
+If you only remember one sentence: **use Tower when the output is a reviewed, integrated repository
+change; use the other patterns when the output is exploration, repeated attempts, or programmatic
+fan-out.**
+
+## 1. The design philosophy
+
+Tower makes several deliberate trade-offs. They explain both its strengths and its cost.
+
+### 1.1 The repository is the unit of accountability
+
+A mission is not a chat thread or a task card. It is a contract attached to a branch and a worktree,
+with a declared write scope, dependencies, completion evidence, and a review record. The question
+"what changed, who changed it, and what proved it?" has a durable answer in
+`<git-common-dir>/dsh-tower/state.json` and the Git history, not only in a conversation.
+
+### 1.2 One writer per mission
+
+Two agents writing the same branch at the same time produce races that no review can repair. Tower
+enforces one live worker per mission, explicit takeover after a stop/interrupt, and a per-repository
+worker cap. Parallelism comes from **separate missions**, not from several writers on one mission.
+
+### 1.3 Contract before code
+
+Planning fixes the scope, tasks, dependencies, and review policy before a worker starts. That
+front-loading is intentional: it lets the tower detect overlapping scopes, serialize dependent work,
+and tell a reviewer exactly what "done" means. It is also why Tower is a poor fit for work whose
+requirements are still being discovered.
+
+### 1.4 Integration is a separate, privileged step
+
+Workers never merge. A reviewer inspects a specific branch tip; the tower runs preflight; only then
+does `tower_merge` perform a `--no-ff` merge. The gate re-checks scope, base freshness, tasks, review
+binding, worktree ownership, worker state, tests, and evidence. Separation of duties is the point:
+the agent that wrote the code is not the agent that approves it, and neither is the agent that merges.
+
+### 1.5 Evidence over assertion
+
+"Done" is a claim; a commit, a diff, a passing test receipt, and an independent review are evidence.
+Tower records all of them. `tower_doctor` checks the environment, `tower_test` records discovery,
+`tower_complete` records checks, `tower_review` binds a verdict to a commit, and `tower_batch` can
+close a finite set of missions only when their required evidence exists.
+
+### 1.6 Fail closed, recover explicitly
+
+Tower prefers a visible blocker over a silent repair. A stale worker is marked, not assumed dead; a
+dirty base blocks a merge; a moved review tip blocks a merge; a crash during merge leaves a persistent
+intent that the next `tower_merge` reconciles. The cost is occasional manual cleanup; the benefit is
+that state never lies about what was integrated.
+
+### 1.7 The human owns the mode
+
+Tower mode changes the session's stance: it narrows the tool surface and injects the mission protocol.
+The shipped patch allows the model to toggle it with a stated reason, but the mode exists because a
+human asked for delivery discipline. Entering pauses an active goal and clears plan mode; leaving does
+not silently resume either. Tower intentionally refuses `goal`, `todo`, Team task-board, Workflow,
+Ralph, and ordinary subagent tools while it is active, so two orchestration protocols do not fight over
+one session.
+
+### 1.8 Local-first, no hidden service
+
+Tower is a Host plugin. It uses local Git, local files, and the DSH subagent service. It does not push,
+does not call a cloud service, and does not send telemetry. The durable state lives in the repository's
+Git metadata, so it survives restarts and is visible to a human with ordinary Git tools.
+
+## 2. Situations where Tower is a good fit
+
+### 2.1 A feature that naturally splits into independent slices
+
+Example: add OAuth login, split into "token model", "callback route", "UI button", and "migration +
+tests". The slices touch mostly different files, can run in parallel, and need a final integration
+review. Tower's scope reservation and automatic dependency for overlapping scopes keep the slices from
+colliding.
+
+**Why Tower:** parallel writers are isolated; each slice has an owner and a review; the merge is
+gated once, not improvised per slice.
+
+### 2.2 A migration or refactor with ordering constraints
+
+Example: rename a package, update imports, regenerate snapshots, then update documentation. Some work
+can proceed in parallel, but later missions depend on earlier merges. Tower records `deps`, refuses to
+merge a mission whose dependency is not merged, and lets the tower check `tower_status`/preflight
+instead of remembering the graph in chat.
+
+**Why Tower:** the dependency graph and branch freshness are enforced, not advisory.
+
+### 2.3 Work that needs a read-only investigation before a change
+
+Example: "find every caller of this API and write a migration plan" followed by "apply the migration".
+A `survey` mission reserves no write scope and is rejected if it changes files; its findings can feed
+the build missions. Tower can also keep findings (`tower_finding`) outside a mission's scope without
+silently widening it.
+
+**Why Tower:** investigation and mutation have different contracts; the survey cannot accidentally
+"fix" something.
+
+### 2.4 A sensitive repository or a release-bound change
+
+Example: a payments service, a library with external users, or a release branch. You want an
+independent reviewer, a specific reviewed commit, test evidence, and a human-visible audit trail.
+
+**Why Tower:** review binding, evidence gates, `MISSIONS.md`, activity log, and optional test discovery
+give you a defensible record. The reviewer is a separate read-only agent, not the author.
+
+### 2.5 Long-running work that spans context compaction or restarts
+
+Example: a multi-day refactor interrupted by restarts, new sessions, or a context reset. The mission
+state, roster, inbox, reviews, and worktrees are durable; `tower_adopt` reconciles a lost roster;
+`tower_doctor` reports what is broken; `tower_merge` reconciles an already-landed merge.
+
+**Why Tower:** the protocol is reconstructable from local state and Git, not from a conversation
+window.
+
+### 2.6 Parallel work with a hard integration boundary
+
+Example: four independent services in one monorepo, each with its own owner, all needing a final
+release review. Tower gives each mission a branch/worktree and reserves write scopes; the tower can
+then audit a finite batch (`tower_batch`) before declaring the release ready.
+
+**Why Tower:** parallelism is real, but integration remains a single, gated step.
+
+### 2.7 When you need a "definition of done" that another agent can check
+
+Example: a task list plus tests plus a required review verdict. Tower's mission contract and
+completion/review tools make "done" observable. If your definition of done is "the user likes it in
+the chat", Tower is overhead.
+
+## 3. Situations where Tower is a poor fit
+
+| Situation | Better fit | Why |
+|---|---|---|
+| One-file edit, typo, small hotfix | Ordinary agent in a single session | Worktree, review, and merge overhead dominate. |
+| Requirements are still being discovered | Ordinary agent, Plan mode, or Agent Teams | Tower asks for scope/tasks before work; a wrong contract causes re-planning. |
+| Open-ended research or brainstorming | Agent Teams, Workflow, or plain subagents | There is no repository change to isolate or merge. |
+| Many tiny independent tasks | Workflow or plain parallel subagents | Per-mission review/merge cost is too high. |
+| Interactive UI pairing / exploratory debugging | Ordinary agent (or a single worker) | Tight feedback loops and frequent human steering; the review gate adds latency. |
+| A one-shot generation with no integration | Plain subagent/Workflow | No branch, no review, no merge decision. |
+| Cross-repository product work | Agent Teams + ordinary tools | Tower is scoped to one Git repository. |
+
+A useful heuristic: **if you would not open a pull request for it, Tower is probably too heavy.**
+
+## 4. How Tower differs from other DSH workflow patterns
+
+All of these patterns can use the same subagent runtime. They differ in **what is durable, who owns
+integration, and what "done" means.**
+
+| Dimension | Tower | Agent Teams | Ralph loop | Workflow orchestration | Ordinary parallel subagents |
+|---|---|---|---|---|---|
+| Primary goal | Deliver reviewed repository changes | Collaborate across people/agents on a shared goal | Repeated fresh attempts at one objective | Programmatic fan-out/pipeline of agent work | Explore or implement in parallel |
+| Unit of work | Mission (branch + worktree + scope + tasks + review) | Task/teammate on a shared board | Round/attempt | Scripted step/stage | Prompt/task per child |
+| Isolation | Git worktree + branch per mission; one writer per mission | Shared workspace; coordination by task ownership | Fresh child per round; no built-in branch/merge contract | Per-step child; no Git isolation | Child sessions; may share workspace |
+| Durable state | Git metadata + JSON state + activity + board | Team task board + sessions | Minimal; each round starts fresh | Run record/results; not a merge ledger | Session/subagent records |
+| Integration authority | Tower only, after review + gate | Humans/teammates merge or edit manually | Usually the parent/worker applies results | Script applies results | Parent applies results |
+| Review / gate | Mandatory independent review + preflight/merge gate | Review is a collaboration convention, not a hard gate | No built-in review gate | No built-in review gate | No built-in review gate |
+| Parallelism | Multiple missions, disjoint scopes, serialized merges | Many teammates, shared board | Sequential rounds (or external fan-out) | High fan-out, script-controlled | High fan-out |
+| Human role | Owns the mode; can inspect evidence and release | Collaborator/coordinator | Author of the repeated objective | Author of the orchestration script | Delegator |
+| Best for | Feature delivery, migrations, release-bound changes | Design, research, cross-cutting collaboration | Iterative search/repair with fresh context | Large audits, batch analysis, deterministic pipelines | Quick exploration or independent subtasks |
+| Main cost | Mission/review/merge overhead; merge serialization | Coordination overhead; no isolation guarantee | Repeated work; weak integration contract | Script complexity; no review/merge semantics | No isolation/review; manual integration |
+
+### 4.1 Tower vs ordinary parallel subagents
+
+Ordinary `subagent`/`subagent_fork` calls are cheap and flexible. They are the right tool for "read
+these five files in parallel" or "try three approaches". They do not provide a write scope, a
+dedicated worktree, a durable mission, an independent review, or a merge gate. Tower wraps the same
+subagent primitive in those contracts; it also costs more per child.
+
+Choose subagents when the work is read-mostly, short-lived, or you will integrate the result
+yourself. Choose Tower when the result must land on a branch and survive a review.
+
+### 4.2 Tower vs Agent Teams
+
+Agent Teams is a **collaboration** pattern: a shared task board, durable teammates, messages, wait
+and interrupt, and a human/Lead coordinating work. It is excellent when the work is cross-cutting,
+exploratory, or needs several perspectives, and when the integration decision is human.
+
+Tower is a **delivery** pattern: mission contracts, Git isolation, review, and a hard merge gate. It
+has less flexible peer-to-peer coordination and more structure. Agent Teams can decide *what* to
+build and *whether* to proceed; Tower can then execute that decision as missions. They are sequential
+or complementary, not concurrent: Tower mode refuses the Team task-board tools so the two protocols do
+not compete for the same session.
+
+### 4.3 Tower vs Ralph loop
+
+Ralph runs the **same objective** through fresh agents, round after round, with the workspace as
+memory. It is useful for iterative search, flaky repair, or "try again with fresh context". It has no
+mission contract, no independent review, and no merge gate.
+
+Tower is incremental: each mission has a bounded deliverable and lands through review. If the problem
+is "I do not know whether this can be done, and repeated fresh attempts may find a way", Ralph is
+often better. If the problem is "I know the slices; build and integrate them safely", Tower is better.
+You can use Ralph outside Tower mode to find an approach, then encode the result as Tower missions.
+
+### 4.4 Tower vs Workflow orchestration
+
+Workflow is **programmatic orchestration**: a JavaScript script fans work out across many subagents
+with phases, pipelines, and structured results. It is excellent for audits, migrations of many
+independent items, multi-angle research, and adversarial verification. It does not give each step a
+Git worktree, a review verdict, or a merge gate.
+
+Tower is a **repository delivery protocol** with a small number of missions, not a high-fan-out data
+plane. Use Workflow for "analyze 200 files in parallel"; use Tower for "make the 6 changes those
+analyses justify, with review and a merge". Tower mode refuses Workflow so a script cannot spawn
+competing writers under the Tower contract.
+
+### 4.5 Tower vs Plan mode
+
+Plan mode is for deciding what to do; Tower is for executing a decided plan against a repository.
+Tower entry clears an active plan (or refuses entry under `mode.planModePolicy:"refuse"`), and a
+Tower session cannot use the goal/todo/team/workflow tools. Plan first, then execute; do not expect
+Tower to discover the plan for you.
+
+## 5. Worked scenarios
+
+### Scenario A: four-slice feature
+
+A team wants "organization invitations": token model, email delivery, accept/decline API, and UI.
+
+1. Plan four build missions with scopes `src/tokens/**`, `src/email/**`, `src/api/invites/**`,
+   `src/ui/invites/**`; make the API depend on tokens and email.
+2. Spawn workers for the independent missions; the API waits for its deps.
+3. Each worker commits on its branch, completes with checks.
+4. Spawn reviewers; a clean+merge review is required.
+5. `tower_preflight` and `tower_merge` each mission; resolve scope/base/review blockers.
+6. `tower_teardown`; `MISSIONS.md` is the human-readable record.
+
+**Why not Team/Workflow?** The work is a known set of repository changes that must land in a specific
+order with independent review. Team tasks would not isolate writes; Workflow would analyze but not
+gate the merge.
+
+### Scenario B: migration with a survey
+
+1. Survey mission: "map all callers of `oldApi`"; scope empty, read-only.
+2. Build missions: codemod, test updates, docs; depend on the survey's findings.
+3. Reviewers check the diff against the survey; tests must pass for the reviewed tip.
+4. Merge in dependency order.
+
+**Why not plain subagents?** The survey must not accidentally mutate; the codemod must not touch
+out-of-scope files; the review must bind to the exact commit.
+
+### Scenario C: incident hotfix
+
+A one-line fix in production. Use an ordinary agent, commit and push through your normal process.
+Tower would add a worktree, a reviewer, a gate, and a merge step; for a one-line urgent fix that is
+mostly latency. If the "hotfix" is actually several coordinated changes, Tower becomes reasonable.
+
+### Scenario D: broad codebase audit
+
+"Find every use of deprecated crypto and summarize risk." Use Workflow or parallel subagents; there
+is no branch to merge and no single reviewed change. If the audit produces a set of fixes, create
+Tower missions from those findings.
+
+### Scenario E: sensitive release
+
+A library release with external consumers. Plan missions for the change, migration guide, and
+release notes; require tests and review; use `tower_batch` to close the release evidence only when
+all required checks are present; merge and tag outside Tower as your release process requires.
+
+## 6. Choosing in practice: a short decision path
+
+1. **Is the output a Git change?** No → use ordinary agents, Agent Teams, Workflow, or Ralph.
+2. **Would you open a PR for it?** No → Tower is too heavy; use a normal agent.
+3. **Do the slices have stable scopes and a known definition of done?** No → plan/explore first; then
+   return to Tower.
+4. **Do you need independent review and a merge gate?** Yes → Tower. If no, plain subagents may be
+   enough.
+5. **Do you need many parallel analyses or repeated fresh attempts?** Use Workflow/Ralph for that
+   phase; encode the resulting changes as Tower missions.
+6. **Do you need cross-cutting human collaboration?** Use Agent Teams to decide; execute the decided
+   repository work with Tower.
+
+## 7. Cost, limits, and anti-patterns
+
+- **Per-mission overhead is real**: worktree creation, spawn, completion checks, review round, gate,
+  merge. Keep missions meaningful (roughly a PR-sized slice), not one task per function.
+- **Merges serialize**: overlapping scopes auto-add dependencies; independent missions still merge
+  one at a time onto the base. Do not expect linear speedup for merge-heavy work.
+- **Review is not free**: every mission needs a reviewer and a clean verdict. Exemptions are opt-in
+  and require a reason; they are not the default.
+- **Too-fine missions** increase coordination and merge cost. **Too-coarse missions** lose the benefit
+  of parallel review and make scope conflicts likely.
+- **Tower is not a sandbox**: it is a coordination protocol. Host permissions, repository hooks, and
+  test commands still execute with the DSH user's OS permissions.
+- **Do not run two orchestration protocols at once**: Tower mode denies Team/Workflow/Ralph/subagent
+  tools and clears plan mode. Sequence the phases instead.
+- **Do not use Tower to hide missing requirements**: a wrong mission contract produces a wrong branch
+  that then fails review. Explore first.
+
+## 8. Checklist before you start
+
+- [ ] The work produces a repository change that deserves a PR-style review.
+- [ ] I can name 2–8 missions with non-overlapping scopes and a rough dependency order.
+- [ ] Each mission has a testable definition of done (tasks, checks/tests, review).
+- [ ] I know which missions can run in parallel and which must wait.
+- [ ] I accept the review/merge overhead and will inspect `MISSIONS.md`/the branch.
+- [ ] I am not currently relying on a Team task board, Workflow script, Ralph loop, or plan mode in
+      the same session.
+- [ ] I have a recovery path if a worker stalls (interrupt/adopt) or a merge conflicts.
+
+If most boxes are checked, Tower is likely a good fit. If not, use the lighter patterns and come back
+when the change is shaped.

package/docs/operations/runbook.md

@@ -23,6 +23,29 @@
 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

package/docs/operations/security.md

@@ -7,6 +7,11 @@ Tower's guarantees are **coordination guarantees**, not a sandbox. Understand wh
 - **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.
@@ -18,6 +23,20 @@ Tower's guarantees are **coordination guarantees**, not a sandbox. Understand wh
   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)
 
@@ -29,6 +48,10 @@ Tower's guarantees are **coordination guarantees**, not a sandbox. Understand wh
   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