dsh-tower 2.0.3 → 2.1.0-beta.1

package/app/review.js

@@ -0,0 +1,145 @@
+// Independent review submission use case.
+import { withLock, writeJsonAtomic, appendJsonl } from '../lib/store.js'
+import { validateState } from '../domain/state.js'
+import { TowerToolError } from '../domain/errors.js'
+import {
+  assertReviewableMission,
+  resolveReviewActor,
+  normalizeReviewVerdict,
+  assertReviewerSpawnTip,
+  reviewRound,
+  reviewOutcome,
+  reviewRecord,
+} from '../domain/missions/review.js'
+
+function fail(message, code = 'invalid-argument') {
+  throw new TowerToolError(code, message)
+}
+
+/**
+ * Phase 1 (#51): load state and capture everything the review needs — actor
+ * checks, worktree ownership, branch tip, and round counters — without holding
+ * the state lock. No git call may run inside the lock.
+ */
+async function prepareReview(tower, input) {
+  const state = await tower.load()
+  const mission = state.missions.find((entry) => entry.id === input.missionId)
+  if (!mission) fail(`unknown mission "${input.missionId}"`)
+  assertReviewableMission(mission)
+
+  const caller = (state.roster ?? []).find((entry) => entry.agentId === input.agentId)
+  const { reviewerName, reviewerRole } = resolveReviewActor({
+    mission,
+    caller,
+    actorRole: input.actor?.role,
+    agentId: input.agentId,
+    breakGlassReason: input.breakGlassReason,
+  })
+
+  if (mission.status !== 'completed') {
+    fail(`mission ${mission.id} is ${mission.status}; only a completed mission can be reviewed`)
+  }
+  const verdict = normalizeReviewVerdict(input)
+
+  await tower.assertWorktree(mission.worktree)
+  const tip = await tower.revParse(mission.worktree.path, 'HEAD')
+  const branch = mission.worktree.branch
+  assertReviewerSpawnTip(caller, tip)
+  const { reviewerRounds, round } = reviewRound({
+    reviews: state.reviews,
+    branch,
+    reviewerName,
+    maxRoundsPerReviewer: tower.config.review.maxRoundsPerReviewer,
+  })
+
+  return {
+    stateRevision: state.revision,
+    missionId: mission.id,
+    branch,
+    tip,
+    status: verdict.status,
+    merge: verdict.merge,
+    findings: verdict.findings,
+    checks: verdict.checks,
+    decision: verdict.decision,
+    reviewerName,
+    reviewerRole,
+    reviewerRounds,
+    round,
+    breakGlassReason: reviewerRole === 'tower' ? input.breakGlassReason.trim() : undefined,
+  }
+}
+
+export async function submitReview(tower, input) {
+  // Two-phase (#51): the lock is held only for the state reload, revision
+  // revalidation, and write; every git call happens in prepareReview.
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const prepared = await prepareReview(tower, input)
+    try {
+      return await withLock(tower.paths, async () => {
+    const state = await tower.load()
+    if (state.revision !== prepared.stateRevision) {
+      throw new TowerToolError('stale-base', 'tower state changed while the review was being prepared; retry')
+    }
+    const mission = state.missions.find((entry) => entry.id === input.missionId)
+    if (!mission) fail(`unknown mission "${input.missionId}"`)
+
+    const now = Date.now()
+    const seq = (state.reviewSeq ?? 0) + 1
+    state.reviewSeq = seq
+    const review = reviewRecord({
+      seq,
+      missionId: mission.id,
+      branch: prepared.branch,
+      tip: prepared.tip,
+      verdict: {
+        status: prepared.status,
+        merge: prepared.merge,
+        findings: prepared.findings,
+        checks: prepared.checks,
+        decision: prepared.decision,
+      },
+      reviewerName: prepared.reviewerName,
+      reviewerRole: prepared.reviewerRole,
+      round: prepared.round,
+      now,
+      breakGlassReason: prepared.breakGlassReason,
+    })
+    if (!Array.isArray(state.reviews)) state.reviews = []
+    state.reviews.push(review)
+
+    const outcome = reviewOutcome({
+      status: prepared.status,
+      merge: prepared.merge,
+      round: prepared.round,
+      reviewerName: prepared.reviewerName,
+    })
+    if (outcome.returnToActive) mission.status = 'active'
+    mission.notes.push(outcome.note)
+    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: 'review',
+      missionId: mission.id,
+      text: `round ${prepared.round} ${prepared.reviewerName}: ${prepared.status} / ${prepared.merge} @ ${prepared.tip.slice(0, 12)}`,
+    })
+    return {
+      review,
+      branchTip: prepared.tip,
+      missionStatus: mission.status,
+      round: prepared.round,
+      reviewerRounds: prepared.reviewerRounds + 1,
+    }
+      })
+    } catch (error) {
+      if (error.code === 'stale-base' && attempt === 0) continue
+      throw error
+    }
+  }
+  throw new TowerToolError('stale-base', 'tower state kept changing while the review was being prepared; retry')
+}

