fix(mcp-health): deterministic MCP namespace attachment (Closes #689)

master_parity_gate.py

@@ -183,6 +183,7 @@ def assess_master_parity(
     startup: dict | None,
     current_head: str | None,
     live_remote_head: str | None = None,
+    bound_cohort: dict | None = None,
 ) -> dict:
     """Compare the startup baseline against the current on-disk ``HEAD``.
 
@@ -192,7 +193,8 @@ def assess_master_parity(
       could not be determined, which is not treated as stale).
     - ``stale``        -- the on-disk master has definitively advanced past the
       running process.
-    - ``restart_required`` -- ``stale`` or ``live_stale``; the recovery action.
+    - ``restart_required`` -- ``stale``, ``live_stale``, or ``cohort_stale``; the
+      recovery action.
     - ``determinable`` -- whether both local HEADs were known well enough to
       compare.
     - ``startup_head`` / ``current_head`` / ``reasons``.
@@ -209,24 +211,69 @@ def assess_master_parity(
     - ``live_known`` -- whether the live remote target was resolved.
     - ``live_stale`` -- the live remote master has advanced past the running
       process (daemon is behind live master) even if local parity is green.
-    - ``mutation_safe`` -- the daemon code, local checkout, and live remote
-      target all agree; the only state in which a mutation may rely on parity.
+    - ``bound_cohort`` -- metadata describing the bound MCP cohort.
+    - ``cohort_parity_match`` -- whether bound cohort startup SHA matches parity.
+    - ``cohort_stale`` -- bound cohort startup SHA is stale relative to parity.
+    - ``mutation_safe`` -- the daemon code, local checkout, live remote target,
+      and bound cohort all agree; the only state in which a mutation may rely
+      on parity.
     """
     startup_head = (startup or {}).get("startup_head")
     reasons: list[str] = []
 
+    cohort_info: dict | None = None
+    cohort_parity_match = True
+    cohort_stale = False
+    if bound_cohort:
+        c_id = str(bound_cohort.get("cohort_id") or "").strip() or None
+        c_pid = bound_cohort.get("pid")
+        c_sha = str(
+            bound_cohort.get("startup_sha")
+            or bound_cohort.get("git_head")
+            or ""
+        ).strip() or None
+        c_endpoint = str(bound_cohort.get("endpoint") or "").strip() or None
+        c_fingerprint = str(
+            bound_cohort.get("config_fingerprint") or ""
+        ).strip() or None
+
+        cohort_info = {
+            "cohort_id": c_id,
+            "pid": c_pid,
+            "startup_sha": c_sha,
+            "endpoint": c_endpoint,
+            "config_fingerprint": c_fingerprint,
+        }
+
+        parity_ref = live_remote_head or current_head or startup_head
+        if c_sha and parity_ref:
+            if c_sha.lower() != parity_ref.lower():
+                cohort_parity_match = False
+                cohort_stale = True
+                reasons.append(
+                    f"bound cohort startup SHA '{_short(c_sha)}' does not "
+                    f"match authoritative parity SHA '{_short(parity_ref)}' "
+                    "(stale cohort refused)"
+                )
+
     if startup_head is None:
         reasons.append(
             "startup commit was not captured; code parity cannot be enforced")
         return _result(True, False, False, startup_head, current_head,
-                       live_remote_head, False, reasons)
+                       live_remote_head, False, reasons,
+                       bound_cohort=cohort_info,
+                       cohort_parity_match=cohort_parity_match,
+                       cohort_stale=cohort_stale)
 
     if current_head is None:
         reasons.append(
             "current workspace HEAD could not be read; code parity cannot be "
             "enforced")
         return _result(True, False, False, startup_head, current_head,
-                       live_remote_head, False, reasons)
+                       live_remote_head, False, reasons,
+                       bound_cohort=cohort_info,
+                       cohort_parity_match=cohort_parity_match,
+                       cohort_stale=cohort_stale)
 
     local_in_parity = startup_head == current_head
     local_stale = not local_in_parity
@@ -246,18 +293,28 @@ def assess_master_parity(
 
     return _result(
         local_in_parity, local_stale, True, startup_head, current_head,
-        live_remote_head, live_stale, reasons)
+        live_remote_head, live_stale, reasons,
+        bound_cohort=cohort_info,
+        cohort_parity_match=cohort_parity_match,
+        cohort_stale=cohort_stale)
 
 
 def _result(in_parity, stale, determinable, startup_head, current_head,
-            live_remote_head, live_stale, reasons):
+            live_remote_head, live_stale, reasons, bound_cohort=None,
+            cohort_parity_match=True, cohort_stale=False):
     live_known = live_remote_head is not None
     mutation_safe = (
-        determinable and in_parity and live_known and not live_stale)
+        determinable
+        and in_parity
+        and live_known
+        and not live_stale
+        and cohort_parity_match
+        and not cohort_stale
+    )
     return {
         "in_parity": in_parity,
         "stale": stale,
-        "restart_required": stale or live_stale,
+        "restart_required": stale or live_stale or cohort_stale,
         "determinable": determinable,
         "startup_head": startup_head,
         "current_head": current_head,
@@ -267,11 +324,15 @@ def _result(in_parity, stale, determinable, startup_head, current_head,
         "live_remote_head": live_remote_head,
         "live_known": live_known,
         "live_stale": live_stale,
+        "cohort_parity_match": cohort_parity_match,
+        "cohort_stale": cohort_stale,
+        "bound_cohort": bound_cohort,
         "mutation_safe": mutation_safe,
         "reasons": list(reasons),
     }
 
 
+
 def gate_disabled() -> bool:
     """Whether the parity gate is disabled by env escape hatch."""
     return bool((os.environ.get(ENV_DISABLE) or "").strip())