@cat-factory/app 0.283.0 → 0.284.0

package/app/stores/execution/wholeRunReads.ts

@@ -0,0 +1,139 @@
+import { ref } from 'vue'
+import type { ExecutionInstance } from '~/types/domain'
+
+/** What the whole-run reader needs from the store it belongs to, as bound callbacks. */
+export interface WholeRunReadDeps {
+  /** The cached run, if the store holds one under this id. Must be a REACTIVE read. */
+  cached: (id: string) => ExecutionInstance | undefined
+  /** The board the reads are scoped to, or null before one is loaded. */
+  workspaceId: () => string | null
+  /** The by-id point-read (`GET /workspaces/:ws/executions/:executionId`). */
+  fetch: (workspaceId: string, executionId: string) => Promise<ExecutionInstance>
+  /** Where a fetched run lands: the same monotonic reconcile a live event goes through. */
+  apply: (instance: ExecutionInstance) => void
+}
+
+/**
+ * The WHOLE-RUN read behind the step-detail overlays, extracted from the execution store as a
+ * cohesive collaborator over bound callbacks (the shape `createExecutionReconcile` and
+ * `createExecutionCommands` use).
+ *
+ * The board snapshot serves a LEAN PROJECTION of every run (`projectExecutionForBoard`): each
+ * step's captured prose is WITHHELD, not absent, and the instance is stamped `projected`. A
+ * surface that renders that prose asks here for the run behind it, and this owns the three facts
+ * such a surface cannot work out for itself: whether it has to ask, whether an answer is still
+ * coming, and whether the last one failed.
+ */
+export function createWholeRunReads(deps: WholeRunReadDeps) {
+  /** Run ids whose whole-run fetch is in flight, so a reader can say "loading" rather than "empty". */
+  const pending = ref<Set<string>>(new Set())
+  /**
+   * Last whole-run fetch error per run id. A withheld field and a failed fetch are different facts
+   * and a reader that cannot tell them apart renders the outage as a step that said nothing, so the
+   * failure is recorded rather than swallowed.
+   *
+   * A recorded failure is only ever READ through {@link fullError}, which withholds it once the run
+   * is held whole: the prose can arrive by a route this fetch knows nothing about (a live
+   * `execution` event delivers every run complete), and a banner saying the run could not be loaded
+   * standing over prose that loaded is worse than no banner at all.
+   */
+  const errors = ref<Record<string, string | null>>({})
+  /** In-flight fetches, so two overlays opening the same run make ONE request. */
+  const inFlight = new Map<string, Promise<void>>()
+  /**
+   * Which BOARD the in-flight reads belong to. A fetch outlives the board that started it (a
+   * switch mid-request is one click), and its result would otherwise be applied to the switched-to
+   * board's cache as a run that board does not have. Bumped by {@link resetFullReads}; a request
+   * whose generation is stale drops its answer.
+   */
+  let generation = 0
+
+  function isFullPending(id: string | null | undefined): boolean {
+    return !!id && pending.value.has(id)
+  }
+
+  function fullError(id: string | null | undefined): string | null {
+    if (!id || !needsFull(id)) return null
+    return errors.value[id] ?? null
+  }
+
+  /** Whether the cache is missing this run's withheld prose, so a reader of it has to ask. */
+  function needsFull(id: string): boolean {
+    const held = deps.cached(id)
+    return !held || held.projected === true
+  }
+
+  /**
+   * What a prose reader WATCHES to know it must ask: null while the cache holds the run whole, and
+   * otherwise a key that changes whenever there is a fresh reason to ask.
+   *
+   * The reason to key on the revision rather than on the id is that a run does not stop being a
+   * projection once an overlay is open. Any full refresh lands a lean projection over the run, and
+   * at a NEWER revision the reconcile cannot carry the cached prose forward (it may no longer be
+   * that run's prose), so an open overlay's prose is withheld again under it and only a re-fetch
+   * restores it. Keyed on the id alone, the watch that fires on open never fires again and the
+   * reader blanks with nothing left to refill it.
+   */
+  function fullFetchKey(id: string | null | undefined): string | null {
+    if (!id || !needsFull(id)) return null
+    return `${id}:${deps.cached(id)?.rev ?? 0}`
+  }
+
+  /**
+   * Make sure the cached run carries what the projection withholds. A no-op for a run the cache
+   * already holds whole (one delivered by a live `execution` event, or already fetched), so
+   * opening a window on an active run costs nothing.
+   *
+   * Single-flight per run id: a board click can open the window and its shell in the same tick,
+   * and two overlays reading one run must not fire two point-reads of the heaviest row in it.
+   */
+  async function ensureFull(id: string | null | undefined): Promise<void> {
+    if (!id || !needsFull(id)) return
+    const running = inFlight.get(id)
+    if (running) return running
+    const workspaceId = deps.workspaceId()
+    if (!workspaceId) return
+    const asked = generation
+    pending.value = new Set(pending.value).add(id)
+    // Clear any recorded failure up front: this attempt is what the reader is waiting on now, and
+    // leaving the previous one in place would render a retry as a failure that already resolved.
+    if (errors.value[id]) errors.value = { ...errors.value, [id]: null }
+    const request = deps
+      .fetch(workspaceId, id)
+      .then((full) => {
+        if (asked !== generation) return
+        deps.apply(full)
+      })
+      .catch((error: unknown) => {
+        if (asked !== generation) return
+        errors.value = {
+          ...errors.value,
+          [id]: error instanceof Error ? error.message : 'Failed to load the run',
+        }
+      })
+      .finally(() => {
+        inFlight.delete(id)
+        if (asked !== generation) return
+        const next = new Set(pending.value)
+        next.delete(id)
+        pending.value = next
+      })
+    inFlight.set(id, request)
+    return request
+  }
+
+  /**
+   * Drop the read bookkeeping, and disown whatever is still in flight. Called on a board SWITCH,
+   * beside the other per-board caches: the cached runs themselves are part of the snapshot and
+   * `hydrate` replaces them, but the pending/failed marks and the requests behind them are keyed
+   * by a run id the switched-to board does not have.
+   */
+  function resetFullReads() {
+    generation += 1
+    inFlight.clear()
+    pending.value = new Set()
+    errors.value = {}
+  }
+
+  return { ensureFull, fullFetchKey, fullError, isFullPending, resetFullReads }
+}

