@cat-factory/app 0.30.6 → 0.32.0

package/app/stores/followUps.ts

@@ -0,0 +1,73 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import { useApi } from '~/composables/useApi'
+import { useWorkspaceStore } from '~/stores/workspace'
+import { useExecutionStore } from '~/stores/execution'
+
+/**
+ * The Follow-up companion action surface. The live item state lives on the run's Coder step
+ * (`step.followUps`) and is kept fresh by the execution stream, so the window reads items
+ * straight off the execution store — this store only wraps the decide actions (file / send
+ * back / answer / dismiss) and tracks which item is mid-action so the window can disable its
+ * buttons. The returned state is also pushed back into the execution store so the UI updates
+ * immediately even before the stream echoes the change.
+ */
+export const useFollowUpsStore = defineStore('followUps', () => {
+  const api = useApi()
+  const workspace = useWorkspaceStore()
+  const execution = useExecutionStore()
+
+  /** Item ids with an action in flight (drives per-row spinners / disabled buttons). */
+  const acting = ref<Set<string>>(new Set())
+  /** The last error message from an action, surfaced inline; cleared on the next action. */
+  const error = ref<string | null>(null)
+
+  function isActing(itemId: string): boolean {
+    return acting.value.has(itemId)
+  }
+
+  function mark(itemId: string, on: boolean) {
+    const next = new Set(acting.value)
+    if (on) next.add(itemId)
+    else next.delete(itemId)
+    acting.value = next
+  }
+
+  /** Run one decide action, reflecting the returned state onto the run's Coder step. */
+  async function act(
+    executionId: string,
+    itemId: string,
+    call: (ws: string) => Promise<unknown>,
+  ): Promise<void> {
+    error.value = null
+    mark(itemId, true)
+    try {
+      const state = await call(workspace.requireId())
+      // Reflect the authoritative state immediately (the stream will also echo it).
+      const instance = execution.getInstance(executionId)
+      const step = instance?.steps.find((s) => s.followUps?.enabled)
+      if (step && state && typeof state === 'object') {
+        step.followUps = state as typeof step.followUps
+      }
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Action failed'
+      throw e
+    } finally {
+      mark(itemId, false)
+    }
+  }
+
+  const fileItem = (executionId: string, itemId: string) =>
+    act(executionId, itemId, (ws) => api.fileFollowUp(ws, executionId, itemId))
+
+  const queueItem = (executionId: string, itemId: string) =>
+    act(executionId, itemId, (ws) => api.queueFollowUp(ws, executionId, itemId))
+
+  const answerItem = (executionId: string, itemId: string, answer: string) =>
+    act(executionId, itemId, (ws) => api.answerFollowUp(ws, executionId, itemId, answer))
+
+  const dismissItem = (executionId: string, itemId: string) =>
+    act(executionId, itemId, (ws) => api.dismissFollowUp(ws, executionId, itemId))
+
+  return { acting, error, isActing, fileItem, queueItem, answerItem, dismissItem }
+})

package/app/stores/kaizen.ts

