@cat-factory/app 0.202.0 → 0.204.0

package/app/stores/pipelines/draftBinaryOutput.spec.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest'
+import { usePipelinesStore } from '~/stores/pipelines'
+
+/**
+ * The pipeline-builder draft's binary-output selection (`stepOptions.binaryOutput`), the store
+ * half of the picker (docs/initiatives/binary-output-foundational-storage.md). Same contract as
+ * the skill and variant helpers beside it — merge into the options bag, normalize an emptied bag
+ * back to null — plus the one rule specific to this field: an empty `contextServiceIds` is
+ * DROPPED rather than persisted, because `[]` and absence are different claims to the agent.
+ */
+describe('pipelines store — per-step binary-output selection', () => {
+  it('sets, reads and clears the selection', () => {
+    const pipelines = usePipelinesStore()
+    pipelines.addToDraft('coder')
+    expect(pipelines.draftBinaryOutput(0)).toBeUndefined()
+
+    pipelines.setDraftBinaryOutput(0, { storageServiceId: 'file-storage' })
+    expect(pipelines.draftBinaryOutput(0)).toEqual({ storageServiceId: 'file-storage' })
+    expect(pipelines.draftStepOptions[0]).toEqual({
+      binaryOutput: { storageServiceId: 'file-storage' },
+    })
+
+    // Clearing drops the field and, with the bag now empty, normalizes the entry back to null —
+    // so a step that never used it persists exactly the shape it always did.
+    pipelines.setDraftBinaryOutput(0, undefined)
+    expect(pipelines.draftBinaryOutput(0)).toBeUndefined()
+    expect(pipelines.draftStepOptions[0]).toBeNull()
+  })
+
+  // `[]` reads as "context was considered and rejected", which the brief would then repeat to
+  // the agent; absence reads as "no scope service was selected". Only one of those is true.
+  it('drops an emptied context list rather than persisting an empty array', () => {
+    const pipelines = usePipelinesStore()
+    pipelines.addToDraft('coder')
+
+    pipelines.setDraftBinaryOutput(0, {
+      storageServiceId: 'file-storage',
+      contextServiceIds: ['asset-management'],
+    })
+    expect(pipelines.draftBinaryOutput(0)?.contextServiceIds).toEqual(['asset-management'])
+
+    pipelines.setDraftBinaryOutput(0, { storageServiceId: 'file-storage', contextServiceIds: [] })
+    expect(pipelines.draftBinaryOutput(0)).toEqual({ storageServiceId: 'file-storage' })
+  })
+
+  // A blank storage id is not a selection: the backend refuses the step either way, so the
+  // draft must not carry a half-filled shape that saves and then fails.
+  it('treats a blank storage id as no selection at all', () => {
+    const pipelines = usePipelinesStore()
+    pipelines.addToDraft('coder')
+    pipelines.setDraftBinaryOutput(0, { storageServiceId: '', contextServiceIds: ['inventory'] })
+    expect(pipelines.draftBinaryOutput(0)).toBeUndefined()
+    expect(pipelines.draftStepOptions[0]).toBeNull()
+  })
+
+  it('merges into the options bag rather than clobbering other per-step options', () => {
+    const pipelines = usePipelinesStore()
+    pipelines.addToDraft('coder')
+    pipelines.draftStepOptions[0] = { agentVariantId: 'acme:fast' }
+
+    pipelines.setDraftBinaryOutput(0, { storageServiceId: 'file-storage' })
+    expect(pipelines.draftStepOptions[0]).toEqual({
+      agentVariantId: 'acme:fast',
+      binaryOutput: { storageServiceId: 'file-storage' },
+    })
+
+    pipelines.setDraftBinaryOutput(0, undefined)
+    expect(pipelines.draftStepOptions[0]).toEqual({ agentVariantId: 'acme:fast' })
+  })
+})

package/app/stores/pipelines/draftStepConfig.ts

