dsh-tower 2.0.4 → 2.1.0-beta.1

package/app/plan.js

@@ -0,0 +1,42 @@
+// Mission planning use case.
+import { nextMissionNumber, addAutoDeps, assertAcyclic } from '../domain/planning.js'
+import {
+  normalizePlanMissions,
+  assignMissionIds,
+  assertKnownDependencies,
+  newMission,
+} from '../domain/missions/plan.js'
+import { validateState } from '../domain/state.js'
+import { fullMission } from '../domain/summary.js'
+import { withLock, writeJsonAtomic, appendJsonl } from '../lib/store.js'
+
+export async function plan(tower, input = {}) {
+  const prepared = normalizePlanMissions(input)
+  return withLock(tower.paths, async () => {
+    const state = await tower.load()
+    const now = Date.now()
+    const assigned = assignMissionIds(prepared, nextMissionNumber(state.missions))
+
+    assertKnownDependencies(assigned, state.missions)
+
+    addAutoDeps(assigned, state.missions)
+    assertAcyclic([...state.missions, ...assigned])
+
+    const created = assigned.map((mission) => newMission(mission.id, mission, now))
+    state.missions.push(...created)
+    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: 'plan',
+      text: `created ${created.map((mission) => mission.id).join(', ')}`,
+    })
+    return {
+      revision: state.revision,
+      missions: created.map((mission) => fullMission(mission)),
+    }
+  })
+}

package/app/provision.js

