@cat-factory/app 0.6.0

package/app/utils/catalog.ts

@@ -0,0 +1,455 @@
+import type {
+  AgentArchetype,
+  AgentCategory,
+  AgentKind,
+  BlockStatus,
+  BlockType,
+} from '~/types/domain'
+
+/** Simple unique id helper (fine for a client-only prototype). */
+export function uid(prefix = 'id'): string {
+  return `${prefix}_${Math.random().toString(36).slice(2, 9)}`
+}
+
+/**
+ * Ordered palette categories — the collapsible sections the pipeline builder groups the
+ * agent archetypes under. The order here is the order they render.
+ */
+export const AGENT_CATEGORIES: { id: AgentCategory; label: string }[] = [
+  { id: 'review', label: 'Review & triage' },
+  { id: 'design', label: 'Design & research' },
+  { id: 'build', label: 'Implementation' },
+  { id: 'test', label: 'Testing' },
+  { id: 'docs', label: 'Documentation' },
+  { id: 'gates', label: 'Gates & observability' },
+]
+
+/** The agent palette — the building blocks of a development pipeline, grouped by category. */
+export const AGENT_ARCHETYPES: AgentArchetype[] = [
+  {
+    kind: 'requirements-review',
+    label: 'Requirements Reviewer',
+    icon: 'i-lucide-clipboard-check',
+    color: '#f59e0b',
+    category: 'review',
+    description:
+      'Reviews the collected context (description + linked PRDs/RFCs) for gaps, ambiguities, assumptions and risks before the architect starts.',
+    // Opens the dedicated structured review window (answer/dismiss findings → incorporate
+    // → re-review loop) instead of the generic prose step-detail panel.
+    resultView: 'requirements-review',
+  },
+  {
+    kind: 'clarity-review',
+    label: 'Clarity Reviewer',
+    icon: 'i-lucide-bug',
+    color: '#f59e0b',
+    category: 'review',
+    description:
+      'Triages a bug report for fixability — raising questions, gaps and assumptions about the report before anyone starts fixing it.',
+    // Opens the dedicated structured review window (answer/dismiss findings → incorporate
+    // → re-review loop) instead of the generic prose step-detail panel.
+    resultView: 'clarity-review',
+  },
+  {
+    // A read-only `/explore` agent (like the architect), so it's a first-class palette block
+    // a user can add to any pipeline — not just the `pl_bugfix` preset where it leads. No
+    // `resultView`: the enriched report is prose, so it uses the generic step-detail panel.
+    kind: 'bug-investigator',
+    label: 'Bug Investigator',
+    icon: 'i-lucide-search-code',
+    color: '#38bdf8',
+    category: 'review',
+    description:
+      'Read-only codebase investigation that traces the bug to its root cause and produces an enriched report (no code changes).',
+  },
+  {
+    kind: 'task-estimator',
+    label: 'Task Estimator',
+    icon: 'i-lucide-gauge',
+    color: '#eab308',
+    category: 'review',
+    description:
+      'Triages the task after requirements are clarified — rates Complexity, Risk and Impact (0..1). Used to gate consensus and conditional companion steps, and shown as ratings on the task.',
+  },
+  {
+    kind: 'architect',
+    label: 'Architect',
+    icon: 'i-lucide-drafting-compass',
+    color: '#a78bfa',
+    category: 'design',
+    description: 'Designs the shape of the solution and breaks down the work.',
+  },
+  {
+    kind: 'researcher',
+    label: 'Researcher',
+    icon: 'i-lucide-telescope',
+    color: '#38bdf8',
+    category: 'design',
+    description: 'Investigates prior art, libraries and constraints.',
+  },
+  {
+    kind: 'coder',
+    label: 'Coder',
+    icon: 'i-lucide-code-xml',
+    color: '#34d399',
+    category: 'build',
+    description: 'Implements the block according to the design.',
+  },
+  {
+    kind: 'integrator',
+    label: 'Integrator',
+    icon: 'i-lucide-plug-zap',
+    color: '#fb923c',
+    category: 'build',
+    description: 'Wires the block into the surrounding system.',
+  },
+  {
+    kind: 'mocker',
+    label: 'Mock Builder',
+    icon: 'i-lucide-server-cog',
+    color: '#fb7185',
+    category: 'build',
+    description: 'Builds WireMock mocks for external services and wires them into local/CI runs.',
+  },
+  {
+    kind: 'tester',
+    label: 'Tester',
+    icon: 'i-lucide-flask-conical',
+    color: '#fbbf24',
+    category: 'test',
+    description: 'Exercises the change against the mocks + spec scenarios and reports outcomes.',
+    // Opens the dedicated structured test-report window (scenarios → outcomes →
+    // concerns tree) instead of the generic prose step-detail panel.
+    resultView: 'tester',
+  },
+  {
+    kind: 'playwright',
+    label: 'Acceptance Test Author',
+    icon: 'i-lucide-theater',
+    color: '#e879f9',
+    category: 'test',
+    description:
+      "Turns scenarios into runnable tests — Playwright for frontend, the project's own framework for backend; adds only new ones.",
+  },
+  {
+    kind: 'documenter',
+    label: 'Documenter',
+    icon: 'i-lucide-book-open-text',
+    color: '#818cf8',
+    category: 'docs',
+    description: 'Produces docs and usage examples.',
+  },
+  {
+    kind: 'business-documenter',
+    label: 'Domain Rules Documenter',
+    icon: 'i-lucide-scroll-text',
+    color: '#84cc16',
+    category: 'docs',
+    description:
+      'Reads the implementation and writes/updates business-logic & domain-rule docs in the repo, weaving in linked context documents.',
+  },
+  {
+    kind: 'business-reviewer',
+    label: 'Domain Rules Reviewer',
+    icon: 'i-lucide-shield-alert',
+    color: '#ef4444',
+    category: 'docs',
+    description:
+      'Reviews a change against the documented domain rules and reports violations, undocumented changes and unexpected drift.',
+  },
+]
+
+/**
+ * Companion archetypes — dependent agents that review a specific producer and loop it back
+ * for rework. They are NOT free palette blocks: the builder surfaces them as a toggle on
+ * their producer step (a reviewer right after the coder it reviews), because a companion
+ * makes no sense without its producer or anywhere else in the chain. They still need display
+ * metadata (icons / labels) for the run timeline + saved-pipeline rendering, and their model
+ * is pinnable, so they live here and are folded into {@link AGENT_BY_KIND}. See
+ * {@link companionForProducer} for the producer→companion mapping (mirrors the backend
+ * `COMPANIONS` registry).
+ */
+export const COMPANION_ARCHETYPES: AgentArchetype[] = [
+  {
+    kind: 'reviewer',
+    label: 'Reviewer (companion)',
+    icon: 'i-lucide-scan-eye',
+    color: '#f472b6',
+    description:
+      "Coder's companion: rates the change for quality/correctness and loops it back for automatic rework below the threshold.",
+  },
+  {
+    kind: 'architect-companion',
+    label: 'Architect Companion',
+    icon: 'i-lucide-bug-play',
+    color: '#c084fc',
+    description:
+      "Challenges the architect's design for quality and completeness, looping it back for rework below the threshold before a human reviews it.",
+  },
+  {
+    kind: 'spec-companion',
+    label: 'Spec Reviewer',
+    icon: 'i-lucide-list-checks',
+    color: '#2dd4bf',
+    description:
+      'Reviews the spec — especially acceptance-scenario coverage — rating it and looping the Spec Writer back for automatic rework below the threshold, instead of requiring a human review.',
+  },
+]
+
+/**
+ * Producer agent kind → its companion agent kind. Mirrors the backend `COMPANIONS` registry
+ * (`@cat-factory/agents`). The builder shows an "add companion" toggle on a producer step
+ * found here, and inserts/removes the companion immediately after it.
+ */
+export const COMPANION_FOR_PRODUCER: Record<string, AgentKind> = {
+  coder: 'reviewer',
+  architect: 'architect-companion',
+  'spec-writer': 'spec-companion',
+}
+
+const COMPANION_KINDS: ReadonlySet<string> = new Set(COMPANION_ARCHETYPES.map((a) => a.kind))
+
+/** The companion kind that depends on a producer kind, or undefined if it has none. */
+export function companionForProducer(kind: string): AgentKind | undefined {
+  return COMPANION_FOR_PRODUCER[kind]
+}
+
+/**
+ * Whether a kind is a dependent producer-companion (reviewer / architect-companion /
+ * spec-companion) — rendered as a toggle on its producer, not a standalone palette block.
+ * Distinct from `pipelineRender`'s `isCompanionKind`, which also counts the Tester's `fixer`.
+ */
+export function isProducerCompanion(kind: string): boolean {
+  return COMPANION_KINDS.has(kind)
+}
+
+export const AGENT_BY_KIND: Record<AgentKind, AgentArchetype> = Object.fromEntries(
+  [...AGENT_ARCHETYPES, ...COMPANION_ARCHETYPES].map((a) => [a.kind, a]),
+) as Record<AgentKind, AgentArchetype>
+
+/**
+ * Agent kinds eligible for the optional consensus mechanism (the pipeline builder shows an
+ * "Enable Consensus" toggle for these). Mirrors the backend default-eligible set assigned by
+ * `registerConsensusTraits()` in `@cat-factory/consensus` — hand-synced, like the other
+ * frontend mirrors. In CONSENSUS mode `architect`/`analysis` reason over the provided context
+ * rather than exploring a checkout (a deliberate trade, gated by the task estimate).
+ */
+export const CONSENSUS_ELIGIBLE_KINDS: ReadonlySet<string> = new Set([
+  'architect',
+  'analysis',
+  'reviewer',
+  'task-estimator',
+])
+
+/** Whether a step kind can be flipped into the consensus execution mode. */
+export function isConsensusEligibleKind(kind: string): boolean {
+  return CONSENSUS_ELIGIBLE_KINDS.has(kind)
+}
+
+/**
+ * Display metadata for the engine-driven "system" kinds — the gate/automation
+ * steps (blueprint mapper, conflicts gate + resolver, CI gate + fixer, merger)
+ * that appear in seeded pipelines and run timelines but are NOT user-addable
+ * palette archetypes, so they're intentionally absent from {@link AGENT_ARCHETYPES}
+ * / {@link AGENT_BY_KIND}. Looked up through {@link agentKindMeta}.
+ */
+export const SYSTEM_AGENT_META: Record<string, AgentArchetype> = {
+  'spec-writer': {
+    kind: 'spec-writer',
+    label: 'Spec Writer',
+    icon: 'i-lucide-clipboard-list',
+    color: '#c084fc',
+    description:
+      "Aggregates every task's clarified requirements into the service's in-repo specification (spec.json) with full acceptance-scenario coverage, derived into Gherkin.",
+  },
+  blueprints: {
+    kind: 'blueprints',
+    label: 'Blueprinter',
+    icon: 'i-lucide-map',
+    color: '#22d3ee',
+    description: 'Maps the repository into the service → modules blueprint.',
+  },
+  conflicts: {
+    kind: 'conflicts',
+    label: 'Conflicts Gate',
+    icon: 'i-lucide-git-merge',
+    color: '#f97316',
+    description: 'Ensures the PR is mergeable with its base, looping the resolver on conflicts.',
+    // Opens the dedicated gate window (verdict, attempts, conflict detail) instead of
+    // the generic prose step-detail panel. Shared with the CI gate.
+    resultView: 'gate',
+  },
+  'conflict-resolver': {
+    kind: 'conflict-resolver',
+    label: 'Conflict Resolver',
+    icon: 'i-lucide-git-merge',
+    color: '#f97316',
+    description: 'Merges the base in and resolves conflicts on the PR branch.',
+  },
+  ci: {
+    kind: 'ci',
+    label: 'CI Gate',
+    icon: 'i-lucide-shield-check',
+    color: '#38bdf8',
+    description: 'Gates the PR on green CI, looping the CI fixer on failure.',
+    // Opens the dedicated gate window (verdict, attempts, the failing checks) instead
+    // of the generic prose step-detail panel. Shared with the conflicts gate.
+    resultView: 'gate',
+  },
+  'ci-fixer': {
+    kind: 'ci-fixer',
+    label: 'CI Fixer',
+    icon: 'i-lucide-wrench',
+    color: '#38bdf8',
+    description: 'Fixes failing CI and pushes back to the PR branch.',
+  },
+  fixer: {
+    kind: 'fixer',
+    label: 'Fixer',
+    icon: 'i-lucide-wrench',
+    color: '#fbbf24',
+    description:
+      "Tester's companion: fixes the bugs the tester found and pushes back, then the tester re-runs.",
+  },
+  merger: {
+    kind: 'merger',
+    label: 'Merger',
+    icon: 'i-lucide-git-pull-request',
+    color: '#a3e635',
+    description: 'Scores the PR and auto-merges within the task thresholds, or asks for review.',
+  },
+  // A polling gate (no model of its own) that watches the released PR's observability
+  // signals after merge and escalates to the on-call agent on a regression. NOT in any
+  // default pipeline and NOT a standing palette archetype — the palette surfaces it
+  // conditionally (only with an observability integration connected, see AgentPalette),
+  // but it still needs display metadata here so timelines/saved pipelines render it.
+  'post-release-health': {
+    kind: 'post-release-health',
+    label: 'Post-Release Health',
+    icon: 'i-lucide-activity',
+    color: '#f43f5e',
+    category: 'gates',
+    description:
+      'Watches the released PR’s Datadog monitors/SLOs after merge and escalates to the on-call agent on a regression.',
+    // Opens the dedicated gate window (verdict, attempts, watch window) like the other gates.
+    resultView: 'gate',
+  },
+}
+
+/**
+ * The observability-gated palette block. NOT in {@link AGENT_ARCHETYPES} (so it never
+ * pollutes model-defaults — it runs no model — and is never offered unconditionally):
+ * the pipeline builder appends it to the palette ONLY when the workspace has an
+ * observability integration connected, and the backend rejects it otherwise.
+ */
+export const OBSERVABILITY_GATE_ARCHETYPE: AgentArchetype =
+  SYSTEM_AGENT_META['post-release-health']!
+
+/**
+ * Engine-driven kinds that still run an LLM, so their model is worth pinning per
+ * workspace even though they aren't user-addable palette archetypes. Surfaced in the
+ * Default Models settings alongside {@link AGENT_ARCHETYPES} (but NOT in the pipeline
+ * palette). The pure gates (`ci`, `conflicts`) are excluded — they run no model, so a
+ * default model would do nothing for them.
+ */
+export const MODEL_CONFIGURABLE_SYSTEM_KINDS: AgentArchetype[] = [
+  ...['spec-writer', 'blueprints', 'conflict-resolver', 'ci-fixer', 'fixer', 'merger'].map(
+    (kind) => SYSTEM_AGENT_META[kind]!,
+  ),
+  // Companions run LLMs but aren't palette-addable (they're producer toggles), so include
+  // them here to keep their per-workspace default model pinnable in the Model Defaults panel.
+  ...COMPANION_ARCHETYPES,
+]
+
+/** Fallback metadata for any kind with no archetype or system entry (unknown/custom). */
+const FALLBACK_AGENT_META: Omit<AgentArchetype, 'kind'> = {
+  label: 'Agent',
+  icon: 'i-lucide-bot',
+  color: '#94a3b8',
+  description: 'Agent step.',
+}
+
+/**
+ * Resolve display metadata for ANY agent kind — a palette archetype (incl. custom
+ * agents registered into {@link AGENT_BY_KIND}), an engine system kind, or an
+ * unknown one — ALWAYS returning a usable icon/label/color. This is the single
+ * lookup every pipeline / run renderer should use so a kind missing from the
+ * archetype map (e.g. `ci`/`merger`/`blueprints` in a seeded pipeline) can never
+ * blow up a component with an undefined access.
+ */
+export function agentKindMeta(kind: string): AgentArchetype {
+  return (
+    AGENT_BY_KIND[kind as AgentKind] ??
+    SYSTEM_AGENT_META[kind] ?? { kind: kind as AgentKind, ...FALLBACK_AGENT_META }
+  )
+}
+
+/** Visual metadata for each architecture block type. */
+export const BLOCK_TYPE_META: Record<BlockType, { label: string; icon: string; accent: string }> = {
+  frontend: { label: 'Frontend', icon: 'i-lucide-monitor', accent: '#60a5fa' },
+  service: { label: 'Service', icon: 'i-lucide-server', accent: '#a78bfa' },
+  api: { label: 'API', icon: 'i-lucide-route', accent: '#22d3ee' },
+  database: { label: 'Database', icon: 'i-lucide-database', accent: '#34d399' },
+  queue: { label: 'Queue', icon: 'i-lucide-list-ordered', accent: '#fbbf24' },
+  integration: {
+    label: 'Integration',
+    icon: 'i-lucide-workflow',
+    accent: '#fb923c',
+  },
+  external: { label: 'External', icon: 'i-lucide-globe', accent: '#94a3b8' },
+  environment: {
+    label: 'Environment',
+    icon: 'i-lucide-container',
+    accent: '#2dd4bf',
+  },
+}
+
+/** Color + iconography for each block status. */
+export const STATUS_META: Record<
+  BlockStatus,
+  { label: string; color: string; chip: string; icon: string }
+> = {
+  planned: {
+    label: 'Planned',
+    color: '#64748b',
+    chip: 'neutral',
+    icon: 'i-lucide-circle-dashed',
+  },
+  ready: {
+    label: 'Ready',
+    color: '#3b82f6',
+    chip: 'info',
+    icon: 'i-lucide-circle-play',
+  },
+  in_progress: {
+    label: 'In progress',
+    color: '#6366f1',
+    chip: 'primary',
+    icon: 'i-lucide-loader',
+  },
+  blocked: {
+    // Generic copy: `blocked` is overloaded — a run parks here for a human
+    // decision, an approval gate, OR a terminal failure. Surfaces that know the
+    // specific reason (TaskCard, the inspector) show the precise label/action;
+    // this fallback must NOT imply a decision is the only thing it can be.
+    label: 'Needs attention',
+    color: '#f59e0b',
+    chip: 'warning',
+    icon: 'i-lucide-alert-triangle',
+  },
+  pr_ready: {
+    label: 'PR ready',
+    color: '#22c55e',
+    chip: 'success',
+    icon: 'i-lucide-git-pull-request',
+  },
+  done: {
+    label: 'Done',
+    color: '#16a34a',
+    chip: 'success',
+    icon: 'i-lucide-circle-check',
+  },
+}
+
+/** Visual metadata for module sub-frames. */
+export const MODULE_META = { icon: 'i-lucide-package', color: '#a78bfa' }

