@cat-factory/app 0.254.3 → 0.255.1

package/README.md

@@ -271,12 +271,20 @@ The builder's palette narrows on two axes, and both controls sit on one row abov
 (`PipelinePurposeSelect` above `AgentTierSelect`), each with its own "n hidden" hint so neither
 narrowing reads as an empty catalog. The tier says how deep to look; the **purpose** says what
 the pipeline is for (`build` / `document` / `review` / `research` / `planning`), and the palette
-drops the categories that purpose has no use for. The purpose is not a view preference: it is
+drops the categories that purpose has no use for. It reaches past the palette: the saved-pipeline
+library in the builder's third column lists the pipelines built for the purpose being edited, so
+one dial narrows both ends of the slideover. The purpose is not a view preference either: it is
 saved on the pipeline and also decides which task pickers offer it, which is why the control
 writes through to the draft while the tier writes to its own store.
 
-Purpose is filtered by two predicates in `@cat-factory/contracts`, and the difference between
-them is the point:
+`Pipeline.purpose` is MANDATORY, so there is no unclassified state for any of these surfaces to
+invent a policy for: a new draft starts at `build` (what an unclassified pipeline always behaved
+as) and the dial only moves it. What each surface still has to read carefully is a purpose the
+BUNDLE cannot name, which the persisted, closed vocabulary makes reachable in both directions (a
+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
   review pipeline designs nothing; a planning pipeline has no pull request to gate), because a
