Merge branch 'master' into feat/issue-642-sanctioned-restart-controls

webui/app.py

@@ -53,6 +53,7 @@ from webui.system_health import (
     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"})
@@ -161,6 +162,24 @@ 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)))
@@ -571,6 +590,7 @@ 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"]),

webui/layout.py

@@ -236,6 +236,25 @@ 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,6 +38,7 @@ class NavGroup:
 NAV_GROUPS: tuple[NavGroup, ...] = (
     NavGroup("Health", (
         NavItem("/health", "Liveness"),
+        NavItem("/system-health", "System health"),
     )),
     NavGroup("Traffic", (
         NavItem("/queue", "Queue"),

webui/system_health_views.py

@@ -0,0 +1,307 @@
+"""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()}"
+    )