dsh-tower 2.1.0 → 2.3.0

package/domain/contracts/outputs.js

@@ -79,6 +79,7 @@ const SCHEMAS = {
       recentFindings: S.arr(S.obj()),
       missions: S.arr(S.obj()),
       activity: S.arr(S.obj()),
+      gitLock: S.obj({ held: S.bool, pid: S.any, phase: S.any, heldMs: S.any }),
       mode: S.any,
       spawn: S.any,
       towerAgentId: S.any,
@@ -169,7 +170,7 @@ const SCHEMAS = {
     ['counts', 'total'],
   ),
   review: S.obj(
-    { review: S.obj(), branchTip: S.str, missionStatus: S.str, round: S.int, reviewerRounds: S.int },
+    { review: S.obj(), branchTip: S.str, missionStatus: S.str, round: S.int, appended: S.bool, reviewerRounds: S.int },
     ['review', 'branchTip', 'missionStatus', 'round', 'reviewerRounds'],
   ),
   preflight: S.obj(
@@ -243,6 +244,8 @@ const SCHEMAS = {
     {
       ok: S.bool,
       checks: S.arr(S.obj()),
+      stateLock: S.any,
+      gitLock: S.any,
       stateSchema: S.obj({
         currentVersion: S.any,
         supportedVersion: S.int,
@@ -250,6 +253,7 @@ const SCHEMAS = {
         status: S.str,
       }),
       reports: S.any,
+      surface: S.any,
       archive: S.obj({
         missions: S.any,
         archivedMissions: S.int,
@@ -266,7 +270,7 @@ const SCHEMAS = {
     ['ok', 'checks'],
   ),
   recover: S.obj(
-    { ok: S.bool, action: S.str, stateLock: S.any, cleared: S.bool, backup: S.any, error: S.str },
+    { ok: S.bool, action: S.str, stateLock: S.any, cleared: S.bool, backup: S.any, forced: S.bool, error: S.str },
     ['ok', 'action'],
   ),
   test: S.obj(

package/domain/contracts/tool-inputs/ops.js

@@ -25,6 +25,7 @@ export const RecoverInput = Type.Object({
   repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
   action: enumOf(RECOVERY_ACTIONS, { description: 'Recovery action.' }),
   confirm: Type.Optional(Type.String({ description: 'Required literal CLEAR_STALE_LOCK for clear-stale-lock.' })),
+  force: Type.Optional(Type.Boolean({ description: 'clear-stale-lock: clear the lock even when its recorded PID is alive (a recycled PID); requires confirm and still moves the record to a .recovered-<ts> backup.' })),
 }, { additionalProperties: false })
 
 export const TestInput = Type.Object({

package/domain/errors.js

@@ -3,8 +3,24 @@
 // Everything a Tower tool throws reaches the model as
 //   [tower:<code>] <original message>
 // so callers (and tests) can branch on the code instead of matching prose.
+// The catalog also carries the recovery metadata the model can act on:
+//
+//   - `retryable`   — the same input may succeed later without a change;
+//   - `nextAction`  — the concrete recovery step, rendered once as a trailing
+//                     ` — next: …` segment (plus ` (retryable)` when retryable);
+//   - `trigger`     — the typical condition, documented in errors.md.
+//
+// Why the message suffix rather than a structured error payload: the DSH tool
+// contract declares output schemas for successful values only, and a thrown
+// error reaches the model as its rendered message. There is no separate
+// structured error channel to return `{ code, retryable, nextAction }` through,
+// so the suffix is the model-visible channel; the error object still carries
+// `code`, `retryable`, `nextAction` and `details` for programmatic callers.
+// Codes without a recovery step render byte-identically to the pre-#74 form.
+//
 // The catalog is documented in docs/reference/errors.md; scripts/check-docs.mjs
-// keeps the two in sync.
+// and scripts/generate-error-reference.mjs keep the two in sync.
+// @ts-check
 
 /** Neutral error type shared by the git adapter and the domain classifier. */
 export class GitError extends Error {
@@ -18,58 +34,295 @@ export class GitError extends Error {
   }
 }
 
+/**
+ * @typedef {object} ErrorCodeEntry
+ * @property {string} description
+ * @property {string} trigger
+ * @property {boolean} retryable
+ * @property {string | null} nextAction
+ */
+
+/**
+ * One stable entry per failure family. `description` and `trigger` are the
+ * documented meaning; `retryable`/`nextAction` are the recovery contract the
+ * tool boundary renders.
+ * @type {Record<string, ErrorCodeEntry>}
+ */
 export const ERROR_CODES = {
-  'invalid-argument': 'A tool argument is missing, malformed, or not allowed.',
-  'repo-invalid': 'repoRoot is missing, relative, or not inside a Git repository.',
-  'not-initialized': 'Tower is not initialized for this repository; run tower_init.',
-  'mission-not-found': 'No mission with that id exists.',
-  'finding-not-found': 'No finding with that id exists.',
-  'invalid-transition': 'The requested state transition is not allowed.',
-  'stale-base': 'The repository state changed while the operation was being prepared; retry.',
-  'state-locked': 'Another Tower writer holds the state lock.',
-  'state-corrupt': 'The Tower state file is unreadable or invalid.',
-  'state-version-unsupported': 'The Tower state file uses a schema version this build cannot read or downgrade.',
-  'state-migration-failed': 'A Tower state migration failed; the original state file was not modified.',
-  'config-invalid': 'Tower configuration is invalid.',
-  'config-unknown-key': 'Tower configuration has an unknown top-level key.',
-  'git-failed': 'A git command failed.',
-  'git-timeout': 'A git command timed out or exceeded its output buffer.',
-  'worktree-dirty': 'The mission worktree has uncommitted changes and cannot complete.',
-  'spawn-unavailable': 'The subagents service is unavailable.',
-  'provider-missing': 'No subagent provider is registered.',
-  'provider-cooldown': 'The provider is throttled; spawn is in a short cooldown.',
-  'preset-missing': 'The configured agent preset is not registered.',
-  'reviewer-prerequisite': 'The reviewer spawn prerequisite is not met.',
-  'not-authorized': 'The calling agent role may not perform this action.',
-  'workspace-busy': 'Another Tower session owns this repository workspace lock.',
-  'worker-limit': 'The repository reached spawn.maxLiveWorkers live workers.',
-  'rate-limited': 'The tower_send per-minute rate limit was reached.',
-  'takeover-refused': 'The mission already has a live worker that was not stopped first.',
-  'reload-unavailable': 'The DSH HMR service is not available in this profile.',
-  'reload-failed': 'The HMR reload failed; check the DSH log and restart if needed.',
-  'tests-failed': 'Declared test discovery failed or did not meet its admission requirements.',
-  'tests-timeout': 'Test discovery exceeded its time or output budget.',
-  'lease-busy': 'Another holder owns the requested advisory lease.',
-  'lease-token': 'The lease release token does not match the current holder.',
-  'batch-invalid': 'The batch request or its close evidence is invalid.',
-  'legacy-invalid': 'The legacy snapshot or mapping is invalid.',
-  'tool-internal': 'An unexpected failure; read the message and the activity log.',
+  'invalid-argument': {
+    description: 'A tool argument is missing, malformed, or not allowed.',
+    trigger: '`missionId`/`id` omitted; unknown status; empty report; bad scope glob; `timeoutMs < 1000`; `status: "all"` on an update.',
+    retryable: false,
+    nextAction: null,
+  },
+  'repo-invalid': {
+    description: 'repoRoot is missing, relative, or not inside a Git repository.',
+    trigger: 'passing a path in a directory that is not a repo',
+    retryable: false,
+    nextAction: 'pass an absolute path to a directory inside a Git repository',
+  },
+  'not-initialized': {
+    description: 'Tower is not initialized for this repository; run tower_init.',
+    trigger: 'a read tool before `tower_init`',
+    retryable: false,
+    nextAction: 'run tower_init for this repository',
+  },
+  'mission-not-found': {
+    description: 'No mission with that id exists.',
+    trigger: 'a stale or mistyped `M9`',
+    retryable: false,
+    nextAction: 'list missions with tower_status',
+  },
+  'finding-not-found': {
+    description: 'No finding with that id exists.',
+    trigger: '`tower_findings({id:"F99"})`',
+    retryable: false,
+    nextAction: 'list findings with tower_findings',
+  },
+  'invalid-transition': {
+    description: 'The requested state transition is not allowed.',
+    trigger: 'a blocked→merged attempt; a finding transition not in the graph; a reviewer mutating findings; completing a mission with open tasks, blockers, no commits, or unread inbox messages.',
+    retryable: false,
+    nextAction: null,
+  },
+  'stale-base': {
+    description: 'The repository state changed while the operation was being prepared; retry.',
+    trigger: 'two-phase mutation revalidation',
+    retryable: true,
+    nextAction: 'retry the tool; if it keeps failing, run tower_preflight and inspect tower_status',
+  },
+  'state-locked': {
+    description: 'Another Tower writer holds the state lock.',
+    trigger: 'concurrent mutation after the lock timeout',
+    retryable: true,
+    nextAction: 'wait for the other Tower writer to finish, then retry',
+  },
+  'state-corrupt': {
+    description: 'The Tower state file is unreadable or invalid.',
+    trigger: 'hand-edited `state.json`; invalid JSON; no usable `schemaVersion`',
+    retryable: false,
+    nextAction: 'restore state.json from a backup, or re-initialize after filing the corruption',
+  },
+  'state-version-unsupported': {
+    description: 'The Tower state file uses a schema version this build cannot read or downgrade.',
+    trigger: 'opening a repository written by a newer plugin; an unknown older version; this build refuses to downgrade',
+    retryable: false,
+    nextAction: 'upgrade dsh-tower to a release that supports this state schemaVersion',
+  },
+  'state-migration-failed': {
+    description: 'A Tower state migration failed; the original state file was not modified.',
+    trigger: 'a bug in a migration step; see the pre-migration `state.json.v<N>.bak`',
+    retryable: false,
+    nextAction: 'restore the pre-migration backup state.json.v<N>.bak and report the migration bug',
+  },
+  'config-invalid': {
+    description: 'Tower configuration is invalid.',
+    trigger: 'malformed repo `config.json`, a value that violates the schema',
+    retryable: false,
+    nextAction: 'fix the repository config file, then retry',
+  },
+  'config-unknown-key': {
+    description: 'Tower configuration has an unknown top-level key.',
+    trigger: 'a typo such as `allowAgentToggle`',
+    retryable: false,
+    nextAction: 'remove the unknown key from the repository config file, then retry',
+  },
+  'git-failed': {
+    description: 'A git command failed.',
+    trigger: 'a rejected merge command, invalid ref',
+    retryable: false,
+    nextAction: null,
+  },
+  'git-timeout': {
+    description: 'A git command timed out or exceeded its output buffer.',
+    trigger: 'slow pre-merge hook, huge diff',
+    retryable: true,
+    nextAction: 'retry; if it persists, raise git.timeoutMs or merge.timeoutMs',
+  },
+  'worktree-dirty': {
+    description: 'The mission worktree has uncommitted changes and cannot complete.',
+    trigger: 'staged, modified, or untracked files left behind before `tower_complete`',
+    retryable: false,
+    nextAction: 'commit or remove the worktree changes, then retry tower_complete',
+  },
+  'spawn-unavailable': {
+    description: 'The subagents service is unavailable.',
+    trigger: 'a Host without `subagents`',
+    retryable: false,
+    nextAction: 'enable the DSH subagents service, then retry',
+  },
+  'provider-missing': {
+    description: 'No subagent provider is registered.',
+    trigger: 'an empty provider list',
+    retryable: false,
+    nextAction: 'register a subagent provider in the DSH profile, then retry',
+  },
+  'provider-cooldown': {
+    description: 'The provider is throttled; spawn is in a short cooldown.',
+    trigger: 'repeated retryable provider failures; wait for `blockedUntil`',
+    retryable: true,
+    nextAction: 'wait for the cooldown to expire, then retry',
+  },
+  'preset-missing': {
+    description: 'The configured agent preset is not registered.',
+    trigger: 'missing `tower-worker`/`tower-reviewer` preset rows, DSH not restarted',
+    retryable: false,
+    nextAction: 'install the tower-worker and tower-reviewer agent presets and restart DSH',
+  },
+  'reviewer-prerequisite': {
+    description: 'The reviewer spawn prerequisite is not met.',
+    trigger: 'reviewer spawned before the mission is `completed`, or before a worktree exists',
+    retryable: false,
+    nextAction: 'complete the mission first, then spawn the reviewer',
+  },
+  'not-authorized': {
+    description: 'The calling agent role may not perform this action.',
+    trigger: 'a worker calling a tower-only tool or changing mission status/scope; a reviewer mutating findings',
+    retryable: false,
+    nextAction: 'call the tool as the tower, or as the worker/reviewer it is assigned to',
+  },
+  'workspace-busy': {
+    description: 'Another Tower session owns this repository workspace lock.',
+    trigger: '`mode.workspaceLock:true` and a second session calls a repo-scoped tool',
+    retryable: true,
+    nextAction: 'run /tower off in the other session or wait for its lock to become stale',
+  },
+  'worker-limit': {
+    description: 'The repository reached spawn.maxLiveWorkers live workers.',
+    trigger: 'spawning a fifth worker with the default limit',
+    retryable: false,
+    nextAction: 'wait for a live worker to finish or raise spawn.maxLiveWorkers',
+  },
+  'rate-limited': {
+    description: 'The tower_send per-minute rate limit was reached.',
+    trigger: '`send.maxPerMinute` exceeded',
+    retryable: true,
+    nextAction: 'wait for the next per-minute window or raise send.maxPerMinute',
+  },
+  'takeover-refused': {
+    description: 'The mission already has a live worker that was not stopped first.',
+    trigger: '`tower_spawn({takeover:true})` before `tower_interrupt`',
+    retryable: false,
+    nextAction: 'run tower_interrupt for the live worker, then retry the takeover',
+  },
+  'reload-unavailable': {
+    description: 'The DSH HMR service is not available in this profile.',
+    trigger: '`tower_reload` / `/tower reload` on a profile without HMR',
+    retryable: false,
+    nextAction: 'restart DSH instead of reloading',
+  },
+  'reload-failed': {
+    description: 'The HMR reload failed; check the DSH log and restart if needed.',
+    trigger: '`reconcileProfile` threw',
+    retryable: false,
+    nextAction: 'check the DSH log and restart DSH',
+  },
+  'tests-failed': {
+    description: 'Declared test discovery failed or did not meet its admission requirements.',
+    trigger: 'nonzero command, malformed output, minCount/required shortfall',
+    retryable: false,
+    nextAction: 'fix the failing tests, then retry tower_complete',
+  },
+  'tests-timeout': {
+    description: 'Test discovery exceeded its time or output budget.',
+    trigger: '`tests.timeoutMs`, or stdout over `tests.maxBytes`',
+    retryable: false,
+    nextAction: 'raise tests.timeoutMs or tests.maxBytes (or speed up the suite), then retry',
+  },
+  'lease-busy': {
+    description: 'Another holder owns the requested advisory lease.',
+    trigger: '`tower_resource acquire` while `heavy-ci` is held',
+    retryable: false,
+    nextAction: 'release the lease or wait for it to expire, then retry',
+  },
+  'lease-token': {
+    description: 'The lease release token does not match the current holder.',
+    trigger: 'releasing with another session\'s token',
+    retryable: false,
+    nextAction: 'use the token returned when the lease was acquired',
+  },
+  'batch-invalid': {
+    description: 'The batch request or its close evidence is invalid.',
+    trigger: 'unknown member, duplicate id, unsafe receipt path, missing receipt hash',
+    retryable: false,
+    nextAction: 'fix the batch request or the receipt hashes, then retry',
+  },
+  'legacy-invalid': {
+    description: 'The legacy snapshot or mapping is invalid.',
+    trigger: 'unknown schema, source inside the Tower state dir, mapping rewrite',
+    retryable: false,
+    nextAction: 'check the legacy snapshot path, schema and mapping, then retry',
+  },
+  'tool-internal': {
+    description: 'An unexpected failure; read the message and the activity log.',
+    trigger: 'a bug; read the message and the activity log',
+    retryable: false,
+    nextAction: null,
+  },
 }
 
 export const ERROR_CODE_VALUES = Object.freeze(Object.keys(ERROR_CODES))
+
+/** @param {unknown} value */
 export function isErrorCode(value) {
   return typeof value === 'string' && Object.hasOwn(ERROR_CODES, value)
 }
 
-const RETRYABLE_CODES = new Set(['state-locked', 'rate-limited', 'provider-cooldown', 'git-timeout', 'workspace-busy', 'merge-intent-pending', 'stale-base'])
+/** @param {string} code */
+export function errorEntry(code) {
+  return isErrorCode(code) ? ERROR_CODES[code] : null
+}
+
+/** @param {string} code */
+export function errorDescription(code) {
+  return errorEntry(code)?.description ?? ''
+}
+
+/** @param {string} code */
+export function errorRetryable(code) {
+  return errorEntry(code)?.retryable === true
+}
+
+/** @param {string} code */
+export function errorNextAction(code) {
+  return errorEntry(code)?.nextAction ?? null
+}
+
+/**
+ * The model-visible message. Exactly one trailing ` — next: …` segment is
+ * appended when there is a recovery step; a retryable code marks the same
+ * segment with ` (retryable)`. A message that already carries the action is
+ * never suffixed twice.
+ * @param {string} code
+ * @param {string} message
+ * @param {{ nextAction?: string | null, retryable?: boolean }} [options]
+ * @returns {string}
+ */
+export function renderErrorMessage(code, message, options = {}) {
+  const text = String(message)
+  const base = `[tower:${code}] ${text}`
+  const nextAction = options.nextAction ?? errorNextAction(code)
+  if (nextAction === null || nextAction === undefined) return base
+  if (text.includes(nextAction) || text.includes('— next:')) return base
+  const retryable = options.retryable ?? errorRetryable(code)
+  return `${base} — next: ${nextAction}${retryable ? ' (retryable)' : ''}`
+}
 
 export class TowerToolError extends Error {
+  /**
+   * @param {string} code
+   * @param {string} message
+   * @param {{ cause?: unknown, retryable?: boolean, nextAction?: string | null, details?: unknown }} [options]
+   */
   constructor(code, message, options = {}) {
-    super(`[tower:${code}] ${message}`, options.cause ? { cause: options.cause } : undefined)
+    const entry = errorEntry(code)
+    const retryable = options.retryable ?? entry?.retryable === true
+    const nextAction = options.nextAction ?? entry?.nextAction ?? null
+    super(renderErrorMessage(code, message, { nextAction, retryable }), options.cause ? { cause: options.cause } : undefined)
     this.name = 'TowerToolError'
     this.code = code
-    this.retryable = options.retryable ?? RETRYABLE_CODES.has(code)
-    this.nextAction = options.nextAction ?? null
+    this.retryable = retryable
+    this.nextAction = nextAction
     this.details = options.details ?? null
   }
 }
@@ -84,8 +337,10 @@ export function classifyError(error) {
   if (error && typeof error.code === 'string' && ERROR_CODES[error.code]) {
     return new TowerToolError(error.code, originalMessage(error), {
       cause: error,
-      retryable: error.retryable === true,
-      nextAction: error.nextAction ?? null,
+      // Let the catalog supply a default when the thrown object does not
+      // explicitly override the recovery metadata.
+      retryable: typeof error.retryable === 'boolean' ? error.retryable : undefined,
+      nextAction: error.nextAction ?? undefined,
       details: error.details ?? null,
     })
   }

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)
+}