dsh-tower 2.0.4 → 2.1.0-beta.1

package/app/board.js

@@ -0,0 +1,25 @@
+// Mission board (MISSIONS.md) writing use cases.
+import path from 'node:path'
+import { fsp } from '../adapters/store-fs.js'
+import { renameWithRetry } from '../lib/store.js'
+
+export function boardFile(tower) {
+  return tower.config.docs?.boardLocation === 'repo'
+    ? path.join(tower.root, 'MISSIONS.md')
+    : path.join(tower.paths.dir, 'MISSIONS.md')
+}
+
+export async function writeBoard(tower) {
+  if (tower.config.docs?.board === false) return null
+  try {
+    const state = await tower.load()
+    const file = boardFile(tower)
+    await tower.ensureExcluded(file)
+    const tmp = `${file}.tmp-${process.pid}-${Date.now()}`
+    await fsp.writeFile(tmp, tower.boardMarkdown(state), 'utf8')
+    await renameWithRetry(tmp, file)
+    return file
+  } catch {
+    return null
+  }
+}

package/app/checkCompletion.js

@@ -0,0 +1,76 @@
+// Worker completion preparation and commit use cases.
+import { TowerToolError } from '../domain/errors.js'
+import {
+  normalizeChecks,
+  assertCompletionRequest,
+  assertCompletionInbox,
+  completionReport,
+} from '../domain/missions/completion.js'
+import { fullMission } from '../domain/summary.js'
+import { validateState } from '../domain/state.js'
+import { countCommits, isClean } from '../lib/git.js'
+import { withLock, writeJsonAtomic, appendJsonl } from '../lib/store.js'
+
+export { normalizeChecks }
+
+export async function checkCompletion(tower, input) {
+  const state = await tower.load()
+  const mission = state.missions.find((entry) => entry.id === input.missionId)
+  if (!mission) {
+    throw new TowerToolError('invalid-argument', `unknown mission "${input.missionId}"`)
+  }
+  const worker = assertCompletionRequest({ mission, roster: state.roster, input })
+  await tower.assertWorktree(mission.worktree)
+  const commits = await countCommits(mission.worktree.path, mission.worktree.baseCommit)
+  if (commits < 1) {
+    throw new TowerToolError(
+      'invalid-argument',
+      `mission branch has no commits since ${String(mission.worktree.baseCommit).slice(0, 12)}`,
+    )
+  }
+  if (!(await isClean(mission.worktree.path))) {
+    const dirty = (await tower.git(mission.worktree.path, ['status', '--porcelain']))
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => line.slice(3).trim())
+    throw new TowerToolError(
+      'worktree-dirty',
+      `mission ${mission.id} worktree has uncommitted changes (${dirty.slice(0, 8).join(', ')}${dirty.length > 8 ? ', …' : ''}); commit, remove, or record them before tower_complete`,
+    )
+  }
+  const unread = tower.unreadFor(state, worker.name)
+  assertCompletionInbox({ mission, worker, unread })
+  return { state, mission, worker, commits }
+}
+
+export async function complete(tower, input) {
+  // Two-phase pilot (#51): expensive git/state checks run before the lock;
+  // the lock only revalidates the state revision and commits the transition.
+  const prepared = await tower.checkCompletion(input)
+  return withLock(tower.paths, async () => {
+    const state = await tower.load()
+    if (state.revision !== prepared.state.revision) {
+      throw new TowerToolError('stale-base', 'tower state changed while completion was being prepared; retry')
+    }
+    const mission = state.missions.find((entry) => entry.id === input.missionId)
+    if (!mission) throw new TowerToolError('mission-not-found', `unknown mission "${input.missionId}"`)
+    const { worker, commits } = prepared
+    const checks = normalizeChecks(input.checks)
+    const now = Date.now()
+    mission.status = 'completed'
+    mission.completionReport = completionReport({ report: input.report, worker, checks, now })
+    mission.updatedAt = now
+    state.revision += 1
+    state.updatedAt = now
+
+    validateState(state, tower.paths.state)
+    await writeJsonAtomic(tower.paths.state, state)
+    await appendJsonl(tower.paths.activity, {
+      at: now,
+      type: 'complete',
+      missionId: mission.id,
+      text: `${worker.name} reported completion (${commits} commit(s))`,
+    })
+    return { mission: fullMission(mission), commits, unread: 0 }
+  })
+}

