fix(webui): arm the recovery gates and make the playbooks reach the process (#644)

Reviewer REQUEST_CHANGES on PR #903 at head 1c88b87 raised five blockers, all reproduced by executing that head. The shared shape: a write path that declared itself gated, audited, and verified, but never armed the gate, mutated a copy of the state it claimed to fix, and then verified against that same copy. B1 - the apply path never asked the execution gate. execute_recovery_playbook called console_authz.authorize with the default for_execution=False, and the phase branch only fires when it is True. ACTIVE_PHASE is 1 and every new action is phase 2, so an operator executed a phase-2 write through POST /api/v1/system/recovery/apply while build_recovery_preview reported execution_enabled false. The call now passes for_execution=True and surfaces the phase_not_active refusal. Preview reports the same decision under execution_authorization / execution_blocked_reason instead of a hardcoded False it could not explain. B2 - both env playbooks mutated a discarded copy and verified against it. source_env = dict(os.environ) meant clear_stale_binding and rebind_session_worktree never touched the running process, and verify_post_recovery(env=source_env) re-diagnosed the same copy, confirming a change that had not happened. Mutations now target the live mapping (apply_recovery's sanctioned env=None -> os.environ path, #702 AC2) and verification re-reads state rather than the mutated input. binding_before / binding_after / binding_changed are returned, and a playbook that changed nothing reports performed: false. verify_post_recovery no longer reads an unverified_inherited binding as clean, because unproven is not clean. B3 - the reconcile playbook called a function that does not exist. merged_cleanup_reconcile.reconcile_merged_cleanups is absent from that module and a bare except turned the AttributeError into a generic failure, so the playbook could never succeed. It now calls gitea_mcp_server.gitea_reconcile_merged_cleanups, the real orchestrator, imported lazily; failures carry error_type. task_capability_map declared gitea.pr.close for reconcile_cleanups while the entry point gates on gitea.read; the two authority statements are reconciled to the one that is enforced. B4 - the #630 contamination integration could not block. assess_contamination_gate was fed marker=None, which short-circuits to block: False on its first statement; the task passed was a console action id outside CONTAMINATION_GATED_TASKS; and the result was read through a "contaminated" key the gate never returns, making STATUS_BLOCKED_CONTAMINATION unreachable. The live marker now comes from the #641 session inventory reader, the gated task key console_recovery_apply is added to CONTAMINATION_GATED_TASKS, every read uses the "block" key the gate actually returns, and the marker is forwarded to sanctioned_restart.execute_restart so a restart cannot launder a contaminated runtime. The reconciler cleanup playbook stays exempt as the designated remedy. B5 - the parity baseline was captured from the head it was compared against. capture_startup_parity(root, head=checkout_head) stores the head verbatim, so in_parity was structurally incapable of being false, and live_remote_head was never passed. The baseline is now the daemon start head that assess_stale_runtime already returns, and the #610 live-remote dimension is restored. Also: _recovery_card was the one renderer in system_health_views.py interpolating without _esc(), and it is where a marker's operator-supplied command_summary lands once B4 is wired; it now escapes, including the except branch. Docs no longer claim apply enforces master parity or that verify asserts clean: true, and the absolute file:///Users/... links are relative. Tests: the two that asserted the defects as intended are inverted - test_api_recovery_apply_with_dev_auth asserted the phase-gate bypass, and the rebind test asserted the input echoed back. Added coverage per blocker, including a no-op detection test that fails when a playbook reports success without changing anything, the previously untested reconcile playbook, contamination block and remedy-exemption tests, and parity baseline/live-remote tests. Both new guards were mutation-verified: disarming for_execution fails 2 tests, restoring the env copy fails 2 tests. Validation: WEBUI_TEST_OFFLINE=1 ../../venv/bin/python -m pytest tests/ -q from branches/feat-issue-644 gives 27 failed / 5291 passed / 6 skipped / 953 subtests; the same command from branches/baseline-master-76f293e at 76f293eb28 gives 28 failed / 5262 passed / 6 skipped / 926 subtests. Suites run one at a time. comm of the sorted FAILED lines shows no new signature at the head. The single absent signature, test_workspace_guard_alignment.py:: TestRuntimeContextGuardAlignment::test_declared_branches_worktree_passes_when_mcp_root_differs, is suite-order dependent: that file passes 9/9 in isolation at both revisions. Closes #644 Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-07-25 17:42:49 -04:00
parent 1c88b87ec5
commit 4a2fae8495
6 changed files with 567 additions and 78 deletions
@@ -2,7 +2,7 @@

 ## Overview

-Stale runtimes, worktree binding mismatches, and un-reconciled merged branches previously required expert manual shell recovery. Manual process kills (`pkill -f mcp_server.py`) are strictly forbidden and classified as runtime contamination ([#630](file:///Users/jasonwalker/Development/Gitea-Tools/docs/sanctioned-restart-controls.md)).
+Stale runtimes, worktree binding mismatches, and un-reconciled merged branches previously required expert manual shell recovery. Manual process kills (`pkill -f mcp_server.py`) are strictly forbidden and classified as runtime contamination ([#630](sanctioned-restart-controls.md)).

 Phase 2 introduces **sanctioned recovery playbooks and controls** into the Web Console:
 - **Diagnose**: Surface stale runtimes, worktree binding errors, contamination markers, and worktree anomalies via health & inventory APIs.
@@ -16,10 +16,10 @@ Phase 2 introduces **sanctioned recovery playbooks and controls** into the Web C

 | Playbook ID | Action ID | Minimum Role | Target / Scope | Description |
 |---|---|---|---|---|
-| `clear_stale_binding` | `system.clear_stale_binding` | Operator | Active worktree binding | Clear provably missing or superseded `GITEA_ACTIVE_WORKTREE` binding ([#702](file:///Users/jasonwalker/Development/Gitea-Tools/stale_binding_recovery.py)). |
-| `rebind_session_worktree` | `system.rebind_session_worktree` | Operator | Session worktree | Rebind or synchronize session worktree to verified lease worktree ([#864](file:///Users/jasonwalker/Development/Gitea-Tools/dirty_same_claimant_session_rebind.py)). |
+| `clear_stale_binding` | `system.clear_stale_binding` | Operator | Active worktree binding | Clear provably missing or superseded `GITEA_ACTIVE_WORKTREE` binding ([#702](../stale_binding_recovery.py)). |
+| `rebind_session_worktree` | `system.rebind_session_worktree` | Operator | Session worktree | Rebind or synchronize session worktree to verified lease worktree ([#864](../dirty_same_claimant_session_rebind.py)). |
 | `reconcile_cleanups` | `system.reconcile_cleanups` | Controller | Worktree hygiene | Execute reconciler cleanup preview and apply for merged/superseded PR branches. |
-| `sanctioned_restart` | `system.restart_namespace` | Admin | MCP Namespace | Restart MCP daemon gracefully via host supervisor ([#642](file:///Users/jasonwalker/Development/Gitea-Tools/docs/sanctioned-restart-controls.md)). |
+| `sanctioned_restart` | `system.restart_namespace` | Admin | MCP Namespace | Restart MCP daemon gracefully via host supervisor ([#642](sanctioned-restart-controls.md)). |

 ---

@@ -42,16 +42,18 @@ Returns:
 - **Authorization Decision**: RBAC check against the operator's principal.

 ### 3. Apply (`POST /api/v1/system/recovery/apply`)
-Requires `playbook_id` and matching `confirmation` phrase.
- Validates RBAC permissions (`console_authz`).
- Verifies confirmation phrase (`confirmation_matches`).
- Enforces contamination rules ([#630](file:///Users/jasonwalker/Development/Gitea-Tools/docs/sanctioned-restart-controls.md)): A contaminated runtime must be cleared through reconciler cleanup before other playbooks run.
- Enforces master parity ([#610](file:///Users/jasonwalker/Development/Gitea-Tools/master_parity_gate.py)).
- Applies sanctioned recovery logic.
- Logs audit record in `console_audit`.
+Requires `playbook_id` and matching `confirmation` phrase. Gates run in this order, and each fails closed before anything is mutated:
+
+1. **RBAC and execution phase** (`console_authz.authorize(..., for_execution=True)`). The phase branch only applies when `for_execution` is set. While `ACTIVE_PHASE` is `1`, every phase-2 recovery action is refused with `phase_not_active`, so no recovery playbook writes yet. Preview reports the same decision under `execution_authorization` / `execution_blocked_reason`.
+2. **Confirmation phrase** (`confirmation_matches`).
+3. **Contamination rules** ([#630](sanctioned-restart-controls.md)): the live marker is read from the session inventory and assessed under the gated task key `console_recovery_apply`. A contaminated runtime must be cleared through the reconciler cleanup playbook, which is the one playbook exempted from this gate because it is the designated remedy. The marker is also forwarded to `sanctioned_restart.execute_restart`, so a restart cannot launder a contaminated runtime.
+
+Apply then executes the sanctioned recovery logic against the **live** process environment — not a copy — and records an audit entry in `console_audit`. A playbook that leaves the binding unchanged reports `performed: false`; `binding_before`, `binding_after`, and `binding_changed` are returned so a no-op cannot read as success.
+
+Apply does **not** enforce master parity. Parity is reported by Diagnose ([#610](../master_parity_gate.py)) as evidence for the operator; it is not a precondition of this endpoint.

 ### 4. Verify (`POST /api/v1/system/recovery/verify`)
-Re-evaluates control-plane diagnostics post-recovery. Asserts `clean: true` before transitioning out of recovery mode.
+Re-evaluates control-plane diagnostics post-recovery and **reports** `clean`, `stale_runtime_clean`, `binding_clean`, `binding_classification`, and `contamination_clean`. It reports; it does not assert or block. State is read fresh rather than from the mapping a mutation just wrote. An `unverified_inherited` binding is reported as not clean, because unproven is not clean.

 ---

@@ -63,6 +63,11 @@ CONTAMINATION_GATED_TASKS = frozenset({
    "merge_pr",
    "delete_branch",
    "complete_issue",
+    # Web console recovery playbooks that write (#644). These mutate runtime
+    # binding and process state, so a live contamination marker must block them
+    # exactly as it blocks the Gitea-side mutations above. The reconciler
+    # cleanup playbook is the designated remedy and is exempted by its caller.
+    "console_recovery_apply",
 })

 CONTAMINATION_KIND = "stable_branch_push"
@@ -151,8 +151,12 @@ TASK_CAPABILITY_MAP: dict[str, dict[str, str]] = {
        "permission": "gitea.read",
        "role": "author",
    },
+    # The console playbook orchestrates gitea_reconcile_merged_cleanups, whose
+    # own gate is gitea.read (matching the existing reconcile_merged_cleanups
+    # entry). Declaring a stricter permission here stated a second, conflicting
+    # authority for one operation.
    "reconcile_cleanups": {
-        "permission": "gitea.pr.close",
+        "permission": "gitea.read",
        "role": "reconciler",
    },
    # PR synchronization lifecycle: assess is read-only (any role with gitea.read);
@@ -2,14 +2,19 @@

 from __future__ import annotations

-import json
 import os
+import sys
+import types
 import unittest
 from unittest.mock import patch

 from starlette.testclient import TestClient

-from webui import console_audit, console_authz, console_recovery
+import merged_cleanup_reconcile
+import runtime_recovery_guard
+import stable_branch_push_guard
+import stale_binding_recovery
+from webui import console_authz, console_recovery, system_health
 from webui.app import create_app


@@ -56,12 +61,15 @@ class TestConsoleRecovery(unittest.TestCase):
        self.assertEqual(preview.get("error"), "unknown_playbook")

    def test_execute_recovery_playbook_confirmation_mismatch(self) -> None:
+        # Authorization is checked before confirmation, so the phase gate has to
+        # pass for this test to reach the branch it is about.
        principal = console_authz.Principal("[email protected]", console_authz.OPERATOR, console_authz.IDENTITY_LOCAL_DEV, True)
-        result = console_recovery.execute_recovery_playbook(
-            playbook_id=console_recovery.PLAYBOOK_CLEAR_STALE_BINDING,
-            confirmation="invalid confirmation",
-            principal=principal,
-        )
+        with self._phase_two_enabled():
+            result = console_recovery.execute_recovery_playbook(
+                playbook_id=console_recovery.PLAYBOOK_CLEAR_STALE_BINDING,
+                confirmation="invalid confirmation",
+                principal=principal,
+            )
        self.assertFalse(result["success"])
        self.assertFalse(result["allowed"])
        self.assertEqual(result["error"], "confirmation_mismatch")
@@ -77,35 +85,303 @@ class TestConsoleRecovery(unittest.TestCase):
        self.assertFalse(result["allowed"])
        self.assertEqual(result["error"], console_authz.DENY_UNAUTHENTICATED)

-    def test_execute_recovery_playbook_clear_stale_binding_success(self) -> None:
-        principal = console_authz.Principal("[email protected]", console_authz.OPERATOR, console_authz.IDENTITY_LOCAL_DEV, True)
-        phrase = console_recovery.confirmation_phrase(console_recovery.PLAYBOOK_CLEAR_STALE_BINDING)
-        
+    def test_execute_refuses_phase_two_write_while_console_is_phase_one(self) -> None:
+        """B1: the apply path must arm the phase gate, not skip it.
+
+        ``authorize`` only applies the phase branch when ``for_execution=True``.
+        The apply path used the default, so an operator executed a phase-2 write
+        while ``ACTIVE_PHASE`` was 1.
+        """
+        self.assertGreater(
+            console_authz.get_action(console_recovery.ACTION_CLEAR_STALE_BINDING).phase,
+            console_authz.ACTIVE_PHASE,
+            "fixture assumes the recovery actions are ahead of the active phase",
+        )
+        principal = console_authz.Principal(
+            "[email protected]", console_authz.OPERATOR, console_authz.IDENTITY_LOCAL_DEV, True
+        )
+        phrase = console_recovery.confirmation_phrase(
+            console_recovery.PLAYBOOK_CLEAR_STALE_BINDING
+        )
        result = console_recovery.execute_recovery_playbook(
            playbook_id=console_recovery.PLAYBOOK_CLEAR_STALE_BINDING,
            confirmation=phrase,
            principal=principal,
        )
-        self.assertTrue(result["allowed"])
-        self.assertIn("applied_result", result)
-        self.assertIn("post_recovery_verification", result)
+        self.assertFalse(result["success"])
+        self.assertFalse(result["allowed"])
+        self.assertEqual(result["error"], console_authz.DENY_PHASE_NOT_ACTIVE)

-        self.assertIn("audit", result)
-        self.assertEqual(result["audit"]["event"]["action"], console_recovery.ACTION_CLEAR_STALE_BINDING)
-
-    def test_execute_recovery_playbook_rebind_session_success(self) -> None:
-        principal = console_authz.Principal("[email protected]", console_authz.OPERATOR, console_authz.IDENTITY_LOCAL_DEV, True)
-        phrase = console_recovery.confirmation_phrase(console_recovery.PLAYBOOK_REBIND_SESSION, "branches/feat-issue-644")
-        
-        result = console_recovery.execute_recovery_playbook(
+    def test_preview_execution_enabled_matches_the_execution_decision(self) -> None:
+        """B1: preview must not report a bare False it cannot explain."""
+        principal = console_authz.Principal(
+            "[email protected]", console_authz.OPERATOR, console_authz.IDENTITY_LOCAL_DEV, True
+        )
+        preview = console_recovery.build_recovery_preview(
            playbook_id=console_recovery.PLAYBOOK_REBIND_SESSION,
-            confirmation=phrase,
            target="branches/feat-issue-644",
            principal=principal,
        )
-        self.assertTrue(result["allowed"])
+        self.assertFalse(preview["execution_enabled"])
+        self.assertEqual(
+            preview["execution_blocked_reason"], console_authz.DENY_PHASE_NOT_ACTIVE
+        )
+        self.assertFalse(preview["execution_authorization"]["allowed"])
+        # The preview (non-execution) decision still allows, by role.
+        self.assertTrue(preview["authorization"]["allowed"])
+
+    def _phase_two_enabled(self):
+        """Raise ACTIVE_PHASE so the execution branches are reachable in tests."""
+        return patch.object(console_authz, "ACTIVE_PHASE", 2)
+
+    def _operator(self) -> console_authz.Principal:
+        return console_authz.Principal(
+            "[email protected]", console_authz.OPERATOR, console_authz.IDENTITY_LOCAL_DEV, True
+        )
+
+    def test_rebind_mutates_the_live_environment_not_a_copy(self) -> None:
+        """B2: the playbook must change the mapping it claims to have changed."""
+        live_env = {stale_binding_recovery.ACTIVE_WORKTREE_ENV: "branches/stale-old"}
+        phrase = console_recovery.confirmation_phrase(
+            console_recovery.PLAYBOOK_REBIND_SESSION, "branches/feat-issue-644"
+        )
+        with self._phase_two_enabled():
+            result = console_recovery.execute_recovery_playbook(
+                playbook_id=console_recovery.PLAYBOOK_REBIND_SESSION,
+                confirmation=phrase,
+                target="branches/feat-issue-644",
+                principal=self._operator(),
+                env=live_env,
+            )
        self.assertTrue(result["success"])
-        self.assertEqual(result["applied_result"]["rebound_worktree"], "branches/feat-issue-644")
+        self.assertEqual(
+            live_env[stale_binding_recovery.ACTIVE_WORKTREE_ENV],
+            "branches/feat-issue-644",
+            "rebind reported success without changing the caller's environment",
+        )
+        self.assertTrue(result["applied_result"]["binding_changed"])
+        self.assertEqual(result["applied_result"]["binding_before"], "branches/stale-old")
+        self.assertEqual(
+            result["applied_result"]["binding_after"], "branches/feat-issue-644"
+        )
+
+    def test_clear_stale_binding_reports_failure_when_nothing_changed(self) -> None:
+        """B2: a no-op recovery must never be reported as success."""
+        live_env: dict[str, str] = {}
+        phrase = console_recovery.confirmation_phrase(
+            console_recovery.PLAYBOOK_CLEAR_STALE_BINDING
+        )
+        with self._phase_two_enabled():
+            result = console_recovery.execute_recovery_playbook(
+                playbook_id=console_recovery.PLAYBOOK_CLEAR_STALE_BINDING,
+                confirmation=phrase,
+                principal=self._operator(),
+                env=live_env,
+            )
+        self.assertFalse(
+            result["success"],
+            "a clear that changed no binding must not report success",
+        )
+        self.assertFalse(result["applied_result"]["binding_changed"])
+
+    def test_clear_stale_binding_clears_the_live_binding(self) -> None:
+        """B2: the sanctioned clear must reach the caller's environment."""
+        missing = "/nonexistent/branches/deleted-worktree"
+        live_env = {stale_binding_recovery.ACTIVE_WORKTREE_ENV: missing}
+        phrase = console_recovery.confirmation_phrase(
+            console_recovery.PLAYBOOK_CLEAR_STALE_BINDING
+        )
+        with self._phase_two_enabled():
+            result = console_recovery.execute_recovery_playbook(
+                playbook_id=console_recovery.PLAYBOOK_CLEAR_STALE_BINDING,
+                confirmation=phrase,
+                principal=self._operator(),
+                env=live_env,
+            )
+        if result["success"]:
+            self.assertNotIn(stale_binding_recovery.ACTIVE_WORKTREE_ENV, live_env)
+            self.assertEqual(result["applied_result"]["binding_before"], missing)
+            self.assertIsNone(result["applied_result"]["binding_after"])
+        else:
+            # Fail closed is acceptable; reporting a clear that did not happen
+            # is not. This is the invariant the blocker was about.
+            self.assertFalse(result["applied_result"]["binding_changed"])
+            self.assertEqual(
+                live_env.get(stale_binding_recovery.ACTIVE_WORKTREE_ENV), missing
+            )
+
+    def test_reconcile_playbook_calls_an_entry_point_that_exists(self) -> None:
+        """B3: the previous call named a function absent from the module."""
+        phrase = console_recovery.confirmation_phrase(
+            console_recovery.PLAYBOOK_RECONCILE_CLEANUPS
+        )
+        fake_server = types.SimpleNamespace(
+            gitea_reconcile_merged_cleanups=lambda **kwargs: {
+                "success": True,
+                "entries": [{"issue_number": 100}],
+            }
+        )
+        with self._phase_two_enabled(), patch.dict(
+            sys.modules, {"gitea_mcp_server": fake_server}
+        ):
+            result = console_recovery.execute_recovery_playbook(
+                playbook_id=console_recovery.PLAYBOOK_RECONCILE_CLEANUPS,
+                confirmation=phrase,
+                principal=console_authz.Principal(
+                    "[email protected]",
+                    console_authz.ADMIN,
+                    console_authz.IDENTITY_LOCAL_DEV,
+                    True,
+                ),
+            )
+        self.assertTrue(result["success"], result.get("applied_result"))
+        self.assertNotIn("error_type", result["applied_result"])
+        self.assertEqual(result["applied_result"]["reconciled_count"], 1)
+
+    def test_reconcile_entry_point_exists_on_the_real_module(self) -> None:
+        """B3 regression: guard the symbol itself, not just the call shape."""
+        import gitea_mcp_server
+
+        self.assertTrue(
+            hasattr(gitea_mcp_server, "gitea_reconcile_merged_cleanups"),
+            "console recovery depends on this reconciler entry point",
+        )
+        self.assertFalse(
+            hasattr(merged_cleanup_reconcile, "reconcile_merged_cleanups"),
+            "if this module grows the orchestrator, point the playbook back at it",
+        )
+
+    def test_contamination_gate_blocks_a_writing_playbook(self) -> None:
+        """B4: a live marker plus a gated task key must actually block."""
+        marker = {
+            "kind": "manual_daemon_kill",
+            "reason_class": "manual_daemon_kill",
+            "command_summary": "pkill -f gitea_mcp_server",
+            "active": True,
+        }
+        phrase = console_recovery.confirmation_phrase(
+            console_recovery.PLAYBOOK_REBIND_SESSION, "branches/feat-issue-644"
+        )
+        live_env = {stale_binding_recovery.ACTIVE_WORKTREE_ENV: "branches/stale-old"}
+        with self._phase_two_enabled(), patch.object(
+            console_recovery, "load_active_contamination_marker", return_value=marker
+        ):
+            result = console_recovery.execute_recovery_playbook(
+                playbook_id=console_recovery.PLAYBOOK_REBIND_SESSION,
+                confirmation=phrase,
+                target="branches/feat-issue-644",
+                principal=self._operator(),
+                env=live_env,
+            )
+        self.assertFalse(result["success"])
+        self.assertEqual(result["error"], "contaminated_runtime")
+        self.assertEqual(
+            live_env[stale_binding_recovery.ACTIVE_WORKTREE_ENV],
+            "branches/stale-old",
+            "a blocked playbook must not have mutated anything",
+        )
+
+    def test_contamination_gate_exempts_the_reconciler_remedy(self) -> None:
+        """B4: the designated remedy must stay reachable while contaminated."""
+        marker = {
+            "kind": "manual_daemon_kill",
+            "reason_class": "manual_daemon_kill",
+            "command_summary": "pkill -f gitea_mcp_server",
+            "active": True,
+        }
+        phrase = console_recovery.confirmation_phrase(
+            console_recovery.PLAYBOOK_RECONCILE_CLEANUPS
+        )
+        fake_server = types.SimpleNamespace(
+            gitea_reconcile_merged_cleanups=lambda **kwargs: {
+                "success": True,
+                "entries": [],
+            }
+        )
+        with self._phase_two_enabled(), patch.object(
+            console_recovery, "load_active_contamination_marker", return_value=marker
+        ), patch.dict(sys.modules, {"gitea_mcp_server": fake_server}):
+            result = console_recovery.execute_recovery_playbook(
+                playbook_id=console_recovery.PLAYBOOK_RECONCILE_CLEANUPS,
+                confirmation=phrase,
+                principal=console_authz.Principal(
+                    "[email protected]",
+                    console_authz.ADMIN,
+                    console_authz.IDENTITY_LOCAL_DEV,
+                    True,
+                ),
+            )
+        self.assertNotEqual(result.get("error"), "contaminated_runtime")
+
+    def test_gated_task_key_is_actually_gated(self) -> None:
+        """B4: the console action id was never a member of the gated set."""
+        self.assertIn(
+            console_recovery.CONTAMINATION_GATED_TASK,
+            stable_branch_push_guard.CONTAMINATION_GATED_TASKS,
+        )
+        self.assertNotIn(
+            console_recovery.ACTION_CLEAR_STALE_BINDING,
+            stable_branch_push_guard.CONTAMINATION_GATED_TASKS,
+        )
+
+    def test_diagnosis_reads_the_key_the_gate_returns(self) -> None:
+        """B4: ``contaminated`` is a key assess_contamination_gate never returns."""
+        gate = runtime_recovery_guard.assess_contamination_gate(
+            None, task=console_recovery.CONTAMINATION_GATED_TASK, actual_role="operator"
+        )
+        self.assertNotIn("contaminated", gate)
+        self.assertIn("block", gate)
+
+    def test_contaminated_runtime_is_reported_unclean(self) -> None:
+        """B4: verify_post_recovery reported contamination_clean unconditionally."""
+        marker = {
+            "kind": "manual_daemon_kill",
+            "reason_class": "manual_daemon_kill",
+            "command_summary": "pkill -f gitea_mcp_server",
+            "active": True,
+        }
+        with patch.object(
+            console_recovery, "load_active_contamination_marker", return_value=marker
+        ):
+            verification = console_recovery.verify_post_recovery()
+            diag = console_recovery.diagnose_recovery()
+        self.assertFalse(verification["contamination_clean"])
+        self.assertFalse(verification["clean"])
+        self.assertEqual(diag.status, console_recovery.STATUS_BLOCKED_CONTAMINATION)
+
+    def test_master_parity_baseline_is_not_the_head_it_is_compared_against(self) -> None:
+        """B5: capture_startup_parity was fed the head it was then compared to."""
+        stale = system_health.StaleRuntime(
+            daemon_head="a" * 40,
+            checkout_head="b" * 40,
+            remote_head="b" * 40,
+            stale=True,
+            determinable=True,
+            mutation_safe=False,
+            reasons=("daemon is behind the checkout",),
+        )
+        with patch.object(system_health, "assess_stale_runtime", return_value=stale):
+            diag = console_recovery.diagnose_recovery()
+        parity = diag.master_parity
+        self.assertEqual(parity["startup_head"], "a" * 40)
+        self.assertEqual(parity["current_head"], "b" * 40)
+        self.assertNotEqual(parity["startup_head"], parity["current_head"])
+        self.assertFalse(parity["in_parity"])
+
+    def test_master_parity_carries_the_live_remote_dimension(self) -> None:
+        """B5: live_remote_head was never passed, dropping the #610 dimension."""
+        stale = system_health.StaleRuntime(
+            daemon_head="c" * 40,
+            checkout_head="c" * 40,
+            remote_head="d" * 40,
+            stale=False,
+            determinable=True,
+            mutation_safe=False,
+            reasons=(),
+        )
+        with patch.object(system_health, "assess_stale_runtime", return_value=stale):
+            diag = console_recovery.diagnose_recovery()
+        self.assertEqual(diag.master_parity.get("live_remote_head"), "d" * 40)

    def test_verify_post_recovery(self) -> None:
        verification = console_recovery.verify_post_recovery()
@@ -113,6 +389,32 @@ class TestConsoleRecovery(unittest.TestCase):
        self.assertIn("status", verification)
        self.assertIn("reasons", verification)

+    def test_unverified_inherited_binding_is_not_reported_clean(self) -> None:
+        """B2: ``not clear_eligible`` also read clean for unproven bindings."""
+        binding = {
+            "classification": stale_binding_recovery.CLASSIFICATION_UNVERIFIED_INHERITED,
+            "clear_eligible": False,
+        }
+        diag = console_recovery.diagnose_recovery()
+        patched = console_recovery.RecoveryDiagnosis(
+            status=diag.status,
+            clean=diag.clean,
+            stale_runtime=diag.stale_runtime,
+            master_parity=diag.master_parity,
+            stale_binding=binding,
+            contamination=diag.contamination,
+            worktree_anomalies=diag.worktree_anomalies,
+            playbooks=diag.playbooks,
+            reasons=diag.reasons,
+        )
+        with patch.object(console_recovery, "diagnose_recovery", return_value=patched):
+            verification = console_recovery.verify_post_recovery()
+        self.assertFalse(verification["binding_clean"])
+        self.assertEqual(
+            verification["binding_classification"],
+            stale_binding_recovery.CLASSIFICATION_UNVERIFIED_INHERITED,
+        )
+

 class TestConsoleRecoveryApi(unittest.TestCase):
    def setUp(self) -> None:
@@ -149,12 +451,19 @@ class TestConsoleRecoveryApi(unittest.TestCase):
        self.assertFalse(data["success"])
        self.assertFalse(data["allowed"])

-    def test_api_recovery_apply_with_dev_auth(self) -> None:
+    def test_api_recovery_apply_refuses_phase_two_write_with_dev_auth(self) -> None:
+        """B1: this previously asserted the phase-gate bypass as intended.
+
+        An authenticated operator posting a valid confirmation still must not
+        execute a phase-2 write while the console is in phase 1. The refusal is
+        the contract; a 200 here means the gate is not armed.
+        """
        env = {
            "WEBUI_AUTH_MODE": "local_dev",
            "WEBUI_DEV_SUBJECT": "[email protected]",
            "WEBUI_DEV_ROLE": "operator",
        }
+        before = os.environ.get("GITEA_ACTIVE_WORKTREE")
        with patch.dict(os.environ, env):
            res = self.client.post(
                "/api/v1/system/recovery/apply",
@@ -164,11 +473,26 @@ class TestConsoleRecoveryApi(unittest.TestCase):
                    "confirmation": "confirm rebind_session_worktree branches/feat-issue-644",
                },
            )
-            self.assertEqual(res.status_code, 200)
+            self.assertEqual(res.status_code, 400)
            data = res.json()
-            self.assertTrue(data["success"])
-            self.assertTrue(data["allowed"])
-            self.assertEqual(data["playbook_id"], "rebind_session_worktree")
+            self.assertFalse(data["success"])
+            self.assertFalse(data["allowed"])
+            self.assertEqual(data["error"], console_authz.DENY_PHASE_NOT_ACTIVE)
+        self.assertEqual(
+            os.environ.get("GITEA_ACTIVE_WORKTREE"),
+            before,
+            "a refused apply must not have rebound the live process environment",
+        )
+
+    def test_api_recovery_preview_reports_why_execution_is_disabled(self) -> None:
+        res = self.client.post(
+            "/api/v1/system/recovery/preview",
+            json={"playbook_id": "rebind_session_worktree", "target": "active"},
+        )
+        self.assertEqual(res.status_code, 200)
+        data = res.json()
+        self.assertFalse(data["execution_enabled"])
+        self.assertIn("execution_authorization", data)

    def test_api_recovery_verify(self) -> None:
        res = self.client.get("/api/v1/system/recovery/verify")
@@ -17,7 +17,6 @@ from pathlib import Path
 from typing import Any

 import master_parity_gate
-import merged_cleanup_reconcile
 import runtime_recovery_guard
 import stale_binding_recovery
 from webui import console_audit, console_authz, sanctioned_restart, system_health, worktree_scanner
@@ -53,6 +52,57 @@ PLAYBOOK_ACTIONS: dict[str, str] = {
    PLAYBOOK_SANCTIONED_RESTART: sanctioned_restart.ACTION_RESTART_NAMESPACE,
 }

+#: Task key handed to :func:`runtime_recovery_guard.assess_contamination_gate`.
+#: A console *action id* is not a task name and is not a member of
+#: ``CONTAMINATION_GATED_TASKS``, so passing one left the #630 gate inert. Every
+#: writing recovery playbook shares this one gated task key; the reconciler
+#: cleanup playbook is exempted separately because it is the designated remedy.
+CONTAMINATION_GATED_TASK = "console_recovery_apply"
+
+#: Remote whose contamination markers govern this console. Markers are written
+#: per remote, so reading the wrong one reports a contaminated runtime clean.
+REMOTE_ENV = "WEBUI_GITEA_REMOTE"
+DEFAULT_REMOTE = "prgs"
+
+
+def _console_remote(env: dict[str, str] | None = None) -> str:
+    env_map = env if env is not None else os.environ
+    return (env_map.get(REMOTE_ENV) or "").strip() or DEFAULT_REMOTE
+
+
+def load_active_contamination_marker(
+    remote: str | None = None, env: dict[str, str] | None = None
+) -> dict[str, Any] | None:
+    """Return the live #630 contamination marker payload, or ``None``.
+
+    The gate is only meaningful when it is fed a real marker: with
+    ``marker=None`` :func:`assess_contamination_gate` returns ``block: False``
+    on its first statement. The #641 session inventory already reads the durable
+    markers, so reuse that reader rather than adding a second source of truth.
+    Never raises into a diagnosis or execution path.
+    """
+    try:
+        from webui import session_loader
+    except Exception:  # noqa: BLE001 — never break recovery on an import problem
+        return None
+    try:
+        markers = session_loader._load_contamination_markers(
+            remote=remote or _console_remote(env)
+        )
+    except Exception:  # noqa: BLE001 — fail soft; the caller degrades to no marker
+        return None
+    for marker in markers:
+        payload = marker.to_dict()
+        if payload.get("active"):
+            return payload
+    return None
+
+
+def _active_binding(env_map: Any) -> str | None:
+    """Read the live worktree binding so a no-op recovery cannot report success."""
+    value = env_map.get(stale_binding_recovery.ACTIVE_WORKTREE_ENV)
+    return value if value else None
+

@dataclass(frozen=True)
 class RecoveryLedgerEntry:
@@ -210,9 +260,19 @@ def diagnose_recovery(
        reasons.append("Runtime HEAD disagrees with checkout/remote HEAD.")

    # 2. Master parity assessment
+    #
+    # The baseline is the commit the *running process* started at, which is what
+    # the parity gate is about. Capturing it from ``checkout_head`` and then
+    # comparing it against that same value made ``in_parity`` structurally
+    # incapable of being false. ``live_remote_head`` restores the #610
+    # live-remote dimension, which was previously dropped.
    checkout_head = stale_runtime_obj.checkout_head
-    startup_dict = master_parity_gate.capture_startup_parity(str(root), head=checkout_head)
-    parity_dict = master_parity_gate.assess_master_parity(startup_dict, checkout_head)
+    startup_dict = master_parity_gate.capture_startup_parity(
+        str(root), head=stale_runtime_obj.daemon_head
+    )
+    parity_dict = master_parity_gate.assess_master_parity(
+        startup_dict, checkout_head, stale_runtime_obj.remote_head
+    )
    if not parity_dict.get("in_parity", True):
        reasons.append("Repository is not in master parity.")

@@ -245,10 +305,18 @@ def diagnose_recovery(
        reasons.append("Inherited worktree binding is unverified.")

    # 4. Contamination assessment (#630)
+    #
+    # A real marker and a task key the gate actually gates on: with marker=None
+    # the gate short-circuits to ``block: False``, and with a console action id
+    # the task is outside CONTAMINATION_GATED_TASKS, so it could never block.
+    contamination_marker = load_active_contamination_marker(env=source_env)
    contamination_dict = runtime_recovery_guard.assess_contamination_gate(
-        marker=None, task=None, actual_role=role_kind
+        contamination_marker,
+        task=CONTAMINATION_GATED_TASK,
+        actual_role=role_kind,
    )
-    if contamination_dict.get("block"):
+    contaminated = bool(contamination_dict.get("block"))
+    if contaminated:
        reasons.append("Runtime is contaminated by manual process kill (#630).")

    # 5. Worktree scanner hygiene & anomalies
@@ -317,7 +385,7 @@ def diagnose_recovery(
    )

    # Playbook 4: Sanctioned Restart
-    restart_eligible = bool(stale_runtime_obj.stale or contamination_dict.get("contaminated"))
+    restart_eligible = bool(stale_runtime_obj.stale or contaminated)
    playbooks.append(
        PlaybookDescriptor(
            playbook_id=PLAYBOOK_SANCTIONED_RESTART,
@@ -335,8 +403,8 @@ def diagnose_recovery(
        )
    )

-    clean = not reasons and not contamination_dict.get("contaminated")
-    if contamination_dict.get("contaminated"):
+    clean = not reasons and not contaminated
+    if contaminated:
        status = STATUS_BLOCKED_CONTAMINATION
    elif reasons:
        status = STATUS_ACTION_REQUIRED
@@ -374,6 +442,13 @@ def build_recovery_preview(
    action_id = PLAYBOOK_ACTIONS[playbook_id]
    action = console_authz.get_action(action_id)
    decision = console_authz.authorize(action_id, principal)
+    # Preview and apply must answer the same question. ``execution_enabled`` was
+    # a hardcoded False beside an authorization decision taken without
+    # ``for_execution``, so the preview could not tell an operator *why*
+    # execution was disabled — and the apply path did not ask at all.
+    execution_decision = console_authz.authorize(
+        action_id, principal, for_execution=True
+    )
    phrase = confirmation_phrase(playbook_id, target)
    ledger = _build_ledger(playbook_id, target)

@@ -387,8 +462,12 @@ def build_recovery_preview(
        "confirmation_phrase": phrase,
        "mutation_ledger": [asdict(entry) for entry in ledger],
        "authorization": decision.to_dict(),
+        "execution_authorization": execution_decision.to_dict(),
        "params": dict(params or {}),
-        "execution_enabled": False,
+        "execution_enabled": bool(execution_decision.allowed),
+        "execution_blocked_reason": (
+            None if execution_decision.allowed else execution_decision.reason_code
+        ),
    }


@@ -412,10 +491,15 @@ def execute_recovery_playbook(
        }

    action_id = PLAYBOOK_ACTIONS[playbook_id]
-    source_env = dict(env) if env is not None else dict(os.environ)
+    # The mapping the playbooks actually mutate. ``dict(os.environ)`` produced a
+    # throwaway copy: every env playbook wrote to it, verified against it, and
+    # left the running daemon bound to the value it claimed to have fixed.
+    mutation_env: Any = env if env is not None else os.environ

-    # 1. Authorization check
-    decision = console_authz.authorize(action_id, principal)
+    # 1. Authorization check — ``for_execution=True`` is what arms the phase
+    # gate (console_authz.authorize only applies it in that branch). Without it
+    # a phase-2 write executed while the console was in phase 1.
+    decision = console_authz.authorize(action_id, principal, for_execution=True)
    if not decision.allowed:
        console_audit.record_event(
            action_id=action_id,
@@ -458,7 +542,12 @@ def execute_recovery_playbook(

    # 3. Contamination rule (#630) check
    role_str = principal.role if principal else None
-    contam = runtime_recovery_guard.assess_contamination_gate(marker=None, task=action_id, actual_role=role_str)
+    contamination_marker = load_active_contamination_marker(env=env)
+    contam = runtime_recovery_guard.assess_contamination_gate(
+        contamination_marker,
+        task=CONTAMINATION_GATED_TASK,
+        actual_role=role_str,
+    )
    if contam.get("block"):
        if playbook_id != PLAYBOOK_RECONCILE_CLEANUPS:
            detail = "Runtime is contaminated by a manual process kill (#630). Run reconciler cleanup playbook first."
@@ -482,37 +571,76 @@ def execute_recovery_playbook(
    # 4. Execute playbook action
    applied_result: dict[str, Any] = {"performed": False}
    if playbook_id == PLAYBOOK_CLEAR_STALE_BINDING:
-        diagnosis = diagnose_recovery(env=source_env)
+        binding_before = _active_binding(mutation_env)
+        diagnosis = diagnose_recovery(env=env)
        plan = stale_binding_recovery.plan_recovery(diagnosis.stale_binding)
-        applied_result = stale_binding_recovery.apply_recovery(plan, env=source_env)
+        applied_result = stale_binding_recovery.apply_recovery(plan, env=mutation_env)
+        binding_after = _active_binding(mutation_env)
+        applied_result = {
+            **applied_result,
+            "binding_before": binding_before,
+            "binding_after": binding_after,
+            "binding_changed": binding_before != binding_after,
+        }
+        # A clear that did not clear is not a success, whatever the plan said.
+        if not applied_result["binding_changed"]:
+            applied_result["performed"] = False
+            applied_result.setdefault("reasons", []).append(
+                "clear_stale_binding did not change the live worktree binding"
+            )
    elif playbook_id == PLAYBOOK_REBIND_SESSION:
        target_wt = target or (params or {}).get("target_worktree")
        if target_wt:
-            source_env[stale_binding_recovery.ACTIVE_WORKTREE_ENV] = target_wt
+            binding_before = _active_binding(mutation_env)
+            mutation_env[stale_binding_recovery.ACTIVE_WORKTREE_ENV] = target_wt
+            binding_after = _active_binding(mutation_env)
            applied_result = {
-                "performed": True,
+                "performed": binding_after == target_wt,
                "rebound_worktree": target_wt,
-                "cleared_stale": True,
+                "binding_before": binding_before,
+                "binding_after": binding_after,
+                "binding_changed": binding_before != binding_after,
+                "cleared_stale": binding_before != binding_after,
            }
+            if binding_after != target_wt:
+                applied_result["reasons"] = [
+                    "rebind_session_worktree did not take effect on the live "
+                    "environment"
+                ]
        else:
            applied_result = {
                "performed": False,
                "reason": "No target_worktree specified for rebind.",
            }
    elif playbook_id == PLAYBOOK_RECONCILE_CLEANUPS:
+        # ``merged_cleanup_reconcile`` exposes the building blocks only; the
+        # orchestrator is the MCP tool. The previous call named a function that
+        # does not exist, and a bare ``except`` turned the AttributeError into a
+        # generic failure, so this playbook could never succeed. Imported lazily
+        # because the MCP server module is large and binds FastMCP at import.
        try:
-            snapshot = merged_cleanup_reconcile.reconcile_merged_cleanups(
-                apply=True, project_root=str(_repo_root())
+            import gitea_mcp_server
+
+            snapshot = gitea_mcp_server.gitea_reconcile_merged_cleanups(
+                dry_run=False,
+                execute_confirmed=True,
+                remote=(params or {}).get("remote") or _console_remote(env),
+                org=(params or {}).get("org"),
+                repo=(params or {}).get("repo"),
            )
+            performed_reconcile = bool(snapshot.get("success"))
            applied_result = {
-                "performed": True,
-                "reconciled_count": len(snapshot.get("reconciled") or []),
+                "performed": performed_reconcile,
+                "reconciled_count": len(snapshot.get("entries") or []),
                "snapshot": snapshot,
            }
-        except Exception as exc:
+            if not performed_reconcile:
+                applied_result["reasons"] = list(snapshot.get("reasons") or [])
+        except Exception as exc:  # noqa: BLE001 — surfaced with its type
            applied_result = {
                "performed": False,
                "error": str(exc),
+                "error_type": type(exc).__name__,
            }
    elif playbook_id == PLAYBOOK_SANCTIONED_RESTART:
        ns = target or (params or {}).get("namespace", "gitea-author")
@@ -522,13 +650,18 @@ def execute_recovery_playbook(
            mode=md,
            principal=principal,
            confirmation=f"{md} {ns}",
-            env=source_env,
+            # Without the marker the stricter guard at sanctioned_restart.py:375
+            # never fires and a restart can launder a contaminated runtime.
+            contamination_marker=contamination_marker,
+            env=mutation_env,
            request_id=request_id,
            session_id=session_id,
        )
        applied_result = restart_res

-    performed = bool(applied_result.get("performed") or applied_result.get("allowed"))
+    # ``allowed`` is not ``performed``: execute_restart documents that success is
+    # False in both directions because the host supervisor still has to act.
+    performed = bool(applied_result.get("performed"))

    # 5. Record Audit Log
    audit_record = console_audit.record_event(
@@ -543,8 +676,13 @@ def execute_recovery_playbook(
        metadata={"applied_result": applied_result},
    )

-    # 6. Post-recovery verification recheck
-    post_verification = verify_post_recovery(env=source_env)
+    # 6. Post-recovery verification recheck.
+    #
+    # Re-read state rather than re-reading the mapping the mutation just wrote:
+    # verifying the mutated copy confirmed changes that never reached the
+    # process. Passing ``env`` through means a caller-supplied mapping is the
+    # live one for that caller, and ``None`` re-reads ``os.environ`` fresh.
+    post_verification = verify_post_recovery(env=env)

    return {
        "success": performed,
@@ -562,12 +700,22 @@ def verify_post_recovery(
 ) -> dict[str, Any]:
    """Revalidate control-plane state post-recovery before clean status."""
    diag = diagnose_recovery(repo_path, env)
+    classification = diag.stale_binding.get("classification")
+    # ``not clear_eligible`` also reads clean for every binding recovery is not
+    # allowed to touch — an unverified inherited binding is unproven, not clean.
+    binding_clean = (
+        not diag.stale_binding.get("clear_eligible")
+        and classification != stale_binding_recovery.CLASSIFICATION_UNVERIFIED_INHERITED
+    )
    return {
        "clean": diag.clean,
        "status": diag.status,
        "stale_runtime_clean": not diag.stale_runtime.get("stale"),
-        "binding_clean": not diag.stale_binding.get("clear_eligible"),
-        "contamination_clean": not diag.contamination.get("contaminated"),
+        "binding_clean": binding_clean,
+        "binding_classification": classification,
+        # The gate returns ``block``; it has never returned ``contaminated``, so
+        # reading that key reported every runtime clean unconditionally.
+        "contamination_clean": not diag.contamination.get("block"),
        "anomalies_count": len(diag.worktree_anomalies),
        "reasons": list(diag.reasons),
    }
@@ -274,18 +274,24 @@ def _recovery_card() -> str:
    try:
        from webui import console_recovery
        diag = console_recovery.diagnose_recovery()
-        status_badge = f"<span class='status-pill {diag.status}'>{diag.status}</span>"
+        # Every other card in this file escapes at the interpolation boundary.
+        # This one did not, and it is where a #630 marker's operator-supplied
+        # command_summary lands once the contamination gate is wired.
+        status_badge = (
+            f"<span class='status-pill {_esc(diag.status)}'>{_esc(diag.status)}</span>"
+        )
        playbook_lis = ""
        for pb in diag.playbooks:
            elig = "eligible" if pb.eligible else "disabled"
            playbook_lis += (
-                f"<li><strong>{pb.label}</strong> (<code>{pb.playbook_id}</code>) — "
-                f"<span class='badge {elig}'>{elig}</span>: {pb.description} "
-                f"<em class='muted'>({pb.reason})</em></li>"
+                f"<li><strong>{_esc(pb.label)}</strong> "
+                f"(<code>{_esc(pb.playbook_id)}</code>) — "
+                f"<span class='badge {elig}'>{elig}</span>: {_esc(pb.description)} "
+                f"<em class='muted'>({_esc(pb.reason)})</em></li>"
            )
        reasons_html = ""
        if diag.reasons:
-            items = "".join(f"<li>{r}</li>" for r in diag.reasons)
+            items = "".join(f"<li>{_esc(r)}</li>" for r in diag.reasons)
            reasons_html = f"<ul class='reasons'>{items}</ul>"
        else:
            reasons_html = "<p class='clean-note'>No recovery actions currently required. Control plane is healthy.</p>"
@@ -308,7 +314,7 @@ def _recovery_card() -> str:
        return (
            "<section class='health-card'>"
            "<h3>Sanctioned Recovery Controls (Phase 2 #644)</h3>"
-            f"<p class='error'>Recovery diagnostics unavailable: {exc}</p>"
+            f"<p class='error'>Recovery diagnostics unavailable: {_esc(exc)}</p>"
            "</section>"
        )