@@ -1,4 +1,4 @@
-import type { StepOptions } from '@cat-factory/contracts'
+import type { BinaryOutputConfig, StepOptions } from '@cat-factory/contracts'
 import type { ConsensusStepConfig } from '~/types/consensus'
 import { defaultConsensusConfig, type PipelinesContext } from './context'
 
@@ -6,7 +6,8 @@ import { defaultConsensusConfig, type PipelinesContext } from './context'
  * The pipeline-builder draft's PER-STEP CONFIG toggles: consensus (inline panel and the workspace
  * consensus-GROUP tier set), the human approval gate, the estimate gate on a companion step, the
  * follow-up and test-QC companions, the per-step enable flag, and the `StepOptions` bag
- * (requirements auto-recommendation, the picked skill, the picked agent-kind variant).
+ * (requirements auto-recommendation, the picked skill, the picked agent-kind variant, the
+ * per-step output-token ceiling, the binary-output storage/context selection).
  *
  * Split out of `./draftActions`, which owns the draft's STRUCTURE (insert / remove / reorder /
  * units). Every function here reads and writes one of the parallel per-step arrays at an index and
@@ -160,6 +161,39 @@ export function createPipelineStepConfigActions(ctx: PipelinesContext) {
     draftStepOptions.value[index] = Object.keys(next).length ? next : null
   }
 
