@cat-factory/app 0.21.0 → 0.22.0

package/app/components/humanTest/HumanTestWindow.vue

@@ -0,0 +1,327 @@
+<script setup lang="ts">
+// Human-testing gate window — the dedicated surface for a `human-test` step (opened via the
+// universal result-view host, the same seam the tester / requirements review use). It reads
+// the gate's live state straight off the execution step (`step.humanTest`, pushed over the
+// stream), surfaces the ephemeral environment URL, and drives the human actions: confirm
+// (pass + tear down + advance), request a fix from findings (the Tester's fixer), pull latest
+// main into the branch + redeploy (conflict → conflict-resolver), recreate, or destroy the env.
+import type { HumanTestEnvironmentStatus, HumanTestStepState } from '~/types/execution'
+import StepRunMeta from '~/components/panels/StepRunMeta.vue'
+
+const board = useBoardStore()
+const execution = useExecutionStore()
+const humanTest = useHumanTestStore()
+
+// Shared seam contract (open/blockId/close + Escape). No `onOpen` loader: the gate state
+// rides on the execution step, pushed over the stream.
+const { open, blockId, instanceId, stepIndex, close } = useResultView('human-test')
+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 ht = computed<HumanTestStepState | null>(() => step.value?.humanTest ?? null)
+const env = computed(() => ht.value?.environment ?? null)
+const phase = computed(() => ht.value?.phase ?? null)
+const busy = computed(() => (blockId.value ? humanTest.isBusy(blockId.value) : false))
+
+/** Whether the human can act right now (parked awaiting their input, not mid-helper/provision). */
+const awaitingHuman = computed(() => phase.value === 'awaiting_human')
+const working = computed(
+  () =>
+    phase.value === 'provisioning' ||
+    phase.value === 'fixing' ||
+    phase.value === 'resolving_conflicts',
+)
+
+const ENV_STATUS_META: Record<HumanTestEnvironmentStatus, { label: string; color: string }> = {
+  provisioning: { label: 'Provisioning…', color: 'text-amber-300' },
+  ready: { label: 'Ready', color: 'text-emerald-300' },
+  failed: { label: 'Failed', color: 'text-rose-300' },
+  expired: { label: 'Expired', color: 'text-slate-400' },
+  tearing_down: { label: 'Tearing down…', color: 'text-slate-400' },
+  torn_down: { label: 'Destroyed', color: 'text-slate-400' },
+}
+
+const PHASE_LABEL: Record<NonNullable<HumanTestStepState['phase']>, string> = {
+  provisioning: 'Provisioning environment…',
+  awaiting_human: 'Awaiting your validation',
+  fixing: 'Fixer is addressing your findings…',
+  resolving_conflicts: 'Resolving conflicts with main…',
+  passed: 'Passed',
+}
+
+const findings = ref('')
+const showFindings = ref(false)
+
+async function confirm() {
+  if (!blockId.value) return
+  await humanTest.confirm(blockId.value)
+  close()
+}
+async function submitFix() {
+  if (!blockId.value || !findings.value.trim()) return
+  await humanTest.requestFix(blockId.value, findings.value.trim())
+  findings.value = ''
+  showFindings.value = false
+}
+async function pullMain() {
+  if (!blockId.value) return
+  await humanTest.pullMain(blockId.value)
+}
+async function recreate() {
+  if (!blockId.value) return
+  await humanTest.recreateEnv(blockId.value)
+}
+async function destroy() {
+  if (!blockId.value) return
+  await humanTest.destroyEnv(blockId.value)
+}
+
+/** Env actions need a provider (an env is/was present, or it's provisioning) — disabled in degraded mode. */
+const envActionsEnabled = computed(() => env.value !== null && env.value !== undefined)
+
+// The env-management actions are only valid in specific phases; mirror the backend's preconditions
+// so the UI never dispatches an action that would 409 ("No human-test gate is currently awaiting
+// input"). Recreate / pull-main route through `findParked` (parked awaiting the human); destroy
+// routes through `findActive`, which also tolerates an in-flight `provisioning` env so a human can
+// cancel a slow/stuck provision.
+const canManageEnv = computed(() => awaitingHuman.value)
+const canDestroy = computed(
+  () => envActionsEnabled.value && (awaitingHuman.value || phase.value === 'provisioning'),
+)
+</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-3xl flex-col overflow-hidden rounded-2xl border border-slate-800 bg-slate-900 shadow-2xl"
+      >
+        <!-- Header -->
+        <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-user-check" class="h-4 w-4" />
+          </span>
+          <div class="min-w-0 flex-1">
+            <h2 class="truncate text-sm font-semibold text-slate-100">
+              Human testing{{ block ? ` — ${block.title}` : '' }}
+            </h2>
+            <p class="truncate text-[11px] text-slate-400">
+              {{ phase ? PHASE_LABEL[phase] : 'Validate the change in a live environment' }}
+            </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="!ht"
+            class="flex flex-col items-center justify-center gap-2 py-10 text-center text-slate-400"
+          >
+            <UIcon name="i-lucide-user-check" class="h-8 w-8 opacity-40" />
+            <p class="text-sm">This step hasn't started yet.</p>
+          </div>
+
+          <template v-else>
+            <!-- Environment -->
+            <section class="rounded-lg border border-slate-800 bg-slate-900/60 p-4">
+              <h3 class="mb-2 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
+                Ephemeral environment
+              </h3>
+              <div v-if="env" class="space-y-2">
+                <div class="flex items-center gap-2 text-[13px]">
+                  <UIcon
+                    name="i-lucide-circle-dot"
+                    class="h-3.5 w-3.5"
+                    :class="ENV_STATUS_META[env.status].color"
+                  />
+                  <span :class="ENV_STATUS_META[env.status].color">{{
+                    ENV_STATUS_META[env.status].label
+                  }}</span>
+                </div>
+                <a
+                  v-if="env.url"
+                  :href="env.url"
+                  target="_blank"
+                  rel="noopener"
+                  class="inline-flex items-center gap-1.5 break-all text-[13px] text-sky-300 hover:underline"
+                >
+                  <UIcon name="i-lucide-external-link" class="h-3.5 w-3.5 shrink-0" />
+                  {{ env.url }}
+                </a>
+                <p v-else class="text-[12px] italic text-slate-500">No URL yet.</p>
+                <p v-if="env.expiresAt" class="text-[11px] text-slate-500">
+                  Expires {{ new Date(env.expiresAt).toLocaleString() }}
+                </p>
+              </div>
+              <p v-else class="text-[12px] text-amber-300/90">
+                {{ ht.degradedReason ?? 'No live environment.' }}
+              </p>
+              <p v-if="env && ht.degradedReason" class="mt-2 text-[12px] text-amber-300/90">
+                {{ ht.degradedReason }}
+              </p>
+
+              <!-- Env management -->
+              <div class="mt-3 flex flex-wrap gap-2">
+                <UButton
+                  size="xs"
+                  variant="soft"
+                  color="neutral"
+                  icon="i-lucide-refresh-cw"
+                  :loading="busy"
+                  :disabled="busy || !canManageEnv"
+                  @click="recreate"
+                >
+                  Recreate
+                </UButton>
+                <UButton
+                  size="xs"
+                  variant="soft"
+                  color="neutral"
+                  icon="i-lucide-trash-2"
+                  :disabled="busy || !canDestroy"
+                  @click="destroy"
+                >
+                  Destroy
+                </UButton>
+                <UButton
+                  size="xs"
+                  variant="soft"
+                  color="neutral"
+                  icon="i-lucide-git-merge"
+                  :loading="busy"
+                  :disabled="busy || !canManageEnv"
+                  @click="pullMain"
+                >
+                  Pull main + redeploy
+                </UButton>
+              </div>
+            </section>
+
+            <!-- Working state -->
+            <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>
+
+            <!-- Findings / fix -->
+            <section
+              v-if="awaitingHuman"
+              class="rounded-lg border border-slate-800 bg-slate-900/60 p-4"
+            >
+              <div class="flex items-center justify-between">
+                <h3 class="text-[11px] font-semibold uppercase tracking-wide text-slate-500">
+                  Found a problem?
+                </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 went wrong — the Fixer agent gets this as context, then the environment is rebuilt for re-testing."
+                  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="ht.rounds && ht.rounds.length"
+              class="rounded-lg border border-slate-800 bg-slate-900/60 p-4"
+            >
+              <h3 class="mb-2 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
+                History ({{ ht.attempts }} round{{ ht.attempts === 1 ? '' : 's' }})
+              </h3>
+              <ol class="space-y-2">
+                <li v-for="(r, i) in ht.rounds" :key="i" class="flex items-start gap-2 text-[12px]">
+                  <UIcon
+                    :name="r.kind === 'fix' ? 'i-lucide-wrench' : 'i-lucide-git-merge'"
+                    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">{{
+                      r.kind === 'fix' ? 'Fix requested' : 'Pulled main'
+                    }}</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: the primary confirm action -->
+        <footer
+          v-if="ht"
+          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"
+          />
+          <UButton
+            color="primary"
+            icon="i-lucide-circle-check"
+            :loading="busy"
+            :disabled="busy || !awaitingHuman"
+            @click="confirm"
+          >
+            Looks good — continue
+          </UButton>
+        </footer>
+      </div>
+    </div>
+  </Teleport>
+</template>

