dsh-tower 2.0.3 → 2.1.0-beta.1

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

@@ -0,0 +1,58 @@
+// tower_spawn / tower_roster / tower_interrupt / tower_send / tower_inbox /
+// tower_adopt input contracts. Pure TypeBox only; no I/O.
+import { ROLES } from '../../vocabulary.js'
+import { Type, enumOf } from './shared.js'
+
+export const SpawnInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  missionId: Type.Optional(Type.String({ description: 'Mission id, e.g. M1 (canonical; alias: id).' })),
+  id: Type.Optional(Type.String({ description: 'Alias for missionId; both are accepted.' })),
+  role: Type.Optional(enumOf(ROLES, { description: 'worker executes; reviewer audits the mission branch.' })),
+  name: Type.Optional(Type.String({ description: 'Unique roster name; defaults to <role>-<missionId>.' })),
+  instructions: Type.Optional(Type.String({ description: 'Extra tower instructions appended to the briefing.' })),
+  worktreeRoot: Type.Optional(Type.String({ description: 'Optional absolute parent directory for the worktree.' })),
+  wait: Type.Optional(Type.Boolean({ description: 'Wait for the child result instead of returning immediately (testing/debug).' })),
+  waitMs: Type.Optional(Type.Number({ description: 'Max wait with wait=true, default 180000; clamped to spawn.maxWaitMs (default 90000).' })),
+  wait_ms: Type.Optional(Type.Number({ description: 'Alias for waitMs.' })),
+  takeover: Type.Optional(Type.Boolean({ description: 'Replace a live worker entry that is no longer running (increments ownerGeneration).' })),
+  includeDirtyBase: Type.Optional(Type.Boolean({ description: 'Use the recorded snapshotCommit baseline when true (default true).' })),
+}, { additionalProperties: false })
+
+export const RosterInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+}, { additionalProperties: false })
+
+export const InterruptInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  to: Type.Optional(Type.String({ description: 'Roster name to interrupt.' })),
+  agentId: Type.Optional(Type.String({ description: 'Agent/session id to interrupt (alternative to to).' })),
+  agent_id: Type.Optional(Type.String({ description: 'Alias for agentId.' })),
+  reason: Type.Optional(Type.String({ description: 'Why the agent is being interrupted (recorded in the roster).' })),
+}, { additionalProperties: false })
+
+export const SendInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  to: Type.String({ description: 'Recipient: a roster agent name, "tower", or "all".' }),
+  subject: Type.String({ description: 'One-line subject.' }),
+  body: Type.String({ description: 'Full message body (markdown).' }),
+  scope: Type.Optional(Type.String({ description: 'Optional scope tag, e.g. the mission id.' })),
+  interrupt: Type.Optional(
+    Type.Boolean({
+      description: 'Interrupt the recipient\'s current turn before delivering (Kimi-style "message interrupts the running turn"); default false = queue at the next step boundary.',
+    }),
+  ),
+  consentRef: Type.Optional(Type.String({ description: 'Optional audit reference recording who consented to this instruction.' })),
+  consent_ref: Type.Optional(Type.String({ description: 'Alias for consentRef.' })),
+}, { additionalProperties: false })
+
+export const InboxInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  limit: Type.Optional(Type.Number({ description: 'Max messages to return (default 20), newest first.' })),
+  include_read: Type.Optional(Type.Boolean({ description: 'Include previously acknowledged messages for history lookup.' })),
+  includeRead: Type.Optional(Type.Boolean({ description: 'Alias for include_read.' })),
+}, { additionalProperties: false })
+
+export const AdoptInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  retireMissing: Type.Optional(Type.Boolean({ description: 'Retire provably gone agents (default true); false marks them missing instead.' })),
+}, { additionalProperties: false })

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