@@ -0,0 +1,101 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+import type { KaizenGrading, KaizenVerifiedCombo } from '~/types/domain'
+import { useWorkspaceStore } from '~/stores/workspace'
+
+/**
+ * Kaizen state: per-run gradings (for the run-window status surface) and the
+ * workspace-wide history + verified-combo library (for the Kaizen screen). Gradings
+ * arrive both via lazy loads and live over the workspace stream (`upsert`). Never
+ * surfaced on the board — only inside run details + the dedicated screen.
+ */
+export const useKaizenStore = defineStore('kaizen', () => {
+  const api = useApi()
+
+  /** Gradings keyed by run (execution) id, for the run window. */
+  const byExecution = ref<Record<string, KaizenGrading[]>>({})
+  /** Recent grading history for the Kaizen screen. */
+  const history = ref<KaizenGrading[]>([])
+  /** The verified-combo library for the Kaizen screen. */
+  const verified = ref<KaizenVerifiedCombo[]>([])
+  const loadingOverview = ref(false)
+  const loadingExecution = ref<Set<string>>(new Set())
+  /** 503 ⇒ the Kaizen feature isn't configured on this deployment. */
+  const available = ref<boolean | null>(null)
+
+  function gradingsFor(executionId: string): KaizenGrading[] {
+    return byExecution.value[executionId] ?? []
+  }
+
+  /** The grading for a specific step of a run, if any. */
+  function gradingForStep(executionId: string, stepIndex: number): KaizenGrading | null {
+    return gradingsFor(executionId).find((g) => g.stepIndex === stepIndex) ?? null
+  }
+
+  async function loadOverview() {
+    const ws = useWorkspaceStore()
+    loadingOverview.value = true
+    try {
+      const overview = await api.getKaizenOverview(ws.requireId())
+      history.value = overview.gradings
+      verified.value = overview.verified
+      available.value = true
+    } catch (e) {
+      if ((e as { statusCode?: number; status?: number })?.statusCode === 503)
+        available.value = false
+      else throw e
+    } finally {
+      loadingOverview.value = false
+    }
+  }
+
+  async function loadForExecution(executionId: string) {
+    const ws = useWorkspaceStore()
+    loadingExecution.value = new Set(loadingExecution.value).add(executionId)
+    try {
+      const { gradings } = await api.getKaizenForExecution(ws.requireId(), executionId)
+      byExecution.value = { ...byExecution.value, [executionId]: gradings }
+      available.value = true
+    } catch (e) {
+      if ((e as { statusCode?: number; status?: number })?.statusCode === 503)
+        available.value = false
+      else throw e
+    } finally {
+      const next = new Set(loadingExecution.value)
+      next.delete(executionId)
+      loadingExecution.value = next
+    }
+  }
+
+  /** Fold a grading pushed over the stream into both the run cache and the screen history. */
+  function upsert(grading: KaizenGrading) {
+    const current = byExecution.value[grading.executionId] ?? []
+    const replaced = current.some((g) => g.id === grading.id)
+    const nextRun = replaced
+      ? current.map((g) => (g.id === grading.id ? grading : g))
+      : [...current, grading]
+    byExecution.value = { ...byExecution.value, [grading.executionId]: nextRun }
+    // Keep the screen history live too (newest first), if it's been loaded.
+    const inHistory = history.value.some((g) => g.id === grading.id)
+    if (inHistory) history.value = history.value.map((g) => (g.id === grading.id ? grading : g))
+    else history.value = [grading, ...history.value]
+  }
+
+  const isLoadingExecution = (executionId: string) => loadingExecution.value.has(executionId)
+  const verifiedCount = computed(() => verified.value.filter((c) => c.verified).length)
+
+  return {
+    byExecution,
+    history,
+    verified,
+    available,
+    loadingOverview,
+    verifiedCount,
+    gradingsFor,
+    gradingForStep,
+    loadOverview,
+    loadForExecution,
+    upsert,
+    isLoadingExecution,
+  }
+})

package/app/stores/pipelines.ts

