@cat-factory/app 0.190.0 → 0.191.0

package/README.md

@@ -54,6 +54,16 @@ over the WebSocket. How that sync works is written up in
 | `types/`          | TypeScript domain unions (`domain.ts`) and wire types mirroring the contracts.                                                                        |
 | `utils/`          | Small pure helpers.                                                                                                                                   |
 
+### Always import a layer component explicitly
+
+**Import a component under `components/` by path before using it in a template.** Do not lean on Nuxt's auto-registration. This layer sets no `components` config, so the default `pathPrefix: true` applies and a component is registered under its path-prefixed name: `components/panels/StepEffortReport.vue` becomes `PanelsStepEffortReport`, and a bare `<StepEffortReport>` matches nothing.
+
+Some bare tags do work, which is exactly what makes this worth writing down. Nuxt drops a directory segment the filename already repeats, so `pipeline/PipelinePicker.vue` registers as `PipelinePicker` and resolves bare, while `pipeline/AgentKindIcon.vue` in the same folder registers as `PipelineAgentKindIcon` and does not. Whether a tag resolves therefore depends on a coincidence between a folder name and a filename, and renaming either end breaks the tag with no error. An explicit import does not care.
+
+The failure is silent, which is why this is a rule rather than a preference. An unresolved tag warns in dev and then renders nothing, so a built SPA has a hole where the component should be. Nothing catches it: not typecheck, not the unit tests, not the e2e suite, and not the user, who reads it as a backend returning no data. Seven components had shipped this way.
+
+`scripts/check-component-imports.mjs` enforces it (CI's `repo-guards` job). If a panel section is missing and the data looks right, check the import first.
+
 ## Interface modes (basic / advanced)
 
 The SPA renders at one of two **interface tiers**. `basic` (the default) is the everyday

package/app/components/environments/EnvironmentSetupWizard.vue

@@ -17,6 +17,7 @@
 import { computed } from 'vue'
 import { JourneyHost, JourneyOutlet } from '@modular-vue/journeys'
 import { environmentSetupHandle } from '~/modular/journeys/environmentSetup'
+import EnvSetupStepper from '~/components/environments/EnvSetupStepper.vue'
 
 const ui = useUiStore()
 const { t } = useI18n()

package/app/components/layout/InfraSetupBanner.vue

@@ -22,17 +22,36 @@
 // account that also has no storage — an accepted trade-off (the setting stays reachable from
 // account settings, and the SESSION dismissal re-nags on the next load regardless).
 //
-// Freshness note: `infraSetup` is a server projection recomputed only on snapshot (re)load, so a
-// banner clears on the next board load after the operator configures the area via the deep-link,
-// not the instant the config panel saves.
+// Two KINDS of card share this surface, and the difference drives the dismissal fork:
+//   - a setup gap (`not_defined`) is a stable operator decision, so both dismissals are offered;
+//   - an OUTAGE (`unreachable` — configured, but the reachability watcher's live probe can't reach
+//     it) is a health state, so ONLY the session dismissal is offered. A permanent "don't notify me
+//     again" on a transient failure would let one click silence every future outage, and the outage
+//     that matters is always the next one. `isInfraSetupHealthStatus` (contracts) is the single
+//     definition both this component and the store's re-nag logic key off.
+//
+// BOTH dismissals are keyed by the CLAIM, never by the area alone, because the two cards say
+// different things about the same area: silencing "you haven't configured this" must not also
+// silence the outage card raised after the operator configures it and the provider then dies.
+//
+// Freshness note: a setup gap clears on the next board load after the operator configures the area
+// via the deep-link, not the instant the config panel saves — the projection is recomputed on
+// snapshot (re)load. An OUTAGE is different: it arrives and clears live, pushed as an `infraSetup`
+// event by the watcher and applied by `workspace.patchInfraSetup`.
 import { useLocalStorage } from '@vueuse/core'
 import { computed } from 'vue'
 // The localStorage key holding the permanent per-user dismissals lives in `@cat-factory/contracts`
 // (a dependency-free package the SPA and the e2e suite both import), so the key + shape can't drift
 // between this component and the e2e seed in `backend/internal/e2e/tests/helpers.ts` (`pinWorkspace`).
-import { INFRA_SETUP_DISMISSED_STORAGE_KEY } from '@cat-factory/contracts'
+import {
+  INFRA_SETUP_DISMISSED_STORAGE_KEY,
+  type InfraSetupProbedArea,
+  isInfraSetupHealthStatus,
+  isInfraSetupProbedArea,
+} from '@cat-factory/contracts'
 import type { DropdownMenuItem } from '@nuxt/ui'
-import type { InfraSetupArea } from '~/types/domain'
+import type { InfraSetupArea, InfraSetupStatus } from '~/types/domain'
+import { infraSetupDismissalKey, type InfraSetupCardKind } from '~/utils/infraSetup'
 
 const { t } = useI18n()
 const ui = useUiStore()
@@ -75,6 +94,18 @@ const AREA_META: Record<
   },
 }
 
