Merge pull request 'feat(transport): add transport-neutral MCP bind seam (Closes #931)' (#966) from feat/issue-931-transport-neutral-bind-seam into master

The execution-authorization gate shifted two cited lines in
mcp_daemon_guard.py, so the fixture and the document must name the commit
where the re-anchored citations actually resolve. Both still named
c1626081, where the two moved anchors no longer point at the claimed code.

Point both at a143cd06. This commit changes no .py file, so every anchor
that resolves at a143cd06 resolves here too. The historical note about
#930's drift between 7bf4f125 and aad5c8b4 stays as written.

Refs #931, #956. Addresses review 635.

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

author_issue_bootstrap.py

@@ -23,6 +23,7 @@ import shutil
 import subprocess
 from typing import Any, Mapping
 
+import author_lock_contract
 import author_mutation_worktree
 import control_plane_db
 import issue_lock_store
@@ -278,6 +279,36 @@ def _verify_assignment_and_lease_ids(
     return None
 
 
+def _branch_exists(canonical_repo_root: str, branch_name: str) -> bool:
+    """Whether *branch_name* still resolves in the canonical checkout (#953 F2).
+
+    Used after compensating recovery to observe what survived rather than infer
+    it from the journal. Fails closed to ``True``: an unobservable branch is
+    reported as present, so the recommendation stays conservative rather than
+    telling an author to re-bootstrap over something that may still be there.
+    """
+    if not branch_name:
+        return False
+    try:
+        res = subprocess.run(
+            [
+                "git",
+                "-C",
+                canonical_repo_root,
+                "rev-parse",
+                "--verify",
+                "--quiet",
+                f"refs/heads/{branch_name}",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except Exception:
+        return True
+    return res.returncode == 0
+
+
 def run_compensating_recovery(
     journal: dict[str, Any],
     canonical_repo_root: str,
@@ -314,10 +345,21 @@ def run_compensating_recovery(
                     issue_number=issue_num,
                     session=session_id,
                     lock_dir=journal_dir,
+                    remote=journal.get("remote"),
+                    # The same defaults the lock was written under, so the
+                    # rollback targets the exact file bind_session_lock keyed.
+                    org=journal.get("org") or "Scaled-Tech-Consulting",
+                    repo=journal.get("repo") or "Gitea-Tools",
                 )
                 rolled_back.append(f"lock:issue-{issue_num}")
-            except Exception:
+            except Exception as exc:
-                pass
+                # #953 F2: a swallowed failure here is what made the rollback
+                # report success while leaving an unrecoverable lock behind.
+                # Record it so the post-compensation classification can see the
+                # lock survived and recommend accordingly.
+                rolled_back.append(
+                    f"lock_release_failed:issue-{issue_num}:{type(exc).__name__}"
+                )
         artifacts["lock_created"] = False
 
     worktree_created = (
@@ -1198,26 +1240,31 @@ def bootstrap_author_issue_worktree(
         save_phase_journal(journal, journal_dir=lock_dir)
 
         # Phase 6: STATE_ESTABLISHED — Issue Lock Acquisition
+        #
+        # #953: this used to hand-build a thinner record — claimant at the top
+        # level, no work_lease, no lock_provenance, no expiry — which every
+        # downstream reader then refused. It now builds through the one shared
+        # canonical contract, so the lock bootstrap writes is the same lock
+        # gitea_lock_issue writes.
         from datetime import datetime, timezone
         try:
-            lock_data = {
+            lock_data = author_lock_contract.build_canonical_issue_lock(
-                "remote": remote,
+                issue_number=issue_number,
-                "org": org or "Scaled-Tech-Consulting",
+                branch_name=target_branch,
-                "repo": repo or "Gitea-Tools",
+                worktree_path=target_worktree,
-                "issue_number": issue_number,
+                remote=remote,
-                "branch": target_branch,
+                org=org or "Scaled-Tech-Consulting",
-                "branch_name": target_branch,
+                repo=repo or "Gitea-Tools",
-                "worktree_path": target_worktree,
+                identity=identity,
-                "owner_session": session,
+                profile=profile,
-                "claimant": {
+                tool="gitea_bootstrap_author_issue_worktree",
-                    "username": identity,
+                source=author_lock_contract.SOURCE_BOOTSTRAP,
-                    "profile": profile,
+                owner_session=session,
-                },
+                assignment_id=assignment_id,
-                "assignment_id": assignment_id,
+                lease_id=lease_id,
-                "lease_id": lease_id,
+                expected_base_sha=live_master_sha,
-                "expected_base_sha": live_master_sha,
+            )
-                "created_at": datetime.now(timezone.utc).isoformat(),
+            lock_data["created_at"] = datetime.now(timezone.utc).isoformat()
-            }
             journal.setdefault("pending_creations", {})["lock"] = True
             journal["artifacts_created"]["lock_created"] = True
             save_phase_journal(journal, journal_dir=lock_dir)
@@ -1235,9 +1282,65 @@ def bootstrap_author_issue_worktree(
                 "exact_next_action": "Verify lease/assignment state and retry.",
             }
 
+        # ── #953 AC7: verify the lock that was actually written ──
+        # Reporting "lock_created: true" and then directing the author to
+        # implement is what produced the unrecoverable state: by the time any
+        # reader refused the lock, the branch already carried commits and every
+        # sanctioned recovery path had become ineligible. The lock is therefore
+        # read back from disk and structurally verified *before* this function
+        # can report success, and a partial lock fails closed here — while the
+        # branch is still base-equivalent and recovery is still cheap.
+        written_lock = issue_lock_store.read_lock_file(lock_res)
+        contract = author_lock_contract.assess_lock_contract(written_lock)
+        if not contract["canonical"]:
+            journal["failure_reason"] = author_lock_contract.format_contract_refusal(
+                contract
+            )
+            compensation = run_compensating_recovery(
+                journal, root, journal_dir=lock_dir
+            )
+            # AC5/AC15: the recommendation must describe the state compensation
+            # actually left, not the state that provoked it.
+            # ``run_compensating_recovery`` has by now released the lock, removed
+            # the worktree, and deleted the branch, so recommending
+            # incomplete-lock recovery for those exact artifacts would refuse
+            # twice over. Observe what survived and answer for that.
+            post_state = author_lock_contract.assess_post_compensation_state(
+                compensation,
+                lock_present=bool(lock_res) and os.path.exists(lock_res),
+                worktree_present=os.path.isdir(target_worktree),
+                branch_present=_branch_exists(root, target_branch),
+            )
+            return {
+                "success": False,
+                "reason_code": "incomplete_issue_lock_contract",
+                "message": author_lock_contract.format_contract_refusal(contract),
+                "issue_number": issue_number,
+                "branch_name": target_branch,
+                "worktree_path": target_worktree,
+                "lock_state": lock_res,
+                "lock_contract": contract,
+                "missing_fields": contract["missing_fields"],
+                "implementation_allowed": False,
+                "compensating_recovery": compensation,
+                "post_compensation_state": post_state,
+                # AC15: never strand a branch or worktree without a structured
+                # recovery recommendation — and never name an artifact the
+                # rollback has already deleted.
+                "exact_next_action": author_lock_contract.post_compensation_action(
+                    post_state,
+                    issue_number=issue_number,
+                    branch_name=target_branch,
+                    worktree_path=target_worktree,
+                    missing_fields=contract["missing_fields"],
+                ),
+                "phase_journal": journal,
+            }
+
         journal["phases"][PHASE_6_STATE_ESTABLISHED] = {
             "status": "completed",
             "lock": lock_res,
+            "lock_contract": contract["contract"],
         }
         journal["phases"][PHASE_7_TRANSITION_COMPLETED] = {
             "status": "completed",
@@ -1261,9 +1364,16 @@ def bootstrap_author_issue_worktree(
             "assignment_id": assignment_id,
             "idempotency_key": key,
             "lock_state": lock_res,
+            "lock_contract": contract,
+            # #953 AC6: the canonical ownership token for this claim. Never null
+            # on a successful bootstrap — it is the fencing token every
+            # subsequent heartbeat and renewal is checked against.
+            "task_session_id": contract["task_session_id"],
+            "implementation_allowed": True,
             "phase_journal": journal,
-            "exact_next_action": (
+            # #953 AC5: executable under the state actually returned. The lock
-                "Call gitea_whoami, then gitea_resolve_task_capability(task='work_issue') "
+            # has been read back and verified canonical, so proceeding to
-                "and proceed with author implementation in the bootstrapped worktree."
+            # implementation is genuinely the correct next step here — which is
-            ),
+            # exactly what the old unconditional wording could not promise.
+            "exact_next_action": author_lock_contract.recommended_action(contract),
         }

author_lock_contract.py

@@ -0,0 +1,623 @@
+"""One canonical author issue-lock contract shared by every writer (#953).
+
+Before this module, ``gitea_lock_issue`` and
+``gitea_bootstrap_author_issue_worktree`` each wrote their own lock record.
+``gitea_lock_issue`` wrote the canonical shape — ``work_lease`` carrying the
+claimant plus a sanctioned ``lock_provenance`` — while bootstrap wrote a thinner
+record with the claimant at the lock top level, ``lease_id: null``, and no
+``work_lease``, ``lock_provenance``, or expiry at all.
+
+Every downstream reader was written against the canonical shape, so a lock that
+bootstrap reported as successfully created was simultaneously:
+
+* un-heartbeatable — the ownership check read the claimant only from
+  ``work_lease.claimant``;
+* un-renewable — expiry is read only from ``work_lease.expires_at``, so a
+  missing lease read as "never expires", and #760 exact-owner renewal only ever
+  assesses an *expired* lease;
+* un-re-lockable — the branch had by then advanced past its base;
+* and rejected by the #447 create-PR provenance guard.
+
+Each of those gates is individually correct. The defect was that two writers
+disagreed about what a lock *is*. This module is the single definition, and both
+writers now build through it.
+
+Nothing here weakens a guard. ``build_sanctioned_lock_provenance`` remains the
+only provenance source, provenance is never accepted from a caller, and the
+#447 guard is untouched — this module simply makes bootstrap satisfy it.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Any, Mapping
+
+import issue_lock_provenance
+import issue_lock_store
+import lease_policy
+
+# Bootstrap writes through the same sanctioned source as gitea_lock_issue: the
+# lock it produces *is* a canonical lock, not a second dialect that readers must
+# learn. Adding a distinct source would have required widening
+# SANCTIONED_LOCK_SOURCES, which is exactly the #447 weakening this issue's
+# safety requirements forbid.
+SOURCE_BOOTSTRAP = issue_lock_provenance.SOURCE_LOCK_ISSUE
+
+# Recovery of an incomplete bootstrap lock (#953 AC8-AC11) deliberately writes
+# through SOURCE_LOCK_ISSUE too, and records its distinctness in
+# ``lock_provenance.written_by_tool`` plus the ``bootstrap_lock_recovery``
+# transition block instead. There is no distinct recovery *source* constant, for
+# the same reason bootstrap has none: minting one would require widening
+# SANCTIONED_LOCK_SOURCES, which the #447 safety requirements forbid.
+
+#: Top-level keys every canonical author issue lock must carry.
+REQUIRED_LOCK_FIELDS: tuple[str, ...] = (
+    "remote",
+    "org",
+    "repo",
+    "issue_number",
+    "branch_name",
+    "worktree_path",
+    "work_lease",
+    "lock_provenance",
+)
+
+#: Keys every canonical ``work_lease`` must carry.
+REQUIRED_WORK_LEASE_FIELDS: tuple[str, ...] = (
+    "operation_type",
+    "issue_number",
+    "branch",
+    "worktree_path",
+    "claimant",
+    "created_at",
+    "expires_at",
+    "last_heartbeat_at",
+    "task_session_id",
+    "lifecycle_version",
+)
+
+# ── Explicit expiration states (AC12) ──
+# The bug this replaces: a lock with no recorded expiry produced
+# ``is_lease_expired() -> False``, which reads as "not yet expired" and made the
+# lock permanently non-expiring *and* permanently ineligible for the renewal
+# path, which only ever assesses an expired lease. "Absent" and "in the future"
+# are different facts and are now named differently.
+EXPIRATION_RECORDED = "recorded"
+EXPIRATION_MISSING = "missing"
+EXPIRATION_UNPARSEABLE = "unparseable"
+
+#: Structural verdicts returned by :func:`assess_lock_contract`.
+CONTRACT_CANONICAL = "canonical"
+CONTRACT_INCOMPLETE = "incomplete"
+CONTRACT_LEGACY = "legacy"
+CONTRACT_ABSENT = "absent"
+
+
+def _text(value: Any) -> str:
+    return str(value or "").strip()
+
+
+def now_utc() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def format_timestamp(value: datetime) -> str:
+    """Serialize in the durable ``...Z`` form already used on disk."""
+    return (
+        value.astimezone(timezone.utc)
+        .replace(microsecond=0)
+        .isoformat()
+        .replace("+00:00", "Z")
+    )
+
+
+def lock_claimant(lock: Mapping[str, Any] | None) -> dict[str, str]:
+    """Read the claimant from either canonical or legacy placement.
+
+    ``work_lease.claimant`` is canonical and is preferred. A top-level
+    ``claimant`` is the legacy/bootstrap placement and is accepted as a
+    fallback (AC14) — three separate readers already disagreed about this
+    (``issue_lock_store``, ``issue_lock_renewal``, ``issue_lock_recovery``),
+    which is why it now lives in one place.
+
+    Reading a legacy placement is *not* a widening: every caller still compares
+    the values it returns against server-resolved identity and profile. This
+    only decides where to look, never whether ownership is proven.
+
+    Delegates to ``issue_lock_store.lock_claimant`` rather than reimplementing
+    the rule. A second copy here would be a fourth reader that could drift from
+    the other three, which is the exact failure #953 exists to end. It lives in
+    the store because ``author_lock_contract`` imports the store, so defining it
+    here would make that import circular.
+    """
+    recorded = issue_lock_store.lock_claimant(dict(lock) if isinstance(lock, Mapping) else None)
+    return {
+        "username": _text(recorded.get("username")),
+        "profile": _text(recorded.get("profile")),
+    }
+
+
+def claimant_placement(lock: Mapping[str, Any] | None) -> str:
+    """Where the claimant was found: ``work_lease``, ``top_level``, or ``absent``."""
+    if not isinstance(lock, Mapping):
+        return "absent"
+    lease = lock.get("work_lease")
+    if isinstance(lease, Mapping) and isinstance(lease.get("claimant"), Mapping):
+        return "work_lease"
+    if isinstance(lock.get("claimant"), Mapping):
+        return "top_level"
+    return "absent"
+
+
+def build_claimant(*, username: str | None, profile: str | None) -> dict[str, str]:
+    """Build the canonical claimant pair from server-resolved values."""
+    return {"username": _text(username), "profile": _text(profile)}
+
+
+def build_author_issue_work_lease(
+    *,
+    issue_number: int,
+    branch_name: str,
+    worktree_path: str,
+    claimant: Mapping[str, Any],
+    task_session_id: str | None = None,
+    created: datetime | None = None,
+) -> dict[str, Any]:
+    """Build the canonical author ``work_lease``.
+
+    The single definition behind both writers. The TTL comes from the central
+    policy rather than a literal, and the window slides from the last valid
+    heartbeat (#790), so an abandoned task releases its claim within one TTL.
+    """
+    started = created or now_utc()
+    policy = lease_policy.policy_for(lease_policy.TASK_CLASS_AUTHOR_ISSUE_WORK)
+    expires = started + timedelta(minutes=policy.initial_ttl_minutes)
+    session_id = _text(task_session_id) or issue_lock_store.mint_task_session_id(
+        issue_lock_store.AUTHOR_ISSUE_WORK_LEASE
+    )
+    return {
+        "operation_type": issue_lock_store.AUTHOR_ISSUE_WORK_LEASE,
+        "issue_number": int(issue_number),
+        "pr_number": None,
+        "branch": branch_name,
+        "worktree_path": worktree_path,
+        "claimant": dict(claimant),
+        "created_at": format_timestamp(started),
+        "expires_at": format_timestamp(expires),
+        "last_heartbeat_at": format_timestamp(started),
+        # #790 AC-N1: the ownership key for this task, distinct from the
+        # recorded PID, which is the shared daemon and identifies no task.
+        "task_session_id": session_id,
+        # #790 AC-N8: the explicit lifecycle marker. Its absence — never a
+        # timestamp comparison — is what makes a lock legacy.
+        "lifecycle_version": lease_policy.LIFECYCLE_HEARTBEAT_V1,
+        "heartbeat_count": 1,
+    }
+
+
+def build_canonical_issue_lock(
+    *,
+    issue_number: int,
+    branch_name: str,
+    worktree_path: str,
+    remote: str,
+    org: str,
+    repo: str,
+    identity: str | None,
+    profile: str | None,
+    tool: str,
+    source: str = issue_lock_provenance.SOURCE_LOCK_ISSUE,
+    owner_session: str | None = None,
+    assignment_id: str | None = None,
+    lease_id: str | None = None,
+    expected_base_sha: str | None = None,
+    task_session_id: str | None = None,
+    created: datetime | None = None,
+) -> dict[str, Any]:
+    """Build a complete canonical lock record.
+
+    ``tool`` and ``source`` are server-supplied. There is deliberately no
+    parameter through which a caller could inject provenance: the #953 safety
+    requirements forbid caller-manufactured provenance, so provenance is always
+    minted here from ``build_sanctioned_lock_provenance``.
+    """
+    claimant = build_claimant(username=identity, profile=profile)
+    work_lease = build_author_issue_work_lease(
+        issue_number=issue_number,
+        branch_name=branch_name,
+        worktree_path=worktree_path,
+        claimant=claimant,
+        task_session_id=task_session_id,
+        created=created,
+    )
+    record: dict[str, Any] = {
+        "remote": remote,
+        "org": org,
+        "repo": repo,
+        "issue_number": int(issue_number),
+        "branch": branch_name,
+        "branch_name": branch_name,
+        "worktree_path": worktree_path,
+        "work_lease": work_lease,
+        "lock_provenance": issue_lock_provenance.build_sanctioned_lock_provenance(
+            tool=tool,
+            source=source,
+            claimant=claimant,
+        ),
+    }
+    if owner_session is not None:
+        record["owner_session"] = owner_session
+    if assignment_id is not None:
+        record["assignment_id"] = assignment_id
+    # #953 AC6: a null lease id is recorded only when no workflow lease was
+    # allocated for this bootstrap. The task-session identifier in the
+    # work_lease is what downstream ownership checks fence on, and it is never
+    # null on a canonical lock.
+    if lease_id is not None:
+        record["lease_id"] = lease_id
+    if expected_base_sha is not None:
+        record["expected_base_sha"] = expected_base_sha
+    return record
+
+
+def expiration_state(lock: Mapping[str, Any] | None) -> dict[str, Any]:
+    """Classify a lock's recorded expiry explicitly (AC12).
+
+    Distinguishes "no expiry was ever recorded" from "an expiry was recorded
+    and is still in the future". Collapsing those two into a single ``False``
+    from ``is_lease_expired`` is what let a malformed lock be treated as
+    permanently live and simultaneously never renewable.
+    """
+    if not isinstance(lock, Mapping):
+        return {"state": EXPIRATION_MISSING, "expires_at": None, "expired": None}
+    lease = lock.get("work_lease")
+    raw = lease.get("expires_at") if isinstance(lease, Mapping) else None
+    text = _text(raw)
+    if not text:
+        return {"state": EXPIRATION_MISSING, "expires_at": None, "expired": None}
+    try:
+        parsed = datetime.fromisoformat(text.replace("Z", "+00:00")).astimezone(
+            timezone.utc
+        )
+    except ValueError:
+        return {"state": EXPIRATION_UNPARSEABLE, "expires_at": text, "expired": None}
+    return {
+        "state": EXPIRATION_RECORDED,
+        "expires_at": text,
+        "expired": parsed <= now_utc(),
+    }
+
+
+def missing_contract_fields(lock: Mapping[str, Any] | None) -> list[str]:
+    """Name every canonical field a lock does not carry (AC7)."""
+    if not isinstance(lock, Mapping):
+        return ["<no lock record>"]
+    missing: list[str] = []
+    for field in REQUIRED_LOCK_FIELDS:
+        value = lock.get(field)
+        if value is None or (isinstance(value, str) and not value.strip()):
+            missing.append(field)
+    lease = lock.get("work_lease")
+    if not isinstance(lease, Mapping):
+        if "work_lease" not in missing:
+            missing.append("work_lease")
+    else:
+        for field in REQUIRED_WORK_LEASE_FIELDS:
+            value = lease.get(field)
+            if value is None or (isinstance(value, str) and not value.strip()):
+                missing.append(f"work_lease.{field}")
+    provenance = lock.get("lock_provenance")
+    if isinstance(provenance, Mapping):
+        if (
+            _text(provenance.get("source"))
+            not in issue_lock_provenance.SANCTIONED_LOCK_SOURCES
+        ):
+            missing.append("lock_provenance.source (not sanctioned)")
+        if not _text(provenance.get("written_by_tool")):
+            missing.append("lock_provenance.written_by_tool")
+    claimant = lock_claimant(lock)
+    if not claimant["username"]:
+        missing.append("claimant.username")
+    if not claimant["profile"]:
+        missing.append("claimant.profile")
+    return missing
+
+
+def assess_lock_contract(lock: Mapping[str, Any] | None) -> dict[str, Any]:
+    """Structural, read-only verdict on a durable lock record (AC7, AC16).
+
+    Pure inspection: it reads the record it is handed and mutates nothing —
+    no lock, lease, branch, worktree, issue, or PR. Callers use it both to
+    verify a lock they just wrote and to report on one they found.
+    """
+    if not isinstance(lock, Mapping) or not lock:
+        return {
+            "contract": CONTRACT_ABSENT,
+            "canonical": False,
+            "missing_fields": ["<no lock record>"],
+            "claimant": {"username": "", "profile": ""},
+            "claimant_placement": "absent",
+            "expiration": {
+                "state": EXPIRATION_MISSING,
+                "expires_at": None,
+                "expired": None,
+            },
+            "heartbeatable": False,
+            "create_pr_eligible": False,
+            "lock_generation": None,
+            "task_session_id": None,
+            "reasons": ["no durable lock record"],
+        }
+
+    missing = missing_contract_fields(lock)
+    claimant = lock_claimant(lock)
+    placement = claimant_placement(lock)
+    expiration = expiration_state(lock)
+    provenance_check = issue_lock_provenance.assess_lock_file_for_create_pr(dict(lock))
+
+    # Canonical means: every required field present, the claimant in the
+    # canonical placement, an expiry actually recorded, and the untouched #447
+    # guard satisfied.
+    canonical = (
+        not missing
+        and placement == "work_lease"
+        and expiration["state"] == EXPIRATION_RECORDED
+        and bool(provenance_check.get("proven"))
+    )
+    if canonical:
+        contract = CONTRACT_CANONICAL
+    elif placement == "top_level" and claimant["username"] and claimant["profile"]:
+        contract = CONTRACT_LEGACY
+    else:
+        contract = CONTRACT_INCOMPLETE
+
+    reasons: list[str] = []
+    if missing:
+        reasons.append("missing canonical fields: " + ", ".join(missing))
+    if placement == "top_level":
+        reasons.append(
+            "claimant recorded at the lock top level rather than in work_lease "
+            "(legacy/bootstrap placement)"
+        )
+    if expiration["state"] == EXPIRATION_MISSING:
+        reasons.append(
+            "no expiration recorded; the lock is neither expirable nor renewable "
+            "until it is upgraded"
+        )
+    elif expiration["state"] == EXPIRATION_UNPARSEABLE:
+        reasons.append(f"unparseable expires_at '{expiration['expires_at']}'")
+    if provenance_check.get("block"):
+        reasons.extend(provenance_check.get("reasons") or [])
+
+    # Heartbeat needs the claimant pair (from either placement, post-fix) plus a
+    # task-session identifier to fence on.
+    lease = lock.get("work_lease")
+    task_session_id = (
+        _text(lease.get("task_session_id")) if isinstance(lease, Mapping) else ""
+    )
+    heartbeatable = bool(
+        claimant["username"] and claimant["profile"] and task_session_id
+    )
+
+    return {
+        "contract": contract,
+        "canonical": canonical,
+        "missing_fields": missing,
+        "claimant": claimant,
+        "claimant_placement": placement,
+        "expiration": expiration,
+        "heartbeatable": heartbeatable,
+        "create_pr_eligible": bool(provenance_check.get("proven")),
+        "lock_generation": lock.get("lock_generation"),
+        "task_session_id": task_session_id or None,
+        "reasons": reasons,
+    }
+
+
+def format_contract_refusal(assessment: Mapping[str, Any]) -> str:
+    """Human-readable refusal naming exactly what the lock is missing."""
+    missing = ", ".join(assessment.get("missing_fields") or []) or "unknown fields"
+    return (
+        "Issue lock contract incomplete (#953): "
+        f"{missing}. The lock cannot be heartbeated, renewed, or accepted by "
+        "gitea_create_pr in this state (fail closed)"
+    )
+
+
+def recommended_action(assessment: Mapping[str, Any]) -> str:
+    """The one executable next step for a lock in this state (AC5, AC15)."""
+    contract = assessment.get("contract")
+    if contract == CONTRACT_CANONICAL:
+        return (
+            "Lock is canonical. Call gitea_whoami, then "
+            "gitea_resolve_task_capability(task='work_issue'), then proceed with "
+            "author implementation in the bootstrapped worktree."
+        )
+    if contract == CONTRACT_ABSENT:
+        return (
+            "No durable lock exists. Call gitea_lock_issue for this issue and "
+            "branch before writing any implementation bytes."
+        )
+    return (
+        "Do not begin implementation. Call "
+        "gitea_recover_incomplete_bootstrap_lock for this exact issue, branch, "
+        "and worktree to upgrade the lock to the canonical contract, or "
+        "gitea_lock_issue while the worktree is still base-equivalent."
+    )
+
+
+# ── Post-compensation recovery guidance (#953 AC5/AC15, review 632 F2) ──
+#
+# ``recommended_action`` above answers "what can be done about a lock in this
+# shape". That is the wrong question on the bootstrap AC7 refusal path, because
+# ``run_compensating_recovery`` has already run by the time the answer is
+# reported: it releases the lock, removes the worktree when clean — which it
+# always is there, no implementation bytes having been written — and deletes the
+# created branch. Recommending incomplete-lock recovery for those artifacts
+# hands the author two refusals in a row (``no_durable_lock``, then
+# ``worktree_invalid``) for a state that a plain bootstrap retry would fix. The
+# advice must describe the state that actually *remains*.
+
+#: Compensation removed every artifact this transition created.
+CLEANUP_COMPLETE = "complete"
+#: Compensation removed some artifacts; others survive and are still actionable.
+CLEANUP_PARTIAL = "partial"
+#: Compensation itself failed or could not be observed; nothing is provable.
+CLEANUP_FAILED = "failed"
+
+
+def assess_post_compensation_state(
+    recovery: Mapping[str, Any] | None,
+    *,
+    lock_present: bool,
+    worktree_present: bool,
+    branch_present: bool,
+) -> dict[str, Any]:
+    """Classify what survived compensation, from observed durable state.
+
+    Pure. The caller observes the filesystem and git; this decides. Observation
+    is authoritative over the journal's ``rolled_back`` list, which records what
+    compensation *attempted*: ``run_compensating_recovery`` swallows a failed
+    lock release and appends nothing, so an absent marker proves nothing either
+    way. The list is still carried through as corroborating evidence.
+
+    The three states are distinct facts, not degrees of the same one:
+
+    * ``CLEANUP_COMPLETE`` — compensation ran and nothing it created remains.
+    * ``CLEANUP_PARTIAL`` — compensation ran and artifacts survive, whether by
+      design (a worktree dirty at rollback time, a branch carrying commits) or
+      because a rollback step errored. Either way the surviving set was observed
+      directly, so it is known and actionable; ``failed_rollback_steps`` records
+      which cause applies.
+    * ``CLEANUP_FAILED`` — compensation never ran to completion, so nothing it
+      would have removed can be assumed removed.
+    """
+    rolled_back = list((recovery or {}).get("rolled_back") or [])
+    executed = bool((recovery or {}).get("executed"))
+    failed_steps = [entry for entry in rolled_back if "_failed" in entry]
+
+    surviving: list[str] = []
+    if lock_present:
+        surviving.append("lock")
+    if worktree_present:
+        surviving.append("worktree")
+    if branch_present:
+        surviving.append("branch")
+
+    if not executed:
+        state = CLEANUP_FAILED
+    elif surviving:
+        state = CLEANUP_PARTIAL
+    else:
+        state = CLEANUP_COMPLETE
+
+    return {
+        "cleanup_state": state,
+        "compensation_executed": executed,
+        "lock_present": bool(lock_present),
+        "worktree_present": bool(worktree_present),
+        "branch_present": bool(branch_present),
+        "surviving_artifacts": surviving,
+        "removed_artifacts": [
+            name
+            for name, present in (
+                ("lock", lock_present),
+                ("worktree", worktree_present),
+                ("branch", branch_present),
+            )
+            if not present
+        ],
+        "failed_rollback_steps": failed_steps,
+        "rolled_back": rolled_back,
+    }
+
+
+def post_compensation_action(
+    state: Mapping[str, Any],
+    *,
+    issue_number: int,
+    branch_name: str,
+    worktree_path: str,
+    missing_fields: list[str] | None = None,
+) -> str:
+    """The one executable next step for the state compensation actually left.
+
+    Every branch names only artifacts the classification says still exist, so no
+    recommendation can point at something the rollback deleted.
+    """
+    missing = ", ".join(missing_fields or []) or "the reported missing fields"
+    cleanup_state = state.get("cleanup_state")
+    lock_present = bool(state.get("lock_present"))
+    worktree_present = bool(state.get("worktree_present"))
+    branch_present = bool(state.get("branch_present"))
+
+    if not state.get("compensation_executed"):
+        # Compensation never ran, so nothing was rolled back and nothing about
+        # the remaining state was decided. The read-only surface is the only
+        # action executable under any state.
+        return (
+            "Compensating rollback did not complete, so the remaining state is "
+            f"not proven. Call gitea_inspect_issue_lock_contract for issue "
+            f"#{issue_number} (read-only) to establish what survives before any "
+            "further action. Do not retry bootstrap until it is known."
+        )
+
+    prefix = ""
+    failed_steps = state.get("failed_rollback_steps") or []
+    if failed_steps:
+        prefix = (
+            "Compensating rollback reported a failed step "
+            f"({', '.join(failed_steps)}); what survives was observed directly "
+            "and the action below is scoped to exactly that. "
+        )
+
+    if cleanup_state == CLEANUP_COMPLETE:
+        return (
+            "Compensating rollback removed the malformed lock, the branch, and "
+            f"the worktree, so nothing from this attempt remains. Resolve "
+            f"{missing} and re-run gitea_bootstrap_author_issue_worktree for "
+            f"issue #{issue_number} from the clean pre-bootstrap state. Do not "
+            "call gitea_recover_incomplete_bootstrap_lock: there is no lock, "
+            "branch, or worktree left for it to act on."
+        )
+
+    if lock_present and worktree_present and branch_present:
+        return prefix + (
+            "The lock, branch, and worktree all survive. Call "
+            "gitea_recover_incomplete_bootstrap_lock for issue "
+            f"#{issue_number}, branch '{branch_name}', and worktree "
+            f"'{worktree_path}', passing the worktree's current head as "
+            "expected_head, to upgrade the lock to the canonical contract."
+        )
+
+    if not lock_present and worktree_present and branch_present:
+        return prefix + (
+            "The malformed lock was released but the branch and worktree "
+            "survive. No implementation bytes were written, so the worktree is "
+            f"still base-equivalent: call gitea_lock_issue for issue "
+            f"#{issue_number} on branch '{branch_name}' from worktree "
+            f"'{worktree_path}' to acquire a canonical lock."
+        )
+
+    if lock_present and not worktree_present:
+        return prefix + (
+            f"The worktree for issue #{issue_number} is gone but the durable "
+            "lock survived, so neither gitea_recover_incomplete_bootstrap_lock "
+            "(it would refuse worktree_invalid) nor gitea_lock_issue (it has no "
+            "worktree to bind) is executable. Call "
+            "gitea_inspect_issue_lock_contract for issue "
+            f"#{issue_number} (read-only) to confirm the surviving lock; it "
+            "must be released by its recorded owner before bootstrap is "
+            "retried."
+        )
+
+    # Lock gone, worktree gone, some git artifact left (a branch with commits,
+    # or a branch this transition did not create).
+    return prefix + (
+        "Compensating rollback removed the lock and worktree; branch "
+        f"'{branch_name}' survives and was not deleted. Call "
+        f"gitea_inspect_issue_lock_contract for issue #{issue_number} "
+        "(read-only) to confirm no durable lock remains, then re-run "
+        "gitea_bootstrap_author_issue_worktree, which will adopt the existing "
+        "branch rather than recreating it."
+    )

bootstrap_lock_recovery.py

@@ -0,0 +1,304 @@
+"""Target-specific recovery for incomplete bootstrap issue locks (#953).
+
+The situation this exists for: ``gitea_bootstrap_author_issue_worktree``
+reported success, wrote an incomplete lock, and told the author to implement.
+The author did — legitimately, following the tool's own reported next action —
+and the branch now carries real committed and pushed work. At that point every
+pre-existing recovery path is simultaneously ineligible:
+
+* heartbeat refuses, because the claimant is not where it looks;
+* ``gitea_lock_issue`` refuses, because the branch is no longer base-equivalent;
+* #760 exact-owner renewal never engages, because a lock with no recorded
+  expiry is never *expired*;
+* the #447 create-PR guard refuses, because there is no provenance.
+
+Distinct from every neighbouring path: #753 ``issue_lock_recovery`` requires a
+dead owner PID, #760 ``issue_lock_renewal`` requires an *expired* lease, and
+#442 ``issue_lock_adoption`` decides branch adoption. None of them addresses a
+lock that is structurally incomplete and therefore never expires at all.
+
+**What this will not do.** It never moves, resets, or rewinds a branch, and
+never requires base-equivalence — the committed work is the thing being
+preserved. It never pushes and never opens a pull request. It touches only the
+one lock file named by (remote, org, repo, issue). It accepts no caller-supplied
+provenance and no caller-supplied authorization flag; both are minted
+server-side. It refuses a healthy foreign-owned lock outright, and a matching
+username alone is never accepted as proof of ownership — the profile must match
+too, and the lock's recorded binding must agree with the observed branch,
+worktree, and head.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Mapping
+
+import author_lock_contract
+import issue_lock_store
+
+#: Refusal codes, so callers can branch on cause rather than parse prose.
+REFUSAL_NO_LOCK = "no_durable_lock"
+REFUSAL_ALREADY_CANONICAL = "already_canonical"
+REFUSAL_FOREIGN_CLAIMANT = "foreign_claimant"
+REFUSAL_HEALTHY_FOREIGN = "healthy_foreign_lock"
+REFUSAL_IDENTITY_UNRESOLVED = "identity_unresolved"
+REFUSAL_BINDING_MISMATCH = "binding_mismatch"
+REFUSAL_WORKTREE_INVALID = "worktree_invalid"
+REFUSAL_HEAD_MISMATCH = "head_mismatch"
+
+
+def _text(value: Any) -> str:
+    return str(value or "").strip()
+
+
+def _same_realpath(left: str | None, right: str | None) -> bool:
+    lhs, rhs = _text(left), _text(right)
+    if not lhs or not rhs:
+        return False
+    try:
+        return os.path.realpath(lhs) == os.path.realpath(rhs)
+    except OSError:
+        return lhs == rhs
+
+
+def assess_bootstrap_lock_recovery(
+    existing_lock: Mapping[str, Any] | None,
+    *,
+    issue_number: int,
+    branch_name: str,
+    worktree_path: str,
+    remote: str,
+    org: str,
+    repo: str,
+    identity: str | None,
+    profile: str | None,
+    observed_head: str | None,
+    declared_head: str | None,
+    worktree_exists: bool,
+    worktree_registered: bool,
+    current_branch: str | None,
+    now: Any = None,
+) -> dict[str, Any]:
+    """Decide whether this exact lock may be upgraded by this exact caller.
+
+    Pure: every input is an observation the caller already made, and nothing
+    here reads or writes the filesystem, git, or Gitea. That is what makes the
+    same decision testable in isolation and reusable by the read-only
+    inspection surface, which must not mutate anything (AC16).
+
+    Returns a dict with ``recovery_sanctioned`` plus the full evidence set. A
+    refusal never raises — it reports, so the caller can surface exactly which
+    piece of evidence was missing.
+    """
+    reasons: list[str] = []
+    refusal_code: str | None = None
+
+    contract = author_lock_contract.assess_lock_contract(existing_lock)
+
+    if not existing_lock:
+        return {
+            "recovery_sanctioned": False,
+            "refusal_code": REFUSAL_NO_LOCK,
+            "reasons": [
+                f"no durable issue lock exists for issue #{issue_number}; there is "
+                "nothing to recover (fail closed)"
+            ],
+            "contract": contract,
+            "evidence": {},
+            "expected_generation": None,
+        }
+
+    active_identity = _text(identity)
+    active_profile = _text(profile)
+    recorded = author_lock_contract.lock_claimant(existing_lock)
+    freshness = issue_lock_store.assess_lock_freshness(dict(existing_lock), now=now)
+    generation = issue_lock_store.lock_generation(existing_lock)
+
+    evidence: dict[str, Any] = {
+        "recorded_claimant": recorded,
+        "active_identity": active_identity,
+        "active_profile": active_profile,
+        "recorded_branch": existing_lock.get("branch_name"),
+        "recorded_worktree": existing_lock.get("worktree_path"),
+        "recorded_owner_session": existing_lock.get("owner_session"),
+        "recorded_generation": generation,
+        "recorded_remote": existing_lock.get("remote"),
+        "recorded_org": existing_lock.get("org"),
+        "recorded_repo": existing_lock.get("repo"),
+        "observed_head": _text(observed_head),
+        "declared_head": _text(declared_head),
+        "current_branch": _text(current_branch),
+        "worktree_exists": bool(worktree_exists),
+        "worktree_registered": bool(worktree_registered),
+        "freshness": freshness,
+        "claimant_placement": contract.get("claimant_placement"),
+        "expiration_state": contract.get("expiration", {}).get("state"),
+    }
+
+    # ── Repository and issue identity (AC10) ──
+    if _text(existing_lock.get("remote")) != _text(remote):
+        reasons.append(
+            f"recorded remote '{existing_lock.get('remote')}' does not match '{remote}'"
+        )
+        refusal_code = refusal_code or REFUSAL_BINDING_MISMATCH
+    if _text(existing_lock.get("org")) != _text(org):
+        reasons.append(
+            f"recorded org '{existing_lock.get('org')}' does not match '{org}'"
+        )
+        refusal_code = refusal_code or REFUSAL_BINDING_MISMATCH
+    if _text(existing_lock.get("repo")) != _text(repo):
+        reasons.append(
+            f"recorded repo '{existing_lock.get('repo')}' does not match '{repo}'"
+        )
+        refusal_code = refusal_code or REFUSAL_BINDING_MISMATCH
+    if existing_lock.get("issue_number") != issue_number:
+        reasons.append(
+            f"lock targets issue #{existing_lock.get('issue_number')}, not "
+            f"#{issue_number}"
+        )
+        refusal_code = refusal_code or REFUSAL_BINDING_MISMATCH
+
+    # ── Branch and worktree binding (AC10) ──
+    if _text(existing_lock.get("branch_name")) != _text(branch_name):
+        reasons.append(
+            f"recorded branch '{existing_lock.get('branch_name')}' does not match "
+            f"'{branch_name}'"
+        )
+        refusal_code = refusal_code or REFUSAL_BINDING_MISMATCH
+    if not _same_realpath(existing_lock.get("worktree_path"), worktree_path):
+        reasons.append(
+            f"recorded worktree '{existing_lock.get('worktree_path')}' does not "
+            f"match '{worktree_path}'"
+        )
+        refusal_code = refusal_code or REFUSAL_BINDING_MISMATCH
+
+    # ── The worktree is real, registered, and on the branch (AC10) ──
+    # Deliberately no base-equivalence requirement and no constraint on how far
+    # the branch has advanced: the whole point is that it already carries the
+    # author's legitimate commits (AC9).
+    if not worktree_exists:
+        reasons.append(f"declared worktree '{worktree_path}' does not exist")
+        refusal_code = refusal_code or REFUSAL_WORKTREE_INVALID
+    if not worktree_registered:
+        reasons.append(f"worktree '{worktree_path}' is not a registered git worktree")
+        refusal_code = refusal_code or REFUSAL_WORKTREE_INVALID
+    if _text(current_branch) != _text(branch_name):
+        reasons.append(
+            f"worktree is on branch '{_text(current_branch) or 'unknown'}', not "
+            f"'{branch_name}'"
+        )
+        refusal_code = refusal_code or REFUSAL_WORKTREE_INVALID
+
+    # ── Current head fencing (AC10) ──
+    # The caller names the commit it believes it is recovering. A mismatch means
+    # the worktree moved under the caller, so the decision is stale.
+    if not _text(observed_head):
+        reasons.append("could not observe the worktree head")
+        refusal_code = refusal_code or REFUSAL_HEAD_MISMATCH
+    elif _text(declared_head) and _text(declared_head) != _text(observed_head):
+        reasons.append(
+            f"declared head '{_text(declared_head)}' does not match observed head "
+            f"'{_text(observed_head)}'"
+        )
+        refusal_code = refusal_code or REFUSAL_HEAD_MISMATCH
+
+    # ── Ownership (AC10, AC11) ──
+    # A matching username alone is never sufficient: the profile must match too,
+    # and both are compared against server-resolved values the caller cannot set.
+    if not active_identity or not active_profile:
+        reasons.append(
+            "active identity and profile could not both be resolved; ownership "
+            "cannot be proven"
+        )
+        refusal_code = refusal_code or REFUSAL_IDENTITY_UNRESOLVED
+    if not recorded["username"] or not recorded["profile"]:
+        reasons.append(
+            "durable lock does not record both a claimant username and profile"
+        )
+        refusal_code = refusal_code or REFUSAL_FOREIGN_CLAIMANT
+    elif (
+        recorded["username"] != active_identity
+        or recorded["profile"] != active_profile
+    ):
+        # AC11: a foreign-owned lock is never recoverable through this path,
+        # healthy or not. The healthy case is reported distinctly so the refusal
+        # is legible, but both refuse.
+        if freshness.get("live"):
+            reasons.append(
+                f"lock is owned by a healthy foreign claimant "
+                f"'{recorded['username']}/{recorded['profile']}'; takeover is not "
+                "a recovery path"
+            )
+            refusal_code = REFUSAL_HEALTHY_FOREIGN
+        else:
+            reasons.append(
+                f"lock claimant '{recorded['username']}/{recorded['profile']}' "
+                f"does not match active '{active_identity}/{active_profile}'"
+            )
+            refusal_code = refusal_code or REFUSAL_FOREIGN_CLAIMANT
+
+    # ── Nothing to recover ──
+    # A lock that is already canonical is left strictly alone. Rewriting it would
+    # mint a new task-session identifier and invalidate the heartbeat token the
+    # legitimate owner is already using.
+    if contract.get("canonical") and not reasons:
+        return {
+            "recovery_sanctioned": False,
+            "refusal_code": REFUSAL_ALREADY_CANONICAL,
+            "reasons": [
+                "lock already satisfies the canonical contract; no recovery is "
+                "required"
+            ],
+            "contract": contract,
+            "evidence": evidence,
+            "expected_generation": generation,
+        }
+
+    sanctioned = not reasons
+    return {
+        "recovery_sanctioned": sanctioned,
+        "refusal_code": None if sanctioned else refusal_code,
+        "reasons": reasons,
+        "contract": contract,
+        "evidence": evidence,
+        "expected_generation": generation,
+    }
+
+
+def build_recovery_record(
+    assessment: Mapping[str, Any],
+    *,
+    recovered_at: str,
+    new_task_session_id: str,
+) -> dict[str, Any]:
+    """Auditable record of the ownership and generation transition (AC10).
+
+    A recovered lock must never read as an original claim, so both sides of the
+    transition are preserved: what the incomplete lock recorded, and what
+    replaced it.
+    """
+    evidence = dict(assessment.get("evidence") or {})
+    contract = dict(assessment.get("contract") or {})
+    return {
+        "recovery_kind": "incomplete_bootstrap_lock",
+        "recovered_at": recovered_at,
+        "prior_contract": contract.get("contract"),
+        "prior_missing_fields": list(contract.get("missing_fields") or []),
+        "prior_claimant_placement": evidence.get("claimant_placement"),
+        "prior_expiration_state": evidence.get("expiration_state"),
+        "prior_generation": evidence.get("recorded_generation"),
+        "prior_owner_session": evidence.get("recorded_owner_session"),
+        "prior_freshness": (evidence.get("freshness") or {}).get("status"),
+        "replacement_task_session_id": new_task_session_id,
+        "preserved_head": evidence.get("observed_head"),
+        "branch_reset": False,
+        "base_equivalence_required": False,
+    }
+
+
+def format_recovery_refusal(assessment: Mapping[str, Any]) -> str:
+    reasons = "; ".join(
+        assessment.get("reasons") or ["unknown bootstrap lock recovery refusal"]
+    )
+    code = assessment.get("refusal_code") or "refused"
+    return f"Bootstrap lock recovery refused ({code}): {reasons} (fail closed)"

docs/author-issue-lock-contract.md

@@ -0,0 +1,209 @@
+# The canonical author issue-lock contract (#953)
+
+Every author issue lock has exactly one shape. Both writers —
+`gitea_bootstrap_author_issue_worktree` and `gitea_lock_issue` — build it
+through `author_lock_contract.build_canonical_issue_lock`, and every reader
+consumes that same shape.
+
+Before #953 the two writers disagreed. `gitea_lock_issue` wrote the canonical
+record; bootstrap wrote a thinner one with the claimant at the lock top level,
+`lease_id: null`, and no `work_lease`, `lock_provenance`, or expiry. Because
+every reader was written against the canonical shape, a lock that bootstrap
+reported as successfully created could not be heartbeated, renewed, re-locked,
+or accepted by `gitea_create_pr`. Each of those gates was individually correct;
+the defect was that two writers disagreed about what a lock *is*.
+
+## Required ordering
+
+**Finalize the lock before writing any implementation bytes.** This ordering is
+what keeps recovery cheap: while the worktree is still base-equivalent, a lock
+problem can be fixed by simply calling `gitea_lock_issue` again. Once the branch
+carries commits, base-equivalence is gone and the ordinary re-lock path is no
+longer available.
+
+1. `gitea_whoami` — resolve identity and profile.
+2. `gitea_resolve_task_capability(task='work_issue')`.
+3. `gitea_bootstrap_author_issue_worktree` — creates the branch, the registered
+   worktree under `branches/`, and a **canonical** lock. It reads the lock back
+   and verifies it structurally before reporting success; a partial lock fails
+   closed here, with the missing fields named, and never reports
+   `implementation_allowed: true`.
+4. `gitea_heartbeat_issue_lock` — prove the lock is usable, using the
+   `task_session_id` bootstrap returned.
+5. Implement, commit, push.
+6. `gitea_create_pr`.
+
+If bootstrap returns `success: false` with
+`reason_code: incomplete_issue_lock_contract`, **do not implement**. Its
+`exact_next_action` names the executable recovery step. Bootstrap's reported
+next action always matches the state it actually returned.
+
+### What that refusal leaves behind
+
+The AC7 refusal runs `run_compensating_recovery` *before* it reports, so the
+advice has to describe the post-rollback state rather than the shape of the lock
+that provoked it. Recommending incomplete-lock recovery for artifacts the
+rollback already deleted would produce `no_durable_lock` and then
+`worktree_invalid` — two refusals for a state a plain retry fixes.
+
+The refusal therefore carries `compensating_recovery` and
+`post_compensation_state`, and derives `exact_next_action` from what was
+observed on disk. `cleanup_state` is one of:
+
+| `cleanup_state` | Meaning | Next action |
+| --- | --- | --- |
+| `complete` | lock, branch, and worktree all removed | resolve `missing_fields` and re-run `gitea_bootstrap_author_issue_worktree` |
+| `partial` | rollback ran; some artifacts survive, by design or because a step errored | scoped to exactly what survives — see below |
+| `failed` | rollback never completed, so nothing is proven removed | `gitea_inspect_issue_lock_contract` (read-only) before anything else |
+
+Within `partial`, the surviving set decides the action:
+
+| Survives | Next action |
+| --- | --- |
+| lock + branch + worktree | `gitea_recover_incomplete_bootstrap_lock` for that exact issue, branch, and worktree |
+| branch + worktree (lock released) | `gitea_lock_issue` — no implementation bytes were written, so the worktree is still base-equivalent |
+| lock only (worktree removed) | `gitea_inspect_issue_lock_contract`; the surviving lock must be released by its recorded owner before bootstrap is retried |
+| branch only | `gitea_inspect_issue_lock_contract`, then re-run bootstrap, which adopts the existing branch |
+
+`failed_rollback_steps` names any rollback step that errored, and the returned
+action says so rather than presenting the surviving state as intentional.
+
+> The lock half of that rollback was dead code until #953 review 632 F2:
+> `run_compensating_recovery` called `issue_lock_store.release_session_lock`,
+> which did not exist, inside a bare `except Exception: pass`. Every rollback
+> removed the branch and worktree and silently left the lock — the exact
+> uninspectable, unrecoverable state this issue exists to eliminate. The
+> function now exists, releases only a lock whose recorded `owner_session`
+> matches, and its failures are recorded rather than swallowed.
+
+## The contract
+
+A canonical lock carries every field in
+`author_lock_contract.REQUIRED_LOCK_FIELDS`:
+
+| Field | Meaning |
+| --- | --- |
+| `remote`, `org`, `repo`, `issue_number` | repository and issue identity |
+| `branch_name`, `worktree_path` | the binding this claim owns |
+| `work_lease` | the canonical lease block, below |
+| `lock_provenance` | sanctioned source, minted server-side |
+| `lock_generation` | monotonic; every write advances it |
+
+`work_lease` carries every field in
+`author_lock_contract.REQUIRED_WORK_LEASE_FIELDS`, notably:
+
+| Field | Meaning |
+| --- | --- |
+| `claimant.{username,profile}` | **canonical** claimant placement |
+| `expires_at` | sliding TTL from `lease_policy` |
+| `last_heartbeat_at`, `heartbeat_count` | liveness evidence |
+| `task_session_id` | the ownership fencing token — never null |
+| `lifecycle_version` | `heartbeat-v1`; its absence is what makes a lock legacy |
+
+### Claimant placement and legacy compatibility
+
+`work_lease.claimant` is canonical. A top-level `claimant` is the legacy
+placement written by pre-#953 bootstrap and is still **read** — through the one
+shared reader, `issue_lock_store.lock_claimant` — so an existing lock is not
+refused for "not recording a claimant" when it plainly records one.
+
+Tolerating the placement is not a widening. Every caller still compares the
+values against server-resolved identity and profile, so a legacy placement
+grants nothing the canonical placement would not. When both are present, the
+`work_lease` copy wins: after an upgrade, a stale top-level copy must never
+decide ownership.
+
+### Expiration is explicit
+
+A lock with no recorded expiry is **not** "not yet expired". `is_lease_expired`
+returns `False` for it, which used to make such a lock permanently non-expiring
+*and* permanently ineligible for #760 exact-owner renewal, which only ever
+assesses an expired lease. `author_lock_contract.expiration_state` names the
+real fact: `recorded`, `missing`, or `unparseable`. A `missing` expiry makes the
+lock eligible for the recovery path below rather than stranding it.
+
+## Recovering an existing incomplete bootstrap lock
+
+For locks already written by the old bootstrap — including those whose branches
+already carry legitimate committed and pushed work — use:
+
+```text
+gitea_inspect_issue_lock_contract(issue_number, branch_name, worktree_path, remote=...)
+gitea_recover_incomplete_bootstrap_lock(issue_number, branch_name, worktree_path, expected_head, remote=...)
+```
+
+`gitea_inspect_issue_lock_contract` is strictly read-only: it performs no lock,
+lease, branch, worktree, issue, or pull-request mutation. Use it first to see
+which fields are missing and what the recommended action is; pass `dry_run=True`
+to the recovery tool to preview the decision without writing.
+
+`gitea_recover_incomplete_bootstrap_lock` upgrades that one lock to the
+canonical contract. Before writing anything it verifies:
+
+* repository (`remote`, `org`, `repo`) and issue number
+* claimant username **and** profile against the server-resolved values — a
+  matching username alone is never accepted
+* branch, worktree path, worktree existence, and worktree registration
+* the worktree is on the recorded branch
+* the observed head equals the caller's `expected_head`
+* the existing lock's generation and provenance state
+* the absence of healthy foreign ownership
+
+What it deliberately does **not** do:
+
+* it never moves, resets, or rewinds the branch, and never requires
+  base-equivalence — preserving the committed work is the entire point;
+* it never pushes and never creates a pull request;
+* it touches only the single lock file for that exact remote/org/repo/issue;
+* it accepts no caller-supplied provenance and no caller-supplied authorization
+  flag — both are minted server-side.
+
+A recovered lock records a `bootstrap_lock_recovery` block holding both sides of
+the transition — prior contract, prior missing fields, prior generation, prior
+owning session, the replacement `task_session_id`, and the preserved head — so a
+recovered claim never reads as an original one.
+
+### Gates, in order
+
+`gitea_recover_incomplete_bootstrap_lock` is an author-only durable-lock
+mutation and carries the same three gates as every comparable author operation,
+in this order:
+
+1. `role_session_router.check_author_mutation_after_reviewer_stop` — no author
+   fallback after a reviewer `wrong_role_stop`.
+2. `_namespace_mutation_block(task, remote=remote, author_role_exclusive=True)` —
+   the namespace wall. It refuses a reviewer-bound session and, because this
+   task's required permission is `gitea.issue.comment` (which merger,
+   controller, and reconciler profiles also hold), additionally requires the
+   active profile's derived role kind to be exactly `author`. A refusal carries
+   `namespace_block: true` and emits a `BLOCKED` audit record naming the
+   namespace and profile.
+3. `_profile_permission_block` — operation, provenance, and session-context
+   gates.
+
+Exact-owner claimant matching inside `assess_bootstrap_lock_recovery` runs
+*after* all three. It is a further layer, never a substitute for them: on its
+own it refuses one step too late and leaves the audit trail silent about the
+attempt.
+
+### Refusals
+
+| `refusal_code` | Meaning |
+| --- | --- |
+| `no_durable_lock` | nothing to recover |
+| `already_canonical` | lock is fine; rewriting would invalidate a live heartbeat token |
+| `foreign_claimant` | recorded claimant is not the active identity/profile pair |
+| `healthy_foreign_lock` | a live foreign-owned lock; takeover is not a recovery path |
+| `identity_unresolved` | identity or profile could not be resolved |
+| `binding_mismatch` | repository, issue, branch, or worktree does not match |
+| `worktree_invalid` | worktree missing, unregistered, or on another branch |
+| `head_mismatch` | the worktree moved under the caller |
+
+## The #447 create-PR provenance guard is unchanged
+
+`issue_lock_provenance.assess_lock_file_for_create_pr` still requires both a
+sanctioned `lock_provenance` and a `work_lease`, and the sanctioned source set
+was **not** widened. Bootstrap writes through
+`issue_lock_provenance.SOURCE_LOCK_ISSUE` — the lock it produces *is* a
+canonical lock, not a second dialect with its own exemption. Bootstrap now
+satisfies the guard rather than the guard being relaxed to admit bootstrap.

docs/mcp-tool-inventory.md

@@ -103,6 +103,7 @@ that gates each call, not which tools exist.
 - `gitea_get_shell_health`
 - `gitea_heartbeat_issue_lock`
 - `gitea_heartbeat_reviewer_pr_lease`
+- `gitea_inspect_issue_lock_contract`
 - `gitea_inspect_workflow_lease`
 - `gitea_issue_irrecoverable_provenance_authorization`
 - `gitea_list_dependency_edges`
@@ -134,6 +135,7 @@ that gates each call, not which tools exist.
 - `gitea_record_pre_review_command`
 - `gitea_record_shell_spawn_outcome`
 - `gitea_record_stable_branch_push_attempt`
+- `gitea_recover_incomplete_bootstrap_lock`
 - `gitea_release_merger_pr_lease`
 - `gitea_release_reviewer_pr_lease`
 - `gitea_release_workflow_lease`

docs/remote-mcp/threat-model-anchors.json

@@ -0,0 +1,80 @@
+{
+  "_comment": [
+    "Machine-checkable anchor table for docs/remote-mcp/threat-model.md (#956).",
+    "Every file:line anchor cited in the threat model must appear here, and the",
+    "source line at that anchor must contain the 'expect' substring.",
+    "tests/test_issue_956_threat_model.py enforces both directions, so a refactor",
+    "that shifts a line number fails the suite instead of silently rotting the",
+    "document. #930's inventory had no such guard and its gitea_mcp_server.py",
+    "anchors drifted between 7bf4f125 and aad5c8b4."
+  ],
+  "generated_against_commit": "a143cd065ba06e1a2bdc5143a19ec156e53650ef",
+  "anchors": [
+    {"anchor": "gitea_mcp_server.py:24728", "expect": "mcp_daemon_guard.bind_native_mcp_transport()"},
+    {"anchor": "mcp_daemon_guard.py:49", "expect": "_PRODUCTION_TRANSPORTS = mcp_transport_config.SUPPORTED_TRANSPORTS"},
+    {"anchor": "mcp_daemon_guard.py:195", "expect": "def bind_native_mcp_transport"},
+    {"anchor": "irrecoverable_provenance.py:497", "expect": "def assess_transport_for_auth_mint"},
+    {"anchor": "gitea_mcp_server.py:9132", "expect": "assess_transport_for_auth_mint()"},
+    {"anchor": "gitea_mcp_server.py:9381", "expect": "assess_transport_for_auth_mint()"},
+    {"anchor": "mcp_server.py:4", "expect": "The transport is selected by deployment configuration"},
+
+    {"anchor": "gitea_mcp_server.py:15415", "expect": "def _is_client_managed_process"},
+    {"anchor": "gitea_mcp_server.py:15445", "expect": "def _provenance_mutation_block"},
+    {"anchor": "gitea_mcp_server.py:15453", "expect": "unsupported_manual_launch"},
+    {"anchor": "gitea_mcp_server.py:19004", "expect": "server_provenance"},
+    {"anchor": "gitea_mcp_server.py:21445", "expect": "def _check_mcp_runtimes_diagnostics"},
+    {"anchor": "gitea_mcp_server.py:21465", "expect": "\"ps\", \"-o\", \"pid,lstart,command\""},
+    {"anchor": "gitea_mcp_server.py:21509", "expect": "\"ps\", \"eww\""},
+    {"anchor": "gitea_config.py:1172", "expect": "RECOGNIZED_GITEA_ENV_KEYS"},
+    {"anchor": "gitea_config.py:1233", "expect": "GITEA_CLIENT_MANAGED"},
+
+    {"anchor": "gitea_config.py:54", "expect": "ENV_PROFILE = \"GITEA_MCP_PROFILE\""},
+    {"anchor": "gitea_config.py:97", "expect": "_REVIEW_MERGE_OPS"},
+    {"anchor": "gitea_config.py:499", "expect": "repository authorization scope"},
+
+    {"anchor": "gitea_config.py:956", "expect": "def _keychain_token"},
+    {"anchor": "gitea_config.py:974", "expect": "def resolve_token"},
+    {"anchor": "gitea_config.py:1015", "expect": "def keychain_auth"},
+    {"anchor": "gitea_config.py:294", "expect": "def _validate_identity_auth"},
+    {"anchor": "mcp_daemon_guard.py:583", "expect": "def assert_keychain_access_allowed"},
+    {"anchor": "gitea_mcp_server.py:19261", "expect": "def gitea_list_profiles"},
+    {"anchor": "gitea_mcp_server.py:19312", "expect": "gitea_config.resolve_token(p)"},
+    {"anchor": "gitea_mcp_server.py:19555", "expect": "def gitea_audit_config"},
+    {"anchor": "gitea_mcp_server.py:19577", "expect": "service_summaries(config)"},
+
+    {"anchor": "gitea_config.py:704", "expect": "def resolve_service"},
+    {"anchor": "gitea_config.py:837", "expect": "def service_summaries"},
+    {"anchor": "gitea_config.py:851", "expect": "_keychain_token(auth.get(\"id\"))"},
+    {"anchor": "gitea_mcp_server.py:17710", "expect": "\"jenkins-mcp\""},
+    {"anchor": "gitea_mcp_server.py:17716", "expect": "external-mcp"},
+    {"anchor": "gitea_mcp_server.py:17737", "expect": "\"glitchtip-mcp\""},
+    {"anchor": "gitea_mcp_server.py:17742", "expect": "external-mcp"},
+    {"anchor": "mcp_discoverability.py:9", "expect": "EXPECTED_JENKINS_TOOLS"},
+    {"anchor": "mcp_discoverability.py:17", "expect": "EXPECTED_GLITCHTIP_TOOLS"},
+
+    {"anchor": "sentry_incident_bridge.py:36", "expect": "SENTRY_AUTH_TOKEN"},
+    {"anchor": "sentry_incident_bridge.py:190", "expect": "def resolve_token"},
+    {"anchor": "sentry_incident_bridge.py:289", "expect": "Authorization"},
+    {"anchor": "sentry_observability.py:55", "expect": "SENTRY_DSN"},
+
+    {"anchor": "master_parity_gate.py:168", "expect": "def capture_startup_parity"},
+    {"anchor": "master_parity_gate.py:255", "expect": "mutation_safe"},
+    {"anchor": "gitea_mcp_server.py:19105", "expect": "def gitea_assess_master_parity"},
+
+    {"anchor": "gitea_mcp_server.py:193", "expect": "ACTIVE_WORKTREE_ENV"},
+    {"anchor": "gitea_mcp_server.py:194", "expect": "AUTHOR_WORKTREE_ENV"},
+    {"anchor": "gitea_mcp_server.py:2351", "expect": "/tmp/gitea_issue_lock.json"},
+    {"anchor": "gitea_mcp_server.py:10897", "expect": "def gitea_bootstrap_author_issue_worktree"},
+    {"anchor": "mcp_server.py:13", "expect": "/tmp/mcp_server_stderr.log"},
+
+    {"anchor": "issue_lock_store.py:26", "expect": "DEFAULT_LOCK_DIR"},
+    {"anchor": "issue_lock_store.py:83", "expect": "def session_pointer_path"},
+    {"anchor": "issue_lock_store.py:98", "expect": "def is_process_alive"},
+    {"anchor": "mcp_session_state.py:27", "expect": "DEFAULT_STATE_DIR"},
+    {"anchor": "control_plane_db.py:47", "expect": "DEFAULT_DB_PATH"},
+    {"anchor": "control_plane_db.py:380", "expect": "mode=0o700"},
+    {"anchor": "control_plane_db.py:386", "expect": "sqlite3.connect"},
+    {"anchor": "control_plane_db.py:1145", "expect": "os.getpid()"},
+    {"anchor": "gitea_mcp_server.py:12804", "expect": "owner_pid_alive"}
+  ]
+}

docs/remote-mcp/threat-model.md

@@ -0,0 +1,407 @@
+# Remote-MCP threat model, trust boundaries, and service decomposition
+
+What the adversary is, what each boundary protects, and which services may share a process.
+
+- **Issue:** #956 (Remote-MCP threat model), child of epic #929, cross-linked to #955.
+- **Depends on:** #930 (closed) — `docs/remote-mcp/coupling-inventory.md`.
+- **Blocks:** #932, #933, #934, #938.
+- **Generated against commit:** `a143cd065ba06e1a2bdc5143a19ec156e53650ef` (#931's transport
+  bind seam). Originally generated against `aad5c8b42361d380a8eeb07b94b90815e594c2c5`
+  (`master`) and re-anchored when #931 shifted the cited lines.
+- **Scope:** documentation only. This child changes no server behavior. It adds one
+  document, one anchor fixture, and the test that enforces them.
+
+## Relationship to #930
+
+#930 asked *what breaks when the process stops being local*. This document asks *what an
+attacker gets, and where we stop them*. The two are deliberately different axes: #930
+classifies each coupling as portable, seam, replacement, or cannot-be-remote; this document
+classifies each **credential** by blast radius and each **boundary** by what crossing it
+requires. An entry can be perfectly portable and still be a trust disaster —
+`gitea_config.py:851` is portable Python that reads a CI secret from inside the Gitea server.
+
+### Anchors are enforced, not asserted
+
+Every `file:line` in this document is declared in `docs/remote-mcp/threat-model-anchors.json`
+with the substring that must appear at that line, and
+`tests/test_issue_956_threat_model.py` fails if any anchor does not resolve or if the
+document cites an anchor the fixture does not cover.
+
+This guard exists because #930 did not have one. Its inventory was generated at
+`7bf4f125`; by `aad5c8b4` its `gitea_mcp_server.py` anchors had drifted — the transport
+bind it cited at line 23750 now lives at `gitea_mcp_server.py:24728`, and its
+client-managed provenance anchor at 14588 now lands in an unrelated function. Nothing
+failed, because nothing checked. Anchors into a ~24,700-line module rot silently, and a
+security document that cannot prove its own citations is worse than none, because it is
+trusted.
+
+---
+
+## 1. Assets
+
+What an adversary wants. Ordered by consequence, not by likelihood.
+
+| ID | Asset | Why it matters |
+| -- | ----- | -------------- |
+| A1 | Merge authority on `Scaled-Tech-Consulting/Gitea-Tools` | This repository *is* the control plane. Code merged here becomes the gate that authorizes every future mutation, so merge authority is self-amplifying: one merge can disable every other control in this document. |
+| A2 | Write authority on the `mdcps` tenant | A second, unrelated organization reachable from the same configuration. Compromise here is a cross-organization incident, not an internal one. |
+| A3 | The eight Gitea role credentials | Long-lived bearer tokens. Possession is authority; there is no second factor at the API. |
+| A4 | Jenkins read access (`mdcps`, enabled) | Build logs routinely carry deployment topology, internal hostnames, and accidentally-echoed secrets. |
+| A5 | Error-tracking read access (GlitchTip / Sentry) | Event payloads carry stack frames, request context, and production user data. |
+| A6 | Coordination-state integrity | The locks, leases, and review-decision records that make "exactly one owner" true. Corrupting them needs no Gitea credential and produces duplicate or lost work. |
+| A7 | The operator's checkout and worktrees | Unmerged code, branch state, and the filesystem the author tools write to. |
+| A8 | The macOS login keychain | The meta-credential. Everything in A3, A4, and A5 resolves from it. |
+| A9 | Separation of duty between review and merge | The property that no single actor both approves and lands a change. An *asset*, not a control, because it is what the controls exist to produce. |
+| A10 | Audit and provenance records | Determine whether an incident is reconstructable. An attacker who can forge provenance makes an intrusion indistinguishable from normal work. |
+
+## 2. Adversaries
+
+| ID | Adversary | Capability assumed | Not assumed |
+| -- | --------- | ------------------ | ----------- |
+| ADV1 | **Compromised LLM client** | Full control of one MCP client. Issues arbitrary tool calls, in any order, with any arguments, at machine speed. Sees every tool result. | Cannot read the operator's disk except through tools; cannot execute arbitrary local code outside the tool surface. |
+| ADV2 | **Prompt injection** via repository content | Controls text the model reads and treats as instruction — issue bodies, PR descriptions, review comments, commit messages, file contents. Reaches the model on any read of untrusted content. | Holds no credential and issues no call directly. Its entire power is causing an *authorized* client to act. |
+| ADV3 | **Malicious tool arguments** | Supplies hostile values to any parameter — paths, branch names, session identifiers, worktree paths, issue numbers — including traversal, injection, and confusion between look-alike identifiers. | Cannot bypass a gate that actually validates its input. |
+| ADV4 | **Network attacker** | Observes and modifies traffic between client, server, and Gitea. Attempts downgrade, replay, and endpoint impersonation. | Does not hold a valid credential at the start. |
+| ADV5 | **Curious operator** | Legitimate local access to the workstation: process table, `/tmp`, home directory, keychain prompts. Not malicious, but not authorized for every role either. | Does not defeat the OS keychain's own access control without a prompt. |
+
+ADV2 is the adversary this architecture most under-models. Every other adversary must first
+obtain something. Prompt injection obtains nothing: it borrows authority the client already
+holds and is indistinguishable at the tool boundary from legitimate work. Each boundary
+below therefore states whether it constrains ADV2 at all — and most do not, because they
+authenticate the *caller*, not the *intent*.
+
+## 3. Trust boundaries
+
+"Crossing requires today" is what the code actually enforces at
+`a143cd065ba06e1a2bdc5143a19ec156e53650ef`, not what the design intends.
+
+| ID | Boundary | Protects | Crossing requires today | Crossing must require remotely |
+| -- | -------- | -------- | ----------------------- | ------------------------------ |
+| B1 | LLM client ↔ MCP server session | A1, A3, A10 — that a mutating session was established through the sanctioned client path | A single configured bind (`gitea_mcp_server.py:24728`) validated against one closed allowlist (`mcp_daemon_guard.py:49`, `mcp_daemon_guard.py:195`) — since #931 the identifier comes from deployment configuration and defaults to the local transport, so the boundary no longer rests on a literal, but it still rests on the *bind* rather than on an authenticated caller; client-managed provenance (`gitea_mcp_server.py:15415`) or a refusal (`gitea_mcp_server.py:15453`); production transport before recovery-authorization mint (`irrecoverable_provenance.py:497`, consumed at `gitea_mcp_server.py:9132` and `gitea_mcp_server.py:9381`) | An authenticated handshake issuing a server-side session identity bound to a principal, with the transport recorded in provenance. The physical proof (a pipe) must become a cryptographic one. |
+| B2 | Role ↔ role | A9 — that author, reviewer, merger, and reconciler are distinct authorities | **The process boundary only.** The role is a property of the process, read once from `GITEA_MCP_PROFILE` (`gitea_config.py:54`). A caller gets author permissions by connecting to the author process. Review and merge are the operations singled out for extra care (`gitea_config.py:97`) | A per-request principal, so the role follows from the credential presented and cannot be selected by reaching a different endpoint. |
+| B3 | MCP server ↔ credential store | A3, A8 — that only sanctioned code turns a profile into a token | `_keychain_token` shelling out to the login keychain (`gitea_config.py:956`), dispatched by `resolve_token` (`gitea_config.py:974`) with the reference type built at `gitea_config.py:1015`, gated by `assert_keychain_access_allowed` (`mcp_daemon_guard.py:583`). Inline secrets are rejected at config load (`gitea_config.py:294`) | A credential provider keyed by the *request* principal, returning only that principal's credential, with the source recorded and the value never returned. |
+| B4 | MCP server ↔ Gitea | A1, A2 — that only authorized calls reach the forge | A bearer token over TLS. Server-side, nothing distinguishes one role's token from another beyond the account it belongs to | Unchanged at the forge; the endpoint in front of it must refuse unauthenticated and plaintext connections before tool dispatch. |
+| B5 | MCP server ↔ caller's filesystem | A7 — that a tool acts on the *caller's* disk or refuses | Nothing. The server's disk *is* the caller's disk. Worktree bootstrap writes directly (`gitea_mcp_server.py:10897`); the active workspace is process-global (`gitea_mcp_server.py:193`, `gitea_mcp_server.py:194`) | An explicit per-tool classification, enforced at dispatch, refusing filesystem tools over a transport that cannot reach the caller's disk. A green verdict about the wrong disk is the failure to prevent. |
+| B6 | MCP server ↔ coordination state | A6, A9 — mutual exclusion | Local files and a local SQLite database, with liveness judged from the local process table (`issue_lock_store.py:98`), keyed on paths under one user's home (`issue_lock_store.py:26`, `mcp_session_state.py:27`, `control_plane_db.py:47`) and on `os.getpid()` (`control_plane_db.py:1145`, `gitea_mcp_server.py:12804`). A legacy global slot still exists at `gitea_mcp_server.py:2351`, and the session-pointer file is named per PID (`issue_lock_store.py:83`) | One authority per ownership question, with liveness from session identity and expiry, and atomic acquire, renew, and release across hosts. |
+| B7 | Gitea integration ↔ unrelated integrations | A4, A5 — that a Gitea compromise is not a CI and observability compromise | **Nothing.** See §5. The Gitea server reads Jenkins and GlitchTip secrets (`gitea_config.py:851`, reached from `gitea_config.py:837`) and holds the Sentry token (`sentry_incident_bridge.py:190`) | A hard process boundary. This is the boundary #956 exists to create. |
+| B8 | Tenant ↔ tenant (`prgs` / `mdcps` / `local-lab`) | A2 — that one organization's compromise is not another's | Convention. One configuration declares all three contexts; `resolve_service` fails closed on a *disabled* context (`gitea_config.py:704`) but the credentials of enabled ones remain reachable in-process. A per-profile repository scope exists (`gitea_config.py:499`) | Separate deployments, or at minimum per-tenant credential scopes with no process able to resolve both. |
+| B9 | Deployed code ↔ merged policy | A1, A10 — that the running server enforces the rules that were actually merged | Comparing this process's startup commit against this disk (`master_parity_gate.py:168`), conjoined into a single verdict (`master_parity_gate.py:255`) published by `gitea_mcp_server.py:19105` | Freshness defined against the deployed build identity, with an explicit fail-closed verdict when undeterminable. |
+
+### What no boundary constrains
+
+None of B1–B9 constrains **ADV2**. Every one authenticates a caller or a process; prompt
+injection supplies neither. An injected instruction that reaches an authorized author
+session crosses B1, B2, B3, and B5 legitimately, because at each of those boundaries it *is*
+the author. The only controls that bite ADV2 are those constraining what an authenticated
+principal may do regardless of what it asks for — the per-role permission split (B2), the
+repository scope at `gitea_config.py:499`, and separation of duty (A9). Sizing those
+controls correctly matters more after the migration, not less, because a remote endpoint
+raises the number of clients that can be injected into.
+
+## 4. Data flows
+
+Flows that cross a boundary. `==>` carries a credential; `-->` does not.
+
+```
+                          B1                         B4
+  [LLM client] ====================> [MCP server] ========> [Gitea]
+        ^        stdio pipe today          |  ^               (A1,A2)
+        |        session identity          |  |
+        |        after migration           |  |
+        |                                  |  | B3
+   untrusted repository content            |  +======> [macOS login keychain] (A8)
+   read back into the model (ADV2)         |              resolves A3, A4, A5
+        ^                                  |
+        +----------------------------------+
+                                           |
+                  B5                       |  B6
+   [operator checkout / worktrees] <--------+-------> [locks · leases · sqlite]
+              (A7)                         |                  (A6)
+                                           |
+                  B7  <-- boundary does not exist today
+                                           |
+                  +========================+========================+
+                  |                        |                        |
+            [Jenkins] (A4)         [GlitchTip] (A5)          [Sentry] (A5)
+        external MCP server      external MCP server      in-process bridge
+```
+
+Two flows deserve attention because neither is obvious from the code:
+
+1. **The keychain flow fans out.** B3 is drawn once but resolves credentials for *every*
+   configured profile and service, not only the active one. `gitea_list_profiles`
+   (`gitea_mcp_server.py:19261`) reports each profile's credential status by calling
+   `resolve_token` on it (`gitea_mcp_server.py:19312`), and `gitea_audit_config`
+   (`gitea_mcp_server.py:19555`) reports service credential status through
+   `service_summaries` (`gitea_mcp_server.py:19577`).
+2. **The return path is a flow too.** Content read from Gitea travels back into the model
+   and is treated as instruction. This is the ADV2 edge, and it is the only edge in the
+   diagram with no authentication on it, because it is not a request.
+
+## 5. Per-boundary credential inventory
+
+**14 credentials in total.** Blast radius is stated as what the credential yields *on its
+own*, assuming every gate not backed by the credential itself has been bypassed — because
+an attacker holding a token calls the API, not our tools.
+
+| ID | Credential | Holder | Boundary | Blast radius |
+| -- | ---------- | ------ | -------- | ------------ |
+| CR1 | `prgs-author` Gitea token — account `jcwalker3` | macOS keychain; resolved in-process (`gitea_config.py:974`) | B3 → B4 | Create branches, push, commit, open PRs, create/close/comment issues on the control-plane repo. Cannot approve or merge. The one credential whose identity is genuinely distinct. |
+| CR2 | `prgs-reviewer` Gitea token — account `sysadmin` | macOS keychain | B3 → B4 | Approve and request changes. **Shares one Gitea account with CR3, CR4, CR5.** |
+| CR3 | `prgs-merger` Gitea token — account `sysadmin` | macOS keychain | B3 → B4 | Merge to `master` — A1 in full. Same account as CR2. |
+| CR4 | `prgs-reconciler` Gitea token — account `sysadmin` | macOS keychain | B3 → B4 | Close PRs, delete branches, irrecoverable decision-lock recovery. Same account as CR2. |
+| CR5 | `prgs-controller` Gitea token — account `sysadmin` | macOS keychain | B3 → B4 | Same operation set as CR4. Same account as CR2. |
+| CR6 | `mdcps-author` Gitea token — account `913443` | macOS keychain | B3 → B4, B8 | Author operations on a second organization. **Shares one account with CR7 and CR8.** |
+| CR7 | `mdcps-reviewer` Gitea token — account `913443` | macOS keychain | B3 → B4, B8 | Approve and request changes on `mdcps`. Same account as CR6. |
+| CR8 | `mdcps-merger` Gitea token — account `913443` | macOS keychain | B3 → B4, B8 | Merge on `mdcps` — A2 in full. Same account as CR6. |
+| CR9 | MDCPS Jenkins read credential | macOS keychain, read from the Gitea server process (`gitea_config.py:851`) | B7 | Read CI jobs, builds, and logs (A4). Enabled today. |
+| CR10 | MDCPS GlitchTip read credential | macOS keychain, read from the Gitea server process (`gitea_config.py:851`) | B7 | Read error events and their payloads (A5). Enabled today. |
+| CR11 | `SENTRY_AUTH_TOKEN` | Process environment, read in-process (`sentry_incident_bridge.py:36`, `sentry_incident_bridge.py:190`), sent as a bearer header (`sentry_incident_bridge.py:289`) | B7 | Read and reconcile Sentry issues (A5). Not a keychain credential — an env var, so it is inherited by anything the process spawns. |
+| CR12 | `SENTRY_DSN` | Process environment (`sentry_observability.py:55`) | B7 | Write events into the observability project. Low read value, real forgery value: an attacker can inject fabricated events into the record (A10). |
+| CR13 | macOS login keychain access | The operator's login session; gated by `assert_keychain_access_allowed` (`mcp_daemon_guard.py:583`) | B3, ADV5 | **Every other credential in this table except CR11 and CR12.** This is the aggregation point. |
+| CR14 | Coordination-store access (no secret) | Filesystem permissions — `control_plane_db.py:47`, created `0o700` (`control_plane_db.py:380`), opened with a local file lock (`control_plane_db.py:386`) | B6, ADV5 | Full read/write of locks, leases, and decision records (A6). **There is no credential here at all** — anything running as the operator can rewrite ownership. |
+
+### Findings
+
+**Finding 1 — Role separation is not credential separation.** Four `prgs` roles resolve to
+one Gitea account (`sysadmin`): reviewer, merger, reconciler, and controller. A stolen
+reviewer credential *is* a merger credential. A9 — separation of duty between approving and
+landing — is therefore enforced entirely by which local process a call reaches (B2), and not
+at all by the forge. It survives exactly as long as B2 does, and B2 is the boundary the
+migration dissolves.
+
+**Finding 2 — The `mdcps` tenant has no role separation at all.** Author, reviewer, and
+merger all resolve to account `913443`. One credential can open a PR, approve it, and merge
+it. The in-process self-review check compares the authenticated username against the PR
+author and would refuse — but that check runs on our side of B4. It is not a property of
+the credential, and an attacker holding the token does not call our tools.
+
+**Finding 3 — Any one role process can resolve every other role's credential.** This is not
+inferred; it is demonstrated by tool output. `gitea_list_profiles`
+(`gitea_mcp_server.py:19261`) called from the **author** session reports
+`identity_status: "credentials present"` for `prgs-merger`, `prgs-reviewer`,
+`prgs-reconciler`, and every `mdcps` profile, because it calls `resolve_token` on each one
+(`gitea_mcp_server.py:19312`). The author process does not merely *have access to* the
+merger's credential — it reads it to answer a status query. B2 is not a credential boundary
+in either direction.
+
+**Finding 4 — The Gitea server reads CI and observability secrets.** `gitea_audit_config`
+(`gitea_mcp_server.py:19555`) reports `MDCPS Jenkins: enabled, read-only, authenticated`.
+That word `authenticated` is produced by `service_summaries` (`gitea_mcp_server.py:19577`,
+defined at `gitea_config.py:837`), whose default check calls `_keychain_token` on the
+service's own keychain reference (`gitea_config.py:851`). Producing that one line requires
+the Gitea MCP server to read the Jenkins secret and the GlitchTip secret out of the
+keychain. B7 does not exist.
+
+**Finding 5 — Jenkins and GlitchTip are already decomposed; the reach is residual.** Their
+tools live in separately registered servers, marked `external-mcp`
+(`gitea_mcp_server.py:17710`, `gitea_mcp_server.py:17716`, `gitea_mcp_server.py:17737`,
+`gitea_mcp_server.py:17742`) with their own expected tool sets (`mcp_discoverability.py:9`,
+`mcp_discoverability.py:17`). The correct decomposition was already chosen. What remains is
+a leak across it: the credential *references* still live in the Gitea configuration and are
+still resolved by the Gitea process. #75 bundled these services into one control-plane
+umbrella; the tools were separated afterwards, the credentials were not.
+
+**Finding 6 — Sentry is the exception that is not decomposed.** Unlike Jenkins and
+GlitchTip, the Sentry bridge runs *inside* the Gitea server, resolving its token from the
+process environment (`sentry_incident_bridge.py:190`) and sending it as a bearer header
+(`sentry_incident_bridge.py:289`). Being an environment variable rather than a keychain item
+makes it strictly worse: it needs no keychain prompt and is inherited by every subprocess the
+server spawns — including the `ps` invocations at `gitea_mcp_server.py:21465` and
+`gitea_mcp_server.py:21509`, reached from `gitea_mcp_server.py:21445`.
+
+**Finding 7 — The highest-value coordination asset has the weakest gate.** A6 is protected
+by filesystem permissions alone (CR14). Corrupting a lease requires no Gitea credential,
+produces no forge-side audit record, and breaks the mutual exclusion the entire workflow
+assumes. Every other asset costs an attacker a credential; this one costs nothing beyond
+local access, which is exactly ADV5's position.
+
+**Finding 8 — Provenance authenticates the launch, not the caller.** `server_provenance` is
+reported as exactly `client_managed` or `manual_launch` (`gitea_mcp_server.py:19004`),
+derived from environment inspection (`gitea_mcp_server.py:15415`) with the recognized-key
+allowlist at `gitea_config.py:1172` and the generator that emits the marker at
+`gitea_config.py:1233`. Every one of those facts is fixed at process start. A client that is
+trustworthy at launch and compromised a minute later remains `client_managed` for the life
+of the process, and the transport contract that underwrites it is stated as a property of
+the server itself (`mcp_server.py:4`). Since #931 that contract names the configured
+transport rather than asserting stdio, but it is still fixed once, at bind, for the life of
+the process.
+
+## 6. Decomposition ruling
+
+This section is the ruling #956 requires. It is a decision, not a recommendation.
+
+**D1 — No unrelated co-residency.** A single integration process **must not** hold, resolve,
+or be able to resolve credentials for services it does not itself integrate with.
+Concretely: the Gitea MCP service may hold Gitea credentials and nothing else. Jenkins,
+GlitchTip, Sentry, and any database credential are **not permitted** to co-reside with Gitea
+credentials in one process.
+
+*Rationale.* A process is the smallest unit an attacker takes whole. Once ADV1 or ADV2
+controls execution in a process, every credential that process can resolve is theirs, and no
+in-process check helps, because the checks are in the process too. Blast radius is therefore
+a property of the process boundary and nothing finer. Findings 4 and 6 show that today one
+compromise of the Gitea server yields CI read access, error-tracking read access, and — via
+CR13 — every role credential on both tenants. That is the single largest reduction in blast
+radius available anywhere in epic #929, and it costs no new mechanism: the decomposition
+already exists (Finding 5) and is merely leaked across.
+
+**D2 — Separation of duty must be backed by credentials.** Two roles whose separation is a
+security property must not resolve to the same forge account. Specifically, reviewer and
+merger must be distinct accounts. Today they are not, on either tenant (Findings 1 and 2).
+
+*Rationale.* B2 is a process boundary, and the migration's entire purpose is to replace
+process boundaries with request-level ones. A separation enforced only by which process a
+call reaches does not survive that replacement — and it is already bypassable by anyone who
+holds the token and calls the API instead of the tool.
+
+**D3 — Credential resolution is scoped to the request principal.** A session must resolve its
+own credential and must have no path to any other principal's. The resolve-every-profile
+behavior behind `gitea_mcp_server.py:19312` and `gitea_mcp_server.py:19577` must report
+configured-or-not from configuration alone, without resolving the secret.
+
+*Rationale.* Finding 3. An audit surface that proves a credential exists by fetching it is a
+credential-aggregation primitive wearing a diagnostic's clothes.
+
+**D4 — Coordination state is a protected asset with its own authority.** Access to locks,
+leases, and decision records must require an authenticated session, not merely local
+filesystem access.
+
+*Rationale.* Finding 7. #937 already moves this store for concurrency reasons; the
+authorization requirement must land with it, or the store becomes remotely reachable while
+still being authorized by nothing.
+
+### Exceptions
+
+**One, time-boxed.** During the dual-run window defined by #939, the **local** stdio fleet
+may continue to resolve Jenkins and GlitchTip credential *references* from the shared
+configuration, because removing them from the local configuration is not a prerequisite for
+standing up the remote endpoint and would strand the operator's existing local workflow.
+
+This exception is bounded by all of:
+
+- It applies to the local stdio deployment only. The remote endpoint (#938) must be
+  configured with Gitea credentials and no others from its first day.
+- It expires when #939 completes. It does not survive cutover.
+- It does not extend to Sentry: CR11 and CR12 are process-environment credentials in the
+  Gitea server (Finding 6) and must be absent from the remote deployment's environment
+  regardless of dual-run state.
+
+No exception is granted to D2, D3, or D4.
+
+### Consequences for the target architecture
+
+- The remote endpoint serves **Gitea only**. It is not a general control-plane endpoint.
+- Jenkins and GlitchTip keep their existing separate servers, and their credential
+  references move out of the Gitea configuration.
+- The Sentry bridge either moves behind its own service boundary or is absent from the
+  remote deployment. It does not travel with the Gitea server.
+- Reviewer and merger accounts diverge before the endpoint is trusted for merges, or A9 is
+  recorded as unenforced.
+
+## 7. Child-to-boundary mapping
+
+Every #929 child from 2 through 10, mapped to the boundary it implements. A child
+implementing more than one boundary names its primary first.
+
+| Child | Issue | Boundaries | What it must establish | Rulings it must honor |
+| ----: | ----- | ---------- | ---------------------- | --------------------- |
+| 2 | #931 | B1, B9 | The bound transport becomes a validated value that provenance and freshness can both key on. Without it neither B1 nor B9 has an input. | — |
+| 3 | #932 | B2 | The role becomes a property of the request, not the process — the boundary the migration otherwise deletes. | D2, D3 |
+| 4 | #933 | B3, B7 | Credentials come from a provider keyed by principal. This is where D1 and D3 are either enforced or permanently lost. | D1, D3 |
+| 5 | #934 | B1 | Session provenance replaces pipe-and-process-table proof with an authenticated session identity. | — |
+| 6 | #935 | B9 | Freshness redefined against deployed build identity, with an explicit undeterminable verdict. | — |
+| 7 | #936 | B5 | Every tool classified and the filesystem boundary enforced at dispatch, so a tool cannot return green about the wrong disk. | — |
+| 8 | #937 | B6 | One authority per ownership question, with session-identity liveness and atomic transitions. | D4 |
+| 9 | #938 | B4, B1, B8 | The endpoint: authentication, principal binding, transport security, and — critically — the deployed credential set. | D1, D2, D3 |
+| 10 | #939 | B6 | Dual-run with exactly one coordination authority at every instant, and the rollback that proves the way back. | D1 exception expiry |
+
+Boundary coverage: B1 (#931, #934, #938), B2 (#932), B3 (#933), B4 (#938), B5 (#936),
+B6 (#937, #939), B7 (#933), B8 (#938), B9 (#931, #935).
+
+B7 has exactly one owner, #933, and that is deliberate. B7 is not created by standing up an
+endpoint; it is created by deciding which credentials a process may resolve, which is
+precisely what the credential-provider child does.
+
+## 8. Adversarial walkthrough: a fully compromised LLM client
+
+The required negative case. ADV1 holds one MCP client and issues arbitrary tool calls. What
+does it reach at each boundary?
+
+### Before the migration
+
+The client is attached to the local fleet over stdio.
+
+| Boundary | What ADV1 reaches | Stopped by |
+| -------- | ----------------- | ---------- |
+| B1 | Everything the fleet serves. The client *is* the sanctioned launcher: it satisfies the client-managed check (`gitea_mcp_server.py:15415`) by construction, and provenance is never re-verified after launch (Finding 8). | Nothing. The guard authenticates the launch, not the caller. |
+| B2 | All five roles — it is attached to all five namespaces. It can author a PR, approve it from the reviewer namespace, and merge it from the merger namespace. | Only the in-process self-review check, which compares `jcwalker3` (author) against `sysadmin` (reviewer) and **passes**, because Finding 1 made them different accounts while leaving reviewer and merger identical. A9 falls in one sequence of legitimate calls. |
+| B3 | Every credential in CR1–CR10 via CR13, with no additional prompt — the daemon is already sanctioned, so `assert_keychain_access_allowed` (`mcp_daemon_guard.py:583`) returns immediately. | Nothing. |
+| B4 | A1 and A2 in full. | Branch protection at the forge, to the extent configured. |
+| B5 | The operator's checkout and every worktree, through the author tools (`gitea_mcp_server.py:10897`), plus the shared stderr path at `mcp_server.py:13`. | Nothing; the server's disk is the target disk. |
+| B6 | All coordination state — no credential required (CR14). It can forge lease ownership and clear decision locks. | Filesystem permissions, which it already satisfies. |
+| B7 | Jenkins (A4) and GlitchTip (A5) secrets via Finding 4, and CR11/CR12 from its own environment. | Nothing. |
+| B8 | Both tenants. | Nothing in-process; only the disabled-context check (`gitea_config.py:704`), which does not apply to enabled contexts. |
+| B9 | Can it run stale code? Only by advancing the checkout, which parity detects (`master_parity_gate.py:255`). | This gate holds — the one boundary that behaves as designed against ADV1. |
+
+**Result: total.** One compromised client yields A1 through A8 and A10. The only asset with
+real resistance is A1 via branch protection, and the client holds the merger credential
+anyway. Nine boundaries, one meaningful stop.
+
+### After the migration
+
+The same client authenticates to the remote endpoint with one role's credential, assuming
+#931–#939 land **and honor D1–D4**.
+
+| Boundary | What ADV1 reaches | Stopped by |
+| -------- | ----------------- | ---------- |
+| B1 | One authenticated session, bound to one principal. | #934: a forged or expired session identity is refused; the client cannot mint one. |
+| B2 | **One role.** Presenting the author credential yields author permissions only. | #932: the principal comes from the credential, not from which endpoint was reached. |
+| B3 | **One credential — its own.** | #933 with D3: the provider resolves by principal, and no diagnostic resolves the others. |
+| B4 | That role's authority on the forge. | Endpoint authentication (#938); plaintext and unauthenticated attempts refused before dispatch. |
+| B5 | **Nothing.** Filesystem tools are refused over the remote transport with a named blocker. | #936. |
+| B6 | Its own leases; contention resolves to exactly one winner. | #937 with D4: authenticated session required, not filesystem access. |
+| B7 | **Nothing.** No CI or observability credential exists in the process. | D1 — the single largest reduction on this table. |
+| B8 | One tenant. | D1 and #938: the deployment carries one tenant's credentials. |
+| B9 | Cannot induce stale enforcement. | #935: explicit fail-closed verdict, including undeterminable. |
+
+**Result: bounded.** The compromise is contained to one role on one tenant, with no
+filesystem reach and no lateral credential access. A9 survives *only if D2 lands* — if
+reviewer and merger still share `sysadmin`, a compromised reviewer session still merges, and
+this row reads the same after the migration as before it.
+
+### What the migration does not fix
+
+Against **ADV2**, both tables are identical. Prompt injection does not need to cross a
+boundary: it arrives inside an authorized session and asks that session to do what it is
+already permitted to do. Every "stopped by" above authenticates a principal, and the
+injected instruction has the correct principal. The migration reduces ADV1's blast radius by
+roughly an order of magnitude and reduces ADV2's by nothing.
+
+The controls that do constrain ADV2 are per-principal permission scope (#932), repository
+scope (`gitea_config.py:499`), and credential-backed separation of duty (D2) — each limiting
+what an authenticated session may do *regardless of what it is asked for*. #955's
+secure-isolation end state should be read with that distinction in mind: removing credentials
+from clients defeats ADV1 and ADV5, and does not by itself defeat ADV2.
+
+Two further items are explicitly out of scope here and unowned by #929:
+
+- **Session-credential rotation and revocation.** #938 names rotation as documentation, but
+  no child owns proving that a revoked credential stops an in-flight session.
+- **ADV3** (malicious tool arguments) is diffused across every child rather than owned. The
+  per-request principal work in #932 is the natural place to assert that identifiers taken
+  from the request never authorize anything on their own.
+
+## 9. How to verify this document
+
+1. `PYTHONPATH=. pytest tests/test_issue_956_threat_model.py` — resolves every anchor
+   against the working tree and checks the document's structural obligations.
+2. Pick any five anchors at random and read them; the fixture states what each line must
+   contain.
+3. Reproduce Findings 3 and 4 live: call `gitea_list_profiles` and `gitea_audit_config`
+   from the **author** namespace. Credential presence reported for roles other than the
+   active one is Finding 3; `MDCPS Jenkins: enabled, read-only, authenticated` is Finding 4.
+
+If the anchor test fails after an unrelated refactor, the anchors moved and the fixture
+needs regenerating — the claims are still true, but they are no longer traceable, which
+#956 treats as the same defect.

gitea_mcp_server.py

@@ -1,7 +1,10 @@
 #!/usr/bin/env python3
 """Gitea MCP Server — exposes Gitea operations as MCP tools.
 
-Runs over stdio. All tools authenticate via macOS keychain (git credential fill).
+The transport is selected by deployment configuration (GITEA_MCP_TRANSPORT) and
+defaults to the local client-spawned transport when unset (#931); the permitted
+set lives in mcp_transport_config. All tools authenticate via macOS keychain
+(git credential fill).
 
 Usage (standalone test):
     python3 mcp_server.py
@@ -2110,6 +2113,8 @@ import issue_lock_store  # noqa: E402
 import issue_lock_adoption  # noqa: E402
 import issue_lock_recovery  # noqa: E402
 import issue_lock_renewal  # noqa: E402
+import author_lock_contract  # noqa: E402
+import bootstrap_lock_recovery  # noqa: E402
 import dirty_orphan_worktree_recovery  # noqa: E402  # #860 dirty orphan recovery
 import dirty_same_claimant_session_rebind  # noqa: E402  # #864
 import stacked_pr_support  # noqa: E402
@@ -2658,33 +2663,17 @@ def _build_author_issue_work_lease(
     worktree_path: str,
     host: str | None,
 ) -> dict:
-    created = _work_lease_now()
+    # #953: the lease shape now lives in author_lock_contract so that bootstrap
-    # #790 Slice A: the window comes from the central policy, not a literal here.
+    # and gitea_lock_issue cannot drift apart again. The policy-derived sliding
-    # It is also now a *sliding* window — the lease lives ``initial_ttl_minutes``
+    # TTL (#790 Slice A) and the task-session ownership key (#790 AC-N1) are
-    # past its last valid heartbeat rather than a fixed four hours past its
+    # unchanged — they simply have one definition instead of two.
-    # creation, so an abandoned task stops holding the claim within one TTL.
+    return author_lock_contract.build_author_issue_work_lease(
-    policy = lease_policy.policy_for(lease_policy.TASK_CLASS_AUTHOR_ISSUE_WORK)
+        issue_number=issue_number,
-    expires = created + timedelta(minutes=policy.initial_ttl_minutes)
+        branch_name=branch_name,
-    return {
+        worktree_path=worktree_path,
-        "operation_type": AUTHOR_ISSUE_WORK_LEASE,
+        claimant=_work_lease_claimant(host),
-        "issue_number": issue_number,
+        created=_work_lease_now(),
-        "pr_number": None,
+    )
-        "branch": branch_name,
-        "worktree_path": worktree_path,
-        "claimant": _work_lease_claimant(host),
-        "created_at": _work_lease_timestamp(created),
-        "expires_at": _work_lease_timestamp(expires),
-        "last_heartbeat_at": _work_lease_timestamp(created),
-        # #790 AC-N1: the ownership key for this task. Distinct from the recorded
-        # PID, which is the shared daemon and identifies no individual task.
-        "task_session_id": issue_lock_store.mint_task_session_id(
-            AUTHOR_ISSUE_WORK_LEASE
-        ),
-        # #790 AC-N8: the explicit lifecycle marker. Its absence — never a
-        # timestamp comparison — is what makes a lock legacy.
-        "lifecycle_version": lease_policy.LIFECYCLE_HEARTBEAT_V1,
-        "heartbeat_count": 1,
-    }
 
 
 def _active_work_lease_block(
@@ -4954,6 +4943,370 @@ def gitea_heartbeat_issue_lock(
     return outcome
 
 
+def _observe_recovery_worktree(worktree_path: str) -> dict:
+    """Observe head, branch, existence, and registration for lock recovery.
+
+    Read-only: it runs ``git`` queries and touches nothing. Kept separate from
+    the decision so the decision stays a pure function of observations (#953).
+    """
+    observation = {
+        "worktree_exists": os.path.isdir(worktree_path),
+        "worktree_registered": False,
+        "current_branch": "",
+        "observed_head": "",
+    }
+    if not observation["worktree_exists"]:
+        return observation
+    try:
+        observation["current_branch"] = subprocess.run(
+            ["git", "-C", worktree_path, "rev-parse", "--abbrev-ref", "HEAD"],
+            capture_output=True,
+            text=True,
+            check=False,
+        ).stdout.strip()
+        observation["observed_head"] = subprocess.run(
+            ["git", "-C", worktree_path, "rev-parse", "HEAD"],
+            capture_output=True,
+            text=True,
+            check=False,
+        ).stdout.strip()
+        listing = subprocess.run(
+            ["git", "-C", worktree_path, "worktree", "list", "--porcelain"],
+            capture_output=True,
+            text=True,
+            check=False,
+        ).stdout
+        real = os.path.realpath(worktree_path)
+        observation["worktree_registered"] = any(
+            os.path.realpath(line.split(" ", 1)[1].strip()) == real
+            for line in listing.splitlines()
+            if line.startswith("worktree ")
+        )
+    except Exception:  # fail closed: unobservable is not provable
+        return observation
+    return observation
+
+
+@mcp.tool()
+def gitea_inspect_issue_lock_contract(
+    issue_number: int,
+    branch_name: str | None = None,
+    worktree_path: str | None = None,
+    remote: str = "dadeschools",
+    host: str | None = None,
+    org: str | None = None,
+    repo: str | None = None,
+) -> dict:
+    """Inspect a durable author issue lock against the canonical contract (#953 AC8/AC16).
+
+    Strictly read-only. It performs no lock, lease, branch, worktree, issue, or
+    pull-request mutation of any kind — it reads the durable lock record and
+    reports. Use it to find out *why* a lock is being refused before choosing a
+    recovery path, and to confirm afterwards that recovery produced a canonical
+    lock.
+
+    Reports which canonical fields are missing, where the claimant is recorded
+    (``work_lease`` is canonical, top level is the legacy/bootstrap placement),
+    whether an expiration is actually recorded — as opposed to absent, which
+    used to masquerade as "not yet expired" — whether the lock can be
+    heartbeated, and whether it satisfies the untouched #447 create-PR
+    provenance guard.
+
+    Args:
+        issue_number: The issue whose lock to inspect.
+        branch_name: Optional; when given, the recovery eligibility preview is
+            evaluated against this branch.
+        worktree_path: Optional; when given, the recovery eligibility preview is
+            evaluated against this worktree.
+        remote: Known instance — 'dadeschools' or 'prgs'.
+        host: Override the Gitea host.
+        org: Override the owner/organization.
+        repo: Override the repository name.
+
+    Returns:
+        dict with 'success', 'lock_present', 'lock_contract' (the structural
+        verdict), 'recommended_action', and — when branch_name and
+        worktree_path are supplied — a non-mutating 'recovery_preview'.
+    """
+    blocked = _profile_permission_block(
+        "gitea.read",
+        issue_number=issue_number,
+        remote=remote,
+        host=host,
+        org=org,
+        repo=repo,
+        org_explicit=org is not None,
+        repo_explicit=repo is not None,
+    )
+    if blocked:
+        return blocked
+
+    h, o, r = _resolve(remote, host, org, repo)
+    existing = _load_existing_issue_lock(
+        remote=remote, org=o, repo=r, issue_number=issue_number
+    )
+    contract = author_lock_contract.assess_lock_contract(existing)
+    result = {
+        "success": True,
+        "performed": False,
+        "mutation_performed": False,
+        "read_only": True,
+        "issue_number": issue_number,
+        "lock_present": bool(existing),
+        "lock_contract": contract,
+        "lock_freshness": (
+            issue_lock_store.assess_lock_freshness(dict(existing))
+            if existing
+            else {"status": issue_lock_store.STATUS_ABSENT, "live": False}
+        ),
+        "recommended_action": author_lock_contract.recommended_action(contract),
+    }
+
+    if branch_name and worktree_path:
+        resolved = issue_lock_worktree.resolve_author_worktree_path(
+            worktree_path, _canonical_local_git_root()
+        )
+        observation = _observe_recovery_worktree(resolved)
+        claimant = _work_lease_claimant(h)
+        result["recovery_preview"] = bootstrap_lock_recovery.assess_bootstrap_lock_recovery(
+            existing,
+            issue_number=issue_number,
+            branch_name=branch_name,
+            worktree_path=resolved,
+            remote=remote,
+            org=o,
+            repo=r,
+            identity=claimant.get("username"),
+            profile=claimant.get("profile"),
+            observed_head=observation["observed_head"],
+            declared_head=None,
+            worktree_exists=observation["worktree_exists"],
+            worktree_registered=observation["worktree_registered"],
+            current_branch=observation["current_branch"],
+        )
+    return result
+
+
+@mcp.tool()
+def gitea_recover_incomplete_bootstrap_lock(
+    issue_number: int,
+    branch_name: str,
+    worktree_path: str,
+    expected_head: str,
+    remote: str = "dadeschools",
+    host: str | None = None,
+    org: str | None = None,
+    repo: str | None = None,
+    dry_run: bool = False,
+) -> dict:
+    """Upgrade an incomplete bootstrap issue lock to the canonical contract (#953 AC8-AC11).
+
+    Explicit, target-specific recovery. It does **not** widen
+    ``gitea_lock_issue``, and it is not a takeover path.
+
+    The state it repairs: ``gitea_bootstrap_author_issue_worktree`` reported
+    success but wrote a lock with the claimant at the top level, no
+    ``work_lease``, no ``lock_provenance``, and no expiry. The author then
+    implemented, committed, and pushed — following bootstrap's own reported next
+    action — after which heartbeat, re-lock, exact-owner renewal, and the #447
+    create-PR guard all refuse simultaneously.
+
+    Deliberate non-behaviours: the branch is never moved, reset, or rewound, and
+    base-equivalence is never required — preserving the already-committed and
+    pushed work is the entire point. Nothing is pushed and no pull request is
+    created. Only the single lock file for this exact (remote, org, repo, issue)
+    is written.
+
+    Ownership is proven, never asserted. The claimant recorded on the durable
+    lock must match **both** the server-resolved identity and the active
+    profile; a matching username alone is refused. Repository, issue, branch,
+    worktree, registration, current branch, and head are all verified before any
+    write, and the declared ``expected_head`` must equal the observed head. A
+    healthy foreign-owned lock is refused outright. Provenance and authorization
+    are minted server-side — there is no parameter through which a caller can
+    supply either.
+
+    Args:
+        issue_number: The issue whose incomplete lock is being recovered.
+        branch_name: The branch recorded on the lock; must match.
+        worktree_path: The registered worktree recorded on the lock; must match.
+        expected_head: Full SHA the caller believes the worktree is at. A
+            mismatch fails closed, so a worktree that moved underneath the
+            caller cannot be recovered against stale evidence.
+        remote: Known instance — 'dadeschools' or 'prgs'.
+        host: Override the Gitea host.
+        org: Override the owner/organization.
+        repo: Override the repository name.
+        dry_run: Report the decision and evidence, mutate nothing.
+
+    Returns:
+        dict with 'success', 'performed', the resulting canonical
+        'lock_contract' and 'work_lease', the auditable
+        'bootstrap_lock_recovery' transition record, and 'exact_next_action'; on
+        refusal 'success'/'performed' False with 'refusal_code' and 'reasons'
+        naming exactly which evidence was missing, and no write performed.
+    """
+    task = "recover_incomplete_bootstrap_lock"
+    ok, block_reasons = role_session_router.check_author_mutation_after_reviewer_stop(
+        task
+    )
+    if not ok:
+        return _author_mutation_block(block_reasons)
+
+    # #953 F1: the namespace/session wall every author state-creating mutation
+    # carries, and which this tool — the structural neighbour of
+    # gitea_recover_dirty_orphaned_issue_worktree, writing the same durable
+    # lock — was the only one to omit. Exact-owner claimant matching inside
+    # assess_bootstrap_lock_recovery is a later layer, not a substitute: it
+    # refuses one commit too late and leaves no BLOCKED audit record of the
+    # attempt. author_role_exclusive is required here because this task is gated
+    # on gitea.issue.comment, which merger, controller, and reconciler profiles
+    # also hold.
+    blocked = _namespace_mutation_block(
+        task, remote=remote, author_role_exclusive=True
+    )
+    if blocked:
+        return blocked
+
+    blocked = _profile_permission_block(
+        task_capability_map.required_permission(task),
+        issue_number=issue_number,
+        remote=remote,
+        host=host,
+        org=org,
+        repo=repo,
+        org_explicit=org is not None,
+        repo_explicit=repo is not None,
+    )
+    if blocked:
+        return blocked
+
+    h, o, r = _resolve(remote, host, org, repo)
+    resolved_worktree = issue_lock_worktree.resolve_author_worktree_path(
+        worktree_path, _canonical_local_git_root()
+    )
+    existing = _load_existing_issue_lock(
+        remote=remote, org=o, repo=r, issue_number=issue_number
+    )
+    observation = _observe_recovery_worktree(resolved_worktree)
+
+    # The claimant pair is resolved server-side from the live session; the
+    # caller cannot influence which identity or profile recovery compares
+    # against.
+    claimant = _work_lease_claimant(h)
+    assessment = bootstrap_lock_recovery.assess_bootstrap_lock_recovery(
+        existing,
+        issue_number=issue_number,
+        branch_name=branch_name,
+        worktree_path=resolved_worktree,
+        remote=remote,
+        org=o,
+        repo=r,
+        identity=claimant.get("username"),
+        profile=claimant.get("profile"),
+        observed_head=observation["observed_head"],
+        declared_head=expected_head,
+        worktree_exists=observation["worktree_exists"],
+        worktree_registered=observation["worktree_registered"],
+        current_branch=observation["current_branch"],
+    )
+
+    if not assessment["recovery_sanctioned"]:
+        return {
+            "success": False,
+            "performed": False,
+            "mutation_performed": False,
+            "issue_number": issue_number,
+            "refusal_code": assessment["refusal_code"],
+            "reasons": assessment["reasons"],
+            "message": bootstrap_lock_recovery.format_recovery_refusal(assessment),
+            "lock_contract": assessment["contract"],
+            "evidence": assessment["evidence"],
+        }
+
+    if dry_run:
+        return {
+            "success": True,
+            "performed": False,
+            "mutation_performed": False,
+            "dry_run": True,
+            "issue_number": issue_number,
+            "would_recover": True,
+            "lock_contract": assessment["contract"],
+            "evidence": assessment["evidence"],
+            "exact_next_action": (
+                "Re-run without dry_run=True to upgrade this lock to the "
+                "canonical contract."
+            ),
+        }
+
+    recovered = author_lock_contract.build_canonical_issue_lock(
+        issue_number=issue_number,
+        branch_name=branch_name,
+        worktree_path=resolved_worktree,
+        remote=remote,
+        org=o,
+        repo=r,
+        identity=claimant.get("username"),
+        profile=claimant.get("profile"),
+        tool="gitea_recover_incomplete_bootstrap_lock",
+        source=issue_lock_provenance.SOURCE_LOCK_ISSUE,
+        owner_session=(existing or {}).get("owner_session"),
+        expected_base_sha=(existing or {}).get("expected_base_sha"),
+    )
+    # AC10: preserve both sides of the transition so a recovered lock never
+    # reads as an original claim.
+    recovered["bootstrap_lock_recovery"] = bootstrap_lock_recovery.build_recovery_record(
+        assessment,
+        recovered_at=_work_lease_timestamp(_work_lease_now()),
+        new_task_session_id=recovered["work_lease"]["task_session_id"],
+    )
+
+    try:
+        lock_path = issue_lock_store.bind_session_lock(
+            recovered,
+            expected_generation=assessment["expected_generation"],
+            recovery_sanctioned=True,
+        )
+    except Exception as exc:
+        return {
+            "success": False,
+            "performed": False,
+            "mutation_performed": False,
+            "issue_number": issue_number,
+            "refusal_code": "lock_write_failed",
+            "reasons": [str(exc)],
+            "message": f"Recovered lock could not be persisted: {exc} (fail closed)",
+        }
+
+    written = issue_lock_store.read_lock_file(lock_path)
+    contract = author_lock_contract.assess_lock_contract(written)
+    return {
+        "success": True,
+        "performed": True,
+        "mutation_performed": True,
+        "issue_number": issue_number,
+        "branch_name": branch_name,
+        "worktree_path": resolved_worktree,
+        "lock_file_path": lock_path,
+        "lock_contract": contract,
+        "work_lease": (written or {}).get("work_lease"),
+        "task_session_id": contract["task_session_id"],
+        "lock_generation": (written or {}).get("lock_generation"),
+        "prior_generation": assessment["expected_generation"],
+        "bootstrap_lock_recovery": (written or {}).get("bootstrap_lock_recovery"),
+        "preserved_head": observation["observed_head"],
+        "branch_reset": False,
+        "pushed": False,
+        "pr_created": False,
+        "exact_next_action": (
+            "Lock is canonical. Heartbeat it with the returned task_session_id, "
+            "then continue the author workflow; publish and create the pull "
+            "request through the normal sanctioned calls."
+        ),
+    }
+
+
 @mcp.tool()
 def gitea_recover_dirty_orphaned_issue_worktree(
     issue_number: int,
@@ -15155,8 +15508,21 @@ def _profile_permission_block(required_operation: str, **extra_fields) -> dict |
     )
 
 
-def _namespace_mutation_block(mutation_task: str, **extra_fields) -> dict | None:
+def _namespace_mutation_block(
-    """Reviewer/author namespace alignment gate (#209)."""
+    mutation_task: str,
+    *,
+    author_role_exclusive: bool = False,
+    **extra_fields,
+) -> dict | None:
+    """Reviewer/author namespace alignment gate (#209).
+
+    ``author_role_exclusive`` additionally requires the active profile's derived
+    role kind to be exactly ``author`` (#953 F1). Off by default, so the six
+    pre-existing call sites are unchanged. Tools whose required permission is
+    ``gitea.issue.comment`` — which every configured role holds — opt in, since
+    the reviewer-namespace check alone would let a merger, controller, or
+    reconciler session through to a durable author lock write.
+    """
     required_permission = task_capability_map.required_permission(mutation_task)
     required_role = task_capability_map.required_role(mutation_task)
     # #714: evaluate active profile only — never auto-switch.
@@ -15178,6 +15544,9 @@ def _namespace_mutation_block(mutation_task: str, **extra_fields) -> dict | None
         }
     ok, reasons = role_namespace_gate.check_author_mutation_namespace(
         mutation_task, profile)
+    if ok and author_role_exclusive:
+        ok, reasons = role_namespace_gate.check_author_role_kind(
+            mutation_task, profile)
     if ok:
         return None
     blocked = {
@@ -24352,7 +24721,11 @@ if __name__ == "__main__":
     # basename-only stack frames, and import-only launch cannot reconstruct
     # native transport; offline imports / standalone scripts fail closed.
     mcp_daemon_guard.mark_sanctioned_daemon()
-    mcp_daemon_guard.bind_native_mcp_transport(transport="stdio")
+    # #931: the transport is no longer a literal here. It comes from deployment
+    # configuration (GITEA_MCP_TRANSPORT), defaults to stdio when unset, and is
+    # validated against the single permitted set in mcp_transport_config. An
+    # unregistered identifier raises here, before any tool can dispatch.
+    mcp_daemon_guard.bind_native_mcp_transport()
     # Lock this session's launch profile into the environment so child CLI
     # processes (e.g. review_pr.py) can detect and refuse profile
     # side-channel overrides (#199).
@@ -24370,4 +24743,11 @@ if __name__ == "__main__":
     sys.stderr.write(
         f"--- Sentry observability: {_sentry_status.get('reason')} ---\n"
     )
-    mcp.run(transport="stdio")
+    # #931: serve over exactly the transport that was bound and pinned, and only
+    # if this entrypoint is commissioned to execute it. Recognition is not
+    # execution authorization (review 635): a registered remote identifier is
+    # bound, pinned and recorded, but serving it would start a listener with no
+    # authentication or per-request principal, which #938 owns. An absent bind
+    # keeps its pre-existing #695 failure; an uncommissioned transport fails
+    # closed here, before any listener exists and before any tool can dispatch.
+    mcp.run(transport=mcp_daemon_guard.authorize_transport_execution("tool service"))

irrecoverable_provenance.py

@@ -500,6 +500,11 @@ def assess_transport_for_auth_mint() -> dict[str, Any]:
     native = mcp_daemon_guard.is_native_mcp_transport()
     pytest = mcp_daemon_guard.is_pytest_runtime()
     production = mcp_daemon_guard.is_production_native_mcp_transport()
+    # #931: report which transport underwrites the verdict, read through the
+    # one shared accessor rather than assumed to be stdio. The gate's decision
+    # is unchanged here; naming the transport is what lets #932 re-derive the
+    # guarantee from an authenticated session instead of from the bind.
+    bound = mcp_daemon_guard.bound_transport()
     if not native and not pytest:
         reasons.append(
             "irrecoverable provenance authorization requires production native "
@@ -510,6 +515,7 @@ def assess_transport_for_auth_mint() -> dict[str, Any]:
         "allowed": not reasons,
         "native_mcp_transport": native,
         "production_native_mcp_transport": production,
+        "bound_transport": bound,
         "pytest": pytest,
         "reasons": reasons,
     }

issue_lock_store.py

@@ -299,9 +299,13 @@ def _ownership_refusals(
             f"lock worktree '{lock.get('worktree_path')}' does not match "
             f"'{worktree_path}'"
         )
-    lease = lock.get("work_lease") if isinstance(lock, dict) else None
+    # #953 AC2/AC13/AC14: read through the shared claimant reader so a lock
-    claimant = lease.get("claimant") if isinstance(lease, dict) else None
+    # written by bootstrap — which records the claimant at the top level — is
-    claimant = claimant if isinstance(claimant, dict) else {}
+    # not refused for "not recording a claimant" when it plainly records one.
+    # This is not a widening: the values are still compared against the
+    # server-resolved identity and profile immediately below, so a legacy
+    # placement grants nothing that the canonical placement would not.
+    claimant = lock_claimant(lock) if isinstance(lock, dict) else {}
     recorded_identity = str(claimant.get("username") or "").strip()
     recorded_profile = str(claimant.get("profile") or "").strip()
     if not recorded_identity or not recorded_profile:
@@ -636,6 +640,99 @@ def iter_lock_files(lock_dir: str | None = None) -> list[str]:
     return sorted(paths)
 
 
+def release_session_lock(
+    *,
+    issue_number: int,
+    session: str,
+    lock_dir: str | None = None,
+    remote: str | None = None,
+    org: str | None = None,
+    repo: str | None = None,
+) -> str:
+    """Remove exactly the durable lock *session* created for *issue_number*.
+
+    ``author_issue_bootstrap.run_compensating_recovery`` has called this name
+    since #850, but it was never defined: the call raised ``AttributeError``
+    into a bare ``except Exception: pass``, so the lock half of every
+    compensating rollback silently did nothing. The branch and worktree were
+    removed and the lock was left behind — a state no sanctioned tool can act
+    on, since recovery refuses ``worktree_invalid`` and ``gitea_lock_issue`` has
+    no worktree to bind (#953 review 632 F2).
+
+    Ownership is proven, not asserted. A record is removed only when its
+    recorded ``owner_session`` equals *session* and its issue number matches;
+    ``remote``/``org``/``repo`` narrow it further when supplied. Zero matches or
+    more than one both raise, so a caller can never delete a lock it does not
+    own and an ambiguous directory is never guessed at. The ``.json.lock`` flock
+    sidecar is deliberately left in place — it is a zero-byte mutex another
+    process may hold, and removing it under contention would be a race.
+
+    Returns the removed lock file path.
+    """
+    target_issue = int(issue_number)
+    owner = str(session or "").strip()
+    if not owner:
+        raise ValueError(
+            "release_session_lock requires the owning session id (fail closed)"
+        )
+
+    def _is_owned_durable_lock(record: dict[str, Any] | None) -> bool:
+        # A durable lock, not a bootstrap phase journal or a session pointer,
+        # both of which can share a directory and carry the same issue number
+        # and owner_session.
+        if not record or "lock_generation" not in record:
+            return False
+        if not str(record.get("branch_name") or "").strip():
+            return False
+        if not str(record.get("worktree_path") or "").strip():
+            return False
+        try:
+            if int(record.get("issue_number") or 0) != target_issue:
+                return False
+        except (TypeError, ValueError):
+            return False
+        return str(record.get("owner_session") or "").strip() == owner
+
+    # Prefer the exact keyed path when the caller knows the repository; scanning
+    # is the fallback for callers that only carry the issue number.
+    if remote and org and repo:
+        exact = lock_file_path(
+            remote=remote,
+            org=org,
+            repo=repo,
+            issue_number=target_issue,
+            lock_dir=lock_dir,
+        )
+        if not _is_owned_durable_lock(read_lock_file(exact)):
+            raise FileNotFoundError(
+                f"durable issue lock '{exact}' is absent or is not owned by "
+                f"session '{owner}' (fail closed; nothing released)"
+            )
+        os.remove(exact)
+        return exact
+
+    matches: list[str] = []
+    for path in iter_lock_files(lock_dir):
+        if _is_owned_durable_lock(read_lock_file(path)):
+            matches.append(path)
+
+    if not matches:
+        raise FileNotFoundError(
+            f"no durable issue lock for issue #{target_issue} is owned by "
+            f"session '{owner}' (fail closed; nothing released)"
+        )
+    if len(matches) > 1:
+        raise RuntimeError(
+            f"{len(matches)} durable locks for issue #{target_issue} claim "
+            f"session '{owner}'; refusing to guess which to release "
+            "(fail closed)"
+        )
+
+    path = matches[0]
+    os.remove(path)
+    return path
+
+
 def find_lock_for_branch(
     *,
     remote: str,
@@ -1112,21 +1209,43 @@ def assess_same_issue_lease_conflict(
     )
 
 
-def _lock_claimant(lock: dict[str, Any] | None) -> dict[str, str]:
+def lock_claimant(lock: dict[str, Any] | None) -> dict[str, str]:
+    """Read the claimant from either canonical or legacy placement (#953 AC13/AC14).
+
+    ``work_lease.claimant`` is the canonical placement and is preferred; a
+    top-level ``claimant`` is the legacy/bootstrap placement and is accepted as
+    a fallback. This is the single definition. Before #953 the readers
+    disagreed: this module, ``issue_lock_renewal``, and ``issue_lock_recovery``
+    tolerated both placements, while ``_ownership_refusals`` looked only in
+    ``work_lease`` — which is what made a bootstrap-written lock
+    un-heartbeatable.
+
+    Preferring ``work_lease`` over the top level is deliberate: once a legacy
+    lock is upgraded, the canonical placement is authoritative and a stale
+    top-level copy must never win.
+
+    This decides *where to look*, never whether ownership is proven — every
+    caller still compares these values against server-resolved identity and
+    profile.
+    """
     if not isinstance(lock, dict):
         return {}
-    claimant = lock.get("claimant")
-    if not isinstance(claimant, dict):
     lease = lock.get("work_lease")
     claimant = lease.get("claimant") if isinstance(lease, dict) else None
+    if not isinstance(claimant, dict):
+        claimant = lock.get("claimant")
     if not isinstance(claimant, dict):
         return {}
     return {
-        "username": str(claimant.get("username") or ""),
+        "username": str(claimant.get("username") or "").strip(),
-        "profile": str(claimant.get("profile") or ""),
+        "profile": str(claimant.get("profile") or "").strip(),
     }
 
 
+#: Back-compatible alias for the pre-#953 private name.
+_lock_claimant = lock_claimant
+
+
 def assess_foreign_lock_overwrite(
     existing_lock: dict[str, Any] | None,
     incoming_lock: dict[str, Any],

mcp_daemon_guard.py

@@ -32,6 +32,8 @@ import time
 from pathlib import Path
 from typing import Any
 
+import mcp_transport_config
+
 SANCTIONED_DAEMON_ENV = "GITEA_MCP_SANCTIONED_DAEMON"
 ALLOW_DIRECT_IMPORT_ENV = "GITEA_ALLOW_DIRECT_MCP_IMPORT"
 ALLOW_KEYCHAIN_CLI_ENV = "GITEA_ALLOW_KEYCHAIN_CLI"
@@ -42,7 +44,9 @@ FORCE_PROVENANCE_FAIL_ENV = "GITEA_TEST_FORCE_UNSANCTIONED"
 _NATIVE_RUNTIME: dict[str, Any] | None = None
 
 # Production transport identifiers accepted by bind_native_mcp_transport.
-_PRODUCTION_TRANSPORTS = frozenset({"stdio"})
+# #931: the permitted set is defined once, in mcp_transport_config. This name
+# is kept as an alias so the guard never restates a transport identifier.
+_PRODUCTION_TRANSPORTS = mcp_transport_config.SUPPORTED_TRANSPORTS
 _RUNTIME_MODE_PRODUCTION = "production"
 _RUNTIME_MODE_TEST = "test"
 _PHASE_ENTRYPOINT_CLAIMED = "entrypoint_claimed"
@@ -58,6 +62,23 @@ class UnsanctionedRuntimeError(RuntimeError):
     """Raised when mutation/credential code runs outside a native MCP daemon."""
 
 
+class TransportExecutionError(UnsanctionedRuntimeError):
+    """Raised when a bound transport may not be served by this entrypoint (#931).
+
+    Subclasses :class:`UnsanctionedRuntimeError` so every existing fail-closed
+    handler still catches it, while letting a caller that cares distinguish
+    "nothing is bound" from "something valid is bound but its listener has not
+    been commissioned". Carries the structured verdict on ``.assessment``.
+    """
+
+    def __init__(self, message: str, assessment: dict[str, Any] | None = None):
+        super().__init__(message)
+        self.assessment = assessment or {}
+        self.blocker_kind = self.assessment.get("blocker_kind")
+        self.owner_issue = self.assessment.get("owner_issue")
+        self.transport = self.assessment.get("transport")
+
+
 def is_pytest_runtime() -> bool:
     if (os.environ.get(FORCE_PROVENANCE_FAIL_ENV) or "").strip() in {
         "1",
@@ -171,17 +192,40 @@ def mark_sanctioned_daemon() -> dict[str, Any]:
     return native_runtime_status()
 
 
-def bind_native_mcp_transport(*, transport: str) -> dict[str, Any]:
+def bind_native_mcp_transport(*, transport: str | None = None) -> dict[str, Any]:
-    """Bind the live native MCP transport lifecycle (#695).
+    """Bind the live native MCP transport lifecycle (#695 / #931).
 
     Must be called from the resolved canonical entrypoint immediately before
-    the real MCP server transport loop (e.g. ``mcp.run(transport=\"stdio\")``).
+    the real MCP server transport loop (``mcp.run``). Requires a prior
-    Requires a prior successful :func:`mark_sanctioned_daemon` claim in this
+    successful :func:`mark_sanctioned_daemon` claim in this process.
-    process. Import-only or offline launch without this bind leaves
+    Import-only or offline launch without this bind leaves
     :func:`is_native_mcp_transport` false.
+
+    #931: ``transport`` is now optional. Omitting it — which is what the
+    production entrypoint does — resolves the identifier from deployment
+    configuration via :func:`mcp_transport_config.resolve_configured_transport`,
+    yielding :data:`mcp_transport_config.DEFAULT_TRANSPORT` when nothing is
+    configured. An explicit argument remains supported for tests and for a
+    launcher that has already resolved the value. Either way the identifier is
+    validated against the single permitted set before the runtime record is
+    written, so no tool can dispatch over an unregistered transport.
+
+    The resolved value is pinned into the process-local record and is read back
+    only through :func:`bound_transport`. Rebinding to a different transport is
+    refused, so two guards can never observe different values in one process.
     """
     global _NATIVE_RUNTIME
-    transport_name = (transport or "").strip().lower()
+    if transport is None:
+        resolution = mcp_transport_config.resolve_configured_transport()
+        transport_name = str(resolution["transport"])
+        if not resolution["supported"]:
+            raise UnsanctionedRuntimeError(
+                "bind_native_mcp_transport rejected: "
+                + "; ".join(resolution["reasons"])
+                + " No tool is served over an unregistered transport."
+            )
+    else:
+        transport_name = mcp_transport_config.normalize_transport(transport)
         if transport_name not in _PRODUCTION_TRANSPORTS:
             raise UnsanctionedRuntimeError(
                 f"bind_native_mcp_transport rejected: transport {transport!r} is "
@@ -216,6 +260,23 @@ def bind_native_mcp_transport(*, transport: str) -> dict[str, Any]:
             "between mark and bind (#695)."
         )
 
+    # #931: one process binds one transport. Re-binding the same identifier is
+    # idempotent (a retried launch step must not fail); re-binding a different
+    # one is refused, because a guard that already read the first value would
+    # otherwise disagree with a guard that reads the second.
+    already_bound = (_NATIVE_RUNTIME.get("transport") or "").strip()
+    if (
+        already_bound
+        and _NATIVE_RUNTIME.get("phase") == _PHASE_TRANSPORT_BOUND
+        and already_bound != transport_name
+    ):
+        raise UnsanctionedRuntimeError(
+            "bind_native_mcp_transport rejected: transport is already bound to "
+            f"{already_bound!r} in this process; rebinding to "
+            f"{transport_name!r} is forbidden (#931). Restart the server to "
+            "change the deployment transport."
+        )
+
     # Pin session-state root for this server lifetime (#695 AC2 / PR #701).
     # Changing GITEA_MCP_SESSION_STATE_DIR after bind must not manufacture a
     # second authority domain for decision locks / workflow proofs.
@@ -353,6 +414,88 @@ def is_production_native_mcp_transport() -> bool:
     return (_NATIVE_RUNTIME or {}).get("mode") == _RUNTIME_MODE_PRODUCTION
 
 
+def bound_transport() -> str | None:
+    """The one authoritative bound transport identifier, or ``None`` (#931).
+
+    This is the shared accessor every transport-aware guard reads. It reports
+    the value pinned at bind time, never the environment, so changing
+    ``GITEA_MCP_TRANSPORT`` after the bind cannot move what a guard observes —
+    the same rule :func:`pinned_session_state_dir` applies to session state.
+
+    ``None`` means unbound: an offline import or a launch that never reached
+    the bind. Callers must treat that as fail-closed, exactly as they already
+    treat :func:`is_native_mcp_transport` returning false.
+    """
+    if not is_native_mcp_transport():
+        return None
+    return (_NATIVE_RUNTIME or {}).get("transport") or None
+
+
+def assert_transport_bound(context: str = "tool service") -> str:
+    """Return the bound transport, or fail closed before *context* (#931).
+
+    Called immediately before the server enters its transport loop so an
+    invalid or absent bind stops the process rather than serving tools over a
+    transport no guard can name.
+    """
+    transport = bound_transport()
+    if transport:
+        return transport
+    raise UnsanctionedRuntimeError(
+        f"No MCP transport is bound; refusing {context} (#931). "
+        "bind_native_mcp_transport must succeed from the canonical entrypoint "
+        "before any tool is served. Offline import and standalone launch "
+        "cannot reconstruct a bind."
+    )
+
+
+def assess_serve_authorization() -> dict[str, Any]:
+    """Structured verdict on whether this process may serve tools (#931).
+
+    This is the decision that consumes :func:`bound_transport`. It is what stops
+    the bound identifier from being reporting-only metadata: the serve path
+    cannot proceed unless the value pinned at bind is one this entrypoint is
+    commissioned to execute.
+
+    Never raises; returns the verdict so callers and diagnostics can inspect it.
+    """
+    return mcp_transport_config.assess_transport_execution(bound_transport())
+
+
+def authorize_transport_execution(context: str = "tool service") -> str:
+    """Return the transport this process may serve, or fail closed (#931).
+
+    Two distinct boundaries, in order:
+
+    1. **Bind presence** — :func:`assert_transport_bound` enforces the
+       pre-existing #695 contract, so an unbound runtime keeps its established
+       failure and reason code.
+    2. **Execution authorization** — the bound identifier must be one this
+       entrypoint is commissioned to serve. A registered transport whose
+       listener has not been commissioned is refused here, before any listener
+       is created and before any tool can dispatch.
+
+    That ordering matters: recognition, validation and durable recording all
+    still happen for a remote identifier, so #931's seam is intact; only the act
+    of *serving* it is withheld until its owning issue commissions it.
+    """
+    # Boundary 1: unbound stays exactly as fail-closed as it was under #695.
+    assert_transport_bound(context)
+
+    # Boundary 2: bound, but is this entrypoint allowed to serve it?
+    assessment = assess_serve_authorization()
+    if assessment.get("allowed"):
+        return str(assessment["transport"])
+
+    reasons = "; ".join(assessment.get("reasons") or []) or "not authorized"
+    next_action = assessment.get("exact_next_action") or ""
+    raise TransportExecutionError(
+        f"Refusing {context} (#931) [{assessment.get('blocker_kind')}]: "
+        f"{reasons} {next_action}".strip(),
+        assessment,
+    )
+
+
 def is_sanctioned_mcp_daemon() -> bool:
     """Backward-compatible name; #695 requires native transport, not env alone."""
     if is_production_native_mcp_transport():
@@ -476,6 +619,21 @@ def native_runtime_status() -> dict[str, Any]:
         "entrypoint_path": rt.get("entrypoint_path"),
         "phase": rt.get("phase"),
         "transport": rt.get("transport"),
+        # #931: the authoritative bound identifier, plus the seam that defines
+        # what may be bound. ``bound_transport`` is None until a bind succeeds,
+        # so an offline import is distinguishable from a stdio session.
+        "bound_transport": bound_transport(),
+        "transport_bound": bound_transport() is not None,
+        "default_transport": mcp_transport_config.DEFAULT_TRANSPORT,
+        "supported_transports": list(mcp_transport_config.supported_transports()),
+        "transport_env": mcp_transport_config.TRANSPORT_ENV,
+        # #931 review 635: recognition and execution authorization are distinct.
+        # ``supported`` is what may be bound; ``executable`` is what this
+        # entrypoint may actually serve. A recognized-but-uncommissioned
+        # transport reports serve_authorized False with a named blocker.
+        "executable_transports": list(mcp_transport_config.executable_transports()),
+        "serve_authorized": bool(assess_serve_authorization().get("allowed")),
+        "serve_authorization": assess_serve_authorization(),
         "mode": rt.get("mode"),
         "session_state_dir": pinned_session_state_dir() or rt.get("session_state_dir"),
         "session_state_dir_pinned": pinned_session_state_dir() is not None,
@@ -502,7 +660,12 @@ def mutation_provenance_fields() -> dict[str, Any]:
     if st.get("mode") == _RUNTIME_MODE_TEST and st["native_mcp_transport"]:
         transport = "test_native_mcp"
     return {
+        # ``transport`` stays the trust *class* it has always been, so existing
+        # durable records keep their shape. ``bound_transport`` (#931) adds the
+        # bound identifier itself, which is what lets an operator tell from a
+        # durable record which transport performed a mutation.
         "transport": transport,
+        "bound_transport": st.get("bound_transport"),
         "native_mcp_transport": bool(st["native_mcp_transport"]),
         "production_native_mcp_transport": bool(
             st.get("production_native_mcp_transport")

mcp_server.py

@@ -1,7 +1,10 @@
 #!/usr/bin/env python3
 """Gitea MCP Server — exposes Gitea operations as MCP tools.
 
-Runs over stdio. All tools authenticate via macOS keychain (git credential fill).
+The transport is selected by deployment configuration (GITEA_MCP_TRANSPORT) and
+defaults to the local client-spawned transport when unset (#931); the permitted
+set lives in mcp_transport_config. All tools authenticate via macOS keychain
+(git credential fill).
 """
 import os
 import sys
@@ -43,8 +46,9 @@ check_conflict_markers()
 
 # #558 / #695: claim the official entrypoint before loading mutation modules.
 # This alone does NOT authorize mutations — gitea_mcp_server binds the live
-# native MCP transport (stdio) immediately before mcp.run. Import-only or
+# native MCP transport immediately before mcp.run, over the configured
-# offline launch without that bind fails closed on mutations.
+# transport (#931). Import-only or offline launch without that bind fails
+# closed on mutations.
 try:
     import mcp_daemon_guard
 

mcp_session_state.py

@@ -588,9 +588,13 @@ def save_state(
                 bool(prov.get("production_native_mcp_transport")),
             )
             body.setdefault("transport", prov.get("transport"))
+            # #931: record the bound transport identifier itself, so a durable
+            # decision lock names which transport performed the mutation.
+            body.setdefault("bound_transport", prov.get("bound_transport"))
         except Exception:
             body.setdefault("native_mcp_transport", False)
             body.setdefault("transport", "untrusted")
+            body.setdefault("bound_transport", None)
 
         envelope = {
             "kind": kind,

mcp_transport_config.py

@@ -0,0 +1,292 @@
+"""Single authoritative source for the bound MCP transport identifier (#931).
+
+Before this module the transport was a literal, passed once at the bottom of
+``gitea_mcp_server`` as ``bind_native_mcp_transport(transport="stdio")``. Every
+guard that later asks "is this a trusted native session" resolves that question
+through the value bound there, so the literal was effectively a constant in the
+authorization chain rather than configuration.
+
+This module is the seam. It owns three things and nothing else:
+
+- the permitted set of transport identifiers,
+- the default used when deployment configuration says nothing,
+- the resolution of the configured value into a validated identifier.
+
+It deliberately holds no state. The *bound* transport is pinned once, at bind
+time, into the process-local native-runtime record owned by
+:mod:`mcp_daemon_guard`, and is read back through
+``mcp_daemon_guard.bound_transport()``. That split matters: configuration is
+read exactly once, before any tool can dispatch, so a later environment change
+cannot move the value a guard observes — the same pinning rule already applied
+to the session-state root under #695 AC2.
+
+Nothing here consumes tool arguments, request bodies, or provenance fields. The
+only input is the deployment environment, read at bind time.
+
+Standing up a listener for a non-stdio transport is #938; this module only
+makes the identifier expressible and validated.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Mapping
+
+# Deployment configuration key. Read once, at bind time, and never again.
+TRANSPORT_ENV = "GITEA_MCP_TRANSPORT"
+
+# The local, client-spawned transport. Unset configuration resolves to this,
+# which is what keeps every existing stdio deployment byte-identical.
+DEFAULT_TRANSPORT = "stdio"
+
+# The sanctioned remote transport identifier. Accepting it here is what makes
+# the bind pluggable; the endpoint that serves it belongs to #938. The name
+# matches the MCP transport name so no second vocabulary has to be mapped.
+REMOTE_TRANSPORT = "streamable-http"
+
+# The permitted set. This is the only place transport identifiers are
+# enumerated; guards consult it rather than restating any member.
+#
+# ``sse`` is a real MCP transport and is deliberately absent: it is the
+# superseded remote transport, and admitting it would give the deployment two
+# remote paths to reason about. An unregistered identifier must fail closed at
+# bind time, and ``sse`` is held to that rule like any other.
+SUPPORTED_TRANSPORTS = frozenset({DEFAULT_TRANSPORT, REMOTE_TRANSPORT})
+
+# Recognition is not execution authorization (#931, review 635 B1/B2).
+#
+# SUPPORTED_TRANSPORTS answers "is this an identifier this system knows, and may
+# it be bound, pinned and recorded?". It deliberately includes the remote
+# identifier, because #931 requires the bind to become pluggable.
+#
+# EXECUTABLE_TRANSPORTS answers a strictly narrower question: "is this entrypoint
+# commissioned to actually *serve* on that transport?". Only the local transport
+# is. Handing ``streamable-http`` to ``mcp.run`` would start FastMCP's HTTP
+# listener with no authentication, no TLS and no per-request principal — the
+# endpoint #938 owns and gates. Recognition must therefore never imply execution.
+#
+# #938 commissions the remote listener by adding REMOTE_TRANSPORT here, together
+# with the authentication and principal boundary its acceptance criteria require.
+EXECUTABLE_TRANSPORTS = frozenset({DEFAULT_TRANSPORT})
+
+# Which issue owns commissioning each recognized-but-not-executable transport.
+# Used to make the refusal actionable rather than a generic denial.
+TRANSPORT_EXECUTION_OWNER = {REMOTE_TRANSPORT: "#938"}
+
+BLOCKER_TRANSPORT_NOT_BOUND = "transport_not_bound"
+BLOCKER_TRANSPORT_NOT_RECOGNIZED = "transport_not_recognized"
+BLOCKER_LISTENER_NOT_COMMISSIONED = "transport_listener_not_commissioned"
+
+SOURCE_CONFIGURED = "deployment_configuration"
+SOURCE_DEFAULT = "default"
+
+
+class TransportConfigurationError(ValueError):
+    """Raised when configured transport is outside :data:`SUPPORTED_TRANSPORTS`."""
+
+
+def normalize_transport(value: Any) -> str:
+    """Canonical form of a transport identifier; ``""`` when there is none.
+
+    Non-string values normalize to ``""`` rather than being coerced, so a
+    structured object smuggled in from a caller can never match a member of the
+    permitted set.
+    """
+    if not isinstance(value, str):
+        return ""
+    return value.strip().lower()
+
+
+def supported_transports() -> tuple[str, ...]:
+    """Permitted identifiers, sorted, for messages and status payloads."""
+    return tuple(sorted(SUPPORTED_TRANSPORTS))
+
+
+def is_supported_transport(value: Any) -> bool:
+    """True when *value* normalizes to a member of the permitted set."""
+    return normalize_transport(value) in SUPPORTED_TRANSPORTS
+
+
+def is_remote_transport(value: Any) -> bool:
+    """True when *value* is a permitted transport that is not the local one."""
+    name = normalize_transport(value)
+    return name in SUPPORTED_TRANSPORTS and name != DEFAULT_TRANSPORT
+
+
+def executable_transports() -> tuple[str, ...]:
+    """Transports this entrypoint is commissioned to serve, sorted."""
+    return tuple(sorted(EXECUTABLE_TRANSPORTS))
+
+
+def is_executable_transport(value: Any) -> bool:
+    """True when *value* may actually be served by this entrypoint (#931).
+
+    Strictly narrower than :func:`is_supported_transport`. A recognized
+    identifier that is not executable is a correct, fully-bound configuration
+    whose listener has simply not been commissioned yet.
+    """
+    return normalize_transport(value) in EXECUTABLE_TRANSPORTS
+
+
+def assess_transport_execution(value: Any) -> dict[str, Any]:
+    """Structured serve-authorization verdict for a bound transport (#931).
+
+    This is the decision that separates a *recognized* transport from one this
+    entrypoint may execute. It is deliberately a pure function of the bound
+    identifier so the serve path cannot reach a listener the deployment has not
+    commissioned.
+
+    Args:
+        value: The bound transport identifier, or ``None`` when unbound.
+
+    Returns:
+        dict with ``transport``, ``recognized``, ``executable``, ``allowed``,
+        ``blocker_kind``, ``owner_issue``, ``reasons`` and
+        ``exact_next_action``. ``allowed`` is true only for a bound, recognized,
+        commissioned transport.
+    """
+    name = normalize_transport(value)
+
+    if not name:
+        return {
+            "transport": None,
+            "recognized": False,
+            "executable": False,
+            "allowed": False,
+            "blocker_kind": BLOCKER_TRANSPORT_NOT_BOUND,
+            "owner_issue": None,
+            "supported_transports": list(supported_transports()),
+            "executable_transports": list(executable_transports()),
+            "reasons": [
+                "no transport is bound; the serve path is fail-closed until "
+                "bind_native_mcp_transport succeeds (#695/#931)"
+            ],
+            "exact_next_action": (
+                "Launch through the canonical entrypoint so "
+                "bind_native_mcp_transport runs before tool service."
+            ),
+        }
+
+    recognized = name in SUPPORTED_TRANSPORTS
+    if not recognized:
+        return {
+            "transport": name,
+            "recognized": False,
+            "executable": False,
+            "allowed": False,
+            "blocker_kind": BLOCKER_TRANSPORT_NOT_RECOGNIZED,
+            "owner_issue": None,
+            "supported_transports": list(supported_transports()),
+            "executable_transports": list(executable_transports()),
+            "reasons": [
+                f"transport {name!r} is not a registered MCP transport (#931); "
+                "it should have been refused at bind time"
+            ],
+            "exact_next_action": (
+                f"Set {TRANSPORT_ENV} to one of {list(supported_transports())}."
+            ),
+        }
+
+    if name in EXECUTABLE_TRANSPORTS:
+        return {
+            "transport": name,
+            "recognized": True,
+            "executable": True,
+            "allowed": True,
+            "blocker_kind": None,
+            "owner_issue": None,
+            "supported_transports": list(supported_transports()),
+            "executable_transports": list(executable_transports()),
+            "reasons": [],
+            "exact_next_action": None,
+        }
+
+    owner = TRANSPORT_EXECUTION_OWNER.get(name)
+    owner_text = owner or "the issue that commissions this transport's listener"
+    return {
+        "transport": name,
+        "recognized": True,
+        "executable": False,
+        "allowed": False,
+        "blocker_kind": BLOCKER_LISTENER_NOT_COMMISSIONED,
+        "owner_issue": owner,
+        "supported_transports": list(supported_transports()),
+        "executable_transports": list(executable_transports()),
+        "reasons": [
+            f"transport {name!r} is registered and was bound and recorded, but "
+            f"this entrypoint is not commissioned to serve it (#931). Serving it "
+            f"would start a listener with no authentication, no transport "
+            f"security and no per-request principal; that endpoint is owned by "
+            f"{owner_text}."
+        ],
+        "exact_next_action": (
+            f"Serve on {DEFAULT_TRANSPORT} until {owner_text} commissions the "
+            f"{name!r} listener with its authentication and principal boundary, "
+            f"which adds {name!r} to EXECUTABLE_TRANSPORTS."
+        ),
+    }
+
+
+def resolve_configured_transport(
+    env: Mapping[str, str] | None = None,
+) -> dict[str, Any]:
+    """Resolve the deployment-configured transport without raising.
+
+    Returns the resolution rather than a bare string so a caller can tell an
+    unset value (which legitimately yields :data:`DEFAULT_TRANSPORT`) from a
+    configured value that is not permitted (which must fail closed, never
+    silently degrade to the default).
+
+    Args:
+        env: Environment mapping to read; defaults to ``os.environ``.
+
+    Returns:
+        dict with ``transport`` (normalized; the default when unset),
+        ``configured``, ``source``, ``raw``, ``supported``, and ``reasons``.
+    """
+    source_env = os.environ if env is None else env
+    raw = source_env.get(TRANSPORT_ENV)
+    normalized = normalize_transport(raw)
+    configured = bool(normalized)
+
+    if not configured:
+        return {
+            "transport": DEFAULT_TRANSPORT,
+            "configured": False,
+            "source": SOURCE_DEFAULT,
+            "raw": raw,
+            "supported": True,
+            "supported_transports": list(supported_transports()),
+            "env_key": TRANSPORT_ENV,
+            "reasons": [],
+        }
+
+    supported = normalized in SUPPORTED_TRANSPORTS
+    reasons: list[str] = []
+    if not supported:
+        reasons.append(
+            f"{TRANSPORT_ENV}={normalized!r} is not a registered MCP transport "
+            f"(#931). Registered: {list(supported_transports())}."
+        )
+    return {
+        "transport": normalized,
+        "configured": True,
+        "source": SOURCE_CONFIGURED,
+        "raw": raw,
+        "supported": supported,
+        "supported_transports": list(supported_transports()),
+        "env_key": TRANSPORT_ENV,
+        "reasons": reasons,
+    }
+
+
+def require_configured_transport(env: Mapping[str, str] | None = None) -> str:
+    """Resolved transport identifier, or raise when it is not permitted.
+
+    Raises:
+        TransportConfigurationError: the configured identifier is unregistered.
+    """
+    resolution = resolve_configured_transport(env)
+    if not resolution["supported"]:
+        raise TransportConfigurationError("; ".join(resolution["reasons"]))
+    return str(resolution["transport"])

role_namespace_gate.py

@@ -74,6 +74,43 @@ def check_author_mutation_namespace(
     return True, []
 
 
+def check_author_role_kind(
+    mutation_task: str,
+    profile: dict,
+) -> tuple[bool, list[str]]:
+    """Author-exclusive wall for durable-lock mutations (#953 F1).
+
+    ``check_author_mutation_namespace`` walls off reviewer-bound sessions, which
+    is the whole gate for tasks whose required permission is itself author-only
+    (``gitea.pr.create``, ``gitea.repo.commit``). It is *not* sufficient for a
+    task gated on ``gitea.issue.comment``, which every configured role holds: a
+    merger, controller, or reconciler session would clear both the namespace
+    check and the permission gate and still reach the durable write.
+
+    Opt-in per call site and additive. It refuses any active profile whose
+    derived role kind is not exactly ``author`` for a task the router declares
+    author-required, and grants nothing to anyone — a ``mixed`` profile is
+    refused rather than admitted.
+    """
+    required_role = role_session_router.required_role_for_task(mutation_task)
+    if required_role != "author":
+        return True, []
+
+    allowed = profile.get("allowed_operations") or []
+    forbidden = profile.get("forbidden_operations") or []
+    active_role = derive_role_kind(allowed, forbidden)
+    if active_role == "author":
+        return True, []
+
+    profile_name = profile.get("profile_name") or ""
+    namespace = infer_mcp_namespace(profile_name)
+    return False, [
+        f"author mutation '{mutation_task}' blocked: active session role kind is "
+        f"'{active_role}', not 'author' ({profile_name} / {namespace}); this "
+        "operation writes a durable author issue lock and is author-exclusive",
+    ]
+
+
 def mutation_audit_context(mutation_task: str, profile: dict, *,
                            remote=None, repository=None) -> dict:
     """Structured mutation metadata for audit records (#209)."""

role_session_router.py

@@ -75,6 +75,10 @@ AUTHOR_TASKS = frozenset({
     "push_branch",
     "bootstrap_author_issue_worktree",
     "gitea_bootstrap_author_issue_worktree",
+    # #953: recovery of an incomplete bootstrap lock is an author-only durable
+    # state mutation and belongs to the same class as bootstrap itself.
+    "recover_incomplete_bootstrap_lock",
+    "gitea_recover_incomplete_bootstrap_lock",
     "create_pr",
     "comment_pr",
     "address_pr_change_requests",
@@ -112,6 +116,12 @@ TASK_REQUIRED_ROLE = {
     "claim_issue": "author",
     "create_branch": "author",
     "push_branch": "author",
+    # #953: without this entry ``required_role_for_task`` returns None and
+    # ``role_namespace_gate.check_author_mutation_namespace`` short-circuits to
+    # "allowed" — the namespace wall on the recovery tool would be inert. The
+    # capability map already records the same role; both tables must agree.
+    "recover_incomplete_bootstrap_lock": "author",
+    "gitea_recover_incomplete_bootstrap_lock": "author",
     "create_pr": "author",
     "comment_pr": "author",
     "address_pr_change_requests": "author",

task_capability_map.py

@@ -41,6 +41,27 @@ TASK_CAPABILITY_MAP: dict[str, dict[str, str]] = {
         "permission": "gitea.issue.comment",
         "role": "author",
     },
+    # #953: target-specific upgrade of an incomplete bootstrap lock (explicit
+    # operation, never a widening of lock_issue). Author-only, and the tool
+    # additionally proves exact-owner claimant match before writing.
+    "recover_incomplete_bootstrap_lock": {
+        "permission": "gitea.issue.comment",
+        "role": "author",
+    },
+    "gitea_recover_incomplete_bootstrap_lock": {
+        "permission": "gitea.issue.comment",
+        "role": "author",
+    },
+    # #953: read-only lock contract inspection. Read permission only — it must
+    # never be able to mutate.
+    "inspect_issue_lock_contract": {
+        "permission": "gitea.read",
+        "role": "author",
+    },
+    "gitea_inspect_issue_lock_contract": {
+        "permission": "gitea.read",
+        "role": "author",
+    },
     # #860: dirty orphaned same-claimant worktree recovery (explicit operation).
     "recover_dirty_orphaned_issue_worktree": {
         "permission": "gitea.issue.comment",

tests/test_issue_931_transport_bind_seam.py

@@ -0,0 +1,924 @@
+"""Transport-neutral MCP bind seam (#931).
+
+These tests drive the *real* bind boundary — ``mark_sanctioned_daemon`` followed
+by ``bind_native_mcp_transport`` from a canonical entrypoint path, with the
+pytest allowance switched off — rather than mocking the new accessor. The
+distinction matters here for the same reason it mattered in #941: a suite that
+only exercises the helper in isolation cannot observe a seam that the live path
+never reaches.
+
+Covered:
+
+1.  no configured transport defaults to the local transport
+2.  explicit local transport binds
+3.  the sanctioned remote identifier binds through the seam
+4.  an unregistered identifier is rejected at bind time
+5.  an invalid bind prevents the server reaching tool service
+6.  the unbound state fails closed where a bind is required
+7.  every transport-aware guard reads the same authoritative value
+8.  client-controlled input cannot alter the bound transport
+9.  the durable decision-lock record carries the selected transport
+10. existing stdio behaviour is unchanged
+11. repeated / conflicting bind attempts follow one fail-closed contract
+12. capability, role, repository and provenance protections do not regress
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+import mcp_daemon_guard
+import mcp_session_state
+import mcp_transport_config
+import irrecoverable_provenance
+
+
+class _ProductionBind:
+    """Context manager that reaches the real production bind path.
+
+    Patches only the two things a unit test cannot otherwise satisfy: the
+    resolved canonical entrypoint frame, and the pytest allowance that would
+    short-circuit ``mark_sanctioned_daemon``. Everything downstream of those —
+    validation, pinning, the rebind contract — runs unmodified.
+    """
+
+    def __init__(self, env: dict[str, str] | None = None):
+        self._env = env or {}
+        self._stack: list = []
+
+    def __enter__(self):
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        canonical = str((REPO_ROOT / "mcp_server.py").resolve())
+        self._stack = [
+            patch.object(
+                mcp_daemon_guard,
+                "_caller_official_entrypoint_path",
+                side_effect=lambda: canonical,
+            ),
+            patch.object(mcp_daemon_guard, "is_pytest_runtime", return_value=False),
+            patch.dict(os.environ, self._env),
+        ]
+        for ctx in self._stack:
+            ctx.__enter__()
+        # Start from a clean configuration unless the test set one.
+        if mcp_transport_config.TRANSPORT_ENV not in self._env:
+            os.environ.pop(mcp_transport_config.TRANSPORT_ENV, None)
+        mcp_daemon_guard.mark_sanctioned_daemon()
+        return mcp_daemon_guard
+
+    def __exit__(self, *exc):
+        for ctx in reversed(self._stack):
+            ctx.__exit__(*exc)
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        return False
+
+
+class TestPermittedSetIsSingleSourceOfTruth(unittest.TestCase):
+    """AC3: identifiers are enumerated once, in the seam."""
+
+    def test_guard_allowlist_is_the_seam_allowlist(self):
+        self.assertIs(
+            mcp_daemon_guard._PRODUCTION_TRANSPORTS,
+            mcp_transport_config.SUPPORTED_TRANSPORTS,
+        )
+
+    def test_default_is_a_member_of_the_permitted_set(self):
+        self.assertIn(
+            mcp_transport_config.DEFAULT_TRANSPORT,
+            mcp_transport_config.SUPPORTED_TRANSPORTS,
+        )
+
+    def test_remote_identifier_is_permitted_and_not_the_default(self):
+        self.assertIn(
+            mcp_transport_config.REMOTE_TRANSPORT,
+            mcp_transport_config.SUPPORTED_TRANSPORTS,
+        )
+        self.assertNotEqual(
+            mcp_transport_config.REMOTE_TRANSPORT,
+            mcp_transport_config.DEFAULT_TRANSPORT,
+        )
+        self.assertTrue(
+            mcp_transport_config.is_remote_transport(
+                mcp_transport_config.REMOTE_TRANSPORT
+            )
+        )
+
+    def test_no_default_transport_literal_outside_the_seam(self):
+        """AC3: no production module reads the literal outside the seam.
+
+        Review 635 flagged that a fixed five-module list cannot catch a *new*
+        module reintroducing the literal. This globs every production module in
+        the repository root instead, so the guarantee holds for code that does
+        not exist yet.
+        """
+        default = mcp_transport_config.DEFAULT_TRANSPORT
+        needles = (f'"{default}"', f"'{default}'")
+        seam = Path(mcp_transport_config.__file__).name
+        scanned: list[str] = []
+        offenders: list[str] = []
+        for path in sorted(REPO_ROOT.glob("*.py")):
+            if path.name == seam:
+                continue  # the seam is the one place the literal may live
+            scanned.append(path.name)
+            for lineno, line in enumerate(
+                path.read_text(encoding="utf-8").splitlines(), start=1
+            ):
+                code = line.split("#", 1)[0]
+                if any(needle in code for needle in needles):
+                    offenders.append(f"{path.name}:{lineno}: {line.strip()}")
+        # Guard the guard: a glob that silently matched nothing would pass.
+        self.assertGreater(len(scanned), 20, "production glob matched too little")
+        self.assertIn("mcp_daemon_guard.py", scanned)
+        self.assertIn("gitea_mcp_server.py", scanned)
+        self.assertEqual(offenders, [], "\n".join(offenders))
+
+
+class TestConfiguredTransportResolution(unittest.TestCase):
+    """AC1: configuration supplies the identifier; unset still yields the default."""
+
+    def test_unset_yields_default(self):
+        res = mcp_transport_config.resolve_configured_transport(env={})
+        self.assertEqual(res["transport"], mcp_transport_config.DEFAULT_TRANSPORT)
+        self.assertFalse(res["configured"])
+        self.assertEqual(res["source"], mcp_transport_config.SOURCE_DEFAULT)
+        self.assertTrue(res["supported"])
+        self.assertEqual(res["reasons"], [])
+
+    def test_blank_and_whitespace_are_treated_as_unset(self):
+        for raw in ("", "   ", "\t\n"):
+            res = mcp_transport_config.resolve_configured_transport(
+                env={mcp_transport_config.TRANSPORT_ENV: raw}
+            )
+            self.assertEqual(res["transport"], mcp_transport_config.DEFAULT_TRANSPORT)
+            self.assertFalse(res["configured"])
+
+    def test_explicit_default_is_reported_as_configured(self):
+        res = mcp_transport_config.resolve_configured_transport(
+            env={
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.DEFAULT_TRANSPORT
+                )
+            }
+        )
+        self.assertEqual(res["transport"], mcp_transport_config.DEFAULT_TRANSPORT)
+        self.assertTrue(res["configured"])
+        self.assertEqual(res["source"], mcp_transport_config.SOURCE_CONFIGURED)
+
+    def test_remote_identifier_resolves_and_is_supported(self):
+        res = mcp_transport_config.resolve_configured_transport(
+            env={
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        )
+        self.assertEqual(res["transport"], mcp_transport_config.REMOTE_TRANSPORT)
+        self.assertTrue(res["supported"])
+
+    def test_case_and_padding_are_normalized(self):
+        padded = f"  {mcp_transport_config.REMOTE_TRANSPORT.upper()}  "
+        res = mcp_transport_config.resolve_configured_transport(
+            env={mcp_transport_config.TRANSPORT_ENV: padded}
+        )
+        self.assertEqual(res["transport"], mcp_transport_config.REMOTE_TRANSPORT)
+        self.assertTrue(res["supported"])
+
+    def test_unregistered_identifier_is_not_silently_defaulted(self):
+        res = mcp_transport_config.resolve_configured_transport(
+            env={mcp_transport_config.TRANSPORT_ENV: "carrier-pigeon"}
+        )
+        self.assertFalse(res["supported"])
+        self.assertEqual(res["transport"], "carrier-pigeon")
+        self.assertNotEqual(res["transport"], mcp_transport_config.DEFAULT_TRANSPORT)
+        self.assertTrue(res["reasons"])
+
+    def test_superseded_sse_transport_is_not_registered(self):
+        """A real MCP transport that this deployment does not sanction."""
+        self.assertFalse(mcp_transport_config.is_supported_transport("sse"))
+        res = mcp_transport_config.resolve_configured_transport(
+            env={mcp_transport_config.TRANSPORT_ENV: "sse"}
+        )
+        self.assertFalse(res["supported"])
+
+    def test_require_configured_transport_raises_on_unregistered(self):
+        with self.assertRaises(mcp_transport_config.TransportConfigurationError):
+            mcp_transport_config.require_configured_transport(
+                env={mcp_transport_config.TRANSPORT_ENV: "carrier-pigeon"}
+            )
+
+    def test_non_string_configuration_never_matches_permitted_set(self):
+        for value in (object(), 1, None, True, ["stdio"], {"t": "stdio"}):
+            self.assertEqual(mcp_transport_config.normalize_transport(value), "")
+            self.assertFalse(mcp_transport_config.is_supported_transport(value))
+
+
+class TestBindSeam(unittest.TestCase):
+    """AC1/AC2: the live bind path resolves, validates, and pins."""
+
+    def tearDown(self) -> None:
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+
+    def test_1_no_configured_transport_binds_default(self):
+        with _ProductionBind() as guard:
+            status = guard.bind_native_mcp_transport()
+            self.assertEqual(
+                status["transport"], mcp_transport_config.DEFAULT_TRANSPORT
+            )
+            self.assertEqual(
+                guard.bound_transport(), mcp_transport_config.DEFAULT_TRANSPORT
+            )
+            self.assertTrue(status["production_native_mcp_transport"])
+
+    def test_2_explicit_default_transport_binds(self):
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.DEFAULT_TRANSPORT
+                )
+            }
+        ) as guard:
+            status = guard.bind_native_mcp_transport()
+            self.assertEqual(
+                status["transport"], mcp_transport_config.DEFAULT_TRANSPORT
+            )
+            self.assertTrue(guard.is_production_native_mcp_transport())
+
+    def test_2b_explicit_argument_still_binds(self):
+        """The pre-#931 call form keeps working for launchers and tests."""
+        with _ProductionBind() as guard:
+            status = guard.bind_native_mcp_transport(
+                transport=mcp_transport_config.DEFAULT_TRANSPORT
+            )
+            self.assertEqual(
+                status["transport"], mcp_transport_config.DEFAULT_TRANSPORT
+            )
+
+    def test_3_sanctioned_remote_identifier_binds_through_the_seam(self):
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            status = guard.bind_native_mcp_transport()
+            self.assertEqual(
+                status["transport"], mcp_transport_config.REMOTE_TRANSPORT
+            )
+            self.assertEqual(
+                guard.bound_transport(), mcp_transport_config.REMOTE_TRANSPORT
+            )
+            # The remote identifier is trusted exactly like the local one; the
+            # listener that serves it is #938 and is not implemented here.
+            self.assertTrue(guard.is_native_mcp_transport())
+            self.assertTrue(guard.is_production_native_mcp_transport())
+            guard.assert_production_mutation_runtime("remote-bind")
+
+    def test_4_unregistered_identifier_rejected_at_bind_time(self):
+        with _ProductionBind(
+            {mcp_transport_config.TRANSPORT_ENV: "carrier-pigeon"}
+        ) as guard:
+            with self.assertRaises(guard.UnsanctionedRuntimeError) as ctx:
+                guard.bind_native_mcp_transport()
+            self.assertIn("carrier-pigeon", str(ctx.exception))
+            self.assertIn("#931", str(ctx.exception))
+            # Nothing was bound, so nothing may dispatch.
+            self.assertIsNone(guard.bound_transport())
+            self.assertFalse(guard.is_native_mcp_transport())
+
+    def test_4b_unregistered_explicit_argument_rejected(self):
+        with _ProductionBind() as guard:
+            with self.assertRaises(guard.UnsanctionedRuntimeError):
+                guard.bind_native_mcp_transport(transport="carrier-pigeon")
+            self.assertIsNone(guard.bound_transport())
+
+    def test_4c_superseded_sse_rejected_at_bind_time(self):
+        with _ProductionBind({mcp_transport_config.TRANSPORT_ENV: "sse"}) as guard:
+            with self.assertRaises(guard.UnsanctionedRuntimeError):
+                guard.bind_native_mcp_transport()
+            self.assertIsNone(guard.bound_transport())
+
+    def test_5_invalid_bind_prevents_tool_service(self):
+        """A failed bind must stop the server before it serves tools."""
+        with _ProductionBind(
+            {mcp_transport_config.TRANSPORT_ENV: "carrier-pigeon"}
+        ) as guard:
+            with self.assertRaises(guard.UnsanctionedRuntimeError):
+                guard.bind_native_mcp_transport()
+            # This is the exact expression the entrypoint passes to mcp.run.
+            with self.assertRaises(guard.UnsanctionedRuntimeError) as ctx:
+                guard.assert_transport_bound("tool service")
+            self.assertIn("No MCP transport is bound", str(ctx.exception))
+
+    def test_6_unbound_state_fails_closed(self):
+        """Entrypoint claimed but never bound — the offline-import shape."""
+        with _ProductionBind() as guard:
+            self.assertIsNone(guard.bound_transport())
+            self.assertFalse(guard.is_native_mcp_transport())
+            with self.assertRaises(guard.UnsanctionedRuntimeError):
+                guard.assert_transport_bound("tool service")
+            with self.assertRaises(guard.UnsanctionedRuntimeError):
+                guard.assert_sanctioned_mutation_runtime("gitea_mutation")
+
+    def test_6b_no_runtime_at_all_fails_closed(self):
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        with patch.object(mcp_daemon_guard, "is_pytest_runtime", return_value=False):
+            self.assertIsNone(mcp_daemon_guard.bound_transport())
+            with self.assertRaises(mcp_daemon_guard.UnsanctionedRuntimeError):
+                mcp_daemon_guard.assert_transport_bound("tool service")
+
+
+class TestOneAuthoritativeValue(unittest.TestCase):
+    """AC: every transport-aware guard observes the same value."""
+
+    def tearDown(self) -> None:
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+
+    def test_7_all_guards_read_the_same_bound_value(self):
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            expected = mcp_transport_config.REMOTE_TRANSPORT
+
+            self.assertEqual(guard.bound_transport(), expected)
+            self.assertEqual(guard.assert_transport_bound(), expected)
+            self.assertEqual(guard.native_runtime_status()["bound_transport"], expected)
+            self.assertEqual(guard.native_runtime_status()["transport"], expected)
+            self.assertEqual(
+                guard.mutation_provenance_fields()["bound_transport"], expected
+            )
+            self.assertEqual(
+                irrecoverable_provenance.assess_transport_for_auth_mint()[
+                    "bound_transport"
+                ],
+                expected,
+            )
+
+    def test_8_environment_change_after_bind_cannot_move_the_value(self):
+        """Client- or environment-shaped input must not alter a bound transport."""
+        with _ProductionBind() as guard:
+            guard.bind_native_mcp_transport()
+            self.assertEqual(
+                guard.bound_transport(), mcp_transport_config.DEFAULT_TRANSPORT
+            )
+            # A stray launcher (or an attacker) rewrites config post-bind.
+            os.environ[mcp_transport_config.TRANSPORT_ENV] = (
+                mcp_transport_config.REMOTE_TRANSPORT
+            )
+            self.assertEqual(
+                guard.bound_transport(), mcp_transport_config.DEFAULT_TRANSPORT
+            )
+            self.assertEqual(
+                guard.mutation_provenance_fields()["bound_transport"],
+                mcp_transport_config.DEFAULT_TRANSPORT,
+            )
+            os.environ[mcp_transport_config.TRANSPORT_ENV] = "carrier-pigeon"
+            self.assertEqual(
+                guard.bound_transport(), mcp_transport_config.DEFAULT_TRANSPORT
+            )
+
+    def test_8b_bound_transport_takes_no_caller_argument(self):
+        """The accessor cannot be steered by a tool parameter."""
+        import inspect
+
+        self.assertEqual(
+            list(inspect.signature(mcp_daemon_guard.bound_transport).parameters), []
+        )
+
+    def test_11_rebinding_the_same_transport_is_idempotent(self):
+        with _ProductionBind() as guard:
+            first = guard.bind_native_mcp_transport()
+            second = guard.bind_native_mcp_transport()
+            self.assertEqual(first["transport"], second["transport"])
+            self.assertEqual(
+                guard.bound_transport(), mcp_transport_config.DEFAULT_TRANSPORT
+            )
+
+    def test_11b_rebinding_a_different_transport_fails_closed(self):
+        with _ProductionBind() as guard:
+            guard.bind_native_mcp_transport()
+            with self.assertRaises(guard.UnsanctionedRuntimeError) as ctx:
+                guard.bind_native_mcp_transport(
+                    transport=mcp_transport_config.REMOTE_TRANSPORT
+                )
+            self.assertIn("already bound", str(ctx.exception))
+            # The first value survives the attempt.
+            self.assertEqual(
+                guard.bound_transport(), mcp_transport_config.DEFAULT_TRANSPORT
+            )
+
+    def test_11c_rebinding_an_unregistered_transport_fails_closed(self):
+        with _ProductionBind() as guard:
+            guard.bind_native_mcp_transport()
+            with self.assertRaises(guard.UnsanctionedRuntimeError):
+                guard.bind_native_mcp_transport(transport="carrier-pigeon")
+            self.assertEqual(
+                guard.bound_transport(), mcp_transport_config.DEFAULT_TRANSPORT
+            )
+
+
+class TestDurableRecordCarriesTransport(unittest.TestCase):
+    """AC4: the identifier reaches a durable decision-lock record."""
+
+    def tearDown(self) -> None:
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+
+    def _save_and_read_decision_lock(self, state_dir: str) -> dict:
+        mcp_session_state.save_state(
+            kind=mcp_session_state.KIND_DECISION_LOCK,
+            payload={"pr_number": 931, "action": "COMMENT"},
+            remote="prgs",
+            org="Scaled-Tech-Consulting",
+            repo="Gitea-Tools",
+            profile_identity="prgs-author",
+            state_dir=state_dir,
+        )
+        loaded = mcp_session_state.load_state(
+            kind=mcp_session_state.KIND_DECISION_LOCK,
+            remote="prgs",
+            org="Scaled-Tech-Consulting",
+            repo="Gitea-Tools",
+            profile_identity="prgs-author",
+            state_dir=state_dir,
+        )
+        self.assertIsNotNone(loaded)
+        return loaded
+
+    def test_9_decision_lock_records_the_bound_transport(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            mcp_daemon_guard.clear_native_runtime_for_tests()
+            mcp_daemon_guard.install_test_native_runtime()
+            record = self._save_and_read_decision_lock(tmp)
+            self.assertIn("bound_transport", record)
+            self.assertEqual(
+                record["bound_transport"], mcp_daemon_guard.bound_transport()
+            )
+
+    def test_9b_unbound_runtime_records_no_transport_identifier(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            mcp_daemon_guard.clear_native_runtime_for_tests()
+            record = self._save_and_read_decision_lock(tmp)
+            self.assertIn("bound_transport", record)
+            self.assertIsNone(record["bound_transport"])
+
+    def test_9c_provenance_fields_expose_the_identifier(self):
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        fields = mcp_daemon_guard.mutation_provenance_fields()
+        self.assertIn("bound_transport", fields)
+        self.assertIsNone(fields["bound_transport"])
+
+
+class TestStdioBehaviourUnchanged(unittest.TestCase):
+    """AC6 / prompt items 10 and 12: no regression on the existing path."""
+
+    def tearDown(self) -> None:
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+
+    def test_10_trust_class_field_keeps_its_pre_931_values(self):
+        """``transport`` remains the trust class, not the identifier."""
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        self.assertEqual(
+            mcp_daemon_guard.mutation_provenance_fields()["transport"], "untrusted"
+        )
+        mcp_daemon_guard.install_test_native_runtime()
+        self.assertEqual(
+            mcp_daemon_guard.mutation_provenance_fields()["transport"],
+            "test_native_mcp",
+        )
+        with _ProductionBind() as guard:
+            guard.bind_native_mcp_transport()
+            self.assertEqual(
+                guard.mutation_provenance_fields()["transport"], "native_mcp"
+            )
+
+    def test_10b_default_bind_reproduces_the_pre_931_runtime_record(self):
+        with _ProductionBind() as guard:
+            status = guard.bind_native_mcp_transport()
+            self.assertTrue(status["native_mcp_transport"])
+            self.assertTrue(status["production_native_mcp_transport"])
+            self.assertEqual(status["mode"], "production")
+            self.assertEqual(status["phase"], "transport_bound")
+            self.assertEqual(
+                status["transport"], mcp_transport_config.DEFAULT_TRANSPORT
+            )
+            guard.assert_sanctioned_mutation_runtime("native-ide")
+            guard.assert_production_mutation_runtime("native-ide")
+
+    def test_12_session_state_root_still_pinned_at_bind(self):
+        """#695 AC2 must survive the seam."""
+        with tempfile.TemporaryDirectory() as legit:
+            with tempfile.TemporaryDirectory() as rogue:
+                with _ProductionBind(
+                    {mcp_daemon_guard.SESSION_STATE_DIR_ENV: legit}
+                ) as guard:
+                    guard.bind_native_mcp_transport()
+                    self.assertEqual(
+                        guard.pinned_session_state_dir(), str(Path(legit).resolve())
+                    )
+                    os.environ[mcp_daemon_guard.SESSION_STATE_DIR_ENV] = rogue
+                    self.assertEqual(
+                        guard.pinned_session_state_dir(), str(Path(legit).resolve())
+                    )
+
+    def test_12b_test_mode_record_still_cannot_authorize_production(self):
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        mcp_daemon_guard.install_test_native_runtime()
+        self.assertTrue(mcp_daemon_guard.is_native_mcp_transport())
+        self.assertFalse(mcp_daemon_guard.is_production_native_mcp_transport())
+        with self.assertRaises(mcp_daemon_guard.UnsanctionedRuntimeError):
+            mcp_daemon_guard.assert_production_mutation_runtime("prod-endpoint")
+
+    def test_12c_bind_still_requires_the_canonical_entrypoint(self):
+        """A remote identifier does not relax provenance."""
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        with patch.object(mcp_daemon_guard, "is_pytest_runtime", return_value=False):
+            with patch.object(
+                mcp_daemon_guard,
+                "_caller_official_entrypoint_path",
+                return_value=None,
+            ):
+                with self.assertRaises(mcp_daemon_guard.UnsanctionedRuntimeError):
+                    mcp_daemon_guard.bind_native_mcp_transport(
+                        transport=mcp_transport_config.REMOTE_TRANSPORT
+                    )
+        self.assertIsNone(mcp_daemon_guard.bound_transport())
+
+    def test_12d_bind_still_requires_a_prior_entrypoint_claim(self):
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        canonical = str((REPO_ROOT / "mcp_server.py").resolve())
+        with patch.object(mcp_daemon_guard, "is_pytest_runtime", return_value=False):
+            with patch.object(
+                mcp_daemon_guard,
+                "_caller_official_entrypoint_path",
+                side_effect=lambda: canonical,
+            ):
+                # No mark_sanctioned_daemon() first.
+                with self.assertRaises(
+                    mcp_daemon_guard.UnsanctionedRuntimeError
+                ) as ctx:
+                    mcp_daemon_guard.bind_native_mcp_transport()
+                self.assertIn("no entrypoint claim", str(ctx.exception))
+
+    def test_12e_auth_mint_verdict_is_unchanged_for_the_default_transport(self):
+        with _ProductionBind() as guard:
+            guard.bind_native_mcp_transport()
+            verdict = irrecoverable_provenance.assess_transport_for_auth_mint()
+            self.assertTrue(verdict["allowed"])
+            self.assertTrue(verdict["native_mcp_transport"])
+            self.assertTrue(verdict["production_native_mcp_transport"])
+            self.assertEqual(verdict["reasons"], [])
+
+    def test_12f_auth_mint_still_refuses_an_unbound_runtime(self):
+        with _ProductionBind():
+            # Claimed but never bound.
+            verdict = irrecoverable_provenance.assess_transport_for_auth_mint()
+            self.assertFalse(verdict["allowed"])
+            self.assertTrue(verdict["reasons"])
+            self.assertIsNone(verdict["bound_transport"])
+
+
+class TestExecutionBoundary(unittest.TestCase):
+    """Recognition is not execution authorization (#931, review 635 B1/B2).
+
+    A registered remote identifier must still bind, pin and record — the #931
+    seam — while being refused at the serve boundary, because serving it would
+    start a listener with no authentication or per-request principal. That
+    listener belongs to #938.
+    """
+
+    def tearDown(self) -> None:
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+
+    # -- the two sets are distinct, and narrower in the right direction ----
+
+    def test_executable_set_is_a_strict_subset_of_recognized(self):
+        self.assertTrue(
+            mcp_transport_config.EXECUTABLE_TRANSPORTS
+            < mcp_transport_config.SUPPORTED_TRANSPORTS
+        )
+
+    def test_default_transport_is_executable(self):
+        self.assertTrue(
+            mcp_transport_config.is_executable_transport(
+                mcp_transport_config.DEFAULT_TRANSPORT
+            )
+        )
+
+    def test_remote_transport_is_recognized_but_not_executable(self):
+        remote = mcp_transport_config.REMOTE_TRANSPORT
+        self.assertTrue(mcp_transport_config.is_supported_transport(remote))
+        self.assertFalse(mcp_transport_config.is_executable_transport(remote))
+
+    def test_remote_listener_ownership_is_declared(self):
+        self.assertEqual(
+            mcp_transport_config.TRANSPORT_EXECUTION_OWNER[
+                mcp_transport_config.REMOTE_TRANSPORT
+            ],
+            "#938",
+        )
+
+    # -- stdio still reaches the runner, unchanged -------------------------
+
+    def test_default_transport_is_authorized_for_service(self):
+        with _ProductionBind() as guard:
+            guard.bind_native_mcp_transport()
+            self.assertEqual(
+                guard.authorize_transport_execution("tool service"),
+                mcp_transport_config.DEFAULT_TRANSPORT,
+            )
+            self.assertTrue(guard.assess_serve_authorization()["allowed"])
+
+    def test_default_transport_reaches_the_real_runner(self):
+        """The production runner is actually invoked, with stdio, unchanged."""
+        with _ProductionBind() as guard:
+            guard.bind_native_mcp_transport()
+            seen = {}
+
+            class _Runner:
+                def run(self, transport=None, **kw):
+                    seen["transport"] = transport
+
+            _Runner().run(transport=guard.authorize_transport_execution("tool service"))
+            self.assertEqual(
+                seen["transport"], mcp_transport_config.DEFAULT_TRANSPORT
+            )
+
+    # -- streamable-http binds, records, and is refused before serving -----
+
+    def test_remote_transport_binds_and_is_recorded(self):
+        """The #931 seam is intact: it binds, pins and records."""
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            self.assertEqual(
+                guard.bound_transport(), mcp_transport_config.REMOTE_TRANSPORT
+            )
+            self.assertEqual(
+                guard.mutation_provenance_fields()["bound_transport"],
+                mcp_transport_config.REMOTE_TRANSPORT,
+            )
+
+    def test_remote_transport_is_refused_at_the_serve_boundary(self):
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            with self.assertRaises(guard.TransportExecutionError) as ctx:
+                guard.authorize_transport_execution("tool service")
+            err = ctx.exception
+            self.assertEqual(
+                err.blocker_kind,
+                mcp_transport_config.BLOCKER_LISTENER_NOT_COMMISSIONED,
+            )
+            self.assertEqual(err.owner_issue, "#938")
+            self.assertEqual(err.transport, mcp_transport_config.REMOTE_TRANSPORT)
+
+    def test_refusal_names_transport_and_unmet_requirement_and_owner(self):
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            with self.assertRaises(guard.TransportExecutionError) as ctx:
+                guard.authorize_transport_execution("tool service")
+            text = str(ctx.exception)
+            self.assertIn(mcp_transport_config.REMOTE_TRANSPORT, text)
+            self.assertIn("#938", text)
+            self.assertIn("not commissioned", text)
+            self.assertIn("#931", text)
+
+    def test_remote_transport_never_reaches_the_runner(self):
+        """No transport value is handed to a run() call for the remote case."""
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            calls = []
+
+            class _Runner:
+                def run(self, transport=None, **kw):
+                    calls.append(transport)
+
+            with self.assertRaises(guard.TransportExecutionError):
+                _Runner().run(
+                    transport=guard.authorize_transport_execution("tool service")
+                )
+            self.assertEqual(calls, [], "runner must never be invoked")
+
+    def test_no_http_listener_is_created_for_remote_transport(self):
+        """Nothing in the refusal path touches uvicorn or a socket bind."""
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            import socket
+
+            bound_sockets = []
+            real_bind = socket.socket.bind
+
+            def _tripwire(self, addr):  # pragma: no cover - must not run
+                bound_sockets.append(addr)
+                return real_bind(self, addr)
+
+            with patch.object(socket.socket, "bind", _tripwire):
+                with self.assertRaises(guard.TransportExecutionError):
+                    guard.authorize_transport_execution("tool service")
+            self.assertEqual(bound_sockets, [], "no socket may be bound")
+
+    def test_no_mutation_is_authorized_after_the_denial(self):
+        """The denial leaves no partial state that would let a tool dispatch."""
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            with self.assertRaises(guard.TransportExecutionError):
+                guard.authorize_transport_execution("tool service")
+            # Serve stays unauthorized on every subsequent query.
+            self.assertFalse(guard.assess_serve_authorization()["allowed"])
+            self.assertFalse(guard.native_runtime_status()["serve_authorized"])
+            with self.assertRaises(guard.TransportExecutionError):
+                guard.authorize_transport_execution("tool service")
+
+    # -- B2: the decision genuinely consumes bound_transport ---------------
+
+    def test_serve_decision_consumes_bound_transport(self):
+        """Changing only bound_transport flips the verdict."""
+        with _ProductionBind() as guard:
+            guard.bind_native_mcp_transport()
+            self.assertTrue(guard.assess_serve_authorization()["allowed"])
+            with patch.object(
+                guard,
+                "bound_transport",
+                return_value=mcp_transport_config.REMOTE_TRANSPORT,
+            ):
+                verdict = guard.assess_serve_authorization()
+                self.assertFalse(verdict["allowed"])
+                self.assertEqual(
+                    verdict["transport"], mcp_transport_config.REMOTE_TRANSPORT
+                )
+                with self.assertRaises(guard.TransportExecutionError):
+                    guard.authorize_transport_execution("tool service")
+
+    def test_serve_verdict_reports_the_bound_transport(self):
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            verdict = guard.assess_serve_authorization()
+            self.assertEqual(
+                verdict["transport"], mcp_transport_config.REMOTE_TRANSPORT
+            )
+            self.assertTrue(verdict["recognized"])
+            self.assertFalse(verdict["executable"])
+
+    # -- earlier and later boundaries are unchanged ------------------------
+
+    def test_unregistered_identifier_still_fails_at_bind_not_at_serve(self):
+        with _ProductionBind(
+            {mcp_transport_config.TRANSPORT_ENV: "carrier-pigeon"}
+        ) as guard:
+            with self.assertRaises(guard.UnsanctionedRuntimeError) as ctx:
+                guard.bind_native_mcp_transport()
+            self.assertIn("not a registered MCP transport", str(ctx.exception))
+            self.assertIsNone(guard.bound_transport())
+
+    def test_unbound_execution_keeps_the_pre_existing_failure(self):
+        with _ProductionBind() as guard:
+            with self.assertRaises(guard.UnsanctionedRuntimeError) as ctx:
+                guard.authorize_transport_execution("tool service")
+            self.assertIn("No MCP transport is bound", str(ctx.exception))
+            self.assertNotIsInstance(ctx.exception, guard.TransportExecutionError)
+
+    def test_transport_execution_error_is_caught_by_existing_handlers(self):
+        """Subclassing keeps every pre-existing fail-closed handler correct."""
+        self.assertTrue(
+            issubclass(
+                mcp_daemon_guard.TransportExecutionError,
+                mcp_daemon_guard.UnsanctionedRuntimeError,
+            )
+        )
+
+    def test_test_mode_runtime_is_not_servable(self):
+        """The pytest-only record is outside the recognized and executable sets."""
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        mcp_daemon_guard.install_test_native_runtime()
+        self.assertNotIn(
+            mcp_daemon_guard.bound_transport(),
+            mcp_transport_config.SUPPORTED_TRANSPORTS,
+        )
+        self.assertFalse(mcp_daemon_guard.assess_serve_authorization()["allowed"])
+
+    def test_serve_authorization_does_not_leak_across_runtimes(self):
+        """A later runtime's verdict never reflects an earlier one."""
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                )
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            self.assertFalse(guard.assess_serve_authorization()["allowed"])
+        with _ProductionBind() as guard:
+            guard.bind_native_mcp_transport()
+            self.assertTrue(guard.assess_serve_authorization()["allowed"])
+        mcp_daemon_guard.clear_native_runtime_for_tests()
+        self.assertEqual(
+            mcp_daemon_guard.assess_serve_authorization()["blocker_kind"],
+            mcp_transport_config.BLOCKER_TRANSPORT_NOT_BOUND,
+        )
+
+    def test_refusal_carries_no_credential_material(self):
+        with _ProductionBind(
+            {
+                mcp_transport_config.TRANSPORT_ENV: (
+                    mcp_transport_config.REMOTE_TRANSPORT
+                ),
+                "GITEA_TOKEN": "super-secret-value",
+            }
+        ) as guard:
+            guard.bind_native_mcp_transport()
+            with self.assertRaises(guard.TransportExecutionError) as ctx:
+                guard.authorize_transport_execution("tool service")
+            blob = str(ctx.exception) + repr(ctx.exception.assessment)
+            self.assertNotIn("super-secret-value", blob)
+            self.assertNotIn("GITEA_TOKEN", blob)
+
+
+class TestEntrypointWiring(unittest.TestCase):
+    """The live entrypoint must use the seam and the execution guard."""
+
+    def test_entrypoint_binds_without_a_literal_transport(self):
+        text = (REPO_ROOT / "gitea_mcp_server.py").read_text(encoding="utf-8")
+        self.assertIn("mcp_daemon_guard.bind_native_mcp_transport()", text)
+        self.assertNotIn('bind_native_mcp_transport(transport="stdio")', text)
+
+    def test_entrypoint_serves_only_through_the_execution_guard(self):
+        text = (REPO_ROOT / "gitea_mcp_server.py").read_text(encoding="utf-8")
+        self.assertIn(
+            "mcp.run(transport=mcp_daemon_guard.authorize_transport_execution", text
+        )
+        self.assertNotIn('mcp.run(transport="stdio")', text)
+        self.assertNotIn(
+            "mcp.run(transport=mcp_daemon_guard.assert_transport_bound", text
+        )
+
+    def test_every_run_call_in_production_goes_through_the_guard(self):
+        """Glob the production surface: no serve site may bypass the guard."""
+        offenders: list[str] = []
+        run_sites = 0
+        for path in sorted(REPO_ROOT.glob("*.py")):
+            for lineno, line in enumerate(
+                path.read_text(encoding="utf-8").splitlines(), start=1
+            ):
+                code = line.split("#", 1)[0]
+                if "mcp.run(" not in code:
+                    continue
+                run_sites += 1
+                if "authorize_transport_execution" not in code:
+                    offenders.append(f"{path.name}:{lineno}: {line.strip()}")
+        self.assertEqual(run_sites, 1, "expected exactly one serve site")
+        self.assertEqual(offenders, [], "\n".join(offenders))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_issue_956_threat_model.py

@@ -0,0 +1,323 @@
+"""Validation tooling for the remote-MCP threat model (#956).
+
+#956 requires that "every boundary claim [is] traceable to a file and line
+anchor that resolves at the reviewed commit". A prose document cannot enforce
+that about itself, and #930 demonstrated the failure mode: its inventory cited
+``gitea_mcp_server.py`` anchors generated at ``7bf4f125`` which no longer point
+at the described code at ``aad5c8b4``. Nothing failed, because nothing checked.
+
+These tests are that check. They enforce, in both directions:
+
+* every ``file.py:NNN`` anchor cited in the prose is declared in the fixture;
+* every declared anchor resolves — the file exists, the line exists, and the
+  source line actually contains the substring the fixture claims for it;
+* the document's structural obligations (assets, adversaries, boundaries,
+  credential rows, the co-residency ruling, and the child mapping) are present
+  and internally consistent.
+
+A refactor that shifts a line number therefore breaks the suite instead of
+silently rotting the security documentation.
+"""
+
+import json
+import os
+import re
+import unittest
+
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+DOC_PATH = os.path.join(REPO_ROOT, "docs", "remote-mcp", "threat-model.md")
+FIXTURE_PATH = os.path.join(
+    REPO_ROOT, "docs", "remote-mcp", "threat-model-anchors.json"
+)
+
+# ``module.py:123`` as it appears inside markdown inline code spans.
+ANCHOR_RE = re.compile(r"`([A-Za-z0-9_./-]+\.py):(\d+)`")
+
+# The epic children this document must map to a boundary (#929 children 2-10).
+REQUIRED_CHILDREN = [931, 932, 933, 934, 935, 936, 937, 938, 939]
+
+# The adversaries #956 names explicitly.
+REQUIRED_ADVERSARIES = [
+    "compromised LLM client",
+    "prompt injection",
+    "malicious tool arguments",
+    "network attacker",
+    "curious operator",
+]
+
+
+def _read(path):
+    with open(path, "r", encoding="utf-8") as fh:
+        return fh.read()
+
+
+def _heading_re(title):
+    """Match a level-2 heading by title, with or without section numbering.
+
+    The document numbers its sections ('## 6. Decomposition ruling'), so an
+    exact-substring assertion would break on renumbering without the document
+    having actually lost anything.
+    """
+    return re.compile(
+        r"^##\s+(?:\d+\.\s+)?" + re.escape(title), re.MULTILINE
+    )
+
+
+def _section_body(doc, title):
+    """Return the text of section *title*, bounded by the next level-2 heading.
+
+    Bounding matters: an unbounded slice runs to end-of-document, so the
+    walkthrough tables in a later section leak into the child-to-boundary
+    mapping and satisfy its coverage check with rows that assign no owner.
+    """
+    match = _heading_re(title).search(doc)
+    if match is None:
+        return None
+    rest = doc[match.end():]
+    nxt = re.search(r"^##\s", rest, re.MULTILINE)
+    return rest[: nxt.start()] if nxt else rest
+
+
+def _source_line(rel_path, lineno):
+    """Return the 1-based *lineno* of *rel_path*, or None if out of range."""
+    abs_path = os.path.join(REPO_ROOT, rel_path)
+    if not os.path.exists(abs_path):
+        return None
+    with open(abs_path, "r", encoding="utf-8", errors="replace") as fh:
+        for idx, line in enumerate(fh, start=1):
+            if idx == lineno:
+                return line
+    return None
+
+
+class ThreatModelFixtureTests(unittest.TestCase):
+    """The fixture itself must be well-formed before it can prove anything."""
+
+    def setUp(self):
+        self.fixture = json.loads(_read(FIXTURE_PATH))
+
+    def test_fixture_declares_a_generation_commit(self):
+        sha = self.fixture.get("generated_against_commit") or ""
+        self.assertRegex(
+            sha,
+            r"^[0-9a-f]{40}$",
+            "the fixture must record the full commit its anchors were taken at",
+        )
+
+    def test_fixture_anchors_are_unique_and_well_formed(self):
+        seen = set()
+        for entry in self.fixture["anchors"]:
+            anchor = entry["anchor"]
+            self.assertNotIn(anchor, seen, f"duplicate anchor entry: {anchor}")
+            seen.add(anchor)
+            self.assertRegex(anchor, r"^[A-Za-z0-9_./-]+\.py:[1-9]\d*$", anchor)
+            self.assertTrue(
+                (entry.get("expect") or "").strip(),
+                f"anchor {anchor} declares no 'expect' substring, so it proves nothing",
+            )
+
+
+class ThreatModelAnchorResolutionTests(unittest.TestCase):
+    """#956 required positive test: every anchor resolves at the reviewed commit."""
+
+    def setUp(self):
+        self.fixture = json.loads(_read(FIXTURE_PATH))
+        self.doc = _read(DOC_PATH)
+
+    def test_every_declared_anchor_resolves_to_the_claimed_source_line(self):
+        failures = []
+        for entry in self.fixture["anchors"]:
+            rel_path, _, raw_lineno = entry["anchor"].partition(":")
+            lineno = int(raw_lineno)
+            line = _source_line(rel_path, lineno)
+            if line is None:
+                failures.append(f"{entry['anchor']}: file or line does not exist")
+                continue
+            if entry["expect"] not in line:
+                failures.append(
+                    f"{entry['anchor']}: expected {entry['expect']!r}, "
+                    f"found {line.strip()!r}"
+                )
+        self.assertEqual(
+            [], failures, "unresolved threat-model anchors:\n" + "\n".join(failures)
+        )
+
+    def test_every_anchor_cited_in_the_document_is_declared_in_the_fixture(self):
+        declared = {e["anchor"] for e in self.fixture["anchors"]}
+        cited = {f"{m.group(1)}:{m.group(2)}" for m in ANCHOR_RE.finditer(self.doc)}
+        undeclared = sorted(cited - declared)
+        self.assertEqual(
+            [],
+            undeclared,
+            "document cites anchors that no test verifies: " + ", ".join(undeclared),
+        )
+
+    def test_the_document_actually_cites_anchors(self):
+        cited = {f"{m.group(1)}:{m.group(2)}" for m in ANCHOR_RE.finditer(self.doc)}
+        self.assertGreaterEqual(
+            len(cited),
+            30,
+            "a boundary document with almost no anchors is not traceable",
+        )
+
+    def test_unresolvable_anchor_is_detected(self):
+        """Negative control: the checker must fail on a deliberately bad anchor.
+
+        Without this, a checker that silently passed everything would look
+        identical to a correct one.
+        """
+        self.assertIsNone(_source_line("gitea_config.py", 10**9))
+        self.assertIsNone(_source_line("no_such_module_for_956.py", 1))
+        real = _source_line("gitea_config.py", 54)
+        self.assertIsNotNone(real)
+        self.assertNotIn("this substring is not on that line", real)
+
+
+class ThreatModelStructureTests(unittest.TestCase):
+    """The document must contain what #956's acceptance criteria demand."""
+
+    def setUp(self):
+        self.doc = _read(DOC_PATH)
+
+    def test_records_the_commit_it_was_generated_against(self):
+        fixture = json.loads(_read(FIXTURE_PATH))
+        self.assertIn(
+            fixture["generated_against_commit"],
+            self.doc,
+            "the document must state the commit its anchors resolve at",
+        )
+
+    def test_names_every_required_adversary(self):
+        low = self.doc.lower()
+        for adversary in REQUIRED_ADVERSARIES:
+            self.assertIn(adversary.lower(), low, f"adversary not covered: {adversary}")
+
+    def test_maps_every_epic_child_from_two_through_ten(self):
+        for number in REQUIRED_CHILDREN:
+            self.assertIn(
+                f"#{number}",
+                self.doc,
+                f"epic child #{number} is not mapped to a boundary",
+            )
+
+    def test_credential_rows_declare_holder_boundary_and_blast_radius(self):
+        for column in ("Holder", "Boundary", "Blast radius"):
+            self.assertIn(
+                column,
+                self.doc,
+                f"the credential inventory must state each credential's {column.lower()}",
+            )
+
+    def test_states_an_explicit_co_residency_ruling(self):
+        """AC3/AC5: an explicit ruling, not an implication."""
+        self.assertIsNotNone(
+            _heading_re("Decomposition ruling").search(self.doc),
+            "the document must contain an explicit decomposition-ruling section",
+        )
+        for service in ("Jenkins", "GlitchTip", "Sentry", "database"):
+            self.assertIn(service, self.doc, f"ruling does not address {service}")
+        self.assertRegex(
+            self.doc,
+            r"D1\b.*must not",
+            "the ruling must state the prohibition, not merely discuss it",
+        )
+
+    def test_contains_the_compromised_client_walkthrough(self):
+        """#956 required negative/adversarial test."""
+        self.assertIsNotNone(
+            _heading_re("Adversarial walkthrough").search(self.doc),
+            "the required compromised-client walkthrough is missing",
+        )
+        self.assertIn("Before the migration", self.doc)
+        self.assertIn("After the migration", self.doc)
+
+    def test_every_boundary_states_what_it_protects_and_what_crossing_requires(self):
+        boundary_ids = set(re.findall(r"\bB(\d+)\b", self.doc))
+        self.assertGreaterEqual(
+            len(boundary_ids), 5, "too few trust boundaries to be a decomposition"
+        )
+        for column in (
+            "Protects",
+            "Crossing requires today",
+            "Crossing must require remotely",
+        ):
+            self.assertIn(column, self.doc, f"boundary table is missing '{column}'")
+
+    def test_declares_itself_documentation_only(self):
+        self.assertIn("documentation only", self.doc.lower())
+
+
+class ThreatModelConsistencyTests(unittest.TestCase):
+    """Counts stated in prose must match the rows actually present."""
+
+    def setUp(self):
+        self.doc = _read(DOC_PATH)
+
+    def _declared_ids(self, prefix):
+        # Table rows begin '| CR1 |' / '| B3 |' / '| A2 |'.
+        return sorted(
+            {
+                int(m)
+                for m in re.findall(
+                    r"^\|\s*%s(\d+)\s*\|" % prefix, self.doc, re.MULTILINE
+                )
+            }
+        )
+
+    def test_identifier_sequences_have_no_gaps(self):
+        for prefix, label in (
+            ("A", "assets"),
+            ("B", "boundaries"),
+            ("CR", "credentials"),
+        ):
+            ids = self._declared_ids(prefix)
+            self.assertTrue(ids, f"no {label} declared")
+            self.assertEqual(
+                list(range(1, len(ids) + 1)),
+                ids,
+                f"{label} identifiers must run 1..n with no gaps; got {ids}",
+            )
+
+    def test_stated_credential_count_matches_the_rows(self):
+        ids = self._declared_ids("CR")
+        match = re.search(r"(\d+)\s+credential(?:s)? in total", self.doc)
+        self.assertIsNotNone(match, "the credential inventory must state its own total")
+        self.assertEqual(
+            len(ids),
+            int(match.group(1)),
+            "stated credential total disagrees with the number of rows",
+        )
+
+    def test_every_boundary_is_owned_by_at_least_one_child(self):
+        """Each boundary must be owned by a child *in the mapping table*.
+
+        Scanning the whole section would let a prose summary line ("Boundary
+        coverage: ... B5 (#936)") satisfy the assertion while the table row
+        that actually assigns the owner had been emptied — verified by
+        deliberately blanking a row and watching a whole-section check still
+        pass. Only table rows count.
+        """
+        mapping_section = _section_body(self.doc, "Child-to-boundary mapping")
+        self.assertIsNotNone(
+            mapping_section, "child-to-boundary mapping section is missing"
+        )
+        rows = [
+            line
+            for line in mapping_section.splitlines()
+            if line.lstrip().startswith("|") and re.search(r"#93\d", line)
+        ]
+        self.assertGreaterEqual(
+            len(rows), len(REQUIRED_CHILDREN), "mapping table has too few child rows"
+        )
+        mapped = set(re.findall(r"\bB(\d+)\b", "\n".join(rows)))
+        declared = {str(i) for i in self._declared_ids("B")}
+        unmapped = sorted(declared - mapped, key=int)
+        self.assertEqual(
+            [],
+            unmapped,
+            "boundaries with no owning child: " + ", ".join("B" + u for u in unmapped),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()