feat(lease): guarded cleanup for obsolete reviewer comment leases (Closes #691) #692

2026-07-12T22:10:55-05:00

jcwalker3 commented

2026-07-12 22:10:55 -05:00

Summary

Closes #691. Adds a guarded, non-owner cleanup path for comment-backed reviewer leases that remain after formal terminal review on a superseded head (and/or after recorded expiry), without a control-plane DB lease_id.

Reproduces the PR #688 / lease comment 10749 class of defect: completed REQUEST_CHANGES on head A, author pushes head B, foreign lease stays pinned to A; diagnosis previously prescribed indefinite wait only.

Design

Cleanup tool

gitea_cleanup_obsolete_reviewer_comment_lease

Read-first (apply=false)
Apply requires:
- controller_recovery_authorized=true
- confirmation exactly CLEANUP OBSOLETE REVIEWER LEASE <pr_number>
- full eligibility from assess_obsolete_reviewer_comment_lease_cleanup
Neutralises via append-only phase: released lease marker + canonical audit comment
Never deletes comments, never repoints head, never transfers validation/decision/workflow proof, never uses PID as ownership, never seeds session lease

Eligibility matrix (all required evidence)

Condition	Required
Past recorded expiry or superseded head with formal terminal review	yes
Current PR head ≠ leased head (superseded path)	yes
Formal APPROVED / REQUEST_CHANGES on leased head when required	yes
No current-head review in progress	yes
Worktree clean or safely absent	yes
Not owned by requesting session	yes
Controller/recovery authorized	yes
Repo/org/PR/head/session/comment identities match when supplied	yes

Diagnosis (#599 extended)

gitea_diagnose_reviewer_pr_lease_handoff now distinguishes:

foreign_active_current_head → wait
foreign_expired_current_head / orphaned_owner_missing → cleanup when safe
foreign_completed_superseded_head / foreign_expired_superseded_head → cleanup_obsolete_reviewer_comment_lease (not indefinite wait)
ambiguous_conflicting_evidence → fail closed

Explicit non-goals

Do not manually clean lease 10749 as part of this author PR
Do not modify PR #688 product code or submit its review

Validation

Focused #691 suite: passed
Lease suites: passed
Review/workflow/capability suites: passed
Full suite: 2636 passed, 6 skipped
compileall: OK
Head: 6d86db793bbdfaed16bd54d93171f1dd66f234ca

Next role

Independent REVIEWER — do not self-review or merge.

## Summary Closes #691. Adds a guarded, non-owner cleanup path for **comment-backed** reviewer leases that remain after formal terminal review on a superseded head (and/or after recorded expiry), without a control-plane DB `lease_id`. Reproduces the PR #688 / lease comment **10749** class of defect: completed REQUEST_CHANGES on head A, author pushes head B, foreign lease stays pinned to A; diagnosis previously prescribed indefinite `wait` only. ## Design ### Cleanup tool `gitea_cleanup_obsolete_reviewer_comment_lease` - Read-first (`apply=false`) - Apply requires: - `controller_recovery_authorized=true` - confirmation exactly `CLEANUP OBSOLETE REVIEWER LEASE <pr_number>` - full eligibility from `assess_obsolete_reviewer_comment_lease_cleanup` - Neutralises via **append-only** `phase: released` lease marker + canonical audit comment - Never deletes comments, never repoints head, never transfers validation/decision/workflow proof, never uses PID as ownership, never seeds session lease ### Eligibility matrix (all required evidence) | Condition | Required | |-----------|----------| | Past recorded expiry **or** superseded head with formal terminal review | yes | | Current PR head ≠ leased head (superseded path) | yes | | Formal APPROVED / REQUEST_CHANGES on leased head when required | yes | | No current-head review in progress | yes | | Worktree clean or safely absent | yes | | Not owned by requesting session | yes | | Controller/recovery authorized | yes | | Repo/org/PR/head/session/comment identities match when supplied | yes | ### Diagnosis (#599 extended) `gitea_diagnose_reviewer_pr_lease_handoff` now distinguishes: - `foreign_active_current_head` → wait - `foreign_expired_current_head` / `orphaned_owner_missing` → cleanup when safe - `foreign_completed_superseded_head` / `foreign_expired_superseded_head` → **cleanup_obsolete_reviewer_comment_lease** (not indefinite wait) - `ambiguous_conflicting_evidence` → fail closed ## Explicit non-goals - Do **not** manually clean lease 10749 as part of this author PR - Do **not** modify PR #688 product code or submit its review ## Validation - Focused #691 suite: **passed** - Lease suites: **passed** - Review/workflow/capability suites: **passed** - Full suite: **2636 passed, 6 skipped** - `compileall`: **OK** - Head: `6d86db793bbdfaed16bd54d93171f1dd66f234ca` ## Next role **Independent REVIEWER** — do not self-review or merge.

jcwalker3 added 1 commit 2026-07-12 22:10:55 -05:00

feat(lease): guarded cleanup for obsolete reviewer comment leases (Closes #691 ) 6d86db793b

Add fail-closed assessment and MCP tool for expired/superseded-head
comment-backed reviewer leases that lack a control-plane lease_id.

- assess_obsolete_reviewer_comment_lease_cleanup eligibility matrix
- diagnose classifications: foreign_active_current_head,
  foreign_expired_current_head, foreign_completed_superseded_head,
  foreign_expired_superseded_head, orphaned_owner_missing,
  ambiguous_conflicting_evidence
- gitea_cleanup_obsolete_reviewer_comment_lease with confirmation
  CLEANUP OBSOLETE REVIEWER LEASE <n> and controller_recovery_authorized
- preserve audit history via append-only phase=released marker
- never repoint, transfer validation, use PID ownership, or steal
  active current-head foreign leases
- regression for PR #688 lease comment 10749 after recorded expiry

jcwalker3 referenced this pull request

2026-07-12 22:11:09 -05:00

Completed reviewer lease pinned to superseded PR head stays active with no canonical non-owner cleanup path #691

jcwalker3 commented

2026-07-12 22:11:20 -05:00

Canonical Issue State

STATE: ready-for-review

WHO_IS_NEXT: reviewer

NEXT_ACTION: Independent REVIEWER validates this PR against #691 ACs; do not self-review or merge

NEXT_PROMPT:

Role: REVIEWER (must differ from PR author jcwalker3 / prgs-author)
Repo: prgs / Scaled-Tech-Consulting / Gitea-Tools
PR: #692  |  Issue: #691 (Closes #691)
Base: master
Head: fix/issue-691-obsolete-reviewer-lease-cleanup @ 6d86db793bbdfaed16bd54d93171f1dd66f234ca

1. gitea_whoami + gitea_load_review_workflow + gitea_resolve_task_capability(review_pr) on prgs-reviewer.
2. Inventory PR #692; pin expected_head_sha.
3. Review worktree under branches/; never mutate control root.
4. Verify:
   - assess_obsolete_reviewer_comment_lease_cleanup eligibility matrix
   - diagnose classifications (foreign_*_current_head / superseded / orphan / ambiguous)
   - gitea_cleanup_obsolete_reviewer_comment_lease confirmation + controller_recovery_authorized
   - no PID ownership, no repoint, no validation transfer, no comment deletion
   - active current-head foreign lease still fail-closed
   - regression PR #688 lease comment 10749 after expires_at 2026-07-13T04:23:00Z
5. Run focused #691 + lease + review suites + full suite from review worktree.
6. Post independent APPROVE or REQUEST_CHANGES. Do not merge.

WHAT_HAPPENED:
Author shipped #691 hardening in commit 6d86db7 and opened this PR with Closes #691.

Implementation summary

reviewer_pr_lease.py: assessor + extended diagnose + find_newest_nonterminal_lease (includes expired comment markers)
gitea_mcp_server.py: diagnose wires live head + formal reviews + worktree porcelain; new cleanup tool
task_capability_map.py: cleanup_obsolete_reviewer_comment_lease → gitea.pr.comment
mcp_native_cleanup_proof.py: authorize new cleanup tool name
tests/test_issue_691_obsolete_reviewer_lease_cleanup.py: AC matrix + 10749 regression

Cleanup eligibility matrix

Case	Result
REQUEST_CHANGES @ A, push B, expired	cleanup OK (foreign_expired_superseded_head)
APPROVE @ A, push B, unexpired	cleanup OK (foreign_completed_superseded_head)
Active foreign on current head	deny + wait
Recent owner progress on current head	deny
Owner absent + dirty worktree	deny
Owner absent + clean worktree + expired current head	orphan cleanup OK
PID equality	never ownership
No DB lease_id	still recoverable via comment ledger
Wrong repo/PR/session/head evidence	fail closed
Malformed expiry	fail closed
Repeated cleanup	idempotent (newest released)

Exact audit behavior

Apply posts: (1) terminal lease marker phase=released with original candidate_head; (2) canonical audit comment citing #691 fields. No history deletion; no session seeding; no head repoint.

WHY: Provides the missing non-owner path for obsolete comment-backed leases after terminal review + head replacement, ending indefinite wait for the 10749 class of incident.

RELATED_PRS: #692 (this); #688 incident reproduction only

BLOCKERS: none for independent review

VALIDATION:

Full suite: 2636 passed, 6 skipped (post-commit, immutable head)
Focused #691 suite passed
compileall OK

LAST_UPDATED_BY: jcwalker3 / prgs-author / AUTHOR / 2026-07-13

## Canonical Issue State STATE: ready-for-review WHO_IS_NEXT: reviewer NEXT_ACTION: Independent REVIEWER validates this PR against #691 ACs; do not self-review or merge NEXT_PROMPT: ```text Role: REVIEWER (must differ from PR author jcwalker3 / prgs-author) Repo: prgs / Scaled-Tech-Consulting / Gitea-Tools PR: #692 | Issue: #691 (Closes #691) Base: master Head: fix/issue-691-obsolete-reviewer-lease-cleanup @ 6d86db793bbdfaed16bd54d93171f1dd66f234ca 1. gitea_whoami + gitea_load_review_workflow + gitea_resolve_task_capability(review_pr) on prgs-reviewer. 2. Inventory PR #692; pin expected_head_sha. 3. Review worktree under branches/; never mutate control root. 4. Verify: - assess_obsolete_reviewer_comment_lease_cleanup eligibility matrix - diagnose classifications (foreign_*_current_head / superseded / orphan / ambiguous) - gitea_cleanup_obsolete_reviewer_comment_lease confirmation + controller_recovery_authorized - no PID ownership, no repoint, no validation transfer, no comment deletion - active current-head foreign lease still fail-closed - regression PR #688 lease comment 10749 after expires_at 2026-07-13T04:23:00Z 5. Run focused #691 + lease + review suites + full suite from review worktree. 6. Post independent APPROVE or REQUEST_CHANGES. Do not merge. ``` WHAT_HAPPENED: Author shipped #691 hardening in commit 6d86db7 and opened this PR with Closes #691. ### Implementation summary - `reviewer_pr_lease.py`: assessor + extended diagnose + find_newest_nonterminal_lease (includes expired comment markers) - `gitea_mcp_server.py`: diagnose wires live head + formal reviews + worktree porcelain; new cleanup tool - `task_capability_map.py`: cleanup_obsolete_reviewer_comment_lease → gitea.pr.comment - `mcp_native_cleanup_proof.py`: authorize new cleanup tool name - `tests/test_issue_691_obsolete_reviewer_lease_cleanup.py`: AC matrix + 10749 regression ### Cleanup eligibility matrix | Case | Result | |------|--------| | REQUEST_CHANGES @ A, push B, expired | cleanup OK (foreign_expired_superseded_head) | | APPROVE @ A, push B, unexpired | cleanup OK (foreign_completed_superseded_head) | | Active foreign on current head | deny + wait | | Recent owner progress on current head | deny | | Owner absent + dirty worktree | deny | | Owner absent + clean worktree + expired current head | orphan cleanup OK | | PID equality | never ownership | | No DB lease_id | still recoverable via comment ledger | | Wrong repo/PR/session/head evidence | fail closed | | Malformed expiry | fail closed | | Repeated cleanup | idempotent (newest released) | ### Exact audit behavior Apply posts: (1) terminal lease marker phase=released with original candidate_head; (2) canonical audit comment citing #691 fields. No history deletion; no session seeding; no head repoint. WHY: Provides the missing non-owner path for obsolete comment-backed leases after terminal review + head replacement, ending indefinite wait for the 10749 class of incident. RELATED_PRS: #692 (this); #688 incident reproduction only BLOCKERS: none for independent review VALIDATION: - Full suite: 2636 passed, 6 skipped (post-commit, immutable head) - Focused #691 suite passed - compileall OK LAST_UPDATED_BY: jcwalker3 / prgs-author / AUTHOR / 2026-07-13

sysadmin commented

2026-07-12 22:18:41 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #692
issue: none
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 25883-70f5dabbf157
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-692
phase: claimed
candidate_head: 6d86db793b
target_branch: master
target_branch_sha: none
last_activity: 2026-07-13T03:18:40Z
expires_at: 2026-07-13T05:18:40Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #692 issue: none reviewer_identity: sysadmin profile: prgs-reviewer session_id: 25883-70f5dabbf157 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-692 phase: claimed candidate_head: 6d86db793bbdfaed16bd54d93171f1dd66f234ca target_branch: master target_branch_sha: none last_activity: 2026-07-13T03:18:40Z expires_at: 2026-07-13T05:18:40Z blocker: none

sysadmin approved these changes 2026-07-12 22:22:41 -05:00

sysadmin left a comment

Canonical PR State

STATE: approved
WHO_IS_NEXT: merger
NEXT_ACTION: Merger executes the merge sequence for PR #692.
NEXT_PROMPT:

Role: MERGER (must differ from PR author jcwalker3 / prgs-author)
Repo: prgs / Scaled-Tech-Consulting / Gitea-Tools
PR: #692  |  Issue: #691
Base: master
Head: fix/issue-691-obsolete-reviewer-lease-cleanup @ 6d86db793bbdfaed16bd54d93171f1dd66f234ca

1. gitea_whoami + gitea_resolve_task_capability(merge_pr) on prgs-merger.
2. Confirm PR #692 is approved at head 6d86db7…
3. Submit merge confirmation: 'MERGE PR 692'.

WHAT_HAPPENED: PR review completed with APPROVED. Independent REVIEWER verified:

Obsolete lease cleanup eligibility matrix handles superseded/expired leases securely.
Mutually exclusive classification matrix correctly maps foreign and orphaned leases.
Mutation tool safety ensures read-first behavior, confirmation checks, and append-only audits.
Regression test for PR #688 / comment 10749 correctly proves cleanup behavior.
All 2636 tests passed.
WHY: The implementation provides a complete, robust, and highly guarded non-owner cleanup path for obsolete comment-backed reviewer leases, fully satisfying all acceptance criteria for Issue #691.
ISSUE: 691
HEAD_SHA: 6d86db793b
REVIEW_STATUS: approved
MERGE_READY: true
BLOCKERS: none
VALIDATION: 2636 passed, 6 skipped on commit 6d86db7.
LAST_UPDATED_BY: reviewer

## Canonical PR State STATE: approved WHO_IS_NEXT: merger NEXT_ACTION: Merger executes the merge sequence for PR #692. NEXT_PROMPT: ```text Role: MERGER (must differ from PR author jcwalker3 / prgs-author) Repo: prgs / Scaled-Tech-Consulting / Gitea-Tools PR: #692 | Issue: #691 Base: master Head: fix/issue-691-obsolete-reviewer-lease-cleanup @ 6d86db793bbdfaed16bd54d93171f1dd66f234ca 1. gitea_whoami + gitea_resolve_task_capability(merge_pr) on prgs-merger. 2. Confirm PR #692 is approved at head 6d86db7… 3. Submit merge confirmation: 'MERGE PR 692'. ``` WHAT_HAPPENED: PR review completed with APPROVED. Independent REVIEWER verified: 1. Obsolete lease cleanup eligibility matrix handles superseded/expired leases securely. 2. Mutually exclusive classification matrix correctly maps foreign and orphaned leases. 3. Mutation tool safety ensures read-first behavior, confirmation checks, and append-only audits. 4. Regression test for PR #688 / comment 10749 correctly proves cleanup behavior. 5. All 2636 tests passed. WHY: The implementation provides a complete, robust, and highly guarded non-owner cleanup path for obsolete comment-backed reviewer leases, fully satisfying all acceptance criteria for Issue #691. ISSUE: 691 HEAD_SHA: 6d86db793bbdfaed16bd54d93171f1dd66f234ca REVIEW_STATUS: approved MERGE_READY: true BLOCKERS: none VALIDATION: 2636 passed, 6 skipped on commit 6d86db7. LAST_UPDATED_BY: reviewer

sysadmin referenced this pull request

2026-07-12 22:22:52 -05:00

Completed reviewer lease pinned to superseded PR head stays active with no canonical non-owner cleanup path #691

sysadmin commented

2026-07-12 22:28:25 -05:00

adopted_at: 2026-07-13T03:28:25Z
adopted_by_identity: sysadmin
adopted_by_profile: prgs-merger
adopted_from_session_id: 25883-70f5dabbf157
adopted_from_profile: prgs-reviewer
adopted_from_reviewer_identity: sysadmin
adopted_from_comment_id: 10820
adoption_reason: merger-handoff-approved-head

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #692
issue: #691
reviewer_identity: sysadmin
profile: prgs-merger
session_id: 92373-e105a388af21
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-654
phase: adopted
candidate_head: 6d86db793b
target_branch: master
target_branch_sha: none
last_activity: 2026-07-13T03:28:25Z
expires_at: 2026-07-13T05:28:25Z
blocker: none

adopted_at: 2026-07-13T03:28:25Z adopted_by_identity: sysadmin adopted_by_profile: prgs-merger adopted_from_session_id: 25883-70f5dabbf157 adopted_from_profile: prgs-reviewer adopted_from_reviewer_identity: sysadmin adopted_from_comment_id: 10820 adoption_reason: merger-handoff-approved-head  repo: Scaled-Tech-Consulting/Gitea-Tools pr: #692 issue: #691 reviewer_identity: sysadmin profile: prgs-merger session_id: 92373-e105a388af21 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-654 phase: adopted candidate_head: 6d86db793bbdfaed16bd54d93171f1dd66f234ca target_branch: master target_branch_sha: none last_activity: 2026-07-13T03:28:25Z expires_at: 2026-07-13T05:28:25Z blocker: none

sysadmin merged commit 237656702f into master

2026-07-12 22:28:59 -05:00

sysadmin commented

2026-07-12 22:31:25 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #692
issue: #691
reviewer_identity: sysadmin
profile: prgs-merger
session_id: 92373-e105a388af21
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-654
phase: released
candidate_head: 6d86db793b
target_branch: master
target_branch_sha: none
last_activity: 2026-07-13T03:31:24Z
expires_at: 2026-07-13T05:31:24Z
blocker: post-merge-moot

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #692 issue: #691 reviewer_identity: sysadmin profile: prgs-merger session_id: 92373-e105a388af21 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-654 phase: released candidate_head: 6d86db793bbdfaed16bd54d93171f1dd66f234ca target_branch: master target_branch_sha: none last_activity: 2026-07-13T03:31:24Z expires_at: 2026-07-13T05:31:24Z blocker: post-merge-moot

jcwalker3 referenced this pull request

2026-07-12 22:33:07 -05:00

Review-decision-lock recovery has no canonical in-workflow path; review-correction authorization and stale-lock cleanup serve as ad-hoc recovery #693

jcwalker3 referenced this pull request

2026-07-12 23:36:27 -05:00

Review-decision-lock recovery has no canonical in-workflow path; review-correction authorization and stale-lock cleanup serve as ad-hoc recovery #693

jcwalker3 commented

2026-07-12 23:36:58 -05:00

Canonical Issue State

STATE:
merged — product work for #691 complete; decision-lock recovery follow-up tracked on #693

WHO_IS_NEXT:
author

NEXT_ACTION:
Track and fix review-decision-lock recovery on issue #693 (do not treat this PR merge as closing that defect)

NEXT_PROMPT:

Role: AUTHOR
Repo: prgs / Scaled-Tech-Consulting / Gitea-Tools
Issue: #693
See issue #693 durable reconstruction comment (comment 10842) for PR #692 sequence, lock ledger (review_ids 425→426), ACs 1–8, and implementation prompt.

WHAT_HAPPENED:
PR #692 formal review hit a review-decision-lock recovery failure: lease acquired at head 6d86db793bbdfaed16bd54d93171f1dd66f234ca (comment 10820, session 25883-70f5dabbf157); gitea_mark_final_review_decision failed; stale lock inspected; gitea_cleanup_stale_review_decision_lock invoked multiple times (ineligible — unrelated open PR #688 terminal); gitea_authorize_review_correction required; mark_final retried; APPROVE eventually landed (review_id 426). Merge 237656702f44cf6621e77ff82188bf953d8eac3a closed #691. Durable issue #693 holds the full failure record.

WHY:
Keep post-merge trail so the recovery-path defect remains discoverable after product merge.

RELATED_PRS:
#692 (this), #691, #693, #688

BLOCKERS:
none on this PR; #693 remains open for decision-lock recovery

VALIDATION:

Issue #693 open (type:bug status:ready workflow-hardening anti-stomp safety)
Reconstruction comment on #693 id 10842
Approved head 6d86db7… review_id 426; merge 2376567…

LAST_UPDATED_BY:
traceability cross-link / 2026-07-13

## Canonical Issue State STATE: merged — product work for #691 complete; decision-lock recovery follow-up tracked on #693 WHO_IS_NEXT: author NEXT_ACTION: Track and fix review-decision-lock recovery on issue #693 (do not treat this PR merge as closing that defect) NEXT_PROMPT: ```text Role: AUTHOR Repo: prgs / Scaled-Tech-Consulting / Gitea-Tools Issue: #693 See issue #693 durable reconstruction comment (comment 10842) for PR #692 sequence, lock ledger (review_ids 425→426), ACs 1–8, and implementation prompt. ``` WHAT_HAPPENED: PR #692 formal review hit a review-decision-lock recovery failure: lease acquired at head `6d86db793bbdfaed16bd54d93171f1dd66f234ca` (comment 10820, session `25883-70f5dabbf157`); `gitea_mark_final_review_decision` failed; stale lock inspected; `gitea_cleanup_stale_review_decision_lock` invoked multiple times (ineligible — unrelated open PR #688 terminal); `gitea_authorize_review_correction` required; mark_final retried; APPROVE eventually landed (review_id 426). Merge `237656702f44cf6621e77ff82188bf953d8eac3a` closed #691. Durable issue **#693** holds the full failure record. WHY: Keep post-merge trail so the recovery-path defect remains discoverable after product merge. RELATED_PRS: #692 (this), #691, #693, #688 BLOCKERS: none on this PR; #693 remains open for decision-lock recovery VALIDATION: - Issue #693 open (type:bug status:ready workflow-hardening anti-stomp safety) - Reconstruction comment on #693 id 10842 - Approved head 6d86db7… review_id 426; merge 2376567… LAST_UPDATED_BY: traceability cross-link / 2026-07-13

jcwalker3 referenced this pull request

2026-07-12 23:37:08 -05:00

Completed reviewer lease pinned to superseded PR head stays active with no canonical non-owner cleanup path #691

jcwalker3 referenced this issue from a commit

2026-07-13 01:29:54 -05:00

fix(review): cross-PR decision-lock isolation and recovery diagnosis (Closes #693)

jcwalker3 referenced this pull request

2026-07-13 01:30:30 -05:00

fix(review): cross-PR decision-lock isolation and recovery diagnosis (Closes #693) #694

jcwalker3 referenced this pull request

2026-07-13 01:30:47 -05:00

Review-decision-lock recovery has no canonical in-workflow path; review-correction authorization and stale-lock cleanup serve as ad-hoc recovery #693