@cat-factory/app 0.277.0 → 0.277.2

package/README.md

@@ -248,6 +248,19 @@ works in (`not_started`, `in_progress`, `needs_you`) plus a collapsed **Done** s
 The vocabulary, the classification and the Done caps are `app/utils/swimlanes.ts`; the ordering and
 grouping are `app/utils/laneSort.ts`; `composables/useFrameLanes.ts` is the only store-facing half.
 
+`useFrameLanes` runs ONE INSTANCE PER MOUNTED FRAME and any execution event invalidates all of them,
+so what it derives is a performance decision as much as a modelling one. Two rules hold that line: a
+derivation over WORKSPACE-wide state belongs on the store that owns its input, never here (the
+review-debt map is `notifications.reviewDebtByBlock` for exactly this reason), and the assembled
+output passes through `utils/laneIdentity.ts`, which hands back the previous lane / group / entry
+objects wherever the fresh ones match, so the common event that moves no card leaves `TaskLane` and
+`LaneGroup` diffing on `===`. That reuse is sound only while every DERIVED field is compared (those
+exist nowhere but the entry, so a stale one is a lie nothing corrects), which is why a new
+`LaneTaskEntry` field must be added to `sameEntry` in the same change. The `task` itself is compared
+by reference and deliberately not field by field: a replaced block is a new reference, and an
+in-place patch (`board/placement.ts`, the optimistic drag and field edits) is one object both entries
+share, which the renderer reads through and deep reactivity invalidates on its own.
+
 **A lane is a CLAIM, which is a higher bar than a badge.** A mislabelled badge sits beside the
 truth; a card filed in the wrong lane states something false _and_ hides the card from the column
 its reader was scanning. Three rules follow, and they are what the tests pin:
@@ -942,16 +955,30 @@ event left to restore it.
   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
-  refresh path.
+- **Full refreshes go through the ONE funnel, which is what makes them monotonic.**
+  `workspace.refresh()` IS the funnel (`stores/workspace/refreshFunnel.ts`), so the ~35 direct
+  post-mutation call sites need no opt-in and a new one inherits it. It SERIALIZES: at most one
+  snapshot fetch is outstanding, so two cannot resolve out of order and no sequence stamp is
+  needed. It is deliberately not plain single-flight: a caller arriving mid-fetch joins a single
+  QUEUED follow-up rather than the in-flight request, because a caller that mutated and then
+  refreshed is entitled to a snapshot read AFTER its call. Do not reintroduce an unguarded
+  `hydrate(await fetch())`, and never add a second refresh path beside the funnel.
+- **Serializing makes one stalled request everyone's problem, so the slot is BOUNDED.** The API
+  client sets no timeout, and a hung fetch behind a shared slot stops every later refresh, the
+  coarse-event resync and the retry chain at once. The funnel puts a deadline on its own read and
+  ABORTS it, so a dead connection surfaces as an ordinary failure rather than a wedge; a snapshot
+  arriving after the deadline is never applied. Anything else that serializes work behind one slot
+  owes the same bound. The same argument is why a dedupe must QUEUE the later ask rather than drop it
+  (`environmentTest.reconcileRun`): the outstanding read may predate the state the later ask exists
+  to observe.
 - **Never gate readiness on a snapshot a later resync can undo.** The on-connect resync flips
-  `connected` only after it settles (which is why e2e gates on `data-connected`).
+  `connected` only after it settles (which is why e2e gates on `data-connected`). A resync that
+  stands down because a NEWER one started must hand its caller that newer one, not resolve: a
+  stand-down is not a reconcile, and `socket.onopen` cannot tell the difference.
 - **A REPLACE-style `hydrate` must never silently drop live-only state.** Either fold that state