@@ -0,0 +1,29 @@
+// tower_finding / tower_findings input contracts. Pure TypeBox only; no I/O.
+import { FINDING_FILTER_STATUSES, FINDING_SEVERITIES, FINDING_TYPES } from '../../vocabulary.js'
+import { Type, enumOf } from './shared.js'
+
+export const FindingInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  type: enumOf(FINDING_TYPES, { description: 'Finding category.' }),
+  title: Type.String({ description: 'Short finding title.' }),
+  severity: Type.Optional(enumOf(FINDING_SEVERITIES, { description: 'Optional severity.' })),
+  summary: Type.String({ description: 'What was found, in a sentence or two.' }),
+  location: Type.Optional(Type.String({ description: 'File/symbol the finding concerns.' })),
+  details: Type.String({ description: 'Full details: evidence, reproduction, impact.' }),
+  suggested_fix: Type.String({ description: 'What you would do about it.' }),
+  missionId: Type.Optional(Type.String({ description: 'Optional mission this finding relates to (alias: mission_id).' })),
+  mission_id: Type.Optional(Type.String({ description: 'Alias for missionId.' })),
+}, { additionalProperties: false })
+
+export const FindingsInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  id: Type.Optional(Type.String({ description: 'Finding id, e.g. F1. When present the call reads or updates that finding.' })),
+  status: Type.Optional(enumOf(FINDING_FILTER_STATUSES, { description: 'With id: target status. Without id: filter (default all).' })),
+  note: Type.Optional(Type.String({ description: 'Optional note recorded together with an update.' })),
+  type: Type.Optional(enumOf(FINDING_TYPES, { description: 'Filter by finding type.' })),
+  severity: Type.Optional(enumOf(FINDING_SEVERITIES, { description: 'Filter by severity.' })),
+  missionId: Type.Optional(Type.String({ description: 'Filter by mission id (alias: mission_id).' })),
+  mission_id: Type.Optional(Type.String({ description: 'Alias for missionId.' })),
+  open: Type.Optional(Type.Boolean({ description: 'Only findings that are not fixed or wontfix.' })),
+  limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 200, description: 'Max findings to list (default 50).' })),
+}, { additionalProperties: false })

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

@@ -0,0 +1,94 @@
+// Tool input contracts (#56 P3c): named schemas grouped by area plus a
+// `ToolInputs` map keyed by registered tool name. Pure data; no I/O.
+import {
+  CompleteInput,
+  MissionInput,
+  PlanInput,
+  PreflightInput,
+  ReviewInput,
+  StatusInput,
+} from './missions.js'
+import {
+  AdoptInput,
+  InboxInput,
+  InterruptInput,
+  RosterInput,
+  SendInput,
+  SpawnInput,
+} from './collaboration.js'
+import { DiffInput, MergeInput, RebaseInput, TeardownInput } from './integration.js'
+import { FindingInput, FindingsInput } from './findings.js'
+import {
+  BatchInput,
+  DoctorInput,
+  ImportLegacyInput,
+  InitInput,
+  LegacyMapInput,
+  RecoverInput,
+  ReloadInput,
+  ResourceInput,
+  TestInput,
+} from './ops.js'
+
+export {
+  CompleteInput,
+  MissionInput,
+  PlanInput,
+  PreflightInput,
+  ReviewInput,
+  StatusInput,
+  AdoptInput,
+  InboxInput,
+  InterruptInput,
+  RosterInput,
+  SendInput,
+  SpawnInput,
+  DiffInput,
+  MergeInput,
+  RebaseInput,
+  TeardownInput,
+  FindingInput,
+  FindingsInput,
+  BatchInput,
+  DoctorInput,
+  ImportLegacyInput,
+  InitInput,
+  LegacyMapInput,
+  RecoverInput,
+  ReloadInput,
+  ResourceInput,
+  TestInput,
+}
+
+/** @type {Record<string, import('@sinclair/typebox').TSchema>} */
+const ToolInputs = {
+  tower_init: InitInput,
+  tower_plan: PlanInput,
+  tower_mission: MissionInput,
+  tower_status: StatusInput,
+  tower_spawn: SpawnInput,
+  tower_roster: RosterInput,
+  tower_interrupt: InterruptInput,
+  tower_adopt: AdoptInput,
+  tower_send: SendInput,
+  tower_inbox: InboxInput,
+  tower_complete: CompleteInput,
+  tower_finding: FindingInput,
+  tower_findings: FindingsInput,
+  tower_diff: DiffInput,
+  tower_review: ReviewInput,
+  tower_preflight: PreflightInput,
+  tower_merge: MergeInput,
+  tower_rebase: RebaseInput,
+  tower_teardown: TeardownInput,
+  tower_doctor: DoctorInput,
+  tower_recover: RecoverInput,
+  tower_test: TestInput,
+  tower_batch: BatchInput,
+  tower_resource: ResourceInput,
+  tower_import_legacy: ImportLegacyInput,
+  tower_legacy_map: LegacyMapInput,
+  tower_reload: ReloadInput,
+}
+
+export { ToolInputs }

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

