fix(mcp): make capability resolver side-effect free (Closes #685)

Stale-runtime detection remains fail-closed, but gitea_resolve_task_capability
must never touch mcp_config.json, spawn recovery threads, or call os._exit.

- Remove _trigger_mcp_auto_restart from the read-only diagnostics path
- Return blocker_kind=runtime_reconnect_required with mutation_performed=false
- Keep exact_safe_next_action pointing at IDE/client reconnect when stale
- Add regression suite across author/reviewer/merger/reconciler profiles

docs/architecture/mcp-stable-control-runtime-policy-adr.md

@@ -0,0 +1,198 @@
+# ADR: Stable control runtime vs dev runtime (Gitea MCP)
+
+- **Status:** Accepted (policy effective immediately for LLM sessions; tooling may lag)
+- **Date:** 2026-07-09
+- **Tracking issue:** [#615](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/615)
+- **Related:**
+  - [#543](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/543) / `docs/mcp-namespace-health.md` — client-namespace health
+  - `docs/mcp-namespace-eof-recovery.md` — reconnect-only EOF recovery (no PID kill)
+  - [#558](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/558) / `docs/mcp-daemon-import-guard.md` — sanctioned daemon
+  - [#557](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/557) / `docs/bootstrap-review-path.md` — controller bootstrap for self-hosted fixes
+  - Allocator / control-plane ADR: `docs/architecture/mcp-allocator-control-plane-observability-adr.md` (#613 / PR #614)
+
+## 1. Context
+
+The Gitea MCP server is the **control plane** for real issue/PR mutations (create, comment, lock, review, merge, etc.). When author/reviewer/merger/reconciler sessions kill or restart that process, relaunch it from a feature worktree, or edit the checkout that process loads, operators observe:
+
+- Mid-session identity/preflight resets
+- Stale-runtime vs master parity failures
+- IDE transport EOF / “tool not found” while code on disk has changed
+- Accidental production mutations from experimental code
+
+This ADR separates **stable control runtime** from **dev/test runtime** and defines promotion proof.
+
+## 2. Decision
+
+### 2.1 Stable control runtime
+
+The Gitea MCP server used for **real workflow mutations** is the **stable control runtime**.
+
+Characteristics:
+
+- Loads a known, promoted revision of Gitea-Tools (or the packaged release layout operators designate)
+- Registered in the IDE/client as the production namespaces (`gitea-tools`, `gitea-reviewer`, `gitea-merger`, `gitea-reconciler`, etc.)
+- Holds production profile credentials via sanctioned keychain/env paths only
+
+### 2.2 Dev / test runtime
+
+MCP **server code** development and testing:
+
+- Happens in isolated **`branches/`** worktrees (or other non-stable checkouts)
+- May use a **separate** dev/test MCP runtime/process when process-level testing is required
+- **Must not** be used for real Gitea mutations on production issues/PRs
+
+### 2.3 Forbidden actions (normal sessions)
+
+Normal **author, reviewer, merger, and reconciler** LLM sessions **must not**:
+
+| Forbidden | Why |
+|-----------|-----|
+| Kill the running MCP server process | Drops all concurrent sessions; loses preflight state |
+| Restart / relaunch the MCP server process | Same as kill; causes stale/identity churn mid-workflow |
+| Relaunch MCP from a development worktree | Runs unpromoted code against production mutations |
+| Edit files in the stable runtime checkout | Hot-mutates control plane under concurrent users |
+| Use experimental/dev MCP for real Gitea mutations | Bypasses promotion proof and audit expectations |
+| Bypass or self-reset a stale master-parity gate | The gate is fail-closed; only an operator reload restores parity |
+
+**LLM-allowed vs operator-owned (authoritative split):**
+
+| Actor | May do | Must not do |
+|-------|--------|-------------|
+| **LLM session** | Call tools on the already-running stable namespaces; **client reconnect** after transport EOF (no process kill); pass `worktree_path` / role worktree args; report blockers and stop mutations when unhealthy/stale | Kill, restart, or relaunch any MCP process; bump config mtimes to force reload; edit the stable checkout; switch to a dev MCP for production mutations |
+| **Operator / release-manager** | Supervised restart/reload of the **stable** control runtime; dual-namespace client configuration; §2.4 promotions; incident recovery | — |
+
+EOF / transport recovery for LLM sessions: **client reconnect only** (see `docs/mcp-namespace-eof-recovery.md`). Do not “fix” health by killing PIDs or bumping MCP config mtimes as a normal session procedure.
+
+This ADR **supersedes** any older runbook wording that told the LLM to relaunch or restart the client/MCP as a self-service step. Where `docs/llm-workflow-runbooks.md` (or wiki runbooks) discuss dual-namespace setup or workspace rebind, **process restart/relaunch is operator-owned**; the LLM stops, reports, and waits.
+
+### 2.4 Promotion (operator / release-manager only)
+
+Promotion of a new revision into the stable control runtime is an **explicit operator/release-manager action**, not an LLM self-service step.
+
+A promotion **must record** (issue comment, release note, or promotion ledger):
+
+| Field | Description |
+|-------|-------------|
+| **previous runtime SHA** | Commit previously loaded by stable runtime |
+| **promoted runtime SHA** | Commit after promotion |
+| **source branch/PR** | Where the change was reviewed |
+| **restart/reload method** | How the process was cycled (e.g. supervised restart, client reload) |
+| **health check proof** | Client-namespace probe success (`gitea_whoami` / namespace health) |
+| **identity/profile proof** | Expected profile(s) and username(s) after reload |
+| **workspace/root proof** | Stable checkout path / root matches intended layout |
+| **mutation capability proof** | Required permissions for the target role present; forbidden ops still forbidden |
+| **rollback instructions** | How to restore previous SHA and re-verify health |
+
+Suggested durable marker:
+
+```text
+## MCP STABLE RUNTIME PROMOTION (#615)
+
+Status: COMPLETED | ROLLED_BACK | ABORTED
+Previous-SHA: <full sha>
+Promoted-SHA: <full sha>
+Source-PR: <number>
+Source-Branch: <name>
+Reload-Method: <text>
+Health-Proof: client_namespace whoami OK / assess_mcp_namespace_health OK
+Identity-Proof: profile=<name> user=<name>
+Workspace-Proof: root=<path>
+Mutation-Proof: allowed_ops include <…>; forbidden include <…>
+Rollback: checkout <previous sha>; reload method <…>; re-run health/identity proofs
+Operator: <username>
+Timestamp: <ISO-8601>
+```
+
+### 2.5 Unhealthy stable runtime → stop work
+
+If the stable MCP runtime is **unhealthy**, including any of:
+
+- client-namespace probes fail
+- wrong identity / wrong profile
+- wrong workspace root
+- missing mutation capability for the intended role
+- persistent EOF after **client reconnect**
+- **master parity is stale** (`startup_head` behind on-disk `master` / `restart_required` from the parity gate)
+
+then:
+
+1. **Normal PR / review / merge / issue-mutation work must stop immediately.**
+2. The session **reports** the unhealthy/stale state (tool error, CTH, or operator handoff) with startup vs current head when known.
+3. Do **not** improvise: no LLM process kill/restart, no dev-worktree MCP for production mutations, no env escape hatches, no manual gate bypass.
+4. Resume only after:
+   - an **operator** restores the runtime (see §2.6 for routine post-merge parity reload), **or**
+   - a **controlled** promotion/rollback completes with the §2.4 promotion record, **or**
+   - a controller invokes the narrow **bootstrap review path** (#557) when the defect is self-hosted and documented,
+   - **and** the session re-verifies health (and master parity when applicable) before the next mutation.
+
+### 2.6 Routine post-merge master-parity staleness (operator reload, not promotion)
+
+**Symptom:** After merges land on `master`, a long-lived stable MCP process still runs the pre-merge `startup_head`. The master-parity gate marks the server **stale** / `restart_required` and **blocks mutations**.
+
+**Sanctioned response (authoritative):**
+
+| Step | Actor | Action |
+|------|-------|--------|
+| 1 | LLM session | Mutations stop immediately when the gate reports stale. |
+| 2 | LLM session | Report the stale state (startup head, current master head, that operator reload is required). Do not retry mutations. |
+| 3 | **Operator** | Reload/restart the **stable** control MCP so it loads current `master` (supervised client/daemon reload). |
+| 4 | LLM session | Resume only after startup/current-head parity is verified (e.g. `gitea_get_runtime_context` / parity assessment shows in parity). |
+
+**Not a §2.4 promotion:** Catching the already-designated stable control checkout up to a newly advanced `master` is a **routine operator reload** of the stable runtime. It does **not** require the nine-field promotion ledger. Use §2.4 only when **changing which unpromoted/dev revision** becomes the stable control runtime (new source branch/PR into the stable designation).
+
+**Code note:** `master_parity_gate.py` may still say “restart the server” in machine-facing reason strings. That string names the **operator recovery action**, not an LLM self-service instruction. This ADR and the runbooks define the actor split.
+
+## 3. Relationship to other controls
+
+| Doc / mechanism | Interaction |
+|-----------------|-------------|
+| Namespace health (#543) | Proves IDE client can call tools; does not authorize restart |
+| EOF recovery | Reconnect only; no process kill |
+| Daemon import guard (#558) | Mutations require sanctioned daemon; not a bare shell import |
+| Bootstrap path (#557) | Only controller-authorized exception when live runtime cannot review its own fix |
+| Allocator / control-plane ADR | Coordination DB is separate; still depends on a healthy MCP surface for Gitea writes |
+
+## 4. Consequences
+
+### Positive
+
+- Predictable control plane for concurrent LLMs
+- Clear operator-only promotion gate with rollback
+- Aligns session behavior with health/EOF docs already landed
+
+### Costs
+
+- LLM sessions must wait when runtime is sick (no DIY restart)
+- Operators must maintain promotion discipline and dual-runtime config if they use a dev MCP
+
+### Non-goals
+
+- Does not ban operator-supervised restarts during incidents
+- Does not replace CI or code review for MCP changes
+- Does not authorize editing stable checkout “because tests need a quick fix”
+
+## 5. Implementation follow-ups (optional tooling)
+
+These may land in later issues; the **policy binds sessions now**:
+
+1. Session preflight that refuses mutations if workspace root equals a `branches/` feature worktree configured as “dev only.”
+2. Explicit `runtime_kind=stable|dev` in MCP config and `gitea_whoami` profile metadata.
+3. Promotion checklist script that emits the durable promotion marker fields.
+
+**Not optional (issue #615 acceptance criterion 2):** operator guide and runbooks **must** cross-link this ADR (see §6). Cross-links are documentation acceptance, not deferred tooling.
+
+## 6. Acceptance for this ADR
+
+1. Document merged under `docs/architecture/mcp-stable-control-runtime-policy-adr.md`.
+2. **Operator guide / runbooks cross-link this ADR** (`docs/wiki/Operator-Guide.md`, `docs/wiki/Runbooks.md`, `docs/llm-workflow-runbooks.md`).
+3. Issue #615 references this path.
+4. LLM/operator runbooks treat kill/restart/relaunch-from-worktree as **LLM violations**; process restart is **operator-owned**.
+5. Unhealthy runtime (including **stale master parity**) stops normal mutation work until operator restore/reload, promotion/rollback, or #557 bootstrap — then re-verify parity before mutating.
+6. Routine post-merge parity reload is documented as operator reload (§2.6), not an LLM self-restart and not a full §2.4 promotion.
+
+## 7. Document history
+
+| Date | Change |
+|------|--------|
+| 2026-07-09 | Initial ADR: stable vs dev runtime, forbidden session actions, promotion proof fields, stop-work rule |
+| 2026-07-16 | Review 443 remediation (#615 / PR #616): mandatory cross-links; LLM vs operator restart split; routine post-merge parity staleness (§2.6); stale parity in §2.5 unhealthy triggers |

docs/llm-workflow-runbooks.md

@@ -195,7 +195,7 @@ To avoid the bottleneck of relaunching/restarting the MCP server to switch betwe
   `gitea_reconcile_already_landed_pr` after ancestry proof — not for normal
   review or author workflows.
 
-* **Fallback:** If the dual-profile MCP launcher pattern is not supported or configured in the client, the LLM must relaunch or restart the client/MCP with the correct profile environment variable before claiming or working on any tasks.
+* **Fallback (operator-owned):** If the dual-profile MCP launcher pattern is not supported or configured in the client, **do not** have the LLM relaunch or restart the client/MCP. The LLM **stops** role-switching work, reports that the correct static namespace is missing, and waits for an **operator** to configure dual namespaces or reload the client with the correct `GITEA_MCP_PROFILE` for that role. Process restart/relaunch is operator-owned under the [stable control runtime ADR](architecture/mcp-stable-control-runtime-policy-adr.md) (#615).
 
 ## Setup runbook — interactive menu
 
@@ -1200,10 +1200,13 @@ When a mutation blocks on workspace binding:
 
 1. Read the error — it names the **resolved workspace path**, **role
    namespace**, and **binding source** (tool arg, env var, or process root).
-2. Reconnect or relaunch the correct namespace MCP server from the intended
-   workspace (or set the role-specific env var before launch).
-3. Pass `worktree_path` on reviewer/merger mutation tools when the active
-   branches/ worktree differs from the MCP process root.
+2. **LLM-allowed:** pass `worktree_path` on reviewer/merger mutation tools when
+   the active `branches/` worktree differs from the MCP process root; **client
+   reconnect** after transport EOF only (no process kill).
+3. **Operator-owned:** if the wrong namespace process was launched, or a role-
+   specific `GITEA_*_WORKTREE` must be set at process start, an **operator**
+   reloads/relaunches the correct static namespace MCP. LLM sessions must not
+   kill or restart MCP processes (see [stable control runtime ADR](architecture/mcp-stable-control-runtime-policy-adr.md)).
 4. **Do not** clean, reset, or discard foreign role worktrees to unblock your
    own namespace — that destroys another agent's WIP.
 
@@ -1213,9 +1216,10 @@ When posting a Canonical Thread Handoff after a binding blocker:
 
 - State which namespace was active (author / reviewer / merger / reconciler).
 - Quote the resolved workspace path and binding source from the error.
-- Name the safe reconnect action (relaunch MCP from `branches/...`, set
-  `GITEA_*_WORKTREE`, or pass `worktree_path`).
-- Explicitly note that foreign worktrees must not be cleaned to unblock.
+- Name the safe next action: pass `worktree_path` if that unblocks the tool, or
+  request an **operator** reload of the correct namespace MCP / env binding.
+- Explicitly note that foreign worktrees must not be cleaned to unblock, and
+  that the LLM must not self-restart the MCP process.
 
 ## Safety notes
 
@@ -1226,6 +1230,7 @@ When posting a Canonical Thread Handoff after a binding blocker:
 
 ## Related documents
 
+- [`architecture/mcp-stable-control-runtime-policy-adr.md`](architecture/mcp-stable-control-runtime-policy-adr.md) — stable control runtime vs dev runtime; LLM must not kill/restart MCP; operator-owned reload and promotions; routine post-merge parity staleness (#615).
 - [`reviewer-handoff-consistency.md`](reviewer-handoff-consistency.md) — reject contradictory reviewer handoffs (#501).
 - [`issue-acceptance-gate.md`](issue-acceptance-gate.md) — controller issue-acceptance audit after PR merge (#500).
 - [`../skills/llm-project-workflow/SKILL.md`](../skills/llm-project-workflow/SKILL.md) — portable cross-project LLM workflow skill.

docs/wiki/Operator-Guide.md

@@ -14,6 +14,7 @@ Handbook for LLM operators and human developers using the Gitea-Tools MCP server
 4. **No self-review / no self-merge** — The authenticated Gitea user must not approve or merge a PR they authored.
 5. **Follow the gates** — Prompts express intent; MCP tools enforce safety. Never bypass gates via prompt instructions.
 6. **Global LLM Worktree Rule** — Main checkout stays on `master`/`main`/`dev`; all mutations happen under `branches/`. Prove project root, `cwd`, branch, stable main-checkout branch, and session worktree path before editing. No exceptions.
+7. **Stable control runtime** — Real Gitea mutations use only the **stable** MCP control runtime. LLM sessions must not kill, restart, or relaunch MCP processes, edit the stable checkout, or use a dev MCP for production mutations. See the policy ADR: [mcp-stable-control-runtime-policy-adr.md](../architecture/mcp-stable-control-runtime-policy-adr.md) (#615).
 
 ## Supported Gitea instances
 
@@ -29,4 +30,5 @@ Always pass `remote` explicitly on tool calls. The server default is `dadeschool
 1. `gitea_whoami` — confirm authenticated user and profile.
 2. `gitea_get_runtime_context` — allowed/forbidden operations for this session.
 3. `gitea_resolve_task_capability` — prove the session may perform the planned task.
-4. For reviewer work: dry-run validation (`gitea_dry_run_pr_review`) before live review mutations.
+4. For reviewer work: dry-run validation (`gitea_dry_run_pr_review`) before live review mutations.
+5. Confirm master parity / runtime health when tools report stale or unhealthy control runtime — stop mutations and request an **operator** reload of the stable MCP (see [stable control runtime ADR](../architecture/mcp-stable-control-runtime-policy-adr.md)).

docs/wiki/Runbooks.md

@@ -12,6 +12,17 @@
 4. `gitea_mark_final_review_decision` → approve via `gitea_review_pr`.
 5. `gitea_merge_pr` with pinned head SHA and `confirmation="MERGE PR <n>"`.
 
+## Stable MCP control runtime (#615)
+
+Policy ADR: [mcp-stable-control-runtime-policy-adr.md](../architecture/mcp-stable-control-runtime-policy-adr.md).
+
+| Situation | Who acts | What to do |
+|-----------|----------|------------|
+| Transport EOF / missing tools | LLM | **Client reconnect only** — do not kill PIDs |
+| Wrong profile / dual-namespace missing | Operator | Configure or reload the correct static namespace(s) |
+| Master parity stale after merge | LLM stops + reports; **operator** reloads stable MCP | Resume only after parity re-verified |
+| Promote unpromoted MCP code to stable | Operator / release-manager only | Full §2.4 promotion record |
+
 ## Gitea Wiki sync
 
 The Gitea Wiki mirrors `docs/wiki/` (source of truth). After merging wiki changes:

gitea_mcp_server.py

@@ -13659,36 +13659,18 @@ def gitea_route_task_session(
     )
 
 
-_restart_triggered = False
-
-
-def _trigger_mcp_auto_restart():
-    global _restart_triggered
-    if _restart_triggered or _preflight_in_test_mode():
-        return
-    _restart_triggered = True
-
-    config_path = os.environ.get(
-        "MCP_CONFIG_PATH",
-        os.path.expanduser("~/.gemini/config/mcp_config.json")
-    )
-
-    try:
-        if os.path.exists(config_path):
-            os.utime(config_path, None)
-    except Exception:
-        pass
-
-    import threading
-    import time
-    def delayed_exit():
-        time.sleep(1.0)
-        os._exit(0)
-    threading.Thread(target=delayed_exit, daemon=True).start()
+# #685: resolver stale-runtime detection is report-only. Config touch / os._exit
+# self-recovery was removed from the read-only path (was _trigger_mcp_auto_restart).
+# Recovery is owned exclusively by the IDE/client reconnect path.
 
 
 def _check_mcp_runtimes_diagnostics(task: str, matching_profiles: list[str]) -> list[str]:
-    """Check running runtimes and return errors if they are missing or stale."""
+    """Read-only: report missing or stale MCP runtimes (no config or process mutation).
+
+    #685: Never touches MCP client config, never spawns recovery threads, never
+    calls ``os._exit``. Stale detection remains fail-closed via returned reasons
+    only; the IDE/client owns reconnect/reload.
+    """
     import subprocess
     import re
     from datetime import datetime
@@ -13768,11 +13750,13 @@ def _check_mcp_runtimes_diagnostics(task: str, matching_profiles: list[str]) ->
             }
 
     if self_stale:
-        _trigger_mcp_auto_restart()
+        # #685: report-only — no config utime, no thread, no os._exit.
         reasons.append(
-            "stale-runtime: The active Gitea MCP server process is stale (running code from before changes were merged). "
-            "Auto-restart has been triggered: touched mcp_config.json to reload the daemon. "
-            "The current process will cleanly exit shortly."
+            "stale-runtime: The active Gitea MCP server process is stale "
+            "(running code from before changes were merged). "
+            "Reconnect the IDE/client-managed MCP namespace for this profile "
+            "so it reloads current master. The resolver does not touch "
+            "mcp_config.json, spawn recovery threads, or terminate this process."
         )
 
     if matching_profiles:
@@ -13804,10 +13788,15 @@ def gitea_resolve_task_capability(
     remote: str = "dadeschools",
     host: str | None = None,
 ) -> dict:
-    """Read-only: Resolve which capability, profile, and namespace is required for a Gitea task.
+    """Read-only / side-effect free: resolve capability, profile, and namespace for a task.
 
-    Helps the client or LLM determine the correct namespace or profile before acting,
-    and returns exact next action instructions if the current session is not authorized.
+    Does **not** mutate MCP client configuration, spawn recovery threads, kill
+    processes, or trigger daemon reloads (#685). Stale-runtime detection remains
+    fail-closed: when the serving process is stale the result includes
+    ``blocker_kind=runtime_reconnect_required``, ``restart_required=true``,
+    ``stop_required=true``, and ``mutation_performed=false`` with a precise
+    ``exact_safe_next_action`` pointing at IDE/client reconnect. Recovery is
+    owned by the client reconnect path — never by this resolver.
 
     Args:
         task: The task/action to check (e.g. review_pr, create_issue).
@@ -13992,31 +13981,32 @@ def gitea_resolve_task_capability(
 
     configured = len(matching_profiles) > 0
     available_in_session = allowed_in_current_session
+    runtime_stale_blocker = False
 
     if "PYTEST_CURRENT_TEST" not in os.environ or "GITEA_FORCE_MCP_RUNTIME_CHECK" in os.environ:
         runtime_reasons = _check_mcp_runtimes_diagnostics(task, matching_profiles)
         if runtime_reasons:
             restart_required = True
+            runtime_stale_blocker = True
             reason_msg = "; ".join(runtime_reasons)
-            next_safe_action = (
-                "stale-runtime: Gitea MCP runtime conflict or missing process detected. "
-                "Please fully restart the Gitea MCP server and retry."
-            )
 
     if not allowed_in_current_session:
         if configured and switching:
             restart_required = True
             available_in_session = False
-            reason_msg = (
-                f"{required_role.capitalize()} profile exists but MCP server "
-                "was added after session startup and is not attached."
-            )
+            if not reason_msg:
+                reason_msg = (
+                    f"{required_role.capitalize()} profile exists but MCP server "
+                    "was added after session startup and is not attached."
+                )
         elif not configured:
-            reason_msg = (
-                f"No profile configured with permission '{required_permission}'."
-            )
+            if not reason_msg:
+                reason_msg = (
+                    f"No profile configured with permission '{required_permission}'."
+                )
         elif role_mismatch_reason:
-            reason_msg = role_mismatch_reason
+            if not reason_msg:
+                reason_msg = role_mismatch_reason
     different_namespace_required = False
     next_safe_action = "None; ready for operations."
 
@@ -14042,6 +14032,16 @@ def gitea_resolve_task_capability(
                     "or use the corresponding MCP namespace."
                 )
 
+    # #685: stale-runtime typed remediation wins for exact_next_action when the
+    # serving process/profile inventory is stale — even if permission is OK.
+    if runtime_stale_blocker:
+        next_safe_action = (
+            "blocker_kind=runtime_reconnect_required: reconnect/restart the "
+            "IDE-managed Gitea MCP server for this profile so it reloads current "
+            "master. Do not edit mcp_config.json by hand; the resolver does not "
+            "touch config, spawn recovery threads, or terminate the process."
+        )
+
     # Task/role alignment guards (#167): the requested task, not the
     # available credential, decides what the session may do. A review/merge
     # task under a non-reviewer profile must stop — not silently degrade
@@ -14103,12 +14103,16 @@ def gitea_resolve_task_capability(
         "configured": configured,
         "restart_required": restart_required,
         "stop_required": stop_required or restart_required,
+        # #685: resolver is always side-effect free; never claims mutations.
+        "mutation_performed": False,
         "task_role_guidance": task_role_guidance,
         "matching_configured_profile": matching_profiles,
         "runtime_switching_supported": switching,
         "different_mcp_namespace_required": different_namespace_required,
         "exact_safe_next_action": next_safe_action,
     }
+    if runtime_stale_blocker:
+        result["blocker_kind"] = "runtime_reconnect_required"
     if reason_msg:
         result["reason"] = reason_msg
     if task in ("review_pr", "merge_pr"):

task_capability_map.py

@@ -84,7 +84,7 @@ TASK_CAPABILITY_MAP: dict[str, dict[str, str]] = {
     },
     "adopt_merger_pr_lease": {
         "permission": "gitea.pr.comment",
-        "role": "reviewer",
+        "role": "merger",
     },
     # #691: guarded non-owner cleanup of obsolete comment-backed reviewer leases.
     # Apply path posts lease release + audit comments (gitea.pr.comment).

tests/test_issue_685_side_effect_free_resolver.py

@@ -0,0 +1,326 @@
+"""#685: gitea_resolve_task_capability must be side-effect free.
+
+Stale-runtime detection remains fail-closed, but the resolver must never:
+  * touch mcp_config.json (or any MCP client config)
+  * spawn recovery threads
+  * call os._exit / terminate the serving process
+  * claim that an auto-restart was triggered
+
+Recovery is owned by the IDE/client reconnect path only.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import threading
+import unittest
+from datetime import datetime
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import sys
+
+ROOT = str(Path(__file__).resolve().parent.parent)
+if ROOT not in sys.path:
+    sys.path.insert(0, ROOT)
+
+import gitea_mcp_server as mcp_server
+
+
+ROLE_PROFILES = (
+    ("create_issue", "prgs-author", "author"),
+    ("review_pr", "prgs-reviewer", "reviewer"),
+    ("merge_pr", "prgs-merger", "merger"),
+    ("reconciliation_cleanup", "prgs-reconciler", "reconciler"),
+)
+
+
+def _stale_self_ps_mocks(profile: str = "prgs-author"):
+    """Build subprocess mocks: self PID is stale vs code mtime."""
+    mock_getpid = MagicMock(return_value=12345)
+    mock_exists = MagicMock(return_value=True)
+    code_time = datetime(2026, 7, 8, 14, 0, 0)
+    mock_getmtime = MagicMock(return_value=code_time.timestamp())
+
+    ps_output = (
+        "  PID LSTART COMMAND\n"
+        "12345 Wed Jul  8 13:00:00 2026 /path/to/python mcp_server.py\n"
+    )
+    mock_run_ps = MagicMock()
+    mock_run_ps.stdout = ps_output
+
+    mock_run_env = MagicMock()
+    mock_run_env.stdout = f"GITEA_MCP_PROFILE={profile}"
+
+    mock_run_git = MagicMock()
+    mock_run_git.stdout = "SAME"
+
+    def side_effect(args, **kwargs):
+        if args[0] == "ps" and "eww" in args:
+            return mock_run_env
+        if args[0] == "ps":
+            return mock_run_ps
+        if args[0] == "git":
+            return mock_run_git
+        raise ValueError(f"Unexpected subprocess args: {args}")
+
+    mock_run = MagicMock(side_effect=side_effect)
+    return mock_getpid, mock_exists, mock_getmtime, mock_run
+
+
+class TestIssue685DiagnosticsNoSideEffects(unittest.TestCase):
+    def setUp(self):
+        mcp_server._process_boot_head_sha = None
+
+    def tearDown(self):
+        mcp_server._process_boot_head_sha = None
+
+    @patch.dict(os.environ, {"GITEA_FORCE_MCP_RUNTIME_CHECK": "1"}, clear=False)
+    @patch("subprocess.run")
+    @patch("os.path.getmtime")
+    @patch("os.path.exists")
+    @patch("os.getpid")
+    @patch("os.utime")
+    @patch("threading.Thread")
+    @patch("os._exit")
+    def test_stale_self_does_not_touch_config_or_exit(
+        self,
+        mock_exit,
+        mock_thread,
+        mock_utime,
+        mock_getpid,
+        mock_exists,
+        mock_getmtime,
+        mock_run,
+    ):
+        mock_getpid.return_value = 12345
+        mock_exists.return_value = True
+        mock_getmtime.return_value = datetime(2026, 7, 8, 14, 0, 0).timestamp()
+        mock_run.side_effect = _stale_self_ps_mocks("prgs-author")[3].side_effect
+
+        before_threads = threading.active_count()
+        reasons = mcp_server._check_mcp_runtimes_diagnostics(
+            "create_issue", ["prgs-author"]
+        )
+        after_threads = threading.active_count()
+
+        self.assertTrue(
+            any("stale-runtime" in r and "active Gitea MCP server process is stale" in r
+                for r in reasons),
+            reasons,
+        )
+        # Must not claim auto-restart / config touch
+        blob = " ".join(reasons)
+        self.assertNotIn("Auto-restart has been triggered", blob)
+        self.assertNotIn("touched mcp_config", blob)
+        self.assertNotIn("will cleanly exit", blob)
+
+        mock_utime.assert_not_called()
+        mock_thread.assert_not_called()
+        mock_exit.assert_not_called()
+        self.assertEqual(before_threads, after_threads)
+
+    @patch.dict(os.environ, {"GITEA_FORCE_MCP_RUNTIME_CHECK": "1"}, clear=False)
+    @patch("subprocess.run")
+    @patch("os.path.getmtime")
+    @patch("os.path.exists")
+    @patch("os.getpid")
+    @patch("os.utime")
+    def test_repeated_stale_calls_do_not_trigger_restart_loop(
+        self, mock_utime, mock_getpid, mock_exists, mock_getmtime, mock_run
+    ):
+        mock_getpid.return_value = 12345
+        mock_exists.return_value = True
+        mock_getmtime.return_value = datetime(2026, 7, 8, 14, 0, 0).timestamp()
+        mock_run.side_effect = _stale_self_ps_mocks("prgs-author")[3].side_effect
+
+        for _ in range(5):
+            reasons = mcp_server._check_mcp_runtimes_diagnostics(
+                "create_issue", ["prgs-author"]
+            )
+            self.assertTrue(any("stale-runtime" in r for r in reasons))
+
+        mock_utime.assert_not_called()
+
+    def test_trigger_mcp_auto_restart_removed(self):
+        """#685 AC: auto-restart helper is removed (unreachable from read-only)."""
+        self.assertFalse(hasattr(mcp_server, "_trigger_mcp_auto_restart"))
+        self.assertFalse(hasattr(mcp_server, "_restart_triggered"))
+
+
+class TestIssue685ResolverTypedBlocker(unittest.TestCase):
+    def setUp(self):
+        mcp_server._process_boot_head_sha = None
+
+    def tearDown(self):
+        mcp_server._process_boot_head_sha = None
+        if hasattr(mcp_server, "capability_stop_terminal"):
+            mcp_server.capability_stop_terminal.clear()
+
+    def _resolve_with_stale_runtime(self, task: str, profile_name: str, role: str):
+        allowed = [
+            "gitea.read",
+            "gitea.issue.create",
+            "gitea.issue.comment",
+            "gitea.issue.close",
+            "gitea.branch.create",
+            "gitea.branch.push",
+            "gitea.branch.delete",
+            "gitea.pr.create",
+            "gitea.pr.comment",
+            "gitea.pr.review",
+            "gitea.pr.approve",
+            "gitea.pr.request_changes",
+            "gitea.pr.merge",
+            "gitea.pr.close",
+            "gitea.repo.commit",
+        ]
+        profile = {
+            "profile_name": profile_name,
+            "role": role,
+            "allowed_operations": allowed,
+            "forbidden_operations": [],
+        }
+        config = {
+            "profiles": {
+                profile_name: {
+                    "role": role,
+                    "allowed_operations": allowed,
+                    "forbidden_operations": [],
+                }
+            }
+        }
+
+        mock_getpid, mock_exists, mock_getmtime, mock_run = _stale_self_ps_mocks(
+            profile_name
+        )
+
+        with patch.dict(
+            os.environ,
+            {
+                "GITEA_FORCE_MCP_RUNTIME_CHECK": "1",
+                "GITEA_MCP_PROFILE": profile_name,
+            },
+            clear=False,
+        ), patch.object(mcp_server, "get_profile", return_value=profile), patch.object(
+            mcp_server.gitea_config, "load_config", return_value=config
+        ), patch.object(
+            mcp_server, "_authenticated_username", return_value="test-user"
+        ), patch.object(
+            mcp_server, "_ensure_matching_profile", return_value=None
+        ), patch.object(
+            mcp_server, "record_preflight_check", return_value=None
+        ), patch.object(
+            mcp_server, "record_mutation_authority", return_value=None
+        ), patch.object(
+            mcp_server, "init_review_decision_lock", return_value=None
+        ), patch(
+            "subprocess.run", mock_run
+        ), patch(
+            "os.path.getmtime", mock_getmtime
+        ), patch(
+            "os.path.exists", mock_exists
+        ), patch(
+            "os.getpid", mock_getpid
+        ), patch(
+            "os.utime"
+        ) as mock_utime, patch(
+            "threading.Thread"
+        ) as mock_thread, patch(
+            "os._exit"
+        ) as mock_exit:
+            result = mcp_server.gitea_resolve_task_capability(task=task, remote="prgs")
+            return result, mock_utime, mock_thread, mock_exit
+
+    def test_stale_returns_typed_blocker_fields(self):
+        result, mock_utime, mock_thread, mock_exit = self._resolve_with_stale_runtime(
+            "create_issue", "prgs-author", "author"
+        )
+        self.assertTrue(result.get("restart_required"), result)
+        self.assertTrue(result.get("stop_required"), result)
+        self.assertEqual(result.get("blocker_kind"), "runtime_reconnect_required")
+        self.assertIs(result.get("mutation_performed"), False)
+        action = result.get("exact_safe_next_action") or ""
+        self.assertIn("reconnect", action.lower())
+        self.assertNotIn("None; ready for operations", action)
+        reason = result.get("reason") or ""
+        self.assertIn("stale-runtime", reason)
+        self.assertNotIn("Auto-restart has been triggered", reason)
+        mock_utime.assert_not_called()
+        mock_thread.assert_not_called()
+        mock_exit.assert_not_called()
+
+    def test_all_four_role_profiles_get_same_side_effect_free_contract(self):
+        for task, profile, role in ROLE_PROFILES:
+            with self.subTest(task=task, profile=profile):
+                # Skip tasks that may be unknown on this branch
+                try:
+                    import task_capability_map as tcm
+
+                    tcm.required_permission(task)
+                except Exception:
+                    self.skipTest(f"task {task} not in capability map")
+
+                result, mock_utime, mock_thread, mock_exit = (
+                    self._resolve_with_stale_runtime(task, profile, role)
+                )
+                self.assertTrue(
+                    result.get("restart_required") or result.get("stop_required"),
+                    result,
+                )
+                self.assertEqual(
+                    result.get("blocker_kind"), "runtime_reconnect_required", result
+                )
+                self.assertIs(result.get("mutation_performed"), False, result)
+                mock_utime.assert_not_called()
+                mock_thread.assert_not_called()
+                mock_exit.assert_not_called()
+
+    def test_config_mtime_and_contents_unchanged(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            cfg = os.path.join(tmp, "mcp_config.json")
+            original = '{"servers": {"gitea-author": {}}}'
+            with open(cfg, "w", encoding="utf-8") as fh:
+                fh.write(original)
+            mtime_before = os.path.getmtime(cfg)
+
+            result, mock_utime, mock_thread, mock_exit = self._resolve_with_stale_runtime(
+                "create_issue", "prgs-author", "author"
+            )
+            # Force-path also must not use real utime when diagnostics runs
+            with open(cfg, encoding="utf-8") as fh:
+                after = fh.read()
+            self.assertEqual(after, original)
+            self.assertEqual(os.path.getmtime(cfg), mtime_before)
+            mock_utime.assert_not_called()
+            self.assertTrue(result.get("restart_required"), result)
+
+
+class TestIssue685MutationGatesStillFailClosed(unittest.TestCase):
+    def test_parity_stale_still_reports_restart_required(self):
+        """Mutation-facing parity gate remains fail-closed when heads differ."""
+        import master_parity_gate as mpg
+
+        out = mpg.assess_master_parity(
+            {"startup_head": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},
+            "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+        )
+        self.assertFalse(out.get("in_parity"))
+        self.assertTrue(out.get("restart_required") or out.get("stale"))
+
+
+class TestIssue685DocstringReadOnlyContract(unittest.TestCase):
+    def test_resolve_docstring_declares_side_effect_free(self):
+        doc = mcp_server.gitea_resolve_task_capability.__doc__ or ""
+        lower = doc.lower()
+        self.assertTrue(
+            "side-effect" in lower or "read-only" in lower or "does not mutate" in lower,
+            doc,
+        )
+        self.assertNotIn("auto-restart", lower)
+        self.assertNotIn("os._exit", lower)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_mcp_stale_runtime.py

@@ -111,21 +111,13 @@ class TestMcpStaleRuntime(unittest.TestCase):
         reasons = gitea_mcp_server._check_mcp_runtimes_diagnostics("create_issue", ["prgs-author"])
         self.assertTrue(any("stale-runtime: The active Gitea MCP server process is stale" in r for r in reasons))
 
-    @patch("threading.Thread")
-    @patch("os.utime")
-    @patch("os.path.exists")
-    @patch.dict("os.environ", {"MCP_CONFIG_PATH": "/tmp/mcp_config.json"})
-    def test_auto_restart_trigger_touches_and_spawns(self, mock_exists, mock_utime, mock_thread):
-        mock_exists.return_value = True
-        gitea_mcp_server._restart_triggered = False
-
-        # Ensure we are not skipped in test mode for testing purposes
-        with patch("gitea_mcp_server._preflight_in_test_mode", return_value=False):
-            gitea_mcp_server._trigger_mcp_auto_restart()
-
-        mock_utime.assert_called_once_with("/tmp/mcp_config.json", None)
-        mock_thread.assert_called_once()
-        self.assertTrue(gitea_mcp_server._restart_triggered)
+    def test_auto_restart_helper_removed_from_read_only_path(self):
+        """#685: config-touch / os._exit self-recovery is no longer on the server."""
+        self.assertFalse(
+            hasattr(gitea_mcp_server, "_trigger_mcp_auto_restart"),
+            "_trigger_mcp_auto_restart must not remain (side-effect-free resolver)",
+        )
+        self.assertFalse(hasattr(gitea_mcp_server, "_restart_triggered"))
 
 
 if __name__ == "__main__":

tests/test_stable_control_runtime_policy_docs.py

@@ -0,0 +1,139 @@
+"""Documentation acceptance for the stable control runtime ADR (#615 / PR #616).
+
+Enforces review 443 remediation:
+
+* F1 — operator guide / runbooks cross-link the ADR (issue #615 AC2).
+* F2 — LLM sessions are not instructed to kill/restart/relaunch MCP; process
+  restart is operator-owned; ADR is the authoritative split.
+* F3 — routine post-merge master-parity staleness has a sanctioned response
+  (stop → report → operator reload → re-verify parity) and is not a full
+  promotion ledger requirement.
+"""
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+ADR = (
+    REPO_ROOT
+    / "docs"
+    / "architecture"
+    / "mcp-stable-control-runtime-policy-adr.md"
+)
+ADR_REL = "architecture/mcp-stable-control-runtime-policy-adr.md"
+ADR_BASENAME = "mcp-stable-control-runtime-policy-adr.md"
+
+CROSS_LINK_DOCS = (
+    REPO_ROOT / "docs" / "wiki" / "Operator-Guide.md",
+    REPO_ROOT / "docs" / "wiki" / "Runbooks.md",
+    REPO_ROOT / "docs" / "llm-workflow-runbooks.md",
+)
+
+
+def _read(path: Path) -> str:
+    assert path.is_file(), f"missing {path.relative_to(REPO_ROOT)}"
+    return path.read_text(encoding="utf-8")
+
+
+def test_adr_exists_with_policy_core():
+    text = _read(ADR)
+    assert text.lstrip().startswith("#"), "ADR lacks a title"
+    assert "#615" in text
+    assert "stable control runtime" in text.lower()
+    assert "2.3" in text and "2.4" in text and "2.5" in text and "2.6" in text
+
+
+def test_f1_operator_docs_cross_link_adr():
+    for path in CROSS_LINK_DOCS:
+        text = _read(path)
+        assert ADR_BASENAME in text, (
+            f"{path.relative_to(REPO_ROOT)} must cross-link {ADR_BASENAME} "
+            f"(issue #615 acceptance criterion 2)"
+        )
+
+
+def test_f1_adr_lists_cross_links_as_acceptance_not_optional_tooling():
+    text = _read(ADR)
+    # Acceptance section must require guide/runbook cross-links.
+    assert "Operator guide / runbooks cross-link" in text or (
+        "operator guide" in text.lower() and "cross-link" in text.lower()
+        and "Acceptance" in text
+    )
+    # Cross-link must not remain only as optional tooling item #4.
+    optional = text.split("## 5. Implementation follow-ups", 1)[-1].split(
+        "## 6. Acceptance", 1
+    )[0]
+    assert "Operator Guide wiki cross-link to this ADR" not in optional, (
+        "ADR §5 must not list operator-guide cross-link as optional tooling"
+    )
+    assert "Not optional" in text or "must** cross-link" in text.lower() or (
+        "must cross-link" in text.lower()
+    )
+
+
+def test_f2_runbook_fallback_is_operator_owned_not_llm_restart():
+    runbooks = _read(REPO_ROOT / "docs" / "llm-workflow-runbooks.md")
+    # Forbidden historical self-service instruction.
+    forbidden = (
+        "the LLM must relaunch or restart the client/MCP with the correct "
+        "profile environment variable before claiming or working on any tasks"
+    )
+    assert forbidden not in runbooks, (
+        "llm-workflow-runbooks must not instruct the LLM to relaunch/restart MCP"
+    )
+    assert "operator-owned" in runbooks.lower() or "Operator-owned" in runbooks
+    assert ADR_BASENAME in runbooks
+
+
+def test_f2_workspace_rebind_does_not_require_llm_process_relaunch():
+    runbooks = _read(REPO_ROOT / "docs" / "llm-workflow-runbooks.md")
+    section = runbooks.split("### Safe reconnect / rebind procedure", 1)[-1]
+    section = section.split("## Safety notes", 1)[0]
+    # Must not tell the LLM alone to relaunch the MCP process as step 2.
+    assert "Reconnect or relaunch the correct namespace MCP server from the intended" not in section
+    assert "Operator-owned" in section or "operator" in section.lower()
+    assert "worktree_path" in section
+    collapsed = " ".join(section.lower().split())
+    assert "client reconnect" in collapsed
+
+
+def test_f2_adr_forbids_llm_restart_and_supersedes_self_service_relaunch():
+    text = _read(ADR)
+    lower = text.lower()
+    assert "must not" in lower and "restart" in lower
+    assert "operator" in lower and "reload" in lower
+    assert "supersedes" in lower
+    assert "llm" in lower
+
+
+def test_f3_adr_defines_post_merge_parity_staleness_response():
+    text = _read(ADR)
+    lower = text.lower()
+    assert "2.6" in text
+    assert "post-merge" in lower or "post merge" in lower
+    assert "parity" in lower and "stale" in lower
+    # Sanctioned steps: stop, report, operator reload, re-verify.
+    assert "stop" in lower
+    assert "report" in lower
+    assert "operator" in lower
+    assert "parity is verified" in lower or "re-verif" in lower or (
+        "startup/current-head" in lower
+    )
+    # Not a full promotion ledger for routine reload.
+    assert "not a §2.4 promotion" in lower or "not a section 2.4 promotion" in lower or (
+        "not a §2.4" in text or "Not a §2.4 promotion" in text
+    )
+    # Stale parity listed among unhealthy triggers.
+    assert "master parity is stale" in lower or "stale master parity" in lower
+
+
+def test_f3_adr_forbids_llm_bypass_of_parity_gate():
+    text = _read(ADR)
+    lower = text.lower()
+    assert "bypass" in lower or "self-reset" in lower or "self-service" in lower
+    assert "parity" in lower
+
+
+def test_cross_links_do_not_embed_secrets_or_raw_hosts_in_wiki_snippets():
+    for path in CROSS_LINK_DOCS:
+        text = _read(path)
+        for marker in ("ghp_", "BEGIN PRIVATE KEY", "Authorization: Bearer"):
+            assert marker not in text, f"{path} contains {marker!r}"

tests/test_task_capability_role_invariants.py

@@ -0,0 +1,205 @@
+"""Invariant tests pinning task_capability_map role assignments (#722/#723).
+
+Added with the operator-authorized break-glass repair for incident #722:
+commit 970e68b remapped ten reviewer tasks to ``role="merger"`` while every
+configured merger profile forbids the review permissions, so no configured
+profile could resolve any formal review task (``matching_configured_profile``
+was empty repository-wide). These tests fail loudly if that class of
+regression recurs:
+
+- every role-exclusive formal-review task must be satisfiable by at least one
+  canonical role profile (permission AND role together);
+- the capability map must agree with ``role_session_router`` task sets;
+- ``adopt_merger_pr_lease`` stays merger-only (the legitimate hunk of
+  970e68b, preserved by the repair);
+- merger profiles must not be able to resolve review_pr/approve_pr.
+"""
+
+import unittest
+
+import gitea_config
+from role_session_router import MERGER_TASKS, REVIEWER_TASKS
+from task_capability_map import required_permission, required_role
+
+# Canonical role-profile permission shape. Mirrors the configured
+# author/reviewer/merger/reconciler profiles (profiles.json v2 role split):
+# reviewers review/approve/request changes but never merge; mergers merge but
+# never review/approve/request changes.
+CANONICAL_ROLE_PROFILES = {
+    "author": {
+        "allowed": [
+            "gitea.read",
+            "gitea.branch.create",
+            "gitea.branch.push",
+            "gitea.repo.commit",
+            "gitea.pr.create",
+            "gitea.pr.comment",
+            "gitea.issue.create",
+            "gitea.issue.comment",
+            "gitea.issue.close",
+        ],
+        "forbidden": [
+            "gitea.pr.approve",
+            "gitea.pr.request_changes",
+            "gitea.pr.merge",
+        ],
+    },
+    "reviewer": {
+        "allowed": [
+            "gitea.read",
+            "gitea.pr.review",
+            "gitea.pr.approve",
+            "gitea.pr.request_changes",
+            "gitea.pr.comment",
+            "gitea.issue.comment",
+        ],
+        "forbidden": [
+            "gitea.branch.create",
+            "gitea.branch.push",
+            "gitea.repo.commit",
+            "gitea.pr.create",
+            "gitea.pr.merge",
+        ],
+    },
+    "merger": {
+        "allowed": [
+            "gitea.read",
+            "gitea.pr.merge",
+            "gitea.pr.comment",
+            "gitea.issue.comment",
+        ],
+        "forbidden": [
+            "gitea.branch.create",
+            "gitea.branch.push",
+            "gitea.repo.commit",
+            "gitea.pr.create",
+            "gitea.pr.approve",
+            "gitea.pr.review",
+            "gitea.pr.request_changes",
+        ],
+    },
+    "reconciler": {
+        "allowed": [
+            "gitea.read",
+            "gitea.pr.close",
+            "gitea.pr.comment",
+            "gitea.issue.comment",
+            "gitea.branch.delete",
+            "gitea.decision_lock.irrecoverable_recovery",
+        ],
+        "forbidden": [
+            "gitea.pr.approve",
+            "gitea.pr.merge",
+            "gitea.pr.review",
+            "gitea.pr.request_changes",
+            "gitea.pr.create",
+            "gitea.branch.create",
+            "gitea.branch.push",
+            "gitea.repo.commit",
+        ],
+    },
+}
+
+# Role-exclusive formal-review tasks (mirrors the resolver's role-exclusive
+# handling for review work): permission alone is not enough — the profile's
+# role kind must also match, so both dimensions are pinned here.
+FORMAL_REVIEW_TASKS = (
+    "review_pr",
+    "approve_pr",
+    "request_changes_pr",
+    "blind_pr_queue_review",
+    "pr_queue_cleanup",
+    "pr-queue-cleanup",
+)
+
+
+def _profile_satisfies(role_name, task):
+    """True when the canonical *role_name* profile can perform *task*."""
+    profile = CANONICAL_ROLE_PROFILES[role_name]
+    ok, _reason = gitea_config.check_operation(
+        required_permission(task), profile["allowed"], profile["forbidden"]
+    )
+    return ok and role_name == required_role(task)
+
+
+class TestFormalReviewProfileCoverage(unittest.TestCase):
+    """#722: some configured profile must be able to formally review."""
+
+    def test_every_formal_review_task_has_a_satisfying_role_profile(self):
+        for task in FORMAL_REVIEW_TASKS:
+            with self.subTest(task=task):
+                satisfying = [
+                    role
+                    for role in CANONICAL_ROLE_PROFILES
+                    if _profile_satisfies(role, task)
+                ]
+                self.assertTrue(
+                    satisfying,
+                    f"no canonical role profile satisfies both permission "
+                    f"{required_permission(task)!r} and role "
+                    f"{required_role(task)!r} for task {task!r} — formal "
+                    f"review would be impossible for every configured "
+                    f"profile (incident #722)",
+                )
+
+    def test_formal_review_tasks_are_reviewer_role(self):
+        for task in FORMAL_REVIEW_TASKS:
+            with self.subTest(task=task):
+                self.assertEqual(required_role(task), "reviewer")
+
+
+class TestMapRouterAgreement(unittest.TestCase):
+    """#723 AC2: the map and the role session router must not drift."""
+
+    def test_reviewer_tasks_map_to_reviewer_role(self):
+        for task in sorted(REVIEWER_TASKS):
+            with self.subTest(task=task):
+                self.assertEqual(
+                    required_role(task),
+                    "reviewer",
+                    f"router classifies {task!r} as a reviewer task but the "
+                    f"capability map assigns role {required_role(task)!r}",
+                )
+
+    def test_merger_tasks_map_to_merger_role(self):
+        for task in sorted(MERGER_TASKS):
+            with self.subTest(task=task):
+                self.assertEqual(
+                    required_role(task),
+                    "merger",
+                    f"router classifies {task!r} as a merger task but the "
+                    f"capability map assigns role {required_role(task)!r}",
+                )
+
+
+class TestMergerBoundary(unittest.TestCase):
+    """Preserve the legitimate hunk of 970e68b and the merger fence."""
+
+    def test_adopt_merger_pr_lease_requires_merger_role(self):
+        self.assertEqual(required_role("adopt_merger_pr_lease"), "merger")
+        self.assertEqual(
+            required_permission("adopt_merger_pr_lease"), "gitea.pr.comment"
+        )
+
+    def test_merge_pr_requires_merger_role(self):
+        self.assertEqual(required_role("merge_pr"), "merger")
+        self.assertEqual(required_permission("merge_pr"), "gitea.pr.merge")
+
+    def test_merger_profile_cannot_resolve_formal_review_tasks(self):
+        merger = CANONICAL_ROLE_PROFILES["merger"]
+        for task in ("review_pr", "approve_pr", "request_changes_pr"):
+            with self.subTest(task=task):
+                ok, reason = gitea_config.check_operation(
+                    required_permission(task),
+                    merger["allowed"],
+                    merger["forbidden"],
+                )
+                self.assertFalse(
+                    ok,
+                    f"merger profile must not hold {task!r} permission "
+                    f"(got reason {reason!r})",
+                )
+
+
+if __name__ == "__main__":
+    unittest.main()