@defrex/autobuild 0.8.0

package/packages/core/src/cli/status.ts

@@ -0,0 +1,895 @@
+/**
+ * `ab builds` and `ab build status <slug>` — the read-only query surface on
+ * build state (SPEC §8.2, §15.5). Their invocation forms require no session,
+ * while a complete ambient phase identity narrows Store authority; `ab build
+ * status` additionally extends that identity to authorize reading the
+ * session's OWN build from a differently located checkout (see the gate
+ * comment on `abBuildStatus`).
+ *
+ * The shape is one decision: **the projection is pure, the IO is a thin
+ * shell.** The functions below map build facts plus an optional build-config
+ * decision to plain data (`BuildSummary`, `BuildDetail`), and the renderers map
+ * that data to `string[]`. The command entry points only resolve a store, fetch
+ * the build-owned config when needed, project, and print. So `--json` IS the
+ * projection object and the human text is a second renderer over the same
+ * value — there is no "compute for text" path that can disagree with the JSON.
+ *
+ * Effective status comes from `reduceBuild` — the authoritative event-derived
+ * projection (§15.5, §3.4). This is NOT a second read model: it reduces the
+ * log and reads the projection's fields, never re-deriving status from
+ * records, worktrees, or OS processes.
+ *
+ * **Status, durable progress, and lease health are separate axes.**
+ * `reduceBuild` reports both effective status and the latest durable event;
+ * mutable `lease`/`heartbeatAt` columns report runner liveness (§15.2.6).
+ * A runner can therefore stay live while its event log is silent. The shared
+ * presentation helper exposes that divergence without folding it into status
+ * or lease health.
+ *
+ * Output carries no ANSI, ever: §16 puts themes and colors out of scope, and
+ * "understandable without relying solely on color" plus "--json without ANSI
+ * formatting" are both satisfied by emitting none rather than by gating on a
+ * TTY check.
+ */
+import { join } from 'node:path'
+import type { AbEvent } from '../events/catalog'
+import type { EventPayload } from '../events/payloads'
+import type { Actor } from '../events/envelope'
+import { loadConfig } from '../config/load'
+import type { Config } from '../config/schema'
+import {
+  BUILD_EFFECTIVE_CONFIG_ARTIFACT,
+  parseEffectiveBuildConfig,
+} from '../processes/build-execution-state'
+import { openExecution } from '../processes/execution-settlement'
+import { currentAutoMergeDeferral } from '../kernel/auto-merge'
+import { decideNext } from '../kernel/engine'
+import {
+  reduceBuild,
+  type BuildState,
+  type OpenEscalation,
+  type OpenSession,
+  type PrLifecycle,
+} from '../kernel/reducer'
+import type {
+  BuildOutcome,
+  BuildStatus,
+  ObservationKind,
+  Phase,
+  TicketRef,
+  VerifyOutcome,
+} from '../ontology'
+import type { Exec } from '../ports/workspace/git-worktree'
+import type { BuildRecord, BuildStore, StreamRecord, StreamScope } from '../store/types'
+import { buildProgress, isDiverged, type BuildProgress } from './build-progress'
+import { normalizeGitRemoteUrl } from '../kernel/origin'
+import { buildInRepository, resolveMainRepo } from './repo-state'
+import { withAmbientReadStore, type StoreOpener } from './store-opening'
+
+/** Backward-compatible name for callers/tests; repository resolution is shared. */
+export const currentRepo = resolveMainRepo
+
+// ── The projection ───────────────────────────────────────────────────────────
+
+/**
+ * Runner liveness, from the mutable lease columns (§15.2.6) — NOT a status.
+ * `none` is deliberately its own value rather than a weaker `expired`: a build
+ * that has not yet claimed its first lease reads this way, and it is the
+ * common case for a freshly launched runner.
+ */
+export type LeaseHealth = 'held' | 'expired' | 'none'
+
+export interface LeaseInfo {
+  health: LeaseHealth
+  holder?: string
+  expiresAt?: string
+  heartbeatAt?: string
+}
+
+export interface BuildSummary {
+  slug: string
+  ticket?: TicketRef
+  /** The reducer's effective status (§15.5) — never mixed with lease health. */
+  status: BuildStatus
+  phase?: Phase
+  round?: number
+  attempt?: number
+  pr?: { number: number; url: string; state?: PrLifecycle }
+  updatedAt: string
+  lease: LeaseInfo
+  /** Durable-event progress, separate from mutable lease renewal. */
+  progress: BuildProgress
+}
+
+export interface VerifyProgress {
+  /** Full-log attempt high-water retained for status-output compatibility. */
+  attempt: number
+  /** Current cycle only — selected by sequence boundary, never attempt. */
+  steps: { step: string; outcome: VerifyOutcome; reason?: string }[]
+  currentStep?: string
+}
+
+export interface SetupFailureDetail {
+  attempt: number
+  command: string
+  exitStatus: number | null
+  output: string
+}
+
+export interface BuildObservation {
+  id: string
+  kind: ObservationKind
+  summary: string
+  files?: string[]
+  refs?: string[]
+}
+
+export type BuildDecisionProjection =
+  | { kind: 'awaiting-pr'; reason?: string }
+  | { kind: 'repository-completion'; prState: Extract<PrLifecycle, 'merged' | 'closed'> }
+  | { kind: 'parked'; reason: string }
+  | { kind: 'runner-work' }
+  | { kind: 'unavailable'; diagnostic: string }
+
+export interface BuildDetail extends BuildSummary {
+  /** Current work-owner decision. Open PRs use the build-owned config; ended
+   * PRs project the repository completion path directly from durable state. */
+  decision?: BuildDecisionProjection
+  openEscalations: OpenEscalation[]
+  /** Per-loop review overrides for the current spec; omitted when none are set. */
+  reviewRoundCeilings?: { plan?: number; code?: number }
+  openSessions: StatusOpenSession[]
+  observations: BuildObservation[]
+  /** Current setup failure only; a later successful attachment clears it. */
+  setupFailure?: SetupFailureDetail
+  /** True when the latest recorded execution has no following
+   * `execution.ended` — the guest may still be running under durable
+   * supervision even with no dispatcher process alive. */
+  executionOpen?: boolean
+  /** Latest provider execution and current lifecycle failure. Full history is
+   * available with --events. */
+  execution?: EventPayload<'execution.started'> & { seq: number }
+  infrastructureFailure?: EventPayload<'infrastructure.failed'> & { seq: number }
+  cleanupPending: boolean
+  verify: VerifyProgress
+  lastEvent?: { type: string; seq: number; ts: string; actor: Actor }
+  /** Present only with `--events <n>`: the newest n, chronological. */
+  events?: AbEvent[]
+  outcome?: BuildOutcome
+}
+
+/**
+ * `none` when there is no lease; `expired` when it has run out; else `held`.
+ *
+ * The boundary matches `Dispatcher.leaseSweep` (src/processes/dispatcher.ts),
+ * whose has-lease branch is `if (expiresAt > now) continue // healthy` — so
+ * `expiresAt === now` is expired in both places and the sweep and this report
+ * agree.
+ *
+ * That agreement is on the has-lease branch only. `leaseSweep` also grants an
+ * ABSENT lease a first-claim grace window (`updatedAt` within `leaseTtlMs`)
+ * before it acts, while this reports `none` regardless. The divergence is
+ * intended: `none` is a distinct word from `expired`, and teaching this
+ * function the grace window would put a dispatcher policy knob (`leaseTtlMs`)
+ * into a read-only reporter. It is documented in the guide instead.
+ */
+export function leaseHealth(record: BuildRecord, now: Date): LeaseHealth {
+  if (record.lease === undefined) return 'none'
+  return new Date(record.lease.expiresAt).getTime() <= now.getTime() ? 'expired' : 'held'
+}
+
+function leaseInfo(record: BuildRecord, now: Date): LeaseInfo {
+  return {
+    health: leaseHealth(record, now),
+    ...(record.lease !== undefined
+      ? { holder: record.lease.holder, expiresAt: record.lease.expiresAt }
+      : {}),
+    ...(record.heartbeatAt !== undefined ? { heartbeatAt: record.heartbeatAt } : {}),
+  }
+}
+
+/**
+ * The summary over an ALREADY-reduced state — so `detail` reduces the log
+ * once and builds both projections from it, rather than reducing twice.
+ */
+function summarizeFrom(record: BuildRecord, state: BuildState, now: Date): BuildSummary {
+  // `phase`, `round`, and `attempt` describe ONE phase occurrence, so they come
+  // from ONE source: the in-flight phase, else the last completed one — the
+  // same `currentPhase ?? lastCompletedPhase` the reducer uses to derive
+  // `state.phase`. Reading `phase` from that pair while reading round/attempt
+  // from `currentPhase` alone made the three disagree the moment a phase
+  // completed: `verify.completed` clears `currentPhase`, so between two verify
+  // steps a build on attempt 3 reported `verify:unit r1` — the attempt gone and
+  // the loop round stamped onto a phase that carries none. That reads as "first
+  // pass through verify" while verify is actually thrashing on its third.
+  //
+  // PhaseContext is authoritative about which axis a phase HAS (§15.3): loop
+  // phases carry `round`, verify and reconcile carry `attempt`, finalize
+  // carries neither. Taking both straight from it is what makes "current round
+  // or attempt WHEN APPLICABLE" fall out, instead of being re-decided here.
+  const active = state.currentPhase ?? state.lastCompletedPhase
+  const round = active?.round
+  const attempt = active?.attempt
+  return {
+    slug: record.slug,
+    // record.ticket is a TicketRef already carrying id/title/url — no artifact
+    // read and no ticket-provider call (live ticket state is out of scope).
+    ...(record.ticket !== undefined ? { ticket: record.ticket } : {}),
+    status: state.status,
+    ...(active?.phase !== undefined ? { phase: active.phase } : {}),
+    ...(round !== undefined ? { round } : {}),
+    ...(attempt !== undefined ? { attempt } : {}),
+    ...(state.pr !== undefined
+      ? {
+          pr: {
+            number: state.pr.number,
+            url: state.pr.url,
+            ...(state.prState !== undefined ? { state: state.prState } : {}),
+          },
+        }
+      : {}),
+    updatedAt: record.updatedAt,
+    lease: leaseInfo(record, now),
+    progress: buildProgress(record, state),
+  }
+}
+
+/**
+ * One build's summary. `round`/`attempt` come from the in-flight phase when
+ * there is one, so "current round or attempt when applicable" reflects what is
+ * happening now rather than the last thing that finished.
+ */
+export function summarize(record: BuildRecord, events: AbEvent[], now: Date): BuildSummary {
+  return summarizeFrom(record, reduceBuild(events), now)
+}
+
+/** Summary plus the detail fields; `eventCount` appends the newest n events. */
+/** One open session enriched with its live-view stream status (SPEC §9). */
+export interface StatusOpenSession extends OpenSession {
+  /** Open until the stream closes; the store's records are authoritative. */
+  streamStatus?: 'open' | 'closed'
+}
+
+export function detail(
+  record: BuildRecord,
+  events: AbEvent[],
+  now: Date,
+  eventCount?: number,
+  decision?: BuildDecisionProjection,
+  streams?: readonly StreamRecord[],
+): BuildDetail {
+  const state = reduceBuild(events)
+  const streamStatus = new Map<string, { stream?: string; status: 'open' | 'closed' }>()
+  if (streams !== undefined) {
+    for (const record of streams) {
+      if (record.scope.kind !== 'build') continue
+      streamStatus.set(record.label, { stream: record.id, status: record.status })
+    }
+  }
+  const summary = summarizeFrom(record, state, now)
+  // §15.6-A: only the CURRENT cycle's results describe the current code.
+  // Without this filter an earlier cycle's passes read as current — wrong, and
+  // wrong in the reassuring direction.
+  //
+  // The cycle test is `seq > verify.cycleSince`, never result attempt equality:
+  // `maxAttemptSeen` is the full-log high-water and still names the failed
+  // cycle in the window before the next `verify.started`. `cycleSince` is the
+  // authoritative boundary the reducer and engine.ts already agree on (max of
+  // restart, code-review approve, and reconcile) — reading it here is what
+  // keeps this command's report equal to the projection used elsewhere rather
+  // than a second, drifting opinion.
+  const steps = state.verify.results
+    .filter((result) => result.seq > state.verify.cycleSince)
+    .map((result) => ({
+      step: result.step,
+      outcome: result.outcome,
+      ...(result.reason !== undefined ? { reason: result.reason } : {}),
+    }))
+  return {
+    ...summary,
+    ...(decision !== undefined ? { decision } : {}),
+    openEscalations: state.openEscalations,
+    ...(state.reviewRoundCeilings.plan !== undefined || state.reviewRoundCeilings.code !== undefined
+      ? { reviewRoundCeilings: { ...state.reviewRoundCeilings } }
+      : {}),
+    openSessions: state.sessions.open.map((session) => {
+      const record = streamStatus.get(`session:${session.session}`)
+      return {
+        ...session,
+        ...(record?.stream !== undefined ? { stream: record.stream } : {}),
+        ...(record !== undefined ? { streamStatus: record.status } : {}),
+      }
+    }),
+    // Observations are historical facts rather than a derived current-state
+    // opinion. Preserve event order and exact optional evidence fields.
+    observations: events
+      .filter((event) => event.type === 'observation.recorded')
+      .map((event) => ({
+        id: event.payload.id,
+        kind: event.payload.kind,
+        summary: event.payload.summary,
+        ...(event.payload.files !== undefined ? { files: event.payload.files } : {}),
+        ...(event.payload.refs !== undefined ? { refs: event.payload.refs } : {}),
+      })),
+    ...(state.setupFailure !== undefined
+      ? {
+          setupFailure: {
+            attempt: state.setupFailure.attempt,
+            command: state.setupFailure.command,
+            exitStatus: state.setupFailure.exitStatus,
+            output: state.setupFailure.output,
+          },
+        }
+      : {}),
+    ...(state.executions.at(-1) !== undefined ? { execution: state.executions.at(-1)! } : {}),
+    // Durable supervision: a recorded execution with no following end is the
+    // source of truth for whether a guest may still be running.
+    executionOpen: openExecution(events) !== null,
+    ...(state.infrastructureFailure !== undefined
+      ? { infrastructureFailure: state.infrastructureFailure }
+      : {}),
+    cleanupPending:
+      state.infrastructureFailure?.cleanupPending === true ||
+      state.cleanupAttempts.at(-1)?.outcome === 'unknown',
+    verify: {
+      // Preserve the status API's display counter while sourcing it explicitly
+      // from the reducer's full-log high-water, never from cycle membership.
+      attempt: state.verify.maxAttemptSeen,
+      steps,
+      ...(state.verify.currentStep !== undefined ? { currentStep: state.verify.currentStep } : {}),
+    },
+    ...(state.lastEvent !== undefined
+      ? {
+          lastEvent: {
+            type: state.lastEvent.type,
+            seq: state.lastEvent.seq,
+            ts: state.lastEvent.ts,
+            actor: state.lastEvent.actor,
+          },
+        }
+      : {}),
+    // getEvents returns seq-ordered events, so the newest n slice out already
+    // chronological — which is what the AC asks for.
+    ...(eventCount !== undefined ? { events: events.slice(-eventCount) } : {}),
+    ...(state.outcome !== undefined ? { outcome: state.outcome } : {}),
+  }
+}
+
+// ── Renderers ────────────────────────────────────────────────────────────────
+
+/** Lease health as a literal word — never a color (§16: colors out of scope). */
+function healthWord(health: LeaseHealth): string {
+  return health === 'none' ? 'no-lease' : health
+}
+
+/** Preserve printable text while making terminal control bytes inert. Newlines
+ * are split by the caller so multiline setup output remains readable. */
+function safeStatusText(value: string): string {
+  let displayed = ''
+  for (const char of value) {
+    const code = char.codePointAt(0)!
+    displayed += code >= 0x20 && code !== 0x7f ? char : `\\u{${code.toString(16)}}`
+  }
+  return displayed
+}
+
+/** `r<round>` / `a<attempt>` suffixed onto the phase — the loop vs verify axis. */
+function phaseCell(summary: BuildSummary): string {
+  if (summary.phase === undefined) return '—'
+  if (summary.attempt !== undefined) return `${summary.phase} a${summary.attempt}`
+  if (summary.round !== undefined) return `${summary.phase} r${summary.round}`
+  return summary.phase
+}
+
+/** `#7 open https://…` — state AND link, per the summary's required fields. */
+function prCell(summary: BuildSummary): string {
+  if (summary.pr === undefined) return '—'
+  const state = summary.pr.state !== undefined ? ` ${summary.pr.state}` : ''
+  return `#${summary.pr.number}${state} ${summary.pr.url}`
+}
+
+/** Long enough to recognize the ticket, short enough to keep rows scannable. */
+const TITLE_WIDTH = 40
+
+/** `AUT-6 Interactive build dashboard…` — id AND title, per the same list. */
+function ticketCell(summary: BuildSummary): string {
+  const ticket = summary.ticket
+  if (ticket === undefined) return '—'
+  if (ticket.title === undefined || ticket.title === '') return ticket.id
+  const title =
+    ticket.title.length > TITLE_WIDTH ? `${ticket.title.slice(0, TITLE_WIDTH - 1)}…` : ticket.title
+  return `${ticket.id} ${title}`
+}
+
+/** Coarse relative age — a status read wants "how stale", not a timestamp. */
+export function relativeTime(iso: string, now: Date): string {
+  const then = new Date(iso).getTime()
+  if (Number.isNaN(then)) return iso
+  const seconds = Math.round((now.getTime() - then) / 1000)
+  if (seconds < 0) return 'just now'
+  if (seconds < 60) return `${seconds}s ago`
+  const minutes = Math.floor(seconds / 60)
+  if (minutes < 60) return `${minutes}m ago`
+  const hours = Math.floor(minutes / 60)
+  if (hours < 24) return `${hours}h ago`
+  return `${Math.floor(hours / 24)}d ago`
+}
+
+/**
+ * Delegated-write attribution (§15.1): a human actor carrying a via marker
+ * renders as `human (via session os_…)` / `human (via mcp client)`; plain
+ * actors render unchanged. The JSON output and the operator API's build
+ * detail serialize the actor object verbatim, so the marker reaches those
+ * surfaces without transformation.
+ */
+function viaMarker(actor: Actor): string {
+  if (actor.kind !== 'human' || actor.via === undefined) return actor.kind
+  return `human (via ${actor.via.kind === 'session' ? `session ${actor.via.id}` : `mcp ${actor.via.client}`})`
+}
+
+function padColumns(rows: string[][]): string[] {
+  const widths: number[] = []
+  for (const row of rows) {
+    row.forEach((cell, i) => {
+      widths[i] = Math.max(widths[i] ?? 0, cell.length)
+    })
+  }
+  return rows.map((row) =>
+    row
+      .map((cell, i) => (i === row.length - 1 ? cell : cell.padEnd(widths[i] ?? 0)))
+      .join('  ')
+      .trimEnd(),
+  )
+}
+
+/**
+ * One aligned row per build. `emptyNote` names the filter in effect when there
+ * is nothing to show, so an empty result is an honest answer rather than a
+ * blank that reads like a bug.
+ */
+export function renderSummaries(summaries: BuildSummary[], now: Date, emptyNote: string): string[] {
+  if (summaries.length === 0) return [emptyNote]
+  // The two free-text columns (ticket title, PR link) go last, where their
+  // width costs no alignment on the scannable columns to their left.
+  const rows: string[][] = [
+    ['BUILD', 'STATUS', 'PHASE', 'LEASE', 'HEARTBEAT', 'PROGRESS', 'TICKET', 'PR'],
+  ]
+  for (const summary of summaries) {
+    const progressAge =
+      summary.progress.lastEventAt === undefined
+        ? '—'
+        : relativeTime(summary.progress.lastEventAt, now)
+    rows.push([
+      summary.slug,
+      summary.status,
+      phaseCell(summary),
+      healthWord(summary.lease.health),
+      summary.progress.heartbeatAt === undefined
+        ? '—'
+        : relativeTime(summary.progress.heartbeatAt, now),
+      `${progressAge}${isDiverged(summary.progress, now) ? ' diverged' : ''}`,
+      ticketCell(summary),
+      prCell(summary),
+    ])
+  }
+  return padColumns(rows)
+}
+
+/** Labeled sections, each omitted when absent ("when each is available"). */
+export function renderDetail(d: BuildDetail, now: Date): string[] {
+  const lines: string[] = [`build ${d.slug}`]
+  if (d.ticket !== undefined) {
+    const title = d.ticket.title !== undefined ? ` — ${d.ticket.title}` : ''
+    lines.push(`  ticket:   ${d.ticket.id}${title}`)
+    if (d.ticket.url !== undefined) lines.push(`  ticket url: ${d.ticket.url}`)
+  }
+  lines.push(`  status:   ${d.status}${d.outcome !== undefined ? ` (${d.outcome})` : ''}`)
+  lines.push(`  phase:    ${phaseCell(d)}`)
+  if (d.reviewRoundCeilings !== undefined) {
+    const ceilings = [
+      ...(d.reviewRoundCeilings.plan !== undefined ? [`plan ${d.reviewRoundCeilings.plan}`] : []),
+      ...(d.reviewRoundCeilings.code !== undefined ? [`code ${d.reviewRoundCeilings.code}`] : []),
+    ]
+    lines.push(`  review round ceiling: ${ceilings.join(', ')}`)
+  }
+  lines.push(`  updated:  ${d.updatedAt} (${relativeTime(d.updatedAt, now)})`)
+
+  // Its own line, never folded into status: a running build with an expired
+  // lease is the case this exists to make visible.
+  const lease = [`  lease:    ${healthWord(d.lease.health)}`]
+  if (d.lease.holder !== undefined) lease.push(`holder ${d.lease.holder}`)
+  if (d.lease.expiresAt !== undefined) lease.push(`expires ${d.lease.expiresAt}`)
+  lines.push(lease.join('  '))
+  lines.push(
+    d.progress.heartbeatAt === undefined
+      ? '  heartbeat: —'
+      : `  heartbeat: ${d.progress.heartbeatAt} (${relativeTime(d.progress.heartbeatAt, now)})`,
+  )
+  lines.push(
+    d.progress.lastEventAt === undefined
+      ? '  progress:  —'
+      : `  progress:  ${d.progress.lastEventAt} (${relativeTime(d.progress.lastEventAt, now)})${
+          isDiverged(d.progress, now) ? ' — diverged' : ''
+        }`,
+  )
+  if (d.status === 'running' && d.lease.health === 'expired') {
+    if (d.decision?.kind === 'awaiting-pr') {
+      lines.push(
+        '  note:     running with an expired lease — parked waiting on the PR; no runner re-attachment is pending',
+      )
+    } else if (d.decision?.kind === 'repository-completion') {
+      lines.push(
+        `  note:     running with an expired lease — the PR is ${d.decision.prState}; repository-level completion is pending and no runner re-attachment is pending`,
+      )
+    } else if (d.decision?.kind === 'parked') {
+      lines.push(
+        '  note:     running with an expired lease — the current decision is parked; no runner re-attachment is pending',
+      )
+    } else if (d.decision?.kind === 'unavailable') {
+      lines.push(
+        '  note:     running with an expired lease — runner actionability could not be determined from the unavailable build config',
+      )
+    } else if (d.executionOpen === true) {
+      lines.push(
+        '  note:     running with an expired lease — the recorded execution is still the\n' +
+          '            source of truth: the guest may keep running and the lease sweep\n' +
+          '            re-attaches only when the guest is actually gone',
+      )
+    } else {
+      lines.push(
+        '  note:     running with an expired lease — the runner is gone; the lease sweep will re-attach it',
+      )
+    }
+  }
+
+  if (d.pr !== undefined) {
+    lines.push(
+      `  pr:       #${d.pr.number}${d.pr.state !== undefined ? ` (${d.pr.state})` : ''} ${d.pr.url}`,
+    )
+  }
+  if (d.decision?.kind === 'awaiting-pr') {
+    lines.push(
+      `  waiting:  on PR${d.decision.reason !== undefined ? ` — ${d.decision.reason}` : ''}`,
+    )
+  } else if (d.decision?.kind === 'repository-completion') {
+    lines.push(
+      `  waiting:  repository-level completion after the PR was ${d.decision.prState}; no runner re-attachment is pending`,
+    )
+  } else if (d.decision?.kind === 'unavailable') {
+    lines.push(`  decision: unavailable — ${d.decision.diagnostic}`)
+  }
+
+  if (d.execution !== undefined) {
+    lines.push(
+      `  execution: ${safeStatusText(d.execution.provider)} workspace=${safeStatusText(d.execution.workspaceRef)} instance=${safeStatusText(d.execution.instance)}`,
+    )
+    if (d.execution.environmentId !== undefined)
+      lines.push(`    environment: ${safeStatusText(d.execution.environmentId)}`)
+    if (d.execution.sessionId !== undefined)
+      lines.push(`    session: ${safeStatusText(d.execution.sessionId)}`)
+  }
+  if (d.infrastructureFailure !== undefined) {
+    lines.push(
+      `  infrastructure failure: ${d.infrastructureFailure.operation} attempt ${d.infrastructureFailure.attempt} (${d.infrastructureFailure.cause})`,
+    )
+    lines.push(`    error: ${safeStatusText(d.infrastructureFailure.error)}`)
+    if (d.cleanupPending) lines.push('    cleanup: pending provider reconciliation')
+  }
+
+  if (d.setupFailure !== undefined) {
+    const status =
+      d.setupFailure.exitStatus === null
+        ? 'exit status unavailable'
+        : `exit status ${d.setupFailure.exitStatus}`
+    lines.push(`  setup failure: attempt ${d.setupFailure.attempt}`)
+    lines.push(`    command: ${safeStatusText(d.setupFailure.command)}`)
+    lines.push(`    status:  ${status}`)
+    lines.push('    output:')
+    const output = d.setupFailure.output || '(no output)'
+    for (const line of output.split('\n')) lines.push(`      ${safeStatusText(line)}`)
+  }
+
+  if (d.openEscalations.length > 0) {
+    lines.push(`  escalations (${d.openEscalations.length} unresolved):`)
+    for (const escalation of d.openEscalations) {
+      lines.push(`    [${escalation.id}] ${escalation.phase}: ${escalation.question}`)
+    }
+  }
+
+  if (d.openSessions.length > 0) {
+    lines.push(`  open sessions (${d.openSessions.length}):`)
+    for (const session of d.openSessions) {
+      const stream =
+        session.stream !== undefined
+          ? ` — stream ${session.stream} (${session.streamStatus ?? 'open'})`
+          : ''
+      lines.push(
+        `    ${session.session} — ${session.role} on ${session.phase} (runner ${session.runner})${stream}`,
+      )
+    }
+  }
+
+  if (d.observations.length > 0) {
+    lines.push(`  observations (${d.observations.length}):`)
+    for (const observation of d.observations) {
+      lines.push(`    [${observation.id}] ${observation.kind}: ${observation.summary}`)
+      if (observation.files !== undefined) {
+        lines.push(`      files: ${observation.files.join(', ')}`)
+      }
+      if (observation.refs !== undefined) {
+        lines.push(`      refs: ${observation.refs.join(', ')}`)
+      }
+    }
+  }
+
+  if (d.verify.attempt > 0) {
+    lines.push(`  verify:   attempt ${d.verify.attempt}`)
+    for (const step of d.verify.steps) {
+      if (step.outcome === 'skipped') {
+        lines.push(`    SKIP  ${step.step} — ${step.reason ?? '(reason unavailable)'}`)
+      } else {
+        lines.push(`    ${step.outcome === 'pass' ? 'pass' : 'FAIL'}  ${step.step}`)
+      }
+    }
+    if (d.verify.currentStep !== undefined) {
+      lines.push(`    running  ${d.verify.currentStep}`)
+    }
+  }
+
+  if (d.lastEvent !== undefined) {
+    lines.push(
+      `  last event: ${d.lastEvent.type} (seq ${d.lastEvent.seq}) ${d.lastEvent.ts} by ${viaMarker(d.lastEvent.actor)}`,
+    )
+  }
+
+  if (d.events !== undefined) {
+    lines.push(`  events (newest ${d.events.length}, chronological):`)
+    const rows = d.events.map((event) => [
+      `    ${event.seq}`,
+      event.ts,
+      event.type,
+      viaMarker(event.actor),
+    ])
+    for (const line of padColumns(rows)) lines.push(line)
+  }
+
+  return lines
+}
+
+// ── The command shells ───────────────────────────────────────────────────────
+
+export interface StatusOpts {
+  /** The cwd — resolved to the main repo root before matching (see currentRepo). */
+  targetRepo: string
+  /** Process environment: AB_STORE / AB_TOKEN (D8). */
+  env: Record<string, string | undefined>
+  exec: Exec
+  stdout: (line: string) => void
+  json?: boolean
+  /** `--store <ref>`; same reference behavior dispatch has (§7.2). */
+  storeRef?: string
+  /** Injectable store seam — mirrors dispatch.ts's `wire`, keeps tests off the
+   * real filesystem. */
+  openStore?: StoreOpener
+  /** Injectable clock; defaults to the wall clock. */
+  now?: () => Date
+}
+
+/** Statuses a bare `ab builds` shows: the ones an operator can still act on. */
+const ACTIVE_STATUSES: BuildStatus[] = ['running', 'paused', 'blocked']
+
+export function statusFilter(all?: boolean, queued?: boolean): BuildStatus[] {
+  if (all === true) return ['queued', 'running', 'paused', 'blocked', 'done', 'aborted']
+  return queued === true ? [...ACTIVE_STATUSES, 'queued'] : ACTIVE_STATUSES
+}
+
+export interface AbBuildsOpts extends StatusOpts {
+  queued?: boolean
+  all?: boolean
+}
+
+/** `ab builds` — this repo's builds, active by default. Read-only. */
+export async function abBuilds(opts: AbBuildsOpts): Promise<void> {
+  const now = (opts.now ?? (() => new Date()))()
+  await withAmbientReadStore(opts, async ({ store, repo }) => {
+    // Repository identity is the checkout's normalized origin. Old records
+    // are keyed by checkout path and are not migrated; they stay visible
+    // from any checkout whose origin matches the recorded `repoOrigin`
+    // (read compatibility, not migration). Foreign-origin records are hidden.
+    const identity = normalizeGitRemoteUrl(repo)
+    const mine = (record: BuildRecord): boolean =>
+      record.repo === identity ||
+      (record.repoOrigin !== undefined && normalizeGitRemoteUrl(record.repoOrigin) === identity)
+    const wanted = new Set(statusFilter(opts.all, opts.queued))
+    // Cross-repo aggregation is out of scope (§12: one dispatcher per repo,
+    // one repo's builds per answer).
+    const records = (await store.listBuilds()).filter(mine)
+    const summaries: BuildSummary[] = []
+    for (const record of records) {
+      const summary = summarize(record, await store.getEvents(record.slug), now)
+      if (wanted.has(summary.status)) summaries.push(summary)
+    }
+    summaries.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+
+    if (opts.json === true) {
+      opts.stdout(JSON.stringify(summaries, null, 2))
+      return
+    }
+    // The empty line names the filter that matched nothing and suggests only
+    // the flags that would actually widen it — telling a caller who passed
+    // --queued to "try --queued" reads as a broken command.
+    const scope =
+      opts.all === true
+        ? 'builds'
+        : opts.queued === true
+          ? 'active or queued builds'
+          : 'active builds'
+    const hint =
+      opts.all === true ? '' : opts.queued === true ? ' — try --all' : ' — try --queued or --all'
+    for (const line of renderSummaries(summaries, now, `no ${scope} for ${repo}${hint}`)) {
+      opts.stdout(line)
+    }
+  })
+}
+
+export interface AbBuildStatusOpts extends StatusOpts {
+  slug: string
+  events?: number
+}
+
+function openWorkspacePath(events: AbEvent[]): string | undefined {
+  let path: string | undefined
+  for (const event of events) {
+    if (event.type === 'workspace.provisioned') {
+      path = event.payload.path ?? event.payload.ref
+    } else if (event.type === 'workspace.released') {
+      path = undefined
+    }
+  }
+  return path
+}
+
+/** The kernel tail both config sources share, so the deposited artifact and
+ * the workspace file cannot drift in what they compute — the sources differ
+ * only in where the config comes from, never in what is decided with it. */
+function decideFromConfig(
+  events: AbEvent[],
+  state: BuildState,
+  config: Config,
+): BuildDecisionProjection {
+  const decision = decideNext(events, config)
+  if (decision.kind !== 'wait') return { kind: 'runner-work' }
+  if (decision.reason !== 'awaiting-pr') return { kind: 'parked', reason: decision.reason }
+  const reason = currentAutoMergeDeferral(events, state)
+  return { kind: 'awaiting-pr', ...(reason !== undefined ? { reason } : {}) }
+}
+
+/** Load the build-owned configuration for the current work-owner decision.
+ *
+ * Source order: the store's deposited `build-runner-effective-config` artifact
+ * first — the exact config the dispatcher froze at the last runner launch and
+ * the one the build child actually runs on — then the local workspace's
+ * `autobuild.toml` when no deposit exists (older records predate per-launch
+ * deposits). For a remote build the recorded workspace path is a guest path
+ * that does not exist on the operator's machine; the deposit is what makes the
+ * decision available there. The decision is reported unavailable only when
+ * neither source can supply a configuration, and the diagnostic then names the
+ * missing source rather than a filesystem path: paths embed guest locations
+ * the operator cannot access. An unavailable decision is a reportable
+ * degradation, never a reason to guess from the current main branch or to make
+ * the read-only command fail. */
+async function projectBuildDecision(
+  slug: string,
+  events: AbEvent[],
+  store: Pick<BuildStore, 'getArtifact'>,
+): Promise<BuildDecisionProjection | undefined> {
+  const state = reduceBuild(events)
+  const active =
+    state.status === 'running' || state.status === 'paused' || state.status === 'blocked'
+  if (!active) return undefined
+  if (state.prState === 'merged' || state.prState === 'closed') {
+    return { kind: 'repository-completion', prState: state.prState }
+  }
+  if (state.prState !== 'open') return undefined
+
+  // Source 1 — the store deposit. A deposit that fails to parse is itself
+  // reportable state: it is surfaced as unavailable naming the artifact rather
+  // than silently falling back to a possibly stale workspace file.
+  const artifact = await store.getArtifact(slug, BUILD_EFFECTIVE_CONFIG_ARTIFACT)
+  if (artifact !== null) {
+    try {
+      return decideFromConfig(events, state, parseEffectiveBuildConfig(artifact))
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      return {
+        kind: 'unavailable',
+        diagnostic: `the deposited ${BUILD_EFFECTIVE_CONFIG_ARTIFACT} artifact could not be read: ${message}`,
+      }
+    }
+  }
+
+  // Source 2 — the local workspace, exactly as before, only when no artifact
+  // is deposited.
+  const workspace = openWorkspacePath(events)
+  if (workspace === undefined) {
+    return {
+      kind: 'unavailable',
+      diagnostic: `no ${BUILD_EFFECTIVE_CONFIG_ARTIFACT} artifact is deposited and no unreleased build workspace is recorded, so the build config cannot be read`,
+    }
+  }
+
+  try {
+    return decideFromConfig(events, state, await loadConfig(join(workspace, 'autobuild.toml')))
+  } catch {
+    // The raw error deliberately stays here: ENOENT/ENOTDIR messages embed the
+    // recorded workspace path, which for a remote build is a guest location.
+    return {
+      kind: 'unavailable',
+      diagnostic: `no ${BUILD_EFFECTIVE_CONFIG_ARTIFACT} artifact is deposited and the build config in the recorded workspace could not be read`,
+    }
+  }
+}
+
+/** `ab build status <slug>` — one build in detail. Read-only.
+ *
+ * Repository authority mirrors the other ambient reads: an operator invocation
+ * (no ambient identity) must match the store-recorded repository by path, or
+ * by normalized origin for a differently located checkout of the same
+ * repository. A validated ambient *build* session additionally authorizes
+ * reading its OWN build — `AB_BUILD` equal to the requested slug, from the
+ * session's own store — the same trust basis as the phase-scoped
+ * `ab artifact get` (AUT-312): the runner-injected tuple validated by
+ * `resolveCliEnv` is the authority, so a guest checkout of the same
+ * repository at a different path can read its build's status projection even
+ * when the record predates origin recording. The bypass is bounded by slug
+ * equality and store-ref equality, never a general relaxation; a sessionless
+ * relocated-checkout read of a record without `repoOrigin` remains foreign by
+ * design (the documented AUT-314 limitation).
+ */
+export async function abBuildStatus(opts: AbBuildStatusOpts): Promise<void> {
+  const now = (opts.now ?? (() => new Date()))()
+  await withAmbientReadStore(opts, async (context) => {
+    const record = await context.store.getBuild(opts.slug)
+    if (record === null) {
+      throw new Error(
+        `no build "${opts.slug}" in this store — run 'ab builds --all' to list ` +
+          "this repo's builds, or pass --store <ref> if it lives in another store",
+      )
+    }
+    // Own-session authority: slug equality bounds the read to the session's
+    // own build, and an explicit --store must name the session's own store for
+    // the bypass to apply. Every other combination falls through to the
+    // ordinary repository gate, unchanged — which now keys on the checkout's
+    // normalized origin identity (`context.checkout` is the physical path;
+    // `buildInRepository` derives the identity from it).
+    const ownSession =
+      context.ambient !== undefined &&
+      'build' in context.ambient &&
+      context.ambient.build === opts.slug &&
+      (opts.storeRef === undefined || opts.storeRef === context.ambient.store)
+    if (!(ownSession || (await buildInRepository(record, context.checkout, opts.exec)))) {
+      throw new Error(
+        `build "${opts.slug}" belongs to repository "${record.repo}", not "${context.repo}"`,
+      )
+    }
+    const events = await context.store.getEvents(opts.slug)
+    const decision = await projectBuildDecision(opts.slug, events, context.store)
+    // Stream enrichment is presentation (SPEC §9): an unavailable read
+    // degrades to payload-carried ids without a status, never a failure.
+    let streams: StreamRecord[] | undefined
+    try {
+      streams = await context.store.listStreams({
+        kind: 'build',
+        build: opts.slug,
+      } satisfies StreamScope)
+    } catch {
+      streams = undefined
+    }
+    const d = detail(record, events, now, opts.events, decision, streams)
+    if (opts.json === true) {
+      opts.stdout(JSON.stringify(d, null, 2))
+      return
+    }
+    for (const line of renderDetail(d, now)) opts.stdout(line)
+  })
+}