package/app/enrichedMissions.js

@@ -0,0 +1,26 @@
+// Dashboard mission enrichment use case.
+import { exists } from '../lib/store.js'
+import { revParse } from '../lib/git.js'
+import {
+  enrichedMissionView,
+  latestReviewForMission,
+  missionsToEnrich,
+} from '../domain/read/enrichedMissions.js'
+
+export async function enrichedMissions(tower, state, onlyIds) {
+  const out = []
+  for (const mission of missionsToEnrich(state.missions, onlyIds)) {
+    const latest = latestReviewForMission(state, mission)
+    let tipMoved = false
+    if (latest && mission.worktree && (await exists(mission.worktree.path))) {
+      try {
+        const tip = await revParse(mission.worktree.path, 'HEAD')
+        tipMoved = tip !== latest.reviewedCommit
+      } catch {
+        tipMoved = false
+      }
+    }
+    out.push(enrichedMissionView({ mission, latest, tipMoved }))
+  }
+  return out
+}

package/app/findings.js

@@ -0,0 +1,78 @@
+// Findings use cases.
+import { withLock, writeJsonAtomic, appendJsonl } from '../lib/store.js'
+import { validateState } from '../domain/state.js'
+import { TowerToolError } from '../domain/errors.js'
+import {
+  normalizeFindingInput,
+  newFinding,
+  normalizeFindingActor,
+  wantsFindingUpdate,
+  readFindingsView,
+  applyFindingUpdate,
+  findingUpdateView,
+} from '../domain/missions/findings.js'
+
+function fail(message, code = 'invalid-argument') {
+  throw new TowerToolError(code, message)
+}
+
+export async function addFinding(tower, input) {
+    return withLock(tower.paths, async () => {
+      const state = await tower.load()
+      if (!Array.isArray(state.findings)) state.findings = []
+      const fields = normalizeFindingInput(input, state.missions)
+      const now = Date.now()
+      const seq = (state.findingSeq ?? 0) + 1
+      state.findingSeq = seq
+      const finding = newFinding(fields, { seq, now, reportedBy: input.reportedBy })
+      state.findings.push(finding)
+      state.revision += 1
+      state.updatedAt = now
+
+      validateState(state, tower.paths.state)
+      await writeJsonAtomic(tower.paths.state, state)
+      await appendJsonl(tower.paths.activity, {
+        at: now,
+        type: 'finding',
+        missionId: finding.missionId,
+        text: `${finding.id} ${finding.type}: ${finding.title}`,
+      })
+      return finding
+    })
+  }
+
+  /** List or read findings. Read-only paths never take the writer lock. */
+  export async function readFindings(tower, input = {}) {
+    const state = await tower.load()
+    return readFindingsView(state.findings ?? [], input)
+  }
+
+  /**
+   * List, read, or transition findings. Listing and reading are lock-free;
+   * only a transition takes the writer lock. Reviewers may only read.
+   */
+  export async function findings(tower, input = {}) {
+    const actor = normalizeFindingActor(input.actor)
+    if (!wantsFindingUpdate(input)) return tower.readFindings(input)
+
+    return withLock(tower.paths, async () => {
+      const state = await tower.load()
+      const all = state.findings ?? []
+      const finding = all.find((entry) => entry.id === input.id)
+      if (!finding) fail(`unknown finding "${input.id}"`, 'finding-not-found')
+      const now = Date.now()
+      const { noteAdded } = applyFindingUpdate({ finding, input, actor, now })
+      state.revision += 1
+      state.updatedAt = now
+      validateState(state, tower.paths.state)
+      await writeJsonAtomic(tower.paths.state, state)
+      await appendJsonl(tower.paths.activity, {
+        at: now,
+        type: 'finding',
+        missionId: finding.missionId,
+        text: `${finding.id} ${finding.status}${noteAdded ? ' +note' : ''} (${actor.name})`,
+      })
+      // Counts must reflect the transition just recorded.
+      return findingUpdateView(finding, all)
+    })
+  }

