nat-engine 1__py3-none-any.whl

mannf/product/dashboard/app.py

@@ -0,0 +1,3567 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""Dashboard routes and WebSocket endpoint for the NAT web dashboard.
+
+Provides:
+- ``GET /dashboard`` — serve the single-page dashboard HTML
+- ``GET /api/v1/dashboard/summary`` — aggregated stats for the overview bar
+- ``GET /api/v1/dashboard/settings`` — read-only server configuration
+- ``GET /api/v1/scan/{scan_id}/export`` — export scan results (html|json|csv|pdf)
+- ``WebSocket /ws/live`` — real-time updates during active scans
+"""
+
+from __future__ import annotations
+
+import asyncio
+import csv
+import io
+import json
+import logging
+import os
+import pathlib
+import uuid
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, List, Optional, Set
+
+from fastapi import APIRouter, File, Form, HTTPException, Query, UploadFile, WebSocket, WebSocketDisconnect
+from fastapi.responses import HTMLResponse, JSONResponse, Response
+
+from mannf.product.dashboard.models import (
+    AnomalyTimelineEntry,
+    AutonomousRequest,
+    BeliefStateSnapshot,
+    BeliefTrend,
+    BugFilingConfig,
+    CalibrationReport,
+    CalibrationBucket,
+    DashboardSummary,
+    DismissedFinding,
+    DiscoveryRequest,
+    DiscoveryResult,
+    DiscoveryScenario,
+    EndpointRiskCard,
+    FailureCluster,
+    FiledBugEntry,
+    FlakinessSummary,
+    FunctionalTestResult,
+    OnboardingStatus,
+    OnboardingStep,
+    PendingBugEntry,
+    PredictiveRiskScore,
+    RootCauseSuggestion,
+    UsageSummary,
+)
+
+logger = logging.getLogger(__name__)
+
+_STATIC_DIR = pathlib.Path(__file__).parent / "static"
+
+# ---------------------------------------------------------------------------
+# In-memory store for discovery results (Phase 3)
+# ---------------------------------------------------------------------------
+
+_discoveries: Dict[str, DiscoveryResult] = {}
+
+# ---------------------------------------------------------------------------
+# In-memory store for autonomous run reports (Phase 5)
+# ---------------------------------------------------------------------------
+
+_autonomous_runs: Dict[str, Any] = {}
+
+# ---------------------------------------------------------------------------
+# In-memory stores for auto-filed and pending bug tickets (Phase 6.4)
+# ---------------------------------------------------------------------------
+
+_filed_bugs: Dict[str, FiledBugEntry] = {}
+_pending_bugs: Dict[str, PendingBugEntry] = {}
+_bug_filing_config: BugFilingConfig = BugFilingConfig()
+
+# ---------------------------------------------------------------------------
+# In-memory store for dismissed findings / FP feedback (Phase 7.4)
+# ---------------------------------------------------------------------------
+
+_dismissed_findings: Dict[str, DismissedFinding] = {}
+
+# ---------------------------------------------------------------------------
+# In-memory stores for finding comments and scan share links (Phase 10.4)
+# ---------------------------------------------------------------------------
+
+# finding_id → list of comment dicts: {id, author, text, created_at}
+_finding_comments: Dict[str, List[Dict[str, Any]]] = {}
+
+# scan_id → share record dict: {token, scan_id, expires_at, created_at}
+_scan_shares: Dict[str, Dict[str, Any]] = {}
+
+# ---------------------------------------------------------------------------
+# In-memory flake detector singleton (Phase 6.5)
+# ---------------------------------------------------------------------------
+
+from mannf.core.diagnostics.flake_detector import FlakeDetector as _FlakeDetector  # noqa: E402
+
+_flake_detector: _FlakeDetector = _FlakeDetector()
+
+# ---------------------------------------------------------------------------
+# WebSocket connection manager for live updates
+# ---------------------------------------------------------------------------
+
+
+class _ConnectionManager:
+    """Manages active WebSocket connections and broadcasts messages."""
+
+    def __init__(self) -> None:
+        self._active: Set[WebSocket] = set()
+
+    async def connect(self, ws: WebSocket) -> None:
+        await ws.accept()
+        self._active.add(ws)
+        logger.debug("WebSocket client connected (%d total)", len(self._active))
+
+    def disconnect(self, ws: WebSocket) -> None:
+        self._active.discard(ws)
+        logger.debug("WebSocket client disconnected (%d total)", len(self._active))
+
+    async def broadcast(self, message: Dict[str, Any]) -> None:
+        """Send a JSON message to all connected clients."""
+        if not self._active:
+            return
+        text = json.dumps(message)
+        dead: Set[WebSocket] = set()
+        for ws in list(self._active):
+            try:
+                await ws.send_text(text)
+            except Exception:  # noqa: BLE001
+                dead.add(ws)
+        self._active -= dead
+
+    @property
+    def connection_count(self) -> int:
+        return len(self._active)
+
+
+manager = _ConnectionManager()
+
+# ---------------------------------------------------------------------------
+# Router
+# ---------------------------------------------------------------------------
+
+router = APIRouter(tags=["dashboard"])
+
+
+@router.get("/dashboard", response_class=HTMLResponse)
+async def dashboard_index() -> HTMLResponse:
+    """Serve the single-page dashboard HTML."""
+    html_path = _STATIC_DIR / "index.html"
+    content = html_path.read_text(encoding="utf-8")
+    return HTMLResponse(content=content)
+
+
+@router.get("/dashboard/status", response_class=HTMLResponse)
+async def dashboard_status() -> HTMLResponse:
+    """Serve a human-readable HTML status page showing component health."""
+    import time as _time
+    from mannf.product.server import _scans, _server_start_time
+    from mannf.product.status import aggregate_status, run_all_checks
+
+    components = await run_all_checks(_scans, _server_start_time)
+    overall = aggregate_status(components)
+    uptime_s = _time.monotonic() - _server_start_time
+
+    def _status_colour(s: str) -> str:
+        return {"healthy": "#22c55e", "degraded": "#f59e0b", "unhealthy": "#ef4444", "disabled": "#9ca3af"}.get(s, "#9ca3af")
+
+    def _badge(s: str) -> str:
+        colour = _status_colour(s)
+        return f'<span style="background:{colour};color:#fff;padding:2px 8px;border-radius:4px;font-size:0.85em">{s.upper()}</span>'
+
+    rows = ""
+    for comp in components:
+        latency = f"{comp.latency_ms:.1f} ms" if comp.latency_ms else "—"
+        details_html = ", ".join(f"<b>{k}</b>: {v}" for k, v in comp.details.items())
+        rows += f"""
+        <tr>
+          <td style="padding:8px 12px">{comp.name}</td>
+          <td style="padding:8px 12px">{_badge(comp.status)}</td>
+          <td style="padding:8px 12px">{latency}</td>
+          <td style="padding:8px 12px;font-size:0.85em;color:#6b7280">{details_html}</td>
+        </tr>"""
+
+    overall_colour = _status_colour(overall)
+    from mannf import __version__
+
+    html = f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>NAT Status</title>
+  <style>
+    body {{ font-family: system-ui, sans-serif; margin: 0; background: #f9fafb; color: #111827; }}
+    header {{ background: #1e293b; color: #fff; padding: 16px 24px; display: flex; align-items: center; gap: 12px; }}
+    header h1 {{ margin: 0; font-size: 1.25rem; }}
+    .container {{ max-width: 960px; margin: 32px auto; padding: 0 16px; }}
+    .card {{ background: #fff; border-radius: 8px; box-shadow: 0 1px 3px rgba(0,0,0,.1); margin-bottom: 24px; overflow: hidden; }}
+    .card-header {{ padding: 16px 20px; border-bottom: 1px solid #e5e7eb; font-weight: 600; }}
+    table {{ width: 100%; border-collapse: collapse; }}
+    th {{ background: #f3f4f6; text-align: left; padding: 8px 12px; font-size: 0.8rem; text-transform: uppercase; color: #6b7280; }}
+    tr:nth-child(even) {{ background: #f9fafb; }}
+    .overall {{ display: inline-block; width: 16px; height: 16px; border-radius: 50%; background: {overall_colour}; vertical-align: middle; margin-right: 8px; }}
+    .meta {{ font-size: 0.85rem; color: #6b7280; margin-top: 4px; }}
+    a {{ color: #3b82f6; text-decoration: none; }}
+    a:hover {{ text-decoration: underline; }}
+  </style>
+</head>
+<body>
+  <header>
+    <div style="font-size:1.5rem">&#x1F9E0;</div>
+    <h1>NAT — System Status</h1>
+    <a href="/dashboard" style="margin-left:auto;color:#93c5fd;font-size:0.9rem">&#x2190; Dashboard</a>
+  </header>
+  <div class="container">
+    <div class="card">
+      <div class="card-header">
+        <span class="overall"></span>
+        Overall: <strong style="color:{overall_colour}">{overall.upper()}</strong>
+        &nbsp;&nbsp;<span class="meta">v{__version__} &mdash; uptime {int(uptime_s // 3600)}h {int((uptime_s % 3600) // 60)}m {int(uptime_s % 60)}s</span>
+      </div>
+      <table>
+        <thead>
+          <tr>
+            <th>Component</th><th>Status</th><th>Latency</th><th>Details</th>
+          </tr>
+        </thead>
+        <tbody>{rows}</tbody>
+      </table>
+    </div>
+    <p style="text-align:center;font-size:0.8rem;color:#9ca3af">
+      Machine-readable JSON: <a href="/api/v1/status">/api/v1/status</a>
+    </p>
+  </div>
+</body>
+</html>"""
+    return HTMLResponse(content=html)
+
+
+@router.get("/manifest.json")
+async def pwa_manifest() -> Response:
+    """Serve the PWA web app manifest."""
+    path = _STATIC_DIR / "manifest.json"
+    return Response(
+        content=path.read_bytes(),
+        media_type="application/manifest+json",
+        headers={"Cache-Control": "public, max-age=86400"},
+    )
+
+
+@router.get("/sw.js")
+async def service_worker() -> Response:
+    """Serve the PWA service worker script at the root scope."""
+    path = _STATIC_DIR / "sw.js"
+    return Response(
+        content=path.read_bytes(),
+        media_type="application/javascript",
+        headers={"Cache-Control": "no-cache", "Service-Worker-Allowed": "/"},
+    )
+
+
+@router.get("/pwa-icon-192.png")
+async def pwa_icon_192() -> Response:
+    """Serve the 192×192 PWA app icon."""
+    path = _STATIC_DIR / "pwa-icon-192.png"
+    return Response(
+        content=path.read_bytes(),
+        media_type="image/png",
+        headers={"Cache-Control": "public, max-age=604800"},
+    )
+
+
+@router.get("/pwa-icon-512.png")
+async def pwa_icon_512() -> Response:
+    """Serve the 512×512 PWA app icon."""
+    path = _STATIC_DIR / "pwa-icon-512.png"
+    return Response(
+        content=path.read_bytes(),
+        media_type="image/png",
+        headers={"Cache-Control": "public, max-age=604800"},
+    )
+
+
+@router.get("/api/v1/dashboard/summary", response_model=DashboardSummary)
+async def dashboard_summary() -> DashboardSummary:
+    """Return aggregated statistics for the dashboard overview bar."""
+    # Import here to avoid circular imports with server.py
+    from mannf.product.server import _scans, _get_anomaly_detector, _get_risk_scorer
+
+    # --- scan stats ---------------------------------------------------------
+    total_scans = len(_scans)
+    total_tests_run = 0
+    total_passed = 0
+    last_scan_at: str | None = None
+
+    for entry in _scans.values():
+        summary = entry.get("summary") or {}
+        total_tests_run += summary.get("total", 0)
+        total_passed += summary.get("passed", 0)
+        completed_at = entry.get("completed_at")
+        if completed_at:
+            if last_scan_at is None or completed_at > last_scan_at:
+                last_scan_at = completed_at
+
+    pass_rate = total_passed / total_tests_run if total_tests_run > 0 else 0.0
+
+    # --- risk stats ---------------------------------------------------------
+    scorer = _get_risk_scorer()
+    risk_report: List[Dict[str, Any]] = scorer.get_risk_report()
+    endpoints_discovered = len(risk_report)
+    avg_risk_score = (
+        sum(e["risk_score"] for e in risk_report) / endpoints_discovered
+        if endpoints_discovered > 0
+        else 0.0
+    )
+    # Health score is inverse of avg risk
+    health_score = max(0.0, 1.0 - avg_risk_score)
+
+    # --- anomaly stats ------------------------------------------------------
+    detector = _get_anomaly_detector()
+    all_alerts: List[Dict[str, Any]] = detector.get_alerts_dict()
+    anomalies_found = len(all_alerts)
+    active_anomalies = sum(
+        1 for a in all_alerts if a.get("severity") in ("warning", "critical")
+    )
+
+    return DashboardSummary(
+        total_scans=total_scans,
+        endpoints_discovered=endpoints_discovered,
+        anomalies_found=anomalies_found,
+        avg_risk_score=round(avg_risk_score, 4),
+        total_tests_run=total_tests_run,
+        pass_rate=round(pass_rate, 4),
+        active_anomalies=active_anomalies,
+        last_scan_at=last_scan_at,
+        health_score=round(health_score, 4),
+    )
+
+
+@router.get("/api/v1/dashboard/endpoints", response_model=List[EndpointRiskCard])
+async def dashboard_endpoints() -> List[EndpointRiskCard]:
+    """Return enriched per-endpoint cards for the risk heatmap."""
+    from mannf.product.server import _get_anomaly_detector, _get_risk_scorer
+
+    scorer = _get_risk_scorer()
+    detector = _get_anomaly_detector()
+    risk_report: List[Dict[str, Any]] = scorer.get_risk_report()
+    all_alerts: List[Dict[str, Any]] = detector.get_alerts_dict()
+
+    # Count anomalies per endpoint
+    anomaly_counts: Dict[str, int] = {}
+    for alert in all_alerts:
+        ep = alert.get("endpoint", "")
+        anomaly_counts[ep] = anomaly_counts.get(ep, 0) + 1
+
+    cards: List[EndpointRiskCard] = []
+    for entry in risk_report:
+        ep = entry["endpoint"]
+        cards.append(
+            EndpointRiskCard(
+                endpoint=ep,
+                risk_score=entry["risk_score"],
+                fault_rate=entry["fault_rate"],
+                belief_signal=entry["belief_signal"],
+                latency_signal=entry["latency_signal"],
+                diversity_signal=entry["diversity_signal"],
+                trend=entry["trend"],
+                run_count=entry["run_count"],
+                fault_count=entry["fault_count"],
+                anomaly_count=anomaly_counts.get(ep, 0),
+            )
+        )
+    return cards
+
+
+@router.get("/api/v1/dashboard/anomalies", response_model=List[AnomalyTimelineEntry])
+async def dashboard_anomalies() -> List[AnomalyTimelineEntry]:
+    """Return anomaly timeline entries sorted newest-first."""
+    from mannf.product.server import _get_anomaly_detector
+
+    detector = _get_anomaly_detector()
+    alerts: List[Dict[str, Any]] = detector.get_alerts_dict()
+    entries = [AnomalyTimelineEntry(**a) for a in alerts]
+    # Sort newest-first
+    entries.sort(key=lambda e: e.detected_at, reverse=True)
+    return entries
+
+
+@router.get("/api/v1/dashboard/agents", response_model=List[BeliefStateSnapshot])
+async def dashboard_agents() -> List[BeliefStateSnapshot]:
+    """Return the most recent telemetry snapshot for each active agent.
+
+    Intended for the initial page load before the WebSocket connects.
+    Each entry is the last ``agent_state`` snapshot emitted after a
+    deliberation cycle.
+    """
+    from mannf.product.dashboard.telemetry import get_agent_snapshots
+
+    snapshots = get_agent_snapshots()
+    result: List[BeliefStateSnapshot] = []
+    for snap in snapshots:
+        confidence_map: Dict[str, Any] = snap.get("confidence", {})
+        avg_confidence = (
+            sum(confidence_map.values()) / len(confidence_map)
+            if confidence_map
+            else 0.5
+        )
+        result.append(
+            BeliefStateSnapshot(
+                agent_id=snap.get("agent_id", ""),
+                agent_role=snap.get("agent_role", ""),
+                beliefs=snap.get("beliefs", {}),
+                active=True,
+                confidence=round(avg_confidence, 4),
+                confidence_per_service=confidence_map,
+                intentions=snap.get("intentions", []),
+                desires=snap.get("desires", {}),
+                entropy=snap.get("entropy", 0.0),
+                timestamp=snap.get("timestamp"),
+            )
+        )
+    return result
+
+
+@router.get("/api/v1/dashboard/settings")
+async def dashboard_settings() -> Dict[str, Any]:
+    """Return read-only server configuration for the Settings tab."""
+    api_key_raw = os.environ.get("NAT_API_KEY", "")
+    if len(api_key_raw) > 4:
+        api_key_preview = "*" * (len(api_key_raw) - 4) + api_key_raw[-4:]
+    elif api_key_raw:
+        api_key_preview = "***"
+    else:
+        api_key_preview = ""
+
+    return {
+        "server": {
+            "host": os.environ.get("NAT_HOST", "0.0.0.0"),
+            "port": int(os.environ.get("NAT_PORT", "8080")),
+            "workers": int(os.environ.get("WEB_CONCURRENCY", "1")),
+            "log_level": os.environ.get("NAT_LOG_LEVEL", "info"),
+        },
+        "auth": {
+            "api_key_configured": bool(api_key_raw),
+            "api_key_preview": api_key_preview,
+        },
+        "queue": {
+            "max_concurrent_scans": int(os.environ.get("NAT_MAX_CONCURRENT_SCANS", "4")),
+            "max_queue_depth": int(os.environ.get("NAT_MAX_QUEUE_DEPTH", "20")),
+            "scan_timeout_seconds": int(os.environ.get("NAT_SCAN_TIMEOUT", "300")),
+        },
+        "rate_limit": os.environ.get("NAT_RATE_LIMIT", ""),
+        "webhook": {
+            "default_url": os.environ.get("NAT_WEBHOOK_URL", ""),
+            "hmac_configured": bool(os.environ.get("NAT_WEBHOOK_SECRET", "")),
+        },
+    }
+
+
+def _render_export_html(
+    scan_id: str,
+    entry: Dict[str, Any],
+    summary: Dict[str, Any],
+    results: List[Any],
+) -> str:
+    """Generate a standalone HTML report for a scan export."""
+    status = entry.get("status", "unknown")
+    spec_name = entry.get("spec_name", "—")
+    base_url = entry.get("base_url", "—")
+    created_at = entry.get("created_at", "—")
+    completed_at = entry.get("completed_at", "—")
+    total = summary.get("total", 0)
+    passed = summary.get("passed", 0)
+    failed = summary.get("failed", 0)
+    pass_rate = summary.get("pass_rate", 0.0)
+
+    status_color = "#3fb950" if status == "completed" else ("#f85149" if status == "failed" else "#8b949e")
+
+    rows_html = ""
+    for r in results:
+        if hasattr(r, "__dict__"):
+            r = r.__dict__
+        tc_id = r.get("test_case_id", "")
+        ep = r.get("endpoint", "")
+        ok = r.get("passed", False)
+        sc = r.get("status_code", "")
+        lat = r.get("execution_time_ms", "")
+        err = r.get("error") or ""
+        row_bg = "#1a2e1a" if ok else "#2e1a1a"
+        badge = '<span style="color:#3fb950;font-weight:700;">PASS</span>' if ok else '<span style="color:#f85149;font-weight:700;">FAIL</span>'
+        rows_html += f"""<tr style="background:{row_bg};">
+          <td style="padding:6px 10px;font-family:monospace;font-size:12px;max-width:140px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;">{tc_id}</td>
+          <td style="padding:6px 10px;font-family:monospace;font-size:12px;">{ep}</td>
+          <td style="padding:6px 10px;text-align:center;">{badge}</td>
+          <td style="padding:6px 10px;text-align:center;">{sc}</td>
+          <td style="padding:6px 10px;text-align:right;">{lat}</td>
+          <td style="padding:6px 10px;font-size:11px;color:#8b949e;">{err}</td>
+        </tr>"""
+
+    report_timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>NAT Scan Report — {scan_id}</title>
+  <style>
+    body {{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;background:#0d1117;color:#e6edf3;margin:0;padding:24px;font-size:14px;}}
+    h1 {{font-size:20px;margin-bottom:4px;}}
+    .meta {{color:#8b949e;font-size:12px;margin-bottom:24px;}}
+    .cards {{display:flex;gap:16px;flex-wrap:wrap;margin-bottom:24px;}}
+    .card {{background:#161b22;border:1px solid #30363d;border-radius:8px;padding:16px 20px;min-width:120px;}}
+    .card-label {{font-size:11px;text-transform:uppercase;letter-spacing:.06em;color:#8b949e;margin-bottom:4px;}}
+    .card-value {{font-size:28px;font-weight:700;line-height:1;}}
+    table {{width:100%;border-collapse:collapse;font-size:13px;}}
+    th {{text-align:left;padding:8px 10px;color:#8b949e;border-bottom:1px solid #30363d;font-weight:600;font-size:11px;text-transform:uppercase;letter-spacing:.05em;}}
+    td {{border-bottom:1px solid rgba(48,54,61,.5);}}
+    .footer {{margin-top:24px;color:#484f58;font-size:11px;}}
+  </style>
+</head>
+<body>
+  <h1>🔬 NAT Scan Report</h1>
+  <div class="meta">Generated {report_timestamp} · Scan ID: {scan_id}</div>
+  <div class="cards">
+    <div class="card">
+      <div class="card-label">Status</div>
+      <div class="card-value" style="font-size:18px;color:{status_color};">{status}</div>
+    </div>
+    <div class="card">
+      <div class="card-label">Total Tests</div>
+      <div class="card-value">{total}</div>
+    </div>
+    <div class="card">
+      <div class="card-label">Passed</div>
+      <div class="card-value" style="color:#3fb950;">{passed}</div>
+    </div>
+    <div class="card">
+      <div class="card-label">Failed</div>
+      <div class="card-value" style="color:#f85149;">{failed}</div>
+    </div>
+    <div class="card">
+      <div class="card-label">Pass Rate</div>
+      <div class="card-value">{pass_rate * 100:.1f}%</div>
+    </div>
+  </div>
+  <table style="background:#161b22;border:1px solid #30363d;border-radius:8px;overflow:hidden;">
+    <thead>
+      <tr>
+        <th>Test Case ID</th>
+        <th>Endpoint</th>
+        <th>Result</th>
+        <th>Status Code</th>
+        <th>Latency (ms)</th>
+        <th>Error</th>
+      </tr>
+    </thead>
+    <tbody>
+      {rows_html if rows_html else '<tr><td colspan="6" style="padding:16px;text-align:center;color:#484f58;">No test results recorded</td></tr>'}
+    </tbody>
+  </table>
+  <div class="footer">
+    Spec: {spec_name} · Base URL: {base_url} · Started: {created_at} · Completed: {completed_at}
+  </div>
+</body>
+</html>"""
+
+
+@router.get("/api/v1/scan/{scan_id}/export")
+async def export_scan(
+    scan_id: str,
+    format: str = Query("json", description="Export format: html, json, csv, or pdf"),
+    request: "Any" = None,
+) -> Response:
+    """Export scan results in html, json, csv, or pdf format.
+
+    - ``html`` — standalone printable HTML report with embedded styles
+    - ``json`` — full machine-readable scan data
+    - ``csv``  — tabular test results for spreadsheet analysis
+    - ``pdf``  — PDF report (Pro+ plans only; Enterprise supports white-label)
+    """
+    if format not in ("html", "json", "csv", "pdf"):
+        raise HTTPException(status_code=400, detail="format must be one of: html, json, csv, pdf")
+
+    from mannf.product.server import _scans
+
+    entry = _scans.get(scan_id)
+    if entry is None:
+        raise HTTPException(status_code=404, detail=f"Scan '{scan_id}' not found")
+
+    summary: Dict[str, Any] = entry.get("summary") or {}
+    results: List[Any] = entry.get("results") or []
+
+    if format == "json":
+        content = json.dumps(entry, indent=2, default=str)
+        return Response(
+            content=content,
+            media_type="application/json",
+            headers={"Content-Disposition": f'attachment; filename="scan-{scan_id}.json"'},
+        )
+
+    if format == "csv":
+        output = io.StringIO()
+        writer = csv.writer(output)
+        writer.writerow(["test_case_id", "endpoint", "passed", "status_code", "execution_time_ms", "error"])
+        for r in results:
+            if hasattr(r, "__dict__"):
+                r = r.__dict__
+            writer.writerow([
+                r.get("test_case_id", ""),
+                r.get("endpoint", ""),
+                r.get("passed", ""),
+                r.get("status_code", ""),
+                r.get("execution_time_ms", ""),
+                r.get("error") or "",
+            ])
+        return Response(
+            content=output.getvalue(),
+            media_type="text/csv",
+            headers={"Content-Disposition": f'attachment; filename="scan-{scan_id}.csv"'},
+        )
+
+    if format == "pdf":
+        from mannf.product.billing.feature_gates import check_feature, get_features  # noqa: PLC0415
+
+        tenant = None
+        if request is not None:
+            tenant = getattr(getattr(request, "state", None), "tenant", None)
+        plan_tier: str = tenant.get("plan_tier", "free") if tenant else "free"
+
+        if not check_feature(plan_tier, "export_pdf"):
+            raise HTTPException(
+                status_code=403,
+                detail={
+                    "code": "FEATURE_NOT_AVAILABLE",
+                    "message": (
+                        "PDF export is not available on the free plan. "
+                        "Upgrade to Pro or higher to download PDF reports."
+                    ),
+                    "feature": "export_pdf",
+                    "plan": plan_tier,
+                    "upgrade_url": "https://app.nat-testing.io/dashboard/upgrade?to=pro",
+                },
+            )
+
+        whitelabel: bool = bool(get_features(plan_tier).get("pdf_whitelabel", False))
+
+        from mannf.product.reports.pdf import PDFReportGenerator  # noqa: PLC0415
+
+        html = _render_export_html(scan_id, entry, summary, results)
+        generator = PDFReportGenerator()
+        pdf_bytes = await generator.generate(html, whitelabel=whitelabel)
+        return Response(
+            content=pdf_bytes,
+            media_type="application/pdf",
+            headers={"Content-Disposition": f'attachment; filename="scan-{scan_id}.pdf"'},
+        )
+
+    # html
+    html = _render_export_html(scan_id, entry, summary, results)
+    return Response(
+        content=html,
+        media_type="text/html",
+        headers={"Content-Disposition": f'attachment; filename="scan-{scan_id}.html"'},
+    )
+
+
+@router.get("/api/v1/dashboard/functional-results", response_model=FunctionalTestResult)
+async def dashboard_functional_results() -> FunctionalTestResult:
+    """Return the latest FunctionalTestOrchestrator run results for the dashboard.
+
+    Pulls data from the server's ``_functional_results`` store when available.
+    Returns an empty result with helpful defaults when no runs exist yet.
+    """
+    try:
+        from mannf.product.server import _functional_results  # noqa: PLC0415
+    except ImportError:
+        _functional_results: List[Dict[str, Any]] = []
+
+    if not _functional_results:
+        return FunctionalTestResult()
+
+    latest = _functional_results[-1]
+    from mannf.product.dashboard.models import (  # noqa: PLC0415
+        A11yViolationSummary,
+        FunctionalTestItem,
+        PerfMetrics,
+        VisualDiffEntry,
+    )
+
+    total = latest.get("total", 0)
+    passed = latest.get("passed", 0)
+    failed = latest.get("failed", total - passed)
+    pass_rate = round(passed / total, 4) if total > 0 else 0.0
+
+    items = [
+        FunctionalTestItem(
+            task_id=item.get("task_id", ""),
+            task_name=item.get("task_name", item.get("task_id", "")),
+            passed=item.get("passed", False),
+            duration_ms=item.get("duration_ms"),
+            error=item.get("error"),
+            artifact_url=item.get("artifact_url"),
+        )
+        for item in latest.get("items", [])
+    ]
+
+    visual_diffs = [
+        VisualDiffEntry(
+            task_id=vd.get("task_id", ""),
+            baseline_url=vd.get("baseline_url"),
+            current_url=vd.get("current_url"),
+            diff_url=vd.get("diff_url"),
+            diff_percent=vd.get("diff_percent", 0.0),
+            passed=vd.get("passed", True),
+        )
+        for vd in latest.get("visual_diffs", [])
+    ]
+
+    a11y_data = latest.get("a11y")
+    a11y = (
+        A11yViolationSummary(
+            critical=a11y_data.get("critical", 0),
+            serious=a11y_data.get("serious", 0),
+            moderate=a11y_data.get("moderate", 0),
+            minor=a11y_data.get("minor", 0),
+            total=a11y_data.get("total", 0),
+            sample_violations=a11y_data.get("sample_violations", []),
+        )
+        if a11y_data
+        else None
+    )
+
+    perf_data = latest.get("perf")
+    perf = (
+        PerfMetrics(
+            lcp_ms=perf_data.get("lcp_ms"),
+            fid_ms=perf_data.get("fid_ms"),
+            cls=perf_data.get("cls"),
+            ttfb_ms=perf_data.get("ttfb_ms"),
+        )
+        if perf_data
+        else None
+    )
+
+    return FunctionalTestResult(
+        run_id=latest.get("run_id"),
+        started_at=latest.get("started_at"),
+        completed_at=latest.get("completed_at"),
+        total=total,
+        passed=passed,
+        failed=failed,
+        pass_rate=pass_rate,
+        items=items,
+        visual_diffs=visual_diffs,
+        a11y=a11y,
+        perf=perf,
+    )
+
+
+@router.get("/api/v1/dashboard/browser-security-findings")
+async def dashboard_browser_security_findings() -> Dict[str, Any]:
+    """Return browser-level security findings from autonomous run(s).
+
+    Aggregates findings collected by the
+    :class:`~mannf.core.browser.reflection_analyzer.ReflectionAnalyzer`
+    across all autonomous run reports in the in-memory store.
+
+    Returns a JSON object with:
+
+    * ``findings`` — list of finding dicts (matching the
+      :class:`~mannf.product.security.models.SecurityFinding` field layout).
+    * ``summary`` — counts by severity.
+    * ``total_findings`` — total number of findings.
+    """
+    all_findings: list[Dict[str, Any]] = []
+
+    for entry in _autonomous_runs.values():
+        # findings may be attached at the top level or inside the report
+        raw_report = entry if isinstance(entry, dict) else {}
+        coverage = raw_report.get("coverage_summary", {})
+        # Collected findings are stored on the agent but we surface them
+        # from the in-memory demo data and any live run data.
+        findings_in_entry = raw_report.get("browser_security_findings", [])
+        all_findings.extend(findings_in_entry)
+
+    # Include demo findings when no live data exists
+    if not all_findings:
+        from mannf.product.demo import _DEMO_BROWSER_SECURITY_FINDINGS  # noqa: PLC0415
+        all_findings = list(_DEMO_BROWSER_SECURITY_FINDINGS)
+
+    severity_order = ["critical", "high", "medium", "low", "info"]
+    summary: Dict[str, int] = {s: 0 for s in severity_order}
+    for f in all_findings:
+        sev = f.get("severity", "info")
+        if sev in summary:
+            summary[sev] += 1
+
+    return {
+        "findings": all_findings,
+        "summary": summary,
+        "total_findings": len(all_findings),
+    }
+
+
+@router.get("/api/v1/dashboard/usage-summary", response_model=UsageSummary)
+async def dashboard_usage_summary(request: "Any" = None) -> UsageSummary:
+    """Return usage gauge data (wraps /api/v1/usage) for the billing tab.
+
+    When a tenant is authenticated the data is tenant-scoped; otherwise
+    returns quota data from the server's environment configuration.
+    """
+    from mannf.product.billing.plans import get_plan  # noqa: PLC0415
+    from mannf.product.dashboard.models import InvoiceEntry  # noqa: PLC0415
+
+    # Attempt to resolve the tenant from the request state (may be None in
+    # environments without full auth middleware)
+    tenant = None
+    if request is not None:
+        tenant = getattr(getattr(request, "state", None), "tenant", None)
+
+    if tenant is not None:
+        from mannf.product.billing.tenant_auth import get_monthly_usage  # noqa: PLC0415
+        import uuid as _uuid  # noqa: PLC0415
+
+        tenant_id = _uuid.UUID(tenant["id"])
+        plan_tier = tenant.get("plan_tier", "free")
+        plan = get_plan(plan_tier)
+        func_used = await get_monthly_usage(tenant_id, "functional")
+        sec_used = await get_monthly_usage(tenant_id, "security")
+    else:
+        plan_tier = "free"
+        plan = get_plan(plan_tier)
+        func_used = 0
+        sec_used = 0
+
+    func_quota = plan.monthly_scan_quota
+    sec_quota = plan.monthly_security_scan_quota
+    func_pct = round(func_used / func_quota, 4) if func_quota > 0 else 0.0
+    sec_pct = round(sec_used / sec_quota, 4) if sec_quota > 0 else 0.0
+    approaching = func_pct >= 0.7 or sec_pct >= 0.7
+
+    # Quota resets on the 1st of the next month
+    now = datetime.now(timezone.utc)
+    if now.month == 12:
+        reset_dt = now.replace(year=now.year + 1, month=1, day=1, hour=0, minute=0, second=0, microsecond=0)
+    else:
+        reset_dt = now.replace(month=now.month + 1, day=1, hour=0, minute=0, second=0, microsecond=0)
+    quota_reset_date = reset_dt.strftime("%Y-%m-%d")
+
+    return UsageSummary(
+        plan_name=plan.display_name,
+        plan_tier=plan_tier,
+        functional_used=func_used,
+        functional_quota=func_quota,
+        security_used=sec_used,
+        security_quota=sec_quota,
+        functional_percent=func_pct,
+        security_percent=sec_pct,
+        approaching_limit=approaching,
+        quota_reset_date=quota_reset_date,
+        stripe_portal_url=None,
+        invoices=[],
+    )
+
+
+@router.get("/api/v1/dashboard/onboarding-status", response_model=OnboardingStatus)
+async def dashboard_onboarding_status(request: "Any" = None) -> OnboardingStatus:
+    """Return onboarding checklist completion state for the getting-started tab.
+
+    Steps are derived from the tenant's activity: whether they have an API
+    key configured, have run at least one scan, and have viewed results.
+    """
+    from mannf.product.server import _scans  # noqa: PLC0415
+
+    tenant = None
+    if request is not None:
+        tenant = getattr(getattr(request, "state", None), "tenant", None)
+
+    api_key_raw = os.environ.get("NAT_API_KEY", "")
+    has_api_key = bool(api_key_raw) or (tenant is not None)
+    has_run_scan = len(_scans) > 0
+    has_viewed_results = has_run_scan  # proxy: if they ran a scan they've seen results
+
+    # Build masked API key for display
+    api_key_masked: Optional[str] = None
+    if api_key_raw:
+        visible = api_key_raw[-4:] if len(api_key_raw) >= 4 else api_key_raw
+        api_key_masked = "nat_pk_" + "•" * 16 + visible
+    elif tenant:
+        api_key_masked = "nat_pk_" + "•" * 20
+
+    steps: List[OnboardingStep] = [
+        OnboardingStep(
+            step=1,
+            title="Account created",
+            description="Your NAT account is set up and ready to use.",
+            completed=True,
+        ),
+        OnboardingStep(
+            step=2,
+            title="Copy your API key",
+            description="Use this key to authenticate CLI and API requests.",
+            completed=has_api_key,
+            action_label="View API key",
+            action_url="/dashboard#settings",
+        ),
+        OnboardingStep(
+            step=3,
+            title="Install NAT CLI",
+            description="Install the NAT testing toolkit with pip.",
+            completed=False,
+            code_snippet="pip install nat-testing",
+        ),
+        OnboardingStep(
+            step=4,
+            title="Run your first scan",
+            description="Point NAT at your OpenAPI spec and base URL.",
+            completed=has_run_scan,
+            code_snippet="nat scan --spec openapi.yaml --url https://api.example.com",
+        ),
+        OnboardingStep(
+            step=5,
+            title="View results in dashboard",
+            description="Explore your scan results, risk heatmap, and agent activity.",
+            completed=has_viewed_results,
+            action_label="Go to Overview",
+            action_url="/dashboard#overview",
+        ),
+    ]
+
+    completed_count = sum(1 for s in steps if s.completed)
+    return OnboardingStatus(
+        steps=steps,
+        completed_count=completed_count,
+        total_count=len(steps),
+        api_key_masked=api_key_masked,
+    )
+
+
+@router.get(
+    "/api/v1/dashboard/onboarding",
+    tags=["dashboard", "onboarding"],
+    summary="Onboarding progress for the authenticated tenant (dashboard view)",
+)
+async def dashboard_onboarding(request: "Any" = None) -> dict:
+    """Return the onboarding progress for the current tenant using the tracker.
+
+    Delegates to :mod:`mannf.product.onboarding` for per-step state, with a
+    fallback to the static checklist when no tenant is authenticated.
+    """
+    from mannf.product.onboarding import get_onboarding_status  # noqa: PLC0415
+
+    tenant = None
+    if request is not None:
+        tenant = getattr(getattr(request, "state", None), "tenant", None)
+
+    if tenant is None:
+        # No authenticated tenant — return an empty/default status
+        return {
+            "tenant_id": None,
+            "completed_steps": [],
+            "next_step": "ACCOUNT_CREATED",
+            "progress_percent": 0.0,
+            "all_steps": [
+                {"step": s, "completed": False, "completed_at": None}
+                for s in [
+                    "ACCOUNT_CREATED",
+                    "API_KEY_PROVISIONED",
+                    "FIRST_SCAN_STARTED",
+                    "FIRST_SCAN_COMPLETED",
+                    "RESULTS_VIEWED",
+                    "BILLING_CONFIGURED",
+                ]
+            ],
+        }
+
+    status = get_onboarding_status(tenant["id"])
+    return status.model_dump()
+
+
+# ---------------------------------------------------------------------------
+# Go-live indicators — plan badge, usage bars, upgrade CTA, demo banner
+# (Phase 8.5 — Go-to-Market Readiness)
+# ---------------------------------------------------------------------------
+
+
+@router.get(
+    "/api/v1/dashboard/go-live-status",
+    tags=["dashboard"],
+    summary="Go-live readiness indicators for the current tenant",
+)
+async def dashboard_go_live_status(request: "Any" = None) -> JSONResponse:
+    """Return plan badge, usage progress, upgrade CTA, and demo-mode info.
+
+    Used by the dashboard to render plan tier badge, usage progress bars,
+    "Upgrade" CTA for free/pro users, trial countdown (if applicable), and
+    the demo environment banner when ``NAT_DEMO_MODE=true``.
+
+    Degrades gracefully when billing is not configured.
+    """
+    from mannf.product.billing.plans import get_plan  # noqa: PLC0415
+
+    tenant = None
+    if request is not None:
+        tenant = getattr(getattr(request, "state", None), "tenant", None)
+
+    # Demo mode
+    raw_demo = os.environ.get("NAT_DEMO_MODE", "").lower().strip()
+    is_demo = raw_demo in ("true", "1", "yes")
+
+    # Billing availability (degrades gracefully when Stripe not configured)
+    stripe_key_set = bool(os.environ.get("STRIPE_SECRET_KEY", "").strip())
+    billing_enabled = stripe_key_set
+
+    if tenant is not None:
+        plan_tier = tenant.get("plan_tier", "free")
+        tenant_name = tenant.get("name", "")
+        monthly_scan_quota = tenant.get("monthly_scan_quota", 50)
+        monthly_security_scan_quota = tenant.get("monthly_security_scan_quota", 10)
+        trial_ends_at = tenant.get("trial_ends_at")
+    else:
+        plan_tier = "free"
+        tenant_name = ""
+        plan_obj = get_plan("free")
+        monthly_scan_quota = plan_obj.monthly_scan_quota
+        monthly_security_scan_quota = plan_obj.monthly_security_scan_quota
+        trial_ends_at = None
+
+    plan_obj = get_plan(plan_tier)
+
+    # Fetch usage if possible
+    func_used = 0
+    sec_used = 0
+    if tenant is not None:
+        try:
+            from mannf.product.billing.tenant_auth import get_monthly_usage  # noqa: PLC0415
+            import uuid as _uuid  # noqa: PLC0415
+
+            tenant_id = _uuid.UUID(tenant["id"])
+            func_used = await get_monthly_usage(tenant_id, "functional")
+            sec_used = await get_monthly_usage(tenant_id, "security")
+        except Exception:  # noqa: BLE001
+            pass
+
+    func_pct = round(func_used / monthly_scan_quota, 4) if monthly_scan_quota > 0 else 0.0
+    sec_pct = round(sec_used / monthly_security_scan_quota, 4) if monthly_security_scan_quota > 0 else 0.0
+
+    # Upgrade CTA: show for free/pro users
+    show_upgrade_cta = plan_tier in ("free", "pro") and billing_enabled
+    upgrade_tier = "pro" if plan_tier == "free" else "team"
+    upgrade_url = f"https://app.nat-testing.io/dashboard/upgrade?to={upgrade_tier}" if show_upgrade_cta else None
+
+    # Trial countdown
+    trial_countdown_days: Optional[int] = None
+    if trial_ends_at:
+        try:
+            from datetime import datetime, timezone  # noqa: PLC0415
+            if isinstance(trial_ends_at, str):
+                ends = datetime.fromisoformat(trial_ends_at)
+            else:
+                ends = trial_ends_at
+            if ends.tzinfo is None:
+                ends = ends.replace(tzinfo=timezone.utc)
+            delta = (ends - datetime.now(timezone.utc)).days
+            trial_countdown_days = max(0, delta)
+        except Exception:  # noqa: BLE001
+            pass
+
+    return JSONResponse(content={
+        "plan": {
+            "tier": plan_tier,
+            "display_name": plan_obj.display_name,
+            "badge_label": plan_obj.display_name.upper(),
+        },
+        "usage": {
+            "functional_scans": {
+                "used": func_used,
+                "quota": monthly_scan_quota,
+                "percent": func_pct,
+                "approaching_limit": func_pct >= 0.8,
+            },
+            "security_scans": {
+                "used": sec_used,
+                "quota": monthly_security_scan_quota,
+                "percent": sec_pct,
+                "approaching_limit": sec_pct >= 0.8,
+            },
+        },
+        "upgrade": {
+            "show_cta": show_upgrade_cta,
+            "upgrade_tier": upgrade_tier if show_upgrade_cta else None,
+            "upgrade_url": upgrade_url,
+        },
+        "trial": {
+            "is_trial": trial_countdown_days is not None,
+            "days_remaining": trial_countdown_days,
+        },
+        "demo_mode": {
+            "active": is_demo,
+            "banner_message": "🎯 Demo Environment — data is synthetic and resets periodically" if is_demo else None,
+        },
+        "billing": {
+            "enabled": billing_enabled,
+        },
+    })
+
+
+# ---------------------------------------------------------------------------
+# Discovery / Scenario Suggestion endpoints (Phase 3)
+# ---------------------------------------------------------------------------
+
+
+def _assign_confidence(scenario: Dict[str, Any]) -> float:
+    """Heuristic confidence score based on scenario type."""
+    type_confidence = {
+        "happy_path": 0.9,
+        "flow": 0.8,
+        "boundary": 0.6,
+        "negative": 0.5,
+        "exploratory": 0.4,
+    }
+    scenario_type = scenario.get("metadata", {}).get("scenario_type", "exploratory")
+    return type_confidence.get(scenario_type, 0.5)
+
+
+def _assign_risk_score(scenario: Dict[str, Any]) -> float:
+    """Heuristic risk score based on scenario type and step count."""
+    type_risk = {
+        "happy_path": 0.3,
+        "flow": 0.5,
+        "boundary": 0.7,
+        "negative": 0.8,
+        "exploratory": 0.4,
+    }
+    scenario_type = scenario.get("metadata", {}).get("scenario_type", "exploratory")
+    return type_risk.get(scenario_type, 0.5)
+
+
+async def _run_discovery(discovery_id: str, req: DiscoveryRequest) -> None:
+    """Background task: crawl target URL and generate scenario suggestions."""
+    from mannf.product.dashboard.telemetry import (  # noqa: PLC0415
+        broadcast_discovery_complete,
+        broadcast_discovery_failed,
+        broadcast_discovery_progress,
+    )
+
+    result = _discoveries[discovery_id]
+    try:
+        # Import Phase 1 / Phase 2 components — gracefully degrade when
+        # Playwright or the crawler aren't installed.
+        try:
+            from mannf.core.agents.web_crawler_agent import WebCrawlerAgent  # noqa: PLC0415
+            from mannf.core.browser.scenario_generator import ScenarioConfigGenerator  # noqa: PLC0415
+            from mannf.core.messaging.bus import MessageBus  # noqa: PLC0415
+        except ImportError as exc:
+            result.status = "failed"
+            result.error = (
+                f"Required components not available (Playwright may not be installed): {exc}"
+            )
+            await broadcast_discovery_failed(discovery_id, result.error)
+            return
+
+        bus = MessageBus()
+        crawler = WebCrawlerAgent(
+            agent_id=f"crawler-{discovery_id[:8]}",
+            bus=bus,
+            service_names=[req.url],
+            base_url=req.url,
+            headless=True,
+            max_pages=req.max_pages,
+            max_depth=req.max_depth,
+        )
+
+        # Broadcast initial progress
+        await broadcast_discovery_progress(
+            discovery_id=discovery_id,
+            pages_visited=0,
+            total_pages=req.max_pages,
+            forms_found=0,
+        )
+
+        await crawler.start_browser()
+        try:
+            await crawler._run_crawl()
+        finally:
+            await crawler.stop_browser()
+
+        discovery_model = crawler._discovery_model
+        if discovery_model is None:
+            result.status = "failed"
+            result.error = "Crawler produced no discovery model"
+            await broadcast_discovery_failed(discovery_id, result.error)
+            return
+
+        # Update stats
+        pages_count = len(discovery_model.pages)
+        forms_count = sum(len(p.forms) for p in discovery_model.pages)
+        edges_count = len(discovery_model.edges)
+
+        await broadcast_discovery_progress(
+            discovery_id=discovery_id,
+            pages_visited=pages_count,
+            total_pages=req.max_pages,
+            forms_found=forms_count,
+        )
+
+        # Generate scenarios via Phase 2
+        llm_provider = None
+        if req.llm_provider:
+            try:
+                from mannf.product.llm.config import LLMConfig  # noqa: PLC0415
+                from mannf.product.llm.factory import get_provider  # noqa: PLC0415
+
+                llm_cfg = LLMConfig(
+                    provider=req.llm_provider,
+                    api_key=req.llm_api_key,
+                    model=req.llm_model or "",
+                )
+                llm_provider = get_provider(llm_cfg)
+            except Exception as llm_exc:  # noqa: BLE001
+                logger.warning("Failed to create LLM provider for discovery: %s", llm_exc)
+
+        generator = ScenarioConfigGenerator(
+            discovery_model,
+            include_negative=req.include_negative,
+            include_boundary=req.include_boundary,
+            llm_provider=llm_provider,
+        )
+        if llm_provider is not None and llm_provider.is_available():
+            raw_scenarios = await generator.generate_all_async()
+        else:
+            raw_scenarios = generator.generate_all()
+
+        scenarios = [
+            DiscoveryScenario(
+                scenario_id=str(uuid.uuid4()),
+                url=s.get("url", req.url),
+                steps=s.get("steps", []),
+                metadata=s.get("metadata", {}),
+                selected=True,
+                confidence=_assign_confidence(s),
+                risk_score=_assign_risk_score(s),
+            )
+            for s in raw_scenarios
+        ]
+
+        result.scenarios = scenarios
+        result.stats = {
+            "pages_discovered": pages_count,
+            "forms_found": forms_count,
+            "flows_detected": edges_count,
+            "total_scenarios": len(scenarios),
+        }
+        result.status = "complete"
+        await broadcast_discovery_complete(discovery_id, len(scenarios))
+        await _persist_discovery(discovery_id)
+
+    except Exception as exc:  # noqa: BLE001
+        logger.exception("Discovery %s failed", discovery_id)
+        result.status = "failed"
+        result.error = str(exc)
+        await broadcast_discovery_failed(discovery_id, str(exc))
+        await _persist_discovery(discovery_id)
+
+
+@router.post("/api/v1/discover")
+async def start_discovery(body: DiscoveryRequest) -> Dict[str, Any]:
+    """Trigger a discovery crawl and scenario generation.
+
+    Returns immediately with a ``discovery_id``; progress is broadcast via
+    the ``/ws/live`` WebSocket connection.
+    """
+    discovery_id = str(uuid.uuid4())
+    result = DiscoveryResult(
+        discovery_id=discovery_id,
+        status="running",
+        base_url=body.url,
+        scenarios=[],
+        stats={},
+        created_at=datetime.now(timezone.utc).isoformat(),
+    )
+    _discoveries[discovery_id] = result
+    asyncio.create_task(_persist_discovery(discovery_id))
+    asyncio.create_task(_run_discovery(discovery_id, body))
+    return {"discovery_id": discovery_id, "status": "running"}
+
+
+@router.post("/api/v1/discover/import")
+async def import_artifact(
+    file: Optional[UploadFile] = File(None),
+    content: Optional[str] = Form(None),
+    format: Optional[str] = Form(None),
+    base_url: Optional[str] = Form(None),
+) -> Dict[str, Any]:
+    """Import an artifact (HAR, Postman, Playwright, cURL, etc.) as a discovery.
+
+    Accepts either:
+
+    * A **file upload** (multipart form data) — ``file`` field.
+    * **Raw content** passed as a form field — ``content`` field (optionally
+      with ``format`` to help format detection).
+
+    The format is auto-detected via
+    :func:`~mannf.product.ingestors.loader.get_ingestor_for_source` when not
+    supplied.  The imported artifact is converted into a
+    :class:`~mannf.product.dashboard.models.DiscoveryResult` via the
+    :class:`~mannf.core.browser.ingestor_bridge.IngestorBridge` and stored in
+    ``_discoveries`` so the standard ``GET /api/v1/discover/{id}`` endpoints
+    work without modification.
+
+    Returns a ``discovery_id`` that can be polled with the existing
+    ``/api/v1/discover/{id}`` endpoints.
+    """
+    from mannf.product.ingestors.loader import (  # noqa: PLC0415
+        get_ingestor_for_source,
+        load_all_ingestors,
+    )
+    from mannf.product.ingestors.models import IngestorSource  # noqa: PLC0415
+    from mannf.core.browser.ingestor_bridge import IngestorBridge  # noqa: PLC0415
+    from mannf.product.dashboard.telemetry import (  # noqa: PLC0415
+        broadcast_discovery_complete,
+    )
+
+    # ---- 1. Resolve raw content ----------------------------------------
+    raw_content: Optional[str] = None
+    filename: str = "import"
+
+    if file is not None:
+        raw_bytes = await file.read()
+        try:
+            raw_content = raw_bytes.decode("utf-8")
+        except UnicodeDecodeError:
+            raw_content = raw_bytes.decode("latin-1")
+        filename = file.filename or "import"
+    elif content is not None:
+        raw_content = content
+    else:
+        raise HTTPException(
+            status_code=422,
+            detail="Provide either a 'file' upload or a 'content' form field.",
+        )
+
+    if not raw_content or not raw_content.strip():
+        raise HTTPException(status_code=422, detail="Artifact content is empty.")
+
+    # ---- 2. Build IngestorSource and auto-detect format ----------------
+    fmt = (format or "").strip().lower() or None
+    source = IngestorSource(
+        format=fmt or "auto",
+        raw_content=raw_content,
+        path=filename,
+        metadata={"filename": filename},
+    )
+
+    # Load all built-ins so get_ingestor_for_source has access to them
+    all_ingestors = load_all_ingestors()
+    ingestor = get_ingestor_for_source(source, all_ingestors)
+
+    if ingestor is None:
+        raise HTTPException(
+            status_code=422,
+            detail=(
+                f"Could not detect format for artifact '{filename}'. "
+                "Supply a 'format' field (e.g. 'har', 'postman', 'playwright', 'curl')."
+            ),
+        )
+
+    # ---- 3. Run the ingestor -------------------------------------------
+    try:
+        ingest_result = await ingestor.ingest(source, config={})
+    except Exception as exc:  # noqa: BLE001
+        logger.exception("Ingestor %r failed for import", ingestor.name)
+        raise HTTPException(
+            status_code=422,
+            detail=f"Ingestor '{ingestor.name}' failed: {exc}",
+        ) from exc
+
+    if not ingest_result.success and not ingest_result.test_cases and not ingest_result.endpoints:
+        errors = "; ".join(ingest_result.errors) if ingest_result.errors else "unknown error"
+        raise HTTPException(
+            status_code=422,
+            detail=f"Ingestion produced no results: {errors}",
+        )
+
+    # ---- 4. Convert via IngestorBridge → scenario dicts ----------------
+    effective_base_url = (base_url or "").strip() or "https://example.com"
+    bridge = IngestorBridge(
+        base_url=effective_base_url,
+        source_tag=ingestor.name,
+    )
+    raw_scenarios = bridge.convert(ingest_result)
+
+    # ---- 5. Build DiscoveryResult and store ----------------------------
+    discovery_id = str(uuid.uuid4())
+    scenarios = [
+        DiscoveryScenario(
+            scenario_id=str(uuid.uuid4()),
+            url=s.get("url", effective_base_url),
+            steps=s.get("steps", []),
+            metadata=s.get("metadata", {}),
+            selected=True,
+            confidence=_assign_confidence(s),
+            risk_score=_assign_risk_score(s),
+        )
+        for s in raw_scenarios
+    ]
+
+    result = DiscoveryResult(
+        discovery_id=discovery_id,
+        status="complete",
+        base_url=effective_base_url,
+        scenarios=scenarios,
+        stats={
+            "pages_discovered": 0,
+            "forms_found": 0,
+            "flows_detected": 0,
+            "total_scenarios": len(scenarios),
+            "endpoints_ingested": len(ingest_result.endpoints),
+            "test_cases_ingested": len(ingest_result.test_cases),
+        },
+        created_at=datetime.now(timezone.utc).isoformat(),
+    )
+    _discoveries[discovery_id] = result
+
+    # ---- 6. Broadcast completion and persist ----------------------------------------
+    await broadcast_discovery_complete(discovery_id, len(scenarios))
+    asyncio.create_task(_persist_discovery(discovery_id))
+
+    return {
+        "discovery_id": discovery_id,
+        "status": "complete",
+        "ingestor": ingestor.name,
+        "scenarios_imported": len(scenarios),
+        "scenario_preview": [
+            {
+                "scenario_id": s.scenario_id,
+                "url": s.url,
+                "description": s.metadata.get("description", ""),
+                "scenario_type": s.metadata.get("scenario_type", ""),
+                "has_auth": s.metadata.get("has_auth", False),
+                "nav_flow": s.metadata.get("nav_flow", []),
+                "assertions_count": len(s.metadata.get("assertions", [])),
+                "steps_count": len(s.steps),
+                "confidence": s.confidence,
+                "risk_score": s.risk_score,
+            }
+            for s in scenarios[:5]
+        ],
+    }
+
+
+@router.post("/api/v1/discover/import/run")
+async def import_and_run(
+    file: Optional[UploadFile] = File(None),
+    content: Optional[str] = Form(None),
+    format: Optional[str] = Form(None),
+    base_url: Optional[str] = Form(None),
+    target_url: Optional[str] = Form(None),
+    max_iterations: int = Form(3),
+    strategy: str = Form("all"),
+) -> Dict[str, Any]:
+    """Import an artifact and immediately launch an autonomous run seeded with the imported scenarios.
+
+    This is the one-click "Run autonomous with these seeds" trigger.  It:
+
+    1. Ingests the artifact (same as ``POST /api/v1/discover/import``).
+    2. Converts the ingested scenarios via :class:`~mannf.core.browser.ingestor_bridge.IngestorBridge`.
+    3. Starts an :class:`~mannf.core.agents.autonomous_loop_agent.AutonomousTestLoopAgent`
+       with the converted scenarios pre-loaded as ``seeded_scenarios``.
+    4. Stores the agent's run ID and the seeded discovery in ``_autonomous_runs`` /
+       ``_discoveries`` so they can be polled via the standard endpoints.
+
+    Returns a ``run_id`` and ``discovery_id`` that can be polled for progress.
+    """
+    from mannf.product.ingestors.loader import (  # noqa: PLC0415
+        get_ingestor_for_source,
+        load_all_ingestors,
+    )
+    from mannf.product.ingestors.models import IngestorSource  # noqa: PLC0415
+    from mannf.core.browser.ingestor_bridge import IngestorBridge  # noqa: PLC0415
+    from mannf.core.agents.autonomous_loop_agent import AutonomousTestLoopAgent  # noqa: PLC0415
+    from mannf.product.dashboard.telemetry import broadcast_discovery_complete  # noqa: PLC0415
+
+    # ---- 1. Resolve content (reuse import logic) -------------------------
+    raw_content: Optional[str] = None
+    filename: str = "import"
+
+    if file is not None:
+        raw_bytes = await file.read()
+        try:
+            raw_content = raw_bytes.decode("utf-8")
+        except UnicodeDecodeError:
+            raw_content = raw_bytes.decode("latin-1")
+        filename = file.filename or "import"
+    elif content is not None:
+        raw_content = content
+    else:
+        raise HTTPException(
+            status_code=422,
+            detail="Provide either a 'file' upload or a 'content' form field.",
+        )
+
+    if not raw_content or not raw_content.strip():
+        raise HTTPException(status_code=422, detail="Artifact content is empty.")
+
+    # ---- 2. Ingest -------------------------------------------------------
+    fmt = (format or "").strip().lower() or None
+    source = IngestorSource(
+        format=fmt or "auto",
+        raw_content=raw_content,
+        path=filename,
+        metadata={"filename": filename},
+    )
+
+    all_ingestors = load_all_ingestors()
+    ingestor = get_ingestor_for_source(source, all_ingestors)
+
+    if ingestor is None:
+        raise HTTPException(
+            status_code=422,
+            detail=(
+                f"Could not detect format for artifact '{filename}'. "
+                "Supply a 'format' field."
+            ),
+        )
+
+    try:
+        ingest_result = await ingestor.ingest(source, config={})
+    except Exception as exc:  # noqa: BLE001
+        logger.exception("Ingestor %r failed for import/run", ingestor.name)
+        raise HTTPException(
+            status_code=422,
+            detail=f"Ingestor '{ingestor.name}' failed: {exc}",
+        ) from exc
+
+    if not ingest_result.success and not ingest_result.test_cases and not ingest_result.endpoints:
+        errors = "; ".join(ingest_result.errors) if ingest_result.errors else "unknown error"
+        raise HTTPException(status_code=422, detail=f"Ingestion produced no results: {errors}")
+
+    # ---- 3. Convert → scenario dicts ------------------------------------
+    effective_base_url = (base_url or target_url or "").strip() or "https://example.com"
+    effective_target_url = (target_url or base_url or "").strip() or "https://example.com"
+
+    bridge = IngestorBridge(base_url=effective_base_url, source_tag=ingestor.name)
+    raw_scenarios = bridge.convert(ingest_result)
+
+    # ---- 4. Store as a discovery ----------------------------------------
+    discovery_id = str(uuid.uuid4())
+    scenarios = [
+        DiscoveryScenario(
+            scenario_id=str(uuid.uuid4()),
+            url=s.get("url", effective_base_url),
+            steps=s.get("steps", []),
+            metadata=s.get("metadata", {}),
+            selected=True,
+            confidence=_assign_confidence(s),
+            risk_score=_assign_risk_score(s),
+        )
+        for s in raw_scenarios
+    ]
+
+    discovery_result = DiscoveryResult(
+        discovery_id=discovery_id,
+        status="complete",
+        base_url=effective_base_url,
+        scenarios=scenarios,
+        stats={
+            "pages_discovered": 0,
+            "forms_found": 0,
+            "flows_detected": 0,
+            "total_scenarios": len(scenarios),
+            "endpoints_ingested": len(ingest_result.endpoints),
+            "test_cases_ingested": len(ingest_result.test_cases),
+        },
+        created_at=datetime.now(timezone.utc).isoformat(),
+    )
+    _discoveries[discovery_id] = discovery_result
+    await broadcast_discovery_complete(discovery_id, len(scenarios))
+    asyncio.create_task(_persist_discovery(discovery_id))
+
+    # ---- 5. Spawn autonomous run with seeds -----------------------------
+    agent = AutonomousTestLoopAgent(
+        target_url=effective_target_url,
+        max_iterations=max(1, min(max_iterations, 20)),
+        strategy=strategy,
+        seeded_scenarios=raw_scenarios,
+    )
+    run_id = agent.run_id
+
+    # Store a placeholder autonomous run record (dict-based, same as standard runs)
+    _autonomous_runs[run_id] = {
+        "run_id": run_id,
+        "target_url": effective_target_url,
+        "strategy": strategy,
+        "status": "running",
+        "started_at": datetime.now(timezone.utc).isoformat(),
+        "total_iterations": 0,
+        "total_scenarios_executed": 0,
+        "total_passed": 0,
+        "total_failed": 0,
+        "total_flaky": 0,
+        "iterations": [],
+        "unique_failures": [],
+        "coverage_summary": {},
+        "seeded_scenarios_count": len(raw_scenarios),
+    }
+    asyncio.create_task(_persist_autonomous_run(run_id))
+
+    # Launch the autonomous loop in the background
+    async def _run_seeded_agent() -> None:
+        try:
+            result = await agent.run_loop()
+            _autonomous_runs[run_id].update(result.model_dump())
+            _autonomous_runs[run_id]["status"] = result.status
+            asyncio.create_task(_persist_autonomous_run(run_id))
+            await _compute_and_dispatch_delta(run_id, result)
+        except Exception:  # noqa: BLE001
+            logger.exception("Seeded autonomous run %s failed", run_id[:8])
+            _autonomous_runs[run_id]["status"] = "failed"
+        finally:
+            _autonomous_runs[run_id].pop("_agent", None)
+
+    asyncio.create_task(_run_seeded_agent())
+
+    return {
+        "run_id": run_id,
+        "discovery_id": discovery_id,
+        "status": "running",
+        "ingestor": ingestor.name,
+        "scenarios_seeded": len(raw_scenarios),
+        "target_url": effective_target_url,
+    }
+
+
+@router.get("/api/v1/discover/{discovery_id}")
+async def get_discovery(discovery_id: str) -> Dict[str, Any]:
+    """Return the current status and scenarios for a discovery run."""
+    result = _discoveries.get(discovery_id)
+    if result is None:
+        raise HTTPException(status_code=404, detail=f"Discovery '{discovery_id}' not found")
+    return result.model_dump()
+
+
+@router.put("/api/v1/discover/{discovery_id}/scenarios/{scenario_id}")
+async def update_scenario(
+    discovery_id: str,
+    scenario_id: str,
+    body: Dict[str, Any],
+) -> Dict[str, Any]:
+    """Apply a partial update to a scenario (steps, values, selection state)."""
+    result = _discoveries.get(discovery_id)
+    if result is None:
+        raise HTTPException(status_code=404, detail=f"Discovery '{discovery_id}' not found")
+    scenario = next((s for s in result.scenarios if s.scenario_id == scenario_id), None)
+    if scenario is None:
+        raise HTTPException(status_code=404, detail=f"Scenario '{scenario_id}' not found")
+
+    allowed_fields = {"url", "steps", "metadata", "selected", "confidence", "risk_score"}
+    for field, value in body.items():
+        if field in allowed_fields:
+            setattr(scenario, field, value)
+
+    return scenario.model_dump()
+
+
+@router.delete("/api/v1/discover/{discovery_id}/scenarios/{scenario_id}")
+async def delete_scenario(discovery_id: str, scenario_id: str) -> Dict[str, Any]:
+    """Remove a scenario from the suggestion list."""
+    result = _discoveries.get(discovery_id)
+    if result is None:
+        raise HTTPException(status_code=404, detail=f"Discovery '{discovery_id}' not found")
+    original_count = len(result.scenarios)
+    result.scenarios = [s for s in result.scenarios if s.scenario_id != scenario_id]
+    if len(result.scenarios) == original_count:
+        raise HTTPException(status_code=404, detail=f"Scenario '{scenario_id}' not found")
+    return {"deleted": scenario_id}
+
+
+@router.post("/api/v1/discover/{discovery_id}/run")
+async def run_scenarios(
+    discovery_id: str,
+    body: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Submit selected (or specified) scenarios to FunctionalTestOrchestrator."""
+    result = _discoveries.get(discovery_id)
+    if result is None:
+        raise HTTPException(status_code=404, detail=f"Discovery '{discovery_id}' not found")
+
+    scenario_ids: Optional[List[str]] = (body or {}).get("scenario_ids")
+    if scenario_ids is not None:
+        selected = [s for s in result.scenarios if s.scenario_id in scenario_ids]
+    else:
+        selected = [s for s in result.scenarios if s.selected]
+
+    if not selected:
+        raise HTTPException(status_code=422, detail="No scenarios selected for execution")
+
+    run_id = str(uuid.uuid4())
+    tasks = [
+        {"url": s.url, "steps": s.steps, "metadata": s.metadata}
+        for s in selected
+    ]
+
+    async def _run() -> None:
+        try:
+            from mannf.core.functional_orchestrator import FunctionalTestOrchestrator  # noqa: PLC0415
+            orch = FunctionalTestOrchestrator()
+            await orch.run(tasks)
+        except Exception:  # noqa: BLE001
+            logger.exception("Scenario run %s failed", run_id)
+
+    asyncio.create_task(_run())
+    return {"run_id": run_id, "scenarios_submitted": len(selected)}
+
+
+@router.websocket("/ws/live")
+async def websocket_live(ws: WebSocket) -> None:
+    """WebSocket endpoint for real-time dashboard updates during scans.
+
+    The client receives JSON messages with ``type`` and ``data`` fields:
+
+    - ``{"type": "ping"}`` — heartbeat every 5 s
+    - ``{"type": "scan_update", "data": {...}}`` — scan progress
+    - ``{"type": "anomaly", "data": {...}}`` — new anomaly detected
+    - ``{"type": "summary", "data": {...}}`` — updated summary stats
+    """
+    await manager.connect(ws)
+    try:
+        # Send an initial ping so the client knows the connection is alive
+        await ws.send_text(json.dumps({"type": "ping"}))
+        while True:
+            # Keep the connection alive with periodic pings; the client can
+            # also send messages (currently ignored but allows future use).
+            try:
+                await asyncio.wait_for(ws.receive_text(), timeout=5.0)
+            except asyncio.TimeoutError:
+                await ws.send_text(json.dumps({"type": "ping"}))
+    except WebSocketDisconnect:
+        pass
+    finally:
+        manager.disconnect(ws)
+
+
+# ---------------------------------------------------------------------------
+# Autonomous Test Loop endpoints (Phase 5)
+# ---------------------------------------------------------------------------
+
+
+async def _run_autonomous(run_id: str, req: AutonomousRequest) -> None:
+    """Background task: run the full autonomous test loop."""
+    from mannf.core.agents.autonomous_loop_agent import AutonomousTestLoopAgent  # noqa: PLC0415
+
+    report = _autonomous_runs[run_id]
+
+    # Build optional LLM provider
+    llm_provider = None
+    if req.llm_provider and req.llm_api_key:
+        try:
+            from mannf.product.llm.config import LLMConfig  # noqa: PLC0415
+            from mannf.product.llm.factory import get_provider  # noqa: PLC0415
+            config = LLMConfig(
+                provider=req.llm_provider,
+                model=req.llm_model or "",
+                api_key=req.llm_api_key,
+            )
+            candidate = get_provider(config)
+            if candidate.is_available():
+                llm_provider = candidate
+        except Exception:  # noqa: BLE001
+            logger.warning("Autonomous run %s: could not initialise LLM provider", run_id)
+
+    agent = AutonomousTestLoopAgent(
+        target_url=req.url,
+        max_iterations=req.max_iterations,
+        max_duration_s=req.max_duration_s,
+        strategy=req.strategy,
+        risk_threshold=req.risk_threshold,
+        max_pages=req.max_pages,
+        max_depth=req.max_depth,
+        headless=req.headless,
+        llm_provider=llm_provider,
+    )
+
+    # Store agent reference for stop support
+    _autonomous_runs[run_id]["_agent"] = agent
+
+    try:
+        result = await agent.run_loop()
+        # Propagate attribution fields from request into the report
+        if req.build_id:
+            result.build_id = req.build_id
+        if req.commit_sha:
+            result.commit_sha = req.commit_sha
+        if req.deploy_tag:
+            result.deploy_tag = req.deploy_tag
+        _autonomous_runs[run_id].update(result.model_dump())
+        _autonomous_runs[run_id]["status"] = result.status
+        if result.status == "paused":
+            _autonomous_runs[run_id]["_pause_state"] = agent.get_pause_state()
+        # Update flake detector with task outcomes from this run (Phase 6.5)
+        _update_flake_detector_from_run(run_id, result)
+        # Compute run-over-run diff and dispatch delta notifications
+        await _compute_and_dispatch_delta(run_id, result)
+        # File bug tickets for unique failures (fire-and-forget, non-blocking)
+        asyncio.create_task(_auto_file_bugs(run_id, result))
+    except Exception as exc:  # noqa: BLE001
+        logger.exception("Autonomous run %s failed", run_id)
+        _autonomous_runs[run_id]["status"] = "failed"
+        _autonomous_runs[run_id]["error"] = str(exc)
+    finally:
+        _autonomous_runs[run_id].pop("_agent", None)
+        await _persist_autonomous_run(run_id)
+
+
+@router.post("/api/v1/autonomous/start")
+async def start_autonomous(body: AutonomousRequest) -> Dict[str, Any]:
+    """Start an autonomous test loop run.
+
+    Returns immediately with a ``run_id``; progress is broadcast via
+    the ``/ws/live`` WebSocket connection.
+    """
+    run_id = str(uuid.uuid4())
+    _autonomous_runs[run_id] = {
+        "run_id": run_id,
+        "target_url": body.url,
+        "strategy": body.strategy,
+        "status": "running",
+        "started_at": datetime.now(timezone.utc).isoformat(),
+        "total_iterations": 0,
+        "total_scenarios_executed": 0,
+        "total_passed": 0,
+        "total_failed": 0,
+        "total_flaky": 0,
+        "iterations": [],
+        "unique_failures": [],
+        "coverage_summary": {},
+        # Deploy attribution (Phase 6.3)
+        "build_id": body.build_id,
+        "commit_sha": body.commit_sha,
+        "deploy_tag": body.deploy_tag,
+    }
+    asyncio.create_task(_persist_autonomous_run(run_id))
+    asyncio.create_task(_run_autonomous(run_id, body))
+    return {"run_id": run_id, "status": "running"}
+
+
+@router.get("/api/v1/autonomous/history")
+async def list_autonomous_runs() -> Dict[str, Any]:
+    """Return summaries of all past autonomous runs."""
+    summaries = []
+    for run_id, run in _autonomous_runs.items():
+        summaries.append(
+            {
+                "run_id": run_id,
+                "target_url": run.get("target_url", ""),
+                "strategy": run.get("strategy", ""),
+                "status": run.get("status", "unknown"),
+                "started_at": run.get("started_at", ""),
+                "completed_at": run.get("completed_at", ""),
+                "total_iterations": run.get("total_iterations", 0),
+                "total_passed": run.get("total_passed", 0),
+                "total_failed": run.get("total_failed", 0),
+            }
+        )
+    return {"runs": summaries}
+
+
+@router.get("/api/v1/autonomous/{run_id}")
+async def get_autonomous_run(run_id: str) -> Dict[str, Any]:
+    """Return the current status and partial results of an autonomous run."""
+    run = _autonomous_runs.get(run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail=f"Autonomous run '{run_id}' not found")
+    # Return a copy without the internal _agent reference
+    return {k: v for k, v in run.items() if not k.startswith("_")}
+
+
+@router.post("/api/v1/autonomous/{run_id}/stop")
+async def stop_autonomous_run(run_id: str) -> Dict[str, Any]:
+    """Gracefully stop a running autonomous loop."""
+    run = _autonomous_runs.get(run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail=f"Autonomous run '{run_id}' not found")
+
+    agent = run.get("_agent")
+    if agent is not None:
+        agent.request_stop()
+        return {"run_id": run_id, "status": "stopping"}
+
+    return {"run_id": run_id, "status": run.get("status", "unknown")}
+
+
+@router.post("/api/v1/autonomous/{run_id}/pause")
+async def pause_autonomous_run(run_id: str) -> Dict[str, Any]:
+    """Pause a running autonomous loop after the current iteration.
+
+    The run state is serialised so it can be resumed later via the
+    ``POST /api/v1/autonomous/{run_id}/resume`` endpoint.
+    """
+    run = _autonomous_runs.get(run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail=f"Autonomous run '{run_id}' not found")
+
+    agent = run.get("_agent")
+    if agent is None:
+        return {"run_id": run_id, "status": run.get("status", "unknown")}
+
+    agent.request_pause()
+    return {"run_id": run_id, "status": "pausing"}
+
+
+@router.post("/api/v1/autonomous/{run_id}/resume")
+async def resume_autonomous_run(run_id: str) -> Dict[str, Any]:
+    """Resume a previously paused autonomous run.
+
+    Reconstructs the agent from the saved pause state stored in the run
+    record and restarts the loop from the paused iteration.
+    """
+    from mannf.core.agents.autonomous_loop_agent import AutonomousTestLoopAgent  # noqa: PLC0415
+
+    run = _autonomous_runs.get(run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail=f"Autonomous run '{run_id}' not found")
+
+    if run.get("status") != "paused":
+        raise HTTPException(
+            status_code=422,
+            detail=f"Autonomous run '{run_id}' is not paused (status={run.get('status')})",
+        )
+
+    pause_state = run.get("_pause_state")
+    if not pause_state:
+        raise HTTPException(
+            status_code=422,
+            detail=f"No pause state available for run '{run_id}'",
+        )
+
+    # Reconstruct and restart the agent
+    agent = AutonomousTestLoopAgent.resume(pause_state)
+    _autonomous_runs[run_id]["status"] = "running"
+    _autonomous_runs[run_id]["_agent"] = agent
+
+    async def _continue() -> None:
+        try:
+            result = await agent.run_loop()
+            _autonomous_runs[run_id].update(result.model_dump())
+            _autonomous_runs[run_id]["status"] = result.status
+            # Update flake detector with task outcomes (Phase 6.5)
+            _update_flake_detector_from_run(run_id, result)
+            await _persist_autonomous_run(run_id)
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("Resumed autonomous run %s failed", run_id)
+            _autonomous_runs[run_id]["status"] = "failed"
+            _autonomous_runs[run_id]["error"] = str(exc)
+            await _persist_autonomous_run(run_id)
+        finally:
+            _autonomous_runs[run_id].pop("_agent", None)
+            _autonomous_runs[run_id].pop("_pause_state", None)
+
+    asyncio.create_task(_continue())
+    return {"run_id": run_id, "status": "running"}
+
+
+# ---------------------------------------------------------------------------
+# Delta diff helpers (Phase 6.3)
+# ---------------------------------------------------------------------------
+
+
+def _update_flake_detector_from_run(
+    run_id: str,
+    result: "AutonomousRunReport",
+) -> None:
+    """Feed autonomous run outcomes into the flake detector (Phase 6.5)."""
+    try:
+        for failure in result.unique_failures:
+            page_key = failure.get("page", failure.get("url", ""))
+            scenario_id = failure.get("task_id", "")
+            if page_key and scenario_id:
+                _flake_detector.record(page_key, scenario_id, passed=False)
+
+        # Also record pages that were covered without failure as passing
+        cs = result.coverage_summary or {}
+        covered_pages = cs.get("covered_pages", [])
+        failed_pages = {f.get("page", "") for f in result.unique_failures}
+        for page_key in covered_pages:
+            if page_key not in failed_pages:
+                # We don't have scenario-level pass data here; record as a
+                # synthetic "run-level" pass for the page using run_id as scenario
+                _flake_detector.record(page_key, run_id, passed=True)
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("_update_flake_detector_from_run failed (non-fatal): %s", exc)
+
+
+
+def _find_previous_run(current_run_id: str, target_url: str) -> Optional[Dict[str, Any]]:
+    """Return the most recent completed run for *target_url* other than *current_run_id*."""
+    candidates = [
+        run
+        for rid, run in _autonomous_runs.items()
+        if rid != current_run_id
+        and run.get("target_url") == target_url
+        and run.get("status") in {"complete", "stopped"}
+        and not run.get("error")
+    ]
+    if not candidates:
+        return None
+    # Sort by started_at descending
+    candidates.sort(key=lambda r: r.get("started_at", ""), reverse=True)
+    return candidates[0]
+
+
+def _run_dict_to_report(run: Dict[str, Any]) -> "AutonomousRunReport":
+    """Reconstruct an AutonomousRunReport from an in-memory run dict."""
+    from mannf.core.agents.autonomous_loop_models import AutonomousRunReport  # noqa: PLC0415
+
+    return AutonomousRunReport(
+        run_id=run.get("run_id", ""),
+        target_url=run.get("target_url", ""),
+        strategy=run.get("strategy", "all"),
+        total_iterations=run.get("total_iterations", 0),
+        total_scenarios_executed=run.get("total_scenarios_executed", 0),
+        total_passed=run.get("total_passed", 0),
+        total_failed=run.get("total_failed", 0),
+        total_flaky=run.get("total_flaky", 0),
+        unique_failures=run.get("unique_failures", []),
+        coverage_summary=run.get("coverage_summary", {}),
+        iterations=run.get("iterations", []),
+        started_at=run.get("started_at", ""),
+        completed_at=run.get("completed_at", ""),
+        duration_s=run.get("duration_s", 0.0),
+        stop_reason=run.get("stop_reason", ""),
+        status=run.get("status", ""),
+        error=run.get("error", ""),
+        build_id=run.get("build_id"),
+        commit_sha=run.get("commit_sha"),
+        deploy_tag=run.get("deploy_tag"),
+    )
+
+
+async def _compute_and_dispatch_delta(
+    run_id: str,
+    result: "AutonomousRunReport",
+) -> None:
+    """Compute the run-over-run diff and dispatch delta notifications (best-effort)."""
+    try:
+        from mannf.core.agents.autonomous_run_differ import AutonomousRunDiffer  # noqa: PLC0415
+        from mannf.product.notifications.dispatcher import dispatch_scan_notification  # noqa: PLC0415
+        from mannf.product.dashboard.telemetry import broadcast_autonomous_complete  # noqa: PLC0415
+
+        previous_run = _find_previous_run(run_id, result.target_url)
+        if previous_run is None:
+            return
+
+        baseline = _run_dict_to_report(previous_run)
+        differ = AutonomousRunDiffer()
+        run_diff = differ.diff(baseline, result)
+
+        # Store diff summary on the current run for retrieval
+        _autonomous_runs[run_id]["_last_diff"] = {
+            "baseline_run_id": run_diff.baseline_run_id,
+            "current_run_id": run_diff.current_run_id,
+            "baseline_commit": run_diff.baseline_commit,
+            "current_commit": run_diff.current_commit,
+            "summary": run_diff.summary,
+        }
+
+        # Re-broadcast with delta enrichment
+        await broadcast_autonomous_complete(
+            run_id=run_id,
+            stop_reason=result.stop_reason,
+            total_iterations=result.total_iterations,
+            total_passed=result.total_passed,
+            total_failed=result.total_failed,
+            delta=run_diff.summary,
+        )
+
+        commit_label = result.commit_sha or result.build_id or "unknown"
+        summary = run_diff.summary
+
+        # Dispatch regression notification if there are new failures
+        if summary.get("new_failure_count", 0) > 0:
+            await dispatch_scan_notification(
+                "autonomous_run.regression",
+                scan_id=run_id,
+                details={
+                    "new_failures": summary["new_failure_count"],
+                    "commit": commit_label,
+                    "target_url": result.target_url,
+                    "total_failed": result.total_failed,
+                },
+            )
+
+        # Dispatch recovery notification if failures were resolved
+        elif summary.get("resolved_failure_count", 0) > 0 and summary.get("new_failure_count", 0) == 0:
+            await dispatch_scan_notification(
+                "autonomous_run.recovery",
+                scan_id=run_id,
+                details={
+                    "resolved_failures": summary["resolved_failure_count"],
+                    "commit": commit_label,
+                    "target_url": result.target_url,
+                    "total_passed": result.total_passed,
+                },
+            )
+
+        # Dispatch flakiness spike notification
+        if summary.get("flakiness_spike_pages", 0) > 0:
+            await dispatch_scan_notification(
+                "autonomous_run.flake_spike",
+                scan_id=run_id,
+                details={
+                    "flakiness_spike_pages": summary["flakiness_spike_pages"],
+                    "commit": commit_label,
+                    "target_url": result.target_url,
+                },
+            )
+
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("Delta diff/alerting for run %s failed (non-fatal): %s", run_id, exc)
+
+
+# ---------------------------------------------------------------------------
+# Auto-bug-filing pipeline (Phase 6.4)
+# ---------------------------------------------------------------------------
+
+
+_SEVERITY_ORDER: dict[str, int] = {
+    "critical": 0,
+    "high": 1,
+    "medium": 2,
+    "low": 3,
+    "info": 4,
+}
+
+
+async def _auto_file_bugs(run_id: str, result: Any) -> None:
+    """Best-effort: file bug tickets for unique failures in *result*.
+
+    This runs as a background task and *never* raises — any error is logged
+    and silently swallowed to ensure the autonomous loop is never delayed.
+    """
+    try:
+        from mannf.product.exporters.finding_adapter import FunctionalFindingAdapter  # noqa: PLC0415
+        from mannf.product.exporters.dedup import (  # noqa: PLC0415
+            make_failure_fingerprint,
+            fingerprint_label,
+        )
+
+        cfg = _bug_filing_config
+        if not cfg.enabled:
+            return
+
+        unique_failures = getattr(result, "unique_failures", []) or []
+        if not unique_failures:
+            return
+
+        target_url = getattr(result, "target_url", "")
+        threshold_order = _SEVERITY_ORDER.get(cfg.severity_threshold.lower(), _SEVERITY_ORDER["high"])
+
+        for failure in unique_failures:
+            try:
+                finding = FunctionalFindingAdapter.from_unique_failure(
+                    failure, run_id=run_id, target_url=target_url
+                )
+                finding_order = _SEVERITY_ORDER.get(finding.severity.lower(), _SEVERITY_ORDER["info"])
+                if finding_order > threshold_order:
+                    # Below threshold — skip
+                    continue
+
+                fingerprint = make_failure_fingerprint(failure)
+                fp_label = fingerprint_label(fingerprint)
+
+                if not cfg.auto_file:
+                    # Queue for manual approval
+                    bug_id = str(uuid.uuid4())
+                    pending = PendingBugEntry(
+                        bug_id=bug_id,
+                        run_id=run_id,
+                        fingerprint=fingerprint,
+                        failure=failure,
+                        severity=finding.severity,
+                        queued_at=datetime.now(timezone.utc).isoformat(),
+                    )
+                    _pending_bugs[bug_id] = pending
+                    logger.info(
+                        "Auto-filing queued for approval: bug_id=%s fingerprint=%s",
+                        bug_id,
+                        fingerprint[:16],
+                    )
+                    continue
+
+                # Auto-file the ticket
+                report = FunctionalFindingAdapter.make_report(
+                    run_id, target_url, len(unique_failures)
+                )
+                # Add fingerprint label so dedup can find it later
+                exporter_cfg = dict(cfg.exporter_config)
+                existing_labels = list(exporter_cfg.get("labels") or [])
+                exporter_cfg["labels"] = list({*existing_labels, fp_label, "nat-auto-filed"})
+
+                was_duplicate = False
+                external_id: Optional[str] = None
+                external_url: Optional[str] = None
+
+                if cfg.deduplicate:
+                    # Check for existing ticket
+                    existing = await _find_existing_bug(fingerprint, cfg)
+                    if existing:
+                        was_duplicate = True
+                        external_id = existing.get("id")
+                        external_url = existing.get("url")
+                        # Add a new-occurrence comment
+                        await _add_duplicate_comment(
+                            existing, cfg, run_id, fingerprint, failure
+                        )
+
+                if not was_duplicate:
+                    result_obj = await _call_exporter(finding, report, cfg.target_system, exporter_cfg)
+                    if result_obj:
+                        external_id = result_obj.external_id
+                        external_url = result_obj.external_url
+
+                bug_id = str(uuid.uuid4())
+                filed = FiledBugEntry(
+                    bug_id=bug_id,
+                    run_id=run_id,
+                    fingerprint=fingerprint,
+                    failure=failure,
+                    target_system=cfg.target_system,
+                    external_id=external_id,
+                    external_url=external_url,
+                    severity=finding.severity,
+                    filed_at=datetime.now(timezone.utc).isoformat(),
+                    was_duplicate=was_duplicate,
+                )
+                _filed_bugs[bug_id] = filed
+                logger.info(
+                    "Auto-filed bug: bug_id=%s target=%s external_id=%s duplicate=%s",
+                    bug_id,
+                    cfg.target_system,
+                    external_id,
+                    was_duplicate,
+                )
+
+            except Exception as inner_exc:  # noqa: BLE001
+                logger.warning(
+                    "Auto-filing failed for failure in run %s (non-fatal): %s",
+                    run_id,
+                    inner_exc,
+                )
+
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("_auto_file_bugs for run %s failed (non-fatal): %s", run_id, exc)
+
+
+async def _find_existing_bug(fingerprint: str, cfg: BugFilingConfig) -> Optional[Dict[str, Any]]:
+    """Check the external system for an existing open ticket with this fingerprint."""
+    try:
+        from mannf.product.exporters.dedup import (  # noqa: PLC0415
+            find_existing_jira_issue,
+            find_existing_github_issue,
+        )
+
+        if cfg.target_system == "jira":
+            ec = cfg.exporter_config
+            key = await find_existing_jira_issue(
+                fingerprint,
+                base_url=ec.get("base_url", ""),
+                project_key=ec.get("project_key", ""),
+                email=ec.get("email", ""),
+                api_token=ec.get("api_token", ""),
+            )
+            if key:
+                base_url = ec.get("base_url", "").rstrip("/")
+                return {"id": key, "url": f"{base_url}/browse/{key}"}
+
+        elif cfg.target_system == "github":
+            ec = cfg.exporter_config
+            number = await find_existing_github_issue(
+                fingerprint,
+                token=ec.get("token", ""),
+                repo=ec.get("repo", ""),
+            )
+            if number is not None:
+                repo = ec.get("repo", "")
+                return {
+                    "id": str(number),
+                    "url": f"https://github.com/{repo}/issues/{number}",
+                }
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("Dedup check failed (non-fatal): %s", exc)
+    return None
+
+
+async def _add_duplicate_comment(
+    existing: Dict[str, Any],
+    cfg: BugFilingConfig,
+    run_id: str,
+    fingerprint: str,
+    failure: Dict[str, Any],
+) -> None:
+    """Append a new-occurrence comment to an existing ticket."""
+    try:
+        from mannf.product.exporters.dedup import (  # noqa: PLC0415
+            add_jira_comment,
+            add_github_comment,
+        )
+
+        comment = (
+            f"**New occurrence detected** (run `{run_id}`)\n\n"
+            f"- Page: `{failure.get('page', '?')}`\n"
+            f"- Error: {failure.get('error', '?')[:200]}\n"
+            f"- Fingerprint: `{fingerprint[:16]}…`\n"
+        )
+        ec = cfg.exporter_config
+
+        if cfg.target_system == "jira":
+            await add_jira_comment(
+                existing["id"],
+                comment,
+                base_url=ec.get("base_url", ""),
+                email=ec.get("email", ""),
+                api_token=ec.get("api_token", ""),
+            )
+
+        elif cfg.target_system == "github":
+            await add_github_comment(
+                int(existing["id"]),
+                comment,
+                token=ec.get("token", ""),
+                repo=ec.get("repo", ""),
+            )
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("Duplicate comment failed (non-fatal): %s", exc)
+
+
+async def _call_exporter(
+    finding: Any,
+    report: Any,
+    target_system: str,
+    exporter_config: dict,
+) -> Optional[Any]:
+    """Instantiate the correct exporter and call export_finding."""
+    try:
+        if target_system == "jira":
+            from mannf.product.exporters.jira_exporter import JiraExporter  # noqa: PLC0415
+            return await JiraExporter().export_finding(finding, report, exporter_config)
+
+        elif target_system == "github":
+            from mannf.product.exporters.github_exporter import GitHubIssuesExporter  # noqa: PLC0415
+            return await GitHubIssuesExporter().export_finding(finding, report, exporter_config)
+
+        elif target_system == "webhook":
+            from mannf.product.exporters.webhook_exporter import WebhookExporter  # noqa: PLC0415
+            return await WebhookExporter().export_finding(finding, report, exporter_config)
+
+        else:
+            logger.warning("Unknown target_system '%s' — skipping export", target_system)
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("_call_exporter(%s) failed (non-fatal): %s", target_system, exc)
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Bug filing REST API (Phase 6.4)
+# ---------------------------------------------------------------------------
+
+
+@router.get("/api/v1/bugs/config")
+async def get_bug_filing_config() -> Dict[str, Any]:
+    """Return the current auto-bug-filing configuration."""
+    return _bug_filing_config.model_dump()
+
+
+@router.put("/api/v1/bugs/config")
+async def update_bug_filing_config(body: BugFilingConfig) -> Dict[str, Any]:
+    """Update the auto-bug-filing configuration."""
+    global _bug_filing_config
+    _bug_filing_config = body
+    return _bug_filing_config.model_dump()
+
+
+@router.get("/api/v1/bugs/filed")
+async def list_filed_bugs() -> Dict[str, Any]:
+    """Return all auto-filed bug tickets with external links."""
+    sorted_bugs = sorted(_filed_bugs.values(), key=lambda b: b.filed_at, reverse=True)
+    return {
+        "total": len(_filed_bugs),
+        "bugs": [b.model_dump() for b in sorted_bugs],
+    }
+
+
+@router.get("/api/v1/bugs/pending")
+async def list_pending_bugs() -> Dict[str, Any]:
+    """Return the queue of failures awaiting manual approval."""
+    pending = [
+        b.model_dump()
+        for b in sorted(
+            _pending_bugs.values(),
+            key=lambda b: b.queued_at,
+            reverse=True,
+        )
+        if b.status == "pending"
+    ]
+    return {"total": len(pending), "bugs": pending}
+
+
+@router.post("/api/v1/bugs/{bug_id}/approve")
+async def approve_pending_bug(bug_id: str) -> Dict[str, Any]:
+    """Approve a pending bug and immediately file a ticket in the configured system.
+
+    Moves the entry from the pending queue to the filed list.
+    """
+    entry = _pending_bugs.get(bug_id)
+    if entry is None:
+        raise HTTPException(status_code=404, detail=f"Pending bug '{bug_id}' not found")
+    if entry.status != "pending":
+        raise HTTPException(
+            status_code=409,
+            detail=f"Bug '{bug_id}' has already been {entry.status}",
+        )
+
+    entry.status = "approved"
+
+    # File the ticket now
+    try:
+        from mannf.product.exporters.finding_adapter import FunctionalFindingAdapter  # noqa: PLC0415
+        from mannf.product.exporters.dedup import fingerprint_label  # noqa: PLC0415
+
+        cfg = _bug_filing_config
+        finding = FunctionalFindingAdapter.from_unique_failure(
+            entry.failure, run_id=entry.run_id
+        )
+        report = FunctionalFindingAdapter.make_report(
+            entry.run_id, entry.failure.get("url", ""), 1
+        )
+        fp_label = fingerprint_label(entry.fingerprint)
+        exporter_cfg = dict(cfg.exporter_config)
+        existing_labels = list(exporter_cfg.get("labels") or [])
+        exporter_cfg["labels"] = list({*existing_labels, fp_label, "nat-auto-filed"})
+
+        result_obj = await _call_exporter(finding, report, cfg.target_system, exporter_cfg)
+
+        filed = FiledBugEntry(
+            bug_id=str(uuid.uuid4()),
+            run_id=entry.run_id,
+            fingerprint=entry.fingerprint,
+            failure=entry.failure,
+            target_system=cfg.target_system,
+            external_id=result_obj.external_id if result_obj else None,
+            external_url=result_obj.external_url if result_obj else None,
+            severity=entry.severity,
+            filed_at=datetime.now(timezone.utc).isoformat(),
+        )
+        _filed_bugs[filed.bug_id] = filed
+
+        return {
+            "bug_id": bug_id,
+            "status": "approved",
+            "filed_bug_id": filed.bug_id,
+            "external_id": filed.external_id,
+            "external_url": filed.external_url,
+        }
+
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("approve_pending_bug %s: filing failed: %s", bug_id, exc)
+        return {"bug_id": bug_id, "status": "approved", "error": "Filing failed — see server logs for details."}
+
+
+@router.post("/api/v1/bugs/{bug_id}/dismiss")
+async def dismiss_pending_bug(bug_id: str) -> Dict[str, Any]:
+    """Dismiss a pending bug — no ticket will be filed."""
+    entry = _pending_bugs.get(bug_id)
+    if entry is None:
+        raise HTTPException(status_code=404, detail=f"Pending bug '{bug_id}' not found")
+    if entry.status != "pending":
+        raise HTTPException(
+            status_code=409,
+            detail=f"Bug '{bug_id}' has already been {entry.status}",
+        )
+
+    entry.status = "dismissed"
+    return {"bug_id": bug_id, "status": "dismissed"}
+
+
+# ---------------------------------------------------------------------------
+# Analytics endpoints (Phase 6.3)
+# ---------------------------------------------------------------------------
+
+
+@router.get("/api/v1/analytics/trends")
+async def get_analytics_trends(
+    page: Optional[str] = Query(None, description="Filter by page path (e.g. /checkout)"),
+    window: str = Query("7d", description="Time window: 1d, 7d, 30d"),
+    target_url: Optional[str] = Query(None, description="Filter by target URL"),
+) -> Dict[str, Any]:
+    """Return pass rate, failure rate, and flakiness trends over completed autonomous runs.
+
+    Query parameters
+    ----------------
+    page:
+        Optional page path filter (e.g. ``/checkout``).
+    window:
+        Time window: ``1d``, ``7d`` (default), or ``30d``.
+    target_url:
+        Optional target URL to filter runs.
+    """
+    from datetime import timedelta  # noqa: PLC0415
+
+    window_map = {"1d": 1, "7d": 7, "30d": 30}
+    days = window_map.get(window, 7)
+    cutoff = datetime.now(timezone.utc) - timedelta(days=days)
+
+    data_points = []
+    for run in sorted(
+        _autonomous_runs.values(),
+        key=lambda r: r.get("started_at", ""),
+    ):
+        if run.get("status") not in {"complete", "stopped"}:
+            continue
+        if target_url and run.get("target_url") != target_url:
+            continue
+
+        started_at_raw = run.get("started_at", "")
+        try:
+            started_dt = datetime.fromisoformat(started_at_raw)
+            if started_dt.tzinfo is None:
+                from datetime import timezone as _tz  # noqa: PLC0415
+                started_dt = started_dt.replace(tzinfo=_tz.utc)
+        except (ValueError, TypeError):
+            continue
+
+        if started_dt < cutoff:
+            continue
+
+        total_executed = run.get("total_scenarios_executed", 0)
+        total_passed = run.get("total_passed", 0)
+        total_failed = run.get("total_failed", 0)
+        total_flaky = run.get("total_flaky", 0)
+
+        # Apply page filter if supplied
+        if page:
+            cs = run.get("coverage_summary") or {}
+            covered = cs.get("covered_pages", [])
+            if page not in covered:
+                continue
+
+        pass_rate = round(total_passed / total_executed, 4) if total_executed > 0 else None
+        fail_rate = round(total_failed / total_executed, 4) if total_executed > 0 else None
+        flaky_rate = round(total_flaky / total_executed, 4) if total_executed > 0 else None
+
+        data_points.append(
+            {
+                "run_id": run.get("run_id", ""),
+                "started_at": started_at_raw,
+                "target_url": run.get("target_url", ""),
+                "total_passed": total_passed,
+                "total_failed": total_failed,
+                "total_flaky": total_flaky,
+                "total_scenarios_executed": total_executed,
+                "pass_rate": pass_rate,
+                "fail_rate": fail_rate,
+                "flaky_rate": flaky_rate,
+                "commit_sha": run.get("commit_sha"),
+                "build_id": run.get("build_id"),
+                "deploy_tag": run.get("deploy_tag"),
+            }
+        )
+
+    return {
+        "window": window,
+        "page_filter": page,
+        "target_url_filter": target_url,
+        "data_points": data_points,
+        "count": len(data_points),
+    }
+
+
+@router.get("/api/v1/analytics/coverage")
+async def get_analytics_coverage(
+    run_id: Optional[str] = Query(None, description="Run ID to inspect coverage for"),
+) -> Dict[str, Any]:
+    """Return coverage breakdown for an autonomous run.
+
+    If ``run_id`` is omitted, returns coverage for the most recent completed run.
+
+    Coverage includes:
+    - Pages covered
+    - Forms tested
+    - Flows executed
+    - Security payloads attempted (if security scenarios were enabled)
+    """
+    if run_id:
+        run = _autonomous_runs.get(run_id)
+        if run is None:
+            raise HTTPException(status_code=404, detail=f"Run '{run_id}' not found")
+    else:
+        # Pick most recent completed run
+        completed = [
+            r
+            for r in _autonomous_runs.values()
+            if r.get("status") in {"complete", "stopped"}
+        ]
+        if not completed:
+            raise HTTPException(status_code=404, detail="No completed autonomous runs found")
+        completed.sort(key=lambda r: r.get("started_at", ""), reverse=True)
+        run = completed[0]
+
+    cs = run.get("coverage_summary") or {}
+
+    return {
+        "run_id": run.get("run_id", ""),
+        "target_url": run.get("target_url", ""),
+        "status": run.get("status", ""),
+        "started_at": run.get("started_at", ""),
+        "completed_at": run.get("completed_at", ""),
+        "pages_covered": cs.get("covered_pages", []),
+        "page_count": len(cs.get("covered_pages", [])),
+        "forms_tested": cs.get("forms_tested", 0),
+        "flows_executed": cs.get("flows_executed", 0),
+        "security_fields_tested": cs.get("security_fields_tested", 0),
+        "security_payloads_attempted": cs.get("security_payloads_attempted", 0),
+        "security_exploits_found": cs.get("security_exploits_found", 0),
+        "owasp_coverage": cs.get("owasp_coverage", []),
+        "coverage_summary": cs,
+    }
+
+
+@router.post("/api/v1/autonomous/diff")
+async def diff_autonomous_runs(body: Dict[str, Any]) -> Dict[str, Any]:
+    """Compare two autonomous runs and return a structured diff.
+
+    Request body
+    ------------
+    ``baseline_run_id`` : str
+        Run ID of the baseline (earlier) run.
+    ``current_run_id`` : str
+        Run ID of the current (later) run to compare against the baseline.
+
+    Returns
+    -------
+    Structured diff including new failures, resolved failures, per-page deltas,
+    flakiness changes, and coverage delta.
+    """
+    from mannf.core.agents.autonomous_run_differ import AutonomousRunDiffer  # noqa: PLC0415
+    from dataclasses import asdict  # noqa: PLC0415
+
+    baseline_id = body.get("baseline_run_id")
+    current_id = body.get("current_run_id")
+
+    if not baseline_id or not current_id:
+        raise HTTPException(
+            status_code=422,
+            detail="Both 'baseline_run_id' and 'current_run_id' are required",
+        )
+
+    baseline_run = _autonomous_runs.get(baseline_id)
+    if baseline_run is None:
+        raise HTTPException(status_code=404, detail=f"Baseline run '{baseline_id}' not found")
+
+    current_run = _autonomous_runs.get(current_id)
+    if current_run is None:
+        raise HTTPException(status_code=404, detail=f"Current run '{current_id}' not found")
+
+    baseline_report = _run_dict_to_report(baseline_run)
+    current_report = _run_dict_to_report(current_run)
+
+    differ = AutonomousRunDiffer()
+    run_diff = differ.diff(baseline_report, current_report)
+
+    return {
+        "baseline_run_id": run_diff.baseline_run_id,
+        "current_run_id": run_diff.current_run_id,
+        "baseline_commit": run_diff.baseline_commit,
+        "current_commit": run_diff.current_commit,
+        "baseline_build": run_diff.baseline_build,
+        "current_build": run_diff.current_build,
+        "summary": run_diff.summary,
+        "new_failures": [asdict(f) for f in run_diff.new_failures],
+        "resolved_failures": [asdict(f) for f in run_diff.resolved_failures],
+        "page_deltas": [asdict(d) for d in run_diff.page_deltas],
+        "flakiness_changes": [asdict(c) for c in run_diff.flakiness_changes],
+        "coverage_delta": asdict(run_diff.coverage_delta),
+    }
+
+
+async def _persist_autonomous_run(run_id: str) -> None:
+    """Upsert the current in-memory autonomous run entry to PostgreSQL (no-op if no DB)."""
+    try:
+        from mannf.product.database import _async_session_factory, _build_engine  # noqa: PLC0415
+
+        if _build_engine() is None or _async_session_factory is None:
+            return
+
+        from mannf.product.models import AutonomousRun  # noqa: PLC0415
+
+        entry = _autonomous_runs.get(run_id)
+        if entry is None:
+            return
+
+        async with _async_session_factory() as session:
+            obj = await session.get(AutonomousRun, uuid.UUID(run_id))
+            if obj is None:
+                obj = AutonomousRun(id=uuid.UUID(run_id))
+                session.add(obj)
+
+            obj.status = str(entry.get("status", ""))
+            obj.target_url = entry.get("target_url")
+            obj.strategy = entry.get("strategy")
+            # Store full run data minus internal keys
+            obj.report = {k: v for k, v in entry.items() if not k.startswith("_")}
+            obj.error = entry.get("error")
+
+            raw_created = entry.get("created_at")
+            if raw_created:
+                try:
+                    obj.created_at = datetime.fromisoformat(raw_created)
+                except (ValueError, TypeError):
+                    pass
+
+            raw_completed = entry.get("completed_at")
+            if raw_completed:
+                try:
+                    obj.completed_at = datetime.fromisoformat(raw_completed)
+                except (ValueError, TypeError):
+                    pass
+
+            raw_tid = entry.get("tenant_id")
+            obj.tenant_id = uuid.UUID(raw_tid) if raw_tid else None
+
+            await session.commit()
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("DB persist_autonomous_run %s failed: %s", run_id, exc)
+
+
+async def _persist_discovery(discovery_id: str) -> None:
+    """Upsert the current in-memory discovery result to PostgreSQL (no-op if no DB)."""
+    try:
+        from mannf.product.database import _async_session_factory, _build_engine  # noqa: PLC0415
+
+        if _build_engine() is None or _async_session_factory is None:
+            return
+
+        from mannf.product.models import DiscoveryRun  # noqa: PLC0415
+
+        result = _discoveries.get(discovery_id)
+        if result is None:
+            return
+
+        async with _async_session_factory() as session:
+            obj = await session.get(DiscoveryRun, uuid.UUID(discovery_id))
+            if obj is None:
+                obj = DiscoveryRun(id=uuid.UUID(discovery_id))
+                session.add(obj)
+
+            obj.status = result.status
+            obj.base_url = result.base_url
+            obj.scenarios = [s.model_dump() for s in result.scenarios]
+            obj.stats = result.stats
+            obj.error = result.error
+
+            raw_created = result.created_at
+            if raw_created:
+                try:
+                    obj.created_at = datetime.fromisoformat(raw_created)
+                except (ValueError, TypeError):
+                    pass
+
+            await session.commit()
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("DB persist_discovery %s failed: %s", discovery_id, exc)
+
+
+async def _preload_autonomous_runs() -> None:
+    """Pre-populate ``_autonomous_runs`` from PostgreSQL on startup."""
+    try:
+        from mannf.product.database import _async_session_factory, _build_engine  # noqa: PLC0415
+
+        if _build_engine() is None or _async_session_factory is None:
+            return
+
+        from sqlalchemy import select, desc  # noqa: PLC0415
+        from mannf.product.models import AutonomousRun  # noqa: PLC0415
+
+        async with _async_session_factory() as session:
+            result = await session.execute(
+                select(AutonomousRun)
+                .order_by(desc(AutonomousRun.created_at))
+                .limit(200)
+            )
+            count = 0
+            for row in result.scalars():
+                run_id = str(row.id)
+                if run_id not in _autonomous_runs:
+                    entry = row.report or {}
+                    entry["run_id"] = run_id
+                    entry["status"] = row.status
+                    entry["target_url"] = row.target_url
+                    entry["strategy"] = row.strategy
+                    entry["error"] = row.error
+                    entry["created_at"] = (
+                        row.created_at.isoformat() if row.created_at else None
+                    )
+                    entry["completed_at"] = (
+                        row.completed_at.isoformat() if row.completed_at else None
+                    )
+                    _autonomous_runs[run_id] = entry
+                    count += 1
+        logger.info("Preloaded %d autonomous runs from DB", count)
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("DB preload_autonomous_runs failed (continuing in-memory only): %s", exc)
+
+
+async def _preload_discoveries() -> None:
+    """Pre-populate ``_discoveries`` from PostgreSQL on startup."""
+    try:
+        from mannf.product.database import _async_session_factory, _build_engine  # noqa: PLC0415
+
+        if _build_engine() is None or _async_session_factory is None:
+            return
+
+        from sqlalchemy import select, desc  # noqa: PLC0415
+        from mannf.product.models import DiscoveryRun  # noqa: PLC0415
+
+        async with _async_session_factory() as session:
+            result = await session.execute(
+                select(DiscoveryRun)
+                .order_by(desc(DiscoveryRun.created_at))
+                .limit(200)
+            )
+            count = 0
+            for row in result.scalars():
+                discovery_id = str(row.id)
+                if discovery_id not in _discoveries:
+                    raw_scenarios = row.scenarios or []
+                    scenarios = []
+                    for s in raw_scenarios:
+                        try:
+                            scenarios.append(DiscoveryScenario(**s))
+                        except Exception:  # noqa: BLE001
+                            pass
+                    _discoveries[discovery_id] = DiscoveryResult(
+                        discovery_id=discovery_id,
+                        status=row.status,
+                        base_url=row.base_url or "",
+                        scenarios=scenarios,
+                        stats=row.stats or {},
+                        error=row.error,
+                        created_at=(
+                            row.created_at.isoformat() if row.created_at else ""
+                        ),
+                    )
+                    count += 1
+        logger.info("Preloaded %d discovery runs from DB", count)
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("DB preload_discoveries failed (continuing in-memory only): %s", exc)
+
+
+# ---------------------------------------------------------------------------
+# ML/LLM Diagnostics analytics endpoints (Phase 6.5)
+# ---------------------------------------------------------------------------
+
+
+@router.get("/api/v1/analytics/beliefs", response_model=List[BeliefTrend])
+async def get_belief_trends(
+    page: Optional[str] = Query(None, description="Filter by page path (e.g. /checkout)"),
+    window: str = Query("30d", description="Time window: 1d, 7d, 30d"),
+    run_id: Optional[str] = Query(None, description="Filter by specific run ID"),
+) -> List[BeliefTrend]:
+    """Return time-series fault_likelihood belief snapshots per page.
+
+    Query parameters
+    ----------------
+    page:
+        Optional page path filter (e.g. ``/checkout``).
+    window:
+        Time window: ``1d``, ``7d`` (default), or ``30d``.
+    run_id:
+        When supplied, return snapshots from that run only.
+    """
+    from datetime import timedelta  # noqa: PLC0415
+
+    window_map = {"1d": 1, "7d": 7, "30d": 30}
+    days = window_map.get(window, 30)
+    cutoff = datetime.now(timezone.utc) - timedelta(days=days)
+
+    results: List[BeliefTrend] = []
+
+    runs_to_scan = (
+        {run_id: _autonomous_runs[run_id]}
+        if run_id and run_id in _autonomous_runs
+        else _autonomous_runs
+    )
+
+    for rid, run in runs_to_scan.items():
+        snapshots = run.get("belief_snapshots") or []
+        for snap in snapshots:
+            ts_str = snap.get("timestamp", "")
+            try:
+                ts = datetime.fromisoformat(ts_str)
+                if ts.tzinfo is None:
+                    ts = ts.replace(tzinfo=timezone.utc)
+                if ts < cutoff:
+                    continue
+            except (ValueError, TypeError):
+                continue
+
+            iteration = snap.get("iteration", 0)
+            beliefs = snap.get("beliefs") or {}
+
+            for page_key, fault_likelihood in beliefs.items():
+                if page and page_key != page:
+                    continue
+                results.append(
+                    BeliefTrend(
+                        run_id=rid,
+                        iteration=iteration,
+                        page_key=page_key,
+                        fault_likelihood=float(fault_likelihood),
+                        timestamp=ts_str,
+                    )
+                )
+
+    # Sort by timestamp then iteration
+    results.sort(key=lambda r: (r.timestamp, r.iteration))
+    return results
+
+
+@router.get("/api/v1/analytics/flakiness", response_model=List[FlakinessSummary])
+async def get_flakiness_summary(
+    page: Optional[str] = Query(None, description="Filter by page path"),
+    flaky_only: bool = Query(False, description="Return only flaky scenarios"),
+) -> List[FlakinessSummary]:
+    """Return flakiness statistics per scenario.
+
+    Aggregates pass/fail history from all persisted autonomous runs using the
+    in-process :class:`~mannf.core.diagnostics.flake_detector.FlakeDetector`.
+
+    Query parameters
+    ----------------
+    page:
+        Optional page path filter.
+    flaky_only:
+        When ``True``, return only scenarios labelled flaky.
+    """
+    summaries = _flake_detector.all_summaries()
+
+    results: List[FlakinessSummary] = []
+    for s in summaries:
+        if page and s.page_key != page:
+            continue
+        if flaky_only and not s.is_flaky:
+            continue
+        results.append(
+            FlakinessSummary(
+                page_key=s.page_key,
+                scenario_id=s.scenario_id,
+                is_flaky=s.is_flaky,
+                flake_rate=s.flake_rate,
+                total_runs=s.total_runs,
+                pass_count=s.pass_count,
+                fail_count=s.fail_count,
+                alternations=s.alternations,
+            )
+        )
+
+    # Sort by flake_rate descending so worst offenders come first
+    results.sort(key=lambda s: s.flake_rate, reverse=True)
+    return results
+
+
+@router.get("/api/v1/analytics/clusters", response_model=List[FailureCluster])
+async def get_failure_clusters(
+    run_id: Optional[str] = Query(None, description="Run ID to cluster failures from"),
+    threshold: float = Query(0.4, description="Cosine similarity threshold (0.0–1.0)"),
+) -> List[FailureCluster]:
+    """Cluster failures by error-message similarity using TF-IDF cosine distance.
+
+    Query parameters
+    ----------------
+    run_id:
+        When supplied, only cluster failures from that run.  Otherwise,
+        aggregates failures from the 10 most recent completed runs.
+    threshold:
+        Cosine similarity threshold in (0, 1].  Higher values produce
+        tighter (more homogeneous) clusters.
+    """
+    from mannf.core.diagnostics.failure_clusterer import FailureClusterer  # noqa: PLC0415
+
+    failures: List[Dict[str, Any]] = []
+
+    if run_id:
+        run = _autonomous_runs.get(run_id)
+        if run is None:
+            raise HTTPException(status_code=404, detail=f"Run '{run_id}' not found")
+        failures = list(run.get("unique_failures") or [])
+    else:
+        # Aggregate from the 10 most recent completed runs
+        completed = [
+            r
+            for r in _autonomous_runs.values()
+            if r.get("status") in {"complete", "stopped"}
+        ]
+        completed.sort(key=lambda r: r.get("started_at", ""), reverse=True)
+        for run in completed[:10]:
+            failures.extend(run.get("unique_failures") or [])
+
+    if not failures:
+        return []
+
+    try:
+        clusterer = FailureClusterer(threshold=threshold)
+    except ValueError:
+        raise HTTPException(status_code=422, detail="threshold must be in (0, 1]")
+
+    raw_clusters = clusterer.cluster(failures)
+    return [
+        FailureCluster(
+            cluster_id=c.cluster_id,
+            label=c.label,
+            representative_error=c.representative_error,
+            pages=c.pages,
+            size=c.size,
+            failures=c.failures,
+        )
+        for c in raw_clusters
+    ]
+
+
+@router.get("/api/v1/analytics/predictions", response_model=List[PredictiveRiskScore])
+async def get_predictive_risk(
+    target_url: Optional[str] = Query(None, description="Filter by target URL"),
+    top_k: int = Query(10, description="Maximum number of pages to return", ge=1, le=100),
+) -> List[PredictiveRiskScore]:
+    """Return predicted failure probability per page for the next run.
+
+    Predictive score is computed from:
+    - **Belief momentum** — rate of change in ``fault_likelihood`` across the
+      last 5 belief snapshots for the page.
+    - **Recent failure density** — fraction of failures on the page across the
+      last 5 completed runs.
+
+    Query parameters
+    ----------------
+    target_url:
+        Optional target URL to filter runs.
+    top_k:
+        Maximum number of pages to return (highest predicted risk first).
+    """
+    # Gather the most recent completed runs
+    completed = [
+        r
+        for r in _autonomous_runs.values()
+        if r.get("status") in {"complete", "stopped"}
+        and (not target_url or r.get("target_url") == target_url)
+    ]
+    completed.sort(key=lambda r: r.get("started_at", ""), reverse=True)
+    recent_runs = completed[:5]
+
+    if not recent_runs:
+        return []
+
+    # Per-page: collect the last N fault_likelihood values from snapshots
+    page_belief_history: Dict[str, List[float]] = {}
+    # Per-page: failure density
+    page_failure_counts: Dict[str, int] = {}
+    total_failure_scenarios = 0
+
+    for run in recent_runs:
+        snapshots = run.get("belief_snapshots") or []
+        for snap in snapshots:
+            beliefs = snap.get("beliefs") or {}
+            for pk, fl in beliefs.items():
+                page_belief_history.setdefault(pk, []).append(float(fl))
+
+        for failure in run.get("unique_failures") or []:
+            pk = failure.get("page", failure.get("url", ""))
+            if pk:
+                page_failure_counts[pk] = page_failure_counts.get(pk, 0) + 1
+            total_failure_scenarios += 1
+
+    all_pages = set(page_belief_history) | set(page_failure_counts)
+    scores: List[PredictiveRiskScore] = []
+
+    for pk in all_pages:
+        belief_vals = page_belief_history.get(pk, [])
+        # Belief momentum: average delta between consecutive snapshots
+        if len(belief_vals) >= 2:
+            deltas = [belief_vals[i] - belief_vals[i - 1] for i in range(1, len(belief_vals))]
+            belief_momentum = sum(deltas) / len(deltas)
+        else:
+            belief_momentum = 0.0
+
+        latest_belief = belief_vals[-1] if belief_vals else 0.5
+
+        failure_density = (
+            page_failure_counts.get(pk, 0) / total_failure_scenarios
+            if total_failure_scenarios > 0
+            else 0.0
+        )
+
+        # Combine signals: weighted average of latest belief, momentum push, and failure density
+        raw_prob = (
+            0.5 * latest_belief
+            + 0.3 * max(0.0, belief_momentum)  # positive momentum = degradation
+            + 0.2 * failure_density
+        )
+        predicted_prob = round(max(0.0, min(1.0, raw_prob)), 4)
+
+        # Confidence: how many data points we have
+        n_obs = len(belief_vals) + page_failure_counts.get(pk, 0)
+        confidence = round(min(0.95, n_obs / (n_obs + 5)), 4)
+
+        scores.append(
+            PredictiveRiskScore(
+                page_key=pk,
+                predicted_failure_probability=predicted_prob,
+                belief_momentum=round(belief_momentum, 4),
+                recent_failure_density=round(failure_density, 4),
+                confidence=confidence,
+            )
+        )
+
+    scores.sort(key=lambda s: s.predicted_failure_probability, reverse=True)
+    return scores[:top_k]
+
+
+# ---------------------------------------------------------------------------
+# Phase 7.4 — Confidence Calibration & Self-Validation endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.post("/api/v1/findings/{finding_id}/dismiss", response_model=DismissedFinding)
+async def dismiss_finding(
+    finding_id: str,
+    dismissed_by: str = "",
+    run_id: str = "",
+    reason: str = "",
+) -> DismissedFinding:
+    """Dismiss a finding as a false positive (FP) and recalibrate belief states.
+
+    When a finding is dismissed:
+
+    1. A ``DismissedFinding`` record is stored in-memory (and would be
+       persisted to the ``dismissed_findings`` table in production via
+       Alembic migration 007).
+    2. ``evidence=0.0`` is injected into every ``BeliefState`` that has
+       knowledge of the endpoint, recalibrating fault-likelihood downward.
+
+    Parameters
+    ----------
+    finding_id:
+        Unique identifier for the finding (from ``unique_failures[].task_id``
+        or ``browser_security_findings[].id``).
+    dismissed_by:
+        Optional identifier for who is dismissing (user name / API key).
+    run_id:
+        Optional autonomous run ID the finding originated from.
+    reason:
+        Optional free-text reason for dismissal.
+    """
+    if finding_id in _dismissed_findings:
+        raise HTTPException(
+            status_code=409,
+            detail=f"Finding '{finding_id}' has already been dismissed.",
+        )
+
+    now_iso = datetime.now(timezone.utc).isoformat()
+
+    # Resolve the endpoint key from the finding
+    endpoint = ""
+    raw_run = _autonomous_runs.get(run_id) if run_id else None
+    if raw_run:
+        for failure in raw_run.get("unique_failures", []):
+            if failure.get("task_id") == finding_id or failure.get("id") == finding_id:
+                endpoint = failure.get("page") or failure.get("url", "")
+                break
+        if not endpoint:
+            for f in raw_run.get("browser_security_findings", []):
+                if f.get("id") == finding_id:
+                    endpoint = f.get("endpoint", "")
+                    break
+
+    # Persist the dismissal record
+    record = DismissedFinding(
+        finding_id=finding_id,
+        endpoint=endpoint,
+        dismissed_by=dismissed_by or "user",
+        dismissed_at=now_iso,
+        run_id=run_id,
+        reason=reason,
+    )
+    _dismissed_findings[finding_id] = record
+
+    # Propagate FP feedback: inject evidence=0.0 into all known belief states
+    if endpoint:
+        _propagate_fp_feedback(endpoint)
+
+    logger.info(
+        "dismiss_finding: finding_id=%s endpoint=%r run_id=%s",
+        finding_id, endpoint, run_id,
+    )
+    return record
+
+
+def _propagate_fp_feedback(endpoint: str) -> None:
+    """Inject ``evidence=0.0`` into active autonomous-run belief states for *endpoint*.
+
+    Iterates over all in-progress autonomous runs and updates their attached
+    belief state so that the FP signal propagates through to the next
+    iteration's scenario generation via the AdaptiveController.
+
+    Parameters
+    ----------
+    endpoint:
+        Endpoint key (page path or full key) for which a finding was dismissed.
+    """
+    # Running agents may store a reference to themselves in the _autonomous_runs
+    # record under the ``"_agent"`` key (set during background task execution).
+    # Fall back gracefully if no live agent reference is found.
+    updated = 0
+    for run_record in _autonomous_runs.values():
+        if run_record.get("status") != "running":
+            continue
+        agent = run_record.get("_agent")
+        if agent is None:
+            continue
+        bs = getattr(agent, "_belief_state", None)
+        if bs is None:
+            continue
+        if endpoint in bs.fault_likelihood or endpoint in bs.confidence:
+            bs.update(endpoint, 0.0)
+            updated += 1
+    if updated:
+        logger.debug(
+            "_propagate_fp_feedback: updated %d belief state(s) for endpoint %r",
+            updated, endpoint,
+        )
+
+
+@router.get("/api/v1/findings/dismissed", response_model=List[DismissedFinding])
+async def list_dismissed_findings(
+    run_id: Optional[str] = Query(None, description="Filter by run ID"),
+    endpoint: Optional[str] = Query(None, description="Filter by endpoint path"),
+) -> List[DismissedFinding]:
+    """Return the list of findings dismissed as false positives.
+
+    Query parameters
+    ----------------
+    run_id:
+        Optional filter — only return dismissals from the specified run.
+    endpoint:
+        Optional filter — only return dismissals for the specified endpoint.
+    """
+    results = list(_dismissed_findings.values())
+    if run_id:
+        results = [r for r in results if r.run_id == run_id]
+    if endpoint:
+        results = [r for r in results if r.endpoint == endpoint]
+    results.sort(key=lambda r: r.dismissed_at, reverse=True)
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Finding annotations (comments) — Phase 10.4
+# ---------------------------------------------------------------------------
+
+
+@router.post("/api/v1/findings/{finding_id}/comments", status_code=201, tags=["findings"])
+async def add_finding_comment(
+    finding_id: str,
+    author: Optional[str] = None,
+    text: str = Query(..., min_length=1, description="Comment body text (required, non-empty)"),
+) -> Dict[str, Any]:
+    """Add a comment/annotation to a finding.
+
+    Comments are stored in-memory keyed by *finding_id*.  Each comment
+    records its author, text body, and creation timestamp.
+
+    Parameters
+    ----------
+    finding_id:
+        Unique identifier of the finding to annotate.
+    author:
+        Display name of the commenter (defaults to ``"anonymous"`` when omitted).
+    text:
+        Comment body text (required, must be non-empty).
+    """
+    comment: Dict[str, Any] = {
+        "id": str(uuid.uuid4()),
+        "finding_id": finding_id,
+        "author": author if author is not None else "anonymous",
+        "text": text,
+        "created_at": datetime.now(timezone.utc).isoformat(),
+    }
+    _finding_comments.setdefault(finding_id, []).append(comment)
+
+    # Broadcast team_annotation event to all WS clients (non-blocking)
+    try:
+        from mannf.product.dashboard import telemetry as _tel  # noqa: PLC0415
+        import asyncio  # noqa: PLC0415
+        loop = asyncio.get_running_loop()
+        loop.create_task(_tel.broadcast_team_annotation(
+            finding_id=finding_id,
+            author=comment["author"],
+            text=text,
+        ))
+    except Exception:  # noqa: BLE001
+        pass
+
+    return comment
+
+
+@router.get("/api/v1/findings/{finding_id}/comments", tags=["findings"])
+async def get_finding_comments(finding_id: str) -> List[Dict[str, Any]]:
+    """Return all comments for a given finding, oldest first.
+
+    Parameters
+    ----------
+    finding_id:
+        Unique identifier of the finding whose comments to retrieve.
+    """
+    return list(_finding_comments.get(finding_id, []))
+
+
+# ---------------------------------------------------------------------------
+# Share scan link — Phase 10.4
+# ---------------------------------------------------------------------------
+
+
+@router.post("/api/v1/scan/{scan_id}/share", status_code=201, tags=["scans"])
+async def share_scan(
+    scan_id: str,
+    expiry_hours: int = 24,
+) -> Dict[str, Any]:
+    """Generate a time-limited public share link for a scan.
+
+    The returned ``token`` can be embedded in a URL for read-only, auth-free
+    access to the scan results.  The link expires after *expiry_hours* hours
+    (default 24 h; max 720 h / 30 days).
+
+    Parameters
+    ----------
+    scan_id:
+        Unique identifier of the scan to share.
+    expiry_hours:
+        Hours until the link expires (1–720).
+    """
+    expiry_hours = max(1, min(expiry_hours, 720))
+    token = str(uuid.uuid4())
+    expires_at = datetime.now(timezone.utc) + timedelta(hours=expiry_hours)
+    record: Dict[str, Any] = {
+        "token": token,
+        "scan_id": scan_id,
+        "expires_at": expires_at.isoformat(),
+        "created_at": datetime.now(timezone.utc).isoformat(),
+    }
+    _scan_shares[token] = record
+    return record
+
+
+@router.get("/api/v1/analytics/calibration", response_model=CalibrationReport)
+async def get_calibration(
+    target_url: Optional[str] = Query(None, description="Filter by target URL"),
+    buckets: int = Query(10, description="Number of equal-width buckets (1–20)", ge=1, le=20),
+) -> CalibrationReport:
+    """Return a predicted-vs-actual reliability curve for the calibration dashboard view.
+
+    Buckets predictions into ``buckets`` equal-width ranges from 0.0 to 1.0
+    and shows:
+    - How many predictions fell in each bucket.
+    - The actual failure rate observed in that bucket (from ``unique_failures``).
+    - The mean predicted probability within the bucket.
+
+    Also computes the **Brier score** (mean squared error between predicted
+    probability and actual outcome) when actual outcomes are available.
+
+    Handles sparse data gracefully: ``actual_failure_rate`` is ``None`` when
+    no outcomes are available for a bucket.
+
+    Query parameters
+    ----------------
+    target_url:
+        Optional target URL to filter runs.
+    buckets:
+        Number of equal-width buckets.  Defaults to 10 (0.0–0.1, 0.1–0.2, …).
+    """
+    now_iso = datetime.now(timezone.utc).isoformat()
+
+    completed = [
+        r
+        for r in _autonomous_runs.values()
+        if r.get("status") in {"complete", "stopped"}
+        and (not target_url or r.get("target_url") == target_url)
+    ]
+    completed.sort(key=lambda r: r.get("started_at", ""), reverse=True)
+    recent_runs = completed[:10]  # use up to last 10 runs
+
+    if not recent_runs:
+        return CalibrationReport(
+            buckets=[],
+            total_predictions=0,
+            total_with_outcomes=0,
+            brier_score=None,
+            generated_at=now_iso,
+        )
+
+    # Gather per-page: (predicted_score, actual_outcome) pairs
+    # Use the same belief-momentum formula as /analytics/predictions to be consistent
+    page_belief_history: Dict[str, List[float]] = {}
+    page_failure_counts: Dict[str, int] = {}
+    page_pass_counts: Dict[str, int] = {}
+    total_failure_scenarios = 0
+
+    for run in recent_runs:
+        for snap in run.get("belief_snapshots") or []:
+            beliefs = snap.get("beliefs") or {}
+            for pk, fl in beliefs.items():
+                page_belief_history.setdefault(pk, []).append(float(fl))
+
+        for failure in run.get("unique_failures") or []:
+            pk = failure.get("page", failure.get("url", ""))
+            if pk:
+                page_failure_counts[pk] = page_failure_counts.get(pk, 0) + 1
+            total_failure_scenarios += 1
+
+        # Use iteration-level pass/fail info where available
+        for iteration in run.get("iterations") or []:
+            pass_count = iteration.get("passed", 0)
+            fail_count = iteration.get("failed", 0)
+            # We can't attribute these to individual pages from iteration-level data,
+            # so we just use the per-page failure counts from unique_failures
+
+    all_pages = set(page_belief_history) | set(page_failure_counts)
+
+    # Build (predicted, actual) pairs for each page with enough data
+    data_points: List[tuple[float, int]] = []  # (predicted, 0|1)
+
+    for pk in all_pages:
+        belief_vals = page_belief_history.get(pk, [])
+        if len(belief_vals) >= 2:
+            deltas = [belief_vals[i] - belief_vals[i - 1] for i in range(1, len(belief_vals))]
+            belief_momentum = sum(deltas) / len(deltas)
+        else:
+            belief_momentum = 0.0
+
+        latest_belief = belief_vals[-1] if belief_vals else 0.5
+        failure_density = (
+            page_failure_counts.get(pk, 0) / total_failure_scenarios
+            if total_failure_scenarios > 0
+            else 0.0
+        )
+        raw_prob = (
+            0.5 * latest_belief
+            + 0.3 * max(0.0, belief_momentum)
+            + 0.2 * failure_density
+        )
+        predicted_prob = max(0.0, min(1.0, raw_prob))
+
+        # Actual outcome: 1 if failed at least once across runs, 0 otherwise
+        actual = 1 if page_failure_counts.get(pk, 0) > 0 else 0
+        data_points.append((predicted_prob, actual))
+
+    # Build reliability curve buckets
+    bucket_width = 1.0 / buckets
+    bucket_data: List[tuple[float, float, List[tuple[float, int]]]] = []
+    for i in range(buckets):
+        low = round(i * bucket_width, 10)
+        high = round((i + 1) * bucket_width, 10)
+        bucket_data.append((low, high, []))
+
+    for pred, actual in data_points:
+        idx = min(int(pred / bucket_width), buckets - 1)
+        bucket_data[idx][2].append((pred, actual))
+
+    calibration_buckets: List[CalibrationBucket] = []
+    brier_sum = 0.0
+    total_with_outcomes = 0
+
+    for low, high, points in bucket_data:
+        n = len(points)
+        if n == 0:
+            calibration_buckets.append(
+                CalibrationBucket(
+                    bucket_low=round(low, 4),
+                    bucket_high=round(high, 4),
+                    predicted_count=0,
+                    actual_failure_rate=None,
+                    mean_predicted=None,
+                )
+            )
+        else:
+            actuals = [p[1] for p in points]
+            preds = [p[0] for p in points]
+            actual_rate = sum(actuals) / n
+            mean_pred = sum(preds) / n
+            for pred_v, act_v in points:
+                brier_sum += (pred_v - act_v) ** 2
+            total_with_outcomes += n
+            calibration_buckets.append(
+                CalibrationBucket(
+                    bucket_low=round(low, 4),
+                    bucket_high=round(high, 4),
+                    predicted_count=n,
+                    actual_failure_rate=round(actual_rate, 4),
+                    mean_predicted=round(mean_pred, 4),
+                )
+            )
+
+    brier_score = round(brier_sum / total_with_outcomes, 4) if total_with_outcomes > 0 else None
+
+    return CalibrationReport(
+        buckets=calibration_buckets,
+        total_predictions=len(data_points),
+        total_with_outcomes=total_with_outcomes,
+        brier_score=brier_score,
+        generated_at=now_iso,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Worker pool status endpoint
+# ---------------------------------------------------------------------------
+
+
+@router.get(
+    "/api/v1/worker-pool/status",
+    tags=["worker-pool"],
+    summary="Get worker pool and queue status",
+)
+async def get_worker_pool_status() -> Dict[str, Any]:
+    """Return the current state of the process-wide worker pool and job queue.
+
+    When no worker pool is configured (default single-process mode) the
+    response contains null pool data with the current in-memory queue stats.
+    """
+    from mannf.core.agents.worker_pool import get_default_pool  # noqa: PLC0415
+    from mannf.product.scheduling.queue import get_default_queue  # noqa: PLC0415
+
+    pool = get_default_pool()
+    queue = get_default_queue()
+
+    pool_info: Dict[str, Any] = {
+        "configured": pool is not None,
+    }
+    if pool is not None:
+        pool_info.update(pool.info())
+
+    queue_stats: Dict[str, Any] = {}
+    if queue is not None:
+        try:
+            stats = await queue.status()
+            queue_stats = stats.to_dict()
+        except Exception:  # noqa: BLE001
+            queue_stats = {}
+
+    return {
+        "pool": pool_info,
+        "queue": queue_stats,
+    }