+  /**
+   * The binary-output SELECTION on the draft step at `index` (its `stepOptions.binaryOutput`) —
+   * the foundational storage service a generator kind's artifacts are stored through, plus any
+   * services consulted for the generation's scope. Undefined on every step of every stock
+   * pipeline; required on a step whose kind carries the `binary-output` trait.
+   */
+  function draftBinaryOutput(index: number): BinaryOutputConfig | undefined {
+    return draftStepOptions.value[index]?.binaryOutput
+  }
+
+  /**
+   * Set (or clear) the binary-output selection on the draft step at `index`. Merges into the
+   * step's `StepOptions` bag rather than clobbering it; clearing drops the field and, if the
+   * bag empties, the whole entry — exactly like the other options here, so a step that never
+   * used it persists the shape it always did.
+   *
+   * An EMPTY `contextServiceIds` is dropped rather than stored, for the reason the consensus
+   * tier set drops its own empty array: the field's absence means "no scope service was
+   * selected", while `[]` reads as "context was considered and rejected" — a different claim,
+   * and one the brief renderer would repeat to the agent.
+   */
+  function setDraftBinaryOutput(index: number, config: BinaryOutputConfig | undefined) {
+    const next: StepOptions = { ...draftStepOptions.value[index] }
+    if (config?.storageServiceId) {
+      const { storageServiceId, contextServiceIds } = config
+      next.binaryOutput = {
+        storageServiceId,
+        ...(contextServiceIds?.length ? { contextServiceIds } : {}),
+      }
+    } else delete next.binaryOutput
+    draftStepOptions.value[index] = Object.keys(next).length ? next : null
+  }
+
   /**
    * The output-token ceiling pinned on the draft step at `index`, or undefined when the step
    * inherits (the workspace's per-kind setting, else the deployment default).
@@ -197,6 +231,8 @@ export function createPipelineStepConfigActions(ctx: PipelinesContext) {
     setDraftSkillId,
     draftAgentVariantId,
     setDraftAgentVariantId,
+    draftBinaryOutput,
+    setDraftBinaryOutput,
     draftMaxOutputTokens,
     setDraftMaxOutputTokens,
   }

package/app/stores/tutorial.spec.ts

@@ -64,6 +64,81 @@ describe('useTutorialStore launch prompt', () => {
   })
 })
 
+describe('useTutorialStore catalogue', () => {
+  it('opens over the launch prompt without answering it', () => {
+    // Browsing the full list is not "no thanks" — it is the opposite — so the offer must
+    // return next launch if the user browses and starts nothing. And the two are modals:
+    // leaving the prompt open would stack them.
+    const tutorial = useTutorialStore()
+    tutorial.maybeOfferOnLaunch()
+    tutorial.openCatalogue()
+    expect(tutorial.catalogueOpen).toBe(true)
+    expect(tutorial.promptOpen).toBe(false)
+    expect(tutorial.decision).toBeNull()
+  })
+
+  it('closes when a tour starts or resumes from it', () => {
+    const tutorial = useTutorialStore()
+    tutorial.openCatalogue()
+    tutorial.startTour('board-basics')
+    expect(tutorial.catalogueOpen).toBe(false)
+
+    tutorial.setStepIndex(2)
+    tutorial.stopTour()
+    tutorial.openCatalogue()
+    tutorial.resumeTour('board-basics')
+    expect(tutorial.catalogueOpen).toBe(false)
+  })
+
+  it('reports its own window as open, so the coach marks stand down', () => {
+    // The overlay renders at z-[70] to sit ABOVE the app's modals, since a step legitimately
+    // points into one. The catalogue is openable mid-tour (that is what the `continue` action
+    // is for), and there the same z-index would float a ring and a tooltip over the window the
+    // user just opened. The tour itself is untouched — only the marks go.
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    expect(tutorial.ownWindowOpen).toBe(false)
+
+    tutorial.openCatalogue()
+    expect(tutorial.ownWindowOpen).toBe(true)
+    expect(tutorial.activeTourId).toBe('board-basics')
+
+    tutorial.closeCatalogue()
+    expect(tutorial.ownWindowOpen).toBe(false)
+
+    tutorial.openPrompt()
+    expect(tutorial.ownWindowOpen).toBe(true)
+  })
+
+  it('resets every record of progress, including the answered offer', () => {
+    // What someone handing the app to a colleague is asking for: the first-launch experience
+    // back. Clearing only the completion list would leave the offer answered, so the prompt
+    // they are trying to demo would never appear.
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.completeTour()
+    tutorial.startTour('run-task')
+    tutorial.setStepIndex(2)
+    tutorial.stopTour()
+
+    tutorial.resetProgress()
+    expect(tutorial.completedTourIds).toEqual([])
+    expect(tutorial.interruptedAt('run-task')).toBeNull()
+    expect(tutorial.decision).toBeNull()
+  })
+
+  it('leaves a running tour alone when progress is reset', () => {
+    // A click about history must not end the walkthrough the user is in the middle of —
+    // which would also leave it unrecorded, since nothing marks a stopped tour complete.
+    const tutorial = useTutorialStore()
+    tutorial.startTour('board-basics')
+    tutorial.setStepIndex(2)
+    tutorial.resetProgress()
+    expect(tutorial.activeTourId).toBe('board-basics')
+    expect(tutorial.stepIndex).toBe(2)
+  })
+})
+
 describe('useTutorialStore tours', () => {
   it('starting a tour records acceptance, closes the prompt, and resets the cursor', () => {
     const tutorial = useTutorialStore()

package/app/stores/tutorial.ts

@@ -16,7 +16,7 @@ export type TutorialDecision = 'accepted' | 'declined'
  *    is a real state distinct from `declined` — only an explicit answer stops the launch
  *    prompt from returning, while closing it without answering merely defers it to the
  *    next launch.
- *  - SESSION-ONLY (`promptOpen`, `activeTourId`, `stepIndex`) — a tour is anchored to live
+ *  - SESSION-ONLY (`promptOpen`, `catalogueOpen`, `activeTourId`, `stepIndex`) — a tour is anchored to live
  *    DOM, so replaying progress across a reload would point step N at a board that hasn't
  *    reached that state; a reloaded tour restarts from its beginning instead.
  *
@@ -36,6 +36,13 @@ export const useTutorialStore = defineStore(
     const promptOpen = ref(false)
     /** Once-per-session guard for the launch auto-open; later opens are user-driven. */
     const promptAutoOpened = ref(false)