package/app/utils/dnd.ts

@@ -0,0 +1,29 @@
+import type { BlockType } from '~/types/domain'
+
+/** MIME-ish key used to carry palette payloads across the HTML5 DnD boundary. */
+export const DND_MIME = 'application/agent-board'
+
+export type DndPayload =
+  | { kind: 'block'; blockType: BlockType }
+  | { kind: 'pipeline'; pipelineId: string }
+
+export function setDndPayload(event: DragEvent, payload: DndPayload) {
+  event.dataTransfer?.setData(DND_MIME, JSON.stringify(payload))
+  if (event.dataTransfer) event.dataTransfer.effectAllowed = 'copy'
+}
+
+export function readDndPayload(event: DragEvent): DndPayload | null {
+  const raw = event.dataTransfer?.getData(DND_MIME)
+  if (!raw) return null
+  try {
+    return JSON.parse(raw) as DndPayload
+  } catch {
+    return null
+  }
+}
+
+/** Walk up from the drop target to find the block it landed on, if any. */
+export function blockIdFromEvent(event: DragEvent): string | null {
+  const el = (event.target as HTMLElement | null)?.closest('[data-block-id]')
+  return el?.getAttribute('data-block-id') ?? null
+}

package/app/utils/observability.ts

@@ -0,0 +1,52 @@
+// Formatting + derivation helpers for the LLM observability surfaces (inline step
+// rollups + the drill-down panel). Kept here so the components stay declarative and
+// the number-crunching is unit-testable.
+
+import type { StepMetrics } from '~/types/execution'
+
+/** Compact token count: 1234 → "1.2k", 980 → "980", 2_500_000 → "2.5M". */
+export function formatTokens(n: number): string {
+  if (n < 1000) return `${n}`
+  if (n < 1_000_000) return `${(n / 1000).toFixed(n < 10_000 ? 1 : 0)}k`
+  return `${(n / 1_000_000).toFixed(1)}M`
+}
+
+/** Compact duration: 850 → "850ms", 1500 → "1.5s", 90_000 → "1m 30s". */
+export function formatMs(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  const totalSec = ms / 1000
+  if (totalSec < 60) return `${totalSec.toFixed(totalSec < 10 ? 1 : 0)}s`
+  const m = Math.floor(totalSec / 60)
+  const sec = Math.round(totalSec % 60)
+  return sec ? `${m}m ${sec}s` : `${m}m`
+}
+
+/** A ratio (0..1) as a whole-number percentage. */
+export function pct(ratio: number): number {
+  return Math.round(ratio * 100)
+}
+
+/**
+ * Output-limit headroom for a step's rollup: the fraction of the output ceiling the
+ * closest call consumed (0..1), or null when the ceiling is unknown. 1 (or any
+ * truncated call) means a call hit the limit and was cut short.
+ */
+export function headroomRatio(
+  m: Pick<StepMetrics, 'peakCompletionTokens' | 'maxOutputTokens'>,
+): number | null {
+  if (m.maxOutputTokens == null || m.maxOutputTokens <= 0) return null
+  return Math.min(1, m.peakCompletionTokens / m.maxOutputTokens)
+}
+
+/** Share of a step's latency spent in transport/proxy overhead (0..1), or null. */
+export function transportRatio(m: Pick<StepMetrics, 'upstreamMs' | 'overheadMs'>): number | null {
+  const total = m.upstreamMs + m.overheadMs
+  return total > 0 ? m.overheadMs / total : null
+}
+
+/** Tailwind text/bg colour for an output-headroom level (green → amber → red). */
+export function headroomColor(ratio: number | null, truncated: boolean): string {
+  if (truncated || (ratio != null && ratio >= 0.98)) return 'text-rose-400'
+  if (ratio != null && ratio >= 0.8) return 'text-amber-400'
+  return 'text-emerald-400'
+}