package/app/stores/execution.spec.ts

@@ -1,5 +1,7 @@
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { computed } from 'vue'
 import { useExecutionStore } from '~/stores/execution'
+import { useWorkspaceStore } from '~/stores/workspace'
 import type { ExecutionInstance } from '~/types/domain'
 
 /**
@@ -323,3 +325,297 @@ describe('execution store per-block index', () => {
     expect(store.getByBlock('b1')?.status).toBe('done')
   })
 })
+
+/**
+ * The board snapshot serves a LEAN PROJECTION of every run: each step's captured prose is
+ * withheld and the instance says so (`projected`). These pin the reconcile rule that makes a
+ * refresh safe to land on top of a run the cache already holds whole.
+ */
+describe('execution store lean-projection reconcile', () => {
+  let store: ReturnType<typeof useExecutionStore>
+  beforeEach(() => {
+    store = useExecutionStore()
+  })
+
+  /** A run whose single step carries prose. */
+  function whole(rev: number, output = 'the full prose'): ExecutionInstance {
+    return {
+      id: 'e1',
+      blockId: 'b1',
+      status: 'running',
+      rev,
+      outputHistory: [{ stepIndex: 0, output: 'superseded' }],
+      steps: [{ agentKind: 'coder', state: 'done', output }],
+    } as unknown as ExecutionInstance
+  }
+
+  /** The same run as the snapshot serves it. */
+  function projected(rev: number): ExecutionInstance {
+    return {
+      id: 'e1',
+      blockId: 'b1',
+      status: 'running',
+      rev,
+      projected: true,
+      steps: [{ agentKind: 'coder', state: 'done', hasOutput: true }],
+    } as unknown as ExecutionInstance
+  }
+
+  it('carries the withheld prose forward at an equal revision, and stops calling it a projection', () => {
+    // The real sequence: a board load, then the live event that carries the whole run, then the
+    // next refresh landing the projection again at the revision the event already delivered.
+    store.hydrate([projected(4)], 'ws1')
+    store.upsert(whole(4))
+    store.hydrate([projected(4)], 'ws1')
+    const held = store.getInstance('e1')!
+    expect(held.steps[0]!.output).toBe('the full prose')
+    expect(held.outputHistory).toHaveLength(1)
+    expect(held.projected).toBe(false)
+  })
+
+  it('does not paste stale prose under a NEWER revision of the run', () => {
+    store.hydrate([projected(4)], 'ws1')
+    store.upsert(whole(4))
+    store.hydrate([projected(5)], 'ws1')
+    const held = store.getInstance('e1')!
+    expect(held.steps[0]!.output).toBeUndefined()
+    expect(held.outputHistory).toBeUndefined()
+    // Still marked, so the overlay knows to fetch the whole run rather than read an absence.
+    expect(held.projected).toBe(true)
+  })
+
+  it('keeps the projection marked when the cache held only a projection too', () => {
+    store.hydrate([projected(4)], 'ws1')
+    store.hydrate([projected(4)], 'ws1')
+    expect(store.getInstance('e1')!.projected).toBe(true)
+  })
+
+  it('applies the same carry-forward to a projection arriving through upsert', () => {
+    store.hydrate([whole(4)], 'ws1')
+    store.upsert(projected(4))
+    expect(store.getInstance('e1')!.steps[0]!.output).toBe('the full prose')
+  })
+
+  it('leaves a whole run delivered by an event alone', () => {
+    store.hydrate([projected(4)], 'ws1')
+    store.upsert(whole(5, 'fresh prose'))
+    const held = store.getInstance('e1')!
+    expect(held.steps[0]!.output).toBe('fresh prose')
+    expect(held.projected).toBeUndefined()
+  })
+})
+
+/**
+ * `instances` is a SHALLOW ref, so every write site has to announce itself. A regression here is
+ * silent in the product (a card just stops updating), which is why the three write shapes are
+ * pinned through a derived value rather than by reading the array back.
+ */
+describe('execution store shallow-ref write sites', () => {
+  let store: ReturnType<typeof useExecutionStore>
+  beforeEach(() => {
+    store = useExecutionStore()
+  })
+
+  function stepRun(id: string, rev: number, output?: string): ExecutionInstance {
+    return {
+      id,
+      blockId: `blk_${id}`,
+      status: 'running',
+      rev,
+      steps: [{ agentKind: 'coder', state: 'done', output }],
+    } as unknown as ExecutionInstance
+  }
+
+  it('a replace, an index assignment, a push and an echo each invalidate a derived read', async () => {
+    const seen = computed(() => store.instances.map((e) => `${e.id}:${e.steps[0]?.output ?? ''}`))
+
+    store.hydrate([stepRun('e1', 1, 'first')], 'ws1')
+    expect(seen.value).toEqual(['e1:first'])
+
+    // push
+    store.upsert(stepRun('e2', 1, 'other'))
+    expect(seen.value).toEqual(['e1:first', 'e2:other'])
+
+    // index assignment
+    store.upsert(stepRun('e1', 2, 'second'))
+    expect(seen.value).toEqual(['e1:second', 'e2:other'])
+
+    // in-place patch through the one echo seam
+    await store.echoAfter(
+      'e1',
+      () => Promise.resolve('echoed'),
+      (state, instance) => {
+        instance.steps[0]!.output = state
+      },
+    )
+    expect(seen.value).toEqual(['e1:echoed', 'e2:other'])
+  })
+})
+
+/**
+ * The chain the UI actually reads through, which is NOT `store.instances`: every window resolves
+ * `computed(() => getInstance(id))`, then that run's step, then one field on it. Each link is
+ * identity-stable, and Vue stops propagating a recomputed value that is `===` the previous one, so
+ * a write that patches the cached objects IN PLACE reaches the first computed and dies there. The
+ * spec above reads the array, which cannot see that; this one is the reader's own chain.
+ */
+describe('execution store shallow-ref writes through the reader chain', () => {
+  let store: ReturnType<typeof useExecutionStore>
+  beforeEach(() => {
+    store = useExecutionStore()
+  })
+
+  function forkRun(rev: number, chat: string[]): ExecutionInstance {
+    return {
+      id: 'e1',
+      blockId: 'b1',
+      status: 'blocked',
+      rev,
+      currentStep: 0,
+      steps: [{ agentKind: 'coder', forkDecision: { status: 'answering', chat } }],
+    } as unknown as ExecutionInstance
+  }
+
+  it('an echo reaches a value derived through getInstance and the step', async () => {
+    // Exactly `ForkDecisionWindow.vue`: instance, then step, then the chat on it.
+    const instance = computed(() => store.getInstance('e1'))
+    const step = computed(
+      () =>
+        instance.value?.steps[0] as unknown as
+          | { forkDecision?: { chat: string[]; status: string } }
+          | undefined,
+    )
+    const chat = computed(() => step.value?.forkDecision?.chat ?? [])
+
+    store.hydrate([forkRun(1, ['human'])], 'ws1')
+    expect(chat.value).toEqual(['human'])
+
+    await store.echoAfter(
+      'e1',
+      () => Promise.resolve({ status: 'answering', chat: ['human', 'echoed'] }),
+      (state, held) => {
+        ;(held.steps[0] as unknown as { forkDecision: unknown }).forkDecision = state
+      },
+    )
+    // Unguarded (an in-place patch), this stayed ['human'] and the "thinking…" bubble spun on.
+    expect(chat.value).toEqual(['human', 'echoed'])
+  })
+
+  it('an echo onto the RUN itself reaches a value derived through getInstance', async () => {
+    const gate = computed(
+      () => (store.getInstance('e1') as unknown as { inputGate?: { state: string } })?.inputGate,
+    )
+    store.hydrate([forkRun(1, [])], 'ws1')
+    expect(gate.value).toBeUndefined()
+
+    await store.echoAfter(
+      'e1',
+      () => Promise.resolve({ state: 'released' }),
+      (state, held) => {
+        ;(held as unknown as { inputGate: unknown }).inputGate = state
+      },
+    )
+    expect(gate.value).toEqual({ state: 'released' })
+  })
+})
+
+/**
+ * The whole-run read behind the step-detail overlays: WHEN a reader has to ask, and what it is
+ * told while the answer is missing. Both are things the overlay cannot work out for itself, which
+ * is why they are the store's to state.
+ */
+describe('execution store whole-run reads', () => {
+  let store: ReturnType<typeof useExecutionStore>
+  // Every read here FAILS: the pending/failed states are the ones the overlay cannot work out for
+  // itself, and the success path is covered by the projection reconcile above.
+  let reads: number
+  beforeEach(() => {
+    reads = 0
+    useWorkspaceStore().workspaceId = 'ws1'
+    vi.stubGlobal('useApi', () => ({
+      getExecution: () => {
+        reads += 1
+        return Promise.reject(new Error('network down'))
+      },
+    }))
+    store = useExecutionStore()
+  })
+
+  function lean(rev: number): ExecutionInstance {
+    return {
+      id: 'e1',
+      blockId: 'b1',
+      status: 'running',
+      rev,
+      projected: true,
+      steps: [{ agentKind: 'coder', state: 'done', hasOutput: true }],
+    } as unknown as ExecutionInstance
+  }
+
+  function full(rev: number): ExecutionInstance {
+    return {
+      id: 'e1',
+      blockId: 'b1',
+      status: 'running',
+      rev,
+      steps: [{ agentKind: 'coder', state: 'done', output: 'prose' }],
+    } as unknown as ExecutionInstance
+  }
+
+  it('asks nothing for a run held whole, and asks AGAIN when a newer projection lands on it', () => {
+    store.hydrate([lean(4)], 'ws1')
+    const first = store.fullFetchKey('e1')
+    expect(first).not.toBeNull()
+
+    store.upsert(full(4))
+    // Held whole: an overlay opening now must not fire a point-read.
+    expect(store.fullFetchKey('e1')).toBeNull()
+
+    // A full refresh lands the lean projection again, one revision on, so the prose it withholds
+    // is no longer the prose the cache holds and cannot be carried forward. The key has to CHANGE,
+    // or the watch that fired on open never fires again and the open overlay blanks for good.
+    store.hydrate([lean(5)], 'ws1')
+    const reasked = store.fullFetchKey('e1')
+    expect(reasked).not.toBeNull()
+    expect(reasked).not.toBe(first)
+  })
+
+  it('withholds a recorded failure once the run arrives whole by another route', async () => {
+    store.hydrate([lean(4)], 'ws1')
+    await store.ensureFull('e1')
+    expect(store.fullError('e1')).toBe('network down')
+    expect(store.isFullPending('e1')).toBe(false)
+
+    // A live `execution` event delivers every run complete, and it knows nothing about the fetch
+    // that failed. A banner saying the run could not be loaded, over prose that loaded, is worse
+    // than no banner.
+    store.upsert(full(5))
+    expect(store.fullError('e1')).toBeNull()
+  })
+
+  it('drops the read bookkeeping on a board switch', async () => {
+    store.hydrate([lean(4)], 'ws1')
+    await store.ensureFull('e1')
+    expect(store.fullError('e1')).toBe('network down')
+
+    store.resetFullReads()
+    expect(store.fullError('e1')).toBeNull()
+    expect(store.isFullPending('e1')).toBe(false)
+  })
+
+  it('makes ONE request for two overlays opening the same run, and re-asks after a failure', async () => {
+    store.hydrate([lean(4)], 'ws1')
+    // The window and its shell both ask in the same tick, on the heaviest row of the run.
+    await Promise.all([store.ensureFull('e1'), store.ensureFull('e1')])
+    expect(reads).toBe(1)
+
+    // The retry is what the reader is waiting on now, so the previous failure stops being the
+    // thing the surface reports the moment the new attempt starts.
+    const retry = store.ensureFull('e1')
+    expect(store.fullError('e1')).toBeNull()
+    expect(store.isFullPending('e1')).toBe(true)
+    await retry
+    expect(reads).toBe(2)
+    expect(store.fullError('e1')).toBe('network down')
+  })
+})