+    /**
+     * The tutorial catalogue (every tour this deployment ships, startable at any time) is
+     * open. Always user-driven — nothing auto-opens it — which is why it carries none of the
+     * prompt's decision machinery: browsing the catalogue answers no question, so it neither
+     * writes a decision nor consumes the launch offer.
+     */
+    const catalogueOpen = ref(false)
     const activeTourId = ref<string | null>(null)
     const stepIndex = ref(0)
     /**
@@ -54,6 +61,22 @@ export const useTutorialStore = defineStore(
     /** A tour is currently running (the overlay mounts off this). */
     const touring = computed(() => activeTourId.value !== null)
 
+    /**
+     * A window this feature owns — the launch prompt or the catalogue — is on screen.
+     *
+     * The coach-mark overlay STANDS DOWN while it is (see `TutorialOverlay.vue`). The marks
+     * render at `z-[70]`, deliberately above the app's own modals, because a tour step
+     * legitimately points INTO one; no step points into the tutorial's own windows, so there
+     * the same rule floats a highlight ring and a tooltip over the modal the user just opened.
+     * The catalogue reaches this state by design — it is openable mid-tour, which is what the
+     * `continue` launch action exists for.
+     *
+     * A derived FACT rather than a `coachMarksHidden` flag, because the reason is the window,
+     * not the overlay: a third tutorial-owned window inherits the behaviour by being named
+     * here, and nothing has to remember to set a flag.
+     */
+    const ownWindowOpen = computed(() => promptOpen.value || catalogueOpen.value)
+
     /**
      * Auto-open the launch prompt, at most once per session and only while the user has
      * never answered it. Callers gate on the rest of the launch context (board ready, no
@@ -91,6 +114,21 @@ export const useTutorialStore = defineStore(
       promptOpen.value = false
     }
 
+    /**
+     * Open the catalogue. Closes the launch prompt WITHOUT answering it: browsing the full
+     * list is not "no thanks" (it is the opposite), and the two are modals that would
+     * otherwise stack — so the offer returns next launch if the user browses and starts
+     * nothing.
+     */
+    function openCatalogue() {
+      promptOpen.value = false
+      catalogueOpen.value = true
+    }
+
+    function closeCatalogue() {
+      catalogueOpen.value = false
+    }
+
     /** The explicit "no thanks": saved, so the launch prompt never auto-opens again. */
     function decline() {
       decision.value = 'declined'
@@ -105,6 +143,7 @@ export const useTutorialStore = defineStore(
     function startTour(tourId: string) {
       decision.value = 'accepted'
       promptOpen.value = false
+      catalogueOpen.value = false
       activeTourId.value = tourId
       stepIndex.value = 0
       // Starting from the top is an explicit choice to discard THIS tour's old position;
@@ -134,6 +173,7 @@ export const useTutorialStore = defineStore(
       }
       decision.value = 'accepted'
       promptOpen.value = false
+      catalogueOpen.value = false
       activeTourId.value = tourId
       stepIndex.value = at.stepIndex
       interrupted.value = null
@@ -189,19 +229,44 @@ export const useTutorialStore = defineStore(
       return completedTourIds.value.includes(tourId)
     }
 
+    /**
+     * Forget everything this browser remembers about the tutorial: which tours were finished,
+     * where one was broken off, and the answer to the launch offer.
+     *
+     * The decision goes with it deliberately. "Reset" is asked for by someone handing the app
+     * to a colleague, demoing it, or re-walking the product after it changed — and every one
+     * of those wants the first-launch experience back, which a cleared completion list alone
+     * does not restore. It does NOT re-open the prompt in this session: `promptAutoOpened` is
+     * session state and stays spent, so the offer returns at the next launch rather than
+     * appearing on top of the catalogue the user is still reading.
+     *
+     * A running tour is left alone: this clears a record, it does not interrupt a walkthrough
+     * the user is in the middle of (which would end it, unrecorded, on a click about history).
+     */
+    function resetProgress() {
+      completedTourIds.value = []
+      interrupted.value = null
+      decision.value = null
+    }
+
     return {
       decision,
       completedTourIds,
       promptOpen,
       promptAutoOpened,
+      catalogueOpen,
       activeTourId,
       stepIndex,
       interrupted,
       touring,
+      ownWindowOpen,
       maybeOfferOnLaunch,
       openPrompt,
       closePrompt,
       deferPrompt,
+      openCatalogue,
+      closeCatalogue,
+      resetProgress,
       decline,
       startTour,
       resumeTour,

package/app/types/domain.ts

@@ -131,6 +131,15 @@ export interface AgentArchetype {
    * hardcoding a kind. Absent → the generic `AgentStepDetail` panel.
    */
   resultView?: string
+  /**
+   * The kind carries the `binary-output` trait: its deliverable is binary artifacts stored
+   * through a foundational service, so a step of this kind REQUIRES a `stepOptions.binaryOutput`
+   * selection and is refused at pipeline save and at run start without one. Projected onto the
+   * snapshot as `CustomAgentKind.binaryOutput` — the only trait with a UI consequence, and the
+   * only way the builder can know which steps must offer the storage picker. Absent ⇒ false,
+   * which is every built-in kind.
+   */
+  binaryOutput?: boolean
 }
 
 /**

package/app/types/execution.ts

@@ -77,6 +77,11 @@ export type {
   RalphStepState,
   RalphAttempt,
   RalphVerdict,
+  // The binary-output trio: the step's SELECTION (`stepOptions.binaryOutput`), the report the
+  // engine parsed off the agent's declaration (`step.binaryOutputs`), and one declared artifact.
+  BinaryOutputArtifact,
+  BinaryOutputConfig,
+  BinaryOutputReport,
   TesterStepState,
   HumanTestEnvironment,
   RunEnvironment,

package/app/utils/binaryOutput.spec.ts

@@ -0,0 +1,307 @@
+import { describe, expect, it } from 'vitest'
+import type { BinaryOutputReport, PipelineStep } from '~/types/execution'
+import {
+  BINARY_OUTPUT_STATE_KEYS,
+  binaryOutputHasWarnings,
+  binaryOutputPickIssues,
+  binaryOutputView,
+} from './binaryOutput'
+
+function step(patch: Partial<PipelineStep>): PipelineStep {
+  return { agentKind: 'image-maker', state: 'done', ...patch } as PipelineStep
+}
+
+function report(patch: Partial<BinaryOutputReport> = {}): BinaryOutputReport {
+  return { stored: [], unknownServices: [], invalidEntries: 0, omitted: 0, ...patch }
+}
+
+const artifact = (service: string, location: string) => ({ service, location })
+
+describe('binaryOutputView', () => {
+  // The regression this whole surface exists to prevent: five of the six outcomes are NOT
+  // "an empty list", so each must resolve to its own state (and, through the shared key map,
+  // its own copy). Collapsing any pair reports a run that stored nothing and a run whose
+  // declaration was unreadable as the same thing.
+  it('keeps the six outcomes apart', () => {
+    const cases: [PipelineStep, string][] = [
+      [
+        step({ state: 'pending', stepOptions: { binaryOutput: { storageServiceId: 'files' } } }),
+        'not-started',
+      ],
+      [step({ stepOptions: { binaryOutput: { storageServiceId: 'files' } } }), 'configured'],
+      [step({ binaryOutputs: report({ undeclared: true }) }), 'undeclared'],
+      [step({ binaryOutputs: report({ parseFailed: true }) }), 'parse-failed'],
+      [step({ binaryOutputs: report() }), 'declared-none'],
+      [step({ binaryOutputs: report({ stored: [artifact('files', 'a/b.png')] }) }), 'stored'],
+    ]
+    for (const [input, expected] of cases) expect(binaryOutputView(input)?.state).toBe(expected)
+    // Every state has its own copy, so no two rows can read identically.
+    const summaries = Object.values(BINARY_OUTPUT_STATE_KEYS).map((k) => k.summary)
+    expect(new Set(summaries).size).toBe(summaries.length)
+  })
+
+  // Absence is the one thing that must NOT render: a step with neither a report nor a
+  // selection had no binary-output story at all, which is every step of every stock pipeline.
+  it('renders nothing for a step that was never briefed', () => {
+    expect(binaryOutputView(step({}))).toBeNull()
+    expect(binaryOutputView(null)).toBeNull()
+  })
+
+  // A queued step has not had the chance to record anything, which `configured` ("running, or it
+  // died") states as the opposite of what is true. It still renders — unlike a SKIPPED step it
+  // has a story ahead of it, and where the artifacts will land is worth saying in advance.
+  it('separates a step that has not started from one that started and recorded nothing', () => {
+    const config = { binaryOutput: { storageServiceId: 'files' } }
+    const queued = binaryOutputView(step({ state: 'pending', stepOptions: config }))
+    expect(queued?.state).toBe('not-started')
+    expect(queued?.target).toBe('files')
+    // Nothing has gone wrong yet, so the section must not open itself expanded.
+    expect(binaryOutputHasWarnings(queued!)).toBe(false)
+
+    for (const state of ['working', 'waiting_decision', 'done'] as const)
+      expect(binaryOutputView(step({ state, stepOptions: config }))?.state).toBe('configured')
+
+    // A recorded claim still wins over either, exactly as it does for a skipped step.
+    expect(
+      binaryOutputView(
+        step({
+          state: 'pending',
+          stepOptions: config,
+          binaryOutputs: report({ undeclared: true }),
+        }),
+      )?.state,
+    ).toBe('undeclared')
+  })
+
+  // A gated-out step holds a selection it never ran with, so `configured` would tell a reader it
+  // is still running or died mid-generation — both wrong, about a step already marked skipped.
+  it('renders nothing for a step skipped by estimate gating', () => {
+    expect(
+      binaryOutputView(
+        step({ skipped: true, stepOptions: { binaryOutput: { storageServiceId: 'files' } } }),
+      ),
+    ).toBeNull()
+    // A recorded claim is never hidden, whatever else the step says about itself.
+    expect(
+      binaryOutputView(
+        step({
+          skipped: true,
+          stepOptions: { binaryOutput: { storageServiceId: 'files' } },
+          binaryOutputs: report({ stored: [artifact('files', 'a.png')] }),
+        }),
+      )?.state,
+    ).toBe('stored')
+  })
+
+  // A parse failure implies an empty `stored`, so reading the list first would report it as
+  // "the agent said it stored nothing" — the one misreading with a completely wrong remedy.
+  it('reports an unreadable declaration as parse-failed, not as declared-none', () => {
+    const view = binaryOutputView(step({ binaryOutputs: report({ parseFailed: true }) }))
+    expect(view?.state).toBe('parse-failed')
+    expect(view?.rows).toHaveLength(0)
+  })
+
+  it('names unknown services and keeps their rows', () => {
+    const view = binaryOutputView(
+      step({
+        binaryOutputs: report({
+          stored: [artifact('files', 'a.png'), artifact('ghost', 'b.png')],
+          unknownServices: ['ghost'],
+        }),
+      }),
+    )
+    // The claim is recorded, not dropped — a reader judges it.
+    expect(view?.rows).toHaveLength(2)
+    expect(view?.unknownDeclaredServices).toEqual(['ghost'])
+    expect(view?.rows[1]?.unknown).toBe(true)
+    expect(view?.rows[0]?.unknown).toBe(false)
+  })
+
+  // The join the report cannot make alone, and the question a human actually opens this for.
+  it('marks a row stored through a service other than the configured target', () => {
+    const view = binaryOutputView(
+      step({
+        stepOptions: { binaryOutput: { storageServiceId: 'files' } },
+        binaryOutputs: report({ stored: [artifact('files', 'a.png'), artifact('audit', 'b.png')] }),
+      }),
+    )
+    expect(view?.target).toBe('files')
+    expect(view?.rows.map((r) => r.misdirected)).toEqual([false, true])
+    expect(view?.misdirected).toBe(1)
+  })
+
+  // A step that never held a selection (a trait-carrying kind dispatched under an overriding
+  // kind) has nothing to compare against — so nothing may be reported as having gone astray.
+  it('marks nothing misdirected when the step carries no selection', () => {
+    const view = binaryOutputView(
+      step({ binaryOutputs: report({ stored: [artifact('audit', 'b.png')] }) }),
+    )
+    expect(view?.target).toBeNull()
+    expect(view?.misdirected).toBe(0)
+    expect(view?.rows[0]?.misdirected).toBe(false)
+  })
+
+  // "The catalog lost the step's own target" and "the agent named a service that never
+  // existed" are the same `unknownServices` entry with opposite fixes.
+  it('distinguishes a lost target from an invented service id', () => {
+    const lost = binaryOutputView(
+      step({
+        stepOptions: { binaryOutput: { storageServiceId: 'files' } },
+        binaryOutputs: report({ stored: [artifact('files', 'a.png')], unknownServices: ['files'] }),
+      }),
+    )
+    expect(lost?.targetUnknown).toBe(true)
+
+    expect(lost?.unknownDeclaredServices).toEqual([])
+
+    const invented = binaryOutputView(
+      step({
+        stepOptions: { binaryOutput: { storageServiceId: 'files' } },
+        binaryOutputs: report({ stored: [artifact('flies', 'a.png')], unknownServices: ['flies'] }),
+      }),
+    )
+    expect(invented?.targetUnknown).toBe(false)
+    expect(invented?.unknownDeclaredServices).toEqual(['flies'])
+  })
+
+  // Both at once is where sharing one field went wrong: the report's own `unknownServices` mixes
+  // the lost target with the invented ids, so a surface reading it raw named ALL of them as "this
+  // step's own storage service" and dropped the invented ones entirely. The two fields are
+  // disjoint by construction, so no renderer can restate one as the other.
+  it('keeps a lost target out of the invented-id list when both happened', () => {
+    const view = binaryOutputView(
+      step({
+        stepOptions: { binaryOutput: { storageServiceId: 'files' } },
+        binaryOutputs: report({
+          stored: [artifact('files', 'a.png'), artifact('ghost', 'b.png')],
+          unknownServices: ['files', 'ghost', 'phantom'],
+        }),
+      }),
+    )
+    expect(view?.targetUnknown).toBe(true)
+    expect(view?.unknownDeclaredServices).toEqual(['ghost', 'phantom'])
+    expect(view?.unknownDeclaredServices).not.toContain('files')
+    expect(binaryOutputHasWarnings(view!)).toBe(true)
+  })
+
+  // A lost target with nothing else unknown is still a warning — it is the whole comparison the
+  // surface exists to make, and the list it used to be counted in is now empty.
+  it('treats a lost target alone as a warning', () => {
+    const view = binaryOutputView(
+      step({
+        stepOptions: { binaryOutput: { storageServiceId: 'files' } },
+        binaryOutputs: report({ stored: [artifact('files', 'a.png')], unknownServices: ['files'] }),
+      }),
+    )
+    expect(view?.unknownDeclaredServices).toEqual([])
+    expect(binaryOutputHasWarnings(view!)).toBe(true)
+  })
+
+  // Without the count, a capped list reads as the whole list and its tail as nonexistent.
+  it('carries the counted losses through verbatim', () => {
+    const view = binaryOutputView(
+      step({
+        binaryOutputs: report({ stored: [artifact('files', 'a')], invalidEntries: 2, omitted: 7 }),
+      }),
+    )
+    expect(view?.invalidEntries).toBe(2)
+    expect(view?.omitted).toBe(7)
+    expect(binaryOutputHasWarnings(view!)).toBe(true)
+  })
+
+  it('treats a clean stored report as warning-free', () => {
+    const view = binaryOutputView(
+      step({
+        stepOptions: { binaryOutput: { storageServiceId: 'files' } },
+        binaryOutputs: report({ stored: [artifact('files', 'a.png')] }),
+      }),
+    )
+    expect(binaryOutputHasWarnings(view!)).toBe(false)
+  })
+})
+
+describe('binaryOutputPickIssues', () => {
+  const service = (id: string, capabilities: string[]) => ({ id, capabilities })
+  const catalog = [
+    service('files', ['asset-storage']),
+    service('inventory', ['generation-context']),
+  ]
+
+  it('accepts a selection that resolves against the catalog', () => {
+    const pick = binaryOutputPickIssues(
+      { storageServiceId: 'files', contextServiceIds: ['inventory'] },
+      catalog,
+      true,
+    )
+    expect(pick.issues).toEqual([])
+  })
+
+  it('flags a step with no storage selection', () => {
+    expect(binaryOutputPickIssues(undefined, catalog, true).issues).toContain('not_selected')
+  })
+
+  // The two refusals run admission raises, surfaced before the round trip rather than after it.
+  it('mirrors the admission refusals for a stale or untagged storage id', () => {
+    expect(binaryOutputPickIssues({ storageServiceId: 'gone' }, catalog, true).issues).toContain(
+      'unknown_service',
+    )
+    expect(
+      binaryOutputPickIssues({ storageServiceId: 'inventory' }, catalog, true).issues,
+    ).toContain('not_storage_capable')
+  })
+
+  // "Pick another" is not a remedy when there is nothing to pick: with no storage service in the
+  // catalog at all, the per-selection judgements would print an instruction the surface cannot
+  // carry out, beside the one that is actionable. The context half is a different selection,
+  // judged on existence alone, so it stays.
+  it('suppresses the per-selection storage judgements when the catalog has no storage service', () => {
+    const contextOnly = [service('inventory', ['generation-context'])]
+    const pick = binaryOutputPickIssues(
+      { storageServiceId: 'gone', contextServiceIds: ['inventory', 'vanished'] },
+      contextOnly,
+      true,
+    )
+    expect(pick.issues).toContain('no_storage_service')
+    expect(pick.issues).not.toContain('unknown_service')
+    expect(pick.issues).not.toContain('not_storage_capable')
+    expect(pick.issues).toContain('unknown_context_service')
+    expect(pick.unknownContextIds).toEqual(['vanished'])
+  })
+
+  it('names every unresolved context id, not just the first', () => {
+    const pick = binaryOutputPickIssues(
+      { storageServiceId: 'files', contextServiceIds: ['inventory', 'gone', 'also-gone'] },
+      catalog,
+      true,
+    )
+    expect(pick.issues).toContain('unknown_context_service')
+    expect(pick.unknownContextIds).toEqual(['gone', 'also-gone'])
+  })
+
+  // An empty picker reads as "no services exist", which is a claim. Not-probed-yet, unreachable
+  // and genuinely empty are three facts an empty array cannot tell apart.
+  it('separates an unreachable and an unprobed catalog from an empty one', () => {
+    expect(binaryOutputPickIssues(undefined, [], true).issues).toContain('no_storage_service')
+    expect(binaryOutputPickIssues(undefined, [], false).issues).toEqual([
+      'catalog_unavailable',
+      'not_selected',
+    ])
+    // Before the probe lands there is nothing to say about the catalog — only about the step.
+    expect(binaryOutputPickIssues(undefined, [], null).issues).toEqual(['not_selected'])
+  })
+
+  // An outage (or a load still in flight) changed nothing about the selection, so neither may
+  // flag every step for re-pick.
+  it('does not judge a selection against a catalog it has not read', () => {
+    for (const available of [false, null] as const) {
+      const pick = binaryOutputPickIssues(
+        { storageServiceId: 'files', contextServiceIds: ['inventory'] },
+        [],
+        available,
+      )
+      expect(pick.issues).not.toContain('unknown_service')
+      expect(pick.issues).not.toContain('unknown_context_service')
+      expect(pick.unknownContextIds).toEqual([])
+    }
+  })
+})