@cat-factory/app 0.283.0 → 0.285.0

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 }
+}

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')
+  })
+})