@cat-factory/app 0.256.3 → 0.258.0

package/app/components/pipeline/PipelineProgress.vue

@@ -11,6 +11,8 @@ import {
   FAILED_STEP_META,
   containerPhaseLabel,
   dedicatedParkView,
+  REDIRECT_PARK_PRESENTATION,
+  stepSkipReasonKey,
 } from '~/utils/pipelineRender'
 import { prReviewPhase } from '~/utils/prReviewProgress'
 import StepMetricsBar from '~/components/observability/StepMetricsBar.vue'
@@ -90,6 +92,17 @@ function prReviewAwaiting(step: PipelineStep): boolean {
   return step.prReview?.status === 'awaiting_selection'
 }
 
+/**
+ * Whether a binary-output step is parked awaiting a human candidate choice. Asked of the shared
+ * park recognizer rather than re-derived from `step.binaryCandidates`, so this chip and the
+ * generic approval gate below (which suppresses itself for exactly the parks that recognizer
+ * names) can never disagree about who owns the park. That disagreement is what leaves a parked
+ * run showing no action at all.
+ */
+function candidatesAwaiting(step: PipelineStep): boolean {
+  return dedicatedParkView(step, props.instance) === 'binary-candidates'
+}
+
 /**
  * Whether a `pr-reviewer` step has a LIVE phase to surface (slicing / reviewing / … ). Drives
  * showing the phase badge in place of the generic subtask count header; a terminal (done/skipped)
@@ -547,6 +560,18 @@ const ITEM_ICON: Record<string, string> = {
             {{ t('pipeline.progress.clickToRead') }}
           </p>
 
+          <!-- Why a skipped step did not run. A skipped step finishes `done` with no output, so
+               without this line it is indistinguishable from one that ran and said nothing —
+               which reads as a tester that silently did its job. -->
+          <p
+            v-if="stepSkipReasonKey(s)"
+            class="mt-2 flex items-center gap-1 text-[11px] text-slate-500"
+            data-testid="step-skip-reason"
+          >
+            <UIcon name="i-lucide-skip-forward" class="h-3 w-3 shrink-0" />
+            {{ t(stepSkipReasonKey(s)!) }}
+          </p>
+
           <!-- Conditionally-run companion (today the Tester's fixer): a distinct
                sub-node marked possible / running / completed / skipped. -->
           <div
@@ -665,6 +690,31 @@ const ITEM_ICON: Record<string, string> = {
             </span>
           </button>
 
+          <!-- A generating step parked between its candidate pass and its delivering pass: a
+               purpose-built chip opening the comparison window, ahead of the generic approval
+               gate (mirrors the fork-decision and pr-review chips above). Without it the step
+               shows no action at all, because the generic gate below is suppressed for every
+               park a dedicated window owns. -->
+          <button
+            v-if="candidatesAwaiting(s)"
+            type="button"
+            data-testid="binary-candidates-open"
+            class="mt-3 flex w-full items-center gap-2 rounded-lg border border-dashed border-cyan-500/50 bg-cyan-500/10 px-2.5 py-1.5 text-start transition followup-blink hover:border-cyan-400/60"
+            @click="ui.openBinaryCandidates(instance.id, i)"
+          >
+            <span
+              class="flex h-6 w-6 shrink-0 items-center justify-center rounded-md border border-cyan-500/40 bg-cyan-500/15"
+            >
+              <UIcon
+                :name="REDIRECT_PARK_PRESENTATION['binary-candidates'].icon"
+                class="h-3 w-3 text-cyan-300"
+              />
+            </span>
+            <span class="min-w-0 flex-1 truncate text-[12px] text-slate-300">
+              {{ t('pipeline.progress.binaryCandidates.choose') }}
+            </span>
+          </button>
+
           <!-- reviewer gate folding/re-reviewing in the background: a working indicator,
                NOT a "Review & approve" gate (the human is summoned only if needed) -->
           <div

package/app/composables/api/binaryCandidates.ts

@@ -0,0 +1,36 @@
+import {
+  getBinaryCandidatesContract,
+  keepBinaryCandidatesContract,
+  type KeepBinaryCandidatesInput,
+} from '@cat-factory/contracts'
+import type { ApiContext } from './context'
+
+/**
+ * Generated-candidate comparison. A binary-output step configured to COMPARE generates a
+ * candidate from each of its selected integrations, stages them through the step's storage
+ * service, and parks. These endpoints read the staged candidates and record which of them
+ * survive (and under which alternate ids); keeping re-runs the step to deliver exactly those.
+ * The read returns null when no step carries candidate state.
+ */
+export function binaryCandidatesApi({ send, ws }: ApiContext) {
+  return {
+    // The live candidate state for a run (null when no step carries one).
+    getBinaryCandidates: (workspaceId: string, executionId: string) =>
+      send(getBinaryCandidatesContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId },
+      }),
+
+    // Keep the chosen candidates and discard the rest.
+    keepBinaryCandidates: (
+      workspaceId: string,
+      executionId: string,
+      body: KeepBinaryCandidatesInput,
+    ) =>
+      send(keepBinaryCandidatesContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId },
+        body,
+      }),
+  }
+}

