@cat-factory/app 0.283.0 → 0.284.0

package/app/composables/useStepApproval.ts

@@ -23,6 +23,11 @@ export function useStepApproval(opts: {
   approvalId: () => string | null
   approvalPending: () => boolean
   companionExceeded: () => boolean
+  /**
+   * Whether the cached run carries the step's captured prose rather than the board snapshot's
+   * projection of it (`ExecutionInstance.projected`). Gates {@link canEditProposal}: see there.
+   */
+  runIsWhole: () => boolean
   close: () => void
 }) {
   const execution = useExecutionStore()
@@ -138,7 +143,20 @@ export function useStepApproval(opts: {
     }
   }
 
+  /**
+   * Whether "approve with corrections" can be ENTERED. The editor seeds itself from the step's own
+   * prose, and the board snapshot WITHHOLDS that prose: an instance is a lean projection until the
+   * overlay's whole-run read lands (`projectExecutionForBoard`, `ExecutionStore.ensureFull`). Under
+   * a projection `step.output` is `undefined`, so entering edit mode would seed an EMPTY draft, and
+   * approving it would replace the agent's proposal with nothing. The reader states the fetch's
+   * pending/failed state on its own (`RunDetailLoadState`), so this withholds the verb rather than
+   * explaining itself twice.
+   */
+  const canEditProposal = computed(() => opts.runIsWhole())
+
   function startEditing() {
+    // Refused rather than clamped: seeding an empty draft is the data loss this guards.
+    if (!canEditProposal.value) return
     draftProposal.value = opts.step()?.output ?? ''
     editing.value = true
     // Editing and the review/reject path are mutually exclusive — clear the other.
@@ -226,6 +244,7 @@ export function useStepApproval(opts: {
     draftProposal,
     rejectArmed,
     canRequestChanges,
+    canEditProposal,
     quorum,
     viewerHasApproved,
     approvalWouldClearGate,

package/app/composables/useStepTimer.ts

@@ -1,4 +1,5 @@
-import { ref, computed, onMounted, onUnmounted } from 'vue'
+import { ref, computed, onMounted, onUnmounted, watchEffect } from 'vue'
+import type { Ref } from 'vue'
 import type { PipelineStep } from '~/types/execution'
 
 /**
@@ -55,21 +56,74 @@ export function stepActivityAgoMs(step: PipelineStep | null, nowMs: number): num
 }
 
 /**
- * A shared 1s wall-clock tick for surfaces that render many steps' live durations
- * at once (the pipeline timeline, the inspector run list). One interval drives every
- * step's elapsed label instead of a per-step timer. Stays `0` until mounted so the
+ * One wall-clock ticker per interval, shared by every caller and running only while at least one
+ * of them WANTS it. Keyed by interval because the surfaces genuinely differ (a 1s elapsed clock,
+ * the outcome card's 30s one) and two intervals cannot share a timer.
+ *
+ * Both halves were per-caller before, and both cost: `useStepTimer` creates a tick per invocation
+ * against its own one-interval intent, so N mounted `StepRunMeta`s meant N independent 1s timers;
+ * and the timer ran for the component's whole mounted lifetime whether or not anything was
+ * running, so a board of finished runs woke the main thread once a second to recompute labels that
+ * are frozen by definition.
+ */
+const tickers = new Map<
+  number,
+  { now: Ref<number>; users: number; timer?: ReturnType<typeof setInterval> }
+>()
+
+function tickerFor(intervalMs: number) {
+  let ticker = tickers.get(intervalMs)
+  if (!ticker) {
+    ticker = { now: ref(0), users: 0 }
+    tickers.set(intervalMs, ticker)
+  }
+  return ticker
+}
+
+function acquireTicker(intervalMs: number) {
+  const ticker = tickerFor(intervalMs)
+  if (++ticker.users === 1) {
+    // Stamp on the way in: a caller that subscribes between ticks must not read the stale
+    // value the last one left behind (or the 0 of a ticker nothing has ever run).
+    ticker.now.value = Date.now()
+    ticker.timer = setInterval(() => (ticker.now.value = Date.now()), intervalMs)
+  }
+  return ticker.now
+}
+
+function releaseTicker(intervalMs: number) {
+  const ticker = tickers.get(intervalMs)
+  if (!ticker || ticker.users === 0) return
+  if (--ticker.users === 0) {
+    clearInterval(ticker.timer)
+    ticker.timer = undefined
+  }
+}
+
+/**
+ * A shared wall-clock tick for surfaces that render live durations (the pipeline timeline, the
+ * inspector run list, a step's elapsed clock). Reads `0` until something is subscribed, so the
  * first paint never reads a stale time.
+ *
+ * `active` gates the SUBSCRIPTION: pass it when the surface only needs a clock some of the time
+ * (a step's timer needs one exactly while the step runs), and the shared timer stops as soon as
+ * the last interested caller stops asking. Omitted means "for as long as this component is
+ * mounted", which is what a surface rendering many steps at once wants.
  */
-export function useNowTick(intervalMs = 1000) {
-  const now = ref(0)
-  let timer: ReturnType<typeof setInterval> | undefined
+export function useNowTick(intervalMs = 1000, active?: () => boolean) {
+  const now = tickerFor(intervalMs).now
+  let subscribed = false
+  function want(on: boolean) {
+    if (on === subscribed) return
+    subscribed = on
+    if (on) acquireTicker(intervalMs)
+    else releaseTicker(intervalMs)
+  }
   onMounted(() => {
-    now.value = Date.now()
-    timer = setInterval(() => (now.value = Date.now()), intervalMs)
-  })
-  onUnmounted(() => {
-    if (timer) clearInterval(timer)
+    if (active) watchEffect(() => want(active()))
+    else want(true)
   })
+  onUnmounted(() => want(false))
   return now
 }
 
@@ -84,12 +138,14 @@ export function useStepTimer(opts: {
   runFailed: () => boolean
   failureAt: () => number | null | undefined
 }) {
-  const nowTick = useNowTick()
-
   // A step that is finished, failed, or parked on a human is not actively
   // executing — no ticking clock or spinner. `pausedAt` is the "waiting on input" freeze.
   const isRunning = computed(() => stepIsRunning(opts.step(), opts.runFailed()))
 
+  // Subscribe to the SHARED 1s clock, and only while this step is actually running: every value
+  // below freezes at the step's own end stamp otherwise, so a tick would recompute nothing.
+  const nowTick = useNowTick(1000, () => isRunning.value)
+
   /** Elapsed/total execution time in ms — null until the step has started. */
   const durationMs = computed(() =>
     stepDurationMs(opts.step(), nowTick.value, opts.runFailed(), opts.failureAt()),

package/app/composables/useUpsertList.spec.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest'
+import { computed } from 'vue'
 import { useUpsertList } from '~/composables/useUpsertList'
 
 interface Item {
@@ -63,6 +64,78 @@ describe('useUpsertList', () => {
     expect(items.value).toHaveLength(2)
   })
 
+  // Lookups run off a lazily-rebuilt key -> position map. Every write that MOVES an existing
+  // position has to invalidate it, and so does a caller replacing `items` wholesale (which the
+  // returned ref deliberately allows). A stale index answers with the wrong row, so these assert
+  // the identity of what comes back, not just that something did.
+  describe('key index coherence', () => {
+    it('answers correctly after a prepend has shifted every later position', () => {
+      const { upsert, get, indexOf } = useUpsertList<Item>({ key: (x) => x.id, prepend: true })
+      upsert({ id: 'a', v: 1 })
+      expect(indexOf('a')).toBe(0)
+      upsert({ id: 'b', v: 2 })
+      expect(indexOf('a')).toBe(1)
+      expect(get('a')).toEqual({ id: 'a', v: 1 })
+    })
+
+    it('answers correctly after a removal has shifted every later position', () => {
+      const { upsert, remove, get, indexOf } = useUpsertList<Item>({ key: (x) => x.id })
+      upsert({ id: 'a', v: 1 })
+      upsert({ id: 'b', v: 2 })
+      upsert({ id: 'c', v: 3 })
+      expect(indexOf('c')).toBe(2)
+      remove('a')
+      expect(indexOf('c')).toBe(1)
+      expect(get('b')).toEqual({ id: 'b', v: 2 })
+      expect(get('a')).toBeUndefined()
+    })
+
+    it('answers correctly after the caller replaces the list wholesale', () => {
+      const { items, upsert, get } = useUpsertList<Item>({ key: (x) => x.id })
+      upsert({ id: 'a', v: 1 })
+      items.value = [
+        { id: 'b', v: 2 },
+        { id: 'a', v: 7 },
+      ]
+      expect(get('a')).toEqual({ id: 'a', v: 7 })
+      expect(get('b')).toEqual({ id: 'b', v: 2 })
+    })
+
+    // The index is a plain Map, so a reader answered out of an ALREADY-FRESH one depends on
+    // nothing the write it is waiting for touches: an append leaves `items.value` the same array,
+    // so a `computed` that missed on a key would never re-run. That is invisible in the store
+    // that has one reader per key today and a bug the moment a second appears, which is why it is
+    // pinned on the composable rather than on any caller.
+    it('re-runs a computed that MISSED on a key when that key is later appended', () => {
+      const { upsert, get } = useUpsertList<Item>({ key: (x) => x.id })
+      upsert({ id: 'a', v: 1 })
+      const wanted = computed(() => get('b'))
+      expect(wanted.value).toBeUndefined()
+
+      upsert({ id: 'b', v: 2 })
+      expect(wanted.value).toEqual({ id: 'b', v: 2 })
+    })
+
+    it('re-runs a computed whose item moved under a prepend', () => {
+      const { upsert, indexOf } = useUpsertList<Item>({ key: (x) => x.id, prepend: true })
+      upsert({ id: 'a', v: 1 })
+      const position = computed(() => indexOf('a'))
+      expect(position.value).toBe(0)
+
+      upsert({ id: 'b', v: 2 })
+      expect(position.value).toBe(1)
+    })
+
+    it('answers correctly after hydrate replaces the list', () => {
+      const { upsert, hydrate, get } = useUpsertList<Item>({ key: (x) => x.id })
+      upsert({ id: 'a', v: 1 })
+      expect(get('a')).toEqual({ id: 'a', v: 1 })
+      hydrate([{ id: 'b', v: 2 }])
+      expect(get('a')).toBeUndefined()
+      expect(get('b')).toEqual({ id: 'b', v: 2 })
+    })
+  })
+
   it('seeds from initial without aliasing the caller array', () => {
     const seed: Item[] = [{ id: 'a', v: 1 }]
     const { items, upsert } = useUpsertList<Item>({ key: (x) => x.id, initial: seed })

package/app/composables/useUpsertList.ts

@@ -28,20 +28,66 @@ export function useUpsertList<T>(opts: {
 } {
   const items = ref<T[]>(opts.initial ? [...opts.initial] : []) as Ref<T[]>
 
+  /**
+   * key -> position, rebuilt LAZILY.
+   *
+   * Every operation here was a `findIndex`, so a store's live-event path scanned its whole list
+   * per event and each `get` scanned it again. The map is invalidated rather than maintained
+   * because the two structural writes that move existing positions (a prepend, a removal) shift
+   * every later index, and a burst of them must not pay a rebuild each: whoever reads next pays
+   * for one. `indexedFor` also catches a caller REPLACING `items` wholesale, which the returned
+   * ref deliberately allows.
+   */
+  let index = new Map<unknown, number>()
+  let indexedFor: T[] | null = null
+
+  function reindex(): Map<unknown, number> {
+    // Track the array's LENGTH on every path, the fresh-index fast path included. The Map is
+    // plain, so a reader answered out of an already-fresh index would otherwise depend on nothing
+    // but the `items` ref, and an in-place append leaves that ref's value the same array: a
+    // computed that MISSED on a key would never re-run when the item it was waiting for arrives.
+    // `length` is the dependency the `findIndex` this replaced established, and it moves on every
+    // write that can turn a miss into a hit (push, unshift, splice) or shift a hit's position.
+    // A replace in place moves neither, and a reader that resolved an item already tracks its
+    // own index through the `items.value[i]` read below.
+    void items.value.length
+    if (indexedFor === items.value) return index
+    index = new Map(items.value.map((item, i) => [opts.key(item), i]))
+    indexedFor = items.value
+    return index
+  }
+
+  /** Mark the index stale after a write that moved existing positions. */
+  function invalidate() {
+    indexedFor = null
+  }
+
   function indexOf(keyValue: unknown): number {
-    return items.value.findIndex((x) => opts.key(x) === keyValue)
+    return reindex().get(keyValue) ?? -1
   }
 
   function upsert(item: T) {
-    const i = indexOf(opts.key(item))
-    if (i >= 0) items.value[i] = item
-    else if (opts.prepend) items.value.unshift(item)
-    else items.value.push(item)
+    const key = opts.key(item)
+    const i = indexOf(key)
+    if (i >= 0) {
+      // A replace in place moves nothing, so the index stays correct.
+      items.value[i] = item
+    } else if (opts.prepend) {
+      items.value.unshift(item)
+      invalidate()
+    } else {
+      // An append is the one structural write that moves nothing already indexed.
+      items.value.push(item)
+      if (indexedFor === items.value) index.set(key, items.value.length - 1)
+    }
   }
 
   function remove(keyValue: unknown) {
     const i = indexOf(keyValue)
-    if (i >= 0) items.value.splice(i, 1)
+    if (i >= 0) {
+      items.value.splice(i, 1)
+      invalidate()
+    }
   }
 
   function get(keyValue: unknown): T | undefined {

package/app/composables/useViewport.ts

@@ -1,4 +1,9 @@
-import { useBreakpoints, breakpointsTailwind, useMediaQuery } from '@vueuse/core'
+import {
+  breakpointsTailwind,
+  createSharedComposable,
+  useBreakpoints,
+  useMediaQuery,
+} from '@vueuse/core'
 
 /**
  * Single source of truth for responsive / input-modality decisions across the SPA.
@@ -18,11 +23,16 @@ import { useBreakpoints, breakpointsTailwind, useMediaQuery } from '@vueuse/core
  * but which can still be finger-panned. Use it for behaviour that must work the
  * moment a finger is on the glass (the board's one-finger pan); use `isTouch` for
  * the dominant-modality choices (hit-target sizing).
+ *
+ * SHARED, as the "single source of truth" above says: every caller gets the same three refs and
+ * the same three media-query listeners. Plain per-call composition attached a fresh listener set
+ * per calling component, so the layout shell, the board canvas and every responsive panel each
+ * registered their own copies of queries that can only ever agree.
  */
-export function useViewport() {
+export const useViewport = createSharedComposable(() => {
   const breakpoints = useBreakpoints(breakpointsTailwind)
   const isCompact = breakpoints.smaller('lg')
   const isTouch = useMediaQuery('(pointer: coarse)')
   const hasTouch = useMediaQuery('(any-pointer: coarse)')
   return { isCompact, isTouch, hasTouch }
-}
+})

package/app/stores/consensus.ts

@@ -2,6 +2,7 @@ import { defineStore } from 'pinia'
 import { ref } from 'vue'
 import type { ConsensusSession } from '~/types/consensus'
 import { useWorkspaceStore } from '~/stores/workspace'
+import { useSingleFlight } from '~/composables/useSingleFlight'
 
 /**
  * Consensus session state. A consensus-enabled step runs a multi-model process (panel /
@@ -18,6 +19,8 @@ export const useConsensusStore = defineStore('consensus', () => {
   const sessions = ref<Record<string, ConsensusSession | null>>({})
   /** Block ids whose session is currently being fetched. */
   const loading = ref<Set<string>>(new Set())
+  /** One in-flight fetch per block: the window and its opener both load on open. */
+  const loads = useSingleFlight<string, void>()
 
   function sessionFor(blockId: string): ConsensusSession | null {
     return sessions.value[blockId] ?? null
@@ -40,7 +43,11 @@ export const useConsensusStore = defineStore('consensus', () => {
   }
 
   /** Load the latest session for a block (window open / reload). Best-effort. */
-  async function load(blockId: string): Promise<void> {
+  function load(blockId: string): Promise<void> {
+    return loads.run(blockId, () => fetchSession(blockId))
+  }
+
+  async function fetchSession(blockId: string): Promise<void> {
     const wsId = workspace.workspaceId
     if (!wsId) return
     loading.value = new Set(loading.value).add(blockId)

package/app/stores/docInterview.ts

@@ -2,6 +2,7 @@ import { defineStore } from 'pinia'
 import { ref } from 'vue'
 import type { DocInterviewSession } from '~/types/domain'
 import { useWorkspaceStore } from '~/stores/workspace'
+import { useSingleFlight } from '~/composables/useSingleFlight'
 
 /**
  * Interactive document-interview sessions (WS5), keyed by their anchor BLOCK id. Loaded on
@@ -18,6 +19,8 @@ export const useDocInterviewStore = defineStore('docInterview', () => {
   const byBlock = ref<Record<string, DocInterviewSession>>({})
   /** True while a window action (continue/proceed) is resuming the run. */
   const resuming = ref(false)
+  /** One in-flight fetch per block: the window and its opener both load on open. */
+  const loads = useSingleFlight<string, void>()
 
   function forBlock(blockId: string): DocInterviewSession | null {
     return byBlock.value[blockId] ?? null
@@ -31,7 +34,13 @@ export const useDocInterviewStore = defineStore('docInterview', () => {
   }
 
   /** Re-fetch one block's session (the interview window's load path). */
-  async function load(blockId: string) {
+  function load(blockId: string): Promise<void> {
+    return loads.run(blockId, () => fetchSession(blockId))
+  }
+
+  // Out-of-order results need no ticket here: `upsert` is monotonic by the session's own
+  // `updatedAt`, so a slow fetch resolving after a live push (or after a newer load) is dropped.
+  async function fetchSession(blockId: string) {
     if (!workspace.workspaceId) return
     const session = await api.getDocInterview(workspace.workspaceId, blockId)
     if (session) upsert(session)

package/app/stores/execution/reconcile.ts

@@ -0,0 +1,182 @@
+import { triggerRef, type ShallowRef } from 'vue'
+import type { ExecutionInstance } from '~/types/domain'
+
+/**
+ * The snapshot/event RECONCILE for the execution store: how a full board snapshot and a live
+ * `execution` event fold into the cached runs without either clobbering the other, plus the two
+ * shared predicates (`revOf`, `isTerminal`) the rest of the store asks the same questions with.
+ *
+ * Created once in the store setup over its `instances` ref, so the rules stay behaviourally
+ * identical to the former in-closure functions: a size-only extraction mirroring
+ * `createPendingGateSelectors` and `createExecutionCommands`, not a new seam.
+ *
+ * It is also where the writes a SHALLOW `instances` cannot see announce themselves. `echoAfter`
+ * (still in the store, because it is about an ACTION's echo rather than about reconciling a read)
+ * is the only other one.
+ */
+export function createExecutionReconcile(instances: ShallowRef<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
+  }
+
+  /**
+   * Carry forward what the board snapshot's LEAN PROJECTION withholds
+   * (`projectExecutionForBoard`): each step's `output` prose, its `rework` and `testerQuality`
+   * blobs, and the run-level `outputHistory`. Withheld is not absent, so a projection landing on
+   * top of a full cached run must not blank an overlay someone is reading mid-scroll.
+   *
+   * ONLY AT AN EQUAL `rev`, which is what makes the carry-forward sound rather than a guess. At the
+   * same revision the run is byte-identical server-side, so the cached prose IS the withheld prose.
+   * One revision later it may not be (a step can have been re-run, reset or bounced), and pasting
+   * the old prose under the new run is the same clobber in reverse. So a NEWER projection replaces,
+   * stays marked `projected`, and the open overlay re-fetches the whole run (`ensureFull`).
+   *
+   * A merge that succeeds drops the `projected` mark when the cached run was itself complete: the
+   * result carries everything the cache did, and leaving the mark set would make every overlay
+   * re-fetch a run it already holds in full.
+   */
+  function withCarriedForwardWithheld(
+    incoming: ExecutionInstance,
+    cached: ExecutionInstance | undefined,
+  ): ExecutionInstance {
+    if (!incoming.projected || !cached || revOf(incoming) !== revOf(cached)) return incoming
+    const steps = incoming.steps.map((step, i) => {
+      const prior = cached.steps[i]
+      // Positionally stable within a run (same guard as `withPreservedMetrics`).
+      if (!prior || prior.agentKind !== step.agentKind) return step
+      return {
+        ...step,
+        ...definedOnly({
+          output: prior.output,
+          rework: prior.rework,
+          testerQuality: prior.testerQuality,
+        }),
+      }
+    })
+    return {
+      ...incoming,
+      steps,
+      ...definedOnly({ outputHistory: cached.outputHistory }),
+      ...(cached.projected ? {} : { projected: false }),
+    }
+  }
+
+  /** The subset of `fields` that is actually present, so a spread never writes `undefined` over a value. */
+  function definedOnly<T extends Record<string, unknown>>(fields: T): Partial<T> {
+    return Object.fromEntries(
+      Object.entries(fields).filter(([, v]) => v !== undefined),
+    ) as Partial<T>
+  }
+
+  /**
+   * 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).
+   *
+   * 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.
+   *
+   * 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).
+   */
+  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 withCarriedForwardWithheld(withPreservedMetrics(incoming, current), 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]
+  }
+
+  /**
+   * 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]!)) return
+      instances.value[i] = withCarriedForwardWithheld(
+        withPreservedMetrics(instance, instances.value[i]!),
+        instances.value[i]!,
+      )
+    } else instances.value.push(instance)
+    // `instances` is shallow: an index assignment and a push are both invisible to it.
+    triggerRef(instances)
+  }
+
+  return { revOf, isTerminal, hydrate, upsert }
+}