@cat-factory/app 0.196.1 → 0.197.0

package/app/modular/tutorial-tours.spec.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest'
+import en from '../../i18n/locales/en.json'
+import { TUTORIAL_TOURS, tutorialToursModule } from '~/modular/tutorial-tours'
+import { NAV_CONTRIBUTIONS, navSlotFilter } from '~/modular/nav-contributions'
+import { isSafeTargetId } from '~/components/tutorial/TutorialOverlay.logic'
+import type { AppSlots, NavGates } from '~/modular/nav-contributions'
+
+const ALL_GATES: NavGates = {
+  canWriteBoard: true,
+  canManageIntegrations: true,
+  canManageSettings: true,
+  githubAvailable: true,
+  libraryAvailable: true,
+  infrastructureAvailable: true,
+  accountsEnabled: true,
+  isAccountAdmin: true,
+  advancedMode: true,
+  boardHasService: true,
+}
+
+const slots = (): AppSlots =>
+  ({
+    nav: [...NAV_CONTRIBUTIONS],
+    tutorialTours: [...TUTORIAL_TOURS],
+  }) as unknown as AppSlots
+
+/** Resolve a dot-path against the en catalog; undefined when any hop is missing. */
+function lookupKey(key: string): unknown {
+  return key
+    .split('.')
+    .reduce<unknown>((node, part) => (node as Record<string, unknown> | undefined)?.[part], en)
+}
+
+describe('the built-in tutorial tour catalog', () => {
+  it('has unique tour ids and unique step ids within each tour', () => {
+    const tourIds = TUTORIAL_TOURS.map((t) => t.id)
+    expect(new Set(tourIds).size).toBe(tourIds.length)
+    for (const tour of TUTORIAL_TOURS) {
+      const stepIds = tour.steps.map((s) => s.id)
+      expect(new Set(stepIds).size).toBe(stepIds.length)
+      expect(tour.steps.length).toBeGreaterThan(0)
+    }
+  })
+
+  it('resolves every i18n key it names against the en catalog', () => {
+    // Tour copy is looked up with runtime-assembled keys, which the typed-key check
+    // cannot cover (i18n drift-guard tier 2): pin the catalog here instead, so a renamed
+    // key or a new step without copy fails a test rather than rendering a raw key path.
+    for (const tour of TUTORIAL_TOURS) {
+      for (const key of [tour.titleKey, tour.descriptionKey]) {
+        expect(typeof lookupKey(key), key).toBe('string')
+      }
+      for (const s of tour.steps) {
+        for (const key of [s.titleKey, s.bodyKey]) {
+          expect(typeof lookupKey(key), key).toBe('string')
+        }
+      }
+    }
+  })
+
+  it('names plain data-testid values as targets, never selectors', () => {
+    for (const tour of TUTORIAL_TOURS) {
+      for (const s of tour.steps) {
+        for (const target of [s.target, ...(s.altTargets ?? [])]) {
+          if (target === undefined) continue
+          // Asserted through the runtime's OWN guard, not a copy of its regex: the overlay
+          // drops an id this rejects, so a built-in tour that tripped it would silently
+          // lose the step rather than fail here.
+          expect(isSafeTargetId(target), `${tour.id}/${s.id}: ${target}`).toBe(true)
+        }
+      }
+    }
+  })
+
+  it('is contributed to the tutorialTours slot by the module', () => {
+    expect(tutorialToursModule.slots?.tutorialTours).toEqual([...TUTORIAL_TOURS])
+  })
+})
+
+describe('navSlotFilter over tutorialTours', () => {
+  it('keeps every tour for a fully-gated user', () => {
+    const filtered = navSlotFilter(slots(), { gates: ALL_GATES })
+    expect(filtered.tutorialTours.map((t) => t.id)).toEqual(TUTORIAL_TOURS.map((t) => t.id))
+  })
+
+  it('drops the task-creating tour for a read-only viewer', () => {
+    const viewer: NavGates = { ...ALL_GATES, canWriteBoard: false }
+    const filtered = navSlotFilter(slots(), { gates: viewer })
+    const ids = filtered.tutorialTours.map((t) => t.id)
+    expect(ids).toContain('board-basics')
+    expect(ids).not.toContain('first-task')
+  })
+
+  it('drops the task-creating tour on a board with no service to add a task to', () => {
+    // Every targeted step of that tour would time out in turn and it would then claim to
+    // have taught the core loop; `board-basics` is what an empty board can deliver.
+    const emptyBoard: NavGates = { ...ALL_GATES, boardHasService: false }
+    const filtered = navSlotFilter(slots(), { gates: emptyBoard })
+    const ids = filtered.tutorialTours.map((t) => t.id)
+    expect(ids).toEqual(['board-basics'])
+  })
+
+  it('passes tours through untouched when no gates service is wired', () => {
+    const filtered = navSlotFilter(slots(), {})
+    expect(filtered.tutorialTours.map((t) => t.id)).toEqual(TUTORIAL_TOURS.map((t) => t.id))
+  })
+})