package/app/composables/api/execution.ts

@@ -15,6 +15,7 @@ import {
   resolveStepExceededContract,
   restartExecutionContract,
   resumeSpendContract,
+  startAgentKindExecutionContract,
   startExecutionContract,
 } from '@cat-factory/contracts'
 import type { RequestStepChangesInput, RunMode } from '@cat-factory/contracts'
@@ -41,6 +42,24 @@ export function executionApi({ send, sendWith, ws, pwHeaders }: ApiContext) {
         body,
       }),
 
+    /**
+     * Start ONE agent kind against a block — a run with no pipeline behind it (the service
+     * frame's "Map service" action, the environment wizard's deep analysis). Gated on the
+     * personal password exactly as a pipeline start is: the kind leases a personal subscription
+     * the same way a pipeline step does.
+     */
+    startAgentKindExecution: (
+      workspaceId: string,
+      blockId: string,
+      agentKind: string,
+      password?: string,
+    ) =>
+      sendWith(pwHeaders(password), startAgentKindExecutionContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { blockId },
+        body: { agentKind },
+      }),
+
     cancelExecution: (workspaceId: string, blockId: string) =>
       send(cancelExecutionContract, { pathPrefix: ws(workspaceId), pathParams: { blockId } }),
 

package/app/composables/useApi.ts

@@ -13,6 +13,7 @@ import { boardApi } from './api/board'
 import { documentsApi } from './api/documents'
 import { executionApi } from './api/execution'
 import { followUpsApi } from './api/followUps'
+import { binaryCandidatesApi } from './api/binaryCandidates'
 import { forkDecisionApi } from './api/forkDecision'
 import { inputGateApi } from './api/inputGate'
 import { judgeApi } from './api/judge'
