@cat-factory/app 0.236.0 → 0.237.0

package/README.md

@@ -79,6 +79,30 @@ earlier than before takes the entire SPA down at boot, and the unit suite cannot
 (nothing there installs the plugin). Every e2e spec does, because every one of them boots
 the app.
 
+### The persisted board pin is UNVALIDATED until `init()` resolves it
+
+`workspace.workspaceId` is restored from persisted state SYNCHRONOUSLY, before any request fires,
+so every `immediate: true` watcher on it (`pages/index.vue`) runs against an id nothing has
+checked. The pin can name a board that was deleted, or one whose access was revoked while the
+browser held it, and the RBAC gate answers both with a 404 (it hides a denial as a not-found, so
+existence never leaks). `init()` then validates the pin against `GET /workspaces` and re-points it
+at a board the user can actually reach.
+
+Firing the per-board reads on the pin anyway is deliberate: it overlaps them with the workspace
+list instead of queueing them behind it, which is why `init()` fetches the pinned SNAPSHOT
+speculatively too. **What travels with that is the miss.** Each of those boot reads states its own
+tolerance at its own seam (`init`'s `.catch(() => null)`, `github.ensureProbed`'s internal catch,
+`models.prefetchForBoard`), because a 404 there is an expected outcome and not a fault: the
+watcher fires again for the board init resolved, which is the read that counts. A bare
+`void store.load(workspace.workspaceId)` in that chain is an uncaught rejection in a real user's
+browser, and the e2e suite's `pageErrors` fixture fails the spec that boots a session whose access
+was just revoked.
+
+Tolerating the miss is not the same as pretending it succeeded: a dropped load leaves its store
+UNLOADED (`models.loaded` stays false, so `useAiReadiness().ready` is false), which reads as
+unresolved rather than as a board with nothing configured, and leaves the next caller free to
+retry. Pin new boot reads with a store-level unit test (`stores/models.spec.ts`).
+
 ### A backend-DECLARED form renders through `DescriptorFields.vue`
 
 When the backend declares the fields and the SPA only collects them, render them with the shared
@@ -87,12 +111,27 @@ When the backend declares the fields and the SPA only collects them, render them
 surfaces use it: an initiative preset's create form and a reusable operation's per-case form on a
 custom task type (`AddTaskModal`). Adding a third is a `:fields` binding, not a component.
 
