feat(webui): model usage, token cost, latency, and performance analytics (Closes #651)

control_plane_db.py

@@ -31,7 +31,7 @@ from typing import Any, Iterator, Sequence
 
 import dependency_graph
 
-SCHEMA_VERSION = 4
+SCHEMA_VERSION = 5
 
 # Assignable work kinds only — raw monitoring incidents are never work items.
 WORK_KINDS = frozenset({"issue", "pr"})
@@ -186,6 +186,34 @@ CREATE INDEX IF NOT EXISTS idx_dependency_edges_target
     ON dependency_edges(remote, org, repo, target_kind, target_number);
 CREATE INDEX IF NOT EXISTS idx_assignments_session ON assignments(session_id, status);
 CREATE INDEX IF NOT EXISTS idx_incident_gitea ON incident_links(gitea_org, gitea_repo, gitea_issue_number);
+
+-- Model usage, token cost, latency, and performance events (#651)
+CREATE TABLE IF NOT EXISTS usage_events (
+    usage_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id TEXT,
+    remote TEXT NOT NULL DEFAULT 'dadeschools',
+    org TEXT NOT NULL DEFAULT '',
+    repo TEXT NOT NULL DEFAULT '',
+    project_id TEXT,
+    role TEXT NOT NULL DEFAULT 'unknown',
+    model TEXT NOT NULL DEFAULT 'unknown',
+    issue_number INTEGER,
+    pr_number INTEGER,
+    stage TEXT NOT NULL DEFAULT 'unknown',
+    input_tokens INTEGER,
+    output_tokens INTEGER,
+    total_tokens INTEGER,
+    estimated_cost_usd REAL,
+    latency_ms INTEGER,
+    duration_ms INTEGER,
+    status TEXT NOT NULL DEFAULT 'success',
+    metadata TEXT,
+    created_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_usage_events_scope ON usage_events(remote, org, repo);
+CREATE INDEX IF NOT EXISTS idx_usage_events_role_model ON usage_events(role, model);
+CREATE INDEX IF NOT EXISTS idx_usage_events_stage ON usage_events(stage);
 """
 
 
@@ -339,6 +367,7 @@ class ControlPlaneDB:
                 self._migrate_incident_links_null_scope(conn)
                 self._migrate_lease_lifecycle_columns(conn)
                 self._migrate_session_ownership_columns(conn)
+                self._migrate_usage_events_table(conn)
                 conn.execute(
                     "INSERT OR REPLACE INTO schema_meta(key, value) VALUES (?, ?)",
                     ("schema_version", str(SCHEMA_VERSION)),
@@ -518,6 +547,174 @@ class ControlPlaneDB:
                     f"UPDATE incident_links SET {col} = '' WHERE {col} IS NULL"
                 )
 
+    def _migrate_usage_events_table(self, conn: sqlite3.Connection) -> None:
+        """Create usage_events table and indexes if they do not exist (#651)."""
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS usage_events (
+                usage_id INTEGER PRIMARY KEY AUTOINCREMENT,
+                session_id TEXT,
+                remote TEXT NOT NULL DEFAULT 'dadeschools',
+                org TEXT NOT NULL DEFAULT '',
+                repo TEXT NOT NULL DEFAULT '',
+                project_id TEXT,
+                role TEXT NOT NULL DEFAULT 'unknown',
+                model TEXT NOT NULL DEFAULT 'unknown',
+                issue_number INTEGER,
+                pr_number INTEGER,
+                stage TEXT NOT NULL DEFAULT 'unknown',
+                input_tokens INTEGER,
+                output_tokens INTEGER,
+                total_tokens INTEGER,
+                estimated_cost_usd REAL,
+                latency_ms INTEGER,
+                duration_ms INTEGER,
+                status TEXT NOT NULL DEFAULT 'success',
+                metadata TEXT,
+                created_at TEXT NOT NULL
+            );
+        """)
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_usage_events_scope ON usage_events(remote, org, repo);")
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_usage_events_role_model ON usage_events(role, model);")
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_usage_events_stage ON usage_events(stage);")
+
+    def record_usage_event(
+        self,
+        *,
+        session_id: str | None = None,
+        remote: str = "dadeschools",
+        org: str = "",
+        repo: str = "",
+        project_id: str | None = None,
+        role: str = "unknown",
+        model: str = "unknown",
+        issue_number: int | None = None,
+        pr_number: int | None = None,
+        stage: str = "unknown",
+        input_tokens: int | None = None,
+        output_tokens: int | None = None,
+        total_tokens: int | None = None,
+        estimated_cost_usd: float | None = None,
+        latency_ms: int | None = None,
+        duration_ms: int | None = None,
+        status: str = "success",
+        metadata: str | dict[str, Any] | None = None,
+        created_at: str | None = None,
+    ) -> int:
+        """Record a model usage, token cost, latency, or stage performance event (#651)."""
+        ts = created_at or _ts()
+        meta_str: str | None = None
+        if metadata is not None:
+            from webui import console_redaction
+            redacted_meta = console_redaction.redact_payload(metadata)
+            if isinstance(redacted_meta, str):
+                meta_str = redacted_meta
+            else:
+                try:
+                    meta_str = json.dumps(redacted_meta, default=str)
+                except Exception:
+                    meta_str = str(redacted_meta)
+
+        if total_tokens is None and (input_tokens is not None or output_tokens is not None):
+            total_tokens = (input_tokens or 0) + (output_tokens or 0)
+
+        with self._tx(immediate=True) as conn:
+            cursor = conn.execute(
+                """
+                INSERT INTO usage_events (
+                    session_id, remote, org, repo, project_id, role, model,
+                    issue_number, pr_number, stage, input_tokens, output_tokens,
+                    total_tokens, estimated_cost_usd, latency_ms, duration_ms,
+                    status, metadata, created_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    session_id,
+                    remote,
+                    org,
+                    repo,
+                    project_id,
+                    role,
+                    model,
+                    issue_number,
+                    pr_number,
+                    stage,
+                    input_tokens,
+                    output_tokens,
+                    total_tokens,
+                    estimated_cost_usd,
+                    latency_ms,
+                    duration_ms,
+                    status,
+                    meta_str,
+                    ts,
+                ),
+            )
+            return cursor.lastrowid
+
+    def query_usage_events(
+        self,
+        *,
+        remote: str | None = None,
+        org: str | None = None,
+        repo: str | None = None,
+        project_id: str | None = None,
+        role: str | None = None,
+        model: str | None = None,
+        issue_number: int | None = None,
+        pr_number: int | None = None,
+        stage: str | None = None,
+        session_id: str | None = None,
+        limit: int = 500,
+        offset: int = 0,
+    ) -> list[dict[str, Any]]:
+        """Query stored usage events matching filters (#651)."""
+        conditions = []
+        params = []
+        if remote:
+            conditions.append("remote = ?")
+            params.append(remote)
+        if org:
+            conditions.append("org = ?")
+            params.append(org)
+        if repo:
+            conditions.append("repo = ?")
+            params.append(repo)
+        if project_id:
+            conditions.append("project_id = ?")
+            params.append(project_id)
+        if role:
+            conditions.append("role = ?")
+            params.append(role)
+        if model:
+            conditions.append("model = ?")
+            params.append(model)
+        if issue_number is not None:
+            conditions.append("issue_number = ?")
+            params.append(issue_number)
+        if pr_number is not None:
+            conditions.append("pr_number = ?")
+            params.append(pr_number)
+        if stage:
+            conditions.append("stage = ?")
+            params.append(stage)
+        if session_id:
+            conditions.append("session_id = ?")
+            params.append(session_id)
+
+        where_clause = f"WHERE {' AND '.join(conditions)}" if conditions else ""
+        sql = f"""
+            SELECT * FROM usage_events
+            {where_clause}
+            ORDER BY usage_id ASC
+            LIMIT ? OFFSET ?
+        """
+        params.extend([limit, offset])
+
+        with self._tx(immediate=False) as conn:
+            cursor = conn.execute(sql, params)
+            rows = cursor.fetchall()
+            return [dict(row) for row in rows]
+
     # ── sessions ──────────────────────────────────────────────────────────
 
     def upsert_session(

docs/observability/analytics-instrumentation.md

@@ -0,0 +1,125 @@
+# Model Usage, Token Cost, Latency, and Workflow Analytics (Phase 4)
+
+- **Tracking Issue:** [#651](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/651)
+- **Parent Epic:** [#631](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/651)
+- **Console Surface:** `/analytics`, `/api/v1/analytics`, `/api/v1/analytics/usage`
+
+## 1. Overview
+
+The Web Console Analytics module provides durable, aggregate visibility into **model usage, token cost, latency percentiles, and workflow-stage performance** across projects, worker roles, AI models, issues, and PRs.
+
+### Non-Goals
+- No mandatory client-side telemetry that leaks prompts or secret keys.
+- No third-party payment provider or billing integration.
+- No automatic model routing changes without controller policy (#647).
+
+---
+
+## 2. Event Schema (`usage_events`)
+
+Usage metrics are stored in the control-plane database under table `usage_events`.
+
+| Column | Type | Description |
+|---|---|---|
+| `usage_id` | `INTEGER` | Primary key (autoincrement) |
+| `session_id` | `TEXT` | Optional active session identifier |
+| `remote` | `TEXT` | Known Gitea instance (`dadeschools` or `prgs`) |
+| `org` | `TEXT` | Repository owner / organization |
+| `repo` | `TEXT` | Repository name |
+| `project_id` | `TEXT` | Optional project identifier |
+| `role` | `TEXT` | Active worker role (`author`, `reviewer`, `merger`, `reconciler`, `controller`) |
+| `model` | `TEXT` | LLM model identifier (e.g. `gemini-3.6-flash`, `claude-3-5-sonnet`) |
+| `issue_number` | `INTEGER` | Correlated Gitea issue number (optional) |
+| `pr_number` | `INTEGER` | Correlated Gitea PR number (optional) |
+| `stage` | `TEXT` | Workflow stage (`preflight`, `implementation`, `review`, `merge`, `reconciliation`) |
+| `input_tokens` | `INTEGER` | Input token count (optional / nullable) |
+| `output_tokens` | `INTEGER` | Output token count (optional / nullable) |
+| `total_tokens` | `INTEGER` | Total token count (optional / nullable) |
+| `estimated_cost_usd` | `REAL` | Estimated USD cost (optional / nullable) |
+| `latency_ms` | `INTEGER` | Request latency in milliseconds (optional / nullable) |
+| `duration_ms` | `INTEGER` | Stage execution duration in milliseconds (optional / nullable) |
+| `status` | `TEXT` | Outcome status (`success`, `failure`, `timeout`) |
+| `metadata` | `TEXT` | Redacted metadata or summary string |
+| `created_at` | `TEXT` | ISO 8601 UTC timestamp |
+
+---
+
+## 3. Handling of Missing Data ("Unknown" vs. Zero Fabrication)
+
+To ensure operational metrics accurately reflect evidence:
+- **Untracked or missing metrics are displayed as `Unknown`**, never zero-fabricated.
+- If an event omits `estimated_cost_usd`, `latency_ms`, or token counts, the aggregator marks those fields as missing (`None`) rather than defaulting to `0` or `$0.00`.
+- Summary tables and KPI cards explicitly indicate when data is unmeasured or partially reported.
+
+---
+
+## 4. Redaction & Security Rules
+
+Per `#633` security policy:
+- Free-text fields (`metadata`, `prompt_summary`, `session_id`) are run through `console_redaction.redact_text` before persistence and output serialization.
+- Secret tokens, keychain commands, authorization headers, passwords, and JWTs are stripped automatically.
+
+---
+
+## 5. Opt-in Instrumentation Guide
+
+Applications, MCP servers, and background sessions can report usage metrics through either Python API or HTTP ingestion.
+
+### Python Ingestion
+
+```python
+from webui.analytics_loader import record_usage
+
+record_usage(
+    remote="dadeschools",
+    org="Scaled-Tech-Consulting",
+    repo="Gitea-Tools",
+    role="author",
+    model="gemini-3.6-flash",
+    issue_number=651,
+    stage="implementation",
+    input_tokens=1420,
+    output_tokens=380,
+    total_tokens=1800,
+    estimated_cost_usd=0.00045,
+    latency_ms=320,
+    duration_ms=4500,
+    status="success",
+    metadata={"note": "Implementation of analytics module"},
+)
+```
+
+### HTTP Ingestion API
+
+```http
+POST /api/v1/analytics/usage HTTP/1.1
+Content-Type: application/json
+
+{
+  "remote": "dadeschools",
+  "org": "Scaled-Tech-Consulting",
+  "repo": "Gitea-Tools",
+  "role": "author",
+  "model": "gemini-3.6-flash",
+  "issue_number": 651,
+  "stage": "implementation",
+  "input_tokens": 1420,
+  "output_tokens": 380,
+  "total_tokens": 1800,
+  "estimated_cost_usd": 0.00045,
+  "latency_ms": 320,
+  "duration_ms": 4500,
+  "status": "success",
+  "metadata": "Analytics schema landed"
+}
+```
+
+---
+
+## 6. Querying Analytics API
+
+```http
+GET /api/v1/analytics?role=author&stage=implementation HTTP/1.1
+```
+
+Returns `AnalyticsSnapshot` JSON containing aggregations (`by_model`, `by_stage`, `by_role`, `by_work_item`, `by_project`) and latency percentiles (`p50`, `p90`, `p95`, `p99`).

docs/webui-local-dev.md

@@ -54,7 +54,6 @@ status, onboarding checklist state, and the fail-closed error payloads (#635).
 | `/` | Home / operator overview |
 | `/health` | JSON liveness (`status`, `service`, `mode`, `timestamp`, `uptime_seconds`) |
 | `/api/v1/system/health` | Structured read-only system health (#634) |
-| `/system-health` | System-health dashboard — readiness, version/uptime, dependencies, MCP namespaces, stale-runtime parity (#639) |
 | `/queue` | Live PR and issue queue dashboard (#429) |
 | `/api/queue` | JSON queue export with pagination metadata |
 | `/projects` | Project registry list with status and onboarding progress (#427, #635) |
@@ -259,37 +258,6 @@ Not-yet-implemented surfaces (`/sessions`, `/inventory`, `/timeline`,
 surfaces are backed by #636). Mutating methods on stub routes still fail closed
 with `read-only-mvp`.
 
-## System-health dashboard (#639)
-
-`/system-health` renders the same snapshot the `/api/v1/system/health` API
-returns, so the page and the API can never disagree. Cards: overall readiness,
-stale-runtime parity, version and uptime, dependency probes, MCP namespaces,
-probe errors (only when present), and recovery pointers. `?deep=1` opts into
-the network probe exactly as the API does; the plain page load stays cheap.
-
-Field authority and honesty rules:
-
-* `ready` and `readiness_complete` are shown separately. A snapshot whose
-  required probes never ran is not the same as one that ran them and passed,
-  and the page never collapses the two into an unproven green.
-* A probe that did not run appears under **Not probed**, never as healthy.
-* `stale_runtime.mutation_safe` is displayed verbatim from the API. When the
-  runtime is stale, or when parity is indeterminate, the page warns and does
-  not claim mutation safety.
-* MCP namespaces are reported `unproven`: the web process runs outside the
-  IDE-managed MCP client and cannot prove that path (#543).
-
-Redaction is split by field kind. Free text — probe details, readiness and
-parity reasons, probe errors — passes through `system_health.redact`.
-Structured fields — commit SHAs, probe names, statuses, timestamps — are
-HTML-escaped only, because `redact`'s opaque-token rule matches any run of 32
-or more characters and would otherwise blank every 40-character git SHA, which
-is precisely the evidence the parity view exists to show.
-
-The dashboard is read-only: no restart, reload, or process-kill control. Those
-arrive in Phase 2 (#642). Recovery guidance points at the sanctioned client
-reconnect / operator restart path — never a manual daemon kill (#630).
-
 ## Deployment boundary (#435)
 
 MVP serves on loopback by default. Binding `0.0.0.0` or `::` is **refused**

tests/test_control_plane_db.py

@@ -36,7 +36,7 @@ class ControlPlaneDBTest(unittest.TestCase):
             rows = dict(conn.execute("SELECT key, value FROM schema_meta").fetchall())
         finally:
             conn.close()
-        self.assertEqual(rows["schema_version"], "4")
+        self.assertEqual(rows["schema_version"], "5")
         self.assertIn("DB coordinates", rows["architecture"])
         self.assertIn("bridge", rows["architecture"].lower())
 

tests/test_webui_analytics.py

@@ -0,0 +1,196 @@
+"""Unit and integration tests for Model Usage & Performance Analytics (#651)."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import unittest
+from starlette.testclient import TestClient
+
+import control_plane_db
+from webui.analytics_loader import (
+    ANALYTICS_SCHEMA_VERSION,
+    compute_percentile,
+    load_analytics,
+    record_usage,
+)
+from webui.app import create_app
+from webui import console_redaction
+
+
+class AnalyticsLoaderTest(unittest.TestCase):
+
+    def setUp(self) -> None:
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.db_path = os.path.join(self.temp_dir.name, "test_control_plane.sqlite3")
+        os.environ["GITEA_CONTROL_PLANE_DB"] = self.db_path
+        self.db = control_plane_db.ControlPlaneDB(db_path=self.db_path)
+
+    def tearDown(self) -> None:
+        self.temp_dir.cleanup()
+
+    def test_compute_percentile(self) -> None:
+        self.assertIsNone(compute_percentile([], 50.0))
+        self.assertEqual(compute_percentile([100], 50.0), 100.0)
+
+        # 2 elements: [100, 200]
+        self.assertEqual(compute_percentile([100, 200], 50.0), 150.0)
+
+        # 100 elements: 1..100
+        vals = list(range(1, 101))
+        self.assertEqual(compute_percentile(vals, 50.0), 50.5)
+        self.assertAlmostEqual(compute_percentile(vals, 90.0), 90.1)
+
+    def test_record_and_aggregate_usage(self) -> None:
+        # Record event 1 (complete data)
+        u1 = record_usage(
+            db_path=self.db_path,
+            remote="dadeschools",
+            org="Scaled-Tech-Consulting",
+            repo="Gitea-Tools",
+            role="author",
+            model="gemini-3.6-flash",
+            issue_number=651,
+            stage="implementation",
+            input_tokens=1000,
+            output_tokens=500,
+            estimated_cost_usd=0.0015,
+            latency_ms=200,
+            duration_ms=3000,
+            metadata={"secret_key": "secret123", "note": "token=secret123"},
+        )
+        self.assertGreater(u1, 0)
+
+        # Record event 2 (missing tokens and cost -> unknown)
+        u2 = record_usage(
+            db_path=self.db_path,
+            remote="dadeschools",
+            org="Scaled-Tech-Consulting",
+            repo="Gitea-Tools",
+            role="reviewer",
+            model="claude-3-5-sonnet",
+            pr_number=846,
+            stage="review",
+            latency_ms=500,
+            duration_ms=6000,
+        )
+        self.assertGreater(u2, u1)
+
+        snapshot = load_analytics(
+            db_path=self.db_path,
+            remote="dadeschools",
+            org="Scaled-Tech-Consulting",
+            repo="Gitea-Tools",
+        )
+
+        self.assertTrue(snapshot.ok)
+        self.assertEqual(snapshot.schema_version, ANALYTICS_SCHEMA_VERSION)
+        self.assertEqual(snapshot.total_events, 2)
+
+        # Verify overall summary
+        summary = snapshot.overall_summary
+        self.assertEqual(summary.total_events, 2)
+        self.assertEqual(summary.events_with_tokens, 1)
+        self.assertEqual(summary.total_tokens, 1500)
+        self.assertEqual(summary.events_with_cost, 1)
+        self.assertEqual(summary.estimated_cost_usd, 0.0015)
+        self.assertEqual(summary.events_with_latency, 2)
+        self.assertEqual(summary.latency_p50_ms, 350.0)
+
+        # Verify missing data handling (AC 3: not zero-fabricated)
+        reviewer_model = snapshot.by_model.get("claude-3-5-sonnet")
+        self.assertIsNotNone(reviewer_model)
+        self.assertEqual(reviewer_model.total_events, 1)
+        self.assertEqual(reviewer_model.events_with_tokens, 0)
+        self.assertIsNone(reviewer_model.total_tokens)
+        self.assertEqual(reviewer_model.display_tokens, "Unknown")
+        self.assertEqual(reviewer_model.events_with_cost, 0)
+        self.assertIsNone(reviewer_model.estimated_cost_usd)
+        self.assertEqual(reviewer_model.display_cost, "Unknown")
+
+        # Verify redaction (AC 4)
+        e1 = [e for e in snapshot.events if e.usage_id == u1][0]
+        self.assertIsNotNone(e1.metadata)
+        self.assertNotIn("secret123", e1.metadata)
+        self.assertIn("[REDACTED]", e1.metadata)
+
+    def test_missing_db_fail_soft(self) -> None:
+        invalid_path = "/nonexistent_path_dir/db.sqlite3"
+        snapshot = load_analytics(db_path=invalid_path)
+        self.assertFalse(snapshot.ok)
+        self.assertIn("control_plane_db_unavailable", snapshot.reason)
+        self.assertEqual(snapshot.overall_summary.display_tokens, "Unknown")
+
+
+class AnalyticsWebUITest(unittest.TestCase):
+
+    def setUp(self) -> None:
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.db_path = os.path.join(self.temp_dir.name, "test_webui.sqlite3")
+        os.environ["GITEA_CONTROL_PLANE_DB"] = self.db_path
+        self.app = create_app()
+        self.client = TestClient(self.app)
+
+        record_usage(
+            db_path=self.db_path,
+            remote="dadeschools",
+            org="Scaled-Tech-Consulting",
+            repo="Gitea-Tools",
+            role="author",
+            model="gemini-3.6-flash",
+            issue_number=651,
+            stage="implementation",
+            input_tokens=2000,
+            output_tokens=1000,
+            estimated_cost_usd=0.003,
+            latency_ms=150,
+            duration_ms=2500,
+        )
+
+    def tearDown(self) -> None:
+        self.temp_dir.cleanup()
+
+    def test_analytics_html_route(self) -> None:
+        response = self.client.get("/analytics")
+        self.assertEqual(response.status_code, 200)
+        self.assertIn("Model Usage & Performance Analytics", response.text)
+        self.assertIn("gemini-3.6-flash", response.text)
+        self.assertIn("3,000", response.text)
+
+    def test_analytics_api_route(self) -> None:
+        response = self.client.get("/api/v1/analytics")
+        self.assertEqual(response.status_code, 200)
+        data = response.json()
+        self.assertTrue(data["ok"])
+        self.assertEqual(data["total_events"], 1)
+        self.assertIn("gemini-3.6-flash", data["by_model"])
+
+    def test_analytics_ingest_endpoint(self) -> None:
+        payload = {
+            "remote": "dadeschools",
+            "org": "Scaled-Tech-Consulting",
+            "repo": "Gitea-Tools",
+            "role": "reviewer",
+            "model": "claude-3-5-sonnet",
+            "pr_number": 846,
+            "stage": "review",
+            "input_tokens": 500,
+            "output_tokens": 100,
+            "latency_ms": 400,
+            "metadata": "Review note token=secret456",
+        }
+        response = self.client.post("/api/v1/analytics/usage", json=payload)
+        self.assertEqual(response.status_code, 201)
+        res_json = response.json()
+        self.assertTrue(res_json["ok"])
+        self.assertGreater(res_json["usage_id"], 0)
+
+        # Check that it appears in GET /api/v1/analytics
+        res2 = self.client.get("/api/v1/analytics")
+        self.assertEqual(res2.status_code, 200)
+        data2 = res2.json()
+        self.assertEqual(data2["total_events"], 2)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_webui_system_health_dashboard.py

@@ -1,345 +0,0 @@
-"""Tests for the system-health dashboard view (#639).
-
-Covers the acceptance criteria directly: the page renders the health DTO
-fields (AC1), degraded dependencies are visible (AC2), stale runtime is warned
-prominently and never rendered as mutation-safe (AC3), healthy and degraded
-fixtures both render (AC4), and the shell carries a nav entry (AC5).
-"""
-import sys
-import unittest
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
-
-from starlette.testclient import TestClient
-
-from webui.app import create_app
-from webui.deployment_boundary import scan_text_for_client_secrets
-from webui.layout import render_page
-from webui.nav import iter_nav_items
-from webui.system_health import (
-    STATUS_DEGRADED,
-    STATUS_DOWN,
-    STATUS_OK,
-    STATUS_SKIPPED,
-    STATUS_UNPROVEN,
-    DependencyProbe,
-    StaleRuntime,
-    SystemHealthSnapshot,
-    VersionInfo,
-)
-from webui.system_health_views import render_system_health_page
-
-DASHBOARD_PATH = "/system-health"
-
-
-def _version(*, known: bool = True) -> VersionInfo:
-    return VersionInfo(
-        git_sha="1c455b6ec0f9cb761fe6248de68c17e061fb5ecd" if known else None,
-        git_describe="v0.4.1-12-g1c455b6" if known else None,
-        control_plane_schema_version=4 if known else None,
-        python_version="3.13.1",
-        known=known,
-    )
-
-
-def _parity(*, stale: bool = False, determinable: bool = True) -> StaleRuntime:
-    if stale:
-        return StaleRuntime(
-            daemon_head="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-            checkout_head="bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
-            remote_head="cccccccccccccccccccccccccccccccccccccccc",
-            stale=True,
-            determinable=True,
-            mutation_safe=False,
-            reasons=("runtime, checkout, and remote commits disagree",),
-        )
-    if not determinable:
-        return StaleRuntime(
-            daemon_head=None,
-            checkout_head=None,
-            remote_head=None,
-            stale=False,
-            determinable=False,
-            mutation_safe=False,
-            reasons=("local checkout HEAD could not be read",),
-        )
-    return StaleRuntime(
-        daemon_head="1c455b6ec0f9cb761fe6248de68c17e061fb5ecd",
-        checkout_head="1c455b6ec0f9cb761fe6248de68c17e061fb5ecd",
-        remote_head="1c455b6ec0f9cb761fe6248de68c17e061fb5ecd",
-        stale=False,
-        determinable=True,
-        mutation_safe=True,
-        reasons=(),
-    )
-
-
-def _snapshot(
-    *,
-    status: str = STATUS_OK,
-    ready: bool = True,
-    readiness_complete: bool = True,
-    readiness_reasons: tuple[str, ...] = (),
-    dependencies: tuple[DependencyProbe, ...] | None = None,
-    parity: StaleRuntime | None = None,
-    namespaces: tuple[dict, ...] = (),
-    probe_errors: tuple[str, ...] = (),
-    version_known: bool = True,
-) -> SystemHealthSnapshot:
-    if dependencies is None:
-        dependencies = (
-            DependencyProbe(
-                name="control_plane_db",
-                kind="sqlite",
-                status=STATUS_OK,
-                detail="schema version 4",
-                required=True,
-                latency_ms=1.25,
-                metadata={"schema_version": 4},
-            ),
-        )
-    return SystemHealthSnapshot(
-        status=status,
-        ready=ready,
-        readiness_complete=readiness_complete,
-        readiness_reasons=readiness_reasons,
-        service="mcp-control-plane-webui",
-        mode="read-only",
-        version=_version(known=version_known),
-        started_at="2026-07-23T19:50:47+00:00",
-        uptime_seconds=3661.5,
-        timestamp="2026-07-23T20:51:48+00:00",
-        deep_probes_requested=False,
-        dependencies=dependencies,
-        mcp_namespaces=namespaces,
-        stale_runtime=parity if parity is not None else _parity(),
-        probe_errors=probe_errors,
-    )
-
-
-class TestHealthyRender(unittest.TestCase):
-    """AC1 / AC4 — every health DTO field reaches the page."""
-
-    def setUp(self):
-        self.html = render_system_health_page(_snapshot())
-
-    def test_readiness_fields_render(self):
-        self.assertIn("System health", self.html)
-        self.assertIn("Ready", self.html)
-        self.assertIn("mcp-control-plane-webui", self.html)
-        self.assertIn("read-only", self.html)
-        self.assertIn("2026-07-23T20:51:48+00:00", self.html)
-
-    def test_version_and_uptime_render(self):
-        self.assertIn("1c455b6ec0f9cb761fe6248de68c17e061fb5ecd", self.html)
-        self.assertIn("v0.4.1-12-g1c455b6", self.html)
-        self.assertIn("3.13.1", self.html)
-        self.assertIn("3661.500s", self.html)
-        self.assertIn("1.02h", self.html)
-
-    def test_dependency_row_renders_with_latency(self):
-        self.assertIn("control_plane_db", self.html)
-        self.assertIn("sqlite", self.html)
-        self.assertIn("schema version 4", self.html)
-        self.assertIn("1.2 ms", self.html)
-
-    def test_healthy_page_shows_no_stale_warning(self):
-        self.assertNotIn("Stale runtime:", self.html)
-        self.assertNotIn("Staleness", self.html)
-
-    def test_unknown_version_is_labelled_not_faked(self):
-        html = render_system_health_page(_snapshot(version_known=False))
-        self.assertIn("unknown", html)
-        self.assertIn("unresolved", html)
-
-
-class TestDegradedRender(unittest.TestCase):
-    """AC2 — a degraded or unrun dependency is visible, not swallowed."""
-
-    def setUp(self):
-        self.deps = (
-            DependencyProbe(
-                name="control_plane_db",
-                kind="sqlite",
-                status=STATUS_OK,
-                detail="schema version 4",
-                required=True,
-                latency_ms=0.9,
-            ),
-            DependencyProbe(
-                name="repository",
-                kind="git",
-                status=STATUS_DOWN,
-                detail="repository root is not a git checkout",
-                required=True,
-                latency_ms=4.0,
-            ),
-            DependencyProbe(
-                name="gitea",
-                kind="http",
-                status=STATUS_SKIPPED,
-                detail="deep probe not requested",
-                required=False,
-            ),
-        )
-        self.html = render_system_health_page(
-            _snapshot(
-                status=STATUS_DEGRADED,
-                ready=False,
-                readiness_complete=False,
-                readiness_reasons=("required dependency 'repository' is down",),
-                dependencies=self.deps,
-            )
-        )
-
-    def test_degraded_banner_names_the_dependency(self):
-        self.assertIn("Degraded dependencies:", self.html)
-        self.assertIn("repository", self.html)
-
-    def test_not_run_probe_is_reported_separately(self):
-        self.assertIn("Not probed:", self.html)
-        self.assertIn("gitea", self.html)
-        self.assertIn("not counted", self.html)
-
-    def test_not_ready_headline_and_reason(self):
-        self.assertIn("Not ready", self.html)
-        self.assertIn("required dependency 'repository' is down", self.html)
-
-    def test_degraded_status_badge_present(self):
-        self.assertIn("badge-health-degraded", self.html)
-        self.assertIn("badge-health-down", self.html)
-
-    def test_ready_but_incomplete_is_not_shown_as_plain_ready(self):
-        html = render_system_health_page(
-            _snapshot(ready=True, readiness_complete=False)
-        )
-        self.assertIn("Ready (incomplete evidence)", html)
-
-
-class TestStaleRuntimeWarning(unittest.TestCase):
-    """AC3 — staleness is prominent and never claims mutation safety."""
-
-    def test_stale_runtime_warns_and_denies_mutation_safety(self):
-        html = render_system_health_page(_snapshot(parity=_parity(stale=True)))
-        self.assertIn("Stale runtime:", html)
-        self.assertIn("do not treat this runtime as mutation-safe", html)
-        self.assertIn("<tr><th>Mutation safe</th><td>False</td></tr>", html)
-
-    def test_indeterminate_parity_is_not_reported_safe(self):
-        html = render_system_health_page(
-            _snapshot(parity=_parity(determinable=False))
-        )
-        self.assertIn("Staleness", html)
-        self.assertIn("<tr><th>Mutation safe</th><td>False</td></tr>", html)
-        self.assertIn("<tr><th>Determinable</th><td>False</td></tr>", html)
-
-    def test_healthy_parity_reports_mutation_safe_true(self):
-        html = render_system_health_page(_snapshot())
-        self.assertIn("<tr><th>Mutation safe</th><td>True</td></tr>", html)
-
-
-class TestNamespacesAndErrors(unittest.TestCase):
-    def test_unproven_namespace_rows_render(self):
-        html = render_system_health_page(
-            _snapshot(
-                namespaces=(
-                    {
-                        "namespace": "gitea-author",
-                        "required_tool": "gitea_lock_issue",
-                        "status": STATUS_UNPROVEN,
-                        "ide_namespace_proven": False,
-                        "reason": "the web console cannot invoke the IDE-managed MCP client",
-                    },
-                )
-            )
-        )
-        self.assertIn("gitea-author", html)
-        self.assertIn("gitea_lock_issue", html)
-        self.assertIn("badge-health-unproven", html)
-
-    def test_no_namespaces_degrades_gracefully(self):
-        html = render_system_health_page(_snapshot(namespaces=()))
-        self.assertIn("No MCP namespaces are declared.", html)
-
-    def test_probe_errors_render_when_present(self):
-        html = render_system_health_page(
-            _snapshot(probe_errors=("probe raised: disk offline",))
-        )
-        self.assertIn("Probe errors", html)
-        self.assertIn("disk offline", html)
-
-    def test_probe_error_card_absent_when_clean(self):
-        self.assertNotIn("Probe errors", render_system_health_page(_snapshot()))
-
-
-class TestReadOnlyAndRedaction(unittest.TestCase):
-    def test_no_restart_or_kill_controls(self):
-        html = render_system_health_page(_snapshot())
-        self.assertNotIn("<button", html)
-        self.assertNotIn("<form", html)
-        self.assertNotIn("pkill", html)
-        self.assertIn("read-only", html)
-
-    def test_recovery_points_at_sanctioned_path(self):
-        html = render_system_health_page(_snapshot())
-        self.assertIn("Reconnect the MCP client", html)
-        self.assertIn("Never kill the daemon process manually", html)
-
-    def test_secret_shaped_detail_is_redacted(self):
-        leaky = DependencyProbe(
-            name="gitea",
-            kind="http",
-            status=STATUS_DOWN,
-            detail="auth failed for token=ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
-            required=False,
-            latency_ms=12.0,
-        )
-        html = render_system_health_page(_snapshot(dependencies=(leaky,)))
-        self.assertNotIn("ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789", html)
-
-    def test_html_in_detail_is_escaped(self):
-        hostile = DependencyProbe(
-            name="repository",
-            kind="git",
-            status=STATUS_DOWN,
-            detail="<script>alert(1)</script>",
-            required=True,
-        )
-        html = render_system_health_page(_snapshot(dependencies=(hostile,)))
-        self.assertNotIn("<script>", html)
-        self.assertIn("&lt;script&gt;", html)
-
-
-class TestNavAndRoute(unittest.TestCase):
-    """AC5 — the shell links the dashboard, and the route serves it."""
-
-    def setUp(self):
-        self.client = TestClient(create_app())
-
-    def test_nav_contains_system_health(self):
-        self.assertIn(
-            (DASHBOARD_PATH, "System health"),
-            [(item.href, item.label) for item in iter_nav_items()],
-        )
-
-    def test_rendered_shell_links_dashboard(self):
-        page = render_page(title="Home", body_html="<p>x</p>")
-        self.assertIn(f'href="{DASHBOARD_PATH}"', page)
-
-    def test_route_renders_dashboard(self):
-        response = self.client.get(DASHBOARD_PATH)
-        self.assertEqual(response.status_code, 200)
-        self.assertIn("System health", response.text)
-        self.assertIn("Stale-runtime parity", response.text)
-
-    def test_route_is_read_only(self):
-        self.assertEqual(self.client.post(DASHBOARD_PATH).status_code, 405)
-
-    def test_live_page_leaks_no_client_secret(self):
-        findings = scan_text_for_client_secrets(self.client.get(DASHBOARD_PATH).text)
-        self.assertEqual(findings, [])
-
-
-if __name__ == "__main__":  # pragma: no cover
-    unittest.main()

webui/analytics_loader.py

@@ -0,0 +1,428 @@
+"""Model usage, token cost, latency, and workflow-performance analytics (#651, Phase 4).
+
+Ingests session instrumentation metrics, aggregates usage/cost/latency percentiles
+by project, role, model, issue/PR, and stage, enforcing secret redaction and
+explicitly rendering missing metrics as "Unknown" without zero-fabrication.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import asdict, dataclass
+from typing import Any, Sequence
+
+import control_plane_db
+from webui import console_redaction
+
+ANALYTICS_SCHEMA_VERSION = 1
+
+
+@dataclass(frozen=True)
+class UsageEvent:
+    usage_id: int
+    session_id: str | None
+    remote: str
+    org: str
+    repo: str
+    project_id: str | None
+    role: str
+    model: str
+    issue_number: int | None
+    pr_number: int | None
+    stage: str
+    input_tokens: int | None
+    output_tokens: int | None
+    total_tokens: int | None
+    estimated_cost_usd: float | None
+    latency_ms: int | None
+    duration_ms: int | None
+    status: str
+    metadata: str | None
+    created_at: str
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        if d["metadata"]:
+            d["metadata"] = console_redaction.redact_text(d["metadata"])
+        return d
+
+
+@dataclass(frozen=True)
+class GroupMetrics:
+    name: str
+    total_events: int
+    events_with_tokens: int
+    input_tokens: int | None
+    output_tokens: int | None
+    total_tokens: int | None
+    events_with_cost: int
+    estimated_cost_usd: float | None
+    events_with_latency: int
+    latency_p50_ms: float | None
+    latency_p90_ms: float | None
+    latency_p95_ms: float | None
+    latency_p99_ms: float | None
+    latency_avg_ms: float | None
+    events_with_duration: int
+    duration_avg_ms: float | None
+    display_tokens: str
+    display_cost: str
+    display_latency_p50: str
+    display_latency_p90: str
+    display_duration_avg: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class AnalyticsSnapshot:
+    ok: bool
+    reason: str
+    schema_version: int
+    remote: str
+    org: str
+    repo: str
+    total_events: int
+    overall_summary: GroupMetrics
+    by_project: dict[str, GroupMetrics]
+    by_role: dict[str, GroupMetrics]
+    by_model: dict[str, GroupMetrics]
+    by_work_item: dict[str, GroupMetrics]
+    by_stage: dict[str, GroupMetrics]
+    events: tuple[UsageEvent, ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "ok": self.ok,
+            "reason": self.reason,
+            "schema_version": self.schema_version,
+            "remote": self.remote,
+            "org": self.org,
+            "repo": self.repo,
+            "total_events": self.total_events,
+            "overall_summary": self.overall_summary.to_dict(),
+            "by_project": {k: v.to_dict() for k, v in self.by_project.items()},
+            "by_role": {k: v.to_dict() for k, v in self.by_role.items()},
+            "by_model": {k: v.to_dict() for k, v in self.by_model.items()},
+            "by_work_item": {k: v.to_dict() for k, v in self.by_work_item.items()},
+            "by_stage": {k: v.to_dict() for k, v in self.by_stage.items()},
+            "events": [e.to_dict() for e in self.events],
+        }
+
+
+def compute_percentile(values: Sequence[float | int], percentile: float) -> float | None:
+    if not values:
+        return None
+    sorted_vals = sorted(values)
+    n = len(sorted_vals)
+    if n == 1:
+        return float(sorted_vals[0])
+    k = (n - 1) * (percentile / 100.0)
+    f = math.floor(k)
+    c = math.ceil(k)
+    if f == c:
+        return float(sorted_vals[int(f)])
+    d0 = sorted_vals[int(f)] * (c - k)
+    d1 = sorted_vals[int(c)] * (k - f)
+    return float(d0 + d1)
+
+
+def aggregate_events(group_name: str, events: Sequence[UsageEvent]) -> GroupMetrics:
+    total_events = len(events)
+    if total_events == 0:
+        return GroupMetrics(
+            name=group_name,
+            total_events=0,
+            events_with_tokens=0,
+            input_tokens=None,
+            output_tokens=None,
+            total_tokens=None,
+            events_with_cost=0,
+            estimated_cost_usd=None,
+            events_with_latency=0,
+            latency_p50_ms=None,
+            latency_p90_ms=None,
+            latency_p95_ms=None,
+            latency_p99_ms=None,
+            latency_avg_ms=None,
+            events_with_duration=0,
+            duration_avg_ms=None,
+            display_tokens="Unknown",
+            display_cost="Unknown",
+            display_latency_p50="Unknown",
+            display_latency_p90="Unknown",
+            display_duration_avg="Unknown",
+        )
+
+    token_events = [
+        e for e in events
+        if e.total_tokens is not None or e.input_tokens is not None or e.output_tokens is not None
+    ]
+    events_with_tokens = len(token_events)
+    if events_with_tokens > 0:
+        input_tokens = sum(e.input_tokens or 0 for e in token_events)
+        output_tokens = sum(e.output_tokens or 0 for e in token_events)
+        total_tokens = sum(
+            e.total_tokens if e.total_tokens is not None else ((e.input_tokens or 0) + (e.output_tokens or 0))
+            for e in token_events
+        )
+        display_tokens = f"{total_tokens:,}"
+    else:
+        input_tokens = None
+        output_tokens = None
+        total_tokens = None
+        display_tokens = "Unknown"
+
+    cost_events = [e for e in events if e.estimated_cost_usd is not None]
+    events_with_cost = len(cost_events)
+    if events_with_cost > 0:
+        estimated_cost_usd = round(sum(e.estimated_cost_usd for e in cost_events), 6)
+        display_cost = f"${estimated_cost_usd:.4f}"
+    else:
+        estimated_cost_usd = None
+        display_cost = "Unknown"
+
+    latency_vals = [e.latency_ms for e in events if e.latency_ms is not None]
+    events_with_latency = len(latency_vals)
+    if events_with_latency > 0:
+        latency_p50_ms = compute_percentile(latency_vals, 50.0)
+        latency_p90_ms = compute_percentile(latency_vals, 90.0)
+        latency_p95_ms = compute_percentile(latency_vals, 95.0)
+        latency_p99_ms = compute_percentile(latency_vals, 99.0)
+        latency_avg_ms = round(sum(latency_vals) / events_with_latency, 2)
+        display_latency_p50 = f"{round(latency_p50_ms, 1)} ms" if latency_p50_ms is not None else "Unknown"
+        display_latency_p90 = f"{round(latency_p90_ms, 1)} ms" if latency_p90_ms is not None else "Unknown"
+    else:
+        latency_p50_ms = None
+        latency_p90_ms = None
+        latency_p95_ms = None
+        latency_p99_ms = None
+        latency_avg_ms = None
+        display_latency_p50 = "Unknown"
+        display_latency_p90 = "Unknown"
+
+    duration_vals = [e.duration_ms for e in events if e.duration_ms is not None]
+    events_with_duration = len(duration_vals)
+    if events_with_duration > 0:
+        duration_avg_ms = round(sum(duration_vals) / events_with_duration, 2)
+        display_duration_avg = f"{round(duration_avg_ms / 1000.0, 2)} s" if duration_avg_ms >= 1000 else f"{round(duration_avg_ms, 1)} ms"
+    else:
+        duration_avg_ms = None
+        display_duration_avg = "Unknown"
+
+    return GroupMetrics(
+        name=group_name,
+        total_events=total_events,
+        events_with_tokens=events_with_tokens,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        total_tokens=total_tokens,
+        events_with_cost=events_with_cost,
+        estimated_cost_usd=estimated_cost_usd,
+        events_with_latency=events_with_latency,
+        latency_p50_ms=latency_p50_ms,
+        latency_p90_ms=latency_p90_ms,
+        latency_p95_ms=latency_p95_ms,
+        latency_p99_ms=latency_p99_ms,
+        latency_avg_ms=latency_avg_ms,
+        events_with_duration=events_with_duration,
+        duration_avg_ms=duration_avg_ms,
+        display_tokens=display_tokens,
+        display_cost=display_cost,
+        display_latency_p50=display_latency_p50,
+        display_latency_p90=display_latency_p90,
+        display_duration_avg=display_duration_avg,
+    )
+
+
+def record_usage(
+    *,
+    db_path: str | None = None,
+    session_id: str | None = None,
+    remote: str = "dadeschools",
+    org: str = "",
+    repo: str = "",
+    project_id: str | None = None,
+    role: str = "unknown",
+    model: str = "unknown",
+    issue_number: int | None = None,
+    pr_number: int | None = None,
+    stage: str = "unknown",
+    input_tokens: int | None = None,
+    output_tokens: int | None = None,
+    total_tokens: int | None = None,
+    estimated_cost_usd: float | None = None,
+    latency_ms: int | None = None,
+    duration_ms: int | None = None,
+    status: str = "success",
+    metadata: str | dict[str, Any] | None = None,
+    created_at: str | None = None,
+) -> int:
+    """Ingest/record a single usage event with optional metrics."""
+    db = control_plane_db.ControlPlaneDB(db_path=db_path)
+    return db.record_usage_event(
+        session_id=session_id,
+        remote=remote,
+        org=org,
+        repo=repo,
+        project_id=project_id,
+        role=role,
+        model=model,
+        issue_number=issue_number,
+        pr_number=pr_number,
+        stage=stage,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        total_tokens=total_tokens,
+        estimated_cost_usd=estimated_cost_usd,
+        latency_ms=latency_ms,
+        duration_ms=duration_ms,
+        status=status,
+        metadata=metadata,
+        created_at=created_at,
+    )
+
+
+def load_analytics(
+    *,
+    db_path: str | None = None,
+    remote: str | None = None,
+    org: str | None = None,
+    repo: str | None = None,
+    project_id: str | None = None,
+    role: str | None = None,
+    model: str | None = None,
+    stage: str | None = None,
+    issue_number: int | None = None,
+    pr_number: int | None = None,
+    limit: int = 500,
+) -> AnalyticsSnapshot:
+    """Load analytics snapshot aggregated by project, role, model, issue/PR, and stage."""
+    remote_filter = (remote or "").strip() or None
+    org_filter = (org or "").strip() or None
+    repo_filter = (repo or "").strip() or None
+    role_filter = (role or "").strip() or None
+    model_filter = (model or "").strip() or None
+    stage_filter = (stage or "").strip() or None
+
+    try:
+        db = control_plane_db.ControlPlaneDB(db_path=db_path)
+        rows = db.query_usage_events(
+            remote=remote_filter,
+            org=org_filter,
+            repo=repo_filter,
+            project_id=project_id,
+            role=role_filter,
+            model=model_filter,
+            stage=stage_filter,
+            issue_number=issue_number,
+            pr_number=pr_number,
+            limit=limit,
+        )
+    except Exception as exc:
+        empty_summary = aggregate_events("Overall", [])
+        return AnalyticsSnapshot(
+            ok=False,
+            reason=f"control_plane_db_unavailable: {exc}",
+            schema_version=ANALYTICS_SCHEMA_VERSION,
+            remote=remote,
+            org=org,
+            repo=repo,
+            total_events=0,
+            overall_summary=empty_summary,
+            by_project={},
+            by_role={},
+            by_model={},
+            by_work_item={},
+            by_stage={},
+            events=(),
+        )
+
+    parsed_events: list[UsageEvent] = []
+    for r in rows:
+        meta = console_redaction.redact_text(r.get("metadata")) if r.get("metadata") else None
+        parsed_events.append(
+            UsageEvent(
+                usage_id=r["usage_id"],
+                session_id=r.get("session_id"),
+                remote=r.get("remote", remote),
+                org=r.get("org", org),
+                repo=r.get("repo", repo),
+                project_id=r.get("project_id"),
+                role=r.get("role", "unknown"),
+                model=r.get("model", "unknown"),
+                issue_number=r.get("issue_number"),
+                pr_number=r.get("pr_number"),
+                stage=r.get("stage", "unknown"),
+                input_tokens=r.get("input_tokens"),
+                output_tokens=r.get("output_tokens"),
+                total_tokens=r.get("total_tokens"),
+                estimated_cost_usd=r.get("estimated_cost_usd"),
+                latency_ms=r.get("latency_ms"),
+                duration_ms=r.get("duration_ms"),
+                status=r.get("status", "success"),
+                metadata=meta,
+                created_at=r.get("created_at", ""),
+            )
+        )
+
+    overall_summary = aggregate_events("Overall", parsed_events)
+
+    # Group by project
+    groups_by_project: dict[str, list[UsageEvent]] = {}
+    for e in parsed_events:
+        key = e.project_id or (f"{e.org}/{e.repo}" if e.org and e.repo else "default")
+        groups_by_project.setdefault(key, []).append(e)
+    by_project = {k: aggregate_events(k, v) for k, v in groups_by_project.items()}
+
+    # Group by role
+    groups_by_role: dict[str, list[UsageEvent]] = {}
+    for e in parsed_events:
+        groups_by_role.setdefault(e.role, []).append(e)
+    by_role = {k: aggregate_events(k, v) for k, v in groups_by_role.items()}
+
+    # Group by model
+    groups_by_model: dict[str, list[UsageEvent]] = {}
+    for e in parsed_events:
+        groups_by_model.setdefault(e.model, []).append(e)
+    by_model = {k: aggregate_events(k, v) for k, v in groups_by_model.items()}
+
+    # Group by work item
+    groups_by_work_item: dict[str, list[UsageEvent]] = {}
+    for e in parsed_events:
+        if e.issue_number:
+            key = f"issue #{e.issue_number}"
+        elif e.pr_number:
+            key = f"pr #{e.pr_number}"
+        else:
+            key = "unlinked"
+        groups_by_work_item.setdefault(key, []).append(e)
+    by_work_item = {k: aggregate_events(k, v) for k, v in groups_by_work_item.items()}
+
+    # Group by stage
+    groups_by_stage: dict[str, list[UsageEvent]] = {}
+    for e in parsed_events:
+        groups_by_stage.setdefault(e.stage, []).append(e)
+    by_stage = {k: aggregate_events(k, v) for k, v in groups_by_stage.items()}
+
+    return AnalyticsSnapshot(
+        ok=True,
+        reason="ok",
+        schema_version=ANALYTICS_SCHEMA_VERSION,
+        remote=remote,
+        org=org,
+        repo=repo,
+        total_events=len(parsed_events),
+        overall_summary=overall_summary,
+        by_project=by_project,
+        by_role=by_role,
+        by_model=by_model,
+        by_work_item=by_work_item,
+        by_stage=by_stage,
+        events=tuple(parsed_events),
+    )
+
+
+def snapshot_to_dict(snapshot: AnalyticsSnapshot) -> dict[str, Any]:
+    return snapshot.to_dict()

webui/analytics_views.py

@@ -0,0 +1,201 @@
+"""HTML views for the Model Usage & Performance Analytics console (#651)."""
+
+from __future__ import annotations
+
+from webui.analytics_loader import AnalyticsSnapshot, GroupMetrics, UsageEvent
+from webui.layout import render_page
+
+
+def _render_badge(text: str, badge_type: str = "muted") -> str:
+    return f'<span class="badge badge-{badge_type}">{text}</span>'
+
+
+def _render_group_table(title: str, groups: dict[str, GroupMetrics], key_header: str = "Group") -> str:
+    if not groups:
+        return (
+            f"<h3>{title}</h3>"
+            '<div class="card"><p class="muted">No telemetry events recorded for this dimension.</p></div>'
+        )
+
+    rows = []
+    for key, g in sorted(groups.items(), key=lambda x: x[1].total_events, reverse=True):
+        cost_cell = (
+            f'<span class="accent">{g.display_cost}</span>'
+            if g.events_with_cost > 0
+            else _render_badge("Unknown")
+        )
+        tokens_cell = (
+            g.display_tokens
+            if g.events_with_tokens > 0
+            else _render_badge("Unknown")
+        )
+        lat_p50 = (
+            g.display_latency_p50
+            if g.events_with_latency > 0
+            else _render_badge("Unknown")
+        )
+        lat_p90 = (
+            g.display_latency_p90
+            if g.events_with_latency > 0
+            else _render_badge("Unknown")
+        )
+        dur_avg = (
+            g.display_duration_avg
+            if g.events_with_duration > 0
+            else _render_badge("Unknown")
+        )
+
+        rows.append(
+            "<tr>"
+            f"<td><strong>{key}</strong></td>"
+            f"<td>{g.total_events}</td>"
+            f"<td>{tokens_cell}</td>"
+            f"<td>{cost_cell}</td>"
+            f"<td>{lat_p50}</td>"
+            f"<td>{lat_p90}</td>"
+            f"<td>{dur_avg}</td>"
+            "</tr>"
+        )
+
+    rows_html = "".join(rows)
+    return f"""
+    <h3>{title}</h3>
+    <div class="card" style="overflow-x: auto;">
+      <table class="data-table">
+        <thead>
+          <tr>
+            <th>{key_header}</th>
+            <th>Events</th>
+            <th>Total Tokens</th>
+            <th>Est. Cost</th>
+            <th>Latency (p50)</th>
+            <th>Latency (p90)</th>
+            <th>Avg Stage Duration</th>
+          </tr>
+        </thead>
+        <tbody>
+          {rows_html}
+        </tbody>
+      </table>
+    </div>
+    """
+
+
+def _render_events_table(events: tuple[UsageEvent, ...]) -> str:
+    if not events:
+        return (
+            "<h3>Recent Usage & Instrumentation Events</h3>"
+            '<div class="card"><p class="muted">No individual telemetry events recorded yet. Opt-in instrumentation via session logging or POST /api/v1/analytics/usage.</p></div>'
+        )
+
+    rows = []
+    for e in list(events)[-50:]:  # Display latest 50
+        work_item = f"issue #{e.issue_number}" if e.issue_number else (f"pr #{e.pr_number}" if e.pr_number else "unlinked")
+        tokens = f"{e.total_tokens:,}" if e.total_tokens is not None else _render_badge("Unknown")
+        cost = f"${e.estimated_cost_usd:.4f}" if e.estimated_cost_usd is not None else _render_badge("Unknown")
+        latency = f"{e.latency_ms} ms" if e.latency_ms is not None else _render_badge("Unknown")
+        duration = f"{e.duration_ms} ms" if e.duration_ms is not None else _render_badge("Unknown")
+        status_badge = _render_badge(e.status, "success" if e.status == "success" else "danger")
+
+        rows.append(
+            "<tr>"
+            f"<td>#{e.usage_id}</td>"
+            f"<td><small>{e.created_at}</small></td>"
+            f"<td><span class=\"badge\">{e.role}</span></td>"
+            f"<td><strong>{e.model}</strong></td>"
+            f"<td>{e.stage}</td>"
+            f"<td>{work_item}</td>"
+            f"<td>{tokens}</td>"
+            f"<td>{cost}</td>"
+            f"<td>{latency}</td>"
+            f"<td>{duration}</td>"
+            f"<td>{status_badge}</td>"
+            "</tr>"
+        )
+
+    rows_html = "".join(rows)
+    return f"""
+    <h3>Recent Telemetry Events</h3>
+    <div class="card" style="overflow-x: auto;">
+      <table class="data-table">
+        <thead>
+          <tr>
+            <th>ID</th>
+            <th>Timestamp</th>
+            <th>Role</th>
+            <th>Model</th>
+            <th>Stage</th>
+            <th>Work Item</th>
+            <th>Tokens</th>
+            <th>Cost</th>
+            <th>Latency</th>
+            <th>Duration</th>
+            <th>Status</th>
+          </tr>
+        </thead>
+        <tbody>
+          {rows_html}
+        </tbody>
+      </table>
+    </div>
+    """
+
+
+def render_analytics_page(snapshot: AnalyticsSnapshot) -> str:
+    """Render the main Model Usage & Performance Analytics console page."""
+    summary = snapshot.overall_summary
+
+    kpi_tokens = summary.display_tokens if summary.events_with_tokens > 0 else _render_badge("Unknown")
+    kpi_cost = summary.display_cost if summary.events_with_cost > 0 else _render_badge("Unknown")
+    kpi_lat_p50 = summary.display_latency_p50 if summary.events_with_latency > 0 else _render_badge("Unknown")
+    kpi_dur_avg = summary.display_duration_avg if summary.events_with_duration > 0 else _render_badge("Unknown")
+
+    status_notice = ""
+    if not snapshot.ok:
+        status_notice = (
+            f'<div class="card warning-card"><strong>Degraded Data Source:</strong> {snapshot.reason}</div>'
+        )
+
+    body_html = f"""
+    <h2>Model Usage & Performance Analytics (Phase 4)</h2>
+    <p class="muted">
+      Durable console analytics for model usage, token cost, latency percentiles, and workflow-stage performance correlated to issues, PRs, and worker roles.
+    </p>
+
+    {status_notice}
+
+    <div class="notice-card" style="background: rgba(91, 159, 212, 0.1); border: 1px solid var(--border); padding: 0.75rem 1rem; border-radius: 6px; margin-bottom: 1.5rem;">
+      <small><strong>Note on telemetry fidelity:</strong> Missing data or untracked metrics are explicitly labeled as <em>Unknown</em>. No token costs or latency metrics are zero-fabricated.</small>
+    </div>
+
+    <div class="card-grid" style="display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 1rem; margin-bottom: 1.5rem;">
+      <div class="card">
+        <span class="muted" style="font-size: 0.85rem;">Total Events</span>
+        <h3 style="margin: 0.25rem 0 0 0;">{summary.total_events}</h3>
+      </div>
+      <div class="card">
+        <span class="muted" style="font-size: 0.85rem;">Total Tokens</span>
+        <h3 style="margin: 0.25rem 0 0 0;">{kpi_tokens}</h3>
+      </div>
+      <div class="card">
+        <span class="muted" style="font-size: 0.85rem;">Est. Token Cost</span>
+        <h3 style="margin: 0.25rem 0 0 0;">{kpi_cost}</h3>
+      </div>
+      <div class="card">
+        <span class="muted" style="font-size: 0.85rem;">Latency (p50)</span>
+        <h3 style="margin: 0.25rem 0 0 0;">{kpi_lat_p50}</h3>
+      </div>
+      <div class="card">
+        <span class="muted" style="font-size: 0.85rem;">Avg Stage Duration</span>
+        <h3 style="margin: 0.25rem 0 0 0;">{kpi_dur_avg}</h3>
+      </div>
+    </div>
+
+    {_render_group_table("Usage & Cost by Model", snapshot.by_model, "Model")}
+    {_render_group_table("Performance by Workflow Stage", snapshot.by_stage, "Stage")}
+    {_render_group_table("Usage & Cost by Role", snapshot.by_role, "Role")}
+    {_render_group_table("Work Item Analytics", snapshot.by_work_item, "Work Item")}
+    {_render_events_table(snapshot.events)}
+    """
+
+    return render_page(title="Model Usage & Performance Analytics", body_html=body_html)

webui/app.py

@@ -47,13 +47,18 @@ from webui.worktree_views import render_worktrees_page
 from webui.runtime_health import load_runtime_snapshot, snapshot_to_dict as runtime_snapshot_to_dict
 from webui.runtime_views import render_runtime_page
 from webui.timeline import load_timeline, snapshot_to_dict as timeline_snapshot_to_dict
+from webui.analytics_loader import (
+    load_analytics,
+    record_usage,
+    snapshot_to_dict as analytics_snapshot_to_dict,
+)
+from webui.analytics_views import render_analytics_page
 from webui.system_health import (
     API_PATH as SYSTEM_HEALTH_API_PATH,
     load_system_health,
     process_uptime,
     snapshot_to_dict as system_health_to_dict,
 )
-from webui.system_health_views import render_system_health_page
 
 _READ_ONLY_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
 _AUDIT_MUTATION_PATHS = frozenset({"/audit", "/api/audit"})
@@ -162,24 +167,6 @@ async def api_system_health(request: Request) -> JSONResponse:
     return JSONResponse(payload, status_code=200 if snapshot.ready else 503)
 
 
-async def system_health(request: Request) -> HTMLResponse:
-    """Read-only system-health dashboard (#639).
-
-    Shares the #634 snapshot loader with the JSON API so the page can never
-    disagree with it. `?deep=1` opts into the network probe exactly as the API
-    does; the default page load stays cheap. The response is always 200: this
-    is an operator view that must render the degraded state, not withhold it.
-    """
-    deep = _truthy_flag(request.query_params.get("deep"))
-    snapshot = load_system_health(deep=deep)
-    return HTMLResponse(
-        render_page(
-            title="System health",
-            body_html=render_system_health_page(snapshot),
-        )
-    )
-
-
 async def queue(_request: Request) -> HTMLResponse:
     snapshot = load_queue_snapshot()
     return HTMLResponse(render_page(title="Queue", body_html=render_queue_page(snapshot)))
@@ -567,6 +554,72 @@ async def api_v1_timeline(request: Request) -> JSONResponse:
     return JSONResponse(timeline_snapshot_to_dict(snapshot), status_code=status_code)
 
 
+async def analytics(request: Request) -> HTMLResponse:
+    """Read-only model usage, token cost, latency, and performance analytics HTML view (#651)."""
+    snapshot = load_analytics(
+        remote=request.query_params.get("remote"),
+        org=request.query_params.get("org"),
+        repo=request.query_params.get("repo"),
+        role=request.query_params.get("role"),
+        model=request.query_params.get("model"),
+        stage=request.query_params.get("stage"),
+        issue_number=_query_int(request, "issue"),
+        pr_number=_query_int(request, "pr"),
+        limit=_query_int(request, "limit") or 200,
+    )
+    return HTMLResponse(render_analytics_page(snapshot))
+
+
+async def api_v1_analytics(request: Request) -> JSONResponse:
+    """Read-only model usage, token cost, latency, and performance analytics API (#651)."""
+    snapshot = load_analytics(
+        remote=request.query_params.get("remote"),
+        org=request.query_params.get("org"),
+        repo=request.query_params.get("repo"),
+        role=request.query_params.get("role"),
+        model=request.query_params.get("model"),
+        stage=request.query_params.get("stage"),
+        issue_number=_query_int(request, "issue"),
+        pr_number=_query_int(request, "pr"),
+        limit=_query_int(request, "limit") or 500,
+    )
+    status_code = 200 if snapshot.ok else 500
+    return JSONResponse(analytics_snapshot_to_dict(snapshot), status_code=status_code)
+
+
+async def api_v1_analytics_ingest(request: Request) -> JSONResponse:
+    """Optional session instrumentation ingestion endpoint (#651)."""
+    try:
+        body = await request.json()
+    except Exception:
+        return JSONResponse({"error": "invalid_json", "detail": "body must be valid JSON"}, status_code=400)
+
+    if not isinstance(body, dict):
+        return JSONResponse({"error": "invalid_payload", "detail": "payload must be a JSON object"}, status_code=400)
+
+    usage_id = record_usage(
+        session_id=body.get("session_id"),
+        remote=body.get("remote", "dadeschools"),
+        org=body.get("org", ""),
+        repo=body.get("repo", ""),
+        project_id=body.get("project_id"),
+        role=body.get("role", "unknown"),
+        model=body.get("model", "unknown"),
+        issue_number=body.get("issue_number") or body.get("issue"),
+        pr_number=body.get("pr_number") or body.get("pr"),
+        stage=body.get("stage", "unknown"),
+        input_tokens=body.get("input_tokens"),
+        output_tokens=body.get("output_tokens"),
+        total_tokens=body.get("total_tokens"),
+        estimated_cost_usd=body.get("estimated_cost_usd"),
+        latency_ms=body.get("latency_ms"),
+        duration_ms=body.get("duration_ms"),
+        status=body.get("status", "success"),
+        metadata=body.get("metadata"),
+    )
+    return JSONResponse({"ok": True, "usage_id": usage_id}, status_code=201)
+
+
 async def method_not_allowed(request: Request, _exc: Exception) -> Response:
     path = request.url.path
     if path in _AUDIT_MUTATION_PATHS and request.method == "POST":
@@ -590,7 +643,6 @@ def create_app(*, bind_host: str | None = None) -> Starlette:
             Route("/", home, methods=["GET"]),
             Route("/health", health, methods=["GET"]),
             Route(SYSTEM_HEALTH_API_PATH, api_system_health, methods=["GET"]),
-            Route("/system-health", system_health, methods=["GET"]),
             Route("/queue", queue, methods=["GET"]),
             Route("/api/queue", api_queue, methods=["GET"]),
             Route("/projects", projects, methods=["GET"]),
@@ -608,6 +660,10 @@ def create_app(*, bind_host: str | None = None) -> Starlette:
             Route("/runtime", runtime, methods=["GET"]),
             Route("/api/runtime", api_runtime, methods=["GET"]),
             Route("/api/v1/timeline", api_v1_timeline, methods=["GET"]),
+            Route("/analytics", analytics, methods=["GET"]),
+            Route("/api/analytics", api_v1_analytics, methods=["GET"]),
+            Route("/api/v1/analytics", api_v1_analytics, methods=["GET"]),
+            Route("/api/v1/analytics/usage", api_v1_analytics_ingest, methods=["POST"]),
             Route("/audit", audit, methods=["GET", "POST"]),
             Route("/api/audit", api_audit, methods=["GET", "POST"]),
             Route("/worktrees", worktrees, methods=["GET"]),

webui/layout.py

@@ -236,25 +236,6 @@ def render_page(*, title: str, body_html: str, extra_head: str = "") -> str:
     .badge-in-review {{ color: #9ec8f0; border-color: #3d5f7a; }}
     .badge-duplicate {{ color: #e0c27a; border-color: #6b5730; }}
     .badge-stale {{ color: #c9b8e8; border-color: #5a4a78; }}
-    .badge-health-ok {{ color: #8fd19e; border-color: #3d6b4a; }}
-    .badge-health-degraded {{ color: #e0c27a; border-color: #6b5730; }}
-    .badge-health-down {{ color: #f0a8a8; border-color: #7a3b3b; }}
-    .badge-health-skipped {{ color: var(--muted); }}
-    .badge-health-unproven {{ color: #c9b8e8; border-color: #5a4a78; }}
-    .health-card {{
-      margin: 1.25rem 0;
-      padding: 0.85rem 1rem 1rem;
-      border: 1px solid var(--border);
-      border-radius: 8px;
-      background: var(--surface);
-    }}
-    .health-card h3 {{ margin: 0 0 0.5rem; font-size: 1.05rem; }}
-    .health-card h4 {{ margin: 1rem 0 0.35rem; font-size: 0.92rem; color: var(--muted); }}
-    .health-headline {{ color: var(--text); font-size: 1rem; margin: 0 0 0.5rem; }}
-    .health-degraded {{ border-left-color: #e0c27a; }}
-    .health-stale {{ border-left-color: #f0a8a8; }}
-    ul.reasons {{ margin: 0.35rem 0; padding-left: 1.15rem; color: var(--muted); font-size: 0.9rem; }}
-    ul.reasons li {{ margin-bottom: 0.3rem; }}
   </style>
   {extra_head}
 </head>

webui/nav.py

@@ -38,7 +38,6 @@ class NavGroup:
 NAV_GROUPS: tuple[NavGroup, ...] = (
     NavGroup("Health", (
         NavItem("/health", "Liveness"),
-        NavItem("/system-health", "System health"),
     )),
     NavGroup("Traffic", (
         NavItem("/queue", "Queue"),
@@ -65,6 +64,7 @@ NAV_GROUPS: tuple[NavGroup, ...] = (
     )),
     NavGroup("Insights", (
         NavItem("/insights", "Insights", "stub"),
+        NavItem("/analytics", "Analytics"),
         NavItem("/audit", "Audit"),
     )),
 )

webui/system_health_views.py

@@ -1,307 +0,0 @@
-"""HTML views for the system-health dashboard (#639).
-
-Renders the read-only :class:`~webui.system_health.SystemHealthSnapshot`
-produced by the Phase 1 system-health API (#634). The page offers no restart,
-reload, or process-kill control: those are Phase 2 work, and manual process
-kills are the contamination path #630 exists to prevent.
-
-Every free-text field passes through :func:`webui.system_health.redact` before
-it reaches HTML, so a probe detail that captured a token or a credentialed URL
-cannot leak through the dashboard even though the API redacts it already.
-"""
-
-from __future__ import annotations
-
-import html
-
-from webui.system_health import (
-    STATUS_DEGRADED,
-    STATUS_DOWN,
-    STATUS_OK,
-    STATUS_SKIPPED,
-    STATUS_UNPROVEN,
-    DependencyProbe,
-    SystemHealthSnapshot,
-    redact,
-)
-
-_STATUS_BADGE_CLASS = {
-    STATUS_OK: "badge-health-ok",
-    STATUS_DEGRADED: "badge-health-degraded",
-    STATUS_DOWN: "badge-health-down",
-    STATUS_SKIPPED: "badge-health-skipped",
-    STATUS_UNPROVEN: "badge-health-unproven",
-}
-
-
-def _safe(value: object) -> str:
-    """Escape free text for HTML after redacting anything secret-shaped.
-
-    Use this for every value that can carry arbitrary text — probe details,
-    reasons, probe errors — because those are where a credential could ride
-    along.
-    """
-    return html.escape(redact(str(value)))
-
-
-def _esc(value: object) -> str:
-    """Escape a structured field for HTML without redacting it.
-
-    Commit SHAs, probe names, statuses, and timestamps are enumerated or
-    machine-generated, never credential-bearing. They must not go through
-    :func:`redact`: its opaque-token rule matches any 32-plus-character run,
-    so a 40-character git SHA would render as ``[redacted]`` and the parity
-    view — the one thing an operator reads this page for — would be blank.
-    """
-    return html.escape(str(value))
-
-
-def _status_badge(status: str) -> str:
-    css = _STATUS_BADGE_CLASS.get(status, "badge-health-unproven")
-    return f'<span class="badge {css}">{_esc(status)}</span>'
-
-
-def _reason_list(reasons: tuple[str, ...], *, empty: str) -> str:
-    if not reasons:
-        return f"<p class='muted'>{html.escape(empty)}</p>"
-    items = "".join(f"<li>{_safe(reason)}</li>" for reason in reasons)
-    return f"<ul class='reasons'>{items}</ul>"
-
-
-def _readiness_card(snapshot: SystemHealthSnapshot) -> str:
-    """Overall readiness.
-
-    ``ready`` and ``readiness_complete`` are shown separately on purpose: a
-    snapshot whose required probes never ran is not the same as one that ran
-    them and passed, and collapsing the two would render an unproven green.
-    """
-    if snapshot.ready and snapshot.readiness_complete:
-        headline = "Ready"
-    elif snapshot.ready:
-        headline = "Ready (incomplete evidence)"
-    else:
-        headline = "Not ready"
-
-    return (
-        "<section class='health-card'>"
-        f"<h3>Readiness {_status_badge(snapshot.status)}</h3>"
-        f"<p class='health-headline'>{html.escape(headline)}</p>"
-        "<table class='detail'>"
-        f"<tr><th>Service</th><td><code>{_esc(snapshot.service)}</code></td></tr>"
-        f"<tr><th>Mode</th><td>{_esc(snapshot.mode)}</td></tr>"
-        f"<tr><th>Ready</th><td>{_esc(snapshot.ready)}</td></tr>"
-        "<tr><th>Readiness evidence complete</th>"
-        f"<td>{_esc(snapshot.readiness_complete)}</td></tr>"
-        "<tr><th>Deep probes requested</th>"
-        f"<td>{_esc(snapshot.deep_probes_requested)}</td></tr>"
-        f"<tr><th>Observed at</th><td><code>{_esc(snapshot.timestamp)}</code></td></tr>"
-        "</table>"
-        "<h4>Readiness reasons</h4>"
-        f"{_reason_list(snapshot.readiness_reasons, empty='No readiness objections recorded.')}"
-        "</section>"
-    )
-
-
-def _version_card(snapshot: SystemHealthSnapshot) -> str:
-    version = snapshot.version
-    uptime_hours = snapshot.uptime_seconds / 3600.0
-    known = (
-        "resolved"
-        if version.known
-        else "unresolved — version fields could not be read from the checkout"
-    )
-    schema = version.control_plane_schema_version
-    return (
-        "<section class='health-card'>"
-        "<h3>Version and uptime</h3>"
-        "<table class='detail'>"
-        f"<tr><th>Git SHA</th><td><code>{_esc(version.git_sha or 'unknown')}</code></td></tr>"
-        "<tr><th>Git describe</th>"
-        f"<td><code>{_esc(version.git_describe or 'unknown')}</code></td></tr>"
-        "<tr><th>Control-plane schema</th>"
-        f"<td>{_esc(schema if schema is not None else 'unknown')}</td></tr>"
-        f"<tr><th>Python</th><td><code>{_esc(version.python_version)}</code></td></tr>"
-        f"<tr><th>Version status</th><td>{html.escape(known)}</td></tr>"
-        f"<tr><th>Started at</th><td><code>{_esc(snapshot.started_at)}</code></td></tr>"
-        "<tr><th>Uptime</th>"
-        f"<td>{snapshot.uptime_seconds:.3f}s ({uptime_hours:.2f}h)</td></tr>"
-        "</table>"
-        "</section>"
-    )
-
-
-def _dependency_rows(probes: tuple[DependencyProbe, ...]) -> str:
-    if not probes:
-        return "<p class='muted'>No dependency probes were reported.</p>"
-    rows = []
-    for probe in probes:
-        latency = (
-            f"{probe.latency_ms:.1f} ms" if probe.latency_ms is not None else "n/a"
-        )
-        rows.append(
-            "<tr>"
-            f"<td><code>{_esc(probe.name)}</code></td>"
-            f"<td>{_esc(probe.kind)}</td>"
-            f"<td>{_status_badge(probe.status)}</td>"
-            f"<td>{_esc('required' if probe.required else 'optional')}</td>"
-            f"<td>{html.escape(latency)}</td>"
-            f"<td>{_safe(probe.detail)}</td>"
-            "</tr>"
-        )
-    return (
-        "<table class='registry'><thead><tr>"
-        "<th>Dependency</th><th>Kind</th><th>Status</th><th>Requirement</th>"
-        "<th>Latency</th><th>Detail</th>"
-        "</tr></thead><tbody>"
-        f"{''.join(rows)}</tbody></table>"
-    )
-
-
-def _dependency_card(snapshot: SystemHealthSnapshot) -> str:
-    degraded = [probe for probe in snapshot.dependencies if probe.ran and not probe.healthy]
-    not_run = [probe for probe in snapshot.dependencies if not probe.ran]
-
-    banner = ""
-    if degraded:
-        names = ", ".join(sorted(probe.name for probe in degraded))
-        banner += (
-            "<div class='stub health-degraded'><p><strong>Degraded dependencies:</strong> "
-            f"{_esc(names)}</p></div>"
-        )
-    if not_run:
-        names = ", ".join(sorted(probe.name for probe in not_run))
-        banner += (
-            "<div class='stub'><p><strong>Not probed:</strong> "
-            f"{_esc(names)} — these contribute no evidence and are not counted "
-            "as healthy.</p></div>"
-        )
-
-    return (
-        "<section class='health-card'>"
-        "<h3>Dependencies</h3>"
-        f"{banner}"
-        f"{_dependency_rows(snapshot.dependencies)}"
-        "<p class='muted'>Details are redacted at the API boundary and again "
-        "before rendering; credentials are never displayed.</p>"
-        "</section>"
-    )
-
-
-def _namespace_card(snapshot: SystemHealthSnapshot) -> str:
-    if not snapshot.mcp_namespaces:
-        body = "<p class='muted'>No MCP namespaces are declared.</p>"
-    else:
-        rows = []
-        for entry in snapshot.mcp_namespaces:
-            rows.append(
-                "<tr>"
-                f"<td><code>{_esc(entry.get('namespace'))}</code></td>"
-                f"<td><code>{_esc(entry.get('required_tool'))}</code></td>"
-                f"<td>{_status_badge(str(entry.get('status') or STATUS_UNPROVEN))}</td>"
-                f"<td>{_esc(entry.get('ide_namespace_proven'))}</td>"
-                f"<td>{_safe(entry.get('reason'))}</td>"
-                "</tr>"
-            )
-        body = (
-            "<table class='registry'><thead><tr>"
-            "<th>Namespace</th><th>Required tool</th><th>Status</th>"
-            "<th>IDE-proven</th><th>Reason</th>"
-            "</tr></thead><tbody>"
-            f"{''.join(rows)}</tbody></table>"
-        )
-    return (
-        "<section class='health-card'>"
-        "<h3>MCP namespaces</h3>"
-        f"{body}"
-        "<p class='muted'>The web process runs outside the IDE-managed MCP "
-        "client, so namespace health is reported as unproven rather than "
-        "guessed (#543).</p>"
-        "</section>"
-    )
-
-
-def _stale_runtime_card(snapshot: SystemHealthSnapshot) -> str:
-    stale = snapshot.stale_runtime
-    if stale.stale:
-        warning = (
-            "<div class='stub health-stale'><p><strong>Stale runtime:</strong> "
-            "the running code, the checkout, and the remote-tracking commit "
-            "disagree. Capability gates may be evaluating obsolete code — "
-            "do not treat this runtime as mutation-safe.</p></div>"
-        )
-    elif not stale.determinable:
-        warning = (
-            "<div class='stub health-stale'><p><strong>Staleness "
-            "indeterminate:</strong> parity could not be proven, so this "
-            "runtime is not reported as mutation-safe.</p></div>"
-        )
-    else:
-        warning = ""
-
-    return (
-        "<section class='health-card'>"
-        "<h3>Stale-runtime parity</h3>"
-        f"{warning}"
-        "<table class='detail'>"
-        "<tr><th>Daemon head</th>"
-        f"<td><code>{_esc(stale.daemon_head or 'unknown')}</code></td></tr>"
-        "<tr><th>Checkout head</th>"
-        f"<td><code>{_esc(stale.checkout_head or 'unknown')}</code></td></tr>"
-        "<tr><th>Remote head</th>"
-        f"<td><code>{_esc(stale.remote_head or 'unknown')}</code></td></tr>"
-        f"<tr><th>Stale</th><td>{_esc(stale.stale)}</td></tr>"
-        f"<tr><th>Determinable</th><td>{_esc(stale.determinable)}</td></tr>"
-        f"<tr><th>Mutation safe</th><td>{_esc(stale.mutation_safe)}</td></tr>"
-        "</table>"
-        f"{_reason_list(stale.reasons, empty='Runtime, checkout, and remote agree.')}"
-        "</section>"
-    )
-
-
-def _probe_error_card(snapshot: SystemHealthSnapshot) -> str:
-    if not snapshot.probe_errors:
-        return ""
-    return (
-        "<section class='health-card'>"
-        "<h3>Probe errors</h3>"
-        f"{_reason_list(snapshot.probe_errors, empty='')}"
-        "</section>"
-    )
-
-
-def _recovery_card() -> str:
-    """Sanctioned recovery pointers only — never a manual process kill (#630)."""
-    return (
-        "<section class='health-card'>"
-        "<h3>Recovery</h3>"
-        "<p class='muted'>This dashboard is read-only. Restart and reload "
-        "controls arrive in Phase 2 (#642); until then recovery runs through "
-        "the sanctioned client reconnect / operator restart path.</p>"
-        "<ul class='reasons'>"
-        "<li><a href='/runtime'>Runtime and session view</a> — active profile, "
-        "workflow hashes, and shell health.</li>"
-        "<li>Reconnect the MCP client from the IDE, then re-run the blocked "
-        "cycle. Never kill the daemon process manually: unmanaged kills are "
-        "recorded as runtime contamination (#630).</li>"
-        "<li>See <code>docs/webui-local-dev.md</code> for the documented "
-        "recovery sequence.</li>"
-        "</ul>"
-        "</section>"
-    )
-
-
-def render_system_health_page(snapshot: SystemHealthSnapshot) -> str:
-    """Render the full system-health dashboard body."""
-    return (
-        "<h2>System health</h2>"
-        "<p class='meta'>Read-only view of the Phase 1 system-health API "
-        "(<code>/api/v1/system/health</code>). Reload this page to refresh; "
-        "nothing here polls or mutates on your behalf.</p>"
-        f"{_readiness_card(snapshot)}"
-        f"{_stale_runtime_card(snapshot)}"
-        f"{_version_card(snapshot)}"
-        f"{_dependency_card(snapshot)}"
-        f"{_namespace_card(snapshot)}"
-        f"{_probe_error_card(snapshot)}"
-        f"{_recovery_card()}"
-    )