@cat-factory/app 0.311.3 → 0.313.0

package/app/composables/useTaskActions.ts

@@ -0,0 +1,254 @@
+import { computed, ref } from 'vue'
+import { defaultBuildPipelineId } from '@cat-factory/contracts'
+import type { Block } from '~/types/domain'
+import { composeRunOutcome, hasOutcomeToShow } from '~/utils/runOutcome'
+
+/**
+ * What a task offers a human to DO, and the handlers that do it.
+ *
+ * Shared by the two surfaces that put a task's action within one click: the board's task card
+ * and the queue's card. Both must offer the same Start (same pipeline), the same Resolve (same
+ * gate) and the same Merge (same confirm), or a reader would learn two products.
+ */
+export function useTaskActions(taskId: () => string) {
+  const board = useBoardStore()
+  const execution = useExecutionStore()
+  const ui = useUiStore()
+  const reviews = useReviewStage()
+  const toast = useActionToast()
+  const { t } = useI18n()
+  const { confirm } = useConfirm()
+  const access = useWorkspaceAccess()
+
+  const task = computed<Block | undefined>(() => board.getBlock(taskId()))
+
+  // This Start is a ONE-TAP live start, so it has nothing to ask for and offers no dry-run
+  // request. What it does owe the reader is the half that is not a choice: a preset that sandboxes
+  // their role means this button opens a pull request and merges nothing, and a card that said so
+  // only after the fact would leave that to be discovered from a run that stops at the merge.
+  const { forcedFor } = useDryRunPolicy()
+  const sandboxed = computed(() => forcedFor(taskId()))
+
+  /** Deps that haven't merged yet: these block this task from running. */
+  const unmet = computed(() => board.unmetDeps(taskId()))
+  const runnable = computed(() => board.isRunnable(taskId()))
+
+  // Start and Merge both need `runs.execute`. A read-only member sees them disabled with the reason,
+  // the way the shared failure banner treats Retry, rather than pressing a button the server
+  // refuses. Asked once here so the two cards cannot gate them differently.
+  const canExecute = computed(() => access.canExecuteRuns.value)
+  const executeDeniedTitle = computed(() =>
+    canExecute.value ? undefined : t('access.noRunExecute'),
+  )
+
+  const pipelineFor = useStartPipelineResolver()
+  const defaultPipeline = computed(() => pipelineFor(task.value))
+
+  /**
+   * Whether the outcome summary has something to show, asked of the SAME reduction the window
+   * renders and the inspector's button gates on: a surface that offered "read the result" on a
+   * task whose every section says "nothing here" would teach people the surface is empty. A task
+   * marked done by hand, with no pull request and no run, is that task.
+   */
+  const outcomeReadable = computed(() => {
+    const block = task.value
+    if (!block) return false
+    return hasOutcomeToShow(
+      composeRunOutcome({ block, instance: execution.getInstance(block.executionId) ?? null }),
+    )
+  })
+
+  function openOutcome() {
+    ui.openOutcome(taskId(), task.value?.executionId ?? null)
+  }
+
+  // Optimistic "Start": flip the button into a spinning "Starting…" state the instant it's
+  // clicked, before the server confirms. The button naturally unmounts once the stream pushes the
+  // block into `in_progress`; if the start call faults we revert and surface a toast.
+  const starting = ref(false)
+
+  async function start() {
+    if (!runnable.value) {
+      // A refusal decided in the browser, in translated copy: the `error` tone (`useActionToast`).
+      toast.error('board.task.blockedByDependenciesTitle', {
+        description: t('board.task.waitingOn', {
+          deps: unmet.value.map((d) => d.title).join(', '),
+        }),
+      })
+      return
+    }
+    const pipeline = defaultPipeline.value
+    if (!pipeline) {
+      toast.error('board.task.noPipelineTitle', { description: t('board.task.noPipelineBody') })
+      return
+    }
+    starting.value = true
+    // false ⇒ the run never started (the user cancelled the personal-password prompt, or the
+    // start was refused: the store surfaces the actionable toast itself). Revert the optimistic
+    // state; on success the button unmounts once the stream pushes in_progress.
+    const started = await execution.start(taskId(), pipeline)
+    if (started) {
+      // Confirm the (optimistic) start landed: the button unmounts once the stream pushes
+      // in_progress, so without this the successful action gives no feedback. A sandboxed start
+      // says so here rather than borrowing the live wording: this is the moment the reader learns
+      // what they just started, and the two runs differ in what they will end up doing.
+      // A sandboxed run is `warning`: it ran, and its outcome differs in a way the reader should
+      // know (it opens a pull request and merges nothing), so it stays until closed.
+      if (sandboxed.value) {
+        toast.warning('board.dryRunToast.title', {
+          description: t('board.dryRunToast.body', { name: pipeline.name }),
+        })
+      } else {
+        toast.success('board.task.startedToast.title', {
+          description: t('board.task.startedToast.body', { name: pipeline.name }),
+        })
+      }
+    } else {
+      starting.value = false
+    }
+  }
+
+  async function merge() {
+    // Merging a PR into its base is consequential and effectively irreversible: gate it behind a
+    // confirm (plain, not the destructive shape). `execution.mergePr` surfaces its own error toast.
+    const ok = await confirm({
+      title: t('board.task.mergeConfirm.title'),
+      description: t('board.task.mergeConfirm.body'),
+      confirmLabel: t('board.task.mergeConfirm.confirm'),
+      icon: 'i-lucide-git-merge',
+    })
+    if (!ok) return
+    await execution.mergePr(taskId())
+  }
+
+  // A `blocked` task is waiting on a human for one of two reasons, an agent-raised decision OR an
+  // approval gate, and both must surface (a failed run is shown separately by the
+  // AgentFailureCard). Read off the per-block index rather than scanning the workspace-wide list:
+  // this computed is mounted once per card and invalidated by every execution event.
+  const pendingDecision = computed(() => execution.decisionsByBlock.get(taskId())?.[0])
+  // The async stage an iterative reviewer gate (requirements-review / clarity-review) is mid-cycle
+  // in (folding the answers, then re-reviewing), or null. While set, the gate needs NO human
+  // action, so its approval is suppressed below and a working indicator shows instead.
+  const reviewStage = computed(() => reviews.stageForBlock(taskId()))
+  const reviewStageLabel = computed(() =>
+    reviewStage.value === 'incorporating'
+      ? t('board.task.incorporatingAnswers')
+      : reviewStage.value === 'reviewing'
+        ? t('board.task.reReviewing')
+        : reviewStage.value === 'recommending'
+          ? t('board.task.recommending')
+          : null,
+  )
+  const pendingApproval = computed(() => {
+    // A reviewer gate whose review is incorporating / re-reviewing in the driver is doing
+    // background work, not awaiting a human: skip it, and offer the first gate a human IS
+    // awaiting. The lane classifier counts any such gate, so a card filed under Needs you for an
+    // approval always has that approval to open.
+    return execution.approvalsByBlock
+      .get(taskId())
+      ?.find((a) => !reviews.isBackground(a.agentKind, taskId()))
+  })
+
+  /**
+   * What this blocked task actually needs from a human: drives the card's label, pulse and
+   * action. Decision takes precedence over approval (a step never holds both at once; this is
+   * just a stable order). Null when nothing is pending.
+   */
+  const attention = computed<{
+    label: string
+    icon: string
+    action: string
+    open: () => void
+  } | null>(() => {
+    const d = pendingDecision.value
+    if (d)
+      return {
+        label: t('board.task.decisionNeeded'),
+        icon: 'i-lucide-circle-help',
+        action: t('board.task.resolve'),
+        open: () => ui.openDecision(d.instanceId, d.decision.id),
+      }
+    const a = pendingApproval.value
+    if (a)
+      return {
+        label: t('board.task.approvalNeeded'),
+        icon: 'i-lucide-shield-check',
+        action: t('board.task.approve'),
+        open: () => ui.openApprovalDetail(a.instanceId, a.approval.id),
+      }
+    return null
+  })
+
+  return {
+    task,
+    sandboxed,
+    unmet,
+    runnable,
+    canExecute,
+    executeDeniedTitle,
+    defaultPipeline,
+    outcomeReadable,
+    openOutcome,
+    starting,
+    start,
+    merge,
+    pendingDecision,
+    reviewStage,
+    reviewStageLabel,
+    attention,
+  }
+}
+
+/** The pipeline a plain "Start" runs, as the descriptor `execution.start` takes. */
+export interface StartPipeline {
+  id: string
+  name: string
+}
+
+/**
+ * Resolve the pipeline a plain "Start" uses for a task. A function rather than a computed so
+ * a caller can ask it about any task, not only about the one its card shows.
+ */
+export function useStartPipelineResolver() {
+  const pipelines = usePipelinesStore()
+  const uiMode = useUiModeStore()
+  const { t } = useI18n()
+
+  /**
+   * The pipeline a plain "Start" will use: the task's pinned pipeline, else the build rung this
+   * INTERFACE MODE defaults to (`defaultBuildPipelineId`: the fixed Standard build in basic mode,
+   * the Adaptive one in advanced). The workspace's positional first pipeline remains the last
+   * resort, for a board whose catalog does not carry the rung (an older seed, or a deployment that
+   * retired it).
+   *
+   * A PIN is honoured even when the library holds no row for it, and that branch is the whole reason
+   * this returns a descriptor rather than a `Pipeline`. An INTERNAL pipeline is withheld from the
+   * library on purpose (the platform starts it on its own behalf, so no picker may offer it), and a
+   * task can legitimately be pinned to one: the docs-refresh preset spawns its tasks onto
+   * `pl_code_comments`. Resolving that pin through the library alone answers undefined, and the
+   * fallback below then starts a FULL BUILD on a comment-only task while the button still reads as
+   * an ordinary Start. The fallback chain exists for a task with NO pin; a pin the library cannot
+   * show is still the task's answer, and the backend resolves the id for the run.
+   */
+  return (task: Pick<Block, 'pipelineId'> | undefined): StartPipeline | undefined => {
+    const pinnedId = task?.pipelineId
+    if (pinnedId) {
+      return (
+        pipelines.getPipeline(pinnedId) ?? {
+          id: pinnedId,
+          // The catalog NAME map spans the whole catalog (unlike the versions map), so an internal
+          // pin still names itself here; the generic label covers a pin to something this build's
+          // catalog does not know at all.
+          name: pipelines.catalogNames[pinnedId] ?? t('board.task.pipelineFallback'),
+        }
+      )
+    }
+    // No pin: the workspace's own DECLARED in-app default outranks the interface-mode rung, because
+    // an operator who named one said something a tier cannot overrule.
+    const declared = pipelines.declaredDefaultId('interactive')
+    return (
+      pipelines.getPipeline(declared ?? defaultBuildPipelineId(uiMode.isAdvanced)) ??
+      pipelines.pipelines[0]
+    )
+  }
+}

