fix(scheduler): resolve live refs before cancelling runs

[seonghobae]

Root cause

The organization queue sweep treated the SHA in the open-PR list as the
authoritative branch head. During a synchronize-event propagation window,
LineageWeave #667 already had current-head runs for 37cc9ab1, while the PR
payload still exposed its preceding head. Queue hygiene cancelled the valid new
runs as superseded.

Repair

• enumerate open PR head repositories and branch names
• resolve each current SHA through GitHub's Get a reference endpoint
• compare queued/in-progress runs with that live ref
• fail closed for the whole repository when any ref is inaccessible or malformed
• retain immediate cancellation of genuinely superseded heads without a time heuristic

Evidence

• uv run --group dev pytest -q — 1,437 passed, 1 skipped, 16 subtests passed
• coverage run -m pytest -q tests && coverage report --fail-under=100 — 100% statements and branches
• interrogate --fail-under=100 scripts/ci — 100%
• actionlint .github/workflows/pr-review-merge-scheduler.yml
• git diff --check

Cross-repository incident: ContextualWisdomLab/LineageWeave#667.

---

Summary by CodeRabbit

• 버그 수정

  • PR의 최신 브랜치 상태를 실시간으로 확인한 후 오래된 워크플로 실행을 취소합니다.
  • 브랜치 참조를 확인할 수 없거나 유효하지 않으면 안전을 위해 해당 저장소의 실행 취소를 중단합니다.
  • 오래된 PR 정보로 인해 현재 커밋의 검사가 잘못 취소되는 문제를 방지합니다.

• 문서

  • 관련 장애 원인, 처리 규칙 및 검증 방법을 문서화했습니다.
  • 변경 사항을 미출시 항목에 기록했습니다.

• 테스트

  • 최신 PR 헤드 확인 및 참조 조회 실패 시 동작을 검증합니다.

[coderabbitai]

Warning

Review limit reached

Next included review available in 51 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1a779997-23b3-4c98-aa72-dee9e2de8eee

📥 Commits

Reviewing files that changed from the base of the PR and between dca874b and 7348cf6.

📒 Files selected for processing (2)

• .github/workflows/pr-review-merge-scheduler.yml
• tests/test_required_workflow_queue_contract.py

📝 Walkthrough

Walkthrough

조직 큐 스윕이 열린 PR의 head SHA를 live Git ref에서 다시 조회합니다. ref 조회 실패나 잘못된 SHA가 있으면 실행 취소를 중단하고 queue_hygiene_ready=false로 처리합니다. 테스트와 문서가 이 계약과 장애 사례를 반영합니다.

Changes

실시간 PR 헤드 검증

Layer / File(s)	Summary
Live Git ref 조회와 안전 중단 .github/workflows/pr-review-merge-scheduler.yml, tests/test_required_workflow_queue_contract.py	조직 큐 스윕이 head 저장소와 브랜치의 live Git ref를 조회합니다. 조회 결과가 없거나 SHA 형식이 잘못되면 실행 취소를 중단하고 오류를 기록합니다. 검증 계약이 ref 조회와 jq 기반 SHA 추출을 확인합니다.
변경 기록과 장애 기준 CHANGELOG.md, docs/doctoring/queue-hygiene-live-ref-race.md, docs/product-technical-gap-baseline.md	변경 기록과 장애 문서가 오래된 PR 페이로드와 현재 Git ref의 불일치, 안전 중단 조건, 이전 head 실행 취소 규칙을 기록합니다.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: 🟡 Moderate · up to dca87

Queue cleanup can still cancel valid active runs when an open PR has a missing or malformed head reference because that PR is silently omitted from live-head resolution. Fix the fail-closed handling before merging.

Sequence Diagram(s)

sequenceDiagram
  participant QueueSweep as 조직 큐 스윕
  participant PullRequestsAPI as GitHub Pull Requests API
  participant GitRefAPI as GitHub Git ref API
  participant ActionsAPI as GitHub Actions API
  QueueSweep->>PullRequestsAPI: 열린 PR의 head 저장소와 브랜치 조회
  QueueSweep->>GitRefAPI: head 브랜치의 live Git ref 조회
  GitRefAPI-->>QueueSweep: 현재 SHA 반환 또는 조회 실패
  QueueSweep->>ActionsAPI: 유효한 이전 head 실행 취소

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 실행 취소 전에 live Git ref를 조회하도록 스케줄러를 수정하는 PR의 핵심 변경을 정확하고 간결하게 설명합니다.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 1 files. (4 skipped: 4 …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 1 files. (4 skipped: 4 unsupported.)

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/queue-hygiene-live-ref-race

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[devin-ai-integration]

Devin Review found 1 new potential issue.