docs: ADR for stable MCP control runtime vs dev runtime

Policy: real Gitea mutations use stable control runtime only; normal
sessions must not kill/restart/relaunch from worktrees or edit the stable
checkout. Promotion is operator-only with proof and rollback.

Refs: #615

allocator_service.py

@@ -1,610 +0,0 @@
-"""Controller-owned work allocator policy (#600).
-
-Builds on the #613 control-plane DB substrate (``ControlPlaneDB.assign_and_lease``).
-
-Workers must not self-select exclusive work under the standard multi-LLM
-workflow. They call ``gitea_allocate_next_work`` which:
-
-1. Inspects candidate Gitea issues/PRs (never raw monitoring incidents).
-2. Applies ADR routing policy (role, terminal path, leases, blocked, deps).
-3. Atomically assigns + leases the selected item in one DB transaction.
-
-This module is pure selection + substrate orchestration. Gitea I/O for live
-inventory lives in the MCP tool wrapper so tests can inject candidates.
-
-#612 remains downstream: bridge-created Gitea issues become candidates only
-after they exist as normal issues; this module never assigns incidents.
-"""
-
-from __future__ import annotations
-
-import os
-import uuid
-from dataclasses import dataclass, field
-from typing import Any, Sequence
-
-from control_plane_db import (
-    ControlPlaneDB,
-    ControlPlaneError,
-    InvalidWorkKindError,
-    LeaseRequiredError,
-    WORK_KINDS,
-)
-
-# Outcomes required by #600 / ADR §5.
-OUTCOME_ASSIGNED = "assigned_work"
-OUTCOME_WAIT = "wait"
-OUTCOME_BLOCKED_TERMINAL = "blocked_by_terminal_path"
-OUTCOME_BLOCKED_LEASE = "blocked_by_active_lease"
-OUTCOME_NEEDS_CONTROLLER = "needs_controller"
-OUTCOME_NO_SAFE = "no_safe_work"
-OUTCOME_ROLE_INELIGIBLE = "role_ineligible"
-OUTCOME_PREVIEW = "preview"  # dry-run only (apply=false)
-
-ROLE_AUTHOR = "author"
-ROLE_REVIEWER = "reviewer"
-ROLE_MERGER = "merger"
-ROLE_RECONCILER = "reconciler"
-ROLE_CONTROLLER = "controller"
-
-VALID_ROLES = frozenset(
-    {ROLE_AUTHOR, ROLE_REVIEWER, ROLE_MERGER, ROLE_RECONCILER, ROLE_CONTROLLER}
-)
-
-# Default action matrices by role (mutation gate will re-check).
-ROLE_ACTIONS: dict[str, tuple[tuple[str, ...], tuple[str, ...]]] = {
-    ROLE_AUTHOR: (
-        ("implement", "comment", "push", "create_pr"),
-        ("approve", "merge", "request_changes", "self_select_without_assignment"),
-    ),
-    ROLE_REVIEWER: (
-        ("review", "comment", "approve", "request_changes"),
-        ("merge", "push", "create_pr", "self_select_without_assignment"),
-    ),
-    ROLE_MERGER: (
-        ("merge", "comment"),
-        ("approve", "request_changes", "push", "create_pr", "self_select_without_assignment"),
-    ),
-    ROLE_RECONCILER: (
-        ("comment", "diagnose", "cleanup"),
-        ("approve", "merge", "push", "create_pr", "self_select_without_assignment"),
-    ),
-    ROLE_CONTROLLER: (
-        ("comment", "diagnose", "allocate"),
-        ("approve", "merge", "push", "create_pr"),
-    ),
-}
-
-
-@dataclass
-class WorkCandidate:
-    """One assignable Gitea issue or PR presented to the allocator."""
-
-    kind: str  # issue | pr
-    number: int
-    state: str = "open"
-    labels: tuple[str, ...] = ()
-    title: str = ""
-    priority: int = 0
-    head_sha: str | None = None
-    # Routing signals (callers derive from Gitea / review feedback).
-    request_changes_current_head: bool = False
-    approval_on_current_head: bool = False
-    approval_stale: bool = False
-    approval_contaminated: bool = False
-    mergeable: bool = False
-    blocked: bool = False
-    dependency_unmet: bool = False
-    dependency_reason: str | None = None
-    already_claimed_elsewhere: bool = False
-
-    def __post_init__(self) -> None:
-        self.kind = (self.kind or "").strip().lower()
-        self.state = (self.state or "open").strip().lower()
-        self.labels = tuple(
-            str(x).strip().lower() for x in (self.labels or ()) if str(x).strip()
-        )
-        if self.kind not in WORK_KINDS:
-            raise InvalidWorkKindError(
-                f"candidate kind '{self.kind}' is not assignable; only "
-                f"{sorted(WORK_KINDS)} (never raw incidents)"
-            )
-
-    def as_dict(self) -> dict[str, Any]:
-        return {
-            "kind": self.kind,
-            "number": self.number,
-            "state": self.state,
-            "labels": list(self.labels),
-            "title": self.title,
-            "priority": self.priority,
-            "head_sha": self.head_sha,
-            "request_changes_current_head": self.request_changes_current_head,
-            "approval_on_current_head": self.approval_on_current_head,
-            "approval_stale": self.approval_stale,
-            "approval_contaminated": self.approval_contaminated,
-            "mergeable": self.mergeable,
-            "blocked": self.blocked,
-            "dependency_unmet": self.dependency_unmet,
-            "dependency_reason": self.dependency_reason,
-        }
-
-
-@dataclass
-class SkipRecord:
-    kind: str
-    number: int
-    reason: str
-
-    def as_dict(self) -> dict[str, Any]:
-        return {"kind": self.kind, "number": self.number, "reason": self.reason}
-
-
-def normalize_role(role: str | None, *, profile_name: str | None = None) -> str:
-    """Map profile/role strings to a canonical allocator role."""
-    raw = (role or "").strip().lower()
-    if raw in VALID_ROLES:
-        return raw
-    prof = (profile_name or "").strip().lower()
-    for token in VALID_ROLES:
-        if token in prof or prof.endswith(f"-{token}"):
-            return token
-    if "author" in raw:
-        return ROLE_AUTHOR
-    if "review" in raw:
-        return ROLE_REVIEWER
-    if "merg" in raw:
-        return ROLE_MERGER
-    if "reconcil" in raw:
-        return ROLE_RECONCILER
-    if "control" in raw:
-        return ROLE_CONTROLLER
-    raise ControlPlaneError(
-        f"unknown allocator role '{role}' (profile={profile_name!r}); "
-        f"expected one of {sorted(VALID_ROLES)}"
-    )
-
-
-def expected_role_for_candidate(c: WorkCandidate) -> str:
-    """ADR §5.3 routing: which role should take this work next."""
-    if c.kind == "pr":
-        if c.approval_contaminated:
-            return ROLE_RECONCILER
-        if c.request_changes_current_head:
-            return ROLE_AUTHOR
-        if c.approval_stale:
-            return ROLE_REVIEWER
-        if c.approval_on_current_head and c.mergeable:
-            return ROLE_MERGER
-        # Open PR without terminal verdict → reviewer
-        return ROLE_REVIEWER
-    # Issues: ready work → author by default; blocked stays controller/none
-    labels = set(c.labels)
-    if "status:blocked" in labels or c.blocked:
-        return ROLE_CONTROLLER
-    return ROLE_AUTHOR
-
-
-def role_actions(role: str) -> tuple[tuple[str, ...], tuple[str, ...]]:
-    return ROLE_ACTIONS.get(role, ROLE_ACTIONS[ROLE_AUTHOR])
-
-
-def classify_skip(
-    c: WorkCandidate,
-    *,
-    role: str,
-    terminal_pr: int | None,
-) -> str | None:
-    """Return skip reason, or None if candidate is selectable for *role*."""
-    if c.state in ("merged", "closed"):
-        return f"{c.kind}#{c.number} is {c.state}; never assign"
-    if c.blocked or "status:blocked" in c.labels:
-        return f"{c.kind}#{c.number} is blocked"
-    if c.dependency_unmet:
-        return (
-            c.dependency_reason
-            or f"{c.kind}#{c.number} has unmet dependencies"
-        )
-    if c.already_claimed_elsewhere:
-        return f"{c.kind}#{c.number} already claimed elsewhere"
-    if c.kind == "pr" and not (c.head_sha or "").strip():
-        return f"pr#{c.number} missing head_sha pin"
-
-    # Terminal path first: when an active terminal PR exists, only that PR
-    # (or controller diagnosis) is assignable for review-path roles.
-    if terminal_pr is not None and c.kind == "pr" and c.number != terminal_pr:
-        if role in (ROLE_REVIEWER, ROLE_MERGER):
-            return (
-                f"pr#{c.number} skipped: active terminal-review lock on "
-                f"PR #{terminal_pr} must be resolved first"
-            )
-
-    expected = expected_role_for_candidate(c)
-    if role == ROLE_CONTROLLER:
-        # Controller may inspect anything but only assigns diagnosis targets
-        # when contaminated / blocked.
-        if expected == ROLE_RECONCILER or c.blocked:
-            return None
-        return f"{c.kind}#{c.number} does not require controller (expected {expected})"
-
-    if role != expected:
-        return (
-            f"{c.kind}#{c.number} expects role '{expected}', active role is '{role}'"
-        )
-
-    # Ready-gate for issues: prefer status:ready when labels present.
-    if c.kind == "issue" and c.labels:
-        if "status:ready" not in c.labels and "status:in-progress" not in c.labels:
-            # Allow unlabeled open issues; only skip explicit non-ready states.
-            if any(l.startswith("status:") for l in c.labels):
-                return f"issue#{c.number} not status:ready ({','.join(c.labels)})"
-    return None
-
-
-def sort_candidates(candidates: Sequence[WorkCandidate]) -> list[WorkCandidate]:
-    """Higher priority first; then lower number (older issues) for stability."""
-    return sorted(
-        candidates,
-        key=lambda c: (-int(c.priority), c.kind != "pr", int(c.number)),
-    )
-
-
-def allocate_next_work(
-    db: ControlPlaneDB,
-    *,
-    session_id: str,
-    role: str,
-    remote: str,
-    org: str,
-    repo: str,
-    candidates: Sequence[WorkCandidate],
-    apply: bool = False,
-    profile_name: str | None = None,
-    username: str | None = None,
-    lease_ttl_seconds: int | None = None,
-) -> dict[str, Any]:
-    """Select and optionally reserve the next work unit via control-plane DB.
-
-    *apply=False* (default): dry-run selection only — no lease/assignment.
-    *apply=True*: atomic ``assign_and_lease`` for the selected candidate.
-
-    Never uses file locks or comment-only leases as the assignment source.
-    """
-    if db is None:
-        return {
-            "success": False,
-            "outcome": OUTCOME_NO_SAFE,
-            "reasons": [
-                "control-plane DB substrate unavailable (fail closed, #600/#613)"
-            ],
-            "skipped": [],
-            "assignment": None,
-            "substrate": "control_plane_db",
-            "file_lock_only": False,
-            "comment_lease_only": False,
-        }
-
-    try:
-        role_norm = normalize_role(role, profile_name=profile_name)
-    except ControlPlaneError as exc:
-        return {
-            "success": False,
-            "outcome": OUTCOME_ROLE_INELIGIBLE,
-            "reasons": [str(exc)],
-            "skipped": [],
-            "assignment": None,
-            "substrate": "control_plane_db",
-        }
-
-    session_id = (session_id or "").strip() or f"alloc-{uuid.uuid4().hex[:12]}"
-    try:
-        db.upsert_session(
-            session_id=session_id,
-            role=role_norm,
-            profile=profile_name,
-            pid=os.getpid(),
-        )
-    except Exception as exc:  # noqa: BLE001 — surface structured
-        return {
-            "success": False,
-            "outcome": OUTCOME_NO_SAFE,
-            "reasons": [
-                f"failed to register session in control-plane DB: {exc} "
-                "(fail closed, #613)"
-            ],
-            "skipped": [],
-            "assignment": None,
-            "substrate": "control_plane_db",
-        }
-
-    # Expire stale leases globally before selection.
-    try:
-        db.expire_stale_leases()
-    except Exception as exc:  # noqa: BLE001
-        return {
-            "success": False,
-            "outcome": OUTCOME_NO_SAFE,
-            "reasons": [f"lease expiry failed: {exc} (fail closed)"],
-            "skipped": [],
-            "assignment": None,
-            "substrate": "control_plane_db",
-        }
-
-    terminal = None
-    try:
-        terminal = db.get_active_terminal_lock(remote=remote, org=org, repo=repo)
-    except Exception as exc:  # noqa: BLE001
-        return {
-            "success": False,
-            "outcome": OUTCOME_NO_SAFE,
-            "reasons": [f"terminal lock lookup failed: {exc} (fail closed)"],
-            "skipped": [],
-            "assignment": None,
-            "substrate": "control_plane_db",
-        }
-    terminal_pr = int(terminal["terminal_pr"]) if terminal else None
-
-    skipped: list[SkipRecord] = []
-    ordered = sort_candidates(list(candidates))
-    selected: WorkCandidate | None = None
-    for c in ordered:
-        reason = classify_skip(c, role=role_norm, terminal_pr=terminal_pr)
-        if reason:
-            skipped.append(SkipRecord(c.kind, c.number, reason))
-            continue
-        selected = c
-        break
-
-    if selected is None:
-        # If terminal lock blocks all review work, surface that explicitly.
-        if terminal_pr is not None and role_norm in (ROLE_REVIEWER, ROLE_MERGER):
-            outcome = OUTCOME_BLOCKED_TERMINAL
-            reasons = [
-                f"no safe work for role '{role_norm}': active terminal-review "
-                f"lock on PR #{terminal_pr} (resolve terminal path first, #332/#600)"
-            ]
-        else:
-            outcome = OUTCOME_NO_SAFE
-            reasons = [
-                f"no safe assignable work for role '{role_norm}' "
-                f"among {len(ordered)} candidates"
-            ]
-        return {
-            "success": True,
-            "outcome": outcome,
-            "apply": bool(apply),
-            "role": role_norm,
-            "profile_name": profile_name,
-            "username": username,
-            "session_id": session_id,
-            "remote": remote,
-            "org": org,
-            "repo": repo,
-            "selected": None,
-            "expected_role_next": None,
-            "reasons": reasons,
-            "skipped": [s.as_dict() for s in skipped],
-            "terminal_pr": terminal_pr,
-            "assignment": None,
-            "substrate": "control_plane_db",
-            "file_lock_only": False,
-            "comment_lease_only": False,
-            "downstream_note": (
-                "#612 incident bridge remains downstream of #600; "
-                "allocator never assigns raw monitoring incidents"
-            ),
-        }
-
-    expected_role = expected_role_for_candidate(selected)
-    allowed, forbidden = role_actions(role_norm)
-    selection = {
-        "kind": selected.kind,
-        "number": selected.number,
-        "title": selected.title,
-        "labels": list(selected.labels),
-        "head_sha": selected.head_sha,
-        "priority": selected.priority,
-        "expected_role_next": expected_role,
-        "reason_selected": (
-            f"highest-priority candidate for role '{role_norm}' "
-            f"(expected_role={expected_role})"
-        ),
-    }
-
-    if not apply:
-        return {
-            "success": True,
-            "outcome": OUTCOME_PREVIEW,
-            "apply": False,
-            "role": role_norm,
-            "profile_name": profile_name,
-            "username": username,
-            "session_id": session_id,
-            "remote": remote,
-            "org": org,
-            "repo": repo,
-            "selected": selection,
-            "expected_role_next": expected_role,
-            "reasons": [
-                "dry-run only (apply=false); no assignment/lease created — "
-                "call again with apply=true to reserve via control-plane DB"
-            ],
-            "skipped": [s.as_dict() for s in skipped],
-            "terminal_pr": terminal_pr,
-            "assignment": None,
-            "substrate": "control_plane_db",
-            "file_lock_only": False,
-            "comment_lease_only": False,
-            "downstream_note": (
-                "#612 incident bridge remains downstream of #600; "
-                "allocator never assigns raw monitoring incidents"
-            ),
-        }
-
-    # Atomic reserve via #613 substrate.
-    ttl = lease_ttl_seconds if lease_ttl_seconds is not None else None
-    try:
-        kwargs: dict[str, Any] = {
-            "session_id": session_id,
-            "role": role_norm,
-            "remote": remote,
-            "org": org,
-            "repo": repo,
-            "kind": selected.kind,
-            "number": selected.number,
-            "expected_head_sha": selected.head_sha,
-            "allowed_actions": allowed,
-            "forbidden_actions": forbidden,
-            "phase": "allocated",
-        }
-        if ttl is not None:
-            kwargs["lease_ttl_seconds"] = int(ttl)
-        result = db.assign_and_lease(**kwargs)
-    except (InvalidWorkKindError, LeaseRequiredError, ControlPlaneError) as exc:
-        return {
-            "success": False,
-            "outcome": OUTCOME_NO_SAFE,
-            "apply": True,
-            "role": role_norm,
-            "session_id": session_id,
-            "remote": remote,
-            "org": org,
-            "repo": repo,
-            "selected": selection,
-            "expected_role_next": expected_role,
-            "reasons": [f"atomic assign+lease failed: {exc} (fail closed, #613)"],
-            "skipped": [s.as_dict() for s in skipped],
-            "terminal_pr": terminal_pr,
-            "assignment": None,
-            "substrate": "control_plane_db",
-            "file_lock_only": False,
-            "comment_lease_only": False,
-        }
-
-    if result.outcome == "wait":
-        return {
-            "success": True,
-            "outcome": OUTCOME_WAIT,
-            "apply": True,
-            "role": role_norm,
-            "session_id": session_id,
-            "remote": remote,
-            "org": org,
-            "repo": repo,
-            "selected": selection,
-            "expected_role_next": expected_role,
-            "reasons": [result.reason or "foreign active lease"],
-            "skipped": [s.as_dict() for s in skipped],
-            "terminal_pr": terminal_pr,
-            "assignment": result.as_dict(),
-            "owner_session_id": result.owner_session_id,
-            "substrate": "control_plane_db",
-            "file_lock_only": False,
-            "comment_lease_only": False,
-        }
-
-    if result.outcome == "no_safe_work":
-        return {
-            "success": True,
-            "outcome": OUTCOME_NO_SAFE,
-            "apply": True,
-            "role": role_norm,
-            "session_id": session_id,
-            "remote": remote,
-            "org": org,
-            "repo": repo,
-            "selected": selection,
-            "expected_role_next": expected_role,
-            "reasons": [result.reason or "no_safe_work"],
-            "skipped": [s.as_dict() for s in skipped],
-            "terminal_pr": terminal_pr,
-            "assignment": result.as_dict(),
-            "substrate": "control_plane_db",
-            "file_lock_only": False,
-            "comment_lease_only": False,
-        }
-
-    # assigned
-    return {
-        "success": True,
-        "outcome": OUTCOME_ASSIGNED,
-        "apply": True,
-        "role": role_norm,
-        "profile_name": profile_name,
-        "username": username,
-        "session_id": session_id,
-        "remote": remote,
-        "org": org,
-        "repo": repo,
-        "selected": selection,
-        "expected_role_next": expected_role,
-        "reasons": [
-            selection["reason_selected"],
-            result.reason or "atomic assign+lease created",
-        ],
-        "skipped": [s.as_dict() for s in skipped],
-        "terminal_pr": terminal_pr,
-        "assignment": result.as_dict(),
-        "lease_proof": {
-            "assignment_id": result.assignment_id,
-            "lease_id": result.lease_id,
-            "expires_at": result.expires_at,
-            "expected_head_sha": result.expected_head_sha,
-            "allowed_actions": list(result.allowed_actions),
-            "forbidden_actions": list(result.forbidden_actions),
-            "source": "control_plane_db.assign_and_lease",
-        },
-        "next_valid_command": _next_command(role_norm, selected),
-        "substrate": "control_plane_db",
-        "file_lock_only": False,
-        "comment_lease_only": False,
-        "downstream_note": (
-            "#612 incident bridge remains downstream of #600; "
-            "allocator never assigns raw monitoring incidents"
-        ),
-    }
-
-
-def _next_command(role: str, c: WorkCandidate) -> str:
-    if role == ROLE_AUTHOR and c.kind == "issue":
-        return f"implement issue #{c.number} under a branches/ worktree; open PR when ready"
-    if role == ROLE_AUTHOR and c.kind == "pr":
-        return (
-            f"address REQUEST_CHANGES on PR #{c.number} at head "
-            f"{(c.head_sha or '')[:12]} and push fixes"
-        )
-    if role == ROLE_REVIEWER:
-        return (
-            f"review PR #{c.number} pinned at head {(c.head_sha or '')[:12]} "
-            "via full reviewer workflow"
-        )
-    if role == ROLE_MERGER:
-        return (
-            f"merge PR #{c.number} only with explicit operator MERGE "
-            f"authorization at head {(c.head_sha or '')[:12]}"
-        )
-    if role == ROLE_RECONCILER:
-        return f"diagnose contested state for {c.kind}#{c.number}"
-    return f"proceed on {c.kind}#{c.number} under role {role}"
-
-
-def candidate_from_dict(data: dict[str, Any]) -> WorkCandidate:
-    """Build a WorkCandidate from a plain dict (tests / MCP inventory)."""
-    return WorkCandidate(
-        kind=str(data.get("kind") or "issue"),
-        number=int(data["number"]),
-        state=str(data.get("state") or "open"),
-        labels=tuple(data.get("labels") or ()),
-        title=str(data.get("title") or ""),
-        priority=int(data.get("priority") or 0),
-        head_sha=data.get("head_sha"),
-        request_changes_current_head=bool(data.get("request_changes_current_head")),
-        approval_on_current_head=bool(data.get("approval_on_current_head")),
-        approval_stale=bool(data.get("approval_stale")),
-        approval_contaminated=bool(data.get("approval_contaminated")),
-        mergeable=bool(data.get("mergeable")),
-        blocked=bool(data.get("blocked")),
-        dependency_unmet=bool(data.get("dependency_unmet")),
-        dependency_reason=data.get("dependency_reason"),
-        already_claimed_elsewhere=bool(data.get("already_claimed_elsewhere")),
-    )