package/app/utils/pipelineRender.ts

@@ -0,0 +1,151 @@
+// Shared rendering helpers for the run-step / pipeline views (PipelineProgress,
+// TaskPipelineMini, AgentStepDetail), so the "is this step still live?" logic stays
+// in one place rather than being re-derived as inline ternaries per component.
+
+import type { AgentState, PipelineStep } from '~/types/execution'
+
+/**
+ * Visual state of a conditionally-run companion attached to a gate step (today the
+ * Tester's `fixer`): it MIGHT run (`possible`), is running now (`running`), ran at
+ * least once (`completed`), the gate passed without ever needing it (`skipped`), or
+ * it was mid-run when the pipeline failed and gave up (`failed`).
+ */
+export type CompanionState = 'possible' | 'running' | 'completed' | 'skipped' | 'failed'
+
+/**
+ * Visual language for a step (or its companion) that was left `working` when its
+ * run failed. A failed mid-flight step is NOT live — it should read as "Failed" with
+ * a red cross, never a frozen/spinning loader or a misleading "Working" label.
+ */
+export const FAILED_STEP_META = {
+  label: 'Failed',
+  color: '#ef4444',
+  icon: 'i-lucide-circle-x',
+} as const
+
+/**
+ * Whether a step left in `working` state should be rendered as failed: it never
+ * finished, and its run has terminated as `failed`, so the engine gave up on it.
+ */
+export function isFailedStep(state: AgentState, runFailed: boolean): boolean {
+  return runFailed && state === 'working'
+}
+
+/** Descriptor for the companion node a gate step renders beneath itself. */
+export interface GateCompanion {
+  /** Agent kind of the companion (resolved through `agentKindMeta` for icon/label). */
+  kind: string
+  state: CompanionState
+}
+
+/** Display metadata per companion state (badge label + Tailwind colour classes). */
+export const COMPANION_STATE_META: Record<
+  CompanionState,
+  { label: string; dot: string; text: string; icon: string }
+> = {
+  possible: {
+    label: 'May run',
+    dot: 'border-slate-600 bg-slate-800/40',
+    text: 'text-slate-400',
+    icon: 'i-lucide-circle-dashed',
+  },
+  running: {
+    label: 'Running',
+    dot: 'border-amber-400 bg-amber-500/20',
+    text: 'text-amber-300',
+    icon: 'i-lucide-loader',
+  },
+  completed: {
+    label: 'Ran',
+    dot: 'border-emerald-500 bg-emerald-500/20',
+    text: 'text-emerald-300',
+    icon: 'i-lucide-circle-check',
+  },
+  skipped: {
+    label: 'Skipped',
+    dot: 'border-slate-700 bg-slate-800/40',
+    text: 'text-slate-500',
+    icon: 'i-lucide-circle-slash',
+  },
+  failed: {
+    label: 'Gave up',
+    dot: 'border-rose-500 bg-rose-500/20',
+    text: 'text-rose-400',
+    icon: 'i-lucide-circle-x',
+  },
+}
+
+/**
+ * The conditionally-run companion (if any) a gate step drives, with its current
+ * state — so the pipeline views can render it as a distinct sub-node marked
+ * possible / running / completed / skipped. The Tester's `fixer` loop is modelled via
+ * `step.test`; the polling gates (`ci` → `ci-fixer`, `conflicts` → `conflict-resolver`)
+ * via `step.gate`, which all share the same possible/running/completed/skipped shape.
+ */
+export function gateCompanionFor(step: PipelineStep, runFailed = false): GateCompanion | null {
+  if (step.agentKind === 'tester') {
+    const attempts = step.test?.attempts ?? 0
+    if (step.state === 'done') {
+      // The gate finished: it ran the fixer iff it ever dispatched one.
+      return { kind: 'fixer', state: attempts > 0 ? 'completed' : 'skipped' }
+    }
+    // A fixer caught mid-loop by a failed run gave up, not "running".
+    if (step.test?.phase === 'fixing')
+      return { kind: 'fixer', state: runFailed ? 'failed' : 'running' }
+    if (attempts > 0) return { kind: 'fixer', state: 'completed' }
+    // Pending, or testing with no attempt yet — the fixer might still be needed.
+    return { kind: 'fixer', state: 'possible' }
+  }
+  const helper =
+    step.agentKind === 'ci'
+      ? 'ci-fixer'
+      : step.agentKind === 'conflicts'
+        ? 'conflict-resolver'
+        : null
+  if (helper) {
+    const attempts = step.gate?.attempts ?? 0
+    if (step.state === 'done') {
+      // The gate passed: it ran the helper iff it ever dispatched one.
+      return { kind: helper, state: attempts > 0 ? 'completed' : 'skipped' }
+    }
+    // A helper (ci-fixer / conflict-resolver) caught mid-run when the gate exhausted
+    // its attempt budget and the run failed gave up — never show it as "running".
+    if (step.gate?.phase === 'working')
+      return { kind: helper, state: runFailed ? 'failed' : 'running' }
+    if (attempts > 0) return { kind: helper, state: 'completed' }
+    // Checking the precheck with no escalation yet — the helper might still be needed.
+    return { kind: helper, state: 'possible' }
+  }
+  return null
+}
+
+/**
+ * Whether an agent kind is a companion of a producer step (the quality companions
+ * that grade-and-loop, plus the Tester's `fixer`). Used to give companion steps a
+ * visually distinct treatment in the pipeline.
+ */
+export function isCompanionKind(kind: string): boolean {
+  return (
+    kind === 'reviewer' ||
+    kind === 'architect-companion' ||
+    kind === 'spec-companion' ||
+    kind === 'fixer'
+  )
+}
+
+/**
+ * Tailwind classes for a subtask-item status icon. An in-progress item spins only
+ * while the run is live: once the run has failed, a step left mid-flight (its item
+ * state still `in_progress`) keeps its colour but stops spinning, matching the frozen
+ * failure card. Completed items are emerald, everything else muted.
+ */
+export function subtaskIconClass(status: string, runFailed: boolean): string[] {
+  return [
+    status === 'in_progress'
+      ? runFailed
+        ? 'text-indigo-400'
+        : 'animate-spin text-indigo-400'
+      : '',
+    status === 'completed' ? 'text-emerald-400' : 'text-slate-500',
+  ]
+}