package/app/gate.js

@@ -0,0 +1,108 @@
+// Merge/preflight gate evaluation.
+import { currentBranch } from '../lib/git.js'
+import { ROSTER_INACTIVE_STATES } from '../domain/roster.js'
+import { completionBlockers, mergeGateBlockers } from '../domain/gate.js'
+import { fullMission } from '../domain/summary.js'
+import { latestReview, reviewsForBranch } from '../domain/integration/review.js'
+import {
+  baseDirtyBlocker,
+  baseWrongBranchBlocker,
+  dependencyBlockers,
+  gateResult,
+  mergeIntentPendingBlocker,
+  missingMissionGateResult,
+  noWorktreeBlocker,
+  outOfScopeBlocker,
+  overwrittenPaths,
+  staleBaseBlocker,
+  surveyChangedFilesBlocker,
+} from '../domain/integration/gate.js'
+
+export async function evaluateGate(tower, input) {
+    const state = await tower.load()
+    const mission = state.missions.find((entry) => entry.id === input.missionId)
+    if (!mission) return missingMissionGateResult(input.missionId)
+    const activity = input.activity ?? {}
+    const blockers = []
+    const push = (code, detail) => blockers.push({ code, detail })
+
+    for (const blocker of completionBlockers(mission, tower.config)) push(blocker.code, blocker.detail)
+    if (state.mergeIntent && state.mergeIntent.missionId === mission.id) {
+      const blocker = mergeIntentPendingBlocker(state.mergeIntent)
+      push(blocker.code, blocker.detail)
+    }
+
+    const worktree = mission.worktree ?? null
+    let branchTip = null
+    let baseTip = null
+    let changedFiles = []
+    if (!worktree) {
+      const blocker = noWorktreeBlocker(mission.id)
+      push(blocker.code, blocker.detail)
+    } else {
+      try {
+        await tower.assertWorktree(worktree)
+        branchTip = await tower.revParse(worktree.path, 'HEAD')
+        baseTip = await tower.revParse(tower.root, state.base)
+        const mergeBase = (await tower.git(worktree.path, ['merge-base', baseTip, branchTip])).trim()
+        changedFiles = (await tower.git(worktree.path, ['diff', '--name-only', `${mergeBase}..${branchTip}`]))
+          .split('\n')
+          .filter(Boolean)
+        if (!(await tower.isAncestor(tower.root, baseTip, branchTip))) {
+          const blocker = staleBaseBlocker({ branch: worktree.branch, base: state.base, baseTip })
+          push(blocker.code, blocker.detail)
+        }
+        if (mission.kind === 'survey') {
+          const blocker = surveyChangedFilesBlocker({ missionId: mission.id, changedFiles })
+          if (blocker) push(blocker.code, blocker.detail)
+        }
+        if (mission.kind !== 'survey') {
+          const blocker = outOfScopeBlocker({ mission, changedFiles })
+          if (blocker) push(blocker.code, blocker.detail)
+        }
+        const dirty = (await tower.git(tower.root, ['status', '--porcelain']))
+          .split('\n')
+          .filter(Boolean)
+          .map((line) => line.slice(3).trim())
+        const blocker = baseDirtyBlocker(overwrittenPaths(changedFiles, dirty))
+        if (blocker) push(blocker.code, blocker.detail)
+      } catch (error) {
+        push('branch-missing', String(error?.message ?? error))
+      }
+    }
+
+    for (const blocker of dependencyBlockers({ deps: mission.deps ?? [], state })) {
+      push(blocker.code, blocker.detail)
+    }
+
+    const branch = worktree ? worktree.branch : null
+    const latest = latestReview(reviewsForBranch(state.reviews, branch))
+    for (const blocker of mergeGateBlockers({
+      mission,
+      roster: state.roster ?? [],
+      branch,
+      branchTip,
+      review: latest,
+      config: tower.config,
+      activity,
+      parentStatus: input.parentStatus,
+      inactiveStates: ROSTER_INACTIVE_STATES,
+      rebaseWaived: latest ? tower.rebaseWaived(mission, latest) : false,
+    })) push(blocker.code, blocker.detail)
+
+    const checkoutBranch = await currentBranch(tower.root)
+    const wrongBranch = baseWrongBranchBlocker({ checkoutBranch, base: state.base })
+    if (wrongBranch) push(wrongBranch.code, wrongBranch.detail)
+
+    return gateResult({
+      mission: fullMission(mission),
+      worktree,
+      branchTip,
+      baseTip,
+      changedFiles,
+      review: latest,
+      blockers,
+    })
+  }
+
+  /** Read-only mission diff for reviewers: branch changes against the merge base. */