@@ -284,14 +292,28 @@ them is the point:
 - `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.
+- `pipelineMatchesPurpose` is **membership**: which SAVED pipelines the builder's library lists,
+  reduced with the label and archive dials in `utils/pipelineLibrary.ts`. The one dial in that
+  column whose control is elsewhere, so it is the one that owes a "n hidden" hint. It may be
+  exact where the pickers' `pipelineAllowedForTaskType` is permissive, because it narrows a list
+  somebody is BROWSING rather than one they are about to run from: two known purposes never mix,
+  while a pipeline whose classifier this build cannot NAME is listed at every purpose rather than
+  vanishing from the editor that has to fix it.
+
+The library's purpose is a BROWSING dial of its own, defaulting to the draft's and relaxed by the
+hint itself ("show every purpose"). Reading the draft directly is the trap: it is an authoring
+field with no "off" setting, so a hint that only NAMES the absence would send the reader to a
+control whose every setting narrows and whose every change is saved. A dial that hides rows owes
+both a count and a way back, and the way back may not be an edit.
 
 Relevance is a subset of compatibility, asserted over the whole grid in `pipeline.spec.ts`. Keep
 it that way: the palette may hide what the save gate tolerates, so tightening the relevance table
 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.
 
-**Each hint counts what relaxing THAT dial alone would reveal**, which is why the reduction is one
-function (`utils/agentPalette.ts`) rather than two chained filters at the call site. Chaining them
+**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
 and subtracting the lengths gives the second dial an honest count and hands the first one the whole
 rest of the catalog: at the default `basic` tier a `planning` pipeline claimed thirteen kinds hidden
 for its purpose when switching back to Build revealed three, the other ten being tier-hidden either

package/app/components/palettes/AgentPalette.vue

@@ -17,8 +17,9 @@ defineEmits<{
 }>()
 // The purpose of the pipeline being built, edited right here by the control above the catalog.
 // It narrows the palette to the categories that purpose has any use for (a review pipeline
-// designs nothing and builds nothing, see `purposeSuggestsAgentCategory`); `null` shows all.
-const props = defineProps<{ purpose?: PipelinePurpose | null }>()
+// designs nothing and builds nothing, see `purposeSuggestsAgentCategory`). Required, like the
+// field it edits: a draft is classified from the moment it exists.
+const props = defineProps<{ purpose: PipelinePurpose }>()
 
 // The post-release-health gate is only meaningful — and only accepted by the backend —
 // with an observability integration connected, so it appears in the palette ONLY then.

package/app/components/palettes/PipelinePurposeSelect.vue

@@ -13,8 +13,8 @@ import { isPipelinePurpose, PIPELINE_PURPOSES, type PipelinePurpose } from '@cat
 const { t } = useI18n()
 
 const props = defineProps<{
-  /** The draft's purpose. `null` = unclassified, which narrows nothing. */
-  purpose?: PipelinePurpose | null
+  /** The draft's purpose. Required: every pipeline carries one, the builder's default being `build`. */
+  purpose: PipelinePurpose
   /** How many agent kinds the current purpose hides. Renders the "n hidden" hint when > 0. */
   hiddenCount?: number
 }>()
@@ -31,19 +31,15 @@ const PURPOSE_LABELS = computed<Record<PipelinePurpose, string>>(() => ({
   planning: t('pipeline.builder.purposeOption.planning'),
 }))
 
-// The button text: the chosen purpose, or the placeholder while the draft carries none. An
-// unclassified draft reads as an unmade choice rather than as a purpose called "none", because
-// that is what it is: nothing is filtered until one is picked.
-//
-// A stored purpose this build has no label for is NAMED as unrecognised and quoted back, not
-// folded into the placeholder and not left to render as an empty string after the colon. It is
-// the one state the user cannot diagnose from the control: the palette is unfiltered (see
-// `purposeSuggestsAgentCategory`), so a blank label would read as a pipeline nobody classified
-// while the saved row says otherwise. The menu still lists every current member, so naming the
-// value is also the way out of it.
+// The button text. A stored purpose this build has no label for is NAMED as unrecognised and
+// quoted back, rather than left to render as an empty string after the colon: it is the one state
+// the user cannot diagnose from the control, because a purpose this bundle cannot name narrows
+// nothing (see `purposeSuggestsAgentCategory`), so a blank label would read as a pipeline nobody
+// classified while the saved row says otherwise. The menu still lists every member this build has,
+// so naming the value is also the way out of it. Reachable even though the field is mandatory: the
+// value is persisted and this bundle can be older than the member it reads.
 const current = computed(() => {
   const purpose = props.purpose
-  if (!purpose) return t('pipeline.builder.purposePlaceholder')
   if (!isPipelinePurpose(purpose)) return t('pipeline.builder.purposeUnrecognized', { purpose })
   return PURPOSE_LABELS.value[purpose]
 })

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'
@@ -11,6 +11,7 @@ import OutputBudgetInput from '~/components/pipeline/OutputBudgetInput.vue'
 import BinaryOutputStepPicker from '~/components/pipeline/BinaryOutputStepPicker.vue'
 import { ESTIMATE_AXES, ESTIMATE_AXIS_FIELD, type EstimateAxis } from '~/utils/estimateGating'
 import { showOverrideField } from '~/utils/uiMode'
+import { narrowPipelineLibrary } from '~/utils/pipelineLibrary'
 import {
   agentKindMeta,
   companionForProducer,
@@ -188,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()
 
@@ -230,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.
@@ -369,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('')
@@ -403,14 +373,26 @@ const showArchived = ref(false)
 const allLabels = computed(() =>
   [...new Set(pipelines.pipelines.flatMap((p) => p.labels ?? []))].sort(),
 )
-const archivedCount = computed(() => pipelines.pipelines.filter((p) => p.archived).length)
-const visiblePipelines = computed(() =>
-  pipelines.pipelines.filter((p) => {
-    if (!showArchived.value && p.archived) return false
-    if (labelFilter.value && !(p.labels ?? []).includes(labelFilter.value)) return false
-    return true
+// The library is narrowed by the same purpose the palette is: browsing at `review` lists the
+// pipelines built for reviewing, not the whole workspace catalog. `narrowPipelineLibrary` owns the
+// reduction so the rule is unit-testable and each hint counts the population its own control can
+// actually reveal, rather than the rows another dial is hiding either way.
+//
+// It is a BROWSING dial of its own, not a read of `draftPurpose`. The draft's purpose is an
+// authoring field with no "unclassified" setting, so keying the library straight off it would
+// leave the only ways back through the hidden rows a re-classification of the pipeline being
+// edited (which persists) or discarding the draft. This ref is what "relax THIS dial alone" means
+// for the purpose: it defaults to following the draft and the hint below toggles it, changing what
+// is listed and nothing that gets saved.
+const browseEveryPurpose = ref(false)
+const library = computed(() =>
+  narrowPipelineLibrary(pipelines.pipelines, {
+    purpose: browseEveryPurpose.value ? null : pipelines.draftPurpose,
+    label: labelFilter.value,
+    showArchived: showArchived.value,
   }),
 )
+const visiblePipelines = computed(() => library.value.offered)
 async function toggleArchive(p: Pipeline) {
   try {
     if (p.archived) await pipelines.unarchive(p.id)
@@ -550,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
@@ -753,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
@@ -1131,7 +1113,7 @@ async function clone(p: Pipeline) {
               {{ t('pipeline.builder.savedPipelines') }}
             </h3>
             <UButton
-              v-if="archivedCount"
+              v-if="library.archivedInScope"
               :icon="showArchived ? 'i-lucide-archive-restore' : 'i-lucide-archive'"
               :color="showArchived ? 'primary' : 'neutral'"
               variant="ghost"
@@ -1145,7 +1127,7 @@ async function clone(p: Pipeline) {
               {{
                 showArchived
                   ? t('pipeline.builder.hideArchived')
-                  : t('pipeline.builder.archivedCount', { count: archivedCount })
+                  : t('pipeline.builder.archivedCount', { count: library.archivedInScope })
               }}
             </UButton>
           </div>
@@ -1174,6 +1156,40 @@ async function clone(p: Pipeline) {
             </UBadge>
           </div>
 
+          <!-- What the purpose is holding back, and the way past it. Stated here rather than
+               beside the palette's purpose control because this is where the absence is noticed:
+               a narrowed library must never read as the whole one, and a hint that only NAMES an
+               absence sends the reader to the authoring dial one column left, whose every setting
+               narrows and whose every change is saved. -->
+          <div
+            v-if="browseEveryPurpose || library.hiddenByPurpose"
+            class="mb-2 flex shrink-0 flex-wrap items-center gap-x-2 px-1 text-[10px] text-slate-500"
+          >
+            <span>
+              {{
+                browseEveryPurpose
+                  ? t('pipeline.builder.everyPurposeListed')
+                  : t(
+                      'pipeline.builder.purposeHiddenPipelines',
+                      { count: library.hiddenByPurpose },
+                      library.hiddenByPurpose,
+                    )
+              }}
+            </span>
+            <button
+              type="button"
+              class="underline underline-offset-2 hover:text-slate-300"
+              data-testid="pipeline-library-purpose-toggle"
+              @click="browseEveryPurpose = !browseEveryPurpose"
+            >
+              {{
+                browseEveryPurpose
+                  ? t('pipeline.builder.narrowToDraftPurpose')
+                  : t('pipeline.builder.listEveryPurpose')
+              }}
+            </button>
+          </div>
+
           <ul class="flex-1 space-y-1.5 pe-1 lg:min-h-0 lg:overflow-y-auto">
             <li
               v-for="p in visiblePipelines"

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/composables/usePipelineHealth.spec.ts

@@ -20,6 +20,7 @@ function builtin(agentKinds: string[], over: Partial<Pipeline> = {}): Pipeline {
   return {
     id: `pl_test_${nextId++}`,
     name: 'Test',
+    purpose: 'build',
     agentKinds,
     builtin: true,
     version: 1,

package/app/stores/pipelines/context.ts

@@ -96,7 +96,7 @@ export interface PipelinesContext {
   draftTesterQuality: Ref<(TesterQualityConfig | null)[]>
   draftStepOptions: Ref<(StepOptions | null)[]>
   draftLabels: Ref<string[]>
-  draftPurpose: Ref<PipelinePurpose | null>
+  draftPurpose: Ref<PipelinePurpose>
   draftName: Ref<string>
   draftDescription: Ref<string>
   editingId: Ref<string | null>

package/app/stores/pipelines/draftActions.ts

@@ -165,7 +165,7 @@ export function createPipelineDraftActions(ctx: PipelinesContext) {
     draftTesterQuality.value = []
     draftStepOptions.value = []
     draftLabels.value = []
-    draftPurpose.value = null
+    draftPurpose.value = 'build'
     draftName.value = 'New pipeline'
     draftDescription.value = ''
     editingId.value = null
@@ -185,7 +185,7 @@ export function createPipelineDraftActions(ctx: PipelinesContext) {
     )
     draftStepOptions.value = pipeline.agentKinds.map((_, i) => pipeline.stepOptions?.[i] ?? null)
     draftLabels.value = [...(pipeline.labels ?? [])]
-    draftPurpose.value = pipeline.purpose ?? null
+    draftPurpose.value = pipeline.purpose
     draftName.value = pipeline.name
     draftDescription.value = pipeline.description ?? ''
     editingId.value = pipeline.id

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([])
+  })
+})