package/app/modular/tutorial-tours.ts

@@ -0,0 +1,147 @@
+import { defineModule } from '@modular-vue/core'
+import type { TutorialTour } from '~/utils/tutorial'
+
+/**
+ * The first-party tutorial-tour catalog, contributed to the `tutorialTours` slot the same
+ * way the nav catalog fills `nav`: declared ONCE as data, rendered by one shared runtime
+ * (`TutorialOverlay`), and open to consumer deployments — `registerAppModule` a module
+ * with its own `tutorialTours` entries and they appear in the launch prompt beside these.
+ *
+ * Authoring rules (what keeps a tour evolvable as the app changes):
+ *
+ *  - A step points at a control by its `data-testid` — the same stable anchor vocabulary
+ *    the e2e suite owns. Covering a control that has none means adding the test id first
+ *    (a behaviour-neutral change), never inventing a parallel attribute.
+ *  - A missing anchor SKIPS the step rather than stranding the tour: controls come and go
+ *    with RBAC, interface tier, and deployment wiring, so a tour must be a set of
+ *    opportunities, not a fixed script. Gate a whole tour on `when` only when its SUBJECT
+ *    requires it (e.g. board-write for a tour that creates a task).
+ *  - "Now click this" steps use `advanceOn: 'target-click'` so the user drives the real
+ *    control and the app's real response (the actual modal, the actual task) is what the
+ *    next step anchors to. Steps whose anchor only exists after that response give it a
+ *    longer `waitForTargetMs`.
+ *  - Copy lives under `tutorial.tours.<tourCamelId>.steps.<stepId>` in the i18n catalogs;
+ *    tours never carry display strings.
+ */
+export const TUTORIAL_TOURS: readonly TutorialTour[] = [
+  {
+    id: 'board-basics',
+    order: 10,
+    icon: 'i-lucide-map',
+    titleKey: 'tutorial.tours.boardBasics.title',
+    descriptionKey: 'tutorial.tours.boardBasics.description',
+    steps: [
+      {
+        id: 'welcome',
+        titleKey: 'tutorial.tours.boardBasics.steps.welcome.title',
+        bodyKey: 'tutorial.tours.boardBasics.steps.welcome.body',
+      },
+      {
+        id: 'canvas',
+        target: 'board-canvas',
+        placement: 'right',
+        titleKey: 'tutorial.tours.boardBasics.steps.canvas.title',
+        bodyKey: 'tutorial.tours.boardBasics.steps.canvas.body',
+      },
+      {
+        id: 'sidebar',
+        target: 'sidebar',
+        placement: 'right',
+        titleKey: 'tutorial.tours.boardBasics.steps.sidebar.title',
+        bodyKey: 'tutorial.tours.boardBasics.steps.sidebar.body',
+      },
+      {
+        id: 'commandBar',
+        target: 'command-bar-launcher',
+        placement: 'right',
+        titleKey: 'tutorial.tours.boardBasics.steps.commandBar.title',
+        bodyKey: 'tutorial.tours.boardBasics.steps.commandBar.body',
+      },
+      {
+        id: 'toolbar',
+        target: 'board-fit-view',
+        placement: 'bottom',
+        titleKey: 'tutorial.tours.boardBasics.steps.toolbar.title',
+        bodyKey: 'tutorial.tours.boardBasics.steps.toolbar.body',
+      },
+      {
+        id: 'finish',
+        titleKey: 'tutorial.tours.boardBasics.steps.finish.title',
+        bodyKey: 'tutorial.tours.boardBasics.steps.finish.body',
+      },
+    ],
+  },
+  {
+    id: 'first-task',
+    order: 20,
+    icon: 'i-lucide-list-plus',
+    titleKey: 'tutorial.tours.firstTask.title',
+    descriptionKey: 'tutorial.tours.firstTask.description',
+    // Creating a task is a board WRITE; a viewer has no add-task button to point at.
+    // It also needs somewhere to PUT the task: on a board with no service frame every
+    // targeted step below would time out in turn, so the tour would spend half a minute
+    // hunting for controls and then claim to have taught the core loop. Offering it only
+    // once a service exists is the honest version — and the launch prompt still lists
+    // `board-basics`, which is the tour an empty board can actually deliver.
+    when: (gates) => gates.canWriteBoard && gates.boardHasService,
+    steps: [
+      {
+        id: 'intro',
+        titleKey: 'tutorial.tours.firstTask.steps.intro.title',
+        bodyKey: 'tutorial.tours.firstTask.steps.intro.body',
+      },
+      {
+        id: 'addTask',
+        target: 'frame-add-task',
+        // An empty frame renders its add-task affordance as a full-width button instead.
+        altTargets: ['frame-add-task-empty'],
+        advanceOn: 'target-click',
+        placement: 'bottom',
+        titleKey: 'tutorial.tours.firstTask.steps.addTask.title',
+        bodyKey: 'tutorial.tours.firstTask.steps.addTask.body',
+      },
+      {
+        id: 'describe',
+        target: 'add-task-title',
+        // Deliberately NOT `target-click`: clicking a text field is how you START typing,
+        // so click-to-advance would move the tooltip off the instruction the moment the
+        // user acted on it. The user reads, types, and presses Next when they are ready;
+        // `target-click` is for buttons, where the click IS the completed action.
+        placement: 'right',
+        // The anchor lives inside the modal the previous click opens; allow it to mount.
+        waitForTargetMs: 8000,
+        titleKey: 'tutorial.tours.firstTask.steps.describe.title',
+        bodyKey: 'tutorial.tours.firstTask.steps.describe.body',
+      },
+      {
+        id: 'create',
+        target: 'add-task-submit',
+        advanceOn: 'target-click',
+        placement: 'top',
+        titleKey: 'tutorial.tours.firstTask.steps.create.title',
+        bodyKey: 'tutorial.tours.firstTask.steps.create.body',
+      },
+      {
+        id: 'card',
+        target: 'task-card',
+        placement: 'bottom',
+        // The card arrives over the live event stream after the create round-trips.
+        waitForTargetMs: 10000,
+        titleKey: 'tutorial.tours.firstTask.steps.card.title',
+        bodyKey: 'tutorial.tours.firstTask.steps.card.body',
+      },
+      {
+        id: 'finish',
+        titleKey: 'tutorial.tours.firstTask.steps.finish.title',
+        bodyKey: 'tutorial.tours.firstTask.steps.finish.body',
+      },
+    ],
+  },
+]
+
+/** The module that contributes the catalog; registered by `createAppRegistry`. */
+export const tutorialToursModule = defineModule({
+  id: 'cat-factory:tutorial-tours',
+  version: '1.0.0',
+  slots: { tutorialTours: [...TUTORIAL_TOURS] },
+})

