feat(webui): Runtime and session view (Phase 1) (Closes #641)
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) <[email protected]>
This commit is contained in:
Claude Opus 4.8
@@ -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"]),
|
||||
|
||||
+1
-6
@@ -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. "
|
||||
|
||||
@@ -88,5 +88,7 @@ def render_runtime_page(snapshot: RuntimeSnapshot) -> str:
|
||||
"<p class='muted'>MVP is read-only — restart MCP servers from your IDE/operator "
|
||||
"workflow. Related issue: <code>#420</code>. Guidance: "
|
||||
f"<code>{html.escape(snapshot.restart_guidance)}</code></p>"
|
||||
"<p class='muted'>This page does not expose tokens or perform MCP restarts.</p>"
|
||||
"<p class='muted'>This page does not expose tokens or perform MCP restarts. "
|
||||
"Correlated sessions, worktree bindings, and contamination markers: "
|
||||
"<a href='/sessions'>/sessions</a> (#641).</p>"
|
||||
)
|
||||
@@ -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": [],
|
||||
}
|
||||
@@ -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'<span class="badge {css}">{escape(text)}</span>'
|
||||
|
||||
|
||||
def _flags(flags: Sequence[str], *, css: str) -> str:
|
||||
if not flags:
|
||||
return '<span class="muted">—</span>'
|
||||
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'<div class="health-card health-stale" style="margin-top:0.75rem;">'
|
||||
f"<strong>Stale runtime:</strong> {escape(stale)}</div>"
|
||||
)
|
||||
identity = runtime.authenticated_username or "unresolved"
|
||||
if runtime.identity_error:
|
||||
identity = f"unresolved ({runtime.identity_error})"
|
||||
|
||||
return f"""<div class="health-card">
|
||||
<h3>Runtime context</h3>
|
||||
<table class="detail">
|
||||
<tr><th>Profile</th><td><code>{escape(runtime.profile_name)}</code></td></tr>
|
||||
<tr><th>Role kind</th><td>{escape(runtime.role_kind)}</td></tr>
|
||||
<tr><th>Identity</th><td>{escape(str(identity))}</td></tr>
|
||||
<tr><th>Remote / host</th>
|
||||
<td><code>{escape(runtime.remote)}</code> · <code>{escape(runtime.host)}</code></td>
|
||||
</tr>
|
||||
<tr><th>Local HEAD</th>
|
||||
<td><code>{escape(runtime.repo_sha or "unknown")}</code></td>
|
||||
</tr>
|
||||
<tr><th>Remote master</th>
|
||||
<td><code>{escape(runtime.remote_master_sha or "unknown")}</code></td>
|
||||
</tr>
|
||||
<tr><th>Commits behind</th>
|
||||
<td>{escape(str(runtime.commits_behind_master if runtime.commits_behind_master is not None else "unknown"))}</td>
|
||||
</tr>
|
||||
</table>
|
||||
<p class="muted">Full runtime detail: <a href="/runtime">/runtime</a> ·
|
||||
Inventory API: <a href="/api/v1/inventory"><code>/api/v1/inventory</code></a></p>
|
||||
{stale_html}
|
||||
</div>"""
|
||||
|
||||
|
||||
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"""<div class="health-card" style="display:flex; flex-wrap:wrap; gap:1rem; align-items:center;">
|
||||
<div><strong>Sessions:</strong> <span class="badge badge-health-ok">{total}</span></div>
|
||||
<div><strong>Stale:</strong> <span class="badge badge-stale">{stale}</span></div>
|
||||
<div><strong>Contaminated:</strong> <span class="badge badge-blocked">{contaminated}</span></div>
|
||||
<div><strong>Active markers:</strong> <span class="badge badge-health-unproven">{active_markers}</span></div>
|
||||
<div><strong>Inventory:</strong> <span class="badge badge-health-skipped">{escape(inv_status)}</span></div>
|
||||
</div>"""
|
||||
|
||||
|
||||
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"<code>{escape(lid)}</code>" for lid in row.lease_ids)
|
||||
if row.lease_ids
|
||||
else '<span class="muted">none</span>'
|
||||
)
|
||||
work = (
|
||||
", ".join(escape(ref) for ref in row.work_refs)
|
||||
if row.work_refs
|
||||
else '<span class="muted">—</span>'
|
||||
)
|
||||
worktrees = (
|
||||
"<br>".join(f"<code>{escape(path)}</code>" for path in row.worktree_paths)
|
||||
if row.worktree_paths
|
||||
else '<span class="muted">unbound</span>'
|
||||
)
|
||||
return f"""<tr>
|
||||
<td><code>{escape(row.session_id)}</code></td>
|
||||
<td>
|
||||
<div><code>{escape(str(row.role or "—"))}</code> / <code>{escape(str(row.profile or "—"))}</code></div>
|
||||
<div class="muted" style="font-size:0.82rem;">ns: <code>{escape(str(row.namespace or "—"))}</code></div>
|
||||
</td>
|
||||
<td>
|
||||
<code>{escape(pid)}</code>
|
||||
{_badge(pid_alive, pid_css)}
|
||||
</td>
|
||||
<td>{escape(str(row.status or "—"))}<div class="muted" style="font-size:0.82rem;">{escape(str(row.last_heartbeat_at or ""))}</div></td>
|
||||
<td>{leases}<div class="muted" style="font-size:0.82rem; margin-top:0.2rem;">{work}</div></td>
|
||||
<td>{worktrees}</td>
|
||||
<td>{_flags(row.stale_flags, css="badge-stale")}</td>
|
||||
<td>{_flags(row.contamination_flags, css="badge-blocked")}</td>
|
||||
</tr>"""
|
||||
|
||||
|
||||
def _sessions_table(rows: Sequence[SessionRow]) -> str:
|
||||
if not rows:
|
||||
return (
|
||||
'<p class="muted">No control-plane sessions recorded. Inventory may '
|
||||
"be unavailable, or no MCP workers have registered yet.</p>"
|
||||
)
|
||||
body = "".join(_render_session_row(row) for row in rows)
|
||||
return f"""<table class="registry">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Session</th>
|
||||
<th>Role / profile / namespace</th>
|
||||
<th>PID</th>
|
||||
<th>Status</th>
|
||||
<th>Leases / work</th>
|
||||
<th>Worktree binding</th>
|
||||
<th>Stale</th>
|
||||
<th>Contamination</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{body}
|
||||
</tbody>
|
||||
</table>"""
|
||||
|
||||
|
||||
def _namespaces_section(snapshot: SessionViewSnapshot) -> str:
|
||||
section = snapshot.inventory.section("namespaces")
|
||||
if section is None:
|
||||
return (
|
||||
'<div class="prompt-card"><h3>Namespaces</h3>'
|
||||
'<p class="muted">Namespaces section not loaded.</p></div>'
|
||||
)
|
||||
if not section.ok:
|
||||
return f"""<div class="prompt-card">
|
||||
<h3>Namespaces {_badge(section.status, "badge-health-degraded")}</h3>
|
||||
<p class="muted">{escape(section.reason or "unavailable")}</p>
|
||||
</div>"""
|
||||
|
||||
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(
|
||||
"<tr>"
|
||||
f"<td><code>{escape(str(item.get('mcp_namespace') or '—'))}</code></td>"
|
||||
f"<td><code>{escape(str(item.get('profile_name') or '—'))}</code></td>"
|
||||
f"<td>{escape(str(item.get('role') or '—'))}</td>"
|
||||
f"<td>{escape(cap_bits)}</td>"
|
||||
f"<td>{'yes' if item.get('active') else 'no'}</td>"
|
||||
"</tr>"
|
||||
)
|
||||
reason = (
|
||||
f'<p class="muted">{escape(section.reason)}</p>'
|
||||
if section.reason
|
||||
else ""
|
||||
)
|
||||
return f"""<div class="prompt-card">
|
||||
<h3>Namespaces / capabilities</h3>
|
||||
{reason}
|
||||
<table class="registry">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Namespace</th>
|
||||
<th>Profile</th>
|
||||
<th>Role</th>
|
||||
<th>Capabilities</th>
|
||||
<th>Active in process</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{"".join(rows) if rows else '<tr><td colspan="5" class="muted">No namespace rows.</td></tr>'}
|
||||
</tbody>
|
||||
</table>
|
||||
</div>"""
|
||||
|
||||
|
||||
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"""<div class="prompt-card">
|
||||
<h3>Worktrees {_badge(section.status, "badge-health-degraded")}</h3>
|
||||
<p class="muted">{escape(section.reason or "unavailable")}</p>
|
||||
</div>"""
|
||||
|
||||
rows = []
|
||||
for item in section.items[:50]:
|
||||
rows.append(
|
||||
"<tr>"
|
||||
f"<td><code>{escape(str(item.get('rel_path') or item.get('path') or '—'))}</code></td>"
|
||||
f"<td><code>{escape(str(item.get('branch') or '—'))}</code></td>"
|
||||
f"<td>{escape(str(item.get('classification') or '—'))}</td>"
|
||||
f"<td>{'yes' if item.get('registered_worktree') else 'no'}</td>"
|
||||
f"<td>{'dirty' if item.get('dirty') else 'clean'}</td>"
|
||||
"</tr>"
|
||||
)
|
||||
more = ""
|
||||
if len(section.items) > 50:
|
||||
more = f'<p class="muted">Showing 50 of {len(section.items)}. Full list: <a href="/worktrees">/worktrees</a>.</p>'
|
||||
return f"""<div class="prompt-card">
|
||||
<h3>Worktree bindings</h3>
|
||||
<p class="muted">Registered issue worktrees under <code>branches/</code>. Hygiene detail: <a href="/worktrees">/worktrees</a>.</p>
|
||||
<table class="registry">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Path</th>
|
||||
<th>Branch</th>
|
||||
<th>Classification</th>
|
||||
<th>Registered</th>
|
||||
<th>State</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{"".join(rows) if rows else '<tr><td colspan="5" class="muted">No worktrees recorded.</td></tr>'}
|
||||
</tbody>
|
||||
</table>
|
||||
{more}
|
||||
</div>"""
|
||||
|
||||
|
||||
def _contamination_section(markers: Sequence[ContaminationMarker]) -> str:
|
||||
if not markers:
|
||||
return (
|
||||
'<div class="prompt-card"><h3>Contamination markers</h3>'
|
||||
'<p class="muted">No contamination kinds inspected.</p></div>'
|
||||
)
|
||||
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(
|
||||
"<tr>"
|
||||
f"<td><code>{escape(marker.kind)}</code></td>"
|
||||
f"<td>{_badge(status, css)}</td>"
|
||||
f"<td>{escape(marker.reason_class or '—')}</td>"
|
||||
f"<td><code>{escape(marker.session_id or '—')}</code></td>"
|
||||
f"<td>{escape(marker.command_summary or marker.summary)}</td>"
|
||||
"</tr>"
|
||||
)
|
||||
return f"""<div class="prompt-card">
|
||||
<h3>Contamination markers (#630 / #671)</h3>
|
||||
<p class="muted">Durable markers only — never silent when present. Clearance is reconciler-only.</p>
|
||||
<table class="registry">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Kind</th>
|
||||
<th>State</th>
|
||||
<th>Reason class</th>
|
||||
<th>Session</th>
|
||||
<th>Summary</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{"".join(rows)}
|
||||
</tbody>
|
||||
</table>
|
||||
</div>"""
|
||||
|
||||
|
||||
def _recovery_section(snapshot: SessionViewSnapshot) -> str:
|
||||
items = []
|
||||
for doc in snapshot.recovery_docs:
|
||||
items.append(
|
||||
"<li>"
|
||||
f"<code>{escape(doc['path'])}</code> — "
|
||||
f"<strong>{escape(doc['label'])}</strong>: {escape(doc['note'])}"
|
||||
"</li>"
|
||||
)
|
||||
return f"""<div class="prompt-card">
|
||||
<h3>Sanctioned recovery (read-only)</h3>
|
||||
<p class="muted">This view does <strong>not</strong> restart, kill, or take over sessions.
|
||||
Manual <code>pkill</code> / <code>kill</code> of MCP daemons is contamination (#630), not recovery.</p>
|
||||
<ul class="reasons">
|
||||
{"".join(items)}
|
||||
<li>Prefer IDE/client reconnect (<code>/mcp reconnect</code>) or an operator-owned restart recorded in the restart inventory.</li>
|
||||
</ul>
|
||||
</div>"""
|
||||
|
||||
|
||||
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'<div class="health-card health-stale"><strong>Partial load:</strong> '
|
||||
f"{escape(snapshot.fetch_error)}</div>"
|
||||
)
|
||||
if snapshot.runtime.fetch_error:
|
||||
error_block += (
|
||||
f'<div class="health-card health-stale"><strong>Runtime note:</strong> '
|
||||
f"{escape(snapshot.runtime.fetch_error)}</div>"
|
||||
)
|
||||
|
||||
body = f"""
|
||||
{error_block}
|
||||
{_runtime_banner(snapshot)}
|
||||
{_summary_bar(snapshot)}
|
||||
|
||||
<div class="prompt-card">
|
||||
<h3>Sessions</h3>
|
||||
<p class="muted">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.</p>
|
||||
{_sessions_table(snapshot.sessions)}
|
||||
</div>
|
||||
|
||||
{_namespaces_section(snapshot)}
|
||||
{_worktrees_section(snapshot)}
|
||||
{_contamination_section(snapshot.contamination_markers)}
|
||||
{_recovery_section(snapshot)}
|
||||
"""
|
||||
return render_page(title="Sessions", body_html=f"""<h2>Runtime and sessions</h2>
|
||||
<p class="meta">Phase 1 read-only view (#641). Combines runtime health (#430) with
|
||||
unified inventory sessions/namespaces/worktrees (#636). No restart or session-takeover controls.</p>
|
||||
{body}""")
|
||||
@@ -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.</p>"
|
||||
"<ul class='reasons'>"
|
||||
"<li><a href='/runtime'>Runtime and session view</a> — active profile, "
|
||||
"workflow hashes, and shell health.</li>"
|
||||
"<li><a href='/runtime'>Runtime health</a> — active profile, workflow "
|
||||
"hashes, and shell health.</li>"
|
||||
"<li><a href='/sessions'>Runtime and sessions</a> — namespaces, session "
|
||||
"rows, worktree bindings, and contamination markers (#641).</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>"
|
||||
|
||||
Reference in New Issue
Block a user