dsh-tower 1.1.2 → 1.3.0

package/docs/guide/quickstart.md

@@ -0,0 +1,65 @@
+# 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).
+
+A complete copy-paste example: [examples/first-mission.md](../examples/first-mission.md).

package/docs/operations/runbook.md

@@ -0,0 +1,57 @@
+# 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.
+
+## 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,39 @@
+# 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`).
+- **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.
+
+## 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.
+- **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).

package/docs/reference/blockers.md

@@ -0,0 +1,50 @@
+# Blockers and failure codes
+
+`tower_preflight` returns `{ok:false, blockers:[{code, detail}]}`. `tower_merge` and `tower_rebase`
+return the same shape for operation failures. Codes are stable; the detail is human-facing.
+
+## Gate blockers (19)
+
+| Code | Meaning / next action |
+|---|---|
+| `mission-missing` | Unknown mission id. Check `tower_status`. |
+| `mission-not-completed` | Mission is not `completed`; only a completed mission (awaiting review) merges. |
+| `tasks-open` | Open tasks remain; the worker must finish or `task_drop` with a reason. |
+| `blockers-present` | The mission has blockers; clear them after resolving. |
+| `branch-missing` | No worktree/branch yet: spawn a worker first. |
+| `stale-base` | The branch does not contain the base tip: run `tower_rebase`. |
+| `read-only-survey` | Survey mission changed files; survey missions must be read-only. |
+| `out-of-scope` | Changed files outside the mission scope; widen scope deliberately or revert. |
+| `base-dirty` | The main checkout has uncommitted changes the merge would overwrite. |
+| `deps-unmerged` | A dependency mission is not merged/abandoned. |
+| `no-review` | No review on the branch: spawn a reviewer. |
+| `review-mission-mismatch` | The latest review belongs to another mission. |
+| `not-clean` | Latest review is `p1-Nitems`/`p2-Nitems`; another round is required. |
+| `review-hold` | Latest review recommends hold; a later clean review must supersede it. |
+| `review-not-approved` | Latest clean review says `fix-then-merge` or `hold`; only `merge` approves. |
+| `tip-moved` | The branch changed after review; review again (or use a clean rebase waiver). |
+| `worker-busy` | A roster agent for this mission is running; wait or retire it. |
+| `base-wrong-branch` | The main checkout is not on the recorded base branch. |
+| `branch-owned-by-closed-missions` | The mission is already merged/abandoned; re-plan under a new title. |
+
+## Merge failures (3)
+
+| Code | Meaning / next action |
+|---|---|
+| `merge-conflict` | Real index conflict; the mission is `blocked`. Resolve, restore the mission to `active`/`completed`, retry. |
+| `merge-hook-failed` | A hook/process failed before a commit existed; repository restored, mission stays `completed`. Retry; `timeout: true` means the git process timed out. Raise `timeoutMs` for slow hooks. |
+| `merge-shape` | Git produced unexpected merge parents; inspect the repository, do not force. |
+
+A merge that already landed is **not** a blocker: `tower_merge` records it (`reconciled`,
+`alreadyLanded`) or recovers it (`recoveredFromFailure`, `warnings`).
+
+## Rebase failures (3; `worker-busy` shared)
+
+| Code | Meaning / next action |
+|---|---|
+| `worktree-dirty` | Commit or discard worktree changes, then retry. |
+| `rebase-conflict` | A real conflict; the mission is `blocked`. Resolve manually, return it to `active`, retry. |
+| `worker-busy` | An agent is running for this mission; wait or retire it first. |
+
+`tower_rebase` returns `alreadyMerged: true` when the branch is already contained in the base; call
+`tower_merge` to record the landed merge.

package/docs/reference/config.md

