@cat-factory/app 0.195.2 → 0.196.1

package/app/components/panels/ResultWindowShell.logic.ts

@@ -0,0 +1,31 @@
+// The result-window width vocabulary, extracted from `ResultWindowShell.vue` so it can be
+// asserted (see `ResultWindowShell.logic.spec.ts`, which pins every window's bucket against a
+// table naming its reason — the shape `nav-contributions.spec.ts` uses for the advanced-nav set).
+//
+// WHICH bucket a window takes, and the reading-measure obligation `full` carries, are documented
+// on the shell's `width` prop — that is what a window author reads. This module owns only the
+// vocabulary and its class mapping.
+
+/** Card width buckets — see `ResultWindowShell.vue`'s `width` prop for what picks `full`. */
+export type ResultWindowWidth = '3xl' | '4xl' | '5xl' | 'full'
+
+/**
+ * The bucket → cap mapping. `full` is deliberately `max-w-none` rather than a bigger number:
+ * the panel's `w-full` then spans the backdrop, which the variant insets by one gutter (`m-4`
+ * stretched, `p-4` centered), so the window fills the screen and still reads as a window rather
+ * than a repaint of the app. A `Record` over the union, so a new bucket fails to compile until
+ * it is mapped.
+ */
+export const RESULT_WINDOW_WIDTH_CLASS: Record<ResultWindowWidth, string> = {
+  '3xl': 'max-w-3xl',
+  '4xl': 'max-w-4xl',
+  '5xl': 'max-w-5xl',
+  full: 'max-w-none',
+}
+
+/**
+ * The reading measure a `full` window puts on a run of continuous prose — the step reader's own
+ * (`AgentStepDetail`, `mx-auto max-w-3xl` over the same 13px `.reader-prose`), so the surfaces
+ * cannot drift into two opinions about how wide prose should be.
+ */
+export const PROSE_MEASURE_CLASS = 'max-w-3xl'

package/app/components/panels/ResultWindowShell.vue

@@ -26,6 +26,10 @@ import StepRestartControl from '~/components/panels/StepRestartControl.vue'
 import StepEffortReport from '~/components/panels/StepEffortReport.vue'
 import StepValidationReport from '~/components/panels/StepValidationReport.vue'
 import { effortBand, effortHint } from '~/utils/effort'
+import {
+  RESULT_WINDOW_WIDTH_CLASS,
+  type ResultWindowWidth,
+} from '~/components/panels/ResultWindowShell.logic'
 
 /** A pipeline step reference — passed by step-result windows to surface the shared
  *  "restart from here" control. `StepRestartControl` self-hides for an off-path open
@@ -42,8 +46,38 @@ const props = withDefaults(
     /** Header title (the accessible dialog name) + optional secondary line. */
     title: string
     subtitle?: string
-    /** Card width bucket + backdrop layout (the two pre-slice-5 chrome variants). */
-    width?: '3xl' | '4xl' | '5xl'
+    /**
+     * Card width bucket + backdrop layout (the two pre-slice-5 chrome variants).
+     *
+     * `full` is the REVIEW/READING bucket: the panel takes the whole viewport minus the
+     * shell's own gutter, the shape the full-bleed step reader (`AgentStepDetail`) already
+     * has. It is for a window whose body lays out in COLUMNS — rails plus a fluid main
+     * column — where the width buys visible layout: the outline and the review rail stop
+     * competing with the document, a findings list stops wrapping every card, a diff or a
+     * results table stops scrolling sideways. A window that is one column of prose or a
+     * short verdict keeps a bucket: stretching two paragraphs across an ultrawide reads
+     * worse, not better.
+     *
+     * The obligation that comes with it: CONTINUOUS PROSE inside a `full` window carries its
+     * own reading measure (`PROSE_MEASURE_CLASS`, the step reader's own, over the same 13px
+     * `.reader-prose`), or the width lands as 200-character lines.
+     *
+     * The unit that obligation attaches to is the PARAGRAPH, not the section — which is the
+     * distinction to get right, because "a findings list reads better at the full span" is
+     * true of the LIST and false of the prose inside each row. A list's rows, badge rows,
+     * control rows, tables, Gherkin blocks, log tails and inputs all take the span; a
+     * finding's detail, a recorded answer, an investigator's justification and a summary
+     * paragraph are prose wherever they sit, and take the measure. Sizing by section is how a
+     * card whose answer control is STACKED under its question — every finding card here —
+     * ends up arguing that its question is "beside" something and keeping 200-character lines.
+     *
+     * What `full` costs: click-outside effectively goes, since the backdrop is then only the
+     * shell's own gutter. That is the same trade the full-bleed reader already makes (it has
+     * no backdrop close at all), and Escape plus the header's close button — the two paths a
+     * keyboard and a pointer user actually reach for — are untouched. A window that wants
+     * click-outside to stay hittable is a window that should have kept a bucket.
+     */
+    width?: ResultWindowWidth
     variant?: 'stretch' | 'centered'
     /** Provide on step-result windows to show the shared restart control; omit on gates
      *  and block-keyed windows (no restart mid-gate / pre-run). */