@@ -0,0 +1,37 @@
+// tower_merge / tower_rebase / tower_teardown / tower_diff input contracts.
+// Pure TypeBox only; no I/O.
+import { Type } from './shared.js'
+
+export const MergeInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  missionId: Type.Optional(Type.String({ description: 'Mission id, e.g. M1 (canonical; alias: id).' })),
+  id: Type.Optional(Type.String({ description: 'Alias for missionId; both are accepted.' })),
+  timeoutMs: Type.Optional(
+    Type.Integer({
+      minimum: 1000,
+      description: 'Optional timeout for the merge command in milliseconds, including pre-merge hooks (default 15 minutes).',
+    }),
+  ),
+  timeout_ms: Type.Optional(Type.Integer({ minimum: 1000, description: 'Alias for timeoutMs.' })),
+}, { additionalProperties: false })
+
+export const RebaseInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  missionId: Type.Optional(Type.String({ description: 'Mission id, e.g. M1 (canonical; alias: id).' })),
+  id: Type.Optional(Type.String({ description: 'Alias for missionId; both are accepted.' })),
+}, { additionalProperties: false })
+
+export const TeardownInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  force: Type.Optional(Type.Boolean({ description: 'Remove worktrees that contain uncommitted changes (never a live agent).' })),
+  exclude: Type.Optional(Type.Array(Type.String(), { description: 'Mission ids to keep.' })),
+  dry_run: Type.Optional(Type.Boolean({ description: 'Preview remove/keep decisions without changing disk or state.' })),
+  dryRun: Type.Optional(Type.Boolean({ description: 'Alias for dry_run.' })),
+}, { additionalProperties: false })
+
+export const DiffInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path to the main checkout root.' }),
+  missionId: Type.Optional(Type.String({ description: 'Mission id, e.g. M1 (canonical; alias: id).' })),
+  id: Type.Optional(Type.String({ description: 'Alias for missionId; both are accepted.' })),
+  maxBytes: Type.Optional(Type.Integer({ minimum: 1024, description: 'Patch cap in bytes (default 65536).' })),
+}, { additionalProperties: false })

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