@@ -48,6 +48,11 @@ export const usePipelinesStore = defineStore('pipelines', () => {
   const draftConsensus = ref<(ConsensusStepConfig | null)[]>([])
   /** Per-step estimate gating, kept index-aligned with `draft` (null ⇒ always run). */
   const draftGating = ref<(StepGating | null)[]>([])
+  /**
+   * Per-step Follow-up companion toggle, kept index-aligned with `draft`. Only meaningful on
+   * a `coder` step; `false` disables the companion there (default/true ⇒ enabled).
+   */
+  const draftFollowUps = ref<(boolean | null)[]>([])
   /** Organizational labels for the pipeline being assembled/edited. */
   const draftLabels = ref<string[]>([])
   const draftName = ref('New pipeline')
@@ -71,6 +76,7 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     draftThresholds.value.splice(index, 0, null)
     draftConsensus.value.splice(index, 0, null)
     draftGating.value.splice(index, 0, null)
+    draftFollowUps.value.splice(index, 0, null)
   }
 
   function addToDraft(kind: AgentKind) {
@@ -84,6 +90,7 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     draftThresholds.value.splice(index, 1)
     draftConsensus.value.splice(index, 1)
     draftGating.value.splice(index, 1)
+    draftFollowUps.value.splice(index, 1)
   }
 
   function moveInDraft(from: number, to: number) {
@@ -100,6 +107,8 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     draftConsensus.value.splice(to, 0, cons ?? null)
     const [gat] = draftGating.value.splice(from, 1)
     draftGating.value.splice(to, 0, gat ?? null)
+    const [fu] = draftFollowUps.value.splice(from, 1)
+    draftFollowUps.value.splice(to, 0, fu ?? null)
   }
 
   /** Whether the producer step at `index` currently has its companion attached after it. */
@@ -174,6 +183,7 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     draftThresholds.value = reorder(draftThresholds.value)
     draftConsensus.value = reorder(draftConsensus.value)
     draftGating.value = reorder(draftGating.value)
+    draftFollowUps.value = reorder(draftFollowUps.value)
   }
 
   /** Toggle the consensus mechanism on the draft step at `index` (default config / off). */
@@ -191,6 +201,12 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     draftGates.value[index] = !draftGates.value[index]
   }
 
