@cat-factory/app 0.277.1 → 0.277.2

package/app/stores/environmentTest.ts

@@ -62,14 +62,38 @@ export const useEnvironmentTestStore = defineStore('environmentTest', () => {
     }
   }
 
+  /**
+   * Runs whose point-read is already out, and whether a later hydrate asked again while it was.
+   * Overlapping refreshes preserve the same still-running runs and would each re-issue the same
+   * GET, so the reads multiply with refresh frequency exactly when the board is busiest.
+   *
+   * Dropping the later ask outright would be wrong for the same reason plain single-flight is wrong
+   * for `workspace.refresh()`: the outstanding read may have been ISSUED before the run reached
+   * terminal, and it is the later ask that would have observed the outcome. Nothing asks again after
+   * that (terminal runs emit no event and the snapshot omits them), so the inspector would sit on
+   * "testing" for the rest of the session. One queued follow-up per run keeps the dedupe while
+   * leaving the newest ask an answer: N overlapping hydrates cost one extra read between them.
+   */
+  const reconciling = new Map<string, { again: boolean }>()
+
   /** Best-effort point-read of one run, folded in through the monotonic {@link upsert}. */
   async function reconcileRun(workspaceId: string, id: string) {
+    const outstanding = reconciling.get(id)
+    if (outstanding) {
+      outstanding.again = true
+      return
+    }
+    const state = { again: false }
+    reconciling.set(id, state)
     try {
       upsert(await api.getEnvironmentTest(workspaceId, id))
     } catch {
       // Best-effort: a transient fetch failure just leaves the cached state; the next
       // snapshot/event reconciles it.
+    } finally {
+      reconciling.delete(id)
     }
+    if (state.again) await reconcileRun(workspaceId, id)
   }
 
   /**

package/app/stores/execution.spec.ts

@@ -273,3 +273,53 @@ describe('execution store echoAfter (optimistic-echo guard)', () => {
     expect(returned).toBe('body')
   })
 })
+
+describe('execution store per-block index', () => {
+  let store: ReturnType<typeof useExecutionStore>
+  beforeEach(() => {
+    store = useExecutionStore()
+  })
+
+  /**
+   * Named apart from the module-level `run()` on purpose: that one's second argument is a `rev`
+   * and this one's is a `blockId`, so one name for both would let a test moved between the two
+   * describes build a nonsense instance that still typechecks at the call site.
+   */
+  function blockRun(id: string, blockId: string, status: string): ExecutionInstance {
+    return { id, blockId, status, steps: [] } as unknown as ExecutionInstance
+  }
+
+  it('indexes one run per block', () => {
+    store.hydrate([blockRun('e1', 'b1', 'running'), blockRun('e2', 'b2', 'done')], 'ws1')
+    expect(store.getByBlock('b1')?.id).toBe('e1')
+    expect(store.getByBlock('b2')?.id).toBe('e2')
+    expect(store.getByBlock('missing')).toBeUndefined()
+  })
+
+  // The case the index has to keep answering the way the scan it replaced did: a stale reconnect
+  // snapshot re-listing a retry's now-deleted terminal predecessor beside the live successor.
+  it('prefers the live run over a terminal predecessor on the same block, in either order', () => {
+    store.hydrate([blockRun('old', 'b1', 'failed'), blockRun('new', 'b1', 'running')], 'ws1')
+    expect(store.getByBlock('b1')?.id).toBe('new')
+
+    store.hydrate([blockRun('new2', 'b2', 'running'), blockRun('old2', 'b2', 'failed')], 'ws1')
+    expect(store.getByBlock('b2')?.id).toBe('new2')
+  })
+
+  it('answers the LAST run when a block holds only terminal ones', () => {
+    store.hydrate([blockRun('first', 'b1', 'done'), blockRun('second', 'b1', 'failed')], 'ws1')
+    expect(store.getByBlock('b1')?.id).toBe('second')
+  })
+
+  it('keeps the first live run when a block holds several', () => {
+    store.hydrate([blockRun('a', 'b1', 'running'), blockRun('b', 'b1', 'blocked')], 'ws1')
+    expect(store.getByBlock('b1')?.id).toBe('a')
+  })
+
+  it('re-indexes when an event upserts a run', () => {
+    store.hydrate([blockRun('e1', 'b1', 'running')], 'ws1')
+    expect(store.getByBlock('b1')?.status).toBe('running')
+    store.upsert({ ...blockRun('e1', 'b1', 'done'), rev: 2 } as unknown as ExecutionInstance)
+    expect(store.getByBlock('b1')?.status).toBe('done')
+  })
+})