@@ -0,0 +1,94 @@
+// tower_plan / tower_mission / tower_status / tower_complete / tower_review /
+// tower_preflight input contracts. Pure TypeBox only; no I/O.
+import {
+  MERGE_VERDICTS,
+  MISSION_KINDS,
+  MISSION_STATUSES,
+  PAUSE_CAUSES,
+  REVIEW_POLICIES,
+  STATUS_FORMATS,
+} from '../../vocabulary.js'
+import { Type, enumOf } from './shared.js'
+
+export const PlanInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  missions: Type.Array(
+    Type.Object({
+      title: Type.String({ description: 'Printable ASCII title; used as the mission label.' }),
+      scope: Type.Optional(Type.Array(Type.String(), { description: 'Relative file globs this mission may touch; empty only for survey.' })),
+      tasks: Type.Optional(Type.Array(Type.String(), { description: 'Verifiable task items the worker ticks off.' })),
+      deps: Type.Optional(Type.Array(Type.String(), { description: 'Mission ids that must merge before this one.' })),
+      kind: Type.Optional(enumOf(MISSION_KINDS, { description: 'survey = read-only investigation that reserves no scope.' })),
+      context: Type.Optional(Type.String({ description: "The user's own key sentences, verbatim (max 4096 chars)." })),
+      references: Type.Optional(Type.Array(Type.String(), { maxItems: 20, description: 'Read-only pointers/files the worker should read (max 20); copied into the briefing.' })),
+      reviewPolicy: Type.Optional(enumOf(REVIEW_POLICIES, { description: 'required-clean (mission default) means a clean review is required when review.requireReview is on; none needs reviewExemptionReason, and with the review gate on it also needs gates.allowReviewExemption.' })),
+      reviewExemptionReason: Type.Optional(Type.String({ description: 'Non-empty justification when reviewPolicy is "none".' })),
+    }, { additionalProperties: false }),
+    { description: 'Missions to create, in intended order.' },
+  ),
+}, { additionalProperties: false })
+
+export const MissionInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  id: Type.Optional(Type.String({ description: 'Mission id, e.g. M1 (canonical; alias: missionId).' })),
+  missionId: Type.Optional(Type.String({ description: 'Alias for id; both are accepted.' })),
+  status: Type.Optional(enumOf(MISSION_STATUSES, { description: 'New lifecycle status.' })),
+  note: Type.Optional(Type.String({ description: 'Append a decision-log note.' })),
+  blocker: Type.Optional(Type.String({ description: 'Report a blocker (also sets status to blocked).' })),
+  clear_blockers: Type.Optional(Type.Boolean({ description: 'Clear all recorded blockers.' })),
+  clearBlockers: Type.Optional(Type.Boolean({ description: 'Alias for clear_blockers.' })),
+  task_done: Type.Optional(Type.String({ description: 'Mark the first open task containing this text as done.' })),
+  taskDone: Type.Optional(Type.String({ description: 'Alias for task_done.' })),
+  task_drop: Type.Optional(Type.String({ description: 'Mark the first open task containing this text as dropped.' })),
+  taskDrop: Type.Optional(Type.String({ description: 'Alias for task_drop.' })),
+  task_drop_reason: Type.Optional(Type.String({ description: 'Required with task_drop: why the task is legitimately descoped.' })),
+  taskDropReason: Type.Optional(Type.String({ description: 'Alias for task_drop_reason.' })),
+  scope: Type.Optional(Type.Array(Type.String(), { description: 'Tower only: replacement scope globs; bumps scopeGeneration.' })),
+  pause_cause: Type.Optional(enumOf(PAUSE_CAUSES, { description: 'With status=paused: why the mission was paused (default user).' })),
+  authorization: Type.Optional(Type.String({ description: 'Authorization reference recorded when resuming a user-paused mission.' })),
+}, { additionalProperties: false })
+
+export const StatusInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  missionId: Type.Optional(Type.String({ description: 'Return full detail for one mission instead of the dashboard list.' })),
+  offset: Type.Optional(Type.Integer({ minimum: 0, description: 'Mission list offset (default 0).' })),
+  limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100, description: 'Mission list page size (default 20).' })),
+  includeGate: Type.Optional(Type.Boolean({ description: 'Compute tower_preflight-style gate digests for missions on this page.' })),
+  format: Type.Optional(enumOf(STATUS_FORMATS, { description: 'markdown returns the MISSIONS.md board text.' })),
+}, { additionalProperties: false })
+
+export const CompleteInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  missionId: Type.Optional(Type.String({ description: 'Mission id, e.g. M1 (canonical; alias: id).' })),
+  id: Type.Optional(Type.String({ description: 'Alias for missionId; both are accepted.' })),
+  report: Type.String({ description: 'Full completion report for the tower and the next review round.' }),
+  checks: Type.Optional(
+    Type.Array(
+      Type.Object({
+        name: Type.String({ description: 'What was checked.' }),
+        command: Type.Optional(Type.String({ description: 'Command or method used.' })),
+        exitCode: Type.Optional(Type.Integer({ description: 'Observed exit code.' })),
+        evidence: Type.Optional(Type.String({ description: 'Short evidence line/log reference.' })),
+      }, { additionalProperties: false }),
+      { description: 'Optional evidence ledger entries: {name, command?, exitCode?, evidence?}.' },
+    ),
+  ),
+}, { additionalProperties: false })
+
+export const ReviewInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  missionId: Type.Optional(Type.String({ description: 'Mission id, e.g. M1 (canonical; alias: id).' })),
+  id: Type.Optional(Type.String({ description: 'Alias for missionId; both are accepted.' })),
+  status: Type.String({ description: 'Verdict: "clean", or "p1-Nitems" / "p2-Nitems" with the number of findings at that priority.' }),
+  merge: enumOf(MERGE_VERDICTS, { description: 'Merge recommendation for the tower.' }),
+  findings: Type.String({ description: 'Full findings text (markdown); write "none" when clean.' }),
+  checks: Type.Optional(Type.Array(Type.String(), { description: 'Checklist items you verified.' })),
+  decision: Type.String({ description: 'The reasoning behind your verdict.' }),
+  breakGlassReason: Type.Optional(Type.String({ description: 'Tower-only exceptional self-review: why no independent reviewer was used.' })),
+}, { additionalProperties: false })
+
+export const PreflightInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  missionId: Type.Optional(Type.String({ description: 'Mission id, e.g. M1 (canonical; alias: id).' })),
+  id: Type.Optional(Type.String({ description: 'Alias for missionId; both are accepted.' })),
+}, { additionalProperties: false })

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

