feat(webui): implement notifications and human-attention routing (#648)

webui/app.py

@@ -72,6 +72,11 @@ from webui.system_health import (
     snapshot_to_dict as system_health_to_dict,
 )
 from webui.system_health_views import render_system_health_page
+from webui.notifications import (
+    load_notifications_snapshot,
+    snapshot_to_dict as notifications_snapshot_to_dict,
+)
+from webui.notification_views import render_notifications_page
 
 _READ_ONLY_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
 _AUDIT_MUTATION_PATHS = frozenset({"/audit", "/api/audit"})
@@ -739,6 +744,23 @@ async def api_v1_analytics_ingest(request: Request) -> JSONResponse:
     )
 
 
+async def notifications_route(request: Request) -> HTMLResponse:
+    project_id = request.query_params.get("project_id")
+    attention_class = request.query_params.get("attention_class") or "inbox"
+    snap = load_notifications_snapshot(project_id)
+    html = render_notifications_page(
+        snap, filter_class=attention_class, filter_project=project_id
+    )
+    return HTMLResponse(html)
+
+
+async def api_notifications(request: Request) -> JSONResponse:
+    project_id = request.query_params.get("project_id")
+    snap = load_notifications_snapshot(project_id)
+    data = notifications_snapshot_to_dict(snap)
+    return JSONResponse(data)
+
+
 async def method_not_allowed(request: Request, _exc: Exception) -> Response:
     path = request.url.path
     if path in _AUDIT_MUTATION_PATHS and request.method == "POST":
@@ -767,6 +789,9 @@ def create_app(*, bind_host: str | None = None) -> Starlette:
             Route("/api/queue", api_queue, methods=["GET"]),
             Route("/traffic", traffic, methods=["GET"]),
             Route("/api/traffic", api_traffic, methods=["GET"]),
+            Route("/notifications", notifications_route, methods=["GET"]),
+            Route("/api/notifications", api_notifications, methods=["GET"]),
+            Route("/api/v1/notifications", api_notifications, methods=["GET"]),
             Route("/projects", projects, methods=["GET"]),
             Route("/projects/{project_id}", project_detail, methods=["GET"]),
             Route("/api/projects", api_projects, methods=["GET"]),

webui/nav.py