package/app/pages/index.vue

@@ -138,6 +138,15 @@ const AiProviderOnboardingModal = defineAsyncComponent(
 const AiPresetMismatchDialog = defineAsyncComponent(
   () => import('~/components/providers/AiPresetMismatchDialog.vue'),
 )
+// The in-app tutorial: the launch prompt (auto-opened once for a user who never answered
+// it) and the coach-mark overlay that runs a tour. Both mount only while their store flag
+// is set, so they cost the initial bundle nothing.
+const TutorialPrompt = defineAsyncComponent(
+  () => import('~/components/tutorial/TutorialPrompt.vue'),
+)
+const TutorialOverlay = defineAsyncComponent(
+  () => import('~/components/tutorial/TutorialOverlay.vue'),
+)
 
 const workspace = useWorkspaceStore()
 const github = useGitHubStore()
@@ -267,6 +276,56 @@ watch(
   { immediate: true },
 )
 
+// Offer the tutorial on launch, once the board is up. Yields to every other startup
+// surface — the GitHub onboarding gate and the advisory/onboarding modals above — so a
+// first launch never stacks the tour prompt on top of a dialog that needs answering
+// first; when one of those is open, the flip of its flag re-fires this watcher and the
+// prompt appears then. The store guards the rest: only a user who never answered is
+// asked, at most once per session.
+//
+// Yielding runs in BOTH directions: an advisory that opens LATER (a health probe that
+// resolves a beat after the board) would otherwise land on top of an open tour prompt,
+// which is the stacking this ordering exists to prevent. So the same watcher withdraws
+// an unanswered prompt and re-arms the offer, and the user is asked once the advisory
+// they actually have to answer is gone.
+//
+// The watcher exists only while it can still do something. A saved decision (hydrated
+// synchronously from the persisted store) means it never registers, and once a decision
+// lands — or the offer has been made and left standing — it stops itself, so the steady
+// state pays nothing for the launch offer: no watcher, no mounted component (the v-ifs
+// below), no store reads.
+const tutorial = useTutorialStore()
+const startupAdvisoryOpen = computed(
+  () =>
+    needsGitHubInstall.value ||
+    githubProbePending.value ||
+    ui.pipelineHealthOpen ||
+    ui.riskPolicyHealthOpen ||
+    ui.modelPresetHealthOpen ||
+    ui.aiProviderSetupOpen ||
+    ui.aiPresetMismatchOpen,
+)
+// Settled = the offer can never need to act again: a decision exists, or the prompt was
+// auto-opened and is still standing (a deferral clears `promptAutoOpened`, which is
+// exactly what keeps the watcher alive to re-offer).
+const tutorialOfferSettled = () =>
+  tutorial.decision !== null || (tutorial.promptAutoOpened && !tutorial.promptOpen)
+if (!tutorialOfferSettled()) {
+  // `let` + optional call: with `immediate: true` the first run happens synchronously
+  // inside `watch(...)`, before the handle is assigned — the trailing check covers it.
+  let stopTutorialOffer: (() => void) | undefined
+  stopTutorialOffer = watch(
+    () => [workspace.ready, startupAdvisoryOpen.value, tutorial.promptOpen],
+    () => {
+      if (startupAdvisoryOpen.value) tutorial.deferPrompt()
+      else if (workspace.ready) tutorial.maybeOfferOnLaunch()
+      if (tutorialOfferSettled()) stopTutorialOffer?.()
+    },
+    { immediate: true },
+  )
+  if (tutorialOfferSettled()) stopTutorialOffer()
+}
+
 // Probe the GitHub integration as soon as a board is active (re-probe per board —
 // connections are per workspace). The result drives the onboarding gate below
 // before the board mounts, so an unconnected user can't slip past it. `ensureProbed`
@@ -448,6 +507,8 @@ watch(
       <VendorCredentialsModal v-if="ui.vendorCredentialsOpen" />
       <AiProviderOnboardingModal v-if="ui.aiProviderSetupOpen" />
       <AiPresetMismatchDialog v-if="ui.aiPresetMismatchOpen" />
+      <TutorialPrompt v-if="tutorial.promptOpen" />
+      <TutorialOverlay v-if="tutorial.touring" />
     </template>
 
     <!-- Backend unreachable / bootstrap failed -->

package/app/stores/board/dependencies.ts

@@ -0,0 +1,52 @@
+import { useWorkspaceStore } from '~/stores/workspace'
+import type { BoardWriteContext } from './context'
+
+/**
+ * The board's dependency-edge writes. Split out of {@link createBoardPlacement} along the same
+ * seam it was split from {@link createBoardMutations}: it closes over the shared
+ * {@link BoardWriteContext} so behaviour is identical to the original in-closure functions, and
+ * the split is purely to keep every function within the size budget.
+ */
+export function createBoardDependencies(ctx: BoardWriteContext) {
+  const { getBlock, upsert, api, toast, tr } = ctx
+
+  /**
+   * Toggle a dependency edge target -> source (target dependsOn source). The backend
+   * rejects an edge that would close a cycle (422) — surface that as a toast rather than
+   * letting it throw unhandled out of a board gesture.
+   */
+  async function toggleDependency(targetId: string, sourceId: string) {
+    if (targetId === sourceId || !getBlock(targetId)) return
+    try {
+      upsert(await api.toggleDependency(useWorkspaceStore().requireId(), targetId, { sourceId }))
+    } catch (e) {
+      toast.add({
+        title: tr('board.toast.linkFailed'),
+        description: e instanceof Error ? e.message : String(e),
+        icon: 'i-lucide-triangle-alert',
+        color: 'error',
+      })
+    }
+  }
+
+  /** Remove a dependency edge target -> source if it exists. */
+  async function removeDependency(targetId: string, sourceId: string) {
+    const t = getBlock(targetId)
+    if (!t || !t.dependsOn.includes(sourceId)) return
+    // the backend exposes a single toggle; the edge exists, so toggling removes it
+    try {
+      upsert(await api.toggleDependency(useWorkspaceStore().requireId(), targetId, { sourceId }))
+    } catch (e) {
+      // Mirror `toggleDependency`: a failure must surface (and leave the edge visible) rather
+      // than rejecting unhandled with no feedback.
+      toast.add({
+        title: tr('board.toast.unlinkFailed'),
+        description: e instanceof Error ? e.message : String(e),
+        icon: 'i-lucide-triangle-alert',
+        color: 'error',
+      })
+    }
+  }
+
+  return { toggleDependency, removeDependency }
+}

package/app/stores/board/placement.ts

@@ -1,6 +1,7 @@
 import type { UpdateBlockInput } from '@cat-factory/contracts'
 import { useServicesStore } from '~/stores/services'
 import { useWorkspaceStore } from '~/stores/workspace'
+import { createBoardDependencies } from './dependencies'
 import type { BoardWriteContext } from './context'
 import { UNDO_WINDOW_MS } from './context'
 
@@ -215,43 +216,9 @@ export function createBoardPlacement(ctx: BoardWriteContext) {
     }
   }
 
-  /**
-   * Toggle a dependency edge target -> source (target dependsOn source). The backend
-   * rejects an edge that would close a cycle (422) — surface that as a toast rather than
-   * letting it throw unhandled out of a board gesture.
-   */
-  async function toggleDependency(targetId: string, sourceId: string) {
-    if (targetId === sourceId || !getBlock(targetId)) return
-    try {
-      upsert(await api.toggleDependency(useWorkspaceStore().requireId(), targetId, { sourceId }))
-    } catch (e) {
-      toast.add({
-        title: tr('board.toast.linkFailed'),
-        description: e instanceof Error ? e.message : String(e),
-        icon: 'i-lucide-triangle-alert',
-        color: 'error',
-      })
-    }
-  }
-
-  /** Remove a dependency edge target -> source if it exists. */
-  async function removeDependency(targetId: string, sourceId: string) {
-    const t = getBlock(targetId)
-    if (!t || !t.dependsOn.includes(sourceId)) return
-    // the backend exposes a single toggle; the edge exists, so toggling removes it
-    try {
-      upsert(await api.toggleDependency(useWorkspaceStore().requireId(), targetId, { sourceId }))
-    } catch (e) {
-      // Mirror `toggleDependency`: a failure must surface (and leave the edge visible) rather
-      // than rejecting unhandled with no feedback.
-      toast.add({
-        title: tr('board.toast.unlinkFailed'),
-        description: e instanceof Error ? e.message : String(e),
-        icon: 'i-lucide-triangle-alert',
-        color: 'error',
-      })
-    }
-  }
+  // The dependency-edge writes, split along the same seam into a sibling factory over the same
+  // context; re-exposed here so every existing caller is unchanged.
+  const { toggleDependency, removeDependency } = createBoardDependencies(ctx)
 
   return {
     reparentBlock,

package/app/stores/execution/pendingGates.ts

@@ -0,0 +1,109 @@
+import { computed, type Ref } from 'vue'
+import type { Decision, ExecutionInstance, PipelineStep, StepApproval } from '~/types/domain'
+
+/**
+ * The read-only projections of what across every cached run is awaiting a human: the open
+ * decisions and approval gates, their per-block indexes, and the two badge counts.
+ *
+ * Created once in the `execution` store setup over its `instances` ref, so the derivations stay
+ * behaviourally identical to the former in-closure computeds — a size-only extraction mirroring
+ * {@link createExecutionCommands}, not a new seam.
+ */
+export function createPendingGateSelectors(instances: Ref<ExecutionInstance[]>) {
+  /** How many decisions anywhere are awaiting a human. */
+  const pendingDecisionCount = computed(() =>
+    instances.value.reduce(
+      (n, e) => n + e.steps.filter((s) => s.decision && !s.decision.chosen).length,
+      0,
+    ),
+  )
+
+  /** All currently-unresolved decisions across all runs (for the toolbar/queue). */
+  const openDecisions = computed(() => {
+    const out: {
+      instanceId: string
+      blockId: string
+      decision: Decision
+      agentKind: PipelineStep['agentKind']
+    }[] = []
+    for (const e of instances.value) {
+      for (const s of e.steps) {
+        if (s.decision && !s.decision.chosen) {
+          out.push({
+            instanceId: e.id,
+            blockId: e.blockId,
+            decision: s.decision,
+            agentKind: s.agentKind,
+          })
+        }
+      }
+    }
+    return out
+  })
+
+  /** All currently-pending approval gates across all runs (board badges/queue). */
+  const openApprovals = computed(() => {
+    const out: {
+      instanceId: string
+      blockId: string
+      approval: StepApproval
+      agentKind: PipelineStep['agentKind']
+      /**
+       * Whether the gate's proposal is a RENDERING of an artifact the step already committed
+       * (`step.outputIsRendered`). Projected here because a surface that reviews the proposal
+       * WITHOUT the step in hand — the initiative tracker's plan-approval rail — otherwise has
+       * no way to tell a rendered document from the agent's raw transcript summary, and would
+       * present a one-line summary as though it were the artifact.
+       */
+      outputIsRendered: boolean
+    }[] = []
+    for (const e of instances.value) {
+      for (const s of e.steps) {
+        if (s.approval?.status === 'pending') {
+          out.push({
+            instanceId: e.id,
+            blockId: e.blockId,
+            approval: s.approval,
+            agentKind: s.agentKind,
+            outputIsRendered: s.outputIsRendered === true,
+          })
+        }
+      }
+    }
+    return out
+  })
+
+  /**
+   * Open decisions/approvals grouped by the block they belong to, so a board card
+   * resolves its own + its tasks' pending gates with O(1) lookups instead of
+   * re-filtering the global lists once per frame on every execution event.
+   */
+  function groupByBlock<T extends { blockId: string }>(items: T[]): Map<string, T[]> {
+    const map = new Map<string, T[]>()
+    for (const item of items) {
+      const list = map.get(item.blockId)
+      if (list) list.push(item)
+      else map.set(item.blockId, [item])
+    }
+    return map
+  }
+  const decisionsByBlock = computed(() => groupByBlock(openDecisions.value))
+  const approvalsByBlock = computed(() => groupByBlock(openApprovals.value))
+
+  /** How many approval gates anywhere are awaiting a human. */
+  const pendingApprovalCount = computed(() =>
+    instances.value.reduce(
+      (n, e) => n + e.steps.filter((s) => s.approval?.status === 'pending').length,
+      0,
+    ),
+  )
+
+  return {
+    pendingDecisionCount,
+    openDecisions,
+    openApprovals,
+    decisionsByBlock,
+    approvalsByBlock,
+    pendingApprovalCount,
+  }
+}

package/app/stores/execution.ts

@@ -1,7 +1,8 @@
 import { defineStore } from 'pinia'
 import { ref, computed } from 'vue'
-import type { Decision, ExecutionInstance, PipelineStep, StepApproval } from '~/types/domain'
+import type { ExecutionInstance } from '~/types/domain'
 import { createExecutionCommands } from '~/stores/execution/commands'
+import { createPendingGateSelectors } from '~/stores/execution/pendingGates'
 
 /**
  * Running pipeline instances. The simulation engine lives on the backend: this
@@ -188,93 +189,10 @@ export const useExecutionStore = defineStore('execution', () => {
     return runs.find((e) => !isTerminal(e.status)) ?? runs.at(-1)
   }
 
-  /** How many decisions anywhere are awaiting a human. */
-  const pendingDecisionCount = computed(() =>
-    instances.value.reduce(
-      (n, e) => n + e.steps.filter((s) => s.decision && !s.decision.chosen).length,
-      0,
-    ),
-  )
-
-  /** All currently-unresolved decisions across all runs (for the toolbar/queue). */
-  const openDecisions = computed(() => {
-    const out: {
-      instanceId: string
-      blockId: string
-      decision: Decision
-      agentKind: PipelineStep['agentKind']
-    }[] = []
-    for (const e of instances.value) {
-      for (const s of e.steps) {
-        if (s.decision && !s.decision.chosen) {
-          out.push({
-            instanceId: e.id,
-            blockId: e.blockId,
-            decision: s.decision,
-            agentKind: s.agentKind,
-          })
-        }
-      }
-    }
-    return out
-  })
-
-  /** All currently-pending approval gates across all runs (board badges/queue). */
-  const openApprovals = computed(() => {
-    const out: {
-      instanceId: string
-      blockId: string
-      approval: StepApproval
-      agentKind: PipelineStep['agentKind']
-      /**
-       * Whether the gate's proposal is a RENDERING of an artifact the step already committed
-       * (`step.outputIsRendered`). Projected here because a surface that reviews the proposal
-       * WITHOUT the step in hand — the initiative tracker's plan-approval rail — otherwise has
-       * no way to tell a rendered document from the agent's raw transcript summary, and would
-       * present a one-line summary as though it were the artifact.
-       */
-      outputIsRendered: boolean
-    }[] = []
-    for (const e of instances.value) {
-      for (const s of e.steps) {
-        if (s.approval?.status === 'pending') {
-          out.push({
-            instanceId: e.id,
-            blockId: e.blockId,
-            approval: s.approval,
-            agentKind: s.agentKind,
-            outputIsRendered: s.outputIsRendered === true,
-          })
-        }
-      }
-    }
-    return out
-  })
-
-  /**
-   * Open decisions/approvals grouped by the block they belong to, so a board card
-   * resolves its own + its tasks' pending gates with O(1) lookups instead of
-   * re-filtering the global lists once per frame on every execution event.
-   */
-  function groupByBlock<T extends { blockId: string }>(items: T[]): Map<string, T[]> {
-    const map = new Map<string, T[]>()
-    for (const item of items) {
-      const list = map.get(item.blockId)
-      if (list) list.push(item)
-      else map.set(item.blockId, [item])
-    }
-    return map
-  }
-  const decisionsByBlock = computed(() => groupByBlock(openDecisions.value))
-  const approvalsByBlock = computed(() => groupByBlock(openApprovals.value))
-
-  /** How many approval gates anywhere are awaiting a human. */
-  const pendingApprovalCount = computed(() =>
-    instances.value.reduce(
-      (n, e) => n + e.steps.filter((s) => s.approval?.status === 'pending').length,
-      0,
-    ),
-  )
+  // What across every cached run is awaiting a human (open decisions + approval gates, their
+  // per-block indexes and the two badge counts), extracted into a cohesive factory over the same
+  // `instances` ref — a size-only split mirroring `createExecutionCommands` below.
+  const pendingGates = createPendingGateSelectors(instances)
 
   // The run-control commands (start / decide / approve / merge / restart / cancel / stop),
   // extracted into a cohesive factory sharing the state above (a size-only split mirroring
@@ -290,12 +208,7 @@ export const useExecutionStore = defineStore('execution', () => {
     byId,
     getInstance,
     getByBlock,
-    pendingDecisionCount,
-    openDecisions,
-    openApprovals,
-    decisionsByBlock,
-    approvalsByBlock,
-    pendingApprovalCount,
+    ...pendingGates,
     ...commands,
   }
 })