@@ -0,0 +1,75 @@
+// tower_init / tower_doctor / tower_recover / tower_test / tower_batch /
+// tower_resource / tower_import_legacy / tower_legacy_map / tower_reload input
+// contracts. Pure TypeBox only; no I/O.
+import {
+  BATCH_ACTIONS,
+  LEASE_ACTIONS,
+  LEGACY_MAP_ACTIONS,
+  RECOVERY_ACTIONS,
+} from '../../vocabulary.js'
+import { Type, enumOf, untypedObject } from './shared.js'
+
+export const InitInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  base: Type.Optional(Type.String({ description: 'Optional local base branch (defaults to the checked-out branch).' })),
+  autoGitInit: Type.Optional(Type.Boolean({ description: 'Run git init (and an empty initial commit) when repoRoot is not a repository yet.' })),
+  snapshotDirty: Type.Optional(Type.Boolean({ description: 'Snapshot uncommitted tracked changes into a dangling commit used as the mission baseline (untracked files are not included).' })),
+  reanchor: Type.Optional(Type.Boolean({ description: 'Update the recorded base when no mission is active.' })),
+}, { additionalProperties: false })
+
+export const DoctorInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+}, { additionalProperties: false })
+
+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.' })),
+}, { additionalProperties: false })
+
+export const TestInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  missionId: Type.String({ description: 'Mission id, e.g. M1 (alias: id).' }),
+  id: Type.Optional(Type.String({ description: 'Alias for missionId.' })),
+}, { additionalProperties: false })
+
+export const BatchInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  action: enumOf(BATCH_ACTIONS, { description: 'Batch operation.' }),
+  missionIds: Type.Optional(Type.Array(Type.String(), { description: 'Exact mission ids in this batch (create).' })),
+  exclusions: Type.Optional(Type.Array(Type.String(), { description: 'Paused legacy mission ids excluded from the batch.' })),
+  requiredChecks: Type.Optional(Type.Array(Type.String(), { description: 'Check names every build member must record (default ["check"]).' })),
+  receiptPaths: Type.Optional(Type.Array(Type.String(), { description: 'Exact relative receipt files checked at close.' })),
+  batchId: Type.Optional(Type.String({ description: 'Batch id (status/close/abandon).' })),
+  reason: Type.Optional(Type.String({ description: 'Reason recorded when abandoning a batch.' })),
+  checks: Type.Optional(Type.Array(untypedObject(), { description: 'Close-time extra check evidence.' })),
+  treeTip: Type.Optional(Type.String({ description: 'Expected reviewed/tested commit for close evidence.' })),
+  receiptHashes: Type.Optional(untypedObject('Relative receipt path -> sha256 observed by the caller.')),
+}, { additionalProperties: false })
+
+export const ResourceInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  action: enumOf(LEASE_ACTIONS, { description: 'Lease operation.' }),
+  name: Type.Optional(Type.String({ description: 'Lease name, e.g. plugin-load or heavy-ci.' })),
+  holder: Type.Optional(Type.String({ description: 'Holder label (defaults to the caller).' })),
+  token: Type.Optional(Type.String({ description: 'Release token; generated on acquire when omitted.' })),
+  ttlMs: Type.Optional(Type.Integer({ minimum: 1000, description: 'Lease lifetime (default leases.ttlMs).' })),
+  force: Type.Optional(Type.Boolean({ description: 'Explicitly release an expired lease (token still required).' })),
+}, { additionalProperties: false })
+
+export const ImportLegacyInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  sourcePath: Type.String({ description: 'Absolute path to the legacy JSON state file.' }),
+}, { additionalProperties: false })
+
+export const LegacyMapInput = Type.Object({
+  repoRoot: Type.String({ description: 'Absolute path inside the target Git repository.' }),
+  action: enumOf(LEGACY_MAP_ACTIONS, { description: 'Mapping operation.' }),
+  sourceHash: Type.Optional(Type.String({ description: 'Legacy snapshot sha256 (map).' })),
+  oldId: Type.Optional(Type.String({ description: 'Legacy mission id (map).' })),
+  newMissionId: Type.Optional(Type.String({ description: 'Current mission id; optional audit pointer.' })),
+}, { additionalProperties: false })
+
+export const ReloadInput = Type.Object({
+  repoRoot: Type.Optional(Type.String({ description: 'Optional repository root; when present the caller must be the tower.' })),
+}, { additionalProperties: false, required: [] })

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