@@ -0,0 +1,51 @@
+# Config reference
+
+Every key is optional; defaults reproduce the shipped behavior. Unknown top-level keys are rejected.
+`section` and `allowAgentControl` are legacy aliases for `mode.promptSection` and
+`mode.allowAgentControl`.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `section` | `''` | Legacy alias: replace the whole Tower-mode prompt text. Empty keeps the built-in reminder. |
+| `allowAgentControl` | `false` (bundled patch: `true`) | Legacy alias: register `tower_control`. |
+| `mode.promptSection` | `''` | Replacement prompt text (takes precedence over `section` when both set). |
+| `mode.sectionAppend` | `''` | Extra text appended after the reminder (team conventions). |
+| `mode.allowAgentControl` | `false` | Register `tower_control`; the model may enter/leave with a reason. |
+| `mode.autoPauseGoal` | `true` | Pause an active goal on entry; the goal is never auto-resumed on exit. |
+| `mode.denyTools` | six goal/todo/team tools | Tools refused while the mode is active. |
+| `mode.storePath` | `$DSH_HOME/tower-mode` | Directory for `modes.json`. |
+| `mode.maxEntries` | `200` | Maximum persisted mode entries (1–2000). |
+| `review.maxRoundsPerReviewer` | `5` | Review-round cap per reviewer per branch. |
+| `merge.timeoutMs` | `900000` (15 min) | Default `tower_merge` timeout, including hooks. A per-call `timeoutMs` wins. |
+| `merge.maxBufferBytes` | `67108864` (64 MB) | Merge output buffer. |
+| `worktrees.root` | `''` | Default worktree parent; empty derives `<checkout parent>/.dsh-tower-worktrees/<hash>`. |
+| `spawn.workerPreset` | `tower-worker` | Preset used for `role=worker`. |
+| `spawn.reviewerPreset` | `tower-reviewer` | Preset used for `role=reviewer`. |
+| `spawn.maxDepth` | `1` | Subagent depth requested at spawn. |
+| `spawn.provider` | `''` | Subagent provider id; empty prefers `spawn`, then the first provider. |
+| `spawn.workerModel` | `{}` | Optional `{provider, model, reasoningEffort, maxTokens}` for workers. |
+| `spawn.reviewerModel` | `{}` | Optional model route for reviewers; independent review is stronger with a different model. |
+
+## Example
+
+```yaml
+- id: tower
+  name: 'dsh-tower'
+  config:
+    mode:
+      allowAgentControl: true
+      sectionAppend: 'Team conventions: tests are mandatory.'
+    review:
+      maxRoundsPerReviewer: 3
+    merge:
+      timeoutMs: 1800000
+    spawn:
+      reviewerModel:
+        provider: deepseek-account
+        model: deepseek-flash
+```
+
+## Looking up the effective schema
+
+`cordis_inspect_query` with `Config.listConfigs({ name: "dsh-tower" })` returns the projected JSON
+Schema once the plugin declares `Config` (this release does).

package/docs/reference/tools.md

