@cat-factory/app 0.254.3 → 0.255.1

package/app/stores/pipelines/draftStepConfig.ts

@@ -15,6 +15,27 @@ import { defaultConsensusConfig, type PipelinesContext } from './context'
  * touches nothing else, which is what makes the two independent; both are spread into the store,
  * so the store's API is unchanged.
  */
+/**
+ * Write ONE field of the step's `StepOptions` bag at `index`, merging into whatever else that step
+ * carries and normalizing an emptied bag back to `null`. `undefined` CLEARS the field.
+ *
+ * Every per-step option below goes through this rather than repeating the clone/assign/normalize
+ * dance, because the two halves that are easy to get wrong are shared by all of them: replacing
+ * the bag loses the neighbouring options a step may also carry, and leaving a `{}` behind makes a
+ * step that is back on every default persist a shape it never had.
+ */
+function patchStepOption<K extends keyof StepOptions>(
+  draftStepOptions: PipelinesContext['draftStepOptions'],
+  index: number,
+  key: K,
+  value: StepOptions[K] | undefined,
+) {
+  const next: StepOptions = { ...draftStepOptions.value[index] }
+  if (value === undefined) delete next[key]
+  else next[key] = value
+  draftStepOptions.value[index] = Object.keys(next).length ? next : null
+}
+
 export function createPipelineStepConfigActions(ctx: PipelinesContext) {
   const {
     draftGates,
@@ -118,10 +139,27 @@ export function createPipelineStepConfigActions(ctx: PipelinesContext) {
    * flag. Merges with any other future StepOptions fields rather than clobbering the whole bag.
    */
   function toggleDraftAutoRecommend(index: number) {
-    const next: StepOptions = { ...draftStepOptions.value[index] }
-    if (draftAutoRecommendEnabled(index)) next.autoRecommend = false
-    else delete next.autoRecommend
-    draftStepOptions.value[index] = Object.keys(next).length ? next : null
+    const off = draftAutoRecommendEnabled(index) ? false : undefined
+    patchStepOption(draftStepOptions, index, 'autoRecommend', off)
+  }
+
+  /**
+   * Whether the draft `deployer` step at `index` declares that its environments outlive the run
+   * (its `stepOptions.retainEnvironment`). OFF by default: the everyday shape is a run that
+   * reclaims what it stood up, and the save boundary refuses a Deployer that does neither.
+   */
+  function draftRetainEnvironment(index: number): boolean {
+    return draftStepOptions.value[index]?.retainEnvironment === true
+  }
+
+  /**
+   * Toggle the retain declaration on the draft `deployer` step at `index`. It is off by default,
+   * so we store ONLY the opt-in (the mirror of `toggleDraftAutoRecommend`, which stores only the
+   * opt-out); toggling back drops the flag and, if the bag empties, the whole entry.
+   */
+  function toggleDraftRetainEnvironment(index: number) {
+    const on = draftRetainEnvironment(index) ? undefined : true
+    patchStepOption(draftStepOptions, index, 'retainEnvironment', on)
   }
 
   /** The skill picked for the draft `skill` step at `index` (its `stepOptions.skillId`). */
@@ -135,10 +173,7 @@ export function createPipelineStepConfigActions(ctx: PipelinesContext) {
    * bag empties, the whole entry (so it normalizes away like the other options).
    */
   function setDraftSkillId(index: number, skillId: string | undefined) {
-    const next: StepOptions = { ...draftStepOptions.value[index] }
-    if (skillId) next.skillId = skillId
-    else delete next.skillId
-    draftStepOptions.value[index] = Object.keys(next).length ? next : null
+    patchStepOption(draftStepOptions, index, 'skillId', skillId || undefined)
   }
 
   /**
@@ -156,10 +191,7 @@ export function createPipelineStepConfigActions(ctx: PipelinesContext) {
    * shipped prompt persists nothing.
    */
   function setDraftAgentVariantId(index: number, agentVariantId: string | undefined) {
-    const next: StepOptions = { ...draftStepOptions.value[index] }
-    if (agentVariantId) next.agentVariantId = agentVariantId
-    else delete next.agentVariantId
-    draftStepOptions.value[index] = Object.keys(next).length ? next : null
+    patchStepOption(draftStepOptions, index, 'agentVariantId', agentVariantId || undefined)
   }
 
   /**
@@ -188,17 +220,16 @@ export function createPipelineStepConfigActions(ctx: PipelinesContext) {
    * wrong thing.
    */
   function setDraftBinaryOutput(index: number, config: BinaryOutputConfig | undefined) {
-    const next: StepOptions = { ...draftStepOptions.value[index] }
-    if (config?.storageServiceId) {
-      const { storageServiceId, contextServiceIds, generatorIds, modalities } = config
-      next.binaryOutput = {
-        storageServiceId,
-        ...(contextServiceIds?.length ? { contextServiceIds } : {}),
-        ...(generatorIds?.length ? { generatorIds } : {}),
-        ...(modalities?.length ? { modalities } : {}),
-      }
-    } else delete next.binaryOutput
-    draftStepOptions.value[index] = Object.keys(next).length ? next : null
+    const { storageServiceId, contextServiceIds, generatorIds, modalities } = config ?? {}
+    const selection = storageServiceId
+      ? {
+          storageServiceId,
+          ...(contextServiceIds?.length ? { contextServiceIds } : {}),
+          ...(generatorIds?.length ? { generatorIds } : {}),
+          ...(modalities?.length ? { modalities } : {}),
+        }
+      : undefined
+    patchStepOption(draftStepOptions, index, 'binaryOutput', selection)
   }
 
   /**
@@ -216,10 +247,7 @@ export function createPipelineStepConfigActions(ctx: PipelinesContext) {
    * other fields here.
    */
   function setDraftMaxOutputTokens(index: number, maxOutputTokens: number | undefined) {
-    const next: StepOptions = { ...draftStepOptions.value[index] }
-    if (maxOutputTokens != null) next.maxOutputTokens = maxOutputTokens
-    else delete next.maxOutputTokens
-    draftStepOptions.value[index] = Object.keys(next).length ? next : null
+    patchStepOption(draftStepOptions, index, 'maxOutputTokens', maxOutputTokens ?? undefined)
   }
 
   return {
@@ -234,6 +262,8 @@ export function createPipelineStepConfigActions(ctx: PipelinesContext) {
     toggleDraftEnabled,
     draftAutoRecommendEnabled,
     toggleDraftAutoRecommend,
+    draftRetainEnvironment,
+    toggleDraftRetainEnvironment,
     draftSkillId,
     setDraftSkillId,
     draftAgentVariantId,

package/app/stores/pipelines/persistence.ts

@@ -62,10 +62,10 @@ export function createPipelinePersistence(
       stepOptions: ctx.draftStepOptions.value.map((o) => o ?? null),
       // Only send labels when there are any.
       ...(ctx.draftLabels.value.length ? { labels: [...ctx.draftLabels.value] } : {}),
-      // Only send purpose when the pipeline is classified (null ⇒ leave unclassified). Like the
-      // legacy per-step arrays, an omitted `purpose` on update reads as "keep existing"; clearing
-      // a classification back to unclassified is not a supported edit (every built-in ships one).
-      ...(ctx.draftPurpose.value ? { purpose: ctx.draftPurpose.value } : {}),
+      // ALWAYS sent, like `stepOptions` above and for the same reason: `purpose` is mandatory on
+      // create, and on update an omitted field reads as "keep existing", so a re-classification
+      // would silently not persist. There is no "unclassified" to clear back to.
+      purpose: ctx.draftPurpose.value,
     }
   }
 

package/app/stores/pipelines.ts

@@ -70,11 +70,15 @@ export const usePipelinesStore = defineStore('pipelines', () => {
   const draftLabels = ref<string[]>([])
   /**
    * The use-case classifier of the pipeline being assembled/edited (`build` / `document` /
-   * `review` / `research` / `planning`), or null when unclassified. Drives which task pickers
-   * offer the saved pipeline and which agent kinds the builder palette shows (a non-`build`
-   * purpose hides the Implementation/Testing kinds).
+   * `review` / `research` / `planning`). Drives which task pickers offer the saved pipeline, which
+   * agent kinds the builder palette shows (a non-`build` purpose hides the Implementation/Testing
+   * kinds) and which saved pipelines the library lists.
+   *
+   * Never null: `Pipeline.purpose` is mandatory, so a draft is classified from the moment it
+   * exists. `build` is the default because it is what an unclassified pipeline has always behaved
+   * as, so the dial starts where the old absence pointed rather than at a choice nobody made.
    */
-  const draftPurpose = ref<PipelinePurpose | null>(null)
+  const draftPurpose = ref<PipelinePurpose>('build')
   const draftName = ref('New pipeline')
   /** Prose description for the pipeline being assembled/edited (shown in the pickers). */
   const draftDescription = ref('')

package/app/utils/agentPalette.spec.ts

@@ -31,27 +31,33 @@ const CATALOG: AgentArchetype[] = [
 ]
 
 describe('narrowAgentPalette', () => {
-  it('narrows nothing for an unclassified pipeline at the widest tier', () => {
-    const { offered, hiddenByPurpose, hiddenByTier } = narrowAgentPalette(CATALOG, null, 'advanced')
+  it('narrows nothing for a build pipeline at the widest tier', () => {
+    const { offered, hiddenByPurpose, hiddenByTier } = narrowAgentPalette(
+      CATALOG,
+      'build',
+      'advanced',
+    )
     expect(offered.map((a) => a.kind)).toEqual(CATALOG.map((a) => a.kind))
     expect(hiddenByPurpose).toBe(0)
     expect(hiddenByTier).toBe(0)
   })
 
   it('accumulates the tiers when the purpose narrows nothing', () => {
-    expect(narrowAgentPalette(CATALOG, null, 'basic').offered.map((a) => a.kind)).toEqual([
+    expect(narrowAgentPalette(CATALOG, 'build', 'basic').offered.map((a) => a.kind)).toEqual([
       'coder',
       'architect',
       'documenter',
     ])
-    expect(narrowAgentPalette(CATALOG, null, 'intermediate').offered.map((a) => a.kind)).toEqual([
-      'coder',
-      'architect',
-      'documenter',
-      // An undeclared tier defaults to intermediate, so it appears here.
-      'acme-auditor',
-    ])
-    expect(narrowAgentPalette(CATALOG, null, 'basic').hiddenByTier).toBe(3)
+    expect(narrowAgentPalette(CATALOG, 'build', 'intermediate').offered.map((a) => a.kind)).toEqual(
+      [
+        'coder',
+        'architect',
+        'documenter',
+        // An undeclared tier defaults to intermediate, so it appears here.
+        'acme-auditor',
+      ],
+    )
+    expect(narrowAgentPalette(CATALOG, 'build', 'basic').hiddenByTier).toBe(3)
   })
 
   it('counts each dial against what the OTHER already admits', () => {

package/app/utils/agentPalette.ts

@@ -42,7 +42,7 @@ export interface NarrowedAgentPalette<T> {
  */
 export function narrowAgentPalette<T extends Pick<AgentArchetype, 'tier' | 'category'>>(
   archetypes: readonly T[],
-  purpose: PipelinePurpose | null | undefined,
+  purpose: PipelinePurpose,
   tier: AgentTier,
 ): NarrowedAgentPalette<T> {
   const relevant = (a: T) => !a.category || purposeSuggestsAgentCategory(purpose, a.category)

package/app/utils/catalog.ts

@@ -210,12 +210,14 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
   },
   {
     // Provisions the ephemeral environment the tester / human-test / playwright steps read, which
-    // is why it leads the testing group. A palette block for the same reason `disposer` is one:
-    // `assertDeployerBeforeConsumer` REFUSES a run whose chain reaches an env consumer with no
-    // Deployer in front of it on a deployable service, and a hand-built pipeline that hits that
-    // refusal has no reseed to fall back on.
+    // is why it leads the testing group.
+    //
+    // `basic`, and it has to be: a pipeline that reaches an env consumer with no Deployer in
+    // front of it is refused at SAVE (`validatePipelineAuthoring`), and the API Tester it serves
+    // is itself `basic`. Leaving the Deployer out of the basic palette would leave a basic-mode
+    // user composing a pipeline they cannot save and cannot see the fix for.
     kind: 'deployer',
-    tier: 'intermediate',
+    tier: 'basic',
     label: 'Deployer',
     icon: 'i-lucide-cloud-upload',
     color: '#34d399',
@@ -276,8 +278,11 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     // is the point of it: after the automated tester, or after a human has finished with the live
     // URL. Without one, the TTL sweep reclaims environments on a timer long after the run
     // settled, which is a fine backstop and cannot close the run's own teardown proof.
+    //
+    // `basic` for the same reason the Deployer is: a chain that deploys and never reclaims is
+    // refused at save, so the fix has to be reachable wherever the fault can be composed.
     kind: 'disposer',
-    tier: 'intermediate',
+    tier: 'basic',
     label: 'Disposer',
     icon: 'i-lucide-cloud-off',
     color: '#34d399',

package/app/utils/pipeline.spec.ts

@@ -74,16 +74,19 @@ describe('pipelineAllowedForTaskType', () => {
     expect(pipelineAllowedForTaskType(pipeline({ purpose: 'document' }), 'document')).toBe(true)
     expect(pipelineAllowedForTaskType(pipeline({ purpose: 'build' }), 'document')).toBe(false)
     expect(pipelineAllowedForTaskType(pipeline({ purpose: 'research' }), 'document')).toBe(false)
-    // An unclassified pipeline is hidden from a document task (it requires the explicit classifier).
-    expect(pipelineAllowedForTaskType(pipeline({ purpose: undefined }), 'document')).toBe(false)
+    // A classifier this build cannot NAME is hidden too: this narrowing requires the explicit
+    // member, because a non-document pipeline on a document task authors no document at all.
+    expect(pipelineAllowedForTaskType(pipeline({ purpose: UNKNOWN_PURPOSE }), 'document')).toBe(
+      false,
+    )
   })
 
   it('a review task offers ONLY review-purpose pipelines', () => {
     expect(pipelineAllowedForTaskType(pipeline({ purpose: 'review' }), 'review')).toBe(true)
     expect(pipelineAllowedForTaskType(pipeline({ purpose: 'build' }), 'review')).toBe(false)
     expect(pipelineAllowedForTaskType(pipeline({ purpose: 'document' }), 'review')).toBe(false)
-    // An unclassified pipeline is hidden from a review task (it requires the explicit classifier).
-    expect(pipelineAllowedForTaskType(pipeline({ purpose: undefined }), 'review')).toBe(false)
+    // Same disposition as the document task's, for the same reason.
+    expect(pipelineAllowedForTaskType(pipeline({ purpose: UNKNOWN_PURPOSE }), 'review')).toBe(false)
   })
 
   it('a programmatic task (feature / bug) hides only what cannot ship code', () => {
@@ -99,26 +102,27 @@ describe('pipelineAllowedForTaskType', () => {
     }
   })
 
-  it('keeps an UNCLASSIFIED pipeline on a feature / bug task', () => {
-    // The one place this narrowing runs opposite to the document/review one, and it has to: a
-    // `purpose` is optional at every write boundary (the builder leaves it unset by default, a
-    // registered deployment pipeline need not declare one), so requiring it here would hide a
-    // workspace's own hand-built pipelines from the picker they were built for — silently, with
-    // nothing on screen to explain the absence. Unclassified is not known-wrong for a feature the
-    // way a document preset is.
+  it('keeps a pipeline whose classifier this build cannot name on a feature / bug task', () => {
+    // The one place this narrowing runs opposite to the document/review one, and it has to. The
+    // value is persisted, so a deployment's own classifier (or one retired since the row was
+    // written) reaches a bundle with no member for it — and hiding it would take that pipeline out
+    // of the picker people use most, silently, with nothing on screen to explain the absence. It is
+    // not known-wrong for a feature the way a document preset is.
     for (const type of ['feature', 'bug'] as const) {
-      expect(pipelineAllowedForTaskType(pipeline({ purpose: undefined }), type)).toBe(true)
+      expect(pipelineAllowedForTaskType(pipeline({ purpose: UNKNOWN_PURPOSE }), type)).toBe(true)
     }
-    // Still hidden from the types whose narrowing DOES demand the explicit classifier.
-    expect(pipelineAllowedForTaskType(pipeline({ purpose: undefined }), 'document')).toBe(false)
-    expect(pipelineAllowedForTaskType(pipeline({ purpose: undefined }), 'review')).toBe(false)
+    // Still hidden from the types whose narrowing DOES demand the explicit member.
+    expect(pipelineAllowedForTaskType(pipeline({ purpose: UNKNOWN_PURPOSE }), 'document')).toBe(
+      false,
+    )
+    expect(pipelineAllowedForTaskType(pipeline({ purpose: UNKNOWN_PURPOSE }), 'review')).toBe(false)
   })
 
   it('an un-narrowed task type stays unrestricted (spike, ralph, custom, undefined)', () => {
     // A custom (namespaced) deployment type has no purpose mapping we could infer, and `spike` /
     // `ralph` pin their own default pipeline instead of narrowing the picker.
     for (const type of ['spike', 'ralph', 'acme:incident', undefined] as const) {
-      for (const purpose of ['build', 'document', 'review', 'research', undefined] as const) {
+      for (const purpose of ['build', 'document', 'review', 'research'] as const) {
         expect(pipelineAllowedForTaskType(pipeline({ purpose }), type)).toBe(true)
       }
     }
@@ -151,8 +155,8 @@ describe('pipelineAllowedForBlockLevel (initiative binding)', () => {
 })
 
 describe('purposeAllowsAgentCategory (builder save gate)', () => {
-  it('a build (or unclassified) pipeline may use every category', () => {
-    for (const purpose of ['build', null, undefined] as const) {
+  it('a build pipeline, and one whose classifier this build cannot name, may use every category', () => {
+    for (const purpose of ['build', UNKNOWN_PURPOSE] as const) {
       for (const cat of AGENT_CATEGORIES) {
         expect(purposeAllowsAgentCategory(purpose, cat)).toBe(true)
       }
@@ -173,8 +177,8 @@ describe('purposeAllowsAgentCategory (builder save gate)', () => {
 })
 
 describe('purposeSuggestsAgentCategory (builder palette filter)', () => {
-  it('offers the whole catalog to a build pipeline and to an unclassified one', () => {
-    for (const purpose of ['build', null, undefined] as const) {
+  it('offers the whole catalog to a build pipeline, and to one it cannot name', () => {
+    for (const purpose of ['build', UNKNOWN_PURPOSE] as const) {
       for (const cat of AGENT_CATEGORIES) {
         expect(purposeSuggestsAgentCategory(purpose, cat)).toBe(true)
       }

package/app/utils/pipelineLibrary.spec.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest'
+import { PIPELINE_PURPOSES } from '@cat-factory/contracts'
+import type { Pipeline } from '~/types/domain'
+import { narrowPipelineLibrary } from '~/utils/pipelineLibrary'
+
+type Row = Pick<Pipeline, 'purpose' | 'labels' | 'archived'> & { id: string }
+
+const row = (id: string, purpose: Pipeline['purpose'], extra: Partial<Row> = {}): Row => ({
+  id,
+  purpose,
+  ...extra,
+})
+
+// A purpose this build has no member for: what a row saved by a newer build (or before a member
+// was retired) looks like on the way back out of the store. Reachable even though the field is
+// mandatory, which is the whole reason the predicates still narrow the value they are handed.
+const UNKNOWN_PURPOSE = 'acme-migration' as Pipeline['purpose']
+
+// Spread across all three dials, so neither count can come out right by coincidence: an archived
+// row and a differently-labelled row are excluded by the OTHER dials either way.
+const LIBRARY: Row[] = [
+  row('build-a', 'build'),
+  row('build-archived', 'build', { archived: true }),
+  row('review-a', 'review'),
+  row('review-tagged', 'review', { labels: ['nightly'] }),
+  row('review-archived-tagged', 'review', { archived: true, labels: ['nightly'] }),
+  row('document-tagged', 'document', { labels: ['nightly'] }),
+]
+
+describe('narrowPipelineLibrary', () => {
+  it('lists every purpose when the library is browsed at none', () => {
+    // `null` is the library's own relaxation, not an unclassified draft: `Pipeline.purpose` is
+    // mandatory, so the reader asking to browse past the purpose is the only way to get here.
+    const { offered, hiddenByPurpose } = narrowPipelineLibrary(LIBRARY, {
+      purpose: null,
+      showArchived: true,
+    })
+    expect(offered.map((p) => p.id)).toEqual(LIBRARY.map((p) => p.id))
+    expect(hiddenByPurpose).toBe(0)
+  })
+
+  it('lists the pipelines built for the purpose being browsed at', () => {
+    const { offered, hiddenByPurpose } = narrowPipelineLibrary(LIBRARY, { purpose: 'review' })
+    expect(offered.map((p) => p.id)).toEqual(['review-a', 'review-tagged'])
+    // `build-archived` is hidden by the archive toggle either way, so the purpose does not claim it.
+    expect(hiddenByPurpose).toBe(2)
+  })
+
+  it('measures the purpose count against what the other dials already admit', () => {
+    // The rule `narrowAgentPalette` established: each hint promises "relax THIS dial alone and you
+    // get n more". Counting over the whole library would name `build-a` here, which the label
+    // filter hides at every purpose.
+    const { offered, hiddenByPurpose } = narrowPipelineLibrary(LIBRARY, {
+      purpose: 'review',
+      label: 'nightly',
+    })
+    expect(offered.map((p) => p.id)).toEqual(['review-tagged'])
+    expect(hiddenByPurpose).toBe(1)
+  })
+
+  it('counts the archived rows the OTHER dials admit, not the whole catalog', () => {
+    // The count the "Archived (n)" toggle renders. Against the raw catalog it would promise rows
+    // the toggle cannot reveal: two pipelines are archived, but only one of them is a `review` one.
+    expect(narrowPipelineLibrary(LIBRARY, { purpose: 'review' }).archivedInScope).toBe(1)
+    expect(narrowPipelineLibrary(LIBRARY, { purpose: 'planning' }).archivedInScope).toBe(0)
+    expect(narrowPipelineLibrary(LIBRARY, { purpose: null }).archivedInScope).toBe(2)
+    expect(
+      narrowPipelineLibrary(LIBRARY, { purpose: null, label: 'nightly' }).archivedInScope,
+    ).toBe(1)
+  })
+
+  it('keeps the archived count steady across the toggle it governs', () => {
+    // Unlike `hiddenByPurpose`, this one may NOT drop to zero once the dial is relaxed: it decides
+    // whether the toggle is offered at all, so a count that vanished when the toggle worked would
+    // strand the archived rows visible with no way to hide them again.
+    const shown = narrowPipelineLibrary(LIBRARY, { purpose: 'review', showArchived: true })
+    expect(shown.offered.map((p) => p.id)).toEqual([
+      'review-a',
+      'review-tagged',
+      'review-archived-tagged',
+    ])
+    expect(shown.archivedInScope).toBe(1)
+  })
+
+  it('narrows by neither purpose this build cannot name', () => {
+    // Same disposition as the palette's: an unrecognised value is one this build has nothing to
+    // narrow BY and nothing to narrow it AGAINST, never a reason to guess a current member. A
+    // stored row carrying one stays reachable in the editor that has to fix it.
+    const stored = [...LIBRARY, row('acme', UNKNOWN_PURPOSE)]
+    for (const purpose of PIPELINE_PURPOSES) {
+      expect(narrowPipelineLibrary(stored, { purpose }).offered.some((p) => p.id === 'acme')).toBe(
+        true,
+      )
+    }
+    expect(narrowPipelineLibrary(stored, { purpose: UNKNOWN_PURPOSE })).toEqual({
+      offered: stored.filter((p) => !p.archived),
+      hiddenByPurpose: 0,
+      archivedInScope: 2,
+    })
+  })
+})

package/app/utils/pipelineLibrary.ts

@@ -0,0 +1,69 @@
+import { pipelineMatchesPurpose, type PipelinePurpose } from '@cat-factory/contracts'
+import type { Pipeline } from '~/types/domain'
+
+/** What the pipeline builder's saved-pipeline library is being browsed at. */
+export interface PipelineLibraryFilters {
+  /**
+   * The purpose to list, or `null` for "every purpose" — the library's own relaxation, NOT an
+   * unclassified draft. `Pipeline.purpose` is mandatory, so the draft always has one; `null` is
+   * the reader saying they want to browse past it.
+   */
+  purpose?: PipelinePurpose | null
+  /** The picked organizational label, or `null` for all of them. */
+  label?: string | null
+  /** Whether archived pipelines are included. */
+  showArchived?: boolean
+}
+
+/**
+ * The saved-pipeline library narrowed to what it lists, plus what each hidden-by-default dial is
+ * holding back.
+ *
+ * Both counts are measured against what the OTHER dials already admit, which is the promise
+ * `narrowAgentPalette` established: relax THIS dial alone and you get n more. Counting either over
+ * the whole catalog would name rows another filter is hiding either way, sending the reader to a
+ * control that cannot produce them.
+ *
+ * The label chips are the one dial with no count, because they are the one dial that already shows
+ * its own selection and its own alternatives.
+ */
+export interface NarrowedPipelineLibrary<T> {
+  /** The pipelines every dial admits: what the library renders, in input order. */
+  offered: T[]
+  /** How many more the CURRENT label + archive selection would list at every purpose. */
+  hiddenByPurpose: number
+  /**
+   * How many ARCHIVED pipelines the current purpose + label selection covers.
+   *
+   * Deliberately independent of `showArchived`, unlike {@link hiddenByPurpose}: this is what the
+   * archive toggle governs, and it has to be the same number in both of the toggle's positions or
+   * the control that turned archived rows ON would vanish the moment it worked, stranding them
+   * visible with no way back. While they are hidden it is also exactly what relaxing that dial
+   * alone would add.
+   */
+  archivedInScope: number
+}
+
+/**
+ * Reduce `pipelines` to the rows the builder's library lists under `filters`.
+ *
+ * A pure reduction rather than three predicates inlined in the template for the reason
+ * {@link import('./agentPalette').narrowAgentPalette} is one: it decides what is VISIBLE and it
+ * owes an honest count of what it hid, and a count re-derived at the call site as a subtraction
+ * measures the wrong population. The purpose rule itself lives in `@cat-factory/contracts` beside
+ * the palette's and the pickers', so the three cannot read a stored `purpose` in different
+ * directions.
+ */
+export function narrowPipelineLibrary<T extends Pick<Pipeline, 'purpose' | 'labels' | 'archived'>>(
+  pipelines: readonly T[],
+  filters: PipelineLibraryFilters,
+): NarrowedPipelineLibrary<T> {
+  const labelled = (p: T) => !filters.label || (p.labels ?? []).includes(filters.label)
+  const listed = (p: T) => Boolean(filters.showArchived) || !p.archived
+  const suits = (p: T) => pipelineMatchesPurpose(p, filters.purpose)
+  return {
+    offered: pipelines.filter((p) => labelled(p) && listed(p) && suits(p)),
+    hiddenByPurpose: pipelines.filter((p) => labelled(p) && listed(p) && !suits(p)).length,
+    archivedInScope: pipelines.filter((p) => labelled(p) && suits(p) && p.archived).length,
+  }
+}

package/i18n/locales/de.json

@@ -4213,7 +4213,6 @@
       "strategy": "Strategie",
       "rounds": "Runden",
       "purposeLabel": "Zweck",
-      "purposePlaceholder": "Zweck auswählen",
       "purposeUnrecognized": "Nicht erkannt ({purpose})",
       "purposeOption": {
         "build": "Entwicklung",
@@ -4232,6 +4231,10 @@
       "removeParticipant": "Teilnehmer entfernen (min. 2)",
       "addParticipant": "Teilnehmer hinzufügen",
       "savedPipelines": "Gespeicherte Pipelines",
+      "purposeHiddenPipelines": "{count} gespeicherte Pipeline ist für diesen Zweck ausgeblendet. | {count} gespeicherte Pipelines sind für diesen Zweck ausgeblendet.",
+      "everyPurposeListed": "Gespeicherte Pipelines aller Zwecke werden aufgelistet.",
+      "listEveryPurpose": "Alle Zwecke anzeigen",
+      "narrowToDraftPurpose": "Auf diesen Zweck eingrenzen",
       "hideArchived": "Archivierte ausblenden",
       "archivedCount": "Archiviert ({count})",
       "allLabels": "Alle",
@@ -4290,6 +4293,13 @@
       "binaryOutputPlaceholder": "Speicherdienst wählen",
       "binaryOutputContextPlaceholder": "Optional: Dienste, die den Umfang bestimmen",
       "binaryOutputNeedsPick": "Für einen Schritt, der binäre Ausgaben erzeugt, ist kein Speicherdienst gewählt. Wähle einen vor dem Speichern.",
+      "envNeedsDeployer": "Vor einem Tester-, manuellen Test- oder Playwright-Schritt wird ein Deployer benötigt. Füge einen hinzu, sonst lässt sich die Pipeline nicht speichern (bei einem Service ohne Provisionierung bleibt er wirkungslos).",
+      "envNeedsDisposer": "Nach einem Deployer wird ein Disposer benötigt, der die bereitgestellte Umgebung wieder freigibt. Füge einen hinzu oder markiere den Deployer so, dass er seine Umgebung über den Lauf hinaus behält, sonst lässt sich die Pipeline nicht speichern.",
+      "envDisposerNeedsDeployer": "Vor diesem Disposer steht kein Deployer, es gibt also nichts freizugeben. Füge einen Deployer hinzu oder entferne den Disposer.",
+      "envConsumerAfterDisposer": "Ein Tester-, manueller Test- oder Playwright-Schritt läuft erst, nachdem der Disposer die Umgebung bereits freigegeben hat, es bliebe also nichts übrig, wogegen er laufen könnte. Verschiebe den Disposer hinter diesen Schritt oder füge davor einen weiteren Deployer ein.",
+      "envRetainedButReclaimed": "Dieser Deployer ist so markiert, dass er seine Umgebung über den Lauf hinaus behält, aber ein nachfolgender Disposer gibt genau diese Umgebung frei. Entferne den Disposer oder hebe die Markierung auf.",
+      "retainEnvironmentSetTooltip": "Wird am Ende des Laufs freigegeben. Klicke, um diese Umgebung danach weiterlaufen zu lassen (eine Vorschau, die Prüfende nach dem Öffnen des PR nutzen); die TTL oder ein Betreiber fährt sie dann herunter.",
+      "retainEnvironmentClearTooltip": "Läuft nach dem Ende des Laufs weiter. Klicke, um sie wieder per Disposer-Schritt freizugeben.",
       "binaryOutputNoStorage": "Kein Dienst im Katalog dieses Boards deklariert die Fähigkeit {capability}. Registriere einen, oder ergänze die Fähigkeit beim gemeinten Dienst unter den grundlegenden Diensten.",
       "binaryOutputMissing": "Dieser Speicherdienst ist nicht mehr im Katalog; wähle einen anderen.",
       "binaryOutputNotStorage": "Dieser Dienst deklariert die Fähigkeit {capability} nicht mehr, deshalb werden Läufe abgelehnt; wähle einen anderen.",

package/i18n/locales/en.json

@@ -4795,7 +4795,6 @@
       "strategy": "Strategy",
       "rounds": "Rounds",
       "purposeLabel": "Purpose",
-      "purposePlaceholder": "Select a purpose",
       "purposeUnrecognized": "Unrecognized ({purpose})",
       "@purposeUnrecognized": {
         "description": "Shown on the pipeline-purpose control when the pipeline carries a purpose this build has no label for (a member added by a newer build, or one since retired). The raw stored value is quoted back so it can be recognised and re-picked."
@@ -4817,6 +4816,13 @@
       "removeParticipant": "Remove participant (min 2)",
       "addParticipant": "Add participant",
       "savedPipelines": "Saved pipelines",
+      "purposeHiddenPipelines": "{count} saved pipeline hidden for this purpose. | {count} saved pipelines hidden for this purpose.",
+      "everyPurposeListed": "Listing saved pipelines for every purpose.",
+      "listEveryPurpose": "Show every purpose",
+      "narrowToDraftPurpose": "Narrow to this purpose",
+      "@purposeHiddenPipelines": {
+        "description": "Shown above the saved-pipeline list in the pipeline builder: how many saved pipelines are not listed because they were built for a different purpose than the one being edited."
+      },
       "hideArchived": "Hide archived",
       "archivedCount": "Archived ({count})",
       "allLabels": "All",
@@ -4875,6 +4881,13 @@
       "binaryOutputPlaceholder": "Pick a storage service",
       "binaryOutputContextPlaceholder": "Optional: services that scope the generation",
       "binaryOutputNeedsPick": "A step that generates binary outputs has no storage service selected. Pick one before saving.",
+      "envNeedsDeployer": "A Tester, human-test or Playwright step needs a Deployer before it. Add one or the pipeline won't save (it is a no-op on a service that provisions nothing).",
+      "envNeedsDisposer": "A Deployer needs a Disposer after it to reclaim the environment it stands up. Add one, or mark the Deployer as keeping its environment past the run, otherwise the pipeline won't save.",
+      "envDisposerNeedsDeployer": "This Disposer has no Deployer before it, so there is nothing for it to reclaim. Add a Deployer, or remove the Disposer.",
+      "envConsumerAfterDisposer": "A Tester, human-test or Playwright step runs after the Disposer has already reclaimed the environment, so nothing would be left to run against. Move the Disposer below that step, or add another Deployer before it.",
+      "envRetainedButReclaimed": "This Deployer is marked as keeping its environment past the run, but a Disposer after it reclaims exactly that environment. Remove the Disposer, or clear the keep-environment setting.",
+      "retainEnvironmentSetTooltip": "Reclaimed at the end of the run. Click to keep this environment running afterwards (a preview reviewers use once the PR is open); its TTL or an operator then takes it down.",
+      "retainEnvironmentClearTooltip": "Kept running after the run ends. Click to go back to reclaiming it with a Disposer step.",
       "binaryOutputNoStorage": "No service in this board's catalog declares the {capability} capability. Register one, or add the capability to the service you meant, under foundational services.",
       "binaryOutputMissing": "This storage service is no longer in the catalog; pick another.",
       "binaryOutputNotStorage": "This service no longer declares the {capability} capability, so runs will be refused; pick another.",

package/i18n/locales/es.json

@@ -4652,7 +4652,6 @@
       "strategy": "Estrategia",
       "rounds": "Rondas",
       "purposeLabel": "Propósito",
-      "purposePlaceholder": "Seleccionar un propósito",
       "purposeUnrecognized": "No reconocido ({purpose})",
       "purposeOption": {
         "build": "Desarrollo",
@@ -4671,6 +4670,10 @@
       "removeParticipant": "Quitar participante (mín. 2)",
       "addParticipant": "Añadir participante",
       "savedPipelines": "Pipelines guardados",
+      "purposeHiddenPipelines": "{count} pipeline guardado oculto para este propósito. | {count} pipelines guardados ocultos para este propósito.",
+      "everyPurposeListed": "Se muestran los pipelines guardados de todos los propósitos.",
+      "listEveryPurpose": "Mostrar todos los propósitos",
+      "narrowToDraftPurpose": "Limitar a este propósito",
       "hideArchived": "Ocultar archivados",
       "archivedCount": "Archivados ({count})",
       "allLabels": "Todas",
@@ -4729,6 +4732,13 @@
       "binaryOutputPlaceholder": "Elige un servicio de almacenamiento",
       "binaryOutputContextPlaceholder": "Opcional: servicios que delimitan la generación",
       "binaryOutputNeedsPick": "Un paso que genera salidas binarias no tiene servicio de almacenamiento elegido. Elige uno antes de guardar.",
+      "envNeedsDeployer": "Un paso de Tester, prueba manual o Playwright necesita un Deployer antes. Añade uno o la canalización no se guardará (no hace nada en un servicio que no aprovisiona).",
+      "envNeedsDisposer": "Un Deployer necesita un Disposer después para liberar el entorno que levanta. Añade uno, o marca el Deployer para que conserve su entorno más allá de la ejecución; de lo contrario la canalización no se guardará.",
+      "envDisposerNeedsDeployer": "Este Disposer no tiene ningún Deployer antes, así que no hay nada que liberar. Añade un Deployer o quita el Disposer.",
+      "envConsumerAfterDisposer": "Un paso de Tester, prueba manual o Playwright se ejecuta después de que el Disposer ya haya liberado el entorno, así que no quedaría nada contra lo que ejecutarlo. Mueve el Disposer por debajo de ese paso, o añade otro Deployer antes.",
+      "envRetainedButReclaimed": "Este Deployer está marcado para conservar su entorno más allá de la ejecución, pero un Disposer posterior libera exactamente ese entorno. Quita el Disposer o desmarca la opción de conservar el entorno.",
+      "retainEnvironmentSetTooltip": "Se libera al terminar la ejecución. Haz clic para mantener este entorno en marcha después (una vista previa que los revisores usan con el PR abierto); luego lo retirará su TTL o un operador.",
+      "retainEnvironmentClearTooltip": "Se mantiene en marcha tras la ejecución. Haz clic para volver a liberarlo con un paso Disposer.",
       "binaryOutputNoStorage": "Ningún servicio del catálogo de este tablero declara la capacidad {capability}. Registra uno, o añade la capacidad al servicio que tenías en mente, en servicios fundamentales.",
       "binaryOutputMissing": "Este servicio de almacenamiento ya no está en el catálogo; elige otro.",
       "binaryOutputNotStorage": "Este servicio ya no declara la capacidad {capability}, así que las ejecuciones se rechazarán; elige otro.",