@cat-factory/app 0.255.0 → 0.256.0

package/README.md

@@ -286,9 +286,13 @@ browser older than a new member, a row older than a retired one).
 Purpose is filtered by three predicates in `@cat-factory/contracts`, and the difference between
 the first two is the point:
 
-- `purposeSuggestsAgentCategory` is **relevance**: what the palette OFFERS. Opinionated (a
+- `purposeSuggestsAgentKind` is **relevance**: what the palette OFFERS. Opinionated (a
   review pipeline designs nothing; a planning pipeline has no pull request to gate), because a
-  wrong guess costs one purpose switch.
+  wrong guess costs one purpose switch. It reads the kind's `category` through
+  `purposeSuggestsAgentCategory` and then the kind's OWN `presentation.purposes`, and the two
+  INTERSECT: a declaration may only hide more, never buy a kind back into a purpose its section
+  is not offered to, which is what keeps relevance inside compatibility whatever a deployment
+  declares.
 - `purposeAllowsAgentCategory` is **compatibility**: what the builder will SAVE. It states only
   what is contradictory (a pipeline that writes no code carrying an implementation step) and
   drives the draft's conflict warning.
@@ -311,6 +315,19 @@ it that way: the palette may hide what the save gate tolerates, so tightening th
 never turns a stored pipeline into one its own editor refuses, but offering a kind the save gate
 then rejects would be a dead end with the refusal arriving after the work.
 
+**A category is a shelf label, not a statement of what a kind does**, which is why relevance is
+asked of the KIND. Keeping `docs` for a `review` pipeline so the Domain Rules Reviewer survives
+also handed it the two kinds that WRITE documentation into the repo, and `document` and `research`
+had identical rows, so moving the dial between them narrowed nothing at all. A kind that belongs
+to one use-case says so in `presentation.purposes` and leaves a section its siblings stay in; the
+section keeps deciding for every kind that declares nothing, which is the normal case and the one
+a deployment-registered kind falls into for free. Declare it only to opt OUT: it can never widen,
+and a list naming only purposes this build cannot name is read as no declaration at all rather
+than as excluding everything, the same default-open reading the unknown `purpose` gets. An EMPTY
+list is refused at registration instead (`agentPresentationSchema`, and `catalog.spec.ts` for the
+static half valibot never parses): the reader cannot tell one from declaring nothing, so it would
+offer the kind everywhere its section is offered, which is the inverse of what writing it means.
+
 **Each hint counts what relaxing THAT dial alone would reveal**, which is why each reduction is one
 function (`utils/agentPalette.ts` for the catalog, `utils/pipelineLibrary.ts` for the library)
 rather than chained filters at the call site. Chaining them

package/app/components/pipeline/PipelineBuilder.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { computed, ref, watch } from 'vue'
-import { purposeAllowsAgentCategory } from '@cat-factory/contracts'
+import { DEPLOYER_AGENT_KIND } from '@cat-factory/contracts'
 import type { AgentKind, Pipeline } from '~/types/domain'
 import AgentPalette from '~/components/palettes/AgentPalette.vue'
 import AgentKindIcon from '~/components/pipeline/AgentKindIcon.vue'
@@ -189,31 +189,6 @@ const skills = useSkillsStore()
 // skill picker. A `skill` step is parametrized by the picked skill (`stepOptions.skillId`).
 const skillSelectItems = computed(() => skills.catalog.map((s) => ({ label: s.name, value: s.id })))
 
-// An enabled `skill` step with no picked skill — mirrors the backend save/start rejection
-// (`assertValidSkillSteps`), surfaced as an inline hint so the user fixes it before saving.
-const skillStepNeedsPick = computed(() =>
-  pipelines.draft.some(
-    (k, i) => k === 'skill' && pipelines.draftEnabled[i] !== false && !pipelines.draftSkillId(i),
-  ),
-)
-
-// Steps whose agent category the chosen purpose CONTRADICTS (a non-`build` purpose writes no code
-// and runs no tests, so the Implementation/Testing categories are disallowed, see
-// `purposeAllowsAgentCategory`). Only reachable by switching an existing draft to a non-`build`
-// purpose AFTER such steps were added, since the palette offers neither. The backend has no
-// kind→category map to gate on, so the builder is the enforcement point: save is blocked until the
-// offending steps are removed (or the purpose set back to Build).
-//
-// Deliberately the compatibility predicate, not the palette's narrower relevance one: a purpose
-// that merely stops SUGGESTING a category must not turn a pipeline somebody already built into
-// one they cannot save.
-const stepsDisallowedByPurpose = computed(() =>
-  pipelines.draft.filter((kind) => {
-    const category = agentKindMeta(kind).category
-    return !!category && !purposeAllowsAgentCategory(pipelines.draftPurpose, category)
-  }),
-)
-
 // The workspace's foundational-services catalog, for the binary-output storage/context picker.
 const foundational = useFoundationalServicesStore()
 
@@ -231,18 +206,22 @@ function showBinaryOutputPicker(kind: AgentKind): boolean {
   return agentKindMeta(kind).binaryOutput === true
 }
 
-// An enabled generator step with no storage selection — mirrors the backend save/start
-// rejection (`assertValidBinaryOutputSteps`), surfaced as an inline hint so the user fixes it
-// before the round trip. Same disposition as `skillStepNeedsPick`, for the same reason: both
-// are a step parametrized by a selection it cannot run without.
-const binaryOutputStepNeedsPick = computed(() =>
-  pipelines.draft.some(
-    (kind, i) =>
-      showBinaryOutputPicker(kind) &&
-      pipelines.draftEnabled[i] !== false &&
-      !pipelines.draftBinaryOutput(i)?.storageServiceId,
-  ),
-)
+/**
+ * Whether to offer the Deployer's "keep this environment past the run" declaration on the step at
+ * `index`. An OVERRIDE in the `showOverrideField` sense — reclaiming what a run stood up is the
+ * default and the everyday shape, and a deliberately retained preview environment is not the
+ * everyday delivery loop — so it is `advanced`-tier, and a step that already CARRIES the
+ * declaration keeps showing it in either mode (never hide the way back).
+ *
+ * Hiding it strands nobody: the fault it answers (`deployer_without_disposer`) always has the
+ * tier-neutral fix of adding the Disposer back, which both the inline hint and the save refusal
+ * name FIRST. That is what makes this different from the binary-output picker above, where the
+ * selection is required and hiding it would leave a step with no savable form at all.
+ */
+function showRetainEnvironmentToggle(kind: AgentKind, index: number): boolean {
+  if (kind !== DEPLOYER_AGENT_KIND) return false
+  return showOverrideField(uiMode.isAdvanced, pipelines.draftRetainEnvironment(index) || null)
+}
 
 // A step's picked skill id is no longer in the account catalog (the source dir was renamed or
 // unlinked). The step will fail cleanly at dispatch; flag it so the user re-picks.
@@ -370,22 +349,12 @@ function companionLabel(kind: string): string | null {
   return companion ? agentKindMeta(companion).label : null
 }
 
-// Surfaced as an inline hint: a gated step needs a task-estimator before it (mirrors the
-// backend validation, which also rejects the save/start). Both the companion estimate gate
-// (`draftGating`) and the Tester QC companion's estimate gate (`draftTesterQuality[i].gating`)
-// count — either without a preceding estimator is rejected on save.
-const gatingNeedsEstimator = computed(() => {
-  const kinds = pipelines.draft
-  const hasEstimatorBefore = (i: number) =>
-    kinds.slice(0, i).some((k, j) => k === 'task-estimator' && pipelines.draftEnabled[j] !== false)
-  for (let i = 0; i < kinds.length; i++) {
-    if (pipelines.draftEnabled[i] === false) continue
-    const gated =
-      pipelines.draftGating[i]?.enabled || pipelines.draftTesterQuality[i]?.gating?.enabled
-    if (gated && !hasEstimatorBefore(i)) return true
-  }
-  return false
-})
+// Everything that is WRONG with the draft, as an ordered list of hints the template renders once,
+// plus the purpose conflict that also disables Save. Lives in its own composable because each of
+// these is one predicate beside one identically-styled line, and five of them had crowded out the
+// component (`usePipelineDraftWarnings`).
+const { hints: draftWarnings, stepsDisallowedByPurpose } =
+  usePipelineDraftWarnings(showBinaryOutputPicker)
 
 // ---- draft labels ----------------------------------------------------------
 const newLabel = ref('')
@@ -563,37 +532,16 @@ async function clone(p: Pipeline) {
             />
           </div>
 
+          <!-- Every draft fault the builder can name, each mirroring a refusal the save boundary
+             makes, so the user fixes it before the round trip (`usePipelineDraftWarnings`). -->
           <p
-            v-if="gatingNeedsEstimator"
-            class="mb-2 flex items-center gap-1.5 rounded-md border border-amber-800/50 bg-amber-950/30 px-2 py-1 text-[11px] text-amber-300"
-          >
-            <UIcon name="i-lucide-alert-triangle" class="h-3.5 w-3.5 shrink-0" />
-            {{ t('pipeline.builder.gatingNeedsEstimator') }}
-          </p>
-
-          <p
-            v-if="skillStepNeedsPick"
+            v-for="warning in draftWarnings"
+            :key="warning.key"
             class="mb-2 flex items-center gap-1.5 rounded-md border border-amber-800/50 bg-amber-950/30 px-2 py-1 text-[11px] text-amber-300"
+            :data-testid="warning.testId"
           >
             <UIcon name="i-lucide-alert-triangle" class="h-3.5 w-3.5 shrink-0" />
-            {{ t('pipeline.builder.skillNeedsPick') }}
-          </p>
-
-          <p
-            v-if="binaryOutputStepNeedsPick"
-            class="mb-2 flex items-center gap-1.5 rounded-md border border-amber-800/50 bg-amber-950/30 px-2 py-1 text-[11px] text-amber-300"
-            data-testid="binary-output-needs-pick"
-          >
-            <UIcon name="i-lucide-alert-triangle" class="h-3.5 w-3.5 shrink-0" />
-            {{ t('pipeline.builder.binaryOutputNeedsPick') }}
-          </p>
-
-          <p
-            v-if="stepsDisallowedByPurpose.length"
-            class="mb-2 flex items-center gap-1.5 rounded-md border border-amber-800/50 bg-amber-950/30 px-2 py-1 text-[11px] text-amber-300"
-          >
-            <UIcon name="i-lucide-alert-triangle" class="h-3.5 w-3.5 shrink-0" />
-            {{ t('pipeline.builder.purposeStepsConflict') }}
+            {{ t(warning.key) }}
           </p>
 
           <div
@@ -766,6 +714,27 @@ async function clone(p: Pipeline) {
                     "
                     @click="pipelines.toggleDraftAutoRecommend(unit.index)"
                   />
+                  <!-- Keep the environment this Deployer stands up past the end of the run: the
+                     preview a reviewer pokes at after the PR is open. Off by default, and the
+                     save boundary refuses a Deployer that neither reclaims nor declares this,
+                     so the tick is how an unreclaimed environment says it is deliberate. -->
+                  <UButton
+                    v-if="showRetainEnvironmentToggle(unit.kind, unit.index)"
+                    :icon="
+                      pipelines.draftRetainEnvironment(unit.index)
+                        ? 'i-lucide-lock'
+                        : 'i-lucide-cloud-off'
+                    "
+                    :color="pipelines.draftRetainEnvironment(unit.index) ? 'warning' : 'neutral'"
+                    variant="ghost"
+                    size="xs"
+                    :title="
+                      pipelines.draftRetainEnvironment(unit.index)
+                        ? t('pipeline.builder.retainEnvironmentClearTooltip')
+                        : t('pipeline.builder.retainEnvironmentSetTooltip')
+                    "
+                    @click="pipelines.toggleDraftRetainEnvironment(unit.index)"
+                  />
                   <!-- System prompt: replace what this agent kind ships with, for every run in
                      this workspace, with the full revision history to switch back through. -->
                   <UButton

package/app/composables/usePipelineDraftWarnings.ts

@@ -0,0 +1,136 @@
+import { computed, type ComputedRef } from 'vue'
+import {
+  pipelineEnvironmentProblems,
+  purposeAllowsAgentCategory,
+  type PipelineEnvironmentProblemReason,
+} from '@cat-factory/contracts'
+import type { AgentKind } from '~/types/domain'
+import { agentKindMeta } from '~/utils/catalog'
+import { usePipelinesStore } from '~/stores/pipelines'
+
+/**
+ * Everything the pipeline builder can say is WRONG with the draft in front of it, as an ordered
+ * list of translation keys, plus the one finding that also blocks the save.
+ *
+ * Extracted from `PipelineBuilder.vue` because these grew into one concern wearing five copies of
+ * the same coat: each was a `computed` predicate beside a `<p>` with byte-identical classes, so
+ * every new rule cost another near-duplicate pair in a component that had run out of room for
+ * them. Here they are a list the template renders once.
+ *
+ * Every entry MIRRORS a refusal the backend already makes at save (or, for the purpose conflict,
+ * one only the builder can make, since the backend has no kind→category map). The point is to
+ * surface it before the round trip, never to be the sole enforcement: a hint that disagrees with
+ * the boundary would let an unsavable draft look clean, so each is derived from the same shared
+ * rule the boundary runs rather than from a hand-written restatement of it.
+ */
+export interface PipelineDraftWarnings {
+  /** One entry per distinct finding, in the order the builder shows them. */
+  hints: ComputedRef<PipelineDraftHint[]>
+  /**
+   * The draft steps whose agent category the chosen purpose CONTRADICTS. Exposed as the list
+   * rather than folded into {@link hints} alone because it is the one finding that also disables
+   * the Save button: the builder is the enforcement point, so an empty list is a precondition.
+   */
+  stepsDisallowedByPurpose: ComputedRef<AgentKind[]>
+}
+
+/** One rendered warning: its i18n key, plus the test id where a spec asserts on it. */
+export interface PipelineDraftHint {
+  key: string
+  testId?: string
+}
+
+/**
+ * The environment-lifecycle faults, mapped onto the copy that names the fix for each. An
+ * exhaustive `Record` over the reason union, so a fault added to the shared rule fails the build
+ * here rather than rendering as a blank hint.
+ */
+const ENVIRONMENT_HINT_KEYS: Record<PipelineEnvironmentProblemReason, string> = {
+  consumer_without_deployer: 'pipeline.builder.envNeedsDeployer',
+  consumer_after_disposer: 'pipeline.builder.envConsumerAfterDisposer',
+  deployer_without_disposer: 'pipeline.builder.envNeedsDisposer',
+  disposer_without_deployer: 'pipeline.builder.envDisposerNeedsDeployer',
+  retained_deployer_reclaimed: 'pipeline.builder.envRetainedButReclaimed',
+}
+
+export function usePipelineDraftWarnings(
+  showBinaryOutputPicker: (kind: AgentKind) => boolean,
+): PipelineDraftWarnings {
+  const pipelines = usePipelinesStore()
+
+  const enabled = (i: number) => pipelines.draftEnabled[i] !== false
+
+  // A gated step with no task-estimator before it (mirrors `assertValidGating`, which rejects the
+  // save and the start). Both the step's own estimate gate (`draftGating`) and the Tester QC
+  // companion's (`draftTesterQuality[i].gating`) count.
+  const gatingNeedsEstimator = computed(() => {
+    const kinds = pipelines.draft
+    const hasEstimatorBefore = (i: number) =>
+      kinds.slice(0, i).some((k, j) => k === 'task-estimator' && enabled(j))
+    return kinds.some((_, i) => {
+      if (!enabled(i)) return false
+      const gated =
+        pipelines.draftGating[i]?.enabled || pipelines.draftTesterQuality[i]?.gating?.enabled
+      return !!gated && !hasEstimatorBefore(i)
+    })
+  })
+
+  // The environment lifecycle a draft has to spell out: provision (Deployer) → consume (a tester /
+  // acceptance / human-test step) → reclaim (Disposer, or a Deployer that declares its environment
+  // outlives the run). One message per DISTINCT fault, so a draft missing both a Deployer and a
+  // Disposer says so at once instead of over two rejected saves.
+  const environmentHintKeys = computed(() => {
+    const problems = pipelineEnvironmentProblems(
+      pipelines.draft,
+      pipelines.draftEnabled,
+      pipelines.draftStepOptions,
+    )
+    return [...new Set(problems.map((p) => ENVIRONMENT_HINT_KEYS[p.reason]))]
+  })
+
+  // An enabled `skill` step with no picked skill (mirrors `assertValidSkillSteps`).
+  const skillStepNeedsPick = computed(() =>
+    pipelines.draft.some((k, i) => k === 'skill' && enabled(i) && !pipelines.draftSkillId(i)),
+  )
+
+  // An enabled generator step with no storage selection (mirrors `assertValidBinaryOutputSteps`).
+  // Same disposition as `skillStepNeedsPick`: both are a step parametrized by a selection it
+  // cannot run without.
+  const binaryOutputStepNeedsPick = computed(() =>
+    pipelines.draft.some(
+      (kind, i) =>
+        showBinaryOutputPicker(kind) &&
+        enabled(i) &&
+        !pipelines.draftBinaryOutput(i)?.storageServiceId,
+    ),
+  )
+
+  // Steps whose agent category the chosen purpose CONTRADICTS (a non-`build` purpose writes no
+  // code and runs no tests, so the Implementation/Testing categories are disallowed). Only
+  // reachable by switching an existing draft to a non-`build` purpose AFTER such steps were added,
+  // since the palette offers neither.
+  //
+  // Deliberately the COMPATIBILITY predicate, not the palette's narrower relevance one: a purpose
+  // that merely stops SUGGESTING a category must not turn a pipeline somebody already built into
+  // one they cannot save.
+  const stepsDisallowedByPurpose = computed(() =>
+    pipelines.draft.filter((kind) => {
+      const category = agentKindMeta(kind).category
+      return !!category && !purposeAllowsAgentCategory(pipelines.draftPurpose, category)
+    }),
+  )
+
+  const hints = computed<PipelineDraftHint[]>(() => [
+    ...(gatingNeedsEstimator.value ? [{ key: 'pipeline.builder.gatingNeedsEstimator' }] : []),
+    ...environmentHintKeys.value.map((key) => ({ key, testId: 'env-lifecycle-hint' })),
+    ...(skillStepNeedsPick.value ? [{ key: 'pipeline.builder.skillNeedsPick' }] : []),
+    ...(binaryOutputStepNeedsPick.value
+      ? [{ key: 'pipeline.builder.binaryOutputNeedsPick', testId: 'binary-output-needs-pick' }]
+      : []),
+    ...(stepsDisallowedByPurpose.value.length
+      ? [{ key: 'pipeline.builder.purposeStepsConflict' }]
+      : []),
+  ])
+
+  return { hints, stepsDisallowedByPurpose }
+}

package/app/modular/agent-kinds.ts

@@ -27,6 +27,9 @@ export function customKindToArchetype(kind: CustomAgentKind): AgentArchetype {
     color: p.color,
     description: p.description,
     ...(p.category ? { category: p.category } : {}),
+    // Carried verbatim, INCLUDING a list this build cannot fully name: `purposeSuggestsAgentKind`
+    // owns the reading of an unrecognised member, so filtering here would fork that rule.
+    ...(p.purposes?.length ? { purposes: p.purposes } : {}),
     // A kind that declares no tier is left WITHOUT one rather than stamped with the default
     // here, so the single fallback stays in `agentTierVisibleAt` — filling it in at the
     // projection would fork the rule the moment the default changes.

package/app/modular/capabilities.spec.ts

@@ -70,6 +70,55 @@ describe('buildWorkspaceCapabilitiesManifest', () => {
     expect(workspaceCapabilitiesVersion([], [])).not.toBe(base)
   })
 
+  it('changes the version for EVERY declared field, including the ones nothing renders', () => {
+    // The signature covers the whole entry rather than a list of fields somebody kept in step,
+    // because an omitted one is not a cosmetic miss: `hydrateCapabilities` no-ops on an unchanged
+    // version, so an open tab keeps filtering its palette on the declaration the backend just
+    // replaced. Asserted field by field over the ones that steer the builder rather than the
+    // label, which is the class the old field list kept missing.
+    const base = workspaceCapabilitiesVersion([kind()], [])
+    expect(workspaceCapabilitiesVersion([kind({ purposes: ['review'] })], [])).not.toBe(base)
+    expect(workspaceCapabilitiesVersion([kind({ category: 'docs' })], [])).not.toBe(base)
+    expect(workspaceCapabilitiesVersion([kind({ tier: 'basic' })], [])).not.toBe(base)
+    expect(workspaceCapabilitiesVersion([{ ...kind(), container: false }], [])).not.toBe(base)
+    expect(workspaceCapabilitiesVersion([{ ...kind(), binaryOutput: true }], [])).not.toBe(base)
+    expect(
+      workspaceCapabilitiesVersion([{ ...kind(), companionTargets: ['coder' as AgentKind] }], []),
+    ).not.toBe(base)
+    // And a purposes list is ORDER-bearing content, not a set: two spellings of the same
+    // declaration are two declarations, so re-signing is the honest answer over guessing.
+    expect(workspaceCapabilitiesVersion([kind({ purposes: ['review', 'build'] })], [])).not.toBe(
+      workspaceCapabilitiesVersion([kind({ purposes: ['build', 'review'] })], []),
+    )
+  })
+
+  it('ignores the KEY ORDER a snapshot happened to serialize with', () => {
+    // The whole point of canonicalizing rather than hashing the raw JSON: a re-serialization
+    // that reorders keys is the same catalog, and re-swapping the manifest for it would
+    // invalidate every `agentKindMeta` consumer for nothing.
+    const ordered: CustomAgentKind = {
+      kind: 'acme-audit' as AgentKind,
+      container: true,
+      presentation: { label: 'Audit', icon: 'i-lucide-shield', color: '#fff', description: 'd' },
+    }
+    const reordered: CustomAgentKind = {
+      presentation: { description: 'd', color: '#fff', icon: 'i-lucide-shield', label: 'Audit' },
+      container: true,
+      kind: 'acme-audit' as AgentKind,
+    }
+    expect(workspaceCapabilitiesVersion([reordered], [])).toBe(
+      workspaceCapabilitiesVersion([ordered], []),
+    )
+  })
+
+  it('reads an explicitly-undefined field as an absent one', () => {
+    // A projection that spreads a conditional field (`...(x ? { x } : {})`) and one that assigns
+    // `x: undefined` describe the same catalog, so they must not hash differently.
+    expect(workspaceCapabilitiesVersion([{ ...kind(), binaryOutput: undefined }], [])).toBe(
+      workspaceCapabilitiesVersion([kind()], []),
+    )
+  })
+
   it('changes the version when a task-type field, its fields, or the set differs', () => {
     const base = workspaceCapabilitiesVersion([], [taskType()])
     expect(workspaceCapabilitiesVersion([], [taskType({ label: 'Renamed' })])).not.toBe(base)

package/app/modular/capabilities.ts

@@ -19,43 +19,46 @@ import type { AppSlots } from './slots'
 /** The stable id for the per-workspace capability manifest built from the snapshot. */
 export const WORKSPACE_CAPABILITIES_MANIFEST_ID = 'cat-factory:workspace-capabilities'
 
+/**
+ * Every key of `value`, recursively, in sorted order: the canonical form
+ * {@link workspaceCapabilitiesVersion} signs. Arrays keep their order (a capability list's order is
+ * content: it is the order the palette and the picker render in); objects lose theirs, so a
+ * re-serialization with reordered keys can't spuriously differ.
+ */
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalize)
+  if (value === null || typeof value !== 'object') return value
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([, entry]) => entry !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([key, entry]) => [key, canonicalize(entry)]),
+  )
+}
+
 /**
  * A deterministic, key-order-independent content signature covering BOTH capability lists, used as
  * the manifest `version`. The workspace snapshot re-delivers the SAME deployment capabilities on
  * every board-event refresh (a full `workspace.refresh()` re-hydrates each time), so a
- * content-derived version lets each store skip re-projecting an UNCHANGED catalog — otherwise every
+ * content-derived version lets each store skip re-projecting an UNCHANGED catalog: otherwise every
  * refresh would replace its read-model and needlessly invalidate every `agentKindMeta` /
  * `taskTypeMeta` consumer. It still changes (and swaps wholesale) when a different workspace's
- * capabilities genuinely differ. Serialized as fixed-order tuples of only the fields that affect
- * display/pairing, so a re-serialization with reordered object keys can't spuriously differ.
+ * capabilities genuinely differ.
+ *
+ * Signs the WHOLE entry, canonicalized, rather than a hand-listed tuple of the fields that seemed
+ * to matter. The two mistakes are not symmetric: folding in a field nothing renders costs one
+ * re-projection nobody sees, while OMITTING one costs correctness, because `hydrateCapabilities`
+ * short-circuits on an unchanged version and the store then keeps serving the PREVIOUS declaration
+ * until something else swaps the manifest. A field list drifts silently into that: it was missing
+ * `tier` and `binaryOutput` before `purposes` was added to it, so a backend that re-declared any of
+ * the three reached an open tab as the catalog it had replaced. There is nothing volatile in either
+ * shape (no timestamps, no ids minted per request), so signing all of it costs nothing.
  */
 export function workspaceCapabilitiesVersion(
   kinds: readonly CustomAgentKind[],
   taskTypes: readonly CustomTaskType[],
 ): string {
-  return JSON.stringify([
-    kinds.map((k) => [
-      k.kind,
-      k.container,
-      k.presentation.label,
-      k.presentation.icon,
-      k.presentation.color,
-      k.presentation.description,
-      k.presentation.category ?? null,
-      k.presentation.resultView ?? null,
-    ]),
-    taskTypes.map((t) => [
-      t.taskType,
-      t.presentation.label,
-      t.presentation.icon,
-      t.presentation.color,
-      t.presentation.description,
-      t.defaultPipelineId ?? null,
-      t.formPanel ?? null,
-      // The descriptor list affects the create-form, so fold its shape into the signature too.
-      (t.fields ?? []).map((f) => [f.key, f.type, f.label, f.required ?? false]),
-    ]),
-  ])
+  return JSON.stringify([canonicalize(kinds), canonicalize(taskTypes)])
 }
 
 /**

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

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest'
+import { pipelineEnvironmentProblems } from '@cat-factory/contracts'
+import { usePipelinesStore } from '~/stores/pipelines'
+
+/**
+ * The pipeline-builder draft's retain declaration (`stepOptions.retainEnvironment`): how an author
+ * says a Deployer's environment is MEANT to outlive the run, which is the only savable form of
+ * "deploy a preview and leave it up" (the reclaim rule refuses a Deployer that neither reclaims
+ * nor declares this). Same contract as the option helpers beside it: merge into the bag, normalize
+ * an emptied bag back to null.
+ */
+describe('pipelines store — per-step retain-environment declaration', () => {
+  it('stores only the opt-in, and normalizes the bag away when it is cleared', () => {
+    const pipelines = usePipelinesStore()
+    pipelines.addToDraft('deployer')
+    // OFF by default, and stored as ABSENCE rather than `false`: reclaiming is the default, so a
+    // step that never touched this persists exactly the shape it always did.
+    expect(pipelines.draftRetainEnvironment(0)).toBe(false)
+    expect(pipelines.draftStepOptions[0]).toBeNull()
+
+    pipelines.toggleDraftRetainEnvironment(0)
+    expect(pipelines.draftRetainEnvironment(0)).toBe(true)
+    expect(pipelines.draftStepOptions[0]).toEqual({ retainEnvironment: true })
+
+    pipelines.toggleDraftRetainEnvironment(0)
+    expect(pipelines.draftRetainEnvironment(0)).toBe(false)
+    expect(pipelines.draftStepOptions[0]).toBeNull()
+  })
+
+  it('merges with the other options on the same step rather than clobbering them', () => {
+    const pipelines = usePipelinesStore()
+    pipelines.addToDraft('deployer')
+    pipelines.setDraftAgentVariantId(0, 'acme:fast')
+
+    pipelines.toggleDraftRetainEnvironment(0)
+    expect(pipelines.draftStepOptions[0]).toEqual({
+      agentVariantId: 'acme:fast',
+      retainEnvironment: true,
+    })
+
+    pipelines.toggleDraftRetainEnvironment(0)
+    expect(pipelines.draftStepOptions[0]).toEqual({ agentVariantId: 'acme:fast' })
+  })
+
+  it('turns a draft the save boundary refuses into one it accepts', () => {
+    // The point of the whole field, asserted against the SAME rule the backend refuses on rather
+    // than against a restatement of it: without the declaration this draft has no savable form,
+    // since dropping the Deployer instead just moves the fault onto the tester.
+    const pipelines = usePipelinesStore()
+    for (const kind of ['coder', 'deployer', 'human-test'] as const) pipelines.addToDraft(kind)
+    const problems = () =>
+      pipelineEnvironmentProblems(
+        pipelines.draft,
+        pipelines.draftEnabled,
+        pipelines.draftStepOptions,
+      ).map((p) => p.reason)
+
+    expect(problems()).toEqual(['deployer_without_disposer'])
+    pipelines.toggleDraftRetainEnvironment(1)
+    expect(problems()).toEqual([])
+  })
+})