dsh-tower 2.0.4 → 2.1.0-beta.1

package/domain/vocabulary.js

@@ -0,0 +1,179 @@
+// Pure shared vocabulary (#56 P5): every status/type/action enum used by the
+// tool contracts and handlers. Keeping one canonical value set here lets
+// tools/** import constants/predicates instead of spelling literals.
+// No fs, git, or config.
+// @ts-check
+
+import {
+  FINDING_SEVERITIES,
+  FINDING_STATUSES,
+  FINDING_TYPES,
+  MERGE_VERDICTS,
+  MISSION_STATUSES,
+  PAUSE_CAUSES,
+} from './mission.js'
+import { ROSTER_INACTIVE_STATES } from './roster.js'
+
+export {
+  FINDING_SEVERITIES,
+  FINDING_STATUSES,
+  FINDING_TYPES,
+  MERGE_VERDICTS,
+  MISSION_STATUSES,
+  PAUSE_CAUSES,
+  ROSTER_INACTIVE_STATES,
+}
+
+// Mission inputs accepted by tower_plan.
+/** @type {readonly string[]} */
+export const MISSION_KINDS = ['build', 'survey']
+/** @type {readonly string[]} */
+export const REVIEW_POLICIES = ['required-clean', 'none']
+
+// Roster actors (the caller resolved by actorFor) and createable agent roles.
+export const ROLE = Object.freeze({
+  tower: 'tower',
+  worker: 'worker',
+  reviewer: 'reviewer',
+  unknown: 'unknown',
+})
+/** @type {readonly string[]} */
+export const ROLES = Object.freeze([ROLE.worker, ROLE.reviewer])
+/** @type {readonly string[]} */
+export const ACTOR_ROLES = Object.freeze([ROLE.tower, ROLE.worker, ROLE.reviewer, ROLE.unknown])
+export const DEFAULT_ROLE = ROLE.worker
+
+/** @param {string | null | undefined} role */
+export function isTowerRole(role) {
+  return role === ROLE.tower
+}
+
+/** @param {string | null | undefined} role */
+export function isWorkerRole(role) {
+  return role === ROLE.worker
+}
+
+/** @param {string | null | undefined} role */
+export function isReviewerRole(role) {
+  return role === ROLE.reviewer
+}
+
+/** @param {string | null | undefined} role */
+export function isUnknownRole(role) {
+  return role === ROLE.unknown
+}
+
+// Inbox recipients: a roster name, the tower, or a broadcast.
+export const RECIPIENT = Object.freeze({ tower: ROLE.tower, all: 'all' })
+
+/** @param {string | null | undefined} to */
+export function isTowerRecipient(to) {
+  return to === RECIPIENT.tower
+}
+
+/** @param {string | null | undefined} to */
+export function isBroadcast(to) {
+  return to === RECIPIENT.all
+}
+
+// Action discriminators for the repository tools.
+export const BATCH_ACTION = Object.freeze({
+  create: 'create',
+  status: 'status',
+  close: 'close',
+  abandon: 'abandon',
+})
+/** @type {readonly string[]} */
+export const BATCH_ACTIONS = Object.freeze(Object.values(BATCH_ACTION))
+
+export const RECOVERY_ACTION = Object.freeze({ status: 'status', clearStaleLock: 'clear-stale-lock' })
+/** @type {readonly string[]} */
+export const RECOVERY_ACTIONS = Object.freeze(Object.values(RECOVERY_ACTION))
+export const RECOVERY_CONFIRM = 'CLEAR_STALE_LOCK'
+
+export const LEASE_ACTION = Object.freeze({ acquire: 'acquire', release: 'release', status: 'status' })
+/** @type {readonly string[]} */
+export const LEASE_ACTIONS = Object.freeze(Object.values(LEASE_ACTION))
+
+export const LEGACY_MAP_ACTION = Object.freeze({ map: 'map', status: 'status' })
+/** @type {readonly string[]} */
+export const LEGACY_MAP_ACTIONS = Object.freeze(Object.values(LEGACY_MAP_ACTION))
+
+export const STATUS_FORMAT = Object.freeze({ json: 'json', markdown: 'markdown' })
+/** @type {readonly string[]} */
+export const STATUS_FORMATS = Object.freeze(Object.values(STATUS_FORMAT))
+
+/** @param {string | null | undefined} format */
+export function isMarkdownFormat(format) {
+  return format === STATUS_FORMAT.markdown
+}
+
+// Finding filters extend the lifecycle statuses with the read-only "all".
+export const FINDING_FILTER_ALL = 'all'
+/** @type {readonly string[]} */
+export const FINDING_FILTER_STATUSES = Object.freeze([...FINDING_STATUSES, FINDING_FILTER_ALL])
+
+// Test admission modes read from config by tower_spawn/tower_complete.
+export const TESTS_ADMISSION = Object.freeze({ off: 'off', spawn: 'spawn', complete: 'complete' })
+/** @type {readonly string[]} */
+export const TESTS_ADMISSIONS = Object.freeze(Object.values(TESTS_ADMISSION))
+
+/** @param {string | null | undefined} admission */
+export function isSpawnAdmission(admission) {
+  return admission === TESTS_ADMISSION.spawn
+}
+
+/** @param {string | null | undefined} admission */
+export function isCompleteAdmission(admission) {
+  return admission === TESTS_ADMISSION.complete
+}
+
+// Roster row states and observed catalog activity.
+export const ROSTER_STATE = Object.freeze({
+  reserved: 'reserved',
+  active: 'active',
+  inactive: 'inactive',
+  retired: 'retired',
+  failed: 'failed',
+  interrupted: 'interrupted',
+  missing: 'missing',
+  stale: 'stale',
+})
+export const ROSTER_STATES = Object.freeze([...ROSTER_INACTIVE_STATES, ROSTER_STATE.reserved, ROSTER_STATE.active])
+/** States treated as gone by roster reporting, excluding "inactive". */
+export const ROSTER_GONE_STATES = Object.freeze([
+  ROSTER_STATE.retired,
+  ROSTER_STATE.failed,
+  ROSTER_STATE.interrupted,
+  ROSTER_STATE.missing,
+  ROSTER_STATE.stale,
+])
+export const ROSTER_ACTIVITY = Object.freeze({
+  running: 'running',
+  inactive: 'inactive',
+  missing: 'missing',
+  unknown: 'unknown',
+})
+export const PARENT_STATUS_OK = 'ok'
+
+/** @param {string | null | undefined} state */
+export function isReservedState(state) {
+  return state === ROSTER_STATE.reserved
+}
+
+/** @param {string | null | undefined} activity */
+export function isRunningActivity(activity) {
+  return activity === ROSTER_ACTIVITY.running
+}
+
+// Spawn completion outcomes recorded in the roster.
+export const SPAWN_OUTCOME = Object.freeze({ failed: 'failed', inactive: 'inactive' })
+export const STOP_REASON = Object.freeze({ completed: 'completed' })
+
+/** @param {string | null | undefined} reason */
+export function isCompletedStopReason(reason) {
+  return reason === STOP_REASON.completed
+}
+
+// Doctor check severities.
+export const DOCTOR_STATUS = Object.freeze({ pass: 'pass', warn: 'warn', fail: 'fail' })

