dsh-tower 2.1.0 → 2.4.0

package/domain/events.js

@@ -0,0 +1,207 @@
+// Stable domain events (#75).
+//
+// The domain layer *describes* what changed; `app/` persists the state and only
+// then emits the event through the injected event port. `state.json` remains the
+// authoritative record — events are a process-local observation channel, not an
+// event-sourced log, and are never replayed.
+//
+// The table below is the single source of truth for the generated reference
+// (`docs/reference/events.md`), so a rename cannot drift from the runtime.
+// Every domain event carries `{ missionId, revision, at }`; `merged` also
+// carries the merge `commit`. Names are dotted (`tower.mission.*`); the older
+// tool-shaped `tower/<tool>` aliases stay for one minor release and are marked
+// deprecated in the generated reference.
+// @ts-check
+
+/** @typedef {'planned'|'completed'|'reviewed'|'merged'|'abandoned'} MissionEventType */
+
+/**
+ * @typedef {object} MissionEventEntry
+ * @property {MissionEventType} type
+ * @property {string} name
+ * @property {string[]} payload
+ * @property {string} description
+ */
+
+/** Stable domain-fact events (`tower.mission.*`). */
+export const MISSION_EVENTS = Object.freeze({
+  planned: {
+    type: 'planned',
+    name: 'tower.mission.planned',
+    payload: ['missionId', 'revision', 'at'],
+    description: 'tower_plan persisted one or more new missions',
+  },
+  completed: {
+    type: 'completed',
+    name: 'tower.mission.completed',
+    payload: ['missionId', 'revision', 'at'],
+    description: 'tower_complete recorded a completion report (or tower_mission set status "completed")',
+  },
+  reviewed: {
+    type: 'reviewed',
+    name: 'tower.mission.reviewed',
+    payload: ['missionId', 'revision', 'at'],
+    description: 'tower_review recorded a verdict for the mission branch',
+  },
+  merged: {
+    type: 'merged',
+    name: 'tower.mission.merged',
+    payload: ['missionId', 'revision', 'at', 'commit'],
+    description: 'tower_merge recorded the merge commit that landed the mission branch',
+  },
+  abandoned: {
+    type: 'abandoned',
+    name: 'tower.mission.abandoned',
+    payload: ['missionId', 'revision', 'at'],
+    description: 'a mission transitioned to "abandoned"',
+  },
+})
+
+/** @type {readonly MissionEventType[]} */
+export const MISSION_EVENT_TYPES = Object.freeze(['planned', 'completed', 'reviewed', 'merged', 'abandoned'])
+
+/** @type {readonly MissionEventEntry[]} */
+export const MISSION_EVENT_TABLE = Object.freeze(
+  MISSION_EVENT_TYPES.map((type) => /** @type {MissionEventEntry} */ (MISSION_EVENTS[type])),
+)
+
+/** Tool-shaped alias events, kept for one minor release (#75). */
+export const LEGACY_TOOL_EVENT_TABLE = Object.freeze([
+  { name: 'tower/init', description: '`tower_init` created or re-anchored state' },
+  { name: 'tower/plan', description: '`tower_plan` created missions' },
+  { name: 'tower/mission', description: '`tower_mission` changed one mission' },
+  { name: 'tower/spawn', description: '`tower_spawn` recorded a worker/reviewer' },
+  { name: 'tower/complete', description: '`tower_complete` recorded a completion report' },
+  { name: 'tower/review', description: '`tower_review` recorded a verdict' },
+  { name: 'tower/merge', description: '`tower_merge` returned (including gate failures; inspect `value.ok`)' },
+  { name: 'tower/rebase', description: '`tower_rebase` returned' },
+  { name: 'tower/teardown', description: '`tower_teardown` removed worktrees' },
+  { name: 'tower/finding', description: '`tower_finding` created one finding' },
+  { name: 'tower/findings', description: '`tower_findings` read/listed/updated findings' },
+  { name: 'tower/send', description: '`tower_send` persisted a message' },
+  { name: 'tower/inbox', description: '`tower_inbox` acknowledged messages' },
+  { name: 'tower/interrupt', description: '`tower_interrupt` stopped a live agent' },
+  { name: 'tower/diff', description: '`tower_diff` read a mission diff' },
+  { name: 'tower/adopt', description: '`tower_adopt` reconciled the roster' },
+  { name: 'tower/roster', description: '`tower_roster` read the roster' },
+  { name: 'tower/status', description: '`tower_status` read the dashboard' },
+  { name: 'tower/preflight', description: '`tower_preflight` evaluated the gate' },
+  { name: 'tower/doctor', description: '`tower_doctor` completed its read-only checks' },
+  { name: 'tower/recover', description: '`tower_recover` inspected or cleared a stale state lock' },
+  { name: 'tower/test', description: '`tower_test` ran discovery' },
+  { name: 'tower/batch', description: '`tower_batch` created, inspected or closed a batch' },
+  { name: 'tower/resource', description: '`tower_resource` acquired/released/inspected leases' },
+  { name: 'tower/import_legacy', description: '`tower_import_legacy` stored a legacy snapshot' },
+  { name: 'tower/legacy_map', description: '`tower_legacy_map` mapped or listed legacy ids' },
+  { name: 'tower/mode', description: '`tower_mode` read the session stance (`value.mode`, `allowAgentControl`, `deniedWhileActive`)' },
+  { name: 'tower/control', description: '`tower_control` entered/left the mode (`value.mode`, actor/reason in `value`)' },
+  { name: 'tower/reload', description: '`tower_reload` returned a reload schedule/result' },
+])
+
+/** @type {readonly string[]} */
+export const LEGACY_TOOL_EVENT_NAMES = Object.freeze(LEGACY_TOOL_EVENT_TABLE.map((entry) => entry.name))
+
+/** Total number of process-local events described by the generated reference. */
+export const EVENT_COUNT = MISSION_EVENT_TABLE.length + LEGACY_TOOL_EVENT_TABLE.length
+
+/**
+ * The runtime name of a domain event type. Throws on an unknown type so a typo
+ * fails in tests instead of emitting an unobservable event.
+ * @param {string} type
+ * @returns {string}
+ */
+export function missionEventName(type) {
+  const entry = /** @type {Record<string, MissionEventEntry>} */ (MISSION_EVENTS)[type]
+  if (!entry) throw new TypeError(`unknown mission event type "${type}"`)
+  return entry.name
+}
+
+/**
+ * A domain transition's event *descriptor*: what changed, before the caller
+ * knows the persisted revision and timestamp. App code finalises it with
+ * `buildMissionEvent` after the state write.
+ * @param {MissionEventType} type
+ * @param {string} missionId
+ * @param {{ commit?: string }} [extra]
+ * @returns {{ type: MissionEventType, missionId: string, commit?: string }}
+ */
+export function missionEventDescriptor(type, missionId, extra = {}) {
+  if (!MISSION_EVENT_TYPES.includes(type)) throw new TypeError(`unknown mission event type "${type}"`)
+  if (typeof missionId !== 'string' || missionId.length === 0) {
+    throw new TypeError('mission events require a non-empty missionId')
+  }
+  const descriptor = /** @type {{ type: MissionEventType, missionId: string, commit?: string }} */ ({
+    type,
+    missionId,
+  })
+  if (type === 'merged') {
+    if (typeof extra.commit !== 'string' || extra.commit.length === 0) {
+      throw new TypeError('tower.mission.merged requires the merge commit')
+    }
+    descriptor.commit = extra.commit
+  }
+  return descriptor
+}
+
+/**
+ * Finalise one descriptor into `{ name, payload }` for the event port.
+ * Payload shapes are fixed here so `docs/reference/events.md` (generated from
+ * the same table) cannot describe a different shape than the runtime emits.
+ * @param {{ type: MissionEventType, missionId: string, commit?: string }} descriptor
+ * @param {{ revision: number, at: number }} context
+ * @returns {{ name: string, payload: Record<string, any> }}
+ */
+export function buildMissionEvent(descriptor, { revision, at }) {
+  const entry = /** @type {Record<string, MissionEventEntry>} */ (MISSION_EVENTS)[descriptor.type]
+  if (!entry) throw new TypeError(`unknown mission event type "${descriptor.type}"`)
+  if (!Number.isInteger(revision)) throw new TypeError('mission events require the persisted integer revision')
+  if (!Number.isFinite(at)) throw new TypeError('mission events require the transition timestamp')
+  /** @type {Record<string, any>} */
+  const payload = { missionId: descriptor.missionId, revision, at }
+  if (entry.payload.includes('commit')) payload.commit = descriptor.commit
+  return { name: entry.name, payload }
+}
+
+/**
+ * Descriptors for a set of freshly persisted missions.
+ * @param {Array<{ id: string }>} missions
+ * @returns {Array<{ type: MissionEventType, missionId: string }>}
+ */
+export function plannedEvents(missions) {
+  return missions.map((mission) => missionEventDescriptor('planned', mission.id))
+}
+
+/**
+ * @param {{ id: string }} mission
+ * @returns {{ type: MissionEventType, missionId: string }}
+ */
+export function completedEvent(mission) {
+  return missionEventDescriptor('completed', mission.id)
+}
+
+/**
+ * @param {{ id: string }} mission
+ * @returns {{ type: MissionEventType, missionId: string }}
+ */
+export function reviewedEvent(mission) {
+  return missionEventDescriptor('reviewed', mission.id)
+}
+
+/**
+ * @param {{ id: string }} mission
+ * @param {string} commit
+ * @returns {{ type: MissionEventType, missionId: string, commit: string }}
+ */
+export function mergedEvent(mission, commit) {
+  return /** @type {{ type: MissionEventType, missionId: string, commit: string }} */ (
+    missionEventDescriptor('merged', mission.id, { commit })
+  )
+}
+
+/**
+ * @param {{ id: string }} mission
+ * @returns {{ type: MissionEventType, missionId: string }}
+ */
+export function abandonedEvent(mission) {
+  return missionEventDescriptor('abandoned', mission.id)
+}

