@cat-factory/app 0.312.0 → 0.313.0

package/app/composables/useSetupRemedies.ts

@@ -0,0 +1,72 @@
+import { computed } from 'vue'
+import { githubPatCheckSource } from '@cat-factory/contracts'
+import type { GitHubPatKind, InfraSetupArea } from '~/types/domain'
+import { githubPatRemintUrl } from '~/utils/vcs'
+
+/**
+ * Where each setup gap is fixed: the ONE map the setup banners and the setup checklist both open
+ * through, so "the row opens what its banner opens" holds because there is one place that says
+ * it, never two copies kept in step by hand.
+ *
+ * Keyed by `InfraSetupArea` for the infrastructure, the vocabulary the server reports in, plus the
+ * model and source-control remedies, which have no area of their own.
+ */
+export function useSetupRemedies() {
+  const ui = useUiStore()
+  const auth = useAuthStore()
+  const github = useGitHubStore()
+
+  const INFRA: Record<InfraSetupArea, () => void> = {
+    agentExecutor: () => ui.openProviderConnection('runner-pool'),
+    ephemeralEnvironments: () => ui.openProviderConnection('environment'),
+    binaryStorage: () => ui.openContentStorageSettings(),
+  }
+
+  /** Open the screen that configures an infrastructure area. */
+  function openInfraArea(area: InfraSetupArea) {
+    INFRA[area]()
+  }
+
+  /** No usable model: the AI onboarding dialog. */
+  function openModelSetup() {
+    ui.openAiProviderSetup()
+  }
+
+  /** Usable models, but the default preset names one that is not: the preset-mismatch dialog. */
+  function openPresetMismatch() {
+    ui.openAiPresetMismatch()
+  }
+
+  /** Local mode with no token: GitHub's token page, scopes preselected. Null outside that case. */
+  const patSetupUrl = computed(() => auth.localMode?.githubPatSetupUrl ?? null)
+
+  /**
+   * The token page for a token GitHub rejected or under-scoped. A rejected token was never
+   * classified, so it falls back to `unknown`, which lands on the classic form, the only one
+   * GitHub lets us pre-fill.
+   */
+  const patReport = computed(() =>
+    github.patCheck?.state === 'checked' ? github.patCheck.report : undefined,
+  )
+  /** The token's kind, which picks the form. `unknown` for a token GitHub rejected outright. */
+  const patKind = computed<GitHubPatKind>(() => patReport.value?.kind ?? 'unknown')
+  const patRemintUrl = computed(() =>
+    githubPatRemintUrl(patKind.value, patReport.value?.webUrl ?? github.connection?.webUrl),
+  )
+
+  /**
+   * Whose token that is: the deployment's (replaced by whoever runs it) or the person's own
+   * (replaced in their settings). Read off the check, which carries it in every state it reports.
+   */
+  const patSource = computed(() => (github.patCheck ? githubPatCheckSource(github.patCheck) : null))
+
+  return {
+    openInfraArea,
+    openModelSetup,
+    openPresetMismatch,
+    patSetupUrl,
+    patKind,
+    patRemintUrl,
+    patSource,
+  }
+}

package/app/modular/nav-contributions.spec.ts

@@ -491,6 +491,7 @@ describe('nav grouping helpers', () => {
     expect(integrations?.items.map((i) => i.id)).toEqual(['integrations-hub'])
     const configuration = groups.find((g) => g.group === 'configuration')
     expect(configuration?.items.map((i) => i.id)).toEqual([
+      'setup-checklist',
       'workspace-settings',
       'account-settings',
       'operator-dashboard',
@@ -524,6 +525,7 @@ describe('nav grouping helpers', () => {
       'ui-role',
       'tutorial',
       'foundational-services',
+      'setup-checklist',
       'queue-view',
       'board-view',
     ])

package/app/modular/nav-contributions.ts

@@ -210,6 +210,7 @@ export const NAV_ACTIONS = [
   'foundationalServices',
   'mergeThresholds',
   'workspaceSettings',
+  'setupChecklist',
   'modelConfiguration',
   'serviceFragmentDefaults',
   'localModels',
@@ -538,6 +539,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'),
 )
@@ -564,6 +567,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

@@ -728,6 +728,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 +776,9 @@ function createSettingsModals(resetHubReturn: ResetHubReturn) {
   }
 
   return {
+    setupChecklistOpen,
+    openSetupChecklist,
+    closeSetupChecklist,
     workspaceSettingsOpen,
     workspaceSettingsTab,
     accountSettingsOpen,

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')
+    })
+  })
+})

package/app/utils/setupChecklist.ts

