docs(webui): document the read-only restart console surface (#667)

Records the two GET routes, what each panel consumes, and the three
properties the surface is held to: an unreadable source reports
unavailable rather than green, authorization is probed with
for_execution=True so a Phase 1 refusal is never shown as an allow, and
the control-plane database is opened mode=ro so reading status never
creates it.

Refs #655 #642 #658 #661 #662 #663 #633 #652 #653 #664

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

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,46 @@ 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.
+
+Honesty rules specific to this view:
+
+* **Ownership columns never assert absence they cannot prove.** When the
+  `leases` or `locks` section is degraded or unavailable, the Leases and
+  Worktree-binding cells render `unknown (inventory <status>)` with an
+  *authority unproven* badge instead of `none` / `unbound`, and a caveat names
+  the unreadable sections. A worktree binding is correlated through lease work
+  numbers, so it is unproven when *either* section fails to read.
+  `/api/sessions` carries the same facts as `ownership_authority_complete`,
+  `ownership_section_status`, and per-row `lease_authority` /
+  `worktree_authority`, so a JSON consumer can tell "holds none" from "could
+  not be read".
+* **Contamination text is redacted at the display boundary.** Marker payloads
+  (`command_summary`, `reason_class`, `session_id`, `role`) are
+  operator-supplied free text that does not arrive through inventory scrubbing,
+  so they pass through `webui.inventory.scrub_text`, which collapses `$HOME` and
+  redacts credential-shaped tokens and URL userinfo *anywhere* in the string.
+  The write-time redactor is a narrow denylist and is not relied on. The field
+  itself is kept — it is the `#630` evidence naming which daemon was killed.
 
 ## System-health dashboard (#639)
 

docs/webui-restart-console.md

@@ -0,0 +1,102 @@
+# Web Console: restart status, impact preview, and approval state (#667)
+
+Phase 1 of the console restart surface. It consumes the #655 coordinator
+substrate and displays it. It performs no restart, reload, drain, approval, or
+process action, and it registers no write endpoint.
+
+Issue #667's rollout is explicit — *status views first, write approval after the
+backend gates are green* — and this change delivers only the status half.
+
+## Surfaces
+
+| Path | Method | Purpose |
+|------|--------|---------|
+| `/runtime/restart` | GET | Restart status page |
+| `/api/v1/system/restart/status` | GET | Same snapshot as JSON |
+
+Both accept an optional `restart_class` query parameter (default
+`full_mcp_restart`). An unrecognised class is not an error: the coordinator
+resolves it as unknown and fails closed, and the page shows the resulting deny.
+
+Neither path accepts `POST`; a write attempt returns `405`, and a test asserts
+it.
+
+## What it shows
+
+* **Impact preview (#658)** — verdict, blast radius, affected sessions, leases,
+  critical sections, mutations, and the counts behind them, evaluated
+  `dry_run=True` against live control-plane state.
+* **Drain proof (#661)** — verification of a supplied proof: valid, clean,
+  expired, tampered, and the reasons behind a refusal.
+* **Post-restart reconcile (#662)** — the most recent completion proof, its
+  overall status, and which dimensions still require follow-up.
+* **Restart classes (#663)** — the least-privilege matrix, with *you may
+  request* and *you may execute* computed for the viewing role rather than for a
+  generic operator.
+* **Approval controls (#633)** — the authorization state of
+  `system.restart_namespace` and `system.reload_namespace`.
+* **Break-glass (#664)** — declared and marked unavailable; see below.
+
+## Three rules this surface holds itself to
+
+A status page that is wrong is worse than one that is missing, because an
+operator acts on it. Three properties are enforced by tests, and each was
+verified by reverting the guard and watching a test fail.
+
+### An unreadable source reports unavailable, never green
+
+Every source carries its own `SourceStatus`. Nothing substitutes a default,
+placeholder, or self-comparison for a reading that failed. An unreadable
+control-plane database yields `inventory_complete: false`, which the coordinator
+itself turns into a fail-closed verdict, and the page says the blast radius is
+unknown rather than showing an empty affected-sessions table.
+
+An absent drain proof is reported as absent — not as a pass. The #661 gate
+authorizes a restart only against a valid, unexpired, clean proof, so no proof
+is precisely the state that gate denies on.
+
+### Authorization is asked the way execution would ask it
+
+Every probe passes `for_execution=True`.
+
+Asked without it, an admin is `allowed` for `system.restart_namespace`. On a
+control surface that reads as a live button. Asked the way an execution attempt
+would ask, the same principal is refused `phase_not_active`, because the console
+is in Phase 1 and the action is Phase 2. This surface reports the second answer.
+
+`execution_enabled` is therefore `false` for every action and every role today,
+and a test asserts that across the whole role matrix.
+
+### The control-plane database is opened read-only
+
+`ControlPlaneDB()` creates directories and runs migrations on construction — a
+write. This surface never constructs one. It opens the sqlite file with
+`mode=ro`, exactly as `webui/inventory.py` does, and treats a missing file as
+missing authority rather than as an empty inventory.
+
+The test that protects this points at a path inside a directory that already
+exists, so a read-write `connect` would really create the file. A nested
+missing-directory path would have passed for the wrong reason.
+
+## Break-glass is declared, not offered
+
+The break-glass workflow (#664) is not available on this branch's base. The
+panel is rendered to operator-class roles as **unavailable**, naming the issue
+that tracks it. It is not silently omitted, because an operator who has been
+told a governance path exists needs to see that it is not wired here; and it is
+not rendered as a control, because there is nothing behind it.
+
+Unprivileged viewers see only a note that the surface is operator-class.
+
+## Redaction and escaping
+
+Every interpolated value passes through `_esc` (`html.escape(..., quote=True)`).
+Free-form text and anything that can carry a filesystem path additionally passes
+through `webui.inventory.scrub_text`, which redacts credential-shaped tokens
+inside a string rather than only at its start. The impact payload is passed
+through `webui.inventory.scrub` before rendering.
+
+## Linkage
+
+Parent #655 · extends #642 · consumes #658, #661, #662, #663 · RBAC #633 ·
+console #631 · vision #652 · roadmap #653 · break-glass #664.

gitea_mcp_server.py

@@ -9552,15 +9552,13 @@ def gitea_edit_pr(
     if closing:
         gate_reasons = _profile_operation_gate("gitea.pr.close")
         if gate_reasons:
-            return {
-                "success": False,
-                "performed": False,
-                "pr_number": pr_number,
-                "requested_state": "closed",
-                "required_permission": "gitea.pr.close",
-                "reasons": gate_reasons,
-                "permission_report": _permission_block_report("gitea.pr.close"),
-            }
+            return _build_operation_gate_refusal(
+                "gitea.pr.close",
+                gate_reasons,
+                pr_number=pr_number,
+                requested_state="closed",
+                required_permission="gitea.pr.close",
+            )
 
     h, o, r = _resolve(remote, host, org, repo)
     auth = _auth(h)
@@ -13823,13 +13821,17 @@ def gitea_view_issue(
 
 def _permission_block_report(required_operation: str,
                              identity: str | None = None) -> dict:
-    """Structured, LLM-safe explanation of a permission denial (#142).
+    """Structured, LLM-safe explanation of a permission denial (#142, #897).
 
     Built only after a gate has already refused; it adds guidance to the
     refusal and never widens any permission, performs network I/O, or
     raises (fail-soft: degrades to a minimal fail-closed report). Names
     configured profiles only — never auth references, tokens, endpoint
     URLs, or keychain IDs.
+
+    #897: never fabricate a missing permission when the active profile
+    already allows the operation. That path is a diagnostic defect (the
+    refusal was not a permission denial), not a cue to switch profiles.
     """
     report = {
         "requested_operation": required_operation,
@@ -13841,6 +13843,7 @@ def _permission_block_report(required_operation: str,
         "matching_configured_profiles": [],
         "runtime_switching_supported": False,
         "different_mcp_namespace_required": True,
+        "diagnostic_defect": False,
         "exact_safe_next_action": (
             "Ask the operator to fix GITEA_MCP_CONFIG/GITEA_MCP_PROFILE; "
             "the active profile could not be resolved (fail closed)."),
@@ -13855,6 +13858,32 @@ def _permission_block_report(required_operation: str,
     report["active_allowed_operations"] = (
         profile.get("allowed_operations") or [])
 
+    # #897: fail closed as a diagnostic defect when the active profile
+    # already holds the operation — callers must not invent "missing".
+    try:
+        holds, _hold_reason = gitea_config.check_operation(
+            required_operation,
+            profile.get("allowed_operations") or [],
+            profile.get("forbidden_operations") or [],
+        )
+    except Exception:
+        holds = False
+    if holds:
+        report["missing_permission"] = None
+        report["required_permission"] = required_operation
+        report["diagnostic_defect"] = True
+        report["different_mcp_namespace_required"] = False
+        report["exact_safe_next_action"] = (
+            "Diagnostic defect: the active profile already allows "
+            f"{required_operation}. This is not a permission denial — "
+            "inspect blocker_kind / reasons (stale-runtime or runtime-mode). "
+            "Do not call gitea_activate_profile or switch MCP sessions."
+        )
+        report["matching_configured_profiles"] = [
+            p for p in [profile.get("profile_name")] if p
+        ]
+        return report
+
     matching = []
     try:
         config = gitea_config.load_config() or {}
@@ -13903,6 +13932,205 @@ def _permission_block_report(required_operation: str,
     return report
 
 
+def _reason_is_stale_runtime(reason: str) -> bool:
+    """True when *reason* is a master-parity / stale-daemon refusal (#897)."""
+    r = (reason or "").lower()
+    if not r:
+        return False
+    if "stale relative to live master" in r:
+        return True
+    if "server code is stale" in r:
+        return True
+    if "daemon is stale" in r:
+        return True
+    if "started at commit" in r and "workspace master is now" in r:
+        return True
+    if "mcp server started at" in r and "stale" in r:
+        return True
+    if "restart the server to load the current capability gates" in r:
+        return True
+    if "restart/reconnect before mutating" in r:
+        return True
+    return False
+
+
+def _reason_is_runtime_mode(reason: str) -> bool:
+    """True when *reason* is a stable-control / runtime-mode refusal (#897)."""
+    r = (reason or "").lower()
+    if not r:
+        return False
+    if _reason_is_stale_runtime(reason):
+        return False
+    if "runtime mode could not be assessed" in r:
+        return True
+    if "runtime mode is" in r:
+        return True
+    if "stable control runtime" in r:
+        return True
+    if "dev-test" in r and ("runtime" in r or "production" in r):
+        return True
+    if "development worktree" in r or "dev worktree" in r:
+        return True
+    if "launched from a 'branches/" in r or "launched from a \"branches/" in r:
+        return True
+    if "process-root / active-workspace alignment" in r:
+        return True
+    if "namespace" in r and "reproof" in r:
+        return True
+    return False
+
+
+def _reason_is_permission(reason: str) -> bool:
+    """True when *reason* is a genuine profile-permission denial (#897)."""
+    r = (reason or "").lower()
+    if not r:
+        return False
+    if _reason_is_stale_runtime(reason) or _reason_is_runtime_mode(reason):
+        return False
+    if "profile could not be resolved" in r:
+        return True
+    if "profile has no configured allowed operations" in r:
+        return True
+    if "profile forbids" in r:
+        return True
+    if "profile is not allowed to" in r:
+        return True
+    if "unrecognized forbidden operation" in r:
+        return True
+    return False
+
+
+def _classify_operation_gate_reasons(reasons: list[str]) -> dict:
+    """Partition gate reasons into stale / runtime-mode / permission (#897)."""
+    stale: list[str] = []
+    runtime_mode: list[str] = []
+    permission: list[str] = []
+    other: list[str] = []
+    for reason in reasons or []:
+        if _reason_is_stale_runtime(reason):
+            stale.append(reason)
+        elif _reason_is_runtime_mode(reason):
+            runtime_mode.append(reason)
+        elif _reason_is_permission(reason):
+            permission.append(reason)
+        else:
+            other.append(reason)
+    return {
+        "stale_runtime": stale,
+        "runtime_mode": runtime_mode,
+        "permission": permission,
+        "other": other,
+    }
+
+
+def _stale_runtime_reconnect_action() -> str:
+    """Sanctioned recovery for a stale daemon — reconnect only (#685/#897)."""
+    return (
+        "Reconnect the IDE/client MCP session so the server reloads at the "
+        "current master head. Do not call gitea_activate_profile or switch "
+        "MCP role sessions — profile switching does not clear a stale daemon."
+    )
+
+
+def _build_operation_gate_refusal(
+    required_operation: str,
+    reasons: list[str],
+    **extra_fields,
+) -> dict:
+    """Structured gate refusal with typed blockers (#897).
+
+    Stale-runtime and runtime-mode refusals never attach a
+    ``permission_report`` and never recommend profile switching. True
+    permission denials still get ``permission_report``. When both apply,
+    causes are reported separately under distinct fields.
+    """
+    classified = _classify_operation_gate_reasons(reasons)
+    stale = classified["stale_runtime"]
+    runtime_mode = classified["runtime_mode"]
+    permission = classified["permission"]
+    other = classified["other"]
+
+    blocked: dict = {
+        "success": False,
+        "performed": False,
+        "reasons": list(reasons),
+        "mutation_performed": False,
+        "session_context_audit": session_ctx.mutation_context_audit_fields(),
+        "gate_reason_classes": {
+            "stale_runtime": list(stale),
+            "runtime_mode": list(runtime_mode),
+            "permission": list(permission),
+            "other": list(other),
+        },
+    }
+
+    if stale:
+        parity = _current_master_parity()
+        blocked["blocker_kind"] = "runtime_reconnect_required"
+        blocked["restart_required"] = True
+        blocked["stop_required"] = True
+        blocked["startup_head"] = parity.get("startup_head")
+        blocked["current_head"] = parity.get("current_head")
+        blocked["daemon_start_head"] = (
+            parity.get("daemon_start_head") or parity.get("startup_head")
+        )
+        blocked["local_head"] = (
+            parity.get("local_head") or parity.get("current_head")
+        )
+        blocked["live_remote_head"] = parity.get("live_remote_head")
+        blocked["live_stale"] = bool(parity.get("live_stale"))
+        blocked["live_known"] = bool(parity.get("live_known"))
+        blocked["exact_safe_next_action"] = _stale_runtime_reconnect_action()
+        if permission or other:
+            blocked["permission_block_reasons"] = list(permission) + list(other)
+            blocked["stale_runtime_reasons"] = list(stale)
+        # Never attach permission_report for a staleness refusal.
+        blocked.update(extra_fields)
+        return blocked
+
+    if runtime_mode:
+        blocked["blocker_kind"] = "runtime_mode_blocked"
+        blocked["restart_required"] = False
+        blocked["stop_required"] = True
+        blocked["exact_safe_next_action"] = (
+            "Real workflow mutations run only on the promoted stable control "
+            "runtime. Promote/reload the stable runtime; do not call "
+            "gitea_activate_profile or switch MCP role sessions to clear a "
+            "runtime-mode block."
+        )
+        if permission or other:
+            blocked["permission_block_reasons"] = list(permission) + list(other)
+            blocked["runtime_mode_reasons"] = list(runtime_mode)
+        blocked.update(extra_fields)
+        return blocked
+
+    # Pure permission (or unclassified-as-permission) denial.
+    blocked["blocker_kind"] = "permission_denied"
+    blocked["permission_report"] = _permission_block_report(required_operation)
+    blocked.update(extra_fields)
+    return blocked
+
+
+def _permission_report_for_gate_reasons(
+    required_operation: str,
+    reasons: list[str] | None,
+) -> dict | None:
+    """Attach ``permission_report`` only for true permission denials (#897).
+
+    Call sites that historically always attached a permission report after
+    ``_profile_operation_gate`` should use this so stale/runtime refusals
+    do not emit a fabricated missing-permission payload.
+    """
+    if not reasons:
+        return None
+    classified = _classify_operation_gate_reasons(reasons)
+    if classified["stale_runtime"] or classified["runtime_mode"]:
+        return None
+    if not (classified["permission"] or classified["other"]):
+        return None
+    return _permission_block_report(required_operation)
+
+
 def _role_for_operation(op: str) -> str | None:
     # Normalize op first
     try:
@@ -14079,7 +14307,7 @@ def _master_parity_block(op: str) -> list[str]:
 
 
 def _profile_operation_gate(op: str) -> list[str]:
-    """Profile permission check for a single gated operation (#126, #216, #420).
+    """Profile permission check for a single gated operation (#126, #216, #420, #897).
 
     Issue discussion comments are gated separately from the gitea.pr.*
     review/merge family: listing requires ``gitea.read``, creating requires
@@ -14092,21 +14320,26 @@ def _profile_operation_gate(op: str) -> list[str]:
     capability gate that has since been merged, and when the runtime itself is
     not the promoted stable control runtime (#615) -- a dev/test or unknown
     runtime holds production credentials but has not been promoted.
+
+    #897: collect *all* independent refusal classes (stale, runtime-mode,
+    permission) rather than short-circuiting after the first. Callers that
+    only need a boolean still treat any non-empty list as blocked; typed
+    consumers (``_build_operation_gate_refusal``) can separate causes.
     """
-    stale_reasons = _master_parity_block(op)
-    if stale_reasons:
-        return stale_reasons
-    runtime_reasons = _runtime_mode_block(op)
-    if runtime_reasons:
-        return runtime_reasons
+    reasons: list[str] = []
+    reasons.extend(_master_parity_block(op))
+    reasons.extend(_runtime_mode_block(op))
     try:
         profile = get_profile()
     except Exception as exc:
-        return [f"profile could not be resolved (fail closed): {_redact(str(exc))}"]
+        reasons.append(
+            f"profile could not be resolved (fail closed): {_redact(str(exc))}"
+        )
+        return reasons
     op_ok, op_reason = gitea_config.check_operation(
         op, profile["allowed_operations"], profile["forbidden_operations"])
     if op_ok:
-        return []
+        return reasons
 
     if _try_auto_switch_for_operation(op):
         try:
@@ -14114,17 +14347,26 @@ def _profile_operation_gate(op: str) -> list[str]:
             op_ok, op_reason = gitea_config.check_operation(
                 op, profile["allowed_operations"], profile["forbidden_operations"])
             if op_ok:
-                return []
+                return reasons
         except Exception as exc:
-            return [f"profile could not be resolved (fail closed): {_redact(str(exc))}"]
+            reasons.append(
+                f"profile could not be resolved (fail closed): {_redact(str(exc))}"
+            )
+            return reasons
 
     if op_reason == "no-allowed-operations":
-        return ["profile has no configured allowed operations (fail closed)"]
-    if op_reason == "forbidden":
-        return [f"profile forbids '{op}'"]
-    if op_reason == "invalid-forbidden-entry":
-        return ["profile has an unrecognized forbidden operation entry (fail closed)"]
-    return [f"profile is not allowed to {op}"]
+        reasons.append(
+            "profile has no configured allowed operations (fail closed)"
+        )
+    elif op_reason == "forbidden":
+        reasons.append(f"profile forbids '{op}'")
+    elif op_reason == "invalid-forbidden-entry":
+        reasons.append(
+            "profile has an unrecognized forbidden operation entry (fail closed)"
+        )
+    else:
+        reasons.append(f"profile is not allowed to {op}")
+    return reasons
 
 
 def _mutation_config_authority_block(required_operation: str) -> dict | None:
@@ -14344,10 +14586,14 @@ def _session_context_mutation_block(
 
 
 def _profile_permission_block(required_operation: str, **extra_fields) -> dict | None:
-    """Structured permission denial for gated tools (#69, #142).
+    """Structured operation-gate denial for gated tools (#69, #142, #897).
 
     Returns a block dict when the active profile forbids *required_operation*,
-    or ``None`` when the gate passes. Never performs network I/O.
+    the daemon is stale, or the runtime mode is not mutation-safe — or
+    ``None`` when the gate passes. Never performs network I/O.
+
+    #897: stale-runtime and runtime-mode refusals are typed
+    (``blocker_kind``) and never carry a ``permission_report``.
     """
     req_role = "reviewer" if any(required_operation.startswith(p) for p in (
         "gitea.pr.approve", "gitea.pr.merge", "gitea.pr.request_changes", "gitea.pr.review"
@@ -14357,15 +14603,9 @@ def _profile_permission_block(required_operation: str, **extra_fields) -> dict |
 
     reasons = _profile_operation_gate(required_operation)
     if reasons:
-        blocked = {
-            "success": False,
-            "performed": False,
-            "reasons": reasons,
-            "permission_report": _permission_block_report(required_operation),
-            "session_context_audit": session_ctx.mutation_context_audit_fields(),
-        }
-        blocked.update(extra_fields)
-        return blocked
+        return _build_operation_gate_refusal(
+            required_operation, reasons, **extra_fields
+        )
 
     auth_block = _mutation_config_authority_block(required_operation)
     if auth_block is not None:
@@ -14494,20 +14734,14 @@ def gitea_acquire_reviewer_pr_lease(
     """Acquire a per-PR reviewer lease before review/merge mutations (#407)."""
     read_block = _profile_operation_gate("gitea.read")
     if read_block:
-        return {
-            "success": False,
-            "acquired": False,
-            "reasons": read_block,
-            "permission_report": _permission_block_report("gitea.read"),
-        }
+        return _build_operation_gate_refusal(
+            "gitea.read", read_block, acquired=False
+        )
     comment_block = _profile_operation_gate("gitea.pr.comment")
     if comment_block:
-        return {
-            "success": False,
-            "acquired": False,
-            "reasons": comment_block,
-            "permission_report": _permission_block_report("gitea.pr.comment"),
-        }
+        return _build_operation_gate_refusal(
+            "gitea.pr.comment", comment_block, acquired=False
+        )
 
     # task=acquire_reviewer_pr_lease so verify_preflight_purity runs shared #604
     # anti-stomp for the declared lease-acquire mutation inventory entry.
@@ -14623,20 +14857,14 @@ def gitea_acquire_merger_pr_lease(
     """
     read_block = _profile_operation_gate("gitea.read")
     if read_block:
-        return {
-            "success": False,
-            "acquired": False,
-            "reasons": read_block,
-            "permission_report": _permission_block_report("gitea.read"),
-        }
+        return _build_operation_gate_refusal(
+            "gitea.read", read_block, acquired=False
+        )
     comment_block = _profile_operation_gate("gitea.pr.comment")
     if comment_block:
-        return {
-            "success": False,
-            "acquired": False,
-            "reasons": comment_block,
-            "permission_report": _permission_block_report("gitea.pr.comment"),
-        }
+        return _build_operation_gate_refusal(
+            "gitea.pr.comment", comment_block, acquired=False
+        )
     merge_block = _profile_operation_gate("gitea.pr.merge")
     if merge_block:
         return {
@@ -19375,14 +19603,12 @@ def gitea_update_pr_branch_by_merge(
     # Permission: author branch push / PR mutation surface.
     push_block = _profile_operation_gate("gitea.branch.push")
     if push_block:
-        return {
-            "success": False,
-            "performed": False,
-            "mutation_allowed": False,
-            "reasons": push_block,
-            "permission_report": _permission_block_report("gitea.branch.push"),
-            "role_kind": role,
-        }
+        return _build_operation_gate_refusal(
+            "gitea.branch.push",
+            push_block,
+            mutation_allowed=False,
+            role_kind=role,
+        )
 
     if role != "author":
         pre = pr_sync_status.assess_update_pr_branch_preflight(

tests/test_issue_897_permission_stale_runtime_classification.py

@@ -0,0 +1,453 @@
+"""#897: stale-runtime / runtime-mode refusals must not look like permission denials.
+
+Acceptance criteria (issue #897):
+
+* Stale-runtime and runtime-mode refusals are typed distinctly from
+  profile-permission refusals (distinct ``blocker_kind``).
+* A refusal caused by staleness or runtime mode never emits a
+  ``permission_report`` and never names a permission the active profile holds.
+* ``_permission_block_report`` verifies the active profile actually lacks the
+  operation before reporting it missing.
+* A stale-runtime refusal reports reconnect-only recovery and never recommends
+  ``gitea_activate_profile`` or an MCP session switch.
+* The blocker payload states the observed heads (parity fields).
+* Matrix across author / reviewer / merger / reconciler profiles.
+* Regression: ``gitea_create_issue`` on a stale daemon under ``prgs-author``
+  never returns ``missing_permission: gitea.issue.create``.
+"""
+from __future__ import annotations
+
+import os
+import sys
+import unittest
+from unittest.mock import patch
+
+sys.path.insert(0, str(__import__("pathlib").Path(__file__).resolve().parent.parent))
+
+import gitea_config  # noqa: E402
+import gitea_mcp_server as mcp_server  # noqa: E402
+
+SHA_START = "7af40fb5ff7debd5e9165fe97d9c7c279358e175"
+SHA_LIVE = "2f4dec832327513118f2fe92b74da25d124a01cb"
+
+ROLE_MATRIX = (
+    (
+        "prgs-author",
+        "author",
+        "gitea.issue.create",
+        [
+            "gitea.read",
+            "gitea.issue.create",
+            "gitea.issue.comment",
+            "gitea.issue.close",
+            "gitea.branch.create",
+            "gitea.branch.push",
+            "gitea.pr.create",
+            "gitea.pr.comment",
+            "gitea.repo.commit",
+        ],
+        ["gitea.pr.approve", "gitea.pr.merge", "gitea.pr.request_changes"],
+        "gitea.pr.merge",  # forbidden op for pure-permission case
+    ),
+    (
+        "prgs-reviewer",
+        "reviewer",
+        "gitea.pr.review",
+        [
+            "gitea.read",
+            "gitea.pr.review",
+            "gitea.pr.approve",
+            "gitea.pr.request_changes",
+            "gitea.pr.comment",
+            "gitea.issue.comment",
+        ],
+        ["gitea.branch.push", "gitea.pr.create"],
+        "gitea.branch.push",
+    ),
+    (
+        "prgs-merger",
+        "merger",
+        "gitea.pr.merge",
+        [
+            "gitea.read",
+            "gitea.pr.merge",
+            "gitea.pr.comment",
+            "gitea.issue.comment",
+        ],
+        ["gitea.pr.approve", "gitea.branch.push", "gitea.pr.create"],
+        "gitea.branch.push",
+    ),
+    (
+        "prgs-reconciler",
+        "reconciler",
+        "gitea.branch.delete",
+        [
+            "gitea.read",
+            "gitea.branch.delete",
+            "gitea.pr.comment",
+            "gitea.issue.comment",
+            "gitea.pr.close",
+            "gitea.issue.close",
+        ],
+        ["gitea.pr.approve", "gitea.pr.merge"],
+        "gitea.pr.merge",
+    ),
+)
+
+
+def _profile(name: str, role: str, allowed: list[str], forbidden: list[str]) -> dict:
+    return {
+        "profile_name": name,
+        "role": role,
+        "role_kind": role,
+        "allowed_operations": list(allowed),
+        "forbidden_operations": list(forbidden),
+        "identity": "test-user",
+    }
+
+
+def _config(profiles: dict) -> dict:
+    return {
+        "version": 2,
+        "profiles": {
+            name: {
+                "role": p["role"],
+                "allowed_operations": p["allowed_operations"],
+                "forbidden_operations": p["forbidden_operations"],
+            }
+            for name, p in profiles.items()
+        },
+        "rules": {"allow_runtime_switching": True},
+    }
+
+
+class Issue897Helpers(unittest.TestCase):
+    def test_classify_stale_reason_strings(self):
+        stale = (
+            f"live remote master is {SHA_LIVE[:12]} but the MCP server started "
+            f"at {SHA_START[:12]}; the daemon is stale relative to live master "
+            "-- restart/reconnect before mutating"
+        )
+        classified = mcp_server._classify_operation_gate_reasons([stale])
+        self.assertEqual(classified["stale_runtime"], [stale])
+        self.assertEqual(classified["permission"], [])
+        self.assertEqual(classified["runtime_mode"], [])
+
+    def test_classify_permission_reason(self):
+        reason = "profile is not allowed to gitea.pr.merge"
+        classified = mcp_server._classify_operation_gate_reasons([reason])
+        self.assertEqual(classified["permission"], [reason])
+        self.assertEqual(classified["stale_runtime"], [])
+
+    def test_classify_runtime_mode_reason(self):
+        reason = (
+            "runtime mode is 'dev-test' and the mutation targets the "
+            "production repository; dev/test runtimes must not mutate real "
+            "issues or PRs (ADR: stable control runtime vs dev runtime)"
+        )
+        classified = mcp_server._classify_operation_gate_reasons([reason])
+        self.assertEqual(classified["runtime_mode"], [reason])
+        self.assertEqual(classified["stale_runtime"], [])
+
+
+class Issue897PermissionBlockReport(unittest.TestCase):
+    def test_holds_op_is_diagnostic_defect_not_missing_permission(self):
+        profile = _profile(
+            "prgs-author",
+            "author",
+            ["gitea.read", "gitea.issue.create", "gitea.issue.comment"],
+            [],
+        )
+        with patch.object(mcp_server, "get_profile", return_value=profile), patch.object(
+            mcp_server.gitea_config, "load_config", return_value=_config({"prgs-author": profile})
+        ), patch.object(
+            mcp_server.gitea_config, "is_runtime_switching_enabled", return_value=True
+        ):
+            report = mcp_server._permission_block_report("gitea.issue.create")
+        self.assertTrue(report.get("diagnostic_defect"), report)
+        self.assertIsNone(report.get("missing_permission"), report)
+        action = (report.get("exact_safe_next_action") or "").lower()
+        # Must not *recommend* profile switching; mentioning the forbidden
+        # action in a "do not call" instruction is fine.
+        self.assertNotIn("call gitea_activate_profile with", action)
+        self.assertNotIn("switch to the author mcp session", action)
+        self.assertNotIn("switch to the reviewer mcp session", action)
+        self.assertIn("diagnostic defect", action)
+
+    def test_true_missing_permission_still_reports(self):
+        profile = _profile(
+            "prgs-author",
+            "author",
+            ["gitea.read", "gitea.issue.create"],
+            ["gitea.pr.merge"],
+        )
+        reviewer = _profile(
+            "prgs-reviewer",
+            "reviewer",
+            ["gitea.read", "gitea.pr.merge", "gitea.pr.approve"],
+            [],
+        )
+        with patch.object(mcp_server, "get_profile", return_value=profile), patch.object(
+            mcp_server.gitea_config,
+            "load_config",
+            return_value=_config({"prgs-author": profile, "prgs-reviewer": reviewer}),
+        ), patch.object(
+            mcp_server.gitea_config, "is_runtime_switching_enabled", return_value=True
+        ):
+            report = mcp_server._permission_block_report("gitea.pr.merge")
+        self.assertFalse(report.get("diagnostic_defect"), report)
+        self.assertEqual(report.get("missing_permission"), "gitea.pr.merge")
+        self.assertIn("prgs-reviewer", report.get("matching_configured_profiles") or [])
+
+
+class Issue897GateRefusalMatrix(unittest.TestCase):
+    def _stale_parity(self) -> dict:
+        return {
+            "in_parity": True,
+            "stale": False,
+            "restart_required": True,
+            "determinable": True,
+            "startup_head": SHA_START,
+            "current_head": SHA_START,
+            "daemon_start_head": SHA_START,
+            "local_head": SHA_START,
+            "live_remote_head": SHA_LIVE,
+            "live_known": True,
+            "live_stale": True,
+            "mutation_safe": False,
+            "reasons": [
+                f"live remote master is {SHA_LIVE[:12]} but the MCP server "
+                f"started at {SHA_START[:12]}; the daemon is stale relative "
+                "to live master -- restart/reconnect before mutating"
+            ],
+        }
+
+    def test_stale_plus_permitted_op_all_roles(self):
+        for name, role, permitted_op, allowed, forbidden, _forbidden_op in ROLE_MATRIX:
+            with self.subTest(profile=name, op=permitted_op):
+                profile = _profile(name, role, allowed, forbidden)
+                parity = self._stale_parity()
+                with patch.object(mcp_server, "get_profile", return_value=profile), patch.object(
+                    mcp_server, "_current_master_parity", return_value=parity
+                ), patch.object(
+                    mcp_server, "_master_parity_block", return_value=list(parity["reasons"])
+                ), patch.object(
+                    mcp_server, "_runtime_mode_block", return_value=[]
+                ), patch.object(
+                    mcp_server, "_ensure_matching_profile", return_value=None
+                ), patch.object(
+                    mcp_server.session_ctx,
+                    "mutation_context_audit_fields",
+                    return_value={"session_profile": name},
+                ):
+                    blocked = mcp_server._profile_permission_block(permitted_op)
+                self.assertIsNotNone(blocked, name)
+                assert blocked is not None
+                self.assertEqual(
+                    blocked.get("blocker_kind"),
+                    "runtime_reconnect_required",
+                    blocked,
+                )
+                self.assertNotIn("permission_report", blocked, blocked)
+                self.assertTrue(blocked.get("restart_required"), blocked)
+                self.assertEqual(blocked.get("startup_head"), SHA_START, blocked)
+                self.assertEqual(blocked.get("live_remote_head"), SHA_LIVE, blocked)
+                action = (blocked.get("exact_safe_next_action") or "").lower()
+                self.assertIn("reconnect", action)
+                self.assertNotIn("call gitea_activate_profile with", action)
+                self.assertNotIn("switch to the author mcp session", action)
+                self.assertNotIn("switch to the reviewer mcp session", action)
+
+    def test_fresh_plus_forbidden_op_all_roles(self):
+        for name, role, _permitted, allowed, forbidden, forbidden_op in ROLE_MATRIX:
+            with self.subTest(profile=name, op=forbidden_op):
+                profile = _profile(name, role, allowed, forbidden)
+                with patch.object(mcp_server, "get_profile", return_value=profile), patch.object(
+                    mcp_server, "_master_parity_block", return_value=[]
+                ), patch.object(
+                    mcp_server, "_runtime_mode_block", return_value=[]
+                ), patch.object(
+                    mcp_server, "_ensure_matching_profile", return_value=None
+                ), patch.object(
+                    mcp_server.session_ctx,
+                    "mutation_context_audit_fields",
+                    return_value={"session_profile": name},
+                ), patch.object(
+                    mcp_server.gitea_config,
+                    "load_config",
+                    return_value=_config({name: profile}),
+                ), patch.object(
+                    mcp_server.gitea_config, "is_runtime_switching_enabled", return_value=False
+                ):
+                    blocked = mcp_server._profile_permission_block(forbidden_op)
+                self.assertIsNotNone(blocked, name)
+                assert blocked is not None
+                self.assertEqual(blocked.get("blocker_kind"), "permission_denied", blocked)
+                self.assertIn("permission_report", blocked, blocked)
+                report = blocked["permission_report"]
+                self.assertEqual(report.get("missing_permission"), forbidden_op, report)
+                self.assertFalse(report.get("diagnostic_defect"), report)
+                # No runtime reconnect fields for pure permission denial
+                self.assertNotEqual(
+                    blocked.get("blocker_kind"), "runtime_reconnect_required"
+                )
+
+    def test_stale_plus_forbidden_op_both_causes_separated(self):
+        for name, role, _permitted, allowed, forbidden, forbidden_op in ROLE_MATRIX:
+            with self.subTest(profile=name, op=forbidden_op):
+                profile = _profile(name, role, allowed, forbidden)
+                parity = self._stale_parity()
+                stale_reason = parity["reasons"][0]
+                with patch.object(mcp_server, "get_profile", return_value=profile), patch.object(
+                    mcp_server, "_current_master_parity", return_value=parity
+                ), patch.object(
+                    mcp_server, "_master_parity_block", return_value=[stale_reason]
+                ), patch.object(
+                    mcp_server, "_runtime_mode_block", return_value=[]
+                ), patch.object(
+                    mcp_server, "_ensure_matching_profile", return_value=None
+                ), patch.object(
+                    mcp_server.session_ctx,
+                    "mutation_context_audit_fields",
+                    return_value={"session_profile": name},
+                ):
+                    # Gate collects both classes; force permission reason too.
+                    with patch.object(
+                        mcp_server,
+                        "_profile_operation_gate",
+                        return_value=[
+                            stale_reason,
+                            f"profile is not allowed to {forbidden_op}",
+                        ],
+                    ):
+                        blocked = mcp_server._profile_permission_block(forbidden_op)
+                self.assertIsNotNone(blocked)
+                assert blocked is not None
+                self.assertEqual(
+                    blocked.get("blocker_kind"), "runtime_reconnect_required", blocked
+                )
+                self.assertNotIn("permission_report", blocked, blocked)
+                self.assertIn("permission_block_reasons", blocked, blocked)
+                self.assertIn("stale_runtime_reasons", blocked, blocked)
+                classes = blocked.get("gate_reason_classes") or {}
+                self.assertTrue(classes.get("stale_runtime"), classes)
+                self.assertTrue(classes.get("permission"), classes)
+
+    def test_runtime_mode_block_no_permission_report(self):
+        profile = _profile(
+            "prgs-author",
+            "author",
+            ["gitea.read", "gitea.issue.create"],
+            [],
+        )
+        runtime_reason = (
+            "runtime mode is 'dev-test' and the mutation targets the "
+            "production repository; dev/test runtimes must not mutate real "
+            "issues or PRs (ADR: stable control runtime vs dev runtime)"
+        )
+        with patch.object(mcp_server, "get_profile", return_value=profile), patch.object(
+            mcp_server, "_master_parity_block", return_value=[]
+        ), patch.object(
+            mcp_server, "_runtime_mode_block", return_value=[runtime_reason]
+        ), patch.object(
+            mcp_server, "_ensure_matching_profile", return_value=None
+        ), patch.object(
+            mcp_server.session_ctx,
+            "mutation_context_audit_fields",
+            return_value={"session_profile": "prgs-author"},
+        ):
+            blocked = mcp_server._profile_permission_block("gitea.issue.create")
+        self.assertIsNotNone(blocked)
+        assert blocked is not None
+        self.assertEqual(blocked.get("blocker_kind"), "runtime_mode_blocked", blocked)
+        self.assertNotIn("permission_report", blocked, blocked)
+        action = (blocked.get("exact_safe_next_action") or "").lower()
+        self.assertNotIn("call gitea_activate_profile with", action)
+        self.assertIn("stable control runtime", action)
+
+
+class Issue897CreateIssueRegression(unittest.TestCase):
+    def test_create_issue_stale_daemon_never_missing_issue_create(self):
+        """Regression AC: stale prgs-author create_issue must not claim missing create."""
+        profile = _profile(
+            "prgs-author",
+            "author",
+            [
+                "gitea.read",
+                "gitea.issue.create",
+                "gitea.issue.comment",
+                "gitea.branch.create",
+                "gitea.branch.push",
+                "gitea.pr.create",
+                "gitea.pr.comment",
+                "gitea.repo.commit",
+            ],
+            [],
+        )
+        stale_reason = (
+            f"live remote master is {SHA_LIVE[:12]} but the MCP server started "
+            f"at {SHA_START[:12]}; the daemon is stale relative to live master "
+            "-- restart/reconnect before mutating"
+        )
+        parity = {
+            "in_parity": True,
+            "stale": False,
+            "restart_required": True,
+            "determinable": True,
+            "startup_head": SHA_START,
+            "current_head": SHA_START,
+            "daemon_start_head": SHA_START,
+            "local_head": SHA_START,
+            "live_remote_head": SHA_LIVE,
+            "live_known": True,
+            "live_stale": True,
+            "mutation_safe": False,
+            "reasons": [stale_reason],
+        }
+
+        with patch.object(mcp_server, "get_profile", return_value=profile), patch.object(
+            mcp_server, "_current_master_parity", return_value=parity
+        ), patch.object(
+            mcp_server, "_master_parity_block", return_value=[stale_reason]
+        ), patch.object(
+            mcp_server, "_runtime_mode_block", return_value=[]
+        ), patch.object(
+            mcp_server, "_ensure_matching_profile", return_value=None
+        ), patch.object(
+            mcp_server.session_ctx,
+            "mutation_context_audit_fields",
+            return_value={"session_profile": "prgs-author"},
+        ), patch.object(
+            mcp_server, "_mutation_config_authority_block", return_value=None
+        ), patch.object(
+            mcp_server, "_session_context_mutation_block", return_value=None
+        ):
+            blocked = mcp_server._profile_permission_block(
+                "gitea.issue.create", remote="prgs"
+            )
+
+        self.assertIsNotNone(blocked)
+        assert blocked is not None
+        self.assertEqual(blocked.get("blocker_kind"), "runtime_reconnect_required")
+        self.assertNotIn("permission_report", blocked)
+        # Even if a caller still built a raw report, holds-check must not claim missing.
+        with patch.object(mcp_server, "get_profile", return_value=profile):
+            raw = mcp_server._permission_block_report("gitea.issue.create")
+        self.assertIsNone(raw.get("missing_permission"), raw)
+        self.assertNotEqual(raw.get("missing_permission"), "gitea.issue.create")
+
+    def test_permission_report_for_gate_reasons_skips_stale(self):
+        stale = (
+            f"live remote master is {SHA_LIVE[:12]} but the MCP server started "
+            f"at {SHA_START[:12]}; the daemon is stale relative to live master "
+            "-- restart/reconnect before mutating"
+        )
+        self.assertIsNone(
+            mcp_server._permission_report_for_gate_reasons(
+                "gitea.issue.comment", [stale]
+            )
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_webui_restart_console.py

@@ -0,0 +1,452 @@
+"""Read-only restart console: views, gates, and honesty rules (#667).
+
+The console consumes the #655 substrate. These tests hold it to the three
+properties that make a status surface trustworthy:
+
+* an unreadable source is reported unavailable, never rendered as green;
+* authorization is probed the way execution would probe it, so an allow is
+  never shown for something that could not run;
+* the surface performs no mutation, including no write to the control-plane DB.
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+import sys
+import tempfile
+import unittest
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from starlette.testclient import TestClient  # noqa: E402
+
+import restart_coordinator  # noqa: E402
+from webui import console_authz, restart_console, restart_views  # noqa: E402
+from webui.app import create_app  # noqa: E402
+
+NOW = datetime(2026, 7, 25, 21, 0, 0, tzinfo=timezone.utc)
+
+
+def _principal(role: str) -> console_authz.Principal:
+    return console_authz.Principal(
+        subject="[email protected]",
+        role=role,
+        identity_source=console_authz.IDENTITY_LOCAL_DEV,
+        authenticated=True,
+    )
+
+
+def _inventory(*, complete: bool = True, sessions=(), leases=()):
+    def _read(**_kwargs):
+        return {
+            "sessions": list(sessions),
+            "leases": list(leases),
+            "terminal_lock": None,
+            "prior_recovery_attempts": [],
+            "inventory_complete": complete,
+            "incomplete_reasons": (
+                [] if complete else ["fixture: inventory withheld"]
+            ),
+        }
+
+    return _read
+
+
+def _live_session(session_id: str = "prgs-author-1234-abcd") -> dict:
+    return {
+        "session_id": session_id,
+        "role": "author",
+        "profile": "prgs-author",
+        "pid": os.getpid(),
+        "status": "active",
+        "last_heartbeat_at": (NOW - timedelta(seconds=30)).isoformat(),
+    }
+
+
+def drain_proof_fixture() -> dict:
+    """A structurally complete but unsigned drain proof."""
+    return {
+        "version": "drain-proof/v1",
+        "proof_id": "deadbeef" * 8,
+        "clean": True,
+        "issued_at": (NOW - timedelta(minutes=1)).isoformat(),
+        "expires_at": (NOW + timedelta(minutes=5)).isoformat(),
+        "requesting_session_id": "s-live",
+        "impact_fingerprint": "f" * 64,
+        "checks": [],
+        "failed_checks": [],
+    }
+
+
+class RestartClassMatrixTest(unittest.TestCase):
+    def test_every_policy_class_is_rendered(self) -> None:
+        views = restart_console.build_restart_class_views("operator")
+        self.assertEqual(len(views), len(restart_coordinator.RESTART_CLASS_POLICIES))
+
+    def test_viewer_capability_is_role_scoped_not_generic(self) -> None:
+        """A worker role must not be shown as able to request a full restart."""
+        author = {
+            v.restart_class: v
+            for v in restart_console.build_restart_class_views("author")
+        }
+        operator = {
+            v.restart_class: v
+            for v in restart_console.build_restart_class_views("operator")
+        }
+        full = restart_coordinator.RestartClass.FULL_MCP_RESTART.value
+
+        self.assertFalse(author[full].viewer_may_request)
+        self.assertFalse(author[full].viewer_may_execute)
+        self.assertTrue(operator[full].viewer_may_request)
+        self.assertTrue(operator[full].viewer_may_execute)
+
+    def test_unknown_role_may_do_nothing(self) -> None:
+        views = restart_console.build_restart_class_views("not-a-role")
+        self.assertTrue(all(not v.viewer_may_request for v in views))
+        self.assertTrue(all(not v.viewer_may_execute for v in views))
+
+
+class AuthorizationProbeTest(unittest.TestCase):
+    def test_probe_asks_for_execution_so_phase_gate_is_reported(self) -> None:
+        """An admin clears the role bar and still cannot execute in Phase 1.
+
+        This is the case that distinguishes the two probes. Asked without
+        ``for_execution`` an admin is *allowed* for ``system.restart_namespace``,
+        which on a control surface reads as a live button. Asked the way
+        execution asks, the same principal is refused ``phase_not_active``. The
+        console must report the second answer.
+        """
+        by_id = {
+            a.action_id: a
+            for a in restart_console.build_action_authorizations(
+                _principal(console_authz.ADMIN)
+            )
+        }
+        restart = by_id["system.restart_namespace"]
+
+        self.assertFalse(restart.execution_enabled)
+        self.assertEqual(restart.reason_code, console_authz.DENY_PHASE_NOT_ACTIVE)
+
+        permissive = console_authz.authorize(
+            "system.restart_namespace", _principal(console_authz.ADMIN)
+        )
+        self.assertTrue(
+            permissive.allowed,
+            "guard precondition: without for_execution an admin is allowed, "
+            "which is exactly why the console must not probe that way",
+        )
+
+    def test_operator_is_refused_the_admin_only_restart_action(self) -> None:
+        """Role refusal precedes the phase gate and is reported as such."""
+        by_id = {
+            a.action_id: a
+            for a in restart_console.build_action_authorizations(
+                _principal(console_authz.OPERATOR)
+            )
+        }
+        self.assertEqual(
+            by_id["system.restart_namespace"].reason_code,
+            console_authz.DENY_INSUFFICIENT_ROLE,
+        )
+
+    def test_anonymous_is_denied_unauthenticated(self) -> None:
+        by_id = {
+            a.action_id: a for a in restart_console.build_action_authorizations(None)
+        }
+        self.assertEqual(
+            by_id["system.restart_namespace"].reason_code,
+            console_authz.DENY_UNAUTHENTICATED,
+        )
+
+    def test_no_authorization_ever_reports_execution_enabled(self) -> None:
+        for role in (
+            console_authz.VIEWER,
+            console_authz.OPERATOR,
+            console_authz.CONTROLLER,
+            console_authz.ADMIN,
+        ):
+            for auth in restart_console.build_action_authorizations(_principal(role)):
+                self.assertFalse(
+                    auth.execution_enabled,
+                    f"{role} reported execution_enabled for {auth.action_id}",
+                )
+
+
+class ImpactPreviewTest(unittest.TestCase):
+    def test_impact_renders_from_coordinator_dto(self) -> None:
+        impact, source = restart_console.load_impact_report(
+            principal=_principal(console_authz.OPERATOR),
+            read_inventory=_inventory(sessions=[_live_session()]),
+            now=NOW,
+        )
+        self.assertTrue(source.available)
+        self.assertIsNotNone(impact)
+        self.assertEqual(
+            impact["restart_class"],
+            restart_coordinator.RestartClass.FULL_MCP_RESTART.value,
+        )
+        self.assertIn("verdict", impact)
+        self.assertFalse(impact["restart_performed"])
+        self.assertTrue(impact["dry_run"])
+
+    def test_incomplete_inventory_is_surfaced_and_denies(self) -> None:
+        impact, source = restart_console.load_impact_report(
+            principal=_principal(console_authz.OPERATOR),
+            read_inventory=_inventory(complete=False),
+            now=NOW,
+        )
+        self.assertFalse(impact["inventory_complete"])
+        self.assertFalse(impact["allow_restart"])
+        self.assertTrue(source.detail, "incomplete inventory must explain itself")
+
+    def test_inventory_reader_failure_is_unavailable_not_empty(self) -> None:
+        """A reader that raises must not be rendered as 'no sessions affected'."""
+
+        def _boom(**_kwargs):
+            raise RuntimeError("control-plane unreachable")
+
+        impact, source = restart_console.load_impact_report(
+            principal=_principal(console_authz.OPERATOR),
+            read_inventory=_boom,
+            now=NOW,
+        )
+        self.assertIsNone(impact)
+        self.assertFalse(source.available)
+        self.assertIn("control-plane unreachable", source.detail)
+
+
+class ControlPlaneReadTest(unittest.TestCase):
+    def test_missing_database_is_incomplete_not_empty(self) -> None:
+        inventory = restart_console.read_control_plane_inventory(
+            db_path="/nonexistent/control-plane.sqlite3"
+        )
+        self.assertFalse(inventory["inventory_complete"])
+        self.assertEqual(inventory["sessions"], [])
+        self.assertTrue(inventory["incomplete_reasons"])
+
+    def test_reader_never_creates_the_database(self) -> None:
+        """Reading status must not bring a control-plane DB into existence.
+
+        The path deliberately sits in a directory that already exists: a
+        read-write ``sqlite3.connect`` would happily create the file there, so
+        this fails if the reader ever stops opening the database ``mode=ro``.
+        A nested-missing-directory path would pass for the wrong reason,
+        because sqlite cannot create the parent directory either way.
+        """
+        with tempfile.TemporaryDirectory() as tmp:
+            path = os.path.join(tmp, "control_plane.sqlite3")
+            self.assertTrue(os.path.isdir(os.path.dirname(path)))
+
+            inventory = restart_console.read_control_plane_inventory(db_path=path)
+
+            self.assertFalse(
+                os.path.exists(path),
+                "reading restart status created a control-plane database",
+            )
+            self.assertFalse(inventory["inventory_complete"])
+
+    def test_reads_active_sessions_from_a_real_database(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = os.path.join(tmp, "cp.sqlite3")
+            conn = sqlite3.connect(path)
+            conn.execute(
+                "CREATE TABLE sessions (session_id TEXT, role TEXT, profile TEXT,"
+                " pid INTEGER, status TEXT, last_heartbeat_at TEXT)"
+            )
+            conn.execute(
+                "CREATE TABLE work_items (work_item_id INTEGER, kind TEXT,"
+                " number INTEGER)"
+            )
+            conn.execute(
+                "CREATE TABLE leases (lease_id TEXT, session_id TEXT, role TEXT,"
+                " phase TEXT, status TEXT, worktree_path TEXT,"
+                " work_item_id INTEGER, expires_at TEXT)"
+            )
+            conn.execute(
+                "INSERT INTO sessions VALUES (?,?,?,?,?,?)",
+                ("s-live", "author", "prgs-author", 4242, "active", NOW.isoformat()),
+            )
+            conn.execute(
+                "INSERT INTO sessions VALUES (?,?,?,?,?,?)",
+                ("s-done", "author", "prgs-author", 11, "closed", NOW.isoformat()),
+            )
+            conn.execute("INSERT INTO work_items VALUES (1, 'issue', 667)")
+            conn.execute(
+                "INSERT INTO leases VALUES (?,?,?,?,?,?,?,?)",
+                (
+                    "l-1",
+                    "s-live",
+                    "author",
+                    "allocated",
+                    "active",
+                    None,
+                    1,
+                    NOW.isoformat(),
+                ),
+            )
+            conn.commit()
+            conn.close()
+
+            inventory = restart_console.read_control_plane_inventory(db_path=path)
+
+        self.assertTrue(inventory["inventory_complete"])
+        self.assertEqual([s["session_id"] for s in inventory["sessions"]], ["s-live"])
+        self.assertEqual(inventory["leases"][0]["work_number"], 667)
+
+
+class DrainAndReconcileTest(unittest.TestCase):
+    def test_absent_drain_proof_is_not_a_pass(self) -> None:
+        drain, source = restart_console.load_drain_status(proof=None, now=NOW)
+        self.assertIsNone(drain)
+        self.assertFalse(source.available)
+        self.assertIn("denies", source.detail)
+
+    def test_tampered_drain_proof_is_reported_invalid(self) -> None:
+        proof = drain_proof_fixture()
+        proof["clean"] = True
+        proof["proof_id"] = "0" * 64
+        drain, source = restart_console.load_drain_status(proof=proof, now=NOW)
+        self.assertTrue(source.available)
+        self.assertFalse(drain["valid"])
+
+    def test_absent_reconcile_proof_is_unavailable(self) -> None:
+        reconcile, source = restart_console.load_reconcile_status(load_proof=None)
+        self.assertIsNone(reconcile)
+        self.assertFalse(source.available)
+
+    def test_reconcile_proof_is_rendered_when_supplied(self) -> None:
+        payload = {
+            "overall_status": "degraded",
+            "mode": "log_only",
+            "resolved_count": 3,
+            "unresolved_count": 2,
+            "items": [
+                {
+                    "dimension": "leases",
+                    "status": "unresolved",
+                    "summary": "2 orphaned leases",
+                    "follow_up_required": True,
+                }
+            ],
+        }
+        reconcile, source = restart_console.load_reconcile_status(
+            load_proof=lambda: payload
+        )
+        self.assertTrue(source.available)
+        self.assertEqual(reconcile["unresolved_count"], 2)
+
+
+class RenderingTest(unittest.TestCase):
+    def _snapshot(self, **kwargs):
+        params = {
+            "principal": _principal(console_authz.OPERATOR),
+            "read_inventory": _inventory(sessions=[_live_session()]),
+            "now": NOW,
+        }
+        params.update(kwargs)
+        return restart_console.load_restart_console_snapshot(**params)
+
+    def test_page_renders_every_section(self) -> None:
+        html = restart_views.render_restart_console_page(self._snapshot())
+        for heading in (
+            "Impact preview",
+            "Drain proof",
+            "Post-restart reconcile",
+            "Restart classes",
+            "Approval controls",
+            "Break-glass",
+        ):
+            self.assertIn(heading, html)
+
+    def test_hostile_session_id_is_escaped(self) -> None:
+        hostile = "<script>alert('x')</script>"
+        html = restart_views.render_restart_console_page(
+            self._snapshot(read_inventory=_inventory(sessions=[_live_session(hostile)]))
+        )
+        self.assertNotIn("<script>alert", html)
+        self.assertIn("&lt;script&gt;", html)
+
+    def test_unavailable_impact_says_unsafe_rather_than_clean(self) -> None:
+        def _boom(**_kwargs):
+            raise RuntimeError("nope")
+
+        snapshot = self._snapshot(read_inventory=_boom)
+        html = restart_views.render_restart_console_page(snapshot)
+        self.assertIn("blast radius of a restart is unknown", html)
+        self.assertIn("unavailable", html)
+
+    def test_break_glass_is_hidden_from_unprivileged_viewers(self) -> None:
+        viewer_html = restart_views.render_restart_console_page(
+            self._snapshot(principal=_principal(console_authz.VIEWER))
+        )
+        self.assertIn("visible to operator-class", viewer_html)
+        self.assertNotIn(
+            f"#{restart_console.BREAK_GLASS_ISSUE}", viewer_html
+        )
+
+    def test_break_glass_shown_to_operator_is_marked_unavailable(self) -> None:
+        html = restart_views.render_restart_console_page(self._snapshot())
+        self.assertIn("unavailable", html)
+        self.assertIn(f"#{restart_console.BREAK_GLASS_ISSUE}", html)
+
+    def test_snapshot_always_declares_itself_read_only(self) -> None:
+        self.assertTrue(self._snapshot().read_only)
+
+
+class RestartConsoleRouteTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.client = TestClient(create_app())
+
+    def test_page_route_renders(self) -> None:
+        res = self.client.get("/runtime/restart")
+        self.assertEqual(res.status_code, 200)
+        self.assertIn("Restart status and impact", res.text)
+
+    def test_api_route_exports_snapshot(self) -> None:
+        res = self.client.get("/api/v1/system/restart/status")
+        self.assertEqual(res.status_code, 200)
+        payload = res.json()
+        self.assertTrue(payload["read_only"])
+        self.assertEqual(payload["links"]["issue"], 667)
+        self.assertEqual(
+            len(payload["restart_classes"]),
+            len(restart_coordinator.RESTART_CLASS_POLICIES),
+        )
+
+    def test_restart_class_is_selectable(self) -> None:
+        res = self.client.get(
+            "/api/v1/system/restart/status?restart_class=client_reconnect"
+        )
+        self.assertEqual(res.status_code, 200)
+        self.assertEqual(res.json()["impact"]["restart_class"], "client_reconnect")
+
+    def test_unknown_restart_class_fails_closed(self) -> None:
+        res = self.client.get(
+            "/api/v1/system/restart/status?restart_class=obliterate-everything"
+        )
+        self.assertEqual(res.status_code, 200)
+        impact = res.json()["impact"]
+        self.assertFalse(impact["allow_restart"])
+
+    def test_anonymous_api_reader_gets_no_execution_grant(self) -> None:
+        payload = self.client.get("/api/v1/system/restart/status").json()
+        self.assertFalse(payload["break_glass"]["available"])
+        for auth in payload["authorizations"]:
+            self.assertFalse(auth["execution_enabled"])
+
+    def test_route_is_registered_in_nav(self) -> None:
+        from webui.nav import nav_hrefs
+
+        self.assertIn("/runtime/restart", nav_hrefs())
+
+    def test_no_write_method_is_exposed(self) -> None:
+        """The surface is read-only: nothing accepts a POST."""
+        for path in ("/runtime/restart", "/api/v1/system/restart/status"):
+            self.assertEqual(self.client.post(path).status_code, 405, path)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_webui_sessions_view.py

@@ -0,0 +1,739 @@
+"""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.
+
+Also pins the two invariants a reviewer found violated at head a81db754:
+degraded ownership sections must render as *unknown* rather than as an
+affirmative "none"/"unbound", and contamination payload text must be redacted
+at the display boundary rather than trusted from the write-time denylist.
+"""
+
+from __future__ import annotations
+
+import os
+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_DEGRADED,
+    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,
+    _inspect_contamination,
+    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, ...] = (),
+    statuses: dict[str, str] | None = None,
+) -> InventorySnapshot:
+    """Build a snapshot; ``statuses`` degrades named sections (default all ok)."""
+    status_of = statuses or {}
+
+    def _status(name: str) -> str:
+        return status_of.get(name, STATUS_OK)
+
+    sections = (
+        InventorySection(
+            name="sessions",
+            authority=AUTHORITY_CONTROL_PLANE_DB,
+            status=_status("sessions"),
+            items=sessions,
+        ),
+        InventorySection(
+            name="leases",
+            authority=AUTHORITY_CONTROL_PLANE_DB,
+            status=_status("leases"),
+            items=leases,
+        ),
+        InventorySection(
+            name="locks",
+            authority=AUTHORITY_FILESYSTEM,
+            status=_status("locks"),
+            items=locks,
+        ),
+        InventorySection(
+            name="worktrees",
+            authority=AUTHORITY_FILESYSTEM,
+            status=_status("worktrees"),
+            items=worktrees,
+        ),
+        InventorySection(
+            name="namespaces",
+            authority=AUTHORITY_FILESYSTEM,
+            status=_status("namespaces"),
+            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</a> <span class="muted">(stub)</span>',
+            home.text,
+        )
+
+
+class TestDegradedOwnershipAuthority(unittest.TestCase):
+    """B1: a section that could not be read must never render as absence."""
+
+    def _snapshot(self, inventory: InventorySnapshot) -> SessionViewSnapshot:
+        return SessionViewSnapshot(
+            runtime=_runtime(),
+            inventory=inventory,
+            sessions=_build_session_rows(inventory, contamination=()),
+            contamination_markers=(),
+        )
+
+    def test_unavailable_leases_mark_row_authority_unproven(self):
+        inventory = _inventory(
+            sessions=(_clean_session(),),
+            statuses={"leases": STATUS_UNAVAILABLE},
+        )
+        row = _build_session_rows(inventory, contamination=())[0]
+        self.assertEqual(row.lease_ids, ())
+        self.assertEqual(row.lease_authority, STATUS_UNAVAILABLE)
+        # Worktree binding is correlated through lease work numbers, so it
+        # inherits the unreadable lease section.
+        self.assertEqual(row.worktree_authority, STATUS_UNAVAILABLE)
+        self.assertFalse(row.ownership_authority_complete)
+
+    def test_readable_locks_are_not_reported_unbound_when_leases_degrade(self):
+        # The narrow variant: locks hold a real worktree_path and read cleanly,
+        # but the lease section that supplies the correlating work number does
+        # not. The row must say unknown, not "unbound".
+        inventory = _inventory(
+            sessions=(_clean_session(),),
+            locks=(
+                {
+                    "issue_number": 641,
+                    "worktree_path": "branches/feat-issue-641",
+                },
+            ),
+            statuses={"leases": STATUS_DEGRADED},
+        )
+        row = _build_session_rows(inventory, contamination=())[0]
+        self.assertEqual(row.worktree_paths, ())
+        self.assertEqual(row.worktree_authority, STATUS_DEGRADED)
+        self.assertFalse(row.ownership_authority_complete)
+
+    def test_degraded_render_says_unknown_not_none_or_unbound(self):
+        inventory = _inventory(
+            sessions=(_clean_session(),),
+            statuses={"leases": STATUS_UNAVAILABLE, "locks": STATUS_UNAVAILABLE},
+        )
+        html = render_sessions_page(self._snapshot(inventory))
+        self.assertIn("unknown (inventory unavailable)", html)
+        self.assertIn("authority unproven", html)
+        self.assertIn("Ownership authority incomplete", html)
+        # The affirmative-absence strings must be gone from the row entirely.
+        self.assertNotIn(">none<", html)
+        self.assertNotIn(">unbound<", html)
+
+    def test_clean_inventory_still_renders_affirmative_absence(self):
+        # Guards against over-correcting B1 into "everything is unknown".
+        inventory = _inventory(sessions=(_clean_session(),))
+        html = render_sessions_page(self._snapshot(inventory))
+        self.assertIn(">none<", html)
+        self.assertIn(">unbound<", html)
+        # The column legend mentions "unknown (inventory …)" as static copy, so
+        # assert on the per-row marker and the concrete statuses instead.
+        self.assertNotIn("authority unproven", html)
+        self.assertNotIn("unknown (inventory unavailable)", html)
+        self.assertNotIn("unknown (inventory degraded)", html)
+        self.assertNotIn("Ownership authority incomplete", html)
+
+    def test_json_export_carries_snapshot_and_per_row_authority(self):
+        inventory = _inventory(
+            sessions=(_clean_session(),),
+            statuses={"locks": STATUS_UNAVAILABLE},
+        )
+        data = snapshot_to_dict(self._snapshot(inventory))
+        self.assertFalse(data["ownership_authority_complete"])
+        self.assertEqual(
+            data["ownership_section_status"]["locks"], STATUS_UNAVAILABLE
+        )
+        self.assertEqual(data["ownership_section_status"]["leases"], STATUS_OK)
+        self.assertIn("unknown, not unowned", data["ownership_note"])
+
+        row = data["sessions"][0]
+        self.assertTrue(row["lease_authority_complete"])
+        self.assertFalse(row["worktree_authority_complete"])
+        self.assertEqual(row["worktree_authority"], STATUS_UNAVAILABLE)
+        self.assertFalse(row["ownership_authority_complete"])
+        self.assertIn("unknown, not unowned", row["ownership_note"])
+
+    def test_json_export_is_affirmative_when_every_source_reads(self):
+        inventory = _inventory(sessions=(_clean_session(),))
+        data = snapshot_to_dict(self._snapshot(inventory))
+        self.assertTrue(data["ownership_authority_complete"])
+        self.assertTrue(data["sessions"][0]["ownership_authority_complete"])
+
+    def test_missing_session_list_is_not_reported_as_no_sessions(self):
+        inventory = _inventory(statuses={"sessions": STATUS_UNAVAILABLE})
+        html = render_sessions_page(self._snapshot(inventory))
+        self.assertIn("could not be read", html)
+        self.assertIn("not evidence that no sessions exist", html)
+
+    def test_expired_lease_flags_row_as_stale(self):
+        inventory = _inventory(
+            sessions=(_clean_session(),),
+            leases=(
+                {
+                    "lease_id": "lease-expired-1",
+                    "session_id": "prgs-author-111-clean",
+                    "status": "active",
+                    "expired": True,
+                    "work_kind": "issue",
+                    "work_number": 641,
+                },
+            ),
+        )
+        row = _build_session_rows(inventory, contamination=())[0]
+        self.assertIn("lease-expired", row.stale_flags)
+        self.assertIn("active-lease-past-expiry", row.stale_flags)
+
+
+class TestContaminationRedaction(unittest.TestCase):
+    """B2: marker payload text is redacted at the display boundary."""
+
+    def _marker(self, payload: dict) -> ContaminationMarker:
+        return _inspect_contamination(
+            "runtime_recovery_contamination",
+            remote="prgs",
+            inspect=lambda **_k: {
+                "on_disk": True,
+                "has_payload": True,
+                "summary": "",
+            },
+            load=lambda **_k: payload,
+        )
+
+    def test_home_paths_are_collapsed(self):
+        home = os.path.expanduser("~")
+        marker = self._marker(
+            {"command_summary": f"pkill -f {home}/Development/Gitea-Tools/x.py"}
+        )
+        self.assertNotIn(home, marker.command_summary)
+        self.assertIn("~/Development/Gitea-Tools/x.py", marker.command_summary)
+
+    def test_secrets_missed_by_the_write_time_denylist_are_redacted(self):
+        # Each of these was verified in review to survive
+        # stable_branch_push_guard.redact_command untouched.
+        cases = (
+            ("curl -H 'X-Api-Key: SUPERSECRET123' https://example.invalid", "SUPERSECRET123"),
+            ("cmd --password hunter2 origin master", "hunter2"),
+            ("PRIVATE_KEY=abc123 python deploy.py", "abc123"),
+            ("fetch https://user:[email protected]/x.git", "user:pw"),
+        )
+        for raw, secret in cases:
+            with self.subTest(raw=raw):
+                marker = self._marker({"command_summary": raw})
+                self.assertNotIn(secret, marker.command_summary)
+                self.assertIn("[redacted]", marker.command_summary)
+
+    def test_command_summary_is_redacted_not_removed(self):
+        # It is legitimate #630 evidence: the operator must still see which
+        # daemon was killed.
+        marker = self._marker(
+            {
+                "command_summary": "pkill -f gitea_mcp_server.py",
+                "reason_class": "manual_daemon_kill",
+                "session_id": "prgs-author-111-clean",
+                "role": "author",
+            }
+        )
+        self.assertIn("pkill -f gitea_mcp_server.py", marker.command_summary)
+        self.assertEqual(marker.reason_class, "manual_daemon_kill")
+        self.assertEqual(marker.session_id, "prgs-author-111-clean")
+        self.assertEqual(marker.role, "author")
+
+    def test_rendered_page_exposes_no_home_path_from_a_marker(self):
+        home = os.path.expanduser("~")
+        marker = self._marker(
+            {
+                "command_summary": f"pkill -f {home}/Development/Gitea-Tools/x.py",
+                "reason_class": "manual_daemon_kill",
+            }
+        )
+        inventory = _inventory(sessions=(_clean_session(),))
+        html = render_sessions_page(
+            SessionViewSnapshot(
+                runtime=_runtime(),
+                inventory=inventory,
+                sessions=_build_session_rows(inventory, (marker,)),
+                contamination_markers=(marker,),
+            )
+        )
+        self.assertIn("Contamination markers", html)
+        self.assertNotIn(home, html)
+
+
+class TestSessionsPageEscaping(unittest.TestCase):
+    """Hostile values from every rendered source stay inert (N2)."""
+
+    HOSTILE = '<script>alert("xss")</script>'
+
+    def test_hostile_session_and_marker_values_are_escaped(self):
+        session = dict(_clean_session())
+        session["session_id"] = f"sid-{self.HOSTILE}"
+        session["role"] = self.HOSTILE
+        session["profile"] = self.HOSTILE
+        session["namespace"] = self.HOSTILE
+        session["status"] = self.HOSTILE
+        inventory = _inventory(
+            sessions=(session,),
+            leases=(
+                {
+                    "lease_id": self.HOSTILE,
+                    "session_id": session["session_id"],
+                    "status": "active",
+                    "expired": False,
+                    "work_kind": self.HOSTILE,
+                    "work_number": 641,
+                },
+            ),
+            locks=(
+                {
+                    "issue_number": 641,
+                    "worktree_path": self.HOSTILE,
+                },
+            ),
+        )
+        marker = ContaminationMarker(
+            kind="runtime_recovery_contamination",
+            on_disk=True,
+            has_payload=True,
+            summary=self.HOSTILE,
+            reason_class=self.HOSTILE,
+            session_id=session["session_id"],
+            role=self.HOSTILE,
+            command_summary=self.HOSTILE,
+            cleared=False,
+        )
+        html = render_sessions_page(
+            SessionViewSnapshot(
+                runtime=_runtime(),
+                inventory=inventory,
+                sessions=_build_session_rows(inventory, (marker,)),
+                contamination_markers=(marker,),
+            )
+        )
+        self.assertNotIn("<script>", html)
+        self.assertNotIn('alert("xss")', html)
+        self.assertIn("&lt;script&gt;", html)
+
+    def test_hostile_values_in_a_degraded_render_are_escaped(self):
+        inventory = _inventory(
+            sessions=(dict(_clean_session(), session_id=f"sid-{self.HOSTILE}"),),
+            statuses={"leases": STATUS_UNAVAILABLE, "locks": STATUS_DEGRADED},
+        )
+        html = render_sessions_page(
+            SessionViewSnapshot(
+                runtime=_runtime(),
+                inventory=inventory,
+                sessions=_build_session_rows(inventory, contamination=()),
+                contamination_markers=(),
+            )
+        )
+        self.assertNotIn("<script>", html)
+        self.assertIn("&lt;script&gt;", html)
+        self.assertIn("unknown (inventory", html)
+
+
+if __name__ == "__main__":
+    unittest.main()

webui/app.py

@@ -47,7 +47,15 @@ from webui.traffic_views import render_traffic_page
 from webui.worktree_scanner import load_hygiene_snapshot, snapshot_to_dict as worktree_snapshot_to_dict
 from webui.worktree_views import render_worktrees_page
 from webui.runtime_health import load_runtime_snapshot, snapshot_to_dict as runtime_snapshot_to_dict
+import restart_coordinator
+from webui.restart_console import load_restart_console_snapshot
+from webui.restart_views import render_restart_console_page
 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 +95,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 +334,44 @@ async def api_runtime(_request: Request) -> JSONResponse:
     return JSONResponse(runtime_snapshot_to_dict(load_runtime_snapshot()))
 
 
+def _restart_console_snapshot(request: Request):
+    """Build the read-only restart snapshot for the requesting principal (#667)."""
+    principal = resolve_principal(request.headers)
+    restart_class = (
+        request.query_params.get("restart_class")
+        or restart_coordinator.RestartClass.FULL_MCP_RESTART.value
+    )
+    return load_restart_console_snapshot(
+        principal=principal, restart_class=restart_class
+    )
+
+
+async def restart_console_page(request: Request) -> HTMLResponse:
+    """Restart status, impact preview, and approval state (#667). Read-only."""
+    snapshot = _restart_console_snapshot(request)
+    return HTMLResponse(
+        render_page(
+            title="Restart", body_html=render_restart_console_page(snapshot)
+        )
+    )
+
+
+async def api_restart_status(request: Request) -> JSONResponse:
+    """JSON export of the read-only restart console snapshot (#667)."""
+    return JSONResponse(_restart_console_snapshot(request).as_dict())
+
+
+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 +811,16 @@ 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"]),
+            # #667 read-only restart status / impact preview / approval state.
+            Route("/runtime/restart", restart_console_page, methods=["GET"]),
+            Route(
+                "/api/v1/system/restart/status",
+                api_restart_status,
+                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"]),

webui/inventory.py

@@ -76,6 +76,35 @@ _CREDENTIAL_KEY_RE = re.compile(
 )
 _REDACTED = "[redacted]"
 
+#: Credential-shaped *name* as it appears inside a free-form command line. This
+#: is deliberately broader than :data:`_CREDENTIAL_KEY_RE` — it also matches a
+#: bare ``key`` component, so ``PRIVATE_KEY=`` is caught. Over-redacting a
+#: displayed string is safe; under-redacting one is not.
+_TEXT_CREDENTIAL_NAME = (
+    r"[A-Za-z0-9_.\-]*"
+    r"(?:token|secret|password|passwd|key|authorization|bearer|credential)"
+    r"[A-Za-z0-9_.\-]*"
+)
+#: A value following such a name: single-quoted, double-quoted, or bare. The
+#: bare form stops at a quote so an enclosing quote survives the redaction.
+_TEXT_CREDENTIAL_VALUE = r"'[^']*'|\"[^\"]*\"|[^\s'\"]+"
+
+_TEXT_CREDENTIAL_FLAG_RE = re.compile(
+    rf"(?P<key>(?<![\w\-])--?{_TEXT_CREDENTIAL_NAME})"
+    rf"(?P<sep>[=\s]+)"
+    rf"(?P<value>{_TEXT_CREDENTIAL_VALUE})",
+    re.IGNORECASE,
+)
+_TEXT_CREDENTIAL_ASSIGN_RE = re.compile(
+    rf"(?P<key>(?<![\w\-]){_TEXT_CREDENTIAL_NAME})"
+    rf"(?P<sep>\s*[:=]\s*)"
+    rf"(?P<value>{_TEXT_CREDENTIAL_VALUE})",
+    re.IGNORECASE,
+)
+_TEXT_URL_USERINFO_RE = re.compile(
+    r"(?P<scheme>\b[A-Za-z][A-Za-z0-9+.\-]*://)[^\s/@]+@"
+)
+
 
 @dataclass(frozen=True)
 class InventorySection:
@@ -225,6 +254,42 @@ def scrub(value: Any, *, key: str | None = None) -> Any:
     return repr(value)
 
 
+def collapse_home(text: str) -> str:
+    """Collapse every ``$HOME`` occurrence *inside* a string, not just a prefix."""
+    home = os.path.expanduser("~")
+    if not home or home == "/":
+        return text
+    return text.replace(home, "~")
+
+
+def scrub_text(value: Any) -> Any:
+    """Redact a free-form text blob such as a recorded command line.
+
+    :func:`scrub` keys off structured field *names* and whole-value prefixes,
+    which is right for inventory records but blind to a secret embedded in the
+    middle of a sentence. This collapses ``$HOME`` and redacts credential-shaped
+    tokens and URL userinfo *anywhere* in the string, so operator-supplied text
+    rendered verbatim — contamination ``command_summary`` (#630) above all — is
+    held to the same standard as every other field on the page.
+
+    Returns ``None`` unchanged so callers can keep "absent" distinct from "".
+    """
+    if value is None:
+        return None
+    text = value if isinstance(value, str) else str(value)
+    text = collapse_home(text)
+    text = _TEXT_URL_USERINFO_RE.sub(
+        lambda m: f"{m.group('scheme')}{_REDACTED}@", text
+    )
+    text = _TEXT_CREDENTIAL_FLAG_RE.sub(
+        lambda m: f"{m.group('key')}{m.group('sep')}{_REDACTED}", text
+    )
+    text = _TEXT_CREDENTIAL_ASSIGN_RE.sub(
+        lambda m: f"{m.group('key')}{m.group('sep')}{_REDACTED}", text
+    )
+    return text
+
+
 # ── control-plane database (read-only) ───────────────────────────────────────
 
 

webui/nav.py

@@ -48,7 +48,8 @@ NAV_GROUPS: tuple[NavGroup, ...] = (
     )),
     NavGroup("Runtime/Sessions", (
         NavItem("/runtime", "Runtime health"),
-        NavItem("/sessions", "Sessions", "stub"),
+        NavItem("/runtime/restart", "Restart status"),
+        NavItem("/sessions", "Sessions"),
     )),
     NavGroup("Projects", (
         NavItem("/projects", "Projects"),
@@ -76,11 +77,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. "

webui/restart_console.py

@@ -0,0 +1,579 @@
+"""Read-only restart status, impact preview, and approval state (#667).
+
+Phase 1 of the console restart surface. It *consumes* the #655 coordinator
+substrate and renders it; it never restarts, reloads, drains, approves, or kills
+anything. There is no apply path in this module, so there is no execution gate
+here to arm incorrectly — the only writes the console could perform are the ones
+it does not implement.
+
+Sources, each independently fail-soft and each reported with its own
+:class:`SourceStatus`:
+
+* :mod:`restart_coordinator` — restart-class policy matrix (#663) and the
+  blast-radius impact report (#658).
+* :mod:`drain_proof` — drain checklist and gate verdict (#661), verified
+  read-only against a caller-supplied proof.
+* :mod:`post_restart_reconcile` — post-restart completion proof (#662).
+* :mod:`webui.console_authz` — role authorization for the approval controls
+  (#633).
+
+Three rules this module holds itself to, because a status surface that lies is
+worse than one that is absent:
+
+**A source that could not be read is reported unavailable, never green.** No
+default, placeholder, or self-comparison is substituted for a reading that
+failed. An unreadable control-plane DB yields ``inventory_complete=False``,
+which the coordinator itself turns into a fail-closed verdict.
+
+**Authorization is asked the way execution would ask it.** Every authorization
+probe passes ``for_execution=True``, so the console reports whether the action
+could actually run rather than the weaker "this principal is the right role".
+While the console is in Phase 1 that answer is ``phase_not_active`` for every
+phase-2 action, and the surface says so plainly instead of showing an allow.
+
+**The database is opened read-only.** ``ControlPlaneDB()`` creates directories
+and runs migrations on construction, which is a write; this module opens the
+sqlite file with ``mode=ro`` exactly as :mod:`webui.inventory` does, and treats
+a missing file as missing authority rather than an empty inventory.
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Callable, Mapping
+
+import control_plane_db
+import drain_proof
+import restart_coordinator
+from webui import console_authz
+from webui.inventory import redact_path, scrub
+
+# --- Source status ----------------------------------------------------------
+
+STATUS_OK = "ok"
+STATUS_UNAVAILABLE = "unavailable"
+
+#: Console actions whose authorization state this surface reports. Both are
+#: pre-existing #642 actions; this module adds no new console action because it
+#: performs no console action.
+REPORTED_ACTIONS: tuple[str, ...] = (
+    "system.restart_namespace",
+    "system.reload_namespace",
+)
+
+#: The break-glass workflow (#664) is not consumed here. It is declared so the
+#: surface is honest about the gap rather than silently omitting a governance
+#: path the operator has been told exists.
+BREAK_GLASS_ISSUE = 664
+BREAK_GLASS_PENDING_REASON = (
+    "The break-glass workflow (#664) is not yet available on this branch's "
+    "base; no break-glass control is offered and none is implied."
+)
+
+
+@dataclass(frozen=True)
+class SourceStatus:
+    """Whether one backing source could be read, and why not when it could not."""
+
+    name: str
+    status: str
+    detail: str = ""
+
+    @property
+    def available(self) -> bool:
+        return self.status == STATUS_OK
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "status": self.status,
+            "available": self.available,
+            "detail": self.detail,
+        }
+
+
+@dataclass(frozen=True)
+class RestartClassView:
+    """One row of the #663 restart-class matrix, scoped to the viewer's role."""
+
+    restart_class: str
+    required_permission: str
+    expected_blast_radius: str
+    drain_requirement: str
+    full_drain_required: bool
+    approval_requirement: str
+    request_roles: tuple[str, ...]
+    execution_roles: tuple[str, ...]
+    viewer_may_request: bool
+    viewer_may_execute: bool
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "restart_class": self.restart_class,
+            "required_permission": self.required_permission,
+            "expected_blast_radius": self.expected_blast_radius,
+            "drain_requirement": self.drain_requirement,
+            "full_drain_required": self.full_drain_required,
+            "approval_requirement": self.approval_requirement,
+            "request_roles": list(self.request_roles),
+            "execution_roles": list(self.execution_roles),
+            "viewer_may_request": self.viewer_may_request,
+            "viewer_may_execute": self.viewer_may_execute,
+        }
+
+
+@dataclass(frozen=True)
+class ActionAuthorization:
+    """Authorization state for one console action, asked as execution would."""
+
+    action_id: str
+    summary: str
+    required_role: str
+    allowed: bool
+    execution_enabled: bool
+    reason_code: str
+    detail: str
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "action_id": self.action_id,
+            "summary": self.summary,
+            "required_role": self.required_role,
+            "allowed": self.allowed,
+            "execution_enabled": self.execution_enabled,
+            "reason_code": self.reason_code,
+            "detail": self.detail,
+        }
+
+
+@dataclass(frozen=True)
+class BreakGlassSurface:
+    """Declared-but-unavailable break-glass panel (#664 is not on this base)."""
+
+    available: bool
+    issue: int
+    reason: str
+    viewer_is_privileged: bool
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "available": self.available,
+            "issue": self.issue,
+            "reason": self.reason,
+            "viewer_is_privileged": self.viewer_is_privileged,
+        }
+
+
+@dataclass(frozen=True)
+class RestartConsoleSnapshot:
+    """Everything the read-only restart console renders."""
+
+    generated_at: str
+    viewer_role: str
+    viewer_authenticated: bool
+    read_only: bool
+    impact: dict[str, Any] | None
+    impact_source: SourceStatus
+    drain: dict[str, Any] | None
+    drain_source: SourceStatus
+    reconcile: dict[str, Any] | None
+    reconcile_source: SourceStatus
+    restart_classes: tuple[RestartClassView, ...]
+    authorizations: tuple[ActionAuthorization, ...]
+    break_glass: BreakGlassSurface
+    notes: tuple[str, ...] = field(default_factory=tuple)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "generated_at": self.generated_at,
+            "viewer_role": self.viewer_role,
+            "viewer_authenticated": self.viewer_authenticated,
+            "read_only": self.read_only,
+            "impact": self.impact,
+            "impact_source": self.impact_source.as_dict(),
+            "drain": self.drain,
+            "drain_source": self.drain_source.as_dict(),
+            "reconcile": self.reconcile,
+            "reconcile_source": self.reconcile_source.as_dict(),
+            "restart_classes": [c.as_dict() for c in self.restart_classes],
+            "authorizations": [a.as_dict() for a in self.authorizations],
+            "break_glass": self.break_glass.as_dict(),
+            "notes": list(self.notes),
+            "links": {
+                "issue": 667,
+                "extends": 642,
+                "umbrella": 655,
+                "coordinator": 658,
+                "drain_proof": 661,
+                "reconcile": 662,
+                "restart_classes": 663,
+                "break_glass": BREAK_GLASS_ISSUE,
+                "vision": 652,
+                "roadmap": 653,
+            },
+        }
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+# --- Control-plane inventory (read-only) ------------------------------------
+
+
+def read_control_plane_inventory(
+    *,
+    db_path: str | None = None,
+    limit: int = 200,
+) -> dict[str, Any]:
+    """Read sessions and leases for an impact evaluation, read-only.
+
+    Returns the inventory mapping
+    :func:`restart_coordinator.evaluate_restart_impact` expects.
+    ``inventory_complete`` is True only when every read succeeded, so a partial
+    read denies rather than under-reporting the blast radius.
+
+    The database is never created, migrated, or written: a missing file means
+    the console has no session authority, which is not the same as there being
+    no sessions.
+    """
+
+    path = (db_path or control_plane_db.default_db_path() or "").strip()
+    incomplete: list[str] = []
+
+    def _incomplete(reason: str) -> dict[str, Any]:
+        return {
+            "sessions": [],
+            "leases": [],
+            "terminal_lock": None,
+            "prior_recovery_attempts": [],
+            "inventory_complete": False,
+            "incomplete_reasons": [reason],
+        }
+
+    if not path:
+        return _incomplete("control-plane database path is not configured")
+    if not os.path.exists(path):
+        return _incomplete(
+            f"control-plane database not present at {redact_path(path)}; "
+            "no session or lease authority available"
+        )
+
+    try:
+        conn = sqlite3.connect(f"file:{path}?mode=ro", uri=True, timeout=5)
+        conn.row_factory = sqlite3.Row
+    except sqlite3.Error as exc:
+        return _incomplete(f"control-plane database could not be opened: {exc}")
+
+    sessions: list[dict[str, Any]] = []
+    leases: list[dict[str, Any]] = []
+    capped = max(1, int(limit))
+    try:
+        tables = {
+            str(row[0])
+            for row in conn.execute(
+                "SELECT name FROM sqlite_master WHERE type = 'table'"
+            ).fetchall()
+        }
+        if "sessions" not in tables:
+            incomplete.append("control-plane database has no sessions table")
+        else:
+            sessions = [
+                dict(row)
+                for row in conn.execute(
+                    "SELECT session_id, role, profile, pid, status,"
+                    " last_heartbeat_at FROM sessions"
+                    " WHERE status = 'active'"
+                    " ORDER BY last_heartbeat_at DESC LIMIT ?",
+                    (capped,),
+                ).fetchall()
+            ]
+
+        if "leases" not in tables:
+            incomplete.append("control-plane database has no leases table")
+        elif "work_items" not in tables:
+            incomplete.append(
+                "control-plane database has no work_items table; lease work "
+                "identity cannot be resolved"
+            )
+        else:
+            leases = [
+                dict(row)
+                for row in conn.execute(
+                    "SELECT l.lease_id, l.session_id, l.role, l.phase,"
+                    " l.status AS freshness, l.worktree_path,"
+                    " w.kind AS work_kind, w.number AS work_number"
+                    " FROM leases l"
+                    " JOIN work_items w ON w.work_item_id = l.work_item_id"
+                    " WHERE l.status = 'active'"
+                    " ORDER BY l.expires_at DESC LIMIT ?",
+                    (capped,),
+                ).fetchall()
+            ]
+    except sqlite3.Error as exc:
+        return _incomplete(f"control-plane database read failed: {exc}")
+    finally:
+        conn.close()
+
+    return {
+        "sessions": sessions,
+        "leases": leases,
+        "terminal_lock": None,
+        "prior_recovery_attempts": [],
+        "inventory_complete": not incomplete,
+        "incomplete_reasons": incomplete,
+    }
+
+
+# --- Composition ------------------------------------------------------------
+
+
+def build_restart_class_views(viewer_role: str | None) -> tuple[RestartClassView, ...]:
+    """Render the #663 class matrix, marking what this viewer may request."""
+
+    normalized = str(viewer_role or "").strip().lower()
+    views: list[RestartClassView] = []
+    for policy in restart_coordinator.RESTART_CLASS_POLICIES.values():
+        views.append(
+            RestartClassView(
+                restart_class=policy.restart_class.value,
+                required_permission=policy.required_permission,
+                expected_blast_radius=policy.expected_blast_radius,
+                drain_requirement=policy.drain_requirement,
+                full_drain_required=policy.full_drain_required,
+                approval_requirement=policy.approval_requirement,
+                request_roles=tuple(policy.request_roles),
+                execution_roles=tuple(policy.execution_roles),
+                viewer_may_request=normalized in policy.request_roles,
+                viewer_may_execute=normalized in policy.execution_roles,
+            )
+        )
+    return tuple(views)
+
+
+def build_action_authorizations(
+    principal: console_authz.Principal | None,
+) -> tuple[ActionAuthorization, ...]:
+    """Authorization state for the approval controls, asked as execution.
+
+    ``for_execution=True`` is deliberate. Asking without it answers "is this
+    principal senior enough", which is not the question an operator looking at a
+    control needs answered; asking with it answers "would this run", and while
+    the console is in Phase 1 the honest answer is no.
+    """
+
+    results: list[ActionAuthorization] = []
+    for action_id in REPORTED_ACTIONS:
+        action = console_authz.get_action(action_id)
+        decision = console_authz.authorize(action_id, principal, for_execution=True)
+        results.append(
+            ActionAuthorization(
+                action_id=action_id,
+                summary=action.summary if action else "",
+                required_role=(
+                    action.minimum_role if action else console_authz.OPERATOR
+                ),
+                allowed=bool(decision.allowed),
+                execution_enabled=bool(decision.execution_enabled),
+                reason_code=str(decision.reason_code or ""),
+                detail=str(decision.detail or ""),
+            )
+        )
+    return tuple(results)
+
+
+def viewer_is_privileged(principal: console_authz.Principal | None) -> bool:
+    """True when the viewer holds at least the operator role."""
+
+    who = principal if principal is not None else console_authz.ANONYMOUS
+    if not who.authenticated:
+        return False
+    return who.rank >= console_authz.ROLE_ORDER.index(console_authz.OPERATOR)
+
+
+def load_impact_report(
+    *,
+    principal: console_authz.Principal | None = None,
+    restart_class: str = restart_coordinator.RestartClass.FULL_MCP_RESTART.value,
+    db_path: str | None = None,
+    limit: int = 200,
+    read_inventory: Callable[..., Mapping[str, Any]] | None = None,
+    now: datetime | None = None,
+) -> tuple[dict[str, Any] | None, SourceStatus]:
+    """Evaluate the blast radius for *restart_class*, always dry-run."""
+
+    reader = read_inventory or read_control_plane_inventory
+    try:
+        inventory = dict(reader(db_path=db_path, limit=limit))
+    except Exception as exc:  # noqa: BLE001
+        return None, SourceStatus(
+            "impact",
+            STATUS_UNAVAILABLE,
+            f"control-plane inventory failed: {type(exc).__name__}: {exc}",
+        )
+
+    who = principal if principal is not None else console_authz.ANONYMOUS
+    viewer_role = str(who.role or "").strip().lower()
+    try:
+        report = restart_coordinator.evaluate_restart_impact(
+            inventory,
+            now=now,
+            dry_run=True,
+            restart_class=restart_class,
+            requester_role=viewer_role,
+            requester_permissions=restart_coordinator.permissions_for_role(
+                viewer_role
+            ),
+        )
+    except Exception as exc:  # noqa: BLE001
+        return None, SourceStatus(
+            "impact",
+            STATUS_UNAVAILABLE,
+            f"impact evaluation failed: {type(exc).__name__}: {exc}",
+        )
+
+    payload = scrub(report.as_dict())
+    detail = ""
+    if not report.inventory_complete:
+        detail = "; ".join(report.incomplete_reasons) or "inventory incomplete"
+    return payload, SourceStatus("impact", STATUS_OK, detail)
+
+
+def load_drain_status(
+    *,
+    proof: Mapping[str, Any] | None = None,
+    now: datetime | None = None,
+    expected_impact_fingerprint: str | None = None,
+) -> tuple[dict[str, Any] | None, SourceStatus]:
+    """Verify a supplied drain proof read-only and report the verdict.
+
+    No proof supplied is not a failure and not a pass: it is reported as the
+    absence of a proof, which is exactly what the #661 gate would deny on.
+    """
+
+    if proof is None:
+        return None, SourceStatus(
+            "drain",
+            STATUS_UNAVAILABLE,
+            "no drain proof supplied; the #661 gate denies a restart without a "
+            "valid unexpired clean proof",
+        )
+    try:
+        verified = drain_proof.verify_drain_proof(
+            proof,
+            now=now,
+            expected_impact_fingerprint=expected_impact_fingerprint,
+        )
+    except Exception as exc:  # noqa: BLE001
+        return None, SourceStatus(
+            "drain",
+            STATUS_UNAVAILABLE,
+            f"drain proof verification failed: {type(exc).__name__}: {exc}",
+        )
+    return scrub(verified.as_dict()), SourceStatus("drain", STATUS_OK)
+
+
+def load_reconcile_status(
+    *,
+    load_proof: Callable[[], Any] | None = None,
+) -> tuple[dict[str, Any] | None, SourceStatus]:
+    """Report the most recent post-restart completion proof (#662)."""
+
+    if load_proof is None:
+        return None, SourceStatus(
+            "reconcile",
+            STATUS_UNAVAILABLE,
+            "no post-restart completion proof source is wired into this view",
+        )
+    try:
+        proof = load_proof()
+    except Exception as exc:  # noqa: BLE001
+        return None, SourceStatus(
+            "reconcile",
+            STATUS_UNAVAILABLE,
+            f"reconcile proof unavailable: {type(exc).__name__}: {exc}",
+        )
+    if proof is None:
+        return None, SourceStatus(
+            "reconcile",
+            STATUS_UNAVAILABLE,
+            "no post-restart reconcile has been recorded",
+        )
+    payload = proof.as_dict() if hasattr(proof, "as_dict") else dict(proof)
+    return scrub(payload), SourceStatus("reconcile", STATUS_OK)
+
+
+def load_restart_console_snapshot(
+    *,
+    principal: console_authz.Principal | None = None,
+    restart_class: str = restart_coordinator.RestartClass.FULL_MCP_RESTART.value,
+    db_path: str | None = None,
+    limit: int = 200,
+    drain_proof_payload: Mapping[str, Any] | None = None,
+    read_inventory: Callable[..., Mapping[str, Any]] | None = None,
+    load_reconcile_proof: Callable[[], Any] | None = None,
+    now: datetime | None = None,
+) -> RestartConsoleSnapshot:
+    """Compose the read-only restart console snapshot."""
+
+    who = principal if principal is not None else console_authz.ANONYMOUS
+    moment = now or _utc_now()
+
+    impact, impact_source = load_impact_report(
+        principal=who,
+        restart_class=restart_class,
+        db_path=db_path,
+        limit=limit,
+        read_inventory=read_inventory,
+        now=moment,
+    )
+    fingerprint = None
+    if impact is not None:
+        try:
+            fingerprint = drain_proof.impact_fingerprint(impact)
+        except Exception:  # noqa: BLE001
+            fingerprint = None
+
+    drain, drain_source = load_drain_status(
+        proof=drain_proof_payload,
+        now=moment,
+        expected_impact_fingerprint=fingerprint,
+    )
+    reconcile, reconcile_source = load_reconcile_status(
+        load_proof=load_reconcile_proof
+    )
+
+    notes: list[str] = [
+        "This surface is read-only: it evaluates and displays, and performs no "
+        "restart, reload, drain, approval, or process action.",
+    ]
+    if not impact_source.available:
+        notes.append(
+            "Impact preview unavailable — a restart decision must not be made "
+            "from this page while the blast radius is unknown."
+        )
+
+    return RestartConsoleSnapshot(
+        generated_at=moment.isoformat(),
+        viewer_role=str(who.role or "anonymous"),
+        viewer_authenticated=bool(who.authenticated),
+        read_only=True,
+        impact=impact,
+        impact_source=impact_source,
+        drain=drain,
+        drain_source=drain_source,
+        reconcile=reconcile,
+        reconcile_source=reconcile_source,
+        restart_classes=build_restart_class_views(who.role),
+        authorizations=build_action_authorizations(who),
+        break_glass=BreakGlassSurface(
+            available=False,
+            issue=BREAK_GLASS_ISSUE,
+            reason=BREAK_GLASS_PENDING_REASON,
+            viewer_is_privileged=viewer_is_privileged(who),
+        ),
+        notes=tuple(notes),
+    )

webui/restart_views.py

@@ -0,0 +1,299 @@
+"""HTML views for the read-only restart console (#667).
+
+Every interpolated value passes through :func:`_esc`. Values that can carry a
+filesystem path or free-form operator text additionally pass through
+:func:`webui.inventory.scrub_text`, which redacts credential-shaped tokens
+*inside* a string rather than only at its start.
+
+The page renders state and never offers a control that would mutate anything:
+the approval and break-glass panels report authorization and availability, and
+there is no form, button, or endpoint behind them.
+"""
+
+from __future__ import annotations
+
+import html
+
+from webui.inventory import scrub_text
+from webui.restart_console import RestartConsoleSnapshot, SourceStatus
+
+
+def _esc(value: object) -> str:
+    """Escape any value for HTML text or a quoted attribute."""
+    if value is None:
+        return ""
+    return html.escape(str(value), quote=True)
+
+
+def _esc_text(value: object) -> str:
+    """Escape free-form text after redacting secrets embedded inside it."""
+    if value is None:
+        return ""
+    return _esc(scrub_text(str(value)))
+
+
+def _bool_badge(
+    value: bool, *, true_label: str = "yes", false_label: str = "no"
+) -> str:
+    css = "badge-ok" if value else "badge-blocked"
+    label = true_label if value else false_label
+    return f'<span class="badge {css}">{_esc(label)}</span>'
+
+
+def _source_badge(source: SourceStatus) -> str:
+    css = "badge-ok" if source.available else "badge-blocked"
+    badge = f'<span class="badge {css}">{_esc(source.status)}</span>'
+    if source.detail:
+        badge += f' <span class="muted">{_esc_text(source.detail)}</span>'
+    return badge
+
+
+def _notes_block(snapshot: RestartConsoleSnapshot) -> str:
+    if not snapshot.notes:
+        return ""
+    items = "".join(f"<li>{_esc_text(note)}</li>" for note in snapshot.notes)
+    return f"<ul class='reasons'>{items}</ul>"
+
+
+def _impact_section(snapshot: RestartConsoleSnapshot) -> str:
+    head = (
+        "<section class='health-card'>"
+        f"<h3>Impact preview {_source_badge(snapshot.impact_source)}</h3>"
+    )
+    impact = snapshot.impact
+    if impact is None:
+        return (
+            head
+            + "<p class='muted'>No impact preview is available, so the blast "
+            "radius of a restart is unknown. Treat this as unsafe.</p></section>"
+        )
+
+    counts = impact.get("counts") or {}
+    verdict = str(impact.get("verdict") or "unknown")
+    verdict_css = "badge-ok" if verdict == "safe" else "badge-blocked"
+    rows = "".join(
+        f"<tr><th>{_esc(key.replace('_', ' '))}</th><td>{_esc(value)}</td></tr>"
+        for key, value in sorted(counts.items())
+    )
+    reasons = "".join(
+        f"<li>{_esc_text(reason)}</li>" for reason in (impact.get("reasons") or [])
+    )
+    incomplete = ""
+    if not impact.get("inventory_complete", False):
+        detail = "; ".join(str(r) for r in (impact.get("incomplete_reasons") or []))
+        incomplete = (
+            "<p class='error'><strong>Inventory incomplete:</strong> "
+            f"{_esc_text(detail or 'unspecified')}. The coordinator fails "
+            "closed on an incomplete inventory.</p>"
+        )
+
+    sessions = impact.get("affected_sessions") or []
+    session_rows = "".join(
+        "<tr>"
+        f"<td><code>{_esc(s.get('session_id'))}</code></td>"
+        f"<td>{_esc(s.get('role'))}</td>"
+        f"<td>{_esc(s.get('pid'))}</td>"
+        f"<td>{_bool_badge(bool(s.get('live')), true_label='live', false_label='idle')}</td>"
+        f"<td>{_bool_badge(not s.get('heartbeat_stale'), true_label='fresh', false_label='stale')}</td>"
+        "</tr>"
+        for s in sessions[:50]
+    )
+    session_table = (
+        "<h4>Sessions a restart would terminate</h4>"
+        "<div class='table-scroll'><table class='registry'><thead><tr>"
+        "<th>Session</th><th>Role</th><th>PID</th><th>State</th>"
+        "<th>Heartbeat</th></tr></thead><tbody>"
+        f"{session_rows}</tbody></table></div>"
+        if session_rows
+        else "<p class='muted'>No affected sessions reported.</p>"
+    )
+    truncated = (
+        f"<p class='muted'>Showing the first 50 of {_esc(len(sessions))} "
+        "affected sessions.</p>"
+        if len(sessions) > 50
+        else ""
+    )
+
+    return (
+        head
+        + "<p class='health-headline'>Verdict "
+        f"<span class='badge {verdict_css}'>{_esc(verdict)}</span> · "
+        f"blast radius <code>{_esc(impact.get('blast_radius'))}</code> · "
+        f"class <code>{_esc(impact.get('restart_class'))}</code></p>"
+        + incomplete
+        + (f"<ul class='reasons'>{reasons}</ul>" if reasons else "")
+        + (f"<table class='registry'><tbody>{rows}</tbody></table>" if rows else "")
+        + session_table
+        + truncated
+        + "</section>"
+    )
+
+
+def _drain_section(snapshot: RestartConsoleSnapshot) -> str:
+    head = (
+        "<section class='health-card'>"
+        f"<h3>Drain proof {_source_badge(snapshot.drain_source)}</h3>"
+    )
+    drain = snapshot.drain
+    if drain is None:
+        return (
+            head
+            + "<p class='muted'>No drain proof has been presented to this view. "
+            "The #661 gate authorizes a restart only against a valid, unexpired, "
+            "clean proof, so the absence of one is a denial, not a pass.</p>"
+            "</section>"
+        )
+    reasons = "".join(
+        f"<li>{_esc_text(reason)}</li>" for reason in (drain.get("reasons") or [])
+    )
+    return (
+        head
+        + "<table class='registry'><tbody>"
+        f"<tr><th>Valid</th><td>{_bool_badge(bool(drain.get('valid')))}</td></tr>"
+        f"<tr><th>Clean</th><td>{_bool_badge(bool(drain.get('clean')))}</td></tr>"
+        f"<tr><th>Expired</th><td>{_bool_badge(not drain.get('expired'), true_label='no', false_label='yes')}</td></tr>"
+        f"<tr><th>Tampered</th><td>{_bool_badge(not drain.get('tampered'), true_label='no', false_label='yes')}</td></tr>"
+        f"<tr><th>Proof id</th><td><code>{_esc(drain.get('proof_id'))}</code></td></tr>"
+        "</tbody></table>"
+        + (f"<ul class='reasons'>{reasons}</ul>" if reasons else "")
+        + "</section>"
+    )
+
+
+def _reconcile_section(snapshot: RestartConsoleSnapshot) -> str:
+    head = (
+        "<section class='health-card'>"
+        f"<h3>Post-restart reconcile {_source_badge(snapshot.reconcile_source)}</h3>"
+    )
+    proof = snapshot.reconcile
+    if proof is None:
+        return (
+            head
+            + "<p class='muted'>No post-restart completion proof is recorded. "
+            "Until one is, the last restart's recovery state is unproven.</p>"
+            "</section>"
+        )
+    items = "".join(
+        "<tr>"
+        f"<td>{_esc(item.get('dimension'))}</td>"
+        f"<td>{_esc(item.get('status'))}</td>"
+        f"<td>{_esc_text(item.get('summary'))}</td>"
+        f"<td>{_bool_badge(not item.get('follow_up_required'), true_label='no', false_label='yes')}</td>"
+        "</tr>"
+        for item in (proof.get("items") or [])
+    )
+    return (
+        head
+        + "<p class='health-headline'>Status "
+        f"<code>{_esc(proof.get('overall_status'))}</code> · mode "
+        f"<code>{_esc(proof.get('mode'))}</code> · resolved "
+        f"{_esc(proof.get('resolved_count'))} · unresolved "
+        f"{_esc(proof.get('unresolved_count'))}</p>"
+        + (
+            "<div class='table-scroll'><table class='registry'><thead><tr>"
+            "<th>Dimension</th><th>Status</th><th>Summary</th>"
+            "<th>Follow-up required</th></tr></thead><tbody>"
+            f"{items}</tbody></table></div>"
+            if items
+            else "<p class='muted'>No reconcile dimensions reported.</p>"
+        )
+        + "</section>"
+    )
+
+
+def _class_matrix_section(snapshot: RestartConsoleSnapshot) -> str:
+    rows = "".join(
+        "<tr>"
+        f"<td><code>{_esc(view.restart_class)}</code></td>"
+        f"<td><code>{_esc(view.required_permission)}</code></td>"
+        f"<td>{_esc(view.expected_blast_radius)}</td>"
+        f"<td>{_esc(view.drain_requirement)}</td>"
+        f"<td>{_esc(view.approval_requirement)}</td>"
+        f"<td>{_bool_badge(view.viewer_may_request)}</td>"
+        f"<td>{_bool_badge(view.viewer_may_execute)}</td>"
+        "</tr>"
+        for view in snapshot.restart_classes
+    )
+    return (
+        "<section class='health-card'>"
+        "<h3>Restart classes</h3>"
+        "<p class='muted'>The least-privilege matrix each restart request is "
+        "resolved against. &ldquo;You may request&rdquo; and &ldquo;you may "
+        "execute&rdquo; are computed for the current viewer role, not for a "
+        "generic operator.</p>"
+        "<div class='table-scroll'><table class='registry'><thead><tr>"
+        "<th>Class</th><th>Permission</th><th>Blast radius</th>"
+        "<th>Drain</th><th>Approval</th><th>You may request</th>"
+        "<th>You may execute</th></tr></thead><tbody>"
+        f"{rows}</tbody></table></div>"
+        "</section>"
+    )
+
+
+def _approval_section(snapshot: RestartConsoleSnapshot) -> str:
+    rows = "".join(
+        "<tr>"
+        f"<td><code>{_esc(a.action_id)}</code></td>"
+        f"<td>{_esc(a.required_role)}</td>"
+        f"<td>{_bool_badge(a.allowed)}</td>"
+        f"<td>{_bool_badge(a.execution_enabled)}</td>"
+        f"<td><code>{_esc(a.reason_code)}</code></td>"
+        f"<td>{_esc_text(a.detail)}</td>"
+        "</tr>"
+        for a in snapshot.authorizations
+    )
+    return (
+        "<section class='health-card'>"
+        "<h3>Approval controls</h3>"
+        "<p class='muted'>Authorization is probed the way execution would probe "
+        "it, so &ldquo;execution enabled&rdquo; answers whether the action would "
+        "actually run — not merely whether this role outranks the requirement. "
+        "No control on this page performs the action.</p>"
+        "<div class='table-scroll'><table class='registry'><thead><tr>"
+        "<th>Action</th><th>Required role</th><th>Authorized</th>"
+        "<th>Execution enabled</th><th>Reason</th><th>Detail</th>"
+        "</tr></thead><tbody>"
+        f"{rows}</tbody></table></div>"
+        "</section>"
+    )
+
+
+def _break_glass_section(snapshot: RestartConsoleSnapshot) -> str:
+    bg = snapshot.break_glass
+    if not bg.viewer_is_privileged:
+        return (
+            "<section class='health-card'>"
+            "<h3>Break-glass</h3>"
+            "<p class='muted'>Break-glass status is visible to operator-class "
+            "roles only. Your role does not carry that authority, so no "
+            "emergency surface is shown.</p>"
+            "</section>"
+        )
+    return (
+        "<section class='health-card'>"
+        "<h3>Break-glass "
+        f"{_bool_badge(bg.available, true_label='available', false_label='unavailable')}"
+        "</h3>"
+        f"<p class='muted'>{_esc_text(bg.reason)}</p>"
+        f"<p class='meta'>Tracked by issue #{_esc(bg.issue)}.</p>"
+        "</section>"
+    )
+
+
+def render_restart_console_page(snapshot: RestartConsoleSnapshot) -> str:
+    """Render the whole read-only restart console body."""
+
+    return (
+        "<h2>Restart status and impact</h2>"
+        f"<p class='meta'>Generated <code>{_esc(snapshot.generated_at)}</code> · "
+        f"viewer role <code>{_esc(snapshot.viewer_role)}</code> · "
+        f"authenticated {_bool_badge(snapshot.viewer_authenticated)} · "
+        f"read-only {_bool_badge(snapshot.read_only)}</p>"
+        + _notes_block(snapshot)
+        + _impact_section(snapshot)
+        + _drain_section(snapshot)
+        + _reconcile_section(snapshot)
+        + _class_matrix_section(snapshot)
+        + _approval_section(snapshot)
+        + _break_glass_section(snapshot)
+    )

webui/runtime_views.py

@@ -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>"
+    )

webui/session_loader.py

@@ -0,0 +1,517 @@
+"""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. Inventory-sourced values arrive already redacted by
+:func:`webui.inventory.scrub`; free-form marker text this module loads itself is
+put through :func:`webui.inventory.scrub_text`, which collapses ``$HOME`` and
+redacts credential-shaped tokens *inside* a string rather than only at its start.
+
+Ownership columns are authority-aware. A lease or lock section that could not be
+read renders as ``unknown``, never as ``none`` or ``unbound``: a lease the reader
+could not load is not an absent lease (see
+:attr:`webui.inventory.InventorySnapshot.ownership_authority_complete`).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+import mcp_session_state
+from webui.inventory import (
+    OWNERSHIP_SECTIONS,
+    STATUS_OK,
+    InventorySection,
+    InventorySnapshot,
+    load_inventory_snapshot,
+    scrub_text,
+    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,
+)
+
+#: Status recorded on a row when the backing inventory section is absent
+#: entirely — distinct from a section that reported itself degraded.
+AUTHORITY_MISSING = "missing"
+
+
+def _section_status(section: InventorySection | None) -> str:
+    """Status of an ownership section, treating an absent section as missing."""
+    if section is None:
+        return AUTHORITY_MISSING
+    return section.status
+
+
+def _combined_authority(*statuses: str) -> str:
+    """Worst status of the sections a derived column depends on.
+
+    A column proved from two sections is only trustworthy when *both* read
+    cleanly, so the first non-``ok`` status wins.
+    """
+    for status in statuses:
+        if status != STATUS_OK:
+            return status
+    return STATUS_OK
+
+
+@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, ...] = ()
+    #: Status of the section backing ``lease_ids``/``work_refs``. While this is
+    #: not ``ok`` those tuples mean "could not be read", never "none held".
+    lease_authority: str = STATUS_OK
+    #: Worst status across the sections backing ``worktree_paths`` (locks are
+    #: correlated through lease work numbers, so both must read cleanly).
+    worktree_authority: str = STATUS_OK
+
+    @property
+    def ownership_authority_complete(self) -> bool:
+        """True only when this row's ownership columns are provable."""
+        return self.lease_authority == STATUS_OK and self.worktree_authority == STATUS_OK
+
+    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),
+            "lease_authority": self.lease_authority,
+            "worktree_authority": self.worktree_authority,
+            "lease_authority_complete": self.lease_authority == STATUS_OK,
+            "worktree_authority_complete": self.worktree_authority == STATUS_OK,
+            "ownership_authority_complete": self.ownership_authority_complete,
+            "ownership_note": (
+                "Lease and worktree columns are proved from sections that read "
+                "cleanly."
+                if self.ownership_authority_complete
+                else "An ownership source could not be read; empty lease_ids or "
+                "worktree_paths on this row mean unknown, not unowned."
+            ),
+        }
+
+
+@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"])
+
+    @property
+    def ownership_authority_complete(self) -> bool:
+        """False while any ownership section is degraded, absent, or unavailable."""
+        return self.inventory.ownership_authority_complete
+
+    @property
+    def ownership_section_status(self) -> dict[str, str]:
+        """Per-section status for the three ownership-bearing sections."""
+        return {
+            name: _section_status(self.inventory.section(name))
+            for name in OWNERSHIP_SECTIONS
+        }
+
+
+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 = scrub_text(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 = scrub_text(
+                    f"{kind}: {reason_class or 'present'}"
+                    + (" (cleared)" if cleared else "")
+                )
+
+    # Marker payloads are operator-supplied free text and are the one thing on
+    # this page that does not arrive through inventory scrubbing. The write-time
+    # redactor is a narrow denylist, so redact again at the display boundary:
+    # it leaves $HOME paths, `-H 'X-Api-Key: …'`, `--password …`, and
+    # `PRIVATE_KEY=…` intact. The field itself stays — it is #630 evidence.
+    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=scrub_text(str(reason_class)) if reason_class else None,
+        session_id=scrub_text(str(session_id)) if session_id else None,
+        role=scrub_text(str(role)) if role else None,
+        command_summary=scrub_text(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")
+
+    # Ownership columns may only assert absence when their source read cleanly.
+    lease_authority = _section_status(leases_section)
+    # Locks carry claimant profile/username, not control-plane session ids, so a
+    # worktree binding is correlated through lease work numbers: it depends on
+    # the locks *and* the leases section.
+    worktree_authority = _combined_authority(
+        lease_authority, _section_status(locks_section)
+    )
+
+    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)
+
+    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)),
+                lease_authority=lease_authority,
+                worktree_authority=worktree_authority,
+            )
+        )
+
+    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,
+        },
+        "ownership_authority_complete": snapshot.ownership_authority_complete,
+        "ownership_section_status": snapshot.ownership_section_status,
+        "ownership_note": (
+            "Every ownership source read cleanly; a session with no lease and no "
+            "worktree path genuinely holds neither."
+            if snapshot.ownership_authority_complete
+            else "An ownership source is degraded or unavailable. Empty lease_ids "
+            "and worktree_paths mean unknown, not unowned; consult each row's "
+            "lease_authority and worktree_authority."
+        ),
+        "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": [],
+    }

webui/session_views.py

@@ -0,0 +1,403 @@
+"""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.inventory import STATUS_OK
+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 _unproven_cell(status: str) -> str:
+    """Render an ownership column whose backing inventory section failed to read.
+
+    Never "none" and never "unbound": an unreadable source proves nothing about
+    ownership, and claiming otherwise is the exact failure the
+    ``ownership_authority_complete`` invariant exists to prevent.
+    """
+    return (
+        f'<span class="muted">unknown (inventory {escape(status)})</span><br>'
+        f'{_badge("authority unproven", "badge-health-degraded")}'
+    )
+
+
+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
+    authority_complete = snapshot.ownership_authority_complete
+    authority_text = "complete" if authority_complete else "incomplete"
+    authority_css = "badge-health-ok" if authority_complete else "badge-health-degraded"
+    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><strong>Ownership authority:</strong> <span class="badge {authority_css}">{authority_text}</span></div>
+</div>"""
+
+
+def _ownership_caveat(snapshot: SessionViewSnapshot) -> str:
+    """Name the unreadable ownership sections, or render nothing when all read."""
+    if snapshot.ownership_authority_complete:
+        return ""
+    degraded = ", ".join(
+        f"{name}: {status}"
+        for name, status in snapshot.ownership_section_status.items()
+        if status != STATUS_OK
+    )
+    return (
+        '<div class="health-card health-stale">'
+        "<strong>Ownership authority incomplete:</strong> "
+        f"{escape(degraded)}. Columns marked <em>unknown</em> could not be read. "
+        "No session below may be treated as holding no lease or no worktree "
+        "binding — absence of evidence is not evidence of absence.</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")
+    )
+    # An empty tuple only means "holds none" when its source read cleanly.
+    if row.lease_authority != STATUS_OK:
+        lease_cell = _unproven_cell(row.lease_authority)
+    else:
+        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>'
+        )
+        lease_cell = (
+            f'{leases}<div class="muted" style="font-size:0.82rem; '
+            f'margin-top:0.2rem;">{work}</div>'
+        )
+
+    if row.worktree_authority != STATUS_OK:
+        worktrees = _unproven_cell(row.worktree_authority)
+    else:
+        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>{lease_cell}</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(snapshot: SessionViewSnapshot) -> str:
+    rows: Sequence[SessionRow] = snapshot.sessions
+    if not rows:
+        sessions_status = snapshot.ownership_section_status.get("sessions", STATUS_OK)
+        if sessions_status != STATUS_OK:
+            return (
+                '<p class="muted">Session inventory is '
+                f"<strong>{escape(sessions_status)}</strong> — the session list "
+                "could not be read. This is not evidence that no sessions "
+                "exist.</p>"
+            )
+        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.
+  Lease and worktree columns read <em>unknown (inventory …)</em> when their source could not be loaded.</p>
+  {_ownership_caveat(snapshot)}
+  {_sessions_table(snapshot)}
+</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}""")

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.</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>"