@cat-factory/app 0.181.0 → 0.182.1

package/app/composables/useInitiativePlanning.ts

@@ -4,7 +4,24 @@ import { useExecutionStore } from '~/stores/execution'
 import { useInitiativesStore } from '~/stores/initiative'
 import { usePipelinesStore } from '~/stores/pipelines'
 import { useUiStore } from '~/stores/ui'
-import { interviewGatePhase } from '~/utils/interviewGate'
+import { agentKindMeta } from '~/utils/catalog'
+import { selectPlanApproval, type InitiativeAttentionKind } from '~/utils/initiative'
+import {
+  INITIATIVE_INTERVIEWER_KIND,
+  interviewGatePhase,
+  interviewStepReached,
+} from '~/utils/interviewGate'
+
+/**
+ * What an initiative's planning run needs from a human right now: which kind of park it is (the
+ * card + inspector resolve its icon/label from the shared `INITIATIVE_ATTENTION_*` maps, so the
+ * two surfaces word one park identically), and the action that opens the surface which can
+ * RESOLVE it — the step's own dedicated window, via `dispatchStepView`.
+ */
+export interface InitiativeAttention {
+  kind: InitiativeAttentionKind
+  open: () => void
+}
 
 /**
  * Shared planning affordances for an `initiative`-level block, used by BOTH the board card
@@ -41,12 +58,14 @@ export function useInitiativePlanning(blockId: MaybeRefOrGetter<string>) {
    * The live interview phase, derived from the entity AND the planning run (see
    * {@link interviewGatePhase} for why the run status is load-bearing).
    */
-  const interviewPhase = computed(() =>
-    interviewGatePhase(
+  const interviewPhase = computed(() => {
+    const run = execution.getByBlock(toValue(blockId))
+    return interviewGatePhase(
       initiative.value?.interview?.status,
-      execution.getByBlock(toValue(blockId))?.status,
-    ),
-  )
+      run?.status,
+      interviewStepReached(run, INITIATIVE_INTERVIEWER_KIND),
+    )
+  })
 
   /**
    * The interviewer has PARKED the planning run for the human. NOT keyed on whether individual
@@ -62,8 +81,74 @@ export function useInitiativePlanning(blockId: MaybeRefOrGetter<string>) {
    */
   const awaitingAnswers = computed(() => interviewPhase.value === 'awaiting')
 
