@cat-factory/app 0.234.1 → 0.235.0

package/README.md

@@ -3,10 +3,10 @@
 The user-facing app, packaged as a **reusable Nuxt 4 layer**: a single-page app
 that runs entirely in the browser and renders the architecture board, drives agent
 pipelines, and reflects live execution. A deployment consumes it via
-`extends: ['@cat-factory/app']` (see [`deploy/frontend`](../../deploy/frontend)).
-It talks to the [backend Worker](../../backend/README.md) over REST and a single
+`extends: ['@cat-factory/app']` (see [`deploy/frontend`](https://github.com/kibertoad/cat-factory/tree/main/deploy/frontend)).
+It talks to the [backend Worker](https://github.com/kibertoad/cat-factory/blob/main/backend/README.md) over REST and a single
 WebSocket, sharing wire types from
-[`@cat-factory/contracts`](../../backend/packages/contracts).
+[`@cat-factory/contracts`](https://github.com/kibertoad/cat-factory/tree/main/backend/packages/contracts).
 
 The SPA source lives under `app/` (the Nuxt srcDir).
 
@@ -364,7 +364,7 @@ is SUPPRESSED rather than unmounted, because it holds the running tour's resolve
 remount would re-resolve it against gates that may have flipped since the tour started.
 
 The decisions behind this surface, and why each alternative was rejected, are recorded in
-[ADR 0036](../../backend/docs/adr/0036-in-app-tutorials.md). This section is the authority on how
+[ADR 0036](https://github.com/kibertoad/cat-factory/blob/main/backend/docs/adr/0036-in-app-tutorials.md). This section is the authority on how
 the thing WORKS.
 
 A tour is **data, not components**: an ordered list of steps, each pointing at an on-screen
@@ -552,11 +552,26 @@ The recurring product bug behind most e2e flakes: a stale full-snapshot refresh
 live state. The SPA has two delivery shapes and mixing them wrong drops live-added state with NO
 event left to restore it.
 
-- **Know how your entity is delivered.** A `board` event is COARSE: no payload, only a debounced
-  full `workspace.refresh()`, and `hydrate` REPLACES whole lists. A spawned task/module block
-  reaches the browser ONLY this way. Targeted events (`execution`/`bootstrap`/`initiative`) carry
-  the entity and `upsert` it, so they don't clobber. Prefer a targeted upsert for anything that
-  must appear reliably.
+- **Know how your entity is delivered.** Targeted events (`execution`/`bootstrap`/`initiative`)
+  carry the entity and `upsert` it, so they don't clobber. A `board` event is delivered EITHER
+  way and the backend decides per change: it carries `block` when the change is fully described
+  by one (a spawned task, a field edit, a dependency toggle, a move), and carries none when it is
+  not (a removal, a reparent, a resize, a blueprint reconcile). A payload-less `board` event still
+  means a debounced full `workspace.refresh()`, where `hydrate` REPLACES whole lists. Routing
+  lives in `composables/workspaceStream/applyWorkspaceEvent.ts`, whose `switch` carries a `never`
+  guard: a new `WorkspaceEvent` member fails the BUILD rather than falling through to nothing. The
+  emit-site decision lives in `BoardService.emitBoardChanged`'s doc comment. Prefer a targeted
+  upsert for anything that must appear reliably.
+- **Two blocks are refused a payload at the wire, on EVERY event that carries one.** Kernel's
+  `deliverableBoardBlock` is the single gate (both facades' `boardChanged` AND `bootstrapChanged`
+  assemble through it, via `boardWireEvent`/`bootstrapWireEvent`), so a new emitter cannot
+  reintroduce either by forgetting: a service FRAME, whose position and size are a per-board
+  `WorkspaceMount` override that one shared payload cannot state correctly on the several boards a
+  fan-out reaches; and a headless `internal` anchor block, which `composeBoard` filters out of
+  every snapshot and which would therefore render as a card no later read can remove. Both degrade
+  to the coarse signal, so nothing is lost but the refresh. A bootstrap's frame is always the first
+  case, which is why the `bootstrap` event's job rides live while the frame's own transitions
+  arrive as coarse `board` events beside it.
 - **Full refreshes MUST be monotonic.** Two `refresh()` calls can be in flight; a staler one
   resolving later overwrites the newer. `workspace.refresh()` guards this with a sequence. Do not
   reintroduce an unguarded `hydrate(await fetch())`, and apply the guard to any new coalesced
@@ -583,7 +598,7 @@ event left to restore it.
 All user-facing SPA copy goes through `@nuxtjs/i18n`; never hard-code a display string. This
 layer ships the base `en` locale, and a downstream deployment overrides by dropping its own files
 (the per-layer deep-merge is the override seam, consumer wins key by key). Migration status:
-[`docs/internal/localization.md`](../../docs/internal/localization.md).
+[`docs/internal/localization.md`](https://github.com/kibertoad/cat-factory/blob/main/docs/internal/localization.md).
 
 - `i18n/locales/<locale>.json`: the catalogs (the v9+ `i18n/` convention, NOT `app/locales/`).
 - `i18n/i18n.config.ts`: runtime vue-i18n behaviour only (fallback locale, the plural
@@ -688,7 +703,7 @@ auto-imported
 (`ResultWindowShell`, the `StepRunMeta` run-metadata block, `useResultView`, …), and the
 namespacing / degradation rules are in
 [`app/docs/consumer-extensions.md`](./app/docs/consumer-extensions.md); a full worked
-example ships in [`deploy/frontend`](../../deploy/frontend) (the `acme:security` module).
+example ships in [`deploy/frontend`](https://github.com/kibertoad/cat-factory/tree/main/deploy/frontend) (the `acme:security` module).
 
 ## Key UI surfaces
 
@@ -795,5 +810,5 @@ pnpm lint         # oxlint + oxfmt --check
 ```
 
 > Building/deploying the static site is covered in the deployment docs: see the
-> [top-level README → Deployment](../../README.md#deployment) and
-> [`deploy/frontend/README.md`](../../deploy/frontend/README.md).
+> [top-level README → Deployment](https://github.com/kibertoad/cat-factory/blob/main/README.md#deployment) and
+> [`deploy/frontend/README.md`](https://github.com/kibertoad/cat-factory/blob/main/deploy/frontend/README.md).

package/app/components/pipeline/AgentKindIcon.vue

@@ -2,7 +2,7 @@
 // The single rendering path for an agent kind's icon (+ optional label) anywhere a
 // pipeline or run lists its steps. Resolves display metadata through
 // `agentKindMeta`, which is total over every kind — palette archetypes, custom
-// agents and the engine's system kinds (ci / merger / blueprints / conflicts) — so
+// agents and the engine's system kinds (ci / merger / conflicts) — so
 // a saved pipeline that contains a system kind can never blow up the renderer.
 import { computed } from 'vue'
 import { agentKindMeta } from '~/utils/catalog'

package/app/components/settings/ModelConfigurationPanel.vue

@@ -56,8 +56,8 @@ const busy = ref(false)
 const filter = ref('')
 
 // The palette archetypes PLUS the engine-driven kinds that still run an LLM
-// (spec-writer, merger, the fixers/resolver). The pure gates run no model, so they
-// stay out — exactly the set the per-agent override list should cover.
+// (merger, the fixers/resolver). The pure gates run no model, so they stay out —
+// exactly the set the per-agent override list should cover.
 const configurableKinds = computed(() => [...agents.archetypes, ...MODEL_CONFIGURABLE_SYSTEM_KINDS])
 
 // Narrowed to the selected agent tier, EXCEPT that a kind the preset being edited already

package/app/composables/useWorkspaceStream.ts

@@ -1,6 +1,10 @@
 import { ref, onScopeDispose } from 'vue'
 import type { WorkspaceEvent } from '~/types/domain'
 import { wsOriginFor } from '~/utils/apiOrigin'
+import {
+  applyWorkspaceEvent,
+  type WorkspaceEventTargets,
+} from '~/composables/workspaceStream/applyWorkspaceEvent'
 
 /**
  * Subscribes to the backend's per-workspace WebSocket event stream and keeps the
@@ -8,11 +12,11 @@ import { wsOriginFor } from '~/utils/apiOrigin'
  * once (e.g. on the board page) after the workspace is ready.
  *
  * `execution` events patch the run + its block directly; `bootstrap` events patch
- * a repo-bootstrap run + its service frame (live "bootstrapping…" progress); the
- * coarse `board` event (module materialised, run cancelled) triggers a debounced
- * full refresh. On every (re)connect we refresh once to reconcile anything missed
- * while disconnected, so the server stays the source of truth and a dropped socket
- * self-heals.
+ * a repo-bootstrap run + its service frame (live "bootstrapping…" progress); a
+ * `board` event patches the block it carries, or triggers a debounced full refresh when it
+ * carries none (a removal, a reparent, a service-frame change). On every (re)connect we refresh
+ * once to reconcile anything missed while disconnected, so the server stays the source of truth
+ * and a dropped socket self-heals. Routing lives in {@link applyWorkspaceEvent}.
  */
 export function useWorkspaceStream() {
   const workspace = useWorkspaceStore()
@@ -81,6 +85,27 @@ export function useWorkspaceStream() {
     boardDebounce = setTimeout(() => void refreshWithRetry(workspaceId), 300)
   }
 
+  // The stores this stream feeds, bound once. Routing lives in `applyWorkspaceEvent` so the
+  // targeted-vs-coarse decision on a `board` event is unit-testable without a socket.
+  const targets: WorkspaceEventTargets = {
+    upsertExecution: (instance) => execution.upsert(instance),
+    upsertBlock: (block) => board.upsert(block),
+    upsertBootstrap: (job) => agentRuns.upsertBootstrap(job),
+    upsertEnvConfigRepair: (job) => agentRuns.upsertEnvConfigRepair(job),
+    upsertEnvironmentTest: (run) => environmentTest.upsert(run),
+    patchInfraSetup: (area, status, detail) => workspace.patchInfraSetup(area, status, detail),
+    upsertNotification: (n) => notifications.upsert(n),
+    appendLlmCall: (call) => observability.appendCall(call),
+    upsertRequirements: (r) => requirements.upsert(r),
+    upsertConsensus: (s) => consensus.upsert(s),
+    upsertClarity: (r) => clarity.upsert(r),
+    upsertBrainstorm: (s) => brainstorm.upsert(s),
+    upsertKaizen: (g) => kaizen.upsert(g),
+    upsertInitiative: (i) => initiatives.upsert(i),
+    upsertDocInterview: (s) => docInterview.upsert(s),
+    refreshBoard: () => debouncedBoardRefresh(),
+  }
+
   function onMessage(raw: string) {
     let event: WorkspaceEvent
     try {
@@ -88,78 +113,7 @@ export function useWorkspaceStream() {
     } catch {
       return
     }
-    if (event.type === 'execution') {
-      // Full instance drives the step-level UI; agentRuns derives its coarse
-      // failure/retry summary from the same store, so no extra call is needed.
-      execution.upsert(event.instance)
-      if (event.block) board.upsert(event.block)
-    } else if (event.type === 'board') {
-      debouncedBoardRefresh()
-    } else if (event.type === 'bootstrap') {
-      // Patch the run's live status/subtasks and its provisional/linked frame so
-      // the "bootstrapping…" card updates in place (then flips to a ready service
-      // or a failed badge) without a full refresh.
-      agentRuns.upsertBootstrap(event.job)
-      if (event.block) board.upsert(event.block)
-    } else if (event.type === 'env-config-repair') {
-      // A provider config-repair run advanced — patch its live status/subtasks/outcome so
-      // the infrastructure-providers window's "repairing…" indicator updates in place
-      // (then flips to ok / residual issues / a failure) without a refetch. No board block.
-      agentRuns.upsertEnvConfigRepair(event.job)
-    } else if (event.type === 'envTest') {
-      // An ephemeral-environment self-test advanced a stage — patch the run so the service
-      // inspector's "Test environment creation" control shows the live stage + final
-      // outcome in place without a refetch. No board block.
-      environmentTest.upsert(event.run)
-    } else if (event.type === 'infraSetup') {
-      // The reachability watcher found a configured infrastructure area dead (or answering again) —
-      // patch that one area so the setup banner appears/clears immediately. A full refresh would
-      // pay the whole snapshot aggregate for a one-field delta, and the projection the snapshot
-      // recomputes already folds the same recorded state.
-      workspace.patchInfraSetup(event.area, event.status, event.detail)
-    } else if (event.type === 'notification') {
-      // A PR needs a merge decision, a pipeline finished, or CI gave up — patch the
-      // inbox + per-block badge in place (resolved ones drop out of the inbox).
-      notifications.upsert(event.notification)
-    } else if (event.type === 'llmCall') {
-      // A container agent just made a model call — fold the compact summary into the
-      // observability store so an open "Model activity" panel updates live (and keeps
-      // updating even when the durable driver is evicted: the proxy emits these
-      // independently of the run's poll loop).
-      observability.appendCall(event.call)
-    } else if (event.type === 'requirements') {
-      // The async incorporate + re-review cycle changed a review's status — patch the cache
-      // so an open review window / inspector reflects it live ("incorporating…" → the next
-      // cycle / converged). The summons back, when needed, arrives as a `notification`.
-      requirements.upsert(event.review)
-    } else if (event.type === 'consensus') {
-      // A consensus session advanced (a round landed, the synthesis completed, or it
-      // failed) — patch the cache so an open Consensus Session window renders the
-      // multi-model process live, round by round.
-      consensus.upsert(event.session)
-    } else if (event.type === 'clarity') {
-      // The async incorporate + re-review cycle changed a clarity review's status — patch the
-      // 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)
-    } else if (event.type === 'initiative') {
-      // An initiative changed (created, plan ingested, an item settled) — patch the cache
-      // so an open tracker window / the board card reflects the transition live.
-      initiatives.upsert(event.initiative)
-    } else if (event.type === 'docInterview') {
-      // The interactive document interview advanced (a fresh batch of questions, an answer, or
-      // convergence) — patch the cache so an open interview window reflects it live.
-      docInterview.upsert(event.session)
-    }
+    applyWorkspaceEvent(event, targets)
   }
 
   async function connect() {

package/app/composables/workspaceStream/applyWorkspaceEvent.spec.ts

@@ -0,0 +1,150 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { Block, WorkspaceEvent } from '~/types/domain'
+import {
+  applyWorkspaceEvent,
+  type WorkspaceEventTargets,
+} from '~/composables/workspaceStream/applyWorkspaceEvent'
+
+function targets(): WorkspaceEventTargets & { calls: string[] } {
+  const calls: string[] = []
+  const record =
+    <T extends unknown[]>(name: string) =>
+    (...args: T) => {
+      void args
+      calls.push(name)
+    }
+  return {
+    calls,
+    upsertExecution: record('upsertExecution'),
+    upsertBlock: record('upsertBlock'),
+    upsertBootstrap: record('upsertBootstrap'),
+    upsertEnvConfigRepair: record('upsertEnvConfigRepair'),
+    upsertEnvironmentTest: record('upsertEnvironmentTest'),
+    patchInfraSetup: record('patchInfraSetup'),
+    upsertNotification: record('upsertNotification'),
+    appendLlmCall: record('appendLlmCall'),
+    upsertRequirements: record('upsertRequirements'),
+    upsertConsensus: record('upsertConsensus'),
+    upsertClarity: record('upsertClarity'),
+    upsertBrainstorm: record('upsertBrainstorm'),
+    upsertKaizen: record('upsertKaizen'),
+    upsertInitiative: record('upsertInitiative'),
+    upsertDocInterview: record('upsertDocInterview'),
+    refreshBoard: record('refreshBoard'),
+  }
+}
+
+const task = {
+  id: 'blk_task',
+  title: 'Ship it',
+  type: 'service',
+  description: '',
+  position: { x: 0, y: 0 },
+  status: 'planned',
+  progress: 0,
+  dependsOn: [],
+  executionId: null,
+  level: 'task',
+  parentId: 'blk_frame',
+} as unknown as Block
+
+describe('applyWorkspaceEvent: the board branch', () => {
+  it('patches the carried block instead of refreshing the whole board', () => {
+    const to = targets()
+    const event: WorkspaceEvent = { type: 'board', reason: 'block-added', block: task, at: 1 }
+
+    applyWorkspaceEvent(event, to)
+
+    // The whole point of the change: a spawned task costs one upsert, not a snapshot fetch that
+    // REPLACES every store's list.
+    expect(to.calls).toEqual(['upsertBlock'])
+  })
+
+  it('falls back to a full refresh when the change carries no block', () => {
+    const to = targets()
+    // Everything the publisher withholds a payload for lands here: a removal that cascades, a
+    // reparent that moves a subtree, and a service FRAME whose geometry is per-board. None has a
+    // single block that states the new shape, so the client must re-read its own projection.
+    const event: WorkspaceEvent = { type: 'board', reason: 'block-removed', at: 1 }
+
+    applyWorkspaceEvent(event, to)
+
+    expect(to.calls).toEqual(['refreshBoard'])
+  })
+
+  it('falls back to a full refresh when the payload is explicitly null', () => {
+    const to = targets()
+    // The frame shape as the publishers actually emit it: `deliverableBoardBlock` answers `null`
+    // rather than omitting the key, and an absent payload and a null one must route identically.
+    const event: WorkspaceEvent = { type: 'board', reason: 'block-archived', block: null, at: 1 }
+
+    applyWorkspaceEvent(event, to)
+
+    expect(to.calls).toEqual(['refreshBoard'])
+  })
+
+  it('routes a board event through the SAME upsert an execution event uses', () => {
+    // Coherence: the monotonic live-upsert stamp that stops a stale refresh clobbering newer
+    // state lives in `board.upsert`. A targeted board event that patched `blocks` any other way
+    // would silently escape that guard.
+    const upsertBlock = vi.fn()
+    const to = { ...targets(), upsertBlock }
+
+    applyWorkspaceEvent({ type: 'board', reason: 'block-updated', block: task, at: 1 }, to)
+    applyWorkspaceEvent(
+      {
+        type: 'execution',
+        instance: { id: 'exec_1', blockId: task.id } as never,
+        block: task,
+        at: 2,
+      },
+      to,
+    )
+
+    expect(upsertBlock).toHaveBeenCalledTimes(2)
+    expect(upsertBlock).toHaveBeenNthCalledWith(1, task)
+    expect(upsertBlock).toHaveBeenNthCalledWith(2, task)
+  })
+})
+
+describe('applyWorkspaceEvent: the other branches', () => {
+  it('keeps every non-board event on its own targeted store call', () => {
+    // Each type below is delivered as a patch rather than a board refresh. This table cannot see
+    // a NEW event type (an absent member is just absent from a hand-written list). That job
+    // belongs to the `never` guard on the switch's `default`, which fails the BUILD instead.
+    const cases: [WorkspaceEvent, string][] = [
+      [{ type: 'bootstrap', job: {} as never, block: null, at: 1 }, 'upsertBootstrap'],
+      [{ type: 'env-config-repair', job: {} as never, at: 1 }, 'upsertEnvConfigRepair'],
+      [{ type: 'envTest', run: {} as never, at: 1 }, 'upsertEnvironmentTest'],
+      [
+        { type: 'infraSetup', area: 'runnerPool' as never, status: 'ok' as never, at: 1 },
+        'patchInfraSetup',
+      ],
+      [{ type: 'notification', notification: {} as never, at: 1 }, 'upsertNotification'],
+      [{ type: 'llmCall', call: {} as never, at: 1 }, 'appendLlmCall'],
+      [{ type: 'requirements', review: {} as never, at: 1 }, 'upsertRequirements'],
+      [{ type: 'consensus', session: {} as never, at: 1 }, 'upsertConsensus'],
+      [{ type: 'clarity', review: {} as never, at: 1 }, 'upsertClarity'],
+      [{ type: 'brainstorm', session: {} as never, at: 1 }, 'upsertBrainstorm'],
+      [{ type: 'kaizen', grading: {} as never, at: 1 }, 'upsertKaizen'],
+      [{ type: 'initiative', initiative: {} as never, at: 1 }, 'upsertInitiative'],
+      [{ type: 'docInterview', session: {} as never, at: 1 }, 'upsertDocInterview'],
+    ]
+
+    for (const [event, expected] of cases) {
+      const to = targets()
+      applyWorkspaceEvent(event, to)
+      expect(to.calls, `${event.type} should route to ${expected}`).toEqual([expected])
+    }
+  })
+
+  it('drops an event type it does not know rather than tearing down the session', () => {
+    // A backend one release ahead pushes types this build has never heard of. The socket carries
+    // every other event for the whole workspace, so the unknown one is dropped, not thrown on.
+    const to = targets()
+
+    applyWorkspaceEvent({ type: 'a-later-release', at: 1 } as unknown as WorkspaceEvent, to)
+
+    expect(to.calls).toEqual([])
+  })
+})

package/app/composables/workspaceStream/applyWorkspaceEvent.ts

@@ -0,0 +1,173 @@
+import type {
+  Block,
+  BootstrapJob,
+  EnvConfigRepairJob,
+  EnvironmentTestRun,
+  ExecutionInstance,
+  InfraSetupArea,
+  InfraSetupStatus,
+  Initiative,
+  KaizenGrading,
+  LlmCallActivity,
+  Notification,
+  WorkspaceEvent,
+} from '~/types/domain'
+import type { BrainstormSession } from '~/types/brainstorm'
+import type { ClarityReview } from '~/types/clarity'
+import type { ConsensusSession } from '~/types/consensus'
+import type { DocInterviewSession } from '~/types/doc-interview'
+import type { RequirementReview } from '~/types/requirements'
+
+/**
+ * Everything {@link applyWorkspaceEvent} needs to route one pushed event into the stores, as bound
+ * callbacks rather than the stores themselves: it makes the routing (above all the `board` branch's
+ * targeted-vs-coarse decision) unit-testable without a Pinia instance or a live socket.
+ *
+ * Each callback names the DOMAIN type it takes, not the event field it happens to be fed from
+ * today. `upsertBlock` is the reason that matters: three branches (`execution`, `board`,
+ * `bootstrap`) share it, so typing it off any one of their payloads would silently retype the
+ * other two the next time that event's shape moved.
+ */
+export interface WorkspaceEventTargets {
+  upsertExecution: (instance: ExecutionInstance) => void
+  upsertBlock: (block: Block) => void
+  upsertBootstrap: (job: BootstrapJob) => void
+  upsertEnvConfigRepair: (job: EnvConfigRepairJob) => void
+  upsertEnvironmentTest: (run: EnvironmentTestRun) => void
+  patchInfraSetup: (area: InfraSetupArea, status: InfraSetupStatus, detail?: string) => void
+  upsertNotification: (n: Notification) => void
+  appendLlmCall: (call: LlmCallActivity) => void
+  upsertRequirements: (r: RequirementReview) => void
+  upsertConsensus: (s: ConsensusSession) => void
+  upsertClarity: (r: ClarityReview) => void
+  upsertBrainstorm: (s: BrainstormSession) => void
+  upsertKaizen: (g: KaizenGrading) => void
+  upsertInitiative: (i: Initiative) => void
+  upsertDocInterview: (s: DocInterviewSession) => void
+  /** Debounced full `workspace.refresh()`: the fallback for a change no payload can state. */
+  refreshBoard: () => void
+}
+
+/**
+ * Route one pushed workspace event into the stores.
+ *
+ * The `board` branch is the one with a decision in it. A `board` event used to mean "re-fetch the
+ * whole snapshot", which on an active board is a REPLACE-style rehydrate of ~20 stores every ~300ms
+ * debounce window, for changes as small as one spawned task. The backend now carries the changed
+ * block whenever the change is fully described by it (see the `board` case in
+ * `@cat-factory/contracts`' `WorkspaceEvent`), so those patch in place exactly like an `execution`
+ * event's block does, through the same `upsert` whose monotonic stamp keeps a later stale refresh
+ * from clobbering them.
+ *
+ * A `board` event with NO block keeps the old behaviour, and that is not a fallback to tidy away:
+ * a removal, a reparent, a blueprint reconcile and every service-frame change genuinely need the
+ * refresh, because their new shape is not one block's contents.
+ */
+export function applyWorkspaceEvent(event: WorkspaceEvent, to: WorkspaceEventTargets): void {
+  switch (event.type) {
+    case 'execution':
+      // Full instance drives the step-level UI; agentRuns derives its coarse
+      // failure/retry summary from the same store, so no extra call is needed.
+      to.upsertExecution(event.instance)
+      if (event.block) to.upsertBlock(event.block)
+      return
+    case 'board':
+      // Targeted when the change fits in one block, coarse otherwise. Both shapes reach every
+      // board that mounts the affected service; only the cost differs.
+      if (event.block) to.upsertBlock(event.block)
+      else to.refreshBoard()
+      return
+    case 'bootstrap':
+      // Patch the run's live status/subtasks and its provisional/linked frame so
+      // the "bootstrapping…" card updates in place (then flips to a ready service
+      // or a failed badge) without a full refresh.
+      to.upsertBootstrap(event.job)
+      if (event.block) to.upsertBlock(event.block)
+      return
+    case 'env-config-repair':
+      // A provider config-repair run advanced: patch its live status/subtasks/outcome so the
+      // infrastructure-providers window's "repairing…" indicator updates in place (then flips to
+      // ok / residual issues / a failure) without a refetch. No board block.
+      to.upsertEnvConfigRepair(event.job)
+      return
+    case 'envTest':
+      // An ephemeral-environment self-test advanced a stage: patch the run so the service
+      // inspector's "Test environment creation" control shows the live stage + final outcome in
+      // place without a refetch. No board block.
+      to.upsertEnvironmentTest(event.run)
+      return
+    case 'infraSetup':
+      // The reachability watcher found a configured infrastructure area dead (or answering again):
+      // patch that one area so the setup banner appears/clears immediately. A full refresh would
+      // pay the whole snapshot aggregate for a one-field delta, and the projection the snapshot
+      // recomputes already folds the same recorded state.
+      to.patchInfraSetup(event.area, event.status, event.detail)
+      return
+    case 'notification':
+      // A PR needs a merge decision, a pipeline finished, or CI gave up: patch the
+      // inbox + per-block badge in place (resolved ones drop out of the inbox).
+      to.upsertNotification(event.notification)
+      return
+    case 'llmCall':
+      // A container agent just made a model call: fold the compact summary into the observability
+      // store so an open "Model activity" panel updates live (and keeps updating even when the
+      // durable driver is evicted, since the proxy emits these independently of the poll loop).
+      to.appendLlmCall(event.call)
+      return
+    case 'requirements':
+      // The async incorporate + re-review cycle changed a review's status: patch the cache so an
+      // open review window / inspector reflects it live ("incorporating…" → the next cycle /
+      // converged). The summons back, when needed, arrives as a `notification`.
+      to.upsertRequirements(event.review)
+      return
+    case 'consensus':
+      // A consensus session advanced (a round landed, the synthesis completed, or it failed):
+      // patch the cache so an open Consensus Session window renders the multi-model process live,
+      // round by round.
+      to.upsertConsensus(event.session)
+      return
+    case 'clarity':
+      // The clarity mirror of `requirements`.
+      to.upsertClarity(event.review)
+      return
+    case '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.
+      to.upsertBrainstorm(event.session)
+      return
+    case '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.
+      to.upsertKaizen(event.grading)
+      return
+    case 'initiative':
+      // An initiative changed (created, plan ingested, an item settled): patch the cache so an
+      // open tracker window / the board card reflects the transition live.
+      to.upsertInitiative(event.initiative)
+      return
+    case 'docInterview':
+      // The interactive document interview advanced (a fresh batch of questions, an answer, or
+      // convergence): patch the cache so an open interview window reflects it live.
+      to.upsertDocInterview(event.session)
+      return
+    default:
+      return dropUnknownEvent(event)
+  }
+}
+
+/**
+ * The exhaustiveness guard for the routing above.
+ *
+ * The COMPILE-TIME half is the point: `never` fails the build the moment `WorkspaceEvent` gains a
+ * member with no case, so a new pushed event cannot ship as a branch that silently does nothing.
+ * The spec's per-type table cannot do that job: a member absent from a hand-written list is just
+ * absent, and the suite stays green.
+ *
+ * At RUNTIME this deliberately drops the event. A backend one release ahead of the SPA legitimately
+ * pushes types this build has never heard of, and the connection carries every other event for the
+ * whole workspace: throwing would trade one unknown payload for the entire live session.
+ */
+function dropUnknownEvent(event: never): void {
+  void event
+}

package/app/docs/consumer-extensions.md

@@ -4,19 +4,19 @@ A deployment that consumes this layer (`extends: ['@cat-factory/app']`) can cont
 its own **components** (result windows, navigation entries, inspector panels, agent-kind
 palette data) **without forking the layer**. This is the frontend counterpart of the
 backend's public registries (`registerAgentKind`, `registerGate`; see
-[`backend/docs/custom-agents.md`](../../../backend/docs/custom-agents.md)). The governing
+[`backend/docs/custom-agents.md`](https://github.com/kibertoad/cat-factory/blob/main/backend/docs/custom-agents.md)). The governing
 principle is the same: **zero host edits for a consumer extension**.
 
 A worked, end-to-end example ships in the template deployment:
-[`deploy/frontend/app/`](../../../deploy/frontend) (the `acme:security` module): the
+[`deploy/frontend/app/`](https://github.com/kibertoad/cat-factory/tree/main/deploy/frontend/app) (the `acme:security` module): the
 frontend analogue of the backend
-[`@cat-factory/example-custom-agent`](../../../backend/internal/example-custom-agent)
+[`@cat-factory/example-custom-agent`](https://github.com/kibertoad/cat-factory/tree/main/backend/internal/example-custom-agent)
 package. Read this guide alongside it.
 
 > This is the **landed** surface (modular-vue adoption slices 1–5). The larger consumer
 > extension programme (custom task types, generic interactive phases, overlays, consumer
 > notification kinds, stream events, and the hardened public export surface) is tracked in
-> [`docs/initiatives/frontend-extension-mechanism.md`](../../../docs/initiatives/frontend-extension-mechanism.md).
+> [`docs/initiatives/frontend-extension-mechanism.md`](https://github.com/kibertoad/cat-factory/blob/main/docs/initiatives/frontend-extension-mechanism.md).
 
 ## The one seam: `registerAppModule`
 
@@ -219,8 +219,11 @@ suite can address a row and the caption inside it.
 Together, `fields` + `defaultFragmentIds` + `defaultPipelineId` are what turns a task type from a
 badge into a **reusable operation**: a canned unit of work an org runs repeatedly with per-case
 input, whose collected values reach every agent's prompt. See
-[`backend/docs/reusable-operations.md`](../../../../backend/docs/reusable-operations.md) and the
-`org:introduce-api` worked example in `backend/internal/example-custom-agent`.
+[`backend/docs/reusable-operations.md`](https://github.com/kibertoad/cat-factory/blob/main/backend/docs/reusable-operations.md) and the
+[`org:introduce-api` worked example](https://github.com/kibertoad/cat-factory/tree/main/backend/internal/example-custom-agent).
+Both links are absolute on purpose: this page ships inside the `@cat-factory/app` tarball, so a
+relative path out of it resolves only from a checkout, which is the one place its reader is not.
+(`scripts/check-shipped-doc-links.mjs` fails CI on a shipped doc that grows one.)
 
 The **same type can be delivered from the backend** instead of code-shipped: register it on the
 deployment's app-owned `TaskTypeRegistry` and it arrives in the workspace snapshot's

package/app/stores/agents.ts

@@ -69,9 +69,11 @@ export const useAgentsStore = defineStore('agents', () => {
    * mapped to display metadata, de-duplicated, and never shadowing a built-in or
    * system kind. The old `registerCustomKinds` only guarded `AGENT_BY_KIND`; this
    * intentionally ALSO drops any custom kind colliding with a `SYSTEM_AGENT_META`
-   * kind (`ci` / `merger` / `blueprints` / gates …), so a snapshot can't override an
-   * engine kind's palette entry either — matching `agentKindMeta`'s precedence
-   * (built-in → system → custom), where a colliding custom kind would never win anyway.
+   * kind (`ci` / `merger` / gates …), so a snapshot can't override an engine kind's
+   * palette entry either — matching `agentKindMeta`'s precedence (built-in → system
+   * → custom), where a colliding custom kind would never win anyway. Note the cost of
+   * that guard: a SYSTEM_AGENT_META entry silently removes a registered kind from the
+   * palette, so the map must stay limited to kinds the engine inserts itself.
    */
   const customArchetypes = computed<AgentArchetype[]>(() => {
     const seen = new Set<string>()

package/app/utils/catalog.spec.ts

@@ -4,6 +4,8 @@ import {
   AGENT_ARCHETYPES,
   AGENT_BY_KIND,
   BLOCK_TYPE_META,
+  COMPANION_FOR_PRODUCER,
+  MODEL_CONFIGURABLE_SYSTEM_KINDS,
   STATUS_META,
   SYSTEM_AGENT_META,
   agentKindMeta,
@@ -20,9 +22,12 @@ const AGENT_KINDS: AgentKind[] = [
   'pr-reviewer',
   'spike',
   'task-estimator',
+  'spec-writer',
+  'blueprints',
   'architect',
   'researcher',
   'coder',
+  'deployer',
   'tester-api',
   'tester-ui',
   'reviewer',
@@ -80,6 +85,38 @@ describe('catalog', () => {
     expect(basic).toEqual(expect.arrayContaining(['architect', 'coder', 'tester-api']))
   })
 
+  it('never shadows a companion producer as a system kind', () => {
+    // A companion is never placed directly: the builder renders it as a toggle on its producer
+    // step, so a producer that cannot be placed takes its companion out of the builder with it.
+    // A producer reaches the palette either statically (AGENT_ARCHETYPES) or from the backend
+    // registry — and an entry in SYSTEM_AGENT_META DROPS the registry's copy (see the agents
+    // store's `customArchetypes`), which is how `spec-writer` and its `spec-companion` both
+    // became unreachable. The shadow is the half this file owns, so it is the half asserted.
+    for (const producer of Object.keys(COMPANION_FOR_PRODUCER)) {
+      expect(
+        producer in SYSTEM_AGENT_META,
+        `${producer} has a companion but is shadowed as a system kind, so neither can be placed`,
+      ).toBe(false)
+    }
+  })
+
+  it('resolves every kind the Model Defaults panel lists beside the palette', () => {
+    // The list is spelled as kind strings indexed into SYSTEM_AGENT_META through a non-null
+    // assertion, so a kind that MOVES to the palette (or is renamed) leaves an `undefined` in
+    // the array rather than a type error, and the panel renders a blank row it cannot pin a
+    // model on. Assert the relation the assertion claims.
+    for (const entry of MODEL_CONFIGURABLE_SYSTEM_KINDS) {
+      expect(entry, 'MODEL_CONFIGURABLE_SYSTEM_KINDS names a kind with no metadata').toBeDefined()
+      expect(entry.kind).toEqual(expect.any(String))
+    }
+    // And nothing is offered twice: a palette archetype is already listed by the panel, so a
+    // kind appearing in both would render a duplicate row.
+    const palette = new Set(AGENT_ARCHETYPES.map((a) => a.kind))
+    for (const entry of MODEL_CONFIGURABLE_SYSTEM_KINDS) {
+      expect(palette.has(entry.kind), `${entry.kind} is listed twice in Model Defaults`).toBe(false)
+    }
+  })
+
   it('resolves usable metadata for every kind via agentKindMeta', () => {
     // Palette archetypes resolve to their own entry.
     for (const a of AGENT_ARCHETYPES) {
@@ -88,8 +125,6 @@ describe('catalog', () => {
     // Engine system kinds (present in seeded pipelines but not the palette) resolve
     // to their system metadata rather than blowing up an undefined access.
     for (const kind of [
-      'spec-writer',
-      'blueprints',
       'conflicts',
       'conflict-resolver',
       'ci',

package/app/utils/catalog.ts

@@ -136,6 +136,21 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
       'A structured dialogue that explores and finalizes a technical approach from the refined requirements — proposing options with explicit trade-offs and letting you converge, before the architect.',
     resultView: 'brainstorm',
   },
+  {
+    // Authors the service's in-repo specification from the clarified requirements, so it sits
+    // beside the design kinds and ahead of the architect that reads what it wrote. Registered on
+    // the backend so it also arrives via the workspace manifest, and modelled statically here for
+    // the same reason `pr-reviewer` is: a `pl_bugfix` / `pl_spec` timeline must name the step
+    // before the manifest hydrates. Mirrors the backend `presentation` in `spec-blueprints.ts`.
+    kind: 'spec-writer',
+    tier: 'intermediate',
+    label: 'Spec Writer',
+    icon: 'i-lucide-clipboard-list',
+    color: '#c084fc',
+    category: 'design',
+    description:
+      "Aggregates every task's clarified requirements into the service's in-repo specification (spec.json) with full acceptance-scenario coverage, derived into Gherkin.",
+  },
   {
     kind: 'architect',
     tier: 'basic',
@@ -145,6 +160,18 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     category: 'design',
     description: 'Designs the shape of the solution and breaks down the work.',
   },
+  {
+    // Refreshes the service → modules map the board projects. Statically modelled beside its
+    // backend `presentation` for the same reason the Spec Writer is: `pl_blueprint` timelines
+    // render before the manifest hydrates.
+    kind: 'blueprints',
+    tier: 'intermediate',
+    label: 'Blueprinter',
+    icon: 'i-lucide-map',
+    color: '#22d3ee',
+    category: 'design',
+    description: 'Maps the repository into the service → modules blueprint.',
+  },
   {
     kind: 'researcher',
     tier: 'intermediate',
@@ -181,6 +208,21 @@ export const AGENT_ARCHETYPES: AgentArchetype[] = [
     category: 'build',
     description: 'Builds WireMock mocks for external services and wires them into local/CI runs.',
   },
+  {
+    // Provisions the ephemeral environment the tester / human-test / playwright steps read, which
+    // is why it leads the testing group. A palette block for the same reason `disposer` is one:
+    // `assertDeployerBeforeConsumer` REFUSES a run whose chain reaches an env consumer with no
+    // Deployer in front of it on a deployable service, and a hand-built pipeline that hits that
+    // refusal has no reseed to fall back on.
+    kind: 'deployer',
+    tier: 'intermediate',
+    label: 'Deployer',
+    icon: 'i-lucide-cloud-upload',
+    color: '#34d399',
+    category: 'test',
+    description:
+      'Provisions the ephemeral environment the tester and human-test gate run against (kubernetes / custom services); a no-op for docker-compose / infraless. Place it before the first step that needs the environment.',
+  },
   {
     kind: 'tester-api',
     tier: 'basic',
@@ -491,29 +533,22 @@ export function isTesterKind(kind: string): boolean {
 
 /**
  * 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}
+ * steps (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}.
+ *
+ * An entry here also SHADOWS the backend's own catalog: the agents store drops any
+ * registered kind whose id appears in this map (see `customArchetypes`), so listing a
+ * kind that declares `presentation` silently overrides the deployment's decision to
+ * offer it. That is how `spec-writer` and `blueprints` stayed out of the palette while
+ * both collapse docs promised them as opt-in builder steps, and it took
+ * `spec-companion` with them: a companion renders as a toggle on its producer, so a
+ * shadowed producer removes both. Add a kind here only when the ENGINE decides the
+ * step exists — a gate it inserts, a helper it escalates to — and never when the
+ * backend registers it as a palette block.
  */
 export const SYSTEM_AGENT_META: Record<string, AgentArchetype> = {
-  'spec-writer': {
-    kind: 'spec-writer',
-    tier: 'intermediate',
-    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',
-    tier: 'intermediate',
-    label: 'Blueprinter',
-    icon: 'i-lucide-map',
-    color: '#22d3ee',
-    description: 'Maps the repository into the service → modules blueprint.',
-  },
   // The read-only Challenge Investigator: dispatched off a parked `pr-reviewer` step when a human
   // challenges a finding, it re-examines that ONE finding against the full source and upholds
   // (strengthening) or retracts it. Never a palette block; modelled here purely so it is a
@@ -529,19 +564,6 @@ export const SYSTEM_AGENT_META: Record<string, AgentArchetype> = {
       'Re-examines a single challenged PR-review finding against the full source, then upholds ' +
       '(strengthening it) or retracts it with a justification. Configurable separately from the reviewer.',
   },
-  // The single environment provisioner: an operational (non-LLM) step that stands up the ephemeral
-  // environment the tester / human-test gate run against for a kubernetes/custom service, and is a
-  // fast no-op for docker-compose / infraless. Seeded before the first tester/human-test step in the
-  // built-in pipelines, so it needs display metadata (else it renders as a generic gray "Agent").
-  deployer: {
-    kind: 'deployer',
-    tier: 'intermediate',
-    label: 'Deployer',
-    icon: 'i-lucide-cloud-upload',
-    color: '#34d399',
-    description:
-      'Provisions the ephemeral environment the tester and human-test gate run against (kubernetes / custom services); a no-op for docker-compose / infraless.',
-  },
   // The Initiative Planning pipeline's steps. Only runnable on an initiative
   // block (pl_initiative — enforced by the engine), so they are display-metadata
   // system kinds, never palette archetypes. The analyst runs FIRST, ahead of the
@@ -766,8 +788,6 @@ export const OBSERVABILITY_GATE_ARCHETYPE: AgentArchetype =
  */
 export const MODEL_CONFIGURABLE_SYSTEM_KINDS: AgentArchetype[] = [
   ...[
-    'spec-writer',
-    'blueprints',
     'initiative-planner',
     'conflict-resolver',
     'ci-fixer',
@@ -798,7 +818,7 @@ const FALLBACK_AGENT_META: Omit<AgentArchetype, 'kind'> = {
  * {@link customAgentKindMeta} by the agents store), 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
+ * `ci`/`merger` in a seeded pipeline) can never blow up a component
  * with an undefined access. Reading `customAgentKindMeta` reactively means a
  * component computed re-runs when the custom catalog changes.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.234.1",
+  "version": "0.235.0",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",
@@ -40,7 +40,7 @@
     "valibot": "^1.4.2",
     "vue": "3.5.40",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.253.0"
+    "@cat-factory/contracts": "0.255.0"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.2",