package/app/stores/execution.ts

@@ -179,14 +179,37 @@ export const useExecutionStore = defineStore('execution', () => {
     return id ? byId.value.get(id) : undefined
   }
 
+  /**
+   * Each block's run, indexed once per change to `instances` instead of scanned per lookup.
+   *
+   * A block only holds several runs transiently: a stale reconnect snapshot re-listing a retry's
+   * now-deleted terminal predecessor alongside the live successor. Prefer the live one so this
+   * projection agrees with `agentRuns.byBlock` (whose last-write-wins already resolves to it):
+   * the failed predecessor is dead and about to fall out on the next read.
+   *
+   * The single pass states that rule as "replace whatever is held whenever it is TERMINAL", which
+   * is the array form (`runs.find(live) ?? runs.at(-1)`) exactly: the first live run wins and is
+   * never displaced, and with no live run the LAST terminal one wins. Keep the two in step, since
+   * this is the only place the rule is written now.
+   *
+   * WHY AN INDEX. {@link getByBlock} was a full `instances` scan per call on three per-event hot
+   * paths: a computed on every mounted task card (`TaskPipelineMini`), `classify` inside the
+   * swimlane assembly of every mounted frame (`useFrameLanes`), and the board's expansion
+   * measurement pass (`useTaskExpansion`, per hover probe and per task when deep-zoomed). Each
+   * execution event invalidated all of them, so the board paid O(cards x runs) per event where one
+   * shared Map pays O(runs).
+   */
+  const byBlockLive = computed(() => {
+    const map = new Map<string, ExecutionInstance>()
+    for (const e of instances.value) {
+      const held = map.get(e.blockId)
+      if (!held || isTerminal(held.status)) map.set(e.blockId, e)
+    }
+    return map
+  })
+
   function getByBlock(blockId: string) {
-    const runs = instances.value.filter((e) => e.blockId === blockId)
-    if (runs.length <= 1) return runs[0]
-    // A block only holds several runs transiently: a stale reconnect snapshot re-listing a
-    // retry's now-deleted terminal predecessor alongside the live successor. Prefer the live
-    // one so this projection agrees with `agentRuns.byBlock` (whose last-write-wins already
-    // resolves to it) — the failed predecessor is dead and about to fall out on the next read.
-    return runs.find((e) => !isTerminal(e.status)) ?? runs.at(-1)
+    return byBlockLive.value.get(blockId)
   }
 
   // What across every cached run is awaiting a human (open decisions + approval gates, their

package/app/stores/notifications.ts

@@ -1,5 +1,6 @@
 import { defineStore } from 'pinia'
 import { computed, ref } from 'vue'
+import { collectReviewDebt } from '@cat-factory/contracts'
 import type { Notification } from '~/types/domain'
 import type {
   NotificationRoutingMatrix,
@@ -90,6 +91,20 @@ export const useNotificationsStore = defineStore('notifications', () => {
     return map
   })
 
+  /**
+   * Per-block "waiting since", derived from the open review-wait cards by the same
+   * `collectReviewDebt` the backend's friction check uses. It is the fallback source for the park
+   * surfaces that stamp no `step.pausedAt`.
+   *
+   * Derived HERE rather than in the reader because the reader is per FRAME: `useFrameLanes` runs
+   * one instance per mounted service frame and each was re-deriving the same reduction over the
+   * WHOLE open list, so a board with n frames paid O(frames x open notifications) on every
+   * notification change for one workspace-wide fact. One store computed serves every frame.
+   */
+  const reviewDebtByBlock = computed(
+    () => new Map(collectReviewDebt(open.value).map((d) => [d.blockId, d.waitingSince])),
+  )
+
   /** Total open count, for the toolbar badge. */
   const count = computed(() => open.value.length)
 
@@ -170,6 +185,7 @@ export const useNotificationsStore = defineStore('notifications', () => {
     hydrateBaseline,
     upsert,
     byBlock,
+    reviewDebtByBlock,
     count,
     act,
     dismiss,

package/app/stores/pipelines.ts

@@ -1,5 +1,5 @@
 import { defineStore } from 'pinia'
-import { ref } from 'vue'
+import { computed, ref } from 'vue'
 import type { Pipeline } from '~/types/domain'
 import type {
   GateConfigForm,
@@ -126,8 +126,15 @@ export const usePipelinesStore = defineStore('pipelines', () => {
     gateConfigForms.value = forms
   }
 
+  /**
+   * The library indexed by id. Indexed rather than scanned because every task card resolves its
+   * own default pipeline through {@link getPipeline}, so a `find` there is O(cards x catalog) on
+   * every catalog or card change.
+   */
+  const pipelineById = computed(() => new Map(pipelines.value.map((p) => [p.id, p])))
+
   function getPipeline(id: string) {
-    return pipelines.value.find((p) => p.id === id)
+    return pipelineById.value.get(id)
   }
 
   /**

package/app/stores/recurringPipelines.ts

@@ -32,9 +32,23 @@ export const useRecurringPipelinesStore = defineStore('recurringPipelines', () =
     return map
   })
 
+  /**
+   * Schedules indexed by the block they reuse. Indexed rather than scanned because `byBlock` is
+   * read from a computed on every mounted task card: a `find` there is O(cards x schedules) on
+   * every change, the same shape the execution store's `byBlockLive` index replaced.
+   *
+   * First wins, matching the `find` this replaced: a block backs at most one schedule, so a second
+   * row for it is transient state a refresh resolves, not a choice to make here.
+   */
+  const scheduleByBlock = computed(() => {
+    const map = new Map<string, PipelineSchedule>()
+    for (const s of schedules.value) if (!map.has(s.blockId)) map.set(s.blockId, s)
+    return map
+  })
+
   /** The schedule whose reused block is `blockId`, if any. */
   function byBlock(blockId: string): PipelineSchedule | undefined {
-    return schedules.value.find((s) => s.blockId === blockId)
+    return scheduleByBlock.value.get(blockId)
   }
 
   async function create(input: Parameters<typeof api.createRecurringPipeline>[1]) {

package/app/stores/workspace/refreshFunnel.spec.ts

@@ -0,0 +1,242 @@
+import { describe, it, expect } from 'vitest'
+import { createRefreshFunnel } from '~/stores/workspace/refreshFunnel'
+import type { WorkspaceSnapshot } from '~/types/domain'
+import type { LiveWriteBaselines } from '~/stores/workspace/hydrate'
+
+interface Harness {
+  readonly funnel: ReturnType<typeof createRefreshFunnel>
+  /** Resolve the oldest pending fetch with a snapshot naming `label`. */
+  readonly settle: (label: string) => Promise<void>
+  /** Reject the oldest pending fetch. */
+  readonly fail: (message?: string) => Promise<void>
+  readonly fetches: () => number
+  /** The workspace ids the funnel actually fetched, in order. */
+  readonly fetched: () => string[]
+  readonly applied: () => string[]
+  /** Whether the oldest pending fetch has been aborted. */
+  readonly aborted: () => boolean
+  setWorkspaceId: (id: string | null) => void
+}
+
+function harness(initialId: string | null = 'ws1', deadlineMs?: number): Harness {
+  let workspaceId = initialId
+  const pending: {
+    resolve: (s: WorkspaceSnapshot) => void
+    reject: (e: Error) => void
+    signal: AbortSignal
+  }[] = []
+  const fetched: string[] = []
+  const applied: string[] = []
+  const baselines = {} as LiveWriteBaselines
+
+  const funnel = createRefreshFunnel({
+    currentWorkspaceId: () => workspaceId,
+    fetchSnapshot: (id, signal) => {
+      fetched.push(id)
+      return new Promise<WorkspaceSnapshot>((resolve, reject) =>
+        pending.push({ resolve, reject, signal }),
+      )
+    },
+    captureBaselines: () => baselines,
+    apply: (snapshot) => applied.push(snapshot.workspace.id),
+    deadlineMs,
+  })
+
+  /** Let the funnel's internal continuations run before the assertions read its state. */
+  const drain = () => new Promise<void>((r) => setTimeout(r, 0))
+
+  return {
+    funnel,
+    settle: async (label) => {
+      pending.shift()!.resolve({ workspace: { id: label } } as unknown as WorkspaceSnapshot)
+      await drain()
+    },
+    fail: async (message = 'offline') => {
+      pending.shift()!.reject(new Error(message))
+      await drain()
+    },
+    fetches: () => fetched.length,
+    fetched: () => fetched,
+    applied: () => applied,
+    aborted: () => pending[0]!.signal.aborted,
+    setWorkspaceId: (id) => {
+      workspaceId = id
+    },
+  }
+}
+
+describe('refresh funnel', () => {
+  it('fetches and hydrates a single refresh', async () => {
+    const h = harness()
+    const done = h.funnel.refresh()
+    expect(h.fetches()).toBe(1)
+    await h.settle('snap1')
+    await done
+    expect(h.applied()).toEqual(['snap1'])
+  })
+
+  /**
+   * The coalescing rule. Callers arriving during a fetch share ONE follow-up, so N of them cost
+   * one extra fetch between them rather than N.
+   */
+  it('collapses callers arriving during a fetch into one follow-up', async () => {
+    const h = harness()
+    const first = h.funnel.refresh()
+    const a = h.funnel.refresh()
+    const b = h.funnel.refresh()
+    const c = h.funnel.refresh()
+    expect(a).toBe(b)
+    expect(b).toBe(c)
+    expect(h.fetches()).toBe(1)
+
+    await h.settle('snap1')
+    await first
+    expect(h.fetches()).toBe(2)
+    await h.settle('snap2')
+    await Promise.all([a, b, c])
+    expect(h.applied()).toEqual(['snap1', 'snap2'])
+  })
+
+  /**
+   * The reason plain single-flight is wrong here. A caller that mutated and then refreshed must
+   * observe a snapshot READ AFTER its call: handing it the in-flight fetch (issued before the
+   * mutation committed) would show it the pre-mutation world.
+   */
+  it('never hands a late caller the result of a fetch that was already in flight', async () => {
+    const h = harness()
+    const early = h.funnel.refresh()
+    const late = h.funnel.refresh()
+    await h.settle('before-mutation')
+    await early
+    // The late caller is still waiting: its own fetch has only just been issued.
+    expect(h.applied()).toEqual(['before-mutation'])
+    await h.settle('after-mutation')
+    await late
+    expect(h.applied()).toEqual(['before-mutation', 'after-mutation'])
+  })
+
+  it('still serves the queued caller when the in-flight fetch fails', async () => {
+    const h = harness()
+    const rejects = expect(h.funnel.refresh()).rejects.toThrow('offline')
+    const queued = h.funnel.refresh()
+    await h.fail()
+    await rejects
+    expect(h.fetches()).toBe(2)
+    await h.settle('recovered')
+    await queued
+    expect(h.applied()).toEqual(['recovered'])
+  })
+
+  it('propagates a failure to the caller that issued the fetch', async () => {
+    const h = harness()
+    // Attach the expectation BEFORE rejecting: `fail` yields to the microtask queue, and an
+    // unobserved rejection in that window is reported as unhandled.
+    const rejects = expect(h.funnel.refresh()).rejects.toThrow('boom')
+    await h.fail('boom')
+    await rejects
+    expect(h.applied()).toEqual([])
+  })
+
+  it('does nothing before a workspace is open', async () => {
+    const h = harness(null)
+    await h.funnel.refresh()
+    expect(h.fetches()).toBe(0)
+    expect(h.applied()).toEqual([])
+  })
+
+  it('discards a snapshot whose board was switched away from mid-fetch', async () => {
+    const h = harness()
+    const done = h.funnel.refresh()
+    h.setWorkspaceId('ws2')
+    await h.settle('stale')
+    await done
+    expect(h.applied()).toEqual([])
+  })
+
+  /**
+   * The queued follow-up is queued FOR a board. A switch while it waits makes it pointless, and
+   * issuing it anyway would read the NEW board's snapshot on behalf of a caller that asked about
+   * the old one, race the switch's own hydrate, and resolve as though the old board had refreshed.
+   */
+  it('does not fetch the new board on behalf of a follow-up queued for the old one', async () => {
+    const h = harness()
+    const first = h.funnel.refresh()
+    const queued = h.funnel.refresh()
+    h.setWorkspaceId('ws2')
+    await h.settle('stale')
+    await first
+    await queued
+    expect(h.fetched()).toEqual(['ws1'])
+    expect(h.applied()).toEqual([])
+  })
+
+  /**
+   * The slot is bounded, because serializing every refresh through it makes ONE stalled request
+   * everyone's problem: the client sets no timeout, so a dropped connection would otherwise leave
+   * the funnel holding a fetch that never settles and every later caller queued behind it forever.
+   */
+  describe('deadline', () => {
+    it('fails the caller, aborts the request and frees the slot when a fetch never settles', async () => {
+      const h = harness('ws1', 5)
+      const stalled = expect(h.funnel.refresh()).rejects.toThrow(/timed out/)
+      await stalled
+      expect(h.aborted()).toBe(true)
+
+      // The funnel is usable again: a fresh caller issues its own fetch rather than joining the
+      // hang, and the abandoned request can no longer hydrate anything if it does answer.
+      const next = h.funnel.refresh()
+      expect(h.fetches()).toBe(2)
+      await h.settle('late-answer-from-the-abandoned-fetch')
+      expect(h.applied()).toEqual([])
+      await h.settle('recovered')
+      await next
+      expect(h.applied()).toEqual(['recovered'])
+    })
+
+    it('does not count a timed-out fetch as coverage', async () => {
+      const h = harness('ws1', 5)
+      const mark = h.funnel.refreshMark()
+      await expect(h.funnel.refresh()).rejects.toThrow(/timed out/)
+      expect(h.funnel.hydratedSince(mark)).toBe(false)
+    })
+  })
+
+  describe('coverage mark', () => {
+    it('reports a fetch that started after the mark and hydrated', async () => {
+      const h = harness()
+      const mark = h.funnel.refreshMark()
+      const done = h.funnel.refresh()
+      expect(h.funnel.hydratedSince(mark)).toBe(false)
+      await h.settle('snap1')
+      await done
+      expect(h.funnel.hydratedSince(mark)).toBe(true)
+    })
+
+    // The mark is taken when a coarse event arrives. A fetch ALREADY in flight may have been
+    // issued before that event, so it must not read as coverage for it.
+    it('does not count a fetch that was already in flight when the mark was taken', async () => {
+      const h = harness()
+      const done = h.funnel.refresh()
+      const mark = h.funnel.refreshMark()
+      await h.settle('in-flight-before-the-event')
+      await done
+      expect(h.funnel.hydratedSince(mark)).toBe(false)
+    })
+
+    it('does not count a fetch that failed or was discarded', async () => {
+      const h = harness()
+      const mark = h.funnel.refreshMark()
+      const rejects = expect(h.funnel.refresh()).rejects.toThrow()
+      await h.fail()
+      await rejects
+      expect(h.funnel.hydratedSince(mark)).toBe(false)
+
+      const mark2 = h.funnel.refreshMark()
+      const discarded = h.funnel.refresh()
+      h.setWorkspaceId('ws2')
+      await h.settle('stale')
+      await discarded
+      expect(h.funnel.hydratedSince(mark2)).toBe(false)
+    })
+  })
+})

package/app/stores/workspace/refreshFunnel.ts

@@ -0,0 +1,156 @@
+import type { WorkspaceSnapshot } from '~/types/domain'
+import type { LiveWriteBaselines } from '~/stores/workspace/hydrate'
+
+/**
+ * The one door every full-snapshot refresh goes through.
+ *
+ * WHY A FUNNEL. `workspace.refresh()` is the client's heaviest operation: a ~20-read snapshot
+ * aggregate on the server, then 31 hydrate calls into 24 stores. Roughly 35 call sites reach for it
+ * directly after a mutation, and the event stream schedules its own on every coarse `board` event,
+ * so the paths that produce the most events are exactly the paths that stacked the most redundant
+ * snapshots. Making the funnel the FUNCTION every caller already calls is what lets those call
+ * sites stay as they are: there is nothing for a new mutation to remember to opt into.
+ *
+ * THE COALESCING RULE, and why it is not plain single-flight. A caller that awaits `refresh()`
+ * after its own mutation is entitled to a snapshot that INCLUDES that mutation. Handing it the
+ * promise of a fetch already in flight would break that: the in-flight request may have been issued
+ * before the mutation committed. So a call arriving during a fetch does not join it, it joins a
+ * SINGLE queued follow-up that starts once the current one settles. Any number of callers during
+ * one slow fetch therefore cost one extra fetch between them, never one each, and every caller
+ * still observes a snapshot read after it called.
+ *
+ * THE COVERAGE MARK. A coarse `board` event means "something changed, resync", and a snapshot whose
+ * fetch was ISSUED after that event arrived necessarily contains the change (the server emits the
+ * event after committing it). {@link RefreshFunnel.refreshMark} + {@link RefreshFunnel.hydratedSince}
+ * let the stream's debounce ask exactly that question and drop a refresh some mutation's own
+ * `refresh()` already covered, which is the duplicate the direct call sites otherwise pay twice.
+ * The mark counts fetches STARTED and only a fetch that actually HYDRATED advances the answer, so a
+ * discarded or failed one never reads as coverage.
+ *
+ * Ordering needs no sequence guard: at most one fetch is ever in flight, so two snapshots cannot
+ * resolve out of order. A board SWITCH is the one thing that outdates a request rather than
+ * ordering it, so it is checked twice: an arrived snapshot for a board nothing is showing is
+ * discarded, and a queued follow-up for such a board is never issued (it would fetch the CURRENT
+ * board on a caller that asked about the old one, and report that as its answer).
+ *
+ * SERIALIZING MAKES A STALL EVERYONE'S PROBLEM, which is why the slot is bounded: see
+ * {@link SNAPSHOT_DEADLINE_MS}.
+ */
+export interface RefreshFunnelDeps {
+  /** The active workspace id, or null before bootstrap. Read fresh on each attempt. */
+  readonly currentWorkspaceId: () => string | null
+  /** Read the snapshot. `signal` aborts on the deadline, so a stalled request is released. */
+  readonly fetchSnapshot: (workspaceId: string, signal: AbortSignal) => Promise<WorkspaceSnapshot>
+  /**
+   * Capture the live-write baselines BEFORE the fetch: anything a live event writes while this
+   * (potentially slow) snapshot is in flight is newer than the snapshot, so the hydrate must not
+   * clobber it back.
+   */
+  readonly captureBaselines: () => LiveWriteBaselines
+  readonly apply: (snapshot: WorkspaceSnapshot, baselines: LiveWriteBaselines) => void
+  /** Override the deadline below. Exists for the tests; production takes the default. */
+  readonly deadlineMs?: number
+}
+
+/**
+ * How long the funnel holds its one slot before giving up on a fetch.
+ *
+ * The snapshot read goes through the shared wretch client, which sets no timeout, so a stalled
+ * connection (a dropped mobile or VPN link) leaves a GET pending without ever rejecting. With every
+ * refresh serialized behind one slot, that single stall would wedge the whole path: no later fetch
+ * is issued, the coarse-event resync stops running, the stream's bounded retry never sees a failure
+ * to retry, and every awaited `refresh()` hangs its caller forever. A deadline turns it into an
+ * ordinary failure all three can act on. It ABORTS as well as abandons, so the stalled request is
+ * released rather than left to answer into nothing, and a snapshot that lands after the deadline is
+ * never applied: the funnel has already moved on, and its baselines are that much staler.
+ *
+ * Sized well above a slow-but-real snapshot (the aggregate is ~20 reads) so it only ever fires on a
+ * connection that is not coming back.
+ */
+const SNAPSHOT_DEADLINE_MS = 30_000
+
+export interface RefreshFunnel {
+  /** Re-fetch the snapshot and re-hydrate, coalesced as described above. */
+  readonly refresh: () => Promise<void>
+  /** A token to compare against later: how many snapshot fetches have STARTED. */
+  readonly refreshMark: () => number
+  /** Whether a snapshot fetch issued after `mark` has already hydrated. */
+  readonly hydratedSince: (mark: number) => boolean
+}
+
+export function createRefreshFunnel(deps: RefreshFunnelDeps): RefreshFunnel {
+  const deadlineMs = deps.deadlineMs ?? SNAPSHOT_DEADLINE_MS
+  let starts = 0
+  let lastHydratedStart = 0
+  let inFlight: Promise<void> | null = null
+  /**
+   * The one queued follow-up, tagged with the board it was queued FOR. A caller joins it only when
+   * it asks about the same board: after a switch mid-fetch, a caller asking about the NEW board must
+   * be neither served nor stood down by a follow-up queued for the old one.
+   */
+  let queued: { readonly targetId: string; readonly promise: Promise<void> } | null = null
+
+  /** Read the snapshot under the deadline, aborting the request when it expires. */
+  async function fetchSnapshot(targetId: string): Promise<WorkspaceSnapshot> {
+    const controller = new AbortController()
+    let timer: ReturnType<typeof setTimeout> | undefined
+    try {
+      return await new Promise<WorkspaceSnapshot>((resolve, reject) => {
+        timer = setTimeout(() => {
+          controller.abort()
+          reject(new Error(`Board snapshot fetch timed out after ${deadlineMs}ms`))
+        }, deadlineMs)
+        deps.fetchSnapshot(targetId, controller.signal).then(resolve, reject)
+      })
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  async function fetchAndApply(targetId: string): Promise<void> {
+    const start = ++starts
+    const baselines = deps.captureBaselines()
+    const snapshot = await fetchSnapshot(targetId)
+    // The active board switched while this fetch was in flight: its snapshot describes a board
+    // nothing is showing, so applying it would replace the new board's state with the old one's.
+    if (deps.currentWorkspaceId() !== targetId) return
+    deps.apply(snapshot, baselines)
+    lastHydratedStart = start
+  }
+
+  function refresh(): Promise<void> {
+    const targetId = deps.currentWorkspaceId()
+    if (!targetId) return Promise.resolve()
+    if (!inFlight) {
+      inFlight = fetchAndApply(targetId).finally(() => {
+        inFlight = null
+      })
+      return inFlight
+    }
+    if (queued?.targetId === targetId) return queued.promise
+    // A fetch is already running and may predate this caller's write, so hand back a follow-up
+    // that starts after it rather than its result. One follow-up serves every caller that arrives
+    // during this fetch asking about the same board. `settle` swallows only the ORDERING dependency
+    // on the current attempt: the failure itself already reached that attempt's own caller, and
+    // this caller gets the outcome of the fresh fetch below.
+    const promise = inFlight.then(settle, settle).then(() => {
+      if (queued?.promise === promise) queued = null
+      // The board switched while this follow-up waited. Fetching now would read the CURRENT
+      // board's snapshot on behalf of a caller that asked about the old one, hydrate it beside
+      // the switch's own hydrate, and resolve as though the board it asked about had refreshed.
+      if (deps.currentWorkspaceId() !== targetId) return
+      return refresh()
+    })
+    queued = { targetId, promise }
+    return promise
+  }
+
+  return {
+    refresh,
+    refreshMark: () => starts,
+    hydratedSince: (mark) => lastHydratedStart > mark,
+  }
+}
+
+/** Resolve regardless of how the awaited attempt ended: this chain sequences, it does not report. */
+function settle(): void {}