-  into the snapshot or reconcile rather than replace. The `refreshSeq` guard above orders
-  refreshes against each OTHER and does nothing when ONE slow fetch straddles a live event, so
-  every such store also takes a WATERMARK: `refresh()` captures each one's `hydrateBaseline()`
+  into the snapshot or reconcile rather than replace. The funnel above orders refreshes against
+  each OTHER and does nothing when ONE slow fetch straddles a live event, so every such store also
+  takes a WATERMARK: `refresh()` captures each one's `hydrateBaseline()`
   before the fetch (`LiveWriteBaselines`) and its `hydrate` keeps whatever was written after it.
   `board` and `notifications` are the two today; `execution` gets the same protection from the
   server `rev` it carries. Whether the store can re-derive the dropped state is what decides how
@@ -969,9 +996,18 @@ event left to restore it.
   "thinking…" bubble spinning). Every echo therefore goes through
   `execution.echoAfter(executionId, send, apply)`, which captures the run's `rev` before the
   request and drops the echo if anything advanced it. Never hand-roll the await-then-assign.
+- **The coarse-event debounce is capped, and it checks coverage before firing.**
+  (`composables/workspaceStream/coarseRefresh.ts`, which owns both ways a full resync is asked for:
+  the on-connect reconcile and the `board`-event fan-out.) Trailing-only
+  re-armed forever under a sustained sub-300ms event stream, so the board stopped resyncing exactly
+  when the workspace was busiest; there is now a max-wait. Before fetching it asks the funnel
+  whether a snapshot issued after the latest coarse event has already hydrated
+  (`refreshMark()` / `hydratedSince()`) and stands down if so, which is what stops a mutation that
+  refreshes directly AND raises a coarse event from paying for two snapshots. That skip rests on
+  the server emitting a coarse `board` event only after committing what it announces.
 - **Pin it with a store-level unit test** (`stores/workspace.spec.ts` for refreshes,
-  `stores/execution.spec.ts` for echoes): drive the two orderings and assert the fresher one
-  wins.
+  `stores/workspace/refreshFunnel.spec.ts` for the funnel's own rules, `stores/execution.spec.ts`
+  for echoes): drive the two orderings and assert the fresher one wins.
 
 ## Internationalization (i18n) authoring
 

package/app/components/board/nodes/TaskCard.vue

