@cat-factory/app 0.39.0 → 0.41.0

package/app/components/layout/NotificationsInbox.vue

@@ -36,6 +36,9 @@ const META: Record<Notification['type'], { icon: string; color: Accent; action:
   // Clicking the title opens the human-testing window for the task (see `reveal`); "act" just
   // marks it read (the gate is resolved in that window — confirm / request a fix — not here).
   human_test_ready: { icon: 'i-lucide-user-check', color: 'primary', action: 'Mark read' },
+  // Clicking the title opens the visual-confirmation window for the task (see `reveal`); "act"
+  // just marks it read (the gate is resolved in that window — approve / request a fix — not here).
+  visual_confirmation_ready: { icon: 'i-lucide-camera', color: 'primary', action: 'Mark read' },
   // Clicking the title opens the task's gate window (where the human can request a freeform
   // fix); "act" just marks it read (approval happens on GitHub, not here).
   human_review: { icon: 'i-lucide-users', color: 'primary', action: 'Mark read' },
@@ -87,6 +90,7 @@ function reveal(n: Notification) {
   else if (n.type === 'clarity_review') ui.openClarityReview(n.blockId)
   else if (n.type === 'decision_required') revealDecision(n)
   else if (n.type === 'human_test_ready') revealHumanTest(n)
+  else if (n.type === 'visual_confirmation_ready') revealVisualConfirm(n)
   else if (n.type === 'human_review') revealHumanReview(n)
   else if (n.type === 'followup_pending') revealFollowUps(n)
   else ui.select(n.blockId)
@@ -128,6 +132,21 @@ function revealHumanTest(n: Notification) {
   else if (n.blockId) ui.select(n.blockId)
 }
 
+/**
+ * Open the visual-confirmation window for a parked `visual-confirmation` gate: find the run's
+ * parked step and open it through the universal step dispatch (its archetype declares the
+ * `visual-confirm` result view). Falls back to focusing the block.
+ */
+function revealVisualConfirm(n: Notification) {
+  const instance = n.executionId ? execution.getInstance(n.executionId) : undefined
+  const idx =
+    instance?.steps.findIndex(
+      (s) => s.agentKind === 'visual-confirmation' && s.state === 'waiting_decision',
+    ) ?? -1
+  if (instance && idx >= 0) ui.openStepDetail(instance.id, idx)
+  else if (n.blockId) ui.select(n.blockId)
+}
+
 /**
  * Open the decision surface for a parked iteration-cap run: find the run's step that is
  * waiting on a human and open it through the universal step dispatch — which routes a

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/panels/StepResultViewHost.vue

@@ -16,6 +16,7 @@ import ClarityReviewWindow from '~/components/clarity/ClarityReviewWindow.vue'
 import BrainstormWindow from '~/components/brainstorm/BrainstormWindow.vue'
 import TestReportWindow from '~/components/testing/TestReportWindow.vue'
 import HumanTestWindow from '~/components/humanTest/HumanTestWindow.vue'
+import VisualConfirmationWindow from '~/components/visualConfirm/VisualConfirmationWindow.vue'
 import GateResultView from '~/components/gates/GateResultView.vue'
 import ConsensusSessionWindow from '~/components/consensus/ConsensusSessionWindow.vue'
 import GenericStructuredResultView from '~/components/panels/GenericStructuredResultView.vue'
@@ -32,6 +33,8 @@ const STEP_RESULT_VIEWS: Record<string, Component> = {
   tester: TestReportWindow,
   // The human-testing gate: env URL + confirm / request-fix / pull-main / recreate / destroy.
   'human-test': HumanTestWindow,
+  // The visual-confirmation gate: actual-vs-reference screenshot gallery + approve / request-fix.
+  'visual-confirm': VisualConfirmationWindow,
   // Shared by both polling gates (`ci` + `conflicts`); the window branches on agentKind.
   gate: GateResultView,
   // Opened for any step that ran the consensus mechanism (routed in `ui.dispatchStepView`).

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/components/settings/WorkspaceSettingsPanel.vue

@@ -68,6 +68,7 @@ const draft = reactive({
   taskLimitShared: 5 as number,
   perType: {} as Record<CreateTaskType, number>,
   storeAgentContext: true,
+  artifactRetentionDays: 14,
   kaizenEnabled: true,
   // Budget: empty string ⇒ "use the built-in default" (null on the wire).
   spendCurrency: '',
@@ -82,6 +83,7 @@ function hydrate() {
   const pt = s.taskLimitPerType ?? {}
   for (const t of TASK_TYPES) draft.perType[t] = pt[t] ?? 3
   draft.storeAgentContext = s.storeAgentContext
+  draft.artifactRetentionDays = s.artifactRetentionDays
   draft.kaizenEnabled = s.kaizenEnabled
   draft.spendCurrency = s.spendCurrency ?? ''
   draft.spendMonthlyLimit = s.spendMonthlyLimit == null ? '' : String(s.spendMonthlyLimit)
@@ -111,6 +113,7 @@ async function save() {
             )
           : null,
       storeAgentContext: draft.storeAgentContext,
+      artifactRetentionDays: draft.artifactRetentionDays,
       kaizenEnabled: draft.kaizenEnabled,
     })
     toast.add({ title: 'Settings saved', icon: 'i-lucide-check', color: 'success' })
@@ -242,6 +245,28 @@ async function saveBudget() {
               </label>
             </section>
 
+            <!-- Visual-confirmation artifact retention -->
+            <section class="space-y-2">
+              <h3 class="text-sm font-semibold text-slate-200">Screenshot retention</h3>
+              <p class="text-[11px] text-slate-400">
+                How long to keep the UI tester’s captured screenshots and the reference design
+                images they’re reviewed against (the visual-confirmation gate). A daily cleanup job
+                deletes both the image bytes and their metadata once they age past this window.
+              </p>
+              <label class="block w-48">
+                <span class="mb-1 block text-[10px] uppercase tracking-wide text-slate-500">
+                  Retention (days)
+                </span>
+                <UInput
+                  v-model.number="draft.artifactRetentionDays"
+                  type="number"
+                  :min="1"
+                  :max="3650"
+                  size="sm"
+                />
+              </label>
+            </section>
+
             <!-- Kaizen agent -->
             <section class="space-y-2">
               <h3 class="text-sm font-semibold text-slate-200">Kaizen agent</h3>

package/app/components/slack/SlackPanel.vue

@@ -28,6 +28,7 @@ const ROUTABLE: { type: NotificationType; label: string }[] = [
   { type: 'clarity_review', label: 'Clarity review' },
   { type: 'release_regression', label: 'Release regression' },
   { type: 'human_test_ready', label: 'Ready for human testing' },
+  { type: 'visual_confirmation_ready', label: 'Ready for visual confirmation' },
 ]
 
 /** Notification-role options for a mapped member (drives who gets @-mentioned). */
@@ -45,6 +46,7 @@ const routes = reactive<Record<NotificationType, SlackRoute>>({
   // In-app only (not in ROUTABLE), but the map is exhaustive over the type.
   decision_required: { enabled: false, channel: '' },
   human_test_ready: { enabled: false, channel: '' },
+  visual_confirmation_ready: { enabled: false, channel: '' },
   human_review: { enabled: false, channel: '' },
   followup_pending: { enabled: false, channel: '' },
 })

package/app/components/visualConfirm/VisualConfirmationWindow.vue

@@ -0,0 +1,357 @@
+<script setup lang="ts">
+// Visual-confirmation gate window — the dedicated surface for a `visual-confirmation` step
+// (opened via the universal result-view host, the same seam the human-test / tester windows
+// use). It reads the gate's live state off the execution step (`step.visualConfirm`, pushed
+// over the stream), renders each captured screenshot next to its reference design (paired by
+// view), and drives the human actions: approve (advance), request a fix from findings (the
+// Tester's fixer), or recapture (refresh the pairs). It also lets the human upload reference
+// design images for the task.
+import { onUnmounted, reactive, ref, watch } from 'vue'
+import type { VisualConfirmStepState } from '~/types/execution'
+import StepRunMeta from '~/components/panels/StepRunMeta.vue'
+
+const board = useBoardStore()
+const execution = useExecutionStore()
+const visualConfirm = useVisualConfirmStore()
+
+// Release the cached screenshot/reference object URLs when the window goes away, so the
+// (potentially large) blob bytes don't linger in memory for the rest of the session.
+onUnmounted(() => visualConfirm.revokeBlobs())
+
+const { open, blockId, instanceId, stepIndex, close } = useResultView('visual-confirm')
+const block = computed(() => (blockId.value ? board.getBlock(blockId.value) : undefined))
+
+const instance = computed(() =>
+  instanceId.value === null ? null : (execution.getInstance(instanceId.value) ?? null),
+)
+const step = computed(() => {
+  if (instance.value === null || stepIndex.value === null) return null
+  return instance.value.steps[stepIndex.value] ?? null
+})
+const vc = computed<VisualConfirmStepState | null>(() => step.value?.visualConfirm ?? null)
+const phase = computed(() => vc.value?.phase ?? null)
+const pairs = computed(() => vc.value?.pairs ?? [])
+const busy = computed(() => (blockId.value ? visualConfirm.isBusy(blockId.value) : false))
+const awaitingHuman = computed(() => phase.value === 'awaiting_human')
+const working = computed(() => phase.value === 'fixing')
+
+const PHASE_LABEL: Record<NonNullable<VisualConfirmStepState['phase']>, string> = {
+  awaiting_human: 'Awaiting your review',
+  fixing: 'Fixer is addressing your findings…',
+  approved: 'Approved',
+}
+
+// Resolve each pair's artifact ids to object URLs for the <img>s (cached in the store).
+const urls = reactive<Record<string, string>>({})
+async function resolveUrl(id: string | null | undefined) {
+  if (!id || urls[id]) return
+  const url = await visualConfirm.blobUrl(id)
+  if (url) urls[id] = url
+}
+watch(
+  pairs,
+  (next) => {
+    for (const p of next) {
+      void resolveUrl(p.actualArtifactId)
+      void resolveUrl(p.referenceArtifactId)
+    }
+  },
+  { immediate: true },
+)
+
+const findings = ref('')
+const showFindings = ref(false)
+
+// When the gate flags its screenshots as an unreliable basis (`degradedReason` — no capture
+// happened, a fix failed, or a fix landed AFTER these shots were taken), approving is no longer
+// a safe one-click: require the human to explicitly acknowledge they reviewed the change another
+// way (or recaptured) first. Re-armed whenever the reason changes so a fresh warning re-gates.
+const ackDegraded = ref(false)
+watch(
+  () => vc.value?.degradedReason ?? null,
+  () => {
+    ackDegraded.value = false
+  },
+)
+const needsAck = computed(() => !!vc.value?.degradedReason)
+const canApprove = computed(
+  () => awaitingHuman.value && !busy.value && (!needsAck.value || ackDegraded.value),
+)
+
+async function approve() {
+  if (!blockId.value || !canApprove.value) return
+  await visualConfirm.approve(blockId.value)
+  close()
+}
+async function submitFix() {
+  if (!blockId.value || !findings.value.trim()) return
+  await visualConfirm.requestFix(blockId.value, findings.value.trim())
+  findings.value = ''
+  showFindings.value = false
+}
+async function recapture() {
+  if (!blockId.value) return
+  await visualConfirm.recapture(blockId.value)
+}
+
+// Reference upload.
+const uploadView = ref('')
+const fileInput = ref<HTMLInputElement | null>(null)
+async function onFilePicked(e: Event) {
+  const input = e.target as HTMLInputElement
+  const file = input.files?.[0]
+  if (!file || !blockId.value) return
+  await visualConfirm.uploadReference(blockId.value, file, uploadView.value.trim())
+  uploadView.value = ''
+  if (fileInput.value) fileInput.value.value = ''
+}
+</script>
+
+<template>
+  <Teleport to="body">
+    <div
+      v-if="open"
+      class="fixed inset-0 z-50 flex items-stretch justify-center bg-slate-950/70 backdrop-blur-sm"
+      @click.self="close"
+    >
+      <div
+        class="m-4 flex w-full max-w-4xl flex-col overflow-hidden rounded-2xl border border-slate-800 bg-slate-900 shadow-2xl"
+      >
+        <header class="flex items-center gap-3 border-b border-slate-800 px-5 py-3">
+          <span
+            class="flex h-8 w-8 items-center justify-center rounded-lg bg-amber-500/15 text-amber-300"
+          >
+            <UIcon name="i-lucide-image-play" class="h-4 w-4" />
+          </span>
+          <div class="min-w-0 flex-1">
+            <h2 class="truncate text-sm font-semibold text-slate-100">
+              Visual confirmation{{ block ? ` — ${block.title}` : '' }}
+            </h2>
+            <p class="truncate text-[11px] text-slate-400">
+              {{ phase ? PHASE_LABEL[phase] : 'Review the UI against the reference designs' }}
+            </p>
+          </div>
+          <button
+            class="rounded-md p-1.5 text-slate-400 hover:bg-slate-800 hover:text-slate-200"
+            @click="close"
+          >
+            <UIcon name="i-lucide-x" class="h-4 w-4" />
+          </button>
+        </header>
+
+        <div class="flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto px-5 py-4">
+          <div
+            v-if="!vc"
+            class="flex flex-col items-center justify-center gap-2 py-10 text-center text-slate-400"
+          >
+            <UIcon name="i-lucide-image-play" class="h-8 w-8 opacity-40" />
+            <p class="text-sm">This step hasn't started yet.</p>
+          </div>
+
+          <template v-else>
+            <p
+              v-if="vc.degradedReason"
+              class="rounded-lg border border-amber-700/40 bg-amber-500/5 px-3 py-2 text-[12px] text-amber-300/90"
+            >
+              {{ vc.degradedReason }}
+            </p>
+
+            <p
+              v-if="working"
+              class="flex items-center gap-2 rounded-lg border border-slate-800 bg-slate-950/40 px-3 py-2 text-[12px] text-slate-300"
+            >
+              <UIcon name="i-lucide-loader" class="h-3.5 w-3.5 animate-spin text-amber-300" />
+              {{ phase ? PHASE_LABEL[phase] : '' }}
+            </p>
+
+            <!-- Actual-vs-reference gallery -->
+            <section v-if="pairs.length" class="space-y-4">
+              <div
+                v-for="(p, i) in pairs"
+                :key="i"
+                class="rounded-lg border border-slate-800 bg-slate-900/60 p-3"
+              >
+                <h3 class="mb-2 text-[12px] font-semibold text-slate-200">{{ p.view }}</h3>
+                <div class="grid grid-cols-2 gap-3">
+                  <figure class="space-y-1">
+                    <figcaption class="text-[10px] uppercase tracking-wide text-slate-500">
+                      Actual
+                    </figcaption>
+                    <img
+                      v-if="p.actualArtifactId && urls[p.actualArtifactId]"
+                      :src="urls[p.actualArtifactId]"
+                      :alt="`${p.view} (actual)`"
+                      class="w-full rounded border border-slate-800"
+                    />
+                    <div
+                      v-else
+                      class="flex h-32 items-center justify-center rounded border border-dashed border-slate-700 text-[11px] text-slate-600"
+                    >
+                      {{ p.actualArtifactId ? 'Loading…' : 'Not captured' }}
+                    </div>
+                  </figure>
+                  <figure class="space-y-1">
+                    <figcaption class="text-[10px] uppercase tracking-wide text-slate-500">
+                      Reference
+                    </figcaption>
+                    <img
+                      v-if="p.referenceArtifactId && urls[p.referenceArtifactId]"
+                      :src="urls[p.referenceArtifactId]"
+                      :alt="`${p.view} (reference)`"
+                      class="w-full rounded border border-slate-800"
+                    />
+                    <div
+                      v-else
+                      class="flex h-32 items-center justify-center rounded border border-dashed border-slate-700 text-[11px] text-slate-600"
+                    >
+                      {{ p.referenceArtifactId ? 'Loading…' : 'No reference' }}
+                    </div>
+                  </figure>
+                </div>
+              </div>
+            </section>
+            <p v-else class="text-[12px] italic text-slate-500">
+              No screenshots were captured — review the change manually.
+            </p>
+
+            <!-- Reference upload -->
+            <section class="rounded-lg border border-slate-800 bg-slate-900/60 p-3">
+              <h3 class="mb-2 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
+                Upload a reference design
+              </h3>
+              <div class="flex flex-wrap items-center gap-2">
+                <input
+                  v-model="uploadView"
+                  placeholder="View name (e.g. login)"
+                  class="rounded-md border border-slate-700 bg-slate-950 px-2 py-1 text-[12px] text-slate-200 placeholder:text-slate-600"
+                />
+                <input
+                  ref="fileInput"
+                  type="file"
+                  accept="image/png,image/jpeg"
+                  :disabled="busy"
+                  class="text-[12px] text-slate-300 file:mr-2 file:rounded file:border-0 file:bg-slate-800 file:px-2 file:py-1 file:text-slate-200"
+                  @change="onFilePicked"
+                />
+              </div>
+            </section>
+
+            <!-- Request fix -->
+            <section
+              v-if="awaitingHuman"
+              class="rounded-lg border border-slate-800 bg-slate-900/60 p-3"
+            >
+              <div class="flex items-center justify-between">
+                <h3 class="text-[11px] font-semibold uppercase tracking-wide text-slate-500">
+                  Needs changes?
+                </h3>
+                <button
+                  class="text-[12px] text-slate-400 hover:text-slate-200"
+                  @click="showFindings = !showFindings"
+                >
+                  {{ showFindings ? 'Cancel' : 'Request a fix' }}
+                </button>
+              </div>
+              <div v-if="showFindings" class="mt-2 space-y-2">
+                <textarea
+                  v-model="findings"
+                  rows="4"
+                  placeholder="Describe what looks wrong — the Fixer agent gets this as context."
+                  class="w-full rounded-md border border-slate-700 bg-slate-950 px-3 py-2 text-[13px] text-slate-200 placeholder:text-slate-600 focus:border-amber-500 focus:outline-none"
+                />
+                <UButton
+                  size="sm"
+                  color="warning"
+                  icon="i-lucide-wrench"
+                  :loading="busy"
+                  :disabled="busy || !findings.trim()"
+                  @click="submitFix"
+                >
+                  Send to Fixer
+                </UButton>
+              </div>
+            </section>
+
+            <!-- Rounds history -->
+            <section
+              v-if="vc.rounds && vc.rounds.length"
+              class="rounded-lg border border-slate-800 bg-slate-900/60 p-3"
+            >
+              <h3 class="mb-2 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
+                History ({{ vc.attempts }} round{{ vc.attempts === 1 ? '' : 's' }})
+              </h3>
+              <ol class="space-y-2">
+                <li v-for="(r, i) in vc.rounds" :key="i" class="flex items-start gap-2 text-[12px]">
+                  <UIcon
+                    name="i-lucide-wrench"
+                    class="mt-0.5 h-3.5 w-3.5 shrink-0 text-slate-400"
+                  />
+                  <div class="min-w-0 flex-1">
+                    <span class="text-slate-200">Fix requested</span>
+                    <span
+                      class="ml-1.5 rounded px-1 text-[10px] uppercase"
+                      :class="
+                        r.outcome === 'completed'
+                          ? 'bg-emerald-500/15 text-emerald-300'
+                          : r.outcome === 'failed'
+                            ? 'bg-rose-500/15 text-rose-300'
+                            : 'bg-slate-500/15 text-slate-300'
+                      "
+                    >
+                      {{ r.outcome ?? 'in progress' }}
+                    </span>
+                    <p v-if="r.findings" class="leading-snug text-slate-400">{{ r.findings }}</p>
+                  </div>
+                </li>
+              </ol>
+            </section>
+          </template>
+        </div>
+
+        <footer
+          v-if="vc"
+          class="flex items-center justify-between gap-3 border-t border-slate-800 px-5 py-3"
+        >
+          <StepRunMeta
+            v-if="step"
+            :step="step"
+            :instance-id="instanceId ?? undefined"
+            :step-number="stepIndex === null ? undefined : stepIndex + 1"
+            :total-steps="instance?.steps.length"
+            :run-failed="instance?.status === 'failed'"
+            :failure-at="instance?.failure?.occurredAt"
+          />
+          <div class="flex items-center gap-2">
+            <label
+              v-if="awaitingHuman && needsAck"
+              class="flex items-center gap-1.5 text-[11px] text-amber-300/90"
+            >
+              <input v-model="ackDegraded" type="checkbox" class="accent-amber-500" />
+              I've reviewed this manually
+            </label>
+            <UButton
+              size="sm"
+              variant="soft"
+              color="neutral"
+              icon="i-lucide-refresh-cw"
+              :loading="busy"
+              :disabled="busy || !awaitingHuman"
+              @click="recapture"
+            >
+              Recapture
+            </UButton>
+            <UButton
+              color="primary"
+              icon="i-lucide-circle-check"
+              :loading="busy"
+              :disabled="!canApprove"
+              @click="approve"
+            >
+              Approve — continue
+            </UButton>
+          </div>
+        </footer>
+      </div>
+    </div>
+  </Teleport>
+</template>

package/app/composables/api/visualConfirm.ts

@@ -0,0 +1,60 @@
+import {
+  approveVisualConfirmContract,
+  recaptureVisualConfirmContract,
+  requestVisualConfirmFixContract,
+} from '@cat-factory/contracts'
+import type { ApiContext } from './context'
+
+/**
+ * The visual-confirmation gate's run-driving actions + the artifact helpers its window needs
+ * (upload a reference design image, fetch a stored blob as an object URL). The action calls
+ * return the updated execution instance (the gate state rides on its current step and also
+ * arrives live via the execution stream). The blob/upload helpers use the authed `$fetch`
+ * (the artifact ingest/blob endpoints are raw, not contract-modelled, because they carry binary).
+ */
+export function visualConfirmApi({ send, ws, http }: ApiContext) {
+  return {
+    // Approve the reviewed screenshots: advance the pipeline.
+    approveVisualConfirm: (workspaceId: string, blockId: string) =>
+      send(approveVisualConfirmContract, { pathPrefix: ws(workspaceId), pathParams: { blockId } }),
+
+    // Submit findings and request a fix (dispatches the Tester's fixer, then re-parks).
+    requestVisualConfirmFix: (workspaceId: string, blockId: string, findings: string) =>
+      send(requestVisualConfirmFixContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { blockId },
+        body: { findings },
+      }),
+
+    // Refresh the actual-vs-reference pairs from the latest UI-tester report.
+    recaptureVisualConfirm: (workspaceId: string, blockId: string) =>
+      send(recaptureVisualConfirmContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { blockId },
+      }),
+
+    // Upload a reference design image for a block (kind=reference), tagged with its view name.
+    uploadReferenceArtifact: async (
+      workspaceId: string,
+      blockId: string,
+      file: File,
+      view: string,
+    ): Promise<{ artifact: { id: string } }> => {
+      const form = new FormData()
+      form.append('file', file)
+      form.append('kind', 'reference')
+      form.append('blockId', blockId)
+      if (view) form.append('view', view)
+      return http(`${ws(workspaceId)}/artifacts`, { method: 'POST', body: form })
+    },
+
+    // Fetch a stored artifact's bytes and turn them into an object URL for an <img>.
+    fetchArtifactBlobUrl: async (workspaceId: string, artifactId: string): Promise<string> => {
+      const blob: Blob = await http(
+        `${ws(workspaceId)}/artifacts/${encodeURIComponent(artifactId)}/blob`,
+        { method: 'GET', responseType: 'blob' },
+      )
+      return URL.createObjectURL(blob)
+    },
+  }
+}