package/app/composables/useTaskLaneClassifier.ts

@@ -0,0 +1,88 @@
+import type { Block } from '~/types/domain'
+import { runActivityAt, runWaitingSince, type LaneTaskEntry } from '~/utils/laneSort'
+import { classifyTask, type TaskLane } from '~/utils/swimlanes'
+
+/** A lane entry plus the lane it was classified into. */
+export interface ClassifiedEntry {
+  readonly entry: LaneTaskEntry
+  readonly lane: TaskLane
+}
+
+/**
+ * The store-facing half of `classifyTask`: resolve one task's lane, reason and rendered entry.
+ *
+ * Shared by the two surfaces that lay tasks out in lanes, a service frame's swimlanes
+ * (`useFrameLanes`) and the workspace-wide queue (`useWorkspaceQueueStore`), so both state the SAME
+ * claim about a task. A card in "Needs you" on the board and in "In flight" in the queue would
+ * make the reader arbitrate between two answers to one question.
+ *
+ * Every cross-block lookup here is a Map read off an index a STORE maintains, never a reduction
+ * of its own: `useFrameLanes` runs one instance per mounted frame, so deriving a workspace-wide
+ * fact here makes a board with n frames pay for it n times on every change. The review-debt map
+ * (`notifications.reviewDebtByBlock`) is the worked example: a reduction over the whole
+ * workspace's open notifications, and it belongs on the store that owns its input.
+ */
+export function useTaskLaneClassifier() {
+  const board = useBoardStore()
+  const execution = useExecutionStore()
+  const agentRuns = useAgentRunsStore()
+  const notifications = useNotificationsStore()
+  const reviews = useReviewStage()
+
+  /**
+   * The module a task belongs to: the module BLOCK's title when it already lives in one, else
+   * the module it DECLARES. The engine only materialises the block on merge
+   * (`applyModuleAssignment`), so keying on the parent alone would leave every unmerged task in
+   * "no module" while its own card names one.
+   */
+  function moduleNameOf(task: Block): string | null {
+    const parent = task.parentId ? board.getBlock(task.parentId) : undefined
+    if (parent?.level === 'module') return parent.title
+    return task.moduleName?.trim() || null
+  }
+
+  /** One task's lane, reason and rendered entry. `order` is the caller's stable tiebreak. */
+  function classify(task: Block, order: number): ClassifiedEntry {
+    const run = execution.getByBlock(task.id) ?? null
+    const decisions = execution.decisionsByBlock.get(task.id) ?? []
+    const allApprovals = execution.approvalsByBlock.get(task.id) ?? []
+    // The same suppression the card and the frame badge apply: an iterative reviewer mid-cycle
+    // holds a pending approval while the driver folds answers in, and nobody is waiting on it.
+    const humanApprovals = allApprovals.filter((a) => !reviews.isBackground(a.agentKind, a.blockId))
+
+    const { lane, reason } = classifyTask({
+      status: task.status,
+      // Read from the coarse per-block summary, which also covers a bootstrap run.
+      runFailed: agentRuns.byBlock[task.id]?.status === 'failed',
+      run,
+      // A park is background exactly when everything asking was suppressed AND nothing else
+      // asks. With no approvals at all it is NOT background: it is a park on a surface this
+      // layer cannot name, which `classifyTask` reports as `parked` rather than as work.
+      parkIsBackground:
+        decisions.length === 0 &&
+        humanApprovals.length === 0 &&
+        allApprovals.length > humanApprovals.length,
+      pendingDecision: decisions.length > 0,
+      pendingApproval: humanApprovals.length > 0,
+      hasUnmetDeps: board.unmetDeps(task.id).length > 0,
+    })
+
+    return {
+      lane,
+      entry: {
+        task,
+        reason,
+        order,
+        activityAt: runActivityAt(run),
+        waitingSince: runWaitingSince(run, notifications.reviewDebtByBlock.get(task.id) ?? null),
+        moduleName: moduleNameOf(task),
+        initiativeName: task.initiativeId
+          ? (board.getBlock(task.initiativeId)?.title ?? null)
+          : null,
+        epicName: board.epicOf(task)?.title ?? null,
+      },
+    }
+  }
+
+  return { classify }
+}

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