@@ -0,0 +1,33 @@
+# Tools reference
+
+All tools take `repoRoot` (an absolute path inside the target Git repository) and return JSON.
+The installable build exposes 19 tools: 18 below plus `tower_control` when
+`mode.allowAgentControl` is enabled (the bundled patch enables it).
+
+| Tool | Parameters | Purpose / notes |
+|---|---|---|
+| `tower_init` | `base?` | Create `.git/dsh-tower/state.json`, record the base branch (idempotent; `base` is ignored on an existing state). |
+| `tower_plan` | `missions[]` (`title`, `scope[]`, `tasks[]?`, `deps[]?`, `kind?`, `context?`) | Create missions `M1..`; overlapping build scopes auto-add a dependency; rejects unknown deps and cycles. |
+| `tower_mission` | `id`, `status?`, `task_done?`, `task_drop?`+`task_drop_reason?`, `blocker?`, `clear_blockers?`, `note?`, `scope?` | Update one mission. `merged` cannot be set here; widening scope makes the mission active again. |
+| `tower_status` | — | Mission counts, roster, open tasks, reviews, findings, recent activity. |
+| `tower_spawn` | `missionId`, `role` (`worker`/`reviewer`), `name?`, `instructions?`, `worktreeRoot?`, `wait?`, `waitMs?` | Provision/reuse the worktree and start a subagent. Worker uses `tower-worker`; reviewer requires a `completed` mission and uses the read-only `tower-reviewer`. Returns agent id immediately; the child final report is delivered to this session. |
+| `tower_roster` | — | Roster with live activity (`running`/`inactive`/`missing`/`unknown`) from the subagent catalog. Read-only. |
+| `tower_adopt` | — | Reconcile roster entries with the durable subagent catalog after restart; provably gone agents are retired. |
+| `tower_diff` | `missionId`, `maxBytes?` | Read-only merge-base diff: files, commits, capped patch. Safe for reviewers. |
+| `tower_send` | `to`, `subject`, `body`, `scope?` | Durable message to a roster name, `tower`, or `all`; delivers live to a running agent. |
+| `tower_inbox` | `page?`, `pageSize?` | Read/ack messages addressed to the caller; unread messages block `tower_complete`. |
+| `tower_complete` | `missionId`, `agentId`, `report`, `commit?` | Worker reports completion (mission becomes `completed`, awaiting review). |
+| `tower_finding` | `type`, `title`, `summary`, `details`, `suggested_fix`, `severity?`, `missionId?`, `location?` | Record an out-of-scope issue; reviewers use this instead of editing. |
+| `tower_review` | `missionId`, `status` (`clean`/`p1-Nitems`/`p2-Nitems`), `merge` (`merge`/`fix-then-merge`/`hold`), `findings`, `decision`, `checks?`, `breakGlassReason?` | Reviewer verdict bound to the current tip. Reviewer must be the assigned reviewer (or tower break-glass). |
+| `tower_preflight` | `missionId` | Read-only gate: returns `{ok, blockers[], branchTip, baseTip, changedFiles, review}`. |
+| `tower_merge` | `missionId`, `timeoutMs?` | Merge after a green gate. If the merge commit already landed, records it (`reconciled`); if the command failed but the commit exists, records it (`recoveredFromFailure`); hook failures return `merge-hook-failed` with `cleanup` and optional `timeout`. |
+| `tower_rebase` | `missionId` | Rebase the branch onto the base in its worktree. Refuses while the worker runs or the worktree is dirty. If the branch is already contained in the base it returns `alreadyMerged` and leaves it untouched. |
+| `tower_teardown` | `force?`, `exclude?`, `dry_run?` | Remove eligible merged/abandoned worktrees and branches; running agents are always kept. |
+| `tower_mode` | — | Report mode, who changed it, whether the model may toggle it, paused goal, denied tools, store path. |
+| `tower_control` | `action` (`enter`/`exit`), `reason` | Model-initiated mode change; only when `mode.allowAgentControl` is true; reason is mandatory. |
+
+## Failure results
+
+Gate tools return `{ok:false, blockers:[{code, detail}]}`. The code list is in
+[blockers.md](blockers.md). `tower_merge` failure blockers may also include `timeout: true`, `cleanup`,
+and `warnings`.

package/index.js

@@ -9,20 +9,14 @@
 import { randomUUID } from 'node:crypto'
 import { registerTowerTools } from './lib/tools.js'
 import { loadModes, saveModes, storePath } from './lib/modeStore.js'
+import { Config as ConfigSchema, DEFAULT_DENY_TOOLS, configureRuntime, runtimeConfig } from './lib/config.js'
 
 export const name = 'dsh-tower'
 export const inject = ['tools', 'systemPrompt']
+export const Config = ConfigSchema
 
