@cat-factory/app 0.136.0 → 0.137.0

package/app/components/panels/MergerResultView.vue

@@ -9,7 +9,7 @@
 import { computed } from 'vue'
 import type { MergeAxis, MergeDecision } from '@cat-factory/contracts'
 import StepRunMeta from '~/components/panels/StepRunMeta.vue'
-import StepRestartControl from '~/components/panels/StepRestartControl.vue'
+import ResultWindowShell from '~/components/panels/ResultWindowShell.vue'
 import MarkdownProse from '~/components/common/MarkdownProse.vue'
 
 const board = useBoardStore()
@@ -17,9 +17,12 @@ const execution = useExecutionStore()
 const agents = useAgentsStore()
 const { t, n } = useI18n()
 
-// Shared seam contract (open/blockId/close + Escape). No loader: the verdict is read
-// straight off the execution step.
-const { open, blockId, instanceId, stepIndex, close } = useResultView('merger')
+// Shared seam contract (open/blockId/close). No loader: the verdict is read straight off
+// the execution step. `manageEscape: false` — `ResultWindowShell` owns Escape (and focus
+// trap + scroll lock + stacking) via the shared overlay behaviour.
+const { open, blockId, instanceId, stepIndex, close } = useResultView('merger', {
+  manageEscape: false,
+})
 const block = computed(() => (blockId.value ? board.getBlock(blockId.value) : undefined))
 
 const instance = computed(() =>
@@ -119,151 +122,122 @@ const reasonText = computed(() => {
 </script>
 
 <template>
-  <Teleport to="body">
-    <div
-      v-if="open"
-      class="fixed inset-0 z-50 flex max-h-[100dvh] items-stretch justify-center bg-slate-950/70 backdrop-blur-sm"
-      @click.self="close"
-    >
-      <div
-        class="m-4 flex w-full max-w-3xl flex-col overflow-hidden rounded-2xl border border-slate-800 bg-slate-900 shadow-2xl"
-      >
-        <!-- Header -->
-        <header class="flex items-center gap-3 border-b border-slate-800 px-5 py-3">
-          <span
-            class="flex h-8 w-8 items-center justify-center rounded-lg bg-lime-500/15 text-lime-300"
-          >
-            <UIcon :name="meta?.icon ?? 'i-lucide-git-pull-request'" class="h-4 w-4" />
-          </span>
-          <div class="min-w-0 flex-1">
-            <h2 class="truncate text-sm font-semibold text-slate-100">{{ headerTitle }}</h2>
-            <p class="truncate text-[11px] text-slate-400">
-              {{ t('panels.mergerResult.description') }}
-            </p>
-          </div>
-          <StepRestartControl
-            :instance-id="instanceId"
-            :step-index="stepIndex"
-            @restarted="close"
-          />
-          <button
-            class="rounded-md p-1.5 text-slate-400 hover:bg-slate-800 hover:text-slate-200"
-            @click="close"
+  <ResultWindowShell
+    :open="open"
+    :icon="meta?.icon ?? 'i-lucide-git-pull-request'"
+    icon-class="bg-lime-500/15 text-lime-300"
+    :title="headerTitle"
+    :subtitle="t('panels.mergerResult.description')"
+    :step-ref="{ instanceId, stepIndex }"
+    width="3xl"
+    @close="close"
+  >
+    <div class="flex min-h-0 flex-1">
+      <div class="min-w-0 flex-1 overflow-y-auto px-5 py-4">
+        <template v-if="decision">
+          <!-- Decision banner: auto-merged (success) vs awaiting human review (warning). -->
+          <div
+            class="mb-4 flex items-start gap-3 rounded-lg border p-3"
+            :class="
+              merged
+                ? 'border-emerald-800/70 bg-emerald-500/10'
+                : 'border-amber-800/70 bg-amber-500/10'
+            "
+            data-testid="merger-decision"
+            :data-outcome="decision.outcome"
           >
-            <UIcon name="i-lucide-x" class="h-4 w-4" />
-          </button>
-        </header>
-
-        <div class="flex min-h-0 flex-1">
-          <div class="min-w-0 flex-1 overflow-y-auto px-5 py-4">
-            <template v-if="decision">
-              <!-- Decision banner: auto-merged (success) vs awaiting human review (warning). -->
-              <div
-                class="mb-4 flex items-start gap-3 rounded-lg border p-3"
-                :class="
-                  merged
-                    ? 'border-emerald-800/70 bg-emerald-500/10'
-                    : 'border-amber-800/70 bg-amber-500/10'
-                "
-                data-testid="merger-decision"
-                :data-outcome="decision.outcome"
+            <UIcon
+              :name="merged ? 'i-lucide-git-merge' : 'i-lucide-user-round-check'"
+              class="mt-0.5 h-5 w-5 shrink-0"
+              :class="merged ? 'text-emerald-300' : 'text-amber-300'"
+            />
+            <div class="min-w-0">
+              <p
+                class="text-sm font-semibold"
+                :class="merged ? 'text-emerald-200' : 'text-amber-200'"
               >
-                <UIcon
-                  :name="merged ? 'i-lucide-git-merge' : 'i-lucide-user-round-check'"
-                  class="mt-0.5 h-5 w-5 shrink-0"
-                  :class="merged ? 'text-emerald-300' : 'text-amber-300'"
-                />
-                <div class="min-w-0">
-                  <p
-                    class="text-sm font-semibold"
-                    :class="merged ? 'text-emerald-200' : 'text-amber-200'"
-                  >
-                    {{ outcomeText }}
-                  </p>
-                  <p class="mt-0.5 text-[13px] leading-relaxed text-slate-300">{{ reasonText }}</p>
-                </div>
-              </div>
+                {{ outcomeText }}
+              </p>
+              <p class="mt-0.5 text-[13px] leading-relaxed text-slate-300">{{ reasonText }}</p>
+            </div>
+          </div>
 
-              <!-- Scores vs the resolved preset's ceilings. -->
-              <template v-if="axes.length">
-                <h3 class="mb-2 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
-                  {{ t('panels.mergerResult.scores') }}
-                </h3>
-                <div class="space-y-2 rounded-lg border border-slate-800 bg-slate-950/40 p-3">
-                  <div v-for="axis in axes" :key="axis.key" class="flex items-center gap-2">
-                    <span class="w-20 shrink-0 text-xs text-slate-400">{{ axis.label }}</span>
-                    <div class="h-1.5 flex-1 overflow-hidden rounded-full bg-slate-800">
-                      <div
-                        class="h-full rounded-full"
-                        :class="exceeded.has(axis.key) ? 'bg-rose-500' : 'bg-emerald-500'"
-                        :style="{ width: `${Math.round(axis.score * 100)}%` }"
-                      />
-                    </div>
-                    <span
-                      class="w-11 shrink-0 text-end text-xs tabular-nums"
-                      :class="exceeded.has(axis.key) ? 'text-rose-300' : 'text-slate-300'"
-                    >
-                      {{ n(axis.score, { key: 'percent' }) }}
-                    </span>
-                    <span class="w-24 shrink-0 text-end text-[10px] tabular-nums text-slate-500">
-                      {{
-                        t('panels.mergerResult.ceiling', {
-                          value: n(axis.ceiling, { key: 'percent' }),
-                        })
-                      }}
-                    </span>
-                  </div>
+          <!-- Scores vs the resolved preset's ceilings. -->
+          <template v-if="axes.length">
+            <h3 class="mb-2 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
+              {{ t('panels.mergerResult.scores') }}
+            </h3>
+            <div class="space-y-2 rounded-lg border border-slate-800 bg-slate-950/40 p-3">
+              <div v-for="axis in axes" :key="axis.key" class="flex items-center gap-2">
+                <span class="w-20 shrink-0 text-xs text-slate-400">{{ axis.label }}</span>
+                <div class="h-1.5 flex-1 overflow-hidden rounded-full bg-slate-800">
+                  <div
+                    class="h-full rounded-full"
+                    :class="exceeded.has(axis.key) ? 'bg-rose-500' : 'bg-emerald-500'"
+                    :style="{ width: `${Math.round(axis.score * 100)}%` }"
+                  />
                 </div>
-              </template>
-
-              <!-- The agent's prose justification. -->
-              <template v-if="decision.assessment?.rationale">
-                <h3
-                  class="mb-2 mt-4 text-[11px] font-semibold uppercase tracking-wide text-slate-500"
+                <span
+                  class="w-11 shrink-0 text-end text-xs tabular-nums"
+                  :class="exceeded.has(axis.key) ? 'text-rose-300' : 'text-slate-300'"
                 >
-                  {{ t('panels.mergerResult.rationale') }}
-                </h3>
-                <MarkdownProse
-                  :text="decision.assessment.rationale"
-                  class="text-[13px] leading-relaxed text-slate-300"
-                />
-              </template>
-              <p v-else class="text-[13px] italic leading-relaxed text-slate-500">
-                {{ t('panels.mergerResult.noAssessment') }}
-              </p>
-            </template>
+                  {{ n(axis.score, { key: 'percent' }) }}
+                </span>
+                <span class="w-24 shrink-0 text-end text-[10px] tabular-nums text-slate-500">
+                  {{
+                    t('panels.mergerResult.ceiling', {
+                      value: n(axis.ceiling, { key: 'percent' }),
+                    })
+                  }}
+                </span>
+              </div>
+            </div>
+          </template>
 
-            <!-- Pre-structured runs kept only the raw prose output. -->
+          <!-- The agent's prose justification. -->
+          <template v-if="decision.assessment?.rationale">
+            <h3 class="mb-2 mt-4 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
+              {{ t('panels.mergerResult.rationale') }}
+            </h3>
             <MarkdownProse
-              v-else-if="step?.output"
-              :text="step.output"
+              :text="decision.assessment.rationale"
               class="text-[13px] leading-relaxed text-slate-300"
             />
-            <div
-              v-else
-              class="flex h-full flex-col items-center justify-center gap-2 text-center text-slate-400"
-            >
-              <UIcon name="i-lucide-git-pull-request" class="h-8 w-8 opacity-40" />
-              <p class="text-sm">{{ t('panels.mergerResult.noResult') }}</p>
-            </div>
-          </div>
-
-          <!-- Sidebar: shared run metadata. -->
-          <aside
-            class="hidden w-60 shrink-0 flex-col gap-4 border-s border-slate-800 bg-slate-900/50 px-4 py-4 lg:flex"
-          >
-            <StepRunMeta
-              v-if="step"
-              :step="step"
-              :instance-id="instanceId ?? undefined"
-              :step-number="stepIndex === null ? undefined : stepIndex + 1"
-              :total-steps="instance?.steps.length"
-              :run-failed="instance?.status === 'failed'"
-              :failure-at="instance?.failure?.occurredAt"
-            />
-          </aside>
+          </template>
+          <p v-else class="text-[13px] italic leading-relaxed text-slate-500">
+            {{ t('panels.mergerResult.noAssessment') }}
+          </p>
+        </template>
+
+        <!-- Pre-structured runs kept only the raw prose output. -->
+        <MarkdownProse
+          v-else-if="step?.output"
+          :text="step.output"
+          class="text-[13px] leading-relaxed text-slate-300"
+        />
+        <div
+          v-else
+          class="flex h-full flex-col items-center justify-center gap-2 text-center text-slate-400"
+        >
+          <UIcon name="i-lucide-git-pull-request" class="h-8 w-8 opacity-40" />
+          <p class="text-sm">{{ t('panels.mergerResult.noResult') }}</p>
         </div>
       </div>
+
+      <!-- Sidebar: shared run metadata. -->
+      <aside
+        class="hidden w-60 shrink-0 flex-col gap-4 border-s border-slate-800 bg-slate-900/50 px-4 py-4 lg:flex"
+      >
+        <StepRunMeta
+          v-if="step"
+          :step="step"
+          :instance-id="instanceId ?? undefined"
+          :step-number="stepIndex === null ? undefined : stepIndex + 1"
+          :total-steps="instance?.steps.length"
+          :run-failed="instance?.status === 'failed'"
+          :failure-at="instance?.failure?.occurredAt"
+        />
+      </aside>
     </div>
-  </Teleport>
+  </ResultWindowShell>
 </template>

package/app/components/panels/ResultWindowShell.vue

@@ -0,0 +1,141 @@
+<script setup lang="ts">
+// Shared modal shell for the agent-run result windows (slice 5 of the modular-vue
+// adoption — docs/initiatives/modular-vue-adoption.md; progress in
+// docs/initiatives/modular-vue-slice5-progress.md).
+//
+// Every result window (the merger verdict, the tester report, the requirements-review
+// loop, the gates, …) used to hand-roll the SAME modal chrome — `<Teleport>`, a
+// backdrop, a bordered card, a header row with an icon/title/close — and, worse,
+// re-implemented the modal *behaviour* inconsistently: only 2 of ~18 trapped focus, each
+// registered its own global Escape listener, and every one hard-coded `z-50` with no
+// stacking. This shell centralises the chrome AND delegates the behaviour to the upstream
+// `useModalBehavior` (`@modular-vue/core`, the slice-5 overlay-host release): focus-trap
+// + focus-return, body-scroll lock, and a shared overlay STACK so the top overlay closes
+// first on Escape. A window becomes body-only markup wrapped in `<ResultWindowShell>`; it
+// keeps its `useResultView` seam but passes `manageEscape: false` (the shell owns Escape).
+//
+// The pick-one SELECTION of which window is active stays exactly the slice-2
+// `resolveComponentRegistry` in `StepResultViewHost.vue` — this shell only owns the
+// per-window chrome + behaviour, so windows convert one at a time behind it.
+import { computed } from 'vue'
+import { useModalBehavior } from '@modular-vue/core'
+import StepRestartControl from '~/components/panels/StepRestartControl.vue'
+
+/** A pipeline step reference — passed by step-result windows to surface the shared
+ *  "restart from here" control. `StepRestartControl` self-hides for an off-path open
+ *  (null ids), so a block-keyed window simply omits this prop. */
+type StepRef = { instanceId: string | null; stepIndex: number | null }
+
+const props = withDefaults(
+  defineProps<{
+    /** Whether the window is open — drives the modal behaviour's activation. */
+    open: boolean
+    /** Header icon (a `UIcon` name) + its badge colour classes. */
+    icon?: string
+    iconClass?: string
+    /** Header title (the accessible dialog name) + optional secondary line. */
+    title: string
+    subtitle?: string
+    /** Card width bucket + backdrop layout (the two pre-slice-5 chrome variants). */
+    width?: '3xl' | '4xl' | '5xl'
+    variant?: 'stretch' | 'centered'
+    /** Provide on step-result windows to show the shared restart control; omit on gates
+     *  and block-keyed windows (no restart mid-gate / pre-run). */
+    stepRef?: StepRef
+    /** `data-testid` on the dialog root — pass a window's existing id to preserve e2e
+     *  selectors; defaults to `result-window`. */
+    testid?: string
+  }>(),
+  {
+    icon: 'i-lucide-square',
+    iconClass: 'bg-slate-500/15 text-slate-300',
+    subtitle: undefined,
+    width: '3xl',
+    variant: 'stretch',
+    stepRef: undefined,
+    testid: undefined,
+  },
+)
+
+const emit = defineEmits<{ close: [] }>()
+const { t } = useI18n()
+
+function requestClose() {
+  emit('close')
+}
+
+// Managed modal behaviour (focus-trap + return, scroll lock, shared-stack Escape). The
+// window unmounts on close, so deactivation + cleanup fire via `active` going false and
+// unmount — no manual teardown here.
+const { dialogRef } = useModalBehavior({
+  active: () => props.open,
+  onClose: requestClose,
+})
+
+const WIDTH: Record<'3xl' | '4xl' | '5xl', string> = {
+  '3xl': 'max-w-3xl',
+  '4xl': 'max-w-4xl',
+  '5xl': 'max-w-5xl',
+}
+const backdropClass = computed(() => [
+  'fixed inset-0 z-50 flex max-h-[100dvh] justify-center bg-slate-950/70 backdrop-blur-sm',
+  props.variant === 'centered' ? 'items-center p-4' : 'items-stretch',
+])
+const panelClass = computed(() => [
+  'flex w-full flex-col overflow-hidden rounded-2xl border border-slate-800 bg-slate-900 shadow-2xl',
+  WIDTH[props.width],
+  props.variant === 'centered' ? 'max-h-[90dvh]' : 'm-4',
+])
+</script>
+
+<template>
+  <Teleport to="body">
+    <div
+      v-if="open"
+      :class="backdropClass"
+      data-testid="result-window-backdrop"
+      @click.self="requestClose"
+    >
+      <div
+        ref="dialogRef"
+        tabindex="-1"
+        :class="panelClass"
+        role="dialog"
+        aria-modal="true"
+        :aria-label="title"
+        :data-testid="testid ?? 'result-window'"
+      >
+        <header class="flex items-center gap-3 border-b border-slate-800 px-5 py-3">
+          <span
+            class="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg"
+            :class="iconClass"
+          >
+            <UIcon :name="icon" class="h-4 w-4" />
+          </span>
+          <div class="min-w-0 flex-1">
+            <h2 class="truncate text-sm font-semibold text-slate-100">{{ title }}</h2>
+            <p v-if="subtitle" class="truncate text-[11px] text-slate-400">{{ subtitle }}</p>
+          </div>
+          <!-- Window-specific header content (status badges, counts). -->
+          <slot name="header-extras" />
+          <StepRestartControl
+            v-if="stepRef"
+            :instance-id="stepRef.instanceId"
+            :step-index="stepRef.stepIndex"
+            @restarted="requestClose"
+          />
+          <button
+            class="rounded-md p-1.5 text-slate-400 hover:bg-slate-800 hover:text-slate-200"
+            data-testid="result-window-close"
+            :aria-label="t('common.close')"
+            @click="requestClose"
+          >
+            <UIcon name="i-lucide-x" class="h-4 w-4" />
+          </button>
+        </header>
+        <!-- The window body. -->
+        <slot />
+      </div>
+    </div>
+  </Teleport>
+</template>

package/app/components/pipeline/PipelineProgress.vue

@@ -300,6 +300,8 @@ const ITEM_ICON: Record<string, string> = {
         >
           <div
             class="group flex cursor-pointer items-center gap-2"
+            data-testid="pipeline-step"
+            :data-step-kind="s.agentKind"
             :title="
               s.output
                 ? t('pipeline.progress.viewDetailsOutput')

package/app/composables/useResultView.ts

@@ -18,10 +18,18 @@
  * review windows) can flush it in one place instead of every caller having to remember to.
  * It runs synchronously; if it kicks off async work it must capture whatever it needs first,
  * because `blockId`/the derived state go null the moment the view closes.
+ *
+ * `manageEscape` (default `true`) owns the global Escape-to-close listener. A window that
+ * renders through `ResultWindowShell` (slice 5 of the modular-vue adoption) passes `false`:
+ * the shell's `useModalBehavior` owns Escape via the shared overlay stack (so the top
+ * overlay closes first, and focus/scroll are managed too), and a second listener here would
+ * double-fire `close`. Un-converted windows keep the default so they still close on Escape.
+ * Remove this option once every result window is on the shell (the listener moves out
+ * entirely).
  */
 export function useResultView(
   viewId: string,
-  opts?: { onOpen?: (blockId: string) => void; onClose?: () => void },
+  opts?: { onOpen?: (blockId: string) => void; onClose?: () => void; manageEscape?: boolean },
 ) {
   const ui = useUiStore()
 
@@ -42,8 +50,10 @@ export function useResultView(
   function onKey(e: KeyboardEvent) {
     if (e.key === 'Escape' && open.value) close()
   }
-  onMounted(() => window.addEventListener('keydown', onKey))
-  onBeforeUnmount(() => window.removeEventListener('keydown', onKey))
+  if (opts?.manageEscape !== false) {
+    onMounted(() => window.addEventListener('keydown', onKey))
+    onBeforeUnmount(() => window.removeEventListener('keydown', onKey))
+  }
 
   // The load-on-open contract: fire immediately on mount and on any later block switch.
   if (opts?.onOpen) {

package/app/stores/auth.ts

@@ -6,6 +6,7 @@ import type {
 import { defineStore } from 'pinia'
 import { computed, ref } from 'vue'
 import type { AuthUser } from '~/types/domain'
+import { retryWhileBackendUnreachable } from '~/utils/backendReady'
 
 /**
  * "Login with GitHub" session state. The backend mints a signed session token
@@ -184,7 +185,10 @@ export const useAuthStore = defineStore(
       // which must be exchanged — not stored as a local token by `consumeRedirectToken`).
       if (!(await maybeConnectMothership())) consumeRedirectToken()
       try {
-        const config = await api.getAuthConfig()
+        // Tolerate a cold-start race: when the SPA and backend boot together, this first call
+        // can beat the backend's listener by a second or two. Retry a not-listening-yet socket
+        // (the gate keeps showing its spinner) instead of degrading to the unreachable screen.
+        const config = await retryWhileBackendUnreachable(() => api.getAuthConfig())
         required.value = config.enabled
         if (config.providers) providers.value = config.providers
         patProviders.value = config.patLogin?.providers ?? []

package/app/stores/workspace.ts

@@ -35,6 +35,7 @@ import { useGitHubStore } from '~/stores/github'
 import { useFragmentsStore } from '~/stores/fragments'
 import { useProviderConnectionsStore } from '~/stores/providerConnections'
 import { markBoot } from '~/utils/bootMarks'
+import { retryWhileBackendUnreachable } from '~/utils/backendReady'
 
 /**
  * Owns the active workspace and bootstraps the app against the backend. On load
@@ -207,7 +208,10 @@ export const useWorkspaceStore = defineStore(
           useAccountsStore()
             .load()
             .catch(() => {}),
-          api.listWorkspaces(),
+          // Retry a not-listening-yet backend (cold-start race) before surfacing the
+          // unreachable screen. This gates the rest of init, so once it resolves the
+          // backend is up and the speculative/follow-up snapshot fetches succeed too.
+          retryWhileBackendUnreachable(() => api.listWorkspaces()),
         ])
         markBoot('workspaces-listed')
         workspaces.value = workspaceList

package/app/utils/backendReady.spec.ts

@@ -0,0 +1,69 @@
+import { SchemaValidationError } from '@toad-contracts/core'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { ApiError } from '~/composables/api/errors'
+import { isBackendUnreachable, retryWhileBackendUnreachable } from '~/utils/backendReady'
+
+// The cold-start race: the SPA's first fetch can beat the backend's listener, throwing a
+// status-less network fault. These lock in that we wait THAT out (with a deadline) but
+// surface a real HTTP error response — a live-but-erroring backend — immediately.
+
+describe('isBackendUnreachable', () => {
+  it('is true for a status-less network fault', () => {
+    expect(isBackendUnreachable(new Error('Failed to fetch'))).toBe(true)
+  })
+
+  it('is false for an HTTP error response (the backend answered)', () => {
+    expect(isBackendUnreachable(new ApiError(500, {}))).toBe(false)
+    expect(isBackendUnreachable({ status: 503 })).toBe(false)
+  })
+
+  it('is false for a schema-validation failure (a deterministic answer, not a dead socket)', () => {
+    // The backend answered but its body (or our request) didn't match the contract — retrying
+    // can never clear it, so it must surface at once rather than wait out the deadline.
+    expect(isBackendUnreachable(new SchemaValidationError([]))).toBe(false)
+  })
+})
+
+describe('retryWhileBackendUnreachable', () => {
+  afterEach(() => vi.useRealTimers())
+
+  it('returns the first result without waiting when the backend answers', async () => {
+    const fn = vi.fn(async () => 'ok')
+    await expect(retryWhileBackendUnreachable(fn)).resolves.toBe('ok')
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('retries a not-listening-yet backend, then succeeds', async () => {
+    vi.useFakeTimers()
+    let calls = 0
+    const fn = vi.fn(async () => {
+      if (++calls < 3) throw new Error('connection refused') // status-less
+      return 'ok'
+    })
+    const promise = retryWhileBackendUnreachable(fn)
+    await vi.advanceTimersByTimeAsync(10_000)
+    await expect(promise).resolves.toBe('ok')
+    expect(fn).toHaveBeenCalledTimes(3)
+  })
+
+  it('rethrows an HTTP error response immediately (no retry)', async () => {
+    const fn = vi.fn(async () => {
+      throw new ApiError(500, {})
+    })
+    await expect(retryWhileBackendUnreachable(fn)).rejects.toBeInstanceOf(ApiError)
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('gives up and rethrows the last fault once the deadline passes', async () => {
+    vi.useFakeTimers()
+    const fn = vi.fn(async () => {
+      throw new Error('down')
+    })
+    const rejects = expect(retryWhileBackendUnreachable(fn, { deadlineMs: 1_000 })).rejects.toThrow(
+      'down',
+    )
+    await vi.advanceTimersByTimeAsync(2_000)
+    await rejects
+    expect(fn.mock.calls.length).toBeGreaterThan(1)
+  })
+})

package/app/utils/backendReady.ts

@@ -0,0 +1,54 @@
+import { SchemaValidationError } from '@toad-contracts/core'
+import { apiErrorStatus } from '~/composables/api/errors'
+
+/**
+ * True only for a not-listening-yet backend — a connection-level fault (connection refused /
+ * reset / DNS) that throws before any HTTP round-trip completes, so it carries neither an HTTP
+ * status nor schema issues. Everything else is a real, deterministic answer that retrying can
+ * never clear, so it must surface at once, not loop:
+ *
+ * - An HTTP RESPONSE arrived — a declared non-2xx (`ApiError`) or an undeclared status
+ *   (`UnexpectedResponseError`); both carry a `statusCode`, so `apiErrorStatus` returns it.
+ * - A `SchemaValidationError` — the backend answered but its body (or our own request) didn't
+ *   match the contract, i.e. a version skew / client bug, NOT a dead socket.
+ */
+export function isBackendUnreachable(error: unknown): boolean {
+  if (error instanceof SchemaValidationError) return false
+  return apiErrorStatus(error) === undefined
+}
+
+export interface BackendRetryOptions {
+  /** Total wall-clock budget before we give up and rethrow (default 15s). */
+  deadlineMs?: number
+  /** First backoff delay; doubles each attempt up to {@link BackendRetryOptions.maxDelayMs}. */
+  baseDelayMs?: number
+  /** Backoff ceiling (default 2s). */
+  maxDelayMs?: number
+}
+
+/**
+ * Run `fn`, retrying while the backend is merely not-listening-yet (see
+ * {@link isBackendUnreachable}) with exponential backoff, up to a wall-clock deadline.
+ *
+ * This exists for the cold-open race: when the frontend and backend are started together,
+ * the SPA's first fetch can beat the backend's listener by a second or two. A single attempt
+ * would strand the board on the "Can't reach the backend" screen until a manual reload, even
+ * though the backend comes up moments later. An HTTP error response (any status) is a real
+ * answer, so it rethrows immediately rather than looping — we only wait out a dead socket.
+ */
+export async function retryWhileBackendUnreachable<T>(
+  fn: () => Promise<T>,
+  { deadlineMs = 15_000, baseDelayMs = 300, maxDelayMs = 2_000 }: BackendRetryOptions = {},
+): Promise<T> {
+  const start = Date.now()
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await fn()
+    } catch (error) {
+      const elapsed = Date.now() - start
+      if (!isBackendUnreachable(error) || elapsed >= deadlineMs) throw error
+      const delay = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt, deadlineMs - elapsed)
+      await new Promise<void>((resolve) => setTimeout(resolve, delay))
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.136.0",
+  "version": "0.137.0",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",
@@ -18,12 +18,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@modular-frontend/core": "^0.4.0",
-    "@modular-vue/core": "^1.3.0",
+    "@modular-frontend/core": "^0.5.0",
+    "@modular-vue/core": "^1.4.0",
     "@modular-vue/journeys": "^1.3.0",
     "@modular-vue/nuxt": "^0.4.0",
     "@modular-vue/runtime": "^1.4.1",
-    "@modular-vue/vue": "^1.3.0",
+    "@modular-vue/vue": "^1.4.0",
     "@nuxt/ui": "^4.10.0",
     "@nuxtjs/i18n": "^10.4.1",
     "@pinia/nuxt": "^1.0.1",