@@ -0,0 +1,25 @@
+// Shared TypeBox helpers for tool input schemas (#45, #56 P3c).
+import { Type } from '@sinclair/typebox'
+
+/**
+ * A string enum that serializes to the same JSON Schema shape as the old
+ * inline schemas (type/enum) rather than TypeBox's anyOf union form.
+ * @template {string} T
+ * @param {readonly T[]} values
+ * @param {Record<string, unknown>} [options]
+ * @returns {import('@sinclair/typebox').TUnsafe<T>}
+ */
+export function enumOf(values, options = {}) {
+  return Type.Unsafe(/** @type {any} */ ({ type: 'string', enum: [...values], ...options }))
+}
+
+/**
+ * Untyped JSON object entries (checks, receiptHashes) must keep their exact
+ * `{ type: 'object' }` shape; Type.Object({}) would add a `properties: {}` key.
+ * @param {string} [description]
+ */
+export function untypedObject(description) {
+  return Type.Unsafe(/** @type {any} */ (description === undefined ? { type: 'object' } : { type: 'object', description }))
+}
+
+export { Type }

package/domain/errors.js

@@ -0,0 +1,96 @@
+// Stable tool error codes.
+//
+// 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 is documented in docs/reference/errors.md; scripts/check-docs.mjs
+// keeps the two in sync.
+
+/** Neutral error type shared by the git adapter and the domain classifier. */
+export class GitError extends Error {
+  constructor(args, detail, code, meta = {}) {
+    super(`git ${args.join(' ')} failed: ${detail}`)
+    this.name = 'GitError'
+    this.code = code
+    this.timedOut = meta.timedOut === true
+    this.bufferOverflow = meta.bufferOverflow === true
+    this.stdout = meta.stdout ?? ''
+  }
+}
+
+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.',
+  '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.',
+}
+
+export const ERROR_CODE_VALUES = Object.freeze(Object.keys(ERROR_CODES))
+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'])
+
+export class TowerToolError extends Error {
+  constructor(code, message, options = {}) {
+    super(`[tower:${code}] ${message}`, 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.details = options.details ?? null
+  }
+}
+
+function originalMessage(error) {
+  return String(error?.message ?? error)
+}
+
+/** Wrap any thrown value into a TowerToolError with a stable code. */
+export function classifyError(error) {
+  if (error instanceof TowerToolError) return 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,
+      details: error.details ?? null,
+    })
+  }
+  if (error instanceof GitError || error?.name === 'GitError') {
+    const message = originalMessage(error)
+    const code = error?.timedOut === true || error?.bufferOverflow === true ? 'git-timeout' : 'git-failed'
+    return new TowerToolError(code, message, { cause: error })
+  }
+  return new TowerToolError('tool-internal', originalMessage(error), { cause: error })
+}

package/domain/gate.js

