@cat-factory/app 0.295.0 → 0.296.0

package/app/components/board/AgentFailureCard.vue

@@ -7,6 +7,7 @@
 import type { ConflictReason, EnvironmentFailureReason } from '@cat-factory/contracts'
 import type { AgentRunSummary } from '~/stores/agentRuns'
 import FailureDetail from '~/components/board/FailureDetail.vue'
+import BootstrapRunSteps from '~/components/bootstrap/BootstrapRunSteps.vue'
 
 const props = withDefaults(
   defineProps<{ run: AgentRunSummary; variant?: 'compact' | 'expanded' }>(),
@@ -92,9 +93,29 @@ const title = computed(() => {
     ? t('board.failure.bootstrapFailed')
     : t('board.failure.runFailed')
 })
-const retryLabel = computed(() =>
-  props.run.kind === 'bootstrap' ? t('board.failure.retryBootstrap') : t('board.failure.retryRun'),
+// A MULTI-STEP bootstrap (the monorepo flow) is not retried from the top: the service resumes
+// from the step the run reached, keeping the survey's paid-for reads and, past the review, the
+// decisions a human already gave. So the button says which step it re-enters at, from the SAME
+// rule the service branches on, rather than "retry", which invites the reviewer to expect to be
+// asked for their decisions again. A single-step run has nothing to resume and keeps "retry".
+const { resumeStep } = useBootstrapRunSteps(() =>
+  props.run.kind === 'bootstrap' ? props.run.runId : null,
 )
+const retryLabel = computed(() => {
+  if (props.run.kind !== 'bootstrap') return t('board.failure.retryRun')
+  const step = resumeStep.value
+  return step
+    ? t('board.failure.resumeBootstrap', { step: t(`bootstrap.steps.name.${step}`) })
+    : t('board.failure.retryBootstrap')
+})
+
+// The run's own observability panel. Offered here because a failed BOOTSTRAP has no step surface
+// to reach it from (a task run's steps each carry their own "Model activity" control), and what
+// a bootstrap failed on is exactly the question its model calls, provided context and tool-call
+// trajectory answer.
+function inspectRun() {
+  ui.openObservability(props.run.runId)
+}
 
 const retrying = ref(false)
 async function retry() {
@@ -159,6 +180,14 @@ async function retry() {
       }}
     </p>
 
+    <!-- Which of the run's steps it got to. Renders for a multi-step (monorepo) bootstrap only;
+         see BootstrapRunSteps. -->
+    <BootstrapRunSteps
+      v-if="!compact && run.kind === 'bootstrap'"
+      :run-id="run.runId"
+      class="mt-2"
+    />
+
     <FailureDetail
       v-if="!compact && failure"
       :detail="failure.detail"
@@ -184,6 +213,18 @@ async function retry() {
         {{ retrying ? t('board.failure.retrying') : compact ? t('common.retry') : retryLabel }}
       </button>
 
+      <button
+        v-if="run.kind === 'bootstrap'"
+        type="button"
+        class="nodrag flex items-center gap-1 rounded-md bg-rose-900/20 text-rose-300 hover:bg-rose-900/50"
+        :class="compact ? 'px-2 py-0.5 text-[10px]' : 'px-2 py-1 text-[11px]'"
+        data-testid="agent-failure-inspect"
+        @click.stop="inspectRun"
+      >
+        <UIcon name="i-lucide-activity" :class="compact ? 'h-3 w-3' : 'h-3.5 w-3.5'" />
+        {{ t('observability.modelActivity') }}
+      </button>
+
       <!-- Environment provisioning failures are almost always a deploy-backend / provider-config
            issue, so link straight to where it's set up rather than leaving the user to hunt. The
            destination + label follow the cause: a `deploy_runner_unwired` failure needs the runner

package/app/components/board/nodes/BlockNode.vue

@@ -8,6 +8,7 @@ import ResizeGrips from './ResizeGrips.vue'
 import AgentFailureCard from '~/components/board/AgentFailureCard.vue'
 import AgentStopButton from '~/components/board/AgentStopButton.vue'
 import AdoptionReviewModal from '~/components/bootstrap/AdoptionReviewModal.vue'
+import BootstrapRunSteps from '~/components/bootstrap/BootstrapRunSteps.vue'
 import { useBlockDrag } from '~/composables/useBlockDrag'
 import { useFrameStacking } from '~/composables/useFrameStacking'
 import { useViewport } from '~/composables/useViewport'
@@ -346,7 +347,21 @@ const ITEM_ICON: Record<string, string> = {
             <span>{{ item.label }}</span>
           </li>
         </ul>
-        <div v-if="run" class="mt-2 flex justify-end">
+        <!-- Which of the run's own steps it is on. A monorepo bootstrap is three moves around a
+             human decision, and the bar above reports only the current container's todo list, so
+             without this the card cannot say whether the survey, the review or the write is what
+             is happening. Renders nothing for a one-step new-repo run. -->
+        <BootstrapRunSteps v-if="run" :run-id="run.runId" class="mt-2" />
+        <div v-if="run" class="mt-2 flex items-center justify-end gap-1.5">
+          <UButton
+            size="xs"
+            color="neutral"
+            variant="ghost"
+            icon="i-lucide-activity"
+            @click.stop="ui.openObservability(run.runId)"
+          >
+            {{ t('observability.modelActivity') }}
+          </UButton>
           <AgentStopButton :run-id="run.runId" :kind="run.kind" size="xs" variant="ghost" />
         </div>
       </div>
@@ -359,6 +374,7 @@ const ITEM_ICON: Record<string, string> = {
           <UIcon name="i-lucide-user-check" class="mt-0.5 h-4 w-4 shrink-0 text-amber-400" />
           <p class="text-xs text-amber-200/90">{{ t('bootstrap.adoption.cardPrompt') }}</p>
         </div>
+        <BootstrapRunSteps :run-id="awaitingReview.id" />
         <div class="flex justify-end">
           <UButton size="xs" color="warning" variant="subtle" @click.stop="reviewOpen = true">
             {{ t('bootstrap.adoption.cardAction') }}

package/app/components/bootstrap/BootstrapRunSteps.vue

@@ -0,0 +1,50 @@
+<script setup lang="ts">
+// The steps a bootstrap run is made of, with the one it reached marked.
+//
+// A monorepo bootstrap is three moves around a human decision (survey → your adoption
+// decisions → write the service and open the PR), and it was rendered as a single
+// "bootstrapping…" bar. That bar cannot say which move a stopped run got to, so "retry" read
+// as "start the whole thing again" when what the platform actually does is resume from the
+// step reached, the survey's paid-for reads and the reviewer's settled decisions included.
+//
+// The steps and their states come from `@cat-factory/contracts`, which is also what
+// `BootstrapService.retry` branches on: the label on the button and the behaviour behind it
+// are one rule, not two. How a state RENDERS is `BOOTSTRAP_STEP_STYLE`, beside the vocabulary
+// it is keyed by.
+import type { BootstrapStepId, BootstrapStepState } from '@cat-factory/contracts'
+
+const props = defineProps<{ runId: string }>()
+
+const { t } = useI18n()
+// A ONE-step run renders nothing: a new-repo bootstrap is a single move, which the banner around
+// this already names, and a one-row checklist restating it is noise rather than information.
+const { steps: allSteps, multiStep } = useBootstrapRunSteps(() => props.runId)
+const steps = computed(() => (multiStep.value ? allSteps.value : []))
+
+function stepLabel(id: BootstrapStepId): string {
+  return t(`bootstrap.steps.name.${id}`)
+}
+function stateLabel(state: BootstrapStepState): string {
+  return t(`bootstrap.steps.state.${state}`)
+}
+</script>
+
+<template>
+  <ol v-if="steps.length" class="space-y-1" data-testid="bootstrap-run-steps">
+    <li
+      v-for="step in steps"
+      :key="step.id"
+      class="flex items-start gap-1.5 text-[11px]"
+      :data-step="step.id"
+      :data-state="step.state"
+    >
+      <UIcon
+        :name="BOOTSTRAP_STEP_STYLE[step.state].icon"
+        class="mt-px h-3 w-3 shrink-0"
+        :class="BOOTSTRAP_STEP_STYLE[step.state].iconClass"
+      />
+      <span :class="BOOTSTRAP_STEP_STYLE[step.state].labelClass">{{ stepLabel(step.id) }}</span>
+      <span class="ms-auto shrink-0 text-slate-500">{{ stateLabel(step.state) }}</span>
+    </li>
+  </ol>
+</template>

package/app/components/panels/InspectorPanel.vue

@@ -7,6 +7,7 @@ import { inspectorPanels } from '~/modular/panels/inspector.logic'
 import IconButton from '~/components/common/IconButton.vue'
 import AgentFailureCard from '~/components/board/AgentFailureCard.vue'
 import AgentStopButton from '~/components/board/AgentStopButton.vue'
+import BootstrapRunSteps from '~/components/bootstrap/BootstrapRunSteps.vue'
 import { BLUEPRINT_AGENT_KIND } from '@cat-factory/contracts'
 import { VCS_PROVIDER_ICONS } from '~/utils/vcs'
 
@@ -489,16 +490,33 @@ const showOriginalDescription = ref(false)
       <!-- failed run (bootstrap or execution): shared failure banner + retry -->
       <AgentFailureCard v-if="failedRun" :run="failedRun" />
 
-      <!-- running bootstrap: let the user stop it (kills the container) -->
+      <!-- running bootstrap: show the steps, let the user inspect it, let them stop it -->
       <div
         v-else-if="runningRun"
-        class="flex items-center justify-between gap-2 rounded-lg border border-amber-900/60 bg-amber-950/30 px-3 py-2"
+        class="space-y-2 rounded-lg border border-amber-900/60 bg-amber-950/30 px-3 py-2"
       >
-        <span class="flex items-center gap-1.5 text-xs text-amber-300">
-          <UIcon name="i-lucide-loader-circle" class="h-3.5 w-3.5 animate-spin" />
-          {{ t('panels.inspector.bootstrapping') }}
-        </span>
-        <AgentStopButton :run-id="runningRun.runId" :kind="runningRun.kind" size="xs" />
+        <div class="flex items-center justify-between gap-2">
+          <span class="flex items-center gap-1.5 text-xs text-amber-300">
+            <UIcon name="i-lucide-loader-circle" class="h-3.5 w-3.5 animate-spin" />
+            {{ t('panels.inspector.bootstrapping') }}
+          </span>
+          <div class="flex items-center gap-1.5">
+            <!-- A bootstrap has no step surface of its own, so this is where its run details are
+                 reached from: the same panel every task run opens, over the same four sinks. -->
+            <UButton
+              v-if="runningRun.kind === 'bootstrap'"
+              size="xs"
+              color="neutral"
+              variant="ghost"
+              icon="i-lucide-activity"
+              @click="ui.openObservability(runningRun.runId)"
+            >
+              {{ t('observability.modelActivity') }}
+            </UButton>
+            <AgentStopButton :run-id="runningRun.runId" :kind="runningRun.kind" size="xs" />
+          </div>
+        </div>
+        <BootstrapRunSteps v-if="runningRun.kind === 'bootstrap'" :run-id="runningRun.runId" />
       </div>
 
       <!-- external links -->

package/app/components/panels/ObservabilityPanel.vue

@@ -50,13 +50,30 @@ const EMPTY_TRAJECTORY: RunToolCallTrajectory = Object.freeze({
 const ui = useUiStore()
 const execution = useExecutionStore()
 const board = useBoardStore()
+const agentRuns = useAgentRunsStore()
 const observability = useObservabilityStore()
 const { t, d } = useI18n()
 
 const executionId = computed(() => ui.observabilityInstanceId)
 const open = computed(() => !!executionId.value)
 const instance = computed(() => execution.getInstance(executionId.value ?? undefined))
-const block = computed(() => (instance.value ? board.getBlock(instance.value.blockId) : undefined))
+// The panel is opened over an AGENT RUN, and a repo bootstrap is one: it has no execution row,
+// so everything below that reads `instance` answers nothing for it. Its own run supplies the two
+// things the panel states about a run rather than about its calls: whose work this was, and what
+// it failed on. The four telemetry reads need none of it: they are keyed by the run id alone.
+const bootstrap = computed(() => agentRuns.bootstrapById(executionId.value))
+const blockId = computed(() => instance.value?.blockId ?? bootstrap.value?.blockId ?? null)
+const block = computed(() => (blockId.value ? board.getBlock(blockId.value) : undefined))
+/**
+ * The line under the title. An execution names its pipeline; a bootstrap names itself, because
+ * "which pipeline" has no answer for it and an empty subtitle on a panel opened from a service
+ * card reads as a panel that failed to load rather than as a run of a different kind.
+ */
+const runSubtitle = computed(() =>
+  instance.value ? instance.value.pipelineName : bootstrap.value ? t('bootstrap.runKind') : '',
+)
+/** The structured failure the pinned summary speaks from, whichever kind of run this is. */
+const runFailure = computed(() => instance.value?.failure ?? bootstrap.value?.failure ?? null)
 
 const calls = computed<LlmCallMetric[]>(() =>
   executionId.value ? observability.callsFor(executionId.value) : [],
@@ -201,7 +218,7 @@ const visibleCalls = computed(() => filterCallsByOutcome(calls.value, callFilter
  */
 const failureEvidence = computed(() =>
   deriveRunFailureEvidence({
-    failure: instance.value?.failure ?? null,
+    failure: runFailure.value,
     calls: calls.value,
     callsAnswer: sinkAnswer({
       loading: loading.value,
@@ -357,7 +374,19 @@ function sum(items: LlmCallMetric[], pick: (m: LlmCallMetric) => number): number
 
 // Where the run's tokens went, by PHASE. Unlike the totals above (derived from the capped call
 // list), this reads the engine's SQL rollup off the steps, so it stays honest on a long run.
-const phaseRows = computed(() => foldRunPhaseMetrics(instance.value?.steps ?? []))
+//
+// A run with NO execution row (a repo bootstrap) has no steps to fold one from, which is a
+// different fact from a run whose phases each spent nothing, and the difference matters here
+// more than anywhere: this rollup is also what prices the run, so left as an empty list it hides
+// both the table and the cost tile, and a bootstrap that made N model calls reads as one that
+// cost nothing. Stated as its own answer, and rendered as a note.
+const phaseRollup = computed<{ available: boolean; rows: ReturnType<typeof foldRunPhaseMetrics> }>(
+  () =>
+    instance.value
+      ? { available: true, rows: foldRunPhaseMetrics(instance.value.steps ?? []) }
+      : { available: false, rows: [] },
+)
+const phaseRows = computed(() => phaseRollup.value.rows)
 const phaseCarryTotal = computed(() =>
   phaseRows.value.reduce((acc, p) => acc + p.carryCostTokens, 0),
 )
@@ -391,6 +420,18 @@ const showCost = computed(
 const runCost = computed(() =>
   formatCost(sumCosts(phaseRows.value.map((p) => p.costEstimate)), costCurrency.value),
 )
+/**
+ * What the cost tile SAYS when it shows no figure. An unpriced phase and a run kind with no
+ * rollup to price from are different facts, and the tile is rendered for the second one rather
+ * than dropped: a missing tile is indistinguishable from a run that cost nothing.
+ */
+const costNoteKey = computed(() =>
+  !phaseRollup.value.available
+    ? 'observability.summary.costNoRollup'
+    : runCost.value
+      ? 'observability.summary.costHint'
+      : 'observability.summary.costIncomplete',
+)
 /** Share of the run's carry cost a phase accounts for (0..100), or null when nothing carried. */
 function carryShare(carryCostTokens: number): number | null {
   return phaseCarryTotal.value > 0 ? pct(carryCostTokens / phaseCarryTotal.value) : null
@@ -473,7 +514,7 @@ function exportJson() {
               {{ t('observability.modelActivity') }}
             </h1>
             <p v-if="block" class="truncate text-xs text-slate-500">
-              {{ block.title }} · {{ instance?.pipelineName }}
+              {{ block.title }} · {{ runSubtitle }}
             </p>
           </div>
           <div class="ms-auto flex items-center gap-1.5">
@@ -569,18 +610,14 @@ function exportJson() {
                   </dt>
                   <dd class="mt-0.5 tabular-nums text-slate-200">{{ totals.calls }}</dd>
                 </div>
-                <div v-if="showCost">
+                <div v-if="showCost || !phaseRollup.available">
                   <dt class="text-[11px] uppercase tracking-wide text-slate-500">
                     {{ t('observability.summary.cost') }}
                   </dt>
                   <dd class="mt-0.5 tabular-nums text-slate-200">
                     {{ runCost ?? '—' }}
                     <span class="mt-0.5 block text-[11px] text-slate-500">
-                      {{
-                        runCost
-                          ? t('observability.summary.costHint')
-                          : t('observability.summary.costIncomplete')
-                      }}
+                      {{ t(costNoteKey) }}
                     </span>
                   </dd>
                 </div>
@@ -683,18 +720,23 @@ function exportJson() {
             <!-- where the run's tokens went, by phase (the engine's SQL rollup, not the
                  capped call list) -->
             <section
-              v-if="phaseRows.length"
+              v-if="phaseRows.length || !phaseRollup.available"
               class="rounded-xl border border-slate-800 bg-slate-900/50 p-4"
             >
               <div class="flex items-baseline gap-2">
                 <h2 class="text-[11px] uppercase tracking-wide text-slate-500">
                   {{ t('observability.phase.title') }}
                 </h2>
-                <span class="text-[11px] text-slate-600">
+                <span v-if="phaseRollup.available" class="text-[11px] text-slate-600">
                   {{ t('observability.phase.subtitle') }}
                 </span>
               </div>
-              <div class="mt-3 overflow-x-auto">
+              <!-- No rollup to fold: said in words, because an absent table and a run that spent
+                   nothing look identical, and the calls listed above prove it spent something. -->
+              <p v-if="!phaseRollup.available" class="mt-2 text-[12px] text-slate-400">
+                {{ t('observability.phase.noRollup') }}
+              </p>
+              <div v-else class="mt-3 overflow-x-auto">
                 <table class="w-full min-w-[32rem] text-[12px]">
                   <thead>
                     <tr class="text-[11px] uppercase tracking-wide text-slate-500">
@@ -998,6 +1040,17 @@ function exportJson() {
               @show-failing-tools="revealFailingToolCalls"
               @retry="retryFailureEvidence"
             />
+            <!-- A monorepo bootstrap's SURVEY explores through the platform's own bounded reader,
+                 whose every read lands on the run's adoption transcript rather than here (that is
+                 the record a reviewer checks a recommendation against, and it outlives this
+                 window). Said out loud because the apply container's calls below are not empty,
+                 so the survey's absence would otherwise read as a phase that used no tools. -->
+            <p
+              v-if="bootstrap?.monorepo"
+              class="rounded-lg border border-dashed border-slate-800 px-3 py-2 text-[12px] text-slate-400"
+            >
+              {{ t('observability.toolCalls.surveyReadsElsewhere') }}
+            </p>
             <ToolCallList
               v-model:filter="toolFilter"
               :trajectory="trajectory"

package/app/composables/useBootstrapRunSteps.spec.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import type { BootstrapJob } from '~/types/domain'
+import { useAgentRunsStore } from '~/stores/agentRuns'
+import { useBootstrapRunSteps } from '~/composables/useBootstrapRunSteps'
+
+// What this composable owns beyond the shared derivation (tested in `@cat-factory/contracts`):
+// the SPA-only question of whether a run has more than one step, which is what decides whether
+// the board renders a step list at all and whether the retry control offers to RESUME.
+
+const MONOREPO: BootstrapJob['monorepo'] = {
+  repoGithubId: 7,
+  directory: 'services/payments',
+  repoOwner: 'acme',
+  repoName: 'platform',
+  branch: null,
+}
+
+function job(id: string, over: Partial<BootstrapJob> = {}): BootstrapJob {
+  return {
+    id,
+    workspaceId: 'ws_test',
+    referenceArchitectureId: null,
+    referenceArchitectureName: null,
+    repoName: id,
+    repoOwner: null,
+    repoUrl: null,
+    instructions: '',
+    status: 'running',
+    blockId: `blk_${id}`,
+    subtasks: null,
+    error: null,
+    failure: null,
+    monorepo: null,
+    phase: null,
+    // The base fixture is a new-repo run, so it takes that target's default delivery. The step
+    // rule never reads the field, which is why no case below overrides it: how a run's work
+    // lands says nothing about how many moves it takes to get there.
+    delivery: 'direct_push',
+    adoptionPlan: null,
+    adoptionReview: null,
+    prUrl: null,
+    createdAt: 1,
+    updatedAt: 1,
+    ...over,
+  }
+}
+
+/** A recorded plan; only its own status is read by the rule. */
+function plan(status: 'ready' | 'unavailable'): BootstrapJob['adoptionPlan'] {
+  return { status } as unknown as BootstrapJob['adoptionPlan']
+}
+
+describe('useBootstrapRunSteps', () => {
+  let store: ReturnType<typeof useAgentRunsStore>
+  beforeEach(() => {
+    store = useAgentRunsStore()
+  })
+
+  it('offers nothing for a new-repo run, which has one move and so nothing to resume', () => {
+    store.upsertBootstrap(job('b1', { status: 'failed' }))
+    const { multiStep, resumeStep } = useBootstrapRunSteps('b1')
+    expect(multiStep.value).toBe(false)
+    // Null rather than 'scaffold': there is progress to keep on a monorepo run and none here,
+    // so the card must keep saying "retry" instead of promising a resume it cannot make.
+    expect(resumeStep.value).toBeNull()
+  })
+
+  it('marks the survey done and the review as the step a broken monorepo run is holding', () => {
+    store.upsertBootstrap(
+      job('b2', {
+        monorepo: MONOREPO,
+        phase: 'survey',
+        status: 'failed',
+        failure: { kind: 'agent' } as unknown as BootstrapJob['failure'],
+        adoptionPlan: plan('ready'),
+      }),
+    )
+    const { steps, multiStep, resumeStep } = useBootstrapRunSteps('b2')
+    expect(multiStep.value).toBe(true)
+    expect(steps.value).toEqual([
+      { id: 'survey', state: 'done' },
+      { id: 'review', state: 'failed' },
+      { id: 'apply', state: 'pending' },
+    ])
+    expect(resumeStep.value).toBe('review')
+  })
+
+  it('renders a run the reviewer STOPPED as stopped, not as a broken review step', () => {
+    // A stop is stored as a `failed` status with a `cancelled` kind, and this is the shape the
+    // card actually renders: stopping a parked run must not report the reviewer's own decision
+    // step back to them as a fault. The resume it offers is unchanged.
+    store.upsertBootstrap(
+      job('b2s', {
+        monorepo: MONOREPO,
+        phase: 'survey',
+        status: 'failed',
+        failure: { kind: 'cancelled' } as unknown as BootstrapJob['failure'],
+        adoptionPlan: plan('ready'),
+      }),
+    )
+    const { steps, resumeStep } = useBootstrapRunSteps('b2s')
+    expect(steps.value.map((step) => step.state)).toEqual(['done', 'stopped', 'pending'])
+    expect(resumeStep.value).toBe('review')
+  })
+
+  it('follows the run as live events advance it, rather than pinning the first read', () => {
+    // The card is open while the run moves: the review is settled and the apply dispatches, and
+    // the step list has to follow the store rather than the value it was mounted with.
+    store.upsertBootstrap(job('b3', { monorepo: MONOREPO, phase: 'survey', updatedAt: 1 }))
+    const { steps, resumeStep } = useBootstrapRunSteps('b3')
+    expect(steps.value.map((s) => s.state)).toEqual(['running', 'pending', 'pending'])
+    store.upsertBootstrap(
+      job('b3', {
+        monorepo: MONOREPO,
+        phase: 'apply',
+        adoptionPlan: plan('ready'),
+        adoptionReview: { choices: [] } as unknown as BootstrapJob['adoptionReview'],
+        updatedAt: 2,
+      }),
+    )
+    expect(steps.value.map((s) => s.state)).toEqual(['done', 'done', 'running'])
+    expect(resumeStep.value).toBe('apply')
+  })
+
+  it('answers empty for a run the store does not hold', () => {
+    const { steps, multiStep, resumeStep } = useBootstrapRunSteps('nope')
+    expect(steps.value).toEqual([])
+    expect(multiStep.value).toBe(false)
+    expect(resumeStep.value).toBeNull()
+  })
+})

package/app/composables/useBootstrapRunSteps.ts

@@ -0,0 +1,37 @@
+import { computed, type ComputedRef, type MaybeRefOrGetter, toValue } from 'vue'
+import {
+  bootstrapResumeStep,
+  bootstrapRunSteps,
+  type BootstrapRunStep,
+  type BootstrapStepId,
+} from '@cat-factory/contracts'
+import { useAgentRunsStore } from '~/stores/agentRuns'
+
+/**
+ * A bootstrap run projected onto its steps, for the surfaces that render them and for the
+ * button that resumes one.
+ *
+ * The projection itself lives in `@cat-factory/contracts` and is shared with the backend, which
+ * BRANCHES on the same rule (`bootstrapResume`) in `BootstrapService.retry`; this side needs only
+ * the step it answers with, never the state it carries. What this composable adds is the
+ * one SPA-side question the backend never asks: whether the run has more than one step at all.
+ * A new-repo bootstrap is a single move, so for it a step list restates the banner it sits under
+ * and "resume from…" is a promise about progress there is none of: it simply starts again.
+ */
+export function useBootstrapRunSteps(runId: MaybeRefOrGetter<string | null | undefined>): {
+  /** The run's steps in order, with the reached one carrying the run's state. Empty if unknown. */
+  steps: ComputedRef<BootstrapRunStep[]>
+  /** Whether the run is a multi-step (monorepo) one: the gate every caller here needs. */
+  multiStep: ComputedRef<boolean>
+  /** The step a retry re-enters at, or null when the run is single-step or unknown. */
+  resumeStep: ComputedRef<BootstrapStepId | null>
+} {
+  const agentRuns = useAgentRunsStore()
+  const job = computed(() => agentRuns.bootstrapById(toValue(runId)))
+  const steps = computed<BootstrapRunStep[]>(() => (job.value ? bootstrapRunSteps(job.value) : []))
+  const multiStep = computed(() => steps.value.length > 1)
+  const resumeStep = computed<BootstrapStepId | null>(() =>
+    job.value && multiStep.value ? bootstrapResumeStep(job.value) : null,
+  )
+  return { steps, multiStep, resumeStep }
+}

package/app/stores/agentRuns.ts

@@ -158,6 +158,18 @@ export const useAgentRunsStore = defineStore('agentRuns', () => {
     return map
   })
 
+  /**
+   * One bootstrap run by its RUN id.
+   *
+   * The counterpart to `execution.getInstance`, and it exists for the same surfaces: anything
+   * that holds a run id and needs the run WHOLE rather than the coarse {@link byBlock} summary:
+   * the observability panel's header, and the step list a card renders. A retry mints a NEW id,
+   * so unlike the block-keyed reads below this one needs nothing of the list's ordering.
+   */
+  function bootstrapById(runId: string | null | undefined): BootstrapJob | undefined {
+    return runId ? bootstrapJobs.value.find((job) => job.id === runId) : undefined
+  }
+
   /**
    * The parked monorepo bootstrap for a block, when it is waiting on an adoption review.
    *
@@ -221,6 +233,7 @@ export const useAgentRunsStore = defineStore('agentRuns', () => {
 
   return {
     bootstrapJobs,
+    bootstrapById,
     awaitingReview,
     submitAdoptionReview,
     hydrate,

package/app/utils/bootstrapSteps.ts

@@ -0,0 +1,60 @@
+import type { BootstrapStepState } from '@cat-factory/contracts'
+
+// Display metadata for a bootstrap run's step states, the `catalog.ts` idea at the scale of one
+// vocabulary: the icon and the two tones that render a state, in ONE record rather than three
+// parallel ones keyed alike. Three had to be kept in step by hand, which is a silent way to give
+// a newly added state (`stopped`, say) a red icon and calm text.
+//
+// Module scope rather than a component's `<script setup>`, where a top-level const is rebuilt for
+// every instance: the step list renders on every in-progress, parked and failed bootstrap card on
+// the board, plus the inspector and the failure card.
+
+/** How one step state renders: its icon, the icon's tone, and the label's. */
+export interface BootstrapStepStyle {
+  icon: string
+  iconClass: string
+  labelClass: string
+}
+
+/**
+ * The style per state. `stopped` is deliberately NOT the failure red: a run someone stopped is
+ * stored as a failure without being one, and the step they stopped in is usually the review,
+ * whose only actor is the reviewer themselves.
+ */
+export const BOOTSTRAP_STEP_STYLE: Record<BootstrapStepState, BootstrapStepStyle> = {
+  pending: {
+    icon: 'i-lucide-circle',
+    iconClass: 'text-slate-500',
+    labelClass: 'text-slate-500',
+  },
+  running: {
+    icon: 'i-lucide-loader-circle',
+    iconClass: 'animate-spin text-amber-400',
+    labelClass: 'text-amber-100',
+  },
+  awaiting_review: {
+    icon: 'i-lucide-user-check',
+    iconClass: 'text-amber-400',
+    labelClass: 'text-amber-100',
+  },
+  done: {
+    icon: 'i-lucide-check-circle-2',
+    iconClass: 'text-emerald-400',
+    labelClass: 'text-slate-400',
+  },
+  failed: {
+    icon: 'i-lucide-alert-triangle',
+    iconClass: 'text-rose-400',
+    labelClass: 'text-rose-200',
+  },
+  stopped: {
+    icon: 'i-lucide-circle-stop',
+    iconClass: 'text-slate-400',
+    labelClass: 'text-slate-300',
+  },
+  unknown: {
+    icon: 'i-lucide-help-circle',
+    iconClass: 'text-slate-400',
+    labelClass: 'text-slate-400',
+  },
+}

package/app/utils/catalog.spec.ts

@@ -1,5 +1,10 @@
 import { describe, it, expect } from 'vitest'
-import { PIPELINE_PURPOSES, purposeAllowsAgentCategory } from '@cat-factory/contracts'
+import {
+  MONOREPO_ADOPTION_AGENT_KIND,
+  PIPELINE_PURPOSES,
+  purposeAllowsAgentCategory,
+  REPO_BOOTSTRAP_AGENT_KIND,
+} from '@cat-factory/contracts'
 import type { AgentKind, BlockStatus, BlockType } from '~/types/domain'
 import { narrowAgentPalette } from '~/utils/agentPalette'
 import {
@@ -78,6 +83,17 @@ describe('catalog', () => {
     }
   })
 
+  it('names the kinds a bootstrap run files its telemetry under', () => {
+    // The backend stamps these two on a bootstrap run's metric, snapshot and tool-call rows, and
+    // the observability panel groups by kind. Unnamed here they roll up under the generic "Agent"
+    // fallback: the survey's model calls and the apply container's under one unlabelled heading,
+    // on the one panel whose job is telling them apart. Asserted through the same constants the
+    // backend imports, so this cannot pass against a stale spelling.
+    for (const kind of [REPO_BOOTSTRAP_AGENT_KIND, MONOREPO_ADOPTION_AGENT_KIND]) {
+      expect(agentKindMeta(kind).label, `${kind} falls back to the unnamed agent`).not.toBe('Agent')
+    }
+  })
+
   it('classifies every built-in kind into a tier', () => {
     // The palette / model-preset surfaces open on `basic`, so a built-in that forgot its tier
     // would silently fall to the DEFAULT (intermediate) and vanish from the default view for