@@ -224,6 +224,8 @@ describe('navSlotFilter', () => {
       tutorial: 'the walkthroughs - the surface with the fewest destinations needs them most',
       'keyboard-shortcuts': 'the cheatsheet covers the board and the palette, which every role has',
       'ui-role': 'the way BACK out of the narrowed role',
+      'queue-view': 'which view of the board a person works in is their own choice, in every role',
+      'board-view': 'the way back to the canvas from the queue view, in every role',
     }
     const intake = NAV_CONTRIBUTIONS.filter((i) => i.intake).map((i) => i.id)
     expect(intake.sort()).toEqual(Object.keys(REASON).sort())
@@ -489,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',
@@ -522,6 +525,9 @@ 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',
@@ -220,6 +221,8 @@ export const NAV_ACTIONS = [
   'tutorial',
   'toggleUiMode',
   'chooseRole',
+  'queueView',
+  'boardView',
 ] as const
 
 export type NavActionId = (typeof NAV_ACTIONS)[number]
@@ -536,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',
@@ -737,6 +764,35 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
       keywordsKey: 'layout.commandBar.keywords.chooseRole',
     },
   },
+  {
+    // The board's two views (issue #2258). The sidebar's Views switcher is the everyday route;
+    // these make each view reachable by name from the palette too. Every tier and role: which view
+    // a person works in is their own choice, and neither view is an override of the other.
+    id: 'queue-view',
+    labelKey: 'layout.commandBar.cmd.queueView',
+    icon: 'i-lucide-list-checks',
+    surfaces: S('command'),
+    intake: true,
+    action: 'queueView',
+    command: {
+      group: 'workspace',
+      order: 130,
+      keywordsKey: 'layout.commandBar.keywords.queueView',
+    },
+  },
+  {
+    id: 'board-view',
+    labelKey: 'layout.commandBar.cmd.boardView',
+    icon: 'i-lucide-map',
+    surfaces: S('command'),
+    intake: true,
+    action: 'boardView',
+    command: {
+      group: 'workspace',
+      order: 131,
+      keywordsKey: 'layout.commandBar.keywords.boardView',
+    },
+  },
 ]
 
 /**

package/app/modular/tutorial-tours.ts

@@ -194,6 +194,16 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
         titleKey: 'tutorial.tours.boardBasics.steps.canvas.title',
         bodyKey: 'tutorial.tours.boardBasics.steps.canvas.body',
       },
+      {
+        // A new person lands on the QUEUE view, and every tour moves them to the canvas, so the
+        // orientation tour is where they learn the queue exists. The switcher renders in the rail
+        // and the expanded sidebar, in every tier and role, so the step needs no `when`.
+        id: 'views',
+        target: 'work-view-switcher',
+        placement: 'right',
+        titleKey: 'tutorial.tours.boardBasics.steps.views.title',
+        bodyKey: 'tutorial.tours.boardBasics.steps.views.body',
+      },
       {
         id: 'sidebar',
         target: 'sidebar',

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'),
 )
@@ -159,12 +162,15 @@ const TutorialNudge = defineAsyncView(() => import('~/components/tutorial/Tutori
 // The first-run role question (Engineer / Product manager / Designer). Same shape as the tutorial
 // launch prompt: mounted only while its store flag is set, so an answered question costs nothing.
 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 workspace = useWorkspaceStore()
 const github = useGitHubStore()
 const models = useModelsStore()
 const ui = useUiStore()
 const aiReadiness = useAiReadiness()
+const views = useWorkViewStore()
 
 // App-wide keyboard shortcuts (Escape to deselect, Delete to remove the selected block, ?
 // for the cheatsheet). Registered ONCE here so a single global listener owns them.
@@ -176,6 +182,8 @@ onMounted(() => {
   // board it names is the one that opens. This is what makes the observability link on an
   // engine-published PR verification report resolve.
   useRunDeepLink()
+  // `?view=queue` / `?view=board`: a link that opens one of the board's two views.
+  views.consumeDeepLink()
   void workspace.init()
   // Honour a `cat-factory k3s` CLI hand-off (`?infraSetup=local-k3s&…`): open the Infrastructure
   // window pre-seeded with the provisioned connection so the user only pastes the token + saves.
@@ -401,6 +409,14 @@ useTutorialNudge()
 // plus the funnel counters. Unconditional and best-effort: with no accounts or no store wired it
 // simply has nothing to talk to, and the browser-persisted store carries on alone.
 useTutorialSync()
+// Starting a tour switches to the canvas, which every tour walks (the view store holds it for the
+// tour's length), and the canvas is then the view used last.
+watch(
+  () => tutorial.touring,
+  (touring) => {
+    if (touring) views.show('board')
+  },
+)
 
 // Subscribe to the backend's real-time event stream and (re)connect whenever the
 // active workspace changes. Runs advance durably server-side; progress arrives as
@@ -462,12 +478,32 @@ watch(
         <main class="relative min-w-0 flex-1">
           <BoardCanvas />
           <!-- Toolbar, nav trigger and every advisory banner, in ONE stacked region that owns
-               their placement, so no two of them can cover each other. -->
-          <BoardTopOverlays
-            :connected="streamConnected"
-            :ever-connected="streamEverConnected"
-            :connection-failed="streamConnectionFailed"
-          />
+               their placement, so no two of them can cover each other.
+
+               The queue view sits OVER the canvas rather than replacing it, so switching back keeps
+               the canvas's camera and selection. Below the inspector (z-20), so a task opened from
+               the queue shows its panel beside it. The same advisories render IN FLOW above its
+               columns, so they push the queue down instead of covering its header.
+
+               ONE overlay instance serves both views, at the same place in this template: two
+               instances would remount every banner on each switch, and a banner whose dismissal
+               is its own component state would come back. On the canvas the wrapper is
+               `display: contents`, so it adds no box and the overlays float over the canvas as
+               before. -->
+          <div
+            :class="
+              views.view === 'queue' ? 'absolute inset-0 z-10 flex flex-col bg-app-950' : 'contents'
+            "
+            :data-testid="views.view === 'queue' ? 'queue-view-host' : undefined"
+          >
+            <BoardTopOverlays
+              :in-flow="views.view === 'queue'"
+              :connected="streamConnected"
+              :ever-connected="streamEverConnected"
+              :connection-failed="streamConnectionFailed"
+            />
+            <QueueView v-if="views.view === 'queue'" class="min-h-0 flex-1" />
+          </div>
           <InspectorPanel />
           <!-- Code-split focus view. The fade lives here (not inside the component) so the
                leave animation still plays when `focusBlockId` clears and the v-if unmounts
@@ -531,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,