package/app/init.js

@@ -0,0 +1,249 @@
+// `tower_init` use case, split into three phases (#51):
+//
+//   prepare — dirty/committed/base/snapshot decisions, all lock-free (no state
+//             lock and no git lock; git reads only).
+//   act     — the only Git mutations (stash/update-ref/for-each-ref) run under
+//             the repo-scoped git mutex, never under the state lock.
+//   commit  — one short state lock writes/claims/reanchors, revalidating the
+//             state revision captured by prepare.
+import { withLock, withGitLock, exists, ensureDir, writeJsonAtomic, appendJsonl } from '../lib/store.js'
+import { validateState } from '../domain/state.js'
+import { TowerToolError } from '../domain/errors.js'
+import {
+  SNAPSHOT_REF_PREFIX,
+  claimCaller,
+  createdInitResult,
+  existingInitResult,
+  existingInitWriteResult,
+  explicitBase,
+  fallbackBase,
+  initActivityText,
+  initialState,
+  invalidBaseMessage,
+  ownedByOther,
+  ownerClaimActivityText,
+  reanchorActivityText,
+  reanchorBlockedMessage,
+  shouldReanchor,
+  shouldSnapshot,
+  snapshotRefFor,
+} from '../domain/integration/init.js'
+
+function fail(message, code = 'invalid-argument') {
+  throw new TowerToolError(code, message)
+}
+
+/** Phase 1 of `Tower.init` (#51). A read-only init returns its result here. */
+async function prepareInit(tower, input) {
+  const dirty = !(await tower.isClean(tower.root))
+  const committed = ((await tower.tryGit(tower.root, ['rev-list', '-n', '1', '--all'])) ?? '').trim().length > 0
+
+  const resolveBase = async () => {
+    const explicit = explicitBase(input.base)
+    if (explicit) {
+      const message = invalidBaseMessage(explicit)
+      if (message) fail(message)
+      if (committed && (await tower.tryGit(tower.root, ['show-ref', '--verify', '--quiet', `refs/heads/${explicit}`])) === null) {
+        fail(`base branch "${explicit}" does not exist locally`)
+      }
+      return explicit
+    }
+    const fallback = fallbackBase({ branch: tower.branch, committed })
+    if ('error' in fallback) fail(fallback.error)
+    return /** @type {{ base: string }} */ (fallback).base
+  }
+
+  if (await exists(tower.paths.state)) {
+    const state = await tower.load()
+    const owner = state.towerAgentId ? String(state.towerAgentId) : null
+    const caller = input.towerAgentId ? String(input.towerAgentId) : null
+    if (ownedByOther(owner, caller)) {
+      fail(`tower state is owned by another agent; ${caller} is not the tower`, 'not-authorized')
+    }
+    let reanchorBase = null
+    if (input.reanchor === true) {
+      const refusal = reanchorBlockedMessage(state.missions)
+      if (refusal) fail(refusal, 'invalid-transition')
+      reanchorBase = await resolveBase()
+    }
+    const claim = claimCaller(owner, caller) !== null
+    const reanchor = shouldReanchor({ reanchor: input.reanchor, reanchorBase, currentBase: state.base })
+    if (!claim && !reanchor) {
+      return { early: existingInitResult({ state, statePath: tower.paths.state, dirty }) }
+    }
+    return { stateRevision: state.revision, claim, reanchor, base: reanchorBase, dirty }
+  }
+
+  return {
+    create: true,
+    base: await resolveBase(),
+    snapshot: shouldSnapshot({ snapshotDirty: input.snapshotDirty, dirty }),
+    dirty,
+  }
+}
+
+/**
+ * Phase 2a of `Tower.init` (#51): create the dirty snapshot and its keeping ref
+ * under the git mutex. The prepared "no state file yet" decision is
+ * revalidated first so a concurrent init cannot leave an unreferenced snapshot.
+ */
+async function actInitCreate(tower, prepared) {
+  return withGitLock(tower.paths, async () => {
+    if (await exists(tower.paths.state)) return { stale: true }
+    if (!prepared.snapshot) return { snapshotCommit: null, snapshotRef: null }
+    const snapshotCommit = ((await tower.tryGit(tower.root, ['stash', 'create'])) ?? '').trim() || null
+    if (!snapshotCommit) {
+      fail('snapshotDirty was requested but no snapshot commit could be created; commit or stash the working tree first')
+    }
+    // A dangling commit can be pruned by git gc; keep a ref so the mission
+    // baseline stays reachable for the life of the state.
+    const snapshotRef = snapshotRefFor(snapshotCommit)
+    await tower.git(tower.root, ['update-ref', snapshotRef, snapshotCommit])
+    return { snapshotCommit, snapshotRef }
+  })
+}
+
+/** Phase 2b of `Tower.init` (#51): snapshot-ref cleanup for a base reanchor. */
+async function actInitReanchor(tower, prepared) {
+  return withGitLock(tower.paths, async () => {
+    const state = await tower.load()
+    if (state.revision !== prepared.stateRevision) return { staleRevision: state.revision }
+    if (state.base === prepared.base) return { deleted: [] }
+    const refs =
+      (await tower.tryGit(tower.root, ['for-each-ref', '--format=%(refname) %(objectname)', SNAPSHOT_REF_PREFIX])) ?? ''
+    const deleted = []
+    for (const line of refs.split('\n').map((entry) => entry.trim()).filter(Boolean)) {
+      const [ref, sha] = line.split(' ')
+      if (!ref) continue
+      try {
+        await tower.git(tower.root, ['update-ref', '-d', ref])
+        deleted.push({ ref, sha })
+      } catch {
+        // best effort: the single-phase code never failed init on a stale snapshot ref
+      }
+    }
+    return { deleted }
+  })
+}
+
+/** Restore snapshot refs when the reanchor commit is rejected after phase 2. */
+async function restoreInitRefs(tower, deleted) {
+  const entries = deleted.filter((entry) => typeof entry.sha === 'string' && entry.sha.length > 0)
+  if (entries.length === 0) return
+  await withGitLock(tower.paths, async () => {
+    for (const entry of entries) {
+      await tower.git(tower.root, ['update-ref', entry.ref, entry.sha]).catch(() => {})
+    }
+  })
+}
+
+/** Phase 3a of `Tower.init` (#51): write the initial state under a short lock. */
+async function commitInitCreate(tower, prepared, acted, input) {
+  return withLock(tower.paths, async () => {
+    // Revision revalidation for the create path: prepare saw "absent", so a
+    // state file that appeared meanwhile must never be overwritten.
+    if (await exists(tower.paths.state)) {
+      throw new TowerToolError('stale-base', 'tower state appeared while init was being prepared; retry')
+    }
+    const now = Date.now()
+    const state = initialState({
+      repoRoot: tower.root,
+      commonDir: tower.commonDir,
+      base: prepared.base,
+      dirty: prepared.dirty,
+      towerAgentId: input.towerAgentId ? String(input.towerAgentId) : null,
+      snapshotCommit: acted.snapshotCommit,
+      snapshotRef: acted.snapshotRef,
+      now,
+    })
+    validateState(state, tower.paths.state)
+    await writeJsonAtomic(tower.paths.state, state)
+    await appendJsonl(tower.paths.activity, {
+      at: now,
+      type: 'init',
+      text: initActivityText({ base: prepared.base, snapshotCommit: acted.snapshotCommit, dirty: prepared.dirty }),
+    })
+    return createdInitResult({
+      repoRoot: tower.root,
+      commonDir: tower.commonDir,
+      statePath: tower.paths.state,
+      base: prepared.base,
+      dirty: prepared.dirty,
+      snapshotCommit: acted.snapshotCommit,
+      snapshotRef: acted.snapshotRef,
+    })
+  })
+}
+
+/** Phase 3b of `Tower.init` (#51): owner claim and reanchor writes under a short lock. */
+async function commitInitExisting(tower, prepared, input) {
+  return withLock(tower.paths, async () => {
+    const state = await tower.load()
+    if (state.revision !== prepared.stateRevision) {
+      throw new TowerToolError(
+        'stale-base',
+        `tower state changed while init was being prepared (${prepared.stateRevision} -> ${state.revision}); retry`,
+      )
+    }
+    const now = Date.now()
+    const owner = state.towerAgentId ? String(state.towerAgentId) : null
+    const caller = input.towerAgentId ? String(input.towerAgentId) : null
+    if (ownedByOther(owner, caller)) {
+      fail(`tower state is owned by another agent; ${caller} is not the tower`, 'not-authorized')
+    }
+    const claimant = claimCaller(owner, caller)
+    if (claimant) {
+      state.towerAgentId = claimant
+      state.revision += 1
+      state.updatedAt = now
+      validateState(state, tower.paths.state)
+      await writeJsonAtomic(tower.paths.state, state)
+      await appendJsonl(tower.paths.activity, {
+        at: now,
+        type: 'init',
+        text: ownerClaimActivityText(claimant),
+      })
+    }
+    let reanchored = false
+    if (prepared.reanchor && state.base !== prepared.base) {
+      state.base = prepared.base
+      state.baseChangedAt = now
+      delete state.snapshotCommit
+      delete state.snapshotRef
+      reanchored = true
+      state.revision += 1
+      state.updatedAt = now
+      validateState(state, tower.paths.state)
+      await writeJsonAtomic(tower.paths.state, state)
+      await appendJsonl(tower.paths.activity, { at: now, type: 'init', text: reanchorActivityText(prepared.base) })
+    }
+    return existingInitWriteResult({ state, statePath: tower.paths.state, dirty: prepared.dirty, reanchored })
+  })
+}
+
+/** #51 two-phase init: prepare/act/commit with stale-state retries. */
+export async function init(tower, input = {}) {
+  await ensureDir(tower.paths.dir)
+  const prepared = await prepareInit(tower, input)
+  if (prepared.early) return prepared.early
+  if (prepared.create) {
+    const acted = await actInitCreate(tower, prepared)
+    if (acted.stale) {
+      throw new TowerToolError('stale-base', 'tower state appeared while init was being prepared; retry')
+    }
+    return commitInitCreate(tower, prepared, acted, input)
+  }
+  const acted = prepared.reanchor ? await actInitReanchor(tower, prepared) : { deleted: [] }
+  if (acted.staleRevision !== undefined) {
+    throw new TowerToolError(
+      'stale-base',
+      `tower state changed while init was being prepared (${prepared.stateRevision} -> ${acted.staleRevision}); retry`,
+    )
+  }
+  try {
+    return await commitInitExisting(tower, prepared, input)
+  } catch (error) {
+    if (acted.deleted.length > 0) await restoreInitRefs(tower, acted.deleted)
+    throw error
+  }
+}