@@ -131,6 +132,7 @@ export function useApi() {
     ...bugHuntApi(ctx),
     ...reviewsApi(ctx),
     ...followUpsApi(ctx),
+    ...binaryCandidatesApi(ctx),
     ...forkDecisionApi(ctx),
     ...inputGateApi(ctx),
     ...judgeApi(ctx),

package/app/composables/usePipelineHealth.spec.ts

@@ -7,7 +7,7 @@ import { usePipelineHealth } from '~/composables/usePipelineHealth'
 /**
  * Guards the startup pipeline-health advisory against the failure that bit the first cut: a
  * legitimate built-in agent kind missing from the frontend catalog made `isKnownAgentKind`
- * return false, so a stock seeded pipeline (`pl_tech_debt`, which uses `analysis` + `tracker`)
+ * return false, so a stock seeded pipeline (one using `analysis` + `tracker`)
  * was reported "invalid" in every workspace with a Reseed action that could never fix it.
  *
  * The kind lists below mirror the canonical built-ins in
@@ -94,8 +94,8 @@ describe('isKnownAgentKind', () => {
 })
 
 describe('usePipelineHealth', () => {
-  it('does not flag the stock tech-debt built-in (analysis + tracker) as invalid', () => {
-    const techDebt = builtin(
+  it('does not flag an audit pipeline (analysis + tracker) as invalid', () => {
+    const audit = builtin(
       [
         'analysis',
         'tracker',
@@ -107,9 +107,9 @@ describe('usePipelineHealth', () => {
         'ci',
         'merger',
       ],
-      { id: 'pl_tech_debt', name: 'Tech debt' },
+      { id: 'pl_audit', name: 'Audit and fix' },
     )
-    const { hasIssues, invalid, outdated } = scan([techDebt])
+    const { hasIssues, invalid, outdated } = scan([audit])
     expect(hasIssues.value).toBe(false)
     expect(invalid.value).toHaveLength(0)
     expect(outdated.value).toHaveLength(0)
@@ -164,6 +164,43 @@ describe('usePipelineHealth', () => {
     expect(invalid.value[0]!.problems.some((p) => p.type === 'shape')).toBe(true)
   })
 
+  // The RUN CONDITION is the second skip axis, and the advisory has to mirror it for the same
+  // reason it mirrors the estimate gate: a rule the engine enforces at save that this scan calls
+  // healthy leaves the author to discover it as a 422.
+  it('accepts a run condition on a kind the shared gatable set allows', () => {
+    const conditional = builtin(['coder', 'reviewer', 'tester-ui'], {
+      stepOptions: [null, null, { condition: { serviceScope: 'frontend' } }],
+    })
+    expect(scan([conditional]).hasIssues.value).toBe(false)
+  })
+
+  it('flags a run condition on a kind the run structurally needs (merger)', () => {
+    const conditionalMerger = builtin(['coder', 'merger'], {
+      stepOptions: [null, { condition: { serviceScope: 'frontend' } }],
+    })
+    const { invalid } = scan([conditionalMerger])
+    expect(invalid.value).toHaveLength(1)
+    expect(invalid.value[0]!.problems.some((p) => p.type === 'shape')).toBe(true)
+  })
+
+  it('flags a step carrying BOTH a human approval gate and a run condition (shape)', () => {
+    const both = builtin(['coder', 'tester-ui'], {
+      gates: [false, true],
+      stepOptions: [null, { condition: { serviceScope: 'frontend' } }],
+    })
+    const { invalid } = scan([both])
+    expect(invalid.value).toHaveLength(1)
+    expect(invalid.value[0]!.problems.some((p) => p.type === 'shape')).toBe(true)
+  })
+
+  it('accepts a run condition BESIDE an estimate gate: the axes compose', () => {
+    const both = builtin(['task-estimator', 'coder', 'tester-ui'], {
+      gating: [null, null, { enabled: true, minComplexity: 0.4, onMissingEstimate: 'run' }],
+      stepOptions: [null, null, { condition: { serviceScope: 'frontend' } }],
+    })
+    expect(scan([both]).hasIssues.value).toBe(false)
+  })
+
   it('flags a step carrying BOTH a human approval gate and an estimate gate (shape)', () => {
     const both = builtin(['task-estimator', 'architect'], {
       gates: [false, true],

package/app/composables/usePipelineHealth.ts

@@ -80,24 +80,11 @@ function companionTargets(companion: string): string[] {
 const isEnabledAt = (p: Pipeline, i: number) => p.enabled?.[i] !== false
 
 /**
- * Client-side mirror of the backend `validatePipelineShape` (companion adjacency + estimate
- * gating, over the ENABLED subset), collecting the first problem instead of throwing. Returns a
- * human message, or null when the shape is valid. Kept in step with
- * `backend/packages/orchestration/src/modules/pipelines/pipelineShape.ts`.
- *
- * A rule here must be keyed off vocabulary SHARED with that module (`@cat-factory/contracts`)
- * wherever one exists, never re-stated locally — see the gating note below for what a drifted copy
- * costs. Adding a rule to `assertValidGating` without adding it here is the milder half of the same
- * drift: a pipeline the engine refuses at save that this advisory calls healthy.
+ * Companion adjacency: an enabled companion's nearest preceding ENABLED step must be a producer it
+ * can review. Mirrors `assertValidCompanionPlacement`.
  */
-function shapeProblem(p: Pipeline): string | null {
+function companionProblem(p: Pipeline): string | null {
   const kinds = p.agentKinds
-  // No enabled steps ⇒ nothing would run.
-  if (kinds.length === 0 || !kinds.some((_, i) => isEnabledAt(p, i))) {
-    return 'No enabled steps — the pipeline has nothing to run.'
-  }
-  // Companion adjacency: an enabled companion's nearest preceding enabled step must be a
-  // producer it can review.
   for (let i = 0; i < kinds.length; i++) {
     const kind = kinds[i]
     if (!kind || !isProducerCompanion(kind) || !isEnabledAt(p, i)) continue
@@ -113,44 +100,118 @@ function shapeProblem(p: Pipeline): string | null {
       return `Companion '${kind}' must run immediately after an enabled step it can review (${targets.join(', ')}).`
     }
   }
-  // Estimate gating: an enabled gated step must be a GATABLE kind, must not also carry a human
-  // approval gate, must set ≥1 threshold, and must have an enabled task-estimator earlier in the
-  // chain. Gatability reads the SHARED `BUILTIN_GATABLE_KINDS` rather than a local rule, because
-  // this advisory auto-opens a modal over the board: a copy of the rule that drifts behind the
-  // engine's does not merely warn wrongly, it calls a pipeline the product SHIPS invalid and leaves
-  // the board unusable. A DEPLOYMENT-registered kind can override gatability for itself through the
-  // agent-kind registry, which the SPA cannot see, so the two are not perfectly symmetric: such a
-  // kind is reported here and accepted by the engine. That is the safe direction of the asymmetry —
-  // a dismissible advisory rather than a refused save — and the only one available without shipping
-  // the registry to the browser.
+  return null
+}
+
+/**
+ * The rule both SKIP AXES share: a step that may be absent from a run must be a kind whose result
+ * later steps read as context, and must not also carry a human approval gate (a skip may leave a
+ * checkpoint un-reached, never cancel one the author asked for). Returns the problem, or null.
+ *
+ * Shared by {@link gatingProblem} and {@link conditionProblem} rather than written twice, because
+ * the reason is identical and only the axis's name differs — which is exactly how the two would
+ * drift apart. `axis` supplies the naming, mirroring `assertValidGating` /
+ * `assertValidRunConditions`.
+ *
+ * Gatability reads the SHARED `BUILTIN_GATABLE_KINDS` rather than a local rule, because this
+ * advisory auto-opens a modal over the board: a copy of the rule that drifts behind the engine's
+ * does not merely warn wrongly, it calls a pipeline the product SHIPS invalid and leaves the board
+ * unusable. A DEPLOYMENT-registered kind can override gatability for itself through the agent-kind
+ * registry, which the SPA cannot see, so the two are not perfectly symmetric: such a kind is
+ * reported here and accepted by the engine. That is the safe direction of the asymmetry — a
+ * dismissible advisory rather than a refused save — and the only one available without shipping the
+ * registry to the browser.
+ */
+function skipAxisProblem(
+  p: Pipeline,
+  i: number,
+  axis: {
+    notGatable: (kind: string | undefined) => string
+    withHumanGate: (kind: string) => string
+  },
+): string | null {
+  const kind = p.agentKinds[i]
+  if (!kind || !isBuiltinGatableKind(kind)) return axis.notGatable(kind)
+  if (p.gates?.[i] === true) return axis.withHumanGate(kind)
+  return null
+}
+
+/**
+ * Estimate gating: the shared skip-axis rules, plus the two specific to an estimate — at least one
+ * axis threshold (with none the step would ALWAYS skip) and an enabled task-estimator earlier in
+ * the chain (or the gate has nothing to consult). Mirrors `assertValidGating`.
+ */
+function gatingProblem(p: Pipeline): string | null {
   const gating = p.gating
-  if (gating) {
-    for (let i = 0; i < kinds.length; i++) {
-      const g = gating[i] as StepGating | null | undefined
-      if (!g?.enabled || !isEnabledAt(p, i)) continue
-      const kind = kinds[i]
-      if (!kind || !isBuiltinGatableKind(kind)) {
-        return `Step '${kind}' may not be estimate-gated — its output is required by the rest of the run. Only a step whose result later steps read as context (a design, a review, an extra verification pass) may be skipped on the estimate.`
-      }
-      // A human approval gate and an estimate gate on the same step contradict: the estimate may
-      // ADD a human checkpoint but never CANCEL a pause the pipeline author asked for.
-      if (p.gates?.[i] === true) {
-        return `Step '${kind}' carries a human approval gate, so it cannot also be estimate-gated — the estimate may add a human checkpoint but never remove one.`
-      }
-      if (g.minComplexity === undefined && g.minRisk === undefined && g.minImpact === undefined) {
-        return `Step '${kind}' is estimate-gated but sets no threshold (complexity / risk / impact).`
-      }
-      const hasEstimator = kinds
-        .slice(0, i)
-        .some((k, j) => k === TASK_ESTIMATOR_KIND && isEnabledAt(p, j))
-      if (!hasEstimator) {
-        return `Step '${kind}' is gated on the estimate but no enabled '${TASK_ESTIMATOR_KIND}' runs before it.`
-      }
+  if (!gating) return null
+  const kinds = p.agentKinds
+  for (let i = 0; i < kinds.length; i++) {
+    const g = gating[i] as StepGating | null | undefined
+    if (!g?.enabled || !isEnabledAt(p, i)) continue
+    const shared = skipAxisProblem(p, i, {
+      notGatable: (kind) =>
+        `Step '${kind}' may not be estimate-gated — its output is required by the rest of the run. Only a step whose result later steps read as context (a design, a review, an extra verification pass) may be skipped on the estimate.`,
+      withHumanGate: (kind) =>
+        `Step '${kind}' carries a human approval gate, so it cannot also be estimate-gated — the estimate may add a human checkpoint but never remove one.`,
+    })
+    if (shared) return shared
+    const kind = kinds[i]
+    if (g.minComplexity === undefined && g.minRisk === undefined && g.minImpact === undefined) {
+      return `Step '${kind}' is estimate-gated but sets no threshold (complexity / risk / impact).`
+    }
+    const hasEstimator = kinds
+      .slice(0, i)
+      .some((k, j) => k === TASK_ESTIMATOR_KIND && isEnabledAt(p, j))
+    if (!hasEstimator) {
+      return `Step '${kind}' is gated on the estimate but no enabled '${TASK_ESTIMATOR_KIND}' runs before it.`
     }
   }
   return null
 }
 
+/**
+ * Run conditions: the SECOND skip axis, held to the shared rules and nothing more. A skip is a skip
+ * whichever axis caused it, so a condition on a non-gatable kind drops something the run needs.
+ * Mirrors `assertValidRunConditions`. A condition BESIDE an estimate gate is deliberately fine.
+ */
+function conditionProblem(p: Pipeline): string | null {
+  const stepOptions = p.stepOptions
+  if (!stepOptions) return null
+  for (let i = 0; i < p.agentKinds.length; i++) {
+    if (!stepOptions[i]?.condition || !isEnabledAt(p, i)) continue
+    const problem = skipAxisProblem(p, i, {
+      notGatable: (kind) =>
+        `Step '${kind}' may not carry a run condition — its output is required by the rest of the run, so a run outside the condition's scope would silently finish without it.`,
+      withHumanGate: (kind) =>
+        `Step '${kind}' carries a human approval gate, so it cannot also carry a run condition — a condition may leave a checkpoint un-reached but never remove one.`,
+    })
+    if (problem) return problem
+  }
+  return null
+}
+
+/**
+ * Client-side mirror of the backend `validatePipelineShape` (companion adjacency + both skip axes,
+ * over the ENABLED subset), collecting the first problem instead of throwing. Returns a human
+ * message, or null when the shape is valid. Kept in step with
+ * `backend/packages/orchestration/src/modules/pipelines/pipelineShape.ts`.
+ *
+ * One delegate per rule, in the order the backend checks them, so adding the next rule is a
+ * function beside these rather than another branch inside one that already carries three.
+ *
+ * A rule here must be keyed off vocabulary SHARED with that module (`@cat-factory/contracts`)
+ * wherever one exists, never re-stated locally — see {@link skipAxisProblem} for what a drifted
+ * copy costs. Adding a rule to `validatePipelineShape` without adding it here is the milder half of
+ * the same drift: a pipeline the engine refuses at save that this advisory calls healthy.
+ */
+function shapeProblem(p: Pipeline): string | null {
+  // No enabled steps ⇒ nothing would run.
+  if (p.agentKinds.length === 0 || !p.agentKinds.some((_, i) => isEnabledAt(p, i))) {
+    return 'No enabled steps — the pipeline has nothing to run.'
+  }
+  return companionProblem(p) ?? gatingProblem(p) ?? conditionProblem(p)
+}
+
 /**
  * Detect pipelines in an unhealthy state for the startup advisory: those referencing an unknown
  * agent kind or with an invalid shape (offer to delete a custom one / reseed a built-in), built-ins

package/app/modular/agent-kinds.ts

@@ -35,6 +35,11 @@ export function customKindToArchetype(kind: CustomAgentKind): AgentArchetype {
     // projection would fork the rule the moment the default changes.
     ...(p.tier ? { tier: p.tier } : {}),
     ...(p.resultView ? { resultView: p.resultView } : {}),
+    // The kind is the platform's to dispatch, not a block anyone places. Carried onto the
+    // archetype rather than dropped at the projection because the catalog is also the READ MODEL
+    // every run view resolves a step's label and icon through: filtering it out here would leave
+    // the wizard's own analyst run rendering as an unknown kind.
+    ...(p.internal ? { internal: true } : {}),
     // Not part of `presentation` on the wire — it is a fact about how the kind RUNS, projected
     // beside `container` — so it is lifted from the entry itself. Carried onto the archetype
     // because the pipeline builder resolves a step's meta through `agentKindMeta`, not through

package/app/modular/result-views.ts

@@ -13,6 +13,7 @@ import ConsensusSessionWindow from '~/components/consensus/ConsensusSessionWindo
 import GenericStructuredResultView from '~/components/panels/GenericStructuredResultView.vue'
 import ServiceSpecWindow from '~/components/spec/ServiceSpecWindow.vue'
 import FollowUpWindow from '~/components/followUp/FollowUpWindow.vue'
+import BinaryCandidatesWindow from '~/components/binaryCandidates/BinaryCandidatesWindow.vue'
 import ForkDecisionWindow from '~/components/forkDecision/ForkDecisionWindow.vue'
 import PrReviewWindow from '~/components/prReview/PrReviewWindow.vue'
 import MergerResultView from '~/components/panels/MergerResultView.vue'
@@ -77,6 +78,9 @@ const BUILT_IN_RESULT_VIEWS: Record<ResultViewId, Component> = {
   'follow-ups': FollowUpWindow,
   // The implementation-fork decision: the proposer's approaches + the human's pick / custom.
   'fork-decision': ForkDecisionWindow,
+  // The generated-candidate comparison: the candidates a generating step staged, side by side,
+  // and the human's keep/discard decision (with the alternate ids they assigned).
+  'binary-candidates': BinaryCandidatesWindow,
   // The PR deep-review: the reviewer's sliced, prioritized findings + the human's multi-select.
   'pr-review': PrReviewWindow,
   // The merger's verdict: PR complexity/risk/impact scores + the engine's decision (and why).

package/app/stores/binaryCandidates.ts

@@ -0,0 +1,89 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import type { KeepBinaryCandidatesInput } from '@cat-factory/contracts'
+import type { BinaryCandidateStepState } from '~/types/execution'
+import { useApi } from '~/composables/useApi'
+import { useWorkspaceStore } from '~/stores/workspace'
+import { useExecutionStore } from '~/stores/execution'
+
+/**
+ * The generated-candidate action surface. The live state lives on the run's step
+ * (`step.binaryCandidates`) and the execution stream keeps it fresh, so the window reads it
+ * straight off the execution store; this store only wraps the `keep` action (plus a warm-up
+ * `load`), tracks the in-flight state so the window can disable its controls, and echoes the
+ * returned state back so the UI settles without waiting for the stream. Shaped exactly like the
+ * fork-decision store, which is the same park one subject over.
+ */
+export const useBinaryCandidatesStore = defineStore('binaryCandidates', () => {
+  const api = useApi()
+  const workspace = useWorkspaceStore()
+  const execution = useExecutionStore()
+
+  /** True while a keep call is in flight (drives the button spinner / disabled state). */
+  const keeping = ref(false)
+  /** The last error message from an action, surfaced inline; cleared on the next action. */
+  const error = ref<string | null>(null)
+
+  /**
+   * Apply an authoritative candidate state to the run's step.
+   *
+   * A pipeline may carry more than one generating step, so target the step this decision is
+   * ABOUT rather than the first that happens to hold candidate state: prefer the one still
+   * awaiting a choice, then the current step, and only then any step carrying state. Without
+   * that order a run whose earlier generator already settled would have its finished record
+   * overwritten by the live one.
+   *
+   * Only ever called through {@link ExecutionStore.echoAfter}, which drops the echo when the
+   * event stream already delivered a newer revision.
+   */
+  function assign(
+    instance: ReturnType<typeof execution.getInstance> & object,
+    state: BinaryCandidateStepState,
+  ): void {
+    const current = instance.steps[instance.currentStep]
+    const step =
+      instance.steps.find((s) => s.binaryCandidates?.status === 'awaiting_choice') ??
+      (current?.binaryCandidates ? current : undefined) ??
+      instance.steps.find((s) => s.binaryCandidates)
+    if (step) step.binaryCandidates = state
+  }
+
+  /** Warm the live state from the GET (the stream also keeps it fresh). Best-effort. */
+  async function load(executionId: string): Promise<void> {
+    error.value = null
+    try {
+      await execution.echoAfter(
+        executionId,
+        () => api.getBinaryCandidates(workspace.requireId(), executionId),
+        (state, instance) => {
+          if (state) assign(instance, state as BinaryCandidateStepState)
+        },
+      )
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Failed to load'
+    }
+  }
+
+  /**
+   * Keep the chosen candidates (each with the id it is to be stored under) and discard the rest.
+   * The step then re-runs to deliver exactly what survived.
+   */
+  async function keep(executionId: string, input: KeepBinaryCandidatesInput): Promise<void> {
+    error.value = null
+    keeping.value = true
+    try {
+      await execution.echoAfter(
+        executionId,
+        () => api.keepBinaryCandidates(workspace.requireId(), executionId, input),
+        (state, instance) => assign(instance, state as BinaryCandidateStepState),
+      )
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Failed to keep candidates'
+      throw e
+    } finally {
+      keeping.value = false
+    }
+  }
+
+  return { keeping, error, load, keep }
+})

package/app/stores/environmentWizard/context.ts

@@ -9,7 +9,6 @@ import type { useBoardStore } from '~/stores/board'
 import type { useExecutionStore } from '~/stores/execution'
 import type { useGitHubStore } from '~/stores/github'
 import type { useInfraConfigStore } from '~/stores/infraConfig'
-import type { usePipelinesStore } from '~/stores/pipelines'
 import type { usePreflightsStore } from '~/stores/preflights'
 
 /**
@@ -47,7 +46,6 @@ export interface WizardContext {
   trialStarted: Ref<boolean>
   // ---- derived the actions read ----
   repoContext: ComputedRef<{ githubId: number; directory?: string | null } | undefined>
-  analysisPipeline: ComputedRef<ReturnType<ReturnType<typeof usePipelinesStore>['getPipeline']>>
   merged: ComputedRef<MergedRecipeDraft | null>
 }
 

package/app/stores/environmentWizard/flow.ts

@@ -1,3 +1,4 @@
+import { ENVIRONMENT_ANALYST_AGENT_KIND } from '@cat-factory/contracts'
 import type { WizardContext } from './context'
 import { cloneRecipe } from './context'
 
@@ -34,7 +35,6 @@ export function createFlowActions(ctx: WizardContext) {
     trialError,
     trialStarted,
     repoContext,
-    analysisPipeline,
     merged,
   } = ctx
 
@@ -117,18 +117,23 @@ export function createFlowActions(ctx: WizardContext) {
     if (id) void detect()
   }
 
-  /** Fire the analyst-only pipeline against the frame (mirrors how bootstrap runs pl_blueprint). */
+  /**
+   * Run the analyst agent against the frame — a SINGLE-KIND run, the same seam the board's
+   * "Map service" action uses. `startAgentKind` reports a refusal by returning false (it has
+   * already surfaced the reason as a toast), so both halves of "it did not start" land on the
+   * wizard's own error state rather than only the thrown one.
+   */
   async function startAnalysis() {
     const id = frameId.value
-    const pipeline = analysisPipeline.value
-    if (!id || !pipeline) {
+    if (!id) {
       analysisError.value = true
       return
     }
     analysisError.value = false
     try {
-      await execution.start(id, pipeline)
-      analysisRequested.value = true
+      const started = await execution.startAgentKind(id, ENVIRONMENT_ANALYST_AGENT_KIND)
+      if (started) analysisRequested.value = true
+      else analysisError.value = true
     } catch {
       analysisError.value = true
     }