Merge pull request 'feat: add root checkout guard for contaminated control checkout (Closes #475)' (#488) from feat/issue-475-root-checkout-guard into master

gitea_mcp_server.py

@@ -651,6 +651,7 @@ def verify_preflight_purity(
                     f"{_format_preflight_files(reviewer_delta)}"
                 )
 
+    _enforce_root_checkout_guard(worktree_path)
     _enforce_branches_only_author_mutation(worktree_path)
     _clear_preflight_capability_state()
 
@@ -693,6 +694,27 @@ def _verify_role_mutation_workspace(
     verify_preflight_purity(remote, worktree_path=resolved, task=task)
     return resolved
 
+
+def _enforce_root_checkout_guard(worktree_path: str | None = None) -> None:
+    """#475: fail closed when the stable control checkout is contaminated."""
+    ctx = _resolve_author_mutation_context(worktree_path)
+    canonical_root = ctx["canonical_repo_root"]
+    workspace = ctx["workspace_path"]
+    git_state = issue_lock_worktree.read_worktree_git_state(canonical_root)
+    remote_master_sha = root_checkout_guard.resolve_remote_master_sha(canonical_root)
+    assessment = root_checkout_guard.assess_root_checkout_guard(
+        workspace_path=workspace,
+        canonical_repo_root=canonical_root,
+        current_branch=git_state.get("current_branch"),
+        head_sha=git_state.get("head_sha"),
+        porcelain_status=git_state.get("porcelain_status") or "",
+        remote_master_sha=remote_master_sha,
+        resolved_role=_preflight_resolved_role,
+    )
+    if assessment["block"]:
+        raise RuntimeError(root_checkout_guard.format_root_checkout_guard_error(assessment))
+
+
 from mcp.server.fastmcp import FastMCP  # noqa: E402
 
 from gitea_auth import (  # noqa: E402
@@ -724,6 +746,7 @@ import stacked_pr_support  # noqa: E402
 import merge_approval_gate  # noqa: E402
 import already_landed_reconcile  # noqa: E402
 import author_mutation_worktree  # noqa: E402
+import root_checkout_guard  # noqa: E402
 import issue_claim_heartbeat  # noqa: E402
 import issue_work_duplicate_gate  # noqa: E402
 import reviewer_pr_lease  # noqa: E402