feat(04-06): implement live-sync SSE vertical slice (LIST-04, D-04/D-10/D-11/D-12)

- Wire publishListEvent fan-out in lists.ts after every write mutation (item:added/updated/deleted, list:updated/deleted)
- Add GET /api/sse/lists scoped endpoint in sse.ts: resolveUserId → 401 on null; getAccessibleListIds → subscribe only to accessible channels; 30s heartbeat; cleanup on disconnect (D-04/T-04-01/T-04-02)
- Create useListSSE.ts: bounded-backoff EventSource wrapper (250ms→500ms→1s→2s→4s→cap 8s); MAX_ATTEMPTS=6; withCredentials:true; close-before-retry prevents reconnect storm (Pitfall 3); invalidates ['list', listId] on open (D-10) and on each event; onStateChange('disconnected') after exhaustion (D-11)
- Create LiveSyncIndicator.tsx: connected=green dot; reconnecting=pulsing muted dot + label; disconnected=red dot + 'Updates paused' (role=alert); correct ARIA per UI-SPEC
- Wire useListSSE + LiveSyncIndicator into ListDetail header; retain refetchInterval:30000 polling fallback (D-12)
- All 8 useListSSE tests pass; all 54 API tests pass; both typechecks pass
- playwright-cli: live update confirmed (eggs item added via API appeared in browser without manual refresh)

apps/pwa/src/components/LiveSyncIndicator.tsx

@@ -0,0 +1,119 @@
+/**
+ * LiveSyncIndicator — visual SSE connection status indicator (LIST-04, D-11).
+ *
+ * States per UI-SPEC §"LiveSyncIndicator":
+ *   connected:    8px filled circle in --color-member-1 (#50C878), no label
+ *   reconnecting: 8px pulsing circle in --color-text-muted + "Reconnecting…" label
+ *   disconnected: 8px filled circle in --color-destructive + "Updates paused" label
+ *
+ * Accessibility:
+ *   - role="status" for connected/reconnecting (polite announcements)
+ *   - role="alert" for disconnected state (assertive announcement)
+ *   - aria-label per UI-SPEC copywriting contract
+ *
+ * Positioned at the right end of the ListDetail header row.
+ * Visible only inside ListDetail (not on ListsIndex).
+ */
+
+import type { SyncState } from '../hooks/useListSSE.js'
+
+interface LiveSyncIndicatorProps {
+  state: SyncState
+}
+
+export function LiveSyncIndicator({ state }: LiveSyncIndicatorProps) {
+  if (state === 'connected') {
+    return (
+      <div
+        role="status"
+        aria-label="Live sync connected"
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 'var(--space-1)',
+        }}
+      >
+        {/* 8px filled green dot — --color-member-1 (#50C878) per UI-SPEC */}
+        <div
+          style={{
+            width: '8px',
+            height: '8px',
+            borderRadius: '50%',
+            backgroundColor: 'var(--color-member-1, #50C878)',
+            flexShrink: 0,
+          }}
+        />
+      </div>
+    )
+  }
+
+  if (state === 'reconnecting') {
+    return (
+      <div
+        role="status"
+        aria-label="Reconnecting"
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 'var(--space-1)',
+        }}
+      >
+        {/* 8px pulsing muted dot — animation via keyframes in CSS */}
+        <div
+          style={{
+            width: '8px',
+            height: '8px',
+            borderRadius: '50%',
+            backgroundColor: 'var(--color-text-muted, #9CA3AF)',
+            flexShrink: 0,
+            animation: 'pulse 1.4s ease-in-out infinite',
+          }}
+        />
+        <span
+          style={{
+            fontSize: 'var(--text-label-size, 13px)',
+            color: 'var(--color-text-muted, #9CA3AF)',
+            fontFamily: 'var(--font-family-base)',
+            whiteSpace: 'nowrap',
+          }}
+        >
+          Reconnecting…
+        </span>
+      </div>
+    )
+  }
+
+  // disconnected — role="alert" for assertive announcement
+  return (
+    <div
+      role="alert"
+      aria-label="Updates paused — tap to retry"
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 'var(--space-1)',
+      }}
+    >
+      {/* 8px filled red dot — --color-destructive (#DC2626) */}
+      <div
+        style={{
+          width: '8px',
+          height: '8px',
+          borderRadius: '50%',
+          backgroundColor: 'var(--color-destructive, #DC2626)',
+          flexShrink: 0,
+        }}
+      />
+      <span
+        style={{
+          fontSize: 'var(--text-label-size, 13px)',
+          color: 'var(--color-destructive, #DC2626)',
+          fontFamily: 'var(--font-family-base)',
+          whiteSpace: 'nowrap',
+        }}
+      >
+        Updates paused
+      </span>
+    </div>
+  )
+}