+  /** Toggle the Follow-up companion on the draft (coder) step at `index` (default on → off). */
+  function toggleDraftFollowUps(index: number) {
+    // Default (null/true) is enabled, so the first toggle disables it (false); toggle back to null.
+    draftFollowUps.value[index] = draftFollowUps.value[index] === false ? null : false
+  }
+
   /** Enable/disable the draft step at `index` without removing it. */
   function toggleDraftEnabled(index: number) {
     draftEnabled.value[index] = draftEnabled.value[index] === false
@@ -203,6 +219,7 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     draftThresholds.value = []
     draftConsensus.value = []
     draftGating.value = []
+    draftFollowUps.value = []
     draftLabels.value = []
     draftName.value = 'New pipeline'
     editingId.value = null
@@ -216,6 +233,7 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     draftThresholds.value = pipeline.agentKinds.map((_, i) => pipeline.thresholds?.[i] ?? null)
     draftConsensus.value = pipeline.agentKinds.map((_, i) => pipeline.consensus?.[i] ?? null)
     draftGating.value = pipeline.agentKinds.map((_, i) => pipeline.gating?.[i] ?? null)
+    draftFollowUps.value = pipeline.agentKinds.map((_, i) => pipeline.followUps?.[i] ?? null)
     draftLabels.value = [...(pipeline.labels ?? [])]
     draftName.value = pipeline.name
     editingId.value = pipeline.id
@@ -240,6 +258,11 @@ export const usePipelinesStore = defineStore('pipelines', () => {
         : {}),
       // Only send gating when at least one step has gating enabled.
       ...(draftGating.value.some((g) => g?.enabled) ? { gating: [...draftGating.value] } : {}),
+      // Only send followUps when at least one step disables it (default is on, so only the
+      // explicit `false` opt-outs are worth persisting).
+      ...(draftFollowUps.value.some((f) => f === false)
+        ? { followUps: [...draftFollowUps.value] }
+        : {}),
       // Only send labels when there are any.
       ...(draftLabels.value.length ? { labels: [...draftLabels.value] } : {}),
     }
@@ -297,6 +320,7 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     draftThresholds,
     draftConsensus,
     draftGating,
+    draftFollowUps,
     draftLabels,
     draftName,
     editingId,
@@ -311,6 +335,7 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     toggleCompanion,
     toggleDraftGating,
     toggleDraftGate,
+    toggleDraftFollowUps,
     toggleDraftEnabled,
     toggleDraftConsensus,
     setDraftConsensus,

package/app/stores/ui.ts

@@ -135,6 +135,10 @@ export const useUiStore = defineStore('ui', () => {
     blockId: string
     instanceId: string | null
     stepIndex: number | null
+    // The brainstorm dialogue stage, set only when `view === 'brainstorm'` (its two agent
+    // kinds share one window). Derived from the step's agent kind on the pipeline path, or
+    // passed explicitly on an off-path open.
+    stage?: 'requirements' | 'architecture'
   } | null>(null)
 
   // Agent step-detail overlay: which pipeline step (a run instance + step index)
@@ -149,6 +153,10 @@ export const useUiStore = defineStore('ui', () => {
   // per-call detail from the observability store on open.
   const observabilityInstanceId = ref<string | null>(null)
 
+  // The Kaizen screen (grading history + verified-combo library), a full-panel overlay
+  // opened from the sidebar. Distinct from the per-run grading status shown in run details.
+  const kaizenScreenOpen = ref(false)
+
   /** Current canvas zoom (driven by Vue Flow viewport). */
   const zoom = ref(1)
 
@@ -229,7 +237,20 @@ export const useUiStore = defineStore('ui', () => {
         ? agentKindMeta(step.agentKind).resultView
         : undefined
     if (view && instance) {
-      resultView.value = { view, blockId: instance.blockId, instanceId, stepIndex }
+      // The brainstorm window is shared by both stages; carry which one from the step's kind.
+      const stage =
+        view === 'brainstorm'
+          ? step?.agentKind === 'architecture-brainstorm'
+            ? 'architecture'
+            : 'requirements'
+          : undefined
+      resultView.value = {
+        view,
+        blockId: instance.blockId,
+        instanceId,
+        stepIndex,
+        ...(stage ? { stage } : {}),
+      }
       return
     }
     stepDetail.value = { instanceId, stepIndex }
@@ -452,10 +473,41 @@ export const useUiStore = defineStore('ui', () => {
   function openClarityReview(blockId: string) {
     resultView.value = { view: 'clarity-review', blockId, instanceId: null, stepIndex: null }
   }
+  function openBrainstorm(blockId: string, stage: 'requirements' | 'architecture') {
+    resultView.value = { view: 'brainstorm', blockId, instanceId: null, stepIndex: null, stage }
+  }
   // Open the service-spec window for a service frame (the inspector's "View Requirements").
   function openServiceSpec(blockId: string) {
     resultView.value = { view: 'service-spec', blockId, instanceId: null, stepIndex: null }
   }
+  // Open the Follow-up companion window for a run's Coder step (the blinking chip + the
+  // `followup_pending` notification). Resolves the Coder step index from the run when not
+  // given, so callers that only know the run can still open it.
+  function openFollowUps(instanceId: string, stepIndex: number | null = null) {
+    const execution = useExecutionStore()
+    const instance = execution.getInstance(instanceId)
+    if (!instance) return
+    // A pipeline may carry more than one follow-up-enabled Coder step, so don't blindly pick
+    // the first when no index is given: prefer the step that still has undecided items (the
+    // one the run is parked on), else the current step, else the first enabled one.
+    const resolveIdx = () => {
+      const pending = instance.steps.findIndex(
+        (s) => s.followUps?.enabled && s.followUps.items.some((i) => i.status === 'pending'),
+      )
+      if (pending >= 0) return pending
+      const current = instance.steps[instance.currentStep]
+      if (current?.followUps?.enabled) return instance.currentStep
+      return instance.steps.findIndex((s) => s.followUps?.enabled)
+    }
+    const idx = stepIndex ?? resolveIdx()
+    if (idx < 0) return
+    resultView.value = {
+      view: 'follow-ups',
+      blockId: instance.blockId,
+      instanceId,
+      stepIndex: idx,
+    }
+  }
   function closeResultView() {
     resultView.value = null
   }
@@ -473,6 +525,12 @@ export const useUiStore = defineStore('ui', () => {
   function closeObservability() {
     observabilityInstanceId.value = null
   }
+  function openKaizen() {
+    kaizenScreenOpen.value = true
+  }
+  function closeKaizen() {
+    kaizenScreenOpen.value = false
+  }
 
   return {
     selectedBlockId,
@@ -513,6 +571,7 @@ export const useUiStore = defineStore('ui', () => {
     closeResultView,
     stepDetail,
     observabilityInstanceId,
+    kaizenScreenOpen,
     zoom,
     lod,
     expandedFrames,
@@ -583,11 +642,15 @@ export const useUiStore = defineStore('ui', () => {
     resetAiOnboarding,
     openRequirementReview,
     openClarityReview,
+    openBrainstorm,
     openServiceSpec,
+    openFollowUps,
     closeRequirementReview,
     openStepDetail,
     closeStepDetail,
     openObservability,
     closeObservability,
+    openKaizen,
+    closeKaizen,
   }
 })

package/app/stores/workspaceSettings.ts

@@ -10,6 +10,7 @@ const DEFAULTS: WorkspaceSettings = {
   taskLimitShared: null,
   taskLimitPerType: null,
   storeAgentContext: true,
+  kaizenEnabled: true,
   spendCurrency: null,
   spendMonthlyLimit: null,
 }

package/app/types/brainstorm.ts

@@ -0,0 +1,55 @@
+// Brainstorm (structured-dialogue) wire types. Mirror of `@cat-factory/contracts`'
+// brainstorm.ts, kept in sync by hand like the rest of `~/types/*` (the SPA does not import
+// the backend package directly).
+//
+// A brainstorm agent runs a structured dialogue: it PROPOSES options with explicit
+// trade-offs (raised as review items), a human picks / steers / dismisses, and the picks are
+// folded into ONE converged direction. There are two stages (`requirements`, `architecture`)
+// served by one engine; a block may have one live session per stage.
+//
+// Structurally identical to a requirements review (the items share the same shape), so the
+// per-item types are reused from `~/types/requirements`; only the `stage` discriminator and
+// the converged document (`convergedDirection`) differ.
+
+import type {
+  RequirementReviewItem,
+  ReviewItemCategory,
+  ReviewItemSeverity,
+  ReviewItemStatus,
+} from '~/types/requirements'
+
+export type { ReviewItemCategory, ReviewItemSeverity, ReviewItemStatus }
+
+/** Which dialogue a brainstorm session drives. */
+export type BrainstormStage = 'requirements' | 'architecture'
+
+/** A brainstorm option is the same shape as a requirements-review item. */
+export type BrainstormItem = RequirementReviewItem
+
+/** Lifecycle of a brainstorm session — identical to the requirements review lifecycle. */
+export type BrainstormStatus =
+  | 'ready'
+  | 'incorporating'
+  | 'reviewing'
+  | 'merged'
+  | 'exceeded'
+  | 'incorporated'
+
+/** How a human resolves a session that hit its iteration cap. */
+export type ResolveBrainstormExceededChoice = 'extra-round' | 'proceed' | 'stop-reset'
+
+export interface BrainstormSession {
+  id: string
+  blockId: string
+  stage: BrainstormStage
+  status: BrainstormStatus
+  items: BrainstormItem[]
+  model: string | null
+  convergedDirection: string | null
+  /** Agent passes run so far (initial pass is 1; each re-run adds one). */
+  iteration: number
+  /** The agent-pass budget (from the task's merge preset; an extra round bumps it). */
+  maxIterations: number
+  createdAt: number
+  updatedAt: number
+}

package/app/types/domain.ts

@@ -20,6 +20,7 @@ import type { Notification } from './notifications'
 import type { RequirementReview } from './requirements'
 import type { ConsensusSession, ConsensusStepConfig, StepGating, TaskEstimate } from './consensus'
 import type { ClarityReview } from './clarity'
+import type { BrainstormSession } from './brainstorm'
 import type { MergeThresholdPreset } from './merge'
 import type { ModelPreset } from './model-presets'
 import type { PipelineSchedule } from './recurring'
@@ -256,6 +257,11 @@ export interface TestReport {
 /** The kinds of agents available in the agent palette. */
 export type AgentKind =
   | 'requirements-review'
+  // Brainstorm (structured-dialogue) gates: propose options with trade-offs and let the human
+  // converge. `requirements-brainstorm` runs before the requirements review; `architecture-
+  // brainstorm` before the architect. Both open the shared brainstorm window.
+  | 'requirements-brainstorm'
+  | 'architecture-brainstorm'
   | 'architect'
   | 'researcher'
   | 'coder'
@@ -309,6 +315,9 @@ export type AgentKind =
   // 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'
+  // The Kaizen agent: post-run grader (NOT a pipeline step / palette archetype). Surfaced
+  // only in Model Configuration (its model is pinnable like any agent) and run details.
+  | 'kaizen'
 
 /** A draggable agent definition shown in the agent palette. */
 /** Palette grouping for the agent archetypes (collapsible sections in the builder). */
@@ -387,6 +396,12 @@ export interface Pipeline {
    * always run. Used to make a companion conditional on the task estimate.
    */
   gating?: (StepGating | null)[]
+  /**
+   * Per-step Follow-up companion toggle, parallel to `agentKinds`: governs whether a `coder`
+   * step runs the future-looking Follow-up companion. `followUps[i] === false` disables it;
+   * `null`/`true`/absent ⇒ enabled (a Coder step gets it by default). Ignored on non-coder steps.
+   */
+  followUps?: (boolean | null)[]
   /** Free-form organizational labels for the library (filter/search). */
   labels?: string[]
   /** True when archived: kept but hidden from the default library view. */
@@ -495,6 +510,8 @@ export interface WorkspaceSettings {
   taskLimitPerType: Partial<Record<CreateTaskType, number>> | null
   /** Whether to store the complete provided-context snapshot for each container agent. */
   storeAgentContext: boolean
+  /** Whether the Kaizen agent grades agent steps after each run. On by default. */
+  kaizenEnabled: boolean
   /** Spend budget currency (ISO 4217). Null ⇒ the built-in default (`EUR`). */
   spendCurrency: string | null
   /** Monthly spend budget in `spendCurrency`. Null ⇒ the built-in default. */
@@ -508,6 +525,7 @@ export interface UpdateWorkspaceSettingsInput {
   taskLimitShared?: number | null
   taskLimitPerType?: Partial<Record<CreateTaskType, number>> | null
   storeAgentContext?: boolean
+  kaizenEnabled?: boolean
   spendCurrency?: string | null
   spendMonthlyLimit?: number | null
 }
@@ -520,6 +538,50 @@ export interface ServiceFragmentDefaults {
   fragmentIds: string[]
 }
 
+/** Lifecycle of a Kaizen grading. Mirrors `@cat-factory/contracts`. */
+export type KaizenGradingStatus = 'scheduled' | 'running' | 'complete' | 'failed'
+
+/**
+ * A Kaizen grading of one completed agent step (how smooth/efficient the interaction
+ * was, 1..5, plus recommendations). Mirrors `@cat-factory/contracts`.
+ */
+export interface KaizenGrading {
+  id: string
+  executionId: string
+  blockId: string
+  stepIndex: number
+  agentKind: string
+  model: string
+  promptVersion: number
+  comboKey: string
+  status: KaizenGradingStatus
+  grade: number | null
+  summary: string
+  recommendations: string[]
+  graderModel: string | null
+  error: string | null
+  createdAt: number
+  updatedAt: number
+}
+
+/** A `(promptVersion, agentKind, model)` combo's verification progress. */
+export interface KaizenVerifiedCombo {
+  comboKey: string
+  agentKind: string
+  model: string
+  promptVersion: number
+  consecutiveHighGrades: number
+  verified: boolean
+  verifiedAt: number | null
+  updatedAt: number
+}
+
+/** The Kaizen screen payload: recent grading history + the verified-combo library. */
+export interface KaizenOverview {
+  gradings: KaizenGrading[]
+  verified: KaizenVerifiedCombo[]
+}
+
 /**
  * Real-time events pushed over the workspace WebSocket stream (see
  * `useWorkspaceStream`). Mirrors `WorkspaceEvent` in `@cat-factory/contracts`.
@@ -533,6 +595,8 @@ export type WorkspaceEvent =
   | { type: 'requirements'; review: RequirementReview; at: number }
   | { type: 'consensus'; session: ConsensusSession; at: number }
   | { type: 'clarity'; review: ClarityReview; at: number }
+  | { type: 'brainstorm'; session: BrainstormSession; at: number }
+  | { type: 'kaizen'; grading: KaizenGrading; at: number }
 
 /** Level-of-detail buckets driven by the canvas zoom level. Shallow → deep:
  * `far`/`mid`/`close` govern a service frame (chip → card → opened with tasks);

package/app/types/execution.ts

@@ -382,6 +382,47 @@ export interface PipelineStep {
    * Mirrors `runEnvironmentSchema`.
    */
   environment?: RunEnvironment | null
+  /**
+   * Live Follow-up companion state when this (coder) step has the future-looking companion
+   * enabled: the forward-looking items the Coder streamed (loose ends / side-tasks /
+   * questions) and the send-back loop budget. The chip blinks while any item is `pending`;
+   * the gate holds the pipeline until every item is decided. Mirrors `followUpsStepStateSchema`.
+   */
+  followUps?: FollowUpsStepState | null
+}
+
+/** What a streamed item is: a forward-looking follow-up or a clarifying question. */
+export type FollowUpItemKind = 'follow_up' | 'question'
+
+/** Lifecycle of a single follow-up / question item (mirrors `followUpItemStatusSchema`). */
+export type FollowUpItemStatus = 'pending' | 'filed' | 'queued' | 'answered' | 'dismissed'
+
+/** One forward-looking item the Coder surfaced (mirrors `followUpItemSchema`). */
+export interface FollowUpItem {
+  id: string
+  kind: FollowUpItemKind
+  title: string
+  detail: string
+  suggestedAction?: string | null
+  status: FollowUpItemStatus
+  /** The human's answer to a `question` item, or null while unanswered / not a question. */
+  answer?: string | null
+  /** Canonical external id of the filed ticket (e.g. "owner/repo#123"), when `filed`. */
+  ticketExternalId?: string | null
+  /** URL of the filed ticket, when `filed`. */
+  ticketUrl?: string | null
+  /** True once a queued / answered item was folded into a Coder loop-back. */
+  sentToCoder?: boolean
+  createdAt: number
+  updatedAt: number
+}
+
+/** Live Follow-up companion state on the Coder step (mirrors `followUpsStepStateSchema`). */
+export interface FollowUpsStepState {
+  enabled: boolean
+  items: FollowUpItem[]
+  loops?: number
+  maxLoops?: number
 }
 
 /** One failing CI check the gate's precheck saw (mirrors `gateFailingCheckSchema`). */

package/app/types/notifications.ts

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

package/app/utils/catalog.spec.ts

@@ -14,6 +14,8 @@ import {
 const AGENT_KINDS: AgentKind[] = [
   'requirements-review',
   'clarity-review',
+  'requirements-brainstorm',
+  'architecture-brainstorm',
   'bug-investigator',
   'task-estimator',
   'architect',