dsh-tower 2.0.4 → 2.1.0-beta.1

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

package/domain/integration/gate.js

@@ -0,0 +1,176 @@
+// 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 { 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
+ * @returns {Blocker | null}
+ */
+export function outOfScopeBlocker({ mission, changedFiles }) {
+  const outOfScope = changedFiles.filter((file) => !fileInScope(mission.scope, file))
+  return outOfScope.length > 0
+    ? {
+        code: 'out-of-scope',
+        detail: `changed files outside scope (${mission.scope.join(', ')}): ${outOfScope.slice(0, 8).join(', ')}`,
+      }
+    : null
+}
+
+/**
+ * @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
+ * @returns {Blocker[]}
+ */
+export function dependencyBlockers({ deps = [], state }) {
+  /** @type {Blocker[]} */
+  const blockers = []
+  for (const depId of deps) {
+    const dep = state.missions.find((entry) => entry.id === 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,
+  }
+}

package/domain/integration/init.js

@@ -0,0 +1,225 @@
+// Pure init decisions: explicit/fallback base selection, ownership and reanchor
+// policy, snapshot decisions, and the initial/existing result projections. All
+// fs/git work and state persistence stay in app/init.js.
+// @ts-check
+import { SCHEMA_VERSION, TERMINAL_STATUSES } from '../mission.js'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+export const SNAPSHOT_REF_PREFIX = 'refs/tower/snapshot/'
+
+/**
+ * @param {string} commit
+ * @returns {string}
+ */
+export function snapshotRefFor(commit) {
+  return `${SNAPSHOT_REF_PREFIX}${commit}`
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function explicitBase(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null
+}
+
+/**
+ * An explicit base must be a local branch name, never a raw ref or remote ref.
+ * @param {string} base
+ * @returns {string | null} the failure message, or null when valid
+ */
+export function invalidBaseMessage(base) {
+  return /^refs\//.test(base) || base.startsWith('origin/') ? `base must be a local branch name, not ${base}` : null
+}
+
+/**
+ * Without an explicit base, use the checked-out branch and fall back to `main`
+ * only for an unborn repository.
+ * @param {object} input
+ * @param {string | null} [input.branch]
+ * @param {boolean} input.committed
+ * @returns {{ base: string } | { error: string }}
+ */
+export function fallbackBase({ branch, committed }) {
+  let base = branch
+  if (!base && !committed) base = 'main'
+  if (!base) return { error: 'repository is in detached HEAD; pass an explicit local base branch' }
+  return { base }
+}
+
+/**
+ * @param {string | null} owner
+ * @param {string | null} caller
+ * @returns {boolean}
+ */
+export function ownedByOther(owner, caller) {
+  return Boolean(owner && caller && owner !== caller)
+}
+
+/**
+ * @param {string | null} owner
+ * @param {string | null} caller
+ * @returns {string | null} the caller that claims an unowned state
+ */
+export function claimCaller(owner, caller) {
+  return !owner && caller ? caller : null
+}
+
+/**
+ * @param {Mission[]} missions
+ * @returns {string | null} refusal message, or null when reanchor may proceed
+ */
+export function reanchorBlockedMessage(missions) {
+  const active = missions.filter((mission) => !TERMINAL_STATUSES.has(mission.status))
+  return active.length > 0 ? `cannot reanchor base while ${active.length} mission(s) are not merged or abandoned` : null
+}
+
+/**
+ * @param {object} input
+ * @param {boolean} input.reanchor
+ * @param {string | null} input.reanchorBase
+ * @param {string} input.currentBase
+ * @returns {boolean}
+ */
+export function shouldReanchor({ reanchor, reanchorBase, currentBase }) {
+  return reanchor === true && reanchorBase !== currentBase
+}
+
+/**
+ * @param {object} input
+ * @param {boolean} input.snapshotDirty
+ * @param {boolean} input.dirty
+ * @returns {boolean}
+ */
+export function shouldSnapshot({ snapshotDirty, dirty }) {
+  return snapshotDirty === true && dirty
+}
+
+/**
+ * @param {object} input
+ * @param {TowerState} input.state
+ * @param {string} input.statePath
+ * @param {boolean} input.dirty
+ * @returns {object}
+ */
+export function existingInitResult({ state, statePath, dirty }) {
+  return {
+    created: false,
+    repoRoot: state.repoRoot,
+    commonDir: state.commonDir,
+    statePath,
+    base: state.base,
+    revision: state.revision,
+    missions: state.missions.length,
+    reanchored: false,
+    dirty,
+    snapshotCommit: state.snapshotCommit ?? null,
+  }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.repoRoot
+ * @param {string} input.commonDir
+ * @param {string} input.base
+ * @param {boolean} input.dirty
+ * @param {string | null} [input.towerAgentId]
+ * @param {string | null} [input.snapshotCommit]
+ * @param {string | null} [input.snapshotRef]
+ * @param {number} input.now
+ * @returns {TowerState}
+ */
+export function initialState({ repoRoot, commonDir, base, dirty, towerAgentId = null, snapshotCommit = null, snapshotRef = null, now }) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    repoRoot,
+    commonDir,
+    base,
+    revision: 0,
+    createdAt: now,
+    updatedAt: now,
+    dirtyBase: dirty,
+    ...(towerAgentId ? { towerAgentId: String(towerAgentId) } : {}),
+    ...(snapshotCommit ? { snapshotCommit, snapshotRef } : {}),
+    missions: [],
+  }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.repoRoot
+ * @param {string} input.commonDir
+ * @param {string} input.statePath
+ * @param {string} input.base
+ * @param {boolean} input.dirty
+ * @param {string | null} input.snapshotCommit
+ * @param {string | null} input.snapshotRef
+ * @returns {object}
+ */
+export function createdInitResult({ repoRoot, commonDir, statePath, base, dirty, snapshotCommit, snapshotRef }) {
+  return {
+    created: true,
+    repoRoot,
+    commonDir,
+    statePath,
+    base,
+    revision: 0,
+    missions: 0,
+    reanchored: false,
+    dirty,
+    snapshotCommit,
+    snapshotRef,
+  }
+}
+
+/**
+ * @param {object} input
+ * @param {TowerState} input.state
+ * @param {string} input.statePath
+ * @param {boolean} input.dirty
+ * @param {boolean} input.reanchored
+ * @returns {object}
+ */
+export function existingInitWriteResult({ state, statePath, dirty, reanchored }) {
+  return {
+    created: false,
+    repoRoot: state.repoRoot,
+    commonDir: state.commonDir,
+    statePath,
+    base: state.base,
+    revision: state.revision,
+    missions: state.missions.length,
+    reanchored,
+    dirty,
+    snapshotCommit: state.snapshotCommit ?? null,
+  }
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.base
+ * @param {string | null} [input.snapshotCommit]
+ * @param {boolean} input.dirty
+ * @returns {string}
+ */
+export function initActivityText({ base, snapshotCommit = null, dirty }) {
+  return `base ${base}${snapshotCommit ? ` snapshot ${snapshotCommit.slice(0, 12)}` : ''}${dirty ? ' (dirty base)' : ''}`
+}
+
+/**
+ * @param {string} caller
+ * @returns {string}
+ */
+export function ownerClaimActivityText(caller) {
+  return `tower owner claimed by ${caller}`
+}
+
+/**
+ * @param {string} base
+ * @returns {string}
+ */
+export function reanchorActivityText(base) {
+  return `base reanchored to ${base}`
+}

package/domain/integration/liveness.js

@@ -0,0 +1,31 @@
+// Pure roster-liveness decisions shared by rebase/teardown guards. A live
+// worker is a roster row for the mission that is neither inactive nor finished
+// and whose observed activity is "running".
+// @ts-check
+import { ROSTER_INACTIVE } from '../roster.js'
+
+/** @typedef {import('../../types/index.js').RosterEntry} RosterEntry */
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+/**
+ * @param {TowerState} state
+ * @param {string} missionId
+ * @param {Record<string, string | undefined>} activity
+ * @returns {RosterEntry | undefined}
+ */
+export function liveAgentFor(state, missionId, activity) {
+  return (state.roster ?? []).find(
+    (entry) =>
+      entry.missionId === missionId && !ROSTER_INACTIVE.has(entry.state) && activity[String(entry.agentId)] === 'running',
+  )
+}
+
+/**
+ * @param {TowerState} state
+ * @param {string} missionId
+ * @param {Record<string, string | undefined>} activity
+ * @returns {boolean}
+ */
+export function hasLiveAgent(state, missionId, activity) {
+  return liveAgentFor(state, missionId, activity) !== undefined
+}