package/index.js

@@ -12,10 +12,11 @@
 // plugin from disk when the HMR service is present (dev/linked installs).
 import fs from 'node:fs'
 import { randomUUID } from 'node:crypto'
-import { registerTowerTools } from './lib/tools.js'
+import { registerTowerTools } from './lib/tool-registry.js'
 import { loadModes, saveModes, storePath } from './lib/modeStore.js'
+import { ModeState } from './lib/modeState.js'
 import { Config as ConfigSchema, DEFAULT_DENY_TOOLS, configureRuntime, runtimeConfig } from './lib/config.js'
-import { TowerToolError } from './lib/errors.js'
+import { TowerToolError } from './domain/errors.js'
 import { resolveRepo } from './lib/git.js'
 import {
   acquireWorkspaceLock,
@@ -25,16 +26,17 @@ import {
   workspaceLockToken,
 } from './lib/workspaceLock.js'
 import { createHmrBridge } from './lib/hmr.js'
+import { assertPresetsAvailable } from './lib/presets.js'
 
 export const name = 'dsh-tower'
 export const inject = ['tools', 'systemPrompt']
 export const Config = ConfigSchema
 
-let MODE = new Map()
+const modeState = new ModeState()
 let denyTools = new Set(DEFAULT_DENY_TOOLS)
 
 function modeOn(key) {
-  const entry = key ? MODE.get(key) : undefined
+  const entry = key ? modeState.get(key) : undefined
   return Boolean(entry && entry.on === true)
 }
 const READ_ONLY_TOOL_NAMES = new Set([
@@ -86,7 +88,9 @@ function configSection(config, allowAgentControl) {
 
 function persistModes() {
   const config = runtimeConfig()
-  saveModes(MODE, config.mode.storePath || undefined, config.mode.maxEntries)
+  saveModes(modeState, config.mode.storePath || undefined, config.mode.maxEntries, {
+    timeoutMs: config.mode.lockTimeoutMs,
+  })
 }
 
 /** Parse `/tower` arguments: bare and free text both mean "ensure on". */
@@ -156,7 +160,7 @@ function clearPlanModeForTower(ctx, agent) {
 }
 
 function enterMode(ctx, key, agent, by, reason) {
-  const previous = MODE.get(key)
+  const previous = modeState.get(key)
   const wasOn = Boolean(previous && previous.on)
   const plan = clearPlanModeForTower(ctx, agent)
   if (plan.refused) {
@@ -177,12 +181,14 @@ function enterMode(ctx, key, agent, by, reason) {
     }
   }
   const now = Date.now()
-  MODE.set(key, {
+  modeState.set(key, {
     on: true,
     pausedGoal,
     lock: previous?.lock ?? null,
     baseBranch: previous?.baseBranch ?? null,
     planModeCleared: plan.cleared,
+    humanAckAt: by === 'user' ? previous?.humanAckAt ?? now : previous?.humanAckAt ?? null,
+    lastDisclosure: previous?.lastDisclosure ?? 'full',
     lastChange: { by, action: 'on', reason: reason ?? null, at: now },
     at: now,
   })
@@ -191,12 +197,12 @@ function enterMode(ctx, key, agent, by, reason) {
 }
 
 async function exitMode(key, by, reason) {
-  const previous = MODE.get(key)
+  const previous = modeState.get(key)
   if (!previous) return { wasOn: false, pausedGoal: null, goalNote: null }
   const wasOn = previous.on === true
   // Keep a timestamped off tombstone so a concurrent save from another
   // session cannot resurrect this mode entry.
-  MODE.set(key, { on: false, at: Date.now() })
+  modeState.set(key, { on: false, at: Date.now(), humanAckAt: previous.humanAckAt ?? null, lastDisclosure: previous.lastDisclosure ?? 'exit' })
   persistModes()
   if (previous.lock) {
     await releaseWorkspaceLock(previous.lock.commonDir, { token: previous.lock.token }).catch(() => {})
@@ -246,7 +252,8 @@ export function apply(ctx, rawConfig) {
   const config = configureRuntime(rawConfig)
   const allowAgentControl = config.mode.allowAgentControl === true
   const reminder = configSection(config, allowAgentControl)
-  MODE = loadModes(config.mode.storePath || undefined)
+  modeState.replace(loadModes(config.mode.storePath || undefined))
+  if (typeof ctx.provide === 'function') ctx.provide('tower', modeState)
   denyTools = new Set(config.mode.denyTools)
   const hotReloadEnabled = config.dev?.hotReload !== false
   const hmrBridge = hotReloadEnabled
@@ -264,7 +271,7 @@ export function apply(ctx, rawConfig) {
       if (runtimeConfig().mode.workspaceLockScope === 'mutations' && READ_ONLY_TOOL_NAMES.has(toolName)) return
       const key = agentKey(exec?.agent)
       if (!key) return
-      const entry = MODE.get(key)
+      const entry = modeState.get(key)
       if (!entry || entry.on !== true) return
       const repo = await resolveRepo(repoRoot)
       const existing = entry.lock
@@ -313,7 +320,26 @@ export function apply(ctx, rawConfig) {
     },
     basePreference(exec) {
       const key = agentKey(exec?.agent)
-      return key && modeOn(key) ? MODE.get(key)?.baseBranch ?? null : null
+      return key && modeOn(key) ? modeState.get(key)?.baseBranch ?? null : null
+    },
+    modeInfo(exec) {
+      const key = agentKey(exec?.agent)
+      if (!key) return null
+      const entry = modeState.get(key)
+      const history = [...modeState.values()]
+        .map((value) => value?.lastChange)
+        .filter((change) => change && typeof change.at === 'number')
+        .sort((a, b) => b.at - a.at)
+        .slice(0, 10)
+      return {
+        mode: modeOn(key) ? 'on' : entry ? 'off' : 'unknown',
+        allowAgentControl: runtimeConfig().mode.allowAgentControl === true,
+        lastChange: entry?.lastChange ?? null,
+        history,
+        workspaceLock: entry?.lock
+          ? { enabled: runtimeConfig().mode.workspaceLock === true, commonDir: entry.lock.commonDir }
+          : null,
+      }
     },
   }
 
@@ -323,7 +349,7 @@ export function apply(ctx, rawConfig) {
   // process still owns; a reloaded plugin restores the entries from modes.json.
   ctx.effect(() => () => {
     if (hmrBridge) hmrBridge.dispose?.()
-    for (const entry of MODE.values()) {
+    for (const entry of modeState.values()) {
       if (entry?.lock) {
         releaseWorkspaceLock(entry.lock.commonDir, { token: entry.lock.token }).catch(() => {})
       }
@@ -374,7 +400,7 @@ export function apply(ctx, rawConfig) {
   // Workspace-lock heartbeat; only sessions holding a lock do I/O.
   ctx.effect(() => {
     const timer = setInterval(() => {
-      for (const entry of MODE.values()) {
+      for (const entry of modeState.values()) {
         if (!entry?.lock) continue
         touchWorkspaceLock(entry.lock.commonDir, { token: entry.lock.token }).catch(() => {})
       }
@@ -411,12 +437,13 @@ export function apply(ctx, rawConfig) {
       },
       async execute(_args, exec) {
         const key = agentKey(exec.agent)
-        const entry = key ? MODE.get(key) : undefined
+        const entry = key ? modeState.get(key) : undefined
         return {
           mode: entry && entry.on === true ? 'on' : key ? 'off' : 'unknown',
           agentId: key,
           allowAgentControl,
           lastChange: entry?.lastChange ?? null,
+          lastDisclosure: entry?.lastDisclosure ?? null,
           pausedGoal: entry?.pausedGoal ?? null,
           deniedWhileActive: [...denyTools],
           persistedAt: storePath(config.mode.storePath || undefined),
@@ -473,12 +500,20 @@ export function apply(ctx, rawConfig) {
           const key = agentKey(exec.agent)
           if (!key) return { ok: false, error: 'tower_control requires a live calling agent' }
           if (typeof args.reason !== 'string' || args.reason.trim().length === 0) {
-            throw new Error('tower_control requires a non-empty reason')
+            throw new TowerToolError('invalid-argument', 'tower_control requires a non-empty reason')
           }
           const reason = args.reason.trim()
+          if (args.action === 'enter' && !modeOn(key)) {
+            await assertPresetsAvailable(ctx, config)
+          }
           const outcome =
             args.action === 'enter'
-              ? enterMode(ctx, key, exec.agent, 'agent', reason)
+              ? (() => {
+                  if (!modeOn(key) && runtimeConfig().mode.requireHumanAckOnFirstEntry === true && !modeState.get(key)?.humanAckAt) {
+                    throw new TowerToolError('not-authorized', 'this profile requires a human acknowledgement; run /tower ack first')
+                  }
+                  return enterMode(ctx, key, exec.agent, 'agent', reason)
+                })()
               : await exitMode(key, 'agent', reason)
           return {
             ok: true,
@@ -499,13 +534,20 @@ export function apply(ctx, rawConfig) {
     commandCtx.commands.register({
       name: 'tower',
       description: 'Enter or leave Tower mode, optionally carrying a user instruction; /tower reload reloads via HMR; /tower base <branch> sets the next init base',
-      input: { hint: '[on|off|reload|base <branch>] [message]', attachments: true },
+      input: { hint: '[on|off|reload|ack|base <branch>] [message]', attachments: true },
       handler: async ({ agent, rawInput, attachments }) => {
         const key = agentKey(agent)
         if (!key) return { kind: 'error', text: 'Tower mode requires a live agent.' }
-        const baseMatch = String(rawInput ?? '').trim().match(/^base\s+(\S+)\s*$/i)
+        const raw = String(rawInput ?? '').trim()
+        if (/^ack$/i.test(raw)) {
+          const previous = modeState.get(key) ?? { on: false }
+          modeState.set(key, { ...previous, on: previous.on === true, humanAckAt: Date.now(), at: Date.now() })
+          persistModes()
+          return { kind: 'success', text: 'Human acknowledgement recorded; the model may now make the first Tower-mode entry in this session.' }
+        }
+        const baseMatch = raw.match(/^base\s+(\S+)\s*$/i)
         if (baseMatch) {
-          const entry = MODE.get(key)
+          const entry = modeState.get(key)
           if (!entry || entry.on !== true) return { kind: 'error', text: 'Run /tower on first, then /tower base <branch>.' }
           entry.baseBranch = baseMatch[1]
           persistModes()
@@ -526,6 +568,7 @@ export function apply(ctx, rawConfig) {
           }
         }
         const { active, message } = parsed
+        if (active) await assertPresetsAvailable(ctx, config)
         const outcome = active
           ? enterMode(ctx, key, agent, 'user', message || null)
           : await exitMode(key, 'user', message || null)

package/lib/briefing.js

@@ -0,0 +1,176 @@
+// Mission briefings: pure text builders for worker/reviewer prompts.
+
+function clip(text, max = 2000) {
+  const value = String(text ?? '')
+  return value.length > max ? `${value.slice(0, max)}\n… truncated` : value
+}
+
+export function workerBriefing({
+  repoRoot,
+  base,
+  mission,
+  deps,
+  worktree,
+  instructions,
+  reviews = [],
+  findings = [],
+  completionReport = null,
+}) {
+  const completion = /** @type {import('../types/index.js').CompletionReport | null} */ (completionReport)
+  const lines = []
+  lines.push(`# Tower mission ${mission.id} — ${mission.title}`)
+  lines.push('')
+  lines.push(`You are the tower worker for mission ${mission.id} in repository ${repoRoot}.`)
+  lines.push('')
+  lines.push(`Work ONLY in this git worktree: ${worktree.path}`)
+  lines.push(`Branch: ${worktree.branch} (based on ${base} @ ${String(worktree.baseCommit).slice(0, 12)})`)
+  lines.push('')
+  lines.push(`Kind: ${mission.kind}`)
+  lines.push(
+    `Scope (only files you may touch): ${mission.scope.length > 0 ? mission.scope.join(', ') : '(none — survey is read-only)'}`,
+  )
+  if (mission.tasks.length > 0) {
+    lines.push('Tasks:')
+    for (const task of mission.tasks) lines.push(`- [${task.status}] ${task.text}`)
+  }
+  if (deps.length > 0) {
+    lines.push('Dependencies:')
+    for (const dep of deps) lines.push(`- ${dep.id} ${dep.title ?? ''} (${dep.status})`)
+  }
+  if (mission.context) {
+    lines.push('Context (verbatim from the user):')
+    lines.push(mission.context)
+  }
+  if ((mission.references ?? []).length > 0) {
+    lines.push('References (read-only pointers; read them before deciding):')
+    for (const reference of mission.references) lines.push(`- ${reference}`)
+  }
+  if (mission.reviewPolicy === 'none') {
+    lines.push(`Review policy: none (user exemption: ${mission.reviewExemptionReason ?? 'missing reason'})`)
+  }
+  if (completion) {
+    lines.push('')
+    lines.push(`Previous completion report (by ${completion.by ?? 'worker'}):`)
+    lines.push(clip(completion.report, 1500))
+    if ((completion.checks ?? []).length > 0) {
+      lines.push('Previous checks:')
+      for (const check of completion.checks ?? []) lines.push(`- ${check.name}${check.exitCode !== undefined ? ` (exit ${check.exitCode})` : ''}`)
+    }
+  }
+  if (reviews.length > 0) {
+    lines.push('')
+    lines.push('Previous review rounds for this branch (newest first) — address every finding:')
+    for (const review of reviews) {
+      lines.push(`- R${review.round} by ${review.reviewer}: ${review.status} / ${review.mergeVerdict}`)
+      if (review.findings) lines.push(`  findings: ${clip(review.findings, 1200).replaceAll('\n', '\n  ')}`)
+      if (review.decision) lines.push(`  decision: ${clip(review.decision, 600)}`)
+    }
+  }
+  if (findings.length > 0) {
+    lines.push('')
+    lines.push('Findings related to this mission:')
+    for (const finding of findings) lines.push(`- ${finding.id} [${finding.status}] ${finding.severity ?? 'severity?'} ${finding.title}`)
+  }
+  lines.push('')
+  lines.push('Rules:')
+  lines.push(`- Pass workdir="${worktree.path}" on every shell command; never edit the main checkout.`)
+  lines.push('- Stay inside the declared scope; out-of-scope changes are rejected later.')
+  lines.push('- Commit your work on the mission branch. Do not merge, push, or spawn other agents.')
+  lines.push(
+    `- Update progress: tower_mission({repoRoot:"${repoRoot}",id:"${mission.id}",task_done:"..."}) or blocker:"...".`,
+  )
+  lines.push(
+    `- When the work is finished and every task is closed, call tower_complete({repoRoot:"${repoRoot}",missionId:"${mission.id}",report:"<full handoff>",checks:[{name,command,exitCode,evidence}]}). Unread inbox messages block completion, so read them with tower_inbox first.`,
+  )
+  lines.push('- Your final message is the full handoff: files changed, how you verified, what remains.')
+  if (instructions) {
+    lines.push('')
+    lines.push('Extra tower instructions:')
+    lines.push(instructions)
+  }
+  return lines.join('\n')
+}
+
+export function reviewerBriefing({
+  repoRoot,
+  base,
+  mission,
+  deps,
+  worktree,
+  instructions,
+  reviews = [],
+  findings = [],
+  completionReport = null,
+}) {
+  const completion = /** @type {import('../types/index.js').CompletionReport | null} */ (completionReport)
+  const lines = []
+  lines.push(`# Tower review — mission ${mission.id} — ${mission.title}`)
+  lines.push('')
+  lines.push(`You are the independent reviewer for mission ${mission.id} in repository ${repoRoot}.`)
+  lines.push('')
+  lines.push(`Review branch: ${worktree.branch}`)
+  lines.push(`Worktree: ${worktree.path}`)
+  lines.push(`Reviewed base: ${base} @ ${String(worktree.baseCommit).slice(0, 12)}`)
+  lines.push('')
+  lines.push(`Kind: ${mission.kind}`)
+  if (mission.tasks.length > 0) {
+    lines.push('The worker was asked to complete:')
+    for (const task of mission.tasks) lines.push(`- [${task.status}] ${task.text}`)
+  }
+  if (deps.length > 0) {
+    lines.push('Dependencies:')
+    for (const dep of deps) lines.push(`- ${dep.id} ${dep.title ?? ''} (${dep.status})`)
+  }
+  if (mission.context) {
+    lines.push('Context (verbatim from the user):')
+    lines.push(mission.context)
+  }
+  if ((mission.references ?? []).length > 0) {
+    lines.push('References (read-only pointers):')
+    for (const reference of mission.references) lines.push(`- ${reference}`)
+  }
+  if (completion) {
+    lines.push('')
+    lines.push(`Completion report (by ${completion.by ?? 'worker'}):`)
+    lines.push(clip(completion.report, 2000))
+    if ((completion.checks ?? []).length > 0) {
+      lines.push('Completion checks the worker ran:')
+      for (const check of completion.checks ?? []) {
+        lines.push(
+          `- ${check.name}${check.exitCode !== undefined ? ` (exit ${check.exitCode})` : ''}${check.evidence ? ` — ${clip(check.evidence, 400)}` : ''}`,
+        )
+      }
+    }
+  }
+  if (reviews.length > 0) {
+    lines.push('')
+    lines.push('Prior review rounds for this branch (newest first):')
+    for (const review of reviews) {
+      lines.push(`- R${review.round} by ${review.reviewer}: ${review.status} / ${review.mergeVerdict}`)
+      if (review.findings) lines.push(`  findings: ${clip(review.findings, 1200).replaceAll('\n', '\n  ')}`)
+    }
+  }
+  if (findings.length > 0) {
+    lines.push('')
+    lines.push('Related findings:')
+    for (const finding of findings) lines.push(`- ${finding.id} [${finding.status}] ${finding.severity ?? 'severity?'} ${finding.title}`)
+  }
+  lines.push('')
+  lines.push('Rules:')
+  lines.push('- Read-only: do not modify files, commit, or merge.')
+  lines.push('- Inspect the diff from the reviewed base to the branch tip and map every task to the diff.')
+  lines.push('- Check scope, correctness, tests, and security. Report severity and concrete evidence.')
+  lines.push(
+    `- Submit the formal verdict with tower_review({repoRoot:"${repoRoot}",missionId:"${mission.id}",status:"clean",merge:"merge",findings:"none",checks:["..."],decision:"..."}). Use status "p1-Nitems"/"p2-Nitems" and merge "fix-then-merge"/"hold" for problems; a non-clean verdict returns the mission to active.`,
+  )
+  lines.push(
+    `- File out-of-scope issues with tower_finding({repoRoot:"${repoRoot}",type:"bug",title:"...",summary:"...",details:"...",suggested_fix:"..."}) instead of fixing them.`,
+  )
+  lines.push('- Your final message is the review report; the tool call above is the formal verdict.')
+  if (instructions) {
+    lines.push('')
+    lines.push('Extra tower instructions:')
+    lines.push(instructions)
+  }
+  return lines.join('\n')
+}

package/lib/compatibility.js

@@ -0,0 +1,108 @@
+// Release compatibility provenance. COMPATIBILITY.md is shipped in the package;
+// no network lookup is involved.
+import { fs } from '../adapters/store-fs.js'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+export function parseVersion(value) {
+  const text = String(value ?? '').trim()
+  const match = text.match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/)
+  if (!match) return null
+  return {
+    numbers: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4] ? match[4].split('.') : [],
+  }
+}
+
+function comparePrerelease(a, b) {
+  if (a.length === 0 && b.length === 0) return 0
+  if (a.length === 0) return 1
+  if (b.length === 0) return -1
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    if (a[index] === undefined) return -1
+    if (b[index] === undefined) return 1
+    const aNumber = /^\d+$/.test(a[index])
+    const bNumber = /^\d+$/.test(b[index])
+    if (aNumber && bNumber) {
+      const delta = Number(a[index]) - Number(b[index])
+      if (delta !== 0) return delta
+    } else if (aNumber !== bNumber) {
+      return aNumber ? -1 : 1
+    } else if (a[index] !== b[index]) {
+      return a[index] < b[index] ? -1 : 1
+    }
+  }
+  return 0
+}
+
+export function compareVersions(a, b) {
+  const left = typeof a === 'string' ? parseVersion(a) : a
+  const right = typeof b === 'string' ? parseVersion(b) : b
+  if (!left || !right) return null
+  for (let index = 0; index < 3; index += 1) {
+    if (left.numbers[index] !== right.numbers[index]) return left.numbers[index] < right.numbers[index] ? -1 : 1
+  }
+  return comparePrerelease(left.prerelease, right.prerelease)
+}
+
+export function parseCompatibility(text) {
+  const rows = []
+  for (const line of String(text ?? '').split('\n')) {
+    if (!/^\|/.test(line)) continue
+    const cells = line.split('|').slice(1, -1).map((cell) => cell.trim())
+    if (cells.length < 4) continue
+    if (!parseVersion(cells[0])) continue
+    rows.push({ hostVersion: cells[0], commit: cells[1], verifiedOn: cells[2], ran: cells[3] })
+  }
+  return rows
+}
+
+export function readCompatibility(file = path.join(PACKAGE_ROOT, 'COMPATIBILITY.md')) {
+  try {
+    return parseCompatibility(fs.readFileSync(file, 'utf8'))
+  } catch {
+    return []
+  }
+}
+
+export function assessHostVersion(hostVersion, rows) {
+  const parsed = parseVersion(hostVersion)
+  if (!parsed) return { verdict: 'unknown', row: null, detail: 'cannot parse the running host version' }
+  const exact = rows.find((row) => compareVersions(row.hostVersion, parsed) === 0)
+  if (exact) return { verdict: 'verified', row: exact, detail: `${exact.hostVersion} verified on ${exact.verifiedOn}` }
+  const known = rows
+    .map((row) => ({ row, cmp: compareVersions(parsed, row.hostVersion) }))
+    .filter((entry) => entry.cmp !== null)
+  if (known.length === 0) return { verdict: 'unknown', row: null, detail: 'COMPATIBILITY.md has no version rows' }
+  const newest = known.reduce((best, entry) => (entry.cmp > best.cmp ? entry : best), known[0])
+  if (newest.cmp > 0) {
+    return {
+      verdict: 'untested-newer',
+      row: newest.row,
+      detail: `${hostVersion} is newer than every verified build (latest row ${newest.row.hostVersion})`,
+    }
+  }
+  return {
+    verdict: 'untested-older',
+    row: newest.row,
+    detail: `${hostVersion} is older than the verified builds (latest row ${newest.row.hostVersion})`,
+  }
+}
+
+export function detectHostVersion(ctx, env = process.env) {
+  for (const value of [env.DSH_VERSION, env.DSH_HOST_VERSION, env.npm_config_dsh_version]) {
+    if (typeof value === 'string' && parseVersion(value)) return value
+  }
+  for (const serviceName of ['app', 'runtime', 'host']) {
+    try {
+      const service = ctx?.get?.(serviceName)
+      const value = service && (service.version ?? service.build?.version)
+      if (typeof value === 'string' && parseVersion(value)) return value
+    } catch {
+      // defensive: a missing service is not a doctor failure
+    }
+  }
+  return null
+}