@cat-factory/app 0.312.0 → 0.314.0

package/app/modular/nav-contributions.ts

@@ -196,6 +196,7 @@ export interface NavCommandSpec {
  * dead button. Consumer modules don't use these — they carry their own `run`.
  */
 export const NAV_ACTIONS = [
+  'describeWork',
   'assistant',
   'guidedReview',
   'buildPipeline',
@@ -210,6 +211,7 @@ export const NAV_ACTIONS = [
   'foundationalServices',
   'mergeThresholds',
   'workspaceSettings',
+  'setupChecklist',
   'modelConfiguration',
   'serviceFragmentDefaults',
   'localModels',
@@ -345,6 +347,26 @@ const S = (...s: NavSurface[]) => s as readonly NavSurface[]
  * the whole sidebar costs it nothing it is there to do.
  */
 export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
+  {
+    // The one-sentence intake (issue #2258): what needs doing, a service, feature or bug. First in
+    // Create, because filing a task is the most frequent thing anyone creates, and until now it had
+    // no entry here at all (it lived on each frame). Every tier and the intake role: describing
+    // work is what that role is for.
+    id: 'describe-work',
+    labelKey: 'queue.describeWork',
+    icon: 'i-lucide-plus',
+    surfaces: S('sidebar', 'command'),
+    gate: (g) => g.canWriteBoard && g.boardHasService,
+    action: 'describeWork',
+    intake: true,
+    testId: 'nav-describe-work',
+    sidebar: { group: 'create', order: 1 },
+    command: {
+      group: 'create',
+      order: 1,
+      keywordsKey: 'layout.commandBar.keywords.describeWork',
+    },
+  },
   {
     // The in-app assistant. `intake: true` and not `advanced`, because it is the shortest route
     // to the two things a narrowed role is on the board to do (put a repository on it, file a
@@ -538,6 +560,30 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
       keywordsKey: 'layout.commandBar.keywords.workspaceSettings',
     },
   },
+  {
+    // Every prerequisite for "a task can run and merge", composed from the probes the setup
+    // banners already read (issue #2258). First in Configuration, because a workspace that cannot
+    // run a task yet needs it before anything else there. Both tiers: getting to green is not an
+    // advanced job. Gated on either permission, since its rows open both kinds of surface. Not
+    // `intake`: the designer surface never configures the platform, and the setup banners give it
+    // no actionable card either. Each row still applies the banners' per-owner rule
+    // (`utils/setupAudience.ts`), because holding one of these permissions does not make a caller
+    // the owner of every gap.
+    id: 'setup-checklist',
+    labelKey: 'nav.setupChecklist',
+    icon: 'i-lucide-list-checks',
+    surfaces: S('sidebar', 'command'),
+    gate: (g) => g.canManageIntegrations || g.canManageSettings,
+    action: 'setupChecklist',
+    testId: 'nav-setup-checklist',
+    sidebar: { group: 'configuration', order: 5 },
+    command: {
+      group: 'workspace',
+      order: 120,
+      labelKey: 'layout.commandBar.cmd.setupChecklist',
+      keywordsKey: 'layout.commandBar.keywords.setupChecklist',
+    },
+  },
   {
     id: 'model-config',
     labelKey: 'nav.modelConfiguration',

package/app/pages/index.vue

@@ -104,6 +104,9 @@ const ModelProvidersHub = defineAsyncView(() => import('~/components/layout/Mode
 const PersonalSetupModal = defineAsyncView(
   () => import('~/components/layout/PersonalSetupModal.vue'),
 )
+const SetupChecklistPanel = defineAsyncView(
+  () => import('~/components/setup/SetupChecklistPanel.vue'),
+)
 const WorkspaceSettingsPanel = defineAsyncView(
   () => import('~/components/settings/WorkspaceSettingsPanel.vue'),
 )
@@ -161,6 +164,7 @@ const TutorialNudge = defineAsyncView(() => import('~/components/tutorial/Tutori
 const RolePrompt = defineAsyncView(() => import('~/components/layout/RolePrompt.vue'))
 // The queue: the board's second view (issue #2258), loaded the first time someone opens it.
 const QueueView = defineAsyncView(() => import('~/components/queue/QueueView.vue'))
+const DescribeWorkModal = defineAsyncView(() => import('~/components/queue/DescribeWorkModal.vue'))
 
 const workspace = useWorkspaceStore()
 const github = useGitHubStore()
@@ -529,6 +533,7 @@ watch(
         <AddTaskModal />
         <ReviewFrictionDialog v-if="ui.reviewFrictionContext" />
         <CreateInitiativeModal />
+        <DescribeWorkModal v-if="ui.describeWorkOpen" />
         <CommandBar />
         <PersonalCredentialModal />
         <ConfirmDialog />
@@ -564,6 +569,7 @@ watch(
         <IntegrationsHub v-if="ui.integrationsOpen" />
         <ModelProvidersHub v-if="ui.modelProvidersOpen" />
         <PersonalSetupModal v-if="ui.personalSetupOpen" />
+        <SetupChecklistPanel v-if="ui.setupChecklistOpen" />
         <WorkspaceSettingsPanel v-if="ui.workspaceSettingsOpen" />
         <AccountSettingsPanel v-if="ui.accountSettingsOpen" />
         <ObservabilityConnectionPanel v-if="ui.observabilityConnectionOpen" />

package/app/stores/github/context.ts

@@ -26,6 +26,7 @@ export interface GitHubStoreContext {
   api: ReturnType<typeof useApi>
   workspace: ReturnType<typeof useWorkspaceStore>
   available: Ref<boolean | null>
+  unavailableCause: Ref<'disabled' | 'failed' | null>
   connection: Ref<GitHubConnection | null>
   /** The connect surfaces this deployment can serve (GitHub App / GitLab PAT / …). */
   connectOptions: Ref<VcsConnectOption[]>

package/app/stores/github/probe.ts

@@ -2,6 +2,7 @@ import type { Ref } from 'vue'
 import type { GitHubPatCheck } from '~/types/domain'
 import { useSingleFlightProbe } from '~/composables/useSingleFlightProbe'
 import type { GitHubStoreContext } from '~/stores/github/context'
+import { apiErrorStatus } from '~/composables/api/errors'
 
 /**
  * The board-load probe: everything the store learns about the deployment's VCS setup in one round
@@ -37,7 +38,7 @@ export function createGitHubProbe(
   ctx: GitHubStoreContext,
   patCheck: Ref<GitHubPatCheck | null>,
 ): { probe: () => Promise<void>; ensureProbed: () => Promise<void> } {
-  const { api, workspace, available, connection, connectOptions } = ctx
+  const { api, workspace, available, unavailableCause, connection, connectOptions } = ctx
 
   async function runPatCheck(): Promise<void> {
     // Which board asked, captured BEFORE the await: a workspace switch mid-flight must not land
@@ -65,11 +66,14 @@ export function createGitHubProbe(
           .catch(() => []),
       ])
       available.value = true
+      unavailableCause.value = null
       connection.value = conn
       connectOptions.value = options
-    } catch {
-      // 503 (integration disabled) or any error → hide the UI entry points.
+    } catch (err) {
+      // 503 (integration disabled) or any error → hide the UI entry points. The cause is kept, so
+      // a surface that states the setup can tell "switched off" from "could not ask".
       available.value = false
+      unavailableCause.value = apiErrorStatus(err) === 503 ? 'disabled' : 'failed'
       connection.value = null
       connectOptions.value = []
     }

package/app/stores/github.ts

@@ -38,6 +38,12 @@ export const useGitHubStore = defineStore('github', () => {
 
   /** null = unknown (not probed yet), true/false = integration on/off. */
   const available = ref<boolean | null>(null)
+  /**
+   * Why `available` is false: the deployment switched the integration off (a 503), or the probe
+   * itself failed. Both hide the GitHub UI, but only the first is a fact about the deployment;
+   * the second is an unanswered question. Null while `available` is not false.
+   */
+  const unavailableCause = ref<'disabled' | 'failed' | null>(null)
   /** The workspace's VCS connection (App installation or PAT), or null when not connected. */
   const connection = ref<GitHubConnection | null>(null)
   /** The connect surfaces this deployment serves; resolved by the probe alongside `connection`. */
@@ -160,6 +166,7 @@ export const useGitHubStore = defineStore('github', () => {
     api,
     workspace,
     available,
+    unavailableCause,
     connection,
     connectOptions,
     installations,
@@ -207,6 +214,7 @@ export const useGitHubStore = defineStore('github', () => {
    */
   function reset() {
     available.value = null
+    unavailableCause.value = null
     connection.value = null
     connectOptions.value = []
     patCheck.value = null
@@ -221,6 +229,7 @@ export const useGitHubStore = defineStore('github', () => {
 
   return {
     available,
+    unavailableCause,
     connection,
     connectOptions,
     patCheck,

package/app/stores/ui/modals.ts

@@ -27,6 +27,14 @@ export interface AddTaskPrefill {
   description?: string
   /** Context items staged on the new task (e.g. the source issue), linked once created. */
   context?: PendingContext[]
+  /**
+   * Choices a person already made on another surface (the one-sentence intake), carried over so
+   * the hand-off does not quietly reset them. Absent means the form's own defaults.
+   */
+  taskType?: 'feature' | 'bug'
+  pipelineId?: string
+  riskPolicyId?: string
+  modelPresetId?: string
 }
 
 /**
@@ -90,6 +98,11 @@ export interface ReviewFrictionModalContext {
    * started a second pipeline run against the same request.
    */
   pending?: () => boolean
+  /**
+   * Close the form that raised the friction. "Go review" and each debt row leave for a waiting
+   * task, and the form must not stay open over it; only the opener knows which form it is.
+   */
+  onLeave: () => void
 }
 
 /** Clears both hub came-from markers; injected into the slices whose `open*` handlers reset them. */
@@ -340,6 +353,17 @@ function createDocumentTaskModals(resetHubReturn: ResetHubReturn) {
   function closeStartFromDesign() {
     startFromDesign.value = null
   }
+  // The one-sentence intake ("Describe new work", issue #2258): open, and the service it opened
+  // on, or null to let the reader pick one. The full form above stays the home of every other kind.
+  const describeWorkOpen = ref(false)
+  const describeWorkServiceId = ref<string | null>(null)
+  function openDescribeWork(serviceId: string | null = null) {
+    describeWorkServiceId.value = serviceId
+    describeWorkOpen.value = true
+  }
+  function closeDescribeWork() {
+    describeWorkOpen.value = false
+  }
   function openAddTask(containerId: string, prefill: AddTaskPrefill | null = null) {
     addTaskPrefill.value = prefill
     addTaskContainerId.value = containerId
@@ -405,6 +429,10 @@ function createDocumentTaskModals(resetHubReturn: ResetHubReturn) {
     closeStartFromDesign,
     openAddTask,
     closeAddTask,
+    describeWorkOpen,
+    describeWorkServiceId,
+    openDescribeWork,
+    closeDescribeWork,
     openReviewFriction,
     closeReviewFriction,
     openAddRecurring,
@@ -728,6 +756,17 @@ function createSettingsModals(resetHubReturn: ResetHubReturn) {
   // so a later plain open doesn't re-scroll. Null when no section was requested.
   const accountSettingsScrollTarget = ref<string | null>(null)
 
+  // Setup checklist: every prerequisite for "a task can run and merge" in one list, composed
+  // from the probes the setup banners already read (issue #2258).
+  const setupChecklistOpen = ref(false)
+  function openSetupChecklist() {
+    resetHubReturn()
+    setupChecklistOpen.value = true
+  }
+  function closeSetupChecklist() {
+    setupChecklistOpen.value = false
+  }
+
   function openWorkspaceSettings(tab = 'workspace') {
     resetHubReturn()
     workspaceSettingsTab.value = tab
@@ -765,6 +804,9 @@ function createSettingsModals(resetHubReturn: ResetHubReturn) {
   }
 
   return {
+    setupChecklistOpen,
+    openSetupChecklist,
+    closeSetupChecklist,
     workspaceSettingsOpen,
     workspaceSettingsTab,
     accountSettingsOpen,

package/app/utils/describeWork.spec.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest'
+import { DERIVED_TITLE_MAX, splitDescribedWork } from '~/utils/describeWork'
+
+describe('splitDescribedWork', () => {
+  it('uses one short sentence as the title and adds no description', () => {
+    expect(splitDescribedWork('  Fix the login redirect  ')).toEqual({
+      title: 'Fix the login redirect',
+    })
+  })
+
+  it('titles with the first sentence and keeps the WHOLE text as the description', () => {
+    const text = 'Add an audit log. Record each sign-in with the time and the user.'
+    expect(splitDescribedWork(text)).toEqual({ title: 'Add an audit log', description: text })
+  })
+
+  it('reads only the first line for the title', () => {
+    const text = 'Rate limit per API key\nUse a token bucket. 100 requests a minute.'
+    expect(splitDescribedWork(text)).toEqual({ title: 'Rate limit per API key', description: text })
+  })
+
+  it('shortens a long first sentence at a word boundary, with an ellipsis', () => {
+    const words = 'word '.repeat(40).trim()
+    const { title, description } = splitDescribedWork(words)
+    expect(title.length).toBeLessThanOrEqual(DERIVED_TITLE_MAX)
+    expect(title.endsWith('word…')).toBe(true)
+    expect(description).toBe(words)
+  })
+
+  it('does not cut a dotted name such as a file or a version', () => {
+    expect(splitDescribedWork('Bump vite to 7.1 in package.json').title).toBe(
+      'Bump vite to 7.1 in package.json',
+    )
+  })
+
+  it('does not end a sentence at a common abbreviation', () => {
+    const text = 'Fix e.g. the login redirect loop. It happens on Safari.'
+    expect(splitDescribedWork(text)).toEqual({
+      title: 'Fix e.g. the login redirect loop',
+      description: text,
+    })
+    expect(splitDescribedWork('Ask Dr. Smith about the export. She owns it.').title).toBe(
+      'Ask Dr. Smith about the export',
+    )
+  })
+
+  it('treats a run of dots as one mark', () => {
+    expect(splitDescribedWork('Fix this... later, after the release.').title).toBe('Fix this')
+    expect(splitDescribedWork('Use a cache, e.g. Redis, for sessions.').title).toBe(
+      'Use a cache, e.g. Redis, for sessions',
+    )
+  })
+
+  it('ends a sentence at a full-width mark, with or without a space after it', () => {
+    const text = '修复登录重定向。记录每次登录。'
+    expect(splitDescribedWork(text)).toEqual({ title: '修复登录重定向', description: text })
+  })
+
+  it('keeps a question or an exclamation mark, and drops a period', () => {
+    expect(splitDescribedWork('Why does login fail?')).toEqual({ title: 'Why does login fail?' })
+    // A final period says nothing the title does not, so it adds no description.
+    expect(splitDescribedWork('Fix the login redirect.')).toEqual({
+      title: 'Fix the login redirect',
+    })
+  })
+
+  it('never cuts an emoji in half when it shortens', () => {
+    const text = `${'a'.repeat(DERIVED_TITLE_MAX - 2)}😀😀😀 more words after it`
+    const { title } = splitDescribedWork(text)
+    expect(title).not.toMatch(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])/)
+    expect(Array.from(title).length).toBeLessThanOrEqual(DERIVED_TITLE_MAX)
+  })
+
+  it('returns an empty title for blank input, so the dialog cannot submit it', () => {
+    expect(splitDescribedWork('   \n ')).toEqual({ title: '' })
+  })
+})

package/app/utils/describeWork.ts

@@ -0,0 +1,71 @@
+/** The longest title the one-box intake derives. Long enough for a sentence, short for a card. */
+export const DERIVED_TITLE_MAX = 80
+
+/**
+ * Abbreviations whose period does not end a sentence. Only the common ones a task description
+ * starts with: the title is derived, so a miss costs a short title, never lost text (the whole text
+ * is the description).
+ */
+const ABBREVIATIONS = new Set(['e.g', 'i.e', 'etc', 'vs', 'cf', 'dr', 'mr', 'mrs', 'ms', 'st'])
+
+/** Ends a sentence. Full-width marks end one with or without a following space. */
+const FULL_WIDTH_END = new Set(['。', '！', '？'])
+const KEPT_END = new Set(['?', '!', '？', '！'])
+
+/**
+ * Split what a person typed into the one-box intake into a task title and a description.
+ *
+ * The title is the first line, cut at its first sentence end, and shortened at a word boundary
+ * to {@link DERIVED_TITLE_MAX} with an ellipsis. A question or an exclamation keeps its mark, which
+ * is part of what it says; a period does not. The description is the WHOLE text, unedited,
+ * whenever it says more than the title does: nothing the person wrote is dropped, and the agents
+ * read the description, never the title alone. Returns an empty title for blank input.
+ */
+export function splitDescribedWork(text: string): { title: string; description?: string } {
+  const body = text.trim()
+  if (!body) return { title: '' }
+  const firstLine = body.split(/\r?\n/, 1)[0]!.trim()
+  const title = shorten(firstSentence(firstLine) || firstLine)
+  return stripEnd(title) === stripEnd(body) ? { title } : { title, description: body }
+}
+
+/** The first sentence of a line, ending mark included only when it is `?` or `!`. */
+function firstSentence(line: string): string {
+  const chars = Array.from(line)
+  for (let i = 0; i < chars.length; i++) {
+    const c = chars[i]!
+    const next = chars[i + 1]
+    // A run of dots ("this... later") is ONE mark: only its last dot can end the sentence, and
+    // the whole run is cut with it.
+    if (c === '.' && next === '.') continue
+    const ends =
+      FULL_WIDTH_END.has(c) || ('.!?'.includes(c) && (next === undefined || /\s/.test(next)))
+    if (!ends) continue
+    if (c === '.' && isAbbreviation(chars.slice(0, i).join(''))) continue
+    let end = KEPT_END.has(c) ? i + 1 : i
+    while (c === '.' && end > 0 && chars[end - 1] === '.') end--
+    return chars.slice(0, end).join('').trim()
+  }
+  return line
+}
+
+/** Whether the word before a period is an abbreviation ("e.g", "Dr"), not a sentence's last word. */
+function isAbbreviation(before: string): boolean {
+  const word = before.split(/\s/).pop() ?? ''
+  return ABBREVIATIONS.has(word.toLowerCase())
+}
+
+/** The text without its final sentence mark, so "Fix the login." says no more than "Fix the login". */
+function stripEnd(s: string): string {
+  return s.replace(/[.!?。！？…]+$/u, '')
+}
+
+/** Shorten by CODE POINTS, so a cut never splits an emoji or another astral character in half. */
+function shorten(line: string): string {
+  const chars = Array.from(line)
+  if (chars.length <= DERIVED_TITLE_MAX) return line
+  const cut = chars.slice(0, DERIVED_TITLE_MAX - 1).join('')
+  const lastSpace = cut.lastIndexOf(' ')
+  const keep = lastSpace > cut.length / 2 ? cut.slice(0, lastSpace) : cut
+  return `${keep.trimEnd()}…`
+}

package/app/utils/reviewFriction.ts

@@ -0,0 +1,47 @@
+import type { ReviewFrictionModalContext } from '~/stores/ui/modals'
+import type { parseConflict } from '~/composables/usePipelineErrorToast'
+
+/** A conflict `parseConflict` recognised. */
+type ParsedConflict = NonNullable<ReturnType<typeof parseConflict>>
+
+/** Whether a create was refused by the opt-in review-debt friction gate. */
+export function isReviewDebtConflict(conflict: ParsedConflict | null): conflict is ParsedConflict {
+  return conflict?.reason === 'review_debt_warn' || conflict?.reason === 'review_debt_blocked'
+}
+
+/**
+ * Turn a parsed review-debt friction 409 into the dialog's context (see ReviewFrictionDialog.vue).
+ *
+ * Shared by every surface that creates a task, so the friction reads the same whichever form
+ * raised it. `retry` re-submits with `acknowledgeReviewDebt` and is offered only on the soft
+ * `warn` tier; `pending` is a GETTER over the opener's own in-flight flag, for the reason the
+ * context type documents; `leave` closes the opener when the person leaves to review.
+ */
+export function reviewFrictionContext(
+  conflict: ParsedConflict,
+  retry: () => void,
+  pending: () => boolean,
+  leave: () => void,
+): ReviewFrictionModalContext {
+  const details = conflict.details
+  const rawDebt = Array.isArray(details.debt) ? details.debt : []
+  const debt = rawDebt.map((d) => {
+    const row = (d ?? {}) as { blockId?: unknown; title?: unknown; waitingMinutes?: unknown }
+    return {
+      blockId: typeof row.blockId === 'string' ? row.blockId : '',
+      title: typeof row.title === 'string' ? row.title : null,
+      waitingMinutes: typeof row.waitingMinutes === 'number' ? row.waitingMinutes : 0,
+    }
+  })
+  const isWarn = conflict.reason === 'review_debt_warn'
+  return {
+    kind: isWarn ? 'warn' : 'blocked',
+    reason:
+      details.friction === 'count' || details.friction === 'stuck' ? details.friction : undefined,
+    threshold: typeof details.threshold === 'number' ? details.threshold : null,
+    debt,
+    onConfirm: isWarn ? retry : null,
+    pending,
+    onLeave: leave,
+  }
+}

package/app/utils/setupChecklist.spec.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it } from 'vitest'
+import type { InfraSetup } from '@cat-factory/contracts'
+import { deriveSetupChecklist, type SetupProbeInput } from '~/utils/setupChecklist'
+import type { SetupActor } from '~/utils/setupAudience'
+
+// The checklist adds no probe of its own; what it owes is to state each probe's answer without
+// changing its meaning. Three rules matter most: an unanswered probe is never "missing" or
+// "done", a broken setup is never "missing" (that would send the reader to create a second one),
+// and a row only offers its action to someone whose save would land.
+
+const ALL_CONFIGURED: InfraSetup = {
+  agentExecutor: 'configured',
+  ephemeralEnvironments: 'configured',
+  binaryStorage: 'configured',
+}
+
+const ADMIN: SetupActor = {
+  fullSurface: true,
+  canManageIntegrations: true,
+  canExecuteRuns: true,
+  isAccountAdmin: true,
+  accountsEnabled: true,
+}
+
+const SOURCE_OK: SetupProbeInput['sourceControl'] = {
+  available: true,
+  unavailableCause: null,
+  connected: true,
+  patMissing: false,
+  patProblem: null,
+}
+
+function input(overrides: Partial<SetupProbeInput> = {}): SetupProbeInput {
+  return {
+    model: { loaded: true, loadFailed: false, usable: true, presetBroken: false },
+    sourceControl: SOURCE_OK,
+    infra: ALL_CONFIGURED,
+    workspaceLoaded: true,
+    infraOwners: null,
+    providers: { loaded: true, needingConfig: [] },
+    actor: ADMIN,
+    ...overrides,
+  }
+}
+
+function row(i: SetupProbeInput, id: string) {
+  const found = deriveSetupChecklist(i).rows.find((r) => r.id === id)
+  if (!found) throw new Error(`no row ${id}`)
+  return found
+}
+
+describe('deriveSetupChecklist', () => {
+  it('reports a fully set-up workspace as done, with nothing left checking', () => {
+    const c = deriveSetupChecklist(input())
+    expect(c.done).toBe(c.total)
+    expect(c.checking).toBe(false)
+  })
+
+  it('reports an unanswered probe as checking, never as missing or done', () => {
+    const c = deriveSetupChecklist(
+      input({
+        model: { loaded: false, loadFailed: false, usable: false, presetBroken: false },
+        sourceControl: { ...SOURCE_OK, available: null, connected: false },
+        infra: null,
+        workspaceLoaded: false,
+      }),
+    )
+    expect(c.rows.every((r) => r.status === 'checking')).toBe(true)
+    expect(c.checking).toBe(true)
+  })
+
+  it('keeps a configured runner checking until the providers say whether it is complete', () => {
+    const waiting = input({ providers: { loaded: false, needingConfig: [] } })
+    expect(row(waiting, 'agentExecutor').status).toBe('checking')
+    expect(deriveSetupChecklist(waiting).checking).toBe(true)
+    // Storage has no provider connection, so it does not wait on them.
+    expect(row(waiting, 'binaryStorage').status).toBe('done')
+  })
+
+  it('names the cause of each broken setup, and tells it from an absent one', () => {
+    expect(
+      row(input({ infra: { ...ALL_CONFIGURED, agentExecutor: 'unreachable' } }), 'agentExecutor'),
+    ).toMatchObject({ status: 'attention', cause: 'unreachable' })
+    expect(
+      row(input({ providers: { loaded: true, needingConfig: ['runner-pool'] } }), 'agentExecutor'),
+    ).toMatchObject({ status: 'attention', cause: 'incomplete' })
+    expect(
+      row(input({ infra: { ...ALL_CONFIGURED, agentExecutor: 'not_defined' } }), 'agentExecutor'),
+    ).toMatchObject({ status: 'missing', cause: null })
+    expect(
+      row(
+        input({ model: { loaded: true, loadFailed: false, usable: true, presetBroken: true } }),
+        'model',
+      ),
+    ).toMatchObject({ status: 'attention', cause: 'presetBroken' })
+    expect(
+      row(input({ sourceControl: { ...SOURCE_OK, patProblem: 'rejected' } }), 'sourceControl'),
+    ).toMatchObject({ status: 'attention', cause: 'rejected' })
+  })
+
+  it('states a failed probe as unanswered, never as an absent capability', () => {
+    expect(
+      row(
+        input({ model: { loaded: false, loadFailed: true, usable: false, presetBroken: false } }),
+        'model',
+      ),
+    ).toMatchObject({ status: 'attention', cause: 'probeFailed' })
+    const failed = input({
+      sourceControl: {
+        ...SOURCE_OK,
+        available: false,
+        unavailableCause: 'failed',
+        connected: false,
+      },
+    })
+    expect(row(failed, 'sourceControl')).toMatchObject({
+      status: 'attention',
+      cause: 'probeFailed',
+    })
+    // A deployment that switched the integration off does not use it: no gap to close.
+    const disabled = input({
+      sourceControl: {
+        ...SOURCE_OK,
+        available: false,
+        unavailableCause: 'disabled',
+        connected: false,
+      },
+    })
+    expect(row(disabled, 'sourceControl').status).toBe('not_needed')
+  })
+
+  it('says so when the loaded workspace does not report its infrastructure, never spins', () => {
+    const i = input({ infra: null, workspaceLoaded: true })
+    expect(row(i, 'agentExecutor')).toMatchObject({ status: 'attention', cause: 'notReported' })
+    expect(deriveSetupChecklist(i).checking).toBe(false)
+  })
+
+  it('leaves an area the deployment does not use out of the count', () => {
+    const c = deriveSetupChecklist(
+      input({ infra: { ...ALL_CONFIGURED, ephemeralEnvironments: 'not_applicable' } }),
+    )
+    expect(c.total).toBe(c.rows.length - 1)
+    expect(c.done).toBe(c.total)
+  })
+
+  describe('who can act on a row (the banners rule, `utils/setupAudience.ts`)', () => {
+    const unconfigured: InfraSetup = {
+      agentExecutor: 'not_defined',
+      ephemeralEnvironments: 'not_defined',
+      binaryStorage: 'not_defined',
+    }
+
+    it('offers a board admin who is not an account admin only the gaps they own', () => {
+      const boardAdmin = { ...ADMIN, isAccountAdmin: false }
+      const i = input({
+        infra: unconfigured,
+        infraOwners: {
+          agentExecutor: 'workspace_admin',
+          ephemeralEnvironments: 'operator',
+          binaryStorage: 'account_admin',
+        },
+        actor: boardAdmin,
+      })
+      expect(row(i, 'agentExecutor').remedy).toBeNull()
+      expect(row(i, 'ephemeralEnvironments').remedy).toBe('operator')
+      expect(row(i, 'binaryStorage').remedy).toBe('account_admin')
+    })
+
+    it('tells someone on the designer surface they can fix it themselves', () => {
+      const i = input({ infra: unconfigured, actor: { ...ADMIN, fullSurface: false } })
+      expect(row(i, 'agentExecutor').remedy).toBe('full_surface')
+    })
+
+    it('gives every caller the token page for a personal access token', () => {
+      const member = { ...ADMIN, canManageIntegrations: false, isAccountAdmin: false }
+      const i = input({
+        sourceControl: { ...SOURCE_OK, patMissing: true, connected: false },
+        actor: member,
+      })
+      expect(row(i, 'sourceControl').remedy).toBeNull()
+      expect(row(input({ actor: member }), 'model').remedy).toBe('workspace_admin')
+    })
+  })
+})