package/app/roster.js

@@ -0,0 +1,123 @@
+// Roster observation and retirement use cases.
+import { withLock, writeJsonAtomic, appendJsonl } from '../lib/store.js'
+import { validateState } from '../domain/state.js'
+import {
+  recordRosterObservations as recordObservations,
+  reconcileObservedInactive as reconcileInactive,
+  retireEntries,
+  markMissingEntries,
+  sweepRosterState,
+} from '../domain/collab/roster.js'
+import { unreadMessages } from '../domain/collab/messages.js'
+
+export async function recordRosterObservations(tower, { present = [], absent = [], confirmations = 2 }) {
+    return withLock(tower.paths, async () => {
+      const state = await tower.load()
+      const now = Date.now()
+      const { candidates, changed } = recordObservations(
+        state.roster ?? [],
+        { present, absent, confirmations },
+        now,
+      )
+      if (changed) {
+        state.revision += 1
+        state.updatedAt = now
+        validateState(state, tower.paths.state)
+        await writeJsonAtomic(tower.paths.state, state)
+      }
+      return { candidates }
+    })
+  }
+
+  /** Release live roster slots whose catalog activity is explicitly inactive. */
+  export async function reconcileObservedInactive(tower, activity = {}) {
+    return withLock(tower.paths, async () => {
+      const state = await tower.load()
+      const now = Date.now()
+      const { released } = reconcileInactive(state.roster ?? [], activity, now)
+      if (released.length > 0) {
+        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: 'roster',
+          text: `released inactive slots: ${released.join(', ')}`,
+        })
+      }
+      return { released }
+    })
+  }
+
+  export async function markRetired(tower, agentIds) {
+    if (!Array.isArray(agentIds) || agentIds.length === 0) return { retired: [] }
+    return withLock(tower.paths, async () => {
+      const state = await tower.load()
+      const now = Date.now()
+      const { retired } = retireEntries(state.roster ?? [], agentIds, now)
+      if (retired.length > 0) {
+        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: 'adopt',
+          text: `retired ${retired.join(', ')}`,
+        })
+      }
+      return { retired }
+    })
+  }
+
+  export async function markMissing(tower, agentIds) {
+    if (!Array.isArray(agentIds) || agentIds.length === 0) return { missing: [] }
+    return withLock(tower.paths, async () => {
+      const state = await tower.load()
+      const now = Date.now()
+      const { missing } = markMissingEntries(state.roster ?? [], agentIds, now)
+      if (missing.length > 0) {
+        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: 'adopt', text: `missing ${missing.join(', ')}` })
+      }
+      return { missing }
+    })
+  }
+
+  /** Mark live roster entries whose catalog activity disappeared after staleMs.
+   * `authoritative` must be true only when the parent catalog was readable;
+   * unknown state is never treated as stopped. */
+  export async function sweepRoster(tower, input = {}) {
+    const staleMs = Number(input.staleMs) || 0
+    if (staleMs <= 0 || input.authoritative !== true) return { marked: [], idled: [] }
+    const activity = input.activity ?? {}
+    return withLock(tower.paths, async () => {
+      const state = await tower.load()
+      const now = Date.now()
+      const { marked, idled } = sweepRosterState(
+        state.roster ?? [],
+        { activity, staleMs, authoritative: input.authoritative },
+        now,
+      )
+      if (marked.length > 0 || idled.length > 0) {
+        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: 'watchdog',
+          text: `stale ${marked.join(', ') || '-'}; idle ${idled.join(', ') || '-'}`,
+        })
+      }
+      return { marked, idled }
+    })
+  }
+
+  export function unreadFor(tower, state, name) {
+    return /** @type {any} */ (unreadMessages(state, name))
+  }

