@cat-factory/app 0.31.0 → 0.32.1

package/app/components/followUp/FollowUpWindow.vue

@@ -0,0 +1,257 @@
+<script setup lang="ts">
+// Follow-up companion window — the dedicated surface for the future-looking Coder's
+// surfaced items, opened via the universal result-view host (`ui.openFollowUps`). It reads
+// the live items straight off the run's Coder step (`step.followUps`, kept fresh by the
+// execution stream — a synchronous window, no `onOpen` loader) and lets a human decide each:
+// file a follow-up as a tracker issue, send it back to the Coder, answer a question, or
+// dismiss it. The pipeline's following steps stay blocked until every item is decided.
+import { computed, reactive } from 'vue'
+import { useResultView } from '~/composables/useResultView'
+import { useExecutionStore } from '~/stores/execution'
+import { useBoardStore } from '~/stores/board'
+import { useFollowUpsStore } from '~/stores/followUps'
+import type { FollowUpItem } from '~/types/execution'
+import { FOLLOW_UP_COMPANION_META } from '~/utils/catalog'
+
+const execution = useExecutionStore()
+const board = useBoardStore()
+const followUps = useFollowUpsStore()
+
+const { open, blockId, instanceId, stepIndex, close } = useResultView('follow-ups')
+
+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 items = computed<FollowUpItem[]>(() => step.value?.followUps?.items ?? [])
+const pendingCount = computed(() => items.value.filter((i) => i.status === 'pending').length)
+const loops = computed(() => step.value?.followUps?.loops ?? 0)
+const maxLoops = computed(() => step.value?.followUps?.maxLoops ?? 0)
+
+// Draft answers per question item (keyed by item id), so typing doesn't clobber on re-render.
+const drafts = reactive<Record<string, string>>({})
+
+function execId(): string | null {
+  return instanceId.value
+}
+
+async function onFile(item: FollowUpItem) {
+  const id = execId()
+  if (id) await followUps.fileItem(id, item.id).catch(() => {})
+}
+async function onQueue(item: FollowUpItem) {
+  const id = execId()
+  if (id) await followUps.queueItem(id, item.id).catch(() => {})
+}
+async function onAnswer(item: FollowUpItem) {
+  const id = execId()
+  const answer = (drafts[item.id] ?? '').trim()
+  if (id && answer) await followUps.answerItem(id, item.id, answer).catch(() => {})
+}
+async function onDismiss(item: FollowUpItem) {
+  const id = execId()
+  if (id) await followUps.dismissItem(id, item.id).catch(() => {})
+}
+
+const STATUS_META: Record<
+  FollowUpItem['status'],
+  { label: string; badge: 'neutral' | 'info' | 'success' | 'warning'; text: string }
+> = {
+  pending: { label: 'Needs a decision', badge: 'warning', text: 'text-amber-300' },
+  filed: { label: 'Filed as issue', badge: 'success', text: 'text-emerald-300' },
+  queued: { label: 'Sent to Coder', badge: 'info', text: 'text-sky-300' },
+  answered: { label: 'Answered', badge: 'info', text: 'text-sky-300' },
+  dismissed: { label: 'Dismissed', badge: 'neutral', text: 'text-slate-400' },
+}
+</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-pink-500/15 text-pink-300"
+          >
+            <UIcon :name="FOLLOW_UP_COMPANION_META.icon" class="h-4 w-4" />
+          </span>
+          <div class="min-w-0 flex-1">
+            <h2 class="truncate text-sm font-semibold text-slate-100">
+              {{ FOLLOW_UP_COMPANION_META.label }}{{ block ? ` — ${block.title}` : '' }}
+            </h2>
+            <p class="truncate text-[11px] text-slate-400">
+              Forward-looking follow-ups & questions the Coder surfaced. The pipeline continues once
+              every item is decided.
+            </p>
+          </div>
+          <UBadge :color="pendingCount > 0 ? 'warning' : 'success'" variant="subtle" size="sm">
+            {{ pendingCount > 0 ? `${pendingCount} to decide` : 'All decided' }}
+          </UBadge>
+          <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="min-h-0 flex-1 overflow-y-auto px-5 py-4">
+          <!-- Empty -->
+          <div
+            v-if="items.length === 0"
+            class="flex h-full flex-col items-center justify-center gap-2 py-10 text-center text-slate-400"
+          >
+            <UIcon :name="FOLLOW_UP_COMPANION_META.icon" class="h-8 w-8 opacity-40" />
+            <p class="text-sm">No follow-ups yet.</p>
+            <p class="max-w-sm text-[11px] text-slate-500">
+              As the Coder works it streams loose ends, side-tasks and questions here. They appear
+              live — you can act on them before the Coder even finishes.
+            </p>
+          </div>
+
+          <div v-else class="space-y-3">
+            <p
+              v-if="followUps.error"
+              class="rounded-md bg-rose-500/10 px-3 py-2 text-[12px] text-rose-300"
+            >
+              {{ followUps.error }}
+            </p>
+
+            <article
+              v-for="item in items"
+              :key="item.id"
+              class="rounded-xl border border-slate-800 bg-slate-900/60 px-4 py-3"
+              :class="item.status === 'pending' ? 'border-amber-500/40' : ''"
+            >
+              <div class="flex items-start gap-2">
+                <UIcon
+                  :name="item.kind === 'question' ? 'i-lucide-circle-help' : 'i-lucide-compass'"
+                  class="mt-0.5 h-4 w-4 shrink-0"
+                  :class="item.kind === 'question' ? 'text-sky-300' : 'text-pink-300'"
+                />
+                <div class="min-w-0 flex-1">
+                  <div class="flex items-center gap-2">
+                    <h3 class="min-w-0 flex-1 truncate text-[13px] font-medium text-slate-100">
+                      {{ item.title }}
+                    </h3>
+                    <UBadge :color="STATUS_META[item.status].badge" variant="subtle" size="sm">
+                      {{ STATUS_META[item.status].label }}
+                    </UBadge>
+                  </div>
+                  <p v-if="item.detail" class="mt-1 whitespace-pre-wrap text-[12px] text-slate-300">
+                    {{ item.detail }}
+                  </p>
+                  <p v-if="item.suggestedAction" class="mt-1 text-[11px] text-slate-400">
+                    <span class="text-slate-500">Suggested:</span> {{ item.suggestedAction }}
+                  </p>
+                  <p v-if="item.status === 'filed' && item.ticketUrl" class="mt-1 text-[11px]">
+                    <a
+                      :href="item.ticketUrl"
+                      target="_blank"
+                      rel="noopener"
+                      class="text-emerald-300 hover:underline"
+                    >
+                      {{ item.ticketExternalId ?? 'View issue' }}
+                    </a>
+                  </p>
+                  <p
+                    v-if="item.status === 'answered' && item.answer"
+                    class="mt-1 text-[11px] text-slate-300"
+                  >
+                    <span class="text-slate-500">Your answer:</span> {{ item.answer }}
+                  </p>
+
+                  <!-- Actions (only while the item is still undecided) -->
+                  <div v-if="item.status === 'pending'" class="mt-2.5">
+                    <!-- A question: answer it -->
+                    <div v-if="item.kind === 'question'" class="space-y-2">
+                      <textarea
+                        v-model="drafts[item.id]"
+                        rows="2"
+                        placeholder="Answer this question — it's folded into the Coder's next pass…"
+                        class="w-full resize-y rounded-md border border-slate-700 bg-slate-950/60 px-2.5 py-1.5 text-[12px] text-slate-100 placeholder:text-slate-600 focus:border-sky-500 focus:outline-none"
+                      />
+                      <div class="flex items-center gap-2">
+                        <UButton
+                          size="xs"
+                          color="primary"
+                          :loading="followUps.isActing(item.id)"
+                          :disabled="!(drafts[item.id] ?? '').trim()"
+                          @click="onAnswer(item)"
+                        >
+                          Answer & send back
+                        </UButton>
+                        <UButton
+                          size="xs"
+                          color="neutral"
+                          variant="ghost"
+                          :loading="followUps.isActing(item.id)"
+                          @click="onDismiss(item)"
+                        >
+                          Dismiss
+                        </UButton>
+                      </div>
+                    </div>
+
+                    <!-- A follow-up: file / send back / dismiss -->
+                    <div v-else class="flex flex-wrap items-center gap-2">
+                      <UButton
+                        size="xs"
+                        color="primary"
+                        icon="i-lucide-ticket"
+                        :loading="followUps.isActing(item.id)"
+                        @click="onFile(item)"
+                      >
+                        File as issue
+                      </UButton>
+                      <UButton
+                        size="xs"
+                        color="info"
+                        variant="soft"
+                        icon="i-lucide-corner-up-left"
+                        :loading="followUps.isActing(item.id)"
+                        @click="onQueue(item)"
+                      >
+                        Send to Coder
+                      </UButton>
+                      <UButton
+                        size="xs"
+                        color="neutral"
+                        variant="ghost"
+                        :loading="followUps.isActing(item.id)"
+                        @click="onDismiss(item)"
+                      >
+                        Dismiss
+                      </UButton>
+                    </div>
+                  </div>
+                </div>
+              </div>
+            </article>
+          </div>
+        </div>
+
+        <footer
+          class="flex items-center justify-between border-t border-slate-800 px-5 py-2.5 text-[11px] text-slate-400"
+        >
+          <span>
+            {{ items.length }} item{{ items.length === 1 ? '' : 's' }} ·
+            {{ pendingCount }} undecided
+          </span>
+          <span v-if="maxLoops > 0">Coder loops used: {{ loops }} / {{ maxLoops }}</span>
+        </footer>
+      </div>
+    </div>
+  </Teleport>
+</template>

