feat: diagnose reviewer lease handoff next actions (#599)

Add read-only diagnose_reviewer_pr_lease_handoff and MCP tool gitea_diagnose_reviewer_pr_lease_handoff so open-PR foreign leases, instructed-lease replacement, reclaimable release, and worktree binding mismatch return a canonical next_action without steal paths. Closes #599
2026-07-09 17:31:14 -04:00
parent 683649424b
commit 964505654f
3 changed files with 402 additions and 1 deletions
@@ -237,5 +237,113 @@ class TestReviewerLeaseMcpGate(unittest.TestCase):
        self.assertTrue(any("lease" in r.lower() for r in reasons))


+
+class TestReviewerLeaseHandoffDiagnose(unittest.TestCase):
+    """#599: canonical next-action diagnosis for open-PR lease handoff."""
+
+    def setUp(self):
+        leases.clear_session_lease()
+
+    def test_no_lease_next_action_acquire(self):
+        result = leases.diagnose_reviewer_pr_lease_handoff(
+            [],
+            pr_number=592,
+            current_session_id="me-1",
+            current_reviewer_identity="sysadmin",
+            proposed_worktree="branches/review-pr-592",
+        )
+        self.assertEqual(result["classification"], "no_lease")
+        self.assertEqual(result["next_action"], leases.NEXT_ACTION_ACQUIRE)
+        self.assertIsNone(result["active_lease"])
+
+    def test_foreign_active_wait_pr592_style(self):
+        # Instructed lease gone; newer foreign claim is active.
+        old = _lease_comment(592, "23139-da018dab43ba", phase="released")
+        old["id"] = 8640
+        active = _lease_comment(592, "51515-2bfb70f0685f", phase="claimed")
+        active["id"] = 8647
+        result = leases.diagnose_reviewer_pr_lease_handoff(
+            [old, active],
+            pr_number=592,
+            current_session_id="fresh-session",
+            current_reviewer_identity="sysadmin",
+            proposed_worktree="branches/review-pr-592-issue-590",
+            instructed_session_id="23139-da018dab43ba",
+            instructed_comment_id=8640,
+        )
+        self.assertEqual(
+            result["classification"],
+            "instructed_lease_missing_with_replacement",
+        )
+        self.assertEqual(result["next_action"], leases.NEXT_ACTION_WAIT)
+        self.assertTrue(result["instructed_lease_missing_with_replacement"])
+        self.assertEqual(result["active_lease"]["session_id"], "51515-2bfb70f0685f")
+        self.assertEqual(result["active_lease"]["comment_id"], 8647)
+        self.assertFalse(result["mutation_allowed"])
+
+    def test_foreign_reclaimable_release_expired(self):
+        reclaim = _lease_comment(
+            592, "foreign-old", phase="claimed", minutes_ago=65
+        )
+        reclaim["id"] = 99
+        result = leases.diagnose_reviewer_pr_lease_handoff(
+            [reclaim],
+            pr_number=592,
+            current_session_id="me-1",
+            current_reviewer_identity="sysadmin",
+            proposed_worktree="branches/review-pr-592",
+        )
+        self.assertEqual(result["classification"], "foreign_reclaimable")
+        self.assertEqual(
+            result["next_action"], leases.NEXT_ACTION_RELEASE_EXPIRED_LEASE
+        )
+
+    def test_own_active_resume(self):
+        head = "a" * 40
+        claim = _lease_comment(592, "me-1", phase="claimed", candidate_head=head)
+        claim["id"] = 10
+        leases.record_session_lease({
+            "pr_number": 592,
+            "session_id": "me-1",
+            "candidate_head": head,
+            "comment_id": 10,
+        }, lease_provenance=mla.build_lease_provenance(
+            source=mla.SOURCE_ACQUIRE,
+            comment_id=10,
+        ))
+        result = leases.diagnose_reviewer_pr_lease_handoff(
+            [claim],
+            pr_number=592,
+            current_session_id="me-1",
+            current_reviewer_identity="rev1",
+            proposed_worktree="branches/review-pr382",
+        )
+        self.assertEqual(result["classification"], "own_active")
+        self.assertEqual(
+            result["next_action"], leases.NEXT_ACTION_RESUME_EXACT_OWNER_SESSION
+        )
+        self.assertTrue(result["mutation_allowed"])
+
+    def test_worktree_binding_mismatch(self):
+        claim = _lease_comment(592, "me-1", phase="claimed")
+        claim["id"] = 11
+        # _lease_comment uses branches/review-pr382
+        result = leases.diagnose_reviewer_pr_lease_handoff(
+            [claim],
+            pr_number=592,
+            current_session_id="me-1",
+            current_reviewer_identity="rev1",
+            proposed_worktree="branches/review-pr-592-issue-590",
+            env_bound_worktree="branches/review-pr-538",
+        )
+        self.assertEqual(result["classification"], "worktree_binding_mismatch")
+        self.assertEqual(
+            result["next_action"], leases.NEXT_ACTION_REPAIR_WORKTREE_BINDING
+        )
+        self.assertFalse(result["worktree_binding"]["match"])
+        self.assertFalse(result["mutation_allowed"])
+
+
+
 if __name__ == "__main__":
    unittest.main()