@@ -0,0 +1,229 @@
+import type { InfraSetup, InfraSetupOwners, InfraSetupStatus } from '@cat-factory/contracts'
+import { isInfraSetupHealthStatus } from '@cat-factory/contracts'
+import type { ProviderConnectionKind } from '~/types/providerConnections'
+import {
+  canActOnSetup,
+  effectiveOwner,
+  type SetupActor,
+  type SetupRemedy,
+} from '~/utils/setupAudience'
+
+// ---------------------------------------------------------------------------
+// The setup checklist: what this workspace needs before a task can run and merge, as ONE list.
+//
+// Every row is composed from a probe that already exists and already drives a banner or a
+// startup dialog (`useAiReadiness`, the GitHub probe, `workspace.infraSetup`, the provider
+// connections' missing-required fields). The checklist adds no probe of its own: it states the
+// same facts in one place, with a finish line, instead of one interruption per missing piece.
+// Who may act on a row is the banners' rule too (`utils/setupAudience.ts`).
+// ---------------------------------------------------------------------------
+
+/** The rows. The infrastructure rows are named by their `InfraSetupArea`, the server's vocabulary. */
+export const SETUP_ROWS = [
+  'model',
+  'sourceControl',
+  'agentExecutor',
+  'ephemeralEnvironments',
+  'binaryStorage',
+] as const
+export type SetupRowId = (typeof SETUP_ROWS)[number]
+
+/**
+ * A row's state. Five, because they need five different reactions:
+ *
+ * - `done`: nothing to do.
+ * - `missing`: never set up. The fix is to connect something.
+ * - `attention`: set up, but broken, unreachable or incomplete. The fix is to repair it, and
+ *   saying "connect" would send the reader to create a second one. Its {@link SetupRowCause} says
+ *   which, because each needs a different fix.
+ * - `checking`: the probe has not answered. Never rendered as missing: an unanswered probe and
+ *   an absent capability are opposite facts.
+ * - `not_needed`: this deployment does not use the area at all. Left out of the count.
+ */
+export type SetupRowStatus = 'done' | 'missing' | 'attention' | 'checking' | 'not_needed'
+
+/** Why a row needs attention. Each one names a different fix. */
+export type SetupRowCause =
+  /** Configured, and its live probe says it cannot be reached. */
+  | 'unreachable'
+  /** Connected, but a mandatory provider field is unset. */
+  | 'incomplete'
+  /** GitHub refused the access token outright. */
+  | 'rejected'
+  /** The token authenticates but cannot push or open pull requests. */
+  | 'underscoped'
+  /** Usable models exist, but the default preset names one that is not. */
+  | 'presetBroken'
+  /** The probe itself failed, so the answer is unknown. The fix is to ask again. */
+  | 'probeFailed'
+  /** The workspace loaded, and this backend does not report the area at all. */
+  | 'notReported'
+
+/** Whether a task can run without the row. An optional row only switches off the agents that use it. */
+export const SETUP_ROW_REQUIRED: Record<SetupRowId, boolean> = {
+  model: true,
+  sourceControl: true,
+  agentExecutor: true,
+  ephemeralEnvironments: false,
+  binaryStorage: false,
+}
+
+/** Everything the checklist reads, resolved by the caller so this stays pure. */
+export interface SetupProbeInput {
+  readonly model: {
+    /** The per-workspace model catalog has loaded for this workspace. */
+    readonly loaded: boolean
+    /** The last attempt to load it failed. */
+    readonly loadFailed: boolean
+    readonly usable: boolean
+    /** Usable models exist, but the default preset names one that is not. */
+    readonly presetBroken: boolean
+  }
+  readonly sourceControl: {
+    /** Null while the GitHub probe is in flight. */
+    readonly available: boolean | null
+    /** Why `available` is false: switched off by the deployment, or the probe failed. */
+    readonly unavailableCause: 'disabled' | 'failed' | null
+    readonly connected: boolean
+    /** Local mode with no personal access token set. */
+    readonly patMissing: boolean
+    /** The token check's verdict, when it needs attention. */
+    readonly patProblem: 'rejected' | 'underscoped' | null
+  }
+  /** Null until the workspace snapshot has delivered it, or from a backend that omits it. */
+  readonly infra: InfraSetup | null
+  /** The workspace snapshot has loaded, so a null `infra` is an answer, not a wait. */
+  readonly workspaceLoaded: boolean
+  /** Who can close each infrastructure gap; null from a backend that does not report it. */
+  readonly infraOwners: InfraSetupOwners | null
+  readonly providers: {
+    /** The provider connections have loaded, so `needingConfig` is an answer. */
+    readonly loaded: boolean
+    /** Provider connections that are wired but miss a mandatory field. */
+    readonly needingConfig: readonly ProviderConnectionKind[]
+  }
+  readonly actor: SetupActor
+}
+
+/** A row's state and, exactly when it needs attention, why. */
+export type SetupRowState =
+  | { readonly status: Exclude<SetupRowStatus, 'attention'>; readonly cause: null }
+  | { readonly status: 'attention'; readonly cause: SetupRowCause }
+
+export type SetupRow = SetupRowState & {
+  readonly id: SetupRowId
+  readonly required: boolean
+  /** Null when this caller can act on the row; otherwise how the gap gets fixed. */
+  readonly remedy: SetupRemedy | null
+}
+
+export interface SetupChecklist {
+  readonly rows: SetupRow[]
+  /** Rows that count toward the finish line (everything except `not_needed`). */
+  readonly total: number
+  readonly done: number
+  /** A counted row has not answered yet, so `done` is not a count of the finished rows yet. */
+  readonly checking: boolean
+}
+
+type RowState = SetupRowState
+const state = (status: Exclude<SetupRowStatus, 'attention'>): RowState => ({ status, cause: null })
+const attention = (cause: SetupRowCause): RowState => ({ status: 'attention', cause })
+
+function infraRow(
+  status: InfraSetupStatus | undefined,
+  workspaceLoaded: boolean,
+  provider: { loaded: boolean; incomplete: boolean } | null,
+): RowState {
+  if (status === undefined) return workspaceLoaded ? attention('notReported') : state('checking')
+  if (status === 'not_applicable') return state('not_needed')
+  if (status === 'not_defined') return state('missing')
+  if (isInfraSetupHealthStatus(status)) return attention('unreachable')
+  // Configured. Whether a mandatory field is unset is known only once the providers load; until
+  // then the row has not answered, rather than claiming done.
+  if (provider && !provider.loaded) return state('checking')
+  return provider?.incomplete ? attention('incomplete') : state('done')
+}
+
+function modelRow(m: SetupProbeInput['model']): RowState {
+  if (!m.loaded) return m.loadFailed ? attention('probeFailed') : state('checking')
+  if (!m.usable) return state('missing')
+  return m.presetBroken ? attention('presetBroken') : state('done')
+}
+
+function sourceControlRow(s: SetupProbeInput['sourceControl']): RowState {
+  if (s.patMissing) return state('missing')
+  if (s.patProblem) return attention(s.patProblem)
+  if (s.connected) return state('done')
+  if (s.available === null) return state('checking')
+  if (s.available === false) {
+    if (s.unavailableCause === 'disabled') return state('not_needed')
+    if (s.unavailableCause === 'failed') return attention('probeFailed')
+  }
+  return state('missing')
+}
+
+/**
+ * Who closes a row's gap. Infrastructure follows its reported owner. A personal access token is
+ * fixed by whoever holds it: the remedy is a token page, not a workspace setting, so every caller
+ * gets the link. A model or a GitHub connection is a workspace setting.
+ */
+function rowOwner(id: SetupRowId, input: SetupProbeInput): unknown {
+  switch (id) {
+    case 'agentExecutor':
+      return input.infraOwners?.agentExecutor
+    case 'ephemeralEnvironments':
+      return input.infraOwners?.ephemeralEnvironments
+    case 'binaryStorage':
+      return input.infraOwners?.binaryStorage
+    case 'model':
+      return 'workspace_admin'
+    case 'sourceControl':
+      return input.sourceControl.patMissing || input.sourceControl.patProblem
+        ? null
+        : 'workspace_admin'
+    default: {
+      const unreachable: never = id
+      return unreachable
+    }
+  }
+}
+
+function remedyFor(owner: unknown, actor: SetupActor): SetupRemedy | null {
+  if (owner === null) return null
+  if (canActOnSetup(owner, actor)) return null
+  return canActOnSetup(owner, { ...actor, fullSurface: true })
+    ? 'full_surface'
+    : effectiveOwner(owner)
+}
+
+export function deriveSetupChecklist(input: SetupProbeInput): SetupChecklist {
+  const { loaded, needingConfig } = input.providers
+  const states: Record<SetupRowId, RowState> = {
+    model: modelRow(input.model),
+    sourceControl: sourceControlRow(input.sourceControl),
+    agentExecutor: infraRow(input.infra?.agentExecutor, input.workspaceLoaded, {
+      loaded,
+      incomplete: needingConfig.includes('runner-pool'),
+    }),
+    ephemeralEnvironments: infraRow(input.infra?.ephemeralEnvironments, input.workspaceLoaded, {
+      loaded,
+      incomplete: needingConfig.includes('environment'),
+    }),
+    // Storage has no provider connection, so nothing about it waits on the providers.
+    binaryStorage: infraRow(input.infra?.binaryStorage, input.workspaceLoaded, null),
+  }
+  const rows = SETUP_ROWS.map((id) => ({
+    id,
+    ...states[id],
+    required: SETUP_ROW_REQUIRED[id],
+    remedy: remedyFor(rowOwner(id, input), input.actor),
+  }))
+  const counted = rows.filter((r) => r.status !== 'not_needed')
+  return {
+    rows,
+    total: counted.length,
+    done: counted.filter((r) => r.status === 'done').length,
+    checking: counted.some((r) => r.status === 'checking'),
+  }
+}