dsh-tower 1.1.2 → 1.3.0

package/lib/tower.js

@@ -1,5 +1,6 @@
 // Tower domain: repo-scoped mission state machine, validation, and gates.
 import path from 'node:path'
+import fsp from 'node:fs/promises'
 import {
   git,
   resolveRepo,
@@ -14,6 +15,7 @@ import {
   countCommits,
   isClean,
   isAncestor,
+  tryGit,
 } from './git.js'
 import {
   pathsFor,
@@ -26,6 +28,7 @@ import {
   withLock,
   shortHash,
 } from './store.js'
+import { runtimeConfig } from './config.js'
 
 export const SCHEMA_VERSION = 1
 export const MISSION_STATUSES = [
@@ -41,7 +44,7 @@ const TERMINAL = new Set(['merged', 'abandoned'])
 const TRANSITIONS = {
   planned: ['active', 'abandoned'],
   active: ['completed', 'blocked', 'paused', 'abandoned'],
-  blocked: ['active', 'paused', 'abandoned'],
+  blocked: ['active', 'paused', 'completed', 'abandoned'],
   paused: ['active', 'abandoned'],
   completed: ['active', 'abandoned'],
   merged: [],
@@ -63,6 +66,49 @@ export const FINDING_SEVERITIES = ['low', 'medium', 'high', 'critical']
 export const MERGE_VERDICTS = ['merge', 'fix-then-merge', 'hold']
 const MAX_REVIEW_ROUNDS = 5
 const REVIEW_STATUS_RE = /^(clean|p1-\d+items|p2-\d+items)$/
+const DEFAULT_MERGE_TIMEOUT_MS = 15 * 60 * 1000
+const MERGE_MAX_BUFFER = 64 * 1024 * 1024
+
+function mergeTimeoutMs(value) {
+  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
+}
+
+async function commitParents(cwd, sha) {
+  const line = await tryGit(cwd, ['rev-list', '--parents', '-n', '1', sha])
+  return line ? line.trim().split(/\s+/).slice(1) : []
+}
+
+/**
+ * Find a reachable merge commit whose second parent is one of the known tips.
+ * `--no-ff` merges put the integrated branch on the second parent, so this is
+ * the concrete evidence that a mission's work already landed in the base.
+ */
+async function findLandedMerge(cwd, baseTip, tips) {
+  const revs = (await tryGit(cwd, ['rev-list', '--merges', '-n', '100', baseTip])) ?? ''
+  for (const sha of revs.split('\n').filter(Boolean)) {
+    const parents = await commitParents(cwd, sha)
+    if (parents.length >= 2 && tips.has(parents[1])) return { commit: sha, parents }
+  }
+  return null
+}
+
+function describeGitFailure(error) {
+  const prefix = error?.timedOut ? 'timed out: ' : error?.bufferOverflow ? 'output buffer overflow: ' : ''
+  return `${prefix}${String(error?.message ?? error)}`
+}
+
+/** A killed git process can leave lock files behind; only used after a failed merge. */
+async function removeStaleGitLocks(commonDir) {
+  for (const name of ['index.lock', 'HEAD.lock', 'MERGE_HEAD.lock', 'ORIG_HEAD.lock']) {
+    await fsp.unlink(path.join(commonDir, name)).catch(() => {})
+  }
+}
 
 function globToRegExp(pattern) {
   let out = '^'
@@ -361,6 +407,8 @@ export function missionSummary(mission) {
     blockers: mission.blockers ?? [],
     tasks: taskCounts(mission.tasks ?? []),
     scopeGeneration: mission.scopeGeneration ?? 1,
+    mergedCommit: mission.mergedCommit ?? null,
+    mergedAt: mission.mergedAt ?? null,
     updatedAt: mission.updatedAt,
   }
 }
@@ -631,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) {
@@ -649,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)
@@ -707,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,
@@ -716,6 +791,7 @@ export class Tower {
         missionId: input.missionId,
         cwd: input.cwd ?? null,
         branch: input.branch ?? null,
+        spawnTip,
         state: 'active',
         spawnedAt: now,
       }
@@ -1067,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
@@ -1286,35 +1368,228 @@ 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
+   * the branch to the base tip. The evidence is concrete: a clean merge review
+   * exists and either the branch tip or the reviewed commit is already an
+   * ancestor of the base.
+   */
+  async reconcileLandedMerge(state, mission) {
+    if (!['completed', 'blocked'].includes(mission.status)) return null
+    if (!mission.worktree) return null
+    const branch = mission.worktree.branch
+    const reviews = (state.reviews ?? []).filter((review) => review.branch === branch)
+    if (reviews.length === 0) return null
+    const latest = reviews.reduce((a, b) => (a.round >= b.round ? a : b))
+    if (latest.status !== 'clean' || latest.mergeVerdict !== 'merge') return null
+    let baseTip
+    let branchTip
+    try {
+      baseTip = await revParse(this.root, state.base)
+      branchTip = await revParse(mission.worktree.path, 'HEAD')
+    } catch {
+      return null
+    }
+    const reviewedTip = latest.reviewedCommit
+    const branchLanded = await isAncestor(this.root, branchTip, baseTip)
+    const reviewedLanded = reviewedTip ? await isAncestor(this.root, reviewedTip, baseTip) : false
+    if (!branchLanded && !reviewedLanded) return null
+    const tips = new Set([branchTip, reviewedTip].filter(Boolean))
+    const found = await findLandedMerge(this.root, baseTip, tips)
+    const mergedCommit = found ? found.commit : reviewedLanded ? reviewedTip : branchTip
+    const now = Date.now()
+    mission.status = 'merged'
+    mission.mergedAt = now
+    mission.mergedCommit = mergedCommit
+    mission.blockers = []
+    mission.notes.push(
+      found
+        ? `reconciled already-landed merge ${mergedCommit.slice(0, 7)} with parents [${found.parents.map((parent) => parent.slice(0, 7)).join(', ')}]`
+        : `reconciled already-landed merge: ${mergedCommit.slice(0, 7)} is contained in ${state.base} (no merge commit found)`,
+    )
+    mission.updatedAt = 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: 'merge',
+      missionId: mission.id,
+      text: `reconciled already-landed ${mergedCommit.slice(0, 7)} on ${state.base}`,
+    })
+    return {
+      ok: true,
+      reconciled: true,
+      alreadyLanded: true,
+      mergedCommit,
+      baseTip,
+      branchTip,
+      parents: found ? found.parents : null,
+      review: {
+        round: latest.round,
+        status: latest.status,
+        mergeVerdict: latest.mergeVerdict,
+        reviewer: latest.reviewer,
+        reviewedCommit: reviewedTip,
+      },
+    }
+  }
+
   async merge(input) {
     return withLock(this.paths, async () => {
-      const gate = await this.evaluateGate(input)
-      if (!gate.ok) return { ok: false, blockers: gate.blockers, missionId: input.missionId }
       const state = await this.load()
       const mission = state.missions.find((entry) => entry.id === input.missionId)
+      if (!mission) {
+        return { ok: false, blockers: [{ code: 'mission-missing', detail: `unknown mission "${input.missionId}"` }] }
+      }
+      const baseTip = await revParse(this.root, state.base)
+      if (mission.status === 'merged') {
+        return { ok: true, alreadyMerged: true, mergedCommit: mission.mergedCommit ?? null, baseTip }
+      }
+      const reconciled = await this.reconcileLandedMerge(state, mission)
+      if (reconciled) return reconciled
+      const gate = await this.evaluateGate(input)
+      if (!gate.ok) return { ok: false, blockers: gate.blockers, missionId: input.missionId }
+
       const worktree = mission.worktree
-      const baseTipBefore = await revParse(this.root, state.base)
+      const baseTipBefore = await revParse(this.root, 'HEAD')
       const branchTip = await revParse(worktree.path, 'HEAD')
-
+      const timeoutMs = mergeTimeoutMs(input.timeoutMs)
+      let failure = null
       try {
-        await git(this.root, ['merge', '--no-ff', worktree.branch, '-m', `tower: merge ${mission.id} — ${mission.title}`])
+        await git(
+          this.root,
+          ['merge', '--no-ff', worktree.branch, '-m', `tower: merge ${mission.id} — ${mission.title}`],
+          { timeoutMs, maxBuffer: runtimeConfig().merge.maxBufferBytes || MERGE_MAX_BUFFER },
+        )
       } catch (error) {
-        await git(this.root, ['merge', '--abort']).catch(() => {})
+        failure = error
+      }
+
+      const newTip = await revParse(this.root, 'HEAD')
+      const parents = await commitParents(this.root, newTip)
+      const expectedShape = parents.length === 2 && parents[0] === baseTipBefore && parents[1] === branchTip
+      const warnings = []
+
+      if (failure && expectedShape) {
+        warnings.push(
+          `merge command reported a failure (${describeGitFailure(failure)}) but merge commit ${newTip.slice(0, 7)} exists; treated as merged`,
+        )
+        const dirty = (await git(this.root, ['status', '--porcelain']))
+          .split('\n')
+          .filter(Boolean)
+          .map((line) => line.slice(3).trim())
+        if (dirty.length > 0) {
+          const changed = new Set(gate.changedFiles ?? [])
+          if (dirty.every((file) => changed.has(file))) {
+            await git(this.root, ['reset', '--hard', 'HEAD'])
+            warnings.push('restored index/worktree to the merge commit (only merge-related paths were dirty)')
+          } else {
+            warnings.push('working tree still has unrelated changes; left untouched — inspect it before the next Git operation')
+          }
+        }
+      } else if (failure) {
+        const unmerged = (await tryGit(this.root, ['ls-files', '-u'])) ?? ''
+        const conflict = unmerged.trim().length > 0
+        let cleanup = 'none'
+        const mergeHeadPath = path.join(this.commonDir, 'MERGE_HEAD')
+        if (await exists(mergeHeadPath)) {
+          try {
+            await git(this.root, ['merge', '--abort'])
+            cleanup = 'aborted'
+          } catch {
+            await removeStaleGitLocks(this.commonDir)
+            try {
+              await git(this.root, ['merge', '--abort'])
+              cleanup = 'aborted-after-lock-cleanup'
+            } catch {
+              await git(this.root, ['reset', '--hard', baseTipBefore]).catch(() => {})
+              cleanup = 'reset'
+            }
+          }
+        } else if (newTip !== baseTipBefore) {
+          await removeStaleGitLocks(this.commonDir)
+          await git(this.root, ['reset', '--hard', baseTipBefore]).catch(() => {})
+          cleanup = 'reset'
+        }
+        // A killed git process can leave the index staged even without
+        // MERGE_HEAD. Restore only when every dirty path belongs to this merge.
+        const dirtyAfter = (await git(this.root, ['status', '--porcelain']))
+          .split('\n')
+          .filter(Boolean)
+          .map((line) => line.slice(3).trim())
+        if (dirtyAfter.length > 0) {
+          const changed = new Set(gate.changedFiles ?? [])
+          if (dirtyAfter.every((file) => changed.has(file))) {
+            await removeStaleGitLocks(this.commonDir)
+            await git(this.root, ['reset', '--hard', baseTipBefore]).catch(() => {})
+            cleanup = cleanup === 'none' ? 'reset' : `${cleanup}+reset`
+          } else {
+            warnings.push(`cleanup left unrelated changes untouched: ${dirtyAfter.slice(0, 5).join(', ')}`)
+          }
+        }
+        const detail = describeGitFailure(failure).slice(0, 2000)
         const now = Date.now()
-        mission.status = 'blocked'
-        mission.blockers.push(`merge conflict: ${String(error?.message ?? error).slice(0, 240)}`)
+        if (conflict) {
+          mission.status = 'blocked'
+          mission.blockers.push(`merge conflict: ${detail.slice(0, 240)}`)
+        } else {
+          mission.notes.push(`merge command failed before creating a commit (${detail.slice(0, 240)}); mission left ${mission.status} for retry`)
+        }
         mission.updatedAt = now
         state.revision += 1
         state.updatedAt = now
         await writeJsonAtomic(this.paths.state, state)
-        await appendJsonl(this.paths.activity, { at: now, type: 'merge', missionId: mission.id, text: 'conflict' })
-        return { ok: false, blockers: [{ code: 'merge-conflict', detail: String(error?.message ?? error) }] }
+        await appendJsonl(this.paths.activity, { at: now, type: 'merge', missionId: mission.id, text: `${conflict ? 'conflict' : 'failed-before-commit'} (${cleanup})` })
+        return {
+          ok: false,
+          missionId: mission.id,
+          blockers: [
+            {
+              code: conflict ? 'merge-conflict' : 'merge-hook-failed',
+              detail,
+              ...(failure.timedOut === true ? { timeout: true } : {}),
+              cleanup,
+            },
+          ],
+          ...(warnings.length > 0 ? { warnings } : {}),
+        }
       }
 
-      const newTip = await revParse(this.root, 'HEAD')
-      const parentLine = await git(this.root, ['rev-list', '--parents', '-n', '1', 'HEAD'])
-      const parents = parentLine.trim().split(/\s+/).slice(1)
-      if (parents.length !== 2 || parents[0] !== baseTipBefore || parents[1] !== branchTip) {
+      if (!expectedShape) {
         return {
           ok: false,
           blockers: [
@@ -1342,7 +1617,14 @@ export class Tower {
         missionId: mission.id,
         text: `${branchTip.slice(0, 7)} -> ${newTip.slice(0, 7)} on ${state.base}`,
       })
-      return { ok: true, mergedCommit: newTip, baseTip: baseTipBefore, branchTip, parents }
+      return {
+        ok: true,
+        mergedCommit: newTip,
+        baseTip: baseTipBefore,
+        branchTip,
+        parents,
+        ...(warnings.length > 0 ? { warnings, recoveredFromFailure: true } : {}),
+      }
     })
   }
 
@@ -1364,6 +1646,20 @@ export class Tower {
       }
       const oldTip = await revParse(mission.worktree.path, 'HEAD')
       const baseTip = await revParse(this.root, state.base)
+      if (await isAncestor(this.root, oldTip, baseTip)) {
+        // The branch is already contained in the base (manual merge, crashed
+        // merge, earlier fast-forward). Rewriting the branch tip to the base
+        // would destroy the reviewed tip and the ability to record the merge.
+        return {
+          ok: true,
+          alreadyMerged: true,
+          skipped: true,
+          oldTip,
+          newTip: oldTip,
+          baseTip,
+          note: `${oldTip.slice(0, 7)} is already contained in ${state.base} ${baseTip.slice(0, 7)}; branch left untouched — call tower_merge to record the landed merge`,
+        }
+      }
       if (await isAncestor(this.root, baseTip, oldTip)) {
         return { ok: true, alreadyUpToDate: true, oldTip, newTip: oldTip, baseTip }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tower",
-  "version": "1.1.2",
+  "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)
+}