dsh-tower 2.0.3 → 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

@@ -1,20 +1,22 @@
 // dsh-tower — Host entry.
 //
-// Tower mode is a session-level stance. The human owns it through the
-// `/tower` command: bare `/tower`, `/tower on [message]`, `/tower off
-// [message]`, and `/tower <message>` all work, and any trailing text is
-// forwarded to the model as the next user message. With
-// config.allowAgentControl the model may also enter or leave the mode through
-// `tower_control` when the user intent or task state clearly calls for it.
+// Tower mode is a session-level stance. It is intentionally operable by both
+// sides: the `/tower` command (bare `/tower`, `/tower on [message]`, `/tower
+// off [message]`, and `/tower <message>`; trailing text is forwarded to the
+// model as the next user message) and, when config.allowAgentControl is true
+// (the default), the model through `tower_control`. Every change is recorded
+// with its actor and reason; set allowAgentControl:false for human-only mode
+// control.
 //
 // `/tower reload` asks DSH HMR to reconcile this profile and reload the Tower
 // 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,
@@ -24,13 +26,19 @@ 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 ? modeState.get(key) : undefined
+  return Boolean(entry && entry.on === true)
+}
 const READ_ONLY_TOOL_NAMES = new Set([
   'tower_status',
   'tower_roster',
@@ -44,11 +52,11 @@ 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.',
   'Mission tracking lives in tower_plan / tower_mission / tower_status, not todo_write or the Team task board.',
   'Do not create or resume goals, do not spawn teammates, and never merge without a green tower_preflight.',
-  'Only the human can normally change this mode with /tower on|off.',
+  'Tower mode changes are explicit and recorded; the user can always use /tower on|off.',
 ].join(' ')
 
 const AGENT_CONTROL_NOTE =
-  'If tower_control is available you may also enter or leave Tower mode yourself when the user intent or task state clearly calls for it, and you must state a concrete reason.'
+  'You may also enter or leave Tower mode with tower_control when the user intent or task state clearly calls for it; always state a concrete reason.'
 
 function readPluginVersion() {
   if (pluginVersion !== null) return pluginVersion
@@ -80,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". */
@@ -150,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) {
@@ -171,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,
   })
@@ -185,14 +197,17 @@ 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 }
-  MODE.delete(key)
+  const wasOn = previous.on === true
+  // Keep a timestamped off tombstone so a concurrent save from another
+  // session cannot resurrect this mode entry.
+  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(() => {})
   }
-  return { wasOn: true, pausedGoal: previous.pausedGoal ?? null, goalNote: null, by, reason: reason ?? null }
+  return { wasOn, pausedGoal: previous.pausedGoal ?? null, goalNote: null, by, reason: reason ?? null }
 }
 
 function forwardInstruction(agent, message, attachments) {
@@ -237,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
@@ -255,8 +271,8 @@ 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)
-      if (!entry) return
+      const entry = modeState.get(key)
+      if (!entry || entry.on !== true) return
       const repo = await resolveRepo(repoRoot)
       const existing = entry.lock
       if (existing && existing.commonDir !== repo.commonDir) {
@@ -304,7 +320,26 @@ export function apply(ctx, rawConfig) {
     },
     basePreference(exec) {
       const key = agentKey(exec?.agent)
-      return 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,
+      }
     },
   }
 
@@ -314,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(() => {})
       }
@@ -324,7 +359,7 @@ export function apply(ctx, rawConfig) {
   ctx.effect(() =>
     ctx.tools.guard((execution) => {
       const key = agentKey(execution.agent)
-      if (!key || !MODE.has(key)) return undefined
+      if (!key || !modeOn(key)) return undefined
       if (denyTools.has(execution.name)) {
         return `tower mode: ${execution.name} is disabled while Tower mode is active; use the Tower tools or /tower off`
       }
@@ -345,7 +380,7 @@ export function apply(ctx, rawConfig) {
     typeof ctx.on === 'function'
       ? ctx.on('agent/pre-step', (payload, next) => {
           const key = agentKey(payload?.agent)
-          if (key && MODE.has(key)) {
+          if (key && modeOn(key)) {
             // Once Tower is active, Tower wins regardless of entry policy: clear
             // any plan state so the two policies cannot coexist.
             const state = planModeState(ctx, payload.agent)
@@ -359,13 +394,13 @@ export function apply(ctx, rawConfig) {
   ctx.systemPrompt.section({
     name: 'tower:mode',
     order: 15000,
-    text: (context) => (context && MODE.has(agentKey(context.agent)) ? reminder : ''),
+    text: (context) => (context && modeOn(agentKey(context.agent)) ? reminder : ''),
   })
 
   // 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(() => {})
       }
@@ -402,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),
@@ -464,17 +500,25 @@ 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,
             action: args.action,
-            mode: MODE.has(key) ? 'on' : 'off',
+            mode: modeOn(key) ? 'on' : 'off',
             changed: args.action === 'enter' ? !outcome.wasOn : outcome.wasOn,
             changedBy: 'agent',
             reason,
@@ -490,14 +534,21 @@ 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)
-          if (!entry) return { kind: 'error', text: 'Run /tower on first, then /tower base <branch>.' }
+          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()
           return { kind: 'success', text: `Tower base preference set to "${entry.baseBranch}"; tower_init without an explicit base will use it.` }
@@ -517,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')
+}