@cat-factory/app 0.195.2 → 0.196.0

package/app/components/panels/StepMetadataCard.vue

@@ -48,6 +48,13 @@ const stateMeta = computed(() => {
 
 const modelLabel = computed(() => (props.step.model ? models.labelForRef(props.step.model) : null))
 
+/**
+ * The deployment-registered VARIANT this step ran under — an alternate prompt for its agent kind.
+ * Reported beside the model because it is the other half of "what actually ran"; null on every
+ * step that ran the shipped prompt, so the field is simply absent on the stock product.
+ */
+const promptVariant = useStepPromptVariant(() => props.step)
+
 const ITEM_ICON: Record<string, string> = {
   completed: 'i-lucide-check-circle-2',
   in_progress: 'i-lucide-loader-circle',
@@ -140,6 +147,15 @@ async function copyRunId() {
           {{ modelLabel ?? t('panels.stepMeta.notRecorded') }}
         </dd>
       </div>
+      <div v-if="promptVariant">
+        <dt class="text-[11px] uppercase tracking-wide text-slate-500">
+          {{ t('panels.stepMeta.promptVariant') }}
+        </dt>
+        <dd class="mt-0.5 truncate text-slate-300">{{ promptVariant.label }}</dd>
+        <dd v-if="promptVariant.note" class="mt-0.5 text-[11px] text-amber-400/80">
+          {{ promptVariant.note }}
+        </dd>
+      </div>
       <!-- The run id this step belongs to, surfaced for debugging (copyable). -->
       <div class="col-span-2 sm:col-span-3">
         <dt class="text-[11px] uppercase tracking-wide text-slate-500">

package/app/components/panels/StepRunMeta.vue

@@ -27,6 +27,14 @@ const props = defineProps<{
 const models = useModelsStore()
 const { t, d } = useI18n()
 
+/**
+ * The deployment-registered VARIANT this step ran under — an alternate prompt for its agent kind.
+ * Reported beside the model because it is the other half of "what actually ran": two steps of the
+ * same kind on the same model can be told to be different things, and nothing else on this panel
+ * would say so. Null on every step that ran the shipped prompt.
+ */
+const promptVariant = useStepPromptVariant(() => props.step)
+
 const { isRunning, durationLabel, activityAgoLabel } = useStepTimer({
   step: () => props.step,
   runFailed: () => props.runFailed ?? false,
@@ -110,6 +118,16 @@ async function copyRunId() {
       </p>
     </div>
 
+    <div v-if="promptVariant">
+      <h4 class="mb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
+        {{ t('panels.stepMeta.promptVariant') }}
+      </h4>
+      <p class="break-all text-[12px] text-slate-300">{{ promptVariant.label }}</p>
+      <p v-if="promptVariant.note" class="mt-0.5 text-[11px] text-amber-400/80">
+        {{ promptVariant.note }}
+      </p>
+    </div>
+
     <div v-if="runId">
       <h4 class="mb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
         {{ t('panels.stepMeta.run') }}

package/app/components/pipeline/PipelineBuilder.vue

@@ -151,6 +151,29 @@ function showOutputBudget(index: number): boolean {
 function inheritedOutputBudget(kind: AgentKind): number | undefined {
   return agentSettings.maxOutputTokensFor(kind)
 }
+/**
+ * Whether to offer the agent-kind VARIANT picker on this step: only when the deployment
+ * registered variants for its kind, and then only in advanced mode WHILE the step is still on the
+ * shipped prompt. Picking a variant is an OVERRIDE of what the kind ships, so `showOverrideField`
+ * keeps it visible the moment one is set — a step varied by a teammate (or by the API) must never
+ * become invisible to a basic-mode user who would then have no way to see, let alone undo, it.
+ */
+function showVariantPicker(index: number, kind: AgentKind): boolean {
+  if (!agents.variantsForKind(kind).length) return false
+  return showOverrideField(uiMode.isAdvanced, pipelines.draftAgentVariantId(index) ?? null)
+}
+
+/**
+ * The variants registered for a step's kind as USelect items, with an explicit "shipped prompt"
+ * entry so clearing the pick is a choice in the same list rather than a separate affordance.
+ */
+function variantSelectItems(kind: AgentKind) {
+  return [
+    { label: t('pipeline.builder.variantShipped'), value: '' },
+    ...agents.variantsForKind(kind).map((variant) => ({ label: variant.label, value: variant.id })),
+  ]
+}
+
 const releaseHealth = useReleaseHealthStore()
 const skills = useSkillsStore()
 
@@ -746,6 +769,29 @@ async function clone(p: Pipeline) {
                 </p>
               </div>
 
+              <!-- Agent-kind VARIANT picker: a deployment-registered alternate prompt for this
+                 step's kind (`stepOptions.agentVariantId`). The step still runs the kind — only
+                 the prompt changes — so this is an override of the shipped text, shown only where
+                 the deployment registered one. -->
+              <div
+                v-if="showVariantPicker(unit.index, unit.kind)"
+                class="ms-6 flex items-center gap-2"
+              >
+                <span class="text-[10px] text-slate-500">
+                  {{ t('pipeline.builder.variantLabel') }}
+                </span>
+                <USelect
+                  class="w-56"
+                  :model-value="pipelines.draftAgentVariantId(unit.index) ?? ''"
+                  :items="variantSelectItems(unit.kind)"
+                  value-key="value"
+                  size="xs"
+                  @update:model-value="
+                    pipelines.setDraftAgentVariantId(unit.index, $event || undefined)
+                  "
+                />
+              </div>
+
               <!-- This step's own output-token ceiling. An OVERRIDE of the workspace's per-kind
                  setting (itself an override of the deployment routing default), so it is
                  advanced-only until a value is pinned; empty inherits. -->

package/app/composables/api/errors.ts

@@ -29,10 +29,17 @@ export class ApiError extends Error {
 
 /** The error envelope every controller emits (`handleError` / contract request-validator). */
 export interface ApiErrorEnvelope {
+  /** The status class — an `ApiErrorCode` from `@cat-factory/contracts`, when recognised. */
   code?: string
   message?: string
   details?: unknown
   issues?: { path?: string; message: string }[]
+  /**
+   * The request's correlation id (`mountRequestLogging` mints or adopts `X-Request-Id` and
+   * `handleError` puts it on EVERY envelope). It is the join between what the user saw and the
+   * one server log line that explains it, so any surface showing failure detail should quote it.
+   */
+  requestId?: string
 }
 
 /** Read the `{ error: {...} }` envelope out of a parsed response body, else undefined. */

package/app/composables/usePipelineErrorToast.spec.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest'
-import { usePipelineErrorToast, parseConflict } from '~/composables/usePipelineErrorToast'
+import {
+  usePipelineErrorToast,
+  parseConflict,
+  describeGenericFailure,
+} from '~/composables/usePipelineErrorToast'
 import { ApiError } from '~/composables/api/errors'
 import en from '../../i18n/locales/en.json'
 
@@ -9,6 +13,9 @@ import en from '../../i18n/locales/en.json'
  * title AND the description (G1) — and only ever shows raw backend prose as a last-resort
  * description (an unmapped reason). These specs assert the KEYS and params a code path
  * resolves (never the English text), so they stay locale-agnostic.
+ *
+ * The same holds for the NON-conflict funnel (G2): the description is keyed off the envelope's
+ * status class and the raw prose is only reachable behind the "Show details" disclosure.
  */
 
 /** Dot-path lookup into the real `en.json`, so `te` mirrors which keys actually ship. */
@@ -21,11 +28,15 @@ function hasKey(path: string): boolean {
 }
 
 let add: ReturnType<typeof vi.fn>
+let update: ReturnType<typeof vi.fn>
 let t: ReturnType<typeof vi.fn>
 let ui: Record<string, ReturnType<typeof vi.fn>>
 
 beforeEach(() => {
-  add = vi.fn()
+  // `add` returns the created toast (Nuxt UI hands back the generated id synchronously), which
+  // the detail disclosure needs in order to `update` the SAME toast in place.
+  add = vi.fn(() => ({ id: 'toast-1' }))
+  update = vi.fn()
   // `t` echoes the key so the toast's title/description IS the resolved key — assert on it.
   t = vi.fn((key: string) => key)
   // The ui-store deep-links a jump action may navigate to (each echoed as a spy).
@@ -36,7 +47,7 @@ beforeEach(() => {
     openModelConfig: vi.fn(),
     openProviderConnection: vi.fn(),
   }
-  vi.stubGlobal('useToast', () => ({ add }))
+  vi.stubGlobal('useToast', () => ({ add, update }))
   vi.stubGlobal('useUiStore', () => ui)
   vi.stubGlobal('useI18n', () => ({ t, te: (key: string) => hasKey(key) }))
 })
@@ -128,10 +139,113 @@ describe('usePipelineErrorToast', () => {
     expect(ui.openAiProviderSetup).toHaveBeenCalledOnce()
   })
 
-  it('uses the fallback title key + raw message for a non-conflict error', () => {
+  it('uses the fallback title key + a TRANSLATED description for a non-conflict error', () => {
+    // G2: the raw JS/backend prose is no longer the description — a bare throw with no HTTP
+    // answer at all is presented as the network case.
     usePipelineErrorToast().present(new Error('boom'), 'errors.action.startFailed')
     const arg = add.mock.calls[0]![0]
     expect(arg.title).toBe('errors.action.startFailed')
-    expect(arg.description).toBe('boom')
+    expect(arg.description).toBe('errors.generic.description.network')
+    expect(arg.description).not.toBe('boom')
+  })
+
+  it('keys the description off the envelope status class, not the backend prose', () => {
+    usePipelineErrorToast().present(
+      new ApiError(503, { error: { code: 'unavailable', message: 'Task sources not configured' } }),
+    )
+    expect(add.mock.calls[0]![0].description).toBe('errors.generic.description.unavailable')
+  })
+
+  it('reveals the raw detail in place when "Show details" is clicked, and makes it sticky', () => {
+    usePipelineErrorToast().present(
+      new ApiError(503, { error: { code: 'unavailable', message: 'Task sources not configured' } }),
+    )
+    const arg = add.mock.calls[0]![0]
+    // Auto-dismissing until the user asks for detail: no `duration` override up front.
+    expect(arg.duration).toBeUndefined()
+    expect(arg.actions[0].label).toBe('errors.generic.showDetail')
+    arg.actions[0].onClick()
+    // Same toast, not a second one; sticky, and the button is dropped so it can't be re-clicked.
+    expect(add).toHaveBeenCalledTimes(1)
+    expect(update).toHaveBeenCalledWith('toast-1', {
+      description: 'Task sources not configured',
+      duration: 0,
+      actions: [],
+    })
+  })
+
+  it('folds validation issues and the requestId into the revealed detail', () => {
+    usePipelineErrorToast().present(
+      new ApiError(400, {
+        error: {
+          code: 'validation',
+          message: 'Request failed validation',
+          requestId: 'req-42',
+          issues: [{ path: 'body.title', message: 'Required' }, { message: 'Unexpected field' }],
+        },
+      }),
+    )
+    const arg = add.mock.calls[0]![0]
+    expect(arg.description).toBe('errors.generic.description.validation')
+    arg.actions[0].onClick()
+    expect(t).toHaveBeenCalledWith('errors.generic.requestId', { id: 'req-42' })
+    // The issues carry the real information on a 422/400 (the message is the fixed
+    // `Request failed validation`), so they must reach the disclosure.
+    expect(update.mock.calls[0]![1].description).toBe(
+      'Request failed validation · body.title: Required, Unexpected field · errors.generic.requestId',
+    )
+  })
+
+  it('offers no disclosure when there is no detail to reveal', () => {
+    usePipelineErrorToast().present(new ApiError(503, { error: { code: 'unavailable' } }))
+    const arg = add.mock.calls[0]![0]
+    // `ApiError` synthesises `Request failed (HTTP 503)` when the envelope carries no message,
+    // so a truly detail-less case is a non-Error throw.
+    expect(arg.description).toBe('errors.generic.description.unavailable')
+    expect(arg.actions[0].label).toBe('errors.generic.showDetail')
+    usePipelineErrorToast().present(null)
+    expect(add.mock.calls[1]![0].actions).toBeUndefined()
+  })
+})
+
+describe('describeGenericFailure', () => {
+  it('maps each known status class to its own description key', () => {
+    for (const code of [
+      'not_found',
+      'validation',
+      'credential_required',
+      'forbidden',
+      'unavailable',
+      'unauthorized',
+      'rate_limited',
+      'internal',
+    ]) {
+      const failure = describeGenericFailure(new ApiError(500, { error: { code } }))
+      expect(failure.descriptionKey).toBe(`errors.generic.description.${code}`)
+      expect(hasKey(failure.descriptionKey)).toBe(true)
+    }
+  })
+
+  it('separates "nothing answered" from "something answered unrecognisably"', () => {
+    // No envelope AND no status: offline / DNS / dropped connection — the remedy is the user's.
+    expect(describeGenericFailure(new Error('Failed to fetch')).descriptionKey).toBe(
+      'errors.generic.description.network',
+    )
+    // A status but not our envelope (an edge 502 page) — the remedy is the server's.
+    expect(
+      describeGenericFailure(new ApiError(502, '<html>bad gateway</html>')).descriptionKey,
+    ).toBe('errors.generic.description.unexpected')
+    // Our envelope, but a code this build does not know.
+    expect(
+      describeGenericFailure(new ApiError(418, { error: { code: 'teapot' } })).descriptionKey,
+    ).toBe('errors.generic.description.unexpected')
+  })
+
+  it('never presents a conflict (parseConflict owns those) but still classifies safely', () => {
+    // `conflict` is deliberately absent from the map, so it reads as an unrecognised code rather
+    // than throwing — the conflict path intercepts it long before this function is reached.
+    expect(
+      describeGenericFailure(new ApiError(409, { error: { code: 'conflict' } })).descriptionKey,
+    ).toBe('errors.generic.description.unexpected')
   })
 })

package/app/composables/usePipelineErrorToast.ts

@@ -11,10 +11,21 @@
  * locale missing the key) and stays untranslated — the contract is "if a server message must be
  * localizable, the backend emits a code and the frontend maps it", not "translate arbitrary server
  * prose on the client".
+ *
+ * G2 closes the same gap for everything that is NOT a 409: this composable is the funnel every
+ * other failure drains into, and it used to show the backend's prose verbatim as the description —
+ * so a non-English user read English, and an internal 500's fixed `Internal server error` was the
+ * whole of what they were told. Those now resolve translated copy from the envelope's STATUS CLASS
+ * (`error.code`, the `ApiErrorCode` union) and keep the untranslated detail — the prose, a
+ * validation 400's `issues`, and the `requestId` an operator can grep — one click away behind
+ * "Show details". Two rules follow from that split: the description says what a user can act on,
+ * the disclosure carries what a user quotes to someone else; and a raw string is never the FIRST
+ * thing shown, however good it is (many of them are — the elaborate remedies this initiative
+ * added — which is exactly why the detail stays reachable rather than being dropped).
  */
 
-import type { ConflictReason } from '@cat-factory/contracts'
-import { apiErrorEnvelope } from './api/errors'
+import type { ApiErrorCode, ConflictReason } from '@cat-factory/contracts'
+import { apiErrorEnvelope, apiErrorStatus } from './api/errors'
 
 /** The parsed shape of a backend conflict (`{ error: { code: 'conflict', details } }`). */
 interface ConflictDetails {
@@ -235,6 +246,87 @@ export function parseConflict(
 /** The non-null parsed shape of a backend conflict, as returned by {@link parseConflict}. */
 type ParsedConflict = NonNullable<ReturnType<typeof parseConflict>>
 
+/**
+ * Generic translated description per STATUS CLASS, for a failure no `reason` code narrows.
+ *
+ * Exhaustive over the wire union (minus `conflict`, which structurally cannot arrive here —
+ * {@link parseConflict} intercepts every envelope carrying that code, so a mapping for it would be
+ * dead copy in ten locales), which makes the `Record` the drift guard: a new `ApiErrorCode` fails
+ * this typecheck until it has wording. The copy is deliberately about the STATUS CLASS and nothing
+ * else — it is what we can say truthfully without having read the specific failure, so it names
+ * the shape of the remedy ("sign in again", "your deployment hasn't wired this", "wait and retry")
+ * and leaves the specifics to the detail disclosure.
+ */
+const GENERIC_DESCRIPTION_KEYS: Record<Exclude<ApiErrorCode, 'conflict'>, string> = {
+  not_found: 'errors.generic.description.not_found',
+  validation: 'errors.generic.description.validation',
+  credential_required: 'errors.generic.description.credential_required',
+  forbidden: 'errors.generic.description.forbidden',
+  unavailable: 'errors.generic.description.unavailable',
+  unauthorized: 'errors.generic.description.unauthorized',
+  rate_limited: 'errors.generic.description.rate_limited',
+  internal: 'errors.generic.description.internal',
+}
+
+/**
+ * The request never reached a server that answered in our envelope shape — offline, DNS, a dropped
+ * connection, CORS. Distinct from {@link UNEXPECTED_DESCRIPTION_KEY} on purpose: this one's remedy
+ * is on the USER's side (check the connection), which is the opposite of "the server is broken".
+ */
+const NETWORK_DESCRIPTION_KEY = 'errors.generic.description.network'
+
+/**
+ * Something answered with an HTTP status but not one of our envelopes (an edge/proxy 502 page, a
+ * gateway timeout), or answered with a `code` this build doesn't know. Reported as an unexpected
+ * SERVER-side failure rather than folded into the network case.
+ */
+const UNEXPECTED_DESCRIPTION_KEY = 'errors.generic.description.unexpected'
+
+/**
+ * A non-conflict failure, split into the part that gets TRANSLATED and the parts that stay raw.
+ * Pure (no i18n, no store) so the classification is unit-testable on its own; the composable
+ * turns it into a toast.
+ */
+export interface GenericFailure {
+  /** i18n key for the translated description shown up front. */
+  descriptionKey: string
+  /** The backend's untranslated prose, when it sent any (absent for a bare network fault). */
+  message: string | null
+  /** `path: message` entries from a request-validation 400, in wire order. */
+  issues: string[]
+  /** The envelope's correlation id, so the user can quote it at whoever reads the logs. */
+  requestId: string | null
+}
+
+/**
+ * Classify a NON-conflict failure for presentation. Never throws and never returns an empty
+ * `descriptionKey`: an error this function cannot recognise at all still gets the network or
+ * unexpected-failure wording, because a toast with no description reads as a successful action.
+ */
+export function describeGenericFailure(error: unknown): GenericFailure {
+  const envelope = apiErrorEnvelope(error)
+  // Read through a widened alias rather than casting the wire string to the union: a `code` we
+  // don't know must resolve to `undefined`, which is exactly what the alias's index signature
+  // says and what a cast would have hidden. The narrow Record above stays the drift guard.
+  const byCode: Readonly<Record<string, string | undefined>> = GENERIC_DESCRIPTION_KEYS
+  const mapped = envelope?.code ? byCode[envelope.code] : undefined
+  // No envelope at all AND no status ⇒ nothing answered; with a status, something did.
+  const unrecognised =
+    !envelope && apiErrorStatus(error) === undefined
+      ? NETWORK_DESCRIPTION_KEY
+      : UNEXPECTED_DESCRIPTION_KEY
+  return {
+    descriptionKey: mapped ?? unrecognised,
+    // `ApiError.message` is the envelope's prose, or a synthesised `Request failed (HTTP n)`; for
+    // a non-API throw it is the JS error text. Either way it is detail, never the headline.
+    message: error instanceof Error ? error.message : error == null ? null : String(error),
+    issues: (envelope?.issues ?? []).map((issue) =>
+      issue.path ? `${issue.path}: ${issue.message}` : issue.message,
+    ),
+    requestId: typeof envelope?.requestId === 'string' ? envelope.requestId : null,
+  }
+}
+
 export function usePipelineErrorToast() {
   const toast = useToast()
   const ui = useUiStore()
@@ -448,6 +540,51 @@ export function usePipelineErrorToast() {
     })
   }
 
+  /**
+   * Everything that is NOT a 409: a translated status-class description, with the raw detail
+   * behind a "Show details" button that swaps it into the same toast (G2).
+   *
+   * The reveal is an UPDATE rather than a second toast so the two readings can't sit on screen
+   * disagreeing, and it makes the toast sticky at the same time — the detail is what someone
+   * copies into a bug report, and a ~5s auto-dismiss takes it away mid-copy. `actions: []` has to
+   * be passed explicitly: `update` merges over the existing toast, so an omitted `actions` would
+   * leave a "Show details" button that is now a no-op.
+   *
+   * No detail worth showing (a network fault with an unhelpful `message` and no correlation id)
+   * ⇒ no button at all, rather than a disclosure that reveals nothing.
+   */
+  function presentGenericFailure(error: unknown, fallbackTitleKey: string): void {
+    const failure = describeGenericFailure(error)
+    const detail = [
+      failure.message,
+      failure.issues.join(', '),
+      failure.requestId ? t('errors.generic.requestId', { id: failure.requestId }) : '',
+    ]
+      .filter((part) => part && part.trim().length > 0)
+      .join(' · ')
+    // No `te` guard: the key comes from a Record exhaustive over the wire union and every entry
+    // ships in the base `en` catalog, so a locale missing it renders English via `fallbackLocale`
+    // (better than the raw prose this replaced) and a bare key can never leak.
+    const added = toast.add({
+      title: t(fallbackTitleKey),
+      description: t(failure.descriptionKey),
+      color: 'error',
+      icon: 'i-lucide-triangle-alert',
+      ...(detail
+        ? {
+            actions: [
+              {
+                label: t('errors.generic.showDetail'),
+                icon: 'i-lucide-info',
+                onClick: () =>
+                  toast.update(added.id, { description: detail, duration: 0, actions: [] }),
+              },
+            ],
+          }
+        : {}),
+    })
+  }
+
   /**
    * Present `error` as a toast. `fallbackTitleKey` is an i18n message key used for
    * non-conflict failures and any conflict reason without a dedicated title.
@@ -459,14 +596,7 @@ export function usePipelineErrorToast() {
       presentMappedConflict(conflict, fallbackTitleKey)
       return
     }
-
-    // Not a conflict (a 4xx/5xx or a network fault) — surface its message plainly.
-    toast.add({
-      title: t(fallbackTitleKey),
-      description: error instanceof Error ? error.message : String(error),
-      color: 'error',
-      icon: 'i-lucide-triangle-alert',
-    })
+    presentGenericFailure(error, fallbackTitleKey)
   }
 
   return { present }

package/app/composables/useStepPromptVariant.spec.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import type { PipelineStep } from '~/types/execution'
+import { useStepPromptVariant } from '~/composables/useStepPromptVariant'
+import en from '../../i18n/locales/en.json'
+
+/**
+ * What the run panels report about a step's agent-kind VARIANT.
+ *
+ * The property under test is that they report what the DISPATCH did, not what the pipeline asked
+ * for. A step can name a variant whose text never reached its prompt — the workspace's own edit of
+ * that kind displaces a variant's replacement, and a variant can be withdrawn mid-run — and a
+ * panel that echoed the selection would confirm a variation that did not run. Each losing
+ * disposition therefore gets its own note.
+ *
+ * Assertions are on KEYS, never English text, so they stay locale-agnostic (the `t` spy echoes
+ * its key) — but every key is checked against the real `en.json` so a typo can't pass.
+ */
+
+function hasKey(path: string): boolean {
+  return (
+    path.split('.').reduce<unknown>((node, seg) => {
+      return node && typeof node === 'object' ? (node as Record<string, unknown>)[seg] : undefined
+    }, en) !== undefined
+  )
+}
+
+beforeEach(() => {
+  vi.stubGlobal('useI18n', () => ({ t: (key: string) => key, te: hasKey }))
+  vi.stubGlobal('useAgentsStore', () => ({
+    variantLabel: (id: string) => (id === 'org:tdd' ? 'TDD-first' : id),
+  }))
+})
+
+function step(promptVariant?: PipelineStep['promptVariant']): PipelineStep {
+  return {
+    agentKind: 'coder',
+    state: 'done',
+    ...(promptVariant ? { promptVariant } : {}),
+  } as PipelineStep
+}
+
+describe('useStepPromptVariant', () => {
+  it('reports nothing for a step that ran the shipped prompt', () => {
+    expect(useStepPromptVariant(() => step()).value).toBeNull()
+  })
+
+  it('reports the label with NO note when the variant fully applied', () => {
+    const variant = useStepPromptVariant(() => step({ id: 'org:tdd', applied: 'full' })).value
+    expect(variant).toEqual({ label: 'TDD-first', note: null })
+  })
+
+  it('reports a note when the workspace prompt displaced the variant entirely', () => {
+    // The case that used to read as a plain confirmation the variant ran.
+    const variant = useStepPromptVariant(() => step({ id: 'org:tdd', applied: 'superseded' })).value
+    expect(variant?.label).toBe('TDD-first')
+    expect(variant?.note).toBe('panels.stepMeta.promptVariantSuperseded')
+    expect(hasKey(variant!.note!)).toBe(true)
+  })
+
+  it('distinguishes a partly-applied variant from a fully displaced one', () => {
+    const note = useStepPromptVariant(() => step({ id: 'org:tdd', applied: 'addition-only' })).value
+      ?.note
+    expect(note).toBe('panels.stepMeta.promptVariantAdditionOnly')
+    expect(hasKey(note!)).toBe(true)
+  })
+
+  it('distinguishes a WITHDRAWN variant, and still names the id it asked for', () => {
+    // The label falls back to the raw id: the step really was configured to run it, so rendering
+    // nothing would show a varied step as if it were the stock kind.
+    const variant = useStepPromptVariant(() => step({ id: 'org:gone', applied: 'withdrawn' })).value
+    expect(variant?.label).toBe('org:gone')
+    expect(variant?.note).toBe('panels.stepMeta.promptVariantWithdrawn')
+    expect(hasKey(variant!.note!)).toBe(true)
+  })
+})

package/app/composables/useStepPromptVariant.ts

@@ -0,0 +1,50 @@
+import { computed, type ComputedRef } from 'vue'
+import type { PipelineStep } from '~/types/execution'
+
+// The deployment-registered agent-kind VARIANT a step ran under, as the run panels report it.
+//
+// Read off the dispatch-time PIN (`step.promptVariant`), never off `stepOptions.agentVariantId`:
+// the option is what the pipeline ASKED for, and the two diverge whenever the workspace has also
+// edited that kind's prompt — the workspace is the narrower tier, so it displaces a variant's own
+// replacement. A panel keyed on the selection would report `Prompt variant: TDD-first` on a step
+// whose prompt contains none of that variant's text, which is worse than saying nothing: it reads
+// as confirmation. So each losing disposition gets its own note rather than being flattened into
+// the label, because they need different fixes (drop the workspace's edit / use an addition
+// instead of a replacement / re-register the variant).
+//
+// Absent before the step dispatches, exactly like `step.model` beside it: what a step RAN under is
+// not a fact until it runs.
+
+/** The dispatch-time pin a panel reads (`PipelineStep.promptVariant`), narrowed to non-null. */
+type PromptVariantPin = NonNullable<PipelineStep['promptVariant']>
+
+/** What a panel shows for a step's variant: the label, plus a note when it did not fully apply. */
+export interface StepPromptVariant {
+  /** The variant's registered label, falling back to its raw id when it is no longer registered. */
+  label: string
+  /** Why the variant's text did not (fully) reach this step's prompt; null when it did. */
+  note: string | null
+}
+
+export function useStepPromptVariant(
+  step: () => PipelineStep,
+): ComputedRef<StepPromptVariant | null> {
+  const agents = useAgentsStore()
+  const { t } = useI18n()
+  // One STATIC literal `t()` per member of the closed disposition union, not a key assembled from
+  // `applied`: the typed-message-key check and the catalog drift guard both read literal keys, and
+  // a runtime-assembled one is invisible to them. The `Record` type is the exhaustiveness half —
+  // a new disposition fails to compile until it has copy.
+  const NOTE: Record<PromptVariantPin['applied'], () => string | null> = {
+    full: () => null,
+    'addition-only': () => t('panels.stepMeta.promptVariantAdditionOnly'),
+    superseded: () => t('panels.stepMeta.promptVariantSuperseded'),
+    withdrawn: () => t('panels.stepMeta.promptVariantWithdrawn'),
+  }
+
+  return computed(() => {
+    const pin = step().promptVariant
+    if (!pin) return null
+    return { label: agents.variantLabel(pin.id), note: NOTE[pin.applied]() }
+  })
+}

package/app/stores/agents.spec.ts

@@ -101,4 +101,34 @@ describe('agents store — custom-kind catalog (slice 2)', () => {
     expect(created.category).toBeUndefined() // lands in the palette "custom" bucket
     expect(agentKindMeta(created.kind).label).toBe('My Agent')
   })
+
+  it('holds agent-kind VARIANTS apart from the palette catalog', () => {
+    // A variant is a per-step OPTION on a kind that is already in the palette, not a kind of its
+    // own — so it must never reach `archetypes` / `agentKindMeta`, or it would become placeable.
+    const agents = useAgentsStore()
+    agents.hydrateVariants([
+      { id: 'org:tdd', baseKind: 'coder', label: 'TDD-first' },
+      { id: 'org:sec', baseKind: 'pr-reviewer', label: 'Security lens' },
+    ])
+    expect(agents.variantsForKind('coder').map((v) => v.id)).toEqual(['org:tdd'])
+    expect(agents.variantsForKind('architect')).toEqual([])
+    expect(agents.archetypes.some((a) => a.kind === 'org:tdd')).toBe(false)
+    expect(isKnownAgentKind('org:tdd')).toBe(false)
+  })
+
+  it('falls back to a variant id the deployment no longer registers', () => {
+    // A step really is configured to run that variant; rendering nothing would show a varied step
+    // as if it were the stock kind.
+    const agents = useAgentsStore()
+    agents.hydrateVariants([{ id: 'org:tdd', baseKind: 'coder', label: 'TDD-first' }])
+    expect(agents.variantLabel('org:tdd')).toBe('TDD-first')
+    expect(agents.variantLabel('org:withdrawn')).toBe('org:withdrawn')
+  })
+
+  it('swaps the variant list wholesale on re-hydrate (per-workspace snapshot)', () => {
+    const agents = useAgentsStore()
+    agents.hydrateVariants([{ id: 'org:tdd', baseKind: 'coder', label: 'TDD-first' }])
+    agents.hydrateVariants([])
+    expect(agents.variantsForKind('coder')).toEqual([])
+  })
 })