package/domain/integration/gate.js

@@ -123,11 +123,26 @@ export function baseDirtyBlocker(wouldOverwrite) {
     : null
 }
 
+/**
+ * Whether a dependency already satisfies the gate. A build mission must be
+ * merged (or abandoned), but a survey is terminal-success at `completed`: it is
+ * read-only and has no branch to merge, so requiring `merged` would keep the
+ * dependent mission blocked forever (#107). Archived entries carry `kind` for
+ * the same decision.
+ * @param {{ kind?: string, status?: string } | null | undefined} dep
+ * @returns {boolean}
+ */
+export function dependencySatisfied(dep) {
+  if (!dep) return false
+  if (dep.status === 'merged' || dep.status === 'abandoned') return true
+  return dep.kind === 'survey' && dep.status === 'completed'
+}
+
 /**
  * @param {object} input
  * @param {string[]} input.deps
  * @param {TowerState} input.state
- * @param {Map<string, { status: string }>} [input.archived] compact archived missions (#73)
+ * @param {Map<string, { status: string, kind?: string }>} [input.archived] compact archived missions (#73)
  * @returns {Blocker[]}
  */
 export function dependencyBlockers({ deps = [], state, archived = new Map() }) {
@@ -135,7 +150,7 @@ export function dependencyBlockers({ deps = [], state, archived = new Map() }) {
   const blockers = []
   for (const depId of deps) {
     const dep = state.missions.find((entry) => entry.id === depId) ?? archived.get(depId)
-    if (!dep || !['merged', 'abandoned'].includes(dep.status)) {
+    if (!dependencySatisfied(dep)) {
       blockers.push({ code: 'deps-unmerged', detail: `${depId} is ${dep ? dep.status : 'missing'}` })
     }
   }

package/domain/integration/merge.js

@@ -3,6 +3,7 @@
 // writes, the state lock, and persistence stay in app/merge.js.
 // @ts-check
 import { isReviewExempt, latestReview, reviewsForBranch } from './review.js'
+import { mergedEvent } from '../events.js'
 
 /** @typedef {import('../../types/index.js').Mission} Mission */
 /** @typedef {import('../../types/index.js').Review} Review */
@@ -182,6 +183,40 @@ export function mergeSuccessNote(branchTip, base, newTip) {
   return `merged ${branchTip.slice(0, 7)} into ${base} as ${newTip.slice(0, 7)}`
 }
 
+/**
+ * Apply a successful two-phase merge to the mission draft and describe the
+ * domain fact, including the commit that landed. Persistence stays in
+ * app/merge.js at the commit phase.
+ * @param {{ mission: Mission, branchTip: string, base: string, newTip: string, now: number }} params
+ * @returns {{ state: Mission, events: Array<{ type: string, missionId: string, commit: string }> }}
+ */
+export function applyMergeSuccess({ mission, branchTip, base, newTip, now }) {
+  mission.status = 'merged'
+  mission.mergedAt = now
+  mission.mergedCommit = newTip
+  mission.updatedAt = now
+  mission.notes = mission.notes ?? []
+  mission.notes.push(mergeSuccessNote(branchTip, base, newTip))
+  return { state: mission, events: [mergedEvent(mission, newTip)] }
+}
+
+/**
+ * Apply an already-landed merge reconciliation to the mission draft. `note` is
+ * the evidence line the caller built from the observed commit and parents.
+ * @param {{ mission: Mission, mergedCommit: string, note: string, now: number }} params
+ * @returns {{ state: Mission, events: Array<{ type: string, missionId: string, commit: string }> }}
+ */
+export function applyLandedMerge({ mission, mergedCommit, note, now }) {
+  mission.status = 'merged'
+  mission.mergedAt = now
+  mission.mergedCommit = mergedCommit
+  mission.blockers = []
+  mission.notes = mission.notes ?? []
+  mission.notes.push(note)
+  mission.updatedAt = now
+  return { state: mission, events: [mergedEvent(mission, mergedCommit)] }
+}
+
 /**
  * @param {string} detail
  * @returns {string}

package/domain/lockBudget.js

@@ -0,0 +1,30 @@
+// Git-mutex budget policy (#93), shared by the app layer and the store
+// infrastructure (#69).
+//
+// The waiter behind the repo-scoped git mutex must outlast a merge that is
+// entitled to `mergeTimeoutMs`: a merge legally holds the mutex for its whole
+// plan.timeoutMs and then runs a few cheap evidence/cleanup git calls before
+// releasing it (#93). The budget is pure policy over the resolved Tower config,
+// so it lives in the domain rather than in an adapter; app/tower.js and
+// adapters/store.js both compute it from here.
+export const GIT_LOCK_MARGIN_MS = 60000
+
+/** The default merge timeout when a caller passes a config without `merge`. */
+export const DEFAULT_MERGE_TIMEOUT_MS = 900000
+
+/**
+ * @param {{ merge?: { timeoutMs?: number } } | null | undefined} config
+ * @param {number} [mergeTimeoutMs] the caller's resolved merge timeout
+ * @returns {number}
+ */
+export function gitLockTimeoutMs(config, mergeTimeoutMs) {
+  const explicit = Number(mergeTimeoutMs)
+  const configured = Number(config?.merge?.timeoutMs)
+  const base =
+    Number.isInteger(explicit) && explicit > 0
+      ? explicit
+      : Number.isInteger(configured) && configured > 0
+        ? configured
+        : DEFAULT_MERGE_TIMEOUT_MS
+  return base + GIT_LOCK_MARGIN_MS
+}

package/domain/mission.js

@@ -12,7 +12,18 @@ export const MISSION_STATUSES = ['planned', 'active', 'completed', 'blocked', 'p
 export const SCHEMA_VERSION = 3
 /** @type {readonly MergeVerdict[]} */
 export const MERGE_VERDICTS = ['merge', 'fix-then-merge', 'hold']
-export const REVIEW_STATUS_RE = /^(clean|p1-\d+items|p2-\d+items)$/
+// #115: the review status vocabulary is one runtime source. The validator
+// accepts any positive item count (`p1-7items`), while the published
+// `ReviewStatus` type is generated from REVIEW_STATUS_ITEMS, which fixes the
+// documented 1..5 range so a consumer sees a closed union.
+export const REVIEW_STATUS_PRIORITIES = ['p1', 'p2']
+export const REVIEW_STATUS_ITEMS = [1, 2, 3, 4, 5]
+/** @type {readonly string[]} */
+export const REVIEW_STATUSES = [
+  'clean',
+  ...REVIEW_STATUS_PRIORITIES.flatMap((priority) => REVIEW_STATUS_ITEMS.map((count) => `${priority}-${count}items`)),
+]
+export const REVIEW_STATUS_RE = new RegExp(`^(?:clean|(?:${REVIEW_STATUS_PRIORITIES.join('|')})-\\d+items)$`)
 /** @type {ReadonlySet<string>} */
 export const TERMINAL_STATUSES = new Set(['merged', 'abandoned'])
 /** @type {readonly FindingType[]} */

package/domain/missions/completion.js

@@ -4,6 +4,7 @@
 // Git, and persists the transition; the rules below are repository-free.
 // @ts-check
 import { TowerToolError } from '../errors.js'
+import { completedEvent } from '../events.js'
 
 /** @typedef {import('../../types/index.js').Mission} Mission */
 /** @typedef {import('../../types/index.js').RosterEntry} RosterEntry */
@@ -165,3 +166,16 @@ export function completionReport({ report, worker, checks, now, maxReportBytes }
   const text = report.trim()
   return { report: text, reportBytes: assertReportSize(text, maxReportBytes), by: worker.name, at: now, checks }
 }
+
+/**
+ * Apply the completion transition to the mission draft and describe the domain
+ * fact. Persistence stays in app/checkCompletion.js.
+ * @param {{ mission: Mission, report: any, now: number }} params
+ * @returns {{ state: Mission, events: Array<{ type: string, missionId: string }> }}
+ */
+export function applyCompletion({ mission, report, now }) {
+  mission.status = 'completed'
+  mission.completionReport = report
+  mission.updatedAt = now
+  return { state: mission, events: [completedEvent(mission)] }
+}

package/domain/missions/lifecycle.js

@@ -5,6 +5,7 @@
 // in-memory mission draft it is given.
 // @ts-check
 import { TowerToolError } from '../errors.js'
+import { abandonedEvent, completedEvent } from '../events.js'
 import { MISSION_STATUSES, TERMINAL_STATUSES, canTransition, pauseCauseError } from '../mission.js'
 import { normalizeScope, scopesOverlap } from '../scope.js'
 
@@ -62,9 +63,10 @@ export function assertMissionActor(mission, actor, input) {
 
 /**
  * Apply one validated `tower_mission` patch to the mission draft and return
- * the human-readable change list used by the activity log.
+ * the human-readable change list used by the activity log plus the domain
+ * events the transition describes.
  * @param {{ mission: Mission, state: TowerState, input: any, config: any }} params
- * @returns {{ changes: string[] }}
+ * @returns {{ state: Mission, changes: string[], events: Array<{ type: string, missionId: string }> }}
  */
 export function applyMissionUpdate({ mission, state, input, config }) {
   const actor = input.actor ?? { name: 'tower', role: 'tower' }
@@ -77,6 +79,8 @@ export function applyMissionUpdate({ mission, state, input, config }) {
   }
   /** @type {string[]} */
   const changes = []
+  /** @type {Array<{ type: string, missionId: string }>} */
+  const events = []
 
   if (input.status !== undefined) {
     if (typeof input.status !== 'string' || !MISSION_STATUSES.includes(input.status)) {
@@ -104,6 +108,8 @@ export function applyMissionUpdate({ mission, state, input, config }) {
     }
     mission.status = input.status
     changes.push(`status=${input.status}`)
+    if (input.status === 'completed') events.push(completedEvent(mission))
+    if (input.status === 'abandoned') events.push(abandonedEvent(mission))
   }
 
   if (input.task_done !== undefined) {
@@ -182,5 +188,5 @@ export function applyMissionUpdate({ mission, state, input, config }) {
   }
 
   if (changes.length === 0) fail('tower_mission requires at least one change')
-  return { changes }
+  return { state: mission, changes, events }
 }

package/domain/missions/plan.js

@@ -4,9 +4,11 @@
 // activity entry; everything here is deterministic and repository-free.
 // @ts-check
 import { TowerToolError } from '../errors.js'
+import { plannedEvents } from '../events.js'
 import { normalizeScope, validateTitle } from '../scope.js'
 
 /** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
 
 /**
  * @param {string} message
@@ -147,3 +149,15 @@ export function newMission(id, input, now) {
     updatedAt: now,
   }))
 }
+
+/**
+ * Append the freshly projected missions to the state document and describe the
+ * resulting domain facts. Persistence and revision accounting stay in app/plan.
+ * @param {TowerState} state
+ * @param {Mission[]} created
+ * @returns {{ state: TowerState, events: Array<{ type: string, missionId: string }> }}
+ */
+export function applyPlan(state, created) {
+  state.missions.push(...created)
+  return { state, events: plannedEvents(created) }
+}

package/domain/missions/review.js

@@ -5,6 +5,7 @@
 // persistence. Everything here is deterministic and repository-free.
 // @ts-check
 import { TowerToolError } from '../errors.js'
+import { reviewedEvent } from '../events.js'
 import { MERGE_VERDICTS, REVIEW_STATUS_RE } from '../mission.js'
 
 /** @typedef {import('../../types/index.js').Mission} Mission */
@@ -109,11 +110,67 @@ export function assertReviewerSpawnTip(caller, tip) {
 }
 
 /**
- * Compute the review round and enforce the per-reviewer cap.
- * @param {{ reviews: Review[] | undefined, branch: string, reviewerName: string, maxRoundsPerReviewer: unknown }} params
+ * The latest review of one branch. Higher rounds win; routes that share a round
+ * are ordered by submission sequence, so "latest" is the most recently recorded
+ * verdict (#108).
+ * @param {Review[]} reviews
+ * @returns {Review | null}
+ */
+function latestBranchReview(reviews) {
+  /** @type {Review | null} */
+  let latest = null
+  for (const review of reviews) {
+    if (!latest) {
+      latest = review
+      continue
+    }
+    const round = Number(review.round) || 0
+    const latestRound = Number(latest.round) || 0
+    if (round > latestRound) latest = review
+    else if (round === latestRound && (Number(review.seq) || 0) > (Number(latest.seq) || 0)) latest = review
+  }
+  return latest
+}
+
+/**
+ * Decide whether this submission starts a new review round or appends to the
+ * current one (#108). A completed mission always starts a new round. A mission
+ * that is `active` accepts a later route for the tip that its current round
+ * reviewed: the first non-clean verdict already returned it to `active`, and the
+ * remaining routes spawned against the same tip must still record their
+ * verdicts. A verdict for a tip that moved is rejected with an explanation.
+ * @param {{ mission: Mission, reviews: Review[] | undefined, branch: string, tip: string }} params
+ * @returns {{ appended: boolean, round: number | null }}
+ */
+export function reviewAdmission({ mission, reviews, branch, tip }) {
+  if (mission.status === 'completed') return { appended: false, round: null }
+  if (mission.status !== 'active') {
+    fail(`mission ${mission.id} is ${mission.status}; only a completed mission can be reviewed`)
+  }
+  const latest = latestBranchReview((reviews ?? []).filter((review) => review.branch === branch))
+  if (!latest) {
+    fail(`mission ${mission.id} is active and has no review round to append to; only a completed mission can be reviewed`)
+  }
+  if (latest.reviewedCommit !== tip) {
+    const cause =
+      latest.status === 'clean'
+        ? 'the reviewed tip moved'
+        : `review round ${latest.round} (${latest.status}) returned it to active and the reviewed tip moved`
+    fail(
+      `mission ${mission.id} is active: ${cause} (${String(latest.reviewedCommit).slice(0, 7)} -> ${tip.slice(0, 7)}); only review routes for the same reviewed tip can append to round ${latest.round} — return the mission to completed before starting a new round`,
+    )
+  }
+  return { appended: true, round: latest.round }
+}
+
+/**
+ * Compute the review round and enforce the per-reviewer cap. `round` joins the
+ * round `reviewAdmission` selected for an appended route; omitted, the
+ * submission opens the next round.
+ * @param {{ reviews: Review[] | undefined, branch: string, reviewerName: string, maxRoundsPerReviewer: unknown, round?: number | null }} params
  * @returns {{ reviewerRounds: number, round: number }}
  */
-export function reviewRound({ reviews, branch, reviewerName, maxRoundsPerReviewer }) {
+export function reviewRound({ reviews, branch, reviewerName, maxRoundsPerReviewer, round: sharedRound }) {
   const prior = (reviews ?? []).filter((review) => review.branch === branch)
   const reviewerRounds = prior.filter((review) => review.reviewer === reviewerName).length
   const maxReviewRounds = Number(maxRoundsPerReviewer) || MAX_REVIEW_ROUNDS
@@ -122,17 +179,28 @@ export function reviewRound({ reviews, branch, reviewerName, maxRoundsPerReviewe
       `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
+  const round = Number.isInteger(sharedRound)
+    ? /** @type {number} */ (sharedRound)
+    : prior.length === 0
+      ? 1
+      : Math.max(...prior.map((review) => review.round)) + 1
   return { reviewerRounds, round }
 }
 
 /**
  * A non-clean verdict returns the mission to active and records the note; a
- * clean verdict leaves the status untouched.
- * @param {{ status: string, merge: string, round: number, reviewerName: string }} params
+ * clean verdict leaves the status untouched. An appended route records the
+ * verdict without flipping the status again (#108).
+ * @param {{ status: string, merge: string, round: number, reviewerName: string, appended?: boolean }} params
  * @returns {{ returnToActive: boolean, note: string }}
  */
-export function reviewOutcome({ status, merge, round, reviewerName }) {
+export function reviewOutcome({ status, merge, round, reviewerName, appended = false }) {
+  if (appended) {
+    return {
+      returnToActive: false,
+      note: `review round ${round} by ${reviewerName}: ${status} (${merge}) — appended to the same round; the mission stays active until it is re-completed`,
+    }
+  }
   if (status !== 'clean') {
     return {
       returnToActive: true,
@@ -142,6 +210,21 @@ export function reviewOutcome({ status, merge, round, reviewerName }) {
   return { returnToActive: false, note: `review round ${round} by ${reviewerName}: clean (${merge})` }
 }
 
+/**
+ * Apply a recorded review's mission-level effect to the draft and describe the
+ * domain fact. Persistence, the review record and the round accounting stay in
+ * app/review.js.
+ * @param {{ mission: Mission, outcome: { returnToActive: boolean, note: string }, now: number }} params
+ * @returns {{ state: Mission, events: Array<{ type: string, missionId: string }> }}
+ */
+export function applyReviewOutcome({ mission, outcome, now }) {
+  if (outcome.returnToActive) mission.status = 'active'
+  mission.notes = mission.notes ?? []
+  mission.notes.push(outcome.note)
+  mission.updatedAt = now
+  return { state: mission, events: [reviewedEvent(mission)] }
+}
+
 /**
  * Project the persisted review record.
  * @param {{ seq: number, missionId: string, branch: string, tip: string, verdict: { status: string, merge: string, findings: string, checks: string[], decision: string }, reviewerName: string, reviewerRole: string, round: number, now: number, breakGlassReason?: string }} params

package/domain/read/views.js

@@ -40,6 +40,7 @@ export function missionDetailView({ state, mission, activity }) {
  * @param {object[]} input.missions enriched mission views
  * @param {number | null} [input.archivedMissions] archived mission count, or null when unreadable
  * @param {object} [input.archive] archive index view/diagnostic
+ * @param {{ held: boolean, pid?: number | null, phase?: string | null, heldMs?: number | null }} [input.gitLock]
  * @returns {object}
  */
 export function statusView({
@@ -51,6 +52,7 @@ export function statusView({
   missions,
   archivedMissions = 0,
   archive = null,
+  gitLock = { held: false },
 }) {
   /** @type {Record<string, number>} */
   const counts = {}
@@ -100,6 +102,7 @@ export function statusView({
     })),
     missions,
     archivedMissions,
+    gitLock,
     ...(archive ? { archive } : {}),
     activity,
   }

package/domain/state/archive.js

@@ -9,7 +9,7 @@
 // This module is pure: it declares the archive document contract, selects what
 // is eligible under the configured policy, and builds the records. Reading and
 // writing the files, and the lock that makes them atomic with state.json, live
-// in `lib/archive.js` and `app/archive.js`.
+// in `adapters/archive.js` and `app/archive.js`.
 // @ts-check
 import { isTerminal } from '../mission.js'
 

package/domain/state.js

@@ -8,7 +8,7 @@
 // `validateState` proves a document matches the *current* schema.
 // `prepareState` is the load-path decision: it inspects the version, applies the
 // ordered migration registry, then validates the target schema. Both are pure;
-// the side effects (backup, write, activity) live in `lib/stateFile.js`.
+// the side effects (backup, write, activity) live in `adapters/stateFile.js`.
 // @ts-check
 import { TowerToolError } from './errors.js'
 import { SCHEMA_VERSION } from './mission.js'