@cat-factory/app 0.21.0 → 0.23.0

package/app/components/board/AddTaskModal.vue

@@ -11,7 +11,7 @@
 // button is disabled with a hint. Linking needs the block id,
 // so chosen items are staged locally and import-and-linked once the task is created
 // (see useContextLinking) — the same context the agents see for every step of the run.
-import type { CreateTaskType, TaskTypeFields } from '~/types/domain'
+import type { CreateTaskType, TaskSourceKind, TaskTypeFields } from '~/types/domain'
 import ContextDocumentPicker from '~/components/documents/ContextDocumentPicker.vue'
 import ContextIssuePicker from '~/components/tasks/ContextIssuePicker.vue'
 
@@ -193,6 +193,61 @@ const issuesConnected = computed(() => tasks.available && tasks.anyOffered)
 const pendingDocs = computed(() => pendingContext.value.filter((c) => c.kind === 'document'))
 const pendingIssues = computed(() => pendingContext.value.filter((c) => c.kind === 'task'))
 
+// Linked issues whose body is in hand, surfaced read-only above the description so the
+// user SEES the original issue description is included in the task (and can add notes on
+// top). The bodies are folded into the saved description on submit (see `add`).
+const linkedIssueBodies = computed(() =>
+  pendingIssues.value
+    .filter((i) => (i.description ?? '').trim().length > 0)
+    .map((i) => ({ key: contextKey(i), title: i.title, body: (i.description ?? '').trim() })),
+)
+const hasLinkedIssueBody = computed(() => linkedIssueBodies.value.length > 0)
+// True while we're fetching a search-hit issue's body so the read-only preview can show
+// a placeholder instead of silently appearing late.
+const resolvingIssueBodies = ref(false)
+
+// A staged issue picked from search results carries no body yet (`needsImport`, and the
+// search result has no description). Resolve it once the form opens — from the local cache
+// when already imported, else by importing it (idempotent; we'd import on add anyway) — so
+// its description can be shown read-only and folded into the task. Best-effort: a failure
+// just leaves that issue without a preview, still linked on add.
+async function resolvePendingIssueBodies() {
+  const unresolved = pendingContext.value.filter(
+    (c) => c.kind === 'task' && !(c.description ?? '').trim(),
+  )
+  if (!unresolved.length) return
+  resolvingIssueBodies.value = true
+  try {
+    const resolved: Record<string, string> = {}
+    for (const item of unresolved) {
+      const source = item.source as TaskSourceKind
+      const cached = tasks.tasks.find(
+        (t) => t.source === source && t.externalId === item.externalId,
+      )
+      if ((cached?.description ?? '').trim()) {
+        resolved[contextKey(item)] = cached!.description
+        continue
+      }
+      if (!item.needsImport) continue
+      try {
+        const imported = await tasks.importTask(source, item.externalId)
+        if ((imported.description ?? '').trim()) resolved[contextKey(item)] = imported.description
+      } catch {
+        // Unreadable/forbidden issue — skip the preview; it still links on add.
+      }
+    }
+    if (Object.keys(resolved).length) {
+      // The issue is now imported, so it links directly on add (needsImport → false).
+      pendingContext.value = pendingContext.value.map((c) => {
+        const body = resolved[contextKey(c)]
+        return body ? { ...c, description: body, needsImport: false } : c
+      })
+    }
+  } finally {
+    resolvingIssueBodies.value = false
+  }
+}
+
 function addPending(item: PendingContext) {
   if (pendingContext.value.some((c) => contextKey(c) === contextKey(item))) return
   pendingContext.value = [...pendingContext.value, item]
@@ -241,6 +296,8 @@ watch(open, (isOpen) => {
   }
   documents.loadDocuments().catch(() => {})
   tasks.loadTasks().catch(() => {})
+  // Fetch any staged search-hit issue's body so its description shows read-only below.
+  resolvePendingIssueBodies().catch(() => {})
 })
 
 // A recurring task only needs a target frame (its details are filled in the schedule
