[Phase 5.3] Async notifications: browser notifications + in-app center

[frankbria]

Goal

Notify users when long-running batch jobs complete, blockers are created, or gate runs fail — without requiring them to keep the tab in focus.

Background

Batch executions can run for hours. There is currently no signal when anything noteworthy happens. Users must babysit the UI.

Scope

Browser Notifications (Web Notifications API):

• On first visit to /execution, request notification permission with a clear explanation
• Subscribe to the existing WebSocket event stream for three event types:
  • batch.completed → "Batch {id} finished — {N} tasks done"
  • blocker.created → "Agent is blocked — your input needed"
  • gate.run.failed → "Gate run failed: {gate_name}"
• Fire new Notification(...) when tab is not visible (document.visibilityState !== 'visible')
• Respect permission denial gracefully (no re-prompt)

In-app Notification Center:

• Bell icon in the sidebar with unread count badge (red dot or number)
• Dropdown/panel listing last 20 notifications: icon + message + relative timestamp + "mark read" X
• "Mark all read" action
• Notification history stored in localStorage (no backend required)
• Clear all action

Out of scope

• Webhook (separate issue)
• Email or Slack integration

Acceptance criteria

• Browser notification fires on batch completion when tab is not focused
• Permission request shown once and respected
• Bell icon shows unread count
• Notification list renders recent events with correct messages
• npm test and npm run build pass

[coderabbitai]

🔗 Related PRs

#491 - feat(web-ui): surface PROOF9 gate link in execution completion banner (#469) [merged]
#494 - feat(web-ui): auto-run gates on execution completion, show summary in banner (#472) [merged]
#495 - feat(web-ui): blocker lifecycle explanation and recovery guidance (#473) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

• The frontend is Next.js 19 + React 19 with Tailwind CSS, Radix UI primitives, and @hugeicons/react for icons. No Radix Popover is installed, but @radix-ui/react-dialog and @radix-ui/react-tooltip are available.
• The existing event stream is SSE-based (useEventSource → useTaskStream → useExecutionMonitor). The three notification event types (batch.completed, blocker.created, gate.run.failed) map to existing SSE event types: completion (on BatchResponse status change), blocker, and error/completion with gate context.
• AppSidebar already renders badge counts for Blockers and Sessions using the same pattern needed for the bell icon.
• localStorage is already used extensively in file:web-ui/src/lib/workspace-storage.ts — the same pattern applies for notification history.
• No Radix Popover package is installed; the notification panel will be implemented as a positioned div toggled by state (matching the existing pattern in AppSidebar).

Approach

Introduce three focused additions: (1) a useNotifications hook encapsulating all state, localStorage persistence, and browser notification logic; (2) a NotificationCenter component (bell + dropdown panel) dropped into AppSidebar; (3) notification dispatch wired into BatchExecutionMonitor and useTaskStream via their existing event callbacks. No new dependencies are needed.

---

Implementation Plan

1. Define the AppNotification type

In file:web-ui/src/types/index.ts, add:

• AppNotificationType: 'batch.completed' | 'blocker.created' | 'gate.run.failed'
• AppNotification interface with fields: id (string UUID), type (AppNotificationType), message (string), timestamp (ISO string), read (boolean), optional batchId, taskId, gateName

---

2. Create useNotifications hook

New file: file:web-ui/src/hooks/useNotifications.ts

This hook is the single source of truth for all notification state. It should:

• Persist up to 20 notifications in localStorage under the key codeframe_notifications using the same guard pattern (typeof window === 'undefined') as file:web-ui/src/lib/workspace-storage.ts.
• Initialize state by reading from localStorage on mount.
• Expose:
  • notifications: AppNotification[] — last 20, newest first
  • unreadCount: number
  • addNotification(n: Omit<AppNotification, 'id' | 'timestamp' | 'read'>): void — prepends, trims to 20, persists
  • markRead(id: string): void
  • markAllRead(): void
  • clearAll(): void
• Browser notification logic inside addNotification:
  • Check document.visibilityState !== 'visible' and Notification.permission === 'granted'
  • If both true, fire new Notification(title, { body, icon: '/favicon.ico' })
  • Never request permission here (permission is requested separately on the execution page)

---

3. Create a NotificationContext

New file: file:web-ui/src/contexts/NotificationContext.tsx

• Wrap useNotifications in a React context so AppSidebar and BatchExecutionMonitor can both access addNotification without prop drilling.
• Export NotificationProvider and useNotificationContext hook.
• Mark 'use client'.

