Merge master into feat/issue-639-webui-system-health-dashboard

Resolve the #638 shell landing against the #639 dashboard:

- webui/layout.py: drop the flat NAV_ITEMS tuple in favor of master's
  grouped NAV_GROUPS nav-config module.
- webui/nav.py: register /system-health as a live item in the Health
  group, satisfying issue #639 AC5 through the canonical nav source.
- docs/webui-local-dev.md: keep both additive sections (#638 shell and
  #639 dashboard).
- tests/test_webui_system_health_dashboard.py: assert the nav entry via
  iter_nav_items() instead of the removed NAV_ITEMS tuple.

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

allocator_service.py

@@ -1216,6 +1216,12 @@ def allocate_next_work(
             "reasons": [
                 "dry-run only (apply=false); no assignment/lease created — "
                 "call again with apply=true to reserve via control-plane DB"
+                + (
+                    "; after apply, the required-role worker consumes via "
+                    "gitea_adopt_workflow_lease (#843)"
+                    if mode == ALLOCATION_MODE_CROSS_ROLE and expected_role != role_norm
+                    else ""
+                )
             ],
             "skipped": [s.as_dict() for s in skipped],
             "terminal_pr": terminal_pr,
@@ -1247,6 +1253,9 @@ def allocate_next_work(
     # Atomic reserve via #613 substrate.
     ttl = lease_ttl_seconds if lease_ttl_seconds is not None else None
     try:
+        cross_role_handoff = (
+            mode == ALLOCATION_MODE_CROSS_ROLE and lease_role != role_norm
+        )
         kwargs: dict[str, Any] = {
             "session_id": session_id,
             "role": lease_role,
@@ -1258,7 +1267,8 @@ def allocate_next_work(
             "expected_head_sha": selected.head_sha,
             "allowed_actions": allowed,
             "forbidden_actions": forbidden,
-            "phase": "allocated",
+            # #843: mark cross-role allocations as awaiting independent consume
+            "phase": "awaiting_handoff" if cross_role_handoff else "allocated",
         }
         if ttl is not None:
             kwargs["lease_ttl_seconds"] = int(ttl)
@@ -1338,7 +1348,52 @@ def allocate_next_work(
         "lease_role": lease_role,
         "source": "control_plane_db.assign_and_lease",
     }
-    return {
+    consume_allocation = None
+    if cross_role_handoff and result.lease_id:
+        # Durable handoff marker so independent required-role workers can
+        # consume without sharing the controller session (#843).
+        handoff_prov = {
+            "cross_role_handoff": True,
+            "handoff_status": "pending",
+            "allocating_session_id": session_id,
+            "allocating_role": role_norm,
+            "required_role": expected_role,
+            "required_profile": selection["required_profile"],
+            "required_namespace": selection["required_namespace"],
+            "assignment_id": result.assignment_id,
+            "lease_id": result.lease_id,
+            "allocation_mode": mode,
+            "adopted_by_session_id": None,
+        }
+        try:
+            db.attach_lease_provenance(result.lease_id, handoff_prov)
+        except ControlPlaneError:
+            # Still return assignment evidence; consume path may be unavailable
+            handoff_prov["attach_failed"] = True
+        consume_allocation = {
+            "tool": "gitea_adopt_workflow_lease",
+            "lease_id": result.lease_id,
+            "assignment_id": result.assignment_id,
+            "required_role": expected_role,
+            "required_profile": selection["required_profile"],
+            "required_namespace": selection["required_namespace"],
+            "handoff_status": "pending",
+            "controller_session_required": False,
+            "instructions": (
+                f"From an independent {expected_role} session "
+                f"({selection['required_namespace']} / "
+                f"{selection['required_profile']}), call "
+                f"gitea_adopt_workflow_lease(lease_id={result.lease_id!r}) "
+                "to consume this controller allocation. The allocating "
+                "controller process does not need to remain alive. Wrong-role "
+                "and second-adoption attempts fail closed."
+            ),
+        }
+        lease_proof["cross_role_handoff"] = True
+        lease_proof["handoff_status"] = "pending"
+        lease_proof["consume_tool"] = "gitea_adopt_workflow_lease"
+
+    out = {
         "success": True,
         "outcome": OUTCOME_ASSIGNED,
         "apply": True,
@@ -1372,8 +1427,17 @@ def allocate_next_work(
             "lease_role": lease_role,
             "lease_proof": lease_proof,
             "selection_policy": SELECTION_POLICY,
+            "cross_role_handoff": bool(cross_role_handoff),
         },
-        "next_valid_command": _next_command(lease_role, selected),
+        "next_valid_command": (
+            (
+                f"consume lease {result.lease_id} via gitea_adopt_workflow_lease "
+                f"as {expected_role}, then "
+            )
+            + _next_command(lease_role, selected)
+            if cross_role_handoff
+            else _next_command(lease_role, selected)
+        ),
         "substrate": "control_plane_db",
         "file_lock_only": False,
         "comment_lease_only": False,
@@ -1388,9 +1452,14 @@ def allocate_next_work(
         "downstream_note": (
             "#612 incident bridge remains downstream of #600; "
             "allocator never assigns raw monitoring incidents; "
-            "controller routes only under cross_role (#840)"
+            "controller routes only under cross_role (#840); "
+            "cross-role assignments are consumable by independent "
+            "required-role workers via gitea_adopt_workflow_lease (#843)"
         ),
     }
+    if consume_allocation is not None:
+        out["consume_allocation"] = consume_allocation
+    return out
 
 
 def _next_command(role: str, c: WorkCandidate) -> str:

control_plane_db.py

@@ -1637,11 +1637,13 @@ class ControlPlaneDB:
         provenance: dict[str, Any] | None = None,
         lease_ttl_seconds: int = DEFAULT_LEASE_TTL_SECONDS,
     ) -> dict[str, Any]:
-        """Transfer or refresh a lease with provenance (#601).
+        """Transfer or refresh a lease with provenance (#601 / #843).
 
         * Same owner + active → refresh (owner-resume).
+        * Cross-role handoff pending + matching required role → atomic consume
+          (even while the allocating controller session still "owns" the lease).
         * Expired/abandoned/released → create new assignment+lease with provenance.
-        * Active foreign → raise ForeignLeaseError (never silent steal).
+        * Active foreign (non-handoff) → raise ForeignLeaseError (never silent steal).
         """
         now = _utc_now()
         now_s = _ts(now)
@@ -1677,7 +1679,35 @@ class ControlPlaneDB:
                 status = "expired"
 
             owner = lease["session_id"]
-            if status == "active" and owner != adopter_session_id:
+            # Parse durable provenance for cross-role handoff consume (#843).
+            lease_prov: dict[str, Any] = {}
+            if "provenance_json" in lease.keys() and lease["provenance_json"]:
+                try:
+                    loaded = json.loads(lease["provenance_json"])
+                    if isinstance(loaded, dict):
+                        lease_prov = loaded
+                except (TypeError, json.JSONDecodeError):
+                    lease_prov = {}
+            handoff_pending = bool(lease_prov.get("cross_role_handoff")) and (
+                str(lease_prov.get("handoff_status") or "pending").strip().lower()
+                == "pending"
+            )
+            already_adopted = bool(
+                (lease["adopted_by_session_id"] if "adopted_by_session_id" in lease.keys() else None)
+                or lease_prov.get("adopted_by_session_id")
+            )
+            required_role = str(
+                lease_prov.get("required_role") or lease["role"] or ""
+            ).strip().lower()
+            adopter_role = (role or "").strip().lower()
+            cross_role_consume = (
+                handoff_pending
+                and not already_adopted
+                and status == "active"
+                and owner != adopter_session_id
+            )
+
+            if status == "active" and owner != adopter_session_id and not cross_role_consume:
                 raise ForeignLeaseError(
                     f"cannot adopt active foreign lease {lease_id} owned by {owner}"
                 )
@@ -1761,6 +1791,142 @@ class ControlPlaneDB:
                     "reasons": ["owner-resume: refreshed lease with provenance"],
                 }
 
+            # #843: controller→required-role handoff consume (atomic, same lease_id)
+            if cross_role_consume:
+                if not required_role:
+                    raise ControlPlaneError(
+                        f"cross-role handoff lease {lease_id} missing required_role"
+                    )
+                if adopter_role != required_role:
+                    raise ForeignLeaseError(
+                        f"wrong role for cross-role handoff consume: "
+                        f"required={required_role} adopter={adopter_role or 'none'} "
+                        f"(fail closed)"
+                    )
+                # CAS: only transfer if still owned by allocating session and unadopted
+                cols = self._lease_columns(conn)
+                adopted_col_null = (
+                    "(adopted_by_session_id IS NULL OR adopted_by_session_id = '')"
+                    if "adopted_by_session_id" in cols
+                    else "1=1"
+                )
+                cas = conn.execute(
+                    f"""
+                    UPDATE leases
+                    SET session_id = ?,
+                        heartbeat_at = ?,
+                        expires_at = ?,
+                        phase = ?,
+                        role = ?
+                    WHERE lease_id = ?
+                      AND status = 'active'
+                      AND session_id = ?
+                      AND {adopted_col_null}
+                    """,
+                    (
+                        adopter_session_id,
+                        now_s,
+                        expires,
+                        "adopted",
+                        required_role,
+                        lease_id,
+                        owner,
+                    ),
+                )
+                if cas.rowcount != 1:
+                    raise ForeignLeaseError(
+                        f"cross-role handoff consume lost race for lease {lease_id} "
+                        "(already adopted or no longer pending; fail closed)"
+                    )
+                if "adopted_from_session_id" in cols:
+                    conn.execute(
+                        """
+                        UPDATE leases
+                        SET adopted_from_session_id = ?, adopted_by_session_id = ?
+                        WHERE lease_id = ?
+                        """,
+                        (owner, adopter_session_id, lease_id),
+                    )
+                if "worktree_path" in cols and worktree_path:
+                    conn.execute(
+                        "UPDATE leases SET worktree_path = ? WHERE lease_id = ?",
+                        (worktree_path, lease_id),
+                    )
+                if "owner_pid" in cols and owner_pid is not None:
+                    conn.execute(
+                        "UPDATE leases SET owner_pid = ? WHERE lease_id = ?",
+                        (owner_pid, lease_id),
+                    )
+                if "expected_head_sha" in cols and expected_head_sha:
+                    conn.execute(
+                        "UPDATE leases SET expected_head_sha = ? WHERE lease_id = ?",
+                        (expected_head_sha, lease_id),
+                    )
+                # Merge handoff provenance + caller provenance
+                merged = dict(lease_prov)
+                merged.update(provenance or {})
+                merged["cross_role_handoff"] = True
+                merged["handoff_status"] = "adopted"
+                merged["adopted_from_session_id"] = owner
+                merged["adopted_by_session_id"] = adopter_session_id
+                merged["required_role"] = required_role
+                if "provenance_json" in cols:
+                    conn.execute(
+                        "UPDATE leases SET provenance_json = ? WHERE lease_id = ?",
+                        (json.dumps(merged), lease_id),
+                    )
+                # Transfer active assignment ownership atomically
+                asn_cas = conn.execute(
+                    """
+                    UPDATE assignments
+                    SET session_id = ?, role = ?
+                    WHERE lease_id = ? AND status = 'active' AND session_id = ?
+                    """,
+                    (adopter_session_id, required_role, lease_id, owner),
+                )
+                if asn_cas.rowcount < 1:
+                    # Fail closed: assignment must move with the lease
+                    raise ControlPlaneError(
+                        f"cross-role handoff: no active assignment for lease {lease_id} "
+                        f"owned by {owner}"
+                    )
+                lease2 = conn.execute(
+                    "SELECT * FROM leases WHERE lease_id = ?", (lease_id,)
+                ).fetchone()
+                asn = conn.execute(
+                    """
+                    SELECT * FROM assignments
+                    WHERE lease_id = ? AND status = 'active'
+                    ORDER BY created_at DESC LIMIT 1
+                    """,
+                    (lease_id,),
+                ).fetchone()
+                conn.execute(
+                    """
+                    INSERT INTO events(work_item_id, event_type, message, created_at)
+                    VALUES (?, 'lease_adopted', ?, ?)
+                    """,
+                    (
+                        lease["work_item_id"],
+                        f"cross-role handoff: {adopter_session_id} consumed "
+                        f"{lease_id} from {owner} as {required_role}",
+                        now_s,
+                    ),
+                )
+                return {
+                    "outcome": "adopted_cross_role_handoff",
+                    "lease": dict(lease2) if lease2 else dict(lease),
+                    "assignment": dict(asn) if asn else None,
+                    "reasons": [
+                        "cross-role handoff: independent required-role worker consumed "
+                        "controller allocation without abandonment"
+                    ],
+                    "adopted_by_session_id": adopter_session_id,
+                    "adopted_from_session_id": owner,
+                    "required_role": required_role,
+                    "handoff_status": "adopted",
+                }
+
             # Non-active: create new lease + assignment (transfer)
             new_lease_id = f"lease-{uuid.uuid4().hex[:16]}"
             new_asn_id = f"asn-{uuid.uuid4().hex[:16]}"

docs/webui-local-dev.md

@@ -54,6 +54,7 @@ status, onboarding checklist state, and the fail-closed error payloads (#635).
 | `/` | Home / operator overview |
 | `/health` | JSON liveness (`status`, `service`, `mode`, `timestamp`, `uptime_seconds`) |
 | `/api/v1/system/health` | Structured read-only system health (#634) |
+| `/system-health` | System-health dashboard — readiness, version/uptime, dependencies, MCP namespaces, stale-runtime parity (#639) |
 | `/queue` | Live PR and issue queue dashboard (#429) |
 | `/api/queue` | JSON queue export with pagination metadata |
 | `/projects` | Project registry list with status and onboarding progress (#427, #635) |
@@ -74,6 +75,11 @@ 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) |
+| `/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 |
+| `/insights` | Phase 1 shell stub — operational insights placeholder |
 
 Most routes are GET-only. POST/PUT/PATCH/DELETE return `405` with
 `read-only-mvp`, except `/audit` and `/api/audit` which accept POST for
@@ -233,6 +239,57 @@ health, workflow/schema SHA-256 hashes, and stale-runtime warnings when the
 checkout is behind merged safety-gate changes. Restart guidance links to #420;
 no tokens or MCP restart actions are exposed.
 
+## Application shell — Phase 1 (#638)
+
+The console shell (`webui/layout.py`) renders a grouped navigation driven by a
+single nav-config module, `webui/nav.py`. Nav groups follow the epic #631
+Phase 1 information architecture: **Health, Traffic, Runtime/Sessions,
+Projects, Inventory, Timeline, Policy** (placeholder), and **Insights**
+(placeholder). Live views and Phase 1 placeholders (`stub`) are declared in one
+place so the layout and the route table cannot drift.
+
+The header carries two read-only status badges — an **environment** badge
+(`local` for loopback binds, `remote` otherwise, derived from `WEBUI_HOST`) and
+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`.
+
+## System-health dashboard (#639)
+
+`/system-health` renders the same snapshot the `/api/v1/system/health` API
+returns, so the page and the API can never disagree. Cards: overall readiness,
+stale-runtime parity, version and uptime, dependency probes, MCP namespaces,
+probe errors (only when present), and recovery pointers. `?deep=1` opts into
+the network probe exactly as the API does; the plain page load stays cheap.
+
+Field authority and honesty rules:
+
+* `ready` and `readiness_complete` are shown separately. A snapshot whose
+  required probes never ran is not the same as one that ran them and passed,
+  and the page never collapses the two into an unproven green.
+* A probe that did not run appears under **Not probed**, never as healthy.
+* `stale_runtime.mutation_safe` is displayed verbatim from the API. When the
+  runtime is stale, or when parity is indeterminate, the page warns and does
+  not claim mutation safety.
+* MCP namespaces are reported `unproven`: the web process runs outside the
+  IDE-managed MCP client and cannot prove that path (#543).
+
+Redaction is split by field kind. Free text — probe details, readiness and
+parity reasons, probe errors — passes through `system_health.redact`.
+Structured fields — commit SHAs, probe names, statuses, timestamps — are
+HTML-escaped only, because `redact`'s opaque-token rule matches any run of 32
+or more characters and would otherwise blank every 40-character git SHA, which
+is precisely the evidence the parity view exists to show.
+
+The dashboard is read-only: no restart, reload, or process-kill control. Those
+arrive in Phase 2 (#642). Recovery guidance points at the sanctioned client
+reconnect / operator restart path — never a manual daemon kill (#630).
+
 ## Deployment boundary (#435)
 
 MVP serves on loopback by default. Binding `0.0.0.0` or `::` is **refused**

gitea_mcp_server.py

@@ -11242,127 +11242,163 @@ def gitea_reconcile_merged_cleanups(
     if dry_run:
         report["dry_run"] = True
         report["executed"] = False
+        # #851: surface planned lifecycle order so dry-run matches execute.
+        report["planned_execution_orders"] = {
+            str(entry.get("pr_number")): entry.get("planned_execution_order") or []
+            for entry in (report.get("entries") or [])
+        }
         return {"success": True, "performed": False, **report}
 
     verify_preflight_purity(
         remote, task="reconcile_merged_cleanups", org=org, repo=repo
     )
     actions: list[dict] = []
+    project_root = _canonical_local_git_root()
+
+    def _ownership_records_for_branch(
+        head_branch: str, pr_num_int: int | None
+    ) -> list[dict]:
+        ownership_bundle = _collect_branch_ownership_records(
+            remote=remote,
+            host=h,
+            org=o,
+            repo=r,
+            branch=head_branch,
+            pr_number=pr_num_int,
+            project_root=project_root,
+            auth=auth,
+            base_api=base,
+        )
+        ownership_records = list(ownership_bundle.get("records") or [])
+        if ownership_bundle.get("inventory_error"):
+            ownership_records.append(
+                {
+                    "category": (
+                        branch_cleanup_guard.OWNERSHIP_CATEGORY_INVENTORY_ERROR
+                    ),
+                    "status": "unknown",
+                    "remote": remote,
+                    "host": h,
+                    "org": o,
+                    "repo": r,
+                    "branch": head_branch,
+                    "reclaim_allowed": False,
+                    "role": "inventory",
+                }
+            )
+        return ownership_records
+
+    def _attempt_owned_remote_delete(
+        *,
+        head_branch: str,
+        pr_num_int: int | None,
+        after_worktree_removal: bool = False,
+    ) -> dict:
+        """Fail-closed remote delete with live ownership reassessment (#851)."""
+        import urllib.parse
+
+        ownership_records = _ownership_records_for_branch(head_branch, pr_num_int)
+        ownership = branch_cleanup_guard.assess_active_branch_ownership(
+            remote=remote,
+            org=o,
+            repo=r,
+            branch=head_branch,
+            host=h,
+            records=ownership_records,
+        )
+        if ownership.get("block"):
+            return {
+                "action": "delete_remote_branch",
+                "branch": head_branch,
+                "success": False,
+                "performed": False,
+                "delete_acknowledged": False,
+                "verified_absent": False,
+                "blocker_kind": "active_branch_ownership",
+                "reasons": ownership.get("reasons") or [],
+                "blocking_categories": ownership.get("blocking_categories") or [],
+                "after_worktree_removal": after_worktree_removal,
+                "ownership_reassessed": after_worktree_removal,
+            }
+
+        encoded = urllib.parse.quote(head_branch, safe="")
+        url = f"{base}/branches/{encoded}"
+        with _audited(
+            "delete_branch",
+            host=h,
+            remote=remote,
+            org=o,
+            repo=r,
+            target_branch=head_branch,
+            request_metadata={
+                "branch": head_branch,
+                "source": "reconcile_merged_cleanups",
+                "ownership_checked": True,
+                "after_worktree_removal": after_worktree_removal,
+            },
+        ):
+            api_request("DELETE", url, auth)
+        readback = _probe_remote_branch(h, o, r, auth, head_branch)
+        readback_assessment = branch_cleanup_guard.assess_post_delete_readback(
+            readback
+        )
+        verified = bool(readback_assessment.get("verified_absent"))
+        return {
+            "action": "delete_remote_branch",
+            "branch": head_branch,
+            "success": bool(readback_assessment.get("ok")),
+            "performed": True,
+            "delete_acknowledged": True,
+            "verified_absent": verified,
+            "readback": readback_assessment.get("readback"),
+            "reasons": readback_assessment.get("reasons") or [],
+            "after_worktree_removal": after_worktree_removal,
+            "ownership_reassessed": after_worktree_removal,
+        }
+
     for entry in report.get("entries") or []:
         head_branch = entry.get("head_branch") or ""
         remote_assessment = entry.get("remote_branch") or {}
         local_assessment = entry.get("local_worktree") or {}
+        pr_num = entry.get("pr_number")
+        try:
+            pr_num_int = int(pr_num) if pr_num is not None else None
+        except (TypeError, ValueError):
+            pr_num_int = None
 
-        if remote_assessment.get("safe_to_delete_remote"):
-            import urllib.parse
-
-            pr_num = entry.get("pr_number")
-            try:
-                pr_num_int = int(pr_num) if pr_num is not None else None
-            except (TypeError, ValueError):
-                pr_num_int = None
-            ownership_bundle = _collect_branch_ownership_records(
-                remote=remote,
-                host=h,
-                org=o,
-                repo=r,
-                branch=head_branch,
-                pr_number=pr_num_int,
-                project_root=_canonical_local_git_root(),
-                auth=auth,
-                base_api=base,
-            )
-            ownership_records = list(ownership_bundle.get("records") or [])
-            if ownership_bundle.get("inventory_error"):
-                ownership_records.append(
-                    {
-                        "category": (
-                            branch_cleanup_guard.OWNERSHIP_CATEGORY_INVENTORY_ERROR
-                        ),
-                        "status": "unknown",
-                        "remote": remote,
-                        "host": h,
-                        "org": o,
-                        "repo": r,
-                        "branch": head_branch,
-                        "reclaim_allowed": False,
-                        "role": "inventory",
-                    }
-                )
-            ownership = branch_cleanup_guard.assess_active_branch_ownership(
-                remote=remote,
-                org=o,
-                repo=r,
-                branch=head_branch,
-                host=h,
-                records=ownership_records,
-            )
-            if ownership.get("block"):
-                actions.append(
-                    {
-                        "action": "delete_remote_branch",
-                        "branch": head_branch,
-                        "success": False,
-                        "performed": False,
-                        "delete_acknowledged": False,
-                        "verified_absent": False,
-                        "blocker_kind": "active_branch_ownership",
-                        "reasons": ownership.get("reasons") or [],
-                        "blocking_categories": ownership.get(
-                            "blocking_categories"
-                        )
-                        or [],
-                    }
-                )
-                continue
-
-            encoded = urllib.parse.quote(head_branch, safe="")
-            url = f"{base}/branches/{encoded}"
-            with _audited(
-                "delete_branch",
-                host=h,
-                remote=remote,
-                org=o,
-                repo=r,
-                target_branch=head_branch,
-                request_metadata={
-                    "branch": head_branch,
-                    "source": "reconcile_merged_cleanups",
-                    "ownership_checked": True,
-                },
-            ):
-                api_request("DELETE", url, auth)
-            readback = _probe_remote_branch(h, o, r, auth, head_branch)
-            readback_assessment = branch_cleanup_guard.assess_post_delete_readback(
-                readback
-            )
-            verified = bool(readback_assessment.get("verified_absent"))
-            actions.append(
-                {
-                    "action": "delete_remote_branch",
-                    "branch": head_branch,
-                    "success": bool(readback_assessment.get("ok")),
-                    "performed": True,
-                    "delete_acknowledged": True,
-                    "verified_absent": verified,
-                    "readback": readback_assessment.get("readback"),
-                    "reasons": readback_assessment.get("reasons") or [],
-                }
-            )
-
+        # #851 lifecycle: when the target worktree is independently safe, remove
+        # it first so worktree_binding ownership does not permanently strand
+        # both the worktree and the remote branch. Never skip worktree removal
+        # merely because remote delete would be blocked by that binding.
+        # Ownership protection for remote delete remains fail-closed below.
+        worktree_removed = False
         if local_assessment.get("safe_to_remove_worktree"):
             result = merged_cleanup_reconcile.remove_local_worktree(
-                _canonical_local_git_root(),
+                project_root,
                 head_branch,
                 worktree_path=local_assessment.get("worktree_path"),
             )
             actions.append({"action": "remove_local_worktree", **result})
+            # Idempotent resume: absent worktree is already gone.
+            msg = (result.get("message") or "").lower()
+            worktree_removed = bool(result.get("success")) or (
+                "not found" in msg
+            )
+
+        if remote_assessment.get("safe_to_delete_remote"):
+            actions.append(
+                _attempt_owned_remote_delete(
+                    head_branch=head_branch,
+                    pr_num_int=pr_num_int,
+                    after_worktree_removal=worktree_removed,
+                )
+            )
 
     for scratch in report.get("reviewer_scratch_entries") or []:
         if not scratch.get("safe_to_remove_worktree"):
             continue
         result = merged_cleanup_reconcile.remove_reviewer_scratch_worktree(
-            _canonical_local_git_root(), scratch.get("worktree_path") or ""
+            project_root, scratch.get("worktree_path") or ""
         )
         actions.append({"action": "remove_reviewer_scratch_worktree", **result})
 
@@ -21149,10 +21185,21 @@ def gitea_adopt_workflow_lease(
     remote: str = "dadeschools",
     host: str | None = None,
 ) -> dict:
-    """Adopt a control-plane lease through the sanctioned path (#601).
+    """Adopt a control-plane lease through the sanctioned path (#601 / #843).
 
-    Same-owner resume refreshes provenance. Foreign active leases are refused.
-    Expired leases may be reclaimed; provenance records adopted_from/by.
+    Same-owner resume refreshes provenance. Foreign active leases are refused
+    unless the lease is a pending controller cross-role handoff and the caller
+    holds the required role (independent consume without sharing the
+    controller session). Expired leases may be reclaimed; provenance records
+    adopted_from/by. Terminal (abandoned/released) leases cannot be adopted.
+
+    #843 F1: the adopter role is derived authoritatively from the active
+    authenticated profile — never from caller input. A supplied ``role`` that
+    does not exactly match the profile-derived role is rejected (no silent
+    accept or reinterpretation), and handoff provenance ``required_profile`` /
+    ``required_namespace`` restrictions are validated against the same
+    authoritative caller context. Caller-supplied role/profile/namespace can
+    never grant authority.
     """
     read_block = _profile_operation_gate("gitea.read")
     if read_block:
@@ -21161,25 +21208,64 @@ def gitea_adopt_workflow_lease(
             "reasons": read_block,
             "permission_report": _permission_block_report("gitea.read"),
         }
+    profile = get_profile()
+    profile_name = (profile.get("profile_name") or "").strip() or "session"
+    active_role = (_profile_role_kind(profile) or "").strip().lower()
+    if not active_role:
+        return {
+            "success": False,
+            "outcome": "blocked",
+            "mutation_performed": False,
+            "reasons": [
+                "active profile role could not be derived authoritatively; "
+                "refusing lease adoption (fail closed, #843)"
+            ],
+            "lease_id": lease_id,
+            "authoritative_source": "control_plane_db",
+            "file_lock_only": False,
+            "comment_lease_only": False,
+        }
+    if role is not None and str(role).strip():
+        supplied_role = str(role).strip().lower()
+        if supplied_role != active_role:
+            return {
+                "success": False,
+                "outcome": "blocked",
+                "mutation_performed": False,
+                "profile_role_kind": active_role,
+                "supplied_role": supplied_role,
+                "reasons": [
+                    f"caller-supplied role '{supplied_role}' does not match "
+                    f"the authenticated profile-derived role '{active_role}'; "
+                    "caller-supplied role/profile/namespace can never grant "
+                    "authority (fail closed, #843)"
+                ],
+                "lease_id": lease_id,
+                "authoritative_source": "control_plane_db",
+                "file_lock_only": False,
+                "comment_lease_only": False,
+            }
     db, errs = _control_plane_db_or_error()
     if db is None:
         return {"success": False, "reasons": errs}
-    profile = get_profile()
-    profile_name = (profile.get("profile_name") or "").strip() or "session"
-    active_role = _profile_role_kind(profile) or "author"
     sid = (session_id or "").strip() or (
         f"{profile_name}-{os.getpid()}-{uuid.uuid4().hex[:8]}"
     )
+    adopter_namespace = allocator_service.DEFAULT_ROLE_NAMESPACES.get(
+        active_role, f"gitea-{active_role}"
+    )
     try:
         return lease_lifecycle.adopt_lease(
             db,
             lease_id=lease_id,
             adopter_session_id=sid,
-            role=(role or active_role).strip() or "author",
+            role=active_role,
             worktree_path=worktree_path,
             expected_head_sha=expected_head_sha,
             owner_pid=os.getpid(),
             operator_authorized=bool(operator_authorized),
+            adopter_profile_name=profile_name,
+            adopter_namespace=adopter_namespace,
         )
     except (lease_lifecycle.LeaseLifecycleError, control_plane_db.ControlPlaneError) as exc:
         return {

lease_lifecycle.py

@@ -39,6 +39,7 @@ SAFE_RELEASE_OWNED = "release_owned"
 SAFE_STALE_PROMPT = "stale_prompt_lease"
 SAFE_UNKNOWN = "inspect_only"
 SAFE_NO_AUTHORITY = "file_or_comment_not_authoritative"
+SAFE_CONSUME_CROSS_ROLE = "consume_cross_role_handoff"
 
 LEASE_STATUS_ACTIVE = "active"
 LEASE_STATUS_RELEASED = "released"
@@ -250,6 +251,23 @@ def decide_safe_next_action(
                 "same_owner": True,
                 "also_allowed": [SAFE_ABANDON_ALLOWED, SAFE_RELEASE_OWNED],
             }
+        handoff = is_pending_cross_role_handoff({"lease": lease})
+        if handoff:
+            return {
+                "safe_next_action": SAFE_CONSUME_CROSS_ROLE,
+                "reasons": [
+                    f"controller allocation pending handoff (freshness={status}); "
+                    "required-role worker may consume without abandon/reassign; "
+                    f"required_role={handoff['required_role']}"
+                ],
+                "block": False,
+                "same_owner": False,
+                "owner_session_id": owner,
+                "required_role": handoff["required_role"],
+                "cross_role_handoff": True,
+                "handoff_status": "pending",
+                "also_allowed": [SAFE_ABANDON_ALLOWED],
+            }
         return {
             "safe_next_action": SAFE_ABANDON_ALLOWED,
             "reasons": [
@@ -272,6 +290,24 @@ def decide_safe_next_action(
         }
 
     if not same_owner and status == "active":
+        # #843: pending cross-role handoff is consumable by required role
+        handoff = is_pending_cross_role_handoff({"lease": lease})
+        if handoff:
+            return {
+                "safe_next_action": SAFE_CONSUME_CROSS_ROLE,
+                "reasons": [
+                    "controller cross-role allocation pending handoff; "
+                    f"required_role={handoff['required_role']}; "
+                    "consume via gitea_adopt_workflow_lease without "
+                    "abandonment or sharing the controller session"
+                ],
+                "block": False,
+                "same_owner": False,
+                "owner_session_id": owner,
+                "required_role": handoff["required_role"],
+                "cross_role_handoff": True,
+                "handoff_status": "pending",
+            }
         return {
             "safe_next_action": SAFE_WAIT_FOREIGN,
             "reasons": [
@@ -440,6 +476,84 @@ def list_active_leases(
     }
 
 
+
+def parse_lease_provenance(lease_or_state: Mapping[str, Any] | None) -> dict[str, Any]:
+    """Return durable lease provenance dict (empty when absent/unparseable)."""
+    if not lease_or_state:
+        return {}
+    if "provenance" in lease_or_state and isinstance(lease_or_state.get("provenance"), dict):
+        return dict(lease_or_state["provenance"])
+    raw = None
+    if "provenance_json" in lease_or_state:
+        raw = lease_or_state.get("provenance_json")
+    elif "lease" in lease_or_state and isinstance(lease_or_state.get("lease"), Mapping):
+        raw = lease_or_state["lease"].get("provenance_json")
+    if not raw:
+        return {}
+    if isinstance(raw, dict):
+        return dict(raw)
+    try:
+        loaded = json.loads(raw)
+    except (TypeError, json.JSONDecodeError):
+        return {}
+    return dict(loaded) if isinstance(loaded, dict) else {}
+
+
+def is_pending_cross_role_handoff(
+    state: Mapping[str, Any] | None,
+) -> dict[str, Any] | None:
+    """Return handoff evidence when a controller allocation awaits consume (#843).
+
+    A pending handoff is identified by durable provenance written at
+    cross-role apply time — not by title heuristics or session-id guessing.
+    """
+    if not state:
+        return None
+    lease = state.get("lease") if isinstance(state.get("lease"), Mapping) else state
+    if not isinstance(lease, Mapping):
+        return None
+    status = str(lease.get("status") or "").strip().lower()
+    if status in (LEASE_STATUS_ABANDONED, LEASE_STATUS_RELEASED, LEASE_STATUS_EXPIRED):
+        return None
+    prov = parse_lease_provenance(state)
+    if not prov and isinstance(lease, Mapping):
+        prov = parse_lease_provenance(lease)
+    if not prov.get("cross_role_handoff"):
+        return None
+    handoff_status = str(prov.get("handoff_status") or "pending").strip().lower()
+    if handoff_status != "pending":
+        return None
+    adopted_by = (
+        lease.get("adopted_by_session_id")
+        or prov.get("adopted_by_session_id")
+        or ""
+    )
+    if str(adopted_by).strip():
+        return None
+    required_role = str(
+        prov.get("required_role") or lease.get("role") or ""
+    ).strip().lower()
+    if not required_role:
+        return None
+    return {
+        "cross_role_handoff": True,
+        "handoff_status": "pending",
+        "required_role": required_role,
+        "allocating_session_id": str(
+            prov.get("allocating_session_id") or lease.get("session_id") or ""
+        ),
+        "allocating_role": str(prov.get("allocating_role") or "controller"),
+        "lease_id": str(lease.get("lease_id") or ""),
+        "assignment_id": (
+            str(state["assignment"]["assignment_id"])
+            if isinstance(state.get("assignment"), Mapping)
+            and state["assignment"].get("assignment_id")
+            else None
+        ),
+        "provenance": prov,
+    }
+
+
 def adopt_lease(
     db: cpd.ControlPlaneDB,
     *,
@@ -450,8 +564,17 @@ def adopt_lease(
     expected_head_sha: str | None = None,
     owner_pid: int | None = None,
     operator_authorized: bool = False,
+    adopter_profile_name: str | None = None,
+    adopter_namespace: str | None = None,
 ) -> dict[str, Any]:
-    """Sanctioned adopt path with provenance; never silent foreign steal."""
+    """Sanctioned adopt path with provenance; never silent foreign steal.
+
+    #843 F1: for a pending cross-role handoff, ``role`` must be the
+    authoritative profile-derived role supplied by the MCP boundary — never
+    caller-asserted authority. When the handoff provenance declares
+    ``required_profile`` / ``required_namespace`` and the caller context is
+    provided, both are validated exactly; a mismatch fails closed.
+    """
     state = db.get_lease_workflow_state(lease_id)
     if not state:
         raise LeaseLifecycleError(
@@ -463,11 +586,8 @@ def adopt_lease(
     owner = str(lease.get("session_id") or "")
     same_owner = owner == str(adopter_session_id)
 
-    if freshness["freshness"] == "active" and not same_owner:
-        raise LeaseLifecycleError(
-            f"refusing to steal active foreign lease {lease_id} owned by "
-            f"{owner} (fail closed)"
-        )
+    handoff = is_pending_cross_role_handoff(state)
+    adopter_role = (role or "").strip().lower()
 
     if freshness["freshness"] in ("abandoned", "released"):
         raise LeaseLifecycleError(
@@ -475,13 +595,64 @@ def adopt_lease(
             "(fail closed)"
         )
 
-    # Expired or stale: require abandon-style safety before ownership transfer
-    # when not same owner; same owner may reclaim.
-    if not same_owner and freshness["freshness"] in (
+    if handoff and not same_owner:
+        # Terminal statuses already rejected above. Freshness may be
+        # active OR stale_dead_process (controller exited) — both are
+        # consumable without abandonment when handoff is still pending.
+        if freshness["freshness"] not in (
+            "active",
+            "stale_dead_process",
+            "stale_missing_worktree",
+        ):
+            raise LeaseLifecycleError(
+                f"lease {lease_id} freshness={freshness['freshness']}; "
+                "terminal or non-active allocation cannot be handoff-consumed "
+                "(fail closed)"
+            )
+        required = handoff["required_role"]
+        if adopter_role != required:
+            raise LeaseLifecycleError(
+                f"wrong role for cross-role handoff consume of {lease_id}: "
+                f"required={required} adopter={adopter_role or 'none'} "
+                "(fail closed)"
+            )
+        # #843 F1: provenance profile/namespace restrictions are validated
+        # against the authoritative caller context when declared. Caller
+        # input can never widen authority; a mismatch fails closed.
+        handoff_prov = handoff.get("provenance") or {}
+        required_profile = str(
+            handoff_prov.get("required_profile") or ""
+        ).strip()
+        if required_profile and adopter_profile_name is not None:
+            if str(adopter_profile_name).strip() != required_profile:
+                raise LeaseLifecycleError(
+                    f"wrong profile for cross-role handoff consume of "
+                    f"{lease_id}: required_profile={required_profile} "
+                    f"adopter_profile={adopter_profile_name} (fail closed)"
+                )
+        required_namespace = str(
+            handoff_prov.get("required_namespace") or ""
+        ).strip()
+        if required_namespace and adopter_namespace is not None:
+            if str(adopter_namespace).strip() != required_namespace:
+                raise LeaseLifecycleError(
+                    f"wrong namespace for cross-role handoff consume of "
+                    f"{lease_id}: required_namespace={required_namespace} "
+                    f"adopter_namespace={adopter_namespace} (fail closed)"
+                )
+        reason = "cross-role-handoff-consume"
+    elif freshness["freshness"] == "active" and not same_owner:
+        raise LeaseLifecycleError(
+            f"refusing to steal active foreign lease {lease_id} owned by "
+            f"{owner} (fail closed)"
+        )
+    elif not same_owner and freshness["freshness"] in (
         "expired",
         "stale_dead_process",
         "stale_missing_worktree",
     ):
+        # Expired or stale (non-handoff): require abandon-style safety before
+        # ownership transfer when not same owner; same owner may reclaim.
         if not operator_authorized and freshness["freshness"] == "expired":
             # Deterministic reclaim of expired foreign lease is allowed
             # without operator flag (sanctioned expire reclaim).
@@ -492,6 +663,9 @@ def adopt_lease(
                 f"lease {lease_id} freshness={freshness['freshness']}; "
                 "use abandon with proof before foreign adopt (fail closed)"
             )
+        reason = "sanctioned-reclaim-adopt"
+    else:
+        reason = "owner-resume-adopt" if same_owner else "sanctioned-reclaim-adopt"
 
     provenance = build_adopt_provenance(
         adopted_from_session_id=owner,
@@ -504,10 +678,14 @@ def adopt_lease(
         worktree_path=worktree_path,
         expected_head_sha=expected_head_sha or lease.get("expected_head_sha"),
         prior_lease_id=lease_id,
-        reason=(
-            "owner-resume-adopt" if same_owner else "sanctioned-reclaim-adopt"
-        ),
+        reason=reason,
     )
+    if handoff and not same_owner:
+        provenance["cross_role_handoff"] = True
+        provenance["handoff_status"] = "adopted"
+        provenance["required_role"] = handoff["required_role"]
+        provenance["allocating_session_id"] = handoff["allocating_session_id"]
+        provenance["allocating_role"] = handoff["allocating_role"]
 
     result = db.adopt_lease(
         lease_id=lease_id,
@@ -518,7 +696,7 @@ def adopt_lease(
         owner_pid=owner_pid if owner_pid is not None else os.getpid(),
         provenance=provenance,
     )
-    return {
+    out = {
         "success": True,
         "outcome": result.get("outcome"),
         "same_owner": same_owner,
@@ -531,6 +709,24 @@ def adopt_lease(
         "comment_lease_only": False,
         "reasons": result.get("reasons") or [],
     }
+    if handoff and not same_owner:
+        out["cross_role_handoff"] = True
+        out["handoff_status"] = "adopted"
+        out["required_role"] = handoff["required_role"]
+        out["adopted_by_session_id"] = adopter_session_id
+        out["adopted_from_session_id"] = owner
+        lease_row = result.get("lease") or {}
+        if isinstance(lease_row, Mapping):
+            out["read_after_write"] = {
+                "lease_id": lease_row.get("lease_id"),
+                "session_id": lease_row.get("session_id"),
+                "role": lease_row.get("role"),
+                "status": lease_row.get("status"),
+                "adopted_by_session_id": lease_row.get("adopted_by_session_id"),
+                "adopted_from_session_id": lease_row.get("adopted_from_session_id"),
+                "phase": lease_row.get("phase"),
+            }
+    return out
 
 
 def release_lease(

merged_cleanup_reconcile.py

@@ -566,6 +566,10 @@ def build_pr_cleanup_entry(
         worktree_state=worktree_state,
         active_lock=active_lock,
     )
+    planned = plan_cleanup_execution_order(
+        remote_assessment=remote,
+        local_assessment=local,
+    )
     return {
         "pr_number": pr_number,
         "issue_number": issue_number,
@@ -576,9 +580,63 @@ def build_pr_cleanup_entry(
         "merged": merged,
         "remote_branch": remote,
         "local_worktree": local,
+        # #851: dry-run and execute share the same lifecycle order description.
+        "planned_execution_order": planned,
     }
 
 
+def plan_cleanup_execution_order(
+    *,
+    remote_assessment: dict[str, Any] | None,
+    local_assessment: dict[str, Any] | None,
+) -> list[dict[str, Any]]:
+    """Describe independent worktree-then-reassess-then-remote cleanup order (#851).
+
+    Remote ownership protection remains fail-closed at execute time. A worktree
+    that is independently safe to remove is never skipped merely because remote
+    deletion may be blocked by that same ``worktree_binding``.
+    """
+    remote = remote_assessment or {}
+    local = local_assessment or {}
+    steps: list[dict[str, Any]] = []
+    worktree_safe = bool(local.get("safe_to_remove_worktree"))
+    remote_safe = bool(remote.get("safe_to_delete_remote"))
+
+    if worktree_safe:
+        steps.append(
+            {
+                "action": "remove_local_worktree",
+                "reason": "independently_safe_to_remove",
+                "phase": 1,
+            }
+        )
+    if remote_safe:
+        if worktree_safe:
+            steps.append(
+                {
+                    "action": "reassess_branch_ownership",
+                    "reason": "after_worktree_removal_clear_worktree_binding",
+                    "phase": 2,
+                }
+            )
+            steps.append(
+                {
+                    "action": "delete_remote_branch",
+                    "reason": "only_if_independently_safe_after_reassessment",
+                    "phase": 3,
+                }
+            )
+        else:
+            steps.append(
+                {
+                    "action": "delete_remote_branch",
+                    "reason": "safe_to_delete_and_no_independent_worktree_removal",
+                    "phase": 1,
+                }
+            )
+    return steps
+
+
 def build_reconciliation_report(
     *,
     project_root: str,

tests/test_branch_cleanup_guard.py

@@ -1266,6 +1266,378 @@ class TestSecondRemediationIntegration(unittest.TestCase):
         self.assertIn("delete_acknowledged", delete_actions[0])
         self.assertTrue(delete_actions[0].get("verified_absent"))
 
+    def test_issue_851_worktree_removed_when_remote_blocked_only_by_worktree_binding(self):
+        """#851: remote blocked by worktree_binding must not skip safe worktree removal.
+
+        Lifecycle: remove clean owned worktree → reassess ownership → delete
+        remote only if independently safe. Unrelated entries stay untouched.
+        """
+        from mcp_server import gitea_reconcile_merged_cleanups
+
+        target_branch = "fix/issue-844-exclude-epic-containers"
+        foreign_branch = "fix/issue-999-unrelated-active"
+        worktree_path = "/tmp/branches/fix-issue-844-exclude-epic-containers"
+        ownership_calls = []
+        remove_calls = []
+        delete_api_calls = []
+
+        def fake_collect(**kwargs):
+            ownership_calls.append(dict(kwargs))
+            # Ownership is reassessed *after* independent worktree removal (#851).
+            # Target worktree is already gone → no worktree_binding remains.
+            # Foreign branch keeps an active author lease → remote delete blocked.
+            if kwargs.get("branch") == foreign_branch:
+                # Match session-bound org/repo + host used by the tool resolve path.
+                return {
+                    "records": [
+                        {
+                            "category": guard.OWNERSHIP_CATEGORY_AUTHOR_LEASE,
+                            "status": "active",
+                            "remote": kwargs.get("remote") or "prgs",
+                            "host": kwargs.get("host") or "gitea.example.com",
+                            "org": kwargs.get("org") or "Scaled-Tech-Consulting",
+                            "repo": kwargs.get("repo") or "Gitea-Tools",
+                            "branch": foreign_branch,
+                            "reclaim_allowed": False,
+                        }
+                    ],
+                    "inventory_error": False,
+                }
+            return {"records": [], "inventory_error": False}
+
+        def fake_remove(project_root, branch, worktree_path=None):
+            remove_calls.append(
+                {"branch": branch, "worktree_path": worktree_path}
+            )
+            return {
+                "success": True,
+                "performed": True,
+                "message": f"removed worktree {worktree_path}",
+                "worktree_path": worktree_path,
+            }
+
+        def fake_probe(h, o, r, auth, br):
+            return guard.classify_branch_readback_http_status(
+                404, not_found_scope=guard.NOT_FOUND_SCOPE_BRANCH
+            )
+
+        def fake_api(method, url, auth, **kwargs):
+            if method == "DELETE":
+                delete_api_calls.append(url)
+            return {}
+
+        report = {
+            "entries": [
+                {
+                    "pr_number": 848,
+                    "head_branch": target_branch,
+                    "remote_branch": {"safe_to_delete_remote": True},
+                    "local_worktree": {
+                        "safe_to_remove_worktree": True,
+                        "worktree_path": worktree_path,
+                    },
+                },
+                {
+                    "pr_number": 999,
+                    "head_branch": foreign_branch,
+                    "remote_branch": {"safe_to_delete_remote": True},
+                    "local_worktree": {
+                        "safe_to_remove_worktree": False,
+                        "worktree_path": None,
+                    },
+                },
+            ],
+            "reviewer_scratch_entries": [],
+        }
+        patch(
+            "mcp_server.get_profile",
+            return_value={
+                "profile_name": "prgs-reconciler",
+                "role": "reconciler",
+                "allowed_operations": [
+                    "gitea.read",
+                    "gitea.branch.delete",
+                    "gitea.pr.close",
+                ],
+                "forbidden_operations": [],
+            },
+        ).start()
+        patch("mcp_server.api_get_all", return_value=[]).start()
+        patch(
+            "mcp_server.merged_cleanup_reconcile.build_reconciliation_report",
+            return_value=report,
+        ).start()
+        patch(
+            "mcp_server.merged_cleanup_reconcile.discover_reviewer_scratch_worktrees",
+            return_value=[],
+        ).start()
+        patch(
+            "mcp_server.audit_reconciliation_mode.check_cleanup_execution_allowed",
+            return_value=(True, []),
+        ).start()
+        patch("mcp_server.verify_preflight_purity", return_value=None).start()
+        patch(
+            "mcp_server._collect_branch_ownership_records",
+            side_effect=fake_collect,
+        ).start()
+        patch("mcp_server._probe_remote_branch", side_effect=fake_probe).start()
+        patch(
+            "mcp_server.merged_cleanup_reconcile.remove_local_worktree",
+            side_effect=fake_remove,
+        ).start()
+        self.mock_api.side_effect = fake_api
+
+        res = gitea_reconcile_merged_cleanups(
+            dry_run=False,
+            execute_confirmed=True,
+            remote="prgs",
+        )
+        self.assertTrue(res.get("performed") or res.get("executed"))
+        actions = res.get("actions") or []
+
+        remove_actions = [
+            a for a in actions if a.get("action") == "remove_local_worktree"
+        ]
+        self.assertEqual(len(remove_actions), 1, actions)
+        self.assertTrue(remove_actions[0].get("success"))
+        self.assertEqual(remove_calls[0]["branch"], target_branch)
+        self.assertEqual(remove_calls[0]["worktree_path"], worktree_path)
+
+        # Target remote delete succeeds after worktree removal + reassessment.
+        target_deletes = [
+            a
+            for a in actions
+            if a.get("action") == "delete_remote_branch"
+            and a.get("branch") == target_branch
+        ]
+        self.assertEqual(len(target_deletes), 1, actions)
+        self.assertTrue(target_deletes[0].get("success"))
+        self.assertTrue(target_deletes[0].get("after_worktree_removal"))
+        self.assertTrue(target_deletes[0].get("ownership_reassessed"))
+        self.assertTrue(target_deletes[0].get("verified_absent"))
+
+        # Foreign branch remains protected (author lease) and is not deleted.
+        foreign_deletes = [
+            a
+            for a in actions
+            if a.get("action") == "delete_remote_branch"
+            and a.get("branch") == foreign_branch
+        ]
+        self.assertEqual(len(foreign_deletes), 1, actions)
+        self.assertFalse(foreign_deletes[0].get("success"))
+        self.assertEqual(
+            foreign_deletes[0].get("blocker_kind"), "active_branch_ownership"
+        )
+        self.assertIn(
+            guard.OWNERSHIP_CATEGORY_AUTHOR_LEASE,
+            foreign_deletes[0].get("blocking_categories") or [],
+        )
+        # Only the target branch should hit the DELETE API.
+        self.assertEqual(len(delete_api_calls), 1)
+
+        # Ownership collected for target (post-removal) and foreign; worktree
+        # removal happened before target remote delete in the action log.
+        target_idx = next(
+            i
+            for i, a in enumerate(actions)
+            if a.get("action") == "remove_local_worktree"
+        )
+        delete_idx = next(
+            i
+            for i, a in enumerate(actions)
+            if a.get("action") == "delete_remote_branch"
+            and a.get("branch") == target_branch
+            and a.get("success")
+        )
+        self.assertLess(target_idx, delete_idx)
+
+    def test_issue_851_dirty_worktree_not_removed_and_remote_stays_protected(self):
+        """#851: dirty/foreign worktrees remain protected; no unsafe cleanup."""
+        from mcp_server import gitea_reconcile_merged_cleanups
+
+        branch = "fix/issue-851-dirty"
+        remove_calls = []
+
+        def fake_collect(**kwargs):
+            return {
+                "records": [
+                    {
+                        "category": guard.OWNERSHIP_CATEGORY_WORKTREE_BINDING,
+                        "status": "active",
+                        "remote": kwargs.get("remote") or "prgs",
+                        "host": kwargs.get("host") or "gitea.example.com",
+                        "org": kwargs.get("org") or "Scaled-Tech-Consulting",
+                        "repo": kwargs.get("repo") or "Gitea-Tools",
+                        "branch": branch,
+                        "reclaim_allowed": False,
+                    }
+                ],
+                "inventory_error": False,
+            }
+
+        report = {
+            "entries": [
+                {
+                    "pr_number": 851,
+                    "head_branch": branch,
+                    "remote_branch": {"safe_to_delete_remote": True},
+                    "local_worktree": {
+                        "safe_to_remove_worktree": False,
+                        "worktree_path": "/tmp/dirty-wt",
+                    },
+                }
+            ],
+            "reviewer_scratch_entries": [],
+        }
+        patch(
+            "mcp_server.get_profile",
+            return_value={
+                "profile_name": "prgs-reconciler",
+                "role": "reconciler",
+                "allowed_operations": [
+                    "gitea.read",
+                    "gitea.branch.delete",
+                ],
+                "forbidden_operations": [],
+            },
+        ).start()
+        patch("mcp_server.api_get_all", return_value=[]).start()
+        patch(
+            "mcp_server.merged_cleanup_reconcile.build_reconciliation_report",
+            return_value=report,
+        ).start()
+        patch(
+            "mcp_server.merged_cleanup_reconcile.discover_reviewer_scratch_worktrees",
+            return_value=[],
+        ).start()
+        patch(
+            "mcp_server.audit_reconciliation_mode.check_cleanup_execution_allowed",
+            return_value=(True, []),
+        ).start()
+        patch("mcp_server.verify_preflight_purity", return_value=None).start()
+        patch(
+            "mcp_server._collect_branch_ownership_records",
+            side_effect=fake_collect,
+        ).start()
+        patch(
+            "mcp_server.merged_cleanup_reconcile.remove_local_worktree",
+            side_effect=lambda *a, **k: remove_calls.append(k) or {
+                "success": True,
+                "performed": True,
+            },
+        ).start()
+        self.mock_api.side_effect = lambda *a, **k: {}
+
+        res = gitea_reconcile_merged_cleanups(
+            dry_run=False,
+            execute_confirmed=True,
+            remote="prgs",
+        )
+        actions = res.get("actions") or []
+        self.assertEqual(remove_calls, [])
+        self.assertFalse(
+            any(a.get("action") == "remove_local_worktree" for a in actions)
+        )
+        deletes = [
+            a for a in actions if a.get("action") == "delete_remote_branch"
+        ]
+        self.assertEqual(len(deletes), 1)
+        self.assertFalse(deletes[0].get("success"))
+        self.assertEqual(deletes[0].get("blocker_kind"), "active_branch_ownership")
+        self.assertIn(
+            guard.OWNERSHIP_CATEGORY_WORKTREE_BINDING,
+            deletes[0].get("blocking_categories") or [],
+        )
+
+    def test_issue_851_idempotent_resume_when_worktree_already_absent(self):
+        """#851: partial failures remain resumable and idempotent."""
+        from mcp_server import gitea_reconcile_merged_cleanups
+
+        branch = "fix/issue-851-resume"
+        ownership_calls = []
+
+        def fake_collect(**kwargs):
+            ownership_calls.append(kwargs)
+            return {"records": [], "inventory_error": False}
+
+        def fake_remove(project_root, branch, worktree_path=None):
+            return {
+                "success": False,
+                "performed": False,
+                "message": f"worktree not found: {worktree_path}",
+            }
+
+        def fake_probe(h, o, r, auth, br):
+            return guard.classify_branch_readback_http_status(
+                404, not_found_scope=guard.NOT_FOUND_SCOPE_BRANCH
+            )
+
+        report = {
+            "entries": [
+                {
+                    "pr_number": 851,
+                    "head_branch": branch,
+                    "remote_branch": {"safe_to_delete_remote": True},
+                    "local_worktree": {
+                        "safe_to_remove_worktree": True,
+                        "worktree_path": "/tmp/already-gone",
+                    },
+                }
+            ],
+            "reviewer_scratch_entries": [],
+        }
+        patch(
+            "mcp_server.get_profile",
+            return_value={
+                "profile_name": "prgs-reconciler",
+                "role": "reconciler",
+                "allowed_operations": [
+                    "gitea.read",
+                    "gitea.branch.delete",
+                ],
+                "forbidden_operations": [],
+            },
+        ).start()
+        patch("mcp_server.api_get_all", return_value=[]).start()
+        patch(
+            "mcp_server.merged_cleanup_reconcile.build_reconciliation_report",
+            return_value=report,
+        ).start()
+        patch(
+            "mcp_server.merged_cleanup_reconcile.discover_reviewer_scratch_worktrees",
+            return_value=[],
+        ).start()
+        patch(
+            "mcp_server.audit_reconciliation_mode.check_cleanup_execution_allowed",
+            return_value=(True, []),
+        ).start()
+        patch("mcp_server.verify_preflight_purity", return_value=None).start()
+        patch(
+            "mcp_server._collect_branch_ownership_records",
+            side_effect=fake_collect,
+        ).start()
+        patch("mcp_server._probe_remote_branch", side_effect=fake_probe).start()
+        patch(
+            "mcp_server.merged_cleanup_reconcile.remove_local_worktree",
+            side_effect=fake_remove,
+        ).start()
+        self.mock_api.side_effect = lambda *a, **k: {}
+
+        res = gitea_reconcile_merged_cleanups(
+            dry_run=False,
+            execute_confirmed=True,
+            remote="prgs",
+        )
+        actions = res.get("actions") or []
+        removes = [a for a in actions if a.get("action") == "remove_local_worktree"]
+        deletes = [a for a in actions if a.get("action") == "delete_remote_branch"]
+        self.assertEqual(len(removes), 1)
+        self.assertFalse(removes[0].get("success"))
+        self.assertEqual(len(deletes), 1)
+        self.assertTrue(deletes[0].get("success"))
+        self.assertTrue(deletes[0].get("after_worktree_removal"))
+        self.assertTrue(ownership_calls)
+
 
 
 if __name__ == "__main__":

tests/test_issue_843_cross_role_handoff.py

@@ -0,0 +1,682 @@
+"""Cross-role allocation handoff consumable by independent workers (#843).
+
+Regression coverage for the controller→required-role consume path:
+
+* controller allocates author work; independent author adopts successfully
+* author adoption succeeds after allocating controller process exits
+* author adoption without sharing controller session identity
+* wrong-role adoption rejected
+* concurrent/second adoption rejected without state corruption
+* terminal allocation adoption rejected
+* successful adoption produces authoritative ownership evidence
+* genuine abandoned-lease recovery remains valid
+* process_work_queue / allocate results include consume identifiers
+* same-role allocation behavior remains compatible
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import unittest
+from datetime import timedelta
+from unittest.mock import patch
+
+from allocator_service import (
+    ALLOCATION_MODE_CROSS_ROLE,
+    ALLOCATION_MODE_ROLE_SCOPED,
+    OUTCOME_ASSIGNED,
+    ROLE_AUTHOR,
+    ROLE_CONTROLLER,
+    ROLE_REVIEWER,
+    WorkCandidate,
+    allocate_next_work,
+)
+from control_plane_db import ControlPlaneDB, ForeignLeaseError, _ts, _utc_now
+import lease_lifecycle as ll
+
+
+class CrossRoleHandoffTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self.db_path = os.path.join(self._tmp.name, "cp.sqlite3")
+        self.db = ControlPlaneDB(self.db_path)
+        self.db.upsert_session(
+            session_id="ctrl-session",
+            role="controller",
+            profile="prgs-controller",
+            pid=99999999,  # dead-looking pid
+        )
+        self.db.upsert_session(
+            session_id="author-worker",
+            role="author",
+            profile="prgs-author",
+            pid=os.getpid(),
+        )
+        self.db.upsert_session(
+            session_id="author-worker-2",
+            role="author",
+            profile="prgs-author",
+            pid=os.getpid(),
+        )
+        self.db.upsert_session(
+            session_id="reviewer-worker",
+            role="reviewer",
+            profile="prgs-reviewer",
+            pid=os.getpid(),
+        )
+        self.wt = self._tmp.name
+
+    def tearDown(self) -> None:
+        self._tmp.cleanup()
+
+    def _ready_issue(self, number: int = 843, title: str = "handoff target") -> WorkCandidate:
+        return WorkCandidate(
+            kind="issue",
+            number=number,
+            labels=("status:ready", "type:bug"),
+            title=title,
+            priority=20,
+        )
+
+    def _controller_allocate(self, number: int = 843, **kwargs):
+        defaults = dict(
+            db=self.db,
+            session_id="ctrl-session",
+            role=ROLE_CONTROLLER,
+            remote="prgs",
+            org="Scaled-Tech-Consulting",
+            repo="Gitea-Tools",
+            candidates=[self._ready_issue(number)],
+            apply=True,
+            profile_name="prgs-controller",
+            username="controller-user",
+            allocation_mode=ALLOCATION_MODE_CROSS_ROLE,
+        )
+        defaults.update(kwargs)
+        return allocate_next_work(**defaults)
+
+    def test_controller_allocates_author_independent_author_adopts(self) -> None:
+        res = self._controller_allocate()
+        self.assertEqual(res["outcome"], OUTCOME_ASSIGNED)
+        self.assertEqual(res["required_role"], ROLE_AUTHOR)
+        self.assertIn("consume_allocation", res)
+        consume = res["consume_allocation"]
+        self.assertEqual(consume["tool"], "gitea_adopt_workflow_lease")
+        self.assertEqual(consume["required_role"], ROLE_AUTHOR)
+        self.assertFalse(consume["controller_session_required"])
+        lid = res["assignment"]["lease_id"]
+        self.assertEqual(consume["lease_id"], lid)
+        self.assertIn(lid, res["next_valid_command"])
+
+        adopted = ll.adopt_lease(
+            self.db,
+            lease_id=lid,
+            adopter_session_id="author-worker",
+            role=ROLE_AUTHOR,
+            worktree_path=self.wt,
+        )
+        self.assertTrue(adopted["success"])
+        self.assertEqual(adopted["outcome"], "adopted_cross_role_handoff")
+        self.assertEqual(adopted["adopted_by_session_id"], "author-worker")
+        self.assertEqual(adopted["adopted_from_session_id"], "ctrl-session")
+        raw = adopted["read_after_write"]
+        self.assertEqual(raw["session_id"], "author-worker")
+        self.assertEqual(raw["adopted_by_session_id"], "author-worker")
+        self.assertEqual(raw["status"], "active")
+        self.assertEqual(raw["phase"], "adopted")
+
+        # Authoritative re-read
+        state = self.db.get_lease_workflow_state(lid)
+        self.assertEqual(state["lease"]["session_id"], "author-worker")
+        self.assertEqual(state["lease"]["adopted_by_session_id"], "author-worker")
+        self.assertEqual(state["assignment"]["session_id"], "author-worker")
+        self.assertEqual(state["provenance"]["handoff_status"], "adopted")
+
+    def test_author_adoption_after_controller_process_exits(self) -> None:
+        res = self._controller_allocate(number=900)
+        lid = res["assignment"]["lease_id"]
+        # Force owner_pid dead + freshness stale_dead_process
+        import sqlite3
+
+        conn = sqlite3.connect(self.db_path)
+        try:
+            conn.execute(
+                "UPDATE leases SET owner_pid = 99999999 WHERE lease_id = ?",
+                (lid,),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+        state = self.db.get_lease_workflow_state(lid)
+        fr = ll.classify_lease_freshness(
+            state["lease"], pid_checker=lambda _p: False
+        )
+        self.assertEqual(fr["freshness"], "stale_dead_process")
+
+        adopted = ll.adopt_lease(
+            self.db,
+            lease_id=lid,
+            adopter_session_id="author-worker",
+            role=ROLE_AUTHOR,
+            worktree_path=self.wt,
+        )
+        self.assertEqual(adopted["outcome"], "adopted_cross_role_handoff")
+        self.assertEqual(adopted["adopted_by_session_id"], "author-worker")
+        # No abandon required
+        state2 = self.db.get_lease_workflow_state(lid)
+        self.assertEqual(state2["lease"]["status"], "active")
+        self.assertNotEqual(state2["lease"]["status"], "abandoned")
+
+    def test_adoption_without_sharing_controller_session_identity(self) -> None:
+        res = self._controller_allocate(number=901)
+        lid = res["assignment"]["lease_id"]
+        adopted = ll.adopt_lease(
+            self.db,
+            lease_id=lid,
+            adopter_session_id="author-worker",
+            role=ROLE_AUTHOR,
+            worktree_path=self.wt,
+        )
+        self.assertNotEqual(adopted["adopted_by_session_id"], "ctrl-session")
+        self.assertFalse(adopted["same_owner"])
+        self.assertEqual(adopted["adopted_from_session_id"], "ctrl-session")
+
+    def test_wrong_role_adoption_rejected(self) -> None:
+        res = self._controller_allocate(number=902)
+        lid = res["assignment"]["lease_id"]
+        with self.assertRaises(ll.LeaseLifecycleError) as ctx:
+            ll.adopt_lease(
+                self.db,
+                lease_id=lid,
+                adopter_session_id="reviewer-worker",
+                role=ROLE_REVIEWER,
+            )
+        self.assertIn("wrong role", str(ctx.exception).lower())
+        # State unchanged
+        state = self.db.get_lease_workflow_state(lid)
+        self.assertEqual(state["lease"]["session_id"], "ctrl-session")
+        self.assertIsNone(state["lease"].get("adopted_by_session_id") or None)
+        self.assertEqual(state["provenance"]["handoff_status"], "pending")
+
+    def test_second_adoption_rejected_without_corruption(self) -> None:
+        res = self._controller_allocate(number=903)
+        lid = res["assignment"]["lease_id"]
+        first = ll.adopt_lease(
+            self.db,
+            lease_id=lid,
+            adopter_session_id="author-worker",
+            role=ROLE_AUTHOR,
+            worktree_path=self.wt,
+        )
+        self.assertEqual(first["outcome"], "adopted_cross_role_handoff")
+        with self.assertRaises(ll.LeaseLifecycleError):
+            ll.adopt_lease(
+                self.db,
+                lease_id=lid,
+                adopter_session_id="author-worker-2",
+                role=ROLE_AUTHOR,
+                worktree_path=self.wt,
+            )
+        state = self.db.get_lease_workflow_state(lid)
+        self.assertEqual(state["lease"]["session_id"], "author-worker")
+        self.assertEqual(state["lease"]["adopted_by_session_id"], "author-worker")
+        self.assertEqual(state["assignment"]["session_id"], "author-worker")
+        self.assertEqual(state["lease"]["status"], "active")
+
+    def test_terminal_allocation_adoption_rejected(self) -> None:
+        res = self._controller_allocate(number=904)
+        lid = res["assignment"]["lease_id"]
+        # Abandon as terminal
+        proof = ll.AbandonProof(
+            dead_process=True,
+            missing_worktree=True,
+            no_open_pr=True,
+            no_live_mutation_risk=True,
+            owner_pid=99999999,
+            worktree_path="/nonexistent/for-843",
+        )
+        # Attach dead pid / missing wt for abandon eligibility
+        import sqlite3
+
+        conn = sqlite3.connect(self.db_path)
+        try:
+            conn.execute(
+                "UPDATE leases SET owner_pid = 99999999, worktree_path = ? WHERE lease_id = ?",
+                ("/nonexistent/for-843", lid),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+        abandoned = ll.abandon_lease(
+            self.db,
+            lease_id=lid,
+            requester_session_id="author-worker",
+            proof=proof,
+        )
+        self.assertEqual(abandoned["outcome"], "abandoned")
+        with self.assertRaises(ll.LeaseLifecycleError) as ctx:
+            ll.adopt_lease(
+                self.db,
+                lease_id=lid,
+                adopter_session_id="author-worker",
+                role=ROLE_AUTHOR,
+            )
+        self.assertIn("abandoned", str(ctx.exception).lower())
+
+    def test_successful_adoption_read_after_write_ownership(self) -> None:
+        res = self._controller_allocate(number=905)
+        lid = res["assignment"]["lease_id"]
+        adopted = ll.adopt_lease(
+            self.db,
+            lease_id=lid,
+            adopter_session_id="author-worker",
+            role=ROLE_AUTHOR,
+            worktree_path=self.wt,
+        )
+        raw = adopted["read_after_write"]
+        self.assertEqual(raw["lease_id"], lid)
+        self.assertEqual(raw["session_id"], "author-worker")
+        self.assertEqual(raw["adopted_by_session_id"], "author-worker")
+        self.assertEqual(raw["adopted_from_session_id"], "ctrl-session")
+        # Re-fetch proves durable write
+        state = self.db.get_lease_workflow_state(lid)
+        self.assertEqual(state["lease"]["session_id"], raw["session_id"])
+        self.assertEqual(
+            state["lease"]["adopted_by_session_id"], raw["adopted_by_session_id"]
+        )
+
+    def test_genuine_abandoned_recovery_still_valid(self) -> None:
+        """Same-role author lease abandoned remains reclaimable via abandon path."""
+        same = allocate_next_work(
+            self.db,
+            session_id="author-worker",
+            role=ROLE_AUTHOR,
+            remote="prgs",
+            org="Scaled-Tech-Consulting",
+            repo="Gitea-Tools",
+            candidates=[self._ready_issue(906, "same-role")],
+            apply=True,
+            profile_name="prgs-author",
+            username="author-user",
+            allocation_mode=ALLOCATION_MODE_ROLE_SCOPED,
+        )
+        self.assertEqual(same["outcome"], OUTCOME_ASSIGNED)
+        lid = same["assignment"]["lease_id"]
+        import sqlite3
+
+        conn = sqlite3.connect(self.db_path)
+        try:
+            conn.execute(
+                "UPDATE leases SET owner_pid = 99999999, worktree_path = ? WHERE lease_id = ?",
+                ("/nonexistent/same-role", lid),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+        proof = ll.AbandonProof(
+            dead_process=True,
+            missing_worktree=True,
+            no_open_pr=True,
+            no_live_mutation_risk=True,
+            owner_pid=99999999,
+            worktree_path="/nonexistent/same-role",
+        )
+        abandoned = ll.abandon_lease(
+            self.db,
+            lease_id=lid,
+            requester_session_id="author-worker-2",
+            proof=proof,
+        )
+        self.assertEqual(abandoned["outcome"], "abandoned")
+        # Foreign author cannot handoff-consume an abandoned non-handoff lease
+        with self.assertRaises(ll.LeaseLifecycleError):
+            ll.adopt_lease(
+                self.db,
+                lease_id=lid,
+                adopter_session_id="author-worker-2",
+                role=ROLE_AUTHOR,
+            )
+        # Reclaim path still works for expired/abandoned after force-expire
+        reclaimed = ll.reclaim_expired_lease(
+            self.db,
+            lease_id=lid,
+            session_id="author-worker-2",
+            role=ROLE_AUTHOR,
+            worktree_path=self.wt,
+        )
+        self.assertEqual(reclaimed["outcome"], "reclaimed")
+        self.assertEqual(reclaimed["assignment"]["session_id"], "author-worker-2")
+
+    def test_allocate_payload_includes_consume_identifiers(self) -> None:
+        res = self._controller_allocate(number=907)
+        self.assertIn("consume_allocation", res)
+        c = res["consume_allocation"]
+        for key in (
+            "tool",
+            "lease_id",
+            "assignment_id",
+            "required_role",
+            "required_profile",
+            "required_namespace",
+            "instructions",
+            "handoff_status",
+        ):
+            self.assertIn(key, c)
+        self.assertEqual(c["required_namespace"], "gitea-author")
+        self.assertEqual(c["required_profile"], "prgs-author")
+        self.assertIn("gitea_adopt_workflow_lease", c["instructions"])
+        self.assertTrue(res["lease_proof"]["cross_role_handoff"])
+        self.assertEqual(res["lease_proof"]["handoff_status"], "pending")
+
+    def test_same_role_allocation_remains_compatible(self) -> None:
+        res = allocate_next_work(
+            self.db,
+            session_id="author-worker",
+            role=ROLE_AUTHOR,
+            remote="prgs",
+            org="Scaled-Tech-Consulting",
+            repo="Gitea-Tools",
+            candidates=[self._ready_issue(908)],
+            apply=True,
+            profile_name="prgs-author",
+            username="author-user",
+        )
+        self.assertEqual(res["outcome"], OUTCOME_ASSIGNED)
+        self.assertNotIn("consume_allocation", res)
+        lid = res["assignment"]["lease_id"]
+        state = self.db.get_lease_workflow_state(lid)
+        # No cross-role handoff provenance
+        prov = state.get("provenance") or {}
+        self.assertFalse(prov.get("cross_role_handoff"))
+        # Owner resume still works
+        resume = ll.adopt_lease(
+            self.db,
+            lease_id=lid,
+            adopter_session_id="author-worker",
+            role=ROLE_AUTHOR,
+            worktree_path=self.wt,
+        )
+        self.assertTrue(resume["same_owner"])
+        self.assertEqual(resume["outcome"], "adopted_owner_resume")
+
+    def test_inspect_points_required_role_at_consume(self) -> None:
+        res = self._controller_allocate(number=909)
+        lid = res["assignment"]["lease_id"]
+        decision = ll.inspect_lease(
+            self.db, lid, caller_session_id="author-worker"
+        )
+        self.assertEqual(
+            decision["safe_next_action"], ll.SAFE_CONSUME_CROSS_ROLE
+        )
+        self.assertFalse(decision["block"])
+        self.assertEqual(decision["required_role"], ROLE_AUTHOR)
+
+    def test_db_cas_rejects_concurrent_second_consume(self) -> None:
+        res = self._controller_allocate(number=910)
+        lid = res["assignment"]["lease_id"]
+        # First consume via DB layer directly
+        first = self.db.adopt_lease(
+            lease_id=lid,
+            adopter_session_id="author-worker",
+            role=ROLE_AUTHOR,
+            worktree_path=self.wt,
+            provenance={
+                "cross_role_handoff": True,
+                "handoff_status": "adopted",
+                "required_role": "author",
+            },
+        )
+        self.assertEqual(first["outcome"], "adopted_cross_role_handoff")
+        # Second CAS must fail
+        with self.assertRaises(ForeignLeaseError):
+            self.db.adopt_lease(
+                lease_id=lid,
+                adopter_session_id="author-worker-2",
+                role=ROLE_AUTHOR,
+                worktree_path=self.wt,
+                provenance={
+                    "cross_role_handoff": True,
+                    "handoff_status": "pending",
+                    "required_role": "author",
+                },
+            )
+        state = self.db.get_lease_workflow_state(lid)
+        self.assertEqual(state["lease"]["session_id"], "author-worker")
+
+
+class MCPBoundaryAdoptRoleBindingTest(unittest.TestCase):
+    """#843 F1: MCP-boundary role binding for ``gitea_adopt_workflow_lease``.
+
+    The library-level wrong-role test calls ``lease_lifecycle.adopt_lease``
+    directly. These tests prove the MCP entry point derives the adopter role
+    authoritatively from the active authenticated profile and rejects any
+    caller-supplied role that disagrees, so a reviewer/merger profile cannot
+    consume an author handoff by passing ``role="author"``.
+    """
+
+    AUTHOR_PROFILE = {
+        "profile_name": "prgs-author",
+        "role": "author",
+        "allowed_operations": [
+            "gitea.read",
+            "gitea.pr.create",
+            "gitea.branch.push",
+        ],
+        "forbidden_operations": [],
+    }
+    REVIEWER_PROFILE = {
+        "profile_name": "prgs-reviewer",
+        "role": "reviewer",
+        "allowed_operations": [
+            "gitea.read",
+            "gitea.pr.review",
+            "gitea.pr.approve",
+            "gitea.pr.request_changes",
+        ],
+        "forbidden_operations": ["gitea.pr.create", "gitea.branch.push"],
+    }
+    MERGER_PROFILE = {
+        "profile_name": "prgs-merger",
+        "role": "merger",
+        "allowed_operations": ["gitea.read", "gitea.pr.merge"],
+        "forbidden_operations": ["gitea.pr.create", "gitea.branch.push"],
+    }
+    FOREIGN_AUTHOR_PROFILE = {
+        "profile_name": "dadeschools-author",
+        "role": "author",
+        "allowed_operations": [
+            "gitea.read",
+            "gitea.pr.create",
+            "gitea.branch.push",
+        ],
+        "forbidden_operations": [],
+    }
+
+    def setUp(self) -> None:
+        self._tmp = tempfile.TemporaryDirectory()
+        self.db_path = os.path.join(self._tmp.name, "cp.sqlite3")
+        self.db = ControlPlaneDB(self.db_path)
+        self.db.upsert_session(
+            session_id="ctrl-session",
+            role="controller",
+            profile="prgs-controller",
+            pid=99999999,
+        )
+        self.db.upsert_session(
+            session_id="author-worker",
+            role="author",
+            profile="prgs-author",
+            pid=os.getpid(),
+        )
+        self.wt = self._tmp.name
+
+    def tearDown(self) -> None:
+        self._tmp.cleanup()
+
+    def _ready_issue(self, number: int) -> WorkCandidate:
+        return WorkCandidate(
+            kind="issue",
+            number=number,
+            labels=("status:ready", "type:bug"),
+            title="handoff target",
+            priority=20,
+        )
+
+    def _handoff_lease(self, number: int = 843) -> str:
+        res = allocate_next_work(
+            db=self.db,
+            session_id="ctrl-session",
+            role=ROLE_CONTROLLER,
+            remote="prgs",
+            org="Scaled-Tech-Consulting",
+            repo="Gitea-Tools",
+            candidates=[self._ready_issue(number)],
+            apply=True,
+            profile_name="prgs-controller",
+            username="controller-user",
+            allocation_mode=ALLOCATION_MODE_CROSS_ROLE,
+        )
+        self.assertEqual(res["outcome"], OUTCOME_ASSIGNED)
+        self.assertEqual(res["required_role"], ROLE_AUTHOR)
+        return res["assignment"]["lease_id"]
+
+    def _call_adopt_tool(self, profile: dict, **kwargs):
+        import gitea_mcp_server as mcp_server
+
+        with (
+            patch.object(mcp_server, "get_profile", return_value=profile),
+            patch.object(
+                mcp_server,
+                "_control_plane_db_or_error",
+                return_value=(self.db, []),
+            ),
+        ):
+            return mcp_server.gitea_adopt_workflow_lease(
+                remote="prgs", **kwargs
+            )
+
+    def _assert_handoff_untouched(self, lease_id: str) -> None:
+        state = self.db.get_lease_workflow_state(lease_id)
+        self.assertEqual(state["lease"]["session_id"], "ctrl-session")
+        self.assertIsNone(state["lease"].get("adopted_by_session_id") or None)
+        self.assertEqual(state["lease"]["status"], "active")
+        self.assertEqual(state["provenance"]["handoff_status"], "pending")
+
+    def test_reviewer_profile_cannot_consume_author_handoff_via_role_author(
+        self,
+    ) -> None:
+        lid = self._handoff_lease(920)
+        result = self._call_adopt_tool(
+            self.REVIEWER_PROFILE,
+            lease_id=lid,
+            session_id="reviewer-worker",
+            role="author",
+            worktree_path=self.wt,
+        )
+        self.assertFalse(result["success"])
+        self.assertEqual(result["outcome"], "blocked")
+        self.assertEqual(result["profile_role_kind"], "reviewer")
+        self.assertEqual(result["supplied_role"], "author")
+        self.assertIn("does not match", result["reasons"][0])
+        self._assert_handoff_untouched(lid)
+
+    def test_merger_profile_cannot_consume_author_handoff_via_role_author(
+        self,
+    ) -> None:
+        lid = self._handoff_lease(921)
+        result = self._call_adopt_tool(
+            self.MERGER_PROFILE,
+            lease_id=lid,
+            session_id="merger-worker",
+            role="author",
+            worktree_path=self.wt,
+        )
+        self.assertFalse(result["success"])
+        self.assertEqual(result["outcome"], "blocked")
+        self.assertEqual(result["profile_role_kind"], "merger")
+        self._assert_handoff_untouched(lid)
+
+    def test_reviewer_profile_rejected_without_role_argument(self) -> None:
+        """Even without a spoofed role, the profile-derived role binds."""
+        lid = self._handoff_lease(922)
+        result = self._call_adopt_tool(
+            self.REVIEWER_PROFILE,
+            lease_id=lid,
+            session_id="reviewer-worker",
+            worktree_path=self.wt,
+        )
+        self.assertFalse(result["success"])
+        self.assertEqual(result["outcome"], "blocked")
+        self.assertIn("wrong role", result["reasons"][0].lower())
+        self._assert_handoff_untouched(lid)
+
+    def test_author_profile_mismatching_supplied_role_rejected(self) -> None:
+        lid = self._handoff_lease(923)
+        result = self._call_adopt_tool(
+            self.AUTHOR_PROFILE,
+            lease_id=lid,
+            session_id="author-worker",
+            role="reviewer",
+            worktree_path=self.wt,
+        )
+        self.assertFalse(result["success"])
+        self.assertEqual(result["outcome"], "blocked")
+        self.assertEqual(result["profile_role_kind"], "author")
+        self.assertEqual(result["supplied_role"], "reviewer")
+        self._assert_handoff_untouched(lid)
+
+    def test_foreign_profile_name_rejected_for_author_handoff(self) -> None:
+        """Provenance required_profile binds even when the role matches."""
+        lid = self._handoff_lease(924)
+        result = self._call_adopt_tool(
+            self.FOREIGN_AUTHOR_PROFILE,
+            lease_id=lid,
+            session_id="foreign-author-worker",
+            worktree_path=self.wt,
+        )
+        self.assertFalse(result["success"])
+        self.assertEqual(result["outcome"], "blocked")
+        self.assertIn("wrong profile", result["reasons"][0].lower())
+        self._assert_handoff_untouched(lid)
+
+    def test_author_profile_consumes_author_handoff(self) -> None:
+        lid = self._handoff_lease(925)
+        result = self._call_adopt_tool(
+            self.AUTHOR_PROFILE,
+            lease_id=lid,
+            session_id="author-worker",
+            role="author",
+            worktree_path=self.wt,
+        )
+        self.assertTrue(result["success"])
+        self.assertEqual(result["outcome"], "adopted_cross_role_handoff")
+        self.assertEqual(result["adopted_by_session_id"], "author-worker")
+        self.assertEqual(result["adopted_from_session_id"], "ctrl-session")
+        state = self.db.get_lease_workflow_state(lid)
+        self.assertEqual(state["lease"]["session_id"], "author-worker")
+        self.assertEqual(
+            state["lease"]["adopted_by_session_id"], "author-worker"
+        )
+        self.assertEqual(state["assignment"]["session_id"], "author-worker")
+        self.assertEqual(state["provenance"]["handoff_status"], "adopted")
+
+    def test_author_profile_consumes_author_handoff_without_role_argument(
+        self,
+    ) -> None:
+        lid = self._handoff_lease(926)
+        result = self._call_adopt_tool(
+            self.AUTHOR_PROFILE,
+            lease_id=lid,
+            session_id="author-worker",
+            worktree_path=self.wt,
+        )
+        self.assertTrue(result["success"])
+        self.assertEqual(result["outcome"], "adopted_cross_role_handoff")
+        state = self.db.get_lease_workflow_state(lid)
+        self.assertEqual(state["lease"]["session_id"], "author-worker")
+        self.assertEqual(state["lease"]["role"], "author")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_merged_cleanup_reconcile.py

@@ -12,6 +12,59 @@ import merged_cleanup_reconcile as mcr  # noqa: E402
 
 
 class TestMergedCleanupAssessment(unittest.TestCase):
+    def test_issue_851_plan_order_worktree_then_reassess_then_remote(self):
+        """#851 dry-run plan: remove worktree, reassess ownership, then remote."""
+        plan = mcr.plan_cleanup_execution_order(
+            remote_assessment={"safe_to_delete_remote": True},
+            local_assessment={"safe_to_remove_worktree": True},
+        )
+        actions = [s["action"] for s in plan]
+        self.assertEqual(
+            actions,
+            [
+                "remove_local_worktree",
+                "reassess_branch_ownership",
+                "delete_remote_branch",
+            ],
+        )
+        self.assertEqual(plan[0]["phase"], 1)
+        self.assertEqual(plan[-1]["phase"], 3)
+        self.assertIn("independently_safe", plan[0]["reason"])
+        self.assertIn("reassessment", plan[-1]["reason"])
+
+    def test_issue_851_plan_remote_only_when_worktree_not_safe(self):
+        plan = mcr.plan_cleanup_execution_order(
+            remote_assessment={"safe_to_delete_remote": True},
+            local_assessment={"safe_to_remove_worktree": False},
+        )
+        self.assertEqual([s["action"] for s in plan], ["delete_remote_branch"])
+        self.assertNotIn("reassess_branch_ownership", [s["action"] for s in plan])
+
+    def test_issue_851_plan_worktree_only_when_remote_not_safe(self):
+        plan = mcr.plan_cleanup_execution_order(
+            remote_assessment={"safe_to_delete_remote": False},
+            local_assessment={"safe_to_remove_worktree": True},
+        )
+        self.assertEqual([s["action"] for s in plan], ["remove_local_worktree"])
+
+    def test_issue_851_entry_includes_planned_execution_order(self):
+        entry = mcr.build_pr_cleanup_entry(
+            pr={
+                "number": 848,
+                "title": "Closes #844",
+                "body": "",
+                "merged_at": "2026-07-23T00:00:00Z",
+                "head": {"ref": "fix/issue-844-x", "sha": "a" * 40},
+            },
+            project_root="/tmp/not-a-real-root",
+            open_pr_heads=set(),
+            remote_branch_exists=True,
+            head_on_master=True,
+            delete_capability_allowed=True,
+        )
+        self.assertIn("planned_execution_order", entry)
+        self.assertIsInstance(entry["planned_execution_order"], list)
+
     def test_extract_linked_issue_from_closes(self):
         issue = mcr.extract_linked_issue(
             "feat: cleanup (Closes #269)",

tests/test_webui_shell.py

@@ -0,0 +1,135 @@
+"""Tests for the Phase 1 operator console application shell (#638)."""
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from starlette.routing import Route
+from starlette.testclient import TestClient
+
+from webui import layout
+from webui.app import create_app
+from webui.nav import NAV_GROUPS, STUB_PAGES, nav_hrefs
+
+
+class TestShellNav(unittest.TestCase):
+    def setUp(self):
+        self.client = TestClient(create_app())
+
+    def test_nav_group_labels_present(self):
+        text = self.client.get("/").text
+        for group in NAV_GROUPS:
+            with self.subTest(group=group.label):
+                self.assertIn(f">{group.label}<", text)
+
+    def test_phase1_group_labels_cover_expected_ia(self):
+        labels = {group.label for group in NAV_GROUPS}
+        for expected in (
+            "Health",
+            "Traffic",
+            "Runtime/Sessions",
+            "Projects",
+            "Inventory",
+            "Timeline",
+            "Policy",
+            "Insights",
+        ):
+            with self.subTest(label=expected):
+                self.assertIn(expected, labels)
+
+    def test_every_nav_href_resolves_to_a_get_route(self):
+        app = create_app()
+        get_paths = {
+            route.path
+            for route in app.routes
+            if isinstance(route, Route) and "GET" in route.methods
+        }
+        for href in nav_hrefs():
+            with self.subTest(href=href):
+                self.assertIn(href, get_paths, f"nav href {href} has no GET route")
+
+    def test_legacy_hrefs_still_navigable(self):
+        text = self.client.get("/").text
+        for href in ("/queue", "/projects", "/prompts", "/runtime",
+                     "/audit", "/worktrees", "/leases", "/actions"):
+            with self.subTest(href=href):
+                self.assertIn(f'href="{href}"', text)
+
+
+class TestShellBadges(unittest.TestCase):
+    def setUp(self):
+        self.client = TestClient(create_app())
+
+    def test_mode_badge_present(self):
+        self.assertIn("mode: read-only", self.client.get("/").text)
+
+    def test_environment_badge_present(self):
+        self.assertIn("env:", self.client.get("/").text)
+
+    def test_default_environment_is_local(self):
+        self.assertEqual(layout.environment_label(), "local")
+
+    def test_remote_bind_reports_remote_environment(self):
+        import os
+
+        prior = os.environ.get("WEBUI_HOST")
+        os.environ["WEBUI_HOST"] = "10.0.0.5"
+        try:
+            self.assertEqual(layout.environment_label(), "remote")
+        finally:
+            if prior is None:
+                os.environ.pop("WEBUI_HOST", None)
+            else:
+                os.environ["WEBUI_HOST"] = prior
+
+    def test_docs_link_present(self):
+        text = self.client.get("/").text
+        self.assertIn(layout.DOCS_URL, text)
+        self.assertIn(">Docs<", text)
+
+
+class TestShellStubs(unittest.TestCase):
+    def setUp(self):
+        self.client = TestClient(create_app())
+
+    def test_stub_routes_render_200(self):
+        for path, (title, _desc) in STUB_PAGES.items():
+            with self.subTest(path=path):
+                response = self.client.get(path)
+                self.assertEqual(response.status_code, 200, path)
+                self.assertIn(title, response.text)
+                self.assertIn("placeholder", response.text)
+
+    def test_stub_routes_are_read_only(self):
+        for path in STUB_PAGES:
+            with self.subTest(path=path):
+                response = self.client.post(path)
+                self.assertEqual(response.status_code, 405)
+                self.assertEqual(response.json()["error"], "read-only-mvp")
+
+    def test_stub_pages_carry_nav_and_badges(self):
+        response = self.client.get("/inventory")
+        self.assertIn("mode: read-only", response.text)
+        self.assertIn('href="/queue"', response.text)
+
+
+class TestShellHome(unittest.TestCase):
+    def setUp(self):
+        self.client = TestClient(create_app())
+
+    def test_home_summarizes_console(self):
+        text = self.client.get("/").text
+        self.assertIn("Operator console", text)
+        self.assertIn("Phase 1", text)
+
+    def test_home_links_legacy_pages(self):
+        text = self.client.get("/").text
+        self.assertIn("MVP legacy pages", text)
+        for href in ("/queue", "/audit", "/leases"):
+            with self.subTest(href=href):
+                self.assertIn(f'href="{href}"', text)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_webui_system_health_dashboard.py

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

webui/app.py

@@ -12,6 +12,7 @@ from starlette.routing import Route
 
 from webui.deployment_boundary import deployment_snapshot
 from webui.layout import render_page
+from webui.nav import NAV_GROUPS, STUB_PAGES
 from webui.project_registry import (
     ProjectRegistry,
     RegistryError,
@@ -51,6 +52,7 @@ from webui.system_health import (
     process_uptime,
     snapshot_to_dict as system_health_to_dict,
 )
+from webui.system_health_views import render_system_health_page
 
 _READ_ONLY_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
 _AUDIT_MUTATION_PATHS = frozenset({"/audit", "/api/audit"})
@@ -65,24 +67,62 @@ def _stub_page(title: str, description: str) -> HTMLResponse:
     return HTMLResponse(render_page(title=title, body_html=body))
 
 
+_LEGACY_PAGES = (
+    ("/queue", "Queue", "live PR and issue dashboard (#429)"),
+    ("/projects", "Projects", "registry and onboarding (#427)"),
+    ("/prompts", "Prompts", "canonical workflow prompt library (#428)"),
+    ("/runtime", "Runtime", "MCP health and stale-runtime detection (#430)"),
+    ("/audit", "Audit", "final-report paste and validator preview (#431)"),
+    ("/worktrees", "Worktrees", "branch hygiene dashboard (#432)"),
+    ("/leases", "Leases", "collision and lease visibility (#433)"),
+    ("/actions", "Actions", "gated write-action framework (#434)"),
+)
+
+
+def _render_home_nav_groups() -> str:
+    groups = []
+    for group in NAV_GROUPS:
+        items = "".join(
+            f'<li><a href="{item.href}">{item.label}</a>'
+            + ("" if item.status == "live" else " <span class=\"muted\">(stub)</span>")
+            + "</li>"
+            for item in group.items
+        )
+        groups.append(f"<h3>{group.label}</h3><ul>{items}</ul>")
+    return "".join(groups)
+
+
 async def home(_request: Request) -> HTMLResponse:
+    legacy = "".join(
+        f"<li><strong>{label}</strong> — {desc} "
+        f'(<a href="{href}">{href}</a>)</li>'
+        for href, label, desc in _LEGACY_PAGES
+    )
     body = (
         "<h2>Operator console</h2>"
-        "<p>Local entry point for MCP Control Plane operational views.</p>"
-        "<ul>"
-        "<li><strong>Queue</strong> — live PR and issue dashboard (#429)</li>"
-        "<li><strong>Projects</strong> — registry and onboarding (#427)</li>"
-        "<li><strong>Prompts</strong> — canonical workflow prompt library (#428)</li>"
-        "<li><strong>Runtime</strong> — MCP health and stale-runtime detection (#430)</li>"
-        "<li><strong>Audit</strong> — final-report paste and validator preview (#431)</li>"
-        "<li><strong>Worktrees</strong> — branch hygiene dashboard (#432)</li>"
-        "<li><strong>Leases</strong> — collision and lease visibility (#433)</li>"
-        "<li><strong>Actions</strong> — gated write-action framework (#434)</li>"
-        "</ul>"
+        "<p>Read-only home for the MCP Control Plane Phase 1 operator console. "
+        "Gitea, MCP capability gates, and canonical workflows remain the source "
+        "of truth; this console never mutates them.</p>"
+        "<h2>Phase 1 surfaces</h2>"
+        + _render_home_nav_groups()
+        + "<h2>MVP legacy pages</h2>"
+        "<ul>" + legacy + "</ul>"
     )
     return HTMLResponse(render_page(title="Home", body_html=body))
 
 
+async def phase_stub(request: Request) -> HTMLResponse:
+    """Graceful read-only placeholder for a not-yet-implemented Phase 1 surface."""
+    title, description = STUB_PAGES[request.url.path]
+    body = (
+        f"<h2>{title}</h2>"
+        f'<div class="stub"><p>{description}</p>'
+        "<p>Phase 1 shell placeholder — no write actions. Tracked under "
+        "epic #631.</p></div>"
+    )
+    return HTMLResponse(render_page(title=title, body_html=body))
+
+
 async def health(_request: Request) -> JSONResponse:
     """Liveness only — deliberately cheap, runs no dependency probe (#634).
 
@@ -121,6 +161,24 @@ async def api_system_health(request: Request) -> JSONResponse:
     return JSONResponse(payload, status_code=200 if snapshot.ready else 503)
 
 
+async def system_health(request: Request) -> HTMLResponse:
+    """Read-only system-health dashboard (#639).
+
+    Shares the #634 snapshot loader with the JSON API so the page can never
+    disagree with it. `?deep=1` opts into the network probe exactly as the API
+    does; the default page load stays cheap. The response is always 200: this
+    is an operator view that must render the degraded state, not withhold it.
+    """
+    deep = _truthy_flag(request.query_params.get("deep"))
+    snapshot = load_system_health(deep=deep)
+    return HTMLResponse(
+        render_page(
+            title="System health",
+            body_html=render_system_health_page(snapshot),
+        )
+    )
+
+
 async def queue(_request: Request) -> HTMLResponse:
     snapshot = load_queue_snapshot()
     return HTMLResponse(render_page(title="Queue", body_html=render_queue_page(snapshot)))
@@ -433,6 +491,7 @@ def create_app(*, bind_host: str | None = None) -> Starlette:
             Route("/", home, methods=["GET"]),
             Route("/health", health, methods=["GET"]),
             Route(SYSTEM_HEALTH_API_PATH, api_system_health, methods=["GET"]),
+            Route("/system-health", system_health, methods=["GET"]),
             Route("/queue", queue, methods=["GET"]),
             Route("/api/queue", api_queue, methods=["GET"]),
             Route("/projects", projects, methods=["GET"]),
@@ -472,6 +531,10 @@ def create_app(*, bind_host: str | None = None) -> Starlette:
                 api_console_security_model,
                 methods=["GET"],
             ),
+            *[
+                Route(path, phase_stub, methods=["GET"])
+                for path in STUB_PAGES
+            ],
         ],
         exception_handlers={405: method_not_allowed},
     )

webui/layout.py

@@ -2,28 +2,66 @@
 
 from __future__ import annotations
 
-NAV_ITEMS = (
-    ("/", "Home"),
-    ("/queue", "Queue"),
-    ("/projects", "Projects"),
-    ("/prompts", "Prompts"),
-    ("/runtime", "Runtime"),
-    ("/audit", "Audit"),
-    ("/worktrees", "Worktrees"),
-    ("/leases", "Leases"),
-    ("/actions", "Actions"),
-)
+import os
+
+from webui.nav import NAV_GROUPS
 
 MVP_NOTICE = (
     "Read-only MVP — Gitea, MCP tools, and canonical workflows remain the "
     "source of truth. No mutation endpoints."
 )
 
+# Canonical docs entry point surfaced from the shell header (#638).
+DOCS_URL = (
+    "https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/src/branch/"
+    "master/docs/webui-local-dev.md"
+)
+
+_LOCAL_HOSTS = frozenset({"", "127.0.0.1", "localhost", "::1"})
+
+
+def environment_label() -> str:
+    """Classify the serving environment as ``local`` or ``remote`` (#638).
+
+    Derived from the same ``WEBUI_HOST`` default the app binds to; loopback
+    hosts are ``local``, anything else is ``remote``. Read-only signal only.
+    """
+    host = (os.environ.get("WEBUI_HOST", "127.0.0.1") or "").strip().lower()
+    return "local" if host in _LOCAL_HOSTS else "remote"
+
+
+def _render_nav() -> str:
+    groups_html = []
+    for group in NAV_GROUPS:
+        links = "".join(
+            f'<a href="{item.href}"'
+            + (' class="nav-stub"' if item.status == "stub" else "")
+            + f'>{item.label}</a>'
+            for item in group.items
+        )
+        groups_html.append(
+            '<div class="nav-group">'
+            f'<span class="nav-group-label">{group.label}</span>'
+            f'<span class="nav-group-links">{links}</span>'
+            "</div>"
+        )
+    return "".join(groups_html)
+
+
+def _render_badges() -> str:
+    env = environment_label()
+    return (
+        '<div class="header-badges">'
+        f'<span class="badge env-badge env-{env}">env: {env}</span>'
+        '<span class="badge mode-badge">mode: read-only</span>'
+        f'<a class="badge docs-link" href="{DOCS_URL}">Docs</a>'
+        "</div>"
+    )
+
 
 def render_page(*, title: str, body_html: str, extra_head: str = "") -> str:
-    nav_links = "".join(
-        f'<a href="{href}">{label}</a>' for href, label in NAV_ITEMS
-    )
+    nav_links = _render_nav()
+    header_badges = _render_badges()
     return f"""<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -53,21 +91,58 @@ def render_page(*, title: str, body_html: str, extra_head: str = "") -> str:
       padding: 0.75rem 1.25rem;
     }}
     header h1 {{
-      margin: 0 0 0.5rem;
+      margin: 0;
       font-size: 1.1rem;
       font-weight: 600;
     }}
+    .header-top {{
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      justify-content: space-between;
+      gap: 0.5rem 1rem;
+      margin-bottom: 0.6rem;
+    }}
+    .header-badges {{ display: inline-flex; flex-wrap: wrap; gap: 0.4rem; }}
+    .env-badge.env-local {{ color: #8fd19e; border-color: #3d6b4a; }}
+    .env-badge.env-remote {{ color: #e0c27a; border-color: #6b5730; }}
+    .mode-badge {{ color: #9ec8f0; border-color: #3d5f7a; }}
+    a.docs-link {{
+      color: var(--accent);
+      border-color: var(--accent);
+      text-decoration: none;
+      text-transform: none;
+    }}
+    a.docs-link:hover {{ filter: brightness(1.12); }}
     nav {{
       display: flex;
       flex-wrap: wrap;
-      gap: 0.75rem 1rem;
+      gap: 0.5rem 1.25rem;
     }}
+    .nav-group {{
+      display: flex;
+      flex-direction: column;
+      gap: 0.15rem;
+    }}
+    .nav-group-label {{
+      font-size: 0.68rem;
+      text-transform: uppercase;
+      letter-spacing: 0.04em;
+      color: var(--muted);
+    }}
+    .nav-group-links {{ display: inline-flex; flex-wrap: wrap; gap: 0.6rem; }}
     nav a {{
       color: var(--accent);
       text-decoration: none;
       font-size: 0.9rem;
     }}
     nav a:hover {{ text-decoration: underline; }}
+    nav a.nav-stub {{ color: var(--muted); }}
+    nav a.nav-stub::after {{
+      content: " ·stub";
+      font-size: 0.7rem;
+      color: var(--muted);
+    }}
     main {{
       max-width: 52rem;
       margin: 0 auto;
@@ -161,12 +236,34 @@ def render_page(*, title: str, body_html: str, extra_head: str = "") -> str:
     .badge-in-review {{ color: #9ec8f0; border-color: #3d5f7a; }}
     .badge-duplicate {{ color: #e0c27a; border-color: #6b5730; }}
     .badge-stale {{ color: #c9b8e8; border-color: #5a4a78; }}
+    .badge-health-ok {{ color: #8fd19e; border-color: #3d6b4a; }}
+    .badge-health-degraded {{ color: #e0c27a; border-color: #6b5730; }}
+    .badge-health-down {{ color: #f0a8a8; border-color: #7a3b3b; }}
+    .badge-health-skipped {{ color: var(--muted); }}
+    .badge-health-unproven {{ color: #c9b8e8; border-color: #5a4a78; }}
+    .health-card {{
+      margin: 1.25rem 0;
+      padding: 0.85rem 1rem 1rem;
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      background: var(--surface);
+    }}
+    .health-card h3 {{ margin: 0 0 0.5rem; font-size: 1.05rem; }}
+    .health-card h4 {{ margin: 1rem 0 0.35rem; font-size: 0.92rem; color: var(--muted); }}
+    .health-headline {{ color: var(--text); font-size: 1rem; margin: 0 0 0.5rem; }}
+    .health-degraded {{ border-left-color: #e0c27a; }}
+    .health-stale {{ border-left-color: #f0a8a8; }}
+    ul.reasons {{ margin: 0.35rem 0; padding-left: 1.15rem; color: var(--muted); font-size: 0.9rem; }}
+    ul.reasons li {{ margin-bottom: 0.3rem; }}
   </style>
   {extra_head}
 </head>
 <body>
   <header>
-    <h1>MCP Control Plane</h1>
+    <div class="header-top">
+      <h1>MCP Control Plane</h1>
+      {header_badges}
+    </div>
     <nav>{nav_links}</nav>
   </header>
   <main>

webui/nav.py

@@ -0,0 +1,112 @@
+"""Navigation IA for the Phase 1 operator console shell (#638).
+
+Single source of truth for the console navigation so ``webui/layout.py`` and
+the ``webui/app.py`` route table stay aligned with epic #631. Read-only: every
+destination is a GET view or a Phase 1 placeholder. No mutation links.
+
+Nav groups follow the #631 Phase 1 information architecture: Health, Traffic,
+Runtime/Sessions, Projects, Inventory, Timeline, Policy (placeholder), and
+Insights (placeholder). Later-phase surfaces are declared as ``stub`` items and
+backed by ``STUB_PAGES`` so their nav links resolve to a graceful placeholder
+instead of a 404.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class NavItem:
+    """A single navigation destination.
+
+    ``status`` is ``"live"`` for implemented views and ``"stub"`` for Phase 1
+    placeholders whose backing view lands in a later child issue.
+    """
+
+    href: str
+    label: str
+    status: str = "live"
+
+
+@dataclass(frozen=True)
+class NavGroup:
+    label: str
+    items: tuple[NavItem, ...]
+
+
+NAV_GROUPS: tuple[NavGroup, ...] = (
+    NavGroup("Health", (
+        NavItem("/health", "Liveness"),
+        NavItem("/system-health", "System health"),
+    )),
+    NavGroup("Traffic", (
+        NavItem("/queue", "Queue"),
+        NavItem("/leases", "Leases"),
+        NavItem("/actions", "Actions"),
+    )),
+    NavGroup("Runtime/Sessions", (
+        NavItem("/runtime", "Runtime health"),
+        NavItem("/sessions", "Sessions", "stub"),
+    )),
+    NavGroup("Projects", (
+        NavItem("/projects", "Projects"),
+    )),
+    NavGroup("Inventory", (
+        NavItem("/inventory", "Inventory", "stub"),
+        NavItem("/worktrees", "Worktrees"),
+    )),
+    NavGroup("Timeline", (
+        NavItem("/timeline", "Timeline", "stub"),
+    )),
+    NavGroup("Policy", (
+        NavItem("/policy", "Policy", "stub"),
+        NavItem("/prompts", "Prompts"),
+    )),
+    NavGroup("Insights", (
+        NavItem("/insights", "Insights", "stub"),
+        NavItem("/audit", "Audit"),
+    )),
+)
+
+
+# Phase 1 placeholder destinations whose backing views land in later child
+# 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. "
+        "Backed by the Phase 1 inventory API (#636).",
+    ),
+    "/timeline": (
+        "Timeline",
+        "Workflow event timeline across issues and PRs. A later Phase 1 surface.",
+    ),
+    "/policy": (
+        "Policy",
+        "Capability and role policy surface. Placeholder until a later phase.",
+    ),
+    "/insights": (
+        "Insights",
+        "Aggregate operational insights and trends. Placeholder until a later "
+        "phase.",
+    ),
+}
+
+
+def iter_nav_items():
+    """Yield every ``NavItem`` across all groups in declared order."""
+    for group in NAV_GROUPS:
+        for item in group.items:
+            yield item
+
+
+def nav_hrefs() -> tuple[str, ...]:
+    """Return every navigation href in declared order."""
+    return tuple(item.href for item in iter_nav_items())

webui/system_health_views.py

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