@cat-factory/app 0.30.6 → 0.32.0

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

@@ -68,6 +68,7 @@ const draft = reactive({
   taskLimitShared: 5 as number,
   perType: {} as Record<CreateTaskType, number>,
   storeAgentContext: true,
+  kaizenEnabled: true,
   // Budget: empty string ⇒ "use the built-in default" (null on the wire).
   spendCurrency: '',
   spendMonthlyLimit: '',
@@ -81,6 +82,7 @@ function hydrate() {
   const pt = s.taskLimitPerType ?? {}
   for (const t of TASK_TYPES) draft.perType[t] = pt[t] ?? 3
   draft.storeAgentContext = s.storeAgentContext
+  draft.kaizenEnabled = s.kaizenEnabled
   draft.spendCurrency = s.spendCurrency ?? ''
   draft.spendMonthlyLimit = s.spendMonthlyLimit == null ? '' : String(s.spendMonthlyLimit)
 }
@@ -107,6 +109,7 @@ async function save() {
             )
           : null,
       storeAgentContext: draft.storeAgentContext,
+      kaizenEnabled: draft.kaizenEnabled,
     })
     toast.add({ title: 'Settings saved', icon: 'i-lucide-check', color: 'success' })
   } catch (e) {
@@ -237,6 +240,23 @@ async function saveBudget() {
               </label>
             </section>
 
+            <!-- Kaizen agent -->
+            <section class="space-y-2">
+              <h3 class="text-sm font-semibold text-slate-200">Kaizen agent</h3>
+              <p class="text-[11px] text-slate-400">
+                After each run completes, the Kaizen agent grades how every agent step went — smooth
+                and efficient vs confused and chaotic — and recommends prompt/model improvements. A
+                prompt + agent + model combination that grades highly with no recommendations five
+                times in a row is marked verified and is no longer graded. Grading runs in the
+                background and is shown inside run details and the Kaizen screen. Set the grader's
+                model in Model Configuration (the “Kaizen” agent).
+              </p>
+              <label class="flex items-center gap-2">
+                <USwitch v-model="draft.kaizenEnabled" size="sm" />
+                <span class="text-sm text-slate-200">Grade agent runs with Kaizen</span>
+              </label>
+            </section>
+
             <div class="flex justify-end">
               <UButton
                 color="primary"

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

@@ -0,0 +1,16 @@
+import type { KaizenGrading, KaizenOverview } from '~/types/domain'
+import type { ApiContext } from './context'
+
+/** Kaizen (post-run grading) read endpoints: the screen overview + a run's gradings. */
+export function kaizenApi({ http, ws }: ApiContext) {
+  return {
+    // The Kaizen screen: recent grading history + the verified-combo library.
+    getKaizenOverview: (workspaceId: string) => http<KaizenOverview>(`${ws(workspaceId)}/kaizen`),
+
+    // The gradings recorded for one run (the run-window status surface).
+    getKaizenForExecution: (workspaceId: string, executionId: string) =>
+      http<{ gradings: KaizenGrading[] }>(
+        `${ws(workspaceId)}/executions/${encodeURIComponent(executionId)}/kaizen`,
+      ),
+  }
+}

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,9 +6,11 @@ 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'
+import { kaizenApi } from './api/kaizen'
 import { modelsApi } from './api/models'
 import { notificationsApi } from './api/notifications'
 import { presetsApi } from './api/presets'
@@ -84,7 +86,9 @@ export function useApi() {
     ...documentsApi(ctx),
     ...tasksApi(ctx),
     ...reviewsApi(ctx),
+    ...followUpsApi(ctx),
     ...humanTestApi(ctx),
+    ...kaizenApi(ctx),
     ...specApi(ctx),
     ...notificationsApi(ctx),
     ...presetsApi(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,8 @@ 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
 
@@ -87,6 +89,15 @@ 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
+      // Kaizen screen history. Never surfaced on the board.
+      kaizen.upsert(event.grading)
     }
   }
 

package/app/pages/index.vue

@@ -11,6 +11,7 @@ import DecisionModal from '~/components/panels/DecisionModal.vue'
 import AgentStepDetail from '~/components/panels/AgentStepDetail.vue'
 import StepResultViewHost from '~/components/panels/StepResultViewHost.vue'
 import ObservabilityPanel from '~/components/panels/ObservabilityPanel.vue'
+import KaizenPanel from '~/components/kaizen/KaizenPanel.vue'
 import BlockFocusView from '~/components/focus/BlockFocusView.vue'
 import DocumentSourceConnectModal from '~/components/documents/DocumentSourceConnectModal.vue'
 import DocumentImportModal from '~/components/documents/DocumentImportModal.vue'
@@ -171,6 +172,7 @@ watch(
       <AgentStepDetail />
       <StepResultViewHost />
       <ObservabilityPanel />
+      <KaizenPanel />
       <DocumentSourceConnectModal />
       <DocumentImportModal />
       <SpawnPreviewModal />

package/app/stores/brainstorm.ts

@@ -0,0 +1,210 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import type {
+  BrainstormSession,
+  BrainstormStage,
+  ResolveBrainstormExceededChoice,
+  ReviewItemStatus,
+} from '~/types/brainstorm'
+import { useWorkspaceStore } from '~/stores/workspace'
+
+/**
+ * Brainstorm (structured-dialogue) state. On the pipeline path a brainstorm runs as an opt-in
+ * gate step: the run parks while the human picks / steers / dismisses the proposed options, then
+ * asks to incorporate. Incorporation + the re-run run ASYNCHRONOUSLY in the durable driver — the
+ * call returns at once (status `incorporating`) and the user goes back to the board; they are
+ * summoned again (a notification) only if the re-run yields options or hits the cap. The store is
+ * patched both from call responses and from live `brainstorm` stream events (see `upsert`).
+ *
+ * A block may have one live session per STAGE (`requirements` / `architecture`), so the cache is
+ * keyed by `${blockId}:${stage}`. `available` mirrors the backend's opt-in gate (a 503 hides the
+ * UI). Per-workspace; nothing is persisted client-side.
+ */
+export const useBrainstormStore = defineStore('brainstorm', () => {
+  const api = useApi()
+  const workspace = useWorkspaceStore()
+
+  const key = (blockId: string, stage: BrainstormStage) => `${blockId}:${stage}`
+
+  /** null = unknown (not probed), true/false = feature on/off. */
+  const available = ref<boolean | null>(null)
+  /** The current session per `${blockId}:${stage}` (null = fetched, none exists). */
+  const sessions = ref<Record<string, BrainstormSession | null>>({})
+  /** `${blockId}:${stage}` keys whose agent is currently running (run / re-run). */
+  const running = ref<Set<string>>(new Set())
+  /** Session ids currently incorporating their picks. */
+  const incorporating = ref<Set<string>>(new Set())
+  /** `${blockId}:${stage}` keys whose current session is being fetched (the initial `load`). */
+  const loadingByKey = ref<Set<string>>(new Set())
+  const inFlight = new Map<string, Promise<void>>()
+
+  function sessionFor(blockId: string, stage: BrainstormStage): BrainstormSession | null {
+    return sessions.value[key(blockId, stage)] ?? null
+  }
+  /** The async background stage a session is in, or null (so the board can show "working"). */
+  function backgroundStage(
+    blockId: string,
+    stage: BrainstormStage,
+  ): 'incorporating' | 'reviewing' | null {
+    const status = sessions.value[key(blockId, stage)]?.status
+    return status === 'incorporating' || status === 'reviewing' ? status : null
+  }
+  function isRunning(blockId: string, stage: BrainstormStage): boolean {
+    return running.value.has(key(blockId, stage))
+  }
+  function isLoading(blockId: string, stage: BrainstormStage): boolean {
+    return loadingByKey.value.has(key(blockId, stage))
+  }
+  function isIncorporating(sessionId: string): boolean {
+    return incorporating.value.has(sessionId)
+  }
+
+  /** Options still needing a human (status `open`). */
+  function openCount(session: BrainstormSession): number {
+    return session.items.filter((i) => i.status === 'open').length
+  }
+  /** Options the human chose (a reply recorded), which the companion folds in. */
+  function answeredCount(session: BrainstormSession): number {
+    return session.items.filter((i) => i.status === 'answered' || i.status === 'resolved').length
+  }
+  /** Every option is settled (chosen or dismissed) — none still open. */
+  function allSettled(session: BrainstormSession): boolean {
+    return openCount(session) === 0
+  }
+  /** Incorporation is possible: all options settled AND at least one was chosen. */
+  function canIncorporate(session: BrainstormSession): boolean {
+    return allSettled(session) && answeredCount(session) > 0
+  }
+  /** Proceed (skip the companion) is possible: all options settled but none chosen. */
+  function canProceed(session: BrainstormSession): boolean {
+    return allSettled(session) && answeredCount(session) === 0
+  }
+
+  function store(session: BrainstormSession) {
+    sessions.value = { ...sessions.value, [key(session.blockId, session.stage)]: session }
+  }
+
+  function withFlag(set: typeof running, k: string, on: boolean) {
+    const next = new Set(set.value)
+    if (on) next.add(k)
+    else next.delete(k)
+    set.value = next
+  }
+
+  /** Fetch the current session for a block + stage (probing the feature's availability). */
+  async function load(blockId: string, stage: BrainstormStage) {
+    if (!workspace.workspaceId) return
+    const k = key(blockId, stage)
+    const pending = inFlight.get(k)
+    if (pending) return pending
+    const promise = (async () => {
+      withFlag(loadingByKey, k, true)
+      try {
+        const session = await api.getBrainstorm(workspace.requireId(), blockId, stage)
+        available.value = true
+        sessions.value = { ...sessions.value, [k]: session }
+      } catch {
+        available.value = false
+      } finally {
+        withFlag(loadingByKey, k, false)
+        inFlight.delete(k)
+      }
+    })()
+    inFlight.set(k, promise)
+    return promise
+  }
+
+  /** Record a human's choice on one option. */
+  async function reply(session: BrainstormSession, itemId: string, text: string) {
+    store(await api.replyBrainstormItem(workspace.requireId(), session.id, itemId, text))
+  }
+
+  /** Set an option's status (dismiss / reopen). */
+  async function setItemStatus(
+    session: BrainstormSession,
+    itemId: string,
+    status: ReviewItemStatus,
+  ) {
+    store(await api.setBrainstormItemStatus(workspace.requireId(), session.id, itemId, status))
+  }
+
+  /**
+   * Ask the driver to incorporate the picks ASYNCHRONOUSLY. Optional `feedback` is the "do it
+   * differently" direction when redoing a merge. Returns at once with the `incorporating`
+   * session (the fold + re-run happen in the background).
+   */
+  async function incorporate(session: BrainstormSession, feedback?: string) {
+    withFlag(incorporating, session.id, true)
+    try {
+      const updated = await api.incorporateBrainstorm(
+        workspace.requireId(),
+        session.blockId,
+        session.stage,
+        feedback,
+      )
+      store(updated)
+      return updated
+    } finally {
+      withFlag(incorporating, session.id, false)
+    }
+  }
+
+  /** Re-run the brainstorm against the converged direction (one more pass; may converge/advance). */
+  async function reReview(blockId: string, stage: BrainstormStage): Promise<BrainstormSession> {
+    withFlag(running, key(blockId, stage), true)
+    try {
+      const updated = await api.reReviewBrainstorm(workspace.requireId(), blockId, stage)
+      store(updated)
+      return updated
+    } finally {
+      withFlag(running, key(blockId, stage), false)
+    }
+  }
+
+  /** Proceed: settle the brainstorm and advance the parked run. */
+  async function proceed(blockId: string, stage: BrainstormStage): Promise<BrainstormSession> {
+    const updated = await api.proceedBrainstorm(workspace.requireId(), blockId, stage)
+    store(updated)
+    return updated
+  }
+
+  /** Resolve a capped session: extra-round / proceed / stop-reset. */
+  async function resolveExceeded(
+    blockId: string,
+    stage: BrainstormStage,
+    choice: ResolveBrainstormExceededChoice,
+  ): Promise<BrainstormSession> {
+    const updated = await api.resolveBrainstormExceeded(
+      workspace.requireId(),
+      blockId,
+      stage,
+      choice,
+    )
+    store(updated)
+    return updated
+  }
+
+  return {
+    available,
+    sessions,
+    sessionFor,
+    backgroundStage,
+    isRunning,
+    isLoading,
+    isIncorporating,
+    openCount,
+    answeredCount,
+    allSettled,
+    canIncorporate,
+    canProceed,
+    load,
+    reply,
+    setItemStatus,
+    incorporate,
+    reReview,
+    proceed,
+    resolveExceeded,
+    // Patch the cache from a live `brainstorm` stream event.
+    upsert: store,
+  }
+})