-  /** An interviewer pass is running — the human is waiting on the planner, not the reverse. */
-  const interviewing = computed(() => interviewPhase.value === 'working')
+  /**
+   * The planning run is mid-flight with nothing for the human to answer — either an interviewer
+   * pass is running (`working`) or the run has not reached the interview yet (`preparing`, the
+   * codebase analysis that now leads). BOTH phases, deliberately: this drives the card's and
+   * inspector's "Planning in progress" button, which is the only route into the planning window
+   * while a run owns the block. Narrowing it to `working` would drop that route for the whole of
+   * the analysis and fall through to a "Run planning" button for a run already running.
+   *
+   * The two phases are distinguished INSIDE the window, where there is room to say which is which;
+   * the affordance is the same either way.
+   */
+  const interviewing = computed(
+    () => interviewPhase.value === 'working' || interviewPhase.value === 'preparing',
+  )
+
+  /**
+   * The planner's parked plan-approval gate, or undefined. `pl_initiative` gates the planner step
+   * (`{ kind: 'initiative-planner', gate: true }`), so a finished planning pass PARKS the run on a
+   * pending `step.approval` until a human accepts the plan — the state this composable's other
+   * flags deliberately do NOT cover (the interview has converged, and the run is `blocked`, so
+   * `awaitingAnswers` and `interviewing` are both false and the card would otherwise sit on a
+   * disabled, spinning "Run planning").
+   *
+   * The interviewer's own park is excluded by the window its step routes to (see
+   * {@link selectPlanApproval}), not by the interview phase, so the two affordances can never both
+   * claim one park.
+   */
+  const planApproval = computed(() =>
+    selectPlanApproval(
+      execution.approvalsByBlock.get(toValue(blockId)) ?? [],
+      (kind) => agentKindMeta(kind).resultView,
+    ),
+  )
+
+  /** An agent-raised decision on the planning run (the analyst is an ordinary agent step). */
+  const pendingDecision = computed(() => execution.decisionsByBlock.get(toValue(blockId))?.[0])
+
+  /**
+   * The single thing a human has to act on, or null — the initiative dual of a task card's
+   * `attention`. A decision outranks an approval (a step never holds both; this is just a stable
+   * order). Opening always goes through the step-view dispatch, so the park lands in the window
+   * that can RESOLVE it (the plan gate → the tracker window's plan-review rail) rather than a
+   * generic panel that would refuse it.
+   */
+  const attention = computed<InitiativeAttention | null>(() => {
+    const id = toValue(blockId)
+    const decision = pendingDecision.value
+    if (decision) {
+      return {
+        kind: 'decision',
+        open: () => {
+          ui.select(id)
+          ui.openDecision(decision.instanceId, decision.decision.id)
+        },
+      }
+    }
+    const approval = planApproval.value
+    if (approval) {
+      return {
+        kind: 'approval',
+        open: () => {
+          ui.select(id)
+          ui.openApprovalDetail(approval.instanceId, approval.approval.id)
+        },
+      }
+    }
+    return null
+  })
 
   /**
    * Optimistic start flag: flip true the instant "Run planning" is clicked, before the stream
@@ -105,6 +190,9 @@ export function useInitiativePlanning(blockId: MaybeRefOrGetter<string>) {
     interviewPhase,
     awaitingAnswers,
     interviewing,
+    planApproval,
+    pendingDecision,
+    attention,
     starting,
     runPlanning,
     openPlanning,

package/app/composables/useTaskExpansion.ts

@@ -15,22 +15,24 @@ function sameSet(a: Set<string>, b: Set<string>) {
 }
 
 /**
- * Board-level driver deciding which task cards may expand their full pipeline list
- * once zoomed in (the deep `steps`/`subtasks` bands). Two gates, recomputed every
- * frame against live DOM rects so they follow pan / zoom / drag / resize:
+ * Board-level driver deciding which task cards expand their full pipeline list.
+ * Recomputed every frame against live DOM rects so it follows pan / zoom / drag / resize,
+ * and writes two independent grants into the `taskExpansion` store (which combines them —
+ * see the store for how they resolve):
  *
- *  - visibility: a task expands only while its card overlaps the board viewport.
- *  - overlap: walking the visible candidates nearest-header-to-screen-centre first, a
- *    task expands only if its footprint doesn't collide with one already granted, so the
- *    card you're looking at wins an overlap and the rest stay compact.
- *  - hover: the task directly under the pointer is granted first, so hovering any card
- *    expands its pipeline regardless of its position on screen. "Under the pointer" is
- *    the TOPMOST card at the cursor (document.elementFromPoint), so hovering a region
+ *  - hover: the task directly under the pointer, at ANY zoom level. "Under the pointer"
+ *    is the TOPMOST card at the cursor (document.elementFromPoint), so hovering a region
  *    already covered by another open pipeline keeps that pipeline, not the card beneath.
+ *  - zoom: at the deep `steps`/`subtasks` bands, every on-screen card, minus overlaps —
+ *    two sub-gates:
+ *      - visibility: a task expands only while its card overlaps the board viewport.
+ *      - overlap: walking the visible candidates nearest-header-to-screen-centre first, a
+ *        task expands only if its footprint doesn't collide with one already granted, so
+ *        the card you're looking at wins an overlap and the rest stay compact. The hovered
+ *        card is granted first, so it wins every overlap it's part of.
  *
- * Writes the permitted id set into the `taskExpansion` store; `TaskPipelineMini` reads it.
- * Only tasks with a running pipeline (steps to show) are candidates — a task that
- * wouldn't expand never blocks a neighbour.
+ * Only tasks with a running pipeline (steps to show) are candidates for either grant — a
+ * task that wouldn't expand never blocks a neighbour and never lifts an empty card.
  */
 export function useTaskExpansion(container: Ref<HTMLElement | null>) {
   const board = useBoardStore()
@@ -65,14 +67,27 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>) {
   // The task whose card is topmost at the pointer, or null. Using elementFromPoint (not a
   // rect test) means an open pipeline stacked above a neighbour wins the hit, so hovering
   // a region obscured by another pipeline doesn't switch to the card hidden beneath it.
+  //
+  // Blocks with no pipeline to show are filtered out here rather than left to the card:
+  // a frame, a module, or a task with no run expands to nothing, and granting it would
+  // still lift an empty card over its neighbours (see DraggableTask's z-index).
   function hoveredTaskId(): string | null {
     if (!pointer) return null
     const hit = document.elementFromPoint(pointer.x, pointer.y)
-    return hit?.closest('[data-block-id]')?.getAttribute('data-block-id') ?? null
+    const id = hit?.closest('[data-block-id]')?.getAttribute('data-block-id') ?? null
+    if (!id || !execution.getByBlock(id)?.steps.length) return null
+    return id
   }
 
   function recompute() {
-    // Task cards only expand at the deep zoom bands; clear everything otherwise.
+    // Hover expands a card at ANY zoom band, so the pointer hit is resolved BEFORE the
+    // zoom gate below — resolving it after would collapse the hovered card the moment the
+    // user zoomed back out past the `steps` band.
+    const hovered = hoveredTaskId()
+    if (store.hoveredId !== hovered) store.setHovered(hovered)
+
+    // The zoom-driven expansion (every on-screen card, overlap-resolved) is deep-band
+    // only; clear its grants otherwise. The hover grant above stands on its own.
     if (!lodAtLeast(ui.lod, 'steps')) {
       if (store.allowed.size) store.setAllowed(new Set())
       return
@@ -117,7 +132,6 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>) {
     // clears every footprint already granted, so the centre-most card wins any overlap.
     // The hovered card is granted FIRST, so hovering a card expands it regardless of its
     // distance from the centre (and a centre-most neighbour it overlaps yields to it).
-    const hovered = hoveredTaskId()
     const claimed: Rect[] = []
     const next = new Set<string>()
     const hoveredCard = hovered ? candidates.find((c) => c.id === hovered) : undefined

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

@@ -285,10 +285,20 @@ describe('nav grouping helpers', () => {
       'workspaceContext',
       'configuration',
     ])
-    // The engines are their own section, ahead of the optional integrations; `model-config`
-    // sits beside the providers it picks models from rather than under `configuration`.
+    // The model layer is its own section, ahead of the optional integrations: the engines,
+    // the per-agent model choice (beside the providers it picks from, rather than under
+    // `configuration`), and the two surfaces that evaluate a prompt+agent+model. Sandbox and
+    // Kaizen used to sit under `integrations`, which read as a claim they connect to an
+    // external system; they don't — they exercise and grade what this section configures.
     const models = groups.find((g) => g.group === 'models')
-    expect(models?.items.map((i) => i.id)).toEqual(['model-providers', 'model-config'])
+    expect(models?.items.map((i) => i.id)).toEqual([
+      'model-providers',
+      'model-config',
+      'sandbox',
+      'kaizen',
+    ])
+    const integrations = groups.find((g) => g.group === 'integrations')
+    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([
       'workspace-settings',

package/app/modular/nav-contributions.ts

@@ -30,11 +30,15 @@ export type NavSurface = 'sidebar' | 'command' | 'toolbar'
  *
  * `models` and `integrations` are deliberately SEPARATE sections even though a model
  * provider is technically also an external system we connect to. They answer different
- * questions: `models` is the ENGINE the harnesses run on (no provider ⇒ nothing runs at
- * all), `integrations` is the optional systems that feed a run context or receive its
- * output (source control, trackers, documents, chat, observability) — each of which a
- * deployment can live without. Folding the providers in among them buried the one
- * connection every deployment must make in a list of ones most never touch.
+ * questions: `models` is the MODEL LAYER — which engine the harnesses run on (no provider
+ * ⇒ nothing runs at all), which model each agent kind uses, and how well a given
+ * prompt+agent+model actually performs (`sandbox`, `kaizen`); `integrations` is the
+ * optional EXTERNAL SYSTEMS that feed a run context or receive its output (source control,
+ * trackers, documents, chat, observability) — each of which a deployment can live without.
+ * Folding the providers in among them buried the one connection every deployment must make
+ * in a list of ones most never touch; parking the two model-quality surfaces there was the
+ * same mistake from the other end — neither Sandbox nor Kaizen connects to anything, they
+ * evaluate what the `models` section configures.
  */
 export type NavSidebarGroup =
   | 'create'
@@ -268,33 +272,6 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
     testId: 'nav-integrations',
     sidebar: { group: 'integrations', order: 10 },
   },
-  {
-    id: 'sandbox',
-    labelKey: 'nav.sandbox',
-    icon: 'i-lucide-flask-conical',
-    surfaces: S('sidebar', 'command'),
-    advanced: true,
-    gate: (g) => g.canManageIntegrations,
-    action: 'sandbox',
-    testId: 'nav-sandbox',
-    sidebar: { group: 'integrations', order: 20 },
-    command: {
-      group: 'workspace',
-      order: 70,
-      labelKey: 'layout.commandBar.cmd.sandbox',
-      keywordsKey: 'layout.commandBar.keywords.sandbox',
-    },
-  },
-  {
-    id: 'kaizen',
-    labelKey: 'nav.kaizen',
-    icon: 'i-lucide-sparkles',
-    surfaces: S('sidebar'),
-    advanced: true,
-    action: 'kaizen',
-    testId: 'nav-kaizen',
-    sidebar: { group: 'integrations', order: 30 },
-  },
   {
     id: 'infrastructure',
     labelKey: 'nav.infrastructure',
@@ -370,6 +347,39 @@ export const NAV_CONTRIBUTIONS: readonly NavContribution[] = [
       keywordsKey: 'layout.commandBar.keywords.modelConfiguration',
     },
   },
+  {
+    // Trying prompt versions and models against graded fixtures — a model-layer surface,
+    // not an integration: it connects to no external system, it exercises the providers
+    // and per-agent models the two entries above configure.
+    id: 'sandbox',
+    labelKey: 'nav.sandbox',
+    icon: 'i-lucide-flask-conical',
+    surfaces: S('sidebar', 'command'),
+    advanced: true,
+    gate: (g) => g.canManageIntegrations,
+    action: 'sandbox',
+    testId: 'nav-sandbox',
+    sidebar: { group: 'models', order: 30 },
+    command: {
+      group: 'workspace',
+      order: 70,
+      labelKey: 'layout.commandBar.cmd.sandbox',
+      keywordsKey: 'layout.commandBar.keywords.sandbox',
+    },
+  },
+  {
+    // The same axis after the fact: grading history and verified prompt+agent+model combos.
+    // Sandbox asks "which combination should we use", Kaizen answers "how is the one we
+    // shipped doing" — both read the model layer, so they sit with it.
+    id: 'kaizen',
+    labelKey: 'nav.kaizen',
+    icon: 'i-lucide-sparkles',
+    surfaces: S('sidebar'),
+    advanced: true,
+    action: 'kaizen',
+    testId: 'nav-kaizen',
+    sidebar: { group: 'models', order: 40 },
+  },
   {
     id: 'service-fragment-defaults',
     labelKey: 'layout.commandBar.cmd.serviceFragmentDefaults',

package/app/modular/panels/inspector.logic.ts

@@ -76,7 +76,7 @@ const isTask = (b: Block) => b.level === 'task'
 const isFrame = (b: Block) => b.level === 'frame'
 /**
  * A block whose inspector carries a pipeline RUN. An initiative's planning pipeline is an
- * ordinary run of ordinary agent steps (interviewer → analyst → planner → committer), so it
+ * ordinary run of ordinary agent steps (analyst → interviewer → planner → committer), so it
  * gets the same execution panel a task does — step list, live phases, step-detail drill-down,
  * and the Stop / Discard-run controls that are the only way to unwedge a stalled planning run.
  * Before this it had no run surface at all, which is why a stuck plan was a dead end.

package/app/stores/taskExpansion.spec.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from 'vitest'
+import { useTaskExpansionStore } from '~/stores/taskExpansion'
+import { useUiStore } from '~/stores/ui'
+
+/**
+ * The expansion gate combines two independent grants (hover at any zoom, the deep zoom
+ * bands otherwise). Both `TaskPipelineMini` (what renders) and `DraggableTask` (what
+ * stacks on top) read `isExpanded`, so these cases pin the rule they share.
+ *
+ * Zoom is set through the ui store's raw `zoom`, the same value the board canvas writes;
+ * `lod` derives from it (< 1.8 is shallower than the `steps` band).
+ */
+function setup(zoom: number) {
+  const ui = useUiStore()
+  ui.zoom = zoom
+  const store = useTaskExpansionStore()
+  store.setDriverActive(true)
+  return store
+}
+
+describe('taskExpansion — hover expands at any zoom level', () => {
+  it('expands the hovered card while zoomed out past the steps band', () => {
+    const store = setup(0.5) // `far`
+    store.setHovered('task-a')
+    expect(store.isExpanded('task-a')).toBe(true)
+    // Hover is a grant of ONE card: its neighbours stay compact at this zoom.
+    expect(store.isExpanded('task-b')).toBe(false)
+  })
+
+  it('expands the hovered card at every band, not just the shallow ones', () => {
+    const store = setup(1) // `mid`
+    store.setHovered('task-a')
+    expect(store.isExpanded('task-a')).toBe(true)
+    useUiStore().zoom = 1.5 // `close`
+    expect(store.isExpanded('task-a')).toBe(true)
+    useUiStore().zoom = 3 // `subtasks`
+    expect(store.isExpanded('task-a')).toBe(true)
+  })
+
+  it('collapses again once the pointer leaves the card', () => {
+    const store = setup(0.5)
+    store.setHovered('task-a')
+    store.setHovered(null)
+    expect(store.isExpanded('task-a')).toBe(false)
+  })
+
+  it('expands a hovered card the zoom gate denied for overlapping a neighbour', () => {
+    const store = setup(2) // `steps`
+    store.setAllowed(new Set(['task-b']))
+    store.setHovered('task-a')
+    expect(store.isExpanded('task-a')).toBe(true)
+    expect(store.isExpanded('task-b')).toBe(true)
+  })
+})
+
+describe('taskExpansion — the zoom grant is unchanged', () => {
+  it('honours the driver grant only from the steps band up', () => {
+    const store = setup(1.5) // `close` — one band shallower than `steps`
+    store.setAllowed(new Set(['task-a']))
+    expect(store.isExpanded('task-a')).toBe(false)
+    useUiStore().zoom = 2 // `steps`
+    expect(store.isExpanded('task-a')).toBe(true)
+  })
+
+  it('denies a card the driver left out of the permitted set', () => {
+    const store = setup(2)
+    store.setAllowed(new Set(['task-b']))
+    expect(store.isExpanded('task-a')).toBe(false)
+  })
+
+  it('falls back to allowed with no driver mounted, still only at the deep bands', () => {
+    const ui = useUiStore()
+    ui.zoom = 2
+    const store = useTaskExpansionStore() // driverActive stays false
+    expect(store.isExpanded('task-a')).toBe(true)
+    ui.zoom = 1
+    expect(store.isExpanded('task-a')).toBe(false)
+  })
+
+  it('drops both grants when the driver unmounts', () => {
+    const store = setup(2)
+    store.setAllowed(new Set(['task-a']))
+    store.setHovered('task-b')
+    store.setDriverActive(false)
+    expect(store.allowed.size).toBe(0)
+    expect(store.hoveredId).toBeNull()
+  })
+})

package/app/stores/taskExpansion.ts

@@ -1,37 +1,57 @@
 import { defineStore } from 'pinia'
 import { ref } from 'vue'
+import { lodAtLeast } from '~/composables/useSemanticZoom'
+import { useUiStore } from '~/stores/ui'
 
 /**
- * Which task cards may expand their full build-pipeline list once zoomed in.
+ * Which task cards render their full build-pipeline list.
  *
- * Deep-zoom (`steps`/`subtasks`) grows a task card downward, and cards are
- * absolutely positioned in their frame, so several expanded cards stacked
- * vertically pile on top of each other. The board driver (`useTaskExpansion`)
- * recomputes a permitted set every frame — only on-screen cards, the one closest to
- * the screen centre when two would overlap, plus whichever card the pointer is hovering
- * (hover expands a card regardless of position) — and writes it here.
- * `TaskPipelineMini` reads `canExpand` to decide whether to expand or stay compact.
+ * Two independent grants, both written every frame by the board driver
+ * (`useTaskExpansion`) and combined HERE so the render (`TaskPipelineMini`) and the
+ * stacking (`DraggableTask`) can never disagree about which cards are expanded:
  *
- * `driverActive` lets the gate degrade gracefully: with no board driver mounted
- * (e.g. a card rendered in isolation) `canExpand` falls back to "allowed", so the
- * plain zoom behaviour is unchanged.
+ *  - HOVER — the card under the pointer expands at ANY zoom level. Pointing at a task
+ *    is asking what it is doing right now, and that answer used to be reachable only
+ *    by first zooming past the `steps` band.
+ *  - ZOOM — past the `steps` band, every on-screen card expands. Deep-zoom grows a card
+ *    downward and cards are absolutely positioned in their frame, so several expanded
+ *    cards stacked vertically pile on top of each other; the driver denies whichever
+ *    would collide with a card nearer the screen centre and writes the survivors here.
+ *
+ * `driverActive` lets the zoom grant degrade gracefully: with no board driver mounted
+ * (e.g. a card rendered in isolation) it falls back to "allowed", so the plain zoom
+ * behaviour is unchanged. The hover grant needs no fallback — without the driver
+ * nothing is hovered.
  */
 export const useTaskExpansionStore = defineStore('taskExpansion', () => {
+  const ui = useUiStore()
   const allowed = ref<Set<string>>(new Set())
+  const hoveredId = ref<string | null>(null)
   const driverActive = ref(false)
 
   function setAllowed(ids: Set<string>) {
     allowed.value = ids
   }
 
+  function setHovered(id: string | null) {
+    hoveredId.value = id
+  }
+
   function setDriverActive(active: boolean) {
     driverActive.value = active
-    if (!active) allowed.value = new Set()
+    if (!active) {
+      allowed.value = new Set()
+      hoveredId.value = null
+    }
   }
 
-  function canExpand(id: string) {
+  /** Whether this task card should render its pipeline: hovered at any zoom, else
+   *  granted by the deep-zoom bands. */
+  function isExpanded(id: string) {
+    if (hoveredId.value === id) return true
+    if (!lodAtLeast(ui.lod, 'steps')) return false
     return driverActive.value ? allowed.value.has(id) : true
   }
 
-  return { allowed, driverActive, setAllowed, setDriverActive, canExpand }
+  return { allowed, hoveredId, driverActive, setAllowed, setHovered, setDriverActive, isExpanded }
 })

package/app/utils/catalog.ts

@@ -439,16 +439,17 @@ export const SYSTEM_AGENT_META: Record<string, AgentArchetype> = {
     description:
       'Provisions the ephemeral environment the tester and human-test gate run against (kubernetes / custom services); a no-op for docker-compose / infraless.',
   },
-  // The Initiative Planning pipeline's two steps. Only runnable on an initiative
+  // The Initiative Planning pipeline's steps. Only runnable on an initiative
   // block (pl_initiative — enforced by the engine), so they are display-metadata
-  // system kinds, never palette archetypes.
+  // system kinds, never palette archetypes. The analyst runs FIRST, ahead of the
+  // interviewer, so the interview covers only what the code cannot answer.
   'initiative-interviewer': {
     kind: 'initiative-interviewer',
     label: 'Initiative Interviewer',
     icon: 'i-lucide-messages-square',
     color: '#818cf8',
     description:
-      'Interviews you on the goals, scope and constraints of the initiative, then synthesizes the agreed brief the analyst and planner build on.',
+      'Interviews you on the goals, scope and constraints the codebase cannot answer, then synthesizes the agreed brief the planner builds on.',
     // Opens the dedicated planning Q&A window (answer / continue / proceed) while parked.
     resultView: 'initiative-planning',
   },
@@ -458,7 +459,7 @@ export const SYSTEM_AGENT_META: Record<string, AgentArchetype> = {
     icon: 'i-lucide-microscope',
     color: '#818cf8',
     description:
-      'Explores the codebase and writes an analysis (architecture, touch points, risks) that grounds the plan. Makes no changes.',
+      'Explores the codebase first and writes an analysis (architecture, touch points, risks) that grounds both the interview and the plan. Makes no changes.',
     resultView: 'initiative-tracker',
   },
   'initiative-planner': {

package/app/utils/initiative.spec.ts

@@ -1,7 +1,12 @@
 import { INITIATIVE_ITEM_TERMINAL_STATUSES } from '@cat-factory/contracts'
 import { describe, it, expect } from 'vitest'
 import type { InitiativeItem, InitiativePhase, InitiativeQa } from '~/types/domain'
-import { isPendingQuestion, orderInterviewQuestions, pendingCheckpointPhase } from './initiative'
+import {
+  isPendingQuestion,
+  orderInterviewQuestions,
+  pendingCheckpointPhase,
+  selectPlanApproval,
+} from './initiative'
 
 // `pendingCheckpointPhase` mirrors the backend `pendingCheckpoint` (orchestration
 // `initiative.logic.ts`); these pin the same ordering/edge cases the loop pauses on, so the
@@ -150,3 +155,48 @@ describe('orderInterviewQuestions', () => {
     expect(orderInterviewQuestions([])).toEqual([])
   })
 })
+
+// The plan-review park: which of a block's pending approvals the board card / inspector offer as
+// "Review plan", and which one they must leave alone. Both gates on the planning pipeline park on
+// a `step.approval`, so the interviewer's park (owned by the planning window's "Answer planning
+// questions") is the case this selector exists to keep out — offering it here would give one park
+// two differently-worded buttons, and the tracker window it opened could not resolve it.
+
+/** A pending approval as `execution.approvalsByBlock` carries it (only the fields read here). */
+const parked = (agentKind: string, id: string) => ({ agentKind, approval: { id } })
+
+/** The catalog's result-view resolver, as the composable passes it in. */
+const resultViewOf = (kind: string): string | undefined =>
+  kind === 'initiative-interviewer'
+    ? 'initiative-planning'
+    : kind.startsWith('initiative-')
+      ? 'initiative-tracker'
+      : undefined
+
+describe('selectPlanApproval', () => {
+  it('is undefined when nothing is parked', () => {
+    expect(selectPlanApproval([], resultViewOf)).toBeUndefined()
+  })
+
+  it('picks the planner gate — the plan awaiting approval', () => {
+    const approvals = [parked('initiative-planner', 'ap_1')]
+    expect(selectPlanApproval(approvals, resultViewOf)?.approval.id).toBe('ap_1')
+  })
+
+  it('leaves the interviewer park to the planning window', () => {
+    const approvals = [parked('initiative-interviewer', 'ap_interview')]
+    expect(selectPlanApproval(approvals, resultViewOf)).toBeUndefined()
+  })
+
+  it('finds the plan gate past an interview park (a re-run interviewing again)', () => {
+    const approvals = [parked('initiative-interviewer', 'ap_interview'), parked('x', 'ap_plan')]
+    expect(selectPlanApproval(approvals, resultViewOf)?.approval.id).toBe('ap_plan')
+  })
+
+  it('offers a gated step of a custom planning pipeline, whatever window it routes to', () => {
+    // A kind with no dedicated window at all still parks a human; the affordance opens whatever
+    // `dispatchStepView` routes it to (the generic panel), which is exactly what resolves it.
+    const approvals = [parked('some-custom-kind', 'ap_custom')]
+    expect(selectPlanApproval(approvals, resultViewOf)?.approval.id).toBe('ap_custom')
+  })
+})

package/app/utils/initiative.ts

@@ -59,6 +59,50 @@ export const INITIATIVE_ITEM_STATUS_CHIPS: Record<InitiativeItemStatus, BadgeCol
   skipped: 'neutral',
 }
 
+/**
+ * The two ways an initiative's planning run parks for a human: an agent-raised `decision`, or a
+ * pending step `approval` (the plan-approval gate the `initiative-planner` step carries). Resolved
+ * per block by `useInitiativePlanning().attention`.
+ */
+export type InitiativeAttentionKind = 'decision' | 'approval'
+
+/** Park kind → i18n label key for the card/inspector button that opens the resolving window. */
+export const INITIATIVE_ATTENTION_LABEL_KEYS: Record<InitiativeAttentionKind, string> = {
+  decision: 'initiative.inspector.resolveDecision',
+  approval: 'initiative.inspector.reviewPlan',
+}
+
+/** Park kind → button icon, so the board card and the inspector can't diverge on one park. */
+export const INITIATIVE_ATTENTION_ICONS: Record<InitiativeAttentionKind, string> = {
+  decision: 'i-lucide-circle-help',
+  approval: 'i-lucide-clipboard-check',
+}
+
+/**
+ * The result view the INTERVIEW gate owns. Its park rides the same `step.approval` mechanism as
+ * every other gate, so anything offering "there is a plan to review here" has to exclude it: the
+ * interview park is already owned by the planning window, behind the differently-worded "Answer
+ * planning questions".
+ */
+export const INTERVIEW_GATE_RESULT_VIEW = 'initiative-planning'
+
+/**
+ * The block's parked approval that is a PLAN REVIEW — the planner's human gate (`pl_initiative`
+ * declares `{ kind: 'initiative-planner', gate: true }`), or any other gated step of a custom
+ * planning pipeline — as opposed to the interviewer's park.
+ *
+ * Discriminated by the step's own result view, the seam `dispatchStepView` routes on, rather than
+ * by an agent-kind list or by the interview phase: the affordance's ACTION is that dispatch, so
+ * keying the offer on the same fact guarantees the button opens a window that can resolve what it
+ * offered — and that the interview and plan affordances can never both claim one park.
+ */
+export function selectPlanApproval<A extends { agentKind: string }>(
+  approvals: readonly A[],
+  resultViewOf: (agentKind: string) => string | undefined,
+): A | undefined {
+  return approvals.find((a) => resultViewOf(a.agentKind) !== INTERVIEW_GATE_RESULT_VIEW)
+}
+
 /** Follow-up triage status → i18n label key. Exhaustive so a new status fails the build. */
 export const INITIATIVE_FOLLOWUP_STATUS_LABEL_KEYS: Record<InitiativeFollowUp['status'], string> = {
   open: 'initiative.followUpStatus.open',