dsh-tower 2.0.4 → 2.1.0

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,98 @@
+// 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.',
+  '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.',
+}
+
+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
+}

package/domain/integration/gate.js

@@ -0,0 +1,190 @@
+// Pure preflight/gate blocker computation from state snapshots plus the Git
+// facts the app already read (tips, changed files, checkout branch). The app
+// performs every read and owns the result assembly.
+// @ts-check
+import { caseInsensitiveScopeMatch, fileInScope } from '../scope.js'
+
+/** @typedef {import('../../types/index.js').Blocker} Blocker */
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+/**
+ * @param {string} missionId
+ * @returns {object}
+ */
+export function missingMissionGateResult(missionId) {
+  return {
+    ok: false,
+    blockers: [{ code: 'mission-missing', detail: `unknown mission "${missionId}"` }],
+    missionId,
+    branchTip: null,
+    baseTip: null,
+    changedFiles: [],
+    review: null,
+  }
+}
+
+/**
+ * @param {{ missionId: string, startedAt?: number }} mergeIntent
+ * @returns {Blocker}
+ */
+export function mergeIntentPendingBlocker(mergeIntent) {
+  return {
+    code: 'merge-intent-pending',
+    detail: `a merge intent for ${mergeIntent.missionId} was recorded at ${new Date(Number(mergeIntent.startedAt) || 0).toISOString()}; run tower_merge to reconcile it`,
+  }
+}
+
+/**
+ * @param {string} missionId
+ * @returns {Blocker}
+ */
+export function noWorktreeBlocker(missionId) {
+  return { code: 'branch-missing', detail: `mission ${missionId} has no worktree or branch` }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.branch
+ * @param {string} input.base
+ * @param {string} input.baseTip
+ * @returns {Blocker}
+ */
+export function staleBaseBlocker({ branch, base, baseTip }) {
+  return {
+    code: 'stale-base',
+    detail: `${branch} does not contain base "${base}" tip ${baseTip.slice(0, 12)}; run tower_rebase first`,
+  }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.missionId
+ * @param {string[]} input.changedFiles
+ * @returns {Blocker | null}
+ */
+export function surveyChangedFilesBlocker({ missionId, changedFiles }) {
+  return changedFiles.length > 0
+    ? {
+        code: 'read-only-survey',
+        detail: `survey ${missionId} is read-only but ${changedFiles.length} file(s) changed: ${changedFiles.slice(0, 5).join(', ')}`,
+      }
+    : null
+}
+
+/**
+ * @param {object} input
+ * @param {Mission} input.mission
+ * @param {string[]} input.changedFiles
+ * @param {boolean} [input.caseInsensitive] the checkout's detected comparison mode
+ * @returns {Blocker | null}
+ */
+export function outOfScopeBlocker({ mission, changedFiles, caseInsensitive = false }) {
+  const outOfScope = changedFiles.filter((file) => !fileInScope(mission.scope, file, { caseInsensitive }))
+  if (outOfScope.length === 0) return null
+  const parts = [`changed files outside scope (${mission.scope.join(', ')}): ${outOfScope.slice(0, 8).join(', ')}`]
+  // On a case-sensitive checkout a case-only mismatch is a human error worth
+  // naming, but it stays a rejection: folding here would make src/Api and
+  // src/api the same directory on a filesystem where they are not (#90).
+  if (!caseInsensitive) {
+    const hints = outOfScope
+      .map((file) => {
+        const pattern = caseInsensitiveScopeMatch(mission.scope, file)
+        return pattern
+          ? `${file} matches "${pattern}" only when case is folded; this checkout is case-sensitive`
+          : null
+      })
+      .filter(Boolean)
+      .slice(0, 3)
+    if (hints.length > 0) parts.push(`case mismatch: ${hints.join('; ')}`)
+  }
+  return { code: 'out-of-scope', detail: parts.join('. ') }
+}
+
+/**
+ * @param {string[]} changedFiles
+ * @param {string[]} dirty
+ * @returns {string[]}
+ */
+export function overwrittenPaths(changedFiles, dirty) {
+  return changedFiles.filter((file) => dirty.includes(file))
+}
+
+/**
+ * @param {string[]} wouldOverwrite
+ * @returns {Blocker | null}
+ */
+export function baseDirtyBlocker(wouldOverwrite) {
+  return wouldOverwrite.length > 0
+    ? {
+        code: 'base-dirty',
+        detail: `main checkout has uncommitted changes this merge would overwrite: ${wouldOverwrite.slice(0, 8).join(', ')}`,
+      }
+    : null
+}
+
+/**
+ * @param {object} input
+ * @param {string[]} input.deps
+ * @param {TowerState} input.state
+ * @param {Map<string, { status: string }>} [input.archived] compact archived missions (#73)
+ * @returns {Blocker[]}
+ */
+export function dependencyBlockers({ deps = [], state, archived = new Map() }) {
+  /** @type {Blocker[]} */
+  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)) {
+      blockers.push({ code: 'deps-unmerged', detail: `${depId} is ${dep ? dep.status : 'missing'}` })
+    }
+  }
+  return blockers
+}
+
+/**
+ * @param {object} input
+ * @param {string | null} input.checkoutBranch
+ * @param {string} input.base
+ * @returns {Blocker | null}
+ */
+export function baseWrongBranchBlocker({ checkoutBranch, base }) {
+  return checkoutBranch !== base
+    ? { code: 'base-wrong-branch', detail: `main checkout is on ${checkoutBranch ?? 'detached HEAD'}, expected "${base}"` }
+    : null
+}
+
+/**
+ * Append every blocker produced by a decision helper.
+ * @param {Blocker[]} blockers
+ * @param {Blocker | null} blocker
+ * @returns {Blocker[]}
+ */
+export function pushBlocker(blockers, blocker) {
+  if (blocker) blockers.push(blocker)
+  return blockers
+}
+
+/**
+ * @param {object} input
+ * @param {object} input.mission full mission projection
+ * @param {object | null} input.worktree
+ * @param {string | null} input.branchTip
+ * @param {string | null} input.baseTip
+ * @param {string[]} input.changedFiles
+ * @param {object | null} input.review
+ * @param {Blocker[]} input.blockers
+ * @returns {object}
+ */
+export function gateResult({ mission, worktree, branchTip, baseTip, changedFiles, review, blockers }) {
+  return {
+    ok: blockers.length === 0,
+    blockers,
+    mission,
+    worktree,
+    branchTip,
+    baseTip,
+    changedFiles,
+    review,
+  }
+}