@cat-factory/app 0.239.0 → 0.241.1

package/app/stores/accounts.ts

@@ -1,6 +1,7 @@
 import { defineStore } from 'pinia'
 import { computed, ref } from 'vue'
 import { useUpsertList } from '~/composables/useUpsertList'
+import type { AuditEventWire } from '@cat-factory/contracts'
 import type {
   Account,
   AccountInvitation,
@@ -113,6 +114,73 @@ export const useAccountsStore = defineStore(
       return updated
     }
 
+    // ---- audit log + session revocation -----------------------------------
+    // The audit log is a paginated, append-only feed, so it is kept OUT of `useUpsertList`: the
+    // rows never change and never arrive out of band, and a keyed upsert list would quietly
+    // reorder a page whose whole meaning is its order. Pages are appended in the order the server
+    // served them, and `auditCursor` is opaque — it round-trips verbatim, never inspected.
+    const auditEvents = ref<AuditEventWire[]>([])
+    const auditCursor = ref<string | null>(null)
+    const auditLoading = ref(false)
+
+    /**
+     * The audit feed has fallen behind something this session did. Set by the writers below and
+     * cleared by whoever reloads; the audit viewer watches it.
+     *
+     * A flag rather than a reload, because reloading here is what conflated two outcomes: the
+     * revocation and the feed refresh are separate calls that fail separately, and awaiting the
+     * second inside the first reported a revocation that HAD succeeded as "could not sign the
+     * member out" whenever the read failed after it. It also fired on surfaces with no audit
+     * panel rendered (basic mode, and any account whose deployment wires no audit store), paying
+     * for a read nothing was going to show and turning its 503 into an error about the write.
+     *
+     * The viewer owns the reload instead, which is where it belongs: it already distinguishes a
+     * failed page from an empty one, and a refresh failure now renders in that slot rather than
+     * as a false report about the revocation.
+     */
+    const auditStale = ref(false)
+
+    /**
+     * Load the newest page, replacing whatever was held. Used on open and on refresh, so a reader
+     * is never shown a feed spliced from two different moments.
+     */
+    async function loadAuditEvents(accountId: string) {
+      auditLoading.value = true
+      // Cleared on ATTEMPT, not on success. A failed reload is reported by the viewer's own error
+      // slot, and leaving the flag set would re-trigger the watch that just failed.
+      auditStale.value = false
+      try {
+        const page = await api.listAuditEvents(accountId)
+        auditEvents.value = page.events
+        auditCursor.value = page.nextCursor
+      } finally {
+        auditLoading.value = false
+      }
+    }
+
+    /** Append the next (older) page. A no-op at the end of the log. */
+    async function loadMoreAuditEvents(accountId: string) {
+      if (!auditCursor.value || auditLoading.value) return
+      auditLoading.value = true
+      try {
+        const page = await api.listAuditEvents(accountId, { cursor: auditCursor.value })
+        auditEvents.value = [...auditEvents.value, ...page.events]
+        auditCursor.value = page.nextCursor
+      } finally {
+        auditLoading.value = false
+      }
+    }
+
+    /**
+     * End every session a member holds. Their membership and roles are untouched, so the roster
+     * needs no patching — what changed is not visible in it, which is why the audit feed is
+     * marked stale instead: the revocation's only lasting trace is the row it wrote.
+     */
+    async function revokeMemberSessions(accountId: string, userId: string) {
+      await api.revokeMemberSessions(accountId, userId)
+      auditStale.value = true
+    }
+
     // ---- email sender connection -----------------------------------------
 
     const emailConnection = ref<EmailConnection | null>(null)
@@ -144,6 +212,10 @@ export const useAccountsStore = defineStore(
       ready,
       members,
       invitations,
+      auditEvents,
+      auditCursor,
+      auditLoading,
+      auditStale,
       emailConnection,
       emailConfigured,
       load,
@@ -155,6 +227,9 @@ export const useAccountsStore = defineStore(
       invite,
       revokeInvite,
       setMemberRoles,
+      loadAuditEvents,
+      loadMoreAuditEvents,
+      revokeMemberSessions,
       loadEmailConnection,
       connectEmail,
       disconnectEmail,

package/app/stores/board/moveRefusal.spec.ts

@@ -0,0 +1,40 @@
+import type { RiskPolicySelectionRefusal } from '@cat-factory/contracts'
+import { describe, expect, it } from 'vitest'
+import en from '../../../i18n/locales/en.json'
+import { moveRefusalKey } from './moveRefusal'
+
+/** The thrown shape the contract client produces for a refused reparent (`ApiError.body`). */
+const refused = (reason: string) => ({
+  body: { error: { code: 'forbidden', details: { reason } } },
+})
+
+const REASONS: RiskPolicySelectionRefusal[] = [
+  'relaxes_role_sandbox',
+  'relaxes_role_submission_allowlist',
+  'relaxes_role_class_rule',
+]
+
+describe('moveRefusalKey', () => {
+  it('maps every refusal reason to a key the catalog actually holds', () => {
+    // Derived from the contracts union rather than a list written here, so a new reason fails
+    // this rather than silently reaching the user as the backend's untranslated English.
+    const catalog = (en as { board: { toast: { moveRefused: Record<string, string> } } }).board
+      .toast.moveRefused
+    for (const reason of REASONS) {
+      const key = moveRefusalKey(refused(reason))
+      expect(key, `${reason} has no key`).toBe(`board.toast.moveRefused.${reason}`)
+      expect(catalog[reason], `${reason} has no copy`).toBeTruthy()
+    }
+    // And nothing else: copy for a reason the backend cannot send is copy nobody translates for
+    // a purpose.
+    expect(Object.keys(catalog).sort()).toEqual([...REASONS].sort())
+  })
+
+  it('falls back to the raw message for anything else', () => {
+    // A 403 the guard did not raise, a network fault, a reason a newer backend knows and this
+    // build does not: the backend's own prose is the honest last resort, not a wrong translation.
+    expect(moveRefusalKey(refused('some_future_reason'))).toBeNull()
+    expect(moveRefusalKey({ body: { error: { code: 'forbidden' } } })).toBeNull()
+    expect(moveRefusalKey(new Error('Network down'))).toBeNull()
+  })
+})

package/app/stores/board/moveRefusal.ts

@@ -0,0 +1,34 @@
+import type { RiskPolicySelectionRefusal } from '@cat-factory/contracts'
+import { apiErrorReason } from '~/composables/api/errors'
+
+/**
+ * The translated description for a reparent the backend refused on merge-preset grounds, or
+ * `null` when the failure is anything else.
+ *
+ * A cross-home drag carries a task into another workspace's preset library, which re-decides
+ * whether its runs are sandboxed for the mover's role (ADR 0037), so the backend refuses one that
+ * would drop a restriction they are under. That refusal is a condition a person can act on, and
+ * the backend does not localize prose: it emits the machine-readable `details.reason` and the SPA
+ * maps it here, exactly as `usePipelineErrorToast` maps a conflict's. Without this the drag toast
+ * showed the raw English `ForbiddenError` message to every locale.
+ *
+ * The copy is deliberately NOT the picker's `riskPolicy.picker.refused.*`, which is worded for
+ * someone holding a control: this person picked no policy at all, and telling them about "the
+ * policy you picked" sends them looking for a picker they never touched.
+ *
+ * Keyed on the contracts union so a renamed reason fails the typecheck rather than silently
+ * falling through to the untranslated prose. An unrecognised reason returns `null` and the caller
+ * falls back to the backend's own message, which is the honest last resort.
+ */
+const MOVE_REFUSAL_KEY: Record<RiskPolicySelectionRefusal, string> = {
+  relaxes_role_sandbox: 'board.toast.moveRefused.relaxes_role_sandbox',
+  relaxes_role_submission_allowlist: 'board.toast.moveRefused.relaxes_role_submission_allowlist',
+  relaxes_role_class_rule: 'board.toast.moveRefused.relaxes_role_class_rule',
+}
+
+/** The i18n key for a thrown reparent error's refusal reason, else `null`. */
+export function moveRefusalKey(error: unknown): string | null {
+  const reason = apiErrorReason(error)
+  if (!reason) return null
+  return MOVE_REFUSAL_KEY[reason as RiskPolicySelectionRefusal] ?? null
+}

package/app/stores/board/placement.ts

@@ -2,6 +2,7 @@ import type { UpdateBlockInput } from '@cat-factory/contracts'
 import { useServicesStore } from '~/stores/services'
 import { useWorkspaceStore } from '~/stores/workspace'
 import { createBoardDependencies } from './dependencies'
+import { moveRefusalKey } from './moveRefusal'
 import type { BoardWriteContext } from './context'
 import { UNDO_WINDOW_MS } from './context'
 
@@ -69,9 +70,13 @@ export function createBoardPlacement(ctx: BoardWriteContext) {
     } catch (e) {
       b.parentId = prevParentId
       b.position = prevPosition
+      // A cross-home drag can be refused on merge-preset grounds, which is a condition the mover
+      // can act on rather than a fault. The backend sends the machine-readable reason and no
+      // translated prose, so map it here; anything else keeps the raw message as the last resort.
+      const refusal = moveRefusalKey(e)
       toast.add({
         title: tr('board.toast.moveFailed'),
-        description: e instanceof Error ? e.message : String(e),
+        description: refusal ? tr(refusal) : e instanceof Error ? e.message : String(e),
         icon: 'i-lucide-triangle-alert',
         color: 'error',
       })

package/app/stores/documents.spec.ts

@@ -0,0 +1,156 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { useDocumentsStore } from '~/stores/documents'
+import { useWorkspaceStore } from '~/stores/workspace'
+import type { DocumentFreshness, SourceDocument } from '~/types/domain'
+
+// The document store's REFRESH half: what a person gets back when they ask a source whether the
+// copy on the board is still the current one.
+//
+// Two things are worth pinning here rather than leaving to the component. The verdict is kept
+// SEPARATE from the row because it is a statement about a moment, not a property of the projection,
+// so an absent entry has to keep meaning "nobody has asked" (listing documents deliberately probes
+// nothing). And a refresh that pulls a moved page has to reconcile the returned row into the same
+// list every surface reads, or the panel goes on showing the title and excerpt import stored while
+// claiming, one line below, that it just confirmed the newer revision.
+
+function doc(over: Partial<SourceDocument> = {}): SourceDocument {
+  return {
+    source: 'figma',
+    externalId: 'file1:1-2',
+    title: 'Checkout flow',
+    url: 'https://figma.com/design/file1',
+    excerpt: 'Checkout',
+    linkedBlockId: 'task_1',
+    role: null,
+    docKind: null,
+    syncedAt: 1_000,
+    ...over,
+  }
+}
+
+const CONFIRMED: DocumentFreshness = { status: 'confirmed', version: 'v2', change: 'reimported' }
+
+/** The store reads `useApi()` off the auto-import, so each test stubs just what it calls. */
+function stubApi(over: Record<string, unknown>) {
+  vi.stubGlobal('useApi', () => ({
+    listDocuments: () => Promise.resolve([]),
+    ...over,
+  }))
+}
+
+beforeEach(() => {
+  useWorkspaceStore().workspaceId = 'ws1'
+})
+
+describe('documents store: manual refresh', () => {
+  it('reconciles the refreshed row into the list every surface reads', async () => {
+    stubApi({
+      listDocuments: () => Promise.resolve([doc()]),
+      refreshDocument: () =>
+        Promise.resolve({
+          document: doc({ title: 'Checkout flow v2', syncedAt: 2_000 }),
+          freshness: CONFIRMED,
+        }),
+    })
+    const store = useDocumentsStore()
+    await store.loadDocuments()
+
+    await store.refresh('figma', 'file1:1-2')
+
+    // Upserted by `(source, externalId)`, not appended: a refresh must not leave the old title
+    // sitting beside the new one in a picker keyed by the same document.
+    expect(store.documents).toHaveLength(1)
+    expect(store.documents[0]?.title).toBe('Checkout flow v2')
+  })
+
+  it('records the verdict beside the row, and reports "nobody asked" until someone does', async () => {
+    stubApi({
+      refreshDocument: () => Promise.resolve({ document: doc(), freshness: CONFIRMED }),
+    })
+    const store = useDocumentsStore()
+
+    // An unasked document has NO verdict. It must not read as unknown-and-therefore-suspect: a
+    // freshly imported page is fine, it simply has not been re-checked since.
+    expect(store.freshnessFor('figma', 'file1:1-2')).toBeUndefined()
+
+    await store.refresh('figma', 'file1:1-2')
+
+    expect(store.freshnessFor('figma', 'file1:1-2')?.verdict).toEqual(CONFIRMED)
+    // Stamped with WHEN it was reached, because a verdict never expires: what keeps an hour-old
+    // confirmation from rendering as the present state of a page that has had an hour to move is
+    // that the moment travels with it.
+    expect(store.freshnessFor('figma', 'file1:1-2')?.checkedAt).toBeTypeOf('number')
+    // Scoped to the document that was asked about, never to the source.
+    expect(store.freshnessFor('figma', 'other:9-9')).toBeUndefined()
+  })
+
+  it('never shows one board\u2019s verdict against another board\u2019s row', async () => {
+    // The same Figma file can be imported into two boards, and `(source, externalId)` is identical
+    // in both, so a verdict keyed by that pair alone would render board A's "confirmed, revision
+    // v2" against a board B row nobody has ever checked. That breaks the "absent means nobody has
+    // asked" rule in the one direction nothing can notice, since the wrong answer looks like a
+    // right one.
+    stubApi({
+      refreshDocument: () => Promise.resolve({ document: doc(), freshness: CONFIRMED }),
+    })
+    const store = useDocumentsStore()
+    await store.refresh('figma', 'file1:1-2')
+    expect(store.freshnessFor('figma', 'file1:1-2')?.verdict).toEqual(CONFIRMED)
+
+    useWorkspaceStore().workspaceId = 'ws2'
+
+    expect(store.freshnessFor('figma', 'file1:1-2')).toBeUndefined()
+
+    // …and switching back does not lose it: the verdict stays true of the board it was asked on.
+    useWorkspaceStore().workspaceId = 'ws1'
+    expect(store.freshnessFor('figma', 'file1:1-2')?.verdict).toEqual(CONFIRMED)
+  })
+
+  it('does not merge a check that outlived a board switch into the new board\u2019s list', async () => {
+    // The list is the ACTIVE board's and is not keyed by board, so a row arriving after the switch
+    // would be a document from somewhere else appearing on a board that never imported it. The
+    // verdict is still filed, under the board that asked.
+    let resolve!: (v: unknown) => void
+    stubApi({
+      listDocuments: () => Promise.resolve([]),
+      refreshDocument: () =>
+        new Promise((res) => {
+          resolve = res
+        }),
+    })
+    const store = useDocumentsStore()
+    await store.loadDocuments()
+
+    const pending = store.refresh('figma', 'file1:1-2')
+    useWorkspaceStore().workspaceId = 'ws2'
+    resolve({ document: doc(), freshness: CONFIRMED })
+    await pending
+
+    expect(store.documents).toHaveLength(0)
+    useWorkspaceStore().workspaceId = 'ws1'
+    expect(store.freshnessFor('figma', 'file1:1-2')?.verdict).toEqual(CONFIRMED)
+  })
+
+  it('reports in-flight state per document, and clears it when the source refuses', async () => {
+    let reject!: (e: Error) => void
+    stubApi({
+      refreshDocument: () =>
+        new Promise((_res, rej) => {
+          reject = rej
+        }),
+    })
+    const store = useDocumentsStore()
+
+    const pending = store.refresh('figma', 'file1:1-2')
+    expect(store.isRefreshing('figma', 'file1:1-2')).toBe(true)
+    expect(store.isRefreshing('figma', 'other:9-9')).toBe(false)
+
+    reject(new Error('figma 429'))
+    await expect(pending).rejects.toThrow('figma 429')
+
+    // A failure that left the flag set would disable the button that is the whole remedy, and the
+    // person would have no way to try again.
+    expect(store.isRefreshing('figma', 'file1:1-2')).toBe(false)
+    expect(store.freshnessFor('figma', 'file1:1-2')).toBeUndefined()
+  })
+})

package/app/stores/documents.ts

@@ -13,6 +13,7 @@ import type {
   SourceDocument,
 } from '~/types/domain'
 import { isConnectableSource } from '@cat-factory/contracts'
+import { useDocumentFreshness } from '~/composables/useDocumentFreshness'
 import { useSourceIntegration } from '~/composables/useSourceIntegration'
 import { useUpsertList } from '~/composables/useUpsertList'
 import { useWorkspaceStore } from '~/stores/workspace'
@@ -56,6 +57,16 @@ export const useDocumentsStore = defineStore('documents', () => {
   })
   const loading = ref(false)
 
+  // The "is this still the current revision" half, in its own collaborator: a verdict is a
+  // statement about a moment rather than a property of a row, and `useDocumentFreshness` owns why
+  // the two must not merge.
+  const { refresh, freshnessFor, isRefreshing } = useDocumentFreshness({
+    workspaceId: () => workspace.workspaceId,
+    refresh: (source, externalId) =>
+      api.refreshDocument(workspace.requireId(), { source, externalId }),
+    onRefreshed: upsertDoc,
+  })
+
   // Workspace+DocKind template / exemplar role links (WS1). Loaded lazily when the management
   // panel opens; the full list of role-tagged documents across kinds.
   const roleLinks = ref<SourceDocument[]>([])
@@ -224,6 +235,9 @@ export const useDocumentsStore = defineStore('documents', () => {
     loadDocuments,
     resolveRef,
     importDocument,
+    refresh,
+    freshnessFor,
+    isRefreshing,
     search,
     plan,
     spawn,

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