package/app/stores/execution.ts

@@ -1,8 +1,11 @@
 import { defineStore } from 'pinia'
-import { ref, computed } from 'vue'
+import { computed, shallowRef, triggerRef } from 'vue'
 import type { ExecutionInstance } from '~/types/domain'
 import { createExecutionCommands } from '~/stores/execution/commands'
 import { createPendingGateSelectors } from '~/stores/execution/pendingGates'
+import { createExecutionReconcile } from '~/stores/execution/reconcile'
+import { createWholeRunReads } from '~/stores/execution/wholeRunReads'
+import { useWorkspaceStore } from '~/stores/workspace'
 
 /**
  * Running pipeline instances. The simulation engine lives on the backend: this
@@ -10,9 +13,11 @@ import { createPendingGateSelectors } from '~/stores/execution/pendingGates'
  * call the worker and then refresh the workspace snapshot, since advancing an
  * execution also rolls status/progress up onto its block server-side.
  *
- * The run-control commands live in a cohesive factory ({@link createExecutionCommands}, under
- * `stores/execution/`) that closes over the state assembled here — a size-only split mirroring
- * `stores/board/`, not a new seam.
+ * Three cohesive factories under `stores/execution/` close over the state assembled here, all
+ * size-only splits mirroring `stores/board/` rather than new seams: the snapshot/event reconcile
+ * ({@link createExecutionReconcile}), the human-gate projections
+ * ({@link createPendingGateSelectors}) and the run-control commands
+ * ({@link createExecutionCommands}).
  */
 export const useExecutionStore = defineStore('execution', () => {
   const api = useApi()
@@ -21,115 +26,33 @@ export const useExecutionStore = defineStore('execution', () => {
   // in the store means every caller (board card, drag-drop, menus, restart controls)
   // gets identical handling, including the fire-and-forget ones that never caught.
   const runErrors = usePipelineErrorToast()
-  const instances = ref<ExecutionInstance[]>([])
-  // The workspace whose snapshot last hydrated the cache. Scopes the DROP-preservation
-  // below: a board SWITCH replaces the cache outright instead of leaking the previous
-  // board's runs (an ExecutionInstance carries no workspaceId of its own).
-  let hydratedWorkspaceId: string | null = null
-
-  /** A run's monotonic server revision (bumped on every persisted write; absent = 0). */
-  function revOf(e: ExecutionInstance): number {
-    return e.rev ?? 0
-  }
-
-  /** A finished run — nothing further will execute or emit. Matches `runLive`/`runFailed`. */
-  function isTerminal(status: ExecutionInstance['status']): boolean {
-    return status === 'done' || status === 'failed'
-  }
-
-  /**
-   * Carry forward each step's LLM-metrics rollup (`step.metrics`) when an incoming
-   * instance omits it. Metrics is DERIVED, LIVE-ONLY state: the backend attaches it only
-   * on step-boundary/terminal emits (not on the frequent progress-only running folds — a
-   * perf optimisation that skips the per-run metrics GROUP BY on every poll tick) and
-   * never persists it, so it rides neither the snapshot nor a running-fold event. A plain
-   * REPLACE would blank the per-step metrics bar on every progress tick; per the live-push
-   * coherence rules a REPLACE must not drop live-only state, so preserve the last-known
-   * rollup per step. Steps are positionally stable within a run (same id ⇒ same shape), so
-   * match by index; the agentKind guard is belt-and-suspenders against a reshaped list.
-   */
-  function withPreservedMetrics(
-    incoming: ExecutionInstance,
-    cached: ExecutionInstance | undefined,
-  ): ExecutionInstance {
-    if (!cached) return incoming
-    let changed = false
-    const steps = incoming.steps.map((step, i) => {
-      if (step.metrics != null) return step
-      const prior = cached.steps[i]
-      if (prior?.metrics == null || prior.agentKind !== step.agentKind) return step
-      changed = true
-      return { ...step, metrics: prior.metrics }
-    })
-    return changed ? { ...incoming, steps } : incoming
-  }
-
   /**
-   * Reconcile the cached executions with a server snapshot for `workspaceId`. A snapshot
-   * is authoritative EXCEPT where a live `execution` event already advanced (or ADDED) a
-   * run past what this (possibly stale) read observed — the same two clobber hazards the
-   * `agentRuns` store guards, keyed here on the run's monotonic `rev`:
-   *   - REGRESS: a run present in BOTH — keep the newer-by-`rev` version, so a lagging
-   *     refresh (the stream's on-(re)connect resync, the debounced `board`-event refetch)
-   *     can't revert a just-terminal run to `running`. A terminal run emits nothing
-   *     further, so a regression here would strand the UI until an unrelated refresh.
-   *   - DROP: a run a live event just ADDED that the (older) snapshot never saw — keep it
-   *     rather than silently dropping it, but ONLY when it is not the terminal predecessor a
-   *     retry replaced (see below).
+   * Every cached run.
    *
-   * The DROP caveat matters because a retry/restart REPLACES a block's run with a fresh one
-   * under a NEW id (the old run is deleted server-side), so the two attempts can't be
-   * reconciled by id or `rev`. Since there is exactly one run per block, a cached-only run
-   * whose block the snapshot already covers is that superseded predecessor — drop it.
-   * Preserving it would leave the dead `failed` run shadowing the running one in the by-block
-   * projection (`agentRuns.byBlock`, last-write-wins), keeping the failure banner up and its
-   * empty trail hiding the retry's carried-forward failure history.
+   * SHALLOW on purpose. A deep `ref` proxies the whole run graph (run to steps to subtasks to
+   * items), and the swimlane assembly, the cards and the pipeline strips read step fields
+   * constantly, so every one of those reads paid proxy overhead on a structure that is only ever
+   * written through this store. Three write sites keep it coherent, and there are no others:
+   * {@link hydrate} and `cancel` replace the array (which a shallow ref tracks on its own);
+   * {@link upsert} index-assigns or pushes; {@link echoAfter} swaps in a patched copy of ONE run.
+   * The last two announce the change with `triggerRef`.
    *
-   * The drop is gated on the cached run being TERMINAL (`done`/`failed`): only a finished
-   * predecessor is ever superseded. A cached run still `running`/`blocked`/`paused` is a
-   * genuinely live-added run, so it must survive even when a stale reconnect snapshot (fetched
-   * before a retry, resolving late under load — see `useWorkspaceStream`) still lists its
-   * block's now-deleted predecessor. Dropping a live run there would strand the UI showing the
-   * dead attempt — the inverse of the bug this guard fixes — and `rev` can't catch it (the
-   * ids differ).
+   * EVERY WRITE MUST ALSO CHANGE IDENTITY, which `triggerRef` alone does not buy. Nothing under
+   * this ref is a reactive proxy any more, so the only dependency a reader can hold is the ref
+   * itself, and almost every reader holds it through an identity-stable chain
+   * (`computed(() => getInstance(id))` to `steps[i]` to one field). A trigger re-runs the first
+   * computed in that chain, but Vue stops propagating when the recomputed value is `===` the old
+   * one, so a run patched IN PLACE re-reads as unchanged and the chain below it never re-runs.
+   * That is why {@link echoAfter} patches a COPY rather than the cached object.
+   *
+   * A reactivity regression here is SILENT (a card simply stops updating), so a new write path
+   * must replace the array or swap the run it touched, and the store specs are what pin that.
    */
-  function hydrate(next: ExecutionInstance[], workspaceId: string) {
-    const sameWorkspace = hydratedWorkspaceId === workspaceId
-    hydratedWorkspaceId = workspaceId
-    if (!sameWorkspace) {
-      instances.value = next
-      return
-    }
-    const incomingIds = new Set(next.map((e) => e.id))
-    const incomingBlocks = new Set(next.map((e) => e.blockId))
-    const held = new Map(instances.value.map((e) => [e.id, e]))
-    const reconciled = next.map((incoming) => {
-      const current = held.get(incoming.id)
-      if (current && revOf(current) > revOf(incoming)) return current
-      return withPreservedMetrics(incoming, current)
-    })
-    // Preserve a cached-only run UNLESS it is the terminal predecessor a retry replaced: a
-    // finished (`done`/`failed`) run whose block the snapshot now covers under a fresh id.
-    // Gating on the CACHED run being terminal keeps a live `running`/`blocked`/`paused` run
-    // that a stale snapshot happens to omit.
-    const preserved = [...held.values()].filter(
-      (e) => !incomingIds.has(e.id) && !(isTerminal(e.status) && incomingBlocks.has(e.blockId)),
-    )
-    instances.value = [...reconciled, ...preserved]
-  }
+  const instances = shallowRef<ExecutionInstance[]>([])
 
-  /**
-   * Insert or replace a single execution instance pushed by the event stream.
-   * Monotonic by `rev`: an out-of-order/stale event can't regress a run a newer
-   * write already advanced (same guard as {@link hydrate}).
-   */
-  function upsert(instance: ExecutionInstance) {
-    const i = instances.value.findIndex((e) => e.id === instance.id)
-    if (i >= 0) {
-      if (revOf(instance) >= revOf(instances.value[i]!))
-        instances.value[i] = withPreservedMetrics(instance, instances.value[i]!)
-    } else instances.value.push(instance)
-  }
+  // Snapshot/event reconcile: `hydrate`, `upsert` and the two shared predicates
+  // (`stores/execution/reconcile.ts`).
+  const { revOf, isTerminal, hydrate, upsert } = createExecutionReconcile(instances)
 
   const byId = computed(() => {
     const map = new Map<string, ExecutionInstance>()
@@ -169,9 +92,21 @@ export const useExecutionStore = defineStore('execution', () => {
     const before = byId.value.get(executionId)
     const revBefore = before ? revOf(before) : -1
     const state = await send()
-    const instance = byId.value.get(executionId)
+    const i = instances.value.findIndex((e) => e.id === executionId)
+    const instance = i >= 0 ? instances.value[i]! : undefined
     if (!instance || revOf(instance) !== revBefore) return state
-    apply(state, instance)
+    // `apply` MUTATES what it is handed, so hand it a COPY and swap that copy in. Patching the
+    // cached objects in place would leave every identity-stable reader
+    // (`computed(() => getInstance(id))` to `steps[i]`) recomputing to the same object, which
+    // Vue treats as no change and stops propagating: the trigger would reach the first computed
+    // in the chain and nothing below it. The steps are copied too, because most echoes write a
+    // step's sub-state and the readers hold the STEP, not the run.
+    const patched: ExecutionInstance = { ...instance, steps: instance.steps.map((s) => ({ ...s })) }
+    apply(state, patched)
+    instances.value[i] = patched
+    // An index assignment is invisible to a shallow ref. This is the one seam every action
+    // store's `assign` goes through, which is what makes one trigger enough.
+    triggerRef(instances)
     return state
   }
 
@@ -179,6 +114,17 @@ export const useExecutionStore = defineStore('execution', () => {
     return id ? byId.value.get(id) : undefined
   }
 
+  // The WHOLE-RUN read behind the step-detail overlays: when a prose reader has to ask for the run
+  // the board snapshot only projected, and what it is told while the answer is missing
+  // (`stores/execution/wholeRunReads.ts`). A cohesive collaborator over bound callbacks, the same
+  // shape as the reconcile above.
+  const wholeRunReads = createWholeRunReads({
+    cached: (id) => byId.value.get(id),
+    workspaceId: () => useWorkspaceStore().workspaceId,
+    fetch: (workspaceId, executionId) => api.getExecution(workspaceId, executionId),
+    apply: upsert,
+  })
+
   /**
    * Each block's run, indexed once per change to `instances` instead of scanned per lookup.
    *
@@ -230,6 +176,7 @@ export const useExecutionStore = defineStore('execution', () => {
     echoAfter,
     byId,
     getInstance,
+    ...wholeRunReads,
     getByBlock,
     ...pendingGates,
     ...commands,