@cat-factory/app 0.241.0 → 0.241.1

package/README.md

@@ -618,7 +618,17 @@ event left to restore it.
 - **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`).
 - **A REPLACE-style `hydrate` must never silently drop live-only state.** Either fold that state
-  into the snapshot or reconcile rather than replace.
+  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()`
+  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
+  bad the bug is: a block's status arrives again on the run's next transition, while a
+  notification is pushed ONCE, so dropping the card leaves a parked run nothing can surface (the
+  `pr-review` spec's flaky 30s wait on `notifications-bell`). A watermark that tracks only
+  INSERTS is half a guard: a card resolved live must also stay gone, or a snapshot read while it
+  was open resurrects an action the server has already taken.
 - **An action's OPTIMISTIC ECHO is a clobber too, and it bypasses both guards above.** A store
   that awaits a mutation and then assigns the returned sub-state onto the cached run
   (`step.forkDecision`, `step.prReview`, `step.judge`, `step.followUps`) is writing straight past

package/app/stores/notifications.ts

@@ -22,11 +22,42 @@ export const useNotificationsStore = defineStore('notifications', () => {
     remove,
   } = useUpsertList<Notification>({ key: (n) => n.id, prepend: true })
 
-  /** Replace the cache from a server snapshot. */
-  function hydrate(notifications: Notification[]) {
-    open.value = [...notifications]
-      .filter((n) => n.status === 'open')
-      .sort((a, b) => b.createdAt - a.createdAt)
+  // Client-side monotonic guard against a stale full-snapshot `hydrate` CLOBBERING newer live
+  // state — the same hazard `useBoardStore` guards, on the delivery shape that has no second
+  // chance. A run raises its card as a targeted `notification` event; a full `refresh()` whose
+  // snapshot was READ before that card existed can resolve AFTER it, and a plain replace then
+  // drops the card with NO further event to restore it, so the inbox bell never appears (the
+  // pr-review e2e flake). Notifications carry no server revision, so each live write is stamped
+  // with a monotonic sequence and a refresh that captured its baseline BEFORE the fetch keeps
+  // every write newer than that baseline. It cuts both ways: a live-ADDED card the snapshot
+  // cannot know about is re-inserted, and a live-RESOLVED one the snapshot still calls open
+  // stays gone.
+  let liveSeq = 0
+  /** Last live write per id: the notification to keep, or `null` once it was resolved. */
+  const liveWrites = new Map<string, { seq: number; value: Notification | null }>()
+
+  /**
+   * Baseline for {@link hydrate}: capture this BEFORE a refresh's snapshot fetch and pass it
+   * back in, so a notification written live while the fetch was in flight survives the hydrate.
+   * Callers that don't pass a baseline get a plain full replace (initial load / board switch —
+   * no live-write race to guard).
+   */
+  function hydrateBaseline(): number {
+    return liveSeq
+  }
+
+  /** Replace the cache from a server snapshot, keeping live writes newer than `since`. */
+  function hydrate(notifications: Notification[], since = liveSeq) {
+    const newer = new Map<string, Notification | null>()
+    for (const [id, write] of liveWrites) {
+      // A write the snapshot already reflects is reconciled and can be forgotten, so the map
+      // stays bounded by what is genuinely in flight rather than by the session's history.
+      if (write.seq > since) newer.set(id, write.value)
+      else liveWrites.delete(id)
+    }
+    const merged = notifications.filter((n) => n.status === 'open' && !newer.has(n.id))
+    for (const value of newer.values()) if (value) merged.push(value)
+    open.value = merged.sort((a, b) => b.createdAt - a.createdAt)
   }
 
   /**
@@ -34,7 +65,9 @@ export const useNotificationsStore = defineStore('notifications', () => {
    * replaced in place; a resolved one (acted/dismissed) is removed from the inbox.
    */
   function upsert(notification: Notification) {
-    if (notification.status !== 'open') {
+    const isOpen = notification.status === 'open'
+    liveWrites.set(notification.id, { seq: ++liveSeq, value: isOpen ? notification : null })
+    if (!isOpen) {
       remove(notification.id)
       return
     }
@@ -76,5 +109,5 @@ export const useNotificationsStore = defineStore('notifications', () => {
     upsert(resolved)
   }
 
-  return { open, hydrate, upsert, byBlock, count, act, dismiss }
+  return { open, hydrate, hydrateBaseline, upsert, byBlock, count, act, dismiss }
 })

package/app/stores/workspace/commands.ts

@@ -13,7 +13,7 @@ export interface WorkspaceCommandContext {
   api: ReturnType<typeof useApi>
   workspaceId: Ref<string | null>
   workspaces: Ref<WorkspaceListItem[]>
-  hydrate: (snapshot: WorkspaceSnapshot, boardSince?: number) => void
+  hydrate: (snapshot: WorkspaceSnapshot) => void
   /** Open one of the active account's boards, creating one when it has none. */
   resolveActiveBoard: () => Promise<void>
 }

package/app/stores/workspace/hydrate.ts

@@ -49,23 +49,28 @@ export function resetPerBoardCaches() {
   useFragmentsStore().invalidate()
 }
 
+/**
+ * The live-write watermarks a refresh captured BEFORE its snapshot fetch, one per store whose
+ * `hydrate` REPLACES a list that live events also write to. Each store preserves whatever it
+ * was handed after its own baseline, so a slower refresh can't clobber newer live state (see
+ * `useBoardStore().hydrate` and `useNotificationsStore().hydrate`). Omitted by fresh loads
+ * (init / board switch / create), where there is no in-flight race to guard.
+ */
+export type LiveWriteBaselines = { board: number; notifications: number }
+
 /**
  * Fan a workspace snapshot out into the per-feature data stores. Extracted verbatim from the
  * `workspace` store's `hydrate` (which keeps the workspace-scoped state it owns + the
  * board-switch cache reset) so the ordering of the hydrate calls is preserved exactly — a
  * size-only split, not a new seam.
- *
- * `boardSince` (captured BEFORE this snapshot's fetch) lets the board store preserve any block
- * live-`upsert`ed while the fetch was in flight, so a slower refresh can't clobber a newer live
- * status (see `useBoardStore().hydrate`).
  */
-export function applySnapshotToStores(snapshot: WorkspaceSnapshot, boardSince?: number) {
+export function applySnapshotToStores(snapshot: WorkspaceSnapshot, baselines?: LiveWriteBaselines) {
   useUserSettingsStore().hydrate(snapshot.userSettings ?? null)
   // The signed-in user's tutorial progress MERGES rather than replaces (see the store): both id
   // lists are grow-only sets, so a snapshot must never un-say a walkthrough this browser finished
   // while the mirror write was failing. Absent ⇒ no server copy, and the local one stands.
   useTutorialStore().mergeServerProgress(snapshot.tutorialProgress ?? null)
-  useBoardStore().hydrate(snapshot.blocks, boardSince)
+  useBoardStore().hydrate(snapshot.blocks, baselines?.board)
   useBoardStore().hydrateArchived(snapshot.archivedServices ?? [])
   usePipelinesStore().hydrate(
     snapshot.pipelines,
@@ -77,7 +82,7 @@ export function applySnapshotToStores(snapshot: WorkspaceSnapshot, boardSince?:
   useAgentRunsStore().hydrate(snapshot.bootstrapJobs ?? [], snapshot.workspace.id)
   useAgentRunsStore().hydrateEnvConfigRepair(snapshot.envConfigRepairJobs ?? [])
   useEnvironmentTestStore().hydrate(snapshot.environmentTestRuns ?? [], snapshot.workspace.id)
-  useNotificationsStore().hydrate(snapshot.notifications ?? [])
+  useNotificationsStore().hydrate(snapshot.notifications ?? [], baselines?.notifications)
   useRiskPoliciesStore().hydrate(snapshot.riskPolicies ?? [], snapshot.riskPolicyCatalogVersions)
   useSharedStacksStore().hydrate(snapshot.sharedStacks ?? [])
   useWorkspaceSettingsStore().hydrate(snapshot.settings)

package/app/stores/workspace.spec.ts

@@ -1,11 +1,14 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
-import type { Block, WorkspaceSnapshot } from '~/types/domain'
+import type { Block, Notification, WorkspaceSnapshot } from '~/types/domain'
 import { useBoardStore } from '~/stores/board'
+import { useNotificationsStore } from '~/stores/notifications'
 import { useWorkspaceStore } from '~/stores/workspace'
 
 // The workspace store's `hydrate` fans out to ~20 sibling stores via Nuxt auto-imports, which
 // aren't defined under plain vitest. Stub every one INERT (a proxy whose every method is a no-op)
-// EXCEPT the board store, which we keep real so the block list a refresh commits is observable.
+// EXCEPT the two stores whose live-write guards these tests drive: the board store (kept real via
+// the stub below) and the notifications store (imported by name in `workspace/hydrate.ts`, so it
+// is real already and must NOT be listed here).
 const INERT_STORES = [
   'useAccountsStore',
   'useAgentConfigStore',
@@ -22,7 +25,6 @@ const INERT_STORES = [
   'useInitiativesStore',
   'useRiskPoliciesStore',
   'useModelPresetsStore',
-  'useNotificationsStore',
   'usePipelinesStore',
   'useProviderConnectionsStore',
   'useRecurringPipelinesStore',
@@ -68,13 +70,34 @@ function block(id: string, over: Partial<Block> = {}): Block {
   }
 }
 
+/** Minimal open inbox card — only the fields the notifications store reads. */
+function notification(id: string, over: Partial<Notification> = {}): Notification {
+  return {
+    id,
+    type: 'pr_review_ready',
+    status: 'open',
+    blockId: 't1',
+    executionId: null,
+    title: id,
+    body: '',
+    createdAt: 1,
+    resolvedAt: null,
+    ...over,
+  }
+}
+
 /** Minimal snapshot — the arrays a bare hydrate iterates; everything else defaults. */
-function snapshot(id: string, blocks: Block[]): WorkspaceSnapshot {
+function snapshot(
+  id: string,
+  blocks: Block[],
+  notifications: Notification[] = [],
+): WorkspaceSnapshot {
   return {
     workspace: { id, name: id, accountId: null },
     blocks,
     pipelines: [],
     executions: [],
+    notifications,
   } as unknown as WorkspaceSnapshot
 }
 
@@ -149,6 +172,70 @@ describe('workspace store refresh ordering', () => {
     // The live terminal status survives — the stale refresh did NOT clobber it back.
     expect(board.getBlock('t1')?.status).toBe('done')
   })
+
+  // The same interleaved-live-write axis on the delivery shape with NO second chance. A parked
+  // run raises its inbox card as a targeted `notification` event and never re-sends it, while the
+  // park ALSO fans out coarse `board` events whose debounced refresh is routinely in flight at
+  // that moment. A snapshot READ before the card existed used to replace the whole inbox and drop
+  // it, so the bell never appeared and nothing could bring it back — the `pr-review` e2e spec's
+  // 30s timeout on `notifications-bell`. The notifications store now stamps each live write and
+  // `refresh()` captures its baseline beside the board's.
+  it('a refresh started before a live notification does not drop the raised card', async () => {
+    const frame = block('f1')
+    let resolveRefresh!: (s: WorkspaceSnapshot) => void
+    const getWorkspace = vi
+      .fn()
+      // 1) switchTo — nothing in the inbox yet.
+      .mockResolvedValueOnce(snapshot('ws1', [frame]))
+      // 2) a refresh whose fetch is in flight while the run parks and raises its card.
+      .mockReturnValueOnce(new Promise<WorkspaceSnapshot>((r) => (resolveRefresh = r)))
+    vi.stubGlobal('useApi', () => ({ getWorkspace }))
+
+    const ws = useWorkspaceStore()
+    const notifications = useNotificationsStore()
+    await ws.switchTo('ws1')
+
+    // A refresh starts (captures the notifications baseline; its snapshot has an empty inbox).
+    const pass = ws.refresh()
+    // The run parks mid-fetch and pushes its card.
+    notifications.upsert(notification('n1'))
+    expect(notifications.count).toBe(1)
+    // The now-stale refresh resolves, still carrying the empty inbox it read.
+    resolveRefresh(snapshot('ws1', [frame]))
+    await pass
+
+    // The card survives: it is the only delivery there will ever be.
+    expect(notifications.count).toBe(1)
+  })
+
+  // The mirror image, and the reason the guard tracks REMOVALS too: a card resolved live (acted
+  // on in another tab, or cleared by the engine) must not be resurrected by a snapshot that was
+  // read while it was still open — a resurrected card offers an action the server has already
+  // taken.
+  it('a refresh started before a live resolve does not resurrect the card', async () => {
+    const frame = block('f1')
+    let resolveRefresh!: (s: WorkspaceSnapshot) => void
+    const getWorkspace = vi
+      .fn()
+      // 1) switchTo — the card is open.
+      .mockResolvedValueOnce(snapshot('ws1', [frame], [notification('n1')]))
+      // 2) a refresh whose fetch is in flight while the card is resolved elsewhere.
+      .mockReturnValueOnce(new Promise<WorkspaceSnapshot>((r) => (resolveRefresh = r)))
+    vi.stubGlobal('useApi', () => ({ getWorkspace }))
+
+    const ws = useWorkspaceStore()
+    const notifications = useNotificationsStore()
+    await ws.switchTo('ws1')
+    expect(notifications.count).toBe(1)
+
+    const pass = ws.refresh()
+    notifications.upsert(notification('n1', { status: 'acted', resolvedAt: 2 }))
+    expect(notifications.count).toBe(0)
+    resolveRefresh(snapshot('ws1', [frame], [notification('n1')]))
+    await pass
+
+    expect(notifications.count).toBe(0)
+  })
 })
 
 // Cold-open waterfall flattening (app-startup initiative, item 8): `init()` fetches the persisted

package/app/stores/workspace.ts

@@ -9,6 +9,8 @@ import type {
 } from '~/types/domain'
 import { useAccountsStore } from '~/stores/accounts'
 import { useBoardStore } from '~/stores/board'
+import { useNotificationsStore } from '~/stores/notifications'
+import type { LiveWriteBaselines } from '~/stores/workspace/hydrate'
 import { applySnapshotToStores, resetPerBoardCaches } from '~/stores/workspace/hydrate'
 import { createWorkspaceCommands } from '~/stores/workspace/commands'
 import { createInfraSetupState } from '~/stores/workspace/infraSetup'
@@ -81,12 +83,12 @@ export const useWorkspaceStore = defineStore(
     )
 
     /**
-     * Push a snapshot into the data stores. `boardSince` (captured BEFORE this snapshot's fetch)
-     * lets the board store preserve any block live-`upsert`ed while the fetch was in flight, so a
-     * slower refresh can't clobber a newer live status (see `useBoardStore().hydrate`). Omitted by
-     * fresh loads (init/switch/create), where there is no in-flight-upsert race to guard.
+     * Push a snapshot into the data stores. `baselines` (captured BEFORE this snapshot's fetch)
+     * lets the replace-style stores preserve anything written live while the fetch was in flight,
+     * so a slower refresh can't clobber newer live state (see {@link LiveWriteBaselines}). Omitted
+     * by fresh loads (init/switch/create), where there is no in-flight race to guard.
      */
-    function hydrate(snapshot: WorkspaceSnapshot, boardSince?: number) {
+    function hydrate(snapshot: WorkspaceSnapshot, baselines?: LiveWriteBaselines) {
       // A change of active board (or the first load) drops the per-block caches that are NOT
       // part of the snapshot; a same-board refresh keeps them (see `resetPerBoardCaches`).
       if (workspaceId.value !== snapshot.workspace.id) resetPerBoardCaches()
@@ -107,7 +109,7 @@ export const useWorkspaceStore = defineStore(
         workspaces.value.unshift(snapshot.workspace)
       }
       // Fan the rest of the snapshot out into the per-feature data stores.
-      applySnapshotToStores(snapshot, boardSince)
+      applySnapshotToStores(snapshot, baselines)
     }
 
     /** Resolve accounts + boards, then open the right board for the active account. */
@@ -209,17 +211,20 @@ export const useWorkspaceStore = defineStore(
       const targetId = workspaceId.value
       if (!targetId) return
       const seq = ++refreshSeq
-      // Capture the board's live-upsert baseline BEFORE the fetch: any block upserted by a live
-      // event while this (potentially slow) snapshot is in flight is newer than the snapshot, so
-      // `hydrate` must NOT clobber it back. The `refreshSeq` guard below only orders refreshes
-      // against each OTHER — this guards a refresh against an interleaved live upsert (e.g. a
-      // run's terminal status landing mid-fetch), the coherence hazard under CI latency.
-      const boardSince = useBoardStore().hydrateBaseline()
+      // 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 `hydrate`
+      // must NOT clobber it back. The `refreshSeq` guard below only orders refreshes against each
+      // OTHER — this guards a refresh against an interleaved live write (a run's terminal status
+      // landing mid-fetch, or the inbox card it raises), the coherence hazard under CI latency.
+      const baselines: LiveWriteBaselines = {
+        board: useBoardStore().hydrateBaseline(),
+        notifications: useNotificationsStore().hydrateBaseline(),
+      }
       const snapshot = await api.getWorkspace(targetId)
       // A newer refresh was issued (or the active board switched) while this fetch was in flight —
       // discard this older/staler result so it can't clobber the newer hydrate.
       if (seq !== refreshSeq || workspaceId.value !== targetId) return
-      hydrate(snapshot, boardSince)
+      hydrate(snapshot, baselines)
     }
 
     /** The active workspace id, or throw if the app isn't bootstrapped yet. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.241.0",
+  "version": "0.241.1",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",