@cat-factory/app 0.38.0 → 0.40.0

package/app/components/observability/StepMetricsBar.vue

@@ -43,6 +43,13 @@ const headroomTone = computed(() => headroomColor(headroom.value, m.value.trunca
       <span class="tabular-nums text-slate-400" title="Prompt / completion tokens">
         {{ formatTokens(m.promptTokens) }}↑ {{ formatTokens(m.completionTokens) }}↓
       </span>
+      <span
+        v-if="(m.cachedPromptTokens ?? 0) > 0"
+        class="tabular-nums text-emerald-400/80"
+        title="Prompt tokens served from the provider's cache"
+      >
+        ({{ formatTokens(m.cachedPromptTokens ?? 0) }} cached)
+      </span>
       <div class="ml-auto flex items-center gap-1">
         <UBadge v-if="m.errors > 0" color="error" variant="subtle" size="sm">
           {{ m.errors }} error{{ m.errors === 1 ? '' : 's' }}

package/app/components/pipeline/PipelineHealthModal.vue

@@ -0,0 +1,201 @@
+<script setup lang="ts">
+// Startup advisory for unhealthy pipelines. Opened once per session from the board page when
+// `usePipelineHealth` reports any issue. Lists:
+//   • invalid pipelines (unknown agent kind / bad shape) — DELETE a custom one, RESEED a built-in;
+//   • outdated built-ins (a newer catalog definition is available) — RESEED to adopt it.
+// Detection is client-side (see usePipelineHealth); the actions hit the pipelines store.
+const ui = useUiStore()
+const pipelines = usePipelinesStore()
+const { invalid, outdated, hasIssues } = usePipelineHealth()
+const toast = useToast()
+
+const open = computed({
+  get: () => ui.pipelineHealthOpen,
+  set: (v: boolean) => {
+    if (!v) ui.closePipelineHealth()
+  },
+})
+
+// Per-pipeline in-flight ids, so each row's button shows its own spinner.
+const busy = ref<Set<string>>(new Set())
+const isBusy = (id: string) => busy.value.has(id)
+const anyBusy = computed(() => busy.value.size > 0)
+
+async function run(id: string, action: () => Promise<unknown>, failTitle: string) {
+  busy.value = new Set(busy.value).add(id)
+  try {
+    await action()
+  } catch (e) {
+    toast.add({
+      title: failTitle,
+      description: e instanceof Error ? e.message : String(e),
+      icon: 'i-lucide-triangle-alert',
+      color: 'error',
+    })
+  } finally {
+    const next = new Set(busy.value)
+    next.delete(id)
+    busy.value = next
+  }
+}
+
+const reseed = (id: string) => run(id, () => pipelines.reseed(id), 'Could not reseed pipeline')
+const remove = (id: string) =>
+  run(id, () => pipelines.removePipeline(id), 'Could not delete pipeline')
+
+/** Reseed every reseedable pipeline (outdated built-ins + invalid built-ins) in one go. */
+async function reseedAll() {
+  const ids = [...invalid.value.filter((h) => h.pipeline.builtin), ...outdated.value].map(
+    (h) => h.pipeline.id,
+  )
+  for (const id of new Set(ids)) await reseed(id)
+}
+
+const reseedableCount = computed(
+  () =>
+    new Set([
+      ...invalid.value.filter((h) => h.pipeline.builtin).map((h) => h.pipeline.id),
+      ...outdated.value.map((h) => h.pipeline.id),
+    ]).size,
+)
+</script>
+
+<template>
+  <UModal v-model:open="open" title="Pipeline health" :ui="{ content: 'max-w-2xl' }">
+    <template #body>
+      <div v-if="!hasIssues" class="py-6 text-center text-sm text-slate-400">
+        <UIcon name="i-lucide-check-circle-2" class="mx-auto mb-2 h-8 w-8 text-emerald-400" />
+        All pipelines are valid and up to date.
+      </div>
+
+      <div v-else class="space-y-5">
+        <!-- Invalid: unknown agent kinds or a broken shape. -->
+        <section v-if="invalid.length" class="space-y-2">
+          <div class="flex items-center gap-2">
+            <UIcon name="i-lucide-triangle-alert" class="h-4 w-4 text-rose-400" />
+            <h3 class="text-sm font-semibold text-slate-200">Invalid pipelines</h3>
+          </div>
+          <p class="text-[11px] text-slate-500">
+            These reference a missing agent or are misconfigured, so they would fail (or misrun) at
+            start. Delete a custom pipeline, or reseed a built-in to restore its catalog definition.
+          </p>
+          <ul class="space-y-2">
+            <li
+              v-for="h in invalid"
+              :key="h.pipeline.id"
+              class="rounded-lg border border-slate-800 bg-slate-900/40 p-3"
+            >
+              <div class="flex items-start justify-between gap-3">
+                <div class="min-w-0">
+                  <div class="flex items-center gap-2">
+                    <span class="truncate text-sm font-medium text-slate-100">
+                      {{ h.pipeline.name }}
+                    </span>
+                    <UBadge v-if="h.pipeline.builtin" color="neutral" variant="subtle" size="xs">
+                      built-in
+                    </UBadge>
+                  </div>
+                  <ul class="mt-1 space-y-0.5">
+                    <li
+                      v-for="(p, i) in h.problems"
+                      :key="i"
+                      class="text-[11px]"
+                      :class="p.type === 'outdated' ? 'text-amber-400/80' : 'text-rose-400/90'"
+                    >
+                      {{ p.message }}
+                    </li>
+                  </ul>
+                </div>
+                <UButton
+                  v-if="h.pipeline.builtin"
+                  size="xs"
+                  color="primary"
+                  variant="subtle"
+                  icon="i-lucide-rotate-ccw"
+                  :loading="isBusy(h.pipeline.id)"
+                  :disabled="anyBusy"
+                  @click="reseed(h.pipeline.id)"
+                >
+                  Reseed
+                </UButton>
+                <UButton
+                  v-else
+                  size="xs"
+                  color="error"
+                  variant="subtle"
+                  icon="i-lucide-trash-2"
+                  :loading="isBusy(h.pipeline.id)"
+                  :disabled="anyBusy"
+                  @click="remove(h.pipeline.id)"
+                >
+                  Delete
+                </UButton>
+              </div>
+            </li>
+          </ul>
+        </section>
+
+        <!-- Outdated built-ins: a newer catalog version is available. -->
+        <section v-if="outdated.length" class="space-y-2">
+          <div class="flex items-center gap-2">
+            <UIcon name="i-lucide-arrow-up-circle" class="h-4 w-4 text-amber-400" />
+            <h3 class="text-sm font-semibold text-slate-200">Updates available</h3>
+          </div>
+          <p class="text-[11px] text-slate-500">
+            A newer version of these built-in pipelines has shipped. Reseed to adopt it (your labels
+            and archive state are kept).
+          </p>
+          <ul class="space-y-2">
+            <li
+              v-for="h in outdated"
+              :key="h.pipeline.id"
+              class="flex items-center justify-between gap-3 rounded-lg border border-slate-800 bg-slate-900/40 p-3"
+            >
+              <div class="min-w-0">
+                <span class="truncate text-sm font-medium text-slate-100">{{
+                  h.pipeline.name
+                }}</span>
+                <p class="text-[11px] text-amber-400/80">{{ h.problems[0]?.message }}</p>
+              </div>
+              <UButton
+                size="xs"
+                color="primary"
+                variant="subtle"
+                icon="i-lucide-rotate-ccw"
+                :loading="isBusy(h.pipeline.id)"
+                :disabled="anyBusy"
+                @click="reseed(h.pipeline.id)"
+              >
+                Reseed
+              </UButton>
+            </li>
+          </ul>
+        </section>
+      </div>
+    </template>
+
+    <template #footer>
+      <div class="flex w-full items-center justify-between gap-2">
+        <UButton
+          v-if="reseedableCount > 1"
+          color="primary"
+          variant="ghost"
+          icon="i-lucide-rotate-ccw"
+          :loading="anyBusy"
+          @click="reseedAll"
+        >
+          Reseed all ({{ reseedableCount }})
+        </UButton>
+        <span v-else />
+        <UButton
+          color="neutral"
+          variant="ghost"
+          :disabled="anyBusy"
+          @click="ui.closePipelineHealth()"
+        >
+          {{ hasIssues ? 'Dismiss' : 'Done' }}
+        </UButton>
+      </div>
+    </template>
+  </UModal>
+</template>

package/app/components/providers/ApiKeysSection.vue

@@ -34,6 +34,13 @@ interface ProviderMeta {
   label: string
   url: string
   steps: string[]
+  /**
+   * Whether this provider caches the re-sent prompt prefix. Connecting a key here
+   * upgrades its models to the caching `direct` flavour, so a long agentic run stops
+   * re-billing its whole growing prompt every turn. Mirrors the backend
+   * `providerCachePolicy`; the gateways are pass-through (no caching we rely on yet).
+   */
+  caches?: boolean
 }
 
 /** Direct vendors: the key reaches that one vendor's own endpoint. */
@@ -46,6 +53,7 @@ const DIRECT_PROVIDERS: ProviderMeta[] = [
       'Open platform.openai.com → API keys and create a new secret key.',
       'Copy the key (starts with sk-…); it is shown only once.',
     ],
+    caches: true,
   },
   {
     value: 'anthropic',
@@ -55,6 +63,7 @@ const DIRECT_PROVIDERS: ProviderMeta[] = [
       'Open console.anthropic.com → Settings → API Keys and create a key.',
       'Copy the key (starts with sk-ant-…).',
     ],
+    caches: true,
   },
   {
     value: 'qwen',
@@ -64,6 +73,7 @@ const DIRECT_PROVIDERS: ProviderMeta[] = [
       'Open the DashScope console (international) → API-KEY and create a key.',
       'Copy the key; it authenticates the OpenAI-compatible Qwen endpoint.',
     ],
+    caches: true,
   },
   {
     value: 'deepseek',
@@ -73,6 +83,7 @@ const DIRECT_PROVIDERS: ProviderMeta[] = [
       'Open platform.deepseek.com → API keys and create a key.',
       'Copy the key (starts with sk-…).',
     ],
+    caches: true,
   },
   {
     value: 'moonshot',
@@ -268,6 +279,14 @@ async function remove(k: ApiKey) {
       </li>
     </ol>
 
+    <!-- caching capability: connecting a direct key that caches upgrades its models to
+         the caching flavour, so long agentic runs stop re-billing the whole prompt. -->
+    <p v-if="selected.caches" class="flex items-center gap-1.5 text-[12px] text-emerald-400/90">
+      <UIcon name="i-lucide-zap" class="h-3.5 w-3.5 shrink-0" />
+      Enables prompt caching for {{ selected.label }} models — a long multi-turn run reuses its
+      cached prompt prefix instead of re-sending it every turn.
+    </p>
+
     <!-- add form -->
     <div class="space-y-2">
       <UFormField label="Label (optional)">

package/app/components/settings/ModelConfigurationPanel.vue

@@ -15,7 +15,7 @@ import { onKeyStroke } from '@vueuse/core'
 import type { AgentKind } from '~/types/domain'
 import type { ModelPreset } from '~/types/model-presets'
 import { MODEL_CONFIGURABLE_SYSTEM_KINDS } from '~/utils/catalog'
-import { contextLabel, costLabel, displayFlavor, isSelectable } from '~/stores/models'
+import { cachingLabel, contextLabel, costLabel, displayFlavor, isSelectable } from '~/stores/models'
 
 const ui = useUiStore()
 const models = useModelsStore()
@@ -84,7 +84,10 @@ const selectableModels = computed(() => {
       const flavor = displayFlavor(m, configured)
       const ctx = contextLabel(flavor.contextTokens)
       const price = costLabel(flavor) ?? (flavor.quotaBased ? 'quota' : undefined)
-      const suffix = [flavor.providerLabel, ctx, price].filter(Boolean).join(' · ')
+      // Surface caching in the suffix: a cache-less flavour (the Workers-AI hot path)
+      // re-bills its whole growing prompt every turn, which the user can act on.
+      const caching = cachingLabel(flavor)
+      const suffix = [flavor.providerLabel, ctx, price, caching].filter(Boolean).join(' · ')
       return {
         id: m.id,
         label: m.label,

package/app/composables/api/board.ts

@@ -13,6 +13,7 @@ import {
   organizePipelineContract,
   removeBlockContract,
   reparentBlockContract,
+  reseedPipelineContract,
   toggleDependencyContract,
   updateBlockContract,
   updatePipelineContract,
@@ -129,5 +130,10 @@ export function boardApi({ send, ws }: ApiContext) {
 
     removePipeline: (workspaceId: string, pipelineId: string) =>
       send(deletePipelineContract, { pathPrefix: ws(workspaceId), pathParams: { pipelineId } }),
+
+    // Restore a built-in pipeline to its current catalog definition (adopt an improved
+    // built-in, or repair a drifted/invalid one). Custom pipelines reject this.
+    reseedPipeline: (workspaceId: string, pipelineId: string) =>
+      send(reseedPipelineContract, { pathPrefix: ws(workspaceId), pathParams: { pipelineId } }),
   }
 }

package/app/composables/usePipelineHealth.spec.ts

@@ -0,0 +1,143 @@
+import { describe, it, expect } from 'vitest'
+import type { Pipeline } from '~/types/domain'
+import { isKnownAgentKind } from '~/utils/catalog'
+import { usePipelinesStore } from '~/stores/pipelines'
+import { usePipelineHealth } from '~/composables/usePipelineHealth'
+
+/**
+ * Guards the startup pipeline-health advisory against the failure that bit the first cut: a
+ * legitimate built-in agent kind missing from the frontend catalog made `isKnownAgentKind`
+ * return false, so a stock seeded pipeline (`pl_tech_debt`, which uses `analysis` + `tracker`)
+ * was reported "invalid" in every workspace with a Reseed action that could never fix it.
+ *
+ * The kind lists below mirror the canonical built-ins in
+ * `backend/packages/kernel/src/domain/seed.ts`; keep them in step when a seed pipeline gains a
+ * new kind. The `every built-in seed kind is known` test then fails loudly if the catalog drifts.
+ */
+
+let nextId = 0
+function builtin(agentKinds: string[], over: Partial<Pipeline> = {}): Pipeline {
+  return {
+    id: `pl_test_${nextId++}`,
+    name: 'Test',
+    agentKinds,
+    builtin: true,
+    version: 1,
+    ...over,
+  }
+}
+
+/** Seed the store with pipelines + their current catalog versions, then scan. */
+function scan(pipelines: Pipeline[], versions: Record<string, number> = {}) {
+  const store = usePipelinesStore()
+  const catalogVersions = {
+    ...Object.fromEntries(pipelines.filter((p) => p.builtin).map((p) => [p.id, p.version ?? 0])),
+    ...versions,
+  }
+  store.hydrate(pipelines, catalogVersions)
+  return usePipelineHealth()
+}
+
+// Every agent kind any built-in catalog pipeline references (mirror of seed.ts). The advisory's
+// validity oracle (`isKnownAgentKind`) must recognise all of them, or a stock pipeline is
+// falsely flagged. `analysis`/`tracker` are the two that originally regressed.
+const BUILTIN_SEED_KINDS = [
+  'requirements-review',
+  'spec-writer',
+  'architect',
+  'coder',
+  'reviewer',
+  'blueprints',
+  'mocker',
+  'tester',
+  'conflicts',
+  'ci',
+  'merger',
+  'integrator',
+  'documenter',
+  'analysis',
+  'tracker',
+  'human-test',
+  'human-review',
+]
+
+describe('isKnownAgentKind', () => {
+  it('recognises every agent kind used by the built-in seed catalog', () => {
+    const unknown = BUILTIN_SEED_KINDS.filter((k) => !isKnownAgentKind(k))
+    expect(unknown).toEqual([])
+  })
+
+  it('specifically recognises analysis + tracker (the kinds that regressed)', () => {
+    expect(isKnownAgentKind('analysis')).toBe(true)
+    expect(isKnownAgentKind('tracker')).toBe(true)
+  })
+
+  it('returns false for a genuinely unknown kind', () => {
+    expect(isKnownAgentKind('totally-made-up-kind')).toBe(false)
+  })
+})
+
+describe('usePipelineHealth', () => {
+  it('does not flag the stock tech-debt built-in (analysis + tracker) as invalid', () => {
+    const techDebt = builtin(
+      [
+        'analysis',
+        'tracker',
+        'coder',
+        'reviewer',
+        'blueprints',
+        'tester',
+        'conflicts',
+        'ci',
+        'merger',
+      ],
+      { id: 'pl_tech_debt', name: 'Tech debt' },
+    )
+    const { hasIssues, invalid, outdated } = scan([techDebt])
+    expect(hasIssues.value).toBe(false)
+    expect(invalid.value).toHaveLength(0)
+    expect(outdated.value).toHaveLength(0)
+  })
+
+  it('flags a pipeline that references an unknown agent kind', () => {
+    const broken = builtin(['coder', 'bogus-kind'])
+    const { invalid } = scan([broken])
+    expect(invalid.value).toHaveLength(1)
+    expect(invalid.value[0]!.problems.some((p) => p.type === 'unknown-kind')).toBe(true)
+  })
+
+  it('accepts a valid producer + companion chain', () => {
+    const { hasIssues } = scan([builtin(['coder', 'reviewer'])])
+    expect(hasIssues.value).toBe(false)
+  })
+
+  it('flags a companion with no preceding producer it can review (shape)', () => {
+    const { invalid } = scan([builtin(['reviewer'])])
+    expect(invalid.value).toHaveLength(1)
+    expect(invalid.value[0]!.problems.some((p) => p.type === 'shape')).toBe(true)
+  })
+
+  it('flags an estimate-gated companion with no task-estimator before it (shape)', () => {
+    const gated = builtin(['coder', 'reviewer'], {
+      gating: [null, { enabled: true, minComplexity: 0.5, onMissingEstimate: 'run' }],
+    })
+    const { invalid } = scan([gated])
+    expect(invalid.value).toHaveLength(1)
+    expect(invalid.value[0]!.problems.some((p) => p.type === 'shape')).toBe(true)
+  })
+
+  it('reports a built-in whose catalog version moved ahead as outdated (not invalid)', () => {
+    const stale = builtin(['coder', 'reviewer'], { id: 'pl_stale', version: 1 })
+    const { invalid, outdated } = scan([stale], { pl_stale: 2 })
+    expect(invalid.value).toHaveLength(0)
+    expect(outdated.value).toHaveLength(1)
+    expect(outdated.value[0]!.problems[0]!.type).toBe('outdated')
+  })
+
+  it('keeps an invalid + outdated built-in out of the outdated list (one fix, not two)', () => {
+    const both = builtin(['coder', 'bogus-kind'], { id: 'pl_both', version: 1 })
+    const { invalid, outdated } = scan([both], { pl_both: 2 })
+    expect(invalid.value).toHaveLength(1)
+    expect(outdated.value).toHaveLength(0)
+  })
+})

package/app/composables/usePipelineHealth.ts

@@ -0,0 +1,140 @@
+import { computed } from 'vue'
+import type { Pipeline } from '~/types/domain'
+import type { StepGating } from '~/types/consensus'
+import { COMPANION_FOR_PRODUCER, isKnownAgentKind, isProducerCompanion } from '~/utils/catalog'
+import { usePipelinesStore } from '~/stores/pipelines'
+
+/** Estimate-gating consults a `task-estimator` step (mirrors the backend constant). */
+const TASK_ESTIMATOR_KIND = 'task-estimator'
+
+export type PipelineProblemType = 'unknown-kind' | 'shape' | 'outdated'
+
+export interface PipelineProblem {
+  type: PipelineProblemType
+  message: string
+}
+
+export interface PipelineHealth {
+  pipeline: Pipeline
+  problems: PipelineProblem[]
+  /** Structural / unknown-kind problems — delete (custom) or reseed (built-in) to fix. */
+  invalid: boolean
+  /** A built-in whose catalog definition is newer than the stored copy — reseed to update. */
+  outdated: boolean
+}
+
+/** Producers a companion kind is allowed to review (inverse of {@link COMPANION_FOR_PRODUCER}). */
+function companionTargets(companion: string): string[] {
+  return Object.entries(COMPANION_FOR_PRODUCER)
+    .filter(([, c]) => c === companion)
+    .map(([producer]) => producer)
+}
+
+const isEnabledAt = (p: Pipeline, i: number) => p.enabled?.[i] !== false
+
+/**
+ * Client-side mirror of the backend `validatePipelineShape` (companion adjacency + estimate
+ * gating, over the ENABLED subset), collecting the first problem instead of throwing. Returns a
+ * human message, or null when the shape is valid. Kept in step with
+ * `backend/packages/orchestration/src/modules/pipelines/pipelineShape.ts`.
+ */
+function shapeProblem(p: Pipeline): string | null {
+  const kinds = p.agentKinds
+  // No enabled steps ⇒ nothing would run.
+  if (kinds.length === 0 || !kinds.some((_, i) => isEnabledAt(p, i))) {
+    return 'No enabled steps — the pipeline has nothing to run.'
+  }
+  // Companion adjacency: an enabled companion's nearest preceding enabled step must be a
+  // producer it can review.
+  for (let i = 0; i < kinds.length; i++) {
+    const kind = kinds[i]
+    if (!kind || !isProducerCompanion(kind) || !isEnabledAt(p, i)) continue
+    const targets = companionTargets(kind)
+    let predecessor: string | undefined
+    for (let j = i - 1; j >= 0; j--) {
+      if (isEnabledAt(p, j)) {
+        predecessor = kinds[j]
+        break
+      }
+    }
+    if (predecessor === undefined || !targets.includes(predecessor)) {
+      return `Companion '${kind}' must run immediately after an enabled step it can review (${targets.join(', ')}).`
+    }
+  }
+  // Estimate gating: an enabled gated step must be a companion, set ≥1 threshold, and have an
+  // enabled task-estimator earlier in the chain.
+  const gating = p.gating
+  if (gating) {
+    for (let i = 0; i < kinds.length; i++) {
+      const g = gating[i] as StepGating | null | undefined
+      if (!g?.enabled || !isEnabledAt(p, i)) continue
+      const kind = kinds[i]
+      if (!kind || !isProducerCompanion(kind)) {
+        return `Step '${kind}' cannot be estimate-gated — only companion steps may be skipped on the estimate.`
+      }
+      if (g.minComplexity === undefined && g.minRisk === undefined && g.minImpact === undefined) {
+        return `Step '${kind}' is estimate-gated but sets no threshold (complexity / risk / impact).`
+      }
+      const hasEstimator = kinds
+        .slice(0, i)
+        .some((k, j) => k === TASK_ESTIMATOR_KIND && isEnabledAt(p, j))
+      if (!hasEstimator) {
+        return `Step '${kind}' is gated on the estimate but no enabled '${TASK_ESTIMATOR_KIND}' runs before it.`
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Detect pipelines in an unhealthy state for the startup advisory: those referencing an unknown
+ * agent kind or with an invalid shape (offer to delete a custom one / reseed a built-in), and
+ * built-ins whose seeded definition has moved ahead of the stored copy (offer to reseed). Reads
+ * the pipeline library + the snapshot's catalog versions from the pipelines store. Detection runs
+ * entirely client-side because the canonical agent-kind catalog lives here (`AGENT_BY_KIND` +
+ * `SYSTEM_AGENT_META` + registered custom kinds); the version comparison uses the catalog
+ * versions the snapshot ships.
+ */
+export function usePipelineHealth() {
+  const store = usePipelinesStore()
+
+  const health = computed<PipelineHealth[]>(() => {
+    const out: PipelineHealth[] = []
+    for (const pipeline of store.pipelines) {
+      const problems: PipelineProblem[] = []
+
+      const unknown = [...new Set(pipeline.agentKinds.filter((k) => !isKnownAgentKind(k)))]
+      if (unknown.length) {
+        problems.push({
+          type: 'unknown-kind',
+          message: `References unknown agent ${unknown.length > 1 ? 'kinds' : 'kind'}: ${unknown.join(', ')}.`,
+        })
+      }
+
+      const shape = shapeProblem(pipeline)
+      if (shape) problems.push({ type: 'shape', message: shape })
+
+      const catalogVersion = pipeline.builtin ? store.catalogVersions[pipeline.id] : undefined
+      const outdated = catalogVersion !== undefined && catalogVersion > (pipeline.version ?? 0)
+      if (outdated) {
+        problems.push({
+          type: 'outdated',
+          message: `A newer version of this built-in pipeline is available (v${pipeline.version ?? 0} → v${catalogVersion}).`,
+        })
+      }
+
+      if (problems.length) {
+        out.push({ pipeline, problems, invalid: unknown.length > 0 || shape !== null, outdated })
+      }
+    }
+    return out
+  })
+
+  // An invalid built-in is reseeded (not deleted) and that also clears any "outdated" flag, so
+  // exclude it from the outdated list to avoid offering the same fix twice.
+  const invalid = computed(() => health.value.filter((h) => h.invalid))
+  const outdated = computed(() => health.value.filter((h) => h.outdated && !h.invalid))
+  const hasIssues = computed(() => health.value.length > 0)
+
+  return { health, invalid, outdated, hasIssues }
+}

package/app/pages/index.vue

@@ -49,6 +49,11 @@ const SlackPanel = defineAsyncComponent(() => import('~/components/slack/SlackPa
 const FragmentLibraryPanel = defineAsyncComponent(
   () => import('~/components/fragments/FragmentLibraryPanel.vue'),
 )
+// Startup advisory for invalid / outdated pipelines — only mounted while open (auto-opened
+// at most once per session by the watcher below), so it stays out of the initial bundle.
+const PipelineHealthModal = defineAsyncComponent(
+  () => import('~/components/pipeline/PipelineHealthModal.vue'),
+)
 const IntegrationsHub = defineAsyncComponent(
   () => import('~/components/layout/IntegrationsHub.vue'),
 )
@@ -122,11 +127,25 @@ watch(
       autoOpenedSetup.value = false
       autoOpenedPreset.value = false
       ui.resetAiOnboarding()
+      // A different board has its own pipeline library, so re-arm the once-per-session advisory.
+      ui.pipelineHealthSeen = false
     }
   },
   { immediate: true },
 )
 
+// Pipeline-health advisory: once a board is loaded, surface any invalid / outdated pipelines in
+// a startup modal (auto-opened at most once per session per board — later opens are user-driven).
+// Detection is reactive, so this fires as soon as the snapshot hydrates.
+const { hasIssues: pipelineIssues } = usePipelineHealth()
+watch(
+  () => [workspace.ready, pipelineIssues.value],
+  () => {
+    if (workspace.ready && pipelineIssues.value) ui.maybeOpenPipelineHealth()
+  },
+  { immediate: true },
+)
+
 // Auto-open the right AI-onboarding dialog once per session: the no-source prompt takes
 // precedence over the preset-mismatch prompt. Honour the per-session dismissed flags so a
 // user who closed the banner isn't re-interrupted, and only auto-open once each (later opens
@@ -242,6 +261,7 @@ watch(
       <GitHubPanel v-if="ui.githubOpen" />
       <SlackPanel v-if="ui.slackOpen" />
       <FragmentLibraryPanel v-if="ui.fragmentLibraryOpen" />
+      <PipelineHealthModal v-if="ui.pipelineHealthOpen" />
       <IntegrationsHub v-if="ui.integrationsOpen" />
       <PersonalSetupModal v-if="ui.personalSetupOpen" />
       <WorkspaceSettingsPanel v-if="ui.workspaceSettingsOpen" />

package/app/stores/models.ts

@@ -12,6 +12,13 @@ export interface DisplayFlavor {
   /** True ⇒ flat-rate quota; its cost is a quota burn rate, not budget spend. */
   quotaBased: boolean
   vendor?: SubscriptionVendor
+  /**
+   * Whether this flavour's provider caches the re-sent prompt prefix. False on a
+   * Cloudflare/Workers-AI flavour (the hot path re-bills the whole prompt every turn);
+   * true once a direct key upgrades the model to its caching `direct` flavour. Undefined
+   * ⇒ unknown (older catalog). Surfaced as a badge in the picker.
+   */
+  cachesPrompts?: boolean
 }
 
 /**
@@ -30,6 +37,7 @@ export function displayFlavor(m: ModelOption, configured: Set<SubscriptionVendor
       cost: m.subscription.cost,
       quotaBased: true,
       vendor: m.subscription.vendor,
+      cachesPrompts: m.subscription.cachesPrompts,
     }
   }
   return {
@@ -40,6 +48,7 @@ export function displayFlavor(m: ModelOption, configured: Set<SubscriptionVendor
     cost: m.cost,
     quotaBased: m.quotaBased ?? false,
     vendor: m.vendor,
+    cachesPrompts: m.cachesPrompts,
   }
 }
 
@@ -69,6 +78,20 @@ export function costLabel(flavor: DisplayFlavor): string | undefined {
   return flavor.quotaBased ? `quota burn ~${body}` : body
 }
 
+/**
+ * A short caching label for the picker: whether the flavour's provider caches the
+ * re-sent prompt prefix. `null` when unknown (older catalog) so the caller can omit it
+ * entirely. A long agentic run on a non-caching flavour re-bills its whole growing
+ * prompt every turn (slower, more rate-limited), so we surface it as an informational
+ * hint the user can act on (connect a direct key / pick a caching model). The model
+ * picker is a text-only dropdown-menu item list, so this is a label token in the option
+ * suffix rather than a styled badge.
+ */
+export function cachingLabel(flavor: DisplayFlavor): string | null {
+  if (flavor.cachesPrompts === undefined) return null
+  return flavor.cachesPrompts ? 'Prompt caching' : 'No prompt caching'
+}
+
 /**
  * The model picker catalog. Served by `GET /models`, where each model is already
  * resolved to the flavour in use for this deployment (direct when the provider's

package/app/stores/pipelines.ts

@@ -31,6 +31,12 @@ function defaultConsensusConfig(): ConsensusStepConfig {
 export const usePipelinesStore = defineStore('pipelines', () => {
   const api = useApi()
   const pipelines = ref<Pipeline[]>([])
+  /**
+   * Current built-in catalog versions (`seedPipelines()`), keyed by pipeline id, from the
+   * workspace snapshot. A built-in whose stored `version` is below its catalog value here has
+   * a newer definition available (see `usePipelineHealth`).
+   */
+  const catalogVersions = ref<Record<string, number>>({})
 
   /** The chain currently being assembled in the builder. */
   const draft = ref<AgentKind[]>([])
@@ -59,9 +65,10 @@ export const usePipelinesStore = defineStore('pipelines', () => {
   /** The id of the pipeline being edited, or null when assembling a brand-new one. */
   const editingId = ref<string | null>(null)
 
-  /** Replace the cached pipelines with a server snapshot. */
-  function hydrate(next: Pipeline[]) {
+  /** Replace the cached pipelines (and the current built-in catalog versions) from a snapshot. */
+  function hydrate(next: Pipeline[], versions?: Record<string, number>) {
     pipelines.value = next
+    if (versions) catalogVersions.value = versions
   }
 
   function getPipeline(id: string) {
@@ -300,6 +307,19 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     if (editingId.value === id) clearDraft()
   }
 
+  /**
+   * Reseed a built-in pipeline from the backend's current catalog definition: restores its
+   * canonical structure + version (adopting an update, or repairing a drifted/invalid copy)
+   * while preserving its labels/archive state. Replaces the pipeline in the cache.
+   */
+  async function reseed(id: string): Promise<Pipeline> {
+    const updated = await api.reseedPipeline(useWorkspaceStore().requireId(), id)
+    const i = pipelines.value.findIndex((p) => p.id === updated.id)
+    if (i >= 0) pipelines.value[i] = updated
+    if (editingId.value === id) clearDraft()
+    return updated
+  }
+
   /** Set a pipeline's organizational metadata (labels / archive). Works on built-ins too. */
   async function organize(id: string, body: { labels?: string[]; archived?: boolean }) {
     const updated = await api.organizePipeline(useWorkspaceStore().requireId(), id, body)
@@ -314,6 +334,7 @@ export const usePipelinesStore = defineStore('pipelines', () => {
 
   return {
     pipelines,
+    catalogVersions,
     draft,
     draftGates,
     draftEnabled,
@@ -344,6 +365,7 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     saveDraft,
     clonePipeline,
     removePipeline,
+    reseed,
     organize,
     archive,
     unarchive,

package/app/stores/ui.ts

@@ -19,6 +19,11 @@ export const useUiStore = defineStore('ui', () => {
   const selectedBlockId = ref<string | null>(null)
   const focusBlockId = ref<string | null>(null)
   const builderOpen = ref(false)
+  // Pipeline-health startup advisory: lists invalid pipelines (delete / reseed) + built-ins
+  // with a newer catalog version (reseed). `pipelineHealthSeen` gates auto-open to once per
+  // session so it does not re-pop on every snapshot re-hydration.
+  const pipelineHealthOpen = ref(false)
+  const pipelineHealthSeen = ref(false)
   const decisionContext = ref<{ instanceId: string; decisionId: string } | null>(null)
 
   // Document-source integration modals, keyed by source. `documentImport` and
@@ -217,6 +222,22 @@ export const useUiStore = defineStore('ui', () => {
     builderOpen.value = true
   }
 
+  /** Auto-open the pipeline-health advisory once per session (no-op after it's been shown). */
+  function maybeOpenPipelineHealth() {
+    if (pipelineHealthSeen.value) return
+    pipelineHealthSeen.value = true
+    pipelineHealthOpen.value = true
+  }
+
+  function openPipelineHealth() {
+    pipelineHealthSeen.value = true
+    pipelineHealthOpen.value = true
+  }
+
+  function closePipelineHealth() {
+    pipelineHealthOpen.value = false
+  }
+
   function openDecision(instanceId: string, decisionId: string) {
     decisionContext.value = { instanceId, decisionId }
   }
@@ -600,6 +621,8 @@ export const useUiStore = defineStore('ui', () => {
     selectedBlockId,
     focusBlockId,
     builderOpen,
+    pipelineHealthOpen,
+    pipelineHealthSeen,
     decisionContext,
     documentConnect,
     documentImport,
@@ -651,6 +674,9 @@ export const useUiStore = defineStore('ui', () => {
     select,
     focus,
     openBuilder,
+    maybeOpenPipelineHealth,
+    openPipelineHealth,
+    closePipelineHealth,
     openDecision,
     closeDecision,
     openApprovalDetail,

package/app/stores/workspace.ts

@@ -82,7 +82,7 @@ export const useWorkspaceStore = defineStore(
       if (i >= 0) workspaces.value[i] = snapshot.workspace
       else workspaces.value.unshift(snapshot.workspace)
       useBoardStore().hydrate(snapshot.blocks)
-      usePipelinesStore().hydrate(snapshot.pipelines)
+      usePipelinesStore().hydrate(snapshot.pipelines, snapshot.pipelineCatalogVersions)
       useExecutionStore().hydrate(snapshot.executions)
       useAgentRunsStore().hydrate(snapshot.bootstrapJobs ?? [])
       useNotificationsStore().hydrate(snapshot.notifications ?? [])

package/app/utils/catalog.ts

@@ -303,6 +303,28 @@ export const SYSTEM_AGENT_META: Record<string, AgentArchetype> = {
     color: '#22d3ee',
     description: 'Maps the repository into the service → modules blueprint.',
   },
+  // A read-only repository audit that emits a prioritized findings report. Not a palette
+  // archetype (it is only seeded into the recurring tech-debt pipeline), so it lives here
+  // for run-timeline / saved-pipeline display rather than in AGENT_ARCHETYPES.
+  analysis: {
+    kind: 'analysis',
+    label: 'Analyst',
+    icon: 'i-lucide-search-code',
+    color: '#818cf8',
+    description:
+      'Audits the repository read-only and emits a prioritized findings report (drives the tech-debt pipeline).',
+  },
+  // A one-shot engine step that files a tracker ticket (GitHub issue / Jira) from the
+  // preceding analysis before implementation. Runs no model itself; seeded only into the
+  // tech-debt pipeline, so it is a display-metadata system kind, not a palette archetype.
+  tracker: {
+    kind: 'tracker',
+    label: 'Issue Tracker',
+    icon: 'i-lucide-ticket',
+    color: '#fb923c',
+    description:
+      'Files a tracker ticket (GitHub issue / Jira) from the analysis before work starts.',
+  },
   conflicts: {
     kind: 'conflicts',
     label: 'Conflicts Gate',
@@ -447,6 +469,18 @@ export function agentKindMeta(kind: string): AgentArchetype {
   )
 }
 
+/**
+ * Whether an agent kind is actually known to this build — a palette archetype or companion
+ * ({@link AGENT_BY_KIND}, which deployment custom kinds are merged into via
+ * `useAgentsStore().registerCustomKinds`), or an engine system/gate kind
+ * ({@link SYSTEM_AGENT_META}). Unlike {@link agentKindMeta} (which always returns a usable
+ * fallback so renderers never crash), this returns `false` for an unknown kind — used to flag
+ * a pipeline that references a nonexistent agent. Call AFTER custom kinds are registered.
+ */
+export function isKnownAgentKind(kind: string): boolean {
+  return kind in AGENT_BY_KIND || kind in SYSTEM_AGENT_META
+}
+
 type BlockTypeMeta = { label: string; icon: string; accent: string }
 
 /** Visual metadata for each architecture block type. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",
@@ -32,7 +32,7 @@
     "pinia-plugin-persistedstate": "^4.7.1",
     "vue": "^3.5.38",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.37.0"
+    "@cat-factory/contracts": "0.39.0"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.1",