---

4. Mount NotificationProvider in the root layout

In file:web-ui/src/app/layout.tsx:

• Wrap <AppLayout> with <NotificationProvider> so the context is available app-wide.

---

5. Request browser notification permission on the execution page

In file:web-ui/src/app/execution/page.tsx, inside ExecutionLandingContent:

• Add a useEffect that runs once when the component mounts.
• Check 'Notification' in window && Notification.permission === 'default'.
• If true, call Notification.requestPermission() — no re-prompt if already 'granted' or 'denied'.
• No UI banner is needed; the browser's native permission prompt is sufficient.

---

6. Wire notification dispatch into BatchExecutionMonitor

In file:web-ui/src/components/execution/BatchExecutionMonitor.tsx:

• Call useNotificationContext() to get addNotification.
• In the polling fetchBatch callback, detect when batch.status transitions to 'COMPLETED', 'FAILED', or 'PARTIAL':
  • Use a prevStatusRef (useRef) to track the previous status.
  • On transition to a terminal state, call addNotification({ type: 'batch.completed', message: \Batch ${batchId} finished — ${completedCount} tasks done` })`.
• In BatchTaskRow, the useExecutionMonitor hook already receives onBlocker and onComplete via useTaskStream. Pass an onBlocker callback that calls addNotification({ type: 'blocker.created', message: 'Agent is blocked — your input needed', taskId }).

---

7. Wire gate run failure notifications

In file:web-ui/src/components/execution/BatchExecutionMonitor.tsx (or wherever gate results are consumed — check file:web-ui/src/components/execution/EventStream.tsx and the execution page for gate polling):

• When a gate result with passed: false is detected, call addNotification({ type: 'gate.run.failed', message: \Gate run failed: ${check.name}`, gateName: check.name })`.

---

8. Create NotificationCenter component

New file: file:web-ui/src/components/layout/NotificationCenter.tsx

Mark 'use client'. Structure:

[Bell icon button with unread badge]
  └── [Dropdown panel — absolute positioned div, toggled by useState]
        ├── Header: "Notifications" + "Mark all read" button + "Clear all" button
        └── ScrollArea (reuse `file:web-ui/src/components/ui/scroll-area.tsx`, max-h ~400px)
              └── For each notification (last 20):
                    ├── Icon (type-specific from @hugeicons/react)
                    ├── Message text
                    ├── Relative timestamp (use `date-fns` `formatDistanceToNow` — already in deps)
                    └── "×" mark-read button

Bell button:

• Use Notification02Icon (or similar) from @hugeicons/react
• Overlay a red badge (bg-red-500 text-white text-[10px]) showing unreadCount when > 0 — matching the existing Blockers badge style in AppSidebar

Dropdown panel:

• Positioned absolute bottom-2 left-full ml-2 (opens to the right of the sidebar) or absolute left-0 bottom-full mb-2 depending on sidebar layout
• Close on outside click via a useEffect with a mousedown listener on document
• z-50 to float above content

Empty state: "No notifications yet" centered text when list is empty.

---

9. Mount NotificationCenter in AppSidebar

In file:web-ui/src/components/layout/AppSidebar.tsx:

• Import and render <NotificationCenter /> at the bottom of the <aside>, below the <nav>, before the closing tag.
• It sits in the sidebar's flex column, pinned to the bottom with mt-auto.

---

Architecture overview

sequenceDiagram
    participant BEM as BatchExecutionMonitor
    participant TS as useTaskStream (SSE)
    participant NC as useNotifications
    participant LS as localStorage
    participant BN as Browser Notification API
    participant UI as NotificationCenter (Sidebar)

    BEM->>TS: subscribe to SSE stream
    TS-->>BEM: blocker event
    BEM->>NC: addNotification(blocker.created)
    NC->>LS: persist notifications[]
    NC->>BN: new Notification(...) if tab hidden

    BEM->>BEM: poll fetchBatch()
    BEM->>NC: addNotification(batch.completed) on status transition
    NC->>LS: persist notifications[]
    NC->>BN: new Notification(...) if tab hidden

    UI->>NC: read notifications, unreadCount
    UI-->>UI: render bell badge + dropdown list

Loading

---

File summary

Action	File
Add types	file:web-ui/src/types/index.ts
New hook	file:web-ui/src/hooks/useNotifications.ts
New context	file:web-ui/src/contexts/NotificationContext.tsx
New component	file:web-ui/src/components/layout/NotificationCenter.tsx
Modify	file:web-ui/src/app/layout.tsx — add NotificationProvider
Modify	file:web-ui/src/app/execution/page.tsx — request permission once
Modify	file:web-ui/src/components/execution/BatchExecutionMonitor.tsx — dispatch notifications
Modify	file:web-ui/src/components/layout/AppSidebar.tsx — render NotificationCenter

Import In IDE

🤖 Prompt for AI Agents

## Observations

- The frontend is **Next.js 19 + React 19** with Tailwind CSS, Radix UI primitives, and `@hugeicons/react` for icons. No Radix Popover is installed, but `@radix-ui/react-dialog` and `@radix-ui/react-tooltip` are available.
- The existing event stream is **SSE-based** (`useEventSource` → `useTaskStream` → `useExecutionMonitor`). The three notification event types (`batch.completed`, `blocker.created`, `gate.run.failed`) map to existing SSE event types: `completion` (on `BatchResponse` status change), `blocker`, and `error`/`completion` with gate context.
- `AppSidebar` already renders badge counts for Blockers and Sessions using the same pattern needed for the bell icon.
- `localStorage` is already used extensively in `file:web-ui/src/lib/workspace-storage.ts` — the same pattern applies for notification history.
- No Radix Popover package is installed; the notification panel will be implemented as a positioned `div` toggled by state (matching the existing pattern in `AppSidebar`).

## Approach

Introduce three focused additions: (1) a `useNotifications` hook encapsulating all state, localStorage persistence, and browser notification logic; (2) a `NotificationCenter` component (bell + dropdown panel) dropped into `AppSidebar`; (3) notification dispatch wired into `BatchExecutionMonitor` and `useTaskStream` via their existing event callbacks. No new dependencies are needed.

---

## Implementation Plan

### 1. Define the `AppNotification` type

In `file:web-ui/src/types/index.ts`, add:

- `AppNotificationType`: `'batch.completed' | 'blocker.created' | 'gate.run.failed'`
- `AppNotification` interface with fields: `id` (string UUID), `type` (`AppNotificationType`), `message` (string), `timestamp` (ISO string), `read` (boolean), optional `batchId`, `taskId`, `gateName`

---

### 2. Create `useNotifications` hook

**New file:** `file:web-ui/src/hooks/useNotifications.ts`

This hook is the single source of truth for all notification state. It should:

- **Persist** up to 20 notifications in `localStorage` under the key `codeframe_notifications` using the same guard pattern (`typeof window === 'undefined'`) as `file:web-ui/src/lib/workspace-storage.ts`.
- **Initialize** state by reading from `localStorage` on mount.
- **Expose**:
  - `notifications: AppNotification[]` — last 20, newest first
  - `unreadCount: number`
  - `addNotification(n: Omit<AppNotification, 'id' | 'timestamp' | 'read'>): void` — prepends, trims to 20, persists
  - `markRead(id: string): void`
  - `markAllRead(): void`
  - `clearAll(): void`
- **Browser notification logic** inside `addNotification`:
  - Check `document.visibilityState !== 'visible'` and `Notification.permission === 'granted'`
  - If both true, fire `new Notification(title, { body, icon: '/favicon.ico' })`
  - Never request permission here (permission is requested separately on the execution page)

---

### 3. Create a `NotificationContext`

**New file:** `file:web-ui/src/contexts/NotificationContext.tsx`

- Wrap `useNotifications` in a React context so `AppSidebar` and `BatchExecutionMonitor` can both access `addNotification` without prop drilling.
- Export `NotificationProvider` and `useNotificationContext` hook.
- Mark `'use client'`.

---

### 4. Mount `NotificationProvider` in the root layout

In `file:web-ui/src/app/layout.tsx`:

- Wrap `<AppLayout>` with `<NotificationProvider>` so the context is available app-wide.

---

### 5. Request browser notification permission on the execution page

In `file:web-ui/src/app/execution/page.tsx`, inside `ExecutionLandingContent`:

- Add a `useEffect` that runs once when the component mounts.
- Check `'Notification' in window && Notification.permission === 'default'`.
- If true, call `Notification.requestPermission()` — no re-prompt if already `'granted'` or `'denied'`.
- No UI banner is needed; the browser's native permission prompt is sufficient.

---

### 6. Wire notification dispatch into `BatchExecutionMonitor`

In `file:web-ui/src/components/execution/BatchExecutionMonitor.tsx`:

- Call `useNotificationContext()` to get `addNotification`.
- In the polling `fetchBatch` callback, detect when `batch.status` transitions to `'COMPLETED'`, `'FAILED'`, or `'PARTIAL'`:
  - Use a `prevStatusRef` (`useRef`) to track the previous status.
  - On transition to a terminal state, call `addNotification({ type: 'batch.completed', message: \`Batch ${batchId} finished — ${completedCount} tasks done\` })`.
- In `BatchTaskRow`, the `useExecutionMonitor` hook already receives `onBlocker` and `onComplete` via `useTaskStream`. Pass an `onBlocker` callback that calls `addNotification({ type: 'blocker.created', message: 'Agent is blocked — your input needed', taskId })`.

---

### 7. Wire gate run failure notifications

In `file:web-ui/src/components/execution/BatchExecutionMonitor.tsx` (or wherever gate results are consumed — check `file:web-ui/src/components/execution/EventStream.tsx` and the execution page for gate polling):

- When a gate result with `passed: false` is detected, call `addNotification({ type: 'gate.run.failed', message: \`Gate run failed: ${check.name}\`, gateName: check.name })`.

---

### 8. Create `NotificationCenter` component

**New file:** `file:web-ui/src/components/layout/NotificationCenter.tsx`

Mark `'use client'`. Structure:

```
[Bell icon button with unread badge]
  └── [Dropdown panel — absolute positioned div, toggled by useState]
        ├── Header: "Notifications" + "Mark all read" button + "Clear all" button
        └── ScrollArea (reuse `file:web-ui/src/components/ui/scroll-area.tsx`, max-h ~400px)
              └── For each notification (last 20):
                    ├── Icon (type-specific from @hugeicons/react)
                    ├── Message text
                    ├── Relative timestamp (use `date-fns` `formatDistanceToNow` — already in deps)
                    └── "×" mark-read button
```

**Bell button:**
- Use `Notification02Icon` (or similar) from `@hugeicons/react`
- Overlay a red badge (`bg-red-500 text-white text-[10px]`) showing `unreadCount` when > 0 — matching the existing Blockers badge style in `AppSidebar`

**Dropdown panel:**
- Positioned `absolute bottom-2 left-full ml-2` (opens to the right of the sidebar) or `absolute left-0 bottom-full mb-2` depending on sidebar layout
- Close on outside click via a `useEffect` with a `mousedown` listener on `document`
- `z-50` to float above content

**Empty state:** "No notifications yet" centered text when list is empty.

---

### 9. Mount `NotificationCenter` in `AppSidebar`

In `file:web-ui/src/components/layout/AppSidebar.tsx`:

- Import and render `<NotificationCenter />` at the **bottom** of the `<aside>`, below the `<nav>`, before the closing tag.
- It sits in the sidebar's flex column, pinned to the bottom with `mt-auto`.

---

### Architecture overview

```mermaid
sequenceDiagram
    participant BEM as BatchExecutionMonitor
    participant TS as useTaskStream (SSE)
    participant NC as useNotifications
    participant LS as localStorage
    participant BN as Browser Notification API
    participant UI as NotificationCenter (Sidebar)

    BEM->>TS: subscribe to SSE stream
    TS-->>BEM: blocker event
    BEM->>NC: addNotification(blocker.created)
    NC->>LS: persist notifications[]
    NC->>BN: new Notification(...) if tab hidden

    BEM->>BEM: poll fetchBatch()
    BEM->>NC: addNotification(batch.completed) on status transition
    NC->>LS: persist notifications[]
    NC->>BN: new Notification(...) if tab hidden

    UI->>NC: read notifications, unreadCount
    UI-->>UI: render bell badge + dropdown list
```

---

### File summary

| Action | File |
|---|---|
| Add types | `file:web-ui/src/types/index.ts` |
| New hook | `file:web-ui/src/hooks/useNotifications.ts` |
| New context | `file:web-ui/src/contexts/NotificationContext.tsx` |
| New component | `file:web-ui/src/components/layout/NotificationCenter.tsx` |
| Modify | `file:web-ui/src/app/layout.tsx` — add `NotificationProvider` |
| Modify | `file:web-ui/src/app/execution/page.tsx` — request permission once |
| Modify | `file:web-ui/src/components/execution/BatchExecutionMonitor.tsx` — dispatch notifications |
| Modify | `file:web-ui/src/components/layout/AppSidebar.tsx` — render `NotificationCenter` |

---

Execution Information

Branch: main
Commit: 3f14270

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.