-const MODE = loadModes()
-
-const DENY_TOOLS = new Set([
-  'create_goal',
-  'todo_write',
-  'team_task_create',
-  'team_task_update',
-  'team_task_reopen',
-  'spawn_teammate',
-])
+let MODE = new Map()
+let denyTools = new Set(DEFAULT_DENY_TOOLS)
 
 const BASE_REMINDER = [
   'Tower mode is active for this session. You are the control tower: plan missions, spawn workers and reviewers, and integrate only through the Tower tools.',
@@ -40,18 +34,20 @@ function agentKey(agent) {
   return key === undefined || key === null ? null : String(key)
 }
 
-function resolveConfig(config) {
-  const input = config ?? {}
-  const unknown = Object.keys(input).filter((key) => !['section', 'allowAgentControl'].includes(key))
-  if (unknown.length > 0) {
-    throw new Error(
-      `Tower config has unknown key(s) ${unknown.join(', ')} — config is { section?, allowAgentControl? }`,
-    )
-  }
-  const section = typeof input.section === 'string' && input.section.trim().length > 0
-    ? input.section
+function configSection(config, allowAgentControl) {
+  const configured = config.mode.promptSection && config.mode.promptSection.trim().length > 0
+    ? config.mode.promptSection
     : BASE_REMINDER
-  return { section, allowAgentControl: input.allowAgentControl === true }
+  const appended = config.mode.sectionAppend && config.mode.sectionAppend.trim().length > 0
+    ? ` ${config.mode.sectionAppend.trim()}`
+    : ''
+  const control = allowAgentControl ? ` ${AGENT_CONTROL_NOTE}` : ''
+  return `${configured}${appended}${control}`
+}
+
+function persistModes() {
+  const config = runtimeConfig()
+  saveModes(MODE, config.mode.storePath || undefined, config.mode.maxEntries)
 }
 
 /** Parse `/tower` arguments: bare and free text both mean "ensure on". */
@@ -94,9 +90,10 @@ function pauseActiveGoal(ctx, agent) {
 function enterMode(ctx, key, agent, by, reason) {
   const previous = MODE.get(key)
   const wasOn = Boolean(previous && previous.on)
+  const autoPauseGoal = runtimeConfig().mode.autoPauseGoal !== false
   let pausedGoal = previous?.pausedGoal ?? null
   let goalNote = null
-  if (!wasOn) {
+  if (!wasOn && autoPauseGoal) {
     const paused = pauseActiveGoal(ctx, agent)
     if (paused.attempted && paused.ok) pausedGoal = paused.goal
     else if (paused.attempted && !paused.ok) goalNote = `pause-failed: ${paused.reason}`
@@ -111,7 +108,7 @@ function enterMode(ctx, key, agent, by, reason) {
     lastChange: { by, action: 'on', reason: reason ?? null, at: now },
     at: now,
   })
-  saveModes(MODE)
+  persistModes()
   return { wasOn, pausedGoal, goalNote }
 }
 
@@ -119,7 +116,7 @@ function exitMode(key, by, reason) {
   const previous = MODE.get(key)
   if (!previous) return { wasOn: false, pausedGoal: null, goalNote: null }
   MODE.delete(key)
-  saveModes(MODE)
+  persistModes()
   return { wasOn: true, pausedGoal: previous.pausedGoal ?? null, goalNote: null, by, reason: reason ?? null }
 }
 
@@ -162,14 +159,18 @@ function describeChange(active, outcome, forwarded, message, allowAgentControl)
 }
 
 export function apply(ctx, rawConfig) {
-  const config = resolveConfig(rawConfig)
+  const config = configureRuntime(rawConfig)
+  const allowAgentControl = config.mode.allowAgentControl === true
+  const reminder = configSection(config, allowAgentControl)
+  MODE = loadModes(config.mode.storePath || undefined)
+  denyTools = new Set(config.mode.denyTools)
   registerTowerTools(ctx)
 
   ctx.effect(() =>
     ctx.tools.guard((execution) => {
       const key = agentKey(execution.agent)
       if (!key || !MODE.has(key)) return undefined
-      if (DENY_TOOLS.has(execution.name)) {
+      if (denyTools.has(execution.name)) {
         return `tower mode: ${execution.name} is disabled while Tower mode is active; use the Tower tools or /tower off`
       }
       if (execution.name === 'update_goal') {
@@ -185,12 +186,7 @@ export function apply(ctx, rawConfig) {
   ctx.systemPrompt.section({
     name: 'tower:mode',
     order: 15000,
-    text: (context) =>
-      context && MODE.has(agentKey(context.agent))
-        ? config.allowAgentControl
-          ? `${config.section} ${AGENT_CONTROL_NOTE}`
-          : config.section
-        : '',
+    text: (context) => (context && MODE.has(agentKey(context.agent)) ? reminder : ''),
   })
 
   ctx.effect(() =>
@@ -209,17 +205,17 @@ export function apply(ctx, rawConfig) {
         return {
           mode: entry && entry.on === true ? 'on' : key ? 'off' : 'unknown',
           agentId: key,
-          allowAgentControl: config.allowAgentControl,
+          allowAgentControl,
           lastChange: entry?.lastChange ?? null,
           pausedGoal: entry?.pausedGoal ?? null,
-          deniedWhileActive: [...DENY_TOOLS],
-          persistedAt: storePath(),
+          deniedWhileActive: [...denyTools],
+          persistedAt: storePath(config.mode.storePath || undefined),
         }
       },
     }),
   )
 
-  if (config.allowAgentControl) {
+  if (allowAgentControl) {
     ctx.effect(() =>
       ctx.tools.register({
         name: 'tower_control',
@@ -288,7 +284,7 @@ export function apply(ctx, rawConfig) {
         }
         return {
           kind: 'success',
-          text: describeChange(active, outcome, forwarded, message, config.allowAgentControl),
+          text: describeChange(active, outcome, forwarded, message, allowAgentControl),
         }
       },
     })

package/lib/config.js

@@ -0,0 +1,119 @@
+// Tower configuration: one declared schema, resolved defaults, and the
+// process-local effective snapshot consumed by the domain modules.
+//
+// Defaults are exactly the 1.2.0 behavior; the shipped cordis patch keeps
+// `allowAgentControl: true` via the legacy top-level key.
+import Schema from '@deepseek-ai/schemastery'
+
+export const DEFAULT_DENY_TOOLS = [
+  'create_goal',
+  'todo_write',
+  'team_task_create',
+  'team_task_update',
+  'team_task_reopen',
+  'spawn_teammate',
+]
+
+const LEGACY_KEYS = ['section', 'allowAgentControl']
+const GROUP_KEYS = ['mode', 'review', 'merge', 'worktrees', 'spawn']
+
+const ModelSchema = () =>
+  Schema.object({
+    provider: Schema.string().description('Provider route override for this role.'),
+    model: Schema.string().description('Model id override for this role.'),
+    reasoningEffort: Schema.string().description('Optional reasoning effort override.'),
+    maxTokens: Schema.natural().description('Optional output token cap.'),
+  })
+
+export const Config = Schema.object({
+  section: Schema.string().description(
+    'Legacy alias for mode.promptSection: replaces the whole Tower-mode system prompt text.',
+  ),
+  allowAgentControl: Schema.boolean().description(
+    'Legacy alias for mode.allowAgentControl: register tower_control so the model may toggle the mode.',
+  ),
+  mode: Schema.object({
+    promptSection: Schema.string().description('Replacement Tower-mode system prompt text. Empty keeps the built-in reminder.'),
+    sectionAppend: Schema.string().description('Extra text appended to the Tower-mode system prompt section (team conventions).'),
+    allowAgentControl: Schema.boolean().default(false).description('Register tower_control so the model may enter/leave the mode with a reason.'),
+    autoPauseGoal: Schema.boolean().default(true).description('Pause an active goal when entering Tower mode.'),
+    denyTools: Schema.array(Schema.string())
+      .default(DEFAULT_DENY_TOOLS)
+      .description('Tools refused while Tower mode is active.'),
+    storePath: Schema.string().description('Directory for modes.json; defaults to $DSH_HOME/tower-mode.'),
+    maxEntries: Schema.natural().min(1).max(2000).default(200).description('Maximum persisted mode entries.'),
+  })
+    .default({})
+    .description('Tower-mode behavior and persistence.'),
+  review: Schema.object({
+    maxRoundsPerReviewer: Schema.natural().min(1).default(5).description('Review-round cap per reviewer per mission branch.'),
+  })
+    .default({})
+    .description('Review policy.'),
+  merge: Schema.object({
+    timeoutMs: Schema.natural().min(1000).default(900000).description('Default tower_merge timeout, including pre-merge hooks.'),
+    maxBufferBytes: Schema.natural().min(65536).default(67108864).description('Captured merge output buffer.'),
+  })
+    .default({})
+    .description('Merge execution policy.'),
+  worktrees: Schema.object({
+    root: Schema.string().description('Default parent directory for mission worktrees; empty derives <main-checkout-parent>/.dsh-tower-worktrees/<hash>.'),
+  })
+    .default({})
+    .description('Worktree placement.'),
+  spawn: Schema.object({
+    workerPreset: Schema.string().default('tower-worker').description('Agent preset for worker missions.'),
+    reviewerPreset: Schema.string().default('tower-reviewer').description('Agent preset for reviewers.'),
+    maxDepth: Schema.natural().min(1).default(1).description('Subagent depth requested when spawning tower agents.'),
+    provider: Schema.string().description('Subagent provider id; empty picks spawn, then the first registered provider.'),
+    workerModel: ModelSchema().description('Model route for workers; omitted inherits the parent session.'),
+    reviewerModel: ModelSchema().description('Model route for reviewers; omitted inherits the parent session (recommended).'),
+  })
+    .default({})
+    .description('Worker and reviewer presets plus model routing.'),
+}).description('DSH Tower configuration')
+
+let effective = null
+
+function clone(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value))
+}
+
+export function resolveTowerConfig(rawConfig) {
+  const raw = rawConfig ?? {}
+  if (raw !== null && typeof raw !== 'object') throw new Error('Tower config must be an object')
+  const unknown = Object.keys(raw).filter((key) => !LEGACY_KEYS.includes(key) && !GROUP_KEYS.includes(key))
+  if (unknown.length > 0) {
+    throw new Error(
+      `Tower config has unknown key(s) ${unknown.join(', ')} — config is { section?, allowAgentControl?, mode?, review?, merge?, worktrees?, spawn? }`,
+    )
+  }
+  let parsed
+  try {
+    parsed = Config(raw)
+  } catch (error) {
+    throw new Error(`Tower config is invalid: ${String(error?.message ?? error)}`)
+  }
+  const mode = clone(parsed.mode ?? {})
+  if (raw.section !== undefined) mode.promptSection = raw.section
+  if (raw.allowAgentControl !== undefined) mode.allowAgentControl = raw.allowAgentControl
+  if (!Array.isArray(mode.denyTools) || mode.denyTools.length === 0) mode.denyTools = [...DEFAULT_DENY_TOOLS]
+  return {
+    section: mode.promptSection ?? '',
+    mode,
+    review: clone(parsed.review ?? {}),
+    merge: clone(parsed.merge ?? {}),
+    worktrees: clone(parsed.worktrees ?? {}),
+    spawn: clone(parsed.spawn ?? {}),
+  }
+}
+
+export function configureRuntime(config) {
+  effective = resolveTowerConfig(config)
+  return effective
+}
+
+export function runtimeConfig() {
+  if (!effective) effective = resolveTowerConfig({})
+  return effective
+}

package/lib/git.js

@@ -6,10 +6,13 @@ const GIT_TIMEOUT_MS = 15000
 const MAX_BUFFER = 16 * 1024 * 1024
 
 export class GitError extends Error {
-  constructor(args, detail, code) {
+  constructor(args, detail, code, meta = {}) {
     super(`git ${args.join(' ')} failed: ${detail}`)
     this.name = 'GitError'
     this.code = code
+    this.timedOut = meta.timedOut === true
+    this.bufferOverflow = meta.bufferOverflow === true
+    this.stdout = meta.stdout ?? ''
   }
 }
 
@@ -27,11 +30,14 @@ export function git(cwd, args, options = {}) {
       },
       (error, stdout, stderr) => {
         if (error) {
+          const timedOut = error.killed === true || error.signal === 'SIGTERM' || error.code === 'ETIMEDOUT'
+          const bufferOverflow = error.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER'
           reject(
             new GitError(
               args,
               String(stderr || error.message || '').trim(),
               typeof error.code === 'number' ? error.code : undefined,
+              { timedOut, bufferOverflow, stdout: String(stdout ?? '').slice(0, 64 * 1024) },
             ),
           )
           return