@@ -0,0 +1,125 @@
+// Pure completion gate checks (#49). No repository I/O.
+// @ts-check
+import { isTerminal } from './mission.js'
+import { isReviewExempt, reviewExemptionInvalid } from './integration/review.js'
+
+/** @typedef {import('../types/index.js').Blocker} Blocker */
+/** @typedef {import('../types/index.js').MergeGateOptions} MergeGateOptions */
+/** @typedef {import('../types/index.js').Mission} Mission */
+/** @typedef {import('../types/index.js').Review} Review */
+/** @typedef {import('../types/index.js').TowerConfig} TowerConfig */
+
+/**
+ * @param {Mission} mission
+ * @param {TowerConfig} [config]
+ * @returns {Blocker[]}
+ */
+export function completionBlockers(mission, config = {}) {
+  /** @type {Blocker[]} */
+  const blockers = []
+  /** @type {(code: string, detail: string) => void} */
+  const push = (code, detail) => {
+    blockers.push({ code, detail })
+  }
+  if (isTerminal(mission.status)) {
+    push(
+      'branch-owned-by-closed-missions',
+      `mission ${mission.id} is ${mission.status}; a merge never flips a closed mission — re-plan the work under a new title`,
+    )
+  }
+  if (mission.status !== 'completed') {
+    push('mission-not-completed', `mission ${mission.id} is ${mission.status}; completion is required`)
+  }
+  const openTasks = (mission.tasks ?? []).filter((task) => task.status === 'open')
+  if (openTasks.length > 0) {
+    push('tasks-open', `${openTasks.length} open task(s): ${openTasks.map((task) => task.text).join('; ')}`)
+  }
+  const presentBlockers = mission.blockers ?? []
+  if (presentBlockers.length > 0) push('blockers-present', presentBlockers.join('; '))
+  if (config.gates?.requireChecks === true) {
+    const checks = mission.completionReport?.checks ?? []
+    if (checks.length === 0) {
+      push('no-check-evidence', `mission ${mission.id} has no completion checks; gates.requireChecks is enabled`)
+    }
+  }
+  return blockers
+}
+
+/**
+ * Review, roster, and test-evidence blockers; all inputs are snapshots.
+ * @param {MergeGateOptions} options
+ * @returns {Blocker[]}
+ */
+export function mergeGateBlockers({
+  mission,
+  roster = [],
+  branch = null,
+  branchTip = null,
+  review = null,
+  config = {},
+  activity = {},
+  parentStatus = null,
+  inactiveStates = [],
+  rebaseWaived = false,
+}) {
+  /** @type {Blocker[]} */
+  const blockers = []
+  /** @type {(code: string, detail: string) => void} */
+  const push = (code, detail) => {
+    blockers.push({ code, detail })
+  }
+  const inactive = new Set(inactiveStates)
+  const requireReview = config.review?.requireReview !== false
+  const exempt = isReviewExempt(mission, config)
+  if (reviewExemptionInvalid(mission, config)) {
+    push('review-exemption-invalid', `mission ${mission.id} requests no review but gates.allowReviewExemption is disabled`)
+  }
+  if (requireReview && !exempt && !review) {
+    push('no-review', `branch ${branch ?? '(none)'} has no review; assign a reviewer first (or set review.requireReview:false)`)
+  } else if (requireReview && !exempt) {
+    const latest = /** @type {Review} */ (review)
+    if (latest.missionId !== mission.id) push('review-mission-mismatch', `latest review belongs to mission ${latest.missionId}`)
+    if (latest.status !== 'clean') push('not-clean', `latest review round ${latest.round} is "${latest.status}"`)
+    if (latest.mergeVerdict === 'hold') {
+      push('review-hold', 'latest review recommends hold — a later clean review must supersede it')
+    } else if (latest.status === 'clean' && latest.mergeVerdict !== 'merge') {
+      push('review-not-approved', `latest clean review recommends "${latest.mergeVerdict}" — only "merge" approves`)
+    }
+    if (branchTip && latest.reviewedCommit !== branchTip && !rebaseWaived) {
+      push('tip-moved', `reviewed ${latest.reviewedCommit.slice(0, 7)} but tip is ${branchTip.slice(0, 7)}; re-review required`)
+    }
+  }
+  for (const entry of (roster ?? []).filter((row) => row.missionId === mission.id && !inactive.has(row.state))) {
+    // Reserved rows can lack an agent id; indexing with undefined is a miss.
+    const agentId = /** @type {string} */ (entry.agentId)
+    if (activity[agentId] === 'running') push('worker-busy', `agent ${entry.name} is still running`)
+    else if (parentStatus && entry.parentSessionId && parentStatus[entry.parentSessionId] !== 'ok') {
+      push('worker-status-unknown', `cannot prove agent ${entry.name} is stopped: its parent catalog is unavailable`)
+    }
+  }
+  const staleWorkers = (roster ?? []).filter(
+    (row) => row.missionId === mission.id && (row.state === 'stale' || (row.stale === true && !inactive.has(row.state))),
+  )
+  if (staleWorkers.length > 0) {
+    push('worker-stale', `stale worker(s) for ${mission.id}: ${staleWorkers.map((row) => row.name).join(', ')}; adopt or interrupt before merge`)
+  }
+  if (config.gates?.requireTests === true) {
+    const runs = (mission.testRuns ?? []).filter((run) => run.ok === true && run.treeTip && branchTip && run.treeTip === branchTip)
+    if (runs.length === 0) {
+      push('tests-missing', `mission ${mission.id} has no passing test discovery for tip ${branchTip ? branchTip.slice(0, 7) : '(none)'}`)
+    }
+  }
+  return blockers
+}
+
+/**
+ * A conflict-free rebase after the reviewed tip waives the stale-tip blocker.
+ * @param {Mission} mission
+ * @param {Review} review
+ * @returns {boolean}
+ */
+export function rebaseWaived(mission, review) {
+  const rebase = mission.rebase
+  if (!rebase) return false
+  return review.at <= rebase.at && review.reviewedCommit === rebase.oldTip
+}