+**Grouping is the descriptor's own, through `descriptorFieldSections`**, not a wrapper each surface
+builds: consecutive fields sharing a `section` render under one caption, and the reduction applies
+`showWhen` first, so a section whose every field is hidden renders no caption. Never re-group or
+re-order the fields at a call site, or a form renders in an order its author never wrote.
+
+**A captioned run is rendered FLAT, never as a per-run wrapper element** (`descriptorFormRows`
+carries each run's caption on the field that opens it). Run membership is derived state that shifts
+as `showWhen` reveals fields, while a field's identity does not: nesting the fields inside a wrapper
+re-parents them when a boundary moves, and Vue can only do that by unmounting and remounting. The
+remounted input is typically the one being TYPED INTO, because typing into the trigger is what moved
+the boundary, so it loses focus, caret and IME composition mid-keystroke. Keep every field a sibling
+keyed by `field.key` and the diff MOVES it instead. The same trap as keying any list by index, with a
+worse symptom: `descriptorFields.spec.ts` pins that a reveal preserves every field key.
+
 Four rules travel with it. **Validate with the shared `validateDescriptorFields`** so the submit
 button reflects exactly what the server will refuse, and **submit the shared
 `sanitizeDescriptorFields` result** so a stale answer on a since-hidden `showWhen` field never
-reaches the wire. **The labels are deployment-authored English rendered verbatim**: only the chrome
-around them (a path-invalid message, section captions) is i18n, so no descriptor string enters a
-locale catalog. And **the value-bag rules live in `utils/descriptorFields.ts`, not in the SFC**
+reaches the wire. **Every string a descriptor carries is deployment-authored English rendered
+verbatim**, labels, help, option captions and the `section` grouping captions alike: only the
+platform's own chrome around them (the path-invalid message) is i18n, so no descriptor string enters
+a locale catalog. And **the value-bag rules live in `utils/descriptorFields.ts`, not in the SFC**
 (`defaultDescriptorValues` for the initial values, `setDescriptorValue` / `setDescriptorCheckbox` /
 `toggleDescriptorGroupValue` for one edit): what an edit freezes on an entity is what a unit test
 must be able to reach, and a rule inside a component is only reachable by mounting one.

package/app/components/auth/LoginScreen.vue

@@ -205,7 +205,10 @@ const noSignInMethod = computed(
 </script>
 
 <template>
-  <div class="flex h-screen w-screen items-center justify-center bg-slate-950 text-slate-100">
+  <div
+    class="flex h-screen w-screen items-center justify-center bg-slate-950 text-slate-100"
+    data-testid="login-screen"
+  >
     <div
       class="w-full max-w-sm rounded-xl border border-slate-800 bg-slate-900/80 p-8 backdrop-blur"
     >
@@ -392,6 +395,7 @@ const noSignInMethod = computed(
           icon="i-lucide-at-sign"
           size="lg"
           class="w-full"
+          data-testid="login-email"
         />
         <SecretInput
           v-model="password"
@@ -400,9 +404,17 @@ const noSignInMethod = computed(
           icon="i-lucide-lock"
           size="lg"
           class="w-full"
+          data-testid="login-password"
         />
-        <p v-if="error" class="text-sm text-rose-400">{{ error }}</p>
-        <UButton block size="lg" color="primary" type="submit" :loading="busy">
+        <p v-if="error" class="text-sm text-rose-400" data-testid="login-error">{{ error }}</p>
+        <UButton
+          block
+          size="lg"
+          color="primary"
+          type="submit"
+          :loading="busy"
+          data-testid="login-submit"
+        >
           {{ mode === 'signup' ? t('auth.login.createAccount') : t('auth.login.signIn') }}
         </UButton>
         <p class="text-center text-xs text-slate-400">

package/app/components/auth/UserMenu.vue

@@ -35,6 +35,7 @@ const items = computed<DropdownMenuItem[][]>(() => [
   <UDropdownMenu v-if="auth.user" :items="items" :content="{ side: 'top', align: 'start' }">
     <button
       type="button"
+      data-testid="user-menu"
       :title="collapsed ? auth.user.name || auth.user.login : undefined"
       class="flex w-full items-center gap-2 rounded-lg border border-slate-800 bg-slate-900/60 p-2 text-start transition hover:bg-slate-800/60"
       :class="collapsed ? 'justify-center' : ''"

package/app/components/common/DescriptorFields.vue

@@ -8,16 +8,18 @@
 //
 // It extends `ProviderConnectionTab.vue`'s flat-field pattern with the shapes a declared form needs:
 // `checkbox-group` (multi-select whose value is `string[]`), `path` (a repo-relative dir with inline
-// safety validation), and single-condition `showWhen` visibility. Labels/help/option captions are
-// backend-supplied English (the `describeConfig` convention); only the chrome is i18n.
+// safety validation), single-condition `showWhen` visibility, and `section` grouping captions.
+// Labels/help/option/section captions are backend-supplied English (the `describeConfig`
+// convention); only the chrome is i18n.
 //
 // The model is the typed `DescriptorFieldValues` map (scalars stay strings, `number` a number,
 // `checkbox` a boolean, `checkbox-group` a `string[]`), so it round-trips the wire contract and the
 // shared `validateDescriptorFields` / `sanitizeDescriptorFields` rules unchanged.
 import { computed } from 'vue'
-import { isDescriptorFieldVisible, isSafeRepoDirPath } from '@cat-factory/contracts'
+import { isSafeRepoDirPath } from '@cat-factory/contracts'
 import type { DescriptorField, DescriptorFieldValue, DescriptorFieldValues } from '~/types/domain'
 import {
+  descriptorFormRows,
   descriptorGroupValue,
   setDescriptorCheckbox,
   setDescriptorValue,
@@ -39,12 +41,20 @@ const props = withDefaults(
 const model = defineModel<DescriptorFieldValues>({ required: true })
 const { t } = useI18n()
 
-// Only fields whose `showWhen` holds against the current values are shown; a hidden field's stale
-// value is kept in the model (so re-showing restores it) but the server + client both drop it at
-// sanitize/validate time, so it can never freeze an unvalidated value.
-const visibleFields = computed(() =>
-  props.fields.filter((f) => isDescriptorFieldVisible(f, model.value)),
-)
+// The fields to render, each carrying the section caption that opens its run. Only fields whose
+// `showWhen` holds against the current values are shown; a hidden field's stale value is kept in the
+// model (so re-showing restores it) but the server + client both drop it at sanitize/validate time,
+// so it can never freeze an unvalidated value.
+//
+// The grouping underneath is the shared `descriptorFieldSections`, so a caption spans exactly what
+// one function says it spans, which is the same statement the boot check refuses a declaration
+// against. A form declaring no section is one uncaptioned run, i.e. byte-for-byte the flat column
+// this component always rendered.
+//
+// The rows are FLAT, and the template keeps them siblings keyed by `field.key`, because run
+// membership shifts as `showWhen` reveals fields while a field's identity does not: see
+// `descriptorFormRows` for why a per-run wrapper would remount the input being typed into.
+const rows = computed(() => descriptorFormRows(props.fields, model.value))
 
 // The value-mutation rules live in `utils/descriptorFields.ts` as pure functions over the bag (what
 // an edit does to it, including the drop-when-empty rule that keeps an unset answer from freezing),
@@ -90,76 +100,93 @@ function selectItems(field: DescriptorField) {
 </script>
 
 <template>
-  <div v-if="visibleFields.length" class="space-y-4">
-    <UFormField
-      v-for="field in visibleFields"
-      :key="field.key"
-      :label="field.label"
-      :help="field.help"
-      :required="field.required"
-      :error="pathInvalid(field) ? t('common.pathInvalid') : undefined"
-      :data-testid="`${testidPrefix}-${field.key}`"
-    >
-      <!-- checkbox-group: a vertical list of toggles whose value is the checked option set. -->
-      <div v-if="field.type === 'checkbox-group'" class="space-y-1.5">
-        <UCheckbox
-          v-for="opt in field.options ?? []"
-          :key="opt.value"
-          :model-value="groupValue(field.key).includes(opt.value)"
-          :label="opt.label"
-          :data-testid="`${testidPrefix}-${field.key}-${opt.value}`"
-          @update:model-value="
-            (v: boolean | 'indeterminate') => toggleGroup(field.key, opt.value, v === true)
-          "
-        />
-      </div>
+  <div v-if="rows.length" class="space-y-4">
+    <!-- One keyed fragment per FIELD, never per run: a run's caption rides the field that opens it,
+         so revealing a field re-captions rows in place instead of re-parenting the inputs (which
+         Vue can only do by remounting them, destroying the one being typed into). -->
+    <template v-for="{ field, caption, startsGroup } in rows" :key="field.key">
+      <!-- The section caption, rendered verbatim above its run (deployment-authored English, like
+           the field labels themselves). Its testid is the same on every caption, because a caption
+           is arbitrary Unicode a deployment writes in its own language: a spec addresses one by the
+           TEXT it is asserting about (`getByTestId(...).filter({ hasText })`) rather than by a
+           testid that would have to be slugified to be selectable. -->
+      <p
+        v-if="caption"
+        class="-mb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-400"
+        :class="{ 'pt-2': startsGroup }"
+        :data-testid="`${testidPrefix}-section`"
+      >
+        {{ caption }}
+      </p>
+      <UFormField
+        :label="field.label"
+        :help="field.help"
+        :required="field.required"
+        :error="pathInvalid(field) ? t('common.pathInvalid') : undefined"
+        :class="{ 'pt-2': startsGroup && !caption }"
+        :data-testid="`${testidPrefix}-${field.key}`"
+      >
+        <!-- checkbox-group: a vertical list of toggles whose value is the checked option set. -->
+        <div v-if="field.type === 'checkbox-group'" class="space-y-1.5">
+          <UCheckbox
+            v-for="opt in field.options ?? []"
+            :key="opt.value"
+            :model-value="groupValue(field.key).includes(opt.value)"
+            :label="opt.label"
+            :data-testid="`${testidPrefix}-${field.key}-${opt.value}`"
+            @update:model-value="
+              (v: boolean | 'indeterminate') => toggleGroup(field.key, opt.value, v === true)
+            "
+          />
+        </div>
 
-      <USelect
-        v-else-if="field.type === 'select'"
-        :model-value="stringValue(field.key)"
-        :items="selectItems(field)"
-        class="w-full"
-        :placeholder="field.placeholder"
-        @update:model-value="(v: string) => set(field.key, v)"
-      />
+        <USelect
+          v-else-if="field.type === 'select'"
+          :model-value="stringValue(field.key)"
+          :items="selectItems(field)"
+          class="w-full"
+          :placeholder="field.placeholder"
+          @update:model-value="(v: string) => set(field.key, v)"
+        />
 
-      <USwitch
-        v-else-if="field.type === 'checkbox'"
-        :model-value="boolValue(field.key)"
-        @update:model-value="(v: boolean) => setCheckbox(field, v)"
-      />
+        <USwitch
+          v-else-if="field.type === 'checkbox'"
+          :model-value="boolValue(field.key)"
+          @update:model-value="(v: boolean) => setCheckbox(field, v)"
+        />
 
-      <UTextarea
-        v-else-if="field.type === 'textarea'"
-        :model-value="stringValue(field.key)"
-        :rows="3"
-        autoresize
-        class="w-full"
-        :maxlength="field.maxLength"
-        :placeholder="field.placeholder"
-        @update:model-value="(v: string) => set(field.key, v)"
-      />
+        <UTextarea
+          v-else-if="field.type === 'textarea'"
+          :model-value="stringValue(field.key)"
+          :rows="3"
+          autoresize
+          class="w-full"
+          :maxlength="field.maxLength"
+          :placeholder="field.placeholder"
+          @update:model-value="(v: string) => set(field.key, v)"
+        />
 
-      <UInput
-        v-else-if="field.type === 'number'"
-        :model-value="numberStr(field.key)"
-        type="number"
-        class="w-full font-mono"
-        :placeholder="field.placeholder"
-        @update:model-value="(v: string) => set(field.key, v === '' ? undefined : Number(v))"
-      />
+        <UInput
+          v-else-if="field.type === 'number'"
+          :model-value="numberStr(field.key)"
+          type="number"
+          class="w-full font-mono"
+          :placeholder="field.placeholder"
+          @update:model-value="(v: string) => set(field.key, v === '' ? undefined : Number(v))"
+        />
 
-      <!-- path + text/password (the untyped default): a single-line input. `path`s stay mono. -->
-      <UInput
-        v-else
-        :model-value="stringValue(field.key)"
-        :type="field.type === 'password' ? 'password' : 'text'"
-        class="w-full"
-        :class="{ 'font-mono': field.type === 'path' }"
-        :maxlength="field.maxLength"
-        :placeholder="field.placeholder"
-        @update:model-value="(v: string) => set(field.key, v)"
-      />
-    </UFormField>
+        <!-- path + text/password (the untyped default): a single-line input. `path`s stay mono. -->
+        <UInput
+          v-else
+          :model-value="stringValue(field.key)"
+          :type="field.type === 'password' ? 'password' : 'text'"
+          class="w-full"
+          :class="{ 'font-mono': field.type === 'path' }"
+          :maxlength="field.maxLength"
+          :placeholder="field.placeholder"
+          @update:model-value="(v: string) => set(field.key, v)"
+        />
+      </UFormField>
+    </template>
   </div>
 </template>

package/app/components/layout/WorkspaceMembersSettings.vue

@@ -187,6 +187,7 @@ function memberLabel(userId: string, name?: string | null, email?: string | null
           :key="m.userId"
           class="flex items-center justify-between gap-2 rounded-md bg-slate-800/40 px-2 py-1"
           data-testid="workspace-member-row"
+          :data-user-id="m.userId"
         >
           <span class="truncate">{{ memberLabel(m.userId, m.name, m.email) }}</span>
           <span class="flex shrink-0 items-center gap-2">

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

@@ -333,6 +333,7 @@ const technicalLabel = computed(() => {
               color="neutral"
               icon="i-lucide-git-merge"
               trailing-icon="i-lucide-chevron-down"
+              data-testid="risk-policy-picker-trigger"
             />
           </template>
         </RiskPolicyPicker>

package/app/components/riskPolicy/RiskPolicyPicker.vue

@@ -113,6 +113,9 @@ function choose(id: string) {
 
 <template>
   <UPopover v-model:open="open" :content="{ align: 'start' }">
+    <!-- A consumer that supplies its own `#trigger` must carry `risk-policy-picker-trigger` on it:
+         the popover trigger is `as-child`, so the slotted element REPLACES the default button below
+         and takes its test hook with it (the inspector's icon button is the one such consumer). -->
     <slot name="trigger" :label="triggerLabel">
       <UButton
         color="neutral"

package/app/components/settings/RiskPolicyPanel.vue

@@ -282,7 +282,7 @@ async function create() {
 </script>
 
 <template>
-  <div class="space-y-4">
+  <div class="space-y-4" data-testid="risk-policy-panel">
     <i18n-t
       keypath="settings.riskPolicy.intro"
       tag="p"
@@ -298,6 +298,8 @@ async function create() {
       v-for="p in store.presets"
       :key="p.id"
       class="rounded-lg border border-slate-700 bg-slate-800/40 p-3"
+      data-testid="risk-policy-row"
+      :data-policy-id="p.id"
     >
       <div class="mb-3 flex items-center gap-2">
         <UInput
@@ -478,6 +480,7 @@ async function create() {
             v-model="draft.name"
             size="sm"
             :placeholder="t('settings.riskPolicy.create.namePlaceholder')"
+            data-testid="risk-policy-create-name"
           />
         </label>
         <label class="block w-20">
@@ -490,19 +493,34 @@ async function create() {
             :min="0"
             :max="100"
             size="sm"
+            data-testid="risk-policy-create-complexity"
           />
         </label>
         <label class="block w-20">
           <span class="mb-1 block text-[10px] uppercase tracking-wide text-slate-500">
             {{ t('settings.riskPolicy.create.risk') }}
           </span>
-          <UInput v-model.number="draft.maxRisk" type="number" :min="0" :max="100" size="sm" />
+          <UInput
+            v-model.number="draft.maxRisk"
+            type="number"
+            :min="0"
+            :max="100"
+            size="sm"
+            data-testid="risk-policy-create-risk"
+          />
         </label>
         <label class="block w-20">
           <span class="mb-1 block text-[10px] uppercase tracking-wide text-slate-500">
             {{ t('settings.riskPolicy.create.impact') }}
           </span>
-          <UInput v-model.number="draft.maxImpact" type="number" :min="0" :max="100" size="sm" />
+          <UInput
+            v-model.number="draft.maxImpact"
+            type="number"
+            :min="0"
+            :max="100"
+            size="sm"
+            data-testid="risk-policy-create-impact"
+          />
         </label>
         <label class="block w-20">
           <span class="mb-1 block text-[10px] uppercase tracking-wide text-slate-500">
@@ -549,6 +567,7 @@ async function create() {
           icon="i-lucide-plus"
           :loading="creating"
           :disabled="!draft.name.trim()"
+          data-testid="risk-policy-create-submit"
           @click="create"
         >
           {{ t('settings.riskPolicy.add') }}

package/app/components/settings/WorkspaceSettingsPanel.vue

@@ -312,6 +312,13 @@ async function save() {
     </template>
     <template #body>
       <UTabs v-model="activeTab" :items="tabs" variant="link" :ui="tabsUi">
+        <!-- The tab LABEL, overridden only to carry a per-tab test hook: `UTabs` renders its own
+             triggers and forwards nothing from an item, so this slot is the one place a stable
+             selector can name which tab a click means (the labels themselves are translated). -->
+        <template #default="{ item }">
+          <span :data-testid="`workspace-settings-tab-${item.value}`">{{ item.label }}</span>
+        </template>
+
         <!-- Workspace -->
         <template #workspace>
           <div class="space-y-6">

package/app/composables/useAiReadiness.ts

@@ -13,9 +13,10 @@ import type { ModelPreset } from '~/types/model-presets'
  *    still points at one or more that aren't usable (⇒ the preset-mismatch prompt). Gated on
  *    `hasUsableModel` so the no-AI prompt owns the "nothing works" case on its own.
  *
- * Read-only over the existing stores; the catalog is loaded elsewhere (on workspace-ready
- * and after credential edits), so `ready` simply reports whether that load has landed for
- * the active workspace.
+ * Read-only over the existing stores; the catalog is loaded elsewhere (on the active board
+ * changing and after credential edits), so `ready` simply reports whether that load has landed
+ * for the active workspace. A load that FAILED leaves it false, which is what keeps the no-AI
+ * prompt off a board whose catalog never arrived (see `models.prefetchForBoard`).
  */
 export function useAiReadiness() {
   const models = useModelsStore()

package/app/docs/consumer-extensions.md

@@ -185,11 +185,15 @@ module). The SPA merges it into the create-task picker and the card-badge catalo
   `category` groups the picker (below).
 - **`fields`** are descriptor-driven create-form inputs over the shared descriptor-form vocabulary
   (`text` / `textarea` / `number` / `select` / `checkbox` / `checkbox-group` / `path`, with
-  defaults and `showWhen` visibility; `password` is excluded by construction because a task field
-  value reaches prompts and telemetry). Their values land in the task's sparse
-  `taskTypeFields.custom` bag (no migration). A BACKEND-registered descriptor is enforced
-  server-side on create as well (required answers, option lists, lengths); a code-shipped one is
-  known only to the SPA, so the create form is its only check (see the Validation note below).
+  defaults, `showWhen` visibility and a `section` grouping caption; `password` is excluded by
+  construction because a task field value reaches prompts and telemetry). Their values land in the
+  task's sparse `taskTypeFields.custom` bag (no migration). A BACKEND-registered descriptor is
+  enforced server-side on create as well (required answers, option lists, lengths); a code-shipped
+  one is known only to the SPA, so the create form is its only check (see the Validation note below).
+  A `section` groups a long form into captioned runs and changes nothing else; declare a section's
+  fields consecutively, since a backend registration whose form could caption one twice fails boot
+  and a code-shipped one would simply render the caption twice. Interleaving a section with a
+  mutually exclusive `showWhen` branch is not that fault: only one half is ever on screen.
 - **`formPanel`** optionally names a bespoke create-form section component you contribute to the
   `taskTypeFormPanels` slot (paired by that id, like `resultViews`); shown INSTEAD of `fields`. An
   unpaired id degrades to the descriptor fields.

package/app/pages/index.vue

@@ -191,10 +191,16 @@ const autoOpenedPreset = ref(false)
 // availability reflects that workspace's keys/subscriptions). This populates the AI-readiness
 // signals regardless of which lazy picker happens to mount, so the onboarding prompts below
 // can fire. Credential edits re-fetch via `models.refresh()` in the provider panels.
+//
+// Through `prefetchForBoard` because the FIRST run reads the persisted pin, which `init()` has
+// not validated yet: a board that was deleted, or whose access was revoked while the browser
+// held the pin, 404s here exactly as it does for init's own speculative snapshot fetch. That
+// board is not this watcher's last word (init re-points the pin and it fires again), so the
+// miss is dropped rather than left to surface as an uncaught rejection in the page.
 watch(
   () => workspace.workspaceId,
   (id, prev) => {
-    if (id) void models.ensureLoaded(id)
+    if (id) void models.prefetchForBoard(id)
     // Switching workspaces resets the per-session AI-onboarding state: dismissals and the
     // auto-open guards are scoped to one workspace, so a prompt dismissed in workspace A must
     // not suppress the (independent) prompt for workspace B that also lacks a usable source.

package/app/stores/models.spec.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect, vi } from 'vitest'
+import type { ModelOption } from '~/types/domain'
+import { useModelsStore } from '~/stores/models'
+
+/** Minimal catalog entry: only the fields the store's own reads touch. */
+function model(over: Partial<ModelOption> = {}): ModelOption {
+  return {
+    id: 'qwen3',
+    label: 'Qwen3',
+    description: '',
+    flavor: 'cloudflare',
+    providerLabel: 'Cloudflare',
+    provider: 'cloudflare',
+    model: 'qwen3',
+    available: true,
+    ...over,
+  } as ModelOption
+}
+
+// The boot-time catalog load runs against the PERSISTED PIN, before `workspace.init()` has
+// validated it against the board list. A pin can name a board that was deleted, or one whose
+// access was revoked while the browser held it, and the RBAC gate answers both with a 404, so
+// the load has to tolerate a miss. Left bare it was an uncaught rejection in the page (the
+// `Workspace not found` a removed member's browser threw on their next visit).
+describe('models store: the speculative load of an unvalidated pin', () => {
+  it('drops a pin that 404s and leaves the catalog retryable for the board init resolves', async () => {
+    const get = vi
+      .fn<(workspaceId: string) => Promise<ModelOption[]>>()
+      .mockRejectedValueOnce(Object.assign(new Error('Workspace not found'), { statusCode: 404 }))
+      .mockResolvedValueOnce([model()])
+    vi.stubGlobal('useApi', () => ({ getWorkspaceModels: get }))
+
+    const store = useModelsStore()
+    // The revoked pin. Resolves rather than rejects: nothing in the page catches it.
+    await expect(store.prefetchForBoard('ws_revoked')).resolves.toBeUndefined()
+
+    // Nothing was latched, so this reads as UNRESOLVED rather than as a board with no models
+    // (`useAiReadiness().ready` is `loaded && loadedWorkspaceId === workspaceId`, which is what
+    // keeps the no-AI onboarding prompt from firing off a catalog that never landed).
+    expect(store.loaded).toBe(false)
+    expect(store.loadedWorkspaceId).toBeNull()
+    expect(store.models).toEqual([])
+
+    // ...and the board `init()` resolves instead still loads, on the same store.
+    await store.ensureLoaded('ws_reachable')
+    expect(store.loaded).toBe(true)
+    expect(store.loadedWorkspaceId).toBe('ws_reachable')
+    expect(store.models).toHaveLength(1)
+  })
+
+  it('a pin that IS reachable loads the catalog once, and the later caller reuses it', async () => {
+    const get = vi.fn(() => Promise.resolve([model()]))
+    vi.stubGlobal('useApi', () => ({ getWorkspaceModels: get }))
+
+    const store = useModelsStore()
+    await store.prefetchForBoard('ws1')
+    // What the cold open pays for: `init()` hydrating the same board finds the catalog already
+    // there, so the prefetch is one request rather than a duplicate of the one that follows it.
+    await store.ensureLoaded('ws1')
+
+    expect(get).toHaveBeenCalledTimes(1)
+    expect(store.hasUsableModel).toBe(true)
+  })
+})

package/app/stores/models.ts

@@ -122,6 +122,26 @@ export const useModelsStore = defineStore('models', () => {
     loaded.value = true
   }
 
+  /**
+   * Load the catalog for a board the app has NOT yet validated: the persisted pin at boot,
+   * fetched in parallel with the workspace list rather than after it.
+   *
+   * A pin can name a board that was deleted, or one whose access has since been revoked, and the
+   * gate answers both with a 404 (`workspace.init()` guards the same speculative read of the same
+   * id with `.catch(() => null)`). So a failure here is an expected outcome rather than a fault,
+   * and dropping it is safe in both directions: `loaded` stays false, so this leaves the catalog
+   * RETRYABLE for the next `ensureLoaded` caller, and `useAiReadiness().ready` stays false, so a
+   * catalog that never landed reads as unresolved instead of as a board with no AI configured.
+   */
+  async function prefetchForBoard(workspaceId: string): Promise<void> {
+    try {
+      await ensureLoaded(workspaceId)
+    } catch {
+      // Deliberate: see above. `init()` re-points the board it resolved, which loads the catalog
+      // that counts; anything else retries on the next caller.
+    }
+  }
+
   /** Force a re-fetch of the per-workspace catalog (e.g. after adding an API key). */
   async function refresh(workspaceId: string) {
     models.value = await api.getWorkspaceModels(workspaceId)
@@ -180,6 +200,7 @@ export const useModelsStore = defineStore('models', () => {
     loaded,
     loadedWorkspaceId,
     ensureLoaded,
+    prefetchForBoard,
     refresh,
     byId,
     getModel,

package/app/utils/descriptorFields.spec.ts

@@ -2,6 +2,7 @@ import { describe, it, expect } from 'vitest'
 import type { DescriptorField } from '~/types/domain'
 import {
   defaultDescriptorValues,
+  descriptorFormRows,
   descriptorGroupValue,
   setDescriptorCheckbox,
   setDescriptorValue,
@@ -124,3 +125,70 @@ describe('toggleDescriptorGroupValue', () => {
     })
   })
 })
+
+// The layout half of `section` grouping. What a caption SPANS is the shared contracts rule (tested
+// there); what these assert is the property that rule's rendering has to preserve, and the reason the
+// rows are flat at all: a field's identity survives a boundary move, so the keyed diff MOVES the
+// live input instead of remounting it.
+describe('descriptorFormRows', () => {
+  const keysOf = (rows: ReturnType<typeof descriptorFormRows>) => rows.map((r) => r.field.key)
+
+  it('carries each run caption on the field that OPENS it, once', () => {
+    const rows = descriptorFormRows(
+      [
+        field({ key: 'entity' }),
+        field({ key: 'style', section: 'Shape' }),
+        field({ key: 'verb', section: 'Shape' }),
+        field({ key: 'dir', type: 'path', section: 'Placement' }),
+      ],
+      {},
+    )
+    expect(rows.map((r) => [r.field.key, r.caption, r.startsGroup])).toEqual([
+      ['entity', undefined, false],
+      ['style', 'Shape', true],
+      ['verb', undefined, false],
+      ['dir', 'Placement', true],
+    ])
+  })
+
+  it('renders a sectionless form as the flat column, with no caption and no group gap', () => {
+    const rows = descriptorFormRows([field({ key: 'entity' }), field({ key: 'notes' })], {})
+    expect(rows.map((r) => [r.caption, r.startsGroup])).toEqual([
+      [undefined, false],
+      [undefined, false],
+    ])
+    expect(descriptorFormRows([], {})).toEqual([])
+  })
+
+  it('keeps a field key STABLE when a reveal moves it into another run', () => {
+    // The regression this shape exists for. `note` is unsectioned and gated, so revealing it splits
+    // the `Shape` run in two and re-captions `style`. Boot refuses THIS declaration (the split is
+    // reachable), and the renderer still has to be total over it, because a wire descriptor can
+    // arrive from a node whose build predates the refusal. Every field key present before is still
+    // present after, so Vue's keyed diff moves those nodes rather than unmounting them: typing into
+    // `advanced` (the trigger) cannot destroy the input being typed into.
+    const fields = [
+      field({ key: 'advanced', type: 'checkbox' }),
+      field({ key: 'verb', section: 'Shape' }),
+      field({ key: 'note', showWhen: { key: 'advanced', equals: true } }),
+      field({ key: 'style', section: 'Shape' }),
+    ]
+    expect(keysOf(descriptorFormRows(fields, {}))).toEqual(['advanced', 'verb', 'style'])
+
+    const revealed = descriptorFormRows(fields, { advanced: true })
+    expect(keysOf(revealed)).toEqual(['advanced', 'verb', 'note', 'style'])
+    // The caption moved (the second run needs its own) while the field identities did not.
+    expect(revealed.map((r) => r.caption)).toEqual([undefined, 'Shape', undefined, 'Shape'])
+  })
+
+  it('marks a later UNCAPTIONED run as opening a group too, so the gap is not caption-only', () => {
+    const rows = descriptorFormRows(
+      [field({ key: 'verb', section: 'Shape' }), field({ key: 'notes' })],
+      {},
+    )
+    expect(rows.map((r) => [r.field.key, r.startsGroup])).toEqual([
+      ['verb', false],
+      ['notes', true],
+    ])
+  })
+})

package/app/utils/descriptorFields.ts

@@ -1,4 +1,4 @@
-import { descriptorFieldDefaults } from '@cat-factory/contracts'
+import { descriptorFieldDefaults, descriptorFieldSections } from '@cat-factory/contracts'
 import type { DescriptorField, DescriptorFieldValue, DescriptorFieldValues } from '~/types/domain'
 
 // Form-side helpers over the shared descriptor-field vocabulary (`contracts/src/form-fields.ts`),
@@ -75,6 +75,45 @@ export function descriptorGroupValue(values: DescriptorFieldValues, key: string)
   return Array.isArray(value) ? value : []
 }
 
+/** One row of a rendered descriptor form: a field, plus the section chrome that precedes it. */
+export interface DescriptorFormRow {
+  /** The field to render. Its `key` is the row's identity in the keyed diff. */
+  field: DescriptorField
+  /** The caption to print above this field, set only on the field that OPENS a captioned run. */
+  caption?: string
+  /** Whether this field opens a run with another run before it, i.e. needs the between-runs gap. */
+  startsGroup: boolean
+}
+
+/**
+ * A descriptor form reduced to a FLAT list of rows: the shared `descriptorFieldSections` grouping,
+ * with each run's caption carried on the field that opens it rather than on a wrapper around it.
+ *
+ * Flat is the whole point, and it is a correctness rule rather than a layout preference. Run
+ * membership is DERIVED state that changes as `showWhen` reveals and hides fields, while a field's
+ * identity does not. Rendering the runs as nested `v-for`s re-parents a field the moment a boundary
+ * moves, and Vue cannot move a node between two parents: it unmounts and remounts it. The field being
+ * remounted is typically the one being TYPED INTO, because typing into a `showWhen` trigger is what
+ * moved the boundary, so the input loses focus, caret and any in-flight IME composition mid-keystroke.
+ * Keeping every field a sibling under one parent, keyed by `field.key`, makes that a MOVE, which
+ * preserves the live input: the behaviour the flat column had before sections existed.
+ *
+ * Presentation, so it lives here rather than in contracts: what a caption spans is the shared rule,
+ * and this is only how the SPA lays that out.
+ */
+export function descriptorFormRows(
+  fields: readonly DescriptorField[],
+  values: DescriptorFieldValues,
+): DescriptorFormRow[] {
+  return descriptorFieldSections(fields, values).flatMap((group, groupIndex) =>
+    group.fields.map((field, fieldIndex) => ({
+      field,
+      ...(fieldIndex === 0 && group.section !== undefined ? { caption: group.section } : {}),
+      startsGroup: fieldIndex === 0 && groupIndex > 0,
+    })),
+  )
+}
+
 /** One option toggled on/off in a `checkbox-group` field's value (deduped, order-preserving). */
 export function toggleDescriptorGroupValue(
   values: DescriptorFieldValues,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.236.0",
+  "version": "0.237.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",
@@ -40,7 +40,7 @@
     "valibot": "^1.4.2",
     "vue": "3.5.40",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.256.0"
+    "@cat-factory/contracts": "0.257.0"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.2",