From 619f67907726631a74e6333d8004a435130e2309 Mon Sep 17 00:00:00 2001 From: Jason Walker <913443@dadeschools.net> Date: Fri, 24 Jul 2026 22:45:27 -0400 Subject: [PATCH 1/2] feat(webui): Runtime and session view (Phase 1) (Closes #641) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Compose runtime health with inventory sessions/namespaces/worktrees into a live /sessions page and JSON API. Surface stale PID/lease flags and durable contamination markers when detectable. Recovery links name sanctioned reconnect/restart paths only — no kill controls. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/webui-local-dev.md | 29 +- tests/test_webui_sessions_view.py | 457 ++++++++++++++++++++++++++++++ webui/app.py | 20 ++ webui/nav.py | 7 +- webui/runtime_views.py | 4 +- webui/session_loader.py | 428 ++++++++++++++++++++++++++++ webui/session_views.py | 344 ++++++++++++++++++++++ webui/system_health_views.py | 6 +- 8 files changed, 1280 insertions(+), 15 deletions(-) create mode 100644 tests/test_webui_sessions_view.py create mode 100644 webui/session_loader.py create mode 100644 webui/session_views.py diff --git a/docs/webui-local-dev.md b/docs/webui-local-dev.md index d9cc022..70bb50b 100644 --- a/docs/webui-local-dev.md +++ b/docs/webui-local-dev.md @@ -77,7 +77,9 @@ status, onboarding checklist state, and the fail-closed error payloads (#635). | `/api/actions/{id}/preview` | Mutation ledger preview (GET, read-only) | | `/leases` | Lease and collision visibility (#433) | | `/api/leases` | JSON lease/collision export | -| `/sessions` | Phase 1 shell stub — session inventory (backed by #636) | +| `/sessions` | Runtime and session view (#641) — health + inventory sessions/namespaces/worktrees | +| `/api/sessions` | JSON export for the runtime/session view | +| `/api/v1/sessions` | Versioned alias of `/api/sessions` | | `/inventory` | Phase 1 shell stub — unified inventory (backed by #636) | | `/timeline` | Phase 1 shell stub — workflow event timeline | | `/policy` | Phase 1 shell stub — capability/role policy placeholder | @@ -284,11 +286,26 @@ The header carries two read-only status badges — an **environment** badge a **mode: read-only** badge — plus a **Docs** link to this document. No privileged action controls are present in the Phase 1 shell. -Not-yet-implemented surfaces (`/sessions`, `/inventory`, `/timeline`, -`/policy`, `/insights`) resolve to graceful read-only stub pages instead of -404s; their backing views land in later child issues of #631 (the inventory -surfaces are backed by #636). Mutating methods on stub routes still fail closed -with `read-only-mvp`. +Not-yet-implemented surfaces (`/inventory`, `/timeline`, `/policy`, +`/insights`) resolve to graceful read-only stub pages instead of 404s; their +backing views land in later child issues of #631 (the inventory surfaces are +backed by #636). Mutating methods on stub routes still fail closed with +`read-only-mvp`. + +### Runtime and sessions (#641) + +`/sessions` is a live Phase 1 read-only view that composes: + +* runtime health from `#430` (profile, role, identity, master parity, stale warning) +* control-plane sessions / leases and filesystem locks / worktrees / namespaces from `#636` +* durable contamination markers when detectable (`#630` runtime recovery, `#671` stable-branch push) + +It surfaces stale indicators (dead PID, expired lease) and never silences an +active contamination marker. Recovery links point only at sanctioned +reconnect/operator restart docs (`docs/mcp-namespace-eof-recovery.md`, +`docs/mcp-namespace-health.md`, `docs/mcp-restart-path-inventory.md`, this +document). The page does **not** restart, kill, or take over sessions; manual +`pkill` of MCP daemons is contamination, not recovery. ## System-health dashboard (#639) diff --git a/tests/test_webui_sessions_view.py b/tests/test_webui_sessions_view.py new file mode 100644 index 0000000..8bb49fd --- /dev/null +++ b/tests/test_webui_sessions_view.py @@ -0,0 +1,457 @@ +"""Tests for the Runtime and session view (Phase 1, #641). + +Covers clean and stale session rendering, contamination marker surfacing, +worktree binding display, sanctioned recovery links (no pkill), nav/live +status, and the JSON API export. +""" + +from __future__ import annotations + +import sys +import unittest +from pathlib import Path +from unittest import mock + +sys.path.insert(0, str(Path(__file__).resolve().parent.parent)) + +from tests.webui_testclient import TestClient + +from webui.app import create_app +from webui.inventory import ( + AUTHORITY_CONTROL_PLANE_DB, + AUTHORITY_FILESYSTEM, + InventorySection, + InventorySnapshot, + STATUS_OK, + STATUS_UNAVAILABLE, +) +from webui.nav import NAV_GROUPS, STUB_PAGES, iter_nav_items +from webui.runtime_health import FileHash, RuntimeSnapshot +from webui.session_loader import ( + ContaminationMarker, + SessionRow, + SessionViewSnapshot, + _build_session_rows, + load_session_view_snapshot, + snapshot_to_dict, +) +from webui.session_views import render_sessions_page + + +def _runtime( + *, + stale: str | None = None, + profile: str = "prgs-author", + role: str = "author", +) -> RuntimeSnapshot: + return RuntimeSnapshot( + project_id="gitea-tools", + repo_root="/tmp/repo", + remote="prgs", + host="gitea.prgs.cc", + profile_name=profile, + role_kind=role, + config_model="v2-contexts", + profile_mode="dynamic-profile", + profile_source="config file profile", + authenticated_username="jcwalker3", + identity_error=None, + repo_sha="a" * 40, + remote_master_sha="a" * 40, + commits_behind_master=0, + stale_runtime_warning=stale, + shell_health={"shell_use_allowed": True, "consecutive_spawn_failures": 0}, + workflow_hashes=( + FileHash(label="SKILL.md", path="skills/llm-project-workflow/SKILL.md", sha256="abc"), + ), + schema_hashes=(), + restart_guidance="docs/mcp-namespace-eof-recovery.md", + fetch_error=None, + ) + + +def _inventory( + *, + sessions: tuple[dict, ...] = (), + leases: tuple[dict, ...] = (), + locks: tuple[dict, ...] = (), + worktrees: tuple[dict, ...] = (), + namespaces: tuple[dict, ...] = (), +) -> InventorySnapshot: + sections = ( + InventorySection( + name="sessions", + authority=AUTHORITY_CONTROL_PLANE_DB, + status=STATUS_OK, + items=sessions, + ), + InventorySection( + name="leases", + authority=AUTHORITY_CONTROL_PLANE_DB, + status=STATUS_OK, + items=leases, + ), + InventorySection( + name="locks", + authority=AUTHORITY_FILESYSTEM, + status=STATUS_OK, + items=locks, + ), + InventorySection( + name="worktrees", + authority=AUTHORITY_FILESYSTEM, + status=STATUS_OK, + items=worktrees, + ), + InventorySection( + name="namespaces", + authority=AUTHORITY_FILESYSTEM, + status=STATUS_OK, + items=namespaces + or ( + { + "profile_name": "prgs-author", + "role": "author", + "mcp_namespace": "gitea-author", + "capability_summary": { + "can_author": True, + "can_review": False, + "can_merge": False, + }, + "active": True, + }, + ), + reason="only the profile serving this web process is observable", + ), + ) + index = {section.name: section for section in sections} + return InventorySnapshot( + generated_at="2026-07-25T00:00:00+00:00", + sections=sections, + collisions=(), + correlations=(), + scan_ms=1.0, + _section_index=index, + ) + + +def _clean_session() -> dict: + return { + "session_id": "prgs-author-111-clean", + "role": "author", + "profile": "prgs-author", + "namespace": "gitea-author", + "pid": 1111, + "pid_alive": True, + "status": "active", + "started_at": "2026-07-25T00:00:00Z", + "last_heartbeat_at": "2026-07-25T01:00:00Z", + } + + +def _stale_session() -> dict: + return { + "session_id": "prgs-author-222-stale", + "role": "author", + "profile": "prgs-author", + "namespace": "gitea-author", + "pid": 2222, + "pid_alive": False, + "status": "active", + "started_at": "2026-07-24T00:00:00Z", + "last_heartbeat_at": "2026-07-24T01:00:00Z", + } + + +class TestBuildSessionRows(unittest.TestCase): + def test_clean_session_has_no_stale_or_contamination_flags(self): + inventory = _inventory( + sessions=(_clean_session(),), + leases=( + { + "lease_id": "lease-clean", + "session_id": "prgs-author-111-clean", + "status": "active", + "expired": False, + "work_kind": "issue", + "work_number": 641, + }, + ), + locks=( + { + "issue_number": 641, + "branch_name": "feat/issue-641-runtime-session-view", + "worktree_path": "~/Development/Gitea-Tools/branches/feat-issue-641", + "live": True, + }, + ), + ) + rows = _build_session_rows(inventory, contamination=()) + self.assertEqual(len(rows), 1) + row = rows[0] + self.assertEqual(row.session_id, "prgs-author-111-clean") + self.assertEqual(row.role, "author") + self.assertEqual(row.namespace, "gitea-author") + self.assertEqual(row.pid_alive, True) + self.assertEqual(row.lease_ids, ("lease-clean",)) + self.assertEqual(row.work_refs, ("issue#641",)) + self.assertTrue(row.worktree_paths) + self.assertEqual(row.stale_flags, ()) + self.assertEqual(row.contamination_flags, ()) + + def test_stale_session_flags_dead_pid(self): + inventory = _inventory(sessions=(_stale_session(),)) + rows = _build_session_rows(inventory, contamination=()) + self.assertEqual(rows[0].stale_flags, ("pid-dead",)) + + def test_contamination_marker_binds_to_session(self): + inventory = _inventory(sessions=(_clean_session(),)) + marker = ContaminationMarker( + kind="runtime_recovery_contamination", + on_disk=True, + has_payload=True, + summary="manual daemon kill", + reason_class="manual_daemon_kill", + session_id="prgs-author-111-clean", + role="author", + command_summary="pkill -f mcp_server.py", + cleared=False, + ) + rows = _build_session_rows(inventory, contamination=(marker,)) + self.assertIn("runtime_recovery_contamination", rows[0].contamination_flags) + + def test_process_wide_contamination_surfaces_on_all_sessions(self): + inventory = _inventory(sessions=(_clean_session(), _stale_session())) + marker = ContaminationMarker( + kind="stable_branch_contamination", + on_disk=True, + has_payload=True, + summary="direct master push attempt", + reason_class="stable_branch_push", + session_id=None, + cleared=False, + ) + rows = _build_session_rows(inventory, contamination=(marker,)) + self.assertEqual(len(rows), 2) + for row in rows: + self.assertTrue( + any("stable_branch_contamination" in f for f in row.contamination_flags) + ) + + +class TestRenderSessionsPage(unittest.TestCase): + def _snapshot( + self, + *, + sessions: tuple[dict, ...], + contamination: tuple[ContaminationMarker, ...] = (), + stale_runtime: str | None = None, + ) -> SessionViewSnapshot: + inventory = _inventory( + sessions=sessions, + leases=( + { + "lease_id": "lease-1", + "session_id": sessions[0]["session_id"] if sessions else "", + "status": "active", + "expired": False, + "work_kind": "issue", + "work_number": 641, + }, + ) + if sessions + else (), + locks=( + { + "issue_number": 641, + "worktree_path": "branches/feat-issue-641", + }, + ) + if sessions + else (), + worktrees=( + { + "rel_path": "branches/feat-issue-641", + "branch": "feat/issue-641-runtime-session-view", + "classification": "active_issue_work", + "registered_worktree": True, + "dirty": False, + }, + ), + ) + rows = _build_session_rows(inventory, contamination) + return SessionViewSnapshot( + runtime=_runtime(stale=stale_runtime), + inventory=inventory, + sessions=rows, + contamination_markers=contamination, + ) + + def test_clean_session_render(self): + html = render_sessions_page(self._snapshot(sessions=(_clean_session(),))) + self.assertIn("Runtime and sessions", html) + self.assertIn("prgs-author-111-clean", html) + self.assertIn("gitea-author", html) + self.assertIn("branches/feat-issue-641", html) + self.assertIn("Sanctioned recovery", html) + self.assertIn("docs/mcp-namespace-eof-recovery.md", html) + # Recovery section must name reconnect and forbid manual kill. + recovery_idx = html.lower().find("sanctioned recovery") + self.assertGreaterEqual(recovery_idx, 0) + recovery = html[recovery_idx:].lower() + self.assertIn("reconnect", recovery) + self.assertIn("contamination", recovery) + self.assertIn("not recovery", recovery) + self.assertNotIn("run pkill", recovery) + self.assertNotIn("killall", recovery) + + def test_stale_session_render(self): + html = render_sessions_page(self._snapshot(sessions=(_stale_session(),))) + self.assertIn("prgs-author-222-stale", html) + self.assertIn("pid-dead", html) + self.assertIn("badge-stale", html) + + def test_contamination_render_is_not_silent(self): + marker = ContaminationMarker( + kind="runtime_recovery_contamination", + on_disk=True, + has_payload=True, + summary="manual kill", + reason_class="manual_daemon_kill", + session_id="prgs-author-111-clean", + command_summary="pkill -f mcp_server.py", + cleared=False, + ) + html = render_sessions_page( + self._snapshot(sessions=(_clean_session(),), contamination=(marker,)) + ) + self.assertIn("Contamination markers", html) + self.assertIn("runtime_recovery_contamination", html) + self.assertIn("ACTIVE", html) + self.assertIn("badge-blocked", html) + + def test_stale_runtime_banner(self): + html = render_sessions_page( + self._snapshot( + sessions=(_clean_session(),), + stale_runtime="server behind master by 3 commits", + ) + ) + self.assertIn("Stale runtime", html) + self.assertIn("server behind master", html) + + +class TestSessionLoaderComposition(unittest.TestCase): + def test_load_with_injected_sources(self): + inventory = _inventory(sessions=(_clean_session(), _stale_session())) + snap = load_session_view_snapshot( + load_runtime=lambda: _runtime(), + load_inventory=lambda: inventory, + inspect_contamination=lambda **_k: { + "on_disk": False, + "has_payload": False, + "summary": "absent", + }, + load_contamination_payload=lambda **_k: None, + ) + self.assertEqual(len(snap.sessions), 2) + self.assertEqual(snap.stale_session_count, 1) + self.assertEqual(snap.contaminated_session_count, 0) + data = snapshot_to_dict(snap) + self.assertEqual(data["view"], "runtime-sessions") + self.assertEqual(data["issue"], 641) + self.assertTrue(data["read_only"]) + self.assertEqual(data["session_counts"]["total"], 2) + self.assertEqual(data["session_counts"]["stale"], 1) + self.assertIn("recovery_docs", data) + + +class TestSessionsRoutes(unittest.TestCase): + def setUp(self): + self.client = TestClient(create_app()) + inventory = _inventory( + sessions=(_clean_session(), _stale_session()), + leases=( + { + "lease_id": "lease-x", + "session_id": "prgs-author-111-clean", + "status": "active", + "expired": False, + "work_kind": "issue", + "work_number": 641, + }, + ), + locks=( + { + "issue_number": 641, + "worktree_path": "branches/feat-issue-641", + }, + ), + worktrees=( + { + "rel_path": "branches/feat-issue-641", + "branch": "feat/issue-641-runtime-session-view", + "classification": "active_issue_work", + "registered_worktree": True, + "dirty": False, + }, + ), + ) + rows = _build_session_rows(inventory, contamination=()) + self.snapshot = SessionViewSnapshot( + runtime=_runtime(stale="stale for test"), + inventory=inventory, + sessions=rows, + contamination_markers=(), + ) + self._patch = mock.patch( + "webui.app.load_session_view_snapshot", + return_value=self.snapshot, + ) + self._patch.start() + + def tearDown(self): + self._patch.stop() + + def test_sessions_page_live(self): + response = self.client.get("/sessions") + self.assertEqual(response.status_code, 200) + self.assertIn("Runtime and sessions", response.text) + self.assertIn("prgs-author-111-clean", response.text) + self.assertIn("prgs-author-222-stale", response.text) + self.assertIn("pid-dead", response.text) + self.assertIn("Sanctioned recovery", response.text) + self.assertNotIn("Phase 1 shell placeholder", response.text) + self.assertNotIn("child issue of #425", response.text.lower()) + + def test_api_sessions_json(self): + for path in ("/api/sessions", "/api/v1/sessions"): + response = self.client.get(path) + self.assertEqual(response.status_code, 200, path) + data = response.json() + self.assertEqual(data["view"], "runtime-sessions") + self.assertEqual(data["session_counts"]["total"], 2) + self.assertEqual(data["session_counts"]["stale"], 1) + self.assertTrue(data["read_only"]) + self.assertEqual(data["mutations"], []) + + def test_nav_marks_sessions_live(self): + sessions_items = [ + item for item in iter_nav_items() if item.href == "/sessions" + ] + self.assertEqual(len(sessions_items), 1) + self.assertEqual(sessions_items[0].status, "live") + self.assertNotIn("/sessions", STUB_PAGES) + # Home page should not mark Sessions as stub. + home = self.client.get("/") + self.assertEqual(home.status_code, 200) + self.assertIn('href="/sessions"', home.text) + # Stub marker only appears next to remaining stub destinations. + self.assertNotIn( + 'href="/sessions">Sessions (stub)', + home.text, + ) + + +if __name__ == "__main__": + unittest.main() diff --git a/webui/app.py b/webui/app.py index cedcef1..560ec75 100644 --- a/webui/app.py +++ b/webui/app.py @@ -48,6 +48,11 @@ from webui.worktree_scanner import load_hygiene_snapshot, snapshot_to_dict as wo 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.session_loader import ( + load_session_view_snapshot, + snapshot_to_dict as session_view_snapshot_to_dict, +) +from webui.session_views import render_sessions_page from webui.inventory import ( SECTION_NAMES as _INVENTORY_SECTIONS, load_inventory_snapshot, @@ -87,6 +92,7 @@ _LEGACY_PAGES = ( ("/projects", "Projects", "registry and onboarding (#427)"), ("/prompts", "Prompts", "canonical workflow prompt library (#428)"), ("/runtime", "Runtime", "MCP health and stale-runtime detection (#430)"), + ("/sessions", "Sessions", "runtime and session view (#641)"), ("/audit", "Audit", "final-report paste and validator preview (#431)"), ("/worktrees", "Worktrees", "branch hygiene dashboard (#432)"), ("/leases", "Leases", "collision and lease visibility (#433)"), @@ -325,6 +331,17 @@ async def api_runtime(_request: Request) -> JSONResponse: return JSONResponse(runtime_snapshot_to_dict(load_runtime_snapshot())) +async def sessions(_request: Request) -> HTMLResponse: + """Runtime and session view (#641) — read-only composition of health + inventory.""" + snapshot = load_session_view_snapshot() + return HTMLResponse(render_sessions_page(snapshot)) + + +async def api_sessions(_request: Request) -> JSONResponse: + """JSON export for the runtime/session view (#641).""" + return JSONResponse(session_view_snapshot_to_dict(load_session_view_snapshot())) + + async def _parse_audit_form(request: Request) -> tuple[str, str | None]: if request.method == "GET": return "", None @@ -764,6 +781,9 @@ def create_app(*, bind_host: str | None = None) -> Starlette: Route("/api/prompts", api_prompts, methods=["GET"]), Route("/runtime", runtime, methods=["GET"]), Route("/api/runtime", api_runtime, methods=["GET"]), + Route("/sessions", sessions, methods=["GET"]), + Route("/api/sessions", api_sessions, methods=["GET"]), + Route("/api/v1/sessions", api_sessions, methods=["GET"]), Route("/api/v1/timeline", api_v1_timeline, methods=["GET"]), Route("/analytics", analytics, methods=["GET"]), Route("/api/analytics", api_v1_analytics, methods=["GET"]), diff --git a/webui/nav.py b/webui/nav.py index 129b2a4..da9f763 100644 --- a/webui/nav.py +++ b/webui/nav.py @@ -48,7 +48,7 @@ NAV_GROUPS: tuple[NavGroup, ...] = ( )), NavGroup("Runtime/Sessions", ( NavItem("/runtime", "Runtime health"), - NavItem("/sessions", "Sessions", "stub"), + NavItem("/sessions", "Sessions"), )), NavGroup("Projects", ( NavItem("/projects", "Projects"), @@ -76,11 +76,6 @@ NAV_GROUPS: tuple[NavGroup, ...] = ( # issues of epic #631. Each maps a path to (title, description). Routes are # registered so nav links resolve to a graceful, read-only stub page. STUB_PAGES: dict[str, tuple[str, str]] = { - "/sessions": ( - "Sessions", - "Active session, capability, and role inventory. Backed by the unified " - "inventory API (#636) once it lands.", - ), "/inventory": ( "Inventory", "Unified sessions, leases, locks, namespaces, and worktree inventory. " diff --git a/webui/runtime_views.py b/webui/runtime_views.py index b057248..18ac5b4 100644 --- a/webui/runtime_views.py +++ b/webui/runtime_views.py @@ -88,5 +88,7 @@ def render_runtime_page(snapshot: RuntimeSnapshot) -> str: "

MVP is read-only — restart MCP servers from your IDE/operator " "workflow. Related issue: #420. Guidance: " f"{html.escape(snapshot.restart_guidance)}

" - "

This page does not expose tokens or perform MCP restarts.

" + "

This page does not expose tokens or perform MCP restarts. " + "Correlated sessions, worktree bindings, and contamination markers: " + "/sessions (#641).

" ) \ No newline at end of file diff --git a/webui/session_loader.py b/webui/session_loader.py new file mode 100644 index 0000000..8838d92 --- /dev/null +++ b/webui/session_loader.py @@ -0,0 +1,428 @@ +"""Compose runtime health + inventory into a sessions/runtime view (#641). + +Phase 1 is read-only. It correlates namespaces, sessions, capabilities, +worktree bindings, lease ownership, stale flags, and contamination markers +when they are detectable on disk (#630 / #671). It never restarts, kills, or +takes over a session. + +Sources: + +* :mod:`webui.runtime_health` — profile, role, stale runtime, shell health. +* :mod:`webui.inventory` — sessions, leases, locks, worktrees, namespaces + and collision signals from the control-plane DB + filesystem. +* :mod:`mcp_session_state` — durable contamination markers (inspect only). + +Secrets are never read. Absolute paths are collapsed by inventory redaction. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from typing import Any, Callable + +import mcp_session_state +from webui.inventory import ( + InventorySnapshot, + load_inventory_snapshot, + snapshot_to_dict as inventory_snapshot_to_dict, +) +from webui.runtime_health import ( + RuntimeSnapshot, + load_runtime_snapshot, + snapshot_to_dict as runtime_snapshot_to_dict, +) + +# Sanctioned recovery pointers only — never pkill / killall (#630). +SANCTIONED_RECOVERY_DOCS: tuple[dict[str, str], ...] = ( + { + "label": "MCP namespace EOF recovery (reconnect only)", + "path": "docs/mcp-namespace-eof-recovery.md", + "note": "IDE/client reconnect or operator-owned restart; never kill daemons.", + }, + { + "label": "MCP namespace health", + "path": "docs/mcp-namespace-health.md", + "note": "client_namespace probe proves namespace health.", + }, + { + "label": "Restart path inventory", + "path": "docs/mcp-restart-path-inventory.md", + "note": "Catalog of sanctioned reconnect/restart paths.", + }, + { + "label": "Local web UI recovery", + "path": "docs/webui-local-dev.md", + "note": "Operator console start and documented recovery sequence.", + }, +) + +_CONTAMINATION_KINDS: tuple[str, ...] = ( + mcp_session_state.KIND_RUNTIME_RECOVERY_CONTAMINATION, + mcp_session_state.KIND_STABLE_BRANCH_CONTAMINATION, +) + + +@dataclass(frozen=True) +class ContaminationMarker: + """A detectable durable contamination marker (audit-safe summary).""" + + kind: str + on_disk: bool + has_payload: bool + summary: str + reason_class: str | None = None + session_id: str | None = None + role: str | None = None + command_summary: str | None = None + cleared: bool = False + + def to_dict(self) -> dict[str, Any]: + return { + "kind": self.kind, + "on_disk": self.on_disk, + "has_payload": self.has_payload, + "summary": self.summary, + "reason_class": self.reason_class, + "session_id": self.session_id, + "role": self.role, + "command_summary": self.command_summary, + "cleared": self.cleared, + "active": self.on_disk and self.has_payload and not self.cleared, + } + + +@dataclass(frozen=True) +class SessionRow: + """One correlated session row for the sessions table.""" + + session_id: str + role: str | None + profile: str | None + namespace: str | None + pid: int | None + pid_alive: bool | None + status: str | None + started_at: str | None + last_heartbeat_at: str | None + lease_ids: tuple[str, ...] = () + work_refs: tuple[str, ...] = () + worktree_paths: tuple[str, ...] = () + stale_flags: tuple[str, ...] = () + contamination_flags: tuple[str, ...] = () + + def to_dict(self) -> dict[str, Any]: + return { + "session_id": self.session_id, + "role": self.role, + "profile": self.profile, + "namespace": self.namespace, + "pid": self.pid, + "pid_alive": self.pid_alive, + "status": self.status, + "started_at": self.started_at, + "last_heartbeat_at": self.last_heartbeat_at, + "lease_ids": list(self.lease_ids), + "work_refs": list(self.work_refs), + "worktree_paths": list(self.worktree_paths), + "stale_flags": list(self.stale_flags), + "contamination_flags": list(self.contamination_flags), + "is_stale": bool(self.stale_flags), + "is_contaminated": bool(self.contamination_flags), + } + + +@dataclass(frozen=True) +class SessionViewSnapshot: + """Composed runtime + session inventory view (#641).""" + + runtime: RuntimeSnapshot + inventory: InventorySnapshot + sessions: tuple[SessionRow, ...] + contamination_markers: tuple[ContaminationMarker, ...] + recovery_docs: tuple[dict[str, str], ...] = SANCTIONED_RECOVERY_DOCS + fetch_error: str | None = None + + @property + def stale_session_count(self) -> int: + return sum(1 for row in self.sessions if row.stale_flags) + + @property + def contaminated_session_count(self) -> int: + return sum(1 for row in self.sessions if row.contamination_flags) + + @property + def active_contamination(self) -> tuple[ContaminationMarker, ...]: + return tuple(m for m in self.contamination_markers if m.to_dict()["active"]) + + +def _inspect_contamination( + kind: str, + *, + remote: str | None, + inspect: Callable[..., dict[str, Any]] | None = None, + load: Callable[..., dict[str, Any] | None] | None = None, +) -> ContaminationMarker: + """Inspect one contamination kind; never raises into the page render path.""" + inspect_fn = inspect or mcp_session_state.inspect_state_envelope + load_fn = load or mcp_session_state.load_state + try: + envelope = inspect_fn(kind=kind, remote=remote) + except Exception as exc: # noqa: BLE001 — fail soft for the dashboard + return ContaminationMarker( + kind=kind, + on_disk=False, + has_payload=False, + summary=f"contamination inspect failed: {type(exc).__name__}", + ) + + reason_class = None + session_id = None + role = None + command_summary = None + cleared = False + summary = str(envelope.get("summary") or "") + + if envelope.get("on_disk") and envelope.get("has_payload"): + try: + payload = load_fn(kind=kind, remote=remote) or {} + except Exception: # noqa: BLE001 + payload = {} + if isinstance(payload, dict): + reason_class = payload.get("reason_class") + session_id = payload.get("session_id") + role = payload.get("role") + command_summary = payload.get("command_summary") or payload.get("detail") + cleared = bool(payload.get("cleared_by_reconciler")) + if not summary: + summary = ( + f"{kind}: {reason_class or 'present'}" + + (" (cleared)" if cleared else "") + ) + + return ContaminationMarker( + kind=kind, + on_disk=bool(envelope.get("on_disk")), + has_payload=bool(envelope.get("has_payload")), + summary=summary or f"{kind}: not present", + reason_class=str(reason_class) if reason_class else None, + session_id=str(session_id) if session_id else None, + role=str(role) if role else None, + command_summary=str(command_summary) if command_summary else None, + cleared=cleared, + ) + + +def _load_contamination_markers( + *, + remote: str | None, + inspect: Callable[..., dict[str, Any]] | None = None, + load: Callable[..., dict[str, Any] | None] | None = None, +) -> tuple[ContaminationMarker, ...]: + return tuple( + _inspect_contamination(kind, remote=remote, inspect=inspect, load=load) + for kind in _CONTAMINATION_KINDS + ) + + +def _build_session_rows( + inventory: InventorySnapshot, + contamination: tuple[ContaminationMarker, ...], +) -> tuple[SessionRow, ...]: + sessions_section = inventory.section("sessions") + leases_section = inventory.section("leases") + locks_section = inventory.section("locks") + + leases_by_session: dict[str, list[dict[str, Any]]] = {} + for lease in (leases_section.items if leases_section else ()): + sid = str(lease.get("session_id") or "") + if sid: + leases_by_session.setdefault(sid, []).append(lease) + + locks_by_session_hint: dict[str, list[dict[str, Any]]] = {} + for lock in (locks_section.items if locks_section else ()): + # Locks carry claimant profile/username, not control-plane session ids. + # Correlate later by matching lease work_number ↔ lock issue_number. + pass + + active_markers = [m for m in contamination if m.to_dict()["active"]] + marker_session_ids = { + m.session_id for m in active_markers if m.session_id + } + + rows: list[SessionRow] = [] + for raw in sessions_section.items if sessions_section else (): + sid = str(raw.get("session_id") or "") + if not sid: + continue + session_leases = leases_by_session.get(sid, []) + lease_ids = tuple( + str(lease["lease_id"]) + for lease in session_leases + if lease.get("lease_id") + ) + work_refs: list[str] = [] + work_numbers: list[int] = [] + for lease in session_leases: + kind = lease.get("work_kind") + number = lease.get("work_number") + if kind and number is not None: + work_refs.append(f"{kind}#{number}") + try: + work_numbers.append(int(number)) + except (TypeError, ValueError): + pass + + worktree_paths: list[str] = [] + for lock in (locks_section.items if locks_section else ()): + try: + issue_no = int(lock.get("issue_number")) + except (TypeError, ValueError): + continue + if issue_no in work_numbers and lock.get("worktree_path"): + worktree_paths.append(str(lock["worktree_path"])) + + stale_flags: list[str] = [] + if raw.get("pid_alive") is False: + stale_flags.append("pid-dead") + status = str(raw.get("status") or "").lower() + if status and status not in {"active", "alive", "running", "ok"}: + stale_flags.append(f"status:{status}") + for lease in session_leases: + if lease.get("expired") is True: + stale_flags.append("lease-expired") + if str(lease.get("status") or "").lower() == "active" and lease.get( + "expired" + ) is True: + stale_flags.append("active-lease-past-expiry") + + contamination_flags: list[str] = [] + if sid in marker_session_ids: + for marker in active_markers: + if marker.session_id == sid: + contamination_flags.append(marker.kind) + # Process-wide contamination with no session binding still surfaces + # against every live session so it cannot be silent (#630). + for marker in active_markers: + if not marker.session_id and marker.kind not in contamination_flags: + contamination_flags.append(f"{marker.kind}:process-wide") + + rows.append( + SessionRow( + session_id=sid, + role=raw.get("role"), + profile=raw.get("profile"), + namespace=raw.get("namespace"), + pid=raw.get("pid") if isinstance(raw.get("pid"), int) else None, + pid_alive=raw.get("pid_alive") + if isinstance(raw.get("pid_alive"), bool) + else None, + status=raw.get("status"), + started_at=raw.get("started_at"), + last_heartbeat_at=raw.get("last_heartbeat_at"), + lease_ids=lease_ids, + work_refs=tuple(work_refs), + worktree_paths=tuple(worktree_paths), + stale_flags=tuple(dict.fromkeys(stale_flags)), + contamination_flags=tuple(dict.fromkeys(contamination_flags)), + ) + ) + + # Silence unused variable for the locks_by_session_hint placeholder path. + _ = locks_by_session_hint + return tuple(rows) + + +def load_session_view_snapshot( + *, + load_runtime: Callable[..., RuntimeSnapshot] | None = None, + load_inventory: Callable[..., InventorySnapshot] | None = None, + inspect_contamination: Callable[..., dict[str, Any]] | None = None, + load_contamination_payload: Callable[..., dict[str, Any] | None] | None = None, +) -> SessionViewSnapshot: + """Build the composed sessions/runtime view. Fail-soft on partial sources.""" + runtime_loader = load_runtime or load_runtime_snapshot + inventory_loader = load_inventory or load_inventory_snapshot + fetch_error: str | None = None + + try: + runtime = runtime_loader() + except Exception as exc: # noqa: BLE001 + fetch_error = f"runtime snapshot failed: {type(exc).__name__}: {exc}" + # Minimal placeholder so the page still renders inventory + recovery. + from webui.runtime_health import RuntimeSnapshot as _RS + + runtime = _RS( + project_id="unknown", + repo_root="", + remote="", + host="", + profile_name="unknown", + role_kind="unknown", + config_model="unknown", + profile_mode="unknown", + profile_source="unknown", + authenticated_username=None, + identity_error=str(exc), + repo_sha=None, + remote_master_sha=None, + commits_behind_master=None, + stale_runtime_warning=None, + shell_health={}, + workflow_hashes=(), + schema_hashes=(), + restart_guidance="docs/mcp-namespace-eof-recovery.md", + fetch_error=str(exc), + ) + + try: + inventory = inventory_loader() + except Exception as exc: # noqa: BLE001 + msg = f"inventory snapshot failed: {type(exc).__name__}: {exc}" + fetch_error = f"{fetch_error}; {msg}" if fetch_error else msg + inventory = load_inventory_snapshot( + db_path="/nonexistent-for-fail-soft", + lock_dir="/nonexistent-for-fail-soft", + ) + + remote = getattr(runtime, "remote", None) + contamination = _load_contamination_markers( + remote=remote, + inspect=inspect_contamination, + load=load_contamination_payload, + ) + sessions = _build_session_rows(inventory, contamination) + return SessionViewSnapshot( + runtime=runtime, + inventory=inventory, + sessions=sessions, + contamination_markers=contamination, + fetch_error=fetch_error, + ) + + +def snapshot_to_dict(snapshot: SessionViewSnapshot) -> dict[str, Any]: + """JSON export for ``/api/sessions`` (read-only).""" + return { + "api_version": "v1", + "view": "runtime-sessions", + "issue": 641, + "fetch_error": snapshot.fetch_error, + "runtime": runtime_snapshot_to_dict(snapshot.runtime), + "inventory": inventory_snapshot_to_dict(snapshot.inventory), + "sessions": [row.to_dict() for row in snapshot.sessions], + "session_counts": { + "total": len(snapshot.sessions), + "stale": snapshot.stale_session_count, + "contaminated": snapshot.contaminated_session_count, + }, + "contamination_markers": [ + marker.to_dict() for marker in snapshot.contamination_markers + ], + "active_contamination": [ + marker.to_dict() for marker in snapshot.active_contamination + ], + "recovery_docs": [dict(doc) for doc in snapshot.recovery_docs], + "read_only": True, + "phase": 1, + "mutations": [], + } diff --git a/webui/session_views.py b/webui/session_views.py new file mode 100644 index 0000000..7c0408e --- /dev/null +++ b/webui/session_views.py @@ -0,0 +1,344 @@ +"""HTML views for the Runtime and session view (Phase 1, #641). + +Read-only composition of runtime health (#430) and inventory sessions / +namespaces / worktrees (#636). Surfaces stale and contamination indicators +when detectable. Recovery links point only at sanctioned reconnect/restart +docs — never at manual process kill (#630). +""" + +from __future__ import annotations + +from html import escape +from typing import Sequence + +from webui.layout import render_page +from webui.session_loader import ( + ContaminationMarker, + SessionRow, + SessionViewSnapshot, +) + + +def _badge(text: str, css: str) -> str: + return f'{escape(text)}' + + +def _flags(flags: Sequence[str], *, css: str) -> str: + if not flags: + return '—' + return " ".join(_badge(flag, css) for flag in flags) + + +def _runtime_banner(snapshot: SessionViewSnapshot) -> str: + runtime = snapshot.runtime + stale = runtime.stale_runtime_warning + stale_html = "" + if stale: + stale_html = ( + f'
' + f"Stale runtime: {escape(stale)}
" + ) + identity = runtime.authenticated_username or "unresolved" + if runtime.identity_error: + identity = f"unresolved ({runtime.identity_error})" + + return f"""
+

Runtime context

+ + + + + + + + + + + + + + + + +
Profile{escape(runtime.profile_name)}
Role kind{escape(runtime.role_kind)}
Identity{escape(str(identity))}
Remote / host{escape(runtime.remote)} · {escape(runtime.host)}
Local HEAD{escape(runtime.repo_sha or "unknown")}
Remote master{escape(runtime.remote_master_sha or "unknown")}
Commits behind{escape(str(runtime.commits_behind_master if runtime.commits_behind_master is not None else "unknown"))}
+

Full runtime detail: /runtime · + Inventory API: /api/v1/inventory

+ {stale_html} +
""" + + +def _summary_bar(snapshot: SessionViewSnapshot) -> str: + total = len(snapshot.sessions) + stale = snapshot.stale_session_count + contaminated = snapshot.contaminated_session_count + active_markers = len(snapshot.active_contamination) + inv_status = snapshot.inventory.status + return f"""
+
Sessions: {total}
+
Stale: {stale}
+
Contaminated: {contaminated}
+
Active markers: {active_markers}
+
Inventory: {escape(inv_status)}
+
""" + + +def _render_session_row(row: SessionRow) -> str: + pid = "—" if row.pid is None else str(row.pid) + pid_alive = "—" if row.pid_alive is None else ("alive" if row.pid_alive else "dead") + pid_css = ( + "badge-health-ok" + if row.pid_alive is True + else ("badge-blocked" if row.pid_alive is False else "badge-health-skipped") + ) + leases = ( + ", ".join(f"{escape(lid)}" for lid in row.lease_ids) + if row.lease_ids + else 'none' + ) + work = ( + ", ".join(escape(ref) for ref in row.work_refs) + if row.work_refs + else '—' + ) + worktrees = ( + "
".join(f"{escape(path)}" for path in row.worktree_paths) + if row.worktree_paths + else 'unbound' + ) + return f""" + {escape(row.session_id)} + +
{escape(str(row.role or "—"))} / {escape(str(row.profile or "—"))}
+
ns: {escape(str(row.namespace or "—"))}
+ + + {escape(pid)} + {_badge(pid_alive, pid_css)} + + {escape(str(row.status or "—"))}
{escape(str(row.last_heartbeat_at or ""))}
+ {leases}
{work}
+ {worktrees} + {_flags(row.stale_flags, css="badge-stale")} + {_flags(row.contamination_flags, css="badge-blocked")} +""" + + +def _sessions_table(rows: Sequence[SessionRow]) -> str: + if not rows: + return ( + '

No control-plane sessions recorded. Inventory may ' + "be unavailable, or no MCP workers have registered yet.

" + ) + body = "".join(_render_session_row(row) for row in rows) + return f""" + + + + + + + + + + + + + + {body} + +
SessionRole / profile / namespacePIDStatusLeases / workWorktree bindingStaleContamination
""" + + +def _namespaces_section(snapshot: SessionViewSnapshot) -> str: + section = snapshot.inventory.section("namespaces") + if section is None: + return ( + '

Namespaces

' + '

Namespaces section not loaded.

' + ) + if not section.ok: + return f"""
+

Namespaces {_badge(section.status, "badge-health-degraded")}

+

{escape(section.reason or "unavailable")}

+
""" + + rows = [] + for item in section.items: + caps = item.get("capability_summary") or {} + cap_bits = ", ".join( + name for name, ok in sorted(caps.items()) if ok + ) or "none" + rows.append( + "" + f"{escape(str(item.get('mcp_namespace') or '—'))}" + f"{escape(str(item.get('profile_name') or '—'))}" + f"{escape(str(item.get('role') or '—'))}" + f"{escape(cap_bits)}" + f"{'yes' if item.get('active') else 'no'}" + "" + ) + reason = ( + f'

{escape(section.reason)}

' + if section.reason + else "" + ) + return f"""
+

Namespaces / capabilities

+ {reason} + + + + + + + + + + + + {"".join(rows) if rows else ''} + +
NamespaceProfileRoleCapabilitiesActive in process
No namespace rows.
+
""" + + +def _worktrees_section(snapshot: SessionViewSnapshot) -> str: + section = snapshot.inventory.section("worktrees") + if section is None: + return "" + if not section.ok and not section.items: + return f"""
+

Worktrees {_badge(section.status, "badge-health-degraded")}

+

{escape(section.reason or "unavailable")}

+
""" + + rows = [] + for item in section.items[:50]: + rows.append( + "" + f"{escape(str(item.get('rel_path') or item.get('path') or '—'))}" + f"{escape(str(item.get('branch') or '—'))}" + f"{escape(str(item.get('classification') or '—'))}" + f"{'yes' if item.get('registered_worktree') else 'no'}" + f"{'dirty' if item.get('dirty') else 'clean'}" + "" + ) + more = "" + if len(section.items) > 50: + more = f'

Showing 50 of {len(section.items)}. Full list: /worktrees.

' + return f"""
+

Worktree bindings

+

Registered issue worktrees under branches/. Hygiene detail: /worktrees.

+ + + + + + + + + + + + {"".join(rows) if rows else ''} + +
PathBranchClassificationRegisteredState
No worktrees recorded.
+ {more} +
""" + + +def _contamination_section(markers: Sequence[ContaminationMarker]) -> str: + if not markers: + return ( + '

Contamination markers

' + '

No contamination kinds inspected.

' + ) + rows = [] + for marker in markers: + active = marker.to_dict()["active"] + status = "ACTIVE" if active else ("cleared" if marker.cleared else "absent") + css = "badge-blocked" if active else "badge-health-ok" + rows.append( + "" + f"{escape(marker.kind)}" + f"{_badge(status, css)}" + f"{escape(marker.reason_class or '—')}" + f"{escape(marker.session_id or '—')}" + f"{escape(marker.command_summary or marker.summary)}" + "" + ) + return f"""
+

Contamination markers (#630 / #671)

+

Durable markers only — never silent when present. Clearance is reconciler-only.

+ + + + + + + + + + + + {"".join(rows)} + +
KindStateReason classSessionSummary
+
""" + + +def _recovery_section(snapshot: SessionViewSnapshot) -> str: + items = [] + for doc in snapshot.recovery_docs: + items.append( + "
  • " + f"{escape(doc['path'])} — " + f"{escape(doc['label'])}: {escape(doc['note'])}" + "
    • " + ) + return f"""
    +

    Sanctioned recovery (read-only)

    +

    This view does not restart, kill, or take over sessions. + Manual pkill / kill of MCP daemons is contamination (#630), not recovery.

    + +
    """ + + +def render_sessions_page(snapshot: SessionViewSnapshot) -> str: + """Render the full HTML body for the runtime/session view.""" + error_block = "" + if snapshot.fetch_error: + error_block = ( + f'
    Partial load: ' + f"{escape(snapshot.fetch_error)}
    " + ) + if snapshot.runtime.fetch_error: + error_block += ( + f'
    Runtime note: ' + f"{escape(snapshot.runtime.fetch_error)}
    " + ) + + body = f""" +{error_block} +{_runtime_banner(snapshot)} +{_summary_bar(snapshot)} + +
    +

    Sessions

    +

    Control-plane sessions correlated with leases and worktree bindings. + Stale and contamination flags are fail-soft: absence of a marker is not proof of cleanliness when inventory is degraded.

    + {_sessions_table(snapshot.sessions)} +
    + +{_namespaces_section(snapshot)} +{_worktrees_section(snapshot)} +{_contamination_section(snapshot.contamination_markers)} +{_recovery_section(snapshot)} +""" + return render_page(title="Sessions", body_html=f"""

    Runtime and sessions

    +

    Phase 1 read-only view (#641). Combines runtime health (#430) with +unified inventory sessions/namespaces/worktrees (#636). No restart or session-takeover controls.

    +{body}""") diff --git a/webui/system_health_views.py b/webui/system_health_views.py index e7ba492..c0474c7 100644 --- a/webui/system_health_views.py +++ b/webui/system_health_views.py @@ -278,8 +278,10 @@ def _recovery_card() -> str: "controls arrive in Phase 2 (#642); until then recovery runs through " "the sanctioned client reconnect / operator restart path.

    " "