@defrex/autobuild 0.8.0

package/packages/core/src/cli/dashboard/model.ts

@@ -0,0 +1,1173 @@
+/**
+ * The dashboard's pure projection: `BuildState` → what the operator sees.
+ *
+ * DISPLAY-ONLY — nothing consults this. The engine decides transitions from
+ * `decideNext` (§2.1's determinism half); a progress row is not a transition
+ * table and must never become one.
+ *
+ * But display-only is NOT a licence to disagree with the engine. The display
+ * IS the deliverable: a row that says `verify:lint [x]` for code the engine is
+ * about to re-verify is a wrong answer, not a cosmetic one. So every row obeys
+ * one rule:
+ *
+ *   >>> A step is `done` iff the engine will not re-run it. <<<
+ *
+ * Which means every `done` predicate is expressed against a fact the engine
+ * ALSO routes on — a seq or a round — never a full-log "latest wins" boolean.
+ * `plan.approved`, `codeReviewApproved` and `prState !== undefined` all look
+ * like the right answer and all lie across a restart, because `spec.revised`
+ * never touches them.
+ *
+ * `provisional` is a separate, display-only fact: this occurrence produced a
+ * terminal output in the current round/cycle, but the engine may still re-run
+ * it. It never participates in routing and never changes the `done` rule. The
+ * rules this file mirrors, and the code that owns them:
+ *
+ *   engine.ts:275     the verify cycle boundary (§15.6-A)
+ *   engine.ts:347-355 a verify failure reopens the CODE loop
+ *   engine.ts:466     a spec restart re-runs both loops (§6.3)
+ *   engine.ts:707-708 a spec restart re-runs finalize and its post-steps
+ *   engine.ts:221-227 an unlanded revise-spec answer parks the whole pipeline
+ *
+ * Display-only inferences live here rather than in the kernel when the spec
+ * asks for pixels without changing lifecycle semantics: build effective status
+ * (blocked overrides paused), the pending-restart boundary, and harvest-row
+ * attention visibility. All derive from retained facts; neither reducer nor
+ * engine is touched.
+ */
+import type { AbEvent } from '../../events/catalog'
+import type { RepositoryEvent } from '../../events/repository'
+import type { Config } from '../../config/schema'
+import type { BuildState, PhaseContext, PrLifecycle } from '../../kernel/reducer'
+import { currentAutoMergeDeferral } from '../../kernel/auto-merge'
+import { decideNext } from '../../kernel/engine'
+import { verifyPhase } from '../../ontology'
+import type { BuildRecord, StreamRecord } from '../../store/types'
+import { reduceDispatchSettings } from '../../kernel/dispatch-settings'
+import { projectSessions, type DashboardSession } from './detail'
+import type { TranscriptPresentation } from './transcript'
+import type { UIMessage } from 'ai'
+import type { StreamOutcome, StreamPart } from '../../store/streams/types'
+export { dashboardBuildControl } from './actions'
+export type { DashboardBuildControl } from './actions'
+import {
+  DEFAULT_MAX_HARVEST_RECOVERY_ATTEMPTS,
+  openHarvestRun,
+  reduceHarvest,
+  type HarvestRunState,
+  type HarvestState,
+} from '../../kernel/harvest'
+
+/** Every capacity-bearing build plus acknowledged abort cleanup is listed.
+ * `aborting` and `cleaning` are display-only projections over durable abort
+ * facts; neither extends the reducer's lifecycle vocabulary. */
+export type EffectiveStatus =
+  | 'queued'
+  | 'running'
+  | 'pausing'
+  | 'paused'
+  | 'resuming'
+  | 'blocked'
+  | 'aborting'
+  | 'cleaning'
+
+export type StepState = 'done' | 'current' | 'provisional' | 'pending'
+
+/** Human intent versus correlated forge application, rendered non-color-only. */
+export type AutoMergeDisplay = 'off' | 'requested' | 'enabled' | 'cancelling'
+
+/**
+ * A step's wall-clock timing, now-INDEPENDENT so the model can be cached and
+ * repainted against a moving clock (the elapsed ticks in the renderer, not
+ * here). `accumulatedMs` is the cumulative duration of every CLOSED occurrence
+ * in scope; `runningSince` is the start epoch-ms of an open occurrence — the
+ * renderer adds `now - runningSince` on top of `accumulatedMs`. A frozen build
+ * (paused/blocked) has its open occurrence closed into `accumulatedMs`, so
+ * `runningSince` is absent and its timer never advances (AC 10).
+ */
+export interface StepTiming {
+  accumulatedMs: number
+  runningSince?: number
+}
+
+export interface PipelineStep {
+  label: string
+  state: StepState
+  /** Display-only and never consulted for routing. `failed` or `skipped` on
+   * a verify/finalize step preserves its outcome alongside lifecycle `state`;
+   * `waiting` annotates merge. Rendered inside the `(…)` note, so outcome
+   * distinctions never rely on color alone. */
+  qualifier?: 'failed' | 'skipped' | 'waiting'
+  /** Round (plan/implement loops) or attempt (verify/reconcile). Rendered as
+   * `/n` riding the elapsed time when > 1 — supersedes the old `r2`/`a2`. */
+  count?: number
+  /** Absent ⇒ the step has never run in the current spec scope ⇒ no time is
+   * shown (AC 6). The renderer composes the elapsed segment from this. */
+  timing?: StepTiming
+}
+
+export type DashboardSelection =
+  | { kind: 'global' }
+  | { kind: 'harvest' }
+  | { kind: 'build'; slug: string }
+
+export type HarvestRunAction = 'resume' | 'acknowledge'
+
+export interface DashboardHarvest {
+  kind: 'harvest'
+  /** A row always represents this concrete run; the repository gate lives in
+   * the header even when no run exists. */
+  run: string
+  status: 'running' | 'paused' | 'escalated' | 'failed'
+  steps: PipelineStep[]
+  observations: number
+  rounds: number
+  detail?: string
+  /** Display-only action currently safe for `p`. Absent for running rows,
+   * acknowledged pauses, and while a resume request awaits the kernel. */
+  action?: HarvestRunAction
+}
+
+export interface DashboardBuild {
+  slug: string
+  status: EffectiveStatus
+  /** True when the build is BOTH paused and blocked: blocked wins the status
+   * (the spec's visual override), and this keeps the pause visible so no
+   * information is lost. */
+  alsoPaused: boolean
+  ticketId?: string
+  steps: PipelineStep[]
+  /** Queued-only explanation of the dispatcher boundary currently pending. */
+  dispatch?: string
+  /** Abort-stage explanation. Present instead of pipeline progress so the two
+   * destructive-action stages remain explicit without manufacturing work. */
+  abortProgress?: string
+  /** Current durable setup error, attributed to this build and retained until
+   * a later successful attachment proves recovery. */
+  setupError?: string
+  /** Every unresolved blocker's question. Resolved ones drop out by
+   * construction — the reducer moves them to answeredEscalations. */
+  blockers: string[]
+  /** Current-spec per-loop review budget overrides. */
+  reviewRoundCeilings?: { plan?: number; code?: number }
+  /** Native auto-merge desired/applied state. */
+  autoMerge: AutoMergeDisplay
+  pr?: { url: string; state: PrLifecycle }
+  /** Chronological session history projected from the retained raw log. */
+  sessions?: DashboardSession[]
+}
+
+export type DashboardView =
+  | {
+      kind: 'detail'
+      slug: string
+      /** Process-local offset into the fully wrapped detail body. */
+      scroll: number
+      sessionId?: string
+      /** Retained display content. Raising it is a one-shot controller reveal;
+       * its continued presence never implies a standing follow mode. */
+      message?: string
+      /** Message validity fence for facts that can change on the next poll. */
+      messageWhileSessionOpen?: string
+    }
+  | {
+      kind: 'transcript'
+      slug: string
+      sessionId: string
+      transcript: TranscriptPresentation
+      scroll: number
+    }
+  | {
+      /** The read-only live/closed stream view. Pure display state: the feed
+       * only appends freshly read chunks to the accumulated array, and stored
+       * parts are never altered. */
+      kind: 'session'
+      slug: string
+      sessionId: string
+      stream: string
+      status: 'open' | 'closed'
+      outcome?: StreamOutcome
+      /** The content source: the accumulated part sequence while chunks are
+       * readable, or the finalized `UIMessage[]` document once chunks are
+       * pruned (or the closed session never had a chunk log). */
+      source:
+        | { kind: 'parts'; parts: StreamPart[]; lastSeq: number }
+        | { kind: 'document'; document: UIMessage[] }
+      /** The last failed read's message, shown in place of content until a
+       * retry succeeds. */
+      error?: string
+      /** Tail-follow mode. True while the operator keeps the viewport at the
+       * bottom; Up away from the bottom pauses it, back to the bottom
+       * resumes. While true the render pins `scroll` to the limit. */
+      follow: boolean
+      scroll: number
+    }
+
+export type SessionDashboardView = Extract<DashboardView, { kind: 'session' }>
+
+export interface ResumeInputView {
+  /** The prompt stays bound to this build even while polling re-sorts rows. */
+  slug: string
+  /** Full operator input, line structure included. Rendering may scroll it,
+   * submission never truncates it. */
+  value: string
+  /** Caret position as a UTF-16 grapheme-boundary offset into `value` — the
+   * composer's one string coordinate the controller owns. */
+  cursor: number
+}
+
+export interface AbortConfirmationView {
+  /** Captured build identity; confirmation never retargets after re-sorting. */
+  slug: string
+}
+export interface DashboardCounter {
+  current: number
+  limit: number
+}
+
+export interface DashboardModel {
+  repo: string
+  /** Ready tickets waiting for a slot — the dispatcher's standing queue depth. */
+  queued: number
+  /** Every nonterminal build consumes one configured dispatch capacity slot. */
+  active: DashboardCounter
+  /** Recorded observation occurrences not claimed by a Harvest snapshot,
+   * against the configured count-pressure trigger. */
+  observations: DashboardCounter
+  /** Durable repository intake state (`true` means claims are disabled). */
+  drained: boolean
+  /** Durable repository-wide hold (`true` means queued builds cannot launch). */
+  repositoryPaused: boolean
+  /** Durable repository claim-time default for newly claimed builds. */
+  defaultAutoMerge: boolean
+  /** Durable repository gate reduced from acknowledged journal facts. Pending
+   * commands deliberately do not change this field optimistically. */
+  harvestPaused: boolean
+  /** Stable row identity, never a row index. */
+  selection?: DashboardSelection
+  /** Release courtesy, separate from transient and startup warnings so those
+   * notices can never overwrite one another. Store-only frontends project it
+   * from their correlated dispatcher run. */
+  availableUpgrade?: string
+  /** Process-local warnings/errors, in render order. Routine dispatcher
+   * notices never enter the interactive model; absence (or an empty array)
+   * means the warning chrome is omitted. */
+  warningLines?: readonly string[]
+  /** Ephemeral blocked-resume field; never derived from or stored in events. */
+  resumeInput?: ResumeInputView
+  /** Ephemeral destructive-action confirmation; the first `a` writes nothing. */
+  abortConfirmation?: AbortConfirmationView
+  /** Nested read-only dashboard mode. Omission is the byte-stable list view. */
+  view?: DashboardView
+  builds: DashboardBuild[]
+  /** Present only for an open run or unresolved run-level attention. It is
+   * selectable display state, never a synthetic build. */
+  harvest?: DashboardHarvest
+}
+
+/**
+ * §15.5 sets the reducer's precedence to paused > blocked and documents why:
+ * pausing is the operator's explicit instruction, and the escalation is not
+ * lost — it stays in `openEscalations`, so resuming reports blocked again. The
+ * spec asks for the opposite VISUALLY ("a build with unresolved blockers is
+ * treated as blocked even when it is also manually paused"). Both hold at once
+ * because the reducer retains both facts: the display overrides, the lifecycle
+ * does not. A paused+blocked build still parks on `paused` in `decideNext`,
+ * exactly as today.
+ */
+export function effectiveStatus(state: BuildState): EffectiveStatus | BuildState['status'] {
+  // Terminal outcomes outrank every pending command and visual override. An
+  // acknowledged abort remains in its cleanup display stage, while `done`
+  // stays filterable as terminal. Only nonterminal abort intent projects as
+  // `aborting`; blocked and pause/resume overrides follow it.
+  if (state.status === 'done') return 'done'
+  if (state.status === 'aborted') return 'cleaning'
+  if (state.pendingCommands.some((command) => command.command === 'abort')) return 'aborting'
+  if (
+    (state.status === 'paused' || state.status === 'blocked') &&
+    state.openEscalations.length > 0
+  ) {
+    return 'blocked'
+  }
+  if (state.status === 'running') {
+    return state.pendingCommands.some((command) => command.command === 'pause')
+      ? 'pausing'
+      : 'running'
+  }
+  if (state.status === 'paused') {
+    return state.pendingCommands.some((command) => command.command === 'resume')
+      ? 'resuming'
+      : 'paused'
+  }
+  return state.status
+}
+
+function isVisible(status: EffectiveStatus | BuildState['status']): status is EffectiveStatus {
+  return (
+    status === 'queued' ||
+    status === 'running' ||
+    status === 'pausing' ||
+    status === 'paused' ||
+    status === 'resuming' ||
+    status === 'blocked' ||
+    status === 'aborting' ||
+    status === 'cleaning'
+  )
+}
+
+export function autoMergeDisplay(state: BuildState): AutoMergeDisplay {
+  const { requested, commandSeq, applied } = state.autoMerge
+  if (requested) {
+    return applied?.enabled === true && applied.commandSeq === commandSeq ? 'enabled' : 'requested'
+  }
+  if (commandSeq === undefined) return 'off'
+  if (applied?.enabled === false && applied.commandSeq === commandSeq) return 'off'
+  // Before a PR exists, cancellation clears the durable desired flag and there
+  // is no remote state to wait on. Once a PR (or prior enabled fact) exists,
+  // keep the pending disable visible until its correlated fact lands.
+  if (state.pr === undefined && applied?.enabled !== true) return 'off'
+  return 'cancelling'
+}
+
+/**
+ * One step, built through one helper so the precedence rule cannot be applied
+ * inconsistently: **`current > done > provisional > pending`**. In particular,
+ * an active occurrence stays current even when an earlier terminal output for
+ * that same occurrence exists. `producedOutput` is display-only and means a
+ * terminal event exists in the current round/cycle — never merely a start or
+ * an open timing interval.
+ */
+interface StepExtra {
+  producedOutput?: boolean
+  qualifier?: 'failed' | 'skipped' | 'waiting'
+  count?: number
+  timing?: StepTiming
+}
+
+function step(label: string, done: boolean, current: boolean, extra: StepExtra = {}): PipelineStep {
+  return {
+    label,
+    state: current
+      ? 'current'
+      : done
+        ? 'done'
+        : extra.producedOutput === true
+          ? 'provisional'
+          : 'pending',
+    ...(extra.qualifier !== undefined ? { qualifier: extra.qualifier } : {}),
+    ...(extra.count !== undefined ? { count: extra.count } : {}),
+    ...(extra.timing !== undefined ? { timing: extra.timing } : {}),
+  }
+}
+
+/** One phase occurrence's wall-clock span, keyed by phase. `startSeq` is the
+ * seq of the `*.started` event, so callers can scope by the same seq
+ * boundaries (`restartSince`/`cycleSince`) the step STATES already use. */
+interface PhaseInterval {
+  start: number
+  end: number
+  startSeq: number
+}
+interface PhaseTiming {
+  closed: PhaseInterval[]
+  open?: { start: number; startSeq: number }
+}
+
+/**
+ * Walk the raw event log into per-phase `[start, end]` intervals in epoch-ms
+ * (`Date.parse(ev.ts)`), the durations the reducer collapses away. Each
+ * `*.started` opens an interval for its phase key and its terminal event
+ * (`.completed`/`.verdict`) closes it. A second `*.started` while one is still
+ * open REPLACES the open start — a §15.6-C cross-sandbox re-run starts the
+ * phase afresh, so the crashed attempt contributes nothing. Finalize post-steps
+ * (`finalize.step-completed`) have no `.started` and so no interval.
+ */
+function phaseIntervals(events: AbEvent[]): Map<string, PhaseTiming> {
+  const timings = new Map<string, PhaseTiming>()
+  const get = (key: string): PhaseTiming => {
+    let t = timings.get(key)
+    if (t === undefined) {
+      t = { closed: [] }
+      timings.set(key, t)
+    }
+    return t
+  }
+  for (const ev of events) {
+    const ms = Date.parse(ev.ts)
+    const open = (key: string): void => {
+      get(key).open = { start: ms, startSeq: ev.seq }
+    }
+    const close = (key: string): void => {
+      const t = get(key)
+      if (t.open === undefined) return
+      t.closed.push({ start: t.open.start, end: ms, startSeq: t.open.startSeq })
+      t.open = undefined
+    }
+    switch (ev.type) {
+      case 'plan.started':
+        open('plan')
+        break
+      case 'plan.completed':
+        close('plan')
+        break
+      case 'plan-review.started':
+        open('plan-review')
+        break
+      case 'plan-review.verdict':
+        close('plan-review')
+        break
+      case 'implement.started':
+        open('implement')
+        break
+      case 'implement.completed':
+        close('implement')
+        break
+      case 'code-review.started':
+        open('code-review')
+        break
+      case 'code-review.verdict':
+        close('code-review')
+        break
+      case 'verify.started':
+        open(verifyPhase(ev.payload.step))
+        break
+      case 'verify.completed':
+        close(verifyPhase(ev.payload.step))
+        break
+      case 'finalize.started':
+        open('finalize')
+        break
+      case 'finalize.completed':
+        close('finalize')
+        break
+      case 'reconcile.started':
+        open('reconcile')
+        break
+      case 'reconcile.completed':
+        close('reconcile')
+        break
+      default:
+        break
+    }
+  }
+  return timings
+}
+
+/**
+ * Sum the in-scope occurrences of one phase into a `StepTiming`, or `undefined`
+ * when the phase never ran in scope (the step shows no time, AC 6). Scope is
+ * `startSeq > sinceSeq` — the SAME boundary the step's `done`/`current` state
+ * uses, so durations restart in lockstep with states (AC 12). The open
+ * occurrence stays open (`runningSince`) only when the build is running; a
+ * frozen build (`frozenNow` given) closes it at that instant so its timer does
+ * not advance (AC 10).
+ */
+function timingFor(
+  intervals: Map<string, PhaseTiming>,
+  key: string,
+  sinceSeq: number,
+  frozenNow: number | undefined,
+): StepTiming | undefined {
+  const t = intervals.get(key)
+  if (t === undefined) return undefined
+  let accumulatedMs = 0
+  let inScope = false
+  for (const iv of t.closed) {
+    if (iv.startSeq > sinceSeq) {
+      accumulatedMs += iv.end - iv.start
+      inScope = true
+    }
+  }
+  let runningSince: number | undefined
+  if (t.open !== undefined && t.open.startSeq > sinceSeq) {
+    inScope = true
+    if (frozenNow !== undefined) accumulatedMs += Math.max(0, frozenNow - t.open.start)
+    else runningSince = t.open.start
+  }
+  if (!inScope) return undefined
+  return { accumulatedMs, ...(runningSince !== undefined ? { runningSince } : {}) }
+}
+
+/**
+ * `record` + `state` → one dashboard row, or `null` only for terminal builds.
+ */
+export function projectBuild(
+  record: BuildRecord,
+  state: BuildState,
+  config: Config,
+  events: AbEvent[],
+  streams?: readonly StreamRecord[],
+): DashboardBuild | null {
+  const status = effectiveStatus(state)
+  if (!isVisible(status)) return null
+  const abortProgress =
+    status === 'aborting'
+      ? state.status === 'queued'
+        ? 'abort requested; waiting for dispatcher acknowledgement'
+        : 'abort requested; waiting for running work to stop'
+      : status === 'cleaning'
+        ? 'running work stopped; abort cleanup pending or in progress'
+        : undefined
+
+  if (status === 'queued') {
+    const created = events.findLast((event) => event.type === 'build.created')
+    const workspace = events.findLast((event) => event.type === 'workspace.provisioned')
+    const released = events.findLast((event) => event.type === 'workspace.released')
+    const openWorkspace =
+      workspace !== undefined && (released === undefined || workspace.seq > released.seq)
+    const spec = events.findLast(
+      (event) => event.type === 'spec.imported' || event.type === 'spec.authored',
+    )
+    const commentPosted = events.findLast((event) => event.type === 'dispatch.comment-posted')
+    const latestFailure = events.findLast((event) => event.type === 'dispatch.failed')
+    const failureSuperseded =
+      latestFailure !== undefined &&
+      ((latestFailure.payload.stage === 'create' &&
+        created !== undefined &&
+        created.seq > latestFailure.seq) ||
+        (latestFailure.payload.stage === 'workspace' &&
+          workspace !== undefined &&
+          workspace.seq > latestFailure.seq) ||
+        (latestFailure.payload.stage === 'spec' &&
+          spec !== undefined &&
+          spec.seq > latestFailure.seq) ||
+        (latestFailure.payload.stage === 'comment' &&
+          commentPosted !== undefined &&
+          commentPosted.seq > latestFailure.seq))
+    const dispatch =
+      state.discardRequest !== undefined
+        ? 'discard requested; cleanup and Ready handback pending'
+        : latestFailure !== undefined && !failureSuperseded
+          ? `dispatch ${latestFailure.payload.stage} failed (attempt ${latestFailure.payload.attempt}): ${latestFailure.payload.error}`
+          : created === undefined
+            ? 'dispatch initialization pending'
+            : !openWorkspace
+              ? 'workspace provisioning pending'
+              : spec === undefined
+                ? 'spec import pending'
+                : 'runner attachment pending'
+    return {
+      slug: record.slug,
+      status,
+      alsoPaused: false,
+      ...(record.ticket?.id !== undefined ? { ticketId: record.ticket.id } : {}),
+      steps: [],
+      dispatch,
+      blockers: [],
+      autoMerge: autoMergeDisplay(state),
+      sessions: projectSessions(events, streams),
+    }
+  }
+
+  if (abortProgress !== undefined) {
+    return {
+      slug: record.slug,
+      status,
+      alsoPaused: false,
+      ...(record.ticket?.id !== undefined ? { ticketId: record.ticket.id } : {}),
+      steps: [],
+      abortProgress,
+      blockers: state.openEscalations.map((escalation) => escalation.question),
+      ...(state.reviewRoundCeilings.plan !== undefined ||
+      state.reviewRoundCeilings.code !== undefined
+        ? { reviewRoundCeilings: { ...state.reviewRoundCeilings } }
+        : {}),
+      autoMerge: autoMergeDisplay(state),
+      ...(state.pr !== undefined && state.prState !== undefined
+        ? { pr: { url: state.pr.url, state: state.prState } }
+        : {}),
+      sessions: projectSessions(events, streams),
+    }
+  }
+
+  // ── Boundaries ────────────────────────────────────────────────────────────
+  //
+  // A revise-spec answer whose `spec.revised` has not landed yet (§6.3,
+  // engine.ts:221-227): the engine is parked on `wait{awaiting-spec}` and will
+  // restart the build from plan the instant the revision arrives. This window
+  // is HUMAN-paced — the operator is off rewriting the spec — so it is exactly
+  // the durable state this dashboard exists to render, and rendering
+  // `finalize [x] merge [>] waiting` in it would be a wrong answer: every one
+  // of those steps is about to re-run. A pending restart therefore raises the
+  // boundary the same way the landed one will. (`decideNext` returns `wait`
+  // here, naming no phase, so the engine oracle in the tests is blind to this
+  // state — it is asserted by hand.)
+  const pendingRestart = state.answeredEscalations.some(
+    (e) => e.resolution === 'revise-spec' && e.answeredSeq > state.restartSince,
+  )
+  const restartSince = pendingRestart ? state.lastSeq : state.restartSince
+  const cycleSince = Math.max(state.verify.cycleSince, restartSince)
+  // Post-steps re-run after a restart too (engine.ts:710-712). Their reducer
+  // projection is full-log history, so the same effective boundary handles
+  // both a landed revision and the pending human-paced restart window.
+  const finalizeSteps = state.finalizeSteps.filter((completion) => completion.seq > restartSince)
+
+  /**
+   * The current phase, scoped to the current spec.
+   *
+   * `currentPhase` is latest-wins over the FULL log — the same shape as
+   * `plan.approved` and `prState`, and stale for the same reason. `start()`
+   * sets `currentPhase` and only that phase's OWN terminal event clears it
+   * (`reducer.ts`); `escalation.raised` deliberately does not
+   * (the phase still needs re-running), and `spec.revised` advances
+   * `restartSince` and `cycleSince` but does not clear these. So a phase that
+   * was in flight when a restart landed still reads as running.
+   *
+   * That is the plan's own defect class in the one predicate its rule never
+   * quantified over — `current`, not `done` — so it gets the same treatment:
+   * across a restart (landed OR pending) nothing is current until a new
+   * `*.started` lands. That is exactly what the engine does; it re-runs the
+   * loops from plan (engine.ts:466) rather than resuming the interrupted
+   * phase, and during a pending restart it runs nothing at all
+   * (engine.ts:221-227).
+   *
+   * `reconcile` is included deliberately. The epilogue is restart-orthogonal
+   * in the facts it routes on (engine.ts:161-162) — but rule 3 preempts it
+   * while a restart is pending, and once one lands the engine goes to plan and
+   * only re-reaches the epilogue after a full rebuild re-opens the PR. A
+   * pre-restart `reconcile.started` is not "reconcile is running now".
+   */
+  const scoped = (ctx: PhaseContext | undefined): PhaseContext | undefined =>
+    ctx !== undefined && ctx.seq > restartSince ? ctx : undefined
+  const activePhase = scoped(state.currentPhase)
+
+  // ── Timing ────────────────────────────────────────────────────────────────
+  // Per-occurrence durations from the raw log — the reducer collapses them
+  // away, so they are derived here (display-only, at the one call site that
+  // already has the log in hand). A running build keeps its open interval live
+  // (the renderer ticks it against `now`); a paused build freezes every open
+  // interval at its acknowledgement (including while RESUMING), while a
+  // blocked build freezes at the latest durable event. Timers therefore do not
+  // advance behind either gate (AC 10). Each step scopes by the SAME seq boundary its state uses, so
+  // durations and states restart in lockstep (AC 12).
+  const intervals = phaseIntervals(events)
+  const pausedAt =
+    state.status === 'paused'
+      ? events.findLast((event) => event.type === 'build.paused')?.ts
+      : undefined
+  const frozenNow =
+    state.status === 'running'
+      ? undefined
+      : pausedAt !== undefined
+        ? Date.parse(pausedAt)
+        : state.lastEvent !== undefined
+          ? Date.parse(state.lastEvent.ts)
+          : undefined
+
+  // ── Shared derivations ────────────────────────────────────────────────────
+  // ORDER MATTERS: `cycleFailed` must be defined before `codeDone` reads it.
+  const cycle = state.verify.results.filter((r) => r.seq > cycleSince)
+  const cycleFailed = cycle.some((r) => r.outcome === 'fail')
+  const verifyPassed = (s: string): boolean =>
+    cycle.some((r) => r.step === s && r.outcome === 'pass')
+  const verifySkipped = (s: string): boolean =>
+    cycle.some((r) => r.step === s && r.outcome === 'skipped')
+  const verifySatisfied = (s: string): boolean => verifyPassed(s) || verifySkipped(s)
+  const verifyDrained = !cycleFailed && config.verify.steps.every(verifySatisfied)
+
+  // A loop is settled only if its standing approval survived the last restart
+  // AND no later producer round reopened it. `approved` alone is a full-log
+  // boolean and lies in both cases.
+  const loopDone = (
+    approval: { seq: number; round: number } | undefined,
+    producerRound: number,
+  ): boolean =>
+    approval !== undefined && approval.seq > restartSince && approval.round === producerRound
+
+  const planDone = loopDone(state.plan.approval, state.plan.round)
+  // `&& !cycleFailed`: a verify failure reopens the CODE loop (§15.6-A) the
+  // MOMENT it lands — long before `implement.started` moves `implement.round`,
+  // and under default policy that start may never come (see below).
+  const codeDone = loopDone(state.codeReviewApproval, state.implement.round) && !cycleFailed
+
+  // A loop row is provisional only when ITS terminal output belongs to the
+  // reducer's currently tracked round and landed after the effective restart
+  // boundary. Starts and timing intervals are deliberately insufficient: a
+  // crashed phase has run, but has produced no output. Matching the round also
+  // drops a review verdict as soon as the next producer round starts.
+  const planProduced = events.some(
+    (ev) =>
+      ev.seq > restartSince &&
+      ev.type === 'plan.completed' &&
+      ev.payload.round === state.plan.round,
+  )
+  const planReviewProduced = events.some(
+    (ev) =>
+      ev.seq > restartSince &&
+      ev.type === 'plan-review.verdict' &&
+      ev.payload.round === state.plan.round,
+  )
+  const implementProduced = events.some(
+    (ev) =>
+      ev.seq > restartSince &&
+      ev.type === 'implement.completed' &&
+      ev.payload.round === state.implement.round,
+  )
+  const codeReviewProduced = events.some(
+    (ev) =>
+      ev.seq > restartSince &&
+      ev.type === 'code-review.verdict' &&
+      ev.payload.round === state.implement.round,
+  )
+
+  // Finalize ran for the CURRENT spec — NOT `prState !== undefined`, which a
+  // spec restart never resets while the engine re-runs finalize from scratch.
+  const finalizeDone = state.finalizeCompletedSeq > restartSince
+  const postStepsDrained = config.finalize.steps.every((s) =>
+    finalizeSteps.some((f) => f.step === s),
+  )
+
+  const at = (phase: string): boolean => activePhase?.phase === phase
+  // Retain first-round counts for detail rendering. The compact renderer still
+  // suppresses `/1`, preserving its existing density and output.
+  const planCount = state.plan.round > 0 ? state.plan.round : undefined
+  const codeCount = state.implement.round > 0 ? state.implement.round : undefined
+
+  const steps: PipelineStep[] = [
+    step('plan', planDone, at('plan'), {
+      producedOutput: planProduced,
+      count: planCount,
+      timing: timingFor(intervals, 'plan', restartSince, frozenNow),
+    }),
+    step('plan-review', planDone, at('plan-review'), {
+      producedOutput: planReviewProduced,
+      count: planCount,
+      timing: timingFor(intervals, 'plan-review', restartSince, frozenNow),
+    }),
+    step('implement', codeDone, at('implement'), {
+      producedOutput: implementProduced,
+      count: codeCount,
+      timing: timingFor(intervals, 'implement', restartSince, frozenNow),
+    }),
+    step('code-review', codeDone, at('code-review'), {
+      producedOutput: codeReviewProduced,
+      count: codeCount,
+      timing: timingFor(intervals, 'code-review', restartSince, frozenNow),
+    }),
+  ]
+
+  for (const s of config.verify.steps) {
+    const phase = verifyPhase(s)
+    const current = at(phase)
+    const stepResults = cycle.filter((r) => r.step === s)
+    // The attempt COUNT comes from `currentPhase.attempt` for the running step
+    // — the attempt ACTUALLY running (`verify.started` populates it directly),
+    // never `verify.maxAttemptSeen`, which is a full-log high-water and names
+    // the previous cycle in the window after a boundary move. A non-running
+    // step takes the max attempt among its results IN THE CURRENT CYCLE, so a
+    // past cycle's attempt can never leak. Rendered as `/n` only when > 1.
+    const maxAttempt =
+      current && activePhase?.attempt !== undefined
+        ? activePhase.attempt
+        : stepResults.length > 0
+          ? Math.max(...stepResults.map((r) => r.attempt))
+          : undefined
+    const count = maxAttempt
+    // `!cycleFailed &&`: §15.6-A re-runs the cycle FROM THE FIRST STEP, so
+    // once any step in the cycle has failed, an earlier step's pass in that
+    // same cycle is not durably done either. The failing step keeps a `failed`
+    // qualifier so the operator does not lose the information; completed rows
+    // are provisional because they produced output but will genuinely re-run.
+    steps.push(
+      step(phase, !cycleFailed && verifySatisfied(s), current, {
+        producedOutput: stepResults.length > 0,
+        qualifier: stepResults.some((r) => r.outcome === 'fail')
+          ? 'failed'
+          : stepResults.some((r) => r.outcome === 'skipped')
+            ? 'skipped'
+            : undefined,
+        count,
+        timing: timingFor(intervals, phase, cycleSince, frozenNow),
+      }),
+    )
+  }
+
+  steps.push(
+    step('finalize', finalizeDone, at('finalize'), {
+      timing: timingFor(intervals, 'finalize', restartSince, frozenNow),
+    }),
+  )
+  for (const s of config.finalize.steps) {
+    // Post-steps have no `.started` event, so they carry no timing.
+    const done = finalizeSteps.find((f) => f.step === s)
+    steps.push(
+      step(s, done !== undefined, false, { qualifier: done?.ok === false ? 'failed' : undefined }),
+    )
+  }
+
+  // Conditional (§15.7): the epilogue is not guaranteed future work, so the
+  // row appears only once a conflict activates it. `reconcileAttempts` is
+  // full-log — legitimately, per the rule above: the engine routes the
+  // epilogue on the same full-log values (engine.ts:402,:416), so a restart
+  // genuinely does not re-run reconcile and the display agrees.
+  if (state.prState === 'conflicted' || state.reconcileAttempts > 0) {
+    steps.push(
+      step(
+        'reconcile',
+        state.reconcileAttempts > 0 && state.prState !== 'conflicted',
+        at('reconcile'),
+        {
+          count: state.reconcileAttempts > 0 ? state.reconcileAttempts : undefined,
+          // Full-log scope (sinceSeq 0), matching reconcile's full-log
+          // done/current predicate: the epilogue is restart-orthogonal.
+          timing: timingFor(intervals, 'reconcile', 0, frozenNow),
+        },
+      ),
+    )
+  }
+
+  // Merge is never `done` for a LISTED build — a merged build is `done` and
+  // filtered out above. It is `current` exactly when the engine would return
+  // `wait{awaiting-pr}`: the PR is open and every piece of work behind it has
+  // drained. `prState === 'open'` alone is not enough — it is set at
+  // `finalize.completed` AND again at `reconcile.completed`, both with real
+  // work outstanding.
+  const mergeCurrent =
+    finalizeDone &&
+    state.prState === 'open' &&
+    verifyDrained &&
+    postStepsDrained &&
+    activePhase === undefined
+  // Merge-ready start = the log's last-event ts: once the build drains the
+  // engine parks on `wait{awaiting-pr}` and appends nothing, so `lastEvent.ts`
+  // is exactly when it became merge-ready, ticking like a running phase (AC 9).
+  // Frozen at that same ts when the build is not running.
+  const lastMs = state.lastEvent !== undefined ? Date.parse(state.lastEvent.ts) : 0
+  const mergeTiming: StepTiming | undefined = !mergeCurrent
+    ? undefined
+    : frozenNow !== undefined
+      ? { accumulatedMs: Math.max(0, frozenNow - lastMs) }
+      : { accumulatedMs: 0, runningSince: lastMs }
+  steps.push(step('merge', false, mergeCurrent, { qualifier: 'waiting', timing: mergeTiming }))
+
+  const setupError =
+    state.infrastructureFailure !== undefined
+      ? `${state.infrastructureFailure.provider} ${state.infrastructureFailure.operation} failed ` +
+        `(attempt ${state.infrastructureFailure.attempt}, ${state.infrastructureFailure.cause}${
+          state.infrastructureFailure.cleanupPending ? ', cleanup pending' : ''
+        }): ${state.infrastructureFailure.error}`
+      : state.setupFailure === undefined
+        ? undefined
+        : `[commands].setup ${JSON.stringify(state.setupFailure.command)} failed ` +
+          `(attempt ${state.setupFailure.attempt}, ${
+            state.setupFailure.exitStatus === null
+              ? 'exit status unavailable'
+              : `exit status ${state.setupFailure.exitStatus}`
+          }): ${state.setupFailure.output || '(no output)'}`
+
+  const decision = decideNext(events, config)
+  const mergeWaitReason =
+    decision.kind === 'wait' && decision.reason === 'awaiting-pr'
+      ? currentAutoMergeDeferral(events, state)
+      : undefined
+
+  return {
+    slug: record.slug,
+    status,
+    alsoPaused: state.status === 'paused' && status === 'blocked',
+    ...(record.ticket?.id !== undefined ? { ticketId: record.ticket.id } : {}),
+    steps,
+    ...(setupError !== undefined ? { setupError } : {}),
+    blockers: [
+      ...state.openEscalations.map((e) => e.question),
+      ...(mergeWaitReason !== undefined ? [mergeWaitReason] : []),
+    ],
+    ...(state.reviewRoundCeilings.plan !== undefined || state.reviewRoundCeilings.code !== undefined
+      ? { reviewRoundCeilings: { ...state.reviewRoundCeilings } }
+      : {}),
+    autoMerge: autoMergeDisplay(state),
+    ...(state.pr !== undefined && state.prState !== undefined
+      ? { pr: { url: state.pr.url, state: state.prState } }
+      : {}),
+    sessions: projectSessions(events, streams),
+  }
+}
+
+function harvestStepTiming(
+  occurrences: Array<{
+    step: string
+    startedAt: string
+    completedAt?: string
+  }>,
+  name: string,
+  frozenAt?: number,
+): StepTiming | undefined {
+  const matching = occurrences.filter((occurrence) => occurrence.step === name)
+  if (matching.length === 0) return undefined
+  let accumulatedMs = 0
+  let runningSince: number | undefined
+  for (const occurrence of matching) {
+    const start = Date.parse(occurrence.startedAt)
+    if (occurrence.completedAt !== undefined) {
+      accumulatedMs += Math.max(0, Date.parse(occurrence.completedAt) - start)
+    } else if (frozenAt !== undefined) {
+      accumulatedMs += Math.max(0, frozenAt - start)
+    } else {
+      runningSince = start
+    }
+  }
+  return {
+    accumulatedMs,
+    ...(runningSince !== undefined ? { runningSince } : {}),
+  }
+}
+
+/** A deliberate escalation has no dedicated acknowledgement event. For display
+ * only, pair a post-terminal human resume request with the later kernel resume
+ * that consumed it. A countermanding pause invalidates the pending request,
+ * matching the repository reducer's command semantics. */
+function escalationAttentionDismissed(events: RepositoryEvent[], terminalSeq: number): boolean {
+  let pendingHumanResume = false
+  for (const event of events) {
+    if (event.seq <= terminalSeq) continue
+    if (event.type === 'harvest.resume-requested' && event.actor.kind === 'human') {
+      pendingHumanResume = true
+      continue
+    }
+    if (event.type === 'harvest.pause-requested') {
+      pendingHumanResume = false
+      continue
+    }
+    if (event.type === 'harvest.resumed' && pendingHumanResume) return true
+  }
+  return false
+}
+
+function selectDashboardHarvestRun(
+  events: RepositoryEvent[],
+  state: HarvestState,
+): HarvestRunState | undefined {
+  const attention = state.runs.find((run) => {
+    if (run.status === 'failed') {
+      return run.recoveryExhaustion?.attentionAcknowledgedSeq === undefined
+    }
+    if (run.status !== 'escalated') return false
+    return run.terminalSeq === undefined || !escalationAttentionDismissed(events, run.terminalSeq)
+  })
+  return attention ?? openHarvestRun(state)
+}
+
+/** Project one deterministic concrete run. The oldest unresolved failed,
+ * exhausted, or escalated attention outranks merely open work; completed and
+ * acknowledged terminal history never hides an older actionable run. */
+function projectHarvestRun(
+  events: RepositoryEvent[],
+  state: HarvestState,
+): DashboardHarvest | undefined {
+  const run = selectDashboardHarvestRun(events, state)
+  if (run === undefined || run.status === 'completed') return undefined
+  const exhaustion = run.recoveryExhaustion
+
+  const occurrences = run.steps
+  const stopped = run.status !== 'running'
+  const current = (name: string): boolean => {
+    if (stopped || state.paused) return false
+    const latest = [...occurrences].reverse().find((occurrence) => occurrence.step === name)
+    return latest !== undefined && latest.completedSeq === undefined
+  }
+  const hasCompleted = (name: string): boolean =>
+    occurrences.some(
+      (occurrence) => occurrence.step === name && occurrence.completedSeq !== undefined,
+    )
+  const hasOutcome = (name: string, outcome: string): boolean =>
+    occurrences.some((occurrence) => occurrence.step === name && occurrence.outcome === outcome)
+  const failedAt = (name: string): boolean => run.status === 'failed' && run.failure?.step === name
+  const rounds = Math.max(
+    0,
+    ...run.proposals.map((proposal) => proposal.round),
+    ...run.reviews.map((review) => review.round),
+    ...occurrences.map((occurrence) => occurrence.round ?? 0),
+  )
+  const count = rounds > 1 ? rounds : undefined
+  const approved = run.reviews.some((review) => review.verdict === 'approve')
+  const synthOutput = run.proposals.length > 0
+  const reviewOutput = run.reviews.length > 0
+  const failedEvent =
+    run.status === 'failed'
+      ? [...events]
+          .reverse()
+          .find(
+            (event) =>
+              event.type === 'harvest.failed' &&
+              event.payload.run === run.run &&
+              event.payload.willRetry === false,
+          )
+      : undefined
+  // Both durable stop states freeze any open occurrence. A failure normally
+  // closes its step immediately afterward, but projecting the boundary itself
+  // must never make an errored row look like work is still accumulating time.
+  const frozenAt =
+    state.pausedAt !== undefined
+      ? Date.parse(state.pausedAt)
+      : failedEvent !== undefined
+        ? Date.parse(failedEvent.ts)
+        : undefined
+  const steps: PipelineStep[] = [
+    step('scan', hasOutcome('scan', 'completed'), current('scan'), {
+      qualifier: failedAt('scan') ? 'failed' : undefined,
+      producedOutput: hasCompleted('scan'),
+      timing: harvestStepTiming(occurrences, 'scan', frozenAt),
+    }),
+    step(
+      'synthesize',
+      synthOutput && (approved || stopped) && !failedAt('synthesize'),
+      current('synthesize'),
+      {
+        producedOutput: synthOutput || hasCompleted('synthesize'),
+        qualifier: failedAt('synthesize') ? 'failed' : undefined,
+        count,
+        timing: harvestStepTiming(occurrences, 'synthesize', frozenAt),
+      },
+    ),
+    step(
+      'review',
+      reviewOutput && (approved || stopped) && !failedAt('review'),
+      current('review'),
+      {
+        producedOutput: reviewOutput || hasCompleted('review'),
+        qualifier: failedAt('review') ? 'failed' : undefined,
+        count,
+        timing: harvestStepTiming(occurrences, 'review', frozenAt),
+      },
+    ),
+    step('file', false, current('file'), {
+      producedOutput: hasCompleted('file'),
+      qualifier: failedAt('file') ? 'failed' : undefined,
+      timing: harvestStepTiming(occurrences, 'file', frozenAt),
+    }),
+  ]
+  const recoveryAttempts = run.recoveryRequests.length
+  const recoveryLimit =
+    exhaustion?.limit ?? run.recoveryRequests.at(-1)?.limit ?? DEFAULT_MAX_HARVEST_RECOVERY_ATTEMPTS
+  const stoppedAt = run.failure
+    ? `${run.failure.step}${run.failure.round !== undefined ? ` r${run.failure.round}` : ''}`
+    : undefined
+  const detail =
+    run.escalation !== undefined
+      ? run.escalation.reason
+      : exhaustion !== undefined
+        ? `recovery exhausted - human attention required; stopped at ${exhaustion.step}${
+            exhaustion.round !== undefined ? ` r${exhaustion.round}` : ''
+          }; pending ${exhaustion.releasedObservations.length}`
+        : run.failure !== undefined
+          ? `stopped at ${stoppedAt} - automatic recovery ${recoveryAttempts}/${recoveryLimit}; ${run.failure.error}`
+          : recoveryAttempts > 0
+            ? `automatic recovery ${recoveryAttempts}/${recoveryLimit} resumed`
+            : undefined
+  const hasPendingResume = state.pendingCommands.some((command) => command.command === 'resume')
+  const action: HarvestRunAction | undefined =
+    state.paused || hasPendingResume
+      ? undefined
+      : run.status === 'failed'
+        ? exhaustion === undefined
+          ? 'resume'
+          : 'acknowledge'
+        : run.status === 'escalated'
+          ? 'acknowledge'
+          : undefined
+  return {
+    kind: 'harvest',
+    run: run.run,
+    // A paused gate freezes an open run. Attention statuses remain visible as
+    // FAILED/ESCALATED because the header now carries the gate state.
+    status: state.paused && run.status === 'running' ? 'paused' : run.status,
+    steps,
+    observations: run.observations.length,
+    rounds,
+    ...(detail !== undefined ? { detail } : {}),
+    ...(action !== undefined ? { action } : {}),
+  }
+}
+
+interface RepositoryHarvestProjection {
+  harvestPaused: boolean
+  harvest?: DashboardHarvest
+}
+
+function projectRepositoryHarvest(events: RepositoryEvent[]): RepositoryHarvestProjection {
+  const state = reduceHarvest(events)
+  const harvest = projectHarvestRun(events, state)
+  return {
+    harvestPaused: state.paused,
+    ...(harvest !== undefined ? { harvest } : {}),
+  }
+}
+
+export function projectHarvest(events: RepositoryEvent[]): DashboardHarvest | undefined {
+  return projectRepositoryHarvest(events).harvest
+}
+
+interface DashboardFrameHeader {
+  repo: string
+  queued: number
+  observationCount: number
+  selection?: DashboardSelection
+  availableUpgrade?: string
+  warningLines?: readonly string[]
+  resumeInput?: ResumeInputView
+}
+
+/** Exact dynamic and configured facts needed by the preprojected live path. */
+export interface DashboardHeader extends DashboardFrameHeader {
+  activeCount: number
+  capacity: number
+  observationLimit: number
+}
+
+/**
+ * Compose a frame from already projected active rows. Keeping repository
+ * projection here means build rows (including their phase intervals) may be
+ * cached without caching dispatcher settings or Harvest state.
+ */
+export function buildDashboardFromProjected(
+  projectedBuilds: readonly DashboardBuild[],
+  header: DashboardHeader,
+  repositoryEvents: RepositoryEvent[] = [],
+): DashboardModel {
+  const builds = [...projectedBuilds].sort((a, b) => a.slug.localeCompare(b.slug))
+  const harvestProjection = projectRepositoryHarvest(repositoryEvents)
+  const settings = reduceDispatchSettings(repositoryEvents)
+  return {
+    repo: header.repo,
+    queued: header.queued,
+    active: { current: header.activeCount, limit: header.capacity },
+    observations: { current: header.observationCount, limit: header.observationLimit },
+    drained: !settings.intake,
+    repositoryPaused: settings.paused,
+    defaultAutoMerge: settings.defaultAutoMerge,
+    harvestPaused: harvestProjection.harvestPaused,
+    ...(header.selection !== undefined ? { selection: header.selection } : {}),
+    ...(header.availableUpgrade !== undefined ? { availableUpgrade: header.availableUpgrade } : {}),
+    ...(header.warningLines !== undefined && header.warningLines.length > 0
+      ? { warningLines: header.warningLines }
+      : {}),
+    ...(header.resumeInput !== undefined ? { resumeInput: header.resumeInput } : {}),
+    builds,
+    ...(harvestProjection.harvest !== undefined ? { harvest: harvestProjection.harvest } : {}),
+  }
+}
+
+/** Existing entry-based convenience for uncached callers and projection tests. */
+export function buildDashboard(
+  entries: { record: BuildRecord; state: BuildState; events: AbEvent[] }[],
+  config: Config,
+  header: DashboardFrameHeader,
+  repositoryEvents: RepositoryEvent[] = [],
+): DashboardModel {
+  const builds = entries
+    .map(({ record, state, events }) => projectBuild(record, state, config, events))
+    .filter((build): build is DashboardBuild => build !== null)
+  const activeCount = entries.filter(
+    ({ state }) => state.status !== 'done' && state.status !== 'aborted',
+  ).length
+  return buildDashboardFromProjected(
+    builds,
+    {
+      ...header,
+      activeCount,
+      capacity: config.capacity,
+      observationLimit: config.policy.harvestThreshold,
+    },
+    repositoryEvents,
+  )
+}