docs/architecture/control-plane-db-substrate.md

@@ -1,63 +0,0 @@
-# Control-plane DB substrate (#613)
-
-**Status:** Implemented (SQLite single-writer MVP)
-
-**ADR:** [`mcp-allocator-control-plane-observability-adr.md`](mcp-allocator-control-plane-observability-adr.md)
-
-**Module:** `control_plane_db.py`
-
-## Architecture statement
-
-> **DB coordinates, Gitea records, Sentry/GlitchTip observe; the bridge is the only path that turns observations into Gitea work.**
-
-## What this ships
-
-| Capability | Notes |
-|------------|--------|
-| Schema | `sessions`, `work_items`, `leases`, `assignments`, `terminal_locks`, `events`, `incident_links` |
-| Atomic assign+lease | `ControlPlaneDB.assign_and_lease` — one `BEGIN IMMEDIATE` transaction |
-| Mutation gate | `require_valid_assignment` — live lease + allowed action + non-terminal work + non-stale head |
-| Heartbeat / release / expire | Lease lifecycle helpers |
-| Terminal-lock index | Routing signal for #600 (terminal path first) |
-| `incident_links` | Provider-neutral link model for #612 — **not** assignable work; scope keys NULL-safe |
-
-## Hard rules (enforced in code)
-
-1. Assignable `work_items.kind` ∈ {`issue`, `pr`} only — **never** raw Sentry/GlitchTip incidents.
-2. Two concurrent sessions cannot both receive an active assignment on the same open work item (second gets `wait`).
-3. Merged/closed work items return `no_safe_work` at assign time, and `require_valid_assignment` fails closed if the work item becomes terminal later.
-4. Assignments pin `expected_head_sha`; mutations fail closed if the work item head drifts.
-5. SQLite path is the **single-writer MVP** (`GITEA_CONTROL_PLANE_DB`, default under `~/.cache/gitea-tools/control-plane/`). Multi-session multi-host production requires **Postgres** or a **single allocator daemon** (ADR §6).
-6. `incident_links` optional scope fields are stored as empty strings (never NULL) so UNIQUE is canonical across minimal upserts.
-7. Legacy `incident_links` migration collapses NULL-scope duplicates **only** when Gitea targets **and** all meaningful observation metadata agree (fingerprint, status, event_count, permalink, timestamps, linked PRs, etc.). Conflicting metadata fails closed — no silent discard.
-
-## Dependency chain
-
-```text
-#613 control-plane DB (this)  →  #600 allocator API  →  #612 incident bridge
-```
-
-- **#600** must call this substrate (not file locks / comment-only leases alone) for completion.
-- **#612** must write `incident_links` here and create **Gitea issues**; the allocator assigns those issues, not raw incidents.
-
-## Allocator API (#600)
-
-Module: `allocator_service.py` · MCP tool: `gitea_allocate_next_work`
-
-- Workers call `gitea_allocate_next_work(apply=false|true)` instead of self-selecting work.
-- `apply=false` returns a dry-run selection (`outcome=preview`) with skip reasons.
-- `apply=true` reserves via `ControlPlaneDB.assign_and_lease` (atomic assignment+lease).
-- Coordination source is **always** the control-plane DB — not file locks or comment-only leases.
-- Routing follows ADR §5.3 (REQUEST_CHANGES → author, terminal path first, foreign lease → wait).
-- Raw monitoring incidents are never candidates (#612 remains downstream).
-
-## Non-goals (intentionally deferred)
-
-- Sentry/GlitchTip provider adapters and auto-watchdog — **#612**
-- Gitea comment/label mirror writers (may be added by allocator tooling later)
-
-## Tests
-
-```bash
-python3 -m pytest tests/test_control_plane_db.py -q
-```

docs/architecture/mcp-allocator-control-plane-observability-adr.md

@@ -1,301 +0,0 @@
-# ADR: MCP allocator, control-plane DB, and Sentry/GlitchTip incident bridge architecture
-
-- **Status:** Accepted (implementation pending; blocks code for #600 / #612 / #613)
-- **Date:** 2026-07-09
-- **Tracking issues:**
-  - [#613](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/613) — control-plane DB (first)
-  - [#600](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/600) — allocator API (second)
-  - [#612](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/612) — Sentry/GlitchTip incident bridge (third)
-- **Related:** existing GlitchTip contracts (`glitchtip-to-gitea-workflow-design.md`, `glitchtip-gitea-deduplication-linking-design.md`), trust boundaries (`tool-boundaries.md`, `safety-model.md`), current leases (`pr_work_lease.py`, `issue_lock_store.py`)
-
-## 1. Context
-
-Multiple LLM sessions can independently inspect the Gitea queue and start the same issue or PR. Existing coordination (Gitea comment leases, local issue-lock files, labels) often detects collisions **after** work has started. Parallel issues #600, #612, and #613 each describe part of a fix; without one ADR they risk overlapping stores, wrong dependency order, and trust-boundary violations.
-
-This ADR is the canonical architecture decision **before** implementing those issues.
-
-## 2. Decision summary (core)
-
-| Layer | Owns | Must not |
-|-------|------|----------|
-| **Control-plane DB** | Sessions, atomic assignment, leases, heartbeats, terminal-lock index, events, incident links | Bypass Gitea workflow gates or replace issue/PR history |
-| **Gitea** | Durable work record: issues, PRs, comments, labels, reviews, merges | Be the only concurrency lock under multi-session load |
-| **Sentry / GlitchTip** | Incidents, events, provider UI | Assign work, approve/merge/close, or mutate Gitea outside the bridge |
-| **Incident bridge** | Provider adapters, reconcile/create Gitea issues, link storage upsert, optional provider writeback | Hand raw provider incidents to the allocator as work items |
-
-**One-liner:** **DB coordinates. Gitea records. Sentry/GlitchTip observe. The bridge is the only path that turns observations into Gitea work. The allocator assigns only Gitea issues/PRs, never raw monitoring incidents.**
-
-## 3. Dependency order
-
-Implementation **must** follow:
-
-```text
-#613 control-plane DB  →  #600 allocator API  →  #612 incident bridge
-   (atomic substrate)      (routing policy)       (feeds Gitea work)
-```
-
-| Issue | Role | Depends on |
-|-------|------|------------|
-| **#613** | Durable coordination DB + lease/assignment transactions | — |
-| **#600** | `gitea_allocate_next_work` policy and tool surface | **#613** (hard) |
-| **#612** | Multi-project Sentry/GlitchTip → Gitea bridge | **#613** for `incident_links` index; **#600** before treating bridge-created issues as allocator feed in multi-worker prod |
-
-**Hard rules:**
-
-1. Do **not** implement #600 on file locks / comment-only leases and call it done.
-2. Do **not** ship #612 as a second assignment system for raw incidents.
-3. Partial previews (read-only list tools, schema stubs) may land earlier if they do not claim “allocator complete” or “bridge complete.”
-
-## 4. Authority boundaries
-
-### 4.1 Gitea (durable source of truth for work)
-
-Gitea remains authoritative for:
-
-- Issue and PR identity, titles, bodies, state (open/closed/merged)
-- Comments, reviews, approvals, REQUEST_CHANGES
-- Labels and workflow status labels (`status:ready`, `status:in-progress`, …)
-- Merges, closes, branch refs as recorded by Gitea/git hosting
-
-Operators and auditors read **history** from Gitea.
-
-### 4.2 Control-plane DB (coordination / index)
-
-The control-plane DB is authoritative for **live multi-session coordination**:
-
-- Which session holds which assignment/lease
-- Heartbeat freshness and expiry
-- Terminal-lock index for routing
-- Event log of allocation/lease transitions
-- `incident_links` index (see §8)
-
-It is **not** a substitute for Gitea history. When DB and Gitea disagree on durable work state (e.g. PR already merged), **Gitea wins**; the DB is reconciled.
-
-### 4.3 Sentry / GlitchTip (observe)
-
-Providers own incident lifecycle and raw event data. They:
-
-- Must **not** bypass Gitea gates
-- Must **not** assign LLM work
-- May receive **writeback** of resolution status only through the bridge, when configured and supported
-
-### 4.4 Trust boundaries for credentials
-
-Aligned with `docs/tool-boundaries.md` and `docs/safety-model.md`:
-
-- **One MCP server process per trust boundary** remains the default.
-- Monitor API tokens (Sentry/GlitchTip) live in the **bridge/orchestrator boundary** (or a dedicated observability write/read profile), **not** blindly inside every Gitea MCP author/reviewer/merger process.
-- Gitea tokens stay on Gitea MCP profiles only.
-- Orchestrators compose services; they must not become a single credential pool that silently mixes Gitea write + monitor tokens into every worker.
-
-Tool names such as `gitea_observability_*` may exist as a **namespace façade** only if the runtime still enforces separate credential scopes (e.g. bridge process vs pure Gitea mutation process).
-
-## 5. Allocator rules (#600 on top of #613)
-
-### 5.1 Worker contract
-
-- Workers **do not self-select** work under the standard multi-LLM workflow.
-- Workers call **`gitea_allocate_next_work`** (with `apply=true` only when taking work).
-- Mutations that claim exclusive work require a **valid assignment and lease** from the control-plane DB.
-- Return values include at least: role, issue/PR number, expected head SHA (when applicable), lease ID, expiry, allowed actions, forbidden actions — or a non-assignment outcome (`WAIT`, terminal-path block, no safe work, needs controller, etc.).
-
-### 5.2 Atomic reserve
-
-- **Assignment creation and lease creation happen in one DB transaction.**
-- Two concurrent sessions **must not** receive the same issue/PR as assigned work.
-- On contention: second session gets **WAIT** or **owner-resume**, never a duplicate lease.
-
-### 5.3 Routing policy
-
-| Condition | Route |
-|-----------|--------|
-| Current-head **REQUEST_CHANGES** | **Author** (not reviewer/merger) |
-| **Stale** approval (approval not on current head) | **Reviewer** |
-| **Clean** approval on current head, mergeable | **Merger** |
-| Contested / contaminated approval | **Diagnosis / reconciler** (controller path) |
-| Active **foreign** lease | **WAIT** or **owner-resume** |
-| **Terminal-review** lock present | **Terminal-path resolution first** before downstream review work |
-| Merged / closed PR | **Never assign** |
-| Issue locked by sanctioned lease | **Never assign** to another worker unless lease cleanup/adoption is sanctioned |
-
-### 5.4 Relationship to Gitea mirrors
-
-After a successful assignment, the allocator (or sanctioned tooling) may update Gitea comments/labels so humans and audits see state. Those mirrors **are not** the sole lock source.
-
-## 6. Control-plane DB topology (#613)
-
-### 6.1 Preferred architecture (multi-daemon / Proxmox)
-
-For true multi-session concurrency (multiple MCP daemons, multiple hosts, or Proxmox VMs):
-
-**Prefer either:**
-
-1. **Shared Postgres** used by all Gitea MCP profiles / allocator callers, **or**
-2. A **single allocator daemon** (sole writer to the coordination store) that all workers call over MCP/RPC.
-
-Both satisfy: one transactional authority for “who has this work item.”
-
-### 6.2 SQLite MVP
-
-SQLite is acceptable **only** for a **single-writer MVP**:
-
-- One process owns writes (allocator daemon or single co-located MCP server), **or**
-- Documented single-host single-daemon experiments with file locking and no multi-host claims.
-
-SQLite is **not** sufficient to declare multi-session production readiness when four independent LLM sessions talk to four MCP processes without a shared writer.
-
-### 6.3 Suggested entities (normative shape)
-
-Minimum logical entities (names may vary; semantics must not):
-
-1. **sessions** — session_id, role/profile, namespace, pid, started_at, last_heartbeat_at, status  
-2. **work_items** — remote/org/repo, kind ∈ {`issue`, `pr`}, number, state, priority, current_head_sha, updated_at  
-3. **leases** — lease_id, work_item_id, session_id, role, phase, expires_at, heartbeat_at, status  
-4. **assignments** — assignment_id, work_item_id, session_id, allowed_action(s), expected_head_sha, status  
-5. **terminal_locks** — repo/org, terminal_pr, review_id, decision, status, cleanup_state  
-6. **events** — event_id, work_item_id, type, message, created_at  
-7. **incident_links** — provider-neutral link model (see §8)
-
-**Explicit non-kind:** do **not** use `work_items.kind = sentry_incident` (or glitchtip_incident) as an assignable work unit. Incidents become work only after the bridge creates/links a **Gitea issue**.
-
-## 7. Lease migration (avoid split-brain)
-
-### 7.1 Target state
-
-- **Primary** for live coordination: **control-plane DB** leases and assignments.
-- **Gitea comment leases** (e.g. `<!-- mcp-review-lease:v1 -->`) and **local issue-lock files** become:
-  - **mirrors** of DB state for human visibility / recovery, and/or
-  - written **only** through the allocator (or sanctioned lease tools that update DB + mirror in one workflow).
-
-### 7.2 Migration rules
-
-1. New exclusive claims go through DB assignment+lease first.
-2. Comment lease / file lock writers that skip the DB are **deprecated** once #613+#600 land.
-3. Reconciler tooling heals: expired DB lease, orphan Gitea comment, orphan local file — fail closed when ambiguous.
-4. **Split-brain is a defect:** “DB free + Gitea comment leased” or “DB leased + Gitea free” must be detectable and reconcilable; production paths must not rely on two independent writers.
-
-### 7.3 Heartbeats
-
-- Heartbeats update the **DB**.
-- Optional Gitea summaries must avoid comment spam (periodic summary or edit-in-place policy).
-
-## 8. Observability bridge (#612)
-
-### 8.1 Role
-
-The bridge:
-
-1. Scans configured Sentry and/or GlitchTip projects (multi-project mappings).
-2. Deduplicates against existing links / Gitea issues.
-3. Creates or updates **normal Gitea issues** (labels, sanitized body, provider URL).
-4. Upserts **one** canonical `incident_links` row.
-5. Optionally writes resolution status back to the provider when supported.
-6. Never approves, merges, closes, or otherwise bypasses Gitea workflow gates.
-
-### 8.2 Allocator interaction
-
-- The allocator sees observability work **only after** a Gitea issue exists (typically `status:ready` + observability labels).
-- **Do not assign raw Sentry/GlitchTip incidents** as work items.
-- Bridge AC “allocator can see linked issues” means: **as ordinary Gitea issues**, not a special incident queue.
-
-### 8.3 Provider adapters and trust
-
-- Separate **Sentry** and **GlitchTip** adapters; document API differences; do not assume writeback parity.
-- Self-hosted base URLs supported (e.g. `https://sentry.prgs.cc`).
-- Tokens from environment / secret store only.
-- Prefer phase-1 **explicit reconcile / dry-run** before unsupervised watchdog auto-filing, consistent with existing GlitchTip filing safety contracts.
-
-### 8.4 Home of implementation
-
-Filing/orchestration may live in:
-
-- a control-plane / bridge package or profile, and/or  
-- Gitea-Tools as operator-facing tools that **delegate** to that boundary,
-
-but must not violate §4.4 credential isolation.
-
-## 9. Incident link storage (single source of truth)
-
-### 9.1 Canonical model: `incident_links` (provider-neutral)
-
-Prefer a **provider-neutral** model over Sentry-only `sentry_links`:
-
-| Field (logical) | Purpose |
-|-----------------|---------|
-| provider | `sentry` \| `glitchtip` \| … |
-| provider_base_url | Self-hosted base |
-| provider_org / provider_project | Mapping key |
-| provider_issue_id / provider_short_id | Provider identity |
-| provider_permalink | Human URL |
-| fingerprint | Stable dedupe key when available |
-| gitea_org / gitea_repo / gitea_issue_number | Linked work |
-| linked_pr_numbers | Optional PR association |
-| first_seen / last_seen / event_count | Summary metrics (safe) |
-| status | link lifecycle |
-| release_resolved_at / last_sync_at | Sync bookkeeping |
-
-### 9.2 Gitea as human mirror
-
-- Issue body markers / structured comments (e.g. HTML comment metadata) remain the **human- and audit-visible mirror**.
-- They must stay consistent with `incident_links` but are **not** a second independent write path for inventing links without the bridge.
-
-### 9.3 One truth
-
-- **Do not** maintain two independent systems of record (e.g. full mapping only in #612 storage **and** a separate #613 `sentry_links` with different semantics).
-- #612 implementation **must** use the same `incident_links` model introduced under #613 (or a single agreed store both reference).
-
-## 10. Security and redaction
-
-Mandatory for bridge payloads, Gitea issue bodies/comments, DB-stored event summaries, and logs:
-
-- No API tokens, DSNs, passwords, cookies, auth headers
-- No keychain IDs, private config contents, raw session-state files, full prompt bodies
-- Sanitize stack locals and request data; store only safe tags/context
-- Logs must never print provider tokens or DSNs
-- Redaction tests are required for #612
-
-## 11. Non-goals
-
-- Replace Gitea as the durable workflow record  
-- Let Sentry/GlitchTip assign work or mutate Gitea workflow state outside sanctioned tools  
-- Let the bridge approve, merge, close, release, or bypass Gitea gates  
-- Implement #600 on file locks / comments alone and call allocator complete  
-- Treat raw monitoring incidents as `work_items` for the allocator  
-- Put monitor tokens into every Gitea MCP worker process by default  
-
-## 12. Consequences
-
-### Positive
-
-- Clear implementation order and ownership  
-- Multi-session safety becomes testable at the DB layer  
-- Observability becomes assignable work without special-casing the allocator  
-- Trust boundaries stay compatible with existing control-plane docs  
-
-### Costs / risks
-
-- Migration from comment/file leases requires reconciler work  
-- Shared Postgres or single allocator daemon is operational cost  
-- Bridge must be careful not to spam Gitea issues (dedupe, caps, policy modes)  
-
-### Follow-ups (documentation only until implemented)
-
-1. Update #600, #612, and #613 bodies to **link this ADR** and restate hard dependencies.  
-2. Implement #613 schema + atomic assign/lease.  
-3. Implement #600 against the DB.  
-4. Implement #612 against `incident_links` + Gitea create/update.  
-5. Deprecate dual writers for leases.
-
-## 13. Acceptance criteria for *this* ADR
-
-This document is accepted when:
-
-1. It is merged into `docs/architecture/` on the default branch.  
-2. #600 / #612 / #613 (or their PRs) reference this path as the architecture source of truth.  
-3. No implementation PR for those issues claims completion without conforming to §§2–11.
-
-## 14. Document history
-
-| Date | Change |
-|------|--------|
-| 2026-07-09 | Initial ADR: dependency order, authority model, topology, lease migration, bridge, `incident_links`, security, non-goals |

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

@@ -0,0 +1,156 @@
+# 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** sessions **must not**:
+
+| Forbidden | Why |
+|-----------|-----|
+| Kill the running MCP server process | Drops all concurrent sessions; loses preflight state |
+| Restart 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 |
+
+EOF / transport recovery: **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.
+
+### 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** (client-namespace probes fail, wrong identity, wrong root, missing mutation capability, persistent EOF after reconnect):
+
+1. **Normal PR / review / merge / issue-mutation work must stop.**
+2. Do **not** improvise by switching to a dev worktree MCP for production mutations.
+3. Resume only after:
+   - runtime is restored, **or**
+   - a **controlled** promotion/rollback completes with the promotion record above, **or**
+   - a controller invokes the narrow **bootstrap review path** (#557) when the defect is self-hosted and documented.
+
+## 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.
+4. Operator Guide wiki cross-link to this ADR.
+
+## 6. Acceptance for this ADR
+
+1. Document merged under `docs/architecture/`.
+2. Issue #615 references this path.
+3. LLM/operator runbooks treat kill/restart/relaunch-from-worktree as **violations**.
+4. Unhealthy runtime stops normal mutation work until restore/promotion/rollback/bootstrap.
+
+## 7. Document history
+
+| Date | Change |
+|------|--------|
+| 2026-07-09 | Initial ADR: stable vs dev runtime, forbidden session actions, promotion proof fields, stop-work rule |

gitea_mcp_server.py

@@ -21,7 +21,6 @@ import json
 import functools
 import contextlib
 import subprocess
-import uuid
 from datetime import datetime, timedelta, timezone
 
 
@@ -833,8 +832,6 @@ import review_workflow_boundary  # noqa: E402
 import review_workflow_load  # noqa: E402
 import mcp_session_state  # noqa: E402
 import stale_review_decision_lock  # noqa: E402
-import allocator_service  # noqa: E402
-import control_plane_db  # noqa: E402
 import agent_temp_artifacts
 import issue_lock_worktree  # noqa: E402
 import issue_lock_provenance  # noqa: E402
@@ -1370,26 +1367,8 @@ def cleanup_in_progress_for_pr(pr_payload: dict, remote: str, host: str | None,
 
 # ── Helpers ───────────────────────────────────────────────────────────────────
 
-def _effective_remote(remote: str) -> str:
-    """If remote is the default ('dadeschools') but the active profile base_url maps to a known remote, use that remote instead."""
-    try:
-        profile = get_profile()
-        base_url = profile.get("base_url")
-        if remote == "dadeschools" and base_url:
-            import urllib.parse
-            url = urllib.parse.urlparse(base_url)
-            host = (url.netloc or url.path or "").strip().lower()
-            for k, v in REMOTES.items():
-                if v.get("host") == host:
-                    return k
-    except Exception:
-        pass
-    return remote
-
-
 def _resolve(remote: str, host: str | None, org: str | None, repo: str | None):
     """Resolve remote + overrides to (host, org, repo)."""
-    remote = _effective_remote(remote)
     if remote not in REMOTES:
         raise ValueError(f"Unknown remote '{remote}'. Choose from: {list(REMOTES)}")
     profile = REMOTES[remote]
@@ -1423,7 +1402,6 @@ def _resolve_control_plane_guide_target(
     if org is not None and repo is not None:
         return _resolve(remote, host, org, repo)
 
-    remote = _effective_remote(remote)
     if remote not in REMOTES:
         raise ValueError(f"Unknown remote '{remote}'. Choose from: {list(REMOTES)}")
 
@@ -3098,15 +3076,11 @@ def check_review_decision_gate(
         )
 
     prior = list(lock.get("live_mutations") or [])
-    ready_head = lock.get("ready_expected_head_sha")
-    if stale_review_decision_lock.prior_live_mutations_block_boundary(
-        lock, pr_number=pr_number, expected_head_sha=ready_head
-    ):
     if prior and not lock.get("correction_authorized"):
         reasons.append(
-                "live review mutation already recorded for this PR head in this "
-                "run; only one live review mutation is allowed per head unless "
-                "gitea_authorize_review_correction was invoked (fail closed, #620)"
+            "live review mutation already recorded in this run; only one live "
+            "review mutation is allowed unless "
+            "gitea_authorize_review_correction was invoked (fail closed)"
         )
     elif (
         action in _TERMINAL_REVIEW_ACTIONS
@@ -3114,9 +3088,9 @@ def check_review_decision_gate(
         and not lock.get("correction_authorized")
     ):
         reasons.append(
-                "terminal review decision already submitted for this PR head in "
-                "this run; blocked unless an operator-approved correction was "
-                "authorized (fail closed, #620)"
+            "terminal review decision already submitted on this PR in this "
+            "run; blocked unless an operator-approved correction was "
+            "authorized (fail closed)"
         )
 
     return reasons
@@ -3125,18 +3099,12 @@ def check_review_decision_gate(
 def record_live_review_mutation(pr_number: int, action: str, review_id: int | None = None):
     lock = _load_review_decision_lock() or {}
     mutations = list(lock.get("live_mutations") or [])
-    head_sha = stale_review_decision_lock.normalize_head_sha(
-        lock.get("ready_expected_head_sha")
-    )
-    entry = {
+    mutations.append({
         "pr_number": pr_number,
         "action": action,
         "review_id": review_id,
         "review_state": action,
-    }
-    if head_sha:
-        entry["head_sha"] = head_sha
-    mutations.append(entry)
+    })
     lock["live_mutations"] = mutations
     if lock.get("correction_authorized"):
         lock["correction_authorized"] = False
@@ -3144,28 +3112,17 @@ def record_live_review_mutation(pr_number: int, action: str, review_id: int | No
     _save_review_decision_lock(lock)
 
 
-def terminal_review_hard_stop_reasons(
-    pr_number: int,
-    operation: str,
-    expected_head_sha: str | None = None,
-) -> list[str]:
-    """Session hard-stop after a terminal live review mutation (#332 / #620).
+def terminal_review_hard_stop_reasons(pr_number: int, operation: str) -> list[str]:
+    """Session hard-stop after a terminal live review mutation (#332).
 
-    After a terminal verdict is consumed for a given PR **head**, the only
-    permitted continuation is the merge sequence for that same approved PR
-    (merge does not require a new head). A REQUEST_CHANGES (or an approval of
-    a different PR, or the same head) blocks further review/mark-ready/merge
-    mutations for that boundary.
+    After a terminal verdict is consumed in this run, the only permitted
+    continuation is the merge sequence for the same PR that was approved.
+    A REQUEST_CHANGES (or an approval of a different PR) blocks every
+    further review/mark-ready/merge mutation. An operator-approved
+    correction (#211) re-opens the review path only — never a cross-PR
+    merge.
 
-    #620: when *expected_head_sha* differs from the last terminal's reviewed
-    head on the **same open PR**, mark_ready / review / resume may proceed so
-    a fresh formal decision can be recorded for the new head. Historical
-    mutations are preserved.
-
-    An operator-approved correction (#211) re-opens the review path only —
-    never a cross-PR merge.
-
-    *operation* is one of 'merge', 'mark_ready', 'review', or 'resume'.
+    *operation* is one of 'merge', 'mark_ready', or 'review'.
     Returns [] when the operation may proceed.
     """
     lock = _load_review_decision_lock()
@@ -3184,19 +3141,8 @@ def terminal_review_hard_stop_reasons(
         and last.get("pr_number") == pr_number
     ):
         return []
-    if operation in ("mark_ready", "review", "resume") and lock.get(
-        "correction_authorized"
-    ):
+    if operation in ("mark_ready", "review") and lock.get("correction_authorized"):
         return []
-    # #620: same PR, different reviewed head → fresh decision boundary.
-    if stale_review_decision_lock.terminal_boundary_allows_fresh_decision(
-        lock,
-        pr_number=pr_number,
-        expected_head_sha=expected_head_sha,
-        operation=operation,
-    ):
-        return []
-    locked_head = stale_review_decision_lock.mutation_head_sha(last, lock)
     if last.get("action") == "approve":
         guidance = (
             f"only the merge sequence for approved PR "
@@ -3204,22 +3150,15 @@ def terminal_review_hard_stop_reasons(
         )
     else:
         guidance = "the session must stop and produce a final report"
-    head_note = (
-        f" at head {locked_head[:12]}…"
-        if locked_head
-        else ""
-    )
     recovery = (
         "if that PR is already merged/closed, use "
         "gitea_cleanup_stale_review_decision_lock (apply=true) after live-state "
-        "proof (#594); if the PR is still open but the head moved, mark/submit "
-        "with the new expected_head_sha (#620); never delete session-state "
-        "files by hand"
+        "proof (#594); never delete session-state files by hand"
     )
     return [
         "terminal review mutation already consumed in this run "
-        f"({last.get('action')} on PR #{last.get('pr_number')}{head_note}); "
-        f"{guidance} (fail closed, #332); {recovery}"
+        f"({last.get('action')} on PR #{last.get('pr_number')}); {guidance} "
+        f"(fail closed, #332); {recovery}"
     ]
 
 
@@ -3842,11 +3781,18 @@ def gitea_mark_final_review_decision(
             "reasons": workflow_blockers + (
                 review_workflow_load.recovery_handoff_without_replay()),
         }
-    hard_stop = terminal_review_hard_stop_reasons(
-        pr_number, "mark_ready", expected_head_sha=expected_head_sha
-    )
+    hard_stop = terminal_review_hard_stop_reasons(pr_number, "mark_ready")
     if hard_stop:
         return {"marked_ready": False, "reasons": hard_stop}
+    if lock.get("live_mutations") and not lock.get("correction_authorized"):
+        return {
+            "marked_ready": False,
+            "reasons": [
+                "cannot mark final decision after a live review mutation was "
+                "already recorded in this run unless an operator-approved "
+                "correction was authorized"
+            ],
+        }
     if action not in _REVIEW_ACTIONS:
         return {
             "marked_ready": False,
@@ -3863,17 +3809,6 @@ def gitea_mark_final_review_decision(
                 "decision (fail closed, #399)"
             ],
         }
-    if stale_review_decision_lock.prior_live_mutations_block_boundary(
-        lock, pr_number=pr_number, expected_head_sha=expected_head_sha
-    ):
-        return {
-            "marked_ready": False,
-            "reasons": [
-                "cannot mark final decision after a live review mutation was "
-                "already recorded for this PR head unless an operator-approved "
-                "correction was authorized (fail closed, #620)"
-            ],
-        }
     elig = gitea_check_pr_eligibility(
         pr_number=pr_number,
         action="review",
@@ -3926,8 +3861,6 @@ def gitea_mark_final_review_decision(
                     "#332)"
                 ],
             }
-    # Preserve historical terminal head boundaries before advancing ready_* (#620).
-    stale_review_decision_lock.backfill_terminal_heads_from_ready(lock)
     lock["final_review_decision_ready"] = True
     lock["ready_pr_number"] = pr_number
     lock["ready_action"] = action
@@ -3945,7 +3878,6 @@ def gitea_mark_final_review_decision(
         "org": org,
         "repo": repo,
         "final_review_decision_ready": True,
-        "head_scoped": True,
         "reasons": [],
     }
 
@@ -4112,12 +4044,6 @@ def gitea_cleanup_stale_review_decision_lock(
         "cleanup_allowed": assessment.get("cleanup_allowed"),
         "last_terminal_pr": assessment.get("last_terminal_pr"),
         "last_terminal_action": assessment.get("last_terminal_action"),
-        "locked_head_sha": assessment.get("locked_head_sha"),
-        "current_pr_head_sha": assessment.get("current_pr_head_sha"),
-        "stale_by_head": assessment.get("stale_by_head"),
-        "fresh_review_on_current_head_allowed": assessment.get(
-            "fresh_review_on_current_head_allowed"
-        ),
         "pr_state": assessment.get("pr_state"),
         "pr_merged": assessment.get("pr_merged"),
         "pr_merged_or_closed": assessment.get("pr_merged_or_closed"),
@@ -8824,7 +8750,6 @@ def gitea_whoami(
         metadata: profile_name + allowed_operations; never the token).
     """
     record_preflight_check("whoami")
-    remote = _effective_remote(remote)
     if remote not in REMOTES:
         raise ValueError(f"Unknown remote '{remote}'. Choose from: {list(REMOTES)}")
     h = host or REMOTES[remote]["host"]
@@ -8933,6 +8858,8 @@ def gitea_get_profile(
         "execution_profile": profile.get("execution_profile"),
         "auth_source_type": profile.get("auth_source_type"),
         # Auth is reported as a status only (#120): the token source *name*
+        # (env var name / keychain id) joins endpoint URLs behind the
+        # GITEA_MCP_REVEAL_ENDPOINTS admin opt-in. Token values never appear.
         "auth_status": ("configured" if profile["token_source_name"]
                         else "unconfigured"),
         "remote": remote if remote in REMOTES else None,
@@ -8944,7 +8871,6 @@ def gitea_get_profile(
         result["base_url"] = profile["base_url"]
         result["server"] = None
 
-    remote = _effective_remote(remote)
     if remote not in REMOTES:
         # Mark ambiguity rather than raising: the tool stays inspectable.
         result["identity_status"] = "unknown"
@@ -11112,310 +11038,6 @@ def gitea_capability_stop_terminal_report() -> dict:
     })
 
 
-def _control_plane_db_or_error() -> tuple[Any | None, list[str]]:
-    """Open the #613 control-plane DB substrate; fail closed on errors."""
-    try:
-        db = control_plane_db.ControlPlaneDB()
-        return db, []
-    except Exception as exc:  # noqa: BLE001
-        return None, [
-            f"control-plane DB substrate unavailable: {_redact(str(exc))} "
-            "(fail closed, #613/#600)"
-        ]
-
-
-def _allocator_candidates_from_gitea(
-    *,
-    remote: str,
-    host: str | None,
-    org: str,
-    repo: str,
-    include_issues: bool = True,
-    include_prs: bool = True,
-    limit: int = 50,
-) -> tuple[list[Any], list[str]]:
-    """Build allocator candidates from live Gitea open issues/PRs."""
-    reasons: list[str] = []
-    candidates: list[Any] = []
-    try:
-        h, o, r = _resolve(remote, host, org, repo)
-        auth = _auth(h)
-    except Exception as exc:  # noqa: BLE001
-        return [], [f"failed to resolve Gitea target: {_redact(str(exc))}"]
-
-    if include_prs:
-        try:
-            prs = api_get_all(
-                f"{repo_api_url(h, o, r)}/pulls?state=open", auth
-            ) or []
-        except Exception as exc:  # noqa: BLE001
-            reasons.append(f"failed to list open PRs: {_redact(str(exc))}")
-            prs = []
-        for pr in prs[: max(1, int(limit))]:
-            if not isinstance(pr, dict):
-                continue
-            number = pr.get("number")
-            if number is None:
-                continue
-            head = pr.get("head") if isinstance(pr.get("head"), dict) else {}
-            head_sha = head.get("sha") or pr.get("head_sha")
-            labels = []
-            for lab in pr.get("labels") or []:
-                if isinstance(lab, dict) and lab.get("name"):
-                    labels.append(str(lab["name"]))
-                elif isinstance(lab, str):
-                    labels.append(lab)
-            # Lightweight review signals (best-effort; fail soft into reviewer path).
-            rc_current = False
-            approval_current = False
-            approval_stale = False
-            try:
-                feedback = gitea_get_pr_review_feedback(
-                    int(number), remote=remote, org=o, repo=r
-                )
-                if feedback.get("success"):
-                    rc_current = bool(
-                        feedback.get("has_blocking_change_requests")
-                        and not feedback.get("review_feedback_stale")
-                    )
-                    # Stale RC means author pushed; reviewer still next.
-                    if feedback.get("has_blocking_change_requests") and feedback.get(
-                        "review_feedback_stale"
-                    ):
-                        approval_stale = False
-            except Exception:
-                pass
-            mergeable = bool(pr.get("mergeable"))
-            try:
-                candidates.append(
-                    allocator_service.WorkCandidate(
-                        kind="pr",
-                        number=int(number),
-                        state="open",
-                        labels=tuple(labels),
-                        title=str(pr.get("title") or ""),
-                        priority=10 if rc_current else 5,
-                        head_sha=head_sha,
-                        request_changes_current_head=rc_current,
-                        approval_on_current_head=approval_current,
-                        approval_stale=approval_stale,
-                        mergeable=mergeable,
-                    )
-                )
-            except Exception as exc:  # noqa: BLE001
-                reasons.append(
-                    f"skipped invalid PR candidate #{number}: {_redact(str(exc))}"
-                )
-
-    if include_issues:
-        try:
-            issues = api_get_all(
-                f"{repo_api_url(h, o, r)}/issues?state=open&type=issues", auth
-            ) or []
-        except Exception as exc:  # noqa: BLE001
-            # Fallback without type filter
-            try:
-                issues = api_get_all(
-                    f"{repo_api_url(h, o, r)}/issues?state=open", auth
-                ) or []
-            except Exception as exc2:  # noqa: BLE001
-                reasons.append(
-                    f"failed to list open issues: {_redact(str(exc2))}"
-                )
-                issues = []
-        for issue in issues[: max(1, int(limit))]:
-            if not isinstance(issue, dict):
-                continue
-            # Pull requests also appear in /issues on Gitea — skip them.
-            if issue.get("pull_request") is not None:
-                continue
-            number = issue.get("number")
-            if number is None:
-                continue
-            labels = []
-            for lab in issue.get("labels") or []:
-                if isinstance(lab, dict) and lab.get("name"):
-                    labels.append(str(lab["name"]).lower())
-                elif isinstance(lab, str):
-                    labels.append(lab.lower())
-            body = str(issue.get("body") or "")
-            title = str(issue.get("title") or "")
-            blocked = "status:blocked" in labels
-            # Explicit downstream dependency: #612 waits on #600 allocator.
-            dep_unmet = False
-            dep_reason = None
-            if int(number) == 612:
-                dep_unmet = True
-                dep_reason = (
-                    "issue#612 (incident bridge) remains downstream of #600 "
-                    "allocator and must not be allocated until #600 is complete"
-                )
-            # Generic body markers for blocked-on unfinished deps.
-            lower_body = body.lower()
-            if "blocked on #600" in lower_body or "downstream of #600" in lower_body:
-                dep_unmet = True
-                dep_reason = dep_reason or (
-                    f"issue#{number} body marks dependency on #600"
-                )
-            try:
-                candidates.append(
-                    allocator_service.WorkCandidate(
-                        kind="issue",
-                        number=int(number),
-                        state="open",
-                        labels=tuple(labels),
-                        title=title,
-                        priority=20 if "status:ready" in labels else 1,
-                        blocked=blocked,
-                        dependency_unmet=dep_unmet,
-                        dependency_reason=dep_reason,
-                    )
-                )
-            except Exception as exc:  # noqa: BLE001
-                reasons.append(
-                    f"skipped invalid issue candidate #{number}: {_redact(str(exc))}"
-                )
-
-    return candidates, reasons
-
-
-@mcp.tool()
-def gitea_allocate_next_work(
-    apply: bool = False,
-    role: str | None = None,
-    session_id: str | None = None,
-    remote: str = "dadeschools",
-    host: str | None = None,
-    org: str | None = None,
-    repo: str | None = None,
-    include_issues: bool = True,
-    include_prs: bool = True,
-    candidates_json: str | None = None,
-    limit: int = 50,
-) -> dict:
-    """Controller-owned next-work allocator using the #613 control-plane DB (#600).
-
-    Workers must not self-select exclusive work under the standard multi-LLM
-    workflow. Call this tool instead.
-
-    *apply=false* (default): dry-run selection only — no assignment/lease.
-    *apply=true*: atomically assign + lease the selected Gitea issue/PR via
-    ``ControlPlaneDB.assign_and_lease`` (never file locks or comment-only
-    leases as the coordination source).
-
-    Outcomes include: ``assigned_work``, ``preview``, ``wait``,
-    ``blocked_by_terminal_path``, ``no_safe_work``, ``role_ineligible``.
-
-    *candidates_json* may inject a JSON list of candidate dicts (tests /
-    controller overrides). When omitted, open issues/PRs are loaded from Gitea.
-
-    #612 remains downstream: raw monitoring incidents are never candidates.
-    """
-    read_block = _profile_operation_gate("gitea.read")
-    if read_block:
-        return {
-            "success": False,
-            "outcome": allocator_service.OUTCOME_NO_SAFE,
-            "apply": bool(apply),
-            "reasons": read_block,
-            "permission_report": _permission_block_report("gitea.read"),
-            "assignment": None,
-            "substrate": "control_plane_db",
-            "file_lock_only": False,
-            "comment_lease_only": False,
-        }
-
-    try:
-        h, o, r = _resolve(remote, host, org, repo)
-    except ValueError as exc:
-        return {
-            "success": False,
-            "outcome": allocator_service.OUTCOME_NO_SAFE,
-            "reasons": [str(exc)],
-            "assignment": None,
-            "substrate": "control_plane_db",
-        }
-
-    profile = get_profile()
-    profile_name = (profile.get("profile_name") or "").strip() or None
-    active_role = _profile_role_kind(profile)
-    role_in = (role or active_role or "").strip() or "author"
-
-    try:
-        username = _authenticated_username(h)
-    except Exception:
-        username = None
-
-    db, db_errs = _control_plane_db_or_error()
-    if db is None:
-        return {
-            "success": False,
-            "outcome": allocator_service.OUTCOME_NO_SAFE,
-            "apply": bool(apply),
-            "reasons": db_errs,
-            "assignment": None,
-            "substrate": "control_plane_db",
-            "file_lock_only": False,
-            "comment_lease_only": False,
-        }
-
-    inv_reasons: list[str] = []
-    candidates: list[Any] = []
-    if candidates_json:
-        try:
-            raw = json.loads(candidates_json)
-            if not isinstance(raw, list):
-                raise ValueError("candidates_json must be a JSON list")
-            for item in raw:
-                if not isinstance(item, dict):
-                    continue
-                candidates.append(allocator_service.candidate_from_dict(item))
-        except Exception as exc:  # noqa: BLE001
-            return {
-                "success": False,
-                "outcome": allocator_service.OUTCOME_NO_SAFE,
-                "apply": bool(apply),
-                "reasons": [
-                    f"invalid candidates_json: {_redact(str(exc))} (fail closed)"
-                ],
-                "assignment": None,
-                "substrate": "control_plane_db",
-            }
-    else:
-        candidates, inv_reasons = _allocator_candidates_from_gitea(
-            remote=remote,
-            host=host,
-            org=o,
-            repo=r,
-            include_issues=include_issues,
-            include_prs=include_prs,
-            limit=limit,
-        )
-
-    sid = (session_id or "").strip() or (
-        f"{profile_name or 'session'}-{os.getpid()}-{uuid.uuid4().hex[:8]}"
-    )
-    result = allocator_service.allocate_next_work(
-        db,
-        session_id=sid,
-        role=role_in,
-        remote=remote if remote in REMOTES else remote,
-        org=o,
-        repo=r,
-        candidates=candidates,
-        apply=bool(apply),
-        profile_name=profile_name,
-        username=username,
-    )
-    if inv_reasons:
-        result.setdefault("inventory_warnings", inv_reasons)
-    result["candidate_count"] = len(candidates)
-    result["inventory_source"] = (
-        "candidates_json" if candidates_json else "gitea_live"
-    )
-    return result
-
-
 # ── Entry point ───────────────────────────────────────────────────────────────
 
 if __name__ == "__main__":

mcp_server.py

@@ -6,9 +6,6 @@ Runs over stdio. All tools authenticate via macOS keychain (git credential fill)
 import os
 import sys
 
-sys.stderr = open("/tmp/mcp_server_stderr.log", "a", buffering=1)
-sys.stderr.write(f"\n--- MCP SERVER STARTUP (PID {os.getpid()}) ---\n")
-
 from role_session_router import (
     python_bytes_have_conflict_markers,
     skip_python_scan_walk_root,

stale_review_decision_lock.py

@@ -1,4 +1,4 @@
-"""Stale / moot #332 review-decision lock detection and cleanup policy (#594/#620).
+"""Stale / moot #332 review-decision lock detection and cleanup policy (#594).
 
 #332 correctly hard-stops a reviewer session after a terminal live review
 mutation. After #559 those locks are durable on disk, so they can outlive the
@@ -6,12 +6,6 @@ work they protect: when the referenced PR is already merged or closed, no
 same-PR merge sequence remains, yet the durable ledger still blocks unrelated
 new terminal reviews.
 
-#620 scopes the terminal boundary by **reviewed head SHA**: a prior
-REQUEST_CHANGES (or APPROVE) on head A must not block a fresh formal decision
-on head B of the **same open PR**. Same-head duplicates remain fail-closed.
-Open-PR lock *cleanup* remains forbidden unless the PR is truly merged/closed
-(#594); new-head re-review is allowed without deleting the durable lock.
-
 This module is pure policy (no Gitea I/O). The MCP tool
 ``gitea_cleanup_stale_review_decision_lock`` fetches live PR state, calls these
 helpers, and only then clears durable state when cleanup is allowed.
@@ -29,45 +23,6 @@ from typing import Any
 TERMINAL_REVIEW_ACTIONS = frozenset({"approve", "request_changes"})
 
 
-def normalize_head_sha(value: Any) -> str | None:
-    """Normalize a git SHA for equality comparison; None if empty/invalid."""
-    if value is None:
-        return None
-    text = str(value).strip().lower()
-    if not text:
-        return None
-    return text
-
-
-def heads_equal(a: Any, b: Any) -> bool:
-    na = normalize_head_sha(a)
-    nb = normalize_head_sha(b)
-    if not na or not nb:
-        return False
-    return na == nb
-
-
-def mutation_head_sha(mutation: dict | None, lock: dict | None = None) -> str | None:
-    """Head SHA that bounds a live mutation (#620).
-
-    Prefers fields recorded on the mutation itself. For *legacy* mutations
-    that predate head-scoping, falls back to the lock's
-    ``ready_expected_head_sha`` only when that ready binding is for the same
-    PR number (the frozen durable PR #619-style ledger).
-    """
-    if not isinstance(mutation, dict):
-        return None
-    for key in ("head_sha", "expected_head_sha", "reviewed_head_sha"):
-        head = normalize_head_sha(mutation.get(key))
-        if head:
-            return head
-    if not isinstance(lock, dict):
-        return None
-    if lock.get("ready_pr_number") != mutation.get("pr_number"):
-        return None
-    return normalize_head_sha(lock.get("ready_expected_head_sha"))
-
-
 def last_terminal_mutation(lock: dict | None) -> dict | None:
     """Return the last terminal live mutation on *lock*, or None."""
     if not lock:
@@ -80,125 +35,18 @@ def last_terminal_mutation(lock: dict | None) -> dict | None:
     return terminals[-1] if terminals else None
 
 
-def prior_live_mutations_block_boundary(
-    lock: dict | None,
-    *,
-    pr_number: int,
-    expected_head_sha: str | None,
-) -> bool:
-    """True when prior live mutations block a new decision for PR+head (#620).
-
-    Historical terminals on a **different head of the same PR** do not block.
-    Any prior mutation on another PR, the same head, or without a comparable
-    head SHA fails closed (blocks).
-
-    Head resolution uses ``mutation_head_sha(m, lock)`` so pre-#620 ledgers
-    that only stored ``ready_expected_head_sha`` still compare correctly
-    (PR #619-style).
-    """
-    if not lock:
-        return False
-    if lock.get("correction_authorized"):
-        return False
-    prior = list(lock.get("live_mutations") or [])
-    if not prior:
-        return False
-    target = normalize_head_sha(expected_head_sha)
-    for m in prior:
-        if not isinstance(m, dict):
-            return True
-        m_pr = m.get("pr_number")
-        m_head = mutation_head_sha(m, lock)
-        if (
-            m_pr == pr_number
-            and target
-            and m_head
-            and not heads_equal(m_head, target)
-        ):
-            # Same open PR, different reviewed head — historical boundary only.
-            continue
-        return True
-    return False
-
-
-def terminal_boundary_allows_fresh_decision(
-    lock: dict | None,
-    *,
-    pr_number: int,
-    expected_head_sha: str | None,
-    operation: str,
-) -> bool:
-    """Whether #332 hard-stop should yield for a new PR+head boundary (#620).
-
-    Only for ``mark_ready`` / ``review`` / ``resume`` on the **same PR** when
-    the requested head differs from the last terminal's head. Merge is never
-    reopened by head change (approved head merge path is separate).
-    """
-    if operation not in ("mark_ready", "review", "resume"):
-        return False
-    if not lock:
-        return False
-    if lock.get("correction_authorized"):
-        return True
-    last = last_terminal_mutation(lock)
-    if last is None:
-        return True
-    if last.get("pr_number") != pr_number:
-        return False
-    locked_head = mutation_head_sha(last, lock)
-    target = normalize_head_sha(expected_head_sha)
-    if not locked_head or not target:
-        return False
-    return not heads_equal(locked_head, target)
-
-
-def backfill_terminal_heads_from_ready(lock: dict) -> dict:
-    """Stamp head_sha onto legacy terminal mutations before overwriting ready_*.
-
-    Called when marking a fresh decision on a new head so historical rows keep
-    their original boundary after ``ready_expected_head_sha`` advances (#620).
-    """
-    if not isinstance(lock, dict):
-        return lock
-    ready_pr = lock.get("ready_pr_number")
-    ready_head = normalize_head_sha(lock.get("ready_expected_head_sha"))
-    if ready_pr is None or not ready_head:
-        return lock
-    mutations = list(lock.get("live_mutations") or [])
-    changed = False
-    for m in mutations:
-        if not isinstance(m, dict):
-            continue
-        if m.get("action") not in TERMINAL_REVIEW_ACTIONS:
-            continue
-        if m.get("pr_number") != ready_pr:
-            continue
-        if mutation_head_sha(m):
-            continue
-        m["head_sha"] = ready_head
-        changed = True
-    if changed:
-        lock["live_mutations"] = mutations
-    return lock
-
-
 def classify_pr_live_state(pr_live: dict | None) -> dict[str, Any]:
     """Normalize a Gitea PR payload into merge/closed flags."""
     pr = pr_live or {}
     merged = bool(pr.get("merged") or pr.get("merged_at"))
     state = (pr.get("state") or "").strip().lower() or None
     closed = state == "closed"
-    head = pr.get("head") if isinstance(pr.get("head"), dict) else {}
-    head_sha = normalize_head_sha(
-        pr.get("head_sha") or pr.get("head_commit_sha") or head.get("sha")
-    )
     return {
         "pr_state": state,
         "pr_merged": merged,
         "pr_merged_or_closed": merged or closed,
         "merge_commit_sha": pr.get("merge_commit_sha")
         or pr.get("merged_commit_sha"),
-        "current_pr_head_sha": head_sha,
     }
 
 
@@ -208,7 +56,6 @@ def lock_summary(lock: dict | None) -> dict[str, Any] | None:
         return None
     last = last_terminal_mutation(lock)
     mutations = list(lock.get("live_mutations") or [])
-    last_head = mutation_head_sha(last, lock) if last else None
     return {
         "task": lock.get("task"),
         "remote": lock.get("remote"),
@@ -220,21 +67,16 @@ def lock_summary(lock: dict | None) -> dict[str, Any] | None:
         "session_profile": lock.get("session_profile"),
         "ready_pr_number": lock.get("ready_pr_number"),
         "ready_action": lock.get("ready_action"),
-        "ready_expected_head_sha": normalize_head_sha(
-            lock.get("ready_expected_head_sha")
-        ),
         "live_mutations_count": len(mutations),
         "last_terminal": (
             {
                 "pr_number": last.get("pr_number"),
                 "action": last.get("action"),
                 "review_id": last.get("review_id"),
-                "head_sha": last_head,
             }
             if last
             else None
         ),
-        "locked_head_sha": last_head,
         "correction_authorized": bool(lock.get("correction_authorized")),
         "updated_at": lock.get("updated_at") or lock.get("recorded_at"),
     }
@@ -246,16 +88,13 @@ def assess_stale_review_decision_lock(
     pr_live: dict | None = None,
     pr_lookup_error: str | None = None,
     active_profile_identity: str | None = None,
-    current_pr_head_sha: str | None = None,
 ) -> dict[str, Any]:
-    """Assess whether a durable review-decision lock is stale/moot (#594/#620).
+    """Assess whether a durable review-decision lock is stale/moot (#594).
 
     *pr_live* must be the live Gitea payload for the **last terminal
     mutation's PR**. When no lock / no terminal mutation exists, cleanup is
     not applicable. When the PR is still open (or lookup fails), cleanup is
-    forbidden (#594). Open PR + different live head reports
-    ``stale_by_head`` / ``fresh_review_on_current_head_allowed`` (#620)
-    without enabling cleanup.
+    forbidden and #332 hard-stop remains in force.
     """
     summary = lock_summary(lock)
     result: dict[str, Any] = {
@@ -263,10 +102,6 @@ def assess_stale_review_decision_lock(
         "lock_summary": summary,
         "last_terminal_pr": None,
         "last_terminal_action": None,
-        "locked_head_sha": None,
-        "current_pr_head_sha": normalize_head_sha(current_pr_head_sha),
-        "stale_by_head": False,
-        "fresh_review_on_current_head_allowed": False,
         "is_moot": False,
         "cleanup_allowed": False,
         "profile_match": True,
@@ -306,10 +141,8 @@ def assess_stale_review_decision_lock(
 
     pr_number = last.get("pr_number")
     action = last.get("action")
-    locked_head = mutation_head_sha(last, lock)
     result["last_terminal_pr"] = pr_number
     result["last_terminal_action"] = action
-    result["locked_head_sha"] = locked_head
 
     if pr_number is None:
         result["reasons"].append(
@@ -332,35 +165,16 @@ def assess_stale_review_decision_lock(
         return result
 
     live = classify_pr_live_state(pr_live)
-    current_head = normalize_head_sha(
-        current_pr_head_sha or live.get("current_pr_head_sha")
-    )
     result.update(
         {
             "pr_state": live["pr_state"],
             "pr_merged": live["pr_merged"],
             "pr_merged_or_closed": live["pr_merged_or_closed"],
             "merge_commit_sha": live["merge_commit_sha"],
-            "current_pr_head_sha": current_head,
         }
     )
 
     if not live["pr_merged_or_closed"]:
-        stale_by_head = bool(
-            locked_head and current_head and not heads_equal(locked_head, current_head)
-        )
-        result["stale_by_head"] = stale_by_head
-        # Fresh formal decision is allowed on the new head without cleanup (#620).
-        result["fresh_review_on_current_head_allowed"] = stale_by_head
-        if stale_by_head:
-            result["reasons"].append(
-                f"terminal {action} on PR #{pr_number} is bound to head "
-                f"{locked_head[:12]}…; live head is {current_head[:12]}… — "
-                "fresh formal review on current head is allowed without "
-                "cleanup (fail closed for cleanup, #620); #332 same-head "
-                "duplicate protection remains"
-            )
-        else:
         result["reasons"].append(
             f"terminal review mutation on open PR #{pr_number} is still active "
             f"({action}); #332 hard-stop remains — cleanup forbidden (#594)"
@@ -370,8 +184,6 @@ def assess_stale_review_decision_lock(
     # Merged or closed: lock is moot. Same-PR merge continuation is impossible.
     result["is_moot"] = True
     result["cleanup_allowed"] = True
-    result["stale_by_head"] = False
-    result["fresh_review_on_current_head_allowed"] = False
     result["reasons"].append(
         f"terminal mutation ({action} on PR #{pr_number}) is moot: PR is "
         f"{'merged' if live['pr_merged'] else 'closed'}; canonical cleanup allowed (#594)"

task_capability_map.py

@@ -139,17 +139,6 @@ TASK_CAPABILITY_MAP: dict[str, dict[str, str]] = {
         "permission": "gitea.pr.create",
         "role": "author",
     },
-    # #600: controller-owned allocator — any authenticated profile may call;
-    # routing enforces role match to selected work. Uses control-plane DB (#613).
-    "allocate_next_work": {
-        "permission": "gitea.read",
-        "role": "author",
-    },
-    "gitea_allocate_next_work": {
-        "permission": "gitea.read",
-        "role": "author",
-    },
-
     "reconcile_landed_pr": {
         "permission": "gitea.read",
         "role": "author",

test_mcp_conn.py

@@ -275,6 +275,7 @@ def main():
                 servers[name],
                 required_tool=REQUIRED_NAMESPACE_TOOLS.get(name),
                 config_path=config_path,
+                probe_source="offline_spawn",
             ):
                 failed = True
         else:

tests/test_allocator_service.py

@@ -1,366 +0,0 @@
-"""Tests for controller-owned allocator (#600) on control-plane DB (#613)."""
-
-from __future__ import annotations
-
-import os
-import tempfile
-import threading
-import unittest
-from concurrent.futures import ThreadPoolExecutor, as_completed
-
-from allocator_service import (
-    OUTCOME_ASSIGNED,
-    OUTCOME_BLOCKED_TERMINAL,
-    OUTCOME_NO_SAFE,
-    OUTCOME_PREVIEW,
-    OUTCOME_WAIT,
-    WorkCandidate,
-    allocate_next_work,
-    candidate_from_dict,
-    classify_skip,
-    expected_role_for_candidate,
-)
-from control_plane_db import ControlPlaneDB, InvalidWorkKindError
-
-
-class AllocatorServiceTest(unittest.TestCase):
-    def setUp(self) -> None:
-        self._tmp = tempfile.TemporaryDirectory()
-        self.db_path = os.path.join(self._tmp.name, "cp.sqlite3")
-        self.db = ControlPlaneDB(self.db_path)
-
-    def tearDown(self) -> None:
-        self._tmp.cleanup()
-
-    def _alloc(self, **kwargs):
-        defaults = dict(
-            db=self.db,
-            session_id="s-test",
-            role="author",
-            remote="prgs",
-            org="org",
-            repo="repo",
-            candidates=[],
-            apply=False,
-            profile_name="prgs-author",
-            username="jcwalker3",
-        )
-        defaults.update(kwargs)
-        return allocate_next_work(**defaults)
-
-    def test_selects_ready_issue_for_author(self) -> None:
-        cands = [
-            WorkCandidate(
-                kind="issue",
-                number=612,
-                labels=("status:ready",),
-                title="bridge",
-                dependency_unmet=True,
-                dependency_reason="downstream of #600",
-            ),
-            WorkCandidate(
-                kind="issue",
-                number=600,
-                labels=("status:ready", "type:feature"),
-                title="allocator",
-                priority=50,
-            ),
-            WorkCandidate(
-                kind="issue",
-                number=601,
-                labels=("status:blocked",),
-                title="blocked",
-                blocked=True,
-            ),
-        ]
-        res = self._alloc(candidates=cands, apply=False)
-        self.assertTrue(res["success"])
-        self.assertEqual(res["outcome"], OUTCOME_PREVIEW)
-        self.assertEqual(res["selected"]["number"], 600)
-        self.assertEqual(res["selected"]["kind"], "issue")
-        # When 600 is highest priority valid work, lower-priority blocked/dep
-        # candidates are not visited. Prove they are skipped when they sort first.
-        res2 = self._alloc(
-            candidates=[
-                WorkCandidate(
-                    kind="issue",
-                    number=612,
-                    labels=("status:ready",),
-                    priority=99,
-                    dependency_unmet=True,
-                    dependency_reason="downstream of #600",
-                ),
-                WorkCandidate(
-                    kind="issue",
-                    number=601,
-                    labels=("status:blocked",),
-                    priority=98,
-                    blocked=True,
-                ),
-                WorkCandidate(
-                    kind="issue",
-                    number=600,
-                    labels=("status:ready",),
-                    priority=1,
-                ),
-            ],
-            apply=False,
-        )
-        skipped_nums = {s["number"] for s in res2["skipped"]}
-        self.assertIn(612, skipped_nums)
-        self.assertIn(601, skipped_nums)
-        self.assertEqual(res2["selected"]["number"], 600)
-        self.assertIsNone(res["assignment"])
-        self.assertFalse(res["file_lock_only"])
-        self.assertFalse(res["comment_lease_only"])
-
-    def test_atomic_assign_and_lease_on_apply(self) -> None:
-        cands = [
-            WorkCandidate(
-                kind="issue",
-                number=600,
-                labels=("status:ready",),
-                priority=10,
-            )
-        ]
-        res = self._alloc(candidates=cands, apply=True, session_id="s-a")
-        self.assertEqual(res["outcome"], OUTCOME_ASSIGNED)
-        asn = res["assignment"]
-        self.assertEqual(asn["outcome"], "assigned")
-        self.assertIsNotNone(asn["assignment_id"])
-        self.assertIsNotNone(asn["lease_id"])
-        self.assertEqual(asn["work_number"], 600)
-        self.assertIn("implement", asn["allowed_actions"])
-        self.assertIn("merge", asn["forbidden_actions"])
-        proof = res["lease_proof"]
-        self.assertEqual(proof["source"], "control_plane_db.assign_and_lease")
-
-    def test_concurrent_allocators_no_double_assign(self) -> None:
-        cand = WorkCandidate(
-            kind="pr",
-            number=100,
-            head_sha="a" * 40,
-            priority=10,
-        )
-        # Seed work item so both race the same target
-        self.db.upsert_work_item(
-            remote="prgs",
-            org="org",
-            repo="repo",
-            kind="pr",
-            number=100,
-            current_head_sha="a" * 40,
-        )
-        results = []
-        lock = threading.Lock()
-
-        def worker(sid: str):
-            r = allocate_next_work(
-                self.db,
-                session_id=sid,
-                role="reviewer",
-                remote="prgs",
-                org="org",
-                repo="repo",
-                candidates=[cand],
-                apply=True,
-                profile_name="prgs-reviewer",
-            )
-            with lock:
-                results.append(r)
-
-        with ThreadPoolExecutor(max_workers=2) as pool:
-            futs = [pool.submit(worker, f"s-{i}") for i in range(2)]
-            for f in as_completed(futs):
-                f.result()
-
-        outcomes = [r["outcome"] for r in results]
-        self.assertEqual(outcomes.count(OUTCOME_ASSIGNED), 1, outcomes)
-        self.assertEqual(outcomes.count(OUTCOME_WAIT), 1, outcomes)
-
-    def test_blocked_and_dependency_skipped(self) -> None:
-        cands = [
-            WorkCandidate(kind="issue", number=1, blocked=True, labels=("status:blocked",)),
-            WorkCandidate(
-                kind="issue",
-                number=612,
-                labels=("status:ready",),
-                dependency_unmet=True,
-                dependency_reason="downstream of #600",
-            ),
-        ]
-        res = self._alloc(candidates=cands, apply=True, role="author")
-        self.assertEqual(res["outcome"], OUTCOME_NO_SAFE)
-        self.assertIsNone(res["selected"])
-        reasons = " ".join(s["reason"] for s in res["skipped"])
-        self.assertIn("blocked", reasons.lower())
-        self.assertIn("600", reasons)
-
-    def test_already_leased_returns_wait(self) -> None:
-        self.db.upsert_session(session_id="owner", role="author")
-        self.db.assign_and_lease(
-            session_id="owner",
-            role="author",
-            remote="prgs",
-            org="org",
-            repo="repo",
-            kind="issue",
-            number=50,
-        )
-        res = self._alloc(
-            session_id="other",
-            candidates=[
-                WorkCandidate(kind="issue", number=50, labels=("status:ready",))
-            ],
-            apply=True,
-        )
-        self.assertEqual(res["outcome"], OUTCOME_WAIT)
-        self.assertEqual(res["owner_session_id"], "owner")
-
-    def test_role_ineligible_skipped(self) -> None:
-        # PR with current-head REQUEST_CHANGES expects author, not reviewer.
-        cand = WorkCandidate(
-            kind="pr",
-            number=9,
-            head_sha="b" * 40,
-            request_changes_current_head=True,
-        )
-        self.assertEqual(expected_role_for_candidate(cand), "author")
-        res = self._alloc(
-            role="reviewer",
-            profile_name="prgs-reviewer",
-            candidates=[cand],
-            apply=False,
-        )
-        self.assertEqual(res["outcome"], OUTCOME_NO_SAFE)
-        self.assertTrue(any("expects role" in s["reason"] for s in res["skipped"]))
-
-    def test_terminal_lock_blocks_downstream_reviewer_prs(self) -> None:
-        self.db.set_terminal_lock(
-            remote="prgs",
-            org="org",
-            repo="repo",
-            terminal_pr=10,
-            decision="request_changes",
-            status="active",
-        )
-        cands = [
-            WorkCandidate(kind="pr", number=11, head_sha="c" * 40, priority=5),
-            WorkCandidate(kind="pr", number=10, head_sha="d" * 40, priority=1),
-        ]
-        res = self._alloc(
-            role="reviewer",
-            profile_name="prgs-reviewer",
-            candidates=cands,
-            apply=False,
-        )
-        # Terminal PR #10 is selectable; #11 skipped for terminal path.
-        self.assertEqual(res["selected"]["number"], 10)
-        self.assertTrue(
-            any(
-                s["number"] == 11 and "terminal-review lock" in s["reason"]
-                for s in res["skipped"]
-            )
-        )
-
-    def test_terminal_lock_blocks_all_when_only_downstream(self) -> None:
-        self.db.set_terminal_lock(
-            remote="prgs",
-            org="org",
-            repo="repo",
-            terminal_pr=10,
-            decision="request_changes",
-            status="active",
-        )
-        res = self._alloc(
-            role="reviewer",
-            profile_name="prgs-reviewer",
-            candidates=[
-                WorkCandidate(kind="pr", number=99, head_sha="e" * 40),
-            ],
-            apply=False,
-        )
-        self.assertEqual(res["outcome"], OUTCOME_BLOCKED_TERMINAL)
-
-    def test_no_work_structured(self) -> None:
-        res = self._alloc(candidates=[], apply=True)
-        self.assertEqual(res["outcome"], OUTCOME_NO_SAFE)
-        self.assertIsNone(res["selected"])
-        self.assertTrue(res["reasons"])
-
-    def test_rejects_incident_kind(self) -> None:
-        with self.assertRaises(InvalidWorkKindError):
-            WorkCandidate(kind="sentry_incident", number=1)
-
-    def test_612_downstream_marker_in_result(self) -> None:
-        res = self._alloc(
-            candidates=[
-                WorkCandidate(kind="issue", number=600, labels=("status:ready",))
-            ],
-            apply=True,
-        )
-        self.assertIn("612", res.get("downstream_note", ""))
-
-    def test_substrate_not_file_or_comment_lease(self) -> None:
-        res = self._alloc(
-            candidates=[
-                WorkCandidate(kind="issue", number=1, labels=("status:ready",))
-            ],
-            apply=True,
-        )
-        self.assertEqual(res["substrate"], "control_plane_db")
-        self.assertFalse(res["file_lock_only"])
-        self.assertFalse(res["comment_lease_only"])
-        self.assertEqual(
-            res["lease_proof"]["source"], "control_plane_db.assign_and_lease"
-        )
-
-    def test_candidate_from_dict(self) -> None:
-        c = candidate_from_dict(
-            {
-                "kind": "pr",
-                "number": 7,
-                "head_sha": "f" * 40,
-                "approval_on_current_head": True,
-                "mergeable": True,
-            }
-        )
-        self.assertEqual(expected_role_for_candidate(c), "merger")
-
-    def test_merger_gets_clean_approval(self) -> None:
-        c = WorkCandidate(
-            kind="pr",
-            number=3,
-            head_sha="1" * 40,
-            approval_on_current_head=True,
-            mergeable=True,
-            priority=100,
-        )
-        res = self._alloc(
-            role="merger",
-            profile_name="prgs-merger",
-            candidates=[c],
-            apply=True,
-            session_id="merger-1",
-        )
-        self.assertEqual(res["outcome"], OUTCOME_ASSIGNED)
-        self.assertEqual(res["assignment"]["work_number"], 3)
-        self.assertIn("merge", res["assignment"]["allowed_actions"])
-
-    def test_db_unavailable_fails_closed(self) -> None:
-        res = allocate_next_work(
-            None,  # type: ignore[arg-type]
-            session_id="x",
-            role="author",
-            remote="prgs",
-            org="o",
-            repo="r",
-            candidates=[],
-            apply=True,
-        )
-        self.assertFalse(res["success"])
-        self.assertIn("unavailable", res["reasons"][0].lower())
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/test_control_plane_db.py

@@ -1,824 +0,0 @@
-"""Tests for control-plane DB substrate (#613)."""
-
-from __future__ import annotations
-
-import os
-import tempfile
-import threading
-import unittest
-from concurrent.futures import ThreadPoolExecutor, as_completed
-from datetime import timedelta
-
-from control_plane_db import (
-    ControlPlaneDB,
-    InvalidWorkKindError,
-    LeaseRequiredError,
-    WORK_KINDS,
-    _ts,
-    _utc_now,
-)
-
-
-class ControlPlaneDBTest(unittest.TestCase):
-    def setUp(self) -> None:
-        self._tmp = tempfile.TemporaryDirectory()
-        self.db_path = os.path.join(self._tmp.name, "cp.sqlite3")
-        self.db = ControlPlaneDB(self.db_path)
-
-    def tearDown(self) -> None:
-        self._tmp.cleanup()
-
-    def test_schema_and_architecture_meta(self) -> None:
-        import sqlite3
-
-        conn = sqlite3.connect(self.db_path)
-        try:
-            rows = dict(conn.execute("SELECT key, value FROM schema_meta").fetchall())
-        finally:
-            conn.close()
-        self.assertEqual(rows["schema_version"], "2")
-        self.assertIn("DB coordinates", rows["architecture"])
-        self.assertIn("bridge", rows["architecture"].lower())
-
-    def test_rejects_raw_incident_as_work_kind(self) -> None:
-        with self.assertRaises(InvalidWorkKindError):
-            self.db.upsert_work_item(
-                remote="prgs",
-                org="org",
-                repo="repo",
-                kind="sentry_incident",
-                number=1,
-            )
-        with self.assertRaises(InvalidWorkKindError):
-            self.db.assign_and_lease(
-                session_id="s1",
-                role="author",
-                remote="prgs",
-                org="org",
-                repo="repo",
-                kind="glitchtip_incident",
-                number=9,
-            )
-        self.assertEqual(WORK_KINDS, frozenset({"issue", "pr"}))
-
-    def test_atomic_assign_and_lease_fields(self) -> None:
-        self.db.upsert_session(session_id="s-a", role="author", profile="prgs-author")
-        result = self.db.assign_and_lease(
-            session_id="s-a",
-            role="author",
-            remote="prgs",
-            org="Scaled-Tech-Consulting",
-            repo="Gitea-Tools",
-            kind="issue",
-            number=613,
-            expected_head_sha="abc123",
-            allowed_actions=("implement", "comment"),
-            forbidden_actions=("approve", "merge"),
-        )
-        self.assertEqual(result.outcome, "assigned")
-        self.assertIsNotNone(result.assignment_id)
-        self.assertIsNotNone(result.lease_id)
-        self.assertEqual(result.role, "author")
-        self.assertEqual(result.work_kind, "issue")
-        self.assertEqual(result.work_number, 613)
-        self.assertEqual(result.expected_head_sha, "abc123")
-        self.assertIn("implement", result.allowed_actions)
-        self.assertIn("merge", result.forbidden_actions)
-        self.assertIsNotNone(result.expires_at)
-
-    def test_second_session_waits_on_foreign_lease(self) -> None:
-        self.db.upsert_session(session_id="s1", role="author")
-        self.db.upsert_session(session_id="s2", role="author")
-        first = self.db.assign_and_lease(
-            session_id="s1",
-            role="author",
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="pr",
-            number=100,
-            expected_head_sha="deadbeef",
-        )
-        self.assertEqual(first.outcome, "assigned")
-        second = self.db.assign_and_lease(
-            session_id="s2",
-            role="author",
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="pr",
-            number=100,
-            expected_head_sha="deadbeef",
-        )
-        self.assertEqual(second.outcome, "wait")
-        self.assertEqual(second.owner_session_id, "s1")
-
-    def test_owner_resume_refreshes_lease(self) -> None:
-        self.db.upsert_session(session_id="s1", role="reviewer")
-        a = self.db.assign_and_lease(
-            session_id="s1",
-            role="reviewer",
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="pr",
-            number=50,
-            expected_head_sha="head-50",
-        )
-        b = self.db.assign_and_lease(
-            session_id="s1",
-            role="reviewer",
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="pr",
-            number=50,
-            expected_head_sha="head-50",
-        )
-        self.assertEqual(b.outcome, "assigned")
-        self.assertEqual(b.lease_id, a.lease_id)
-        self.assertIn("owner-resume", b.reason)
-
-    def test_require_valid_assignment_gates_mutations(self) -> None:
-        self.db.upsert_session(session_id="s1", role="author")
-        self.db.assign_and_lease(
-            session_id="s1",
-            role="author",
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="issue",
-            number=7,
-            allowed_actions=("implement",),
-            forbidden_actions=("merge",),
-        )
-        proof = self.db.require_valid_assignment(
-            session_id="s1",
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="issue",
-            number=7,
-            action="implement",
-        )
-        self.assertEqual(proof["session_id"], "s1")
-        with self.assertRaises(LeaseRequiredError):
-            self.db.require_valid_assignment(
-                session_id="s1",
-                remote="prgs",
-                org="o",
-                repo="r",
-                kind="issue",
-                number=7,
-                action="merge",
-            )
-        with self.assertRaises(LeaseRequiredError):
-            self.db.require_valid_assignment(
-                session_id="s-other",
-                remote="prgs",
-                org="o",
-                repo="r",
-                kind="issue",
-                number=7,
-                action="implement",
-            )
-
-    def test_expired_lease_allows_reassign(self) -> None:
-        self.db.upsert_session(session_id="s1", role="author")
-        self.db.upsert_session(session_id="s2", role="author")
-        past = _utc_now() - timedelta(hours=1)
-        # Create lease already expired by using negative TTL edge via direct assign then expire
-        assigned = self.db.assign_and_lease(
-            session_id="s1",
-            role="author",
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="issue",
-            number=3,
-            lease_ttl_seconds=1,
-        )
-        self.assertEqual(assigned.outcome, "assigned")
-        # Force expiry in DB
-        import sqlite3
-
-        conn = sqlite3.connect(self.db_path)
-        try:
-            conn.execute(
-                "UPDATE leases SET expires_at = ? WHERE lease_id = ?",
-                (_ts(past), assigned.lease_id),
-            )
-            conn.commit()
-        finally:
-            conn.close()
-        n = self.db.expire_stale_leases()
-        self.assertGreaterEqual(n, 1)
-        second = self.db.assign_and_lease(
-            session_id="s2",
-            role="author",
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="issue",
-            number=3,
-        )
-        self.assertEqual(second.outcome, "assigned")
-        self.assertEqual(second.session_id, "s2")
-
-    def test_merged_work_never_assigned(self) -> None:
-        self.db.upsert_session(session_id="s1", role="merger")
-        self.db.upsert_work_item(
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="pr",
-            number=99,
-            state="merged",
-        )
-        result = self.db.assign_and_lease(
-            session_id="s1",
-            role="merger",
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="pr",
-            number=99,
-            expected_head_sha="merged-head",
-        )
-        self.assertEqual(result.outcome, "no_safe_work")
-
-    def test_four_concurrent_sessions_unique_assignments(self) -> None:
-        """Four concurrent assigners on four different issues — all succeed uniquely.
-
-        Also two concurrent assigners on the *same* issue: at most one assigned.
-        """
-        for i in range(4):
-            self.db.upsert_session(session_id=f"sess-{i}", role="author")
-
-        def claim_unique(i: int):
-            return self.db.assign_and_lease(
-                session_id=f"sess-{i}",
-                role="author",
-                remote="prgs",
-                org="o",
-                repo="r",
-                kind="issue",
-                number=1000 + i,
-            )
-
-        with ThreadPoolExecutor(max_workers=4) as pool:
-            results = [f.result() for f in as_completed([pool.submit(claim_unique, i) for i in range(4)])]
-        self.assertEqual({r.outcome for r in results}, {"assigned"})
-        numbers = sorted(r.work_number for r in results)
-        self.assertEqual(numbers, [1000, 1001, 1002, 1003])
-
-        # Contention on one item
-        self.db.upsert_session(session_id="c1", role="author")
-        self.db.upsert_session(session_id="c2", role="author")
-        self.db.upsert_session(session_id="c3", role="author")
-        self.db.upsert_session(session_id="c4", role="author")
-        barrier = threading.Barrier(4)
-        outcomes: list[str] = []
-        lock = threading.Lock()
-
-        def contend(sid: str) -> None:
-            barrier.wait()
-            res = self.db.assign_and_lease(
-                session_id=sid,
-                role="author",
-                remote="prgs",
-                org="o",
-                repo="r",
-                kind="issue",
-                number=7777,
-            )
-            with lock:
-                outcomes.append(res.outcome)
-
-        threads = [threading.Thread(target=contend, args=(f"c{i}",)) for i in range(1, 5)]
-        for t in threads:
-            t.start()
-        for t in threads:
-            t.join()
-        self.assertEqual(outcomes.count("assigned"), 1)
-        self.assertEqual(outcomes.count("wait"), 3)
-
-    def test_terminal_lock_index(self) -> None:
-        self.db.set_terminal_lock(
-            remote="prgs",
-            org="o",
-            repo="r",
-            terminal_pr=332,
-            review_id="rev-1",
-            decision="approve",
-        )
-        row = self.db.get_active_terminal_lock(remote="prgs", org="o", repo="r")
-        self.assertIsNotNone(row)
-        assert row is not None
-        self.assertEqual(row["terminal_pr"], 332)
-        self.assertEqual(row["status"], "active")
-
-    def test_incident_links_not_work_items(self) -> None:
-        link = self.db.upsert_incident_link(
-            provider="sentry",
-            provider_base_url="https://sentry.prgs.cc",
-            provider_org="prgs",
-            provider_project="gitea-tools-mcp",
-            provider_issue_id="12345",
-            gitea_org="Scaled-Tech-Consulting",
-            gitea_repo="Gitea-Tools",
-            gitea_issue_number=9001,
-            fingerprint="fp-1",
-        )
-        self.assertEqual(link["gitea_issue_number"], 9001)
-        found = self.db.get_incident_link_for_gitea_issue(
-            gitea_org="Scaled-Tech-Consulting",
-            gitea_repo="Gitea-Tools",
-            gitea_issue_number=9001,
-        )
-        self.assertIsNotNone(found)
-        # Linking does not create a work_item of incident kind
-        with self.assertRaises(InvalidWorkKindError):
-            self.db.upsert_work_item(
-                remote="prgs",
-                org="Scaled-Tech-Consulting",
-                repo="Gitea-Tools",
-                kind="sentry",
-                number=12345,
-            )
-
-    def test_heartbeat_and_release(self) -> None:
-        self.db.upsert_session(session_id="s1", role="author")
-        a = self.db.assign_and_lease(
-            session_id="s1",
-            role="author",
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="issue",
-            number=1,
-        )
-        hb = self.db.heartbeat_lease(a.lease_id, session_id="s1")
-        self.assertEqual(hb["lease_id"], a.lease_id)
-        self.db.release_lease(a.lease_id, session_id="s1")
-        # After release another session can claim
-        self.db.upsert_session(session_id="s2", role="author")
-        b = self.db.assign_and_lease(
-            session_id="s2",
-            role="author",
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="issue",
-            number=1,
-        )
-        self.assertEqual(b.outcome, "assigned")
-        self.assertEqual(b.session_id, "s2")
-
-    def test_require_valid_assignment_rejects_stale_head(self) -> None:
-        """Assignment must not authorize mutations after work-item head drifts."""
-        self.db.upsert_session(session_id="s1", role="author")
-        self.db.assign_and_lease(
-            session_id="s1",
-            role="author",
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="pr",
-            number=42,
-            expected_head_sha="head-v1",
-            allowed_actions=("implement",),
-        )
-        # Head drifts after assignment
-        self.db.upsert_work_item(
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="pr",
-            number=42,
-            current_head_sha="head-v2",
-        )
-        with self.assertRaises(LeaseRequiredError) as ctx:
-            self.db.require_valid_assignment(
-                session_id="s1",
-                remote="prgs",
-                org="o",
-                repo="r",
-                kind="pr",
-                number=42,
-                action="implement",
-            )
-        self.assertIn("stale head", str(ctx.exception).lower())
-
-    def test_require_valid_assignment_rejects_terminal_state(self) -> None:
-        """Assignment must not authorize mutations after work item is merged/closed."""
-        self.db.upsert_session(session_id="s1", role="author")
-        self.db.assign_and_lease(
-            session_id="s1",
-            role="author",
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="pr",
-            number=55,
-            expected_head_sha="abc",
-            allowed_actions=("implement",),
-        )
-        self.db.upsert_work_item(
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="pr",
-            number=55,
-            state="merged",
-            current_head_sha="abc",
-        )
-        with self.assertRaises(LeaseRequiredError) as ctx:
-            self.db.require_valid_assignment(
-                session_id="s1",
-                remote="prgs",
-                org="o",
-                repo="r",
-                kind="pr",
-                number=55,
-                action="implement",
-            )
-        self.assertIn("terminal", str(ctx.exception).lower())
-
-        self.db.upsert_work_item(
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="issue",
-            number=56,
-            state="open",
-        )
-        self.db.assign_and_lease(
-            session_id="s1",
-            role="author",
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="issue",
-            number=56,
-            allowed_actions=("implement",),
-        )
-        self.db.upsert_work_item(
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="issue",
-            number=56,
-            state="closed",
-        )
-        with self.assertRaises(LeaseRequiredError):
-            self.db.require_valid_assignment(
-                session_id="s1",
-                remote="prgs",
-                org="o",
-                repo="r",
-                kind="issue",
-                number=56,
-                action="implement",
-            )
-
-    def test_pr_assignment_requires_expected_head_sha(self) -> None:
-        """PR assign and mutation must fail closed without a head pin."""
-        self.db.upsert_session(session_id="s1", role="author")
-        with self.assertRaises(LeaseRequiredError) as ctx:
-            self.db.assign_and_lease(
-                session_id="s1",
-                role="author",
-                remote="prgs",
-                org="o",
-                repo="r",
-                kind="pr",
-                number=88,
-                expected_head_sha=None,
-                allowed_actions=("implement",),
-            )
-        self.assertIn("expected_head_sha", str(ctx.exception))
-
-        # Legacy path: force an unpinned PR assignment into the DB, then
-        # populate head and prove mutation is still rejected.
-        import sqlite3
-
-        self.db.upsert_work_item(
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="pr",
-            number=89,
-            current_head_sha=None,
-        )
-        conn = sqlite3.connect(self.db_path)
-        try:
-            wid = conn.execute(
-                "SELECT work_item_id FROM work_items WHERE kind='pr' AND number=89"
-            ).fetchone()[0]
-            conn.execute(
-                """
-                INSERT INTO sessions(session_id, role, started_at, last_heartbeat_at, status)
-                VALUES ('legacy', 'author', '2020-01-01T00:00:00Z', '2020-01-01T00:00:00Z', 'active')
-                """
-            )
-            conn.execute(
-                """
-                INSERT INTO leases(
-                    lease_id, work_item_id, session_id, role, phase,
-                    expires_at, heartbeat_at, status
-                ) VALUES (
-                    'lease-legacy', ?, 'legacy', 'author', 'claimed',
-                    '2099-01-01T00:00:00Z', '2020-01-01T00:00:00Z', 'active'
-                )
-                """,
-                (wid,),
-            )
-            conn.execute(
-                """
-                INSERT INTO assignments(
-                    assignment_id, work_item_id, session_id, lease_id,
-                    allowed_actions, forbidden_actions, expected_head_sha,
-                    role, status, created_at
-                ) VALUES (
-                    'asn-legacy', ?, 'legacy', 'lease-legacy',
-                    '["implement"]', '["merge"]', NULL,
-                    'author', 'active', '2020-01-01T00:00:00Z'
-                )
-                """,
-                (wid,),
-            )
-            conn.commit()
-        finally:
-            conn.close()
-        self.db.upsert_work_item(
-            remote="prgs",
-            org="o",
-            repo="r",
-            kind="pr",
-            number=89,
-            current_head_sha="populated-head",
-        )
-        with self.assertRaises(LeaseRequiredError) as ctx2:
-            self.db.require_valid_assignment(
-                session_id="legacy",
-                remote="prgs",
-                org="o",
-                repo="r",
-                kind="pr",
-                number=89,
-                action="implement",
-            )
-        self.assertIn("expected_head_sha pin", str(ctx2.exception))
-
-    def test_migrate_duplicate_null_scope_incident_links(self) -> None:
-        """Legacy NULL-scope duplicates must migrate without UNIQUE crash."""
-        import sqlite3
-
-        from control_plane_db import ControlPlaneDB, ControlPlaneError
-
-        # Build a v1-like table with nullable scope columns and insert dups
-        # that collapse under normalization, then open ControlPlaneDB on it.
-        path = os.path.join(self._tmp.name, "legacy_dups.sqlite3")
-        conn = sqlite3.connect(path)
-        try:
-            conn.executescript(
-                """
-                CREATE TABLE schema_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
-                CREATE TABLE incident_links (
-                    link_id INTEGER PRIMARY KEY AUTOINCREMENT,
-                    provider TEXT NOT NULL,
-                    provider_base_url TEXT,
-                    provider_org TEXT,
-                    provider_project TEXT,
-                    provider_issue_id TEXT NOT NULL,
-                    provider_short_id TEXT,
-                    provider_permalink TEXT,
-                    fingerprint TEXT,
-                    gitea_org TEXT NOT NULL,
-                    gitea_repo TEXT NOT NULL,
-                    gitea_issue_number INTEGER NOT NULL,
-                    linked_pr_numbers TEXT,
-                    first_seen TEXT,
-                    last_seen TEXT,
-                    event_count INTEGER,
-                    status TEXT NOT NULL DEFAULT 'open',
-                    release_resolved_at TEXT,
-                    last_sync_at TEXT,
-                    UNIQUE (
-                        provider, provider_base_url, provider_org,
-                        provider_project, provider_issue_id
-                    )
-                );
-                INSERT INTO incident_links(
-                    provider, provider_base_url, provider_org, provider_project,
-                    provider_issue_id, gitea_org, gitea_repo, gitea_issue_number, status
-                ) VALUES
-                    ('sentry', NULL, NULL, NULL, 'dup-1', 'org', 'repo', 10, 'open'),
-                    ('sentry', NULL, NULL, NULL, 'dup-1', 'org', 'repo', 10, 'open');
-                """
-            )
-            # SQLite allows two NULL-scope rows with same provider/issue under UNIQUE.
-            n = conn.execute("SELECT COUNT(*) FROM incident_links").fetchone()[0]
-            self.assertEqual(n, 2)
-            conn.commit()
-        finally:
-            conn.close()
-
-        db = ControlPlaneDB(path)
-        conn2 = sqlite3.connect(path)
-        try:
-            n2 = conn2.execute("SELECT COUNT(*) FROM incident_links").fetchone()[0]
-            rows = conn2.execute(
-                "SELECT provider_base_url, provider_org, provider_project, gitea_issue_number "
-                "FROM incident_links"
-            ).fetchall()
-        finally:
-            conn2.close()
-        self.assertEqual(n2, 1)
-        self.assertEqual(rows[0][0], "")
-        self.assertEqual(rows[0][1], "")
-        self.assertEqual(rows[0][2], "")
-        self.assertEqual(rows[0][3], 10)
-        # Touch to silence unused import in type checkers if needed
-        self.assertTrue(issubclass(ControlPlaneError, Exception))
-        del db
-
-    def test_migrate_conflicting_duplicate_incident_links_fails_closed(self) -> None:
-        """Conflicting Gitea targets for the same provider key must fail closed."""
-        import sqlite3
-        from control_plane_db import ControlPlaneDB, ControlPlaneError
-
-        path = os.path.join(self._tmp.name, "legacy_conflict.sqlite3")
-        conn = sqlite3.connect(path)
-        try:
-            conn.executescript(
-                """
-                CREATE TABLE incident_links (
-                    link_id INTEGER PRIMARY KEY AUTOINCREMENT,
-                    provider TEXT NOT NULL,
-                    provider_base_url TEXT,
-                    provider_org TEXT,
-                    provider_project TEXT,
-                    provider_issue_id TEXT NOT NULL,
-                    gitea_org TEXT NOT NULL,
-                    gitea_repo TEXT NOT NULL,
-                    gitea_issue_number INTEGER NOT NULL,
-                    status TEXT NOT NULL DEFAULT 'open',
-                    UNIQUE (
-                        provider, provider_base_url, provider_org,
-                        provider_project, provider_issue_id
-                    )
-                );
-                INSERT INTO incident_links(
-                    provider, provider_base_url, provider_org, provider_project,
-                    provider_issue_id, gitea_org, gitea_repo, gitea_issue_number
-                ) VALUES
-                    ('sentry', NULL, NULL, NULL, 'dup-c', 'org', 'repo', 1),
-                    ('sentry', NULL, NULL, NULL, 'dup-c', 'org', 'repo', 2);
-                """
-            )
-            conn.commit()
-        finally:
-            conn.close()
-
-        with self.assertRaises(ControlPlaneError) as ctx:
-            ControlPlaneDB(path)
-        self.assertIn("conflicting", str(ctx.exception).lower())
-
-    def test_migrate_conflicting_observation_metadata_fails_closed(self) -> None:
-        """Same provider key + same Gitea target but differing obs metadata must fail closed.
-
-        Regression for silent data loss: migration used to keep lowest link_id and
-        delete peers after comparing only Gitea targets (#619 RC3).
-        """
-        import sqlite3
-        from control_plane_db import ControlPlaneDB, ControlPlaneError
-
-        path = os.path.join(self._tmp.name, "legacy_meta_conflict.sqlite3")
-        conn = sqlite3.connect(path)
-        try:
-            conn.executescript(
-                """
-                CREATE TABLE schema_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
-                CREATE TABLE incident_links (
-                    link_id INTEGER PRIMARY KEY AUTOINCREMENT,
-                    provider TEXT NOT NULL,
-                    provider_base_url TEXT,
-                    provider_org TEXT,
-                    provider_project TEXT,
-                    provider_issue_id TEXT NOT NULL,
-                    provider_short_id TEXT,
-                    provider_permalink TEXT,
-                    fingerprint TEXT,
-                    gitea_org TEXT NOT NULL,
-                    gitea_repo TEXT NOT NULL,
-                    gitea_issue_number INTEGER NOT NULL,
-                    linked_pr_numbers TEXT,
-                    first_seen TEXT,
-                    last_seen TEXT,
-                    event_count INTEGER,
-                    status TEXT NOT NULL DEFAULT 'open',
-                    release_resolved_at TEXT,
-                    last_sync_at TEXT,
-                    UNIQUE (
-                        provider, provider_base_url, provider_org,
-                        provider_project, provider_issue_id
-                    )
-                );
-                INSERT INTO incident_links(
-                    provider, provider_base_url, provider_org, provider_project,
-                    provider_issue_id, provider_permalink, fingerprint,
-                    gitea_org, gitea_repo, gitea_issue_number,
-                    event_count, status, first_seen, last_seen
-                ) VALUES
-                    (
-                        'sentry', NULL, NULL, NULL, 'dup-meta',
-                        'https://sentry.example/issues/1', 'fingerprint-A',
-                        'org', 'repo', 42,
-                        1, 'open', '2026-01-01T00:00:00Z', '2026-01-01T01:00:00Z'
-                    ),
-                    (
-                        'sentry', NULL, NULL, NULL, 'dup-meta',
-                        'https://sentry.example/issues/1', 'fingerprint-B',
-                        'org', 'repo', 42,
-                        99, 'resolved', '2026-01-01T00:00:00Z', '2026-01-02T00:00:00Z'
-                    );
-                """
-            )
-            n = conn.execute("SELECT COUNT(*) FROM incident_links").fetchone()[0]
-            self.assertEqual(n, 2)
-            conn.commit()
-        finally:
-            conn.close()
-
-        with self.assertRaises(ControlPlaneError) as ctx:
-            ControlPlaneDB(path)
-        msg = str(ctx.exception).lower()
-        self.assertIn("conflicting", msg)
-        self.assertIn("observation metadata", msg)
-
-        # Rows must still be present — migration must not delete before failing.
-        conn2 = sqlite3.connect(path)
-        try:
-            remaining = conn2.execute("SELECT COUNT(*) FROM incident_links").fetchone()[0]
-            fps = {
-                r[0]
-                for r in conn2.execute(
-                    "SELECT fingerprint FROM incident_links ORDER BY link_id"
-                ).fetchall()
-            }
-        finally:
-            conn2.close()
-        self.assertEqual(remaining, 2)
-        self.assertEqual(fps, {"fingerprint-A", "fingerprint-B"})
-
-    def test_incident_links_minimal_upsert_is_canonical(self) -> None:
-        """Repeated minimal upserts must update one row (NULL-safe uniqueness)."""
-        a = self.db.upsert_incident_link(
-            provider="sentry",
-            provider_issue_id="inc-1",
-            gitea_org="org",
-            gitea_repo="repo",
-            gitea_issue_number=1,
-        )
-        b = self.db.upsert_incident_link(
-            provider="sentry",
-            provider_issue_id="inc-1",
-            gitea_org="org",
-            gitea_repo="repo",
-            gitea_issue_number=2,
-            # omit optional scope fields again
-        )
-        c = self.db.upsert_incident_link(
-            provider="sentry",
-            provider_issue_id="inc-1",
-            gitea_org="org",
-            gitea_repo="repo",
-            gitea_issue_number=3,
-            provider_base_url=None,
-            provider_org="",
-            provider_project="  ",
-        )
-        self.assertEqual(a["link_id"], b["link_id"])
-        self.assertEqual(b["link_id"], c["link_id"])
-        self.assertEqual(c["gitea_issue_number"], 3)
-        self.assertEqual(c["provider_base_url"], "")
-        self.assertEqual(c["provider_org"], "")
-        self.assertEqual(c["provider_project"], "")
-
-        import sqlite3
-
-        conn = sqlite3.connect(self.db_path)
-        try:
-            n = conn.execute(
-                "SELECT COUNT(*) FROM incident_links WHERE provider_issue_id = ?",
-                ("inc-1",),
-            ).fetchone()[0]
-        finally:
-            conn.close()
-        self.assertEqual(n, 1)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/test_head_scoped_review_decision_lock.py

@@ -1,397 +0,0 @@
-"""Head-scoped #332 review-decision locks (#620).
-
-Proves:
-  * REQUEST_CHANGES on head A does not block mark_ready/submit on head B
-  * APPROVE on head B is allowed after RC on head A (same open PR)
-  * same-head duplicate terminal remains blocked
-  * open-PR cleanup remains forbidden; assessment reports stale_by_head
-  * historical mutations keep their head_sha (preserved ledger)
-  * PR #619-style: old RC at 036b78e…, current head 2429d9d…, approve allowed
-"""
-
-from __future__ import annotations
-
-import os
-import unittest
-from unittest.mock import patch
-
-import mcp_server
-import stale_review_decision_lock as srdl
-
-HEAD_A = "036b78e31ea5d036452b3a52e0e086b01e0c763f"
-HEAD_B = "2429d9d2e826e519eb8eb4ade45987c00838aefb"
-HEAD_C = "c" * 40
-
-
-def _lock(mutations=None, correction=False, ready_pr=None, ready_head=None, ready_action=None):
-    return {
-        "task": "review_pr",
-        "remote": "prgs",
-        "org": "Scaled-Tech-Consulting",
-        "repo": "Gitea-Tools",
-        "session_pid": os.getpid(),
-        "session_profile": "prgs-reviewer",
-        "session_profile_lock": "prgs-reviewer",
-        "profile_identity": "prgs-reviewer",
-        "final_review_decision_ready": False,
-        "ready_pr_number": ready_pr,
-        "ready_action": ready_action,
-        "ready_expected_head_sha": ready_head,
-        "ready_remote": "prgs" if ready_pr else None,
-        "ready_org": "Scaled-Tech-Consulting" if ready_pr else None,
-        "ready_repo": "Gitea-Tools" if ready_pr else None,
-        "live_mutations": list(mutations or []),
-        "correction_authorized": correction,
-        "correction_reason": None,
-    }
-
-
-RC_619_LEGACY = {
-    "pr_number": 619,
-    "action": "request_changes",
-    "review_id": 410,
-    "review_state": "request_changes",
-    # no head_sha — pre-#620 durable ledger shape
-}
-RC_619_HEAD_A = {
-    "pr_number": 619,
-    "action": "request_changes",
-    "review_id": 410,
-    "review_state": "request_changes",
-    "head_sha": HEAD_A,
-}
-APPROVE_619_HEAD_B = {
-    "pr_number": 619,
-    "action": "approve",
-    "review_id": 411,
-    "review_state": "approve",
-    "head_sha": HEAD_B,
-}
-
-
-def _seed(mutations=None, **kwargs):
-    import review_workflow_load
-
-    review_workflow_load.record_review_workflow_load(mcp_server.PROJECT_ROOT)
-    mcp_server._save_review_decision_lock(_lock(mutations, **kwargs))
-    mcp_server.gitea_load_review_workflow()
-
-
-def _open_pr(pr_number=619, head=HEAD_B):
-    return {
-        "number": pr_number,
-        "state": "open",
-        "merged": False,
-        "merged_at": None,
-        "head": {"sha": head},
-    }
-
-
-def _no_lease():
-    return {"block": False, "reasons": [], "mutation_allowed": True}
-
-
-def _feedback(blocking=False, stale=False, success=True):
-    return {
-        "success": success,
-        "has_blocking_change_requests": blocking,
-        "review_feedback_stale": stale,
-        "current_head_sha": HEAD_B,
-    }
-
-
-class TestPureHeadScopeHelpers(unittest.TestCase):
-    def test_mutation_head_prefers_recorded_sha(self):
-        m = {"pr_number": 1, "head_sha": HEAD_A}
-        self.assertEqual(srdl.mutation_head_sha(m), HEAD_A)
-
-    def test_legacy_mutation_uses_ready_expected_for_same_pr(self):
-        lock = _lock(
-            [RC_619_LEGACY],
-            ready_pr=619,
-            ready_head=HEAD_A,
-            ready_action="request_changes",
-        )
-        self.assertEqual(srdl.mutation_head_sha(RC_619_LEGACY, lock), HEAD_A)
-
-    def test_legacy_mutation_ignores_ready_for_other_pr(self):
-        lock = _lock([RC_619_LEGACY], ready_pr=1, ready_head=HEAD_A)
-        self.assertIsNone(srdl.mutation_head_sha(RC_619_LEGACY, lock))
-
-    def test_prior_blocks_same_head_not_other_head(self):
-        lock = _lock([RC_619_HEAD_A])
-        self.assertTrue(
-            srdl.prior_live_mutations_block_boundary(
-                lock, pr_number=619, expected_head_sha=HEAD_A
-            )
-        )
-        self.assertFalse(
-            srdl.prior_live_mutations_block_boundary(
-                lock, pr_number=619, expected_head_sha=HEAD_B
-            )
-        )
-
-    def test_backfill_stamps_legacy_terminals(self):
-        lock = _lock(
-            [dict(RC_619_LEGACY)],
-            ready_pr=619,
-            ready_head=HEAD_A,
-            ready_action="request_changes",
-        )
-        srdl.backfill_terminal_heads_from_ready(lock)
-        self.assertEqual(lock["live_mutations"][0]["head_sha"], HEAD_A)
-
-
-class TestHardStopHeadScope(unittest.TestCase):
-    def tearDown(self):
-        mcp_server._save_review_decision_lock(None)
-        mcp_server.review_workflow_load.clear_review_workflow_load()
-
-    def test_rc_head_a_allows_mark_ready_head_b(self):
-        _seed(
-            [RC_619_HEAD_A],
-            ready_pr=619,
-            ready_head=HEAD_A,
-            ready_action="request_changes",
-        )
-        self.assertEqual(
-            mcp_server.terminal_review_hard_stop_reasons(
-                619, "mark_ready", expected_head_sha=HEAD_B
-            ),
-            [],
-        )
-
-    def test_rc_head_a_blocks_mark_ready_same_head(self):
-        _seed(
-            [RC_619_HEAD_A],
-            ready_pr=619,
-            ready_head=HEAD_A,
-            ready_action="request_changes",
-        )
-        reasons = mcp_server.terminal_review_hard_stop_reasons(
-            619, "mark_ready", expected_head_sha=HEAD_A
-        )
-        self.assertTrue(reasons)
-        self.assertIn("#332", reasons[0])
-
-    def test_rc_head_a_blocks_other_pr(self):
-        _seed([RC_619_HEAD_A], ready_pr=619, ready_head=HEAD_A)
-        reasons = mcp_server.terminal_review_hard_stop_reasons(
-            700, "mark_ready", expected_head_sha=HEAD_B
-        )
-        self.assertTrue(reasons)
-
-    def test_legacy_619_ledger_allows_new_head(self):
-        """PR #619-style durable lock without mutation head_sha."""
-        _seed(
-            [RC_619_LEGACY],
-            ready_pr=619,
-            ready_head=HEAD_A,
-            ready_action="request_changes",
-        )
-        self.assertEqual(
-            mcp_server.terminal_review_hard_stop_reasons(
-                619, "mark_ready", expected_head_sha=HEAD_B
-            ),
-            [],
-        )
-
-
-class TestMarkFinalAndRecord(unittest.TestCase):
-    def tearDown(self):
-        mcp_server._save_review_decision_lock(None)
-        mcp_server.review_workflow_load.clear_review_workflow_load()
-
-    def _mark(self, pr, action, head, feedback=None):
-        with patch("mcp_server._list_pr_lease_comments", return_value=[]), patch(
-            "mcp_server._pr_work_lease_reviewer_block", return_value=_no_lease()
-        ), patch.object(
-            mcp_server,
-            "gitea_get_pr_review_feedback",
-            return_value=feedback or _feedback(blocking=False, stale=True),
-        ), patch.object(
-            mcp_server,
-            "gitea_check_pr_eligibility",
-            return_value={"eligible": True, "head_sha": head},
-        ):
-            return mcp_server.gitea_mark_final_review_decision(
-                pr_number=pr,
-                action=action,
-                expected_head_sha=head,
-                remote="prgs",
-                org="Scaled-Tech-Consulting",
-                repo="Gitea-Tools",
-            )
-
-    def test_rc_then_rc_on_new_head(self):
-        _seed(
-            [RC_619_HEAD_A],
-            ready_pr=619,
-            ready_head=HEAD_A,
-            ready_action="request_changes",
-        )
-        # Prior RC at head A is unresolved but head moved → feedback stale.
-        res = self._mark(
-            619,
-            "request_changes",
-            HEAD_B,
-            feedback=_feedback(blocking=True, stale=True),
-        )
-        self.assertTrue(res.get("marked_ready"), res)
-        lock = mcp_server._load_review_decision_lock()
-        # Historical head A preserved on mutation after backfill.
-        heads = {
-            m.get("head_sha")
-            for m in lock["live_mutations"]
-            if m.get("action") == "request_changes"
-        }
-        self.assertIn(HEAD_A, heads)
-        self.assertEqual(lock["ready_expected_head_sha"], HEAD_B)
-
-    def test_rc_then_approve_on_new_head(self):
-        _seed(
-            [RC_619_HEAD_A],
-            ready_pr=619,
-            ready_head=HEAD_A,
-            ready_action="request_changes",
-        )
-        res = self._mark(619, "approve", HEAD_B)
-        self.assertTrue(res.get("marked_ready"), res)
-        self.assertTrue(res.get("head_scoped"))
-
-    def test_same_head_rc_still_blocked_by_hard_stop(self):
-        _seed(
-            [RC_619_HEAD_A],
-            ready_pr=619,
-            ready_head=HEAD_A,
-            ready_action="request_changes",
-        )
-        res = self._mark(619, "approve", HEAD_A)
-        self.assertFalse(res.get("marked_ready"))
-        self.assertTrue(any("#332" in r for r in res.get("reasons") or []))
-
-    def test_pr619_style_legacy_lock_approve_on_current_head(self):
-        _seed(
-            [RC_619_LEGACY],
-            ready_pr=619,
-            ready_head=HEAD_A,
-            ready_action="request_changes",
-        )
-        res = self._mark(619, "approve", HEAD_B)
-        self.assertTrue(res.get("marked_ready"), res)
-        lock = mcp_server._load_review_decision_lock()
-        # Backfill should have stamped HEAD_A onto the legacy mutation.
-        self.assertEqual(lock["live_mutations"][0].get("head_sha"), HEAD_A)
-        self.assertEqual(lock["ready_expected_head_sha"], HEAD_B)
-
-    def test_record_live_mutation_stores_head(self):
-        _seed(ready_pr=619, ready_head=HEAD_B, ready_action="approve")
-        lock = mcp_server._load_review_decision_lock()
-        lock["final_review_decision_ready"] = True
-        lock["ready_pr_number"] = 619
-        lock["ready_expected_head_sha"] = HEAD_B
-        mcp_server._save_review_decision_lock(lock)
-        mcp_server.record_live_review_mutation(619, "approve", review_id=99)
-        stored = mcp_server._load_review_decision_lock()["live_mutations"][-1]
-        self.assertEqual(stored["head_sha"], HEAD_B)
-        self.assertEqual(stored["pr_number"], 619)
-
-    def test_submit_gate_allows_new_head_after_prior_terminal(self):
-        """check_review_decision_gate must not block different-head submit."""
-        mutations = [RC_619_HEAD_A]
-        _seed(
-            mutations,
-            ready_pr=619,
-            ready_head=HEAD_B,
-            ready_action="approve",
-        )
-        lock = mcp_server._load_review_decision_lock()
-        lock["final_review_decision_ready"] = True
-        lock["ready_pr_number"] = 619
-        lock["ready_action"] = "approve"
-        lock["ready_expected_head_sha"] = HEAD_B
-        lock["ready_remote"] = "prgs"
-        lock["ready_org"] = "Scaled-Tech-Consulting"
-        lock["ready_repo"] = "Gitea-Tools"
-        mcp_server._save_review_decision_lock(lock)
-        reasons = mcp_server.check_review_decision_gate(
-            619,
-            "approve",
-            final_review_decision_ready=True,
-            remote="prgs",
-            org="Scaled-Tech-Consulting",
-            repo="Gitea-Tools",
-        )
-        self.assertEqual(reasons, [], reasons)
-
-    def test_submit_gate_blocks_same_head_duplicate(self):
-        mutations = [RC_619_HEAD_A]
-        _seed(
-            mutations,
-            ready_pr=619,
-            ready_head=HEAD_A,
-            ready_action="request_changes",
-        )
-        lock = mcp_server._load_review_decision_lock()
-        lock["final_review_decision_ready"] = True
-        lock["ready_pr_number"] = 619
-        lock["ready_action"] = "request_changes"
-        lock["ready_expected_head_sha"] = HEAD_A
-        lock["ready_remote"] = "prgs"
-        lock["ready_org"] = "Scaled-Tech-Consulting"
-        lock["ready_repo"] = "Gitea-Tools"
-        mcp_server._save_review_decision_lock(lock)
-        reasons = mcp_server.check_review_decision_gate(
-            619,
-            "request_changes",
-            final_review_decision_ready=True,
-            remote="prgs",
-            org="Scaled-Tech-Consulting",
-            repo="Gitea-Tools",
-        )
-        self.assertTrue(reasons)
-
-
-class TestAssessmentOpenPrHead(unittest.TestCase):
-    def test_open_pr_stale_by_head_no_cleanup(self):
-        lock = _lock(
-            [RC_619_HEAD_A],
-            ready_pr=619,
-            ready_head=HEAD_A,
-            ready_action="request_changes",
-        )
-        a = srdl.assess_stale_review_decision_lock(
-            lock, pr_live=_open_pr(619, HEAD_B)
-        )
-        self.assertTrue(a["has_lock"])
-        self.assertFalse(a["is_moot"])
-        self.assertFalse(a["cleanup_allowed"])
-        self.assertTrue(a["stale_by_head"])
-        self.assertTrue(a["fresh_review_on_current_head_allowed"])
-        self.assertEqual(a["locked_head_sha"], HEAD_A)
-        self.assertEqual(a["current_pr_head_sha"], HEAD_B)
-
-    def test_open_pr_same_head_no_fresh(self):
-        lock = _lock([RC_619_HEAD_A], ready_pr=619, ready_head=HEAD_A)
-        a = srdl.assess_stale_review_decision_lock(
-            lock, pr_live=_open_pr(619, HEAD_A)
-        )
-        self.assertFalse(a["stale_by_head"])
-        self.assertFalse(a["fresh_review_on_current_head_allowed"])
-        self.assertFalse(a["cleanup_allowed"])
-
-    def test_historical_mutation_preserved_in_summary(self):
-        lock = _lock(
-            [RC_619_HEAD_A, APPROVE_619_HEAD_B],
-            ready_pr=619,
-            ready_head=HEAD_B,
-            ready_action="approve",
-        )
-        summary = srdl.lock_summary(lock)
-        self.assertEqual(summary["live_mutations_count"], 2)
-        self.assertEqual(summary["last_terminal"]["head_sha"], HEAD_B)
-        self.assertEqual(summary["locked_head_sha"], HEAD_B)
-
-
-if __name__ == "__main__":
-    unittest.main()