@@ -45,6 +45,7 @@ NAV_GROUPS: tuple[NavGroup, ...] = (
         NavItem("/queue", "Queue"),
         NavItem("/leases", "Leases"),
         NavItem("/actions", "Actions"),
+        NavItem("/notifications", "Notifications"),
     )),
     NavGroup("Runtime/Sessions", (
         NavItem("/runtime", "Runtime health"),

webui/notification_views.py

@@ -0,0 +1,158 @@
+"""HTML rendering for Phase 3 Notifications and Human-Attention Console (#648)."""
+
+from __future__ import annotations
+
+from html import escape
+from typing import Sequence
+
+from webui.layout import render_page
+from webui.notifications import (
+    ATTENTION_HUMAN_REQUIRED,
+    ATTENTION_OPERATOR,
+    ATTENTION_ROUTINE,
+    NotificationItem,
+    NotificationSnapshot,
+)
+
+
+def _render_attention_badge(attention_class: str) -> str:
+    cls = "badge"
+    if attention_class == ATTENTION_HUMAN_REQUIRED:
+        cls += " badge-blocked"
+    elif attention_class == ATTENTION_OPERATOR:
+        cls += " badge-claimed"
+    else:
+        cls += " muted"
+    return f'<span class="{cls}">{escape(attention_class)}</span>'
+
+
+def _render_notification_row(item: NotificationItem) -> str:
+    category_label = escape(item.category.upper())
+    id_str = escape(item.id)
+    title_str = escape(item.title)
+    summary_str = escape(item.summary)
+    att_badge = _render_attention_badge(item.attention_class)
+
+    work_item_html = "—"
+    if item.work_number and item.work_kind:
+        kind_label = escape(item.work_kind.upper())
+        num_str = f"#{item.work_number}"
+        link = item.deep_link or "#"
+        work_item_html = f'<a href="{escape(link)}"><code>{kind_label} {num_str}</code></a>'
+
+    requires_human_label = (
+        '<span class="badge badge-blocked" style="font-size:0.75rem;">HUMAN REQUIRED</span>'
+        if item.requires_human
+        else ""
+    )
+
+    return f"""<tr>
+  <td><code>{category_label}</code><br><span class="muted" style="font-size:0.75rem;">{id_str}</span></td>
+  <td>
+    <div><strong>{title_str}</strong> {att_badge} {requires_human_label}</div>
+    <div class="muted" style="font-size:0.85rem; margin-top:0.25rem;">{summary_str}</div>
+  </td>
+  <td>{work_item_html}</td>
+  <td><span class="muted" style="font-size:0.8rem;">{escape(item.created_at[:19])}</span></td>
+</tr>"""
+
+
+def _render_notifications_table(items: Sequence[NotificationItem], empty_message: str) -> str:
+    if not items:
+        return f'<p class="muted" style="padding:1rem 0;">{escape(empty_message)}</p>'
+
+    rows = "".join(_render_notification_row(item) for item in items)
+    return f"""<table class="registry">
+  <thead>
+    <tr>
+      <th style="width: 18%;">Category & ID</th>
+      <th style="width: 52%;">Title & Attention Summary</th>
+      <th style="width: 15%;">Work Item</th>
+      <th style="width: 15%;">Time</th>
+    </tr>
+  </thead>
+  <tbody>
+    {rows}
+  </tbody>
+</table>"""
+
+
+def render_notifications_page(
+    snapshot: NotificationSnapshot,
+    *,
+    filter_class: str = "inbox",
+    filter_project: str | None = None,
+) -> str:
+    """Render the notifications and attention inbox page."""
+    title = "Notifications & Attention Inbox"
+
+    err_html = ""
+    if snapshot.fetch_error:
+        err_html = f'<div class="stub" style="border-color:#e53e3e; background:#fff5f5; color:#c53030; margin-bottom:1rem;"><p><strong>Fetch Warning:</strong> {escape(snapshot.fetch_error)}</p></div>'
+
+    # Determine items to render based on filter_class
+    if filter_class == ATTENTION_HUMAN_REQUIRED:
+        display_items = snapshot.human_required_items
+        active_tab_title = "Human-Required Escalations"
+    elif filter_class == ATTENTION_OPERATOR:
+        display_items = snapshot.operator_items
+        active_tab_title = "Operator Inbox Items"
+    elif filter_class == ATTENTION_ROUTINE:
+        display_items = snapshot.routine_items
+        active_tab_title = "Routine Workflow Transitions"
+    elif filter_class == "all":
+        display_items = snapshot.items
+        active_tab_title = "All Events (including Routine)"
+    else:  # "inbox" default
+        display_items = snapshot.inbox_items
+        active_tab_title = "Attention Inbox (Human + Operator)"
+
+    hr_cls = "badge-blocked" if snapshot.human_required_count > 0 else "muted"
+    op_cls = "badge-claimed" if snapshot.operator_count > 0 else "muted"
+
+    metrics_html = f"""<div style="display:flex; gap:1rem; margin-bottom:1.5rem;">
+  <div class="health-card" style="flex:1;">
+    <span class="muted" style="font-size:0.85rem;">Human Required</span>
+    <h2 style="margin:0.2rem 0;"><span class="badge {hr_cls}" style="font-size:1.4rem;">{snapshot.human_required_count}</span></h2>
+    <p class="muted" style="font-size:0.8rem; margin:0;">Critical escalation boundary</p>
+  </div>
+  <div class="health-card" style="flex:1;">
+    <span class="muted" style="font-size:0.85rem;">Operator Inbox</span>
+    <h2 style="margin:0.2rem 0;"><span class="badge {op_cls}" style="font-size:1.4rem;">{snapshot.operator_count}</span></h2>
+    <p class="muted" style="font-size:0.8rem; margin:0;">Operational items needing review</p>
+  </div>
+  <div class="health-card" style="flex:1;">
+    <span class="muted" style="font-size:0.85rem;">Routine Transitions</span>
+    <h2 style="margin:0.2rem 0;"><span class="badge muted" style="font-size:1.4rem;">{snapshot.routine_count}</span></h2>
+    <p class="muted" style="font-size:0.8rem; margin:0;">Background transitions (filtered)</p>
+  </div>
+</div>"""
+
+    # Filter navigation links
+    def _tab_link(target_class: str, label: str) -> str:
+        is_active = (filter_class == target_class)
+        style = "font-weight:bold; border-bottom:2px solid currentColor;" if is_active else "color:#4a5568;"
+        return f'<a href="/notifications?attention_class={target_class}" style="margin-right:1.25rem; text-decoration:none; padding-bottom:0.25rem; {style}">{label}</a>'
+
+    tabs_html = f"""<div style="margin-bottom:1.25rem; border-bottom:1px solid #e2e8f0; padding-bottom:0.5rem;">
+  {_tab_link("inbox", f"Attention Inbox ({snapshot.human_required_count + snapshot.operator_count})")}
+  {_tab_link("human-required", f"Human Required ({snapshot.human_required_count})")}
+  {_tab_link("operator", f"Operator ({snapshot.operator_count})")}
+  {_tab_link("routine", f"Routine ({snapshot.routine_count})")}
+  {_tab_link("all", f"All Events ({snapshot.total_count})")}
+</div>"""
+
+    table_html = _render_notifications_table(
+        display_items,
+        f"No items match attention filter '{filter_class}'.",
+    )
+
+    body = f"""<h2>{escape(title)}</h2>
+<p class="muted">Phase 3 console surface for human-attention routing (#648). Routine workflow transitions are filtered by default to eliminate notification fatigue.</p>
+{err_html}
+{metrics_html}
+{tabs_html}
+<h3>{escape(active_tab_title)}</h3>
+{table_html}"""
+
+    return render_page(title=title, body_html=body)

webui/notifications.py

@@ -0,0 +1,480 @@
+"""Notifications and human-attention routing module for Phase 3 web console (#648).
+
+Defines attention classes, event classification rules, and inbox aggregation so
+operators receive direct alerts only for human-required escalation boundaries
+(#628) while routine workflow transitions remain available for pull-based review.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Callable, Sequence
+
+from webui import console_redaction
+from webui.project_registry import find_project, load_registry
+from webui.queue_loader import QueueSnapshot, load_queue_snapshot
+from webui.lease_loader import LeaseSnapshot, load_lease_snapshot
+from webui.system_health import SystemHealthSnapshot, load_system_health
+
+# Attention class definitions (#628, #648)
+ATTENTION_ROUTINE = "routine"
+ATTENTION_OPERATOR = "operator"
+ATTENTION_HUMAN_REQUIRED = "human-required"
+
+ATTENTION_CLASSES = (
+    ATTENTION_ROUTINE,
+    ATTENTION_OPERATOR,
+    ATTENTION_HUMAN_REQUIRED,
+)
+
+# Notification categories
+CATEGORY_AUTH = "auth"
+CATEGORY_BLOCKER = "blocker"
+CATEGORY_LEASE = "lease"
+CATEGORY_VALIDATION = "validation"
+CATEGORY_WORKFLOW = "workflow"
+CATEGORY_SYSTEM = "system"
+
+CATEGORIES = (
+    CATEGORY_AUTH,
+    CATEGORY_BLOCKER,
+    CATEGORY_LEASE,
+    CATEGORY_VALIDATION,
+    CATEGORY_WORKFLOW,
+    CATEGORY_SYSTEM,
+)
+
+
+@dataclass(frozen=True)
+class NotificationItem:
+    """A single notification or inbox event."""
+
+    id: str
+    attention_class: str  # "routine", "operator", "human-required"
+    category: str  # "auth", "blocker", "lease", "validation", etc.
+    title: str
+    summary: str
+    work_kind: str | None  # "issue", "pr", "session", "system"
+    work_number: int | None
+    project_id: str
+    repo_label: str
+    created_at: str
+    deep_link: str | None = None
+    requires_human: bool = False
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "attention_class": self.attention_class,
+            "category": self.category,
+            "title": self.title,
+            "summary": console_redaction.redact_text(self.summary),
+            "work_kind": self.work_kind,
+            "work_number": self.work_number,
+            "project_id": self.project_id,
+            "repo_label": self.repo_label,
+            "created_at": self.created_at,
+            "deep_link": self.deep_link,
+            "requires_human": self.requires_human,
+            "extra": self.extra,
+        }
+
+
+@dataclass(frozen=True)
+class NotificationSnapshot:
+    """Snapshot of notifications and attention inbox state."""
+
+    project_id: str
+    repo_label: str
+    items: tuple[NotificationItem, ...]
+    human_required_count: int
+    operator_count: int
+    routine_count: int
+    total_count: int
+    fetch_error: str | None = None
+
+    @property
+    def inbox_items(self) -> tuple[NotificationItem, ...]:
+        """Items requiring operator or human attention (excluding routine)."""
+        return tuple(
+            item
+            for item in self.items
+            if item.attention_class in {ATTENTION_OPERATOR, ATTENTION_HUMAN_REQUIRED}
+        )
+
+    @property
+    def human_required_items(self) -> tuple[NotificationItem, ...]:
+        return tuple(
+            item for item in self.items if item.attention_class == ATTENTION_HUMAN_REQUIRED
+        )
+
+    @property
+    def operator_items(self) -> tuple[NotificationItem, ...]:
+        return tuple(
+            item for item in self.items if item.attention_class == ATTENTION_OPERATOR
+        )
+
+    @property
+    def routine_items(self) -> tuple[NotificationItem, ...]:
+        return tuple(
+            item for item in self.items if item.attention_class == ATTENTION_ROUTINE
+        )
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "project_id": self.project_id,
+            "repo_label": self.repo_label,
+            "human_required_count": self.human_required_count,
+            "operator_count": self.operator_count,
+            "routine_count": self.routine_count,
+            "total_count": self.total_count,
+            "fetch_error": self.fetch_error,
+            "inbox_items": [item.as_dict() for item in self.inbox_items],
+            "all_items": [item.as_dict() for item in self.items],
+        }
+
+
+def classify_attention_event(
+    category: str,
+    title: str,
+    summary: str,
+    *,
+    is_hard_stop: bool = False,
+    is_auth_failure: bool = False,
+    is_irrecoverable: bool = False,
+    is_decision_lock: bool = False,
+    is_validation_failure: bool = False,
+    is_stale: bool = False,
+    is_blocker: bool = False,
+) -> tuple[str, bool]:
+    """Classify an event into an attention class and human requirement flag.
+
+    Rules (#628, #648):
+    1. Critical boundaries (hard stop, auth failure, irrecoverable state,
+       decision lock, validation failure) -> ATTENTION_HUMAN_REQUIRED (requires_human=True).
+    2. Operational queues (blocker, stale lease, unassigned ready work, queue collision)
+       -> ATTENTION_OPERATOR (requires_human=False).
+    3. Routine state transitions (clean progression, healthy heartbeats) -> ATTENTION_ROUTINE (requires_human=False).
+    """
+    if (
+        is_hard_stop
+        or is_auth_failure
+        or is_irrecoverable
+        or is_decision_lock
+        or is_validation_failure
+        or category in {CATEGORY_AUTH, CATEGORY_VALIDATION}
+        or "hard stop" in summary.lower()
+        or "unauthorized" in summary.lower()
+        or "irrecoverable" in summary.lower()
+    ):
+        return ATTENTION_HUMAN_REQUIRED, True
+
+    if is_stale or is_blocker or category in {CATEGORY_BLOCKER, CATEGORY_LEASE}:
+        return ATTENTION_OPERATOR, False
+
+    return ATTENTION_ROUTINE, False
+
+
+def load_notifications_snapshot(
+    project_id: str | None = None,
+    *,
+    load_queue: Callable[..., QueueSnapshot] | None = None,
+    load_leases: Callable[..., LeaseSnapshot] | None = None,
+    load_health: Callable[..., SystemHealthSnapshot] | None = None,
+) -> NotificationSnapshot:
+    """Load and classify attention notifications across queue, leases, and system health."""
+    registry = load_registry()
+    project = None
+    if project_id:
+        for entry in registry.projects:
+            if entry.id == project_id:
+                project = entry
+                break
+    else:
+        project = registry.projects[0] if registry.projects else None
+
+    if project is None:
+        return NotificationSnapshot(
+            project_id=project_id or "",
+            repo_label="",
+            items=(),
+            human_required_count=0,
+            operator_count=0,
+            routine_count=0,
+            total_count=0,
+            fetch_error="project not found in registry",
+        )
+
+    queue_loader_fn = load_queue or load_queue_snapshot
+    lease_loader_fn = load_leases or load_lease_snapshot
+    health_loader_fn = load_health or load_system_health
+
+    try:
+        queue_snap = queue_loader_fn(project.id)
+    except TypeError:
+        queue_snap = queue_loader_fn(project_id=project.id)
+
+    try:
+        lease_snap = lease_loader_fn(project_id=project.id)
+    except TypeError:
+        lease_snap = lease_loader_fn(project.id)
+
+    try:
+        health_snap = health_loader_fn(project_id=project.id)
+    except TypeError:
+        try:
+            health_snap = health_loader_fn(project.id)
+        except TypeError:
+            health_snap = health_loader_fn()
+
+    items: list[NotificationItem] = []
+    now_iso = datetime.now(timezone.utc).isoformat()
+
+    # 1. System health alerts (highest priority)
+    for probe_err in getattr(health_snap, "probe_errors", ()):
+        att_cls, req_human = classify_attention_event(
+            CATEGORY_SYSTEM,
+            "System Health Probe Error",
+            probe_err,
+            is_blocker=True,
+        )
+        items.append(
+            NotificationItem(
+                id=f"notif-sys-err-{project.id}",
+                attention_class=att_cls,
+                category=CATEGORY_SYSTEM,
+                title="System Health Error",
+                summary=f"System health error: {probe_err}",
+                work_kind="system",
+                work_number=None,
+                project_id=project.id,
+                repo_label=f"{project.gitea_owner}/{project.repo_name}",
+                created_at=now_iso,
+                deep_link="/system",
+                requires_human=req_human,
+            )
+        )
+
+    for probe in getattr(health_snap, "dependencies", ()):
+        if probe.status not in ("ok", "healthy"):
+            att_cls, req_human = classify_attention_event(
+                CATEGORY_SYSTEM,
+                f"Probe Failure: {probe.name}",
+                probe.detail or probe.status,
+                is_hard_stop=("stop" in probe.status or "fatal" in probe.status),
+                is_auth_failure=("auth" in probe.name.lower() or "unauthorized" in probe.status.lower()),
+                is_blocker=True,
+            )
+            items.append(
+                NotificationItem(
+                    id=f"notif-probe-{probe.name}",
+                    attention_class=att_cls,
+                    category=CATEGORY_AUTH if "auth" in probe.name.lower() else CATEGORY_SYSTEM,
+                    title=f"Health Probe Alert: {probe.name}",
+                    summary=f"Probe '{probe.name}' reported status '{probe.status}': {probe.detail}",
+                    work_kind="system",
+                    work_number=None,
+                    project_id=project.id,
+                    repo_label=f"{project.gitea_owner}/{project.repo_name}",
+                    created_at=now_iso,
+                    deep_link="/system",
+                    requires_human=req_human,
+                )
+            )
+
+    # 2. Queue items (PRs and Issues)
+    for pr in queue_snap.prs:
+        if "blocked" in pr.badges:
+            att_cls, req_human = classify_attention_event(
+                CATEGORY_BLOCKER,
+                f"PR #{pr.number} Blocked",
+                f"PR #{pr.number} '{pr.title}' is blocked or has merge conflicts.",
+                is_blocker=True,
+            )
+            items.append(
+                NotificationItem(
+                    id=f"notif-pr-block-{pr.number}",
+                    attention_class=att_cls,
+                    category=CATEGORY_BLOCKER,
+                    title=f"Blocked PR #{pr.number}",
+                    summary=f"PR #{pr.number} ({pr.title}) requires merge conflict resolution.",
+                    work_kind="pr",
+                    work_number=pr.number,
+                    project_id=project.id,
+                    repo_label=f"{project.gitea_owner}/{project.repo_name}",
+                    created_at=now_iso,
+                    deep_link=f"/traffic",
+                    requires_human=req_human,
+                )
+            )
+        elif "stale" in pr.badges:
+            att_cls, req_human = classify_attention_event(
+                CATEGORY_WORKFLOW,
+                f"PR #{pr.number} Stale",
+                f"PR #{pr.number} '{pr.title}' has had no activity for over 14 days.",
+                is_stale=True,
+            )
+            items.append(
+                NotificationItem(
+                    id=f"notif-pr-stale-{pr.number}",
+                    attention_class=att_cls,
+                    category=CATEGORY_WORKFLOW,
+                    title=f"Stale PR #{pr.number}",
+                    summary=f"PR #{pr.number} ({pr.title}) is stale.",
+                    work_kind="pr",
+                    work_number=pr.number,
+                    project_id=project.id,
+                    repo_label=f"{project.gitea_owner}/{project.repo_name}",
+                    created_at=now_iso,
+                    deep_link=f"/queue",
+                    requires_human=req_human,
+                )
+            )
+        else:
+            # Routine PR transition
+            att_cls, req_human = classify_attention_event(
+                CATEGORY_WORKFLOW,
+                f"PR #{pr.number} Active",
+                f"PR #{pr.number} '{pr.title}' is in routine state {', '.join(pr.badges)}.",
+            )
+            items.append(
+                NotificationItem(
+                    id=f"notif-pr-routine-{pr.number}",
+                    attention_class=att_cls,
+                    category=CATEGORY_WORKFLOW,
+                    title=f"Routine PR #{pr.number}",
+                    summary=f"PR #{pr.number} ({pr.title}) state: {', '.join(pr.badges)}.",
+                    work_kind="pr",
+                    work_number=pr.number,
+                    project_id=project.id,
+                    repo_label=f"{project.gitea_owner}/{project.repo_name}",
+                    created_at=now_iso,
+                    deep_link=f"/queue",
+                    requires_human=req_human,
+                )
+            )
+
+    for issue in queue_snap.issues:
+        if "duplicate" in issue.badges:
+            att_cls, req_human = classify_attention_event(
+                CATEGORY_BLOCKER,
+                f"Issue #{issue.number} Duplicate PRs",
+                f"Issue #{issue.number} has multiple linked PRs.",
+                is_blocker=True,
+            )
+            items.append(
+                NotificationItem(
+                    id=f"notif-issue-dup-{issue.number}",
+                    attention_class=att_cls,
+                    category=CATEGORY_BLOCKER,
+                    title=f"Duplicate PRs on Issue #{issue.number}",
+                    summary=f"Issue #{issue.number} ({issue.title}) linked to multiple PRs.",
+                    work_kind="issue",
+                    work_number=issue.number,
+                    project_id=project.id,
+                    repo_label=f"{project.gitea_owner}/{project.repo_name}",
+                    created_at=now_iso,
+                    deep_link=f"/traffic",
+                    requires_human=req_human,
+                )
+            )
+        elif "claimed" in issue.badges or "in-review" in issue.badges:
+            att_cls, req_human = classify_attention_event(
+                CATEGORY_WORKFLOW,
+                f"Issue #{issue.number} Active",
+                f"Issue #{issue.number} '{issue.title}' in state {', '.join(issue.badges)}.",
+            )
+            items.append(
+                NotificationItem(
+                    id=f"notif-issue-routine-{issue.number}",
+                    attention_class=att_cls,
+                    category=CATEGORY_WORKFLOW,
+                    title=f"Routine Issue #{issue.number}",
+                    summary=f"Issue #{issue.number} ({issue.title}) state: {', '.join(issue.badges)}.",
+                    work_kind="issue",
+                    work_number=issue.number,
+                    project_id=project.id,
+                    repo_label=f"{project.gitea_owner}/{project.repo_name}",
+                    created_at=now_iso,
+                    deep_link=f"/queue",
+                    requires_human=req_human,
+                )
+            )
+
+    # 3. Leases / Collisions
+    for lease in lease_snap.reviewer_leases:
+        if lease.get("is_expired") or lease.get("status") == "expired":
+            pr_num = lease.get("pr_number") or lease.get("work_item_number")
+            att_cls, req_human = classify_attention_event(
+                CATEGORY_LEASE,
+                f"Reviewer Lease Expired for PR #{pr_num}",
+                f"Reviewer lease for PR #{pr_num} has expired.",
+                is_stale=True,
+            )
+            items.append(
+                NotificationItem(
+                    id=f"notif-lease-exp-pr-{pr_num}",
+                    attention_class=att_cls,
+                    category=CATEGORY_LEASE,
+                    title=f"Expired Reviewer Lease (PR #{pr_num})",
+                    summary=f"Reviewer lease for PR #{pr_num} expired.",
+                    work_kind="pr",
+                    work_number=pr_num,
+                    project_id=project.id,
+                    repo_label=f"{project.gitea_owner}/{project.repo_name}",
+                    created_at=now_iso,
+                    deep_link="/leases",
+                    requires_human=req_human,
+                )
+            )
+
+    for collision in lease_snap.duplicate_prs:
+        att_cls, req_human = classify_attention_event(
+            CATEGORY_BLOCKER,
+            f"Duplicate PR Collision ({collision.kind})",
+            collision.message,
+            is_blocker=True,
+        )
+        items.append(
+            NotificationItem(
+                id=f"notif-collision-{collision.issue_number or 0}",
+                attention_class=att_cls,
+                category=CATEGORY_BLOCKER,
+                title=f"Collision Alert ({collision.kind})",
+                summary=collision.message,
+                work_kind="issue" if collision.issue_number else "pr",
+                work_number=collision.issue_number,
+                project_id=project.id,
+                repo_label=f"{project.gitea_owner}/{project.repo_name}",
+                created_at=now_iso,
+                deep_link="/leases",
+                requires_human=req_human,
+            )
+        )
+
+    human_req_count = sum(1 for i in items if i.attention_class == ATTENTION_HUMAN_REQUIRED)
+    operator_count = sum(1 for i in items if i.attention_class == ATTENTION_OPERATOR)
+    routine_count = sum(1 for i in items if i.attention_class == ATTENTION_ROUTINE)
+
+    fetch_err = queue_snap.fetch_error or lease_snap.fetch_error or getattr(health_snap, "probe_errors", None)
+    if isinstance(fetch_err, (tuple, list)):
+        fetch_err = "; ".join(fetch_err) if fetch_err else None
+
+    return NotificationSnapshot(
+        project_id=project.id,
+        repo_label=f"{project.gitea_owner}/{project.repo_name}",
+        items=tuple(items),
+        human_required_count=human_req_count,
+        operator_count=operator_count,
+        routine_count=routine_count,
+        total_count=len(items),
+        fetch_error=fetch_err,
+    )
+
+
+def snapshot_to_dict(snapshot: NotificationSnapshot) -> dict[str, Any]:
+    """JSON-serializable export for /api/v1/notifications."""
+    return snapshot.as_dict()