package/app/composables/useApi.ts

@@ -12,6 +12,7 @@ import { fragmentsApi } from './api/fragments'
 import { githubApi } from './api/github'
 import { humanReviewApi } from './api/humanReview'
 import { humanTestApi } from './api/humanTest'
+import { visualConfirmApi } from './api/visualConfirm'
 import { kaizenApi } from './api/kaizen'
 import { localSettingsApi } from './api/localSettings'
 import { modelsApi } from './api/models'
@@ -98,6 +99,7 @@ export function useApi() {
     ...reviewsApi(ctx),
     ...followUpsApi(ctx),
     ...humanTestApi(ctx),
+    ...visualConfirmApi(ctx),
     ...humanReviewApi(ctx),
     ...kaizenApi(ctx),
     ...localSettingsApi(ctx),

package/app/composables/usePipelineHealth.spec.ts

@@ -49,7 +49,9 @@ const BUILTIN_SEED_KINDS = [
   'reviewer',
   'blueprints',
   'mocker',
-  'tester',
+  'tester-api',
+  'tester-ui',
+  'visual-confirmation',
   'conflicts',
   'ci',
   'merger',
@@ -86,7 +88,7 @@ describe('usePipelineHealth', () => {
         'coder',
         'reviewer',
         'blueprints',
-        'tester',
+        'tester-api',
         'conflicts',
         'ci',
         'merger',

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/visualConfirm.ts

@@ -0,0 +1,92 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import { useExecutionStore } from '~/stores/execution'
+import { useWorkspaceStore } from '~/stores/workspace'
+
+/**
+ * Visual-confirmation gate actions. The gate's live state rides on its execution step
+ * (`step.visualConfirm`) and arrives via the execution stream, so this store holds NO gate
+ * state — it only drives the actions (approve / request a fix / recapture), uploads reference
+ * design images, and resolves stored artifacts into object URLs for the gallery. A per-block
+ * `busy` flag lets the window disable its controls while an action is in flight.
+ */
+export const useVisualConfirmStore = defineStore('visualConfirm', () => {
+  const api = useApi()
+  const ws = useWorkspaceStore()
+  const execution = useExecutionStore()
+
+  const busy = ref<Set<string>>(new Set())
+  /** Cache of artifactId → object URL, so the gallery doesn't re-fetch the same blob. */
+  const blobUrls = ref<Map<string, string>>(new Map())
+
+  function isBusy(blockId: string): boolean {
+    return busy.value.has(blockId)
+  }
+
+  async function run(blockId: string, action: () => Promise<unknown>): Promise<void> {
+    const next = new Set(busy.value)
+    next.add(blockId)
+    busy.value = next
+    try {
+      const instance = await action()
+      if (instance && typeof instance === 'object' && 'steps' in instance) {
+        execution.upsert(instance as Parameters<typeof execution.upsert>[0])
+      }
+    } finally {
+      const after = new Set(busy.value)
+      after.delete(blockId)
+      busy.value = after
+    }
+  }
+
+  /** Approve the reviewed screenshots: advance the pipeline. */
+  function approve(blockId: string): Promise<void> {
+    return run(blockId, () => api.approveVisualConfirm(ws.requireId(), blockId))
+  }
+
+  /** Submit findings and request a fix. */
+  function requestFix(blockId: string, findings: string): Promise<void> {
+    return run(blockId, () => api.requestVisualConfirmFix(ws.requireId(), blockId, findings))
+  }
+
+  /** Refresh the actual-vs-reference pairs from the latest UI-tester report. */
+  function recapture(blockId: string): Promise<void> {
+    return run(blockId, () => api.recaptureVisualConfirm(ws.requireId(), blockId))
+  }
+
+  /** Upload a reference design image for a block, tagged with the view it depicts. */
+  function uploadReference(blockId: string, file: File, view: string): Promise<void> {
+    return run(blockId, () => api.uploadReferenceArtifact(ws.requireId(), blockId, file, view))
+  }
+
+  /** Resolve a stored artifact to an object URL (cached). Returns null on failure. */
+  async function blobUrl(artifactId: string): Promise<string | null> {
+    const cached = blobUrls.value.get(artifactId)
+    if (cached) return cached
+    try {
+      const url = await api.fetchArtifactBlobUrl(ws.requireId(), artifactId)
+      blobUrls.value.set(artifactId, url)
+      return url
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Release every cached object URL and clear the cache. `URL.createObjectURL` holds the
+   * blob in memory until explicitly revoked, so the gate window calls this on unmount to
+   * avoid leaking the (potentially large) screenshot bytes for the session's lifetime.
+   */
+  function revokeBlobs(): void {
+    for (const url of blobUrls.value.values()) {
+      try {
+        URL.revokeObjectURL(url)
+      } catch {
+        // Ignore — a URL already revoked / unsupported environment.
+      }
+    }
+    blobUrls.value = new Map()
+  }
+
+  return { isBusy, approve, requestFix, recapture, uploadReference, blobUrl, revokeBlobs }
+})

package/app/stores/workspaceSettings.ts

@@ -10,6 +10,7 @@ const DEFAULTS: WorkspaceSettings = {
   taskLimitShared: null,
   taskLimitPerType: null,
   storeAgentContext: true,
+  artifactRetentionDays: 14,
   kaizenEnabled: true,
   delegateAgentsToRunnerPool: false,
   delegateTestEnvToProvider: false,

package/app/types/execution.ts

@@ -37,6 +37,9 @@ export type {
   RunEnvironment,
   HumanTestRound,
   HumanTestStepState,
+  VisualConfirmStepState,
+  VisualConfirmPair,
+  VisualConfirmRound,
   ExecutionInstance,
   // The historical frontend name for a per-block review comment is the contract's
   // StepReviewComment; the env-status union is the contract's EnvironmentStatus.

package/app/utils/catalog.spec.ts

@@ -21,7 +21,8 @@ const AGENT_KINDS: AgentKind[] = [
   'architect',
   'researcher',
   'coder',
-  'tester',
+  'tester-api',
+  'tester-ui',
   'reviewer',
   'documenter',
   'integrator',
@@ -32,6 +33,7 @@ const AGENT_KINDS: AgentKind[] = [
   'business-documenter',
   'business-reviewer',
   'human-test',
+  'visual-confirmation',
 ]
 const BLOCK_TYPES: BlockType[] = [
   'frontend',

package/app/utils/catalog.ts

@@ -134,8 +134,8 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     description: 'Builds WireMock mocks for external services and wires them into local/CI runs.',
   },
   {
-    kind: 'tester',
-    label: 'Tester',
+    kind: 'tester-api',
+    label: 'API Tester',
     icon: 'i-lucide-flask-conical',
     color: '#fbbf24',
     category: 'test',
@@ -144,6 +144,17 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     // concerns tree) instead of the generic prose step-detail panel.
     resultView: 'tester',
   },
+  {
+    kind: 'tester-ui',
+    label: 'UI Tester',
+    icon: 'i-lucide-camera',
+    color: '#fbbf24',
+    category: 'test',
+    description:
+      'Drives a real browser through the new UI, captures a screenshot of each view, and reports outcomes.',
+    // Same structured test-report window; it additionally renders the captured screenshots.
+    resultView: 'tester',
+  },
   {
     kind: 'playwright',
     label: 'Acceptance Test Author',
@@ -165,6 +176,18 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     // recreate / destroy) instead of the generic prose step-detail panel.
     resultView: 'human-test',
   },
+  {
+    kind: 'visual-confirmation',
+    label: 'Visual Confirmation',
+    icon: 'i-lucide-image-play',
+    color: '#f59e0b',
+    category: 'test',
+    description:
+      'Pauses for a person to review the UI tester’s screenshots against the uploaded reference designs — approve, or request a fix from findings — before the pipeline continues.',
+    // Opens the dedicated visual-confirmation window (actual-vs-reference gallery + approve /
+    // request-fix / recapture) instead of the generic prose step-detail panel.
+    resultView: 'visual-confirm',
+  },
   {
     kind: 'documenter',
     label: 'Documenter',

package/app/utils/pipelineRender.ts

@@ -83,7 +83,7 @@ export const COMPANION_STATE_META: Record<
  * via `step.gate`, which all share the same possible/running/completed/skipped shape.
  */
 export function gateCompanionFor(step: PipelineStep, runFailed = false): GateCompanion | null {
-  if (step.agentKind === 'tester') {
+  if (step.agentKind === 'tester-api' || step.agentKind === 'tester-ui') {
     const attempts = step.test?.attempts ?? 0
     if (step.state === 'done') {
       // The gate finished: it ran the fixer iff it ever dispatched one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.39.0",
+  "version": "0.41.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.38.0"
+    "@cat-factory/contracts": "0.40.0"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.1",