@@ -232,9 +232,10 @@ async function merge() {
 // separately by the AgentFailureCard above). The board previously only handled
 // decisions, so an approval-gated task was a dead end: it read "Decision needed"
 // (the old generic `blocked` label) with no badge and a click that did nothing.
-const pendingDecision = computed(() =>
-  execution.openDecisions.find((d) => d.blockId === props.taskId),
-)
+// Read off the per-block index rather than scanning the workspace-wide list: this computed is
+// mounted once per card and invalidated by every execution event, so a `find` over `openDecisions`
+// cost O(cards x open gates) per event. `decisionsByBlock` is the index built for exactly this.
+const pendingDecision = computed(() => execution.decisionsByBlock.get(props.taskId)?.[0])
 // The async stage an iterative reviewer gate (requirements-review / clarity-review) is
 // mid-cycle in (folding the answers, then re-reviewing), or null. While set, the gate
 // needs NO human action, so its approval is suppressed below and a working indicator
@@ -250,7 +251,7 @@ const reviewStageLabel = computed(() =>
         : null,
 )
 const pendingApproval = computed(() => {
-  const a = execution.openApprovals.find((a) => a.blockId === props.taskId)
+  const a = execution.approvalsByBlock.get(props.taskId)?.[0]
   // A reviewer gate whose review is incorporating / re-reviewing in the driver is doing
   // background work, not awaiting a human — don't surface it as "Approval needed".
   if (a && reviews.isBackground(a.agentKind, props.taskId)) return undefined

package/app/components/board/nodes/TaskLane.vue

@@ -1,8 +1,7 @@
 <script setup lang="ts">
 import LaneGroup from './LaneGroup.vue'
-import type { RenderedLane } from '~/composables/useFrameLanes'
 import { LANE_GEOMETRY } from '~/utils/laneGeometry'
-import type { LaneGroupKey } from '~/utils/laneSort'
+import type { LaneGroupKey, RenderedLane } from '~/utils/laneSort'
 import { LANE_META } from '~/utils/swimlanes'
 
 /**

package/app/composables/api/workspaces.ts

@@ -29,8 +29,10 @@ export function workspacesApi({ send, ws }: ApiContext) {
       body: { name?: string; description?: string; seed?: boolean; accountId?: string } = {},
     ) => send(createWorkspaceContract, { body }),
 
-    getWorkspace: (workspaceId: string) =>
-      send(getWorkspaceContract, { pathParams: { workspaceId } }),
+    // `signal` is what lets the refresh funnel put a deadline on the app's heaviest read: it holds
+    // one slot for every refresh in the SPA, and the client sets no timeout of its own.
+    getWorkspace: (workspaceId: string, signal?: AbortSignal) =>
+      send(getWorkspaceContract, { pathParams: { workspaceId }, signal }),
 
     updateWorkspace: (workspaceId: string, body: { name?: string; description?: string | null }) =>
       send(updateWorkspaceContract, { pathParams: { workspaceId }, body }),

package/app/composables/useFrameLanes.ts

@@ -1,13 +1,13 @@
 import { computed, type Ref } from 'vue'
-import { collectReviewDebt } from '@cat-factory/contracts'
 import type { Block } from '~/types/domain'
+import { createLaneMemo } from '~/utils/laneIdentity'
 import {
   groupLaneTasks,
   runActivityAt,
   runWaitingSince,
   sortLaneTasks,
-  type LaneGroup,
   type LaneTaskEntry,
+  type RenderedLane,
 } from '~/utils/laneSort'
 import {
   classifyTask,
@@ -17,14 +17,6 @@ import {
   type TaskLane,
 } from '~/utils/swimlanes'
 
-/** One rendered lane: its identity, its groups, and the count its header states. */
-export interface RenderedLane {
-  readonly lane: TaskLane
-  readonly groups: LaneGroup[]
-  /** Every task classified into this lane, BEFORE the Done lane's caps. */
-  readonly total: number
-}
-
 /** A lane entry plus the lane it was classified into. */
 interface ClassifiedEntry {
   readonly entry: LaneTaskEntry
@@ -57,16 +49,6 @@ export function useFrameLanes(frameId: Ref<string>) {
     () => new Map(board.modulesOf(frameId.value).map((m) => [m.title, m.id])),
   )
 
-  /**
-   * Per-block "waiting since", derived once from the workspace's 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`; deriving it once rather than per task is
-   * what keeps this assembly linear.
-   */
-  const waitingSinceByBlock = computed(
-    () => new Map(collectReviewDebt(notifications.open).map((d) => [d.blockId, d.waitingSince])),
-  )
-
   /**
    * The module a task belongs to: the module BLOCK's title when it already lives in one, else
    * the module it DECLARES. The engine only materialises the block on merge
@@ -79,6 +61,17 @@ export function useFrameLanes(frameId: Ref<string>) {
     return task.moduleName?.trim() || null
   }
 
+  /**
+   * One task's lane, reason and rendered entry.
+   *
+   * Every cross-block lookup here is a Map read off an index a STORE maintains, never a reduction
+   * of its own: this composable runs ONE INSTANCE PER MOUNTED FRAME, so deriving a workspace-wide
+   * fact here makes a board with n frames pay for it n times on every change. The review-debt map
+   * (`notifications.reviewDebtByBlock`) is the worked example: a reduction over the whole
+   * workspace's open notifications, and it belongs on the store that owns its input. The rule for
+   * anything else this assembly needs: a per-FRAME derivation belongs here, a workspace-wide one
+   * belongs on that store.
+   */
   function classify(task: Block, order: number): ClassifiedEntry {
     const run = execution.getByBlock(task.id) ?? null
     const decisions = execution.decisionsByBlock.get(task.id) ?? []
@@ -111,7 +104,7 @@ export function useFrameLanes(frameId: Ref<string>) {
         reason,
         order,
         activityAt: runActivityAt(run),
-        waitingSince: runWaitingSince(run, waitingSinceByBlock.value.get(task.id) ?? null),
+        waitingSince: runWaitingSince(run, notifications.reviewDebtByBlock.get(task.id) ?? null),
         moduleName: moduleNameOf(task),
         initiativeName: task.initiativeId
           ? (board.getBlock(task.initiativeId)?.title ?? null)
@@ -153,18 +146,28 @@ export function useFrameLanes(frameId: Ref<string>) {
     ),
   )
 
+  /**
+   * Identity preservation for the assembled output, so an event that changed nothing in a lane
+   * hands `TaskLane`/`LaneGroup` the SAME objects it had and their diffs short-circuit on `===`.
+   * Every execution event invalidates this whole chain for every mounted frame, and most of them
+   * (a subtask tick, a progress fold) move no card at all. See `utils/laneIdentity.ts`.
+   */
+  const shareLanes = createLaneMemo()
+
   const lanes = computed<RenderedLane[]>(() =>
-    TASK_LANES.map((lane) => {
-      const bucket = byLane.value.get(lane) ?? []
-      // Only the Done lane is capped; every other lane renders everything in it.
-      const visible = lane === 'done' ? admittedByCaps(bucket, doneSelection.value) : bucket
-      const ordered = sortLaneTasks(visible, laneView.sortKey, lane)
-      return {
-        lane,
-        groups: groupLaneTasks(ordered, laneView.groupKey, moduleBlockIdByName.value),
-        total: bucket.length,
-      }
-    }),
+    shareLanes(
+      TASK_LANES.map((lane) => {
+        const bucket = byLane.value.get(lane) ?? []
+        // Only the Done lane is capped; every other lane renders everything in it.
+        const visible = lane === 'done' ? admittedByCaps(bucket, doneSelection.value) : bucket
+        const ordered = sortLaneTasks(visible, laneView.sortKey, lane)
+        return {
+          lane,
+          groups: groupLaneTasks(ordered, laneView.groupKey, moduleBlockIdByName.value),
+          total: bucket.length,
+        }
+      }),
+    ),
   )
 
   return { lanes, doneSelection }

package/app/composables/useWorkspaceStream.ts

@@ -5,6 +5,7 @@ import {
   applyWorkspaceEvent,
   type WorkspaceEventTargets,
 } from '~/composables/workspaceStream/applyWorkspaceEvent'
+import { createCoarseRefresh } from '~/composables/workspaceStream/coarseRefresh'
 
 /**
  * Subscribes to the backend's per-workspace WebSocket event stream and keeps the
@@ -53,37 +54,22 @@ export function useWorkspaceStream() {
   let stopped = false
   let attempt = 0
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null
-  let boardDebounce: ReturnType<typeof setTimeout> | null = null
 
   // http→ws, https→wss. `apiBase` is an absolute origin on a split-origin deployment (see
   // nuxt.config.ts) and EMPTY on a same-origin one (one proxy in front of the SPA + the API —
   // the compose preview stack), where the socket origin comes from the page instead.
   const wsBase = wsOriginFor(String(apiBase), import.meta.client ? window.location.origin : '')
 
-  // A coarse board refresh (the resync on reconnect, and the `board` event fan-out) must not be
-  // left silently stale by ONE transient failure: retry a few times with backoff so a blip
-  // self-heals. Bounded (the socket-level reconnect + the offline banner are the backstop for a
-  // genuine outage). Aborts between attempts if the stream stopped or the workspace switched.
-  const REFRESH_MAX_ATTEMPTS = 4
-  const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms))
-  async function refreshWithRetry(workspaceId: string): Promise<void> {
-    for (let i = 0; i < REFRESH_MAX_ATTEMPTS; i++) {
-      if (stopped || workspace.workspaceId !== workspaceId) return
-      try {
-        await workspace.refresh()
-        return
-      } catch {
-        if (i < REFRESH_MAX_ATTEMPTS - 1) await sleep(Math.min(4_000, 400 * 2 ** i))
-      }
-    }
-  }
-
-  function debouncedBoardRefresh() {
-    const workspaceId = workspace.workspaceId
-    if (!workspaceId) return
-    if (boardDebounce) clearTimeout(boardDebounce)
-    boardDebounce = setTimeout(() => void refreshWithRetry(workspaceId), 300)
-  }
+  // How a full resync is scheduled and driven (the retry chain, the capped debounce and its
+  // coverage check), extracted into a cohesive collaborator over bound callbacks so those rules are
+  // testable without a socket. This file keeps the socket lifecycle and the event routing.
+  const coarse = createCoarseRefresh({
+    stopped: () => stopped,
+    currentWorkspaceId: () => workspace.workspaceId,
+    refresh: () => workspace.refresh(),
+    refreshMark: () => workspace.refreshMark(),
+    hydratedSince: (mark) => workspace.hydratedSince(mark),
+  })
 
   // 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.
@@ -103,7 +89,7 @@ export function useWorkspaceStream() {
     upsertKaizen: (g) => kaizen.upsert(g),
     upsertInitiative: (i) => initiatives.upsert(i),
     upsertDocInterview: (s) => docInterview.upsert(s),
-    refreshBoard: () => debouncedBoardRefresh(),
+    refreshBoard: () => coarse.schedule(),
   }
 
   function onMessage(raw: string) {
@@ -159,10 +145,10 @@ export function useWorkspaceStream() {
       // it. Anything acting on a `connected` board (a user, or an e2e spec gating on
       // `data-connected`) then does so only after this reconcile, so a lagging resync
       // can't drop the state that action produces. The resync RETRIES on a transient
-      // failure (`refreshWithRetry`) so a reconnect no longer presents as fully live while
+      // failure (`coarse.withRetry`) so a reconnect no longer presents as fully live while
       // silently missing everything from the outage; `connected` is still set even if every
       // retry fails (we ARE connected; a refresh error must not wedge the indicator/tests).
-      void refreshWithRetry(workspaceId).finally(() => {
+      void coarse.withRetry(workspaceId).finally(() => {
         // A workspace switch (or stop()) may have happened while the refresh was in
         // flight — don't announce a connection for a socket we've since abandoned.
         if (!stopped && socket && workspace.workspaceId === workspaceId) {
@@ -206,7 +192,7 @@ export function useWorkspaceStream() {
   function stop() {
     stopped = true
     if (reconnectTimer) clearTimeout(reconnectTimer)
-    if (boardDebounce) clearTimeout(boardDebounce)
+    coarse.cancel()
     socket?.close()
     socket = null
     connected.value = false

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

@@ -0,0 +1,146 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { createCoarseRefresh } from '~/composables/workspaceStream/coarseRefresh'
+
+function harness() {
+  const pending: { resolve: () => void; reject: (e: Error) => void }[] = []
+  let workspaceId: string | null = 'ws1'
+  let stopped = false
+  let mark = 0
+  /** The mark a hydrated fetch was issued after, i.e. what `hydratedSince` answers against. */
+  let hydratedAfter: number | null = null
+
+  const coarse = createCoarseRefresh({
+    stopped: () => stopped,
+    currentWorkspaceId: () => workspaceId,
+    refresh: () => new Promise<void>((resolve, reject) => pending.push({ resolve, reject })),
+    refreshMark: () => mark,
+    hydratedSince: (m) => hydratedAfter !== null && hydratedAfter > m,
+  })
+
+  return {
+    coarse,
+    refreshes: () => pending.length,
+    settle: async (i = pending.length - 1) => {
+      pending[i]!.resolve()
+      await vi.advanceTimersByTimeAsync(0)
+    },
+    fail: async (i = pending.length - 1) => {
+      pending[i]!.reject(new Error('offline'))
+      await vi.advanceTimersByTimeAsync(0)
+    },
+    setWorkspaceId: (id: string | null) => {
+      workspaceId = id
+    },
+    stop: () => {
+      stopped = true
+    },
+    /** Pretend a direct `refresh()` call site already hydrated a snapshot issued just now. */
+    coverNow: () => {
+      mark += 1
+      hydratedAfter = mark
+    },
+  }
+}
+
+describe('coarse refresh', () => {
+  beforeEach(() => vi.useFakeTimers())
+  afterEach(() => vi.useRealTimers())
+
+  it('retries a transient failure with backoff', async () => {
+    const h = harness()
+    const done = h.coarse.withRetry('ws1')
+    expect(h.refreshes()).toBe(1)
+    await h.fail()
+    expect(h.refreshes()).toBe(1) // still in backoff
+    await vi.advanceTimersByTimeAsync(400)
+    expect(h.refreshes()).toBe(2)
+    await h.settle()
+    await done
+  })
+
+  it('stops retrying once the stream stopped or the board switched', async () => {
+    const h = harness()
+    const done = h.coarse.withRetry('ws1')
+    await h.fail()
+    h.setWorkspaceId('ws2')
+    await vi.advanceTimersByTimeAsync(400)
+    await done
+    expect(h.refreshes()).toBe(1)
+  })
+
+  /**
+   * The readiness rule. `socket.onopen` announces `connected` off this promise, so a chain that
+   * stands down for a NEWER one must hand its caller that newer chain: resolving on supersession
+   * would announce a board whose reconcile has not run, which is exactly what gating the
+   * announcement on the resync exists to prevent.
+   */
+  it('a superseded chain resolves only once the chain that replaced it has reconciled', async () => {
+    const h = harness()
+    let announced = false
+    const open = h.coarse.withRetry('ws1').then(() => {
+      announced = true
+    })
+    // The on-connect chain's first attempt fails, so it drops into backoff...
+    await h.fail()
+    // ...and a buffered coarse event starts a newer chain while it sleeps.
+    const newer = h.coarse.withRetry('ws1')
+    expect(h.refreshes()).toBe(2)
+
+    // The older chain wakes, sees it has been superseded and stops issuing fetches of its own.
+    await vi.advanceTimersByTimeAsync(400)
+    expect(h.refreshes()).toBe(2)
+    expect(announced).toBe(false)
+
+    await h.settle()
+    await Promise.all([open, newer])
+    expect(announced).toBe(true)
+  })
+
+  describe('debounce', () => {
+    it('collapses a burst of coarse events into one refresh', async () => {
+      const h = harness()
+      h.coarse.schedule()
+      h.coarse.schedule()
+      h.coarse.schedule()
+      await vi.advanceTimersByTimeAsync(300)
+      expect(h.refreshes()).toBe(1)
+    })
+
+    /**
+     * `cancel()` must clear the window, not just the timer. The window start is read whenever a
+     * window is already open, so a handle left behind here lets the first event of the NEXT session
+     * inherit a start whose max-wait expired long ago and fire an undebounced full snapshot fetch.
+     */
+    it('debounces the first event after a cancel instead of firing immediately', async () => {
+      const h = harness()
+      h.coarse.schedule()
+      h.coarse.cancel()
+      // Long enough that the cancelled window's max-wait would have elapsed.
+      await vi.advanceTimersByTimeAsync(3_000)
+      expect(h.refreshes()).toBe(0)
+
+      h.coarse.schedule()
+      await vi.advanceTimersByTimeAsync(0)
+      expect(h.refreshes()).toBe(0)
+      await vi.advanceTimersByTimeAsync(300)
+      expect(h.refreshes()).toBe(1)
+    })
+
+    it('fires within the max wait under a sustained event stream', async () => {
+      const h = harness()
+      for (let i = 0; i < 12; i++) {
+        h.coarse.schedule()
+        await vi.advanceTimersByTimeAsync(200)
+      }
+      expect(h.refreshes()).toBeGreaterThan(0)
+    })
+
+    it('stands down when a snapshot issued after the event has already hydrated', async () => {
+      const h = harness()
+      h.coarse.schedule()
+      h.coverNow()
+      await vi.advanceTimersByTimeAsync(300)
+      expect(h.refreshes()).toBe(0)
+    })
+  })
+})

package/app/composables/workspaceStream/coarseRefresh.ts

@@ -0,0 +1,121 @@
+/**
+ * How the stream asks for a FULL resync: the on-(re)connect reconcile and the coarse `board`
+ * event's debounced fan-out, which are the same operation reached two ways.
+ *
+ * Extracted from `useWorkspaceStream` (which keeps the socket lifecycle and the event routing) so
+ * the scheduling rules below are unit-testable without a WebSocket. Every dependency is a bound
+ * callback, so nothing here reaches for a store.
+ */
+export interface CoarseRefreshDeps {
+  /** True once the stream has stopped: a scheduled pass stands down rather than firing. */
+  readonly stopped: () => boolean
+  /** The board the stream is bound to right now, or null before bootstrap. */
+  readonly currentWorkspaceId: () => string | null
+  /** `workspace.refresh()`: the one funnel every full-snapshot refresh goes through. */
+  readonly refresh: () => Promise<void>
+  /** The funnel's coverage mark, taken when a coarse event arrives. */
+  readonly refreshMark: () => number
+  /** Whether a snapshot fetch issued after `mark` has already hydrated. */
+  readonly hydratedSince: (mark: number) => boolean
+}
+
+export interface CoarseRefresh {
+  /**
+   * Reconcile the board now, retrying a transient failure. Resolves once the board HAS been
+   * reconciled, or once the attempts are spent; a caller may treat that as "safe to announce".
+   */
+  readonly withRetry: (workspaceId: string) => Promise<void>
+  /** Schedule a debounced coarse resync (the `board`-event fan-out). */
+  readonly schedule: () => void
+  /** Drop any pending pass. */
+  readonly cancel: () => void
+}
+
+// A coarse board refresh (the resync on reconnect, and the `board` event fan-out) must not be
+// left silently stale by ONE transient failure: retry a few times with backoff so a blip
+// self-heals. Bounded (the socket-level reconnect + the offline banner are the backstop for a
+// genuine outage). Aborts between attempts if the stream stopped or the workspace switched.
+const REFRESH_MAX_ATTEMPTS = 4
+
+// The coarse-event debounce. Trailing, so a burst of `board` events costs one refresh, and
+// CAPPED, because trailing alone re-armed the timer forever under a sustained sub-300ms stream:
+// the board stopped resyncing exactly when the workspace was busiest. Past the cap the pending
+// refresh fires on schedule and the next event starts a fresh window.
+const BOARD_DEBOUNCE_MS = 300
+const BOARD_DEBOUNCE_MAX_WAIT_MS = 2_000
+
+export function createCoarseRefresh(deps: CoarseRefreshDeps): CoarseRefresh {
+  const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms))
+
+  // A chain stands down when a NEWER one has started: the backoff sleeps run for seconds, so a
+  // sustained event stream used to leave several chains alive at once, each still issuing full
+  // snapshot fetches for a resync a later chain had already superseded.
+  //
+  // Standing down HANDS THE CALLER THE NEWER CHAIN rather than resolving, because the socket's
+  // `onopen` announces `connected` off this promise: resolving on supersession would announce a
+  // board whose reconcile is still in flight, which is the stale-readiness bug the
+  // resync-before-announce ordering exists to prevent. A stood-down chain always awaits a STRICTLY
+  // newer one, so the wait terminates at whichever chain is newest.
+  let chainCount = 0
+  let newest: Promise<void> = Promise.resolve()
+
+  function withRetry(workspaceId: string): Promise<void> {
+    const chain = ++chainCount
+    const run = drive(workspaceId, chain)
+    newest = run
+    return run
+  }
+
+  async function drive(workspaceId: string, chain: number): Promise<void> {
+    for (let i = 0; i < REFRESH_MAX_ATTEMPTS; i++) {
+      if (deps.stopped() || deps.currentWorkspaceId() !== workspaceId) return
+      if (chain !== chainCount) return newest
+      try {
+        await deps.refresh()
+        return
+      } catch {
+        if (i < REFRESH_MAX_ATTEMPTS - 1) await sleep(Math.min(4_000, 400 * 2 ** i))
+      }
+    }
+  }
+
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let windowStart = 0
+  // The funnel's coverage mark as of the LATEST coarse event in this window. A snapshot fetch
+  // issued after that event necessarily contains what the event announced (the server emits it
+  // after committing), so if one has already hydrated by the time the timer fires there is nothing
+  // left to resync. This is what stops a mutation that refreshes directly AND raises a coarse
+  // event from paying for two full snapshots.
+  let coverageMark = 0
+
+  function schedule() {
+    const workspaceId = deps.currentWorkspaceId()
+    if (!workspaceId) return
+    const now = Date.now()
+    coverageMark = deps.refreshMark()
+    if (timer) clearTimeout(timer)
+    else windowStart = now
+    const wait = Math.max(
+      0,
+      Math.min(BOARD_DEBOUNCE_MS, windowStart + BOARD_DEBOUNCE_MAX_WAIT_MS - now),
+    )
+    timer = setTimeout(() => {
+      timer = null
+      if (deps.hydratedSince(coverageMark)) return
+      void withRetry(workspaceId)
+    }, wait)
+  }
+
+  /**
+   * `timer` is NULLED, not just cleared: it is what says "a window is open", so a stale handle left
+   * behind here would make the first event of the next session inherit the previous session's
+   * window start, whose max-wait has long since expired, and fire a full snapshot fetch immediately
+   * with no debounce at all.
+   */
+  function cancel() {
+    if (timer) clearTimeout(timer)
+    timer = null
+  }
+
+  return { withRetry, schedule, cancel }
+}

package/app/stores/environmentTest.spec.ts

@@ -77,6 +77,39 @@ describe('environmentTest store — monotonic run reconcile', () => {
     expect(store.runForBlock('blk_r1')!.status).toBe('failed')
   })
 
+  /**
+   * Overlapping refreshes preserve the same still-running run, so the point-read is deduped. It
+   * must be deduped with a QUEUED FOLLOW-UP rather than dropped: the outstanding read may have been
+   * issued before the run reached terminal, and it is the later ask that would observe the outcome.
+   * Nothing asks a third time (terminal runs emit no event and the snapshot omits them), so a
+   * dropped ask leaves the inspector on "testing" for the rest of the session.
+   */
+  it('re-reads once when a hydrate asks again while a point-read is still out', async () => {
+    store.upsert(run('r1', { status: 'running', updatedAt: 5 }))
+    let releaseFirst!: () => void
+    const held = new Promise<void>((r) => (releaseFirst = r))
+    apiMock.getEnvironmentTest = vi
+      .fn()
+      // Issued before the run reached terminal, so it can only ever answer `running`.
+      .mockImplementationOnce(async () => {
+        await held
+        return run('r1', { status: 'running', updatedAt: 6 })
+      })
+      // The queued follow-up: the read that picks up the outcome.
+      .mockImplementationOnce(async () =>
+        run('r1', { status: 'succeeded', stage: 'done', updatedAt: 9 }),
+      )
+
+    store.hydrate([], 'ws_test')
+    store.hydrate([], 'ws_test')
+    // Deduped while the first read is out: the second hydrate did not issue its own.
+    expect(apiMock.getEnvironmentTest).toHaveBeenCalledTimes(1)
+
+    releaseFirst()
+    await vi.waitFor(() => expect(store.runForBlock('blk_r1')!.status).toBe('succeeded'))
+    expect(apiMock.getEnvironmentTest).toHaveBeenCalledTimes(2)
+  })
+
   it('hydrate DROPS a cached run from a different workspace (board switch starts clean)', () => {
     store.upsert(run('r1', { status: 'failed', updatedAt: 5, workspaceId: 'ws_other' }))
     store.hydrate([run('r2', { workspaceId: 'ws_test' })], 'ws_test')