@cat-factory/app 0.255.0 → 0.256.0

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/types/domain.ts

@@ -117,7 +117,7 @@ export type {
   PreviewStatus,
 } from '@cat-factory/contracts'
 
-import type { AgentCategory, AgentKind, AgentTier } from '@cat-factory/contracts'
+import type { AgentCategory, AgentKind, AgentTier, PipelinePurpose } from '@cat-factory/contracts'
 
 // The document-kind list + the per-kind field descriptors are runtime values (used to render
 // the picker and the conditional per-kind inputs), so they are re-exported as values — the
@@ -135,6 +135,12 @@ export interface AgentArchetype {
   description: string
   /** Palette category this archetype is grouped under. Absent ⇒ ungrouped/system kind. */
   category?: AgentCategory
+  /**
+   * The pipeline PURPOSES the palette offers this kind to, WITHIN the ones its {@link category}
+   * already admits (`purposeSuggestsAgentKind`). Absent ⇒ the category alone decides, which is
+   * the normal case: declare this only to opt OUT of a purpose the category would admit.
+   */
+  purposes?: readonly PipelinePurpose[]
   /**
    * How specialist this kind is — the tier the palette / model-preset override list filter on
    * (`basic` shows only basic kinds, `intermediate` adds those, `advanced` shows everything).

package/app/utils/agentPalette.spec.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest'
+import type { PipelinePurpose } from '@cat-factory/contracts'
 import type { AgentArchetype } from '~/types/domain'
 import { groupAgentPalette, narrowAgentPalette } from '~/utils/agentPalette'
 
@@ -6,6 +7,7 @@ const archetype = (
   kind: string,
   category?: AgentArchetype['category'],
   tier?: AgentArchetype['tier'],
+  purposes?: AgentArchetype['purposes'],
 ): AgentArchetype => ({
   kind: kind as AgentArchetype['kind'],
   label: kind,
@@ -14,6 +16,7 @@ const archetype = (
   description: kind,
   ...(category ? { category } : {}),
   ...(tier ? { tier } : {}),
+  ...(purposes ? { purposes } : {}),
 })
 
 // Spread across both dials on purpose: every combination of relevant/irrelevant to a `planning`
@@ -100,6 +103,33 @@ describe('narrowAgentPalette', () => {
     expect(hiddenByBoth).toBe(1)
   })
 
+  it('narrows WITHIN a category when a kind declares the purposes it is for', () => {
+    // The reason relevance is asked of the KIND: a category is a shelf label, so `documenter` and
+    // `doc-reviewer` sit on the same shelf while only one of them belongs in a pipeline that
+    // reviews someone else's pull request. Both dials still apply to the declaring kind.
+    const catalog = [
+      archetype('documenter', 'docs', 'basic', ['build', 'document']),
+      archetype('doc-reviewer', 'docs', 'basic', ['build', 'review']),
+      archetype('house-style', 'docs', 'basic'),
+    ]
+    const offered = (purpose: PipelinePurpose) =>
+      narrowAgentPalette(catalog, purpose, 'advanced').offered.map((a) => a.kind)
+    expect(offered('review')).toEqual(['doc-reviewer', 'house-style'])
+    expect(offered('document')).toEqual(['documenter', 'house-style'])
+    // `planning` drops the whole `docs` category, and the declarations do not override that for
+    // the kinds that named it: a declared list is the kind's own answer, not an exemption.
+    expect(offered('planning')).toEqual([])
+    expect(narrowAgentPalette(catalog, 'review', 'advanced').hiddenByPurpose).toBe(1)
+  })
+
+  it('falls back to the category when a declared list names nothing this build knows', () => {
+    // The mirror of the unknown-purpose rule: a kind whose entire list was retired has told this
+    // build nothing, so its section decides rather than the kind vanishing from every palette.
+    const stale = archetype('acme-doc', 'docs', 'basic', ['acme-migration' as never])
+    expect(narrowAgentPalette([stale], 'document', 'advanced').offered).toEqual([stale])
+    expect(narrowAgentPalette([stale], 'planning', 'advanced').offered).toEqual([])
+  })
+
   it('keeps a purpose this build does not recognise from narrowing anything', () => {
     // A stored `purpose` from a build that shipped a member this one has not (or has retired):
     // unknown is not a licence to guess, so the palette offers what the tier admits and says so.

package/app/utils/agentPalette.ts

@@ -2,7 +2,7 @@ import {
   type AgentTier,
   agentTierVisibleAt,
   type PipelinePurpose,
-  purposeSuggestsAgentCategory,
+  purposeSuggestsAgentKind,
 } from '@cat-factory/contracts'
 import type { AgentArchetype } from '~/types/domain'
 
@@ -36,16 +36,17 @@ export interface NarrowedAgentPalette<T> {
  * Reduce `archetypes` to what the palette offers at `purpose` + `tier`, with each dial's hint
  * count (see {@link NarrowedAgentPalette} for what the counts promise).
  *
- * An archetype carrying no `category` has nothing for the purpose dial to judge, so it is always
- * relevant; an absent `tier` is `DEFAULT_AGENT_TIER`. Both are how a deployment-registered kind
- * that declares neither behaves, and neither is a reason to drop it from the catalog.
+ * Relevance is asked of the KIND (`purposeSuggestsAgentKind`), which reads the kind's own
+ * `purposes` when it declares one and falls back to its `category`'s row otherwise, so a kind
+ * that belongs to one use-case can leave a section its siblings still belong in. An archetype
+ * carrying neither has nothing for the purpose dial to judge and is always relevant; an absent
+ * `tier` is `DEFAULT_AGENT_TIER`. All three are how a deployment-registered kind that declares
+ * nothing behaves, and none of them is a reason to drop it from the catalog.
  */
-export function narrowAgentPalette<T extends Pick<AgentArchetype, 'tier' | 'category'>>(
-  archetypes: readonly T[],
-  purpose: PipelinePurpose,
-  tier: AgentTier,
-): NarrowedAgentPalette<T> {
-  const relevant = (a: T) => !a.category || purposeSuggestsAgentCategory(purpose, a.category)
+export function narrowAgentPalette<
+  T extends Pick<AgentArchetype, 'tier' | 'category' | 'purposes'>,
+>(archetypes: readonly T[], purpose: PipelinePurpose, tier: AgentTier): NarrowedAgentPalette<T> {
+  const relevant = (a: T) => purposeSuggestsAgentKind(purpose, a)
   const inTier = (a: T) => agentTierVisibleAt(a.tier, tier)
   return {
     offered: archetypes.filter((a) => relevant(a) && inTier(a)),

package/app/utils/catalog.spec.ts

@@ -1,5 +1,7 @@
 import { describe, it, expect } from 'vitest'
+import { PIPELINE_PURPOSES, purposeAllowsAgentCategory } from '@cat-factory/contracts'
 import type { AgentKind, BlockStatus, BlockType } from '~/types/domain'
+import { narrowAgentPalette } from '~/utils/agentPalette'
 import {
   AGENT_ARCHETYPES,
   AGENT_BY_KIND,
@@ -85,6 +87,39 @@ describe('catalog', () => {
     expect(basic).toEqual(expect.arrayContaining(['architect', 'coder', 'tester-api']))
   })
 
+  it('leaves every purpose a palette to build from, and every declaration saveable', () => {
+    // Two properties over the whole grid rather than a pinned count, which every ordinary
+    // addition would break without naming anything.
+    //
+    // A `purposes` declaration only ever HIDES, so the way to get it wrong is to hide too much:
+    // a purpose whose palette reduces to nothing is a dial setting with no way forward, and the
+    // widest tier is where that has to be checked because the tier hint is the way out of a thin
+    // one. And relevance stays a subset of compatibility per KIND, so a declaration can never
+    // offer a step the save gate would then refuse.
+    for (const purpose of PIPELINE_PURPOSES) {
+      const offered = narrowAgentPalette(AGENT_ARCHETYPES, purpose, 'advanced').offered
+      expect(offered.length, `${purpose} offers no agent at all`).toBeGreaterThan(0)
+      for (const a of offered) {
+        expect(
+          !a.category || purposeAllowsAgentCategory(purpose, a.category),
+          `${a.kind} is offered to a ${purpose} pipeline its step could not be saved in`,
+        ).toBe(true)
+      }
+    }
+  })
+
+  it('never declares an EMPTY `purposes` (which reads as no declaration, not as "nowhere")', () => {
+    // `agentPresentationSchema` refuses an empty list at registration, but this catalog is
+    // authored in TypeScript and parsed by nothing, so the same guard has to be asserted for the
+    // half valibot never sees. Left empty, a kind someone meant to offer NOWHERE is offered
+    // everywhere its section is: `purposeSuggestsAgentKind` cannot tell an authored `[]` from a
+    // kind that declared nothing at all.
+    for (const a of [...AGENT_ARCHETYPES, ...Object.values(SYSTEM_AGENT_META)]) {
+      if (!a.purposes) continue
+      expect(a.purposes.length, `${a.kind} declares an empty purposes list`).toBeGreaterThan(0)
+    }
+  })
+
   it('never shadows a companion producer as a system kind', () => {
     // A companion is never placed directly: the builder renders it as a toggle on its producer
     // step, so a producer that cannot be placed takes its companion out of the builder with it.

package/app/utils/catalog.ts

@@ -35,6 +35,10 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-clipboard-check',
     color: '#f59e0b',
     category: 'review',
+    // Settles the PRODUCT layer before anyone builds, which is every use-case except reviewing
+    // someone else's open pull request: there the requirements are already someone's shipped
+    // decision and nothing here can change them.
+    purposes: ['build', 'document', 'research', 'planning'],
     description:
       'Reviews the collected context (description + linked PRDs/RFCs) for gaps, ambiguities, assumptions and risks before the architect starts.',
     // Opens the dedicated structured review window (answer/dismiss findings → incorporate
@@ -48,6 +52,8 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-bug',
     color: '#f59e0b',
     category: 'review',
+    // Triages a BUG REPORT for fixability, so it only makes sense where something gets fixed.
+    purposes: ['build'],
     description:
       'Triages a bug report for fixability — raising questions, gaps and assumptions about the report before anyone starts fixing it.',
     // Opens the dedicated structured review window (answer/dismiss findings → incorporate
@@ -65,6 +71,9 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-search-code',
     color: '#38bdf8',
     category: 'review',
+    // Traces a bug to its root cause in the code: a fixing pipeline's opening move, and nothing
+    // a document, review, spike or plan has any use for.
+    purposes: ['build'],
     description:
       'Read-only, multi-repo codebase investigation that traces the bug to its root cause and decides whether the report is fixable as-is or needs the reporter to clarify (no code changes).',
     resultView: 'generic-structured',
@@ -81,6 +90,9 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-clipboard-check',
     color: '#6366f1',
     category: 'review',
+    // Reviews an EXISTING open pull request, which is the whole of the review use-case, and is
+    // available to a build pipeline that wants a deep pass over the pull request it just opened.
+    purposes: ['build', 'review'],
     description:
       'Deep, token-bounded review of an open pull request: slices a large diff into cohesive ' +
       'chunks, reviews each, and returns prioritized findings.',
@@ -148,6 +160,8 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-clipboard-list',
     color: '#c084fc',
     category: 'design',
+    // Writes the in-repo spec the implementation is then built against.
+    purposes: ['build', 'planning'],
     description:
       "Aggregates every task's clarified requirements into the service's in-repo specification (spec.json) with full acceptance-scenario coverage, derived into Gherkin.",
   },
@@ -158,6 +172,9 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-drafting-compass',
     color: '#a78bfa',
     category: 'design',
+    // Designs the shape of a CODE change, so it belongs wherever code is planned or written and
+    // nowhere a document is being authored.
+    purposes: ['build', 'research', 'planning'],
     description: 'Designs the shape of the solution and breaks down the work.',
   },
   {
@@ -170,6 +187,8 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-map',
     color: '#22d3ee',
     category: 'design',
+    // Decomposes a repository into services and modules on the board.
+    purposes: ['build', 'planning'],
     description: 'Maps the repository into the service → modules blueprint.',
   },
   {
@@ -210,12 +229,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 +297,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',
@@ -305,6 +329,9 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-book-open-text',
     color: '#818cf8',
     category: 'docs',
+    // WRITES documentation into the repository, which a pipeline that reviews someone else's
+    // pull request never does.
+    purposes: ['build', 'document'],
     description: 'Produces docs and usage examples.',
   },
   {
@@ -314,6 +341,8 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-scroll-text',
     color: '#84cc16',
     category: 'docs',
+    // Writes domain-rule docs into the repository (see `documenter`).
+    purposes: ['build', 'document'],
     description:
       'Reads the implementation and writes/updates business-logic & domain-rule docs in the repo, weaving in linked context documents.',
   },
@@ -324,6 +353,9 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     icon: 'i-lucide-shield-alert',
     color: '#ef4444',
     category: 'docs',
+    // The review activity that groups under Documentation: it reads a change against the
+    // documented rules and reports violations, writing nothing.
+    purposes: ['build', 'review'],
     description:
       'Reviews a change against the documented domain rules and reports violations, undocumented changes and unexpected drift.',
   },

package/app/utils/pipeline.spec.ts

@@ -8,7 +8,9 @@ import {
   pipelineAllowedForTaskType,
   purposeAllowsAgentCategory,
   purposeSuggestsAgentCategory,
+  purposeSuggestsAgentKind,
 } from '@cat-factory/contracts'
+import type { PipelinePurpose } from '@cat-factory/contracts'
 import type { Block, Pipeline } from '~/types/domain'
 import {
   pipelineAllowedForManualStart,
@@ -216,6 +218,73 @@ describe('purposeSuggestsAgentCategory (builder palette filter)', () => {
   })
 })
 
+describe('purposeSuggestsAgentKind (what the palette actually filters on)', () => {
+  it('defers to the category for a kind that declares no purposes of its own', () => {
+    // The normal case, and the one that keeps a deployment-registered kind exactly as visible as
+    // it was before kinds could speak for themselves.
+    for (const purpose of [...PIPELINE_PURPOSES, UNKNOWN_PURPOSE]) {
+      for (const category of AGENT_CATEGORIES) {
+        expect(purposeSuggestsAgentKind(purpose, { category })).toBe(
+          purposeSuggestsAgentCategory(purpose, category),
+        )
+      }
+      expect(purposeSuggestsAgentKind(purpose, {})).toBe(true)
+    }
+  })
+
+  it('lets a kind narrow within a category its siblings still belong to', () => {
+    // What the category table structurally cannot say: `docs` survives a `review` pipeline so the
+    // Domain Rules Reviewer does, which also handed it the two kinds that WRITE documentation.
+    const author = { category: 'docs', purposes: ['build', 'document'] } as const
+    expect(purposeSuggestsAgentKind('document', author)).toBe(true)
+    expect(purposeSuggestsAgentKind('review', author)).toBe(false)
+    expect(purposeSuggestsAgentCategory('review', 'docs')).toBe(true)
+  })
+
+  it('is a declaration, not an exemption from the category', () => {
+    // A kind cannot buy its way back into a purpose its section is not offered to: `docs` is gone
+    // for `planning`, and the palette drops the kind whether or not it named `planning` itself.
+    const doc = { category: 'docs', purposes: ['planning'] } as const
+    expect(purposeSuggestsAgentKind('planning', doc)).toBe(
+      purposeSuggestsAgentCategory('planning', 'docs'),
+    )
+  })
+
+  it('reads a list naming nothing this build knows as no declaration at all', () => {
+    const stale = { category: 'docs', purposes: [UNKNOWN_PURPOSE] } as const
+    for (const purpose of PIPELINE_PURPOSES) {
+      expect(purposeSuggestsAgentKind(purpose, stale)).toBe(
+        purposeSuggestsAgentCategory(purpose, 'docs'),
+      )
+    }
+    // And a purpose this build cannot name still narrows nothing, declaration or not.
+    expect(
+      purposeSuggestsAgentKind(UNKNOWN_PURPOSE, { category: 'docs', purposes: ['build'] }),
+    ).toBe(true)
+  })
+
+  it('never offers what the save gate would refuse', () => {
+    // The same invariant the category predicate carries, restated where the palette now reads it:
+    // a kind's own declaration may only ever hide more, so it can never open a hole through which
+    // a kind is offered and its step then blocks the save.
+    for (const purpose of [...PIPELINE_PURPOSES, UNKNOWN_PURPOSE]) {
+      for (const category of AGENT_CATEGORIES) {
+        const declarations: (readonly PipelinePurpose[] | undefined)[] = [
+          undefined,
+          PIPELINE_PURPOSES,
+          ['build'],
+          [UNKNOWN_PURPOSE],
+        ]
+        for (const purposes of declarations) {
+          if (purposeSuggestsAgentKind(purpose, { category, purposes })) {
+            expect(purposeAllowsAgentCategory(purpose, category)).toBe(true)
+          }
+        }
+      }
+    }
+  })
+})
+
 describe('a purpose or category this build does not recognise', () => {
   it('is recognised as unknown rather than trusted', () => {
     for (const purpose of PIPELINE_PURPOSES) expect(isPipelinePurpose(purpose)).toBe(true)

package/i18n/locales/de.json

@@ -4293,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

@@ -4881,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

@@ -4732,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.",

package/i18n/locales/fr.json

@@ -4732,6 +4732,13 @@
       "binaryOutputPlaceholder": "Choisir un service de stockage",
       "binaryOutputContextPlaceholder": "Facultatif : services qui délimitent la génération",
       "binaryOutputNeedsPick": "Une étape qui génère des sorties binaires n'a aucun service de stockage choisi. Choisissez-en un avant d'enregistrer.",
+      "envNeedsDeployer": "Une étape Tester, de test manuel ou Playwright a besoin d'un Deployer avant elle. Ajoutez-en un, sinon le pipeline ne sera pas enregistré (il ne fait rien sur un service qui ne provisionne rien).",
+      "envNeedsDisposer": "Un Deployer a besoin d'un Disposer après lui pour libérer l'environnement qu'il provisionne. Ajoutez-en un, ou marquez le Deployer comme conservant son environnement au-delà de l'exécution, sinon le pipeline ne sera pas enregistré.",
+      "envDisposerNeedsDeployer": "Ce Disposer n'a aucun Deployer avant lui, il n'a donc rien à libérer. Ajoutez un Deployer ou retirez le Disposer.",
+      "envConsumerAfterDisposer": "Une étape Tester, de test manuel ou Playwright s'exécute après que le Disposer a déjà libéré l'environnement : il ne resterait rien pour l'exécuter. Déplacez le Disposer après cette étape, ou ajoutez un autre Deployer avant elle.",
+      "envRetainedButReclaimed": "Ce Deployer est marqué comme conservant son environnement au-delà de l'exécution, mais un Disposer placé après lui libère précisément cet environnement. Retirez le Disposer, ou désactivez la conservation de l'environnement.",
+      "retainEnvironmentSetTooltip": "Libéré à la fin de l'exécution. Cliquez pour laisser cet environnement actif ensuite (un aperçu que les relecteurs utilisent une fois la PR ouverte) ; son TTL ou un opérateur l'arrêtera.",
+      "retainEnvironmentClearTooltip": "Reste actif après la fin de l'exécution. Cliquez pour le libérer de nouveau via une étape Disposer.",
       "binaryOutputNoStorage": "Aucun service du catalogue de ce tableau ne déclare la capacité {capability}. Enregistrez-en un, ou ajoutez la capacité au service que vous visiez, dans les services fondamentaux.",
       "binaryOutputMissing": "Ce service de stockage n'est plus dans le catalogue ; choisissez-en un autre.",
       "binaryOutputNotStorage": "Ce service ne déclare plus la capacité {capability}, les exécutions seront donc refusées ; choisissez-en un autre.",

package/i18n/locales/he.json

@@ -4732,6 +4732,13 @@
       "binaryOutputPlaceholder": "בחר שירות אחסון",
       "binaryOutputContextPlaceholder": "לא חובה: שירותים שמגדירים את היקף היצירה",
       "binaryOutputNeedsPick": "לשלב שמייצר פלטים בינאריים לא נבחר שירות אחסון. בחר אחד לפני השמירה.",
+      "envNeedsDeployer": "שלב Tester, בדיקה ידנית או Playwright דורש Deployer לפניו. הוסף אחד, אחרת הצינור לא יישמר (בשירות שאינו מקצה סביבה הוא לא עושה דבר).",
+      "envNeedsDisposer": "אחרי Deployer נדרש Disposer שישחרר את הסביבה שהוקצתה. הוסף אחד, או סמן את ה-Deployer כשומר על הסביבה שלו גם אחרי הריצה, אחרת הצינור לא יישמר.",
+      "envDisposerNeedsDeployer": "לפני ה-Disposer הזה אין Deployer, ולכן אין מה לשחרר. הוסף Deployer או הסר את ה-Disposer.",
+      "envConsumerAfterDisposer": "שלב Tester, בדיקה ידנית או Playwright רץ אחרי שה-Disposer כבר שחרר את הסביבה, ולכן לא יישאר דבר להריץ מולו. העבר את ה-Disposer מתחת לשלב הזה, או הוסף Deployer נוסף לפניו.",
+      "envRetainedButReclaimed": "ה-Deployer הזה מסומן כשומר על הסביבה שלו גם אחרי הריצה, אך Disposer שאחריו משחרר בדיוק את אותה סביבה. הסר את ה-Disposer, או בטל את סימון שמירת הסביבה.",
+      "retainEnvironmentSetTooltip": "משוחררת בסוף הריצה. לחץ כדי להשאיר את הסביבה פעילה אחריה (תצוגה מקדימה שסוקרים משתמשים בה אחרי פתיחת ה-PR); ה-TTL או מפעיל יורידו אותה בהמשך.",
+      "retainEnvironmentClearTooltip": "נשארת פעילה אחרי סיום הריצה. לחץ כדי לחזור לשחרור שלה בשלב Disposer.",
       "binaryOutputNoStorage": "אף שירות בקטלוג של לוח זה אינו מצהיר על יכולת {capability}. רשום שירות כזה, או הוסף את היכולת לשירות שהתכוונת אליו, תחת שירותי בסיס.",
       "binaryOutputMissing": "שירות אחסון זה כבר אינו בקטלוג; בחר אחר.",
       "binaryOutputNotStorage": "השירות הזה כבר אינו מצהיר על יכולת {capability}, ולכן הרצות יידחו; בחר אחר.",

package/i18n/locales/it.json

@@ -4293,6 +4293,13 @@
       "binaryOutputPlaceholder": "Scegli un servizio di archiviazione",
       "binaryOutputContextPlaceholder": "Facoltativo: servizi che delimitano la generazione",
       "binaryOutputNeedsPick": "Un passo che genera output binari non ha un servizio di archiviazione scelto. Scegline uno prima di salvare.",
+      "envNeedsDeployer": "Un passaggio Tester, di test manuale o Playwright ha bisogno di un Deployer prima di sé. Aggiungine uno, altrimenti la pipeline non verrà salvata (su un servizio che non effettua provisioning non fa nulla).",
+      "envNeedsDisposer": "Un Deployer ha bisogno di un Disposer dopo di sé, che liberi l'ambiente creato. Aggiungine uno, oppure contrassegna il Deployer come tale da mantenere il proprio ambiente oltre l'esecuzione, altrimenti la pipeline non verrà salvata.",
+      "envDisposerNeedsDeployer": "Questo Disposer non ha alcun Deployer prima di sé, quindi non ha nulla da liberare. Aggiungi un Deployer oppure rimuovi il Disposer.",
+      "envConsumerAfterDisposer": "Un passaggio Tester, di test manuale o Playwright viene eseguito dopo che il Disposer ha già liberato l'ambiente, quindi non resterebbe nulla su cui eseguirlo. Sposta il Disposer dopo quel passaggio, oppure aggiungi un altro Deployer prima di esso.",
+      "envRetainedButReclaimed": "Questo Deployer è contrassegnato come tale da mantenere il proprio ambiente oltre l'esecuzione, ma un Disposer successivo libera proprio quell'ambiente. Rimuovi il Disposer, oppure togli il contrassegno di mantenimento dell'ambiente.",
+      "retainEnvironmentSetTooltip": "Liberato al termine dell'esecuzione. Fai clic per lasciare questo ambiente attivo dopo (un'anteprima che i revisori usano a PR aperta); lo spegneranno poi il suo TTL o un operatore.",
+      "retainEnvironmentClearTooltip": "Resta attivo dopo la fine dell'esecuzione. Fai clic per tornare a liberarlo con un passaggio Disposer.",
       "binaryOutputNoStorage": "Nessun servizio nel catalogo di questa board dichiara la capacità {capability}. Registrane uno, oppure aggiungi la capacità al servizio che intendevi, nei servizi fondamentali.",
       "binaryOutputMissing": "Questo servizio di archiviazione non è più nel catalogo; scegline un altro.",
       "binaryOutputNotStorage": "Questo servizio non dichiara più la capacità {capability}, quindi le esecuzioni verranno rifiutate; scegline un altro.",

package/i18n/locales/ja.json

@@ -4732,6 +4732,13 @@
       "binaryOutputPlaceholder": "保存サービスを選択",
       "binaryOutputContextPlaceholder": "任意: 生成の範囲を定めるサービス",
       "binaryOutputNeedsPick": "バイナリ成果物を生成するステップに保存サービスが選択されていません。保存前に選んでください。",
+      "envNeedsDeployer": "Tester、手動テスト、または Playwright のステップの前には Deployer が必要です。追加しないとパイプラインは保存できません（プロビジョニングしないサービスでは何もしません）。",
+      "envNeedsDisposer": "Deployer の後には、用意した環境を解放する Disposer が必要です。追加するか、Deployer に実行後も環境を残す設定を付けてください。どちらもない場合、パイプラインは保存できません。",
+      "envDisposerNeedsDeployer": "この Disposer の前に Deployer がないため、解放する対象がありません。Deployer を追加するか、Disposer を削除してください。",
+      "envConsumerAfterDisposer": "Tester、手動テスト、または Playwright のステップが、Disposer が環境を解放した後に実行されるため、実行対象が残りません。Disposer をそのステップより後ろに移すか、その前にもう一つ Deployer を追加してください。",
+      "envRetainedButReclaimed": "この Deployer には実行後も環境を残す設定が付いていますが、後続の Disposer がまさにその環境を解放します。Disposer を削除するか、環境を残す設定を解除してください。",
+      "retainEnvironmentSetTooltip": "実行の終了時に解放されます。クリックすると実行後も環境を残します（PR を開いた後にレビュアーが使うプレビュー用）。その後は TTL または運用者が停止します。",
+      "retainEnvironmentClearTooltip": "実行の終了後も環境を残します。クリックすると Disposer ステップで解放する動作に戻ります。",
       "binaryOutputNoStorage": "このボードのカタログに {capability} 機能を宣言するサービスがありません。基盤サービスで新たに登録するか、意図したサービスにこの機能を追加してください。",
       "binaryOutputMissing": "この保存サービスはカタログに存在しません。別のサービスを選んでください。",
       "binaryOutputNotStorage": "このサービスは {capability} 機能を宣言しなくなったため、実行は拒否されます。別のサービスを選んでください。",