Merge remote-tracking branch 'prgs/master' into feat/issue-648-notifications-console

B1: classify_attention_event uses structured flags/category only — never
substring-match human-authored title/summary for escalation.

B2: make notification ids unique across probe_errors and collisions
(include loop index / kind).

B3: do not assign probe_errors to fetch_error (avoids false Fetch Warning
and double-reporting).

Regression tests cover all three blockers.

Refs #648

docs/mcp-config-drift-runbook.md

@@ -1,70 +0,0 @@
-# MCP Config Drift Diagnostic & Sanctioned Repair Runbook (#672)
-
-This document describes the diagnostic framework for detecting configuration drift between the active IDE MCP configuration (`~/.gemini/antigravity-ide/mcp_config.json`) and the offline/global canonical configuration (`~/.gemini/config/mcp_config.json`), and establishes the **sanctioned repair runbook**.
-
-## Background & Problem Statement
-
-Offline tools like `test_mcp_conn.py` test the global configuration (`~/.gemini/config/mcp_config.json`) via `subprocess.Popen`. However, the active IDE/client namespace uses `~/.gemini/antigravity-ide/mcp_config.json`. When required Gitea role servers (`gitea-author`, `gitea-reviewer`, `gitea-merger`, `gitea-reconciler`, `gitea-controller`, `gitea-tools`) are missing or carry mismatched profile environments in the active IDE config:
-
-1. Offline tests pass (`test_mcp_conn.py` green).
-2. The IDE client returns `EOF` / `transport closed` when attempting role-scoped mutations.
-3. Operators misdiagnose missing server definitions as stale runtimes, leading to forbidden `pkill` attempts (#630) or `mtime` hacks (#655).
-
-## Diagnostic Tool: `mcp_config_drift.py`
-
-Run the diagnostic tool directly to compare configurations:
-
-```bash
-python3 mcp_config_drift.py --json
-```
-
-Or specify custom config locations:
-
-```bash
-python3 mcp_config_drift.py \
-  --active-config ~/.gemini/antigravity-ide/mcp_config.json \
-  --global-config ~/.gemini/config/mcp_config.json
-```
-
-### Key Diagnostic Outputs
-
-- `in_sync`: Boolean indicating if all required Gitea role servers exist in the active IDE config with matching profile declarations.
-- `missing_role_servers`: List of role servers present in global config but missing from active IDE config.
-- `profile_mismatches`: List of profile environment mismatches per server.
-- `reasons`: Explicit, human-readable list of drift causes.
-
-All returned payloads automatically redact secret tokens, DSNs, Authorization headers, and private keys.
-
----
-
-## Sanctioned Repair Path (Step-by-Step)
-
-When `mcp_config_drift.py` reports drift (`in_sync: false`), execute the following **sanctioned repair steps**:
-
-1. **Backup Active IDE Config:**
-   ```bash
-   cp ~/.gemini/antigravity-ide/mcp_config.json ~/.gemini/antigravity-ide/mcp_config.json.bak
-   ```
-2. **Patch Active IDE Config:**
-   Copy the missing Gitea role server JSON blocks (`gitea-author`, `gitea-reviewer`, etc.) from `~/.gemini/config/mcp_config.json` into `~/.gemini/antigravity-ide/mcp_config.json`.
-3. **Reconnect via IDE/Client:**
-   Use the IDE / client UI reconnection control (or restart the IDE client app).
-4. **Verify Active Namespace Health:**
-   Invoke `gitea_whoami` (and optional `gitea_resolve_task_capability`) through the active IDE client on each required role namespace.
-
----
-
-## FORBIDDEN Repair Actions (#630 / #655)
-
-The following actions are **strictly forbidden** for config drift repair:
-
-- ❌ **`pkill` or manual daemon process kill commands:** Process kills cause contamination and break active session leases.
-- ❌ **`mtime` touch edits:** Artificial mtime modifications mask stale runtimes without updating configuration.
-- ❌ **Source code edits:** Mutating python tool logic to bypass missing server entries.
-- ❌ **Session-state edits:** Direct database or lock-file state mutation.
-
----
-
-## Final Report Guidelines
-
-A workflow final report **must not** rely on offline `test_mcp_conn.py` output alone. Final reports must include active-config evidence from live `gitea_whoami` calls on the active IDE namespaces.

docs/webui-notifications.md

@@ -0,0 +1,81 @@
+# Web Console: Notifications & Human-Attention Routing (#648)
+
+- **Status:** Phase 3 Live
+- **Tracking Issue:** [#648](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/648)
+- **Parent Epic:** [#631](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/631)
+- **Attention Boundary Reference:** [#628](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/628)
+
+---
+
+## 1. Overview
+
+The **Notifications & Human-Attention Console** (`/notifications`, `/api/v1/notifications`) provides intelligent event classification and human-attention routing for autonomous workflow operations.
+
+To prevent alert fatigue while ensuring critical escalation boundaries are never missed, events are classified into three distinct **Attention Classes**:
+
+1. **`human-required`** (Urgent Escalation Boundary):
+   - Items requiring immediate human intervention or business decisions.
+   - Triggers: Auth failures, hard stops, irrecoverable state, decision locks, failed report validations, critical probe errors.
+   - Display: Highlighted in red (`badge-blocked`) with a `HUMAN REQUIRED` badge.
+
+2. **`operator`** (Operational Inbox):
+   - Items requiring controller or operator review/triage during routine execution.
+   - Triggers: Blocked PRs (merge conflicts), stale leases, duplicate PRs on issues, unassigned ready work.
+   - Display: Displayed in orange/yellow (`badge-claimed`).
+
+3. **`routine`** (Background Workflow Transitions):
+   - Normal, healthy workflow transitions and state progressions.
+   - Triggers: Active PRs/issues in standard state, clean branch creation, routine heartbeats.
+   - Display: Filtered out of default inbox views to eliminate notification spam; viewable on demand via the "Routine" or "All" tab.
+
+---
+
+## 2. API Endpoints
+
+### `GET /api/v1/notifications`
+*Compatibility Alias:* `GET /api/notifications`
+
+#### Query Parameters:
+- `project_id` (optional): Filter notifications by project ID.
+- `attention_class` (optional): `inbox` (default: human-required + operator), `human-required`, `operator`, `routine`, `all`.
+
+#### Example JSON Response:
+```json
+{
+  "project_id": "gitea-tools",
+  "repo_label": "Scaled-Tech-Consulting/Gitea-Tools",
+  "human_required_count": 0,
+  "operator_count": 2,
+  "routine_count": 5,
+  "total_count": 7,
+  "fetch_error": null,
+  "inbox_items": [
+    {
+      "id": "notif-pr-block-742",
+      "attention_class": "operator",
+      "category": "blocker",
+      "title": "Blocked PR #742",
+      "summary": "PR #742 requires merge conflict resolution.",
+      "work_kind": "pr",
+      "work_number": 742,
+      "project_id": "gitea-tools",
+      "repo_label": "Scaled-Tech-Consulting/Gitea-Tools",
+      "created_at": "2026-07-25T16:39:47Z",
+      "deep_link": "/traffic",
+      "requires_human": false,
+      "extra": {}
+    }
+  ],
+  "all_items": [...]
+}
+```
+
+---
+
+## 3. UI Navigation
+
+- Access via the **Traffic** navigation menu: **Traffic → Notifications**.
+- The main view displays:
+  - **Metrics Summary Bar**: Highlighting counts for Human Required, Operator Inbox, and Routine items.
+  - **Attention Filter Tabs**: Toggle between Inbox (Human + Operator), Human Required, Operator, Routine, and All.
+  - **Structured Event Table**: Displays category, title, summary, work item links, and timestamps.

mcp_config_drift.py

@@ -1,237 +0,0 @@
-"""Antigravity IDE vs Global MCP Config Drift Diagnostic (#672).
-
-Diagnoses config drift between the active IDE MCP configuration
-(e.g. ``~/.gemini/antigravity-ide/mcp_config.json``) and the offline/global
-canonical configuration (e.g. ``~/.gemini/config/mcp_config.json``).
-
-Hard rules (#672 / #630 / #655):
-* Distinguish offline/global success from active IDE namespace availability.
-* Never print tokens, DSNs, Authorization headers, or secret-bearing env vars.
-* Sanctioned repair path is: backup active config -> patch active config from canonical
-  -> reconnect through IDE/client -> verify with live ``gitea_whoami``.
-* FORBIDDEN: ``pkill``, mtime edits, source edits, or session-state edits for repair.
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import sys
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Any
-
-from webui import console_redaction
-
-DEFAULT_ACTIVE_IDE_CONFIG = "~/.gemini/antigravity-ide/mcp_config.json"
-DEFAULT_GLOBAL_CONFIG = "~/.gemini/config/mcp_config.json"
-
-REQUIRED_GITEA_ROLE_SERVERS = (
-    "gitea-author",
-    "gitea-reviewer",
-    "gitea-merger",
-    "gitea-reconciler",
-    "gitea-controller",
-    "gitea-tools",
-)
-
-SANCTIONED_REPAIR_RUNBOOK: tuple[str, ...] = (
-    "1. Backup active IDE config: cp ~/.gemini/antigravity-ide/mcp_config.json ~/.gemini/antigravity-ide/mcp_config.json.bak",
-    "2. Patch active IDE config: copy required missing Gitea role server entries from global config (~/.gemini/config/mcp_config.json) into active IDE config.",
-    "3. Reconnect via IDE/client UI or client restart (do NOT use host process kill).",
-    "4. Verify active namespace health using live gitea_whoami and gitea_resolve_task_capability on each role namespace.",
-    "FORBIDDEN REPAIR PATHS: pkill / host process kill, mtime touch edits, source code edits, or session-state edits.",
-)
-
-
-def resolve_config_path(path_str: str) -> Path:
-    """Expand user and resolve absolute path."""
-    return Path(os.path.expanduser(path_str)).resolve()
-
-
-def load_mcp_config(config_path: str | Path) -> tuple[dict[str, Any] | None, str | None]:
-    """Load and parse JSON MCP configuration from file.
-
-    Returns (config_dict, error_message).
-    """
-    resolved = resolve_config_path(str(config_path))
-    if not resolved.exists():
-        return None, f"file_not_found: {resolved}"
-    try:
-        with open(resolved, "r", encoding="utf-8") as f:
-            data = json.load(f)
-        if not isinstance(data, dict):
-            return None, f"invalid_schema: root is not a JSON object in {resolved}"
-        return data, None
-    except Exception as exc:
-        return None, f"unreadable_json: {exc} in {resolved}"
-
-
-def extract_mcp_servers(config: dict[str, Any] | None) -> dict[str, dict[str, Any]]:
-    """Extract the mcpServers or mcp_servers mapping safely."""
-    if not config:
-        return {}
-    servers = config.get("mcpServers") or config.get("mcp_servers") or {}
-    if isinstance(servers, dict):
-        return {str(k): v for k, v in servers.items() if isinstance(v, dict)}
-    return {}
-
-
-def _safe_redact_server_config(srv_cfg: dict[str, Any]) -> dict[str, Any]:
-    """Redact secrets from environment variables and command line args."""
-    safe = {}
-    if "command" in srv_cfg:
-        safe["command"] = str(srv_cfg["command"])
-    if "args" in srv_cfg and isinstance(srv_cfg["args"], list):
-        safe["args"] = [console_redaction.redact_text(str(a)) for a in srv_cfg["args"]]
-    if "env" in srv_cfg and isinstance(srv_cfg["env"], dict):
-        safe_env = {}
-        for k, v in srv_cfg["env"].items():
-            if any(secret_kw in k.lower() for secret_kw in ("token", "secret", "pass", "key", "auth")):
-                safe_env[k] = "[REDACTED]"
-            else:
-                safe_env[k] = console_redaction.redact_text(str(v))
-        safe["env"] = safe_env
-    return safe
-
-
-def analyze_config_drift(
-    active_config_path: str = DEFAULT_ACTIVE_IDE_CONFIG,
-    global_config_path: str = DEFAULT_GLOBAL_CONFIG,
-) -> dict[str, Any]:
-    """Analyze MCP configuration drift between active IDE config and global config.
-
-    Returns structured diagnostic output.
-    """
-    active_resolved = resolve_config_path(active_config_path)
-    global_resolved = resolve_config_path(global_config_path)
-
-    active_cfg, active_err = load_mcp_config(active_resolved)
-    global_cfg, global_err = load_mcp_config(global_resolved)
-
-    active_servers = extract_mcp_servers(active_cfg)
-    global_servers = extract_mcp_servers(global_cfg)
-
-    missing_role_servers: list[str] = []
-    present_role_servers: list[str] = []
-    profile_mismatches: list[dict[str, Any]] = []
-    reasons: list[str] = []
-
-    if active_err:
-        reasons.append(f"Active IDE config error: {active_err}")
-    if global_err:
-        reasons.append(f"Global canonical config error: {global_err}")
-
-    # Check Gitea role servers
-    for srv_name in REQUIRED_GITEA_ROLE_SERVERS:
-        in_active = srv_name in active_servers
-        in_global = srv_name in global_servers
-
-        if in_active:
-            present_role_servers.append(srv_name)
-        elif in_global:
-            missing_role_servers.append(srv_name)
-            reasons.append(
-                f"Missing Gitea role server '{srv_name}' in active IDE config ({active_resolved})"
-            )
-
-        if in_active and in_global:
-            # Compare profiles & environments
-            act_env = active_servers[srv_name].get("env", {}) if isinstance(active_servers[srv_name], dict) else {}
-            glo_env = global_servers[srv_name].get("env", {}) if isinstance(global_servers[srv_name], dict) else {}
-
-            act_prof = act_env.get("GITEA_MCP_PROFILE") or act_env.get("GITEA_PROFILE_NAME")
-            glo_prof = glo_env.get("GITEA_MCP_PROFILE") or glo_env.get("GITEA_PROFILE_NAME")
-
-            if act_prof != glo_prof:
-                mismatch_item = {
-                    "server": srv_name,
-                    "active_profile": act_prof,
-                    "global_profile": glo_prof,
-                }
-                profile_mismatches.append(mismatch_item)
-                reasons.append(
-                    f"Profile mismatch for '{srv_name}': active='{act_prof}' != global='{glo_prof}'"
-                )
-
-    in_sync = bool(
-        not active_err
-        and not global_err
-        and not missing_role_servers
-        and not profile_mismatches
-    )
-
-    report = {
-        "timestamp": datetime.now(timezone.utc).isoformat(),
-        "in_sync": in_sync,
-        "active_config_path": str(active_resolved),
-        "active_config_exists": active_cfg is not None,
-        "global_config_path": str(global_resolved),
-        "global_config_exists": global_cfg is not None,
-        "required_role_servers": list(REQUIRED_GITEA_ROLE_SERVERS),
-        "present_role_servers": present_role_servers,
-        "missing_role_servers": missing_role_servers,
-        "profile_mismatches": profile_mismatches,
-        "reasons": reasons,
-        "sanctioned_repair_runbook": list(SANCTIONED_REPAIR_RUNBOOK),
-        "forbidden_repair_methods": [
-            "pkill / host process kill",
-            "mtime touch edits",
-            "source code edits",
-            "session-state edits",
-        ],
-    }
-
-    return console_redaction.redact_payload(report)
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(
-        description="Diagnose Gitea MCP role server config drift between active IDE and global config."
-    )
-    parser.add_argument(
-        "--active-config",
-        default=DEFAULT_ACTIVE_IDE_CONFIG,
-        help="Path to active IDE MCP config JSON",
-    )
-    parser.add_argument(
-        "--global-config",
-        default=DEFAULT_GLOBAL_CONFIG,
-        help="Path to global/canonical MCP config JSON",
-    )
-    parser.add_argument(
-        "--json", action="store_true", help="Print raw JSON report"
-    )
-
-    args = parser.parse_args()
-
-    report = analyze_config_drift(args.active_config, args.global_config)
-
-    if args.json:
-        print(json.dumps(report, indent=2))
-    else:
-        print("=== MCP Config Drift Diagnostic Report ===")
-        print(f"Timestamp: {report['timestamp']}")
-        print(f"In Sync: {report['in_sync']}")
-        print(f"Active IDE Config: {report['active_config_path']} (exists={report['active_config_exists']})")
-        print(f"Global Config: {report['global_config_path']} (exists={report['global_config_exists']})")
-        print(f"Present Role Servers: {', '.join(report['present_role_servers']) if report['present_role_servers'] else 'None'}")
-        print(f"Missing Role Servers: {', '.join(report['missing_role_servers']) if report['missing_role_servers'] else 'None'}")
-        if report['profile_mismatches']:
-            print("Profile Mismatches:")
-            for m in report['profile_mismatches']:
-                print(f"  - {m['server']}: active={m['active_profile']} vs global={m['global_profile']}")
-        if report['reasons']:
-            print("Drift Reasons:")
-            for r in report['reasons']:
-                print(f"  - {r}")
-        print("\nSanctioned Repair Runbook:")
-        for step in report['sanctioned_repair_runbook']:
-            print(f"  {step}")
-
-    sys.exit(0 if report["in_sync"] else 1)
-
-
-if __name__ == "__main__":
-    main()

tests/test_mcp_config_drift.py

@@ -1,149 +0,0 @@
-"""Unit tests for mcp_config_drift.py (#672)."""
-
-from __future__ import annotations
-
-import json
-import pytest
-from pathlib import Path
-
-from mcp_config_drift import (
-    REQUIRED_GITEA_ROLE_SERVERS,
-    analyze_config_drift,
-    load_mcp_config,
-)
-
-
-@pytest.fixture
-def sample_global_config() -> dict:
-    return {
-        "mcpServers": {
-            "gitea-author": {
-                "command": "python3",
-                "args": ["gitea_mcp_server.py"],
-                "env": {"GITEA_MCP_PROFILE": "prgs-author", "SENTRY_AUTH_TOKEN": "secret-token-999"},
-            },
-            "gitea-reviewer": {
-                "command": "python3",
-                "args": ["gitea_mcp_server.py"],
-                "env": {"GITEA_MCP_PROFILE": "prgs-reviewer"},
-            },
-            "gitea-merger": {
-                "command": "python3",
-                "args": ["gitea_mcp_server.py"],
-                "env": {"GITEA_MCP_PROFILE": "prgs-merger"},
-            },
-            "gitea-reconciler": {
-                "command": "python3",
-                "args": ["gitea_mcp_server.py"],
-                "env": {"GITEA_MCP_PROFILE": "prgs-reconciler"},
-            },
-            "gitea-controller": {
-                "command": "python3",
-                "args": ["gitea_mcp_server.py"],
-                "env": {"GITEA_MCP_PROFILE": "prgs-controller"},
-            },
-            "gitea-tools": {
-                "command": "python3",
-                "args": ["gitea_mcp_server.py"],
-                "env": {"GITEA_MCP_PROFILE": "prgs-author"},
-            },
-        }
-    }
-
-
-def write_json(path: Path, data: dict) -> str:
-    path.write_text(json.dumps(data, indent=2), encoding="utf-8")
-    return str(path)
-
-
-def test_drift_detection_in_sync(tmp_path, sample_global_config):
-    glob_file = tmp_path / "global_mcp.json"
-    act_file = tmp_path / "active_mcp.json"
-
-    write_json(glob_file, sample_global_config)
-    write_json(act_file, sample_global_config)
-
-    report = analyze_config_drift(active_config_path=str(act_file), global_config_path=str(glob_file))
-
-    assert report["in_sync"] is True
-    assert report["missing_role_servers"] == []
-    assert report["profile_mismatches"] == []
-    assert set(report["present_role_servers"]) == set(REQUIRED_GITEA_ROLE_SERVERS)
-
-
-def test_drift_detection_missing_author(tmp_path, sample_global_config):
-    glob_file = tmp_path / "global_mcp.json"
-    act_file = tmp_path / "active_mcp.json"
-
-    active_config = json.loads(json.dumps(sample_global_config))
-    del active_config["mcpServers"]["gitea-author"]
-
-    write_json(glob_file, sample_global_config)
-    write_json(act_file, active_config)
-
-    report = analyze_config_drift(active_config_path=str(act_file), global_config_path=str(glob_file))
-
-    assert report["in_sync"] is False
-    assert "gitea-author" in report["missing_role_servers"]
-    assert "gitea-author" not in report["present_role_servers"]
-
-
-def test_drift_detection_missing_reviewer(tmp_path, sample_global_config):
-    glob_file = tmp_path / "global_mcp.json"
-    act_file = tmp_path / "active_mcp.json"
-
-    active_config = json.loads(json.dumps(sample_global_config))
-    del active_config["mcpServers"]["gitea-reviewer"]
-
-    write_json(glob_file, sample_global_config)
-    write_json(act_file, active_config)
-
-    report = analyze_config_drift(active_config_path=str(act_file), global_config_path=str(glob_file))
-
-    assert report["in_sync"] is False
-    assert "gitea-reviewer" in report["missing_role_servers"]
-
-
-def test_drift_detection_profile_mismatch(tmp_path, sample_global_config):
-    glob_file = tmp_path / "global_mcp.json"
-    act_file = tmp_path / "active_mcp.json"
-
-    active_config = json.loads(json.dumps(sample_global_config))
-    active_config["mcpServers"]["gitea-author"]["env"]["GITEA_MCP_PROFILE"] = "dadeschools-author"
-
-    write_json(glob_file, sample_global_config)
-    write_json(act_file, active_config)
-
-    report = analyze_config_drift(active_config_path=str(act_file), global_config_path=str(glob_file))
-
-    assert report["in_sync"] is False
-    assert len(report["profile_mismatches"]) == 1
-    mismatch = report["profile_mismatches"][0]
-    assert mismatch["server"] == "gitea-author"
-    assert mismatch["active_profile"] == "dadeschools-author"
-    assert mismatch["global_profile"] == "prgs-author"
-
-
-def test_secret_redaction_in_drift_report(tmp_path, sample_global_config):
-    glob_file = tmp_path / "global_mcp.json"
-    act_file = tmp_path / "active_mcp.json"
-
-    write_json(glob_file, sample_global_config)
-    write_json(act_file, sample_global_config)
-
-    report = analyze_config_drift(active_config_path=str(act_file), global_config_path=str(glob_file))
-    serialized = str(report)
-
-    assert "secret-token-999" not in serialized
-
-
-def test_sanctioned_runbook_forbids_pkill():
-    report = analyze_config_drift(active_config_path="/nonexistent/path/active.json", global_config_path="/nonexistent/path/global.json")
-
-    runbook_text = " ".join(report["sanctioned_repair_runbook"]).lower()
-    forbidden_text = " ".join(report["forbidden_repair_methods"]).lower()
-
-    assert "pkill" in forbidden_text
-    assert "mtime" in forbidden_text
-    assert "source" in forbidden_text
-    assert "session-state" in forbidden_text

tests/test_webui_notifications.py

@@ -0,0 +1,465 @@
+"""Unit tests for Phase 3 Notifications and Human-Attention Console (#648)."""
+
+from __future__ import annotations
+
+import pytest
+from starlette.testclient import TestClient
+
+from webui.app import create_app
+from webui.notifications import (
+    ATTENTION_HUMAN_REQUIRED,
+    ATTENTION_OPERATOR,
+    ATTENTION_ROUTINE,
+    CATEGORY_AUTH,
+    CATEGORY_BLOCKER,
+    CATEGORY_LEASE,
+    CATEGORY_SYSTEM,
+    CATEGORY_VALIDATION,
+    CATEGORY_WORKFLOW,
+    NotificationItem,
+    NotificationSnapshot,
+    classify_attention_event,
+    load_notifications_snapshot,
+    snapshot_to_dict,
+)
+from webui.notification_views import render_notifications_page
+from webui.project_registry import load_registry
+from webui.queue_loader import QueueItem, QueueSnapshot
+from webui.lease_loader import CollisionWarning, LeaseSnapshot
+from webui.system_health import DependencyProbe, SystemHealthSnapshot, VersionInfo, StaleRuntime
+
+
+def test_classify_attention_event_rules():
+    # 1. Critical escalation boundaries -> human-required
+    att_cls, req_human = classify_attention_event(
+        CATEGORY_AUTH, "Auth error", "Unauthorized access attempt", is_auth_failure=True
+    )
+    assert att_cls == ATTENTION_HUMAN_REQUIRED
+    assert req_human is True
+
+    att_cls, req_human = classify_attention_event(
+        CATEGORY_SYSTEM, "Hard stop", "Hard stop triggered", is_hard_stop=True
+    )
+    assert att_cls == ATTENTION_HUMAN_REQUIRED
+    assert req_human is True
+
+    att_cls, req_human = classify_attention_event(
+        CATEGORY_VALIDATION, "Validation Error", "Report validation failed", is_validation_failure=True
+    )
+    assert att_cls == ATTENTION_HUMAN_REQUIRED
+    assert req_human is True
+
+    # 2. Operational issues -> operator
+    att_cls, req_human = classify_attention_event(
+        CATEGORY_BLOCKER, "PR Blocked", "Merge conflict detected", is_blocker=True
+    )
+    assert att_cls == ATTENTION_OPERATOR
+    assert req_human is False
+
+    att_cls, req_human = classify_attention_event(
+        CATEGORY_LEASE, "Lease Expired", "Session lease expired", is_stale=True
+    )
+    assert att_cls == ATTENTION_OPERATOR
+    assert req_human is False
+
+    # 3. Routine workflow transitions -> routine
+    att_cls, req_human = classify_attention_event(
+        CATEGORY_WORKFLOW, "PR Active", "PR in review"
+    )
+    assert att_cls == ATTENTION_ROUTINE
+    assert req_human is False
+
+
+def test_notification_snapshot_aggregation():
+    reg = load_registry()
+    proj_id = reg.projects[0].id if reg.projects else "gitea-tools"
+
+    mock_queue = QueueSnapshot(
+        project_id=proj_id,
+        repo_label="org/repo",
+        prs=(
+            QueueItem(
+                number=101,
+                title="Blocked PR",
+                badges=("blocked",),
+                extra={},
+            ),
+            QueueItem(
+                number=102,
+                title="Normal PR",
+                badges=("in-review",),
+                extra={},
+            ),
+        ),
+        issues=(),
+        pr_pagination=None,
+        issue_pagination=None,
+    )
+
+    mock_leases = LeaseSnapshot(
+        project_id=proj_id,
+        repo_label="org/repo",
+        issue_lock=None,
+        claim_inventory={},
+        reviewer_leases=(
+            {
+                "pr_number": 101,
+                "status": "expired",
+                "is_expired": True,
+            },
+        ),
+        duplicate_prs=(
+            CollisionWarning(
+                kind="duplicate_pr",
+                message="Multiple open PRs for issue #101",
+                issue_number=101,
+                pr_numbers=(101, 103),
+            ),
+        ),
+        duplicate_branches=(),
+        collision_history=(),
+        fetch_error=None,
+    )
+
+    mock_version = VersionInfo(
+        git_sha="abc1234",
+        git_describe="v1.0.0",
+        control_plane_schema_version=1,
+        python_version="3.11",
+        known=True,
+    )
+
+    mock_stale = StaleRuntime(
+        daemon_head="abc1234",
+        checkout_head="abc1234",
+        remote_head="abc1234",
+        stale=False,
+        determinable=True,
+        mutation_safe=True,
+        reasons=(),
+    )
+
+    mock_health = SystemHealthSnapshot(
+        status="degraded",
+        ready=False,
+        readiness_complete=True,
+        readiness_reasons=("Auth failure",),
+        service="webui",
+        mode="test",
+        version=mock_version,
+        started_at="2026-07-25T00:00:00Z",
+        uptime_seconds=100.0,
+        timestamp="2026-07-25T00:00:00Z",
+        deep_probes_requested=True,
+        dependencies=(
+            DependencyProbe(
+                name="auth_service",
+                kind="auth",
+                status="unauthorized",
+                detail="Token expired",
+                required=True,
+            ),
+        ),
+        mcp_namespaces=(),
+        stale_runtime=mock_stale,
+        probe_errors=(),
+    )
+
+    snapshot = load_notifications_snapshot(
+        proj_id,
+        load_queue=lambda _id: mock_queue,
+        load_leases=lambda **_kwargs: mock_leases,
+        load_health=lambda **_kwargs: mock_health,
+    )
+
+    assert snapshot.project_id == proj_id
+    assert snapshot.total_count == 5
+    assert snapshot.human_required_count >= 1  # auth probe failure
+    assert snapshot.operator_count >= 3  # blocked PR + expired lease + duplicate PR collision
+    assert snapshot.routine_count >= 1  # normal PR
+
+    # Inbox items should include operator and human-required items only
+    inbox_classes = {item.attention_class for item in snapshot.inbox_items}
+    assert ATTENTION_ROUTINE not in inbox_classes
+    assert ATTENTION_OPERATOR in inbox_classes
+    assert ATTENTION_HUMAN_REQUIRED in inbox_classes
+
+
+def test_snapshot_to_dict_and_redaction():
+    item = NotificationItem(
+        id="notif-1",
+        attention_class=ATTENTION_HUMAN_REQUIRED,
+        category=CATEGORY_AUTH,
+        title="Auth Error",
+        summary="Failed auth header: Bearer secret_token_12345",
+        work_kind="system",
+        work_number=None,
+        project_id="test-proj",
+        repo_label="org/repo",
+        created_at="2026-07-25T16:00:00Z",
+        requires_human=True,
+    )
+    snap = NotificationSnapshot(
+        project_id="test-proj",
+        repo_label="org/repo",
+        items=(item,),
+        human_required_count=1,
+        operator_count=0,
+        routine_count=0,
+        total_count=1,
+    )
+
+    data = snapshot_to_dict(snap)
+    assert data["project_id"] == "test-proj"
+    assert data["human_required_count"] == 1
+    assert len(data["inbox_items"]) == 1
+
+    # Redaction test
+    summary = data["inbox_items"][0]["summary"]
+    assert "secret_token_12345" not in summary
+    assert "<redacted>" in summary or "Bearer" in summary
+
+
+def test_notifications_html_views():
+    item = NotificationItem(
+        id="notif-1",
+        attention_class=ATTENTION_HUMAN_REQUIRED,
+        category=CATEGORY_AUTH,
+        title="Critical Auth Failure",
+        summary="Auth failure details",
+        work_kind="issue",
+        work_number=42,
+        project_id="test-proj",
+        repo_label="org/repo",
+        created_at="2026-07-25T16:00:00Z",
+        requires_human=True,
+    )
+    snap = NotificationSnapshot(
+        project_id="test-proj",
+        repo_label="org/repo",
+        items=(item,),
+        human_required_count=1,
+        operator_count=0,
+        routine_count=0,
+        total_count=1,
+    )
+
+    html = render_notifications_page(snap, filter_class="inbox")
+    assert "Notifications &amp; Attention Inbox" in html or "Notifications & Attention Inbox" in html
+    assert "Critical Auth Failure" in html
+    assert "HUMAN REQUIRED" in html
+    assert "Human Required" in html
+
+
+def test_notifications_app_routes():
+    app = create_app()
+    client = TestClient(app)
+
+    # 1. HTML Route
+    res = client.get("/notifications")
+    assert res.status_code == 200
+    assert "Notifications" in res.text
+    assert "Attention Inbox" in res.text
+
+    # 2. API Route /api/v1/notifications
+    res_api = client.get("/api/v1/notifications")
+    assert res_api.status_code == 200
+    json_data = res_api.json()
+    assert "human_required_count" in json_data
+    assert "operator_count" in json_data
+    assert "routine_count" in json_data
+    assert "inbox_items" in json_data
+
+    # 3. Compatibility Alias /api/notifications
+    res_alias = client.get("/api/notifications")
+    assert res_alias.status_code == 200
+    assert res_alias.json()["project_id"] == json_data["project_id"]
+
+
+def test_classify_ignores_human_authored_title_and_summary_keywords():
+    """B1: keywords in human-authored titles must not escalate routine work (#905)."""
+    # Routine transition whose title/summary mention critical-boundary words
+    att_cls, req_human = classify_attention_event(
+        CATEGORY_WORKFLOW,
+        "record irrecoverable decision lock provenance",
+        "PR #999 'record irrecoverable decision lock provenance' is in routine state in-review.",
+    )
+    assert att_cls == ATTENTION_ROUTINE
+    assert req_human is False
+
+    att_cls, req_human = classify_attention_event(
+        CATEGORY_WORKFLOW,
+        "fix unauthorized token path",
+        "Issue #1 'fix unauthorized token path' state: claimed. hard stop docs only.",
+    )
+    assert att_cls == ATTENTION_ROUTINE
+    assert req_human is False
+
+    # Structured flags still escalate (machine-driven)
+    att_cls, req_human = classify_attention_event(
+        CATEGORY_SYSTEM,
+        "anything",
+        "anything with hard stop in text",
+        is_hard_stop=True,
+    )
+    assert att_cls == ATTENTION_HUMAN_REQUIRED
+    assert req_human is True
+
+
+def test_notification_ids_are_unique_across_probe_errors_and_collisions():
+    """B2: published notification ids must be unique within a snapshot (#905)."""
+    reg = load_registry()
+    proj_id = reg.projects[0].id if reg.projects else "gitea-tools"
+
+    mock_queue = QueueSnapshot(
+        project_id=proj_id,
+        repo_label="org/repo",
+        prs=(),
+        issues=(),
+        pr_pagination=None,
+        issue_pagination=None,
+    )
+    mock_leases = LeaseSnapshot(
+        project_id=proj_id,
+        repo_label="org/repo",
+        issue_lock=None,
+        claim_inventory={},
+        reviewer_leases=(),
+        duplicate_prs=(
+            CollisionWarning(
+                kind="duplicate_pr",
+                message="Multiple open PRs for issue #10",
+                issue_number=10,
+                pr_numbers=(10, 11),
+            ),
+            CollisionWarning(
+                kind="duplicate_branch",
+                message="Another collision without issue",
+                issue_number=None,
+                pr_numbers=(12, 13),
+            ),
+            CollisionWarning(
+                kind="duplicate_pr",
+                message="Second issue collision",
+                issue_number=10,
+                pr_numbers=(14, 15),
+            ),
+        ),
+        duplicate_branches=(),
+        collision_history=(),
+        fetch_error=None,
+    )
+    mock_version = VersionInfo(
+        git_sha="abc1234",
+        git_describe="v1.0.0",
+        control_plane_schema_version=1,
+        python_version="3.11",
+        known=True,
+    )
+    mock_stale = StaleRuntime(
+        daemon_head="abc1234",
+        checkout_head="abc1234",
+        remote_head="abc1234",
+        stale=False,
+        determinable=True,
+        mutation_safe=True,
+        reasons=(),
+    )
+    mock_health = SystemHealthSnapshot(
+        status="degraded",
+        ready=False,
+        readiness_complete=True,
+        readiness_reasons=(),
+        service="webui",
+        mode="test",
+        version=mock_version,
+        started_at="2026-07-25T00:00:00Z",
+        uptime_seconds=100.0,
+        timestamp="2026-07-25T00:00:00Z",
+        deep_probes_requested=True,
+        dependencies=(),
+        mcp_namespaces=(),
+        stale_runtime=mock_stale,
+        probe_errors=("error alpha", "error beta"),
+    )
+
+    snapshot = load_notifications_snapshot(
+        proj_id,
+        load_queue=lambda _id: mock_queue,
+        load_leases=lambda **_kwargs: mock_leases,
+        load_health=lambda **_kwargs: mock_health,
+    )
+    ids = [item.id for item in snapshot.items]
+    assert len(ids) == len(set(ids)), f"duplicate notification ids: {ids}"
+    assert any(i.startswith(f"notif-sys-err-{proj_id}-") for i in ids)
+    assert any(i.startswith("notif-collision-") for i in ids)
+
+
+def test_probe_errors_do_not_set_fetch_error():
+    """B3: probe_errors must not be reported as fetch_error (#905)."""
+    reg = load_registry()
+    proj_id = reg.projects[0].id if reg.projects else "gitea-tools"
+
+    mock_queue = QueueSnapshot(
+        project_id=proj_id,
+        repo_label="org/repo",
+        prs=(),
+        issues=(),
+        pr_pagination=None,
+        issue_pagination=None,
+        fetch_error=None,
+    )
+    mock_leases = LeaseSnapshot(
+        project_id=proj_id,
+        repo_label="org/repo",
+        issue_lock=None,
+        claim_inventory={},
+        reviewer_leases=(),
+        duplicate_prs=(),
+        duplicate_branches=(),
+        collision_history=(),
+        fetch_error=None,
+    )
+    mock_version = VersionInfo(
+        git_sha="abc1234",
+        git_describe="v1.0.0",
+        control_plane_schema_version=1,
+        python_version="3.11",
+        known=True,
+    )
+    mock_stale = StaleRuntime(
+        daemon_head="abc1234",
+        checkout_head="abc1234",
+        remote_head="abc1234",
+        stale=False,
+        determinable=True,
+        mutation_safe=True,
+        reasons=(),
+    )
+    mock_health = SystemHealthSnapshot(
+        status="degraded",
+        ready=False,
+        readiness_complete=True,
+        readiness_reasons=(),
+        service="webui",
+        mode="test",
+        version=mock_version,
+        started_at="2026-07-25T00:00:00Z",
+        uptime_seconds=100.0,
+        timestamp="2026-07-25T00:00:00Z",
+        deep_probes_requested=True,
+        dependencies=(),
+        mcp_namespaces=(),
+        stale_runtime=mock_stale,
+        probe_errors=("probe blew up",),
+    )
+
+    snapshot = load_notifications_snapshot(
+        proj_id,
+        load_queue=lambda _id: mock_queue,
+        load_leases=lambda **_kwargs: mock_leases,
+        load_health=lambda **_kwargs: mock_health,
+    )
+    assert snapshot.fetch_error is None
+    # probe errors still appear as items
+    assert any("probe blew up" in item.summary for item in snapshot.items)

webui/app.py

@@ -80,6 +80,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
 from webui import request_service
 from webui.request_views import render_requests_page
 
@@ -889,6 +894,22 @@ 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)
+
 def _default_request_scope() -> dict[str, str]:
     """Resolve remote/org/repo from the project registry for request forms.
 
@@ -1020,6 +1041,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

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

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,486 @@
+"""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
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+from webui import console_redaction
+from webui.project_registry import 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).
+
+    Classification uses structured flags and category only. Human-authored
+    ``title`` / ``summary`` text is never substring-matched for escalation
+    (PR #905 review B1) — callers that need text signals must set flags from
+    machine-generated status/detail fields before calling this function.
+    """
+    del title, summary  # kept for API stability; never used for classification
+    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}
+    ):
+        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 err_idx, probe_err in enumerate(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}-{err_idx}",
+                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 col_idx, collision in enumerate(lease_snap.duplicate_prs):
+        att_cls, req_human = classify_attention_event(
+            CATEGORY_BLOCKER,
+            f"Duplicate PR Collision ({collision.kind})",
+            collision.message,
+            is_blocker=True,
+        )
+        issue_part = collision.issue_number if collision.issue_number is not None else "none"
+        kind_part = (collision.kind or "unknown").replace(" ", "-")
+        items.append(
+            NotificationItem(
+                id=f"notif-collision-{kind_part}-{issue_part}-{col_idx}",
+                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 errors are transport/load failures only — not probe results that
+    # already surface as first-class notification items (PR #905 review B3).
+    fetch_err = queue_snap.fetch_error or lease_snap.fetch_error
+    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()