+// Outage titles are keyed over the PROBED areas only, not over every area: `binaryStorage` has no
+// reachability probe, so an entry for it would be copy that ships in every locale and can never
+// render. Each probed area carries its OWN title rather than interpolating the area name into a
+// shared one — a predicate adjective ("is unreachable") agrees with its subject's gender in most of
+// the locales we ship, so `{area} is unreachable` cannot be translated correctly as one string. The
+// outage BODY and action ARE shared, because neither refers back to the area; each locale's body
+// opens with its own fixed subject noun for exactly that reason.
+const UNREACHABLE_TITLE_KEYS: Record<InfraSetupProbedArea, string> = {
+  agentExecutor: 'layout.infraSetupBanner.agentExecutor.unreachableTitle',
+  ephemeralEnvironments: 'layout.infraSetupBanner.ephemeralEnvironments.unreachableTitle',
+}
+
 // Permanent, per-user dismissals: one shared localStorage record keyed BY user id (so it's
 // scoped to the signed-in user and doesn't leak across accounts on a shared browser). No
 // signed-in user (local/auth-off single-user mode) ⇒ the `local` bucket.
@@ -94,30 +125,64 @@ function dismissPermanently(area: InfraSetupArea) {
   }
 }
 
-const visible = computed<InfraSetupArea[]>(() => {
+/** One rendered card: the area plus which CLAIM it is making about it. */
+interface AreaCard {
+  area: InfraSetupArea
+  /** `outage` for a live-health status — drives the copy, the severity styling and the dismissals. */
+  kind: InfraSetupCardKind
+  /** The failing probe's reason, when this session saw the transition that raised the card. */
+  detail?: string
+}
+
+const visible = computed<AreaCard[]>(() => {
   const status = workspace.infraSetup
   if (!status) return []
-  return AREAS.filter(
-    (area) =>
-      status[area] === 'not_defined' &&
-      !ui.infraSetupSessionDismissed.includes(area) &&
-      !dismissedForUser.value.includes(area),
-  )
+  return AREAS.filter((area) => {
+    const kind = cardKind(status[area])
+    if (!kind) return false
+    // Both dismissals are keyed by the CLAIM, not by the area: silencing "you haven't configured
+    // this" must not also silence "you configured it and it is now down". The permanent dismissal
+    // only ever covers a setup gap (`dismissPermanently` is offered nowhere else).
+    if (ui.infraSetupSessionDismissed.includes(infraSetupDismissalKey(area, kind))) return false
+    return !(kind === 'setup' && dismissedForUser.value.includes(area))
+  }).map((area) => ({
+    area,
+    kind: cardKind(status[area])!,
+    ...(workspace.infraSetupDetails[area] ? { detail: workspace.infraSetupDetails[area] } : {}),
+  }))
 })
 
-// The dismiss dropdown: the product wants the user asked WHICH kind of dismissal on close.
-function dismissMenu(area: InfraSetupArea): DropdownMenuItem[][] {
+/** Which card an area's status raises, or null when it raises none (`configured`/`not_applicable`). */
+function cardKind(status: InfraSetupStatus): InfraSetupCardKind | null {
+  if (isInfraSetupHealthStatus(status)) return 'outage'
+  return status === 'not_defined' ? 'setup' : null
+}
+
+/** The card's title key: the per-area outage title for an outage, else the setup-gap title. */
+function titleKey(card: AreaCard): string {
+  return card.kind === 'outage' && isInfraSetupProbedArea(card.area)
+    ? UNREACHABLE_TITLE_KEYS[card.area]
+    : AREA_META[card.area].titleKey
+}
+
+/**
+ * The dismiss dropdown: the product wants the user asked WHICH kind of dismissal on close. An
+ * outage offers the session option ONLY — see the fork note at the top of this file.
+ */
+function dismissMenu(card: AreaCard): DropdownMenuItem[][] {
+  const session = {
+    label: t('layout.infraSetupBanner.dismiss.session'),
+    icon: 'i-lucide-clock',
+    onSelect: () => ui.dismissInfraSetupForSession(card.area, card.kind),
+  }
+  if (card.kind === 'outage') return [[session]]
   return [
     [
-      {
-        label: t('layout.infraSetupBanner.dismiss.session'),
-        icon: 'i-lucide-clock',
-        onSelect: () => ui.dismissInfraSetupForSession(area),
-      },
+      session,
       {
         label: t('layout.infraSetupBanner.dismiss.permanent'),
         icon: 'i-lucide-bell-off',
-        onSelect: () => dismissPermanently(area),
+        onSelect: () => dismissPermanently(card.area),
       },
     ],
   ]
@@ -135,42 +200,81 @@ function dismissMenu(area: InfraSetupArea): DropdownMenuItem[][] {
       role="status"
       aria-live="polite"
     >
+      <!-- An OUTAGE reads red, a setup gap amber: one is something breaking now, the other is
+           something never switched on, and a reader has to be able to tell at a glance. -->
       <div
-        v-for="area in visible"
-        :key="area"
-        class="pointer-events-auto w-full max-w-3xl rounded-2xl border-2 border-amber-500/70 bg-amber-950/95 p-5 shadow-2xl backdrop-blur"
-        :data-testid="`infra-setup-banner-${area}`"
+        v-for="card in visible"
+        :key="card.area"
+        class="pointer-events-auto w-full max-w-3xl rounded-2xl border-2 p-5 shadow-2xl backdrop-blur"
+        :class="
+          card.kind === 'outage'
+            ? 'border-red-500/70 bg-red-950/95'
+            : 'border-amber-500/70 bg-amber-950/95'
+        "
+        :data-testid="`infra-setup-banner-${card.area}`"
+        :data-infra-status="card.kind === 'outage' ? 'unreachable' : 'not_defined'"
       >
         <div class="flex items-start gap-4">
-          <UIcon :name="AREA_META[area].icon" class="mt-0.5 h-9 w-9 shrink-0 text-amber-400" />
+          <UIcon
+            :name="card.kind === 'outage' ? 'i-lucide-plug-zap' : AREA_META[card.area].icon"
+            class="mt-0.5 h-9 w-9 shrink-0"
+            :class="card.kind === 'outage' ? 'text-red-400' : 'text-amber-400'"
+          />
           <div class="min-w-0 flex-1">
             <div class="flex items-start justify-between gap-3">
-              <h2 class="text-lg font-semibold text-amber-100">
-                {{ t(AREA_META[area].titleKey) }}
+              <h2
+                class="text-lg font-semibold"
+                :class="card.kind === 'outage' ? 'text-red-100' : 'text-amber-100'"
+              >
+                {{ t(titleKey(card)) }}
               </h2>
-              <UDropdownMenu :items="dismissMenu(area)" :content="{ align: 'end' }">
+              <UDropdownMenu :items="dismissMenu(card)" :content="{ align: 'end' }">
                 <UButton
                   color="neutral"
                   variant="ghost"
                   size="xs"
                   icon="i-lucide-x"
                   :aria-label="t('common.close')"
-                  :data-testid="`infra-setup-dismiss-${area}`"
+                  :data-testid="`infra-setup-dismiss-${card.area}`"
                 />
               </UDropdownMenu>
             </div>
-            <p class="mt-1 text-sm text-amber-200/90">
-              {{ t(AREA_META[area].bodyKey) }}
+            <p
+              class="mt-1 text-sm"
+              :class="card.kind === 'outage' ? 'text-red-200/90' : 'text-amber-200/90'"
+            >
+              {{
+                card.kind === 'outage'
+                  ? t('layout.infraSetupBanner.unreachable.body')
+                  : t(AREA_META[card.area].bodyKey)
+              }}
+            </p>
+            <!-- The failing probe's OWN reason, when this session saw the transition that raised the
+                 card: a refused connection, a rejected token and a timeout need different fixes, and
+                 the generic body cannot tell them apart. Absent after a reload (it rides the live
+                 event, never the deduped notification), so it is an addition to the copy above and
+                 never the only thing that explains the card. -->
+            <p
+              v-if="card.detail"
+              class="mt-2 truncate font-mono text-xs text-red-300/80"
+              :title="card.detail"
+              :data-testid="`infra-setup-detail-${card.area}`"
+            >
+              {{ t('layout.infraSetupBanner.unreachable.reason', { detail: card.detail }) }}
             </p>
             <div class="mt-4">
               <UButton
-                color="warning"
+                :color="card.kind === 'outage' ? 'error' : 'warning'"
                 variant="solid"
                 icon="i-lucide-settings"
-                :data-testid="`infra-setup-configure-${area}`"
-                @click="AREA_META[area].onConfigure()"
+                :data-testid="`infra-setup-configure-${card.area}`"
+                @click="AREA_META[card.area].onConfigure()"
               >
-                {{ t(AREA_META[area].actionKey) }}
+                {{
+                  card.kind === 'outage'
+                    ? t('layout.infraSetupBanner.unreachable.action')
+                    : t(AREA_META[card.area].actionKey)
+                }}
               </UButton>
             </div>
           </div>

package/app/components/layout/NotificationsInbox.vue

@@ -88,6 +88,10 @@ const META: Record<Notification['type'], { icon: string; color: Accent }> = {
   // sealed). Not block-scoped; "act" drops the listed stale ciphertexts so they can be re-entered
   // (or restore the previous key to recover them instead).
   key_drift: { icon: 'i-lucide-key-round', color: 'error' },
+  // A configured infrastructure connection stopped answering its live probe. Not block-scoped and
+  // nothing to act on from here — the fix is on the provider's side, and the card clears itself when
+  // the reachability watcher sees it answer again; "act" just marks it read.
+  infra_unreachable: { icon: 'i-lucide-plug-zap', color: 'error' },
 }
 
 // Per-type primary-action label. An exhaustive Record keyed off the notification
@@ -114,6 +118,7 @@ const ACTION_KEYS: Record<Notification['type'], string> = {
   platform_health: 'layout.notifications.action.platform_health',
   budget_paused: 'layout.notifications.action.budget_paused',
   key_drift: 'layout.notifications.action.key_drift',
+  infra_unreachable: 'layout.notifications.action.infra_unreachable',
 }
 
 /** The localized primary-action label for a notification (te()-guarded against a

package/app/components/panels/AgentStepDetail.vue

@@ -6,6 +6,8 @@ import { agentKindMeta } from '~/utils/catalog'
 import StepRestartControl from '~/components/panels/StepRestartControl.vue'
 import StepMetadataCard from '~/components/panels/StepMetadataCard.vue'
 import StepTestReport from '~/components/panels/StepTestReport.vue'
+import StepEffortReport from '~/components/panels/StepEffortReport.vue'
+import StepFragmentAdherence from '~/components/panels/StepFragmentAdherence.vue'
 import EnvironmentStatusPanel from '~/components/environments/EnvironmentStatusPanel.vue'
 import FrontendBindingsResolved from '~/components/panels/inspector/FrontendBindingsResolved.vue'
 import { UI_TESTER_AGENT_KIND } from '@cat-factory/contracts'

package/app/components/panels/ReportsPanel.vue

@@ -16,6 +16,7 @@ import {
   segmentPct,
   trendMagnitude,
 } from './ReportsPanel.logic'
+import ReportsSpendBreakdown from '~/components/panels/ReportsSpendBreakdown.vue'
 
 // Reports: cross-cutting usage analytics for the active account — where the spend and the
 // work actually go. Spend per model and agent kind, spend + run activity per workspace /

package/app/components/panels/inspector/TaskRunSettings.vue

@@ -8,6 +8,7 @@ import { showOverrideField } from '~/utils/uiMode'
 import InspectorSection from '~/components/panels/inspector/InspectorSection.vue'
 import RiskPolicyPicker from '~/components/riskPolicy/RiskPolicyPicker.vue'
 import TaskAprioriBranches from '~/components/panels/inspector/TaskAprioriBranches.vue'
+import DocReferenceRepos from '~/components/panels/inspector/DocReferenceRepos.vue'
 
 const props = defineProps<{ block: Block }>()
 

package/app/components/pipeline/PipelinePreview.vue

@@ -12,6 +12,7 @@ import { computed } from 'vue'
 import type { Pipeline } from '~/types/domain'
 import { agentKindMeta } from '~/utils/catalog'
 import { pipelineDisplaySteps, pipelineGateCount } from '~/utils/pipeline'
+import AgentKindIcon from '~/components/pipeline/AgentKindIcon.vue'
 
 const props = defineProps<{ pipeline: Pipeline }>()
 const { t } = useI18n()

package/app/components/prReview/PrReviewWindow.vue

@@ -24,6 +24,7 @@ import { subtaskIconClass } from '~/utils/pipelineRender'
 import { activeChunkLabels, chunkReviewPercent, hasNoSlicePlan } from '~/utils/prReviewProgress'
 import ResultWindowShell from '~/components/panels/ResultWindowShell.vue'
 import StepRunMeta from '~/components/panels/StepRunMeta.vue'
+import StepFragmentAdherence from '~/components/panels/StepFragmentAdherence.vue'
 
 const execution = useExecutionStore()
 const board = useBoardStore()

package/app/components/settings/RiskPolicyPanel.vue

@@ -12,6 +12,7 @@ import {
   RISK_POLICY_CEILING_FIELD,
   type RiskPolicyAxis,
 } from '~/utils/riskPolicy'
+import MergeClassRulesEditor from '~/components/settings/MergeClassRulesEditor.vue'
 
 const { t } = useI18n()
 

package/app/components/slack/SlackPanel.vue

@@ -43,6 +43,7 @@ const ROUTABLE = computed<{ type: NotificationType; label: string }[]>(() => [
   { type: 'pr_review_ready', label: t('slack.routable.pr_review_ready') },
   { type: 'initiative', label: t('slack.routable.initiative') },
   { type: 'platform_health', label: t('slack.routable.platform_health') },
+  { type: 'infra_unreachable', label: t('slack.routable.infra_unreachable') },
 ])
 
 /** Notification-role options for a mapped member (drives who gets @-mentioned). */
@@ -75,6 +76,7 @@ const routes = reactive<Record<NotificationType, SlackRoute>>({
   budget_paused: { enabled: false, channel: '' },
   // In-app only (not in ROUTABLE), but the map is exhaustive over the type.
   key_drift: { enabled: false, channel: '' },
+  infra_unreachable: { enabled: false, channel: '' },
 })
 const mentionsEnabled = ref(false)
 // Editable member rows carry a client-only stable `uid` (see `slackMemberMapping`) so

package/app/composables/api/client.spec.ts

@@ -0,0 +1,50 @@
+import type { ApiContract } from '@toad-contracts/core'
+import { describe, expect, it } from 'vitest'
+import { type SendParams, withoutUndefinedQueryParams } from '~/composables/api/client'
+
+// An omitted optional query param used to reach the server as `key=`: the contract client
+// serialises with `fast-querystring`, whose `stringify({ blockId: undefined })` is `'blockId='`,
+// and request validation waves the key through because `v.optional(...)` accepts `undefined`. On
+// `listTasksContract`, whose `blockId` carries a `minLength(1)`, that made every unscoped
+// `listTasks()` a guaranteed 400. These lock the strip in.
+
+// The helper is contract-generic and only ever reads `queryParams`, so the cases below describe
+// request params structurally rather than picking a real contract per shape.
+type Params = Record<string, unknown>
+const strip = (params: Params): Params =>
+  withoutUndefinedQueryParams(params as SendParams<ApiContract>) as Params
+
+describe('withoutUndefinedQueryParams', () => {
+  it('drops undefined-valued query keys so they never reach the query string', () => {
+    const out = strip({ pathPrefix: '/workspaces/ws_1', queryParams: { blockId: undefined } })
+    expect(out.queryParams).toEqual({})
+  })
+
+  // The guard against "fix" it with a falsy check: 0, false and '' are all values a caller
+  // deliberately sent, and only `undefined` means absent.
+  it('keeps defined values, including falsy ones a caller meant to send', () => {
+    const out = strip({ queryParams: { blockId: 'blk_1', page: 0, all: false, q: '' } })
+    expect(out.queryParams).toEqual({ blockId: 'blk_1', page: 0, all: false, q: '' })
+  })
+
+  it('drops only the undefined keys from a mixed set', () => {
+    const out = strip({ queryParams: { window: '7d', workspaceId: undefined } })
+    expect(out.queryParams).toEqual({ window: '7d' })
+  })
+
+  it('leaves other request params untouched', () => {
+    const params = {
+      pathPrefix: '/workspaces/ws_1',
+      pathParams: { source: 'jira' },
+      body: { a: 1 },
+    }
+    expect(strip(params)).toEqual(params)
+  })
+
+  it('returns the same object when there is nothing to strip', () => {
+    const params = { queryParams: { blockId: 'blk_1' } }
+    expect(strip(params)).toBe(params)
+    const noQuery = { pathPrefix: '/workspaces/ws_1' }
+    expect(strip(noQuery)).toBe(noQuery)
+  })
+})

package/app/composables/api/client.ts

@@ -71,6 +71,31 @@ export function createApiClient(): WretchInstance {
   ])
 }
 
+/**
+ * Drop query keys whose value is `undefined`, so an omitted optional param is absent from the
+ * query string instead of present-but-empty.
+ *
+ * `sendByApiContract` serialises with `fast-querystring`, and `stringify({ blockId: undefined })`
+ * is `'blockId='`. Request validation does not catch it, because `v.optional(...)` accepts
+ * `undefined` and the key only becomes empty on the way out. The server then validates the parsed
+ * `''`, so any optional param carrying a `minLength(1)` rejects the whole request with a 400. That
+ * is what made an unscoped `listTasks()` uncallable. Params with no length check are luckier but
+ * still wrong: the handler reads `''` where it asked for absence.
+ *
+ * Stripping at this one chokepoint fixes every contract at once, which is the point. Writing
+ * `queryParams: { foo }` for an optional `foo` is the obvious thing to write and it should work,
+ * rather than each call site remembering to spread the key in conditionally.
+ */
+export function withoutUndefinedQueryParams<T extends ApiContract>(
+  params: SendParams<T>,
+): SendParams<T> {
+  const query = (params as { queryParams?: Record<string, unknown> }).queryParams
+  if (!query) return params
+  const present = Object.entries(query).filter(([, value]) => value !== undefined)
+  if (present.length === Object.keys(query).length) return params
+  return { ...params, queryParams: Object.fromEntries(present) }
+}
+
 /**
  * Send a contract request and unwrap to the success body (or throw the typed error).
  * The public signature preserves per-contract inference for callers; inside,
@@ -82,7 +107,7 @@ export async function sendContract<T extends ApiContract>(
   contract: T,
   params: SendParams<T>,
 ): Promise<SuccessBodyOf<T>> {
-  const outcome = await sendByApiContract(client, contract, params)
+  const outcome = await sendByApiContract(client, contract, withoutUndefinedQueryParams(params))
   if (outcome.error) {
     const error = outcome.error
     // A contract-declared non-2xx is reported as a plain `{ statusCode, headers, body }`

package/app/composables/useWorkspaceStream.ts

@@ -111,6 +111,12 @@ export function useWorkspaceStream() {
       // inspector's "Test environment creation" control shows the live stage + final
       // outcome in place without a refetch. No board block.
       environmentTest.upsert(event.run)
+    } else if (event.type === 'infraSetup') {
+      // The reachability watcher found a configured infrastructure area dead (or answering again) —
+      // patch that one area so the setup banner appears/clears immediately. A full refresh would
+      // pay the whole snapshot aggregate for a one-field delta, and the projection the snapshot
+      // recomputes already folds the same recorded state.
+      workspace.patchInfraSetup(event.area, event.status, event.detail)
     } else if (event.type === 'notification') {
       // A PR needs a merge decision, a pipeline finished, or CI gave up — patch the
       // inbox + per-block badge in place (resolved ones drop out of the inbox).

package/app/stores/ui/modals.ts

@@ -2,6 +2,11 @@ import { ref } from 'vue'
 import type { DocumentSourceKind, InfraSetupArea, TaskSourceKind } from '~/types/domain'
 import type { InfrastructureTab, ProviderConnectionKind } from '~/types/providerConnections'
 import type { PendingContext } from '~/composables/useContextLinking'
+import {
+  infraSetupDismissalKey,
+  type InfraSetupCardKind,
+  type InfraSetupDismissalKey,
+} from '~/utils/infraSetup'
 import {
   DEFAULT_PROVISION_DEEP_LINK_PARAM,
   DEFAULT_PROVISION_DEEP_LINK_VALUE,
@@ -820,18 +825,35 @@ function createAiOnboardingModals() {
   const aiSetupDismissed = ref(false)
   const aiPresetDismissed = ref(false)
 
-  // Infra-setup banner: per-SESSION dismissals, one flag per area, cleared on workspace switch
-  // exactly like the AI-onboarding flags (a dismissal in one workspace must not suppress the
-  // independent prompt for another). The PERMANENT "don't notify me again" dismissal is per-USER
-  // and persists in localStorage from the banner component; this only covers "hide for now".
-  const infraSetupSessionDismissed = ref<InfraSetupArea[]>([])
-  function dismissInfraSetupForSession(area: InfraSetupArea) {
-    if (!infraSetupSessionDismissed.value.includes(area))
-      infraSetupSessionDismissed.value = [...infraSetupSessionDismissed.value, area]
+  // Infra-setup banner: per-SESSION dismissals, cleared on workspace switch exactly like the
+  // AI-onboarding flags (a dismissal in one workspace must not suppress the independent prompt for
+  // another). The PERMANENT "don't notify me again" dismissal is per-USER and persists in
+  // localStorage from the banner component; this only covers "hide for now".
+  //
+  // Keyed by area AND KIND, not by area alone: the two cards an area can raise are different
+  // claims. Dismissing "you haven't configured this" for the session must not also silence the
+  // OUTAGE card that appears after the operator configures it and the provider then dies — the same
+  // asymmetry that makes the permanent dismissal setup-gap-only, one tier down.
+  const infraSetupSessionDismissed = ref<InfraSetupDismissalKey[]>([])
+  function dismissInfraSetupForSession(area: InfraSetupArea, kind: InfraSetupCardKind) {
+    const key = infraSetupDismissalKey(area, kind)
+    if (!infraSetupSessionDismissed.value.includes(key))
+      infraSetupSessionDismissed.value = [...infraSetupSessionDismissed.value, key]
   }
   function resetInfraSetupDismissals() {
     infraSetupSessionDismissed.value = []
   }
+  /**
+   * Drop an area's OUTAGE session dismissal — called when that area RECOVERS, so a transient health
+   * state (`unreachable`) re-nags the next time it fails. Without it, "hide for now" on one outage
+   * would quietly cover every later outage for the rest of the session, which is precisely the
+   * semantics `isInfraSetupHealthStatus` exists to keep away from a health state. The area's
+   * setup-gap dismissal is left alone: recovery says nothing about that claim.
+   */
+  function clearInfraSetupSessionDismissal(area: InfraSetupArea) {
+    const key = infraSetupDismissalKey(area, 'outage')
+    infraSetupSessionDismissed.value = infraSetupSessionDismissed.value.filter((k) => k !== key)
+  }
 
   // Default-test-environment banner: a single per-SESSION dismissal, cleared on workspace switch
   // like the flags above. There is deliberately no PERMANENT dismissal here (unlike the
@@ -889,6 +911,7 @@ function createAiOnboardingModals() {
     infraSetupSessionDismissed,
     dismissInfraSetupForSession,
     resetInfraSetupDismissals,
+    clearInfraSetupSessionDismissal,
     defaultProvisionDismissed,
     dismissDefaultProvision,
     resetDefaultProvisionDismissal,

package/app/stores/workspace/infraSetup.ts

@@ -0,0 +1,77 @@
+import { ref } from 'vue'
+import { applyInfraSetupTransition, isInfraSetupHealthStatus } from '@cat-factory/contracts'
+import type { InfraSetup, InfraSetupArea, InfraSetupStatus } from '~/types/domain'
+
+// The workspace store's infra-setup slice: the per-area setup/health projection the setup banner
+// renders, and the live `infraSetup` event patch the reachability watcher pushes into it. Its own
+// collaborator rather than more lines in the store body, because it is the one slice with RULES
+// (which prior state a probe verdict may overwrite, and what a recovery does to a dismissal) instead
+// of a plain assign-from-snapshot.
+
+/**
+ * Create the infra-setup slice. `hydrate` takes the authoritative projection off a snapshot;
+ * `patchInfraSetup` applies one live transition.
+ */
+export function createInfraSetupState() {
+  /**
+   * Per-area infrastructure-setup status (ephemeral environments / agent executor / binary
+   * storage) from the snapshot, driving the infra-setup banner. Null on an older backend that
+   * doesn't compute it (⇒ no banner).
+   */
+  const infraSetup = ref<InfraSetup | null>(null)
+  /**
+   * The failing probe's own operator-facing reason per area ("connect ECONNREFUSED …", "HTTP 401"),
+   * from the live `infraSetup` event only — a refused connection reads very differently from a
+   * rejected token, and it is the one thing on the banner that says WHY.
+   *
+   * Deliberately NOT on the snapshot: the reason varies between passes and the notification card is
+   * content-deduped, so persisting it there would re-toast the inbox for the whole outage. The
+   * consequence is that a reload mid-outage renders the banner with no reason line, which is honest
+   * (this session never saw the probe) and is why the reason is an ADDITION to the copy rather than
+   * a replacement for it.
+   */
+  const infraSetupDetails = ref<Partial<Record<InfraSetupArea, string>>>({})
+
+  function hydrate(next: InfraSetup | null | undefined) {
+    infraSetup.value = next ?? null
+    // The reasons belong to the live pushes this session observed, so an authoritative snapshot
+    // supersedes them: keeping one would caption a freshly-read status with a stale probe.
+    infraSetupDetails.value = {}
+  }
+
+  /**
+   * Patch ONE infra area's status from a live `infraSetup` event, so the setup banner appears (or
+   * clears) the moment the reachability watcher notices rather than on the next snapshot load.
+   *
+   * A targeted upsert, deliberately not a `refresh()`: this is a one-field delta on a projection
+   * the snapshot recomputes wholesale, and a coalesced full refresh here would pay the ~18-read
+   * aggregate for it. A no-op before the first snapshot has landed — `hydrate` is about to set the
+   * authoritative projection, which already carries the recorded outage.
+   *
+   * The write goes through contracts' `applyInfraSetupTransition`, the SAME rule the backend's
+   * snapshot fold uses, so live and reloaded state cannot disagree: only a `configured` area may
+   * become `unreachable`. Assigning unconditionally (as this once did) rendered a red "check that
+   * the service is running" banner over a `not_applicable`/`not_defined` area, which then vanished
+   * on the next reload — a banner that contradicts the projection is worse than a late one.
+   *
+   * Recovering an area also drops its OUTAGE session dismissal, so a health state re-nags when it
+   * recurs (see `isInfraSetupHealthStatus`): without this, dismissing one outage would silence the
+   * next one for the rest of the session.
+   */
+  function patchInfraSetup(area: InfraSetupArea, status: InfraSetupStatus, detail?: string) {
+    const current = infraSetup.value
+    if (!current) return
+    const next = applyInfraSetupTransition(current, area, status)
+    // Refused by the shared rule (the projection out-ranks this probe), so nothing about the area
+    // changed and its reason must not be captioned onto a status it does not describe.
+    if (next === current) return
+    infraSetup.value = next
+    infraSetupDetails.value = { ...infraSetupDetails.value, [area]: detail }
+    // `useUiStore` is resolved through the auto-import at CALL time, as it was in the store body
+    // this moved out of: the ui store is only needed on a recovery, and reaching for it lazily keeps
+    // this slice constructible before pinia has that store (and stubbable in the store unit tests).
+    if (!isInfraSetupHealthStatus(status)) useUiStore().clearInfraSetupSessionDismissal(area)
+  }
+
+  return { infraSetup, infraSetupDetails, hydrate, patchInfraSetup }
+}