package/app/components/kaizen/KaizenPanel.vue

@@ -97,8 +97,8 @@ function statusLabel(g: KaizenGrading): string {
               <span class="text-xs font-normal text-slate-500">({{ kaizen.verifiedCount }})</span>
             </h2>
             <p class="mb-3 text-[11px] text-slate-500">
-              A prompt + agent + model combination that graded 4 or 5 with no recommendations
-              five times in a row. These are no longer graded.
+              A prompt + agent + model combination that graded 4 or 5 with no recommendations five
+              times in a row. These are no longer graded.
             </p>
             <ul class="space-y-2">
               <li

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 Follow-up companion window for the run (see `reveal`); "act"
+  // just marks it read (items are decided in that window — file / send back / answer — not here).
+  followup_pending: { icon: 'i-lucide-compass', color: 'warning', action: 'Mark read' },
 }
 
 /** A notification the escalation sweep has flagged as overdue (waited past the threshold). */
@@ -81,9 +84,19 @@ 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 === 'followup_pending') revealFollowUps(n)
   else ui.select(n.blockId)
 }
 
+/**
+ * Open the Follow-up companion window for a run whose Coder parked on undecided items.
+ * Falls back to focusing the block when the run isn't loaded.
+ */
+function revealFollowUps(n: Notification) {
+  if (n.executionId && execution.getInstance(n.executionId)) ui.openFollowUps(n.executionId)
+  else if (n.blockId) 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

package/app/components/panels/StepResultViewHost.vue

@@ -13,18 +13,22 @@
 import { computed, type Component } from 'vue'
 import RequirementsReviewWindow from '~/components/requirements/RequirementsReviewWindow.vue'
 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 GateResultView from '~/components/gates/GateResultView.vue'
 import ConsensusSessionWindow from '~/components/consensus/ConsensusSessionWindow.vue'
 import GenericStructuredResultView from '~/components/panels/GenericStructuredResultView.vue'
 import ServiceSpecWindow from '~/components/spec/ServiceSpecWindow.vue'
+import FollowUpWindow from '~/components/followUp/FollowUpWindow.vue'
 
 const ui = useUiStore()
 
 const STEP_RESULT_VIEWS: Record<string, Component> = {
   'requirements-review': RequirementsReviewWindow,
   'clarity-review': ClarityReviewWindow,
+  // Shared by both brainstorm stages (requirements + architecture); the window reads the stage.
+  brainstorm: BrainstormWindow,
   tester: TestReportWindow,
   // The human-testing gate: env URL + confirm / request-fix / pull-main / recreate / destroy.
   'human-test': HumanTestWindow,
@@ -38,6 +42,9 @@ const STEP_RESULT_VIEWS: Record<string, Component> = {
   // The service's prescriptive spec tree (+ Gherkin), opened from the inspector's "View
   // Requirements" button. Not a pipeline-step view — opened directly via `ui.openServiceSpec`.
   'service-spec': ServiceSpecWindow,
+  // The future-looking Follow-up companion: the Coder's surfaced loose ends / questions.
+  // Opened directly via `ui.openFollowUps` (the blinking chip + the `followup_pending` card).
+  'follow-ups': FollowUpWindow,
 }
 
 const active = computed<Component | null>(() => {

package/app/components/pipeline/PipelineBuilder.vue

@@ -381,6 +381,27 @@ async function clone(p: Pipeline) {
                     "
                     @click="pipelines.toggleDraftConsensus(unit.index)"
                   />
+                  <!-- Follow-up companion: the future-looking Coder surfaces loose ends /
+                     side-tasks / questions mid-run (coder steps only). Enabled by default. -->
+                  <UButton
+                    v-if="unit.kind === 'coder'"
+                    :icon="
+                      pipelines.draftFollowUps[unit.index] === false
+                        ? 'i-lucide-circle-slash'
+                        : 'i-lucide-compass'
+                    "
+                    :color="
+                      pipelines.draftFollowUps[unit.index] === false ? 'neutral' : 'secondary'
+                    "
+                    variant="ghost"
+                    size="xs"
+                    :title="
+                      pipelines.draftFollowUps[unit.index] === false
+                        ? 'Follow-up companion disabled — click to enable (Coder surfaces loose ends / questions)'
+                        : 'Follow-up companion enabled — Coder surfaces loose ends / side-tasks / questions; click to disable'
+                    "
+                    @click="pipelines.toggleDraftFollowUps(unit.index)"
+                  />
                   <UButton
                     icon="i-lucide-chevron-up"
                     color="neutral"

package/app/components/pipeline/PipelineProgress.vue

@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import type { AgentState, ExecutionInstance } from '~/types/domain'
-import { agentKindMeta } from '~/utils/catalog'
+import type { PipelineStep } from '~/types/execution'
+import { agentKindMeta, FOLLOW_UP_COMPANION_META } from '~/utils/catalog'
 import {
   subtaskIconClass,
   gateCompanionFor,
@@ -43,6 +44,18 @@ function openStep(i: number) {
   ui.openStepDetail(props.instance.id, i)
 }
 
+// Follow-up companion (the future-looking Coder): how many surfaced items still need a
+// decision, and the chip's roll-up label. The chip blinks while any item is pending.
+function followUpPending(step: PipelineStep): number {
+  return (step.followUps?.items ?? []).filter((it) => it.status === 'pending').length
+}
+function followUpLabel(step: PipelineStep): string {
+  const items = step.followUps?.items ?? []
+  if (items.length === 0) return 'Watching…'
+  const pending = followUpPending(step)
+  return pending > 0 ? `${pending} to decide` : 'All decided'
+}
+
 // --- restart from a step -----------------------------------------------------
 // Re-run the pipeline from a chosen step onward: the server resets that step +
 // every later step's iteration counters and re-drives a fresh run, keeping the
@@ -420,6 +433,37 @@ const ITEM_ICON: Record<string, string> = {
             </span>
           </div>
 
+          <!-- Follow-up companion (future-looking Coder): a blinking chip that lights up the
+               moment the Coder streams an item; click to triage. Blinks while any item is
+               undecided (the gate holds the pipeline until they're all decided). -->
+          <button
+            v-if="s.followUps?.enabled"
+            type="button"
+            class="mt-3 flex w-full items-center gap-2 rounded-lg border border-dashed px-2.5 py-1.5 text-left transition hover:border-pink-400/60"
+            :class="
+              followUpPending(s) > 0
+                ? 'border-pink-500/50 bg-pink-500/10 followup-blink'
+                : 'border-slate-700/70 bg-slate-900/40'
+            "
+            @click="ui.openFollowUps(instance.id, i)"
+          >
+            <span
+              class="flex h-6 w-6 shrink-0 items-center justify-center rounded-md border border-pink-500/40 bg-pink-500/15"
+            >
+              <UIcon :name="FOLLOW_UP_COMPANION_META.icon" class="h-3 w-3 text-pink-300" />
+            </span>
+            <span class="min-w-0 flex-1 truncate text-[12px] text-slate-300">
+              {{ FOLLOW_UP_COMPANION_META.label }}
+              <span class="text-slate-500">(companion)</span>
+            </span>
+            <span
+              class="shrink-0 text-[11px] font-medium"
+              :class="followUpPending(s) > 0 ? 'text-pink-300' : 'text-slate-400'"
+            >
+              {{ followUpLabel(s) }}
+            </span>
+          </button>
+
           <!-- reviewer gate folding/re-reviewing in the background: a working indicator,
                NOT a "Review & approve" gate (the human is summoned only if needed) -->
           <div
@@ -483,4 +527,18 @@ const ITEM_ICON: Record<string, string> = {
 .step-active {
   animation: step-pulse 1.6s ease-in-out infinite;
 }
+/* The Follow-up companion chip blinks (pink) while it has undecided items, drawing the eye
+   to forward-looking work surfaced mid-run. */
+@keyframes followup-blink {
+  0%,
+  100% {
+    box-shadow: 0 0 0 0 rgba(244, 114, 182, 0.5);
+  }
+  50% {
+    box-shadow: 0 0 0 5px rgba(244, 114, 182, 0);
+  }
+}
+.followup-blink {
+  animation: followup-blink 1.4s ease-in-out infinite;
+}
 </style>

package/app/components/slack/SlackPanel.vue

@@ -45,6 +45,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: '' },
+  followup_pending: { enabled: false, channel: '' },
 })
 const mentionsEnabled = ref(false)
 const mapping = ref<SlackMemberMappingEntry[]>([])

package/app/composables/api/followUps.ts

@@ -0,0 +1,52 @@
+import type { FollowUpsStepState } from '~/types/execution'
+import type { ApiContext } from './context'
+
+/**
+ * The Follow-up companion: the Coder surfaces forward-looking items (loose ends /
+ * side-tasks / questions) live on its run step; these endpoints decide each one. Every
+ * call returns the updated live state; when the run is parked on the follow-up gate and
+ * the last item is decided, the backend drives the run forward (loop the Coder for the
+ * queued / answered items, else advance).
+ */
+export function followUpsApi({ http, ws }: ApiContext) {
+  const base = (workspaceId: string, executionId: string) =>
+    `${ws(workspaceId)}/executions/${encodeURIComponent(executionId)}/follow-ups`
+
+  return {
+    // The live follow-up state for a run (null when the companion is off / nothing surfaced).
+    getFollowUps: (workspaceId: string, executionId: string) =>
+      http<FollowUpsStepState | null>(base(workspaceId, executionId)),
+
+    // File a follow-up as a tracker issue (GitHub Issues / Jira).
+    fileFollowUp: (workspaceId: string, executionId: string, itemId: string) =>
+      http<FollowUpsStepState>(
+        `${base(workspaceId, executionId)}/${encodeURIComponent(itemId)}/file`,
+        {
+          method: 'POST',
+        },
+      ),
+
+    // Send a follow-up back to the Coder (queued for its next pass).
+    queueFollowUp: (workspaceId: string, executionId: string, itemId: string) =>
+      http<FollowUpsStepState>(
+        `${base(workspaceId, executionId)}/${encodeURIComponent(itemId)}/queue`,
+        {
+          method: 'POST',
+        },
+      ),
+
+    // Answer a question item (folded into the Coder's next pass).
+    answerFollowUp: (workspaceId: string, executionId: string, itemId: string, answer: string) =>
+      http<FollowUpsStepState>(
+        `${base(workspaceId, executionId)}/${encodeURIComponent(itemId)}/answer`,
+        { method: 'POST', body: { answer } },
+      ),
+
+    // Dismiss a follow-up / question item without acting on it.
+    dismissFollowUp: (workspaceId: string, executionId: string, itemId: string) =>
+      http<FollowUpsStepState>(
+        `${base(workspaceId, executionId)}/${encodeURIComponent(itemId)}/dismiss`,
+        { method: 'POST' },
+      ),
+  }
+}

package/app/composables/api/reviews.ts

@@ -1,4 +1,9 @@
 import type { ClarityReview, ResolveClarityExceededChoice } from '~/types/clarity'
+import type {
+  BrainstormSession,
+  BrainstormStage,
+  ResolveBrainstormExceededChoice,
+} from '~/types/brainstorm'
 import type { ConsensusSession } from '~/types/consensus'
 import type {
   RequirementReview,
@@ -176,5 +181,68 @@ export function reviewsApi({ http, ws }: ApiContext) {
         `${ws(workspaceId)}/blocks/${encodeURIComponent(blockId)}/clarity-review/resolve-exceeded`,
         { method: 'POST', body: { choice } },
       ),
+
+    // ---- brainstorm (structured-dialogue agent, stage-scoped) ------------
+    // The current session for a block + stage (null when none has been run). A 503 means
+    // the feature is unconfigured (the panel hides on any error here).
+    getBrainstorm: (workspaceId: string, blockId: string, stage: BrainstormStage) =>
+      http<BrainstormSession | null>(
+        `${ws(workspaceId)}/blocks/${encodeURIComponent(blockId)}/brainstorm/${stage}`,
+      ),
+
+    replyBrainstormItem: (workspaceId: string, sessionId: string, itemId: string, reply: string) =>
+      http<BrainstormSession>(
+        `${ws(workspaceId)}/brainstorm-sessions/${encodeURIComponent(sessionId)}/items/${encodeURIComponent(itemId)}/reply`,
+        { method: 'POST', body: { reply } },
+      ),
+
+    setBrainstormItemStatus: (
+      workspaceId: string,
+      sessionId: string,
+      itemId: string,
+      status: ReviewItemStatus,
+    ) =>
+      http<BrainstormSession>(
+        `${ws(workspaceId)}/brainstorm-sessions/${encodeURIComponent(sessionId)}/items/${encodeURIComponent(itemId)}`,
+        { method: 'PATCH', body: { status } },
+      ),
+
+    // Incorporate the picks ASYNCHRONOUSLY (the durable driver folds + re-runs).
+    incorporateBrainstorm: (
+      workspaceId: string,
+      blockId: string,
+      stage: BrainstormStage,
+      feedback?: string,
+    ) =>
+      http<BrainstormSession>(
+        `${ws(workspaceId)}/blocks/${encodeURIComponent(blockId)}/brainstorm/${stage}/incorporate`,
+        { method: 'POST', body: feedback ? { feedback } : {} },
+      ),
+
+    // Re-run the brainstorm against the converged direction (one more pass).
+    reReviewBrainstorm: (workspaceId: string, blockId: string, stage: BrainstormStage) =>
+      http<BrainstormSession>(
+        `${ws(workspaceId)}/blocks/${encodeURIComponent(blockId)}/brainstorm/${stage}/re-review`,
+        { method: 'POST' },
+      ),
+
+    // Proceed: settle the brainstorm and advance the parked run (all options dismissed).
+    proceedBrainstorm: (workspaceId: string, blockId: string, stage: BrainstormStage) =>
+      http<BrainstormSession>(
+        `${ws(workspaceId)}/blocks/${encodeURIComponent(blockId)}/brainstorm/${stage}/proceed`,
+        { method: 'POST' },
+      ),
+
+    // Resolve a session that hit its iteration cap: extra-round / proceed / stop-reset.
+    resolveBrainstormExceeded: (
+      workspaceId: string,
+      blockId: string,
+      stage: BrainstormStage,
+      choice: ResolveBrainstormExceededChoice,
+    ) =>
+      http<BrainstormSession>(
+        `${ws(workspaceId)}/blocks/${encodeURIComponent(blockId)}/brainstorm/${stage}/resolve-exceeded`,
+        { method: 'POST', body: { choice } },
+      ),
   }
 }

package/app/composables/useApi.ts

@@ -6,6 +6,7 @@ import { bootstrapApi } from './api/bootstrap'
 import { boardApi } from './api/board'
 import { documentsApi } from './api/documents'
 import { executionApi } from './api/execution'
+import { followUpsApi } from './api/followUps'
 import { fragmentsApi } from './api/fragments'
 import { githubApi } from './api/github'
 import { humanTestApi } from './api/humanTest'
@@ -85,6 +86,7 @@ export function useApi() {
     ...documentsApi(ctx),
     ...tasksApi(ctx),
     ...reviewsApi(ctx),
+    ...followUpsApi(ctx),
     ...humanTestApi(ctx),
     ...kaizenApi(ctx),
     ...specApi(ctx),

package/app/composables/useResultView.ts

@@ -22,6 +22,8 @@ export function useResultView(viewId: string, opts?: { onOpen?: (blockId: string
   const blockId = computed(() => (open.value ? ui.resultView!.blockId : null))
   const instanceId = computed(() => (open.value ? ui.resultView!.instanceId : null))
   const stepIndex = computed(() => (open.value ? ui.resultView!.stepIndex : null))
+  // Set only for the brainstorm window (its two stages share one view id).
+  const stage = computed(() => (open.value ? (ui.resultView!.stage ?? null) : null))
 
   function close() {
     ui.closeResultView()
@@ -44,5 +46,5 @@ export function useResultView(viewId: string, opts?: { onOpen?: (blockId: string
     )
   }
 
-  return { open, blockId, instanceId, stepIndex, close }
+  return { open, blockId, instanceId, stepIndex, stage, close }
 }

package/app/composables/useWorkspaceStream.ts

@@ -23,6 +23,7 @@ export function useWorkspaceStream() {
   const requirements = useRequirementsStore()
   const consensus = useConsensusStore()
   const clarity = useClarityStore()
+  const brainstorm = useBrainstormStore()
   const kaizen = useKaizenStore()
   const api = useApi()
   const apiBase = useRuntimeConfig().public.apiBase
@@ -88,6 +89,10 @@ export function useWorkspaceStream() {
       // cache so an open review window / inspector reflects it live ("incorporating…" → the
       // next cycle / converged). The summons back, when needed, arrives as a `notification`.
       clarity.upsert(event.review)
+    } else if (event.type === 'brainstorm') {
+      // The async incorporate + re-run cycle changed a brainstorm session's status — patch the
+      // cache so an open brainstorm window / inspector reflects it live.
+      brainstorm.upsert(event.session)
     } else if (event.type === 'kaizen') {
       // A post-run Kaizen grading was scheduled, started or completed — fold it into the
       // run cache (so an open run window shows scheduled→running→complete live) and the