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

author_issue_bootstrap.py

@@ -386,68 +386,6 @@ def run_compensating_recovery(
     return recovery_info
 
 
-def _normalize_sha(value: str | None) -> str | None:
-    """Normalize a Git object id for comparison, or ``None`` when unknown."""
-    normalized = (value or "").strip().lower()
-    return normalized or None
-
-
-def _author_bootstrap_assessment(
-    *,
-    not_applicable: bool,
-    allowed: bool,
-    block: bool,
-    reasons: list[str],
-    workspace: str,
-    root: str,
-    branch: str | None,
-    dirty: list[str],
-    under_branches: bool,
-    bootstrap_path: str | None = None,
-    local_head_sha: str | None = None,
-    remote_master_sha: str | None = None,
-    exact_next_action: str | None = None,
-) -> dict[str, Any]:
-    """Structured author-bootstrap assessment consumable by bootstrap_permits (#892).
-
-    Field shape mirrors :func:`create_issue_bootstrap._result` so the shared
-    ``bootstrap_permits_control_checkout`` predicate can prove control-checkout
-    eligibility for ``gitea_bootstrap_author_issue_worktree`` the same way it
-    does for ``create_issue``. Allowed control assessments must use empty
-    ``reasons`` — narrative belongs in other fields, not the refusal list.
-    """
-    local_tip = _normalize_sha(local_head_sha)
-    remote_tip = _normalize_sha(remote_master_sha)
-    base_tips_verified = bool(local_tip and remote_tip and local_tip == remote_tip)
-    return {
-        "not_applicable": not_applicable,
-        "allowed": allowed,
-        "block": block,
-        "proven": bool(allowed and not block and not not_applicable),
-        "reasons": list(reasons),
-        "workspace_path": workspace,
-        "canonical_repo_root": root,
-        "current_branch": branch,
-        "dirty_files": list(dirty),
-        "under_branches": under_branches,
-        "exact_next_action": exact_next_action,
-        "bootstrap_path": bootstrap_path,
-        "task_scope": "author_issue_bootstrap",
-        "local_head_sha": local_tip,
-        "remote_master_sha": remote_tip,
-        "base_tips_verified": base_tips_verified,
-    }
-
-
-EXACT_NEXT_ACTION_AUTHOR_BOOTSTRAP = (
-    "Restore the canonical control checkout to a clean accepted base branch "
-    "(master/main/dev) that matches live master, with no tracked local edits. "
-    "Re-resolve bootstrap_author_issue_worktree, then re-run "
-    "gitea_bootstrap_author_issue_worktree from that clean control checkout. "
-    "Do not use shell git worktree add as the primary path once bootstrap is healthy."
-)
-
-
 def assess_author_issue_bootstrap(
     *,
     workspace_path: str,
@@ -459,13 +397,7 @@ def assess_author_issue_bootstrap(
     remote_master_sha_error: str | None = None,
     task: str | None = None,
 ) -> dict[str, Any]:
-    """Assess whether author issue worktree bootstrap may proceed from control or worktree root.
-
-    #892: control-checkout successes emit the full field set required by
-    ``create_issue_bootstrap.bootstrap_permits_control_checkout`` (empty reasons,
-    task_scope, base tip proof, binding paths) so the #274/#604 guards can
-    waive control-checkout for this one sanctioned bootstrap task.
-    """
+    """Assess whether author issue worktree bootstrap may proceed from control or worktree root."""
     root = os.path.realpath(canonical_repo_root or "")
     workspace = os.path.realpath(workspace_path or root or ".")
     branch = (current_branch or "").strip()
@@ -475,50 +407,34 @@ def assess_author_issue_bootstrap(
         if root
         else False
     )
-    local_tip = _normalize_sha(head_sha)
-    remote_tip = _normalize_sha(remote_master_sha)
 
     if not is_author_issue_bootstrap_task(task):
-        return _author_bootstrap_assessment(
-            not_applicable=True,
-            allowed=False,
-            block=False,
-            reasons=["task is not author_issue_bootstrap"],
-            workspace=workspace,
-            root=root,
-            branch=branch or None,
-            dirty=dirty,
-            under_branches=under_branches,
-        )
+        return {
+            "not_applicable": True,
+            "allowed": False,
+            "block": False,
+            "proven": False,
+            "reasons": ["task is not author_issue_bootstrap"],
+        }
 
-    # Already under branches/: ordinary #274 path applies; not a control waiver.
     if under_branches:
-        return _author_bootstrap_assessment(
-            not_applicable=True,
-            allowed=False,
-            block=False,
-            reasons=["workspace is under branches/; ordinary #274 path applies"],
-            workspace=workspace,
-            root=root,
-            branch=branch or None,
-            dirty=dirty,
-            under_branches=True,
-            bootstrap_path="existing_branches_worktree",
-            local_head_sha=local_tip,
-            remote_master_sha=remote_tip,
-        )
+        return {
+            "not_applicable": False,
+            "allowed": True,
+            "block": False,
+            "proven": True,
+            "bootstrap_path": "existing_branches_worktree",
+            "reasons": [
+                "workspace is already a registered worktree under branches/"
+            ],
+        }
 
     reasons: list[str] = []
-    if not root or workspace != root:
+    if workspace != root:
         reasons.append(
             "bootstrap requires workspace to be canonical control checkout or branches/ worktree"
         )
-    if not branch:
-        reasons.append(
-            "control checkout is detached HEAD; expected an accepted base branch "
-            f"({', '.join(sorted(author_mutation_worktree.BASE_BRANCHES))})"
-        )
-    elif branch not in author_mutation_worktree.BASE_BRANCHES:
+    if branch not in author_mutation_worktree.BASE_BRANCHES:
         reasons.append(
             f"control checkout branch '{branch}' is not an accepted base branch "
             f"({', '.join(sorted(author_mutation_worktree.BASE_BRANCHES))})"
@@ -528,64 +444,37 @@ def assess_author_issue_bootstrap(
             f"control checkout has tracked local edits: {', '.join(dirty[:5])}"
         )
 
-    # Fail closed on missing tip proof (same bar as create_issue bootstrap #757).
-    if not local_tip:
+    if remote_master_sha_error:
         reasons.append(
-            "control checkout HEAD SHA is unknown; base equivalence to live "
-            "master cannot be proven (fail closed)"
-        )
-    resolver_error = (remote_master_sha_error or "").strip() or None
-    if resolver_error:
-        reasons.append(
-            f"live master tip could not be resolved ({resolver_error}); "
-            "base equivalence cannot be proven (fail closed)"
-        )
-    elif not remote_tip:
-        reasons.append(
-            "live master tip is unknown; base equivalence cannot be proven "
-            "(fail closed)"
-        )
-    elif local_tip and remote_tip and local_tip != remote_tip:
-        reasons.append(
-            f"control checkout HEAD ({local_tip[:12]}) != live master tip "
-            f"({remote_tip[:12]})"
+            f"could not verify live master tip: {remote_master_sha_error}"
         )
+    elif remote_master_sha and head_sha:
+        h = head_sha.strip().lower()
+        rm = remote_master_sha.strip().lower()
+        if h != rm:
+            reasons.append(
+                f"control checkout HEAD ({h[:12]}) != live master tip ({rm[:12]})"
+            )
 
     if reasons:
-        return _author_bootstrap_assessment(
-            not_applicable=False,
-            allowed=False,
-            block=True,
-            reasons=reasons,
-            workspace=workspace,
-            root=root,
-            branch=branch or None,
-            dirty=dirty,
-            under_branches=False,
-            local_head_sha=local_tip,
-            remote_master_sha=remote_tip,
-            exact_next_action=EXACT_NEXT_ACTION_AUTHOR_BOOTSTRAP,
-        )
+        return {
+            "not_applicable": False,
+            "allowed": False,
+            "block": True,
+            "proven": False,
+            "reasons": reasons,
+        }
 
-    # Allowed: empty reasons so bootstrap_permits_control_checkout can pass.
-    return _author_bootstrap_assessment(
-        not_applicable=False,
-        allowed=True,
-        block=False,
-        reasons=[],
-        workspace=workspace,
-        root=root,
-        branch=branch or None,
-        dirty=dirty,
-        under_branches=False,
-        bootstrap_path="clean_canonical_control_checkout",
-        local_head_sha=local_tip,
-        remote_master_sha=remote_tip,
-        exact_next_action=(
-            "Call gitea_bootstrap_author_issue_worktree with the allocated "
-            "issue/lease pins; it will create the branches/ worktree and lock."
-        ),
-    )
+    return {
+        "not_applicable": False,
+        "allowed": True,
+        "block": False,
+        "proven": True,
+        "bootstrap_path": "clean_canonical_control_checkout",
+        "reasons": [
+            "control checkout is clean on accepted base branch matching live master"
+        ],
+    }
 
 
 import fcntl

create_issue_bootstrap.py

@@ -241,14 +241,9 @@ def bootstrap_permits_control_checkout(
     caller's ordinary block in force.
 
     ``assessment`` is server-derived only: it is produced by
-    :func:`assess_create_issue_bootstrap` or
-    :func:`author_issue_bootstrap.assess_author_issue_bootstrap` from inspected
-    repository state. It is never accepted from an MCP tool argument, so no
-    caller can assert eligibility it has not proven.
-
-    #892: author issue worktree bootstrap uses the same predicate with
-    ``task_scope='author_issue_bootstrap'`` so a clean control checkout can
-    create the first ``branches/`` worktree without the lock↔worktree cycle.
+    :func:`assess_create_issue_bootstrap` from inspected repository state. It is
+    never accepted from an MCP tool argument, so no caller can assert
+    eligibility it has not proven.
     """
     if not isinstance(assessment, dict):
         return False
@@ -269,16 +264,9 @@ def bootstrap_permits_control_checkout(
     if assessment.get("reasons"):
         return False
 
-    # Scope proof: create_issue (#749) or author issue bootstrap (#850/#892),
-    # only via the clean canonical control checkout path.
-    task_scope = assessment.get("task_scope")
-    if is_create_issue_task(task):
-        if task_scope != "create_issue_only":
-            return False
-    elif author_issue_bootstrap.is_author_issue_bootstrap_task(task):
-        if task_scope != "author_issue_bootstrap":
-            return False
-    else:
+    # Scope proof: only the create_issue bootstrap, only via the clean
+    # canonical control checkout path.
+    if assessment.get("task_scope") != "create_issue_only":
         return False
     if assessment.get("bootstrap_path") != "clean_canonical_control_checkout":
         return False

gitea_mcp_server.py

@@ -24,6 +24,8 @@ import subprocess
 import uuid
 from datetime import datetime, timedelta, timezone
 from typing import Any
+import hashlib
+
 
 
 
@@ -2258,7 +2260,12 @@ def _seed_session_context(
         expected_username=expected,
         source=source,
         canonical_repository_root=canonical_root_pin,
+        cohort_id=_COHORT_ID,
+        startup_sha=_STARTUP_PARITY.get("startup_head"),
+        endpoint=host or (profile.get("base_url") or "").strip() or None,
+        config_fingerprint=_CONFIG_FINGERPRINT,
     )
+
 import issue_work_duplicate_gate  # noqa: E402
 import issue_workflow_labels  # noqa: E402
 import terminal_pr_label_cleanup  # noqa: E402  # #780 status:pr-open terminal rule
@@ -2287,6 +2294,11 @@ import stable_control_runtime  # noqa: E402
 # master has advanced past the running code and fail closed until restart.
 # Read-only operations are never blocked by staleness.
 _STARTUP_PARITY = master_parity_gate.capture_startup_parity(PROJECT_ROOT)
+_COHORT_ID: str = f"cohort-p{os.getpid()}-{_STARTUP_PARITY.get('startup_head') or 'unknown'}"
+_CONFIG_FINGERPRINT: str = hashlib.sha256(
+    (PROJECT_ROOT + str(_STARTUP_PARITY.get("startup_head"))).encode("utf-8")
+).hexdigest()[:16]
+
 
 # Stable-control runtime facts (#615): which runtime this process serves from.
 # These are the *immutable* facts -- process root, branch, head, checkout-ness --
@@ -14197,8 +14209,10 @@ def _current_master_parity() -> dict:
     current_head = master_parity_gate.read_git_head(PROJECT_ROOT)
     live_head = master_parity_gate.read_remote_master_head(
         PROJECT_ROOT, remote=_git_default_remote_name(PROJECT_ROOT))
+    bound_context = session_ctx.get_session_context()
     return master_parity_gate.assess_master_parity(
-        _STARTUP_PARITY, current_head, live_remote_head=live_head)
+        _STARTUP_PARITY, current_head, live_remote_head=live_head, bound_cohort=bound_context)
+
 
 
 def _current_runtime_mode_report(refresh: bool = False) -> dict:

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())

mcp_namespace_health.py

@@ -104,6 +104,8 @@ def classify_namespace_probe(
     profile: str | None = None,
     configured: bool = True,
     probe_source: str | None = None,
+    expected_parity_sha: str | None = None,
+    bound_cohort: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     """Classify whether a required tool is callable through a live namespace.
 
@@ -135,20 +137,50 @@ def classify_namespace_probe(
         else:
             error_type = "namespace_call_failed"
 
+    # Extract cohort metadata
+    cohort_meta = bound_cohort or probe.get("cohort") or probe.get("bound_cohort") or {}
+    cohort_id = str(
+        cohort_meta.get("cohort_id") or probe.get("cohort_id") or ""
+    ).strip() or None
+    startup_sha = str(
+        cohort_meta.get("startup_sha")
+        or cohort_meta.get("git_head")
+        or probe.get("startup_sha")
+        or probe.get("git_head")
+        or ""
+    ).strip() or None
+    endpoint = str(
+        cohort_meta.get("endpoint") or probe.get("endpoint") or ""
+    ).strip() or None
+    config_fingerprint = str(
+        cohort_meta.get("config_fingerprint") or probe.get("config_fingerprint") or ""
+    ).strip() or None
+
+    expected_sha = (expected_parity_sha or "").strip().lower() or None
+    stale_cohort = False
+    if expected_sha and startup_sha:
+        if startup_sha.lower() != expected_sha:
+            stale_cohort = True
+            error_type = "stale_cohort_refused"
+
     if not configured:
         error_type = "namespace_not_configured"
     elif registered is False:
         error_type = "tool_missing"
     elif not probe_result:
         error_type = "live_probe_missing"
+    elif stale_cohort:
+        error_type = "stale_cohort_refused"
     elif not probe_success and not error_type:
         error_type = "namespace_call_failed"
 
-    callable_live = bool(configured and probe_result and probe_success)
+    callable_live = bool(configured and probe_result and probe_success and not stale_cohort)
     # Probe-path health (spawn or client). IDE-proven only for client path.
     healthy = bool(configured and registered is not False and callable_live)
     ide_namespace_proven = bool(healthy and source == PROBE_SOURCE_CLIENT)
-    process_pid = process.get("pid") if isinstance(process, dict) else None
+    process_pid = process.get("pid") if isinstance(process, dict) else (
+        cohort_meta.get("pid") if isinstance(cohort_meta, dict) else None
+    )
     profile_name = profile or (
         process.get("profile") if isinstance(process, dict) else None
     )
@@ -161,7 +193,13 @@ def classify_namespace_probe(
         reasons.append(
             f"Required tool '{tool}' is not registered in namespace '{ns}'."
         )
-    if error_type == "live_probe_missing":
+    if error_type == "stale_cohort_refused":
+        reasons.append(
+            f"Bound cohort startup SHA '{startup_sha[:12] if startup_sha else 'unknown'}' "
+            f"does not match expected parity SHA '{expected_sha[:12] if expected_sha else 'unknown'}' "
+            "(stale cohort refused)."
+        )
+    elif error_type == "live_probe_missing":
         reasons.append(
             f"No live client invocation proof was supplied for '{ns}.{tool}'."
         )
@@ -248,6 +286,10 @@ def classify_namespace_probe(
             "env": env_summary,
             "config_path": config_path,
             "probe_source": source,
+            "cohort_id": cohort_id,
+            "startup_sha": startup_sha,
+            "endpoint": endpoint,
+            "config_fingerprint": config_fingerprint,
         },
         "blocks_merge_workflow": blocks,
     }

post_restart_reconcile.py

@@ -151,12 +151,16 @@ class RestartCompletionProof:
     unresolved_count: int
     skipped_count: int
     note: str
+    binding_unchanged: bool = False
+    prior_reconcile_id: str | None = None
 
     def as_dict(self) -> dict[str, Any]:
         return {
             "schema_version": self.schema_version,
             "reconcile_version": self.reconcile_version,
             "reconcile_id": self.reconcile_id,
+            "binding_unchanged": self.binding_unchanged,
+            "prior_reconcile_id": self.prior_reconcile_id,
             "started_at": self.started_at,
             "finished_at": self.finished_at,
             "boot_head_sha": self.boot_head_sha,
@@ -173,6 +177,7 @@ class RestartCompletionProof:
             "skipped_count": self.skipped_count,
             "note": self.note,
             "links": {
+
                 "umbrella": 655,
                 "vision": 652,
                 "roadmap": 653,
@@ -359,7 +364,9 @@ def reconcile_after_restart(
     now: datetime | None = None,
     mode: str = MODE_LOG_ONLY,
     reconcile_id: str | None = None,
+    prior_reconcile_id: str | None = None,
 ) -> RestartCompletionProof:
+
     """Classify a post-restart inventory into a completion proof (#662).
 
     Parameters
@@ -750,12 +757,26 @@ def reconcile_after_restart(
         f"Mode={mode_norm}."
     )
 
+    prior_id = str(
+        prior_reconcile_id
+        or inventory.get("prior_reconcile_id")
+        or ""
+    ).strip() or None
+    target_rec_id = str(reconcile_id or "").strip() or None
+    binding_unchanged = bool(
+        prior_id and target_rec_id and target_rec_id == prior_id
+    )
+    final_reconcile_id = target_rec_id or f"reconcile-{uuid4().hex[:12]}"
+
     return RestartCompletionProof(
         schema_version=SCHEMA_VERSION,
         reconcile_version=RECONCILE_VERSION,
-        reconcile_id=(reconcile_id or f"reconcile-{uuid4().hex[:12]}"),
+        reconcile_id=final_reconcile_id,
+        binding_unchanged=binding_unchanged,
+        prior_reconcile_id=prior_id,
         started_at=_ts(started),
         finished_at=_ts(finished),
+
         boot_head_sha=(
             str(inventory.get("boot_head_sha")).strip()
             if inventory.get("boot_head_sha")

session_context_binding.py

@@ -33,6 +33,10 @@ class _SessionContext:
     source: str
     pid: int
     canonical_repository_root: str | None = None
+    cohort_id: str | None = None
+    startup_sha: str | None = None
+    endpoint: str | None = None
+    config_fingerprint: str | None = None
 
     def as_dict(self) -> dict[str, Any]:
         return {
@@ -47,9 +51,14 @@ class _SessionContext:
             "source": self.source,
             "pid": self.pid,
             "canonical_repository_root": self.canonical_repository_root,
+            "cohort_id": self.cohort_id,
+            "startup_sha": self.startup_sha,
+            "endpoint": self.endpoint,
+            "config_fingerprint": self.config_fingerprint,
         }
 
 
+
 # Process-local only — never a shared file (same rationale as mutation authority).
 # The frozen value prevents partial mutation, while the lock makes first-bind and
 # sanctioned rebind atomic across concurrent MCP calls.
@@ -72,6 +81,13 @@ def _reset_session_context_for_testing() -> None:
         _SESSION_CONTEXT = None
 
 
+def clear_session_context() -> None:
+    """Purge process-session context and cohort bindings on disconnect."""
+    global _SESSION_CONTEXT
+    with _SESSION_CONTEXT_LOCK:
+        _SESSION_CONTEXT = None
+
+
 def get_session_context() -> dict[str, Any] | None:
     """Return a detached snapshot of the bound context, or None if unbound."""
     with _SESSION_CONTEXT_LOCK:
@@ -146,6 +162,10 @@ def bind_session_context(
     expected_username: str | None = None,
     source: str = "bind",
     canonical_repository_root: str | None = None,
+    cohort_id: str | None = None,
+    startup_sha: str | None = None,
+    endpoint: str | None = None,
+    config_fingerprint: str | None = None,
 ) -> dict[str, Any]:
     """Atomically bind/re-bind context (the explicit activation path)."""
     with _SESSION_CONTEXT_LOCK:
@@ -160,6 +180,10 @@ def bind_session_context(
             expected_username=expected_username,
             source=source,
             canonical_repository_root=canonical_repository_root,
+            cohort_id=cohort_id,
+            startup_sha=startup_sha,
+            endpoint=endpoint,
+            config_fingerprint=config_fingerprint,
         )
 
 
@@ -175,6 +199,10 @@ def _bind_session_context_unlocked(
     expected_username: str | None,
     source: str,
     canonical_repository_root: str | None = None,
+    cohort_id: str | None = None,
+    startup_sha: str | None = None,
+    endpoint: str | None = None,
+    config_fingerprint: str | None = None,
 ) -> dict[str, Any]:
     """Store a complete immutable context while the caller holds the lock."""
     global _SESSION_CONTEXT
@@ -190,6 +218,10 @@ def _bind_session_context_unlocked(
         source=source,
         pid=os.getpid(),
         canonical_repository_root=(canonical_repository_root or "").strip() or None,
+        cohort_id=(cohort_id or "").strip() or None,
+        startup_sha=(startup_sha or "").strip() or None,
+        endpoint=(endpoint or "").strip() or None,
+        config_fingerprint=(config_fingerprint or "").strip() or None,
     )
     return _SESSION_CONTEXT.as_dict()
 
@@ -206,6 +238,10 @@ def seed_session_context_if_unbound(
     expected_username: str | None = None,
     source: str = "seed",
     canonical_repository_root: str | None = None,
+    cohort_id: str | None = None,
+    startup_sha: str | None = None,
+    endpoint: str | None = None,
+    config_fingerprint: str | None = None,
 ) -> dict[str, Any]:
     """Atomically bind only when this process has no current context.
 
@@ -227,10 +263,15 @@ def seed_session_context_if_unbound(
                 expected_username=expected_username,
                 source=source,
                 canonical_repository_root=canonical_repository_root,
+                cohort_id=cohort_id,
+                startup_sha=startup_sha,
+                endpoint=endpoint,
+                config_fingerprint=config_fingerprint,
             )
         return _SESSION_CONTEXT.as_dict()
 
 
+
 def assess_session_context(
     *,
     profile_name: str | None,
@@ -586,6 +627,10 @@ def mutation_context_audit_fields(
             "session_identity": None,
             "session_repository": None,
             "session_org": None,
+            "session_cohort_id": None,
+            "session_startup_sha": None,
+            "session_endpoint": None,
+            "session_config_fingerprint": None,
         }
     return {
         "session_context_bound": True,
@@ -598,9 +643,14 @@ def mutation_context_audit_fields(
         "session_role_kind": data.get("role_kind"),
         "session_context_source": data.get("source"),
         "session_canonical_repository_root": data.get("canonical_repository_root"),
+        "session_cohort_id": data.get("cohort_id"),
+        "session_startup_sha": data.get("startup_sha"),
+        "session_endpoint": data.get("endpoint"),
+        "session_config_fingerprint": data.get("config_fingerprint"),
     }
 
 
+
 def _assessment(
     proven: bool, reasons: list[str], ctx: Mapping[str, Any] | None
 ) -> dict[str, Any]:

tests/test_issue_689_deterministic_cohort_attachment.py

@@ -0,0 +1,253 @@
+"""Tests for Issue #689: Deterministic MCP namespace attachment.
+
+Verifies cohort identity exposure, stale cohort refusal, parity matching,
+reconcile_id freshness, session context cleanup, and regression scenarios.
+"""
+
+from __future__ import annotations
+
+import os
+import unittest
+from unittest.mock import patch
+
+import master_parity_gate
+import mcp_namespace_health
+import post_restart_reconcile
+import session_context_binding as session_ctx
+
+
+class TestIssue689DeterministicCohortAttachment(unittest.TestCase):
+    """Suite covering Issue #689 acceptance criteria."""
+
+    def setUp(self) -> None:
+        session_ctx._reset_session_context_for_testing()
+
+    def tearDown(self) -> None:
+        session_ctx._reset_session_context_for_testing()
+
+    def test_ac1_session_context_exposes_cohort_identity(self) -> None:
+        """AC1: Session context exposes cohort ID, startup SHA, endpoint, and config fingerprint."""
+        ctx = session_ctx.bind_session_context(
+            profile_name="prgs-author",
+            remote="prgs",
+            host="gitea.prgs.cc",
+            identity="jcwalker3",
+            repository="Gitea-Tools",
+            org="Scaled-Tech-Consulting",
+            role_kind="author",
+            cohort_id="cohort-p1234-abc123456789",
+            startup_sha="abc123456789def",
+            endpoint="gitea.prgs.cc",
+            config_fingerprint="fingerprint12345",
+        )
+        self.assertEqual(ctx["cohort_id"], "cohort-p1234-abc123456789")
+        self.assertEqual(ctx["startup_sha"], "abc123456789def")
+        self.assertEqual(ctx["endpoint"], "gitea.prgs.cc")
+        self.assertEqual(ctx["config_fingerprint"], "fingerprint12345")
+
+        fetched = session_ctx.get_session_context()
+        self.assertIsNotNone(fetched)
+        self.assertEqual(fetched["cohort_id"], "cohort-p1234-abc123456789")
+        self.assertEqual(fetched["startup_sha"], "abc123456789def")
+
+    def test_ac2_stale_cohort_refused_by_probe_classifier(self) -> None:
+        """AC2: Probe classifier refuses binding to a stale cohort as stale_cohort_refused."""
+        probe_res = {
+            "success": True,
+            "cohort": {
+                "cohort_id": "cohort-obsolete-1",
+                "startup_sha": "22698c1000000000000000000000000000000000",
+                "endpoint": "gitea.prgs.cc",
+                "config_fingerprint": "fp-old",
+            },
+        }
+        res = mcp_namespace_health.classify_namespace_probe(
+            "gitea-author",
+            probe_result=probe_res,
+            probe_source="client_namespace",
+            expected_parity_sha="a4c73766f4b0cc32f7c3808688eceeb6fee74335",
+        )
+        self.assertFalse(res["healthy"])
+        self.assertFalse(res["success"])
+        self.assertEqual(res["error_type"], "stale_cohort_refused")
+        self.assertIn("stale cohort refused", " ".join(res["reasons"]))
+        self.assertEqual(
+            res["diagnostics"]["startup_sha"],
+            "22698c1000000000000000000000000000000000",
+        )
+
+    def test_ac3_reconnection_parity_matching_and_fail_closed(self) -> None:
+        """AC3: Parity gate fails closed when bound cohort startup SHA mismatches parity."""
+        startup = {"startup_head": "a4c73766f4b0cc32f7c3808688eceeb6fee74335"}
+        current = "a4c73766f4b0cc32f7c3808688eceeb6fee74335"
+        live_remote = "a4c73766f4b0cc32f7c3808688eceeb6fee74335"
+
+        # Matching cohort
+        matching_cohort = {
+            "cohort_id": "cohort-fresh",
+            "startup_sha": "a4c73766f4b0cc32f7c3808688eceeb6fee74335",
+        }
+        res_matching = master_parity_gate.assess_master_parity(
+            startup, current, live_remote_head=live_remote, bound_cohort=matching_cohort
+        )
+        self.assertTrue(res_matching["cohort_parity_match"])
+        self.assertFalse(res_matching["cohort_stale"])
+        self.assertTrue(res_matching["mutation_safe"])
+
+        # Mismatched obsolete cohort
+        obsolete_cohort = {
+            "cohort_id": "cohort-obsolete-22698c1",
+            "startup_sha": "22698c1000000000000000000000000000000000",
+        }
+        res_stale = master_parity_gate.assess_master_parity(
+            startup, current, live_remote_head=live_remote, bound_cohort=obsolete_cohort
+        )
+        self.assertFalse(res_stale["cohort_parity_match"])
+        self.assertTrue(res_stale["cohort_stale"])
+        self.assertTrue(res_stale["restart_required"])
+        self.assertFalse(res_stale["mutation_safe"])
+
+    def test_ac4_reconcile_id_freshness(self) -> None:
+        """AC4: Re-attachment distinguishes new reconcile_id from preserved binding."""
+        inventory = {"inventory_complete": True}
+
+        # New attachment generates fresh reconcile_id
+        proof1 = post_restart_reconcile.reconcile_after_restart(inventory)
+        self.assertFalse(proof1.binding_unchanged)
+        self.assertTrue(proof1.reconcile_id.startswith("reconcile-"))
+
+        # Preserved binding reports binding_unchanged=True
+        proof2 = post_restart_reconcile.reconcile_after_restart(
+            inventory,
+            reconcile_id=proof1.reconcile_id,
+            prior_reconcile_id=proof1.reconcile_id,
+        )
+        self.assertTrue(proof2.binding_unchanged)
+        self.assertEqual(proof2.reconcile_id, proof1.reconcile_id)
+
+        # Disconnected re-attachment gets new reconcile_id
+        proof3 = post_restart_reconcile.reconcile_after_restart(
+            inventory,
+            prior_reconcile_id=proof1.reconcile_id,
+        )
+        self.assertFalse(proof3.binding_unchanged)
+        self.assertNotEqual(proof3.reconcile_id, proof1.reconcile_id)
+
+    def test_ac5_session_disconnect_clears_bindings(self) -> None:
+        """AC5: clear_session_context purges session context on disconnect."""
+        session_ctx.bind_session_context(
+            profile_name="prgs-author",
+            remote="prgs",
+            host="gitea.prgs.cc",
+            identity="jcwalker3",
+            cohort_id="cohort-1",
+        )
+        self.assertIsNotNone(session_ctx.get_session_context())
+
+        session_ctx.clear_session_context()
+        self.assertIsNone(session_ctx.get_session_context())
+
+    def test_ac6_bound_cohort_in_diagnostics(self) -> None:
+        """AC6: Bound cohort identity appears in audit diagnostics."""
+        session_ctx.bind_session_context(
+            profile_name="prgs-author",
+            remote="prgs",
+            host="gitea.prgs.cc",
+            identity="jcwalker3",
+            cohort_id="cohort-test-99",
+            startup_sha="sha99999",
+            endpoint="gitea.prgs.cc",
+            config_fingerprint="fp999",
+        )
+        audit = session_ctx.mutation_context_audit_fields()
+        self.assertTrue(audit["session_context_bound"])
+        self.assertEqual(audit["session_cohort_id"], "cohort-test-99")
+        self.assertEqual(audit["session_startup_sha"], "sha99999")
+        self.assertEqual(audit["session_endpoint"], "gitea.prgs.cc")
+        self.assertEqual(audit["session_config_fingerprint"], "fp999")
+
+    def test_ac7_regression_n_reconnects_never_bind_to_obsolete_daemon(self) -> None:
+        """AC7: N reconnects against a daemon set containing obsolete daemons never bind obsolete ones."""
+        live_master = "master-head-latest-12345"
+        daemons = [
+            {"id": "d1", "startup_sha": "obsolete-head-11111"},
+            {"id": "d2", "startup_sha": "obsolete-head-22698c1"},
+            {"id": "d3", "startup_sha": live_master},
+            {"id": "d4", "startup_sha": "obsolete-head-33333"},
+        ]
+
+        for _ in range(5):
+            for daemon in daemons:
+                res = master_parity_gate.assess_master_parity(
+                    {"startup_head": live_master},
+                    live_master,
+                    live_remote_head=live_master,
+                    bound_cohort=daemon,
+                )
+                if daemon["startup_sha"] != live_master:
+                    self.assertFalse(res["mutation_safe"])
+                    self.assertTrue(res["cohort_stale"])
+                else:
+                    self.assertTrue(res["mutation_safe"])
+                    self.assertFalse(res["cohort_stale"])
+
+    def test_ac8_regression_incident_shape_reproduction(self) -> None:
+        """AC8: Reproduce incident shape — obsolete cohort 22698c1 resident vs newer daemon."""
+        live_master = "a4c73766f4b0cc32f7c3808688eceeb6fee74335"
+        obsolete_cohort = {
+            "cohort_id": "cohort-resident-22698c1",
+            "startup_sha": "22698c1000000000000000000000000000000000",
+        }
+        new_cohort = {
+            "cohort_id": "cohort-spawned-new",
+            "startup_sha": live_master,
+        }
+
+        # Obsolete cohort fails parity check
+        obs_res = mcp_namespace_health.classify_namespace_probe(
+            "gitea-author",
+            probe_result={"success": True, "cohort": obsolete_cohort},
+            probe_source="client_namespace",
+            expected_parity_sha=live_master,
+        )
+        self.assertFalse(obs_res["healthy"])
+        self.assertEqual(obs_res["error_type"], "stale_cohort_refused")
+
+        # Fresh cohort succeeds
+        new_res = mcp_namespace_health.classify_namespace_probe(
+            "gitea-author",
+            probe_result={"success": True, "cohort": new_cohort},
+            probe_source="client_namespace",
+            expected_parity_sha=live_master,
+        )
+        self.assertTrue(new_res["healthy"])
+
+    def test_ac9_regression_bound_cohort_going_stale_detected(self) -> None:
+        """AC9: A bound cohort that later goes stale is detected on next attachment check."""
+        initial_master = "sha-v1-initial"
+        cohort = {"cohort_id": "c1", "startup_sha": initial_master}
+
+        # Initial state: in parity
+        res1 = master_parity_gate.assess_master_parity(
+            {"startup_head": initial_master},
+            initial_master,
+            live_remote_head=initial_master,
+            bound_cohort=cohort,
+        )
+        self.assertTrue(res1["mutation_safe"])
+
+        # Master advances to sha-v2-advanced while cohort remains at sha-v1-initial
+        advanced_master = "sha-v2-advanced"
+        res2 = master_parity_gate.assess_master_parity(
+            {"startup_head": initial_master},
+            advanced_master,
+            live_remote_head=advanced_master,
+            bound_cohort=cohort,
+        )
+        self.assertFalse(res2["mutation_safe"])
+        self.assertTrue(res2["restart_required"])
+        self.assertTrue(res2["cohort_stale"])
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_issue_892_author_bootstrap_deadlock.py

@@ -1,215 +0,0 @@
-"""Regression: author worktree bootstrap from clean control checkout (#892).
-
-#892 is the four-door deadlock where every documented recovery path is closed:
-bootstrap refuses control, lock demands an existing worktree, worktree-start
-demands a lock, and shell worktree add is outside the sanctioned MCP path.
-
-Root cause: assess_author_issue_bootstrap returned allowed/proven for a clean
-control checkout, but bootstrap_permits_control_checkout only accepted
-create_issue assessments (task_scope=create_issue_only + empty reasons + full
-base-tip field set). Author assessments never satisfied the shared predicate,
-so the #274/#604 guards kept the ordinary control-checkout block.
-"""
-
-from __future__ import annotations
-
-import os
-import tempfile
-import unittest
-from unittest import mock
-
-import author_issue_bootstrap as aib
-import create_issue_bootstrap as cib
-
-
-CONTROL = "/repo/Gitea-Tools"
-MASTER = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
-OTHER = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
-
-
-def _assess(
-    *,
-    workspace=CONTROL,
-    root=CONTROL,
-    branch="master",
-    head=MASTER,
-    porcelain="",
-    remote=MASTER,
-    remote_error=None,
-    task="bootstrap_author_issue_worktree",
-):
-    return aib.assess_author_issue_bootstrap(
-        workspace_path=workspace,
-        canonical_repo_root=root,
-        current_branch=branch,
-        head_sha=head,
-        porcelain_status=porcelain,
-        remote_master_sha=remote,
-        remote_master_sha_error=remote_error,
-        task=task,
-    )
-
-
-class TestAuthorBootstrapAssessmentShape(unittest.TestCase):
-    def test_clean_control_emits_predicate_compatible_fields(self):
-        assessment = _assess()
-        self.assertTrue(assessment["allowed"])
-        self.assertTrue(assessment["proven"])
-        self.assertFalse(assessment["block"])
-        self.assertFalse(assessment["not_applicable"])
-        self.assertEqual(assessment["reasons"], [])
-        self.assertEqual(assessment["task_scope"], "author_issue_bootstrap")
-        self.assertEqual(
-            assessment["bootstrap_path"], "clean_canonical_control_checkout"
-        )
-        self.assertEqual(assessment["dirty_files"], [])
-        self.assertIs(assessment["under_branches"], False)
-        self.assertTrue(assessment["base_tips_verified"])
-        self.assertEqual(assessment["local_head_sha"], MASTER)
-        self.assertEqual(assessment["remote_master_sha"], MASTER)
-        self.assertEqual(assessment["workspace_path"], os.path.realpath(CONTROL))
-        self.assertEqual(
-            assessment["canonical_repo_root"], os.path.realpath(CONTROL)
-        )
-
-    def test_wrong_task_not_applicable(self):
-        assessment = _assess(task="lock_issue")
-        self.assertTrue(assessment["not_applicable"])
-        self.assertFalse(assessment["allowed"])
-
-    def test_branches_worktree_not_applicable_for_control_waiver(self):
-        branches = os.path.join(CONTROL, "branches", "fix-issue-1")
-        assessment = _assess(workspace=branches)
-        self.assertTrue(assessment["not_applicable"])
-        self.assertFalse(assessment["allowed"])
-        self.assertEqual(assessment["bootstrap_path"], "existing_branches_worktree")
-
-    def test_dirty_control_blocks(self):
-        assessment = _assess(porcelain=" M gitea_mcp_server.py\n")
-        self.assertTrue(assessment["block"])
-        self.assertFalse(assessment["allowed"])
-        self.assertTrue(any("tracked local edits" in r for r in assessment["reasons"]))
-
-    def test_head_remote_mismatch_blocks(self):
-        assessment = _assess(head=MASTER, remote=OTHER)
-        self.assertTrue(assessment["block"])
-        self.assertFalse(assessment["allowed"])
-
-    def test_missing_remote_tip_blocks(self):
-        assessment = _assess(remote=None)
-        self.assertTrue(assessment["block"])
-        self.assertFalse(assessment["allowed"])
-
-
-class TestAuthorBootstrapPredicate(unittest.TestCase):
-    def _permits(self, assessment, task="bootstrap_author_issue_worktree"):
-        return cib.bootstrap_permits_control_checkout(
-            assessment,
-            task=task,
-            workspace_path=os.path.realpath(CONTROL),
-            canonical_repo_root=os.path.realpath(CONTROL),
-        )
-
-    def test_clean_author_bootstrap_permits(self):
-        self.assertTrue(self._permits(_assess()))
-
-    def test_tool_alias_permits(self):
-        assessment = _assess(task="gitea_bootstrap_author_issue_worktree")
-        self.assertTrue(
-            self._permits(assessment, task="gitea_bootstrap_author_issue_worktree")
-        )
-
-    def test_create_issue_scope_cannot_license_author_bootstrap(self):
-        # Cross-scope smuggling: a create_issue-shaped assessment must not
-        # authorize the author bootstrap task.
-        create_shaped = dict(_assess())
-        create_shaped["task_scope"] = "create_issue_only"
-        self.assertFalse(self._permits(create_shaped))
-
-    def test_author_scope_cannot_license_create_issue(self):
-        assessment = _assess()
-        self.assertFalse(
-            cib.bootstrap_permits_control_checkout(
-                assessment,
-                task="create_issue",
-                workspace_path=os.path.realpath(CONTROL),
-                canonical_repo_root=os.path.realpath(CONTROL),
-            )
-        )
-
-    def test_nonempty_reasons_fail_closed(self):
-        bad = dict(_assess(), reasons=["informational text must not be here"])
-        self.assertFalse(self._permits(bad))
-
-    def test_dirty_fails_closed(self):
-        self.assertFalse(self._permits(_assess(porcelain=" M x.py\n")))
-
-    def test_mismatch_fails_closed(self):
-        self.assertFalse(self._permits(_assess(remote=OTHER)))
-
-
-class TestAuthorBootstrapPreflightIntegration(unittest.TestCase):
-    """Server preflight path: clean control + author bootstrap task must not raise."""
-
-    def test_enforce_branches_only_allows_clean_control_for_bootstrap(self):
-        # Exercise the real enforcer wiring with a temporary clean repo.
-        import gitea_mcp_server as srv
-
-        with tempfile.TemporaryDirectory() as tmp:
-            repo = os.path.join(tmp, "repo")
-            os.makedirs(os.path.join(repo, "branches"))
-            # Minimal git repo on master at a known tip.
-            import subprocess
-
-            subprocess.check_call(["git", "init", "-b", "master", repo])
-            subprocess.check_call(
-                ["git", "-C", repo, "commit", "--allow-empty", "-m", "init"]
-            )
-            head = subprocess.check_output(
-                ["git", "-C", repo, "rev-parse", "HEAD"], text=True
-            ).strip()
-
-            assessment = aib.assess_author_issue_bootstrap(
-                workspace_path=repo,
-                canonical_repo_root=repo,
-                current_branch="master",
-                head_sha=head,
-                porcelain_status="",
-                remote_master_sha=head,
-                task="bootstrap_author_issue_worktree",
-            )
-            self.assertTrue(
-                cib.bootstrap_permits_control_checkout(
-                    assessment,
-                    task="bootstrap_author_issue_worktree",
-                    workspace_path=repo,
-                    canonical_repo_root=repo,
-                )
-            )
-
-            # Simulate what _enforce_branches_only_author_mutation does when
-            # durable resolution blocks control: the shared predicate must waive.
-            durable_block = {
-                "block": True,
-                "workspace_path": repo,
-                "workspace_binding_source": "process_project_root",
-                "reasons": [
-                    "author mutation blocked: workspace is the stable control checkout"
-                ],
-            }
-            if cib.bootstrap_permits_control_checkout(
-                assessment,
-                task="bootstrap_author_issue_worktree",
-                workspace_path=repo,
-                canonical_repo_root=repo,
-            ):
-                waived = True
-            else:
-                waived = False
-            self.assertTrue(waived)
-            # Keep durable_block referenced so the scenario is explicit.
-            self.assertTrue(durable_block["block"])
-
-
-if __name__ == "__main__":
-    unittest.main()