package/app/spawn.js

@@ -0,0 +1,125 @@
+// Spawn reservation/outcome and roster recording use cases.
+import { TowerToolError } from '../domain/errors.js'
+import {
+  applySpawnOutcome,
+  applyInterrupt,
+  reserveRosterEntry,
+  recordSpawnEntry,
+  rosterProjection,
+} from '../domain/collab/spawn.js'
+import { validateState } from '../domain/state.js'
+import { withLock, writeJsonAtomic, appendJsonl } from '../lib/store.js'
+
+function fail(message, code = 'invalid-argument') {
+  throw new TowerToolError(code, message)
+}
+
+/** Record that a spawned agent failed or went idle, so roster state is truthful. */
+export async function recordSpawnOutcome(tower, input) {
+  return withLock(tower.paths, async () => {
+    const state = await tower.load()
+    const entry = (state.roster ?? []).find((row) => row.name === input.name && row.missionId === input.missionId)
+    if (!entry) return null
+    const now = Date.now()
+    applySpawnOutcome(entry, input, 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: 'spawn',
+      missionId: input.missionId,
+      text: `${entry.name} ${entry.state}${entry.outcome ? `: ${entry.outcome.slice(0, 160)}` : ''}`,
+    })
+    return entry
+  })
+}
+
+/** Record that a live agent was interrupted by the tower. */
+export async function recordInterrupt(tower, input) {
+  return withLock(tower.paths, async () => {
+    const state = await tower.load()
+    const entry = (state.roster ?? []).find(
+      (row) =>
+        (input.agentId !== undefined && row.agentId === input.agentId) ||
+        (input.name !== undefined && row.name === input.name),
+    )
+    if (!entry) fail(`unknown roster agent "${input.name ?? input.agentId}"`)
+    const now = Date.now()
+    applyInterrupt(entry, input, 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: 'spawn',
+      missionId: entry.missionId,
+      text: `${entry.name} interrupted: ${entry.outcome}`,
+    })
+    return entry
+  })
+}
+
+/** Reserve a roster name before activation so a failed spawn is recoverable. */
+export async function reserveRoster(tower, input) {
+  return withLock(tower.paths, async () => {
+    const state = await tower.load()
+    const mission = state.missions.find((entry) => entry.id === input.missionId)
+    if (!mission) fail(`unknown mission "${input.missionId}"`)
+    if (!Array.isArray(state.roster)) state.roster = []
+    const now = Date.now()
+    const entry = reserveRosterEntry({ roster: state.roster, input, now })
+    state.roster.push(entry)
+    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: 'spawn',
+      missionId: input.missionId,
+      text: `reserved ${input.role} ${input.name}`,
+    })
+    return entry
+  })
+}
+
+export async function recordSpawn(tower, input) {
+  // Capture the spawn tip before taking the state lock (#51).
+  const spawnTip = input.cwd ? ((await tower.tryGit(input.cwd, ['rev-parse', 'HEAD'])) ?? '').trim() || null : null
+  return withLock(tower.paths, async () => {
+    const state = await tower.load()
+    const mission = state.missions.find((entry) => entry.id === input.missionId)
+    if (!mission) fail(`unknown mission "${input.missionId}"`)
+    if (!Array.isArray(state.roster)) state.roster = []
+    const now = Date.now()
+    const entry = recordSpawnEntry({
+      roster: state.roster,
+      mission,
+      input,
+      spawnTip,
+      maxLiveWorkers: tower.config.spawn.maxLiveWorkers,
+      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: 'spawn',
+      missionId: input.missionId,
+      text: `${input.role} ${input.name} (${input.agentId})`,
+    })
+    return entry
+  })
+}
+
+export async function rosterView(tower) {
+  const state = await tower.load()
+  return rosterProjection(state)
+}