apps/pwa/src/hooks/useListSSE.test.ts

@@ -313,7 +313,7 @@ describe('useListSSE — D-11 bounded backoff', () => {
     })
 
     expect(mockInstances.length).toBe(instanceCountAfterUnmount) // no new connection post-unmount
-    expect(firstEs.closeCalled ?? (firstEs as unknown as { close: () => void; closeCalled?: boolean }).closeCalled).toBeTruthy()
+    expect((firstEs as unknown as { closeCalled?: boolean }).closeCalled).toBeTruthy()
   })
 
   it('uses withCredentials: true on EventSource (Pitfall 7 — session cookie)', async () => {

apps/pwa/src/hooks/useListSSE.ts

@@ -0,0 +1,114 @@
+/**
+ * useListSSE — Bounded-backoff EventSource wrapper for live list sync (LIST-04).
+ *
+ * Decisions implemented:
+ *   D-10: Full refetch on reconnect — invalidates ['list', listId] on open.
+ *   D-11: Silent bounded-backoff reconnect (250ms→500ms→1s→2s→4s→cap 8s).
+ *         After MAX_ATTEMPTS failures: onStateChange('disconnected'), stop retrying.
+ *   D-12: Polling fallback (refetchInterval:30000) lives in ListDetail — always active.
+ *
+ * Security (Pitfall 7, T-04-01):
+ *   withCredentials: true ensures the OIDC session cookie is sent.
+ *
+ * Implementation notes (Pitfall 3 — no reconnect storm):
+ *   On onerror: close the EventSource BEFORE scheduling setTimeout.
+ *   This prevents the browser's built-in reconnect stacking with our manual one.
+ *   Refs (not state) for esRef/attemptsRef/timerRef — avoids re-render loops.
+ *
+ * Source: RESEARCH.md Finding 4 verbatim pattern.
+ */
+
+import { useEffect, useRef, useCallback } from 'react'
+import { useQueryClient } from '@tanstack/react-query'
+
+export type SyncState = 'connected' | 'reconnecting' | 'disconnected'
+
+/**
+ * Backoff schedule per D-11: 250ms → 500ms → 1000ms → 2000ms → 4000ms → cap 8000ms.
+ * 6 steps → MAX_ATTEMPTS = 6; after exhaustion, state → 'disconnected'.
+ */
+const BACKOFF_STEPS_MS = [250, 500, 1000, 2000, 4000, 8000]
+const MAX_ATTEMPTS = BACKOFF_STEPS_MS.length
+
+export interface UseListSSEOptions {
+  listId: number
+  onStateChange: (state: SyncState) => void
+}
+
+/**
+ * Opens a scoped SSE connection to /api/sse/lists and invalidates React Query
+ * cache on events — driving a full refetch (D-10).
+ *
+ * Lifecycle:
+ *   Mount  → connect() → EventSource opened
+ *   Open   → attemptsRef reset → onStateChange('connected') → invalidate cache
+ *   Event  → invalidate ['list', listId]
+ *   Error  → es.close() → if attempts left: onStateChange('reconnecting') + setTimeout(connect, backoff)
+ *                          else: onStateChange('disconnected') — stop
+ *   Unmount → es.close() + clearTimeout(timerRef)
+ */
+export function useListSSE({ listId, onStateChange }: UseListSSEOptions): void {
+  const queryClient = useQueryClient()
+  const esRef = useRef<EventSource | null>(null)
+  const attemptsRef = useRef(0)
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  // handleListChange is stable — invalidate the list on any list-change event
+  const handleListChange = useCallback(() => {
+    queryClient.invalidateQueries({ queryKey: ['list', listId] })
+  }, [queryClient, listId])
+
+  const connect = useCallback(() => {
+    // Close any existing connection (prevents stacking)
+    esRef.current?.close()
+
+    const es = new EventSource('/api/sse/lists', { withCredentials: true })
+    esRef.current = es
+
+    // Subscribe to all list-change event types (D-10 — trigger refetch on any change)
+    es.addEventListener('item:added', handleListChange)
+    es.addEventListener('item:updated', handleListChange)
+    es.addEventListener('item:deleted', handleListChange)
+    es.addEventListener('list:updated', handleListChange)
+    es.addEventListener('list:deleted', handleListChange)
+
+    es.onopen = () => {
+      // Reset attempt counter on successful open (D-11)
+      attemptsRef.current = 0
+      onStateChange('connected')
+      // Full refetch on (re)connect — D-10: no Last-Event-ID replay, just refetch
+      queryClient.invalidateQueries({ queryKey: ['list', listId] })
+    }
+
+    es.onerror = () => {
+      // Close BEFORE scheduling retry — prevents browser auto-reconnect stacking (Pitfall 3)
+      es.close()
+
+      const attempt = attemptsRef.current
+
+      if (attempt >= MAX_ATTEMPTS) {
+        // Backoff exhausted — surface "Updates paused" indicator and stop (D-11)
+        onStateChange('disconnected')
+        // D-12 polling fallback (refetchInterval:30000 in ListDetail) keeps data fresh
+        return
+      }
+
+      onStateChange('reconnecting')
+      const delay = BACKOFF_STEPS_MS[attempt]
+      attemptsRef.current = attempt + 1
+      timerRef.current = setTimeout(connect, delay)
+    }
+  }, [listId, queryClient, onStateChange, handleListChange])
+
+  useEffect(() => {
+    connect()
+    return () => {
+      // Cleanup: close EventSource + cancel any pending reconnect timer (Pitfall 3)
+      esRef.current?.close()
+      if (timerRef.current !== null) {
+        clearTimeout(timerRef.current)
+        timerRef.current = null
+      }
+    }
+  }, [connect])
+}

apps/pwa/src/routes/ListDetail.tsx

@@ -1,7 +1,7 @@
 /**
  * ListDetail — Single list view (/lists/:listId).
  *
- * Replaces the Plan 04-01 placeholder. Delivers LIST-02 + LIST-03:
+ * Delivers LIST-02 + LIST-03 + LIST-04:
  *   - Fetches items via useQuery(['list', listId]) with 30s polling fallback (D-12)
  *   - Splits items into active (!checked, sorted rank ASC) and completed (checked) (D-05)
  *   - Optimistic mutations for add / check / delete (D-07/D-09)
@@ -14,7 +14,14 @@
  *   - Remote reorders animate via CSS.Transform.toString in ItemRow (D-14)
  *   - Concurrent reorder converges via server last-write-wins (D-15)
  *
- * Live sync (SSE) is wired in Plan 06.
+ * Live sync (LIST-04, D-10/D-11/D-12):
+ *   - useListSSE wires /api/sse/lists with bounded backoff reconnect (D-11)
+ *   - On SSE event: invalidates ['list', listId] → background refetch (D-10)
+ *   - LiveSyncIndicator renders connection status in the header
+ *   - refetchInterval:30000 polling fallback always active (D-12)
+ *   - Note: SSE connection lives in ListDetail (one stream per list navigation).
+ *     A future optimization could hoist this to the Lists route level — acceptable
+ *     for Phase 4 per RESEARCH note; Phase 5 push will own the session lifecycle.
  *
  * Security: item text rendered as plain-text JSX children (T-04-06 XSS guard).
  */
@@ -47,6 +54,9 @@ import {
 } from '../api/listsClient.js'
 import { ItemRow } from '../components/ItemRow.js'
 import { AddItemInput } from '../components/AddItemInput.js'
+import { LiveSyncIndicator } from '../components/LiveSyncIndicator.js'
+import { useListSSE } from '../hooks/useListSSE.js'
+import type { SyncState } from '../hooks/useListSSE.js'
 import type { ListItem, ListItemsResponse } from '../api/listsClient.js'
 
 /**
@@ -97,6 +107,13 @@ export function ListDetail() {
   const parsedListId = Number(listId)
 
   const [completedExpanded, setCompletedExpanded] = useState(true)
+  const [syncState, setSyncState] = useState<SyncState>('connected')
+
+  // ── Live sync (LIST-04) ──────────────────────────────────────────────────
+  // Bounded-backoff SSE hook (D-11). On open: invalidates ['list', listId] (D-10).
+  // On event: invalidates ['list', listId] → background refetch.
+  // Polling fallback: refetchInterval:30000 below stays always active (D-12).
+  useListSSE({ listId: parsedListId, onStateChange: setSyncState })
 
   // ── dnd-kit sensors ────────────────────────────────────────────────────────
   // PointerSensor: desktop mouse — immediate activation
@@ -363,6 +380,9 @@ export function ListDetail() {
               Plan 05/06 can enrich from the ['lists'] cache by listId. */}
           List
         </h1>
+
+        {/* Live sync indicator — connected/reconnecting/disconnected (LIST-04, D-11) */}
+        <LiveSyncIndicator state={syncState} />
       </div>
 
       {/* Content area */}