package/app/components/layout/NotificationsInbox.vue

@@ -33,6 +33,9 @@ const META: Record<Notification['type'], { icon: string; color: Accent; action:
   // with the iteration-cap prompt; requirements → the review window); "act" just marks it
   // read (the decision itself is resolved in that surface, not here).
   decision_required: { icon: 'i-lucide-circle-help', color: 'warning', action: 'Mark read' },
+  // 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' },
 }
 
 /** A notification the escalation sweep has flagged as overdue (waited past the threshold). */
@@ -77,9 +80,25 @@ function reveal(n: Notification) {
   if (n.type === 'requirement_review') ui.openRequirementReview(n.blockId)
   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 ui.select(n.blockId)
 }
 
+/**
+ * Open the human-testing window for a parked `human-test` gate: find the run's parked
+ * human-test step and open it through the universal step dispatch (its archetype declares
+ * the `human-test` result view). Falls back to focusing the block.
+ */
+function revealHumanTest(n: Notification) {
+  const instance = n.executionId ? execution.getInstance(n.executionId) : undefined
+  const idx =
+    instance?.steps.findIndex(
+      (s) => s.agentKind === 'human-test' && 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/panels/StepResultViewHost.vue

@@ -14,6 +14,7 @@ import { computed, type Component } from 'vue'
 import RequirementsReviewWindow from '~/components/requirements/RequirementsReviewWindow.vue'
 import ClarityReviewWindow from '~/components/clarity/ClarityReviewWindow.vue'
 import TestReportWindow from '~/components/testing/TestReportWindow.vue'
+import HumanTestWindow from '~/components/humanTest/HumanTestWindow.vue'
 import GateResultView from '~/components/gates/GateResultView.vue'
 import ConsensusSessionWindow from '~/components/consensus/ConsensusSessionWindow.vue'
 import GenericStructuredResultView from '~/components/panels/GenericStructuredResultView.vue'
@@ -25,6 +26,8 @@ const STEP_RESULT_VIEWS: Record<string, Component> = {
   'requirements-review': RequirementsReviewWindow,
   'clarity-review': ClarityReviewWindow,
   tester: TestReportWindow,
+  // The human-testing gate: env URL + confirm / request-fix / pull-main / recreate / destroy.
+  'human-test': HumanTestWindow,
   // 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/slack/SlackPanel.vue

@@ -25,6 +25,7 @@ const ROUTABLE: { type: NotificationType; label: string }[] = [
   { type: 'requirement_review', label: 'Requirement review' },
   { type: 'clarity_review', label: 'Clarity review' },
   { type: 'release_regression', label: 'Release regression' },
+  { type: 'human_test_ready', label: 'Ready for human testing' },
 ]
 
 /** Notification-role options for a mapped member (drives who gets @-mentioned). */
@@ -41,6 +42,7 @@ const routes = reactive<Record<NotificationType, SlackRoute>>({
   release_regression: { enabled: false, channel: '' },
   // 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: '' },
 })
 const mentionsEnabled = ref(false)
 const mapping = ref<SlackMemberMappingEntry[]>([])

package/app/composables/api/humanTest.ts

@@ -0,0 +1,37 @@
+import type { ExecutionInstance } from '~/types/domain'
+import type { ApiContext } from './context'
+
+/**
+ * The human-testing gate's run-driving actions. Each acts on the block's parked `human-test`
+ * step and returns the updated execution instance (the gate state rides on its current step,
+ * and also arrives live via the execution stream).
+ */
+export function humanTestApi({ http, ws }: ApiContext) {
+  const base = (workspaceId: string, blockId: string) =>
+    `${ws(workspaceId)}/blocks/${encodeURIComponent(blockId)}/human-test`
+
+  return {
+    // Confirm the change works: tear the env down and advance the pipeline.
+    confirmHumanTest: (workspaceId: string, blockId: string) =>
+      http<ExecutionInstance>(`${base(workspaceId, blockId)}/confirm`, { method: 'POST' }),
+
+    // Submit findings and request a fix (dispatches the Tester's fixer, then rebuilds the env).
+    requestHumanTestFix: (workspaceId: string, blockId: string, findings: string) =>
+      http<ExecutionInstance>(`${base(workspaceId, blockId)}/request-fix`, {
+        method: 'POST',
+        body: { findings },
+      }),
+
+    // Pull latest main into the PR branch + redeploy (conflict → conflict-resolver).
+    pullMainHumanTest: (workspaceId: string, blockId: string) =>
+      http<ExecutionInstance>(`${base(workspaceId, blockId)}/pull-main`, { method: 'POST' }),
+
+    // Rebuild the ephemeral environment on demand.
+    recreateHumanTestEnv: (workspaceId: string, blockId: string) =>
+      http<ExecutionInstance>(`${base(workspaceId, blockId)}/recreate-env`, { method: 'POST' }),
+
+    // Destroy the ephemeral environment on demand (the run stays parked).
+    destroyHumanTestEnv: (workspaceId: string, blockId: string) =>
+      http<ExecutionInstance>(`${base(workspaceId, blockId)}/destroy-env`, { method: 'POST' }),
+  }
+}

package/app/composables/useApi.ts

@@ -8,6 +8,7 @@ import { documentsApi } from './api/documents'
 import { executionApi } from './api/execution'
 import { fragmentsApi } from './api/fragments'
 import { githubApi } from './api/github'
+import { humanTestApi } from './api/humanTest'
 import { modelsApi } from './api/models'
 import { notificationsApi } from './api/notifications'
 import { presetsApi } from './api/presets'
@@ -80,6 +81,7 @@ export function useApi() {
     ...documentsApi(ctx),
     ...tasksApi(ctx),
     ...reviewsApi(ctx),
+    ...humanTestApi(ctx),
     ...specApi(ctx),
     ...notificationsApi(ctx),
     ...presetsApi(ctx),

package/app/stores/humanTest.ts

@@ -0,0 +1,70 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import { useExecutionStore } from '~/stores/execution'
+import { useWorkspaceStore } from '~/stores/workspace'
+
+/**
+ * Human-testing gate actions. The gate's live state rides on its execution step
+ * (`step.humanTest`) and arrives via the execution stream, so this store holds NO gate
+ * state — it only drives the actions (confirm / request a fix / pull main / recreate /
+ * destroy) and patches the execution store from each response. A per-block `busy` flag lets
+ * the window disable its controls while an action is in flight. Per-workspace; nothing
+ * persisted client-side.
+ */
+export const useHumanTestStore = defineStore('humanTest', () => {
+  const api = useApi()
+  const ws = useWorkspaceStore()
+  const execution = useExecutionStore()
+
+  /** Block ids with an action currently in flight (the window disables its buttons). */
+  const busy = ref<Set<string>>(new Set())
+
+  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()
+      // The action returns the updated run; patch the store so the window reflects it
+      // immediately (the stream also pushes it, but this avoids a flash of stale state).
+      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
+    }
+  }
+
+  /** Confirm the change works: tear the env down and advance the pipeline. */
+  function confirm(blockId: string): Promise<void> {
+    return run(blockId, () => api.confirmHumanTest(ws.requireId(), blockId))
+  }
+
+  /** Submit findings and request a fix. */
+  function requestFix(blockId: string, findings: string): Promise<void> {
+    return run(blockId, () => api.requestHumanTestFix(ws.requireId(), blockId, findings))
+  }
+
+  /** Pull latest main into the branch + redeploy. */
+  function pullMain(blockId: string): Promise<void> {
+    return run(blockId, () => api.pullMainHumanTest(ws.requireId(), blockId))
+  }
+
+  /** Rebuild the ephemeral environment. */
+  function recreateEnv(blockId: string): Promise<void> {
+    return run(blockId, () => api.recreateHumanTestEnv(ws.requireId(), blockId))
+  }
+
+  /** Destroy the ephemeral environment (the run stays parked). */
+  function destroyEnv(blockId: string): Promise<void> {
+    return run(blockId, () => api.destroyHumanTestEnv(ws.requireId(), blockId))
+  }
+
+  return { isBusy, confirm, requestFix, pullMain, recreateEnv, destroyEnv }
+})

package/app/types/domain.ts

@@ -296,6 +296,10 @@ export type AgentKind =
   // read-only `bug-investigator` container agent enriches it into a prose report.
   | 'clarity-review'
   | 'bug-investigator'
+  // The human-testing gate: spins up an ephemeral environment and PARKS for a person to
+  // validate the change in a live URL, dispatching the Tester's `fixer` (from findings) or
+  // the `conflict-resolver` (on a conflicting pull-main) on demand. Opens its own window.
+  | 'human-test'
 
 /** A draggable agent definition shown in the agent palette. */
 /** Palette grouping for the agent archetypes (collapsible sections in the builder). */

package/app/types/execution.ts

@@ -333,6 +333,12 @@ export interface PipelineStep {
    * on non-gate steps. Mirrors `gateStepStateSchema`.
    */
   gate?: GateStepState | null
+  /**
+   * Live state of a `human-test` gate (ephemeral env + human validation loop): the phase,
+   * the live environment, the fix/pull-main round history, and any degraded-mode reason.
+   * Absent on non-human-test steps. Mirrors `humanTestStepStateSchema`.
+   */
+  humanTest?: HumanTestStepState | null
 }
 
 /** One failing CI check the gate's precheck saw (mirrors `gateFailingCheckSchema`). */
@@ -387,6 +393,53 @@ export interface TesterStepState {
   lastReport?: TestReport | null
 }
 
+/** The lifecycle status of an ephemeral environment (mirrors `environmentStatusSchema`). */
+export type HumanTestEnvironmentStatus =
+  | 'provisioning'
+  | 'ready'
+  | 'failed'
+  | 'expired'
+  | 'tearing_down'
+  | 'torn_down'
+
+/** The compact env view a `human-test` gate carries (mirrors `humanTestEnvironmentSchema`). */
+export interface HumanTestEnvironment {
+  id: string
+  url: string | null
+  status: HumanTestEnvironmentStatus
+  expiresAt?: number | null
+}
+
+/** One fix / pull-main round on a `human-test` gate (mirrors `humanTestRoundSchema`). */
+export interface HumanTestRound {
+  kind: 'fix' | 'pull-main'
+  /** The human's findings (fix), or a one-line note (pull-main). */
+  findings: string
+  /** The helper container kind this round dispatched (`fixer` / `conflict-resolver`). */
+  helperKind: string
+  jobId?: string | null
+  /** How the helper ended once its job settled; absent while in flight. */
+  outcome?: 'completed' | 'failed' | null
+  /** epoch ms the round opened */
+  at: number
+}
+
+/** Live state of a `human-test` gate (mirrors `humanTestStepStateSchema`). */
+export interface HumanTestStepState {
+  phase: 'provisioning' | 'awaiting_human' | 'fixing' | 'resolving_conflicts' | 'passed'
+  /** the live ephemeral environment (null in degraded manual mode / after destroy) */
+  environment?: HumanTestEnvironment | null
+  /** why no env was auto-provisioned (degraded manual mode), for the window to explain */
+  degradedReason?: string | null
+  /** how many helper (fixer / conflict-resolver) attempts have been dispatched so far */
+  attempts: number
+  /** ceiling on helper attempts (from the task's merge preset) */
+  maxAttempts: number
+  headSha?: string | null
+  /** append-only history of fix / pull-main rounds */
+  rounds?: HumanTestRound[]
+}
+
 /** A pipeline instance running against one block. */
 export interface ExecutionInstance {
   id: string

package/app/types/notifications.ts

@@ -14,6 +14,7 @@ export type NotificationType =
   | 'clarity_review'
   | 'release_regression'
   | 'decision_required'
+  | 'human_test_ready'
 export type NotificationStatus = 'open' | 'acted' | 'dismissed'
 
 /** The on-call agent's recommendation on a `release_regression`. */

package/app/utils/catalog.spec.ts

@@ -29,6 +29,7 @@ const AGENT_KINDS: AgentKind[] = [
   'mocker',
   'business-documenter',
   'business-reviewer',
+  'human-test',
 ]
 const BLOCK_TYPES: BlockType[] = [
   'frontend',

package/app/utils/catalog.ts

@@ -131,6 +131,18 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     description:
       "Turns scenarios into runnable tests — Playwright for frontend, the project's own framework for backend; adds only new ones.",
   },
+  {
+    kind: 'human-test',
+    label: 'Human Testing',
+    icon: 'i-lucide-user-check',
+    color: '#f59e0b',
+    category: 'test',
+    description:
+      'Spins up an ephemeral environment and pauses for a person to validate the change in a live URL — request a fix from findings, pull main + redeploy, or recreate/destroy the env — before the pipeline continues.',
+    // Opens the dedicated human-testing window (env URL + confirm / request-fix / pull-main /
+    // recreate / destroy) instead of the generic prose step-detail panel.
+    resultView: 'human-test',
+  },
   {
     kind: 'documenter',
     label: 'Documenter',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.21.0",
+  "version": "0.22.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",