---
kind: epic
slug: unified-notifications
title: Unified notification inbox
plan_slug: workspace-communications
status: ready
priority: P1
tenant_id: global
cursor_epic_id: null
updated_at: "2026-09-25"
---

# Epic objective

Create a durable inbox for chat mentions, replies, assignments, gates, and agent outcomes, with accurate unread counts and user-controlled delivery preferences.

## In scope / out of scope

**In scope**

- Notification, preference, and delivery-attempt persistence.
- Inbox queries, read/archive mutations, aggregation, and deep links.
- Producers for chat mentions/replies and existing human-attention events.
- Global and chat-specific badges.

**Out of scope**

- Shipping email or mobile push in the first release.
- Treating transient WebSocket events as notification truth.

## Related tasks

| Task | Link |
|------|------|
| Build notification persistence and inbox API | `./Task-notification-inbox-foundation.md` |
| Connect producers, preferences, and badges | `./Task-notification-producers-and-preferences.md` |

## Dependencies

- Depends on: workspace chat persistence for chat notifications.
- Blocks: agent completion and approval notifications.

## Acceptance criteria

- [ ] Notifications are recipient-specific and workspace-scoped.
- [ ] Inbox counts remain correct after reconnect, multi-device reads, and event replay.
- [ ] Chat mentions and direct messages produce deep-linked inbox entries.
- [ ] Existing gate events can appear in the unified inbox without losing their domain state.

## Proposed timeline

| Phase | Window | Notes |
|-------|--------|-------|
| Inbox foundation | 1 | Schema, API, read/archive semantics |
| Producers and UI | 2 | Event mapping, preferences, badges |