@@ -0,0 +1,193 @@
+// `tower_provision` use case, split into three phases (#51):
+//
+//   prepare — mission/base commit/worktree identity, all lock-free.
+//   act     — revalidate the prepared revision, then `git worktree add` (and
+//             its supporting exclude/canonical reads) under the git mutex.
+//   commit  — one short state lock revalidates the revision and that the
+//             mission still has no worktree, then records it. A rejected
+//             commit rolls the created worktree/branch back outside the lock.
+import path from 'node:path'
+import { withLock, withGitLock, exists, ensureDir, writeJsonAtomic, appendJsonl, shortHash } from '../lib/store.js'
+import { validateState } from '../domain/state.js'
+import { canonicalPath } from '../lib/worktreeOwnership.js'
+import { TowerToolError } from '../domain/errors.js'
+import {
+  baseCommitChoice,
+  createdWorktreeResult,
+  existingWorktreeResult,
+  hasMissionId,
+  provisionActivityText,
+  worktreeBranch,
+  worktreePath,
+  worktreeRecord,
+  worktreeRoot,
+} from '../domain/integration/provision.js'
+
+function fail(message, code = 'invalid-argument') {
+  throw new TowerToolError(code, message)
+}
+
+/** Phase 1 of `Tower.provision` (#51). An existing worktree returns here. */
+async function prepareProvision(tower, input) {
+  const state = await tower.load()
+  const mission = state.missions.find((entry) => entry.id === input.missionId)
+  if (!mission) fail(`unknown mission "${input.missionId}"`, 'mission-not-found')
+  if (mission.worktree) {
+    await tower.assertWorktree(mission.worktree)
+    return { early: existingWorktreeResult(mission, mission.worktree) }
+  }
+  const needsSnapshot = !input.baseCommit && input.includeDirtyBase !== false
+  const snapshotCommitValid =
+    needsSnapshot && state.snapshotCommit
+      ? (await tower.tryGit(tower.root, ['cat-file', '-e', `${state.snapshotCommit}^{commit}`])) !== null
+      : false
+  const choice = baseCommitChoice({
+    baseCommit: input.baseCommit,
+    includeDirtyBase: input.includeDirtyBase,
+    snapshotCommit: state.snapshotCommit,
+    snapshotCommitValid,
+  })
+  const baseCommit = 'commit' in choice ? choice.commit : await tower.revParse(tower.root, state.base)
+  const branch = worktreeBranch(mission)
+  const root = worktreeRoot({
+    worktreeRoot: input.worktreeRoot,
+    configuredRoot: tower.config.worktrees.root,
+    repoRoot: tower.root,
+    commonDirHash: shortHash(tower.commonDir),
+  })
+  if (!path.isAbsolute(root)) fail('worktreeRoot must be an absolute path')
+  tower.assertOutside(root)
+  await ensureDir(root)
+  const wtPath = worktreePath(root, mission.id)
+  if (await exists(wtPath)) fail(`worktree path already exists: ${wtPath}`)
+  if ((await tower.tryGit(tower.root, ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`])) !== null) {
+    fail(`branch already exists: ${branch}`)
+  }
+  return { stateRevision: state.revision, missionId: mission.id, baseCommit, branch, wtPath }
+}
+
+/** Phase 2 of `Tower.provision` (#51): no state lock, worktree add under the git mutex. */
+async function actProvision(tower, prepared) {
+  return withGitLock(tower.paths, async () => {
+    let fresh
+    try {
+      fresh = await tower.load()
+    } catch (error) {
+      return { phase: 'stale', detail: String(error?.message ?? error) }
+    }
+    if (fresh.revision !== prepared.stateRevision) {
+      return { phase: 'stale', detail: `state revision changed from ${prepared.stateRevision} to ${fresh.revision}` }
+    }
+    const mission = fresh.missions.find((entry) => entry.id === prepared.missionId)
+    if (!mission) return { phase: 'missing' }
+    if (mission.worktree) {
+      await tower.assertWorktree(mission.worktree)
+      return { phase: 'existing', mission, worktree: mission.worktree }
+    }
+    if (await exists(prepared.wtPath)) fail(`worktree path already exists: ${prepared.wtPath}`)
+    if ((await tower.tryGit(tower.root, ['show-ref', '--verify', '--quiet', `refs/heads/${prepared.branch}`])) !== null) {
+      fail(`branch already exists: ${prepared.branch}`)
+    }
+    await tower.git(tower.root, ['worktree', 'add', '-b', prepared.branch, prepared.wtPath, prepared.baseCommit])
+    await tower.ensureExcluded(prepared.wtPath)
+    const worktree = worktreeRecord({
+      path: prepared.wtPath,
+      branch: prepared.branch,
+      baseCommit: prepared.baseCommit,
+      createdAt: Date.now(),
+      realPath: await canonicalPath(prepared.wtPath),
+    })
+    return { phase: 'created', worktree }
+  })
+}
+
+/** Phase 3 of `Tower.provision` (#51): record the worktree under a short lock. */
+async function commitProvision(tower, prepared, acted) {
+  return withLock(tower.paths, async () => {
+    const state = await tower.load()
+    const mission = state.missions.find((entry) => entry.id === prepared.missionId)
+    if (!mission) throw new TowerToolError('mission-not-found', `unknown mission "${prepared.missionId}"`)
+    // Revision revalidation: the plan was built from prepared.stateRevision.
+    if (state.revision !== prepared.stateRevision) return { phase: 'stale', revision: state.revision }
+    // Never overwrite a worktree another writer recorded while git ran.
+    if (mission.worktree) return { phase: 'existing', mission, worktree: mission.worktree }
+    const now = acted.worktree.createdAt
+    mission.worktree = acted.worktree
+    mission.baseCommit = prepared.baseCommit
+    mission.updatedAt = now
+    state.revision += 1
+    state.updatedAt = now
+    try {
+      validateState(state, tower.paths.state)
+      await writeJsonAtomic(tower.paths.state, state)
+    } catch (error) {
+      return { phase: 'persist-error', error }
+    }
+    await appendJsonl(tower.paths.activity, {
+      at: now,
+      type: 'worktree',
+      missionId: prepared.missionId,
+      text: provisionActivityText(prepared.branch, prepared.wtPath),
+    }).catch(() => {})
+    return { phase: 'committed', mission, worktree: acted.worktree }
+  })
+}
+
+/** Undo a created worktree/branch outside the state lock (git mutex only). */
+async function rollbackProvision(tower, prepared) {
+  await withGitLock(tower.paths, async () => {
+    await tower.git(tower.root, ['worktree', 'remove', '--force', prepared.wtPath]).catch(() => {})
+    await tower.git(tower.root, ['branch', '-D', prepared.branch]).catch(() => {})
+  })
+}
+
+/** #51 two-phase provision: prepare/act/commit with rollback on rejection. */
+export async function provision(tower, input = {}) {
+  const missionId = input.missionId
+  if (!hasMissionId(missionId)) {
+    fail('tower_spawn requires missionId in this version')
+  }
+  const prepared = await prepareProvision(tower, input)
+  if (prepared.early) return prepared.early
+
+  const acted = await actProvision(tower, prepared)
+  if (acted.phase === 'existing') return existingWorktreeResult(acted.mission, acted.worktree)
+  if (acted.phase === 'missing') fail(`unknown mission "${prepared.missionId}"`, 'mission-not-found')
+  if (acted.phase === 'stale') {
+    throw new TowerToolError(
+      'stale-base',
+      `tower state changed while the worktree was being prepared (${acted.detail}); no worktree was created — retry`,
+    )
+  }
+
+  let committed
+  try {
+    committed = await commitProvision(tower, prepared, acted)
+  } catch (error) {
+    // The worktree already exists. A commit that cannot even take the state
+    // lock must not leave the mission wedged with an unrecorded worktree.
+    await rollbackProvision(tower, prepared)
+    throw error
+  }
+  if (committed.phase === 'stale') {
+    await rollbackProvision(tower, prepared)
+    throw new TowerToolError(
+      'stale-base',
+      `tower state changed while the worktree was being created (${prepared.stateRevision} -> ${committed.revision}); the new worktree was rolled back — retry`,
+    )
+  }
+  if (committed.phase === 'existing') {
+    // Another writer recorded a worktree for this mission while git ran; the
+    // one created here is orphaned, so remove it and report the recorded one.
+    await rollbackProvision(tower, prepared)
+    await tower.assertWorktree(committed.worktree)
+    return existingWorktreeResult(committed.mission, committed.worktree)
+  }
+  if (committed.phase === 'persist-error') {
+    // Preserve the single-phase rollback: a failed state write must not leave
+    // an untracked worktree/branch behind.
+    await rollbackProvision(tower, prepared)
+    throw committed.error
+  }
+  return createdWorktreeResult(committed.mission, committed.worktree)
+}

package/app/read.js

@@ -0,0 +1,57 @@
+// Read-only dashboard/detail use cases.
+import { TowerToolError } from '../domain/errors.js'
+import { diffView, missionDetailView, statusView } from '../domain/read/views.js'
+import { readActivityTail } from '../lib/store.js'
+
+function fail(message, code = 'invalid-argument') {
+  throw new TowerToolError(code, message)
+}
+
+export async function missionDetail(tower, missionId) {
+  const state = await tower.load()
+  const mission = state.missions.find((entry) => entry.id === missionId)
+  if (!mission) fail(`unknown mission "${missionId}"`, 'mission-not-found')
+  const activity = await readActivityTail(tower.paths.activity, 200)
+  return missionDetailView({ state, mission, activity })
+}
+
+export async function status(tower, input = {}) {
+  const state = await tower.load()
+  const activity = await readActivityTail(tower.paths.activity, 12)
+  return statusView({
+    state,
+    statePath: tower.paths.state,
+    activity,
+    unreadTower: tower.unreadFor(state, 'tower').length,
+    config: tower.config,
+    missions: await tower.enrichedMissions(state, input.missionIds),
+  })
+}
+
+export async function diff(tower, input = {}) {
+  const state = await tower.load()
+  const mission = state.missions.find((entry) => entry.id === input.missionId)
+  if (!mission) fail(`unknown mission "${input.missionId}"`, 'mission-not-found')
+  if (!mission.worktree) fail(`mission ${mission.id} has no worktree to diff`)
+  await tower.assertWorktree(mission.worktree)
+  const baseTip = await tower.revParse(tower.root, state.base)
+  const branchTip = await tower.revParse(mission.worktree.path, 'HEAD')
+  const mergeBase = (await tower.git(mission.worktree.path, ['merge-base', baseTip, branchTip])).trim()
+  const files = (await tower.git(mission.worktree.path, ['diff', '--name-status', `${mergeBase}..${branchTip}`]))
+    .split('\n')
+    .filter(Boolean)
+  const commits = (await tower.git(mission.worktree.path, ['log', '--oneline', `${mergeBase}..${branchTip}`]))
+    .split('\n')
+    .filter(Boolean)
+  const fullPatch = await tower.git(mission.worktree.path, ['diff', `${mergeBase}..${branchTip}`])
+  return diffView({
+    mission,
+    baseTip,
+    branchTip,
+    mergeBase,
+    files,
+    commits,
+    fullPatch,
+    maxBytes: input.maxBytes,
+  })
+}

package/app/rebase.js

@@ -0,0 +1,302 @@
+// Rebase use case.
+//
+// #51 two-phase: long git work runs outside the state lock.
+//   prepare (lock-free reads) -> intent (short state lock) -> act (git lock)
+//   -> commit (short state lock with revision revalidation).
+// The durable `state.rebaseIntent` lets a crash between act and commit be
+// reconciled by the next tower_rebase, and `mission.rebase` keeps the
+// reviewed-tip waiver semantics the merge gate depends on.
+import crypto from 'node:crypto'
+import { withLock, withGitLock, writeJsonAtomic, appendJsonl } from '../lib/store.js'
+import { validateState } from '../domain/state.js'
+import { TowerToolError } from '../domain/errors.js'
+import { liveAgentFor } from '../domain/integration/liveness.js'
+import {
+  alreadyMergedRebaseResult,
+  alreadyUpToDateResult,
+  ambiguousRebaseIntentMessage,
+  buildRebaseIntent,
+  classifyRebaseIntent,
+  clearedRebaseIntentActivityText,
+  dirtyWorktreeResult,
+  malformedRebaseIntent,
+  rebaseActivityText,
+  rebaseConflictNote,
+  rebaseConflictResult,
+  rebaseReconcileActivityText,
+  rebaseReconcileNote,
+  rebaseSuccessNote,
+  rebaseSuccessResult,
+  rebaseTipsMoved,
+  rebaseTipsMovedDetail,
+  STALE_ACT,
+  STALE_PREPARE,
+  workerBusyResult,
+} from '../domain/integration/rebase.js'
+
+const RECONCILE_ATTEMPTS = 5
+
+function fail(message, code = 'invalid-transition') {
+  throw new TowerToolError(code, message)
+}
+
+function stale(message) {
+  return new TowerToolError('stale-base', message)
+}
+
+function findMission(state, missionId) {
+  return state.missions.find((entry) => entry.id === missionId)
+}
+
+/**
+ * Phase 1 (#51): every read needed to decide the rebase — roster liveness,
+ * worktree ownership, cleanliness, and both tips — happens without any lock.
+ * Returns the snapshot the intent and the commit revalidate against.
+ */
+async function prepareRebase(tower, input) {
+  const state = await tower.load()
+  const mission = findMission(state, input.missionId)
+  if (!mission) fail(`unknown mission "${input.missionId}"`)
+  if (!mission.worktree) fail(`mission ${mission.id} has no worktree to rebase`)
+  const activity = input.activity ?? {}
+  const busy = liveAgentFor(state, mission.id, activity)
+  if (busy) {
+    return { early: workerBusyResult(busy) }
+  }
+  await tower.assertWorktree(mission.worktree)
+  if (!(await tower.isClean(mission.worktree.path))) {
+    return { early: dirtyWorktreeResult(mission.worktree.path) }
+  }
+  const oldTip = await tower.revParse(mission.worktree.path, 'HEAD')
+  const baseTip = await tower.revParse(tower.root, state.base)
+  if (await tower.isAncestor(tower.root, oldTip, baseTip)) {
+    // The branch is already contained in the base (manual merge, crashed
+    // merge, earlier fast-forward). Rewriting the branch tip to the base
+    // would destroy the reviewed tip and the ability to record the merge.
+    return { early: alreadyMergedRebaseResult({ oldTip, baseTip, base: state.base }) }
+  }
+  if (await tower.isAncestor(tower.root, baseTip, oldTip)) {
+    return { early: alreadyUpToDateResult({ oldTip, baseTip }) }
+  }
+  // Count the commits a successful rebase will replay. The count is recorded
+  // with the intent so reconciliation can prove a crashed rebase finished
+  // instead of guessing from a moved tip.
+  let commits = null
+  try {
+    const count = Number.parseInt(String(await tower.git(mission.worktree.path, ['rev-list', '--count', `${baseTip}..${oldTip}`])).trim(), 10)
+    commits = Number.isInteger(count) ? count : null
+  } catch {
+    commits = null
+  }
+  return {
+    stateRevision: state.revision,
+    missionId: mission.id,
+    worktree: { path: mission.worktree.path, branch: mission.worktree.branch },
+    base: state.base,
+    oldTip,
+    baseTip,
+    commits,
+    early: null,
+  }
+}
+
+/** Inspect a durable intent with lock-free git reads. Never mutates. */
+async function inspectRebaseIntent(tower, state, intent) {
+  const mission = findMission(state, intent.missionId)
+  const worktreePath =
+    mission && mission.worktree && typeof mission.worktree.path === 'string' ? mission.worktree.path : null
+  if (!worktreePath) {
+    return classifyRebaseIntent({ intent, mission, tipReadable: false, baseIsAncestor: false })
+  }
+  let tip
+  try {
+    tip = await tower.revParse(worktreePath, 'HEAD')
+  } catch {
+    return classifyRebaseIntent({ intent, mission, tipReadable: false, baseIsAncestor: false })
+  }
+  if (tip === intent.oldTip) {
+    return classifyRebaseIntent({ intent, mission, tip, tipReadable: true, baseIsAncestor: true })
+  }
+  if (!(await tower.isAncestor(tower.root, intent.baseTip, tip))) {
+    return classifyRebaseIntent({ intent, mission, tip, tipReadable: true, baseIsAncestor: false })
+  }
+  let actualCommits = null
+  if (intent.commits !== null && intent.commits !== undefined) {
+    try {
+      const raw = await tower.git(worktreePath, ['rev-list', '--count', `${intent.baseTip}..${tip}`])
+      actualCommits = Number.parseInt(String(raw).trim(), 10)
+    } catch {
+      actualCommits = null
+    }
+  }
+  return classifyRebaseIntent({ intent, mission, tip, tipReadable: true, baseIsAncestor: true, actualCommits })
+}
+
+/**
+ * Reconcile a rebase intent left behind by a crash between act and commit.
+ * The two unambiguous outcomes (the branch never moved, or the rebase landed
+ * with the expected commit count) are committed; anything else keeps the
+ * marker and refuses rather than guessing.
+ */
+async function reconcileRebaseIntent(tower) {
+  for (let attempt = 0; attempt < RECONCILE_ATTEMPTS; attempt += 1) {
+    const snapshot = await tower.load()
+    const intent = snapshot.rebaseIntent
+    if (!intent) return
+    if (malformedRebaseIntent(intent)) {
+      throw stale('a rebase intent in tower state is malformed; inspect it and retry')
+    }
+    const inspection = await inspectRebaseIntent(tower, snapshot, intent)
+    if (inspection.action === 'ambiguous') {
+      throw stale(ambiguousRebaseIntentMessage(intent, inspection.tip))
+    }
+    const applied = await withLock(tower.paths, async () => {
+      const state = await tower.load()
+      if (state.revision !== snapshot.revision) return false
+      const current = state.rebaseIntent
+      if (!current || current.token !== intent.token) return true
+      const now = Date.now()
+      const mission = findMission(state, intent.missionId)
+      delete state.rebaseIntent
+      state.revision += 1
+      state.updatedAt = now
+      if (inspection.action === 'record' && mission) {
+        const tip = /** @type {string} */ (inspection.tip)
+        mission.rebase = { at: now, oldTip: intent.oldTip, newTip: tip, baseTip: intent.baseTip }
+        if (mission.status === 'blocked') mission.status = 'active'
+        mission.notes.push(rebaseReconcileNote({ oldTip: intent.oldTip, newTip: tip, baseTip: intent.baseTip }))
+        mission.updatedAt = now
+      }
+      validateState(state, tower.paths.state)
+      await writeJsonAtomic(tower.paths.state, state)
+      await appendJsonl(tower.paths.activity, {
+        at: now,
+        type: 'rebase',
+        missionId: intent.missionId,
+        text:
+          inspection.action === 'record'
+            ? rebaseReconcileActivityText({
+                oldTip: intent.oldTip,
+                newTip: /** @type {string} */ (inspection.tip),
+                baseTip: intent.baseTip,
+              })
+            : clearedRebaseIntentActivityText(inspection.reason),
+      })
+      return true
+    })
+    if (applied) return
+  }
+  throw stale('tower state kept changing while reconciling a pending rebase intent; retry')
+}
+
+export async function rebase(tower, input) {
+  await reconcileRebaseIntent(tower)
+  const prepared = await prepareRebase(tower, input)
+  if (prepared.early) return prepared.early
+  const worktree = /** @type {{ path: string, branch: string }} */ (prepared.worktree)
+
+  // Record the intent before touching Git: a crash between the rebase and the
+  // commit leaves a durable marker instead of an unexplained moved branch.
+  const token = crypto.randomUUID()
+  const startedAt = Date.now()
+  const intentRevision = await withLock(tower.paths, async () => {
+    const state = await tower.load()
+    if (state.revision !== prepared.stateRevision) throw stale(STALE_PREPARE)
+    const mission = findMission(state, prepared.missionId)
+    if (!mission) throw new TowerToolError('mission-not-found', `unknown mission "${prepared.missionId}"`)
+    if (!mission.worktree) fail(`mission ${mission.id} has no worktree to rebase`)
+    state.rebaseIntent = buildRebaseIntent({
+      token,
+      missionId: mission.id,
+      base: prepared.base,
+      oldTip: prepared.oldTip,
+      baseTip: prepared.baseTip,
+      commits: prepared.commits ?? null,
+      startedAt,
+    })
+    state.revision += 1
+    state.updatedAt = startedAt
+    await writeJsonAtomic(tower.paths.state, state)
+    return state.revision
+  })
+
+  // Phase 2 (#51): the long git work runs under the git lock and never under
+  // the state lock. Re-verify the snapshot right before rewriting the branch.
+  const outcome = await withGitLock(tower.paths, async () => {
+    const currentTip = await tower.revParse(worktree.path, 'HEAD')
+    const currentBase = await tower.revParse(tower.root, prepared.base)
+    if (rebaseTipsMoved({ oldTip: prepared.oldTip, baseTip: prepared.baseTip, currentTip, currentBase })) {
+      return {
+        phase: 'stale',
+        detail: rebaseTipsMovedDetail({
+          oldTip: prepared.oldTip,
+          baseTip: prepared.baseTip,
+          currentTip,
+          currentBase,
+        }),
+      }
+    }
+    try {
+      await tower.git(worktree.path, ['rebase', prepared.baseTip])
+    } catch (error) {
+      await tower.git(worktree.path, ['rebase', '--abort']).catch(() => {})
+      return { phase: 'conflict', detail: String(error?.message ?? error) }
+    }
+    const newTip = await tower.revParse(worktree.path, 'HEAD')
+    return { phase: 'done', newTip }
+  })
+
+  // Phase 3 (#51): re-read state and revalidate the revision computed by the
+  // intent write; the lock only holds the state mutation, never a subprocess.
+  return withLock(tower.paths, async () => {
+    const state = await tower.load()
+    if (state.revision !== intentRevision) throw stale(STALE_ACT)
+    const mission = findMission(state, prepared.missionId)
+    if (!mission) throw new TowerToolError('mission-not-found', `unknown mission "${prepared.missionId}"`)
+    const intent = state.rebaseIntent
+    if (!intent || intent.token !== token) throw stale(STALE_ACT)
+    const now = Date.now()
+
+    if (outcome.phase === 'stale') {
+      delete state.rebaseIntent
+      state.revision += 1
+      state.updatedAt = now
+      validateState(state, tower.paths.state)
+      await writeJsonAtomic(tower.paths.state, state)
+      throw stale(outcome.detail)
+    }
+
+    if (outcome.phase === 'conflict') {
+      delete state.rebaseIntent
+      mission.status = 'blocked'
+      mission.blockers.push(rebaseConflictNote(prepared.base, prepared.baseTip))
+      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: 'rebase', missionId: mission.id, text: 'conflict' })
+      return rebaseConflictResult(outcome.detail)
+    }
+
+    const { newTip } = outcome
+    delete state.rebaseIntent
+    mission.rebase = { at: now, oldTip: prepared.oldTip, newTip, baseTip: prepared.baseTip }
+    if (mission.status === 'blocked') mission.status = 'active'
+    mission.notes.push(
+      rebaseSuccessNote({ oldTip: prepared.oldTip, newTip, baseTip: prepared.baseTip }),
+    )
+    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: 'rebase',
+      missionId: mission.id,
+      text: rebaseActivityText({ oldTip: prepared.oldTip, newTip, baseTip: prepared.baseTip }),
+    })
+    return rebaseSuccessResult({ oldTip: prepared.oldTip, newTip, baseTip: prepared.baseTip })
+  })
+}

package/app/recording.js

@@ -0,0 +1,72 @@
+// State recording use cases for test receipts and imported legacy snapshots.
+import { TowerToolError } from '../domain/errors.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)
+}
+
+export async function recordTestRun(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 (!mission.testRuns) mission.testRuns = []
+    const rawReceipt = { ...input.receipt, recordedAt: Date.now() }
+    // Keep state bounded even when a repository reports a huge suite.
+    const tests = Array.isArray(rawReceipt.tests) ? rawReceipt.tests : []
+    const receipt = tests.length > 100
+      ? { ...rawReceipt, tests: tests.slice(0, 100), testsTotal: rawReceipt.count ?? tests.length, testsTruncated: true }
+      : rawReceipt
+    mission.testRuns.push(receipt)
+    if (mission.testRuns.length > 50) mission.testRuns = mission.testRuns.slice(-50)
+    const MAX_RUNS_BYTES = 512 * 1024
+    while (mission.testRuns.length > 1 && Buffer.byteLength(JSON.stringify(mission.testRuns), 'utf8') > MAX_RUNS_BYTES) {
+      mission.testRuns.shift()
+    }
+    state.revision += 1
+    state.updatedAt = Date.now()
+    validateState(state, tower.paths.state)
+    await writeJsonAtomic(tower.paths.state, state)
+    await appendJsonl(tower.paths.activity, {
+      at: Date.now(),
+      type: 'test',
+      missionId: mission.id,
+      text: receipt.ok === true ? `passed ${receipt.tests?.length ?? 0} test(s)` : `failed: ${String(receipt.error ?? 'unknown').slice(0, 200)}`,
+    })
+    return receipt
+  })
+}
+
+export async function recordLegacySnapshot(tower, snapshot) {
+  return withLock(tower.paths, async () => {
+    const state = await tower.load()
+    if (!Array.isArray(state.legacySnapshots)) state.legacySnapshots = []
+    const existing = state.legacySnapshots.find((entry) => entry.sourceHash === snapshot.sourceHash)
+    if (existing) return { snapshot: existing, duplicate: true }
+    state.legacySnapshots.push(snapshot)
+    state.revision += 1
+    state.updatedAt = Date.now()
+    validateState(state, tower.paths.state)
+    await writeJsonAtomic(tower.paths.state, state)
+    return { snapshot, duplicate: false }
+  })
+}
+
+export async function recordLegacyMap(tower, map) {
+  return withLock(tower.paths, async () => {
+    const state = await tower.load()
+    if (!Array.isArray(state.legacyMaps)) state.legacyMaps = []
+    const existing = state.legacyMaps.find(
+      (entry) => entry.sourceHash === map.sourceHash && entry.oldId === map.oldId,
+    )
+    if (existing) return { map: existing, duplicate: true }
+    state.legacyMaps.push(map)
+    state.revision += 1
+    state.updatedAt = Date.now()
+    validateState(state, tower.paths.state)
+    await writeJsonAtomic(tower.paths.state, state)
+    return { map, duplicate: false }
+  })
+}