dsh-tower 2.0.3 → 2.1.0-beta.1

package/domain/integration/rebase.js

@@ -0,0 +1,236 @@
+// Pure rebase decisions: the prepared snapshot, durable-intent classification,
+// replay/conflict outcomes, and the strings recorded for reconciliation.
+// Git reads/writes and persistence stay in app/rebase.js.
+// @ts-check
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').RosterEntry} RosterEntry */
+
+export const STALE_PREPARE = 'tower state changed while the rebase was being prepared; retry'
+export const STALE_ACT =
+  'tower state changed while the rebase was running; the rebase intent is retained so the next tower_rebase can reconcile it; retry'
+
+/**
+ * @param {string | null | undefined} tip
+ * @returns {string}
+ */
+export function shortTip(tip) {
+  return String(tip ?? '').slice(0, 7)
+}
+
+/**
+ * @param {RosterEntry} agent
+ * @returns {{ ok: false, blockers: Array<{ code: string, detail: string }> }}
+ */
+export function workerBusyResult(agent) {
+  return { ok: false, blockers: [{ code: 'worker-busy', detail: `agent ${agent.name} is running; rebase refused` }] }
+}
+
+/**
+ * @param {string} path
+ * @returns {{ ok: false, blockers: Array<{ code: string, detail: string }> }}
+ */
+export function dirtyWorktreeResult(path) {
+  return { ok: false, blockers: [{ code: 'worktree-dirty', detail: `${path} has uncommitted changes` }] }
+}
+
+/**
+ * Rewriting an already-landed branch would destroy the reviewed tip.
+ * @param {object} input
+ * @param {string} input.oldTip
+ * @param {string} input.baseTip
+ * @param {string} input.base
+ * @returns {object}
+ */
+export function alreadyMergedRebaseResult({ oldTip, baseTip, base }) {
+  return {
+    ok: true,
+    alreadyMerged: true,
+    skipped: true,
+    oldTip,
+    newTip: oldTip,
+    baseTip,
+    note: `${oldTip.slice(0, 7)} is already contained in ${base} ${baseTip.slice(0, 7)}; branch left untouched — call tower_merge to record the landed merge`,
+  }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.oldTip
+ * @param {string} input.baseTip
+ * @returns {object}
+ */
+export function alreadyUpToDateResult({ oldTip, baseTip }) {
+  return { ok: true, alreadyUpToDate: true, oldTip, newTip: oldTip, baseTip }
+}
+
+/**
+ * Both tips must still match the prepared snapshot before the branch rewrite.
+ * @param {object} input
+ * @param {string} input.oldTip
+ * @param {string} input.baseTip
+ * @param {string} input.currentTip
+ * @param {string} input.currentBase
+ * @returns {boolean}
+ */
+export function rebaseTipsMoved({ oldTip, baseTip, currentTip, currentBase }) {
+  return currentTip !== oldTip || currentBase !== baseTip
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.oldTip
+ * @param {string} input.baseTip
+ * @param {string} input.currentTip
+ * @param {string} input.currentBase
+ * @returns {string}
+ */
+export function rebaseTipsMovedDetail({ oldTip, baseTip, currentTip, currentBase }) {
+  return `tips moved after preparation (${shortTip(oldTip)}/${shortTip(baseTip)} -> ${shortTip(currentTip)}/${shortTip(currentBase)}), so nothing was rebased`
+}
+
+/**
+ * Malformed durable intents are refused rather than guessed.
+ * @param {unknown} intent
+ * @returns {boolean}
+ */
+export function malformedRebaseIntent(intent) {
+  const record = /** @type {Record<string, unknown> | null} */ (intent)
+  return (
+    typeof record !== 'object' ||
+    record === null ||
+    typeof record.missionId !== 'string' ||
+    typeof record.token !== 'string'
+  )
+}
+
+/**
+ * Classify the durable intent from the observed worktree tip. Only the two
+ * unambiguous outcomes are recordable; anything else stays pending.
+ * @param {object} input
+ * @param {{ oldTip: string, baseTip: string, commits?: number | null }} input.intent
+ * @param {Mission | undefined} input.mission
+ * @param {string} [input.tip]
+ * @param {boolean} input.tipReadable
+ * @param {boolean} input.baseIsAncestor
+ * @param {number | null} [input.actualCommits]
+ * @returns {{ action: 'clear' | 'ambiguous' | 'record', reason?: string, tip?: string }}
+ */
+export function classifyRebaseIntent({ intent, mission, tip, tipReadable, baseIsAncestor, actualCommits = null }) {
+  if (!mission || !mission.worktree || typeof mission.worktree.path !== 'string') {
+    return { action: 'clear', reason: 'the mission has no worktree' }
+  }
+  if (!tipReadable) return { action: 'clear', reason: 'the worktree is not readable' }
+  if (tip === intent.oldTip) {
+    return { action: 'clear', reason: 'the branch tip is unchanged (the rebase never ran)' }
+  }
+  if (!baseIsAncestor) return { action: 'ambiguous', tip }
+  if (intent.commits !== null && intent.commits !== undefined) {
+    if (actualCommits !== Number(intent.commits)) return { action: 'ambiguous', tip }
+  }
+  return { action: 'record', tip }
+}
+
+/**
+ * @param {{ missionId: string, startedAt?: number }} intent
+ * @param {string | undefined} tip
+ * @returns {string}
+ */
+export function ambiguousRebaseIntentMessage(intent, tip) {
+  return `a rebase intent for ${intent.missionId} from ${new Date(Number(intent.startedAt) || 0).toISOString()} is pending and cannot be reconciled automatically (tip ${shortTip(tip)} does not match the prepared snapshot); finish or abort the rebase in that worktree, then retry`
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.token
+ * @param {string} input.missionId
+ * @param {string} input.base
+ * @param {string} input.oldTip
+ * @param {string} input.baseTip
+ * @param {number | null} input.commits
+ * @param {number} input.startedAt
+ * @returns {object}
+ */
+export function buildRebaseIntent({ token, missionId, base, oldTip, baseTip, commits, startedAt }) {
+  return { token, missionId, base, oldTip, baseTip, commits, startedAt }
+}
+
+/**
+ * @param {string} base
+ * @param {string} baseTip
+ * @returns {string}
+ */
+export function rebaseConflictNote(base, baseTip) {
+  return `rebase conflict onto ${base} @ ${baseTip.slice(0, 12)}`
+}
+
+/**
+ * @param {string} detail
+ * @returns {{ ok: false, blockers: Array<{ code: string, detail: string }> }}
+ */
+export function rebaseConflictResult(detail) {
+  return { ok: false, blockers: [{ code: 'rebase-conflict', detail }] }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.oldTip
+ * @param {string} input.newTip
+ * @param {string} input.baseTip
+ * @returns {{ ok: true, oldTip: string, newTip: string, baseTip: string, reviewWaived: true }}
+ */
+export function rebaseSuccessResult({ oldTip, newTip, baseTip }) {
+  return { ok: true, oldTip, newTip, baseTip, reviewWaived: true }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.oldTip
+ * @param {string} input.newTip
+ * @param {string} input.baseTip
+ * @returns {string}
+ */
+export function rebaseSuccessNote({ oldTip, newTip, baseTip }) {
+  return `rebased ${shortTip(oldTip)} -> ${shortTip(newTip)} onto ${shortTip(baseTip)}; conflict-free rebase waives re-review`
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.oldTip
+ * @param {string} input.newTip
+ * @param {string} input.baseTip
+ * @returns {string}
+ */
+export function rebaseReconcileNote({ oldTip, newTip, baseTip }) {
+  return `reconciled interrupted rebase ${shortTip(oldTip)} -> ${shortTip(newTip)} onto ${shortTip(baseTip)}; the clean rebase waiver is preserved`
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.oldTip
+ * @param {string} input.newTip
+ * @param {string} input.baseTip
+ * @returns {string}
+ */
+export function rebaseActivityText({ oldTip, newTip, baseTip }) {
+  return `${shortTip(oldTip)} -> ${shortTip(newTip)} onto ${shortTip(baseTip)}`
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.oldTip
+ * @param {string} input.newTip
+ * @param {string} input.baseTip
+ * @returns {string}
+ */
+export function rebaseReconcileActivityText({ oldTip, newTip, baseTip }) {
+  return `reconciled ${shortTip(oldTip)} -> ${shortTip(newTip)} onto ${shortTip(baseTip)}`
+}
+
+/**
+ * @param {string | undefined} reason
+ * @returns {string}
+ */
+export function clearedRebaseIntentActivityText(reason) {
+  return `cleared a stale rebase intent (${reason})`
+}

package/domain/integration/review.js

@@ -0,0 +1,52 @@
+// Pure review-selection and exemption decisions shared by the merge/gate/read
+// projections. No repository I/O.
+// @ts-check
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').Review} Review */
+/** @typedef {import('../../types/index.js').TowerConfig} TowerConfig */
+
+/**
+ * Reviews are branch-scoped; a missing branch has no reviews.
+ * @param {Review[] | null | undefined} reviews
+ * @param {string | null} branch
+ * @returns {Review[]}
+ */
+export function reviewsForBranch(reviews, branch) {
+  return branch ? (reviews ?? []).filter((review) => review.branch === branch) : []
+}
+
+/**
+ * The latest review round, or null when the branch has no reviews.
+ * @param {Review[]} reviews
+ * @returns {Review | null}
+ */
+export function latestReview(reviews) {
+  return reviews.length > 0 ? reviews.reduce((left, right) => (left.round >= right.round ? left : right)) : null
+}
+
+/**
+ * A mission may skip review only with both the exemption gate and a reason.
+ * @param {Mission} mission
+ * @param {TowerConfig} [config]
+ * @returns {boolean}
+ */
+export function isReviewExempt(mission, config = {}) {
+  return (
+    config.review?.requireReview === false ||
+    (mission.reviewPolicy === 'none' &&
+      config.gates?.allowReviewExemption === true &&
+      String(mission.reviewExemptionReason ?? '').trim().length > 0)
+  )
+}
+
+/**
+ * `reviewPolicy: none` is invalid when the reviewer gate does not allow it.
+ * @param {Mission} mission
+ * @param {TowerConfig} [config]
+ * @returns {boolean}
+ */
+export function reviewExemptionInvalid(mission, config = {}) {
+  const requireReview = config.review?.requireReview !== false
+  return requireReview && mission.reviewPolicy === 'none' && config.gates?.allowReviewExemption !== true
+}

package/domain/integration/teardown.js

@@ -0,0 +1,118 @@
+// Pure teardown decisions: keep/remove eligibility and the revalidation of a
+// prepared candidate. Worktree ownership checks and git removals stay in
+// app/teardown.js.
+// @ts-check
+import { hasLiveAgent } from './liveness.js'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+export const STALE_TEARDOWN = 'tower state changed while teardown was being prepared; retry'
+
+/** @typedef {{ missionId: string, action: string, reason?: string, forced?: boolean }} Decision */
+
+/**
+ * Replace a decision object in place so mission order is preserved.
+ * @param {Decision} decision
+ * @param {Record<string, unknown>} value
+ * @returns {void}
+ */
+export function replaceDecision(decision, value) {
+  const missionId = decision.missionId
+  for (const key of Object.keys(decision)) delete /** @type {Record<string, unknown>} */ (decision)[key]
+  Object.assign(decision, { missionId, ...value })
+}
+
+/**
+ * Snapshot-only eligibility before ownership/dirty diagnostics run.
+ * `skip` means the mission has no removable worktree; `decision` is a keep
+ * outcome; `proceed` means the caller must run the ownership/dirty checks.
+ * @param {Mission} mission
+ * @param {object} input
+ * @param {boolean} [input.excluded]
+ * @param {boolean} [input.hasLiveAgent]
+ * @returns {{ skip: true } | { decision: Decision } | { proceed: true }}
+ */
+export function teardownPrecheck(mission, { excluded = false, hasLiveAgent = false } = {}) {
+  const record = /** @type {Record<string, any>} */ (mission)
+  if (!record.worktree || record.worktreeRemovedAt) return { skip: true }
+  if (excluded) return { decision: { missionId: mission.id, action: 'keep', reason: 'excluded' } }
+  if (hasLiveAgent) return { decision: { missionId: mission.id, action: 'keep', reason: 'live agent' } }
+  if (!['merged', 'abandoned'].includes(mission.status)) {
+    return { decision: { missionId: mission.id, action: 'keep', reason: `mission is ${mission.status}` } }
+  }
+  return { proceed: true }
+}
+
+/**
+ * @param {string} missionId
+ * @param {unknown} error
+ * @returns {Decision}
+ */
+export function ownershipUnverifiedDecision(missionId, error) {
+  return {
+    missionId,
+    action: 'keep',
+    reason: `worktree ownership/registration unverified: ${String(/** @type {{ message?: unknown }} */ (error)?.message ?? error).slice(0, 240)}`,
+  }
+}
+
+/**
+ * @param {boolean} dirty
+ * @param {boolean} [force]
+ * @returns {{ action: 'keep', reason: string } | null}
+ */
+export function teardownDirtyDecision(dirty, force) {
+  return dirty && force !== true ? { action: 'keep', reason: 'uncommitted changes' } : null
+}
+
+/**
+ * @param {boolean} dirty
+ * @returns {{ action: 'remove', reason: 'eligible', forced: boolean }}
+ */
+export function teardownRemoveDecision(dirty) {
+  return { action: 'remove', reason: 'eligible', forced: dirty }
+}
+
+/**
+ * Revalidate a prepared candidate against the current state. Used both before
+ * the git lock and again after re-reading state inside it.
+ * @param {TowerState} state
+ * @param {{ missionId: string, worktree: { path: string } }} candidate
+ * @param {Record<string, string | undefined>} [activity]
+ * @returns {{ ok: true, mission: Mission } | { ok: false, reason: string }}
+ */
+export function revalidateTeardownCandidate(state, candidate, activity = {}) {
+  const mission = state.missions.find((entry) => entry.id === candidate.missionId)
+  const record = mission ? /** @type {Record<string, any>} */ (mission) : null
+  if (!record || !record.worktree || record.worktreeRemovedAt) return { ok: false, reason: 'worktree is already gone' }
+  if (record.worktree.path !== candidate.worktree.path) {
+    return { ok: false, reason: 'worktree path changed during teardown' }
+  }
+  if (!['merged', 'abandoned'].includes(record.status)) return { ok: false, reason: `mission is ${record.status}` }
+  if (hasLiveAgent(state, record.id, activity)) return { ok: false, reason: 'live agent' }
+  return { ok: true, mission: /** @type {Mission} */ (mission) }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.branch
+ * @param {string | null} [input.branchDeleteError]
+ * @returns {{ action: 'removed', branch: string, branchRetained?: true, branchDeleteError?: string }}
+ */
+export function teardownRemovedDecision({ branch, branchDeleteError = null }) {
+  return {
+    action: 'removed',
+    branch,
+    ...(branchDeleteError ? { branchRetained: true, branchDeleteError } : {}),
+  }
+}
+
+/**
+ * @param {string} branch
+ * @param {string | null} [branchDeleteError]
+ * @returns {string}
+ */
+export function teardownActivityText(branch, branchDeleteError = null) {
+  return `${branch}${branchDeleteError ? ' (branch retained)' : ''}`
+}

package/domain/mission.js

@@ -0,0 +1,68 @@
+// Pure mission vocabulary and transition rules (#49). No fs, git, or config.
+// @ts-check
+
+/** @typedef {import('../types/index.js').FindingSeverity} FindingSeverity */
+/** @typedef {import('../types/index.js').FindingStatus} FindingStatus */
+/** @typedef {import('../types/index.js').FindingType} FindingType */
+/** @typedef {import('../types/index.js').MergeVerdict} MergeVerdict */
+/** @typedef {import('../types/index.js').MissionStatus} MissionStatus */
+
+/** @type {readonly MissionStatus[]} */
+export const MISSION_STATUSES = ['planned', 'active', 'completed', 'blocked', 'paused', 'merged', 'abandoned']
+export const SCHEMA_VERSION = 1
+/** @type {readonly MergeVerdict[]} */
+export const MERGE_VERDICTS = ['merge', 'fix-then-merge', 'hold']
+export const REVIEW_STATUS_RE = /^(clean|p1-\d+items|p2-\d+items)$/
+/** @type {ReadonlySet<string>} */
+export const TERMINAL_STATUSES = new Set(['merged', 'abandoned'])
+/** @type {readonly FindingType[]} */
+export const FINDING_TYPES = ['bug', 'improve', 'vuln', 'idea']
+/** @type {readonly FindingSeverity[]} */
+export const FINDING_SEVERITIES = ['low', 'medium', 'high', 'critical']
+/** @type {readonly FindingStatus[]} */
+export const FINDING_STATUSES = ['open', 'triaged', 'fixed', 'wontfix']
+/** @type {Record<string, readonly string[]>} */
+export const FINDING_TRANSITIONS = {
+  open: ['triaged', 'fixed', 'wontfix'],
+  triaged: ['open', 'fixed', 'wontfix'],
+  fixed: ['open'],
+  wontfix: ['open'],
+}
+/** @type {readonly string[]} */
+export const PAUSE_CAUSES = ['user', 'failure', 'resource', 'dependency']
+/** @type {Record<string, readonly string[] | undefined>} */
+export const TRANSITIONS = {
+  planned: ['active', 'abandoned'],
+  active: ['completed', 'blocked', 'paused', 'abandoned'],
+  blocked: ['active', 'paused', 'completed', 'abandoned'],
+  paused: ['active', 'abandoned'],
+  completed: ['active', 'abandoned'],
+  merged: [],
+  abandoned: [],
+}
+
+/**
+ * @param {string} status
+ * @returns {boolean}
+ */
+export function isTerminal(status) {
+  return TERMINAL_STATUSES.has(status)
+}
+
+/**
+ * @param {string} from
+ * @param {string} to
+ * @returns {boolean}
+ */
+export function canTransition(from, to) {
+  return (TRANSITIONS[from] ?? []).includes(to)
+}
+
+/**
+ * @param {string | null | undefined} [value]
+ * @returns {string | null}
+ */
+export function pauseCauseError(value) {
+  if (value === undefined || value === null || value === '') return null
+  return PAUSE_CAUSES.includes(value) ? null : `pause_cause must be one of ${PAUSE_CAUSES.join('|')}`
+}

package/domain/missions/completion.js

@@ -0,0 +1,114 @@
+// Pure worker-completion policy and check normalization.
+//
+// app/checkCompletion.js still loads state, verifies the worktree/commits with
+// Git, and persists the transition; the rules below are repository-free.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').RosterEntry} RosterEntry */
+
+/**
+ * @param {string} message
+ * @param {string} [code]
+ * @returns {never}
+ */
+function fail(message, code = 'invalid-argument') {
+  throw new TowerToolError(code, message)
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * Normalize `tower_complete` check evidence.
+ * @param {any} checks
+ * @returns {any[]}
+ */
+export function normalizeChecks(checks) {
+  if (checks === undefined) return []
+  if (!Array.isArray(checks)) fail('checks must be an array')
+  if (checks.length > 20) fail('checks may contain at most 20 entries')
+  return checks.map((check, index) => {
+    if (!isPlainObject(check)) fail(`checks[${index}] must be an object`)
+    const name = typeof check.name === 'string' ? check.name.trim() : ''
+    if (!name) fail(`checks[${index}].name must be a non-empty string`)
+    /** @type {Record<string, any>} */
+    const entry = { name }
+    if (typeof check.command === 'string' && check.command.trim()) entry.command = check.command.trim()
+    if (check.exitCode !== undefined && check.exitCode !== null) {
+      if (!Number.isInteger(check.exitCode)) fail(`checks[${index}].exitCode must be an integer`)
+      entry.exitCode = check.exitCode
+    }
+    if (typeof check.evidence === 'string' && check.evidence.trim()) entry.evidence = check.evidence.trim().slice(0, 4000)
+    return entry
+  })
+}
+
+/**
+ * Resolve and validate the reporting worker and the mission's completion
+ * preconditions that need no repository access.
+ * @param {{ mission: Mission, roster: RosterEntry[] | undefined, input: any }} params
+ * @returns {RosterEntry}
+ */
+export function assertCompletionRequest({ mission, roster, input }) {
+  const worker = (roster ?? []).find((entry) => entry.agentId === input.agentId)
+  if (!worker || worker.missionId !== mission.id) {
+    fail(`agent ${input.agentId} is not assigned to mission ${mission.id}`)
+  }
+  if (worker.role !== 'worker') fail(`agent ${worker.name} is a ${worker.role}, not a worker`)
+  if (['retired', 'failed', 'interrupted', 'missing', 'stale'].includes(worker.state)) {
+    fail(`agent ${worker.name} is ${worker.state}; a stopped worker cannot report completion`)
+  }
+  if (mission.owner && mission.owner !== worker.name) {
+    fail(`agent ${worker.name} is not the current owner of mission ${mission.id} (owner: ${mission.owner})`)
+  }
+  if (mission.status === 'completed') fail(`mission ${mission.id} is already completed`)
+  if (!['active', 'planned'].includes(mission.status)) {
+    fail(`mission ${mission.id} is ${mission.status}; it cannot be completed from that state`)
+  }
+  if (typeof input.report !== 'string' || input.report.trim().length === 0) {
+    fail('tower_complete requires a non-empty report')
+  }
+  const openTasks = (mission.tasks ?? []).filter((task) => task.status === 'open')
+  if (openTasks.length > 0) {
+    fail(
+      `mission ${mission.id} still has ${openTasks.length} open task(s): ${openTasks
+        .map((task) => task.text)
+        .join('; ')}`,
+    )
+  }
+  const blockers = mission.blockers ?? []
+  if (blockers.length > 0) {
+    fail(`mission ${mission.id} has unresolved blockers: ${blockers.join('; ')}`)
+  }
+  if (!mission.worktree) fail(`mission ${mission.id} has no worktree`)
+  return worker
+}
+
+/**
+ * Unread inbox messages block completion.
+ * @param {{ mission: Mission, worker: RosterEntry, unread: unknown[] }} params
+ * @returns {void}
+ */
+export function assertCompletionInbox({ mission, worker, unread }) {
+  if (unread.length > 0) {
+    fail(
+      `mission ${mission.id} cannot complete with ${unread.length} unread inbox message(s) for ${worker.name}; call tower_inbox until unread is 0, incorporate them, then retry`,
+    )
+  }
+}
+
+/**
+ * Project the completion report stored on the mission.
+ * @param {{ report: string, worker: RosterEntry, checks: any[], now: number }} params
+ * @returns {any}
+ */
+export function completionReport({ report, worker, checks, now }) {
+  return { report: report.trim(), by: worker.name, at: now, checks }
+}