feat: controller-owned allocator API on control-plane DB (Closes #600)

Add gitea_allocate_next_work and allocator_service routing policy on top of
the #613 ControlPlaneDB substrate. Workers get atomic assign+lease results
(or wait/no_safe_work/terminal-path outcomes) without self-selecting work
via file locks or comment-only leases. #612 remains downstream.

Closes #600

allocator_service.py

@@ -0,0 +1,610 @@
+"""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

@@ -40,9 +40,19 @@
 - **#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)
 
-- Full `gitea_allocate_next_work` routing policy (REQUEST_CHANGES → author, etc.) — **#600**
 - Sentry/GlitchTip provider adapters and auto-watchdog — **#612**
 - Gitea comment/label mirror writers (may be added by allocator tooling later)
 

gitea_mcp_server.py

@@ -21,6 +21,7 @@ import json
 import functools
 import contextlib
 import subprocess
+import uuid
 from datetime import datetime, timedelta, timezone
 
 
@@ -832,6 +833,8 @@ 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
@@ -3095,22 +3098,26 @@ def check_review_decision_gate(
         )
 
     prior = list(lock.get("live_mutations") or [])
-    if prior and not lock.get("correction_authorized"):
+    ready_head = lock.get("ready_expected_head_sha")
-        reasons.append(
+    if stale_review_decision_lock.prior_live_mutations_block_boundary(
-            "live review mutation already recorded in this run; only one live "
+        lock, pr_number=pr_number, expected_head_sha=ready_head
-            "review mutation is allowed unless "
-            "gitea_authorize_review_correction was invoked (fail closed)"
-        )
-    elif (
-        action in _TERMINAL_REVIEW_ACTIONS
-        and any(m.get("action") in _TERMINAL_REVIEW_ACTIONS for m in prior)
-        and not lock.get("correction_authorized")
     ):
-        reasons.append(
+        if prior and not lock.get("correction_authorized"):
-            "terminal review decision already submitted on this PR in this "
+            reasons.append(
-            "run; blocked unless an operator-approved correction was "
+                "live review mutation already recorded for this PR head in this "
-            "authorized (fail closed)"
+                "run; only one live review mutation is allowed per head unless "
-        )
+                "gitea_authorize_review_correction was invoked (fail closed, #620)"
+            )
+        elif (
+            action in _TERMINAL_REVIEW_ACTIONS
+            and any(m.get("action") in _TERMINAL_REVIEW_ACTIONS for m in prior)
+            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)"
+            )
 
     return reasons
 
@@ -3118,12 +3125,18 @@ 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 [])
-    mutations.append({
+    head_sha = stale_review_decision_lock.normalize_head_sha(
+        lock.get("ready_expected_head_sha")
+    )
+    entry = {
         "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
@@ -3131,17 +3144,28 @@ 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) -> list[str]:
+def terminal_review_hard_stop_reasons(
-    """Session hard-stop after a terminal live review mutation (#332).
+    pr_number: int,
+    operation: str,
+    expected_head_sha: str | None = None,
+) -> list[str]:
+    """Session hard-stop after a terminal live review mutation (#332 / #620).
 
-    After a terminal verdict is consumed in this run, the only permitted
+    After a terminal verdict is consumed for a given PR **head**, the only
-    continuation is the merge sequence for the same PR that was approved.
+    permitted continuation is the merge sequence for that same approved PR
-    A REQUEST_CHANGES (or an approval of a different PR) blocks every
+    (merge does not require a new head). A REQUEST_CHANGES (or an approval of
-    further review/mark-ready/merge mutation. An operator-approved
+    a different PR, or the same head) blocks further review/mark-ready/merge
-    correction (#211) re-opens the review path only — never a cross-PR
+    mutations for that boundary.
-    merge.
 
-    *operation* is one of 'merge', 'mark_ready', or 'review'.
+    #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'.
     Returns [] when the operation may proceed.
     """
     lock = _load_review_decision_lock()
@@ -3160,8 +3184,19 @@ def terminal_review_hard_stop_reasons(pr_number: int, operation: str) -> list[st
         and last.get("pr_number") == pr_number
     ):
         return []
-    if operation in ("mark_ready", "review") and lock.get("correction_authorized"):
+    if operation in ("mark_ready", "review", "resume") 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 "
@@ -3169,15 +3204,22 @@ def terminal_review_hard_stop_reasons(pr_number: int, operation: str) -> list[st
         )
     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); never delete session-state files by hand"
+        "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"
     )
     return [
         "terminal review mutation already consumed in this run "
-        f"({last.get('action')} on PR #{last.get('pr_number')}); {guidance} "
+        f"({last.get('action')} on PR #{last.get('pr_number')}{head_note}); "
-        f"(fail closed, #332); {recovery}"
+        f"{guidance} (fail closed, #332); {recovery}"
     ]
 
 
@@ -3800,18 +3842,11 @@ 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")
+    hard_stop = terminal_review_hard_stop_reasons(
+        pr_number, "mark_ready", expected_head_sha=expected_head_sha
+    )
     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,
@@ -3828,6 +3863,17 @@ 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",
@@ -3880,6 +3926,8 @@ 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
@@ -3897,6 +3945,7 @@ def gitea_mark_final_review_decision(
         "org": org,
         "repo": repo,
         "final_review_decision_ready": True,
+        "head_scoped": True,
         "reasons": [],
     }
 
@@ -4063,6 +4112,12 @@ 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"),
@@ -11057,6 +11112,310 @@ 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__":

stale_review_decision_lock.py

@@ -1,4 +1,4 @@
-"""Stale / moot #332 review-decision lock detection and cleanup policy (#594).
+"""Stale / moot #332 review-decision lock detection and cleanup policy (#594/#620).
 
 #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,6 +6,12 @@ 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.
@@ -23,6 +29,45 @@ 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:
@@ -35,18 +80,125 @@ 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,
     }
 
 
@@ -56,6 +208,7 @@ 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"),
@@ -67,16 +220,21 @@ 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"),
     }
@@ -88,13 +246,16 @@ 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).
+    """Assess whether a durable review-decision lock is stale/moot (#594/#620).
 
     *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 and #332 hard-stop remains in force.
+    forbidden (#594). Open PR + different live head reports
+    ``stale_by_head`` / ``fresh_review_on_current_head_allowed`` (#620)
+    without enabling cleanup.
     """
     summary = lock_summary(lock)
     result: dict[str, Any] = {
@@ -102,6 +263,10 @@ 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,
@@ -141,8 +306,10 @@ 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(
@@ -165,25 +332,46 @@ 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"]:
-        result["reasons"].append(
+        stale_by_head = bool(
-            f"terminal review mutation on open PR #{pr_number} is still active "
+            locked_head and current_head and not heads_equal(locked_head, current_head)
-            f"({action}); #332 hard-stop remains — cleanup forbidden (#594)"
         )
+        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)"
+            )
         return result
 
     # 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,6 +139,17 @@ 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",

tests/test_allocator_service.py

@@ -0,0 +1,366 @@
+"""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_head_scoped_review_decision_lock.py

@@ -0,0 +1,397 @@
+"""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()