feat: replace global issue lock with keyed persistent store (Closes #443)

Store per remote/org/repo/issue locks under GITEA_ISSUE_LOCK_DIR with
atomic writes and per-session binding. Integrate own-branch adoption for
lock recovery, update worktree-start and cleanup reconcile, and add tests
documenting the ban on manual global lock seeding.

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

docs/llm-workflow-runbooks.md

@@ -291,9 +291,7 @@ recovery path.** That global slot is deprecated and can clobber unrelated live
 leases (#438). After an MCP restart, call `gitea_lock_issue` again — own-branch
 adoption rebinds the session when the issue's exact branch already exists (#442).
 `gitea_create_pr` resolves the durable keyed lock by session pointer or by
-matching `head` branch without unsafe manual seeding (#440). Branch ownership
+matching `head` branch without unsafe manual seeding.
-uses structured ``(fix|feat|docs|chore)/issue-<n>-`` parsing — not broad
-substring matches like ``issue-420`` inside ``issue-4200``.
 
 Remote branches matching the issue number are also treated as active work unless
 the recovery review proves the branch is abandoned or superseded. Never delete

gitea_mcp_server.py

@@ -537,13 +537,13 @@ import role_namespace_gate  # noqa: E402
 import task_capability_map  # noqa: E402
 import review_proofs  # noqa: E402
 import agent_temp_artifacts
-import issue_branch_ownership  # noqa: E402
 import issue_lock_worktree  # noqa: E402
 import issue_lock_store  # noqa: E402
 import issue_lock_adoption  # noqa: E402
 import already_landed_reconcile  # noqa: E402
 import author_mutation_worktree  # noqa: E402
 import issue_claim_heartbeat  # noqa: E402
+import issue_work_duplicate_gate  # noqa: E402
 import merged_cleanup_reconcile  # noqa: E402
 import reconciler_profile  # noqa: E402
 import reconciliation_workflow  # noqa: E402
@@ -727,6 +727,119 @@ def _branch_entry_name(branch: dict | str) -> str:
     return str(branch.get("name") or branch.get("ref") or "")
 
 
+def _live_fetch_issue_duplicate_context(
+    h: str,
+    o: str,
+    r: str,
+    auth: str,
+    issue_number: int,
+) -> tuple[list[dict], list[str], dict]:
+    """Live open PRs, remote branch names, and claim state for one issue."""
+    base = repo_api_url(h, o, r)
+    open_prs = api_get_all(f"{base}/pulls?state=open", auth)
+    branches = api_get_all(f"{base}/branches", auth)
+    branch_names = [_branch_entry_name(b) for b in branches]
+    issue = api_request("GET", f"{base}/issues/{issue_number}", auth) or {}
+    comments = api_request(
+        "GET", f"{base}/issues/{issue_number}/comments", auth
+    ) or []
+    claim_entry = issue_claim_heartbeat.classify_issue_claim(
+        issue=issue,
+        comments=comments,
+        open_prs=open_prs,
+        branch_names=branch_names,
+    )
+    return open_prs, branch_names, claim_entry
+
+
+# Injectable duplicate-work context fetcher (#400). Production uses the live
+# Gitea API path above; unit tests patch this symbol instead of hitting the
+# network.
+issue_duplicate_context_fetcher = _live_fetch_issue_duplicate_context
+
+
+def _collect_issue_duplicate_context(
+    h: str,
+    o: str,
+    r: str,
+    auth: str,
+    issue_number: int,
+) -> tuple[list[dict], list[str], dict]:
+    return issue_duplicate_context_fetcher(h, o, r, auth, issue_number)
+
+
+def _assess_issue_duplicate_gate(
+    issue_number: int,
+    *,
+    h: str,
+    o: str,
+    r: str,
+    auth: str,
+    locked_branch: str | None = None,
+    phase: str,
+) -> dict:
+    open_prs, branch_names, claim_entry = _collect_issue_duplicate_context(
+        h, o, r, auth, issue_number
+    )
+    return issue_work_duplicate_gate.assess_work_issue_duplicate_gate(
+        issue_number,
+        open_prs=open_prs,
+        branch_names=branch_names,
+        claim_entry=claim_entry,
+        locked_branch=locked_branch,
+        phase=phase,
+    )
+
+
+def _duplicate_gate_block_response(gate: dict, **extra) -> dict:
+    out = {
+        "success": False,
+        "performed": False,
+        "reasons": list(gate.get("reasons") or []),
+        "duplicate_gate": gate,
+        "safe_next_action": gate.get("safe_next_action"),
+    }
+    out.update(extra)
+    return out
+
+
+def _enforce_locked_issue_duplicate_recheck(
+    remote: str,
+    phase: str,
+    *,
+    host: str | None = None,
+    org: str | None = None,
+    repo: str | None = None,
+) -> dict | None:
+    """Re-check duplicate-work gates for the locked issue (#400)."""
+    lock_data = _load_existing_issue_lock()
+    if not lock_data:
+        return None
+    issue_number = int(lock_data.get("issue_number") or 0)
+    locked_branch = lock_data.get("branch_name")
+    if not issue_number:
+        return None
+    h, o, r = _resolve(
+        remote or lock_data.get("remote") or "dadeschools",
+        host or lock_data.get("host"),
+        org or lock_data.get("org"),
+        repo or lock_data.get("repo"),
+    )
+    auth = _auth(h)
+    gate = _assess_issue_duplicate_gate(
+        issue_number,
+        h=h,
+        o=o,
+        r=r,
+        auth=auth,
+        locked_branch=locked_branch,
+        phase=phase,
+    )
+    if gate.get("block"):
+        return gate
+    return None
+
+
 def _branch_entry_commit_sha(branch: dict | str) -> str | None:
     """Best-effort head SHA for a Gitea branch entry (None when absent)."""
     if not isinstance(branch, dict):
@@ -1213,34 +1326,20 @@ def gitea_lock_issue(
             issue_lock_worktree.format_issue_lock_worktree_error(lock_assessment)
         )
 
-    # 2. Check if the issue already has an open PR (reuse protection)
     auth = _auth(h)
-    url = f"{repo_api_url(h, o, r)}/pulls?state=open"
+    duplicate_gate = _assess_issue_duplicate_gate(
-
+        issue_number,
-    try:
+        h=h,
-        prs = api_get_all(url, auth)
+        o=o,
-    except Exception as e:
+        r=r,
-        raise RuntimeError(f"Could not list open PRs to verify issue lock: {e}")
+        auth=auth,
-
+        locked_branch=branch_name,
-    for pr in prs:
+        phase=issue_work_duplicate_gate.PHASE_LOCK,
-        pr_head = pr.get("head", {}).get("ref", "")
-        pr_title = pr.get("title", "")
-        pr_body = pr.get("body", "")
-
-        if issue_branch_ownership.branch_tracks_issue(pr_head, issue_number):
-            raise ValueError(
-                f"Issue #{issue_number} is already tied to an open PR (PR #{pr.get('number')}, branch '{pr_head}') (fail closed)"
-            )
-
-        patterns = [
-            f"closes #{issue_number}",
-            f"fixes #{issue_number}",
-        ]
-        text_to_check = f"{pr_title} {pr_body}".lower()
-        if any(p in text_to_check for p in patterns):
-            raise ValueError(
-                f"Issue #{issue_number} is already tied to an open PR (PR #{pr.get('number')}) via Closes/Fixes reference (fail closed)"
     )
+    if duplicate_gate.get("block"):
+        raise ValueError("; ".join(duplicate_gate.get("reasons") or [
+            f"duplicate work gate blocked issue #{issue_number} (fail closed)"
+        ]))
 
     branch_url = f"{repo_api_url(h, o, r)}/branches"
     try:
@@ -1321,6 +1420,39 @@ def gitea_lock_issue(
     return result
 
 
+@mcp.tool()
+def gitea_assess_work_issue_duplicate(
+    issue_number: int,
+    branch_name: str | None = None,
+    phase: str = issue_work_duplicate_gate.PHASE_LOCK,
+    remote: str = "dadeschools",
+    host: str | None = None,
+    org: str | None = None,
+    repo: str | None = None,
+) -> dict:
+    """Read-only duplicate-work gate for author sessions before mutations (#400)."""
+    read_block = _profile_operation_gate("gitea.read")
+    if read_block:
+        return {
+            "success": False,
+            "performed": False,
+            "reasons": read_block,
+            "permission_report": _permission_block_report("gitea.read"),
+        }
+    h, o, r = _resolve(remote, host, org, repo)
+    auth = _auth(h)
+    gate = _assess_issue_duplicate_gate(
+        issue_number,
+        h=h,
+        o=o,
+        r=r,
+        auth=auth,
+        locked_branch=branch_name,
+        phase=phase,
+    )
+    return {"success": not gate.get("block"), **gate}
+
+
 @mcp.tool()
 def gitea_create_pr(
     title: str,
@@ -1405,6 +1537,21 @@ def gitea_create_pr(
             f"PR title or body must contain 'Closes #{locked_issue}' or 'Fixes #{locked_issue}' exactly to ensure durable tracking (fail closed)"
         )
 
+    duplicate_block = _enforce_locked_issue_duplicate_recheck(
+        remote,
+        issue_work_duplicate_gate.PHASE_CREATE_PR,
+        host=host,
+        org=org,
+        repo=repo,
+    )
+    if duplicate_block:
+        return _duplicate_gate_block_response(
+            duplicate_block,
+            number=None,
+            issue_number=locked_issue,
+            branch_name=locked_branch,
+        )
+
     auth = _auth(h)
     url = f"{repo_api_url(h, o, r)}/pulls"
     payload = {"title": title, "body": body, "head": head, "base": base}
@@ -3003,6 +3150,20 @@ def gitea_commit_files(
     if blocked:
         return blocked
 
+    duplicate_block = _enforce_locked_issue_duplicate_recheck(
+        remote,
+        issue_work_duplicate_gate.PHASE_COMMIT,
+        host=host,
+        org=org,
+        repo=repo,
+    )
+    if duplicate_block:
+        return _duplicate_gate_block_response(
+            duplicate_block,
+            commit="",
+            branch="",
+        )
+
     verify_preflight_purity(remote)
     processed_files, source_proofs = _prepare_commit_payload_files(files)
 

issue_branch_ownership.py

@@ -1,31 +0,0 @@
-"""Structured issue/branch ownership evidence (#440).
-
-Author branches must follow ``(fix|feat|docs|chore)/issue-<n>-<desc>``. Duplicate-work
-and recovery gates use this parser instead of broad substring checks like
-``issue-420`` inside unrelated names (for example ``issue-4200``).
-"""
-
-from __future__ import annotations
-
-import re
-
-IMPLEMENTATION_BRANCH_RE = re.compile(
-    r"^(?:fix|feat|docs|chore)/issue-(\d+)(?:-.+)?$"
-)
-
-
-def parse_tracked_issue_number(branch_name: str) -> int | None:
-    """Return the issue number encoded in a canonical author branch name."""
-    text = (branch_name or "").strip()
-    if not text:
-        return None
-    match = IMPLEMENTATION_BRANCH_RE.match(text)
-    if not match:
-        return None
-    return int(match.group(1))
-
-
-def branch_tracks_issue(branch_name: str, issue_number: int) -> bool:
-    """True when ``branch_name`` structurally belongs to ``issue_number``."""
-    parsed = parse_tracked_issue_number(branch_name)
-    return parsed == issue_number if parsed is not None else False

issue_lock_adoption.py

@@ -14,8 +14,6 @@ this module additionally records whether they passed for proof purposes.
 
 from __future__ import annotations
 
-import issue_branch_ownership
-
 ADOPT = "adopt_existing_branch"
 BLOCK_COMPETING = "block_competing_branch"
 NO_MATCH = "no_matching_branch"
@@ -42,12 +40,13 @@ def assess_own_branch_adoption(
     existing_branches,
 ) -> dict:
     """Decide whether an existing matching branch is adoptable."""
+    marker = f"issue-{issue_number}"
     requested = (requested_branch or "").strip()
 
     matches: list[tuple[str, str | None]] = []
     for entry in existing_branches or []:
         name = _branch_name(entry).strip()
-        if issue_branch_ownership.branch_tracks_issue(name, issue_number):
+        if marker in name:
             matches.append((name, _branch_sha(entry)))
 
     competing = sorted({name for name, _ in matches if name != requested})

issue_work_duplicate_gate.py

@@ -0,0 +1,180 @@
+"""Early duplicate-work detection for author work-issue sessions (#400)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import issue_claim_heartbeat as claim_hb
+
+PHASE_LOCK = "lock_issue"
+PHASE_COMMIT = "commit"
+PHASE_PUSH = "push"
+PHASE_CREATE_PR = "create_pr"
+
+OUTCOME_DUPLICATE_PR_PREVENTED = "duplicate_pr_prevented"
+OUTCOME_DUPLICATE_BRANCH_PREVENTED = "duplicate_branch_prevented"
+OUTCOME_DUPLICATE_COMMIT_PREVENTED = "duplicate_commit_prevented"
+OUTCOME_DUPLICATE_WORK_NOT_PREVENTED = "duplicate_work_not_prevented"
+
+_ACTIVE_CLAIM_STATUSES = frozenset({"active", "awaiting_review"})
+
+
+def _issue_pattern(issue_number: int) -> str:
+    return f"issue-{int(issue_number)}"
+
+
+def _linked_open_pr(issue_number: int, open_prs: list[dict]) -> dict | None:
+    return claim_hb._linked_open_pr(issue_number, open_prs)
+
+
+def _matching_branches(
+    issue_number: int,
+    branch_names: list[str],
+    *,
+    locked_branch: str | None = None,
+) -> list[str]:
+    pattern = _issue_pattern(issue_number)
+    matches = [
+        name for name in (branch_names or [])
+        if pattern in (name or "").lower()
+    ]
+    if locked_branch:
+        locked = locked_branch.strip()
+        matches = [name for name in matches if name != locked]
+    return matches
+
+
+def assess_work_issue_duplicate_gate(
+    issue_number: int,
+    *,
+    open_prs: list[dict] | None = None,
+    branch_names: list[str] | None = None,
+    claim_entry: dict | None = None,
+    locked_branch: str | None = None,
+    phase: str = PHASE_LOCK,
+) -> dict[str, Any]:
+    """Fail closed when duplicate work is already in flight for an issue."""
+    reasons: list[str] = []
+    outcome = OUTCOME_DUPLICATE_WORK_NOT_PREVENTED
+    prs = list(open_prs or [])
+    branches = list(branch_names or [])
+    pattern = _issue_pattern(issue_number)
+
+    linked = _linked_open_pr(issue_number, prs)
+    if linked:
+        reasons.append(
+            f"open PR #{linked.get('number')} already covers issue "
+            f"#{issue_number} (fail closed)"
+        )
+        outcome = OUTCOME_DUPLICATE_PR_PREVENTED
+
+    conflicting_branches = _matching_branches(
+        issue_number, branches, locked_branch=locked_branch
+    )
+    if conflicting_branches:
+        names = ", ".join(conflicting_branches[:5])
+        reasons.append(
+            f"remote branch(es) already match issue pattern '{pattern}': "
+            f"{names} (fail closed)"
+        )
+        if outcome == OUTCOME_DUPLICATE_WORK_NOT_PREVENTED:
+            outcome = OUTCOME_DUPLICATE_BRANCH_PREVENTED
+
+    entry = claim_entry or {}
+    if entry.get("linked_open_pr") and not linked:
+        reasons.append(
+            f"claim inventory reports open PR #{entry['linked_open_pr']} "
+            f"for issue #{issue_number} (fail closed)"
+        )
+        outcome = OUTCOME_DUPLICATE_PR_PREVENTED
+
+    status = (entry.get("status") or "").strip().lower()
+    if status in _ACTIVE_CLAIM_STATUSES and not linked:
+        heartbeat = entry.get("latest_heartbeat") or {}
+        claim_branch = (heartbeat.get("branch") or "").strip()
+        if locked_branch and claim_branch and claim_branch != locked_branch:
+            reasons.append(
+                f"active claim lease on branch '{claim_branch}' blocks "
+                f"work on '{locked_branch}' for issue #{issue_number} "
+                "(fail closed)"
+            )
+            if outcome == OUTCOME_DUPLICATE_WORK_NOT_PREVENTED:
+                outcome = OUTCOME_DUPLICATE_BRANCH_PREVENTED
+        elif not locked_branch and status == "active":
+            reasons.append(
+                f"issue #{issue_number} has an active claim lease "
+                "(fail closed)"
+            )
+            if outcome == OUTCOME_DUPLICATE_WORK_NOT_PREVENTED:
+                outcome = OUTCOME_DUPLICATE_BRANCH_PREVENTED
+
+    if phase in {PHASE_COMMIT, PHASE_PUSH} and reasons:
+        if outcome == OUTCOME_DUPLICATE_PR_PREVENTED:
+            outcome = OUTCOME_DUPLICATE_COMMIT_PREVENTED
+        elif outcome == OUTCOME_DUPLICATE_BRANCH_PREVENTED:
+            outcome = OUTCOME_DUPLICATE_COMMIT_PREVENTED
+
+    block = bool(reasons)
+    return {
+        "block": block,
+        "performed": not block,
+        "issue_number": issue_number,
+        "phase": phase,
+        "outcome": outcome,
+        "linked_open_pr": linked.get("number") if linked else entry.get("linked_open_pr"),
+        "conflicting_branches": conflicting_branches,
+        "claim_status": status or None,
+        "reasons": reasons,
+        "safe_next_action": (
+            "stop before mutating; preserve local work and produce a "
+            "reconciliation handoff if a concurrent PR appeared after push"
+            if block and phase == PHASE_CREATE_PR
+            else "stop before mutating; do not commit or push duplicate work"
+            if block
+            else "proceed"
+        ),
+    }
+
+
+def assess_work_issue_duplicate_report(report_text: str) -> dict[str, Any]:
+    """Require explicit duplicate-work outcome wording in work-issue reports."""
+    text = (report_text or "").lower()
+    markers = {
+        OUTCOME_DUPLICATE_PR_PREVENTED: (
+            "duplicate pr prevented",
+            "duplicate_pr_prevented",
+        ),
+        OUTCOME_DUPLICATE_BRANCH_PREVENTED: (
+            "duplicate branch prevented",
+            "duplicate_branch_prevented",
+        ),
+        OUTCOME_DUPLICATE_COMMIT_PREVENTED: (
+            "duplicate commit prevented",
+            "duplicate_commit_prevented",
+        ),
+        OUTCOME_DUPLICATE_WORK_NOT_PREVENTED: (
+            "duplicate work not prevented",
+            "duplicate_work_not_prevented",
+            "no duplicate work",
+        ),
+    }
+    matched = [
+        key for key, phrases in markers.items()
+        if any(phrase in text for phrase in phrases)
+    ]
+    if len(matched) != 1:
+        return {
+            "complete": False,
+            "downgraded": True,
+            "reasons": [
+                "work-issue report must state exactly one duplicate-work "
+                "outcome (duplicate PR/branch/commit prevented, or "
+                "duplicate work not prevented)"
+            ],
+        }
+    return {
+        "complete": True,
+        "downgraded": False,
+        "outcome": matched[0],
+        "reasons": [],
+    }

review_proofs.py

@@ -3624,9 +3624,12 @@ def assess_work_issue_mode_isolation(report_text: str) -> dict:
 
 def assess_work_issue_final_report(report_text: str) -> dict:
     """#139: composite verifier for work-issue final reports."""
+    from issue_work_duplicate_gate import assess_work_issue_duplicate_report
+
     checks = {
         "workflow_source": assess_work_issue_workflow_source(report_text),
         "mode_isolation": assess_work_issue_mode_isolation(report_text),
+        "duplicate_work_outcome": assess_work_issue_duplicate_report(report_text),
     }
 
     reasons = []

skills/llm-project-workflow/workflows/work-issue.md

@@ -297,6 +297,36 @@ Report:
 
 Do not create another branch/PR for the same issue unless the project explicitly allows taking over or updating existing work and exact capability is proven.
 
+### 10A. Duplicate-work gate phases (#400)
+
+Before any file edits, prove duplicate-work clearance with
+`gitea_assess_work_issue_duplicate` or `gitea_lock_issue` (which runs the same
+gate). The gate checks live:
+
+* open PRs linked to the issue (head branch or Closes/Fixes reference),
+* remote branches matching `issue-<number>`,
+* active claim leases from structured heartbeats.
+
+Re-check immediately before:
+
+* `gitea_commit_files` (commit),
+* branch push,
+* `gitea_create_pr` (PR creation).
+
+If a concurrent open PR appears after work begins:
+
+* before commit/push → stop and preserve local work without pushing,
+* after commit but before push → stop without pushing,
+* after push but before PR creation → stop and produce a reconciliation
+  handoff instead of opening a PR.
+
+Final reports must state exactly one duplicate-work outcome:
+
+* `duplicate PR prevented`
+* `duplicate branch prevented`
+* `duplicate commit prevented`
+* `duplicate work not prevented`
+
 ## 11. Claim or lock the issue before implementation
 
 Claim/lock the issue before implementation if the project provides a claim/lock mechanism.
@@ -309,15 +339,6 @@ Do not implement unclaimed work.
 
 If the claim/lock gates are broken, produce a recovery handoff.
 
-### Lost lock recovery after push (non-destructive)
-
-If the MCP server restarts after the issue branch was pushed but before PR creation:
-
-* **Do not** delete the remote branch as the normal recovery path.
-* Call `gitea_lock_issue` again with the same issue number and exact branch name. Own-branch adoption rebinds the session when open-PR, competing-lock, and worktree safety checks pass.
-* Call `gitea_create_pr` afterward. Durable keyed locks resolve from the session pointer or by matching the PR `head` branch without manual lock seeding.
-* If adoption is blocked by an open PR, a competing live lease, or a different same-issue branch, stop and produce a recovery handoff.
-
 Create a tooling issue only if this run is explicitly authorized to switch to issue-creation mode and exact `create_issue` capability is proven.
 
 Report:

tests/test_agent_temp_artifacts.py

@@ -83,7 +83,10 @@ class TestIssueLockArtifactWarning(unittest.TestCase):
         self._env_patcher.stop()
         self._lock_dir.cleanup()
 
-    @patch("mcp_server.api_get_all", return_value=[])
+    @patch(
+        "mcp_server.issue_duplicate_context_fetcher",
+        return_value=([], [], {"status": "not_claimed"}),
+    )
     @patch("mcp_server._auth", return_value="token x")
     @patch("mcp_server._resolve", return_value=("h", "o", "r"))
     @patch("issue_lock_worktree.read_worktree_git_state")

tests/test_commit_files_capability.py

@@ -76,7 +76,14 @@ class CommitFilesCapabilityBase(unittest.TestCase):
         with open(self.config_path, "w", encoding="utf-8") as fh:
             fh.write(json.dumps(CONFIG))
 
+        self._dup_fetcher_patcher = patch(
+            "mcp_server.issue_duplicate_context_fetcher",
+            return_value=([], [], {"status": "not_claimed"}),
+        )
+        self._dup_fetcher_patcher.start()
+
     def tearDown(self):
+        self._dup_fetcher_patcher.stop()
         self._remotes.stop()
         mcp_server._IDENTITY_CACHE.clear()
         mcp_server._preflight_whoami_called, mcp_server._preflight_capability_called = (

tests/test_commit_payloads.py

@@ -90,7 +90,14 @@ class TestCommitPayloads(unittest.TestCase):
         mcp_server._preflight_whoami_called = True
         mcp_server._preflight_capability_called = True
 
+        self._dup_fetcher_patcher = patch(
+            "mcp_server.issue_duplicate_context_fetcher",
+            return_value=([], [], {"status": "not_claimed"}),
+        )
+        self._dup_fetcher_patcher.start()
+
     def tearDown(self):
+        self._dup_fetcher_patcher.stop()
         self._remotes.stop()
         mcp_server._IDENTITY_CACHE.clear()
 

tests/test_issue_branch_ownership.py

@@ -1,35 +0,0 @@
-"""Unit tests for structured issue/branch ownership parsing (#440)."""
-import sys
-import unittest
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
-
-from issue_branch_ownership import (  # noqa: E402
-    branch_tracks_issue,
-    parse_tracked_issue_number,
-)
-
-
-class TestIssueBranchOwnership(unittest.TestCase):
-    def test_parses_canonical_author_branch(self):
-        self.assertEqual(
-            parse_tracked_issue_number("feat/issue-420-server-code-parity"),
-            420,
-        )
-
-    def test_issue_4200_does_not_track_issue_420(self):
-        self.assertEqual(parse_tracked_issue_number("feat/issue-4200-unrelated"), 4200)
-        self.assertFalse(branch_tracks_issue("feat/issue-4200-unrelated", 420))
-
-    def test_branch_tracks_issue_exact_match(self):
-        self.assertTrue(
-            branch_tracks_issue("fix/issue-440-branch-recovery", 440)
-        )
-
-    def test_unrelated_branch_does_not_track(self):
-        self.assertFalse(branch_tracks_issue("feat/issue-999-other", 440))
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/test_issue_lock_adoption.py

@@ -43,14 +43,6 @@ class TestAssessOwnBranchAdoption(unittest.TestCase):
         )
         self.assertEqual(result["outcome"], NO_MATCH)
 
-    def test_issue_number_substring_collision_is_ignored(self):
-        result = assess_own_branch_adoption(
-            issue_number=420,
-            requested_branch=REQ,
-            existing_branches=[{"name": "feat/issue-4200-unrelated"}],
-        )
-        self.assertEqual(result["outcome"], NO_MATCH)
-
 
 class TestBuildAdoptionProof(unittest.TestCase):
     def test_proof_has_required_fields(self):

tests/test_issue_lock_recovery.py

@@ -1,152 +0,0 @@
-"""Integration tests for non-destructive lock/PR recovery (#440)."""
-import os
-import sys
-import tempfile
-import unittest
-from pathlib import Path
-from unittest import mock
-from unittest.mock import patch
-
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
-
-import issue_lock_adoption  # noqa: E402
-import issue_lock_store as ils  # noqa: E402
-import mcp_server  # noqa: E402
-from mcp_server import gitea_create_pr, gitea_lock_issue  # noqa: E402
-from tests.test_mcp_server import CREATE_PR_ENV, ISSUE_WRITE_ENV  # noqa: E402
-
-FAKE_AUTH = "token fake"
-BRANCH = "feat/issue-420-server-code-parity"
-
-
-def _lock_record(**overrides):
-    record = {
-        "issue_number": 420,
-        "branch_name": BRANCH,
-        "remote": "prgs",
-        "org": "Scaled-Tech-Consulting",
-        "repo": mcp_server.REMOTES["prgs"]["repo"],
-        "worktree_path": "/tmp/wt-420",
-        "work_lease": {
-            "operation_type": "author_issue_work",
-            "expires_at": "2999-01-01T00:00:00Z",
-        },
-    }
-    record.update(overrides)
-    return record
-
-
-def _clean_git_state():
-    return {
-        "current_branch": BRANCH,
-        "porcelain_status": "",
-        "base_equivalent": True,
-        "inspected_git_root": os.getcwd(),
-        "base_branch": "master",
-    }
-
-
-class TestIssueLockRecovery(unittest.TestCase):
-    def setUp(self):
-        self._tmpdir = tempfile.TemporaryDirectory()
-        self._lock_dir = self._tmpdir.name
-        self._env = {
-            **ISSUE_WRITE_ENV,
-            "GITEA_ISSUE_LOCK_DIR": self._lock_dir,
-        }
-        self._create_pr_env = {
-            **CREATE_PR_ENV,
-            "GITEA_ISSUE_LOCK_DIR": self._lock_dir,
-        }
-
-    def tearDown(self):
-        self._tmpdir.cleanup()
-
-    def test_adoption_after_restart_without_session_pointer(self):
-        with patch.dict(os.environ, self._env, clear=True):
-            with mock.patch("os.getpid", return_value=9999):
-                self.assertIsNone(ils.read_session_issue_lock())
-
-            with mock.patch(
-                "mcp_server.issue_lock_worktree.read_worktree_git_state",
-                return_value=_clean_git_state(),
-            ), mock.patch("mcp_server.api_get_all") as mock_api, mock.patch(
-                "mcp_server.get_auth_header", return_value=FAKE_AUTH
-            ):
-                mock_api.side_effect = [
-                    [],
-                    [{"name": BRANCH, "commit": {"id": "934688a"}}],
-                ]
-                res = gitea_lock_issue(
-                    issue_number=420,
-                    branch_name=BRANCH,
-                    remote="prgs",
-                    worktree_path=os.path.realpath(os.getcwd()),
-                )
-        self.assertTrue(res["success"])
-        self.assertIn("adoption", res)
-        self.assertEqual(res["adoption"]["branch_head_commit"], "934688a")
-
-    @mock.patch(
-        "mcp_server.role_session_router.check_author_mutation_after_reviewer_stop",
-        return_value=(True, []),
-    )
-    @mock.patch("mcp_server.api_request")
-    @mock.patch("mcp_server.get_auth_header", return_value=FAKE_AUTH)
-    def test_create_pr_resolves_keyed_lock_after_restart(self, _auth, mock_api, _role):
-        mock_api.return_value = {"number": 501, "html_url": "https://example/pr/501"}
-        worktree = os.path.realpath(os.getcwd())
-        with patch.dict(os.environ, self._create_pr_env, clear=True):
-            path = ils.lock_file_path(
-                remote="prgs",
-                org=mcp_server.REMOTES["prgs"]["org"],
-                repo=mcp_server.REMOTES["prgs"]["repo"],
-                issue_number=420,
-                lock_dir=self._lock_dir,
-            )
-            ils.save_lock_file(path, _lock_record(worktree_path=worktree))
-
-            with mock.patch("os.getpid", return_value=4242):
-                self.assertIsNone(ils.read_session_issue_lock())
-
-            res = gitea_create_pr(
-                title="feat: recovery Closes #420",
-                head=BRANCH,
-                base="master",
-                remote="prgs",
-                worktree_path=worktree,
-            )
-        self.assertEqual(res["number"], 501)
-
-    def test_open_pr_blocks_adoption(self):
-        with patch.dict(os.environ, self._env, clear=True):
-            with mock.patch(
-                "mcp_server.issue_lock_worktree.read_worktree_git_state",
-                return_value=_clean_git_state(),
-            ), mock.patch("mcp_server.api_get_all") as mock_api, mock.patch(
-                "mcp_server.get_auth_header", return_value=FAKE_AUTH
-            ):
-                mock_api.side_effect = [
-                    [{"number": 99, "head": {"ref": BRANCH}, "title": "", "body": ""}],
-                    [{"name": BRANCH, "commit": {"id": "934688a"}}],
-                ]
-                with self.assertRaises(ValueError) as ctx:
-                    gitea_lock_issue(
-                        issue_number=420,
-                        branch_name=BRANCH,
-                        remote="prgs",
-                        worktree_path=os.path.realpath(os.getcwd()),
-                    )
-        self.assertIn("already tied to an open PR", str(ctx.exception))
-
-    def test_structured_ownership_ignores_issue_4200_collision(self):
-        result = issue_lock_adoption.assess_own_branch_adoption(
-            issue_number=420,
-            requested_branch=BRANCH,
-            existing_branches=[{"name": "feat/issue-4200-unrelated"}],
-        )
-        self.assertEqual(result["outcome"], issue_lock_adoption.NO_MATCH)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/test_issue_work_duplicate_gate.py

@@ -0,0 +1,251 @@
+"""Tests for early duplicate-work detection (#400)."""
+import json
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import issue_work_duplicate_gate as dup_gate
+import mcp_server
+from issue_work_duplicate_gate import (
+    OUTCOME_DUPLICATE_BRANCH_PREVENTED,
+    OUTCOME_DUPLICATE_COMMIT_PREVENTED,
+    OUTCOME_DUPLICATE_PR_PREVENTED,
+    OUTCOME_DUPLICATE_WORK_NOT_PREVENTED,
+    PHASE_COMMIT,
+    PHASE_CREATE_PR,
+    PHASE_LOCK,
+    assess_work_issue_duplicate_gate,
+    assess_work_issue_duplicate_report,
+)
+
+
+class TestDuplicateGateAssessment(unittest.TestCase):
+    def test_clear_issue_passes(self):
+        result = assess_work_issue_duplicate_gate(
+            400,
+            open_prs=[],
+            branch_names=["feat/other-issue-99"],
+            claim_entry={"status": "not_claimed"},
+            locked_branch="feat/issue-400-duplicate-work-preflight",
+            phase=PHASE_LOCK,
+        )
+        self.assertFalse(result["block"])
+        self.assertEqual(result["outcome"], OUTCOME_DUPLICATE_WORK_NOT_PREVENTED)
+
+    def test_open_pr_blocks(self):
+        prs = [{
+            "number": 397,
+            "title": "feat: handoff",
+            "body": "Closes #395",
+            "head": {"ref": "feat/issue-395-proof-backed-review-handoff"},
+        }]
+        result = assess_work_issue_duplicate_gate(
+            395,
+            open_prs=prs,
+            branch_names=[],
+            phase=PHASE_LOCK,
+        )
+        self.assertTrue(result["block"])
+        self.assertEqual(result["outcome"], OUTCOME_DUPLICATE_PR_PREVENTED)
+
+    def test_conflicting_remote_branch_blocks(self):
+        result = assess_work_issue_duplicate_gate(
+            395,
+            open_prs=[],
+            branch_names=["feat/issue-395-proof-backed-handoff-claims"],
+            locked_branch="feat/issue-395-new-attempt",
+            phase=PHASE_LOCK,
+        )
+        self.assertTrue(result["block"])
+        self.assertEqual(result["outcome"], OUTCOME_DUPLICATE_BRANCH_PREVENTED)
+
+    def test_active_claim_on_other_branch_blocks(self):
+        result = assess_work_issue_duplicate_gate(
+            398,
+            open_prs=[],
+            branch_names=[],
+            claim_entry={
+                "status": "active",
+                "latest_heartbeat": {
+                    "branch": "feat/issue-398-validation-cwd-proof",
+                },
+            },
+            locked_branch="feat/issue-398-other-branch",
+            phase=PHASE_LOCK,
+        )
+        self.assertTrue(result["block"])
+
+    def test_commit_phase_maps_to_commit_outcome(self):
+        prs = [{
+            "number": 411,
+            "title": "x",
+            "body": "Closes #398",
+            "head": {"ref": "feat/issue-398-validation-cwd-proof"},
+        }]
+        result = assess_work_issue_duplicate_gate(
+            398,
+            open_prs=prs,
+            branch_names=[],
+            locked_branch="feat/issue-398-alt",
+            phase=PHASE_COMMIT,
+        )
+        self.assertTrue(result["block"])
+        self.assertEqual(result["outcome"], OUTCOME_DUPLICATE_COMMIT_PREVENTED)
+
+    def test_stale_claim_does_not_block_by_status_alone(self):
+        result = assess_work_issue_duplicate_gate(
+            400,
+            open_prs=[],
+            branch_names=[],
+            claim_entry={"status": "reclaimable", "reasons": ["stale"]},
+            locked_branch="feat/issue-400-duplicate-work-preflight",
+            phase=PHASE_LOCK,
+        )
+        self.assertFalse(result["block"])
+
+
+class TestDuplicateReportOutcome(unittest.TestCase):
+    def test_requires_exactly_one_outcome(self):
+        bad = assess_work_issue_duplicate_report("work finished")
+        self.assertFalse(bad["complete"])
+
+        good = assess_work_issue_duplicate_report(
+            "Duplicate work not prevented for issue #400."
+        )
+        self.assertTrue(good["complete"])
+        self.assertEqual(good["outcome"], OUTCOME_DUPLICATE_WORK_NOT_PREVENTED)
+
+
+class TestInjectableDuplicateFetcher(unittest.TestCase):
+    @patch("mcp_server.get_auth_header", return_value="token x")
+    def test_lock_issue_uses_injected_fetcher(self, _auth):
+        seen = {}
+
+        def fetcher(h, o, r, auth, issue_number):
+            seen["issue_number"] = issue_number
+            return [], [], {"status": "not_claimed"}
+
+        with patch(
+            "mcp_server.issue_duplicate_context_fetcher",
+            side_effect=fetcher,
+        ), patch(
+            "mcp_server.issue_lock_worktree.read_worktree_git_state",
+            return_value={
+                "current_branch": "master",
+                "porcelain_status": "",
+                "base_equivalent": True,
+            },
+        ), patch.dict(os.environ, {
+            "GITEA_ALLOWED_OPERATIONS": "gitea.issue.comment",
+        }, clear=True):
+            with patch.object(mcp_server, "ISSUE_LOCK_FILE", tempfile.mktemp()):
+                mcp_server.gitea_lock_issue(
+                    issue_number=400,
+                    branch_name="feat/issue-400-duplicate-work-preflight",
+                    remote="prgs",
+                )
+        self.assertEqual(seen["issue_number"], 400)
+
+
+class TestMcpDuplicateRecheck(unittest.TestCase):
+    def setUp(self):
+        self._dir = tempfile.TemporaryDirectory()
+        self.lock_path = os.path.join(self._dir.name, "gitea_issue_lock.json")
+        self._lock_patch = patch.object(
+            mcp_server, "ISSUE_LOCK_FILE", self.lock_path
+        )
+        self._lock_patch.start()
+        self._remotes = patch.dict(mcp_server.REMOTES, {
+            "prgs": {"host": "gitea.example.com", "org": "Example-Org",
+                     "repo": "Example-Repo"},
+        })
+        self._remotes.start()
+        mcp_server._IDENTITY_CACHE.clear()
+
+    def tearDown(self):
+        patch.stopall()
+        self._dir.cleanup()
+
+    def _write_lock(self, issue_number=400, branch="feat/issue-400-x"):
+        with open(self.lock_path, "w", encoding="utf-8") as fh:
+            json.dump({
+                "issue_number": issue_number,
+                "branch_name": branch,
+                "remote": "prgs",
+            }, fh)
+
+    @patch("mcp_server._assess_issue_duplicate_gate")
+    @patch("mcp_server.get_profile", return_value={
+        "profile_name": "test-author",
+        "allowed_operations": ["gitea.read", "gitea.repo.commit"],
+        "forbidden_operations": [],
+        "audit_label": "test-author",
+    })
+    @patch("mcp_server.get_auth_header", return_value="token x")
+    def test_commit_files_blocked_on_recheck(self, _auth, _profile, mock_gate):
+        self._write_lock()
+        mock_gate.return_value = {
+            "block": True,
+            "reasons": ["open PR #412 already covers issue #400"],
+            "outcome": OUTCOME_DUPLICATE_COMMIT_PREVENTED,
+            "safe_next_action": "stop",
+        }
+        mcp_server.record_preflight_check("whoami")
+        mcp_server.record_preflight_check("capability", resolved_role="author")
+        with patch(
+            "mcp_server.role_session_router.check_author_mutation_after_reviewer_stop",
+            return_value=(True, []),
+        ):
+            result = mcp_server.gitea_commit_files(
+                files=[{
+                    "operation": "create",
+                    "path": "a.txt",
+                    "content_plain": "hi",
+                }],
+                message="test",
+                remote="prgs",
+            )
+        self.assertFalse(result["success"])
+        self.assertIn("duplicate_gate", result)
+
+    @patch("mcp_server._assess_issue_duplicate_gate")
+    @patch("mcp_server.get_profile", return_value={
+        "profile_name": "test-author",
+        "allowed_operations": ["gitea.read", "gitea.pr.create"],
+        "forbidden_operations": [],
+        "audit_label": "test-author",
+    })
+    @patch("mcp_server.get_auth_header", return_value="token x")
+    def test_create_pr_returns_handoff_on_duplicate(self, _auth, _profile, mock_gate):
+        self._write_lock()
+        mock_gate.return_value = {
+            "block": True,
+            "reasons": ["open PR #412 already covers issue #400"],
+            "outcome": OUTCOME_DUPLICATE_PR_PREVENTED,
+            "safe_next_action": "reconciliation handoff",
+        }
+        mcp_server.record_preflight_check("whoami")
+        mcp_server.record_preflight_check("capability", resolved_role="author")
+        with patch(
+            "mcp_server.role_session_router.check_author_mutation_after_reviewer_stop",
+            return_value=(True, []),
+        ):
+            result = mcp_server.gitea_create_pr(
+                title="feat: x (Closes #400)",
+                head="feat/issue-400-x",
+                base="master",
+                body="Closes #400",
+                remote="prgs",
+            )
+        self.assertFalse(result["success"])
+        self.assertIsNone(result.get("number"))
+        self.assertIn("duplicate_gate", result)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_mcp_server.py

@@ -116,6 +116,11 @@ def _sample_issue_lock(issue_number=123, branch_name="feat/x", **overrides):
     return record
 
 
+def _clear_duplicate_context_fetcher(*_args, **_kwargs):
+    """Default injectable duplicate-work context for lock/create_pr tests."""
+    return [], [], {"status": "not_claimed"}
+
+
 def _bind_test_lock(**overrides) -> str:
     remote = overrides.get("remote", "dadeschools")
     record = _sample_issue_lock(**overrides)
@@ -181,11 +186,15 @@ class TestCreateIssue(unittest.TestCase):
 # ---------------------------------------------------------------------------
 class TestCreatePR(unittest.TestCase):
 
+    @patch(
+        "mcp_server.issue_duplicate_context_fetcher",
+        return_value=([], [], {"status": "not_claimed"}),
+    )
     @patch("mcp_server.role_session_router.check_author_mutation_after_reviewer_stop",
            return_value=(True, []))
     @patch("mcp_server.api_request")
     @patch("mcp_server.get_auth_header", return_value=FAKE_AUTH)
-    def test_creates_pr(self, _auth, mock_api, _role):
+    def test_creates_pr(self, _auth, mock_api, _role, _dup_fetcher):
         worktree = os.path.realpath(os.getcwd())
         mock_api.return_value = {"number": 3, "html_url": "https://example.com/pulls/3"}
         with tempfile.TemporaryDirectory() as lock_dir:
@@ -205,11 +214,15 @@ class TestCreatePR(unittest.TestCase):
         self.assertEqual(payload["base"], "main")
         self.assertIn("Closes #123", payload["title"])
 
+    @patch(
+        "mcp_server.issue_duplicate_context_fetcher",
+        return_value=([], [], {"status": "not_claimed"}),
+    )
     @patch("mcp_server.role_session_router.check_author_mutation_after_reviewer_stop",
            return_value=(True, []))
     @patch("mcp_server.api_request")
     @patch("mcp_server.get_auth_header", return_value=FAKE_AUTH)
-    def test_create_pr_reveal_opt_in_includes_url(self, _auth, mock_api, _role):
+    def test_create_pr_reveal_opt_in_includes_url(self, _auth, mock_api, _role, _dup_fetcher):
         worktree = os.path.realpath(os.getcwd())
         mock_api.return_value = {"number": 3, "html_url": "https://example.com/pulls/3"}
         with tempfile.TemporaryDirectory() as lock_dir:
@@ -3079,8 +3092,14 @@ class TestIssueLocking(unittest.TestCase):
         }
         self._env_patcher = patch.dict(os.environ, env, clear=True)
         self._env_patcher.start()
+        self._dup_fetcher_patcher = patch(
+            "mcp_server.issue_duplicate_context_fetcher",
+            return_value=([], [], {"status": "not_claimed"}),
+        )
+        self.mock_dup_fetcher = self._dup_fetcher_patcher.start()
 
     def tearDown(self):
+        self._dup_fetcher_patcher.stop()
         self._env_patcher.stop()
         self._lock_dir.cleanup()
 
@@ -3094,10 +3113,9 @@ class TestIssueLocking(unittest.TestCase):
         "mcp_server.issue_lock_worktree.read_worktree_git_state",
         return_value=_clean_master_git_state_for_lock(),
     )
-    @patch("mcp_server.api_get_all")
+    @patch("mcp_server.api_get_all", return_value=[])
     @patch("mcp_server.get_auth_header", return_value=FAKE_AUTH)
-    def test_lock_issue_success(self, _auth, mock_api, _git_state):
+    def test_lock_issue_success(self, _auth, _api, _git_state):
-        mock_api.return_value = [] # no open PRs
         res = gitea_lock_issue(issue_number=196, branch_name="feat/issue-196-mutations", remote="prgs")
         self.assertTrue(res["success"])
         self.assertEqual(res["work_lease"]["operation_type"], "author_issue_work")
@@ -3121,50 +3139,48 @@ class TestIssueLocking(unittest.TestCase):
         "mcp_server.issue_lock_worktree.read_worktree_git_state",
         return_value=_clean_master_git_state_for_lock(),
     )
-    @patch("mcp_server.api_get_all")
     @patch("mcp_server.get_auth_header", return_value=FAKE_AUTH)
-    def test_lock_issue_reused_by_open_pr_branch(self, _auth, mock_api, _git_state):
+    def test_lock_issue_reused_by_open_pr_branch(self, _auth, _git_state):
-        mock_api.return_value = [{
+        self.mock_dup_fetcher.return_value = ([{
             "number": 200,
             "head": {"ref": "feat/issue-196-boundary"},
             "title": "Some PR",
-            "body": "No closes ref"
+            "body": "No closes ref",
-        }]
+        }], [], {"status": "not_claimed"})
         with self.assertRaises(ValueError) as ctx:
             gitea_lock_issue(issue_number=196, branch_name="feat/issue-196-mutations", remote="prgs")
-        self.assertIn("already tied to an open PR", str(ctx.exception))
+        self.assertIn("open PR #200 already covers issue", str(ctx.exception))
 
     @patch(
         "mcp_server.issue_lock_worktree.read_worktree_git_state",
         return_value=_clean_master_git_state_for_lock(),
     )
-    @patch("mcp_server.api_get_all")
     @patch("mcp_server.get_auth_header", return_value=FAKE_AUTH)
-    def test_lock_issue_reused_by_open_pr_closes_ref(self, _auth, mock_api, _git_state):
+    def test_lock_issue_reused_by_open_pr_closes_ref(self, _auth, _git_state):
-        mock_api.return_value = [{
+        self.mock_dup_fetcher.return_value = ([{
             "number": 200,
             "head": {"ref": "feat/other-branch"},
             "title": "Some PR",
-            "body": "fixes #196"
+            "body": "fixes #196",
-        }]
+        }], [], {"status": "not_claimed"})
         with self.assertRaises(ValueError) as ctx:
             gitea_lock_issue(issue_number=196, branch_name="feat/issue-196-mutations", remote="prgs")
-        self.assertIn("already tied to an open PR", str(ctx.exception))
+        self.assertIn("open PR #200 already covers issue", str(ctx.exception))
 
     @patch(
         "mcp_server.issue_lock_worktree.read_worktree_git_state",
         return_value=_clean_master_git_state_for_lock(),
     )
-    @patch("mcp_server.api_get_all")
     @patch("mcp_server.get_auth_header", return_value=FAKE_AUTH)
-    def test_lock_issue_reused_by_remote_branch(self, _auth, mock_api, _git_state):
+    def test_lock_issue_reused_by_remote_branch(self, _auth, _git_state):
-        mock_api.side_effect = [
+        self.mock_dup_fetcher.return_value = (
             [],
-            [{"name": "feat/issue-196-existing-work"}],
+            ["feat/issue-196-existing-work"],
-        ]
+            {"status": "not_claimed"},
+        )
         with self.assertRaises(ValueError) as ctx:
             gitea_lock_issue(issue_number=196, branch_name="feat/issue-196-mutations", remote="prgs")
-        self.assertIn("not the requested branch", str(ctx.exception))
+        self.assertIn("remote branch(es) already match issue pattern", str(ctx.exception))
 
     @patch(
         "mcp_server.issue_lock_worktree.read_worktree_git_state",
@@ -3174,10 +3190,8 @@ class TestIssueLocking(unittest.TestCase):
     @patch("mcp_server.get_auth_header", return_value=FAKE_AUTH)
     def test_lock_issue_adopts_exact_own_branch(self, _auth, mock_api, _git_state):
         branch = "feat/issue-196-mutations"
-        mock_api.side_effect = [
+        self.mock_dup_fetcher.return_value = ([], [branch], {"status": "not_claimed"})
-            [],
+        mock_api.return_value = [{"name": branch, "commit": {"id": "abc123"}}]
-            [{"name": branch, "commit": {"id": "abc123"}}],
-        ]
         res = gitea_lock_issue(issue_number=196, branch_name=branch, remote="prgs")
         self.assertTrue(res["success"])
         self.assertIn("adoption", res)

tests/test_review_proofs.py

@@ -2346,6 +2346,7 @@ class TestWorkIssueFinalReport(unittest.TestCase):
             "- Safe next action: open PR",
             "- Next: open PR",
             "- Safety statement: no review/merge",
+            "- Duplicate work outcome: duplicate work not prevented",
         ])
 
     def test_complete_work_issue_report_earns_a(self):