package/app/teardown.js

@@ -0,0 +1,184 @@
+// Worktree teardown use case.
+//
+// #51 two-phase: eligibility diagnostics (ownership, registration, dirty
+// state) run outside the state lock; each removal runs its git commands under
+// the git lock and is committed in its own short state lock. Every removal
+// therefore bumps the state revision exactly once, and the revision is
+// revalidated immediately before the irreversible git mutation so a stale
+// decision never removes a worktree that changed hands.
+import { withLock, withGitLock, writeJsonAtomic, appendJsonl } from '../lib/store.js'
+import { validateState } from '../domain/state.js'
+import { TowerToolError } from '../domain/errors.js'
+import { hasLiveAgent } from '../domain/integration/liveness.js'
+import {
+  ownershipUnverifiedDecision,
+  replaceDecision as setDecision,
+  revalidateTeardownCandidate,
+  STALE_TEARDOWN as STALE,
+  teardownActivityText,
+  teardownDirtyDecision,
+  teardownPrecheck,
+  teardownRemoveDecision,
+  teardownRemovedDecision,
+} from '../domain/integration/teardown.js'
+
+/**
+ * Phase 1 (#51): decide every keep/remove outcome without holding the state
+ * lock. Removable worktrees become candidates; the returned decision objects
+ * stay mutable so the removal outcome can replace them in mission order.
+ */
+async function prepareTeardown(tower, input) {
+  const state = await tower.load()
+  const activity = input.activity ?? {}
+  const exclude = new Set(input.exclude ?? [])
+  const dryRun = input.dryRun === true
+  const decisions = []
+  const candidates = []
+
+  for (const mission of state.missions) {
+    const precheck = teardownPrecheck(mission, {
+      excluded: exclude.has(mission.id),
+      hasLiveAgent: hasLiveAgent(state, mission.id, activity),
+    })
+    if ('skip' in precheck) continue
+    if ('decision' in precheck) {
+      decisions.push(precheck.decision)
+      continue
+    }
+    try {
+      await tower.assertWorktree(mission.worktree)
+    } catch (error) {
+      decisions.push(ownershipUnverifiedDecision(mission.id, error))
+      continue
+    }
+    let dirty = true
+    try {
+      dirty = !(await tower.isClean(mission.worktree.path))
+    } catch {
+      dirty = true
+    }
+    const dirtyKeep = teardownDirtyDecision(dirty, input.force)
+    if (dirtyKeep) {
+      decisions.push({ missionId: mission.id, ...dirtyKeep })
+      continue
+    }
+    if (dryRun) {
+      decisions.push({ missionId: mission.id, ...teardownRemoveDecision(dirty) })
+      continue
+    }
+    const decision = { missionId: mission.id, ...teardownRemoveDecision(dirty) }
+    decisions.push(decision)
+    candidates.push({ missionId: mission.id, worktree: mission.worktree, decision })
+  }
+
+  return { stateRevision: state.revision, decisions, candidates, dryRun }
+}
+
+/** Short state lock: reject a stale decision before any git mutation. */
+async function claimRemoval(tower, candidate, expectedRevision, input) {
+  const activity = input.activity ?? {}
+  return withLock(tower.paths, async () => {
+    const state = await tower.load()
+    if (state.revision !== expectedRevision) {
+      throw new TowerToolError('stale-base', `${STALE}. No worktree was removed.`)
+    }
+    return revalidateTeardownCandidate(state, candidate, activity)
+  })
+}
+
+export async function teardown(tower, input) {
+  const prepared = await prepareTeardown(tower, input)
+  if (prepared.dryRun) return { ok: true, dryRun: true, removed: [], decisions: prepared.decisions }
+
+  const removed = []
+  let expectedRevision = prepared.stateRevision
+
+  for (const candidate of prepared.candidates) {
+    const claim = await claimRemoval(tower, candidate, expectedRevision, input)
+    if (!claim.ok) {
+      setDecision(candidate.decision, { action: 'keep', reason: claim.reason })
+      continue
+    }
+
+    // Phase 2 (#51): the irreversible git work runs under the git lock and
+    // never under the state lock. Re-read state without the lock right before
+    // mutating: the git lock may have waited behind another operation, so a
+    // stale candidate is refused while the worktree still exists.
+    const outcome = await withGitLock(tower.paths, async () => {
+      let fresh
+      try {
+        fresh = await tower.load()
+      } catch (error) {
+        return { phase: 'stale', detail: String(error?.message ?? error) }
+      }
+      if (fresh.revision !== expectedRevision) {
+        return { phase: 'stale', detail: `state revision changed from ${expectedRevision} to ${fresh.revision} before the removal` }
+      }
+      const current = revalidateTeardownCandidate(fresh, candidate, input.activity ?? {})
+      if (!current.ok) return { phase: 'skip', reason: current.reason }
+      const mission = current.mission
+      const worktree = mission.worktree
+      if (!worktree) return { phase: 'skip', reason: 'worktree is already gone' }
+      let dirty = true
+      try {
+        dirty = !(await tower.isClean(worktree.path))
+      } catch {
+        dirty = true
+      }
+      const dirtyKeep = teardownDirtyDecision(dirty, input.force)
+      if (dirtyKeep) return { phase: 'skip', reason: dirtyKeep.reason }
+      try {
+        await tower.git(tower.root, ['worktree', 'remove', ...(dirty ? ['--force'] : []), worktree.path])
+      } catch (error) {
+        return { phase: 'remove-failed', reason: `remove failed: ${String(error?.message ?? error)}` }
+      }
+      let branchDeleteError = null
+      try {
+        await tower.git(tower.root, ['branch', '-d', worktree.branch])
+      } catch (error) {
+        branchDeleteError = String(error?.message ?? error).slice(0, 240)
+      }
+      return { phase: 'removed', branch: worktree.branch, branchDeleteError }
+    })
+
+    if (outcome.phase === 'stale') {
+      throw new TowerToolError('stale-base', `${STALE}: ${outcome.detail}. No worktree was removed.`)
+    }
+    if (outcome.phase !== 'removed') {
+      setDecision(candidate.decision, { action: 'keep', reason: outcome.reason })
+      continue
+    }
+
+    // Phase 3 (#51): commit this removal alone in a short state lock. The
+    // removal already happened, so if a writer landed while git ran we apply
+    // the removal on the freshly loaded state instead of rejecting it (which
+    // would leave state claiming a worktree that no longer exists). Only this
+    // mission's fields change, so no concurrent update is lost.
+    const commit = await withLock(tower.paths, async () => {
+      const state = await tower.load()
+      const mission = state.missions.find((entry) => entry.id === candidate.missionId)
+      if (!mission) return { revision: state.revision }
+      const now = Date.now()
+      mission.worktreeRemovedAt = now
+      mission.updatedAt = now
+      if (outcome.branchDeleteError) mission.branchDeleteError = outcome.branchDeleteError
+      else delete mission.branchDeleteError
+      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: 'teardown',
+        missionId: mission.id,
+        text: teardownActivityText(outcome.branch, outcome.branchDeleteError),
+      })
+      return { revision: state.revision }
+    })
+    expectedRevision = commit.revision
+    removed.push(candidate.missionId)
+    setDecision(candidate.decision, teardownRemovedDecision(outcome))
+  }
+
+  return { ok: true, dryRun: false, removed, decisions: prepared.decisions }
+}