dsh-tower 1.2.0 → 1.3.0

package/lib/tools.js

@@ -1,5 +1,6 @@
 // Tower tools: init, plan, mission, status, spawn, roster, adopt.
 import { Tower } from './tower.js'
+import { runtimeConfig } from './config.js'
 
 const OUTPUT = {
   schema: { type: 'object' },
@@ -251,7 +252,7 @@ export function registerTowerTools(ctx) {
   define(ctx, {
     name: 'tower_spawn',
     description:
-      'Spawn a worker or reviewer for a mission. Provisions (or reuses) the mission git worktree and branch, generates a self-contained briefing (mission tasks, scope, deps, context, rules), and starts a background tower-worker subagent in that worktree. Records the agent in the roster and marks the mission active. Returns immediately unless wait=true.',
+      'Spawn a worker or reviewer for a mission. Workers use the tower-worker preset; reviewers require a completed mission and use the read-only tower-reviewer preset. Provisions (or reuses) the mission git worktree and branch, generates a self-contained briefing, and starts a background subagent in that worktree. The child final report is delivered back to this session; tower_roster shows authoritative activity. Records the agent in the roster; reviewer spawns record the branch tip so a reviewer that modifies the branch cannot submit a review. Returns immediately unless wait=true.',
     parameters: {
       type: 'object',
       properties: {
@@ -272,9 +273,17 @@ export function registerTowerTools(ctx) {
       const tower = await Tower.open(args.repoRoot)
       const role = args.role ?? 'worker'
       if (!ROLE_ENUM.includes(role)) fail(`role must be one of ${ROLE_ENUM.join('|')}`)
+      const config = runtimeConfig()
+      const preset = role === 'reviewer' ? config.spawn.reviewerPreset : config.spawn.workerPreset
+      const model = role === 'reviewer' ? config.spawn.reviewerModel : config.spawn.workerModel
       const context = await tower.missionContext(args.missionId)
-      if (role === 'reviewer' && !context.mission.worktree) {
-        fail('reviewer needs an existing mission worktree; spawn a worker first')
+      if (role === 'reviewer') {
+        if (!context.mission.worktree) {
+          fail('reviewer needs an existing mission worktree; spawn a worker first')
+        }
+        if (context.mission.status !== 'completed') {
+          fail(`reviewer requires a completed mission awaiting review; ${context.mission.id} is ${context.mission.status}`)
+        }
       }
       const provisioned = await tower.provision({
         missionId: args.missionId,
@@ -311,25 +320,35 @@ export function registerTowerTools(ctx) {
       const subagents = ctx.get('subagents')
       if (!subagents) fail('subagents service is unavailable; cannot spawn')
       const providers = subagents.list()
-      const provider = providers.includes('spawn') ? 'spawn' : providers[0]
+      const provider = config.spawn.provider || (providers.includes('spawn') ? 'spawn' : providers[0])
       if (!provider) fail('no subagent provider is registered')
+      const presets = ctx.get('agentPresets')
+      if (presets && typeof presets.list === 'function') {
+        const available = await presets.list()
+        if (!available.some((entry) => String(entry.id) === preset)) {
+          fail(`agent preset "${preset}" is not registered; check the Tower bundle's preset rows and restart DSH`)
+        }
+      }
+
+      const agentOptions = {}
+      for (const key of ['provider', 'model', 'reasoningEffort', 'maxTokens']) {
+        if (model && model[key] !== undefined && model[key] !== null && model[key] !== '') agentOptions[key] = model[key]
+      }
 
       const activation = await subagents.startActivation({
         provider,
         label: name,
         request: {
           cwd: worktree.path,
-          agentPreset: 'tower-worker',
+          agentPreset: preset,
           prompt: [{ type: 'text', text: briefing }],
           parent: exec.agent,
-          maxDepth: 1,
+          maxDepth: config.spawn.maxDepth ?? 1,
+          ...(Object.keys(agentOptions).length > 0 ? { agentOptions } : {}),
         },
         signal: exec.signal,
         delivery: 'parent',
       })
-      if (activation.result && typeof activation.result.catch === 'function') {
-        activation.result.catch(() => {})
-      }
 
       const agentId = String(activation.childId)
       const entry = await tower.recordSpawn({
@@ -342,16 +361,22 @@ export function registerTowerTools(ctx) {
         branch: worktree.branch,
       })
 
+      const recordOutcome = (state, detail) =>
+        tower.recordSpawnOutcome({ missionId: mission.id, name, state, detail }).catch(() => {})
+
       const report = {
         name,
         agentId,
         role,
         missionId: mission.id,
+        preset,
+        provider,
+        maxDepth: config.spawn.maxDepth ?? 1,
+        ...(Object.keys(agentOptions).length > 0 ? { agentOptions } : {}),
         worktree: { path: worktree.path, branch: worktree.branch, baseCommit: worktree.baseCommit },
         created: provisioned.created,
         briefingChars: briefing.length,
         rosterEntry: entry,
-        provider,
       }
 
       if (args.wait === true) {
@@ -363,16 +388,32 @@ export function registerTowerTools(ctx) {
         let result
         try {
           result = await Promise.race([activation.result, timeout])
+        } catch (error) {
+          report.stopReason = 'failed'
+          report.diagnostic = String(error?.message ?? error)
+          await recordOutcome('failed', report.diagnostic)
+          throw error
         } finally {
           clearTimeout(timer)
         }
         if (result && result.__timeout) {
           report.timedOut = true
+          recordOutcome('unknown', 'spawn wait timed out; check tower_roster')
         } else {
           report.stopReason = result?.stopReason ?? null
           report.output = textOf(result?.output)
           report.diagnostic = result?.diagnostic ?? null
+          const state = report.stopReason === 'completed' ? 'inactive' : 'failed'
+          if (state === 'failed') report.diagnostic = report.diagnostic ?? report.stopReason
+          await recordOutcome(state, report.diagnostic ?? null)
         }
+      } else {
+        activation.result
+          .then((result) => {
+            const state = result?.stopReason === 'completed' ? 'inactive' : 'failed'
+            return recordOutcome(state, result?.diagnostic ?? result?.stopReason ?? null)
+          })
+          .catch((error) => recordOutcome('failed', String(error?.message ?? error)))
       }
       return report
     },
@@ -423,6 +464,27 @@ export function registerTowerTools(ctx) {
     },
   })
 
+  define(ctx, {
+    name: 'tower_diff',
+    description:
+      'Read-only view of a mission branch for review: merge base, changed files, commits, and a capped patch against the recorded base. Safe for reviewers; it never modifies the repository.',
+    parameters: {
+      type: 'object',
+      properties: {
+        repoRoot: { type: 'string', description: 'Absolute path to the main checkout root.' },
+        missionId: { type: 'string', description: 'Mission id, e.g. M1.' },
+        maxBytes: { type: 'integer', minimum: 1024, description: 'Patch cap in bytes (default 65536).' },
+      },
+      required: ['repoRoot', 'missionId'],
+      additionalProperties: false,
+    },
+    output: OUTPUT,
+    async execute(args) {
+      const tower = await Tower.open(args.repoRoot)
+      return tower.diff({ missionId: args.missionId, maxBytes: args.maxBytes })
+    },
+  })
+
   define(ctx, {
     name: 'tower_adopt',
     description:

package/lib/tower.js

@@ -28,6 +28,7 @@ import {
   withLock,
   shortHash,
 } from './store.js'
+import { runtimeConfig } from './config.js'
 
 export const SCHEMA_VERSION = 1
 export const MISSION_STATUSES = [
@@ -69,7 +70,10 @@ const DEFAULT_MERGE_TIMEOUT_MS = 15 * 60 * 1000
 const MERGE_MAX_BUFFER = 64 * 1024 * 1024
 
 function mergeTimeoutMs(value) {
-  if (value === undefined || value === null) return DEFAULT_MERGE_TIMEOUT_MS
+  if (value === undefined || value === null) {
+    const configured = runtimeConfig().merge.timeoutMs
+    return Number.isInteger(configured) && configured >= 1000 ? configured : DEFAULT_MERGE_TIMEOUT_MS
+  }
   const ms = Number(value)
   if (!Number.isInteger(ms) || ms < 1000) fail('timeoutMs must be an integer of at least 1000 milliseconds')
   return ms
@@ -675,6 +679,30 @@ export class Tower {
     return worktree
   }
 
+  /** Record that a spawned agent failed or went idle, so roster state is truthful. */
+  async recordSpawnOutcome(input) {
+    return withLock(this.paths, async () => {
+      const state = await this.load()
+      const entry = (state.roster ?? []).find((row) => row.name === input.name && row.missionId === input.missionId)
+      if (!entry) return null
+      const now = Date.now()
+      entry.state = input.state ?? 'failed'
+      entry.outcome = input.detail ? String(input.detail).slice(0, 1000) : null
+      entry.outcomeAt = now
+      state.revision += 1
+      state.updatedAt = now
+      validateState(state, this.paths.state)
+      await writeJsonAtomic(this.paths.state, state)
+      await appendJsonl(this.paths.activity, {
+        at: now,
+        type: 'spawn',
+        missionId: input.missionId,
+        text: `${entry.name} ${entry.state}${entry.outcome ? `: ${entry.outcome.slice(0, 160)}` : ''}`,
+      })
+      return entry
+    })
+  }
+
   async provision(input = {}) {
     const missionId = input.missionId
     if (typeof missionId !== 'string' || missionId.trim().length === 0) {
@@ -693,7 +721,9 @@ export class Tower {
       const branch = `tower/${mission.id.toLowerCase()}-${slugify(mission.title)}`
       const root = input.worktreeRoot
         ? path.resolve(input.worktreeRoot)
-        : path.join(path.dirname(this.root), '.dsh-tower-worktrees', shortHash(this.commonDir))
+        : runtimeConfig().worktrees.root
+          ? path.resolve(runtimeConfig().worktrees.root)
+          : path.join(path.dirname(this.root), '.dsh-tower-worktrees', shortHash(this.commonDir))
       if (!path.isAbsolute(root)) fail('worktreeRoot must be an absolute path')
       this.assertOutside(root)
       await ensureDir(root)
@@ -751,6 +781,7 @@ export class Tower {
         fail(`agent ${input.agentId} is already in the roster`)
       }
       const now = Date.now()
+      const spawnTip = input.cwd ? ((await tryGit(input.cwd, ['rev-parse', 'HEAD'])) ?? '').trim() || null : null
       const entry = {
         name: input.name,
         role: input.role,
@@ -760,6 +791,7 @@ export class Tower {
         missionId: input.missionId,
         cwd: input.cwd ?? null,
         branch: input.branch ?? null,
+        spawnTip,
         state: 'active',
         spawnedAt: now,
       }
@@ -1111,11 +1143,17 @@ export class Tower {
       await this.assertWorktree(mission.worktree)
       const tip = await revParse(mission.worktree.path, 'HEAD')
       const branch = mission.worktree.branch
+      if (caller && caller.role === 'reviewer' && caller.spawnTip && caller.spawnTip !== tip) {
+        fail(
+          `reviewer ${caller.name} modified the mission branch after it was spawned (${caller.spawnTip.slice(0, 7)} -> ${tip.slice(0, 7)}); reviewers must be read-only — spawn a fresh reviewer`,
+        )
+      }
       const prior = (state.reviews ?? []).filter((review) => review.branch === branch)
       const reviewerRounds = prior.filter((review) => review.reviewer === reviewerName).length
-      if (reviewerRounds >= MAX_REVIEW_ROUNDS) {
+      const maxReviewRounds = Number(runtimeConfig().review.maxRoundsPerReviewer) || MAX_REVIEW_ROUNDS
+      if (reviewerRounds >= maxReviewRounds) {
         fail(
-          `reviewer ${reviewerName} reached the ${MAX_REVIEW_ROUNDS}-round cap for ${branch}; continue with a different reviewer`,
+          `reviewer ${reviewerName} reached the ${maxReviewRounds}-round cap for ${branch}; continue with a different reviewer`,
         )
       }
       const round = prior.length === 0 ? 1 : Math.max(...prior.map((review) => review.round)) + 1
@@ -1330,6 +1368,37 @@ export class Tower {
     }
   }
 
+  /** Read-only mission diff for reviewers: branch changes against the merge base. */
+  async diff(input = {}) {
+    const state = await this.load()
+    const mission = state.missions.find((entry) => entry.id === input.missionId)
+    if (!mission) fail(`unknown mission "${input.missionId}"`)
+    if (!mission.worktree) fail(`mission ${mission.id} has no worktree to diff`)
+    await this.assertWorktree(mission.worktree)
+    const baseTip = await revParse(this.root, state.base)
+    const branchTip = await revParse(mission.worktree.path, 'HEAD')
+    const mergeBase = (await git(mission.worktree.path, ['merge-base', baseTip, branchTip])).trim()
+    const files = (await git(mission.worktree.path, ['diff', '--name-status', `${mergeBase}..${branchTip}`]))
+      .split('\n')
+      .filter(Boolean)
+    const commits = (await git(mission.worktree.path, ['log', '--oneline', `${mergeBase}..${branchTip}`]))
+      .split('\n')
+      .filter(Boolean)
+    const fullPatch = await git(mission.worktree.path, ['diff', `${mergeBase}..${branchTip}`])
+    const limit = Number.isInteger(input.maxBytes) && input.maxBytes > 0 ? input.maxBytes : 64 * 1024
+    return {
+      missionId: mission.id,
+      branch: mission.worktree.branch,
+      baseTip,
+      branchTip,
+      mergeBase,
+      files,
+      commits,
+      truncated: fullPatch.length > limit,
+      patch: fullPatch.slice(0, limit),
+    }
+  }
+
   /**
    * Record a merge that already landed in Git without being recorded here:
    * a crashed/timed-out merge, a manual merge, or a rebase that fast-forwarded
@@ -1424,7 +1493,7 @@ export class Tower {
         await git(
           this.root,
           ['merge', '--no-ff', worktree.branch, '-m', `tower: merge ${mission.id} — ${mission.title}`],
-          { timeoutMs, maxBuffer: MERGE_MAX_BUFFER },
+          { timeoutMs, maxBuffer: runtimeConfig().merge.maxBufferBytes || MERGE_MAX_BUFFER },
         )
       } catch (error) {
         failure = error

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tower",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "DSH-native Tower: mission planning, worktree isolation, review-gated merges, and a human-owned Tower mode.",
   "license": "MIT",
@@ -28,12 +28,18 @@
   "exports": {
     ".": "./index.js",
     "./worker": "./worker.js",
+    "./reviewer": "./reviewer.js",
+    "./skills": "./skills.js",
     "./locale/*.json": "./locale/*.json",
-    "./icon": "./icon.svg"
+    "./icon": "./icon.svg",
+    "./package.json": "./package.json"
   },
   "files": [
     "index.js",
     "worker.js",
+    "reviewer.js",
+    "skills.js",
+    "skills/",
     "lib/*.js",
     "cordis.patch.yml",
     "locale/*.json",
@@ -41,7 +47,10 @@
     "README.md",
     "README.en.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "docs/"
   ],
   "dsh": {
     "bundle": {
@@ -50,6 +59,11 @@
   },
   "scripts": {
     "test": "node --test tests/*.test.mjs",
-    "test:watch": "node --test --watch tests/*.test.mjs"
+    "test:watch": "node --test --watch tests/*.test.mjs",
+    "docs:check": "node scripts/check-docs.mjs",
+    "check": "npm test && npm run docs:check"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.5"
   }
 }

package/reviewer.js

@@ -0,0 +1,39 @@
+// tower-reviewer preset policy: read-only review surface. The reviewer must
+// never modify the mission branch: tower_review binds the verdict to the tip
+// recorded when the reviewer was spawned, so a modified tip is rejected.
+export const name = 'dsh-tower/reviewer'
+export const inject = ['tools', 'systemPrompt']
+
+const ALLOW = [
+  'read',
+  'glob',
+  'grep',
+  'tower_diff',
+  'tower_status',
+  'tower_send',
+  'tower_inbox',
+  'tower_finding',
+  'tower_review',
+  'skill',
+]
+
+const PROTOCOL = [
+  'You are an independent Tower reviewer in a DeepSeek Harness Tower workspace.',
+  'You are read-only: do not write, edit, commit, rebase, or merge, and never modify the mission branch.',
+  'Inspect the mission diff with tower_diff, check scope, tasks, and the reviewed tip, then submit exactly one',
+  'tower_review verdict (clean + merge, or p1-/p2-items + hold/fix-then-merge) with findings and decision.',
+  'You must not be the mission worker. Use tower_finding for out-of-scope issues instead of editing files.',
+].join(' ')
+
+export function apply(ctx) {
+  try {
+    ctx.tools.restrict({ allow: ALLOW })
+  } catch {
+    // a composition without the tool registry still gets the protocol text
+  }
+  try {
+    ctx.systemPrompt.section({ name: 'tower:reviewer-protocol', order: 12000, text: PROTOCOL })
+  } catch {
+    // prompt assembly remains valid without the section
+  }
+}

package/skills/tower-recovery.md

@@ -0,0 +1,40 @@
+# Tower recovery playbook
+
+Read `tower_preflight` and the last failure before changing anything.
+
+## Merge hook failed or timed out (`merge-hook-failed`)
+
+The merge commit was not created; the repository was restored. Re-run `tower_merge`. For slow
+`pre-merge-commit` hooks pass a larger `timeoutMs` (default 15 minutes).
+
+## Merge commit landed but the call failed (`recoveredFromFailure`)
+
+The mission is already recorded as merged. Do not merge again; run `tower_teardown`.
+
+## Merge already landed earlier (`reconciled` / `alreadyMerged`)
+
+`tower_merge` detects the existing merge commit or a branch contained in the base and records it.
+Only a clean/merge review qualifies; otherwise ask for a fresh review.
+
+## Merge blocked with `stale-base`
+
+Run `tower_rebase` inside the mission worktree, then `tower_preflight` and `tower_merge`.
+If the branch was already contained in the base, rebase returns `alreadyMerged` and leaves it
+untouched — call `tower_merge` to record it.
+
+## `state.lock` reports another writer
+
+Wait, then retry. Never delete the lock while a writer may be active; if the process is gone,
+remove `<git-common-dir>/dsh-tower/state.lock` deliberately and retry.
+
+## Worktree missing or dirty
+
+`tower_status` shows the expected path and branch. Re-add a missing worktree only from Git if the
+branch still exists; do not delete a branch you have not reviewed. Dirty worktrees require an
+explicit teardown `force` decision.
+
+## Reset a repository's Tower state
+
+Only when no mission is in flight and you accept losing mission history: stop all agents, remove
+`<git-common-dir>/dsh-tower/`, then `tower_init` again. Worktrees and branches must be cleaned
+manually.

package/skills/tower-review.md

@@ -0,0 +1,14 @@
+# Tower review
+
+You are the independent reviewer of a completed Tower mission. You are read-only.
+
+1. Read the mission briefing and the review binding: the reviewed tip must equal the current branch tip.
+2. Inspect the diff with `tower_diff` (files, commits, patch). Do not run write, edit, pwsh, commit, rebase, or merge.
+3. Verify: every task is met; all changes are inside the mission scope; no unrelated or generated files; no secrets; tests or evidence are adequate.
+4. Check the reviewed commit is the tip you inspected. If it moved, stop and report a blocker instead of approving.
+5. Submit exactly one `tower_review`:
+   - `clean` + `merge` + `findings: "none"` when everything passes.
+   - `p1-Nitems` or `p2-Nitems` + `hold` or `fix-then-merge` with concrete findings when it does not.
+6. Put out-of-scope observations in `tower_finding`, never in the branch.
+
+The verdict is bound to the inspected tip; do not modify the branch.

package/skills/tower-worker-protocol.md

@@ -0,0 +1,13 @@
+# Tower worker protocol
+
+You are a Tower worker: one mission, one worktree, one commit series.
+
+1. Read the briefing: mission id, branch, task list, scope globs, dependencies, and context.
+2. Work only inside the assigned worktree. Never modify the main checkout or other missions.
+3. Keep changes inside the scope globs; report anything else as a `tower_finding` instead of editing it.
+4. As you finish each task call `tower_mission` with `task_done` (and `note` when useful).
+5. Run the verification available to you (tests, type check, build). Record it in your final message.
+6. Commit on the mission branch with a clear message. Do not push, spawn agents, review, or merge.
+7. If blocked, call `tower_mission` with `blocker`, then stop and report exactly what is blocking.
+
+Final message must contain: mission id, branch, every changed file, how you verified it, and anything left undone.

package/skills.js

@@ -0,0 +1,63 @@
+// Bundled Tower skills: protocol, review checklist, and recovery playbook.
+// The provider is mounted by the bundle patch so every agent sees the catalog;
+// the short system-prompt sections stay authoritative for safety rules.
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+
+export const name = 'dsh-tower/skills'
+export const inject = ['skills']
+
+const ASSETS = fileURLToPath(new URL('./skills/', import.meta.url))
+
+const SKILLS = [
+  {
+    name: 'tower-worker-protocol',
+    description:
+      'Follow the Tower worker workflow: work only in the assigned mission worktree, update the mission, commit the branch, and report a complete handoff. Use when spawned as a Tower worker.',
+    file: 'tower-worker-protocol.md',
+  },
+  {
+    name: 'tower-review',
+    description:
+      'Run an independent Tower review: inspect the mission diff read-only, verify scope/tasks/reviewed tip, and submit exactly one clean or p1/p2 review verdict. Use when spawned as a Tower reviewer.',
+    file: 'tower-review.md',
+  },
+  {
+    name: 'tower-recovery',
+    description:
+      'Recover a Tower mission from a merge hook failure, an already-landed merge, a stale branch, a stuck state lock, or a missing worktree. Use when tower_merge, tower_rebase, or tower_preflight reports a blocker.',
+    file: 'tower-recovery.md',
+  },
+]
+
+const provider = {
+  name: 'dsh-tower',
+  list: async () =>
+    SKILLS.map((skill) => ({
+      name: skill.name,
+      description: skill.description,
+      invocation: { modelInvocable: true, userInvocable: true },
+      provider: 'dsh-tower',
+      source: 'bundled',
+      resourceBase: { kind: 'directory', path: ASSETS },
+      rank: 600,
+      locator: new URL(skill.file, new URL('./skills/', import.meta.url)),
+    })),
+  async get(candidate) {
+    const skill = SKILLS.find((entry) => entry.name === candidate.name)
+    if (!skill) throw new Error(`unknown dsh-tower skill: ${candidate.name}`)
+    return {
+      name: skill.name,
+      description: skill.description,
+      invocation: { modelInvocable: true, userInvocable: true },
+      provider: 'dsh-tower',
+      source: 'bundled',
+      resourceBase: { kind: 'directory', path: ASSETS },
+      content: await readFile(new URL(skill.file, new URL('./skills/', import.meta.url)), 'utf8'),
+    }
+  },
+}
+
+export function apply(ctx) {
+  ctx.skills.registerProvider(() => provider)
+}

package/worker.js

@@ -11,11 +11,12 @@ const ALLOW = [
   'pwsh',
   'tower_mission',
   'tower_status',
+  'tower_diff',
   'tower_send',
   'tower_inbox',
   'tower_complete',
   'tower_finding',
-  'tower_review',
+  'skill',
 ]
 
 const PROTOCOL = [
@@ -24,7 +25,7 @@ const PROTOCOL = [
   'Commit your work on the mission branch. Update the mission as you go with tower_mission',
   '(task_done, blocker, status), and put the full handoff in your final message: what changed,',
   'every file path, how you verified it, and anything left undone.',
-  'Do not spawn other agents and do not merge branches; the tower owns integration.',
+  'Do not spawn other agents, do not review, and do not merge branches; the tower owns integration.',
 ].join(' ')
 
 export function apply(ctx) {