@@ -119,18 +153,13 @@ const chipClass = computed(() =>
   effortReport.value ? CHIP_CLASS[effortBand(effortReport.value.difficulty)] : '',
 )
 
-const WIDTH: Record<'3xl' | '4xl' | '5xl', string> = {
-  '3xl': 'max-w-3xl',
-  '4xl': 'max-w-4xl',
-  '5xl': 'max-w-5xl',
-}
 const backdropClass = computed(() => [
   'fixed inset-0 z-50 flex max-h-[100dvh] justify-center bg-slate-950/70 backdrop-blur-sm',
   props.variant === 'centered' ? 'items-center p-4' : 'items-stretch',
 ])
 const panelClass = computed(() => [
   'flex w-full flex-col overflow-hidden rounded-2xl border border-slate-800 bg-slate-900 shadow-2xl',
-  WIDTH[props.width],
+  RESULT_WINDOW_WIDTH_CLASS[props.width],
   props.variant === 'centered' ? 'max-h-[90dvh]' : 'm-4',
 ])
 </script>

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/components/prReview/PrReviewWindow.vue

@@ -266,7 +266,7 @@ async function onDismiss(id: string): Promise<void> {
     icon-class="bg-indigo-500/15 text-indigo-300"
     :title="block ? t('prReview.titleWithBlock', { title: block.title }) : t('prReview.title')"
     :subtitle="t('prReview.subtitle')"
-    width="3xl"
+    width="full"
     testid="pr-review-window"
     @close="close"
   >
@@ -525,10 +525,11 @@ async function onDismiss(id: string): Promise<void> {
             </p>
           </div>
 
-          <!-- The reviewer's overall assessment. -->
+          <!-- The reviewer's overall assessment. Prose, so it takes the reading measure (see the
+               shell's `width` prop) — this window is `full`-width. -->
           <p
             v-if="state?.summary"
-            class="mb-3 rounded-md bg-slate-800/50 px-3 py-2 text-[12px] text-slate-300"
+            class="mb-3 max-w-3xl rounded-md bg-slate-800/50 px-3 py-2 text-[12px] text-slate-300"
           >
             <span class="text-slate-500">{{ t('prReview.summaryLabel') }}</span>
             {{ state.summary }}
@@ -579,7 +580,7 @@ async function onDismiss(id: string): Promise<void> {
               <h3 class="mb-1.5 text-[11px] font-semibold uppercase tracking-wide text-slate-400">
                 {{ g.title }}
               </h3>
-              <p v-if="g.rationale" class="mb-1.5 text-[11px] text-slate-500">
+              <p v-if="g.rationale" class="mb-1.5 max-w-3xl text-[11px] text-slate-500">
                 {{ g.rationale }}
               </p>
               <article
@@ -672,15 +673,22 @@ async function onDismiss(id: string): Promise<void> {
                         · {{ t('prReview.line', { line: f.line }) }}</template
                       >
                     </p>
+                    <!-- The reviewer's prose — what the finding is, what to do about it, and the
+                         investigator's verdict below. Each takes the reading measure even though
+                         the card around it takes the span (see the shell's `width` prop: the unit
+                         is the paragraph, not the section). This window went from the NARROWEST
+                         bucket to `full`, so these are the three paragraphs the width would
+                         otherwise have stretched furthest; the path/line row, the badges and the
+                         per-finding actions are what it is actually for. -->
                     <p
-                      class="mt-1 whitespace-pre-wrap text-[12px] text-slate-300"
+                      class="mt-1 max-w-3xl whitespace-pre-wrap text-[12px] text-slate-300"
                       :class="isRetracted(f) ? 'line-through' : ''"
                     >
                       {{ f.detail }}
                     </p>
                     <p
                       v-if="f.suggestedFix"
-                      class="mt-1 whitespace-pre-wrap rounded-md bg-slate-800/50 px-2 py-1 text-[11px] text-slate-300"
+                      class="mt-1 max-w-3xl whitespace-pre-wrap rounded-md bg-slate-800/50 px-2 py-1 text-[11px] text-slate-300"
                     >
                       <span class="text-slate-500">{{ t('prReview.suggestedFix') }}</span>
                       {{ f.suggestedFix }}
@@ -691,7 +699,7 @@ async function onDismiss(id: string): Promise<void> {
                     <p
                       v-if="f.challenge?.justification"
                       data-testid="pr-review-finding-justification"
-                      class="mt-1.5 whitespace-pre-wrap rounded-md px-2 py-1 text-[11px]"
+                      class="mt-1.5 max-w-3xl whitespace-pre-wrap rounded-md px-2 py-1 text-[11px]"
                       :class="
                         isRetracted(f)
                           ? 'bg-rose-500/10 text-rose-200'

package/app/components/requirements/RequirementsReviewWindow.vue

@@ -653,7 +653,7 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
     :subtitle="block?.title"
     :step-ref="{ instanceId, stepIndex }"
     variant="centered"
-    width="5xl"
+    width="full"
     @close="close"
   >
     <template v-if="review" #header-extras>
@@ -796,7 +796,11 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
                         {{ STATUS_LABELS[item.status] }}
                       </UBadge>
                     </div>
-                    <p class="mt-1 whitespace-pre-line text-sm text-slate-400">
+                    <!-- The reviewer's question is prose, so it takes the measure even though the
+                         card around it takes the span (see the shell's `width` prop: the unit is
+                         the paragraph, not the section). The badge row above and the mode buttons
+                         and textarea below are what the full width is actually for. -->
+                    <p class="mt-1 max-w-3xl whitespace-pre-line text-sm text-slate-400">
                       {{ item.detail }}
                     </p>
 
@@ -804,7 +808,7 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
                            ones the answer lives in the textarea below, seeded from the reply) -->
                     <div
                       v-if="item.reply && item.status !== 'open' && item.status !== 'answered'"
-                      class="mt-2 rounded-md border-s-2 border-slate-700 bg-slate-950/40 px-3 py-1.5 text-sm text-slate-300"
+                      class="mt-2 max-w-3xl rounded-md border-s-2 border-slate-700 bg-slate-950/40 px-3 py-1.5 text-sm text-slate-300"
                     >
                       <span class="text-[10px] uppercase tracking-wide text-slate-500">
                         {{ t('requirements.answerLabel') }}
@@ -925,7 +929,9 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
                             >
                               {{ GROUNDING_LABELS[rec.groundedIn] }}
                             </UBadge>
-                            <p class="mt-1 whitespace-pre-line text-sm text-slate-300">
+                            <!-- The Writer's suggested answer — agent prose, so it takes the
+                                 measure like the finding's own question above it. -->
+                            <p class="mt-1 max-w-3xl whitespace-pre-line text-sm text-slate-300">
                               {{ rec.recommendedText }}
                             </p>
                             <div class="mt-2 flex flex-wrap items-center gap-2">
@@ -1037,7 +1043,11 @@ async function resolveExceeded(choice: 'extra-round' | 'proceed' | 'stop-reset')
                 }}
               </span>
             </button>
-            <div v-show="!docCollapsed">
+            <!-- The same reading measure the findings' own prose takes above (see the shell's
+                 `width` prop): the window is `full`-width now, and this is continuous prose that
+                 would otherwise run to 200-character lines. Left-aligned rather than centred, so
+                 it starts where every finding above it starts. -->
+            <div v-show="!docCollapsed" class="max-w-3xl">
               <div v-for="s in outline.sections" :key="s.id" class="mb-2">
                 <button
                   v-if="s.title"

package/app/components/spec/ServiceSpecWindow.vue

@@ -185,7 +185,7 @@ function kindLabel(item: RequirementItem): string {
     :title="t('spec.title')"
     :subtitle="block ? spec?.service || block.title : undefined"
     variant="centered"
-    width="5xl"
+    width="full"
     @close="close"
   >
     <!-- view toggle: Gherkin only when the spec (and its feature files) are on main -->
@@ -318,7 +318,10 @@ function kindLabel(item: RequirementItem): string {
         <!-- service overview -->
         <template v-if="selected === null">
           <h2 class="text-lg font-semibold text-white">{{ spec?.service }}</h2>
-          <p v-if="spec?.summary" class="mt-2 whitespace-pre-line text-sm text-slate-300">
+          <!-- The service's own prose, so it takes the reading measure the shell's `full` width
+               obliges (see the `width` prop). The requirement rows and Gherkin blocks below keep
+               the full span — they are structure, not paragraphs. -->
+          <p v-if="spec?.summary" class="mt-2 max-w-3xl whitespace-pre-line text-sm text-slate-300">
             {{ spec.summary }}
           </p>
           <p v-else class="mt-2 text-sm text-slate-500">{{ t('spec.noSummary') }}</p>
@@ -352,7 +355,7 @@ function kindLabel(item: RequirementItem): string {
             {{ selectedModule?.name }}
           </div>
           <h2 class="text-lg font-semibold text-white">{{ selectedGroup.name }}</h2>
-          <p v-if="selectedGroup.summary" class="mt-1 text-sm text-slate-400">
+          <p v-if="selectedGroup.summary" class="mt-1 max-w-3xl text-sm text-slate-400">
             {{ selectedGroup.summary }}
           </p>
 
@@ -500,7 +503,7 @@ function kindLabel(item: RequirementItem): string {
                 <UIcon name="i-lucide-shield-check" class="h-3.5 w-3.5" />
                 {{ t('spec.domainRules') }}
               </div>
-              <ul class="space-y-1.5">
+              <ul class="max-w-3xl space-y-1.5">
                 <li
                   v-for="rule in selectedGroup.rules ?? []"
                   :key="rule.id"

package/app/components/testing/TestReportWindow.vue

@@ -313,7 +313,7 @@ const GROUP_STATUS_META: Record<ScenarioGroup['status'], { icon: string; text: s
     :title="headerTitle"
     :subtitle="t('testing.subtitle')"
     :step-ref="{ instanceId, stepIndex }"
-    width="5xl"
+    width="full"
     testid="tester-report-window"
     @close="close"
   >
@@ -489,7 +489,7 @@ const GROUP_STATUS_META: Record<ScenarioGroup['status'], { icon: string; text: s
                 :icon="a.outcome === 'completed' ? 'i-lucide-wrench' : 'i-lucide-circle-x'"
                 :icon-class="a.outcome === 'completed' ? 'text-amber-300' : 'text-rose-400'"
               />
-              <p v-if="a.summary" class="mt-1 text-[12px] leading-snug text-slate-400">
+              <p v-if="a.summary" class="mt-1 max-w-3xl text-[12px] leading-snug text-slate-400">
                 {{ a.summary }}
               </p>
               <div v-if="a.concerns && a.concerns.length" class="mt-1.5">
@@ -607,8 +607,13 @@ const GROUP_STATUS_META: Record<ScenarioGroup['status'], { icon: string; text: s
         </div>
 
         <template v-else>
-          <!-- Summary -->
-          <p v-if="report.summary" class="mb-4 text-[13px] leading-relaxed text-slate-300">
+          <!-- Summary — the tester's own prose, so it takes the reading measure the shell's `full`
+               width obliges (see the `width` prop). The scenario rows and log tails below keep the
+               full span. -->
+          <p
+            v-if="report.summary"
+            class="mb-4 max-w-3xl text-[13px] leading-relaxed text-slate-300"
+          >
             {{ report.summary }}
           </p>
 
@@ -675,7 +680,7 @@ const GROUP_STATUS_META: Record<ScenarioGroup['status'], { icon: string; text: s
                   />
                   <div class="min-w-0">
                     <span class="text-[13px] text-slate-200">{{ o.name }}</span>
-                    <p v-if="o.detail" class="text-[12px] leading-snug text-slate-400">
+                    <p v-if="o.detail" class="max-w-3xl text-[12px] leading-snug text-slate-400">
                       {{ o.detail }}
                     </p>
                   </div>
@@ -705,7 +710,7 @@ const GROUP_STATUS_META: Record<ScenarioGroup['status'], { icon: string; text: s
                         {{ SEVERITY_LABELS[c.severity] }}
                       </span>
                     </div>
-                    <p v-if="c.detail" class="text-[12px] leading-snug text-slate-400">
+                    <p v-if="c.detail" class="max-w-3xl text-[12px] leading-snug text-slate-400">
                       {{ c.detail }}
                     </p>
                   </div>

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')
   })
 })