@@ -264,21 +321,23 @@ async function add() {
   saving.value = true
   try {
     const typeFields = buildTypeFields()
-    const block = await board.addTask(
-      containerId,
-      title.value.trim(),
-      description.value.trim() || undefined,
-      {
-        taskType: taskType.value as CreateTaskType,
-        ...(typeFields ? { taskTypeFields: typeFields } : {}),
-        ...(mergePresetId.value ? { mergePresetId: mergePresetId.value } : {}),
-        ...(modelPresetId.value ? { modelPresetId: modelPresetId.value } : {}),
-        ...(pipelineId.value ? { pipelineId: pipelineId.value } : {}),
-        ...(Object.keys(agentConfigValues.value).length
-          ? { agentConfig: agentConfigValues.value }
-          : {}),
-      },
-    )
+    // The saved description includes each linked issue's body (shown read-only above)
+    // followed by the user's own notes, so the original issue description is part of the
+    // task — not only reachable via the context link.
+    const notes = description.value.trim()
+    const fullDescription =
+      [...linkedIssueBodies.value.map((b) => b.body), notes].filter(Boolean).join('\n\n') ||
+      undefined
+    const block = await board.addTask(containerId, title.value.trim(), fullDescription, {
+      taskType: taskType.value as CreateTaskType,
+      ...(typeFields ? { taskTypeFields: typeFields } : {}),
+      ...(mergePresetId.value ? { mergePresetId: mergePresetId.value } : {}),
+      ...(modelPresetId.value ? { modelPresetId: modelPresetId.value } : {}),
+      ...(pipelineId.value ? { pipelineId: pipelineId.value } : {}),
+      ...(Object.keys(agentConfigValues.value).length
+        ? { agentConfig: agentConfigValues.value }
+        : {}),
+    })
     if (block) {
       const failed = await linkPending(block.id, pendingContext.value)
       if (failed > 0) {
@@ -352,12 +411,37 @@ async function add() {
             />
           </UFormField>
 
-          <UFormField label="Description">
+          <!-- Linked issue description(s), read-only: shown so the user sees the original
+               issue description is included in the task. It's folded into the saved
+               description (before their notes) on add. -->
+          <UFormField
+            v-for="issue in linkedIssueBodies"
+            :key="issue.key"
+            :label="`${issue.title} (from issue, included)`"
+          >
+            <UTextarea
+              :model-value="issue.body"
+              :rows="4"
+              autoresize
+              readonly
+              class="w-full"
+              :ui="{ base: 'cursor-default text-slate-300' }"
+            />
+          </UFormField>
+          <p v-if="resolvingIssueBodies" class="text-[11px] text-slate-500">
+            Loading the linked issue's description…
+          </p>
+
+          <UFormField :label="hasLinkedIssueBody ? 'Additional notes' : 'Description'">
             <UTextarea
               v-model="description"
               :rows="4"
               autoresize
-              placeholder="Describe the work — context, acceptance criteria, anything the agent should know…"
+              :placeholder="
+                hasLinkedIssueBody
+                  ? 'Add anything else the agent should know — appended to the issue description above…'
+                  : 'Describe the work — context, acceptance criteria, anything the agent should know…'
+              "
               class="w-full"
             />
           </UFormField>

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/components/tasks/ContextIssuePicker.vue

@@ -6,7 +6,7 @@
 // It only *stages* a choice: the caller collects PendingContext items and links
 // them once the block exists (see useContextLinking). A search hit / pasted ref
 // carries `needsImport: true` so it's fetched + persisted before linking.
-import type { TaskSearchResult, TaskSourceKind } from '~/types/domain'
+import type { SourceTask, TaskSearchResult, TaskSourceKind } from '~/types/domain'
 
 const props = defineProps<{
   /** contextKeys already staged by the caller, so they're filtered out / not re-offered. */
@@ -120,15 +120,18 @@ const empty = computed(
     refRow.value === null,
 )
 
-function pickImported(externalId: string, title: string, status: string) {
+function pickImported(task: SourceTask) {
   if (!source.value) return
   emit('pick', {
     kind: 'task',
     source: source.value,
-    externalId,
-    title: `${externalId} · ${title}`,
-    subtitle: status || undefined,
+    externalId: task.externalId,
+    title: `${task.externalId} · ${task.title}`,
+    subtitle: task.status || undefined,
     icon: icon.value,
+    // Already imported, so its body is in hand — carry it so the add-task form can
+    // show it read-only and fold it into the new task's description.
+    description: task.description || undefined,
     needsImport: false,
   })
 }
@@ -200,7 +203,7 @@ onMounted(() => {
         :key="`imp:${t.externalId}`"
         type="button"
         class="flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-left text-xs text-slate-300 hover:bg-slate-800/70"
-        @click="pickImported(t.externalId, t.title, t.status)"
+        @click="pickImported(t)"
       >
         <UIcon :name="icon" class="h-3.5 w-3.5 shrink-0 text-indigo-400" />
         <span class="truncate">{{ t.externalId }} · {{ t.title }}</span>

package/app/components/tasks/TaskImportModal.vue

@@ -118,10 +118,13 @@ watch(open, (isOpen) => {
 
 // Selecting an issue hands off to the add-task form, prefilled with the issue title
 // and the issue staged as linked context (so agents see its description + comments).
-// The user still confirms pipeline / preset there before the task is created — we do
-// NOT dump the issue body into the description; the link is enough.
+// The user still confirms pipeline / preset there before the task is created. The
+// issue body is carried when already in hand (imported issues); for a search hit it's
+// resolved in the add-task form (by importing). Either way the form shows it read-only
+// and folds it into the new task's description, so the original description is visible
+// and included — the user adds their own notes on top.
 function selectIssue(
-  issue: { externalId: string; title: string; status?: string },
+  issue: { externalId: string; title: string; status?: string; description?: string },
   needsImport: boolean,
 ) {
   if (!source.value || !containerId.value) return
@@ -135,6 +138,7 @@ function selectIssue(
         title: `${issue.externalId} · ${issue.title}`,
         subtitle: issue.status || undefined,
         icon: descriptor.value?.icon,
+        description: issue.description || undefined,
         needsImport,
       },
     ],

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/composables/useContextLinking.ts

@@ -19,6 +19,13 @@ export interface PendingContext {
   subtitle?: string
   /** Lucide icon for the row. */
   icon?: string
+  /**
+   * The item's body/description (Markdown), when known. Populated for an
+   * already-imported issue at pick time and resolved (by importing) for a search
+   * hit when the add-task form opens, so the form can surface it read-only and
+   * fold it into the new task's description. Absent until resolved.
+   */
+  description?: string
   /** True when